@object-ui/core 17.5.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/theme/index.d.ts

@@ -5,4 +5,4 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';
+export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine.js';

package/dist/theme/index.js

@@ -11,4 +11,4 @@ export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, genera
 // 17.0.0-rc.3 (objectstack#5021) — see ThemeEngine's RETIRED THEME BLOCKS
 // note. `theme.customVars` is the declared door for a `--duration-*` or
 // `--z-*` now.
-generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';
+generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine.js';

package/dist/types/index.d.ts

@@ -30,24 +30,103 @@
  * rather than restated, so there is exactly one declaration left to disagree
  * with — a structural copy would reproduce the defect the moment either side
  * moved. This package already depends on `@object-ui/types`, so the edge exists
- * and adds no cycle, and core's own entry surface is unchanged (`dist/index.d.ts`
- * is byte-identical across the change — measured, both rounds).
+ * and adds no cycle.
+ *
+ * ## The entry-surface sentence that used to close this block is WITHDRAWN
+ *
+ * It read: *core's own entry surface is unchanged (`dist/index.d.ts` is
+ * byte-identical across the change — measured, both rounds)*. The reading was
+ * real, and it certified nothing (objectui#5673).
+ *
+ * `core/dist/index.d.ts` is emitted from a barrel that only FORWARDS this
+ * symbol, and forwarding never restates a shape — not `export *`, and not the
+ * `export type { SchemaNode, … } from './types/index.js'` line that names it.
+ * Only the module that DECLARES the symbol can move. So that file is
+ * byte-identical under any change to a re-exported declaration's shape, naming
+ * the symbol or not, and a gauge that cannot fail for the change class it is
+ * quoted against has discharged nothing.
+ *
+ * ## The gauge that can fail — and how to prove it can, before believing it
+ *
+ * 1. Watch the emitted `.d.ts` of the module that DECLARES the symbol. For
+ *    `SchemaNode` that is `@object-ui/types`' `dist/base.d.ts`, in another
+ *    package — not core's entry, and not core's own `dist/types/index.d.ts`
+ *    either, which forwards exactly as the entry does. For the shape claim
+ *    itself, resolve the symbol through the TypeScript CHECKER from
+ *    `core/dist/index.d.ts`.
+ * 2. Build both legs from a cleared `dist/` AND a cleared
+ *    `tsconfig.tsbuildinfo` — the build info lives outside `dist/`, so
+ *    composite `tsc` skips emit if it survives and two stale trees compare
+ *    equal for free.
+ * 3. CALIBRATE: inject a probe key into the declaring module, rebuild, and
+ *    require the hash you are watching to MOVE; drop the probe, rebuild, and
+ *    require it to come back to its original value. A probe that leaves your
+ *    hash unmoved means the gauge is not wired to this symbol — that is what
+ *    failure looks like here, and no "byte-identical" sentence may be written
+ *    from a gauge that just failed it.
+ *
+ * Run against this file's own claim — probe: one additive optional key on
+ * `BaseSchema`, the shape `SchemaNode` publishes — `@object-ui/types`'
+ * `dist/base.d.ts` moved and came back, while `core/dist/index.d.ts` and
+ * `core/dist/types/index.d.ts` held one hash across all three legs. The
+ * withdrawn sentence was watching the two files that cannot move.
  *
  * The collision is only observable from a package that resolves BOTH through
  * `node_modules`; the pin therefore lives in `@object-ui/react`
  * (`src/__tests__/SchemaNode.reconciliation.test.ts`), not here.
  */
 export type { SchemaNode } from '@object-ui/types';
-import type { SchemaNode } from '@object-ui/types';
 /**
- * ⛔ Deliberately NOT reconciled with `@object-ui/types`' `ComponentRendererProps`
- * (objectui#4594). The two declarations differ — types' is generic
- * (`< TSchema extends BaseSchema = BaseSchema >`), this one is not — but that
- * card measured **zero consumers** of this declaration, so reconciling it here
- * would be an unmeasured change riding a card that was scoped to `SchemaNode`.
- * It stays dual-declared until #4594 is dispatched on its own evidence.
+ * One `ComponentRendererProps` (objectui#4594).
+ *
+ * This package used to hand-declare `interface ComponentRendererProps
+ * { schema: SchemaNode; [key: string]: any }` here — two lines below `SchemaNode`
+ * and against `@object-ui/types`' generic
+ * `ComponentRendererProps< TSchema extends BaseSchema = BaseSchema >`. Same name,
+ * two packages the same consumers import together: the second such pair in this
+ * one file, and the third across this fault line after `SchemaNode` (#4580) and
+ * `ComponentInput` (#4972).
+ *
+ * **`@object-ui/types`' generic declaration wins**, and is RE-EXPORTED rather
+ * than restated, so there is exactly one declaration left to disagree with — a
+ * structural copy would reproduce the defect the moment either side moved.
+ *
+ * Reconciled now, at **zero consumers** — re-verified on the merged ref rather
+ * than inherited from the card: repo-wide, `ComponentRendererProps` occurred only
+ * at the two declarations, each package's own entry re-export, and one line of
+ * `packages/components/CHANGELOG.md` recording that nothing used it. Zero
+ * consumers is why this is cheap today and would not stay cheap: the day someone
+ * imports it, which declaration they get decides whether a primitive node is
+ * admissible.
+ *
+ * ## What the re-export moves, and how that was measured
+ *
+ * It is NOT surface-neutral, and the gauge that would have said so is vacuous.
+ * `core/dist/index.d.ts` is emitted from a barrel that only FORWARDS this
+ * symbol — its `export type { … }` line names it, and naming is not restating
+ * — so that file is byte-identical under ANY change to a re-exported
+ * declaration's shape and cannot fail for this change class (objectui#5673,
+ * where the `SchemaNode` block above withdraws the same reading and carries the
+ * probe calibration that tells a live gauge from this one).
+ *
+ * Measured instead by resolving the symbol through the TypeScript CHECKER from
+ * `core/dist/index.d.ts`, over a `dist/` + `tsconfig.tsbuildinfo` clean rebuild
+ * on both legs (the build info lives outside `dist/`, so composite `tsc` skips
+ * emit if it survives and two stale trees compare equal for free):
+ *
+ * ```
+ * before   ComponentRendererProps            schema: BaseSchema | string | number | boolean | null | undefined
+ * after    ComponentRendererProps<TSchema>   schema: TSchema  (TSchema extends BaseSchema = BaseSchema)
+ * ```
+ *
+ * So `schema` NARROWS back to the object form — core's copy had silently widened
+ * when #4608 made `SchemaNode` a re-export of types' union, which is the interim
+ * state this card closes — and the type gains a parameter. Nothing downstream
+ * can observe either move, because nothing imports it.
+ *
+ * The collision is only observable from a package that resolves BOTH through
+ * `node_modules`; the pin therefore lives in `@object-ui/react`
+ * (`src/__tests__/ComponentRendererProps.reconciliation.test.ts`), not here —
+ * same position, same reason, as `SchemaNode`'s pin above.
  */
-export interface ComponentRendererProps {
-    schema: SchemaNode;
-    [key: string]: any;
-}
+export type { ComponentRendererProps } from '@object-ui/types';

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;
+}