Dashboard composition blocks

The dashboard composition vocabulary is the safe, semantic input used by the assistant and dashboard tools. Snoze compiles each entry into the ordinary page block model. It intentionally omits persisted block IDs, order keys, and raw manifests.

Every composition block can have a 12-column-grid layout and an optional tab name. Layout stores column, row, width, and height. Embed blocks can set restrictAccess; when true, a viewer must also be allowed to read the target.

Canonical contract values:

• heading
• text
• divider
• insight
• database_view
• metric
• data
• doc
• agenda
• clock_in
• timesheet
• page_link
• activity_feed
• button
• form_embed
• drive_embed
• control
• template_text

Composition blocks

Heading heading

A dashboard heading. Set visible text and optional level 1, 2, or 3, horizontal alignment, and vertical alignment. content is accepted only as a repair-friendly alias for text. It compiles to the matching page heading kind.

Text text

An ordinary paragraph with horizontal and vertical alignment. Use text for the visible copy; content is a compatibility alias. This is static copy, not parameter interpolation.

Divider divider

A horizontal or vertical separator with grid placement. It carries no text or data binding and compiles to a Divider page block.

Insight insight

A durable briefing with required title, optional body, original prompt, and source workspace item IDs. content is a compatibility alias for body. Refreshing an insight replaces stored block content rather than computing a different answer for every viewer. It may restrict access to the sources.

Database view database_view

An inline database layout. databaseId is required; viewId, viewKind, and owned viewConfig select or describe its presentation. paramFilters map dashboard parameter names to database fields, while selectionParam lets the widget expose its selected record to other blocks. The target database’s permissions still apply.

Metric metric

The earlier single-database number or chart: a required database and optional saved view, with count, sum, avg, min, or max (fieldKey for all but count) and a number, column, bar, line, or pie display. It still compiles and renders; new dashboards use data instead.

Data data

A data widget in the current metrics model. widget holds the series (which metrics to plot, by id from the dashboard’s metrics or the widget’s own), the grouping (a time grain, a field, or a shared field), an optional split, period and comparison overrides, sort, a top-N limit, whether empty groups show, and the visual: KPI, line, area, column, bar, combo, donut, funnel, waterfall, table, leaderboard, progress, gauge, or heatmap with its options. An optional title names the card; without one it is named after its metrics.

Doc doc

Rich text inside a card. Give either markdown — headings, lists, to-dos, quotes, code, and tables are converted into document blocks — or blocks, a list of semantic entries (kind, text, code and language, caption, checked state, and the index of a parent block for nesting). Only the block kinds a Doc can hold are accepted, up to 300 blocks. Snoze generates block ids and ordering.

Agenda agenda

Upcoming calendar events for the viewer, over today, this_week, next_7_days, or next_30_days.

Clock in clock_in

Clock in and out for the viewer, with the running timer. Needs time tracking.

Timesheet timesheet

Tracked hours for this_week, last_week, this_month, or last_7_days, for the viewer (me) or the team. Needs time tracking.

Page link page_link

A preview card for a required workspace itemId. It opens that item and may restrict access. It does not copy or snapshot the target.

Activity feed activity_feed

Recent workspace activity, optionally capped with limit. It has no event-type filter in the composition contract and is not a replacement for full event history.

Button button

A required label plus either a saved Action reference or a local command. Local commands can open an item, set a dashboard parameter, or open a dashboard tab. Legacy inline button actions are not part of the composition vocabulary.

Form embed form_embed

An inline Form selected by required workspace item ID. It uses the Form’s own database, question, validation, step, and public settings and may restrict access.

Drive embed drive_embed

A workspace drive browser. An optional folderId chooses its starting folder; without one it starts at the root. The browser owns navigation after it opens and may restrict access.

Control control

An input that writes a required named dashboard parameter. The control style can be select, search, date, member, segmented, or toggle and can have a label and placeholder. Creating a Control does not bind other widgets automatically: their parameter filters or templates must name the same parameter.

Template text template_text

Dynamic presentation copy with a required template string and optional alignment. The compiler resolves the template’s supported dashboard tokens; it does not treat the string as HTML or arbitrary code.

Dashboard data

Create and edit requests can also carry the dashboard’s own data. metrics is the metric library every data widget can plot: aggregates over a database or Snoze app, or formulas over other metrics, such as [Revenue] - [Expenses]. sharedFields name one concept — Client, Owner — and the field that holds it in each source, so a single grouping or filter lines several databases up. filters sets the filter bar: the default period and comparison and which shared fields appear as filters. Unknown metric references and formula cycles are rejected before anything is saved, and an edit that omits these fields keeps the existing ones.

Parameters and tabs

Dashboard-level params declare the shared inputs Controls and data blocks use. Tabs declare named sections; a block’s tab value assigns it to one. Parameter bindings are explicit and field-specific, so one owner selector can filter several widgets differently without changing their underlying saved views.

For every persisted block kind, including blocks that the semantic composer does not expose, see Page block types.