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:

- 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

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

Sin argumento lista los dashboards disponibles en examples/.