# Dashboards

A dashboard is a grid of widgets, optionally driven by shared top-bar
parameter slots. Widgets pack onto a 12-column grid automatically.

## Create — `bi_create_dashboard`

Pass a `name` (and optional `description`). Returns the new `dashboard_id`.

## Dashboard-level parameter slots — `bi_update_dashboard(parameters=[...])`

Slots are the dashboard's shared top-bar controls. Several widgets can bind
to the **same** slot so they re-render together when the operator changes it.

`bi_update_dashboard` with a `parameters` list **replaces** the full slot set
(it is not additive). Each slot:

```json
{"name": "global_country", "type": "enum",
 "title": "Pais", "default": "CO",
 "enumOptions": ["CO", "MX", "PE"]}
```

- `name` is what a widget's `parameter_mappings` references via `mapTo`.
- `type` is one of `date`, `enum`, `text`, `number` (and the other query
  parameter types); it must **exactly match** the type of any widget
  parameter mapped to it.
- `enumOptions` is required for `enum` slots.
- Pass `parameters=[]` to remove all slots. Omit `parameters` to leave slots
  unchanged and edit name/description/tags instead.
- To remove a single slot, fetch the current list (`bi_get_dashboard`), drop
  the one you don't want, and pass the rest. Removing a slot that widgets are
  still bound to is rejected.

## Widgets

- `bi_add_widget(dashboard_id, title, chart_type, query_id, width, height)` —
  data widget backed by a saved query.
- `bi_add_text_card` — a note/link card (no SQL).
- `bi_add_title_block` — a full-width section banner.
- `bi_update_widget(dashboard_id, widget_index, ...)` — change a widget's
  title, type, size/position, axis columns, palette, data source, or
  `parameter_mappings`. `widget_index` is zero-based.
- `bi_remove_widget` — delete a widget.

To make a widget interactive, bind its parameters with
`bi_update_widget(parameter_mappings=...)`. See the `widget-parameters`
topic for the full two-step flow.