Merge pull request #1692 from objectstack-ai/feat-trim-charttype-schema

feat(spec)!: trim ChartTypeSchema to distinctly-renderable families

Author: os-zhuang

.changeset/trim-charttype-schema.md

@@ -0,0 +1,21 @@
+---
+"@objectstack/spec": major
+---
+
+BREAKING: `ChartTypeSchema` drops 8 variant types that only rendered as their
+base chart, so the taxonomy now advertises only families the renderer draws
+distinctly.
+
+Removed: `grouped-bar`, `stacked-bar`, `bi-polar-bar` (→ bar — no multi-series
+grouping/stacking), `stacked-area` (→ area), `step-line`, `spline` (→ line),
+`pyramid` (→ funnel), `bubble` (→ scatter — no size encoding).
+
+Kept: bar / horizontal-bar / column, line / area, pie / donut / funnel, scatter,
+treemap / sankey, radar, table / pivot, and the single-value performance family
+(metric / kpi / gauge / solid-gauge / bullet — these render an honest value
+today and gain a dial when a gauge renderer lands).
+
+Migration: a widget/series using a removed type should switch to its base
+(`stacked-bar`→`bar`, `spline`→`line`, `pyramid`→`funnel`, `bubble`→`scatter`,
+etc.). These can return via an opt-in renderer once a real renderer + data model
+backs them.

.objectui-sha

@@ -1 +1 @@
-76094e0d4ed79b8732ba9879c75aa5ab8283180d
+ec530a92ba2cdb6dbb0a1f5ee3b800503296e2f1

content/docs/references/ui/chart.mdx

@@ -69,7 +69,7 @@ const result = ChartAnnotation.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **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'>` | ✅ |  |
+| **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 |
@@ -109,7 +109,7 @@ const result = ChartAnnotation.parse(data);
 | :--- | :--- | :--- | :--- |
 | **name** | `string` | ✅ | Field name or series identifier |
 | **label** | `string` | optional | Series display label |
-| **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'>` | optional | Override chart type for this series |
+| **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 |
@@ -127,20 +127,12 @@ const result = ChartAnnotation.parse(data);
 * `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`

examples/app-showcase/test/coverage.test.ts

