rapid_dashboards/docs/schema.md

# Schema YAML — Referencia completa

Referencia rapida de todos los campos del YAML de dashboard.

## Top level

| Campo | Tipo | Requerido | Default | Descripcion |
|-------|------|-----------|---------|-------------|
| `settings` | object | si | — | Configuracion global |
| `theme` | string | no | `"dark"` | Nombre del tema |
| `connections` | map | si | — | Conexiones a bases de datos |
| `queries` | map | si | — | Definiciones de queries SQL |
| `filters` | map | no | `{}` | Filtros interactivos |
| `sections` | array | si | — | Secciones con widgets |

## settings

| Campo | Tipo | Default | Descripcion |
|-------|------|---------|-------------|
| `title` | string | — | Titulo de la ventana (requerido) |
| `refresh` | duration | `"30s"` | Refresh global por defecto |
| `width` | int | `1280` | Ancho de ventana en px |
| `height` | int | `800` | Alto de ventana en px |
| `columns` | int | `12` | Columnas del grid CSS |

## connections[nombre]

| Campo | Tipo | Drivers | Descripcion |
|-------|------|---------|-------------|
| `driver` | string | todos | `sqlite` \| `postgres` \| `duckdb` \| `clickhouse` |
| `path` | string | sqlite, duckdb | Ruta al archivo de BD |
| `host` | string | postgres, clickhouse | Hostname |
| `port` | int | postgres, clickhouse | Puerto (default: 5432/9000) |
| `user` | string | postgres, clickhouse | Usuario |
| `password` | string | postgres, clickhouse | Password (soporta `${ENV}`) |
| `database` | string | postgres, clickhouse | Nombre de la base de datos |
| `sslmode` | string | postgres | Modo SSL (default: `"disable"`) |

## queries[nombre]

| Campo | Tipo | Default | Descripcion |
|-------|------|---------|-------------|
| `connection` | string | — | Nombre de la conexion (requerido) |
| `sql` | string | — | Query SQL (requerido) |
| `refresh` | duration | global | Intervalo de re-ejecucion |
| `stale_time` | duration | refresh/2 | Tiempo antes de considerar dato viejo |
| `params` | map | `{}` | Parametros: `nombre: valor_o_$filter.ref` |

## filters[nombre]

| Campo | Tipo | Tipos de filtro | Descripcion |
|-------|------|-----------------|-------------|
| `type` | string | todos | `select` \| `date_range` \| `text` |
| `label` | string | todos | Etiqueta visible |
| `default` | any | todos | Valor por defecto |
| `options` | array | select | `[{ label, value }]` |
| `presets` | array | date_range | `[{ label, from, to }]` |
| `placeholder` | string | text | Placeholder del input |
| `debounce` | int | text | Delay en ms (default: 300) |

## sections[]

| Campo | Tipo | Default | Descripcion |
|-------|------|---------|-------------|
| `id` | string | — | Identificador unico (requerido) |
| `title` | string | — | Titulo visible |
| `collapsible` | bool | `false` | Permite colapsar |
| `columns` | int | global | Override de columnas del grid |
| `widgets` | array | — | Widgets de esta seccion |

## widgets[]

| Campo | Tipo | Default | Descripcion |
|-------|------|---------|-------------|
| `id` | string | — | Identificador unico (requerido) |
| `type` | string | — | Tipo de componente (requerido) |
| `title` | string | — | Titulo del widget |
| `query` | string | — | Nombre de la query (requerido) |
| `mapping` | object | — | Mapeo de campos SQL a props |
| `options` | object | `{}` | Opciones del componente |
| `span` | int | `1` | Columnas que ocupa |
| `row_span` | int | `1` | Filas que ocupa |

## Tipos de widget y sus mappings

### kpi
```
mapping.value    → campo del resultado (string)
mapping.format   → formato de visualizacion (string, opcional)
```

### line_chart / bar_chart / area_chart
```
mapping.x        → campo del eje X (string)
mapping.y        → campo del eje Y — single series (string)
mapping.series   → multi-series: [{ key, name, color? }]
```

### sparkline
```
mapping.value    → campo numerico (string)
```

### table
```
mapping.columns  → [{ key, label, format? }]
                   Si no se define, auto-detecta del resultado.
```

## Options por tipo

### line_chart
| Option | Tipo | Default | Descripcion |
|--------|------|---------|-------------|
| `curve` | string | `"monotone"` | linear, monotone, step, stepBefore, stepAfter |
| `show_grid` | bool | `true` | Mostrar cuadricula |
| `show_legend` | bool | `false` | Mostrar leyenda |
| `zoomable` | bool | `false` | Habilitar brush zoom |
| `height` | int | `300` | Altura en px |

### bar_chart
| Option | Tipo | Default | Descripcion |
|--------|------|---------|-------------|
| `horizontal` | bool | `false` | Barras horizontales |
| `show_grid` | bool | `true` | Mostrar cuadricula |
| `show_legend` | bool | `false` | Mostrar leyenda |
| `height` | int | `300` | Altura en px |

### area_chart
| Option | Tipo | Default | Descripcion |
|--------|------|---------|-------------|
| `stacked` | bool | `false` | Apilar areas |
| `show_grid` | bool | `true` | Mostrar cuadricula |
| `show_legend` | bool | `false` | Mostrar leyenda |
| `height` | int | `300` | Altura en px |

### sparkline
| Option | Tipo | Default | Descripcion |
|--------|------|---------|-------------|
| `variant` | string | `"area"` | line, area, bar |
| `width` | int | `200` | Ancho en px |
| `height` | int | `40` | Altura en px |

## Duraciones validas

| Formato | Ejemplo |
|---------|---------|
| milisegundos | `100ms`, `200ms`, `500ms` |
| segundos | `1s`, `5s`, `30s` |
| minutos | `1m`, `5m`, `30m` |
| horas | `1h` |
| combinado | `1m30s` |

## Fechas relativas

| Formato | Resultado |
|---------|-----------|
| `now` | momento actual |
| `now-Ns` | hace N segundos |
| `now-Nm` | hace N minutos |
| `now-Nh` | hace N horas |
| `now-Nd` | hace N dias |

## KPI mappings extendidos (v2)

Ademas de `value` y `format`, el widget KPI soporta:

| Mapping | Tipo | Descripcion |
|---------|------|-------------|
| `value` | string | Campo SQL del valor principal |
| `format` | string | Formato: `$,.2f`, `,`, `datetime` |
| `unit` | string | Campo SQL para la unidad (ej: "k", "ms") |
| `unitLabel` | string | Unidad fija (alternativa a `unit` dinamico) |
| `delta` | string | Campo SQL para el cambio porcentual |
| `deltaLabel` | string | Texto antes del delta: "Increased by" |
| `deltaSuffix` | string | Texto despues del delta: "vs yesterday" |
| `sparkline` | string | Campo SQL con valores para mini barras |
| `sparklineColors` | string[] | Colores por barra |

Ejemplo:

```yaml
- type: kpi
  mapping:
    value: "total"
    format: ","
    unitLabel: "k"
    delta: "pct_change"
    deltaLabel: "Increased by"
    deltaSuffix: "vs yesterday"
    sparkline: "daily_value"
    sparklineColors: ["#3b82f6", "#8b5cf6", "#f59e0b", "#10b981"]
```

## Scripts de lanzamiento

```bash
./scripts/dev.sh <nombre>    # symlink + wails dev
./scripts/prod.sh <nombre>   # build + ejecutar
```

Sin argumento lista los dashboards disponibles en `examples/`.