report.mdx

title	Report
description	Report protocol schemas

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

Report Type Enum

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

TypeScript Usage

import { JoinedReportBlock, Report, ReportChart, ReportColumn, ReportGrouping, ReportType } from '@objectstack/spec/ui';
import type { JoinedReportBlock, Report, ReportChart, ReportColumn, ReportGrouping, ReportType } from '@objectstack/spec/ui';

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

---

JoinedReportBlock

Properties

Property	Type	Required	Description
name	string	✅	Snake case identifier (lowercase with underscores only)
label	string	optional	Display label (plain string; i18n keys are auto-generated by the framework)
description	string	optional	Display label (plain string; i18n keys are auto-generated by the framework)
type	Enum<'tabular' | 'summary' | 'matrix'>	✅
chart	{ 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
dataset	string	optional	Dataset name to bind (ADR-0021)
rows	string[]	optional	Dimension names down (dataset-bound)
columns	string[]	optional	Dimension names across (matrix, dataset-bound)
values	string[]	optional	Measure names to show (dataset-bound)
runtimeFilter	any	optional	Render-time scope filter (dataset-bound)

---

Report

Properties

Property	Type	Required	Description
name	string	✅	Report unique name
label	string	✅	Report label
description	string	optional	Display label (plain string; i18n keys are auto-generated by the framework)
type	Enum<'tabular' | 'summary' | 'matrix' | 'joined'>	✅	Report format type
dataset	string	optional	Dataset name to bind (ADR-0021)
rows	string[]	optional	Dimension names down
columns	string[]	optional	Dimension names across (matrix)
values	string[]	optional	Measure names to show
runtimeFilter	any	optional	Render-time scope filter
drilldown	boolean	✅	Click-through to underlying records
chart	{ 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	Embedded chart configuration
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
blocks	{ name: string; label?: string; description?: string; type: Enum<'tabular' | 'summary' | 'matrix'>; … }[]	optional	Sub-reports for type=joined
protection	{ lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string }	optional	Package author protection block — lock policy for this report.
_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.

---

ReportChart

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	string	✅	Dataset dimension name for the X-axis (bound-dataset dimension, not a raw field)
yAxis	string	✅	Dataset measure name for the Y-axis (bound-dataset measure, not a raw field)
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
groupBy	string	optional	[EXPERIMENTAL — not enforced] Additional series-split grouping; not read by the dataset-bound report renderer (liveness #1878/#1890)

---

ReportColumn

Properties

Property	Type	Required	Description
field	string	✅	Field name
label	string	optional	Override label
aggregate	Enum<'sum' | 'avg' | 'max' | 'min' | 'count' | 'unique'>	optional	Aggregation function
responsive	{ breakpoint?: Enum<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'>; hiddenOn?: Enum<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'>[]; columns?: object; order?: object }	optional	Responsive visibility for this column

---

ReportGrouping

Properties

Property	Type	Required	Description
field	string	✅	Field to group by
sortOrder	Enum<'asc' | 'desc'>	✅
dateGranularity	Enum<'day' | 'week' | 'month' | 'quarter' | 'year'>	optional	For date fields

---

ReportType

Allowed Values

• tabular
• summary
• matrix
• joined

---