---
name: dashboard_grid
kind: component
lang: cpp
domain: core
version: "1.0.0"
purity: pure
signature: "void dashboard_grid_begin(int columns = 2, float spacing = 8.0f); void dashboard_grid_next(); void dashboard_grid_end()"
description: "Grid de N columnas para distribuir widgets de dashboard automaticamente con spacing uniforme entre columnas"
tags: [imgui, grid, layout, dashboard, responsive]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: [imgui]
tested: true
tests:
  - "compiles and links against Catch2 (placeholder, visual cubierto en 0048)"
test_file_path: "cpp/tests/test_dashboard_grid.cpp"
file_path: "cpp/functions/core/dashboard_grid.cpp"
framework: imgui
params:
  - name: columns
    desc: "Numero de columnas del grid (minimo 1); el ancho disponible se divide uniformemente entre ellas"
  - name: spacing
    desc: "Espacio horizontal entre columnas en pixels"
output: "Layout de grid aplicado al contenido entre dashboard_grid_begin/end; cada celda recibe un ancho uniforme calculado a partir del espacio disponible"
---

# dashboard_grid

Divide el ancho disponible en N columnas con spacing uniforme y posiciona cada widget en su celda automaticamente. Soporta grids anidados mediante un stack interno de estado.

## Uso

```cpp
dashboard_grid_begin(3, 8.0f);

// Celda 0
dashboard_panel_begin("CPU");
ImGui::Text("%.1f %%", cpu_pct);
dashboard_panel_end();
dashboard_grid_next();

// Celda 1
dashboard_panel_begin("Memory");
ImGui::Text("%.0f MB", mem_mb);
dashboard_panel_end();
dashboard_grid_next();

// Celda 2
dashboard_panel_begin("Disk");
ImGui::Text("%.0f GB", disk_gb);
dashboard_panel_end();

dashboard_grid_end();
```

## Implementacion

### Calculo de ancho

```
col_width = (available_width - spacing * (columns - 1)) / columns
```

`available_width` se obtiene de `ImGui::GetContentRegionAvail().x` en el momento de `dashboard_grid_begin`.

### Mecanica de celdas

Cada celda es un `BeginGroup`/`EndGroup` con `PushItemWidth(col_width)` para que los widgets internos respeten el ancho de columna. Al llamar `dashboard_grid_next`:

1. Se cierra la celda actual (`PopItemWidth`, `EndGroup`).
2. Se incrementa el contador interno.
3. Si `counter % columns != 0` se emite `SameLine(0, spacing)` para continuar en la misma fila.
4. Si `counter % columns == 0` no se emite `SameLine`: ImGui pasa a la siguiente fila automaticamente.
5. Se abre la nueva celda (`BeginGroup`, `PushItemWidth`).

### Grids anidados

El estado (columnas, spacing, col_width, counter) se guarda en `g_grid_stack` (un `std::vector` de structs en un namespace anonimo). Cada llamada a `dashboard_grid_begin` hace `push_back` y `dashboard_grid_end` hace `pop_back`, permitiendo anidar grids sin conflicto.

## Notas

- Llamar `dashboard_grid_next()` entre cada par de widgets, **no** antes del primero ni despues del ultimo.
- El numero de `dashboard_grid_next()` puede ser mayor que `columns - 1`: el grid hace wrap automatico a la siguiente fila.
- Combina bien con `dashboard_panel_begin`/`dashboard_panel_end` para crear dashboards con paneles alineados en cuadricula.
- Si `columns <= 0` se fuerza a 1 para evitar division por cero.
