Dashboard Kit — interfaces

reference

6 min readUpdated 2026-10-04

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: nu...`

Members

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

`DashboardGridGeometry`

ts
interface DashboardGridGeometry

Properties

Name	Type	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. A layout saved in one direction therefore renders mirrored in the other with

`DashboardSpec`

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

ts
interface DashboardSpec

Properties

Name	Type	Description
`nodes`	`Array<Record<string, unknown>>`
`edges`	`Array<Record<string, unknown>>`
`renderCustomNode`	`(node: unknown, host: HTMLElement)`
`finalize`	`(api: unknown)`
`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	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	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	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	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	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	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`

Was this page helpful?

ADocs generated by Atloria — from the code, always in sync →