# Interfaces

Import these from `@grafloria/element`.

## Interfaces

### `BarWidgetData`

`kind: 'bar'` — categorical columns.

```ts
interface BarWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `bars?` | `Array<{ label?: string; value?: number }>` |  |  |

### `CellRect`

One tile in integer board cells — the shape `GridPackEngine` speaks.

```ts
interface CellRect
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` |  |  |
| `y` | `number` |  |  |
| `w` | `number` |  |  |
| `h` | `number` |  |  |

### `DashboardGridApi`

The slice of a DiagramInstance the binder needs (structural, test-friendly).

```ts
interface DashboardGridApi
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement` |  |  |
| `viewport?` | `{ clientToWorld( clientX: number, clientY: number, rect: { left: number; top: number; width: number; height: number } ): { x: number; y: number }; }` |  |  |

**Members**

- `getModel(): DiagramModel`
- `getEngine(): { commandManager: { execute(cmd: Command): Promise<unknown> | unknown } }`
- `render(): void`
- `renderNow(): void`

### `DashboardGridGeometry`

```ts
interface DashboardGridGeometry
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `number` |  | Column count of the board (default 12). |
| `gap` | `number` |  | Gap between cells, px. |
| `padding` | `number` |  | Padding between the board frame and the outermost cells, px. |
| `sizing` | `'fit' \| 'grow'` |  |  |
| `baseRowHeight` | `number` |  | Row height in 'grow' mode, px. |
| `minRowHeight` | `number` |  | Floor for the derived 'fit' row height, px. |
| `designHeight` | `number` |  | The board's design height — 'fit' keeps it, 'grow' never shrinks below it. |
| `rtl?` | `boolean` |  | RIGHT-TO-LEFT boards. The MODEL is direction-agnostic — cell x=0 is always "the first column" and every rule in `GridPackEngine` (push, swap, gravity, the anti-jitter gate) is written in cells, so none of it changes. ONLY this module's pixel mapping mirrors: x=0 renders at the board's RIGHT edge and columns run leftwards. |

### `DashboardSpec`

What `dashboard()` returns — a render spec plus the runtime handle.

```ts
interface DashboardSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `Array<Record<string, unknown>>` |  |  |
| `edges` | `Array<Record<string, unknown>>` |  |  |
| `renderCustomNode` | `(node: unknown, host: HTMLElement) => void` |  |  |
| `finalize` | `(api: unknown) => void` |  |  |
| `handle` | `DashboardHandle` |  | Live handle, populated by finalize(). |
| `renderOptions?` | `{ minZoom?: number; maxZoom?: number }` |  | Instance options the spec asks `render()` to apply — a fluid board pins the zoom range to 1 so the layout can never become a scaled picture. |

### `DashboardViewSpec`

One board. Multiple views are the tab pattern: only one is on-camera.

```ts
interface DashboardViewSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `name?` | `string` |  |  |
| `widgets` | `DashboardWidgetSpec[]` |  |  |
| `columns?` | `number` |  | Per-view overrides of the dashboard-level geometry. |
| `width?` | `number` |  |  |
| `height?` | `number` |  |  |
| `layout?` | `'grid' \| 'split'` |  | Per-view layout (default: the dashboard-level `layout`). `toJSON()` writes it per view. |
| `tree?` | `SplitNode \| null` |  | SPLIT layout only: the authored splitter tree (see `layout`). Omit it and the tree is derived from the widgets' cells, so a grid-authored view keeps its proportions when it opens as a split board. `toJSON()` writes it back. |

### `DonutWidgetData`

`kind: 'donut'` — parts of a whole, with a legend and a centre figure.

```ts
interface DonutWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `slices?` | `Array<{ label?: string; value?: number; color?: string }>` |  |  |
| `centerLabel?` | `string` |  | Centre figure (default: the compacted total). |
| `centerCaption?` | `string` |  | Caption under the centre figure (default 'total'). |

### `DragGripOptions`

A painted grip: the only drag zone, placed along the card's top edge.

```ts
interface DragGripOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `grip` | `true` |  |  |
| `position?` | `'left' \| 'center' \| 'right'` |  | Where along the top edge. Default 'left'. |
| `placement?` | `'inside' \| 'outside'` |  | In the header band, or a tab above the card. Default 'inside'. |

