From a9a2f0ba51379b1f6d573b3aab5b47e18fde59ec Mon Sep 17 00:00:00 2001 From: os-litant Date: Thu, 10 Sep 2026 19:59:44 +0000 Subject: [PATCH 1/2] docs(skills): stageOrder is funnel-only at the three hand-written sites The dashboards skill rule table, the dashboards docs page and the sdui-parser header comment still documented `options.stageOrder` for a `funnel` / `pyramid` pair. `pyramid` is not a chart type: it was removed from `ChartTypeSchema` as a variant that only ever rendered as `funnel`, and `chart.test.ts` pins the refusal. Each site now carries the two statements the schema prose already makes: explicit stage order for a funnel widget, as the dimension's stored values, and `funnel` is the only widget type that reads the key. Net 0 lines; the ratcheted skill row grows by 2 bytes, paid inside the row (`category` -> `stage`, `omit it` -> `omit`, `field's own` -> `field's`). Claude-Session: https://claude.ai/code/session_01YKEjmbYNvYWJvWGSWx26zK Co-authored-by: Claude --- content/docs/ui/dashboards.mdx | 2 +- packages/sdui-parser/src/dashboard-widget-options.ts | 2 +- skills/objectstack-ui/rules/dashboards.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/ui/dashboards.mdx b/content/docs/ui/dashboards.mdx index 4f64e99d1f2..60c7f2b1adb 100644 --- a/content/docs/ui/dashboards.mdx +++ b/content/docs/ui/dashboards.mdx @@ -118,7 +118,7 @@ dataset compiles to: | `sortBy` | `string` | Orders rows by a dimension or measure **this widget selects**. | | `sortOrder` | `asc \| desc` | Direction for `sortBy` (default `asc`). | | `limit` | `number` | Max rows, applied **after** ordering. | -| `stageOrder` | `(string \| number \| boolean)[]` | Explicit stage order for `funnel` / `pyramid`, as the dimension's **stored values**. Omit to use the dimension field's picklist option order. | +| `stageOrder` | `(string \| number \| boolean)[]` | Explicit stage order for a `funnel` widget, as the dimension's **stored values**. `funnel` is the only widget type that reads it — on any other type the key parses and is never consulted; order those with `sortBy` / `sortOrder`. Omit to use the dimension field's picklist option order. | Because they are declared, a misspelling (`sortDirection`, `granularity`) is an author-time error rather than an option that reads as if it works. diff --git a/packages/sdui-parser/src/dashboard-widget-options.ts b/packages/sdui-parser/src/dashboard-widget-options.ts index d0f95264ffb..4bff1398a9e 100644 --- a/packages/sdui-parser/src/dashboard-widget-options.ts +++ b/packages/sdui-parser/src/dashboard-widget-options.ts @@ -48,7 +48,7 @@ * the five the spec DECLARES: * * dateGranularity, sortBy, sortOrder, limit (query-affecting, framework#3588) - * stageOrder (funnel/pyramid stage order) + * stageOrder (funnel stage order — the only type that reads it) * * plus ONE undeclared key with a real read site: * diff --git a/skills/objectstack-ui/rules/dashboards.md b/skills/objectstack-ui/rules/dashboards.md index 80236e9a525..b376e001961 100644 --- a/skills/objectstack-ui/rules/dashboards.md +++ b/skills/objectstack-ui/rules/dashboards.md @@ -342,7 +342,7 @@ author-time type error rather than an option that silently does nothing. | `sortBy` | a name this widget selects | Order by that dimension or measure. It must be one of this widget's own `dimensions` / `values` entries. | | `sortOrder` | `'asc'` \| `'desc'` | Direction for `sortBy` (default ascending). | | `limit` | positive integer | Max rows, applied **after** ordering — so "top 10 accounts" is `limit` **plus** `sortBy`. Without `sortBy` the runtime orders by the selected dimensions: deterministic, but not the top of anything. | -| `stageOrder` | array of **stored** values | Explicit category order for `funnel` / `pyramid`. Stored values, not display labels; omit it to inherit the field's own picklist order. | +| `stageOrder` | array of **stored** values | Explicit stage order for `funnel`; no other type reads it. Stored values, not display labels; omit to inherit the field's picklist order. | ```typescript // Top 10 accounts by revenue, bucketed monthly for this widget only From 6a854fe9b1cffb10d4fe9b660cfa099d0eb35681 Mon Sep 17 00:00:00 2001 From: os-litant Date: Thu, 10 Sep 2026 20:18:00 +0000 Subject: [PATCH 2/2] chore(changeset): patch @objectstack/sdui-parser for the header comment fix The edited header comment is carried into the published `index.d.ts` (measured: the new sentence appears in `dist/index.d.ts` and `dist/index.d.mts`, and `files[]` ships `dist`), so the tarball moves and a patch changeset is owed; `skip-changeset` does not apply. Claude-Session: https://claude.ai/code/session_01YKEjmbYNvYWJvWGSWx26zK Co-authored-by: Claude --- .changeset/sdui-parser-stageorder-funnel-only.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .changeset/sdui-parser-stageorder-funnel-only.md diff --git a/.changeset/sdui-parser-stageorder-funnel-only.md b/.changeset/sdui-parser-stageorder-funnel-only.md new file mode 100644 index 00000000000..57810963f21 --- /dev/null +++ b/.changeset/sdui-parser-stageorder-funnel-only.md @@ -0,0 +1,13 @@ +--- +'@objectstack/sdui-parser': patch +--- + +`dashboard-widget-options.ts` header: `stageOrder` is a `funnel`-only key, not `funnel` / `pyramid` + +The accepted-set census comment at the top of the module (carried into the +published `index.d.ts`) described `stageOrder` as "funnel/pyramid stage order". +There is no `pyramid` widget type: `ChartTypeSchema` refuses it, so an author +who copied the pair got a parse refusal. The line now says what the schema's +own `.describe()` says: `funnel` is the only widget type that reads the key. +Comment-only — the accepted set, the diagnostic code and the emitted JS are +unchanged.