@object-ui/core 17.6.0 → 17.7.0

package/dist/registry/public-blocks.js

@@ -21,6 +21,14 @@
  *
  * This is a single, reviewable source of truth for the public surface — prefer
  * editing this list over scattering `tier` flags across registration sites.
+ *
+ * ⛔ The html tier's intrinsic elements (`h1`, `p`, `a`, the sectioning tags, …)
+ * do NOT belong here. They reach the published manifest through the second
+ * roster beside this one, `HTML_TIER_INTRINSICS`, stamped `tier: 'html'`, so
+ * that the manifest's other reader — the objectstack gate that whitelists a
+ * `kind:'html'` page's tags — accepts them without this curated JSON-surface
+ * vocabulary growing (objectui#10735). Listing one here would widen the
+ * vocabulary silently; `html-tier-intrinsics.test.ts` pins the two disjoint.
  */
 export const PUBLIC_BLOCKS = [
     // ── Tier A — object-aware blocks (the contract core) ──────────────────────
@@ -34,6 +42,23 @@ export const PUBLIC_BLOCKS = [
     'object-gantt',
     'object-timeline',
     'object-map',
+    // Curated by objectui#10064, which is a NARROWING being undone rather than a
+    // widening: `@objectstack/spec` already declares `object-tree` on
+    // `ComponentPropsMap`, and @object-ui/plugin-tree has registered the renderer
+    // all along — this roster was the one face that withheld it, so the tier sat
+    // narrower than the declaration. Everything downstream reported that
+    // faithfully and could not fix it: `getPublicConfigs()` is what both manifest
+    // producers serialize, so the framework's tracked `sdui.manifest.json` could
+    // never carry a block the contract says exists, and moving the objectui pin
+    // could not help while the pinned source had nothing to carry
+    // (objectstack#18407, whose parity-gate half waits on this entry).
+    //
+    // The `tree` alias the same module registers is deliberately NOT here: it is
+    // a second spelling of this one block and @objectstack/spec declares no such
+    // key, so curating it would widen the vocabulary past the declaration — the
+    // opposite act — and leave an authoring model two names for one block, which
+    // is the ground `record:chatter` is held out on above.
+    'object-tree',
     'object-metric',
     'object-chart',
     'dashboard',
@@ -102,6 +127,38 @@ export const PUBLIC_BLOCKS = [
     'tabs',
     'accordion',
     'container',
+    // The neutral block container, minted by the 2026-08-29 ruling as the JSON
+    // surface's replacement for the deprecated `div` (objectui#3965, PR #6878).
+    // It landed on every other declaration face — interface, zod mirror,
+    // `SchemaRegistry`, registration, docs page, and 27 catalog fixtures — and
+    // this list was the one face it missed, so the vocabulary taught a type the
+    // contract did not carry (`3619792bf`).
+    //
+    // MEASURED before it was added, because "add it and see" is how a gate
+    // discovers a new population at merge time. `registry-inputs-spec-parity`
+    // (apps/console) does NOT judge it, and not by tolerance: its coverage set is
+    // SPEC-shaped — `Object.keys(ComponentPropsMap)`, filtered to what this repo
+    // registers with inputs. It never reads this list, and membership here is
+    // neither necessary nor sufficient for being judged: `element:record_picker`
+    // is judged while absent from this list, and `flex` / `grid` / `stack` /
+    // `card` / `container` are all listed here and all unjudged, because
+    // `@objectstack/spec@17` carries no entry for ANY Tier B layout primitive. So
+    // `box` joins a spec-less population five types deep rather than opening a
+    // new one; it needs no spec entry, and no gate needed loosening to accept it.
+    //
+    // ⚠️ And "not on this list" never meant "not on an authoring surface". `box`
+    // has been validated all along through the OTHER consumer of the same
+    // `inputs`: `components/src/renderers/layout/page.tsx` builds the JSX-page
+    // compiler's manifest from `getKnownTypes()`, registry-wide. What this list
+    // gates is `getPublicConfigs()` — the curated AI-authoring vocabulary, and
+    // through `sdui-parser/scripts/gen-manifest.ts` the published
+    // `sdui.manifest.json` and `sdui-intrinsics.d.ts`. THAT is the surface `box`
+    // was missing from, which is a narrower and truer statement of the gap than
+    // "the contract does not know it".
+    //
+    // The measurement is pinned next to the roster census in `apps/console`, over
+    // the DERIVED container population rather than over this list.
+    'box',
     'page:header',
     'text',
     'image',

package/dist/theme/ThemeEngine.js

@@ -124,7 +124,7 @@ export function generateColorVars(colors) {
 // (`fontSize` / `fontWeight` / `lineHeight` / `letterSpacing`, plus
 // `fontFamily.heading` / `fontFamily.mono`) became TOMBSTONES: the schema now
 // rejects them by name and their prescription points at `theme.customVars`, the
-// declared — and since #5021 the only — door for a custom property. A
+// declared — and since objectstack-ai/objectstack#5021 the only — door for a custom property. A
 // `--z-modal` or a `--duration-fast` is authored there now, emitted verbatim as
 // `--<key>: <value>`.
 //

package/dist/utils/chart-category-key.d.ts

@@ -0,0 +1,82 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * chart-category-key — the ONE answer to "which result column carries the
+ * CATEGORY?" for an object-bound chart (objectui#8269).
+ *
+ * The mirror of `chart-measure-key` (objectui#8266) on the other axis. That
+ * card landed `chartMeasureKey` over the contract's `chartAggregateValueKey`;
+ * the contract publishes a CATEGORY sibling in the same module —
+ * `chartAggregateCategoryKey` — and nothing in this repository read it.
+ *
+ * ## The disagreement this replaces
+ *
+ * Both dashboard relays composed the category binding as a LITERAL FLOOR:
+ *
+ *   const xAxisKey = options.xField || 'name';
+ *
+ * and handed it to the `object-chart` node without ever consulting the
+ * `aggregate` that decides it. An object-bound aggregate returns one row per
+ * group, keyed by the raw `groupBy` field, so a widget declaring
+ * `aggregate: { function: 'count', groupBy: 'status' }` and no `options.xField`
+ * bound `'name'` against rows keyed `'status'`.
+ *
+ * Unlike the measure half, this one is LOUD: `hasNoCategoryKey`
+ * (`plugin-charts/src/AdvancedChartImpl.tsx`, framework#4033) fires and the
+ * author reads "This chart cannot plot its category axis: no row has a `name`
+ * field." The diagnostic is wrong-CAUSE — it names a binding the author never
+ * wrote and never mentions the `groupBy` they did — so it points at the wrong
+ * layer. Being loud makes it a lesser harm than objectui#8266, not a
+ * non-defect: measured over the rows a fieldless count returns,
+ * `[{status:'open',count:2},{status:'paid',count:5}]`, an `xAxisKey` of
+ * `'name'` refuses under BOTH series bindings, i.e. objectui#8266's fix does
+ * not reach this authoring shape at all.
+ *
+ * ## Why the answer is delegated rather than restated
+ *
+ * Restating the rule here would make this file a second opinion of a question
+ * the contract already answers — the objectui#5042 / #7544 / #8193 / #8168
+ * drift shape that `chart-measure-key` exists to end. So the rule stays
+ * upstream in `@objectstack/spec/ui` and this is the seam objectui-side callers
+ * share.
+ *
+ * ## ⚠️ NOT the same function as `resolveChartCategoryField`
+ *
+ * `plugin-charts`' own `resolveChartCategoryField` (objectui#8168) reads
+ * `aggregate.groupBy` first too — which is exactly why `ObjectChart` does NOT
+ * refuse this shape at its own level, and then forwards `schema.xAxisKey`
+ * verbatim as the render binding anyway. But the two answer DIFFERENT
+ * questions and must not be collapsed:
+ *
+ *   - `resolveChartCategoryField` answers "which FIELD is the category?" — its
+ *     structured-`groupBy` leg returns `node.field`, because its two readers
+ *     are the refusal (does the author name a category at all?) and the
+ *     field-metadata probe that loads that field's option labels and colours.
+ *   - this function answers "which COLUMN do the returned rows carry it
+ *     under?" — `groupBy.alias ?? groupBy.field` per the contract, because an
+ *     `alias` (admitted by `ChartGroupBySchema`) renames the projected column.
+ *
+ * They coincide whenever no alias is written, which is why the distinction is
+ * easy to miss; conflating them would either bind an axis to a column the rows
+ * do not carry, or probe field metadata for a field that does not exist.
+ */
+import { type ChartAggregateLike } from '@objectstack/spec/ui';
+/**
+ * The result column a chart's category axis / x-axis binding must name.
+ *
+ * `fallback` is the caller's own floor, used ONLY when the contract has no
+ * answer — a chart that declares no `aggregate` at all (its rows are raw
+ * records or authored literals, where the author's `xField` is the right key),
+ * an UNGROUPED aggregate (one row, no category column), or a `groupBy` shape
+ * `ChartGroupBySchema` already rejects. It is never a second opinion about an
+ * aggregate the contract CAN answer for.
+ *
+ * @param aggregate the chart's inline aggregate, or `undefined`
+ * @param fallback  the key to bind when the contract has no answer
+ */
+export declare function chartCategoryKey(aggregate: ChartAggregateLike | undefined, fallback: string): string;

package/dist/utils/chart-category-key.js

@@ -0,0 +1,84 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * chart-category-key — the ONE answer to "which result column carries the
+ * CATEGORY?" for an object-bound chart (objectui#8269).
+ *
+ * The mirror of `chart-measure-key` (objectui#8266) on the other axis. That
+ * card landed `chartMeasureKey` over the contract's `chartAggregateValueKey`;
+ * the contract publishes a CATEGORY sibling in the same module —
+ * `chartAggregateCategoryKey` — and nothing in this repository read it.
+ *
+ * ## The disagreement this replaces
+ *
+ * Both dashboard relays composed the category binding as a LITERAL FLOOR:
+ *
+ *   const xAxisKey = options.xField || 'name';
+ *
+ * and handed it to the `object-chart` node without ever consulting the
+ * `aggregate` that decides it. An object-bound aggregate returns one row per
+ * group, keyed by the raw `groupBy` field, so a widget declaring
+ * `aggregate: { function: 'count', groupBy: 'status' }` and no `options.xField`
+ * bound `'name'` against rows keyed `'status'`.
+ *
+ * Unlike the measure half, this one is LOUD: `hasNoCategoryKey`
+ * (`plugin-charts/src/AdvancedChartImpl.tsx`, framework#4033) fires and the
+ * author reads "This chart cannot plot its category axis: no row has a `name`
+ * field." The diagnostic is wrong-CAUSE — it names a binding the author never
+ * wrote and never mentions the `groupBy` they did — so it points at the wrong
+ * layer. Being loud makes it a lesser harm than objectui#8266, not a
+ * non-defect: measured over the rows a fieldless count returns,
+ * `[{status:'open',count:2},{status:'paid',count:5}]`, an `xAxisKey` of
+ * `'name'` refuses under BOTH series bindings, i.e. objectui#8266's fix does
+ * not reach this authoring shape at all.
+ *
+ * ## Why the answer is delegated rather than restated
+ *
+ * Restating the rule here would make this file a second opinion of a question
+ * the contract already answers — the objectui#5042 / #7544 / #8193 / #8168
+ * drift shape that `chart-measure-key` exists to end. So the rule stays
+ * upstream in `@objectstack/spec/ui` and this is the seam objectui-side callers
+ * share.
+ *
+ * ## ⚠️ NOT the same function as `resolveChartCategoryField`
+ *
+ * `plugin-charts`' own `resolveChartCategoryField` (objectui#8168) reads
+ * `aggregate.groupBy` first too — which is exactly why `ObjectChart` does NOT
+ * refuse this shape at its own level, and then forwards `schema.xAxisKey`
+ * verbatim as the render binding anyway. But the two answer DIFFERENT
+ * questions and must not be collapsed:
+ *
+ *   - `resolveChartCategoryField` answers "which FIELD is the category?" — its
+ *     structured-`groupBy` leg returns `node.field`, because its two readers
+ *     are the refusal (does the author name a category at all?) and the
+ *     field-metadata probe that loads that field's option labels and colours.
+ *   - this function answers "which COLUMN do the returned rows carry it
+ *     under?" — `groupBy.alias ?? groupBy.field` per the contract, because an
+ *     `alias` (admitted by `ChartGroupBySchema`) renames the projected column.
+ *
+ * They coincide whenever no alias is written, which is why the distinction is
+ * easy to miss; conflating them would either bind an axis to a column the rows
+ * do not carry, or probe field metadata for a field that does not exist.
+ */
+import { chartAggregateCategoryKey } from '@objectstack/spec/ui';
+/**
+ * The result column a chart's category axis / x-axis binding must name.
+ *
+ * `fallback` is the caller's own floor, used ONLY when the contract has no
+ * answer — a chart that declares no `aggregate` at all (its rows are raw
+ * records or authored literals, where the author's `xField` is the right key),
+ * an UNGROUPED aggregate (one row, no category column), or a `groupBy` shape
+ * `ChartGroupBySchema` already rejects. It is never a second opinion about an
+ * aggregate the contract CAN answer for.
+ *
+ * @param aggregate the chart's inline aggregate, or `undefined`
+ * @param fallback  the key to bind when the contract has no answer
+ */
+export function chartCategoryKey(aggregate, fallback) {
+    return chartAggregateCategoryKey(aggregate) ?? fallback;
+}

package/dist/utils/chart-measure-key.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * chart-measure-key — the ONE answer to "which result column carries the
+ * measure?" for an object-bound chart (objectui#8266).
+ *
+ * ## The disagreement this replaces
+ *
+ * The question was answered independently in three places, and for a FIELDLESS
+ * `count` — the normal way to author "how many records per status", and the
+ * most common dashboard chart there is — two of them answered differently:
+ *
+ *   - the ROW PROJECTION (`aggregateValueKey` / `aggregateRecords` /
+ *     `runAggregate`'s alias, all in `plugin-charts/src/ObjectChart.tsx`) keys
+ *     the value column `'count'`, the alias the engine projects `COUNT(*)`
+ *     under;
+ *   - the SERIES BINDING, spelled twice in `plugin-dashboard`
+ *     (`DashboardGridLayout.tsx` and `DashboardRenderer.tsx`), read
+ *     `aggregate.field || (options.yField || 'value')` and so bound `'value'`.
+ *
+ * A `dataKey` naming a column no row carries plots nothing, and nothing says
+ * so: measured on `origin/main` `0fa7a9c83`, rows `[{status:'open',count:2},
+ * {status:'paid',count:5}]` with `series:[{dataKey:'value'}]` rendered a
+ * `.recharts-surface` with the category ticks "open"/"paid", **0 bars, 0
+ * rectangles**, no refusal and no empty state — the same rows under
+ * `dataKey:'count'` drew 2 rectangles. An empty chart reads as "no data yet",
+ * which is exactly what an author with a genuinely empty object also sees.
+ *
+ * ## Why the answer is delegated rather than restated
+ *
+ * `chartAggregateValueKey` in `@objectstack/spec/ui` is the CONTRACT's own
+ * derivation — "the VALUE column an object-bound aggregate produces … what a
+ * chart's series / y-axis binding must name". Producers and checkers already
+ * read it. Restating the rule here would make this file a fourth opinion of the
+ * same question, which is the shape (objectui#5042 / #7544 / #8193 / #8168)
+ * this module exists to end. So the rule lives upstream in the spec and this is
+ * the seam objectui-side callers share, exactly as `humanizeLabel` (objectui#5444)
+ * and `buildChartSeries` (ADR-0021) already are.
+ *
+ * ⛔ The inverse fix — making the row projection key a fieldless count
+ * `'value'` — is not available: it contradicts a pin the tree already carries
+ * (`ObjectChart.aggregateResultColumns.test.ts`) and renames the column every
+ * other consumer reads, including the engine's own `COUNT(*)` alias.
+ */
+import { type ChartAggregateLike } from '@objectstack/spec/ui';
+export type { ChartAggregateLike };
+/**
+ * The result column a chart's series must bind to.
+ *
+ * `fallback` is the caller's own floor, used ONLY when the contract has no
+ * answer — a chart that declares no `aggregate` at all (its rows are raw
+ * records or authored literals, where the author's `yField` is the right key),
+ * or an aggregate shape `ChartAggregateSchema` already rejects. It is never a
+ * second opinion about an aggregate the contract CAN answer for.
+ *
+ * @param aggregate the chart's inline aggregate, or `undefined`
+ * @param fallback  the key to bind when the contract has no answer
+ */
+export declare function chartMeasureKey(aggregate: ChartAggregateLike | undefined, fallback: string): string;

package/dist/utils/chart-measure-key.js

@@ -0,0 +1,65 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * chart-measure-key — the ONE answer to "which result column carries the
+ * measure?" for an object-bound chart (objectui#8266).
+ *
+ * ## The disagreement this replaces
+ *
+ * The question was answered independently in three places, and for a FIELDLESS
+ * `count` — the normal way to author "how many records per status", and the
+ * most common dashboard chart there is — two of them answered differently:
+ *
+ *   - the ROW PROJECTION (`aggregateValueKey` / `aggregateRecords` /
+ *     `runAggregate`'s alias, all in `plugin-charts/src/ObjectChart.tsx`) keys
+ *     the value column `'count'`, the alias the engine projects `COUNT(*)`
+ *     under;
+ *   - the SERIES BINDING, spelled twice in `plugin-dashboard`
+ *     (`DashboardGridLayout.tsx` and `DashboardRenderer.tsx`), read
+ *     `aggregate.field || (options.yField || 'value')` and so bound `'value'`.
+ *
+ * A `dataKey` naming a column no row carries plots nothing, and nothing says
+ * so: measured on `origin/main` `0fa7a9c83`, rows `[{status:'open',count:2},
+ * {status:'paid',count:5}]` with `series:[{dataKey:'value'}]` rendered a
+ * `.recharts-surface` with the category ticks "open"/"paid", **0 bars, 0
+ * rectangles**, no refusal and no empty state — the same rows under
+ * `dataKey:'count'` drew 2 rectangles. An empty chart reads as "no data yet",
+ * which is exactly what an author with a genuinely empty object also sees.
+ *
+ * ## Why the answer is delegated rather than restated
+ *
+ * `chartAggregateValueKey` in `@objectstack/spec/ui` is the CONTRACT's own
+ * derivation — "the VALUE column an object-bound aggregate produces … what a
+ * chart's series / y-axis binding must name". Producers and checkers already
+ * read it. Restating the rule here would make this file a fourth opinion of the
+ * same question, which is the shape (objectui#5042 / #7544 / #8193 / #8168)
+ * this module exists to end. So the rule lives upstream in the spec and this is
+ * the seam objectui-side callers share, exactly as `humanizeLabel` (objectui#5444)
+ * and `buildChartSeries` (ADR-0021) already are.
+ *
+ * ⛔ The inverse fix — making the row projection key a fieldless count
+ * `'value'` — is not available: it contradicts a pin the tree already carries
+ * (`ObjectChart.aggregateResultColumns.test.ts`) and renames the column every
+ * other consumer reads, including the engine's own `COUNT(*)` alias.
+ */
+import { chartAggregateValueKey } from '@objectstack/spec/ui';
+/**
+ * The result column a chart's series must bind to.
+ *
+ * `fallback` is the caller's own floor, used ONLY when the contract has no
+ * answer — a chart that declares no `aggregate` at all (its rows are raw
+ * records or authored literals, where the author's `yField` is the right key),
+ * or an aggregate shape `ChartAggregateSchema` already rejects. It is never a
+ * second opinion about an aggregate the contract CAN answer for.
+ *
+ * @param aggregate the chart's inline aggregate, or `undefined`
+ * @param fallback  the key to bind when the contract has no answer
+ */
+export function chartMeasureKey(aggregate, fallback) {
+    return chartAggregateValueKey(aggregate) ?? fallback;
+}

package/dist/utils/chart-presentation.d.ts

@@ -5,58 +5,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/**
- * chart-presentation — the AUTHORED half of a dataset-bound chart, lowered onto
- * the bindings {@link buildChartSeries} derived from the dataset selection.
- *
- * `chart-series.ts` beside this file owns the DATA half: which columns become
- * series, which rows, which buckets. This file owns everything the author gets
- * to say about how that data LOOKS — the ruled data/presentation split of
- * objectui#4229, stated once:
- *
- *  - **Data (derived, never forwarded)** — series MEMBERSHIP and the column each
- *    binding reads. Concretely `buildChartSeries`' `dataKey`s, `xAxisKey`, and
- *    the spec's two binding keys `ChartSeries.name` and `ChartAxis.field`.
- *  - **Presentation (authored, merged forward)** — everything else on those same
- *    objects: `series[].type` (the per-series mark), `series[].yAxis` (which
- *    axis it binds to), `label`/`color`/`stack`/`variant`/`dashArray`/`opacity`,
- *    the axis definitions' `title`/`format`/`min`/`max`/`stepSize`/
- *    `showGridLines`/`position`/`logarithmic`, and the chart chrome
- *    (`showLegend`, `showDataLabels`, `colors`, `annotations`, …).
- *
- * ## Why it lives in `@object-ui/core` rather than in one plugin
- *
- * It was written for `plugin-dashboard`'s `DatasetWidget` (#3135 → objectstack#7016
- * → #4229) and lifted here by objectui#4877, when `plugin-report`'s embedded
- * report chart turned out to need the SAME merge over the same spec shapes: the
- * report was forwarding six keys and dropping every authored chrome key the
- * schema declares, and re-deriving this beside the dashboard's copy is exactly
- * the duplication objectui#4389 filed as a defect (two longhand copies of the
- * analytics label net, one per plugin, drifting apart).
- *
- * Everything here is a pure data transform over plain records, so it sits below
- * both plugins with no React and no i18n — the same layering `chart-series.ts`
- * already has (see {@link OptionLabelTranslator} there for why an i18n-resolved
- * string always arrives as an ARGUMENT rather than being read here).
- *
- * ## Two entry points, because the two surfaces declare axes differently
- *
- * A dashboard widget's `chartConfig` spells its axes as spec `ChartAxis`
- * OBJECTS. A report's `chart.xAxis` / `chart.yAxis` are bare dimension/measure
- * NAME strings — on that surface the axes are pure DATA (they ARE the selection)
- * and carry no presentation at all. So:
- *
- *  - {@link mergeAuthoredPresentation} is the object-axis entry point: series
- *    merge + axis presentation, for a caller whose axes are `ChartAxis` objects.
- *  - {@link mergeAuthoredSeries} is the series merge ALONE, for a caller whose
- *    axes are names. That split is structural, not a guard: handing a bare
- *    string to {@link mergeAuthoredPresentation} would run it through
- *    `axisPresentation`, which reads nothing off a string and would synthesise a
- *    `yAxis: [{}]` entry — a y-axis declaring nothing but its own existence,
- *    which is precisely how the COUNT of entries turns on a secondary axis. A
- *    surface that cannot author axis presentation should not be able to reach
- *    the code that reads it.
- */
 import type { ChartSeriesBinding } from './chart-series.js';
 /** Authored spec `ChartSeries` presentation, in the renderer's internal spelling. */
 export interface AuthoredSeriesPresentation {
@@ -76,39 +24,25 @@ export type MergedChartSeries = ChartSeriesBinding & AuthoredSeriesPresentation;
  * One authored `ChartSeries`, minus its `name` — i.e. everything about it that
  * is presentation rather than membership.
  *
- * `type` is narrowed to the three families that COMPOSE on one cartesian plot,
- * because this array reaches the renderer already speaking the internal shape
- * (`ChartRenderer` forwards a `dataKey`-shaped array untouched, so
- * `normalizeChartSchema`'s own identical narrowing never sees it). Without the
- * narrowing a `type: 'pie'` would not merely be inert — it would count as a
- * family disagreement in `effectiveChartFamily`, flip the whole chart into a
- * combo, and then draw that series as a bar anyway.
+ * `type` is narrowed to the three families that COMPOSE on one cartesian plot.
+ * Without the narrowing a `type: 'pie'` would not merely be inert — it would
+ * count as a family disagreement in `effectiveChartFamily`, flip the whole
+ * chart into a combo, and then draw that series as a bar anyway.
+ *
+ * `ChartRenderer` now narrows the same way for every series it receives,
+ * `dataKey`-shaped or not (`01c27c431` fixed the fast path that used to
+ * forward a `dataKey`-shaped array straight through, so `normalizeChartSchema`'s
+ * own identical narrowing never saw it) — so this module is no longer that
+ * narrowing's only line of defense. It stays anyway:
+ * `AuthoredSeriesPresentation.chartType` is a typed, narrower field
+ * (`'bar' | 'line' | 'area'`) this module's own callers read directly, and the
+ * double narrowing downstream is idempotent.
  */
 export declare function seriesPresentation(raw: Record<string, unknown>): AuthoredSeriesPresentation;
-/**
- * One authored `ChartAxis`, minus its `field` — the axis's presentation.
- *
- * `field` is the one DATA key on an axis (it names the plotted column), and
- * dropping it here is what keeps membership with the dataset **structurally**
- * rather than by a guard: `normalizeChartSchema` synthesises series out of
- * `yAxis[].field` when a chart declares no series, so a forwarded `field`
- * would be a live membership channel on an empty selection. With it gone the
- * axis carries scale and chrome only, and the count of entries — which is what
- * turns on the secondary axis (`yAxes.length > 1`) — survives, including for
- * an entry that declares nothing but its own existence.
- *
- * Keys the renderer does not read on a given axis are dropped by
- * `normalizeChartSchema`, the ONE normalization layer (#2880 S1): today it
- * keeps `format`/`title`/`showGridLines` on the x-axis and the full set on the
- * y-axes. That narrowing is deliberately NOT mirrored here — a second copy
- * would drift from the renderer's real capability the moment it grew.
- */
-export declare function axisPresentation(raw: unknown): Record<string, unknown>;
 /**
  * Merge an authored `series[]` array's PRESENTATION onto the bindings the
- * dataset selection derived — the series half of #4229's split, and the whole
- * of it for a surface whose axes are names rather than objects (see the file
- * header).
+ * dataset selection derived — the series half of #4229's split, and the only
+ * half this module lowers (see the file header).
  *
  * The match rule is **by name/key**: an authored `series[].name` is paired with
  * the derived binding whose `dataKey` it equals, and the pairing decides
@@ -136,28 +70,10 @@ export declare function axisPresentation(raw: unknown): Record<string, unknown>;
  */
 export declare function mergeAuthoredSeries(derived: ChartSeriesBinding[], authoredSeries: unknown): MergedChartSeries[];
 /**
- * Merge an authored chart config's PRESENTATION onto the series and axes the
- * dataset selection derived — the one place that happens for a surface whose
- * axes are spec `ChartAxis` OBJECTS (#4229).
- *
- * The series half is {@link mergeAuthoredSeries}; see it for the match rule and
- * for why membership is safe. The axes half reads `xAxis` / `yAxis` through
- * {@link axisPresentation}, which is why a surface spelling those as bare NAME
- * strings must call `mergeAuthoredSeries` directly instead (file header).
- *
- * @param derived the bindings {@link buildChartSeries} produced from the selection
- * @param raw the authored chart config (anything, incl. absent)
- * @returns the merged series, plus the presentation-only axes to spread onto
- *   the chart schema (absent when the author declared none)
- */
-export declare function mergeAuthoredPresentation(derived: ChartSeriesBinding[], raw: unknown): {
-    series: MergedChartSeries[];
-    axes: Record<string, unknown>;
-};
-/**
- * Lower an authored chart config's CHROME (spec `ChartConfigSchema` /
- * `ReportChartSchema` — the same keys on both) onto the chart schema a
- * dataset-bound surface hands the renderer.
+ * Lower an authored chart config's CHROME (spec
+ * `DashboardWidgetChartConfigSchema` / `ReportChartSchema`, both extensions of
+ * `ChartConfigSchema` that keep its chrome keys unchanged) onto the chart
+ * schema a dataset-bound surface hands the renderer.
  *
  * ## Why this is a whitelist and not a spread
  *
@@ -181,20 +97,48 @@ export declare function mergeAuthoredPresentation(derived: ChartSeriesBinding[],
  *     exists to remove.
  *  2. **It does not fight the dataset derivation.** `type` stays out: the
  *     calling surface's own type already picks the chart family, which is the
- *     dataset path's chart-family channel.
- *
- * `aria` is the one declared key with **no reader at all**: `AdvancedChartImpl`
- * has no `aria` prop, and `SchemaRenderer`'s ARIA injection reads the FLAT
- * `ariaLabel`/`ariaDescribedBy`/`role`, never a nested `aria` object. It is
- * therefore left unforwarded on purpose (criterion 1) rather than papered over
- * with a caller-side flattening that would also collide with the accessible
- * name `description` already sets — reported back to objectstack#5175's
- * narrowing half instead.
+ *     dataset path's chart-family channel. The spec agrees on the dashboard
+ *     carrier: since 17.5.0 `DashboardWidgetChartConfigSchema` refuses
+ *     `chartConfig.type` at parse, with `xAxis` / `yAxis` / `series`, none of
+ *     which this whitelist ever lowered (objectui#11315).
+ *
+ * `aria` is not lowered either. No renderer reads it: `AdvancedChartImpl` has
+ * no `aria` prop, and `SchemaRenderer`'s ARIA injection reads the FLAT
+ * `ariaLabel`/`ariaDescribedBy`/`role`, never a nested `aria` object (criterion
+ * 1). And it is no longer declared: spec 17.5.0 retired `ChartConfig.aria` as
+ * a `retiredKey` tombstone (objectstack#17751, objectui#4044), so an authored
+ * one is refused at parse. The accessible name a chart applies is
+ * `description`, above.
  *
  * `title` IS emitted here. A caller that paints the title itself (the report
  * renderer's own `h3` above the chart) must drop it from the result, or the
  * chart draws a second one.
  *
+ * ## `title` / `subtitle` / `description` are `I18nLabel`, and travel as such
+ *
+ * `ChartConfigSchema` types all three as the spec's `I18nLabel` union — a plain
+ * string OR an inline locale map — so all three are lowered by
+ * {@link forwardedI18nLabel}, which hands the authored value on untouched for
+ * the renderer to resolve against the viewer's language. Read that helper for
+ * why resolving cannot happen in this package.
+ *
+ * ⚠️ LEDGERED, by name, as still unresolved after objectui#9038 — not in
+ * that card's scope and not reached by the change above:
+ *
+ *  - **A series `label`** still goes through {@link labelText}'s
+ *    first-string-wins pick, the design objectui#4020 ledgered and a caller
+ *    can override. Not reopened here.
+ *
+ * ✓ CLEARED, objectui#9150 — **the report renderer's own heading.**
+ * `DatasetReportChart` (`@object-ui/plugin-report`) still drops `title` from
+ * this result and still paints its own `h3`, but that read site no longer
+ * narrows `chart.title` to a plain string: it resolves the union through
+ * `pickLocalized` against the viewer's language, like every other `I18nLabel`
+ * on that surface. Kept here rather than deleted because the ledger entry is
+ * what the fixing card was dispatched from, and because the FIRST half of it —
+ * that a caller painting the title itself must drop `title` from this result —
+ * is a live constraint on this whitelist, stated above.
+ *
  * @param raw the authored chart config (anything, incl. absent)
  * @param fieldCategoryColors per-category colours resolved from the category
  *   dimension's own select/lookup option colours, merged UNDER an explicit
@@ -203,3 +147,42 @@ export declare function mergeAuthoredPresentation(derived: ChartSeriesBinding[],
  *   derived chart schema and every undeclared key keeps the renderer's default
  */
 export declare function chartConfigPresentation(raw: unknown, fieldCategoryColors?: Record<string, string> | null): Record<string, unknown>;
+/**
+ * Whether a chart of this family IGNORES `compareTo` — the one declaration of
+ * that rule (objectui#7495).
+ *
+ * Every surface that turns a `compareTo` into a comparison reads this; none
+ * keeps a list of its own. The inline chart path (`@object-ui/plugin-charts`'
+ * ObjectChart) skips the comparison fetch and synthesises no overlay series for
+ * these families, and the dataset widget path (`@object-ui/plugin-dashboard`'s
+ * DatasetWidget) forwards no `compareTo` to the executor for a chart of one of
+ * them, so the comparison pass never runs and no overlay series is appended.
+ *
+ *  - `pie` / `donut` / `funnel` — single-distribution charts: a comparison
+ *    overlay has no meaning on them, and the renderer's pie and funnel arms
+ *    draw only `series[0]`.
+ *  - `scatter` (objectui#7402) — a scatter binds ONE measure: the renderer reads
+ *    y through the single `YAxis dataKey={series[0].dataKey}`, so an overlay was
+ *    painted on the PRIMARY's y and "previous period" landed exactly on top of
+ *    "current". Drawing it honestly needs the multi-measure projection declined
+ *    as option A of objectui#7194; `compareTo` on a scatter returns WITH that
+ *    projection.
+ *
+ * It reads the RENDERER's chart family (`bar`, `pie`, `scatter`, …), not a
+ * dashboard widget type: a caller whose widget types alias a family (the
+ * dashboard maps `bubble` to `scatter` and `pyramid` to `funnel`) maps first and
+ * asks about the family. An absent or unrecognised family does NOT ignore
+ * `compareTo` — the comparison runs.
+ *
+ * Why it lives here: the dashboard reaches `@object-ui/plugin-charts` only as a
+ * devDependency, so this package — a runtime dependency of both — is the one
+ * place both paths can read. Two copies were how the lists drifted apart: the
+ * dashboard's said "scatter only" while the charts package said all four, so a
+ * compare-to pie widget ran a comparison query whose overlay the renderer then
+ * dropped (objectui#7495; objectui#4389 is the precedent that a second copy of
+ * chart-presentation logic is a defect).
+ *
+ * @param chartType the chart family, or `undefined` when none is declared
+ * @returns `true` for `pie`, `donut`, `funnel` and `scatter`; `false` otherwise
+ */
+export declare function chartTypeIgnoresCompareTo(chartType: string | undefined): boolean;