Skip to content

chart.mdx

Latest commit

 

History

History
206 lines (142 loc) · 6.56 KB

chart.mdx

File metadata and controls

206 lines (142 loc) · 6.56 KB
Raw
title Chart
description Chart protocol schemas

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

Unified Chart Type Taxonomy

Shared by Dashboard and Report widgets.

Provides a comprehensive set of chart types for data visualization.

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

TypeScript Usage

import { ChartAggregate, ChartAggregateFunction, ChartAnnotation, ChartAxis, ChartConfig, ChartGroupBy, ChartInteraction, ChartSeries, ChartType } from '@objectstack/spec/ui';
import type { ChartAggregate, ChartAggregateFunction, ChartAnnotation, ChartAxis, ChartConfig, ChartGroupBy, ChartInteraction, ChartSeries, ChartType } from '@objectstack/spec/ui';

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

ChartAggregate

Inline aggregation for an object-bound chart

Properties

Property Type Required Description
field string optional Field to aggregate — required for sum/avg/min/max, optional for count
function Enum<'count' | 'sum' | 'avg' | 'min' | 'max'> ✅ Aggregation function
groupBy string | { field: string; dateGranularity?: Enum<'day' | 'week' | 'month' | 'quarter' | 'year'>; alias?: string } ✅ Field the rows are grouped by — the chart category axis

ChartAggregateFunction

Allowed Values

  • count
  • sum
  • avg
  • min
  • max

ChartAnnotation

Properties

Property Type Required Description
type Enum<'line' | 'region'> ✅
axis Enum<'x' | 'y'> ✅
value number | string ✅ Start value
endValue number | string optional End value for regions
color string optional
label string optional Display label (plain string; i18n keys are auto-generated by the framework)
style Enum<'solid' | 'dashed' | 'dotted'> ✅

ChartAxis

Properties

Property Type Required Description
field string ✅ Data field key
title string optional Axis display title
format string optional Value format string (e.g., "$0,0.00")
min number optional Minimum value
max number optional Maximum value
stepSize number optional Step size for ticks
showGridLines boolean ✅
position Enum<'left' | 'right' | 'top' | 'bottom'> optional Axis position
logarithmic boolean ✅

ChartConfig

Properties

Property Type Required Description
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 optional Chart title
subtitle string optional Chart subtitle
description string optional Accessibility description
xAxis { field: string; title?: string; format?: string; min?: number; … } optional X-Axis configuration
yAxis { field: string; title?: string; format?: string; min?: number; … }[] optional Y-Axis configuration (support dual axis)
series { name: string; label?: string; type?: Enum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'funnel' | 'scatter' | 'treemap' | 'sankey' | 'gauge' | 'solid-gauge' | 'metric' | 'kpi' | 'bullet' | 'radar' | 'table' | 'pivot'>; color?: string; … }[] optional Defined series configuration
colors string[] | Record<string, string> optional Color palette (string[]) or value→color map ({ value: color })
height number optional Fixed height in pixels
showLegend boolean ✅ Display legend
showDataLabels boolean ✅ Display data labels
annotations { type: Enum<'line' | 'region'>; axis: Enum<'x' | 'y'>; value: number | string; endValue?: number | string; … }[] optional
interaction { tooltips: boolean; zoom: boolean; brush: boolean; clickAction?: string } optional
aria { ariaLabel?: string; ariaDescribedBy?: string; role?: string } optional ARIA accessibility attributes

ChartGroupBy

Union Options

This schema accepts one of the following structures:

Option 1

Field to group by

Type: string

Option 2

Properties

Property Type Required Description
field string ✅ Field to group by
dateGranularity Enum<'day' | 'week' | 'month' | 'quarter' | 'year'> optional Bucket date values into uniform periods
alias string optional Alias for the projected group value (defaults to field) — this becomes the category column

ChartInteraction

Properties

Property Type Required Description
tooltips boolean ✅
zoom boolean ✅
brush boolean ✅
clickAction string optional Action ID to trigger on click

ChartSeries

Properties

Property Type Required Description
name string ✅ Field name or series identifier
label string optional Series display label
type Enum<'bar' | 'horizontal-bar' | 'column' | 'line' | 'area' | 'pie' | 'donut' | 'funnel' | 'scatter' | 'treemap' | 'sankey' | 'gauge' | 'solid-gauge' | 'metric' | 'kpi' | 'bullet' | 'radar' | 'table' | 'pivot'> optional Override chart type for this series
color string optional Series color (hex/rgb/token)
stack string optional Stack identifier to group series
yAxis Enum<'left' | 'right'> ✅ Bind to specific Y-Axis
variant Enum<'primary' | 'comparison'> optional Series visual role
dashArray string optional SVG stroke-dasharray override
opacity number optional Series opacity override

ChartType

Allowed Values

  • bar
  • horizontal-bar
  • column
  • line
  • area
  • pie
  • donut
  • funnel
  • scatter
  • treemap
  • sankey
  • gauge
  • solid-gauge
  • metric
  • kpi
  • bullet
  • radar
  • table
  • pivot