Dashboard

Color variant for dashboard widgets (e.g., KPI cards).

Source: packages/spec/src/ui/dashboard.zod.ts

TypeScript Usage

import { Dashboard, DashboardHeader, DashboardHeaderAction, DashboardWidget, GlobalFilter, GlobalFilterOptionsFrom, WidgetActionType, WidgetColorVariant } from '@objectstack/spec/ui';
import type { Dashboard, DashboardHeader, DashboardHeaderAction, DashboardWidget, GlobalFilter, GlobalFilterOptionsFrom, WidgetActionType, WidgetColorVariant } from '@objectstack/spec/ui';

// Validate data
const result = Dashboard.parse(data);

Properties

Property	Type	Required	Description
name	`string`	✅	Dashboard unique name
label	`string`	✅	Dashboard label
description	`string`	optional	Dashboard description
header	`Object`	optional	Dashboard header configuration
widgets	`Object[]`	✅	Widgets to display
columns	`integer`	optional	Number of grid columns (default 12)
gap	`integer`	optional	Grid gap in Tailwind spacing units
refreshInterval	`number`	optional	Auto-refresh interval in seconds
dateRange	`Object`	optional	Global dashboard date range filter configuration
globalFilters	`Object[]`	optional	Global filters that apply to all widgets in the dashboard
aria	`Object`	optional	ARIA accessibility attributes
performance	`Object`	optional	Performance optimization settings
protection	`Object`	optional	Package author protection block — lock policy for this dashboard.
_lock	`Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>`	optional	Item-level lock — controls overlay & delete (ADR-0010).
_lockReason	`string`	optional	Human-readable reason shown when a write is refused by _lock.
_lockSource	`Enum<'artifact' \| 'package' \| 'env-forced'>`	optional	Layer that set _lock (artifact \| package \| env-forced).
_provenance	`Enum<'package' \| 'org' \| 'env-forced'>`	optional	Origin of the item (package \| org \| env-forced).
_packageId	`string`	optional	Owning package machine id.
_packageVersion	`string`	optional	Owning package version.
_lockDocsUrl	`string`	optional	Optional documentation link surfaced next to _lockReason.

DashboardHeader

Dashboard header configuration

Properties

Property	Type	Required	Description
showTitle	`boolean`	✅	Show dashboard title in header
showDescription	`boolean`	✅	Show dashboard description in header
actions	`Object[]`	optional	Header action buttons

DashboardHeaderAction

Dashboard header action

Properties

Property	Type	Required	Description
label	`string`	✅	Action button label
actionUrl	`string`	✅	URL or target for the action
actionType	`Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api'>`	optional	Type of action
icon	`string`	optional	Icon identifier for the action button

DashboardWidget

Properties

Property	Type	Required	Description
id	`string`	✅	Unique widget identifier (snake_case)
title	`string`	optional	Widget title
description	`string`	optional	Widget description text below the header
type	`Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'radar' \| 'table' \| 'pivot'>`	✅	Visualization type
chartConfig	`Object`	optional	Chart visualization configuration
colorVariant	`Enum<'default' \| 'blue' \| 'teal' \| 'orange' \| 'purple' \| 'success' \| 'warning' \| 'danger'>`	optional	Widget color variant for theming
requiresObject	`string`	optional	Hide the widget unless the named object is registered
requiresService	`string`	optional	Hide the widget unless the named kernel service is registered
actionUrl	`string`	optional	URL or target for the widget action button
actionType	`Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api'>`	optional	Type of action for the widget action button
actionIcon	`string`	optional	Icon identifier for the widget action button
filter	`[__schema0](./__schema0)`	optional	Presentation-scope filter (runtimeFilter)
compareTo	`string \| string \| Object`	optional	Period-over-period comparison window
dataset	`string`	✅	Dataset name to bind (ADR-0021)
dimensions	`string[]`	optional	Dimension names — X/group/split
values	`string[]`	✅	Measure names — Y (at least one)
layout	`Object`	optional	Grid layout position (auto-flowed when omitted)
options	`any`	optional	Widget specific configuration
filterBindings	`Record<string, string \| boolean>`	optional	Per-widget dashboard-filter bindings: filter name → this widget's field, or false to opt out
suppressWarnings	`string[]`	optional	Build diagnostic rule ids suppressed on this widget
responsive	`Object`	optional	Responsive layout configuration
aria	`Object`	optional	ARIA accessibility attributes

GlobalFilter

Properties

Property	Type	Required	Description
name	`string`	optional	Stable filter name (variable key); defaults to field
field	`string`	✅	Field name to filter on
label	`string`	optional	Display label for the filter
type	`Enum<'text' \| 'select' \| 'date' \| 'number' \| 'lookup'>`	optional	Filter input type
options	`Object[]`	optional	Static filter options
optionsFrom	`Object`	optional	Dynamic filter options from object
defaultValue	`string \| number \| boolean`	optional	Default filter value
scope	`Enum<'dashboard' \| 'widget'>`	✅	Filter application scope
targetWidgets	`string[]`	optional	Widget IDs to apply this filter to

GlobalFilterOptionsFrom

Dynamic filter options from object

Properties

Property	Type	Required	Description
object	`string`	✅	Source object name
valueField	`string`	✅	Field to use as option value
labelField	`string`	✅	Field to use as option label
filter	`[__schema0](./__schema0)`	optional	Filter to apply to source object

WidgetActionType

Widget action type

Allowed Values

script
url
modal
flow
api

WidgetColorVariant

Widget color variant

Allowed Values

default
blue
teal
orange
purple
success
warning
danger

Dashboard

On this page