@@ -49,20 +49,14 @@ describe('showcase coverage (introspected against the spec)', () => {
   });
 
   it('covers every distinctly-renderable ChartType', () => {
-    // The Chart Gallery demonstrates only chart families the renderer draws
-    // DISTINCTLY — advertising a type that renders as something else (a "sankey"
-    // that draws bars) is worse than not offering it. The families below have no
-    // distinct renderer yet and fall back to a near-relative, so the showcase
-    // intentionally does not duplicate them: grouped/stacked/bi-polar bars (→bar),
-    // stacked-area (→area), step-line/spline (→line), pyramid (→funnel), bubble
-    // (→scatter), and the dial-less performance variants kpi/gauge/solid-gauge/
-    // bullet (→ the same KPI value as `metric`). Follow-up: trim these from
-    // `ChartTypeSchema` so spec ↔ renderer ↔ showcase stay in lockstep.
-    const FALLBACK_ONLY = new Set([
-      'grouped-bar', 'stacked-bar', 'bi-polar-bar', 'stacked-area', 'step-line',
-      'spline', 'pyramid', 'bubble', 'kpi', 'gauge', 'solid-gauge', 'bullet',
-    ]);
-    const expected = enumValues(ui.ChartTypeSchema).filter((t) => !FALLBACK_ONLY.has(t));
+    // The fallback-only VARIANTS (grouped/stacked/bi-polar bar, stacked-area,
+    // step-line, spline, pyramid, bubble) were removed from `ChartTypeSchema`, so
+    // the enum now lists only families that render. The remaining exception is
+    // the performance group: `metric` represents the single-value KPI, and
+    // `kpi`/`gauge`/`solid-gauge`/`bullet` render the SAME value today (no dial),
+    // so the gallery demonstrates `metric` once rather than duplicating them.
+    const SAME_AS_METRIC = new Set(['kpi', 'gauge', 'solid-gauge', 'bullet']);
+    const expected = enumValues(ui.ChartTypeSchema).filter((t) => !SAME_AS_METRIC.has(t));
     const used = new Set<string>();
     for (const w of ChartGalleryDashboard.widgets ?? []) if (w.type) used.add(w.type);
     expectFullCoverage('ChartType', expected, used);

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

@@ -8,16 +8,16 @@ import {
 
 describe('ChartTypeSchema', () => {
   it('should accept all comparison chart types', () => {
-    const types = ['bar', 'horizontal-bar', 'column', 'grouped-bar', 'stacked-bar'] as const;
-    
+    const types = ['bar', 'horizontal-bar', 'column'] as const;
+
     types.forEach(type => {
       expect(() => ChartTypeSchema.parse(type)).not.toThrow();
     });
   });
 
   it('should accept all trend chart types', () => {
-    const types = ['line', 'area', 'stacked-area', 'step-line'] as const;
-    
+    const types = ['line', 'area'] as const;
+
     types.forEach(type => {
       expect(() => ChartTypeSchema.parse(type)).not.toThrow();
     });
@@ -32,8 +32,8 @@ describe('ChartTypeSchema', () => {
   });
 
   it('should accept all relationship chart types', () => {
-    const types = ['scatter', 'bubble'] as const;
-    
+    const types = ['scatter'] as const;
+
     types.forEach(type => {
       expect(() => ChartTypeSchema.parse(type)).not.toThrow();
     });
@@ -72,6 +72,17 @@ describe('ChartTypeSchema', () => {
     });
   });
 
+  it('should reject variant types that only render as their base chart', () => {
+    // Removed: each fell back to a base family the renderer already draws, so
+    // advertising them lied about the output (see the taxonomy NOTE in chart.zod).
+    const fallbackOnly = ['grouped-bar', 'stacked-bar', 'bi-polar-bar', 'stacked-area',
+      'step-line', 'spline', 'pyramid', 'bubble'] as const;
+
+    fallbackOnly.forEach(type => {
+      expect(() => ChartTypeSchema.parse(type)).toThrow();
+    });
+  });
+
   it('should accept all tabular chart types', () => {
     const types = ['table', 'pivot'] as const;
 

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

@@ -20,32 +20,25 @@ export const ChartTypeSchema = lazySchema(() => z.enum([
   'bar',
   'horizontal-bar',
   'column',
-  'grouped-bar',
-  'stacked-bar',
-  'bi-polar-bar',
-  
+
   // Trend
   'line',
   'area',
-  'stacked-area',
-  'step-line',
-  'spline',
-  
+
   // Distribution
   'pie',
   'donut',
   'funnel',
-  'pyramid',
-  
+
   // Relationship
   'scatter',
-  'bubble',
-  
+
   // Composition
   'treemap',
   'sankey',
 
-  // Performance
+  // Performance (single value — metric/kpi render a number; gauge/solid-gauge/
+  // bullet are honest single-value variants pending a real dial/target renderer)
   'gauge',
   'solid-gauge',
   'metric',
@@ -60,13 +53,22 @@ export const ChartTypeSchema = lazySchema(() => z.enum([
   'pivot',
 ]));
 
-// NOTE: chart families that require data shapes the platform does not model
-// (OHLC for candlestick/stock, per-record distributions for box-plot/violin),
-// geographic data (choropleth/bubble-map/gl-map), or dependencies the default
-// Recharts renderer lacks (sunburst, heatmap, word-cloud, waterfall) were
-// removed from this taxonomy: advertising a chart type the renderer can't draw
-// is worse than not offering it. They can return via an opt-in renderer plugin
-// once there is real demand and a data model to back them.
+// NOTE: the taxonomy lists only chart families the default Recharts renderer
+// draws DISTINCTLY. Two groups are intentionally absent:
+//
+// 1. Families requiring data/dependencies the platform does not model — OHLC
+//    (candlestick/stock), per-record distributions (box-plot/violin), geo
+//    (choropleth/bubble-map/gl-map), or extra renderers (sunburst, heatmap,
+//    word-cloud, waterfall).
+// 2. VARIANTS that only render as their base chart, so advertising them lies
+//    about the output: grouped-bar / stacked-bar / bi-polar-bar (→ bar, no
+//    multi-series grouping/stacking), stacked-area (→ area), step-line / spline
+//    (→ line), pyramid (→ funnel), bubble (→ scatter, no size encoding).
+//
+// Both can return via an opt-in renderer once there is a real renderer and a
+// data model to back them. (`metric`/`kpi` are kept as honest single-value
+// synonyms; `gauge`/`solid-gauge`/`bullet` render a value today and gain a dial
+// when a gauge renderer lands.)
 
 export type ChartType = z.infer<typeof ChartTypeSchema>;