Skip to content

dashboard.mdx

Latest commit

 

History

History
203 lines (144 loc) · 9.85 KB

dashboard.mdx

File metadata and controls

203 lines (144 loc) · 9.85 KB
Raw
title Dashboard
description Dashboard protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

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

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

TypeScript Usage

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

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

Dashboard

Properties

Property Type Required Description
name string ✅ Dashboard unique name
label string ✅ Dashboard label
description string optional Dashboard description
header { showTitle: boolean; showDescription: boolean; actions?: { label: string; actionUrl: string; actionType?: Enum<'script' | 'url' | 'modal' | 'flow' | 'api'>; icon?: string }[] } optional Dashboard header configuration
widgets { id: string; title?: string; description?: string; type: Enum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'funnel' | 'scatter' | 'treemap' | 'sankey' | 'gauge' | 'solid-gauge' | 'metric' | 'kpi' | 'bullet' | 'radar' | 'table' | 'pivot'>; … }[] ✅ 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 { field?: string; defaultRange: Enum<'today' | 'yesterday' | 'this_week' | 'last_week' | 'this_month' | 'last_month' | 'this_quarter' | 'last_quarter' | 'this_year' | 'last_year' | 'last_7_days' | 'last_30_days' | 'last_90_days' | 'custom'>; allowCustomRange: boolean } optional Global dashboard date range filter configuration
globalFilters { name?: string; field: string; label?: string; type?: Enum<'text' | 'select' | 'date' | 'number' | 'lookup'>; … }[] optional Global filters that apply to all widgets in the dashboard
aria { ariaLabel?: string; ariaDescribedBy?: string; role?: string } optional ARIA accessibility attributes
performance { lazyLoad?: boolean; virtualScroll?: object; cacheStrategy?: Enum<'none' | 'cache-first' | 'network-first' | 'stale-while-revalidate'>; prefetch?: boolean; … } optional Performance optimization settings
protection { lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string } 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 { label: string; actionUrl: string; actionType?: Enum<'script' | 'url' | 'modal' | 'flow' | 'api'>; icon?: string }[] 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 { type: Enum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'funnel' | 'scatter' | 'treemap' | 'sankey' | 'gauge' | 'solid-gauge' | 'metric' | 'kpi' | 'bullet' | 'radar' | 'table' | 'pivot'>; title?: string; subtitle?: string; description?: string; … } 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 any optional Presentation-scope filter (runtimeFilter)
compareTo 'previousPeriod' | 'previousYear' | { offset: string } 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 { x: number; y: number; w: number; h: number } optional Grid layout position (auto-flowed when omitted)
options Record<string, any> optional Widget specific configuration
filterBindings Record<string, string | 'false'> 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 { breakpoint?: Enum<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'>; hiddenOn?: Enum<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'>[]; columns?: object; order?: object } optional Responsive layout configuration
aria { ariaLabel?: string; ariaDescribedBy?: string; role?: string } optional ARIA accessibility attributes

DashboardWidgetOptions

Widget configuration — declared query keys + open renderer extras

Properties

Property Type Required Description
dateGranularity Enum<'day' | 'week' | 'month' | 'quarter' | 'year'> optional Bucket selected date dimensions (day/week/month/quarter/year)
sortBy string optional Dimension/measure name to order by
sortOrder Enum<'asc' | 'desc'> optional Sort direction for sortBy
limit integer optional Max rows (applied after ordering)
stageOrder string | number | boolean[] optional Explicit category order for funnel/pyramid stages (stored values)

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 { value: string | number | boolean; label: string }[] optional Static filter options
optionsFrom { object: string; valueField: string; labelField: string; filter?: any } 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 any 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