### `FunnelWidgetData`

`kind: 'funnel'` — ordered stages, each bar scaled against the first.

```ts
interface FunnelWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `stages?` | `Array<{ label?: string; value?: number }>` |  |  |

### `KpiWidgetData`

`kind: 'kpi'` — one headline number, an optional change, an optional trend.

```ts
interface KpiWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label?` | `string` |  | Small caption above the number (falls back to `widget.title`). |
| `value?` | `string \| number` |  | The headline — pre-formatted by you, so units/currency stay yours. |
| `delta?` | `number` |  | Signed percentage change. Positive paints up/green, negative down/red. |
| `deltaLabel?` | `string` |  | Caption after the delta (default 'vs previous'). |
| `spark?` | `number[]` |  | Sparkline values, oldest → newest. Fewer than 2 points draws nothing. |

### `LineSeries`

One named line of a `kind: 'line'` chart.

```ts
interface LineSeries
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name?` | `string` |  |  |
| `values` | `number[]` |  |  |

### `LineWidgetData`

`kind: 'line'` — one or many series over a shared x axis (area + line).

```ts
interface LineWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `series?` | `number[] \| LineSeries[]` |  | A bare `number[]` is the single-series shorthand. |
| `labels?` | `string[]` |  | X-axis tick labels, positionally matched to the values. |

### `SectionCaptionAction`

SECTION CAPTIONS — the header a section (container widget) may carry,
painted by the kit on the slab overlay it already owns.

Three things only the kit can do for a section header, and this module is
where they are decided: RESERVE the pixels (`captionReserve` — the nested
board's frame starts below the band, so no child may take it), PAINT it
(`paintCaptionBand` — one DOM shape, one set of CSS variables, one theme),
and ROUTE its presses (`captionPassThrough` — a button or an input in the
band is content, everything else is the band, which selects the section). Persistence is the container's business: the caption rides on the group's
`containerWidget` metadata beside `layout` and `sizing`, and `toJSON()`
writes it back.

Plan and defaults: documentation/api-architecture/section-caption-plan.html.

```ts
interface SectionCaptionAction
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label` | `string` |  | Accessible name; painted as the glyph when there is no `icon`. |
| `icon?` | `string` |  | A glyph (emoji or short text). |
| `title?` | `string` |  | Tooltip; default: the label. |
| `disabled?` | `boolean` |  |  |

### `SectionCaptionFont`

```ts
interface SectionCaptionFont
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `number` |  |  |
| `weight?` | `number \| string` |  |  |
| `family?` | `string` |  |  |
| `color?` | `string` |  |  |
| `transform?` | `'none' \| 'uppercase'` |  |  |

### `TableWidgetData`

`kind: 'table'` — plain rows. Numbers right-align on their own.

```ts
interface TableWidgetData
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `string[]` |  |  |
| `rows?` | `Array<Array<string \| number>>` |  |  |

### `TabPage`

```ts
interface TabPage
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label` | `string` |  |  |

### `TileDelta`

```ts
interface TileDelta
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `locked?` | `boolean` |  |  |
| `isGroup?` | `boolean` |  | Group members (layout slabs) get cells-only commands — never Move/Resize. |
| `cellBefore` | `CellRect` |  |  |
| `cellAfter` | `CellRect` |  |  |
| `posBefore` | `{ x: number; y: number }` |  |  |
| `posAfter` | `{ x: number; y: number }` |  |  |
| `sizeBefore` | `{ width: number; height: number; depth?: number }` |  |  |
| `sizeAfter` | `{ width: number; height: number; depth?: number }` |  |  |

### `WorldRect`

A world-space rectangle (the group frame, or a projected tile).

```ts
interface WorldRect
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` |  |  |
| `y` | `number` |  |  |
| `width` | `number` |  |  |
| `height` | `number` |  |  |