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, WidgetMeasure } from '@objectstack/spec/ui';
import type { Dashboard, DashboardHeader, DashboardHeaderAction, DashboardWidget, GlobalFilter, GlobalFilterOptionsFrom, WidgetActionType, WidgetColorVariant, WidgetMeasure } 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
_provenance	`Enum<'package' \| 'org' \| 'env-forced'>`	optional	Origin of the item (package
_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' \| 'grouped-bar' \| 'stacked-bar' \| 'bi-polar-bar' \| 'line' \| 'area' \| 'stacked-area' \| 'step-line' \| 'spline' \| 'pie' \| 'donut' \| 'funnel' \| 'pyramid' \| 'scatter' \| 'bubble' \| '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
object	`string`	optional	Data source object name
filter	`[__schema0](./__schema0)`	optional	Data filter criteria
compareTo	`string \| string \| Object`	optional	Period-over-period comparison window
categoryField	`string`	optional	Field for grouping (X-Axis)
categoryGranularity	`Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>`	optional	Bucket categoryField date values into day/week/month/quarter/year periods
valueField	`string`	optional	Field for values (Y-Axis)
aggregate	`Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max'>`	✅	Aggregate function
measures	`Object[]`	optional	Multiple measures for pivot/matrix analysis
layout	`Object`	✅	Grid layout position
options	`any`	optional	Widget specific configuration
responsive	`Object`	optional	Responsive layout configuration
aria	`Object`	optional	ARIA accessibility attributes

GlobalFilter

Properties

Property	Type	Required	Description
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

WidgetMeasure

Widget measure definition

Properties

Property	Type	Required	Description
valueField	`string`	✅	Field to aggregate
aggregate	`Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max'>`	✅	Aggregate function
label	`string`	optional	Measure display label
format	`string`	optional	Number format string

Dashboard

On this page