@object-ui/core 17.6.0 → 17.7.0

package/dist/utils/chart-presentation.js

@@ -8,8 +8,11 @@
 const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 /**
  * An i18n label is a plain string or a `{ en, zh-CN, … }` record; charts render
- * a string. Same pick `normalizeChartSchema` makes, so a label reads the same
- * on both paths.
+ * a string.
+ *
+ * ⚠️ Its one caller is {@link seriesPresentation}'s `label`. An axis `title`
+ * read this too until `061f5e829` moved it off the pick, and the axis lowering
+ * itself is gone since objectui#11372 (file header).
  *
  * **First-string-wins, deliberately, and deliberately NOT locale-aware** — this
  * package is React-free and holds no i18n provider, so it cannot know which
@@ -27,17 +30,83 @@ function labelText(v) {
     }
     return undefined;
 }
+/**
+ * An authored `I18nLabel` that travels to the renderer **unresolved** — the
+ * chart's own `title` / `subtitle` / `description` (objectui#9038).
+ *
+ * ## Why this does not resolve, and why that is not {@link labelText}'s answer
+ *
+ * These three keys are lowered onto a chart SCHEMA slot that already declares
+ * the union: `normalizeChartSchema` (`@object-ui/plugin-charts`) resolves
+ * `title`/`subtitle`/`description` through `pickLocalized` with the viewer's
+ * language, which `ChartRenderer` reads from `useObjectTranslation` and hands
+ * down (objectui#8943), and `ObjectChart` reads `schema.title` through the same
+ * resolver for its drill heading. So the value's one resolution point is
+ * already downstream of here, holding the one thing this package does not have
+ * — the viewer. Forwarding is what lets that resolver see the value at all.
+ *
+ * Resolving here is not merely unnecessary, it is unavailable: `pickLocalized`
+ * lives in `@object-ui/i18n`, which DEPENDS on this package. Declaring the
+ * reverse edge makes the build graph cyclic (measured: `turbo run build
+ * --filter=@object-ui/core` refuses with `Cyclic dependency detected`), and
+ * that package's entry point is a React provider plus hooks — the layering
+ * this file's header states, arrived at from the other side.
+ *
+ * ⛔ Do NOT "fix" this by reusing {@link labelText}. The two answer different
+ * questions and only one of them is a choice:
+ *
+ *  - `labelText` is a locale-unaware PICK for a slot whose consumer takes a
+ *    plain string. It is wrong for a zh console and is ledgered as such
+ *    (objectui#4020) because a caller that CAN resolve the language overrides
+ *    the merged label — the mitigation depends on the value still existing.
+ *  - The guard this replaced (`typeof v === 'string' && v ? v : undefined`)
+ *    offered no such route: it ERASED the map arm, the `if (title)` guard then
+ *    skipped the assignment, and the chart drew **no heading at all**, in every
+ *    language, with no diagnostic. Nothing downstream could override a key that
+ *    never arrived.
+ *
+ * ## The admission test, and what it deliberately does not decide
+ *
+ * A plain string, or a record carrying at least one usable string entry. That
+ * is the same "is there anything here" question the `if (title)` truthiness
+ * guard always asked, extended to the map arm — it does NOT decide which limb
+ * wins, which stays `pickLocalized`'s alone. Everything else (a number, a
+ * boolean, an array, `''`, `{}`, a record with no string value) is refused
+ * exactly as before, so no key reaches the caller that cannot render, and the
+ * `@returns` contract below — only keys that resolved — still holds.
+ *
+ * The map is forwarded VERBATIM: `InlineLocaleMapSchema` is
+ * `z.record(<tag>, z.string())` and enforcing that belongs at the parse, not in
+ * a renderer-side coercion (AGENTS.md #0.1). A non-string entry falls through
+ * `pickLocalized`'s limbs exactly as an absent one does, which is why admitting
+ * the record on the strength of one usable entry cannot paint `[object
+ * Object]`.
+ */
+function forwardedI18nLabel(v) {
+    if (typeof v === 'string')
+        return v || undefined;
+    if (isRecord(v) && Object.values(v).some((x) => typeof x === 'string' && x)) {
+        return v;
+    }
+    return undefined;
+}
 /**
  * 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 function seriesPresentation(raw) {
     const out = {};
@@ -61,54 +130,10 @@ export function seriesPresentation(raw) {
         out.opacity = raw.opacity;
     return out;
 }
-/**
- * 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 function axisPresentation(raw) {
-    const out = {};
-    if (!isRecord(raw))
-        return out;
-    const title = labelText(raw.title);
-    if (title)
-        out.title = title;
-    if (typeof raw.format === 'string' && raw.format)
-        out.format = raw.format;
-    if (typeof raw.min === 'number' && Number.isFinite(raw.min))
-        out.min = raw.min;
-    if (typeof raw.max === 'number' && Number.isFinite(raw.max))
-        out.max = raw.max;
-    if (typeof raw.stepSize === 'number' && Number.isFinite(raw.stepSize) && raw.stepSize > 0) {
-        out.stepSize = raw.stepSize;
-    }
-    if (typeof raw.showGridLines === 'boolean')
-        out.showGridLines = raw.showGridLines;
-    if (raw.position === 'left' || raw.position === 'right' || raw.position === 'top' || raw.position === 'bottom') {
-        out.position = raw.position;
-    }
-    if (typeof raw.logarithmic === 'boolean')
-        out.logarithmic = raw.logarithmic;
-    return out;
-}
 /**
  * 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
@@ -149,43 +174,10 @@ export function mergeAuthoredSeries(derived, authoredSeries) {
     });
 }
 /**
- * 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 function mergeAuthoredPresentation(derived, raw) {
-    const config = isRecord(raw) ? raw : {};
-    const series = mergeAuthoredSeries(derived, config.series);
-    const axes = {};
-    const xAxis = axisPresentation(config.xAxis);
-    if (Object.keys(xAxis).length > 0)
-        axes.xAxis = xAxis;
-    // The COUNT of y-axis entries is itself presentation — it is what declares a
-    // secondary axis — so every declared entry keeps its slot even when it
-    // carries nothing but `field` (which is data and does not travel).
-    const yAxisRaw = Array.isArray(config.yAxis)
-        ? config.yAxis
-        : config.yAxis !== undefined
-            ? [config.yAxis]
-            : [];
-    if (yAxisRaw.length > 0)
-        axes.yAxis = yAxisRaw.map(axisPresentation);
-    return { series, axes };
-}
-/**
- * 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
  *
@@ -209,20 +201,48 @@ export function mergeAuthoredPresentation(derived, raw) {
  *     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.
+ *     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 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.
+ * `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
@@ -233,18 +253,20 @@ export function mergeAuthoredPresentation(derived, raw) {
 export function chartConfigPresentation(raw, fieldCategoryColors) {
     const config = isRecord(raw) ? raw : {};
     const out = {};
-    const text = (v) => (typeof v === 'string' && v ? v : undefined);
     if (typeof config.showLegend === 'boolean')
         out.showLegend = config.showLegend;
     if (typeof config.showDataLabels === 'boolean')
         out.showDataLabels = config.showDataLabels;
-    const title = text(config.title);
+    // The three `I18nLabel` slots, carried through unresolved — see
+    // {@link forwardedI18nLabel} for why this package forwards rather than picks,
+    // and for what is still ledgered as unresolved on purpose.
+    const title = forwardedI18nLabel(config.title);
     if (title)
         out.title = title;
-    const subtitle = text(config.subtitle);
+    const subtitle = forwardedI18nLabel(config.subtitle);
     if (subtitle)
         out.subtitle = subtitle;
-    const description = text(config.description);
+    const description = forwardedI18nLabel(config.description);
     if (description)
         out.description = description;
     // A non-positive height would collapse the plot; the container default is the
@@ -278,3 +300,46 @@ export function chartConfigPresentation(raw, fieldCategoryColors) {
     }
     return out;
 }
+/** The families {@link chartTypeIgnoresCompareTo} answers `true` for. */
+const CHART_TYPES_IGNORING_COMPARE_TO = new Set(['pie', 'donut', 'funnel', 'scatter']);
+/**
+ * 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 function chartTypeIgnoresCompareTo(chartType) {
+    return typeof chartType === 'string' && CHART_TYPES_IGNORING_COMPARE_TO.has(chartType);
+}

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

@@ -10,6 +10,37 @@ export interface ChartResultField {
     label?: string;
     format?: string;
 }
+/**
+ * The OPTIONAL wire discriminator naming which server-side BUILT-IN default
+ * measure a result column is (objectui#7258; producer half objectstack#14492).
+ * The analytics service sets it ONLY on the measures it minted itself with a
+ * hard-coded English default label (`count` → `'Count'`, …); an author-declared
+ * measure never carries it, so its `label` stays the author's verbatim text
+ * (objectui#4106). {@link resolveMeasureLabel} is the one reader.
+ *
+ * Declared BESIDE {@link ChartResultField} rather than on it, deliberately:
+ * `dataset-result-field-spec-parity` pins every key of `ChartResultField` as a
+ * key of the spec's `AnalyticsResult.fields[]`, and the `@objectstack/spec`
+ * this package is built against does not carry `builtinAggregate` yet. The
+ * intersection {@link ChartMeasureField} is what the helpers accept, so a
+ * spec-typed field flows in unchanged today and carries the key the moment
+ * the spec does — structurally, with no cast at the call sites.
+ *
+ * Typed as `string` rather than the closed {@link BuiltinAggregate} union on
+ * purpose: a JSON response is handed here as-is, so the value is validated at
+ * the lookup ({@link isBuiltinAggregate}) instead of trusted at the type.
+ *
+ * TODO(objectstack#14492): once the spec dependency is bumped past the release
+ * that adds `AnalyticsResult.fields[].builtinAggregate`, fold this key into
+ * `ChartResultField` as `DatasetResultField['builtinAggregate']` (pinning the
+ * two closed vocabularies to each other in the parity suite) and retire the
+ * carrier.
+ */
+export interface BuiltinAggregateCarrier {
+    builtinAggregate?: string;
+}
+/** A result field as the series helpers read it: the renderer shape plus the optional discriminator. */
+export type ChartMeasureField = ChartResultField & BuiltinAggregateCarrier;
 /**
  * One renderer-internal series binding produced by {@link buildChartSeries}:
  * WHICH result-set column to draw and what to call it.
@@ -31,6 +62,47 @@ export interface ChartSeriesResult {
     xAxisKey: string | undefined;
     series: ChartSeriesBinding[];
 }
+/**
+ * The closed vocabulary of server-side built-in default measures a result field
+ * can declare itself as (objectui#7258 / objectstack#14492) — the spec's own
+ * measure-aggregate enum spelling (`count_distinct`, not `countDistinct`), so
+ * there is exactly ONE spelling on the wire and this list never grows on its
+ * own: a value outside it is not "a new aggregate", it is an unrecognised one,
+ * and {@link resolveMeasureLabel} treats it as absent.
+ */
+export declare const BUILTIN_AGGREGATES: readonly ["count", "sum", "avg", "min", "max", "count_distinct"];
+/** One member of {@link BUILTIN_AGGREGATES}. */
+export type BuiltinAggregate = (typeof BUILTIN_AGGREGATES)[number];
+/** Runtime membership test for {@link BUILTIN_AGGREGATES}, over an untrusted wire value. */
+export declare function isBuiltinAggregate(value: unknown): value is BuiltinAggregate;
+/**
+ * The LOCALIZED display label per built-in aggregate, as the layer that holds
+ * the i18n provider resolved them (`@object-ui/i18n`'s
+ * `builtinAggregateLabels(tt)`). Partial on purpose: an aggregate the caller
+ * did not resolve falls back to the wire `label`, exactly as if the field had
+ * carried no discriminator.
+ */
+export type BuiltinAggregateLabels = Partial<Record<BuiltinAggregate, string>>;
+/**
+ * The display label of ONE result field, for a legend / axis / tooltip.
+ *
+ * Resolution order (objectui#7258, maintainer ruling B of 2026-09-02):
+ *  1. the field declares itself a built-in default measure
+ *     (`builtinAggregate` ∈ {@link BUILTIN_AGGREGATES}) AND the caller resolved
+ *     a locale label for it → that label. This is the only path that can
+ *     replace a wire `label`, and it is keyed by a STRUCTURAL discriminator —
+ *     never by matching the label's text or the field's name, both of which
+ *     the ruling rejected (a real author measure literally named `count`, or
+ *     labelled `Count`, must keep its own label);
+ *  2. otherwise the wire `label` verbatim — the objectui#4106 contract for an
+ *     author-declared measure (`'Tasks'` reaches the legend untouched);
+ *  3. otherwise the field's `name`.
+ *
+ * So a discriminator the caller has no label for (a provider-less host, or a
+ * value outside the closed vocabulary) costs nothing: the field renders exactly
+ * what it rendered before the discriminator existed.
+ */
+export declare function resolveMeasureLabel(field: ChartMeasureField, labels?: BuiltinAggregateLabels): string;
 /**
  * The bucket a NULL/undefined category VALUE renders under, when the caller
  * supplies no localized label of its own (objectui#4466).
@@ -110,6 +182,16 @@ export interface ChartSeriesOptions {
      * it, so a mismatch costs the null bucket its drill-through.
      */
     nullCategoryLabel?: string;
+    /**
+     * Locale labels for the server's BUILT-IN default measures, keyed by the
+     * wire discriminator a result field carries as `builtinAggregate`
+     * (objectui#7258). Same division of labour as `nullCategoryLabel`: this
+     * package is React-free and i18n-free, so the renderer that holds the
+     * provider resolves the strings (`builtinAggregateLabels(tt)` in
+     * `@object-ui/i18n`) and passes them in. Absent ⇒ every measure keeps its
+     * wire `label`, which for a built-in default is the server's English.
+     */
+    builtinAggregateLabels?: BuiltinAggregateLabels;
 }
 /** Per-CLICK knobs for {@link findChartSeriesRow}, on top of the shared ones. */
 export interface ChartDrillLookupOptions extends ChartSeriesOptions {
@@ -174,7 +256,7 @@ export interface ChartSegmentClickEvent {
     /** The measure value at the click point. */
     value?: number;
 }
-export declare function buildChartSeries(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, fields?: ChartResultField[] | null, options?: ChartSeriesOptions): ChartSeriesResult;
+export declare function buildChartSeries(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, fields?: ChartMeasureField[] | null, options?: ChartSeriesOptions): ChartSeriesResult;
 /**
  * Resolve select/enum dimension VALUES to display LABELS in chart rows.
  *
@@ -362,10 +444,54 @@ export declare function buildDimensionLabelMap(options: unknown, translate?: Opt
  * The object a relationship field points at, or `undefined` when the field is
  * not a relationship (or names no target).
  *
- * The target lives under `reference` on framework-served field defs; older /
- * spec shapes spell it `reference_to` / `referenceTo` / `reference_to_object`,
- * and any of them may carry a bare name, a one-element array, or `{ object }`.
- * Same canonicalization as the dataset designer's `resolveReferenceTo`.
+ * The target lives under `reference` — the ONLY spelling read here, and the same
+ * canonicalization as the dataset designer's `resolveReferenceTo`, which is
+ * narrowed to match in the same pass (objectui#6528). As of objectui#6648 the
+ * CARRIER matches too: a bare string and nothing else. The two helpers are one
+ * doctrine in two files and must never drift — a divergence recreates the
+ * defect one file over.
+ *
+ * The three legacy spellings this dropped (`reference_to` / `referenceTo` /
+ * `reference_to_object`) were censused against every producer, with `reference`
+ * itself as the positive control (445 of 565 lookup / master_detail defs in the
+ * framework tree; ACCEPTED by `ObjectSchema.safeParse` on spec 17.2.0, which
+ * REFUSES all three others BY NAME). No producer emits any of them onto an
+ * object metadata document: `reference_to` was then live only on ObjectUI's own
+ * view/field schema (a different contract, translated INTO from `reference`;
+ * objectui#11070 round 4 moved that contract to `reference` as well),
+ * `referenceTo`'s two producers were retired by objectui#6041, and
+ * `reference_to_object` occurs nowhere in either tree outside this chain and the
+ * test that called it.
+ *
+ * ⚠ Unlike `resolveReferenceTo`, this helper reads the `GET /meta/object/:name`
+ * document DIRECTLY — no `readFields` door strips retired keys on this path. So
+ * the narrowing is load-bearing rather than cosmetic: a stored pre-objectui#6041
+ * row spelling the target `referenceTo` now resolves to `undefined` here, the
+ * walk yields no entry, and the caller keeps the raw value (best-effort by
+ * construction — see {@link resolveDimensionFieldMeta}). That is the intended
+ * outcome: per AGENTS.md #0.1 such a row is a PRODUCER-side defect, and a
+ * lenient consumer here is exactly where it would have stayed hidden. Note
+ * `reference` was already HEAD of the old chain, so any doc carrying both is
+ * unaffected.
+ *
+ * The array and `{ object }` CARRIERS this used to accept were censused on the
+ * same standard and removed with the same reasoning (objectui#6648).
+ * `FieldSchema.reference` is a plain `z.string()`; `ObjectSchema.safeParse`
+ * (spec 17.2.0) ACCEPTS `reference: 'crm_account'` and REFUSES both
+ * `['crm_account']` and `{ object: 'crm_account' }` as `invalid_type`. A
+ * structure-walking, key-position-aware census of both trees found 587
+ * bare-string carriers at the field-def key position and ZERO array or
+ * `{ object }` carriers from any producer — the only ones in either tree were
+ * the green pins asserting this very tolerance. See `resolveReferenceTo` for
+ * the full census, including why a multi-target lookup is NOT what the array
+ * branch was serving: it returned `raw[0]` and discarded the rest, and
+ * polymorphic lookup remains an undeclared, open spec gap.
+ *
+ * This path matters MORE than the designer's for the same reason the spelling
+ * narrowing did: it reads the metadata document directly, with no `readFields`
+ * door in between, so a non-string carrier now degrades visibly (the walk
+ * yields no entry and the caller keeps the raw value) instead of being absorbed
+ * here.
  *
  * The **type gate is deliberate**: only a declared relationship is walked, so a
  * path segment naming a plain field can never be turned into an object name and

package/dist/utils/chart-series.js

@@ -44,6 +44,47 @@
  * know" refuses — one doctrine, and now BOTH branches state it.
  */
 import { pivotBucketId, pivotDimensionValue } from './dataset-pivot.js';
+/**
+ * The closed vocabulary of server-side built-in default measures a result field
+ * can declare itself as (objectui#7258 / objectstack#14492) — the spec's own
+ * measure-aggregate enum spelling (`count_distinct`, not `countDistinct`), so
+ * there is exactly ONE spelling on the wire and this list never grows on its
+ * own: a value outside it is not "a new aggregate", it is an unrecognised one,
+ * and {@link resolveMeasureLabel} treats it as absent.
+ */
+export const BUILTIN_AGGREGATES = ['count', 'sum', 'avg', 'min', 'max', 'count_distinct'];
+/** Runtime membership test for {@link BUILTIN_AGGREGATES}, over an untrusted wire value. */
+export function isBuiltinAggregate(value) {
+    return typeof value === 'string' && BUILTIN_AGGREGATES.includes(value);
+}
+/**
+ * The display label of ONE result field, for a legend / axis / tooltip.
+ *
+ * Resolution order (objectui#7258, maintainer ruling B of 2026-09-02):
+ *  1. the field declares itself a built-in default measure
+ *     (`builtinAggregate` ∈ {@link BUILTIN_AGGREGATES}) AND the caller resolved
+ *     a locale label for it → that label. This is the only path that can
+ *     replace a wire `label`, and it is keyed by a STRUCTURAL discriminator —
+ *     never by matching the label's text or the field's name, both of which
+ *     the ruling rejected (a real author measure literally named `count`, or
+ *     labelled `Count`, must keep its own label);
+ *  2. otherwise the wire `label` verbatim — the objectui#4106 contract for an
+ *     author-declared measure (`'Tasks'` reaches the legend untouched);
+ *  3. otherwise the field's `name`.
+ *
+ * So a discriminator the caller has no label for (a provider-less host, or a
+ * value outside the closed vocabulary) costs nothing: the field renders exactly
+ * what it rendered before the discriminator existed.
+ */
+export function resolveMeasureLabel(field, labels) {
+    const aggregate = field.builtinAggregate;
+    if (isBuiltinAggregate(aggregate)) {
+        const localized = labels?.[aggregate];
+        if (typeof localized === 'string' && localized !== '')
+            return localized;
+    }
+    return field.label ?? field.name;
+}
 /**
  * The bucket a NULL/undefined category VALUE renders under, when the caller
  * supplies no localized label of its own (objectui#4466).
@@ -296,7 +337,13 @@ export function buildChartSeries(rows, dimensions, values, fields, options) {
     const dims = (dimensions ?? []).filter(Boolean);
     const vals = (values ?? []).filter(Boolean);
     const safeRows = Array.isArray(rows) ? rows : [];
-    const labelOf = (name) => (fields ?? []).find((f) => f.name === name)?.label ?? name;
+    // A measure's series label: the locale label when the field declares itself
+    // a built-in default measure and the caller resolved one, else the wire
+    // `label` verbatim (objectui#4106), else the name — see `resolveMeasureLabel`.
+    const labelOf = (name) => {
+        const field = (fields ?? []).find((f) => f.name === name);
+        return field ? resolveMeasureLabel(field, options?.builtinAggregateLabels) : name;
+    };
     // Multi-dimension, single-measure → pivot the second dimension into series.
     if (dims.length >= 2 && vals.length === 1) {
         const xKey = dims[0];
@@ -765,10 +812,54 @@ function fieldDefsOf(schema) {
  * The object a relationship field points at, or `undefined` when the field is
  * not a relationship (or names no target).
  *
- * The target lives under `reference` on framework-served field defs; older /
- * spec shapes spell it `reference_to` / `referenceTo` / `reference_to_object`,
- * and any of them may carry a bare name, a one-element array, or `{ object }`.
- * Same canonicalization as the dataset designer's `resolveReferenceTo`.
+ * The target lives under `reference` — the ONLY spelling read here, and the same
+ * canonicalization as the dataset designer's `resolveReferenceTo`, which is
+ * narrowed to match in the same pass (objectui#6528). As of objectui#6648 the
+ * CARRIER matches too: a bare string and nothing else. The two helpers are one
+ * doctrine in two files and must never drift — a divergence recreates the
+ * defect one file over.
+ *
+ * The three legacy spellings this dropped (`reference_to` / `referenceTo` /
+ * `reference_to_object`) were censused against every producer, with `reference`
+ * itself as the positive control (445 of 565 lookup / master_detail defs in the
+ * framework tree; ACCEPTED by `ObjectSchema.safeParse` on spec 17.2.0, which
+ * REFUSES all three others BY NAME). No producer emits any of them onto an
+ * object metadata document: `reference_to` was then live only on ObjectUI's own
+ * view/field schema (a different contract, translated INTO from `reference`;
+ * objectui#11070 round 4 moved that contract to `reference` as well),
+ * `referenceTo`'s two producers were retired by objectui#6041, and
+ * `reference_to_object` occurs nowhere in either tree outside this chain and the
+ * test that called it.
+ *
+ * ⚠ Unlike `resolveReferenceTo`, this helper reads the `GET /meta/object/:name`
+ * document DIRECTLY — no `readFields` door strips retired keys on this path. So
+ * the narrowing is load-bearing rather than cosmetic: a stored pre-objectui#6041
+ * row spelling the target `referenceTo` now resolves to `undefined` here, the
+ * walk yields no entry, and the caller keeps the raw value (best-effort by
+ * construction — see {@link resolveDimensionFieldMeta}). That is the intended
+ * outcome: per AGENTS.md #0.1 such a row is a PRODUCER-side defect, and a
+ * lenient consumer here is exactly where it would have stayed hidden. Note
+ * `reference` was already HEAD of the old chain, so any doc carrying both is
+ * unaffected.
+ *
+ * The array and `{ object }` CARRIERS this used to accept were censused on the
+ * same standard and removed with the same reasoning (objectui#6648).
+ * `FieldSchema.reference` is a plain `z.string()`; `ObjectSchema.safeParse`
+ * (spec 17.2.0) ACCEPTS `reference: 'crm_account'` and REFUSES both
+ * `['crm_account']` and `{ object: 'crm_account' }` as `invalid_type`. A
+ * structure-walking, key-position-aware census of both trees found 587
+ * bare-string carriers at the field-def key position and ZERO array or
+ * `{ object }` carriers from any producer — the only ones in either tree were
+ * the green pins asserting this very tolerance. See `resolveReferenceTo` for
+ * the full census, including why a multi-target lookup is NOT what the array
+ * branch was serving: it returned `raw[0]` and discarded the rest, and
+ * polymorphic lookup remains an undeclared, open spec gap.
+ *
+ * This path matters MORE than the designer's for the same reason the spelling
+ * narrowing did: it reads the metadata document directly, with no `readFields`
+ * door in between, so a non-string carrier now degrades visibly (the walk
+ * yields no entry and the caller keeps the raw value) instead of being absorbed
+ * here.
  *
  * The **type gate is deliberate**: only a declared relationship is walked, so a
  * path segment naming a plain field can never be turned into an object name and
@@ -781,17 +872,8 @@ export function resolveRelationshipTarget(fieldDef) {
     const type = typeof def.type === 'string' ? def.type.toLowerCase() : '';
     if (!RELATIONSHIP_FIELD_TYPES.has(type))
         return undefined;
-    const raw = def.reference ?? def.reference_to ?? def.referenceTo ?? def.reference_to_object;
-    if (typeof raw === 'string' && raw)
-        return raw;
-    if (Array.isArray(raw) && typeof raw[0] === 'string' && raw[0])
-        return raw[0];
-    if (raw && typeof raw === 'object') {
-        const obj = raw.object;
-        if (typeof obj === 'string' && obj)
-            return obj;
-    }
-    return undefined;
+    const raw = def.reference;
+    return typeof raw === 'string' && raw ? raw : undefined;
 }
 /**
  * Resolve each dataset dimension's underlying `field` to that field's select