feat(spec,lint): the ui vocabularies admit what the renderers implement (objectui#2945)

Additions-only follow-up to the vocabulary audit. Nothing narrows, so no
already-stored metadata changes meaning.

- ChartTypeSchema admits `combo`. The taxonomy could not name the one
  family the rest of chart.zod.ts is written for: ChartSeriesSchema.type
  exists to override a series' type ("combo charts", per its own doc
  comment) and ChartSeriesSchema.yAxis binds left/right, which only means
  something for mixed marks. objectui draws it distinctly and carried
  `combo` in a local fork whose comment claimed to mirror this list.

- WidgetActionTypeSchema is ActionType. They disagreed by `form`, and
  backwards: a widget/header action dispatches through the same
  ActionRunner that implements `form` (DashboardRenderer routes everything
  but a raw `url` into it, deliberately — #3528), so the narrower enum
  rejected at validation what the dispatcher executes.

- ListChartConfigSchema.chartType is ChartTypeSchema.extract([...]) —
  same five members, a de-duplication rather than a widening.

- @objectstack/lint's chart-family set derives from the taxonomy. Its
  omissions failed in the worst direction: an unlisted family read as
  "not a chart", so a widget with no chartConfig measure mapping PASSED
  validation. Pinning the old hand-written list back reproduces exactly
  that for `combo` — zero findings — which is the new test's teeth.

ActionType deliberately does NOT gain `navigation`: executeNavigation is a
strictly weaker executeUrl (no ${param} interpolation, no apiBase
promotion, no openIn) differing only by `replace`, and its one live
producer is the SDUI element:button `action` prop that
ElementButtonPropsSchema does not model at all. Adding the name would put
a second spelling of "navigate" into a closed vocabulary without closing
the real gap.

spec 6944 tests / 267 files and lint 544 / 37 green; tsc clean on both.

Refs objectstack-ai/objectui#2945, objectstack-ai/objectui#2901, #3528

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/ui-vocabularies-derive-not-restate.md

@@ -0,0 +1,60 @@
+---
+"@objectstack/spec": minor
+"@objectstack/lint": patch
+---
+
+feat(spec,lint): the `ui` vocabularies admit what the renderers implement, and derive instead of restating (objectui#2945)
+
+Additions-only follow-up to the vocabulary audit
+(objectstack-ai/objectui#2901, #2945). Nothing here narrows a vocabulary, so no
+already-stored metadata changes meaning — three of the four `ui/` enums that had
+drifted from what is actually implemented, plus the fork that drift had made
+invisible.
+
+**`ChartTypeSchema` admits `combo`.** The taxonomy could not name the one chart
+family the rest of `chart.zod.ts` is written for: `ChartSeriesSchema.type`
+exists to override a series' type — its doc comment literally says *"combo
+charts"* — and `ChartSeriesSchema.yAxis` binds a series to the left or right
+axis, which is only meaningful for mixed marks. objectui's renderer draws it
+distinctly (mixed bar/line/area on dual axes, per-series type) and had to carry
+`combo` in a local fork of this list, whose own comment claimed to mirror it.
+
+**`WidgetActionTypeSchema` is `ActionType`.** The two disagreed by one member,
+`form`, and the disagreement was backwards: a dashboard header or widget action
+button dispatches through the same `ActionRunner` that implements `form` —
+objectui's `DashboardRenderer` deliberately routes everything except a raw `url`
+into it, so a `flow` header action works (#3528). The narrower enum therefore
+rejected at validation exactly what the shared dispatcher then executes.
+Derived, so the next type the runner implements needs one edit, not two.
+
+**`ListChartConfigSchema.chartType` is `ChartTypeSchema.extract([...])`.** Same
+five members as before — a de-duplication, not a widening. A member renamed in
+the taxonomy now fails at build time instead of leaving a second list quietly
+disagreeing.
+
+**`@objectstack/lint`'s chart-family set is derived from the taxonomy.**
+`validate-widget-bindings` decides which widgets need a `chartConfig` measure
+mapping from a hand-written list of families, and its omissions fail in the
+worst direction: an unlisted family reads as *"not a chart"*, so a widget
+missing its mapping **passes** validation. `combo` was exactly that case —
+verified by pinning the old list back, where a `combo` widget with no
+`chartConfig` produced zero findings. The set is now the taxonomy minus an
+explicit `MEASURE_EXEMPT_CHART_TYPES` (single-value and tabular families), so a
+family added to the spec is covered without editing the rule.
+
+Guards: `packages/spec/src/ui/vocabulary-derivation.test.ts` asserts both
+derivations still hold (a restated list fails silently — it keeps validating,
+just not what the other list says), and the lint suite now walks every
+multi-series family in the taxonomy rather than a list of its own.
+
+`ActionType` deliberately does **not** gain `navigation`, which the audit
+suggested. `ActionRunner.executeNavigation` is a strictly weaker
+`executeUrl` — no `${param.X}` interpolation, no `apiBase` promotion, no
+`openIn` — differing only by a `replace` option, and its one live producer is
+the SDUI `element:button` `action` prop, which `ElementButtonPropsSchema` does
+not model at all. Promoting the name would add a second spelling of *navigate*
+to a closed authorable vocabulary (members cannot be removed later) without
+closing the gap that actually exists. Tracked separately.
+
+Verified: `@objectstack/spec` **6944 tests / 267 files**, `@objectstack/lint`
+**544 tests / 37 files**, both green; `tsc --noEmit` clean on both.

packages/lint/src/validate-widget-bindings.test.ts

@@ -203,11 +203,25 @@ describe('validateWidgetBindings (reference integrity, issue #1721)', () => {
   });
 
   it('(d) non-chart types do not warn on missing chartConfig', () => {
-    for (const type of ['metric', 'kpi', 'gauge', 'table']) {
+    for (const type of ['metric', 'kpi', 'gauge', 'solid-gauge', 'bullet', 'table', 'pivot']) {
       expect(validateWidgetBindings(chartStack({ type, chartConfig: undefined }))).toHaveLength(0);
     }
   });
 
+  it('(d) every multi-series family in the taxonomy warns — including a newly added one', () => {
+    // The set of chart families that need a measure mapping is derived from
+    // `ChartTypeSchema`, so a family added to the taxonomy is covered without
+    // editing a list here. `combo` is the case that proved it: as a hand-written
+    // list, an unlisted family read as "not a chart" and the missing mapping
+    // went unreported. objectui#2945.
+    for (const type of ['bar', 'horizontal-bar', 'column', 'line', 'area', 'pie',
+      'donut', 'funnel', 'scatter', 'treemap', 'sankey', 'radar', 'combo']) {
+      const findings = validateWidgetBindings(chartStack({ type, chartConfig: undefined }));
+      expect(findings, `expected a warning for chart type '${type}'`).toHaveLength(1);
+      expect(findings[0].rule).toBe(CHART_CONFIG_MISSING);
+    }
+  });
+
   it('errors are NOT suppressible via suppressWarnings', () => {
     const findings = validateWidgetBindings(chartStack({
       dataset: 'no_such_dataset',

packages/lint/src/validate-widget-bindings.ts

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { isIncoherentAggregate } from '@objectstack/spec/data';
+import { ChartTypeSchema } from '@objectstack/spec/ui';
 
 /**
  * Build-time dashboard widget binding diagnostics (issues #1719, #1721).
@@ -139,17 +140,29 @@ function asStrings(v: unknown): string[] {
 }
 
 /**
- * Chart families whose renderer needs a `chartConfig` measure mapping.
- * Single-value types (metric/kpi/gauge/…) plot their lone value and tabular
- * types (table/pivot) render every column, so they are exempt.
+ * Chart families that plot a single value or every column, and so need no
+ * `chartConfig` measure mapping: single-value types plot their lone value,
+ * tabular types render each column as-is.
  */
-const CHART_TYPES = new Set([
-  'bar', 'horizontal-bar', 'column',
-  'line', 'area',
-  'pie', 'donut', 'funnel',
-  'scatter', 'treemap', 'sankey', 'radar',
+const MEASURE_EXEMPT_CHART_TYPES = new Set([
+  'gauge', 'solid-gauge', 'metric', 'kpi', 'bullet',
+  'table', 'pivot',
 ]);
 
+/**
+ * Chart families whose renderer needs a `chartConfig` measure mapping — the
+ * taxonomy minus the exemptions above.
+ *
+ * Derived from `ChartTypeSchema` rather than restated. As a hand-written list it
+ * had no way to know when the taxonomy grew, and the omission is silent in
+ * exactly the wrong direction: an unlisted family is treated as "not a chart",
+ * so a widget missing its measure mapping passes validation instead of being
+ * reported. objectui#2945.
+ */
+const CHART_TYPES = new Set<string>(
+  ChartTypeSchema.options.filter(t => !MEASURE_EXEMPT_CHART_TYPES.has(t)),
+);
+
 function levenshtein(a: string, b: string): number {
   const m = a.length, n = b.length;
   let prev = Array.from({ length: n + 1 }, (_, j) => j);

packages/spec/src/ui/chart.test.ts

@@ -47,6 +47,12 @@ describe('ChartTypeSchema', () => {
     });
   });
 
+  it('should accept the mixed chart type', () => {
+    // `combo` draws bar/line/area series together on left/right axes — the
+    // family `ChartSeriesSchema.type` and `ChartSeriesSchema.yAxis` configure.
+    expect(() => ChartTypeSchema.parse('combo')).not.toThrow();
+  });
+
   it('should accept all performance chart types', () => {
     const types = ['gauge', 'metric', 'kpi'] as const;
 

packages/spec/src/ui/chart.zod.ts

@@ -37,6 +37,14 @@ export const ChartTypeSchema = lazySchema(() => z.enum([
   'treemap',
   'sankey',
 
+  // Mixed — bar/line/area series on shared dual axes. `ChartSeriesSchema.type`
+  // and `ChartSeriesSchema.yAxis` below exist precisely to configure this
+  // family (the former's own doc comment says "combo charts"), so the taxonomy
+  // was unable to name the one chart type the rest of the file is written for.
+  // objectui's renderer draws it distinctly — mixed marks, left/right axes,
+  // per-series type — and had to carry `combo` in a local fork of this list.
+  'combo',
+
   // Performance (single value — metric/kpi render a number; gauge/solid-gauge/
   // bullet are honest single-value variants pending a real dial/target renderer)
   'gauge',

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

@@ -6,6 +6,7 @@ import { MetadataProtectionFields } from '../kernel/metadata-protection.zod';
 import { FilterConditionSchema } from '../data/filter.zod';
 import { DateGranularity } from '../data/query.zod';
 import { ChartTypeSchema, ChartConfigSchema } from './chart.zod';
+import { ActionType } from './action.zod';
 import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
 import { I18nLabelSchema, AriaPropsSchema } from './i18n.zod';
 import { ResponsiveConfigSchema, PerformanceConfigSchema } from './responsive.zod';
@@ -27,14 +28,20 @@ export const WidgetColorVariantSchema = lazySchema(() => z.enum([
 
 /**
  * Action type for widget action buttons.
+ *
+ * `ActionType` itself, not a hand-kept subset of it. The two lists had drifted
+ * apart by one member — `form` — and the disagreement was backwards: a
+ * dashboard header or widget action button dispatches through the same
+ * `ActionRunner` that implements `form` (objectui's `DashboardRenderer` routes
+ * everything except a raw `url` into it, deliberately, so a `flow` header
+ * action works — objectstack#3528). So the narrower enum rejected at validation
+ * exactly what the shared dispatcher then executes at runtime.
+ *
+ * Derived rather than restated: a type added to `ActionType` is dispatchable
+ * from a widget the moment the runner implements it, with no second list to
+ * remember.
  */
-export const WidgetActionTypeSchema = lazySchema(() => z.enum([
-  'script',
-  'url',
-  'modal',
-  'flow',
-  'api',
-]).describe('Widget action type'));
+export const WidgetActionTypeSchema = lazySchema(() => ActionType.describe('Widget action type'));
 
 /**
  * Dashboard Header Action Schema

packages/spec/src/ui/view.zod.ts

@@ -7,6 +7,7 @@ import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
 import { ExpressionInputSchema } from '../shared/expression.zod';
 import { normalizeVisibleWhen, strictVisibilityError } from '../shared/visibility';
 import { I18nLabelSchema, AriaPropsSchema } from './i18n.zod';
+import { ChartTypeSchema } from './chart.zod';
 import { SharingConfigSchema } from './sharing.zod';
 import { ResponsiveConfigSchema, PerformanceConfigSchema } from './responsive.zod';
 import { FieldType, SelectOptionSchema } from '../data/field.zod';
@@ -467,7 +468,14 @@ export const KanbanConfigSchema = lazySchema(() => z.object({
  * `ChartConfigSchema` in `chart.zod.ts` (which is for embedded reports).
  */
 export const ListChartConfigSchema = lazySchema(() => z.object({
-  chartType: z.enum(['bar', 'line', 'pie', 'area', 'scatter']).default('bar').describe('Chart visualisation type'),
+  /**
+   * Narrowed from `ChartTypeSchema` with `.extract()` rather than retyped.
+   * Same five members as before — this is a de-duplication, not a widening —
+   * but a member renamed in the chart taxonomy now fails here at build time
+   * instead of leaving a second list quietly disagreeing with the first.
+   */
+  chartType: ChartTypeSchema.extract(['bar', 'line', 'pie', 'area', 'scatter'])
+    .default('bar').describe('Chart visualisation type'),
   /**
    * ADR-0021 — the semantic-layer `dataset` this chart binds to. Selects
    * dimensions/measures BY NAME so the chart's numbers stay consistent with

packages/spec/src/ui/vocabulary-derivation.test.ts

@@ -0,0 +1,70 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Two `ui/` vocabularies are now *derived* from another rather than restated
+ * (objectstack-ai/objectui#2945). These tests assert the derivation still holds,
+ * because the failure mode of a restated list is silence: it keeps validating,
+ * it just validates something the other list no longer says.
+ *
+ *   - `ListChartConfigSchema.chartType` — a five-member `.extract()` of
+ *     `ChartTypeSchema`, not a second enum that happened to agree with it.
+ *   - `WidgetActionTypeSchema` — `ActionType` itself. It used to omit `form`,
+ *     and so rejected at validation what the `ActionRunner` a widget action
+ *     dispatches through already executes.
+ */
+import { describe, it, expect } from 'vitest';
+import { ChartTypeSchema } from './chart.zod';
+import { ListChartConfigSchema } from './view.zod';
+import { ActionType } from './action.zod';
+import { WidgetActionTypeSchema } from './dashboard.zod';
+
+/** `z.enum(...).options` through the lazySchema proxy. */
+const optionsOf = (schema: unknown): string[] =>
+  (schema as { options: string[] }).options;
+
+describe('ListChartConfigSchema.chartType is extracted from ChartTypeSchema', () => {
+  const listChartType = (ListChartConfigSchema as unknown as {
+    shape: { chartType: { def: { innerType: unknown } } };
+  }).shape.chartType.def.innerType;
+
+  it('admits exactly the five list-chart visualisations', () => {
+    expect(optionsOf(listChartType).slice().sort())
+      .toEqual(['area', 'bar', 'line', 'pie', 'scatter']);
+  });
+
+  it('admits only members of the chart taxonomy', () => {
+    const taxonomy = new Set(optionsOf(ChartTypeSchema));
+    const strays = optionsOf(listChartType).filter(t => !taxonomy.has(t));
+    expect(strays).toEqual([]);
+  });
+
+  /** Minimal valid config — `dataset` and `values` are both required. */
+  const minimal = { dataset: 'sales_by_month', values: ['revenue'] };
+
+  it('still rejects a taxonomy member outside the list-chart subset', () => {
+    expect(() => ListChartConfigSchema.parse({ ...minimal, chartType: 'donut' })).toThrow();
+    expect(() => ListChartConfigSchema.parse({ ...minimal, chartType: 'combo' })).toThrow();
+  });
+
+  it('accepts every member of the subset, and defaults to bar', () => {
+    for (const chartType of optionsOf(listChartType)) {
+      expect(ListChartConfigSchema.parse({ ...minimal, chartType }).chartType).toBe(chartType);
+    }
+    expect(ListChartConfigSchema.parse(minimal).chartType).toBe('bar');
+  });
+});
+
+describe('WidgetActionTypeSchema is ActionType', () => {
+  it('admits every action type, with no subset of its own', () => {
+    expect(optionsOf(WidgetActionTypeSchema).slice().sort())
+      .toEqual(optionsOf(ActionType).slice().sort());
+  });
+
+  it('admits form — the member the hand-kept subset had dropped', () => {
+    expect(() => WidgetActionTypeSchema.parse('form')).not.toThrow();
+  });
+
+  it('still rejects an unknown action type', () => {
+    expect(() => WidgetActionTypeSchema.parse('teleport')).toThrow();
+  });
+});