@object-ui/core 17.5.0 → 17.7.0

package/dist/utils/chart-series.js

@@ -5,6 +5,86 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * chart-series — shape a semantic-layer `queryDataset` result into the
+ * `{ data, xAxisKey, series }` triple a chart renderer consumes (ADR-0021, #1759).
+ *
+ * Shared by `ObjectChart` (plugin-charts) and `DatasetWidget` (plugin-dashboard)
+ * so multi-dimension charts visualise identically across surfaces.
+ *
+ * Rules:
+ *  - **2+ dimensions, single measure** → pivot the SECOND dimension into one
+ *    series per distinct value (grouped/coloured bars). `xAxisKey` = first
+ *    dimension; each output row is one first-dimension bucket with a column per
+ *    second-dimension value holding the measure. This makes the second dimension
+ *    visible instead of just repeating the x-axis label.
+ *  - **otherwise** (single dimension, or multiple measures) → first dimension is
+ *    the x-axis and each measure is its own series (long format passes through).
+ *
+ * BOTH branches map a NULL first-dimension VALUE to an explicit bucket label
+ * ({@link NULL_CATEGORY_LABEL}) so the group renders instead of vanishing —
+ * objectui#4466 for the single-dimension branch, objectui#4497 for the pivot.
+ * One doctrine, one predicate (`isNullCategory`), two call sites.
+ *
+ * The pivot's SECOND dimension gets the same answer as of objectui#4673, where
+ * it needed one more thing than an axis bucket does: a series bucket's key is a
+ * renderer `dataKey` AND a column in the emitted row, so it has to be
+ * collision-safe as well as drawable. See {@link pivotSeriesBuckets}.
+ *
+ * A bucket's IDENTITY is separate from that display label (objectui#4508). The
+ * label used to serve as its own key, which conflated two pairs of genuinely
+ * different groups; see {@link chartBucketId} for the identity, and
+ * {@link CHART_BUCKET_ID_KEY} for how it reaches a click handler.
+ *
+ * Key ABSENCE survives the pivot as of objectui#4507: an emitted bucket carries
+ * the x-axis key exactly when some row of it did. A first dimension that was
+ * grouped by but never PROJECTED therefore still reaches the renderer key-less,
+ * where `hasNoCategoryKey` (framework#4033) names it instead of drawing an axis
+ * with no marks. "Known to be empty" draws under the bucket label, "cannot
+ * 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).
@@ -22,6 +102,64 @@
  * clicked bucket bar resolve back to its (raw null) dataset row.
  */
 export const NULL_CATEGORY_LABEL = '(None)';
+/**
+ * The IDENTITY of the chart bucket a first-dimension raw value falls in —
+ * distinct from the string that bucket DISPLAYS (objectui#4508).
+ *
+ * Deliberately the SAME encoder the pivot TABLE already keys its buckets with
+ * (`pivotBucketId` over a `pivotDimensionValue`-normalized value), because the
+ * two surfaces answer the same question about the same dataset rows and were
+ * answering it differently: `buildPivot` gives a null dimension value a bucket
+ * id no string can spell, while the chart used the display label as its own
+ * key. That gap is the whole of objectui#4508 — see `dataset-pivot.ts` for why
+ * the encoding is JSON rather than a delimiter or a placeholder character.
+ *
+ * Two collisions follow from a label-as-key, and one encoder closes both:
+ *  - `null` and `''` are different groups. `String(x ?? '')` made them one
+ *    bucket, so two groups drew ONE bar and one of them lost its drill.
+ *    `[null]` and `[""]` are different ids.
+ *  - a stored value that literally spells the bucket label (`'(None)'`, or any
+ *    localized `nullCategoryLabel` — `'(未指定)'` and the other nine packs) is
+ *    not the null group. `["(None)"]` and `[null]` are different ids, so the
+ *    click resolves to the rows its own bar was drawn from.
+ */
+export function chartBucketId(rawValue) {
+    return pivotBucketId([pivotDimensionValue(rawValue)]);
+}
+/**
+ * The key an emitted chart row carries its {@link chartBucketId} under, when it
+ * carries one — the "alongside the display label" half of objectui#4508.
+ *
+ * **Written exactly when the display string does not name one bucket**, i.e.
+ * when two or more DISTINCT buckets render the same axis text. That is not a
+ * cost-saving heuristic, it is the complete condition: with the reader's
+ * matching made exact (see {@link findChartSeriesRow}), a display string that
+ * one bucket alone produces already identifies it, and the rows a chart is
+ * drawn from are also an authoring-visible surface (`data` on a `chart`
+ * schema) that renderer-internal metadata should not appear in for every
+ * ordinary chart. Rows that do not carry the category key at all never get one
+ * — they have no bucket, and that shape belongs to `hasNoCategoryKey`
+ * (framework#4033), not here.
+ *
+ * Read it with {@link chartRowBucketId} rather than the literal key.
+ */
+export const CHART_BUCKET_ID_KEY = '__bucketId';
+/**
+ * Read the bucket identity off a row a chart was drawn from, or `undefined`
+ * when the row carries none (an unambiguous bucket, or rows a caller built
+ * itself rather than through {@link buildChartSeries}).
+ *
+ * Takes `unknown` because its callers hold a click payload, not a typed row:
+ * recharts hands a pie/funnel click a SPREAD COPY of the data item, which is
+ * why the identity is an ordinary enumerable property and not a symbol or a
+ * non-enumerable one — either of those would silently not survive the copy.
+ */
+export function chartRowBucketId(row) {
+    if (!row || typeof row !== 'object')
+        return undefined;
+    const id = row[CHART_BUCKET_ID_KEY];
+    return typeof id === 'string' && id !== '' ? id : undefined;
+}
 /**
  * Does this row carry `key` with a NULL/undefined value — the shape that gets
  * the bucket label (objectui#4466 / objectui#4497)?
@@ -39,69 +177,279 @@ export const NULL_CATEGORY_LABEL = '(None)';
  * sentence and a false one.
  */
 function isNullCategory(row, key) {
-    return (!!row &&
-        typeof row === 'object' &&
-        key in row &&
-        row[key] == null);
+    return carriesKey(row, key) && row[key] == null;
+}
+/**
+ * Does this row carry `key` AT ALL — the precondition {@link isNullCategory}
+ * and every bucketing call site share.
+ *
+ * Stated once because the two halves of the doctrine hang off it and the
+ * difference is invisible at a glance: `row[key] == null` is TRUE for a row
+ * that simply has no such column, so reading the raw value alone silently
+ * relabels "this dimension was never projected" as "these records have no
+ * value" (framework#4033's signal, erased). Every place that decides whether a
+ * row has a bucket asks THIS, never the raw value.
+ */
+function carriesKey(row, key) {
+    return !!row && typeof row === 'object' && key in row;
+}
+/**
+ * The axis text a bucket paints, from its ALREADY-RESOLVED display value — the
+ * string a chart library puts on the tick and hands back as the clicked
+ * category. Two buckets "look alike" exactly when these are equal: `1` and
+ * `'1'` included (which is why this stringifies rather than comparing raw
+ * values), and an absent display alongside `''` (both paint a blank tick).
+ *
+ * Takes the display value, never the raw one: in both branches a null category
+ * has ALREADY become the bucket label by the time ambiguity is asked about, and
+ * feeding the raw value here would ask the question about the wrong string.
+ */
+function bucketDisplayKey(displayValue) {
+    return displayValue == null ? '' : String(displayValue);
+}
+/**
+ * Which display strings are produced by MORE THAN ONE distinct bucket — the
+ * complete set of cases where the axis text cannot name the bucket a user
+ * clicked, and therefore exactly the set that needs {@link CHART_BUCKET_ID_KEY}
+ * written (objectui#4508).
+ *
+ * Counted over DISTINCT ids, not over rows: two rows of the same group share
+ * one id and are one bucket, so an ordinary repeated category is not ambiguous
+ * and its rows stay untouched.
+ */
+function ambiguousDisplays(buckets) {
+    const idsByDisplay = new Map();
+    for (const { id, display } of buckets) {
+        let ids = idsByDisplay.get(display);
+        if (!ids)
+            idsByDisplay.set(display, (ids = new Set()));
+        ids.add(id);
+    }
+    const ambiguous = new Set();
+    for (const [display, ids] of idsByDisplay)
+        if (ids.size > 1)
+            ambiguous.add(display);
+    return ambiguous;
 }
 /**
  * Map a null/undefined category VALUE to its bucket label, for the
- * single-dimension branch (objectui#4466).
+ * single-dimension branch (objectui#4466), and give a bucket whose label is
+ * shared with another bucket its own identity (objectui#4508).
  *
- * Returns the input array itself when nothing was null, and copies only the
+ * Returns the input array itself when neither applied, and copies only the
  * rows it rewrites, so the caller's rows are never mutated — dataset surfaces
  * drill through by index into the RAW rows, which must keep their null.
+ *
+ * A row that does not carry `key` at all is left ENTIRELY alone: it has no
+ * bucket to label and none to identify, and adding either would erase the
+ * signal `hasNoCategoryKey` (framework#4033) reads.
  */
 function bucketNullCategories(rows, key, label) {
+    // The value this row's bar will PAINT — the label when its category is null,
+    // its own value otherwise. Ambiguity is a question about that string.
+    const displayOf = (row) => isNullCategory(row, key) ? label : row[key];
+    const ambiguous = ambiguousDisplays(rows.filter((row) => carriesKey(row, key)).map((row) => ({
+        id: chartBucketId(row[key]),
+        display: bucketDisplayKey(displayOf(row)),
+    })));
     let changed = false;
     const next = rows.map((row) => {
-        if (!isNullCategory(row, key))
+        if (!carriesKey(row, key))
+            return row;
+        const isNull = isNullCategory(row, key);
+        const shared = ambiguous.has(bucketDisplayKey(displayOf(row)));
+        if (!isNull && !shared)
             return row;
         changed = true;
-        return { ...row, [key]: label };
+        return {
+            ...row,
+            ...(isNull ? { [key]: label } : {}),
+            ...(shared ? { [CHART_BUCKET_ID_KEY]: chartBucketId(row[key]) } : {}),
+        };
     });
     return changed ? next : rows;
 }
+/**
+ * The pivot's series buckets, in first-seen order — objectui#4673.
+ *
+ * The second dimension used to be bucketed by `String(row[groupKey] ?? '')`
+ * behind a `gId !== ''` gate, which is the PRE-objectui#4466 answer one
+ * dimension over: a null (or empty-string) group never joined the series list,
+ * while the line below the gate still wrote its measure into the bucket. The
+ * number was in the emitted row and bound to no mark — the chart understated
+ * its own data without saying so, which is #4466's harm verbatim.
+ *
+ * A series bucket needs one thing an axis bucket does not, and that is the
+ * whole reason this is a function rather than two more lines inline: its key is
+ * a **row column and a renderer `dataKey`**, so it must be UNIQUE within the
+ * emitted row, where an axis bucket's key is a private map key. Hence the
+ * assignment below, which is injective by construction:
+ *
+ *  - a bucket keys its column by its own LABEL — so an ordinary pivot's rows
+ *    and series are byte-identical to what they have always been, and the
+ *    legend, the tooltip and the drill title read the group's own text;
+ *  - unless that label cannot NAME it: shared with another bucket (the null
+ *    bucket beside a stored value spelling its label — objectui#4508's second
+ *    collision, on the series axis), reserved by the row itself (`xKey`, whose
+ *    column IS the axis value, and {@link CHART_BUCKET_ID_KEY}), or equal to
+ *    some bucket's identity;
+ *  - in which case it keys by its own IDENTITY, which no other bucket has.
+ *
+ * The third exclusion is what makes the first two safe rather than merely
+ * likely: identities are pairwise distinct, and no surviving label is one of
+ * them, so the two key spaces cannot meet. That is the card's "collision-safe"
+ * requirement discharged, not approximated — a record whose stored group value
+ * literally spells `[null]` is a real value with a real bar, and it keeps it.
+ *
+ * The empty-string group keys by its own label, `''`, exactly as it paints a
+ * blank legend entry (and a blank tick on the x-axis — objectui#4508 ruled `''`
+ * and `null` two different groups, and this is that ruling on the series axis).
+ * Measured, not assumed: recharts binds `dataKey=""` through the same
+ * `getValueByDataKey` path as any other key and draws the bar at its true
+ * height. That measurement is pinned at the DOM in plugin-charts.
+ *
+ * A row that does not carry `groupKey` at all gets NO bucket and contributes no
+ * column — the other half of the doctrine, unchanged: "known to be empty" draws
+ * and "cannot know" refuses (framework#4033). Inventing a group for it would
+ * merge unprojected rows into the empty-string group and call it data.
+ */
+function pivotSeriesBuckets(rows, groupKey, nullLabel, xKey) {
+    const byId = new Map();
+    for (const row of rows) {
+        if (!carriesKey(row, groupKey))
+            continue;
+        const id = chartBucketId(row[groupKey]);
+        if (byId.has(id))
+            continue;
+        byId.set(id, { id, label: isNullCategory(row, groupKey) ? nullLabel : String(row[groupKey]) });
+    }
+    const buckets = Array.from(byId.values());
+    const shared = ambiguousDisplays(buckets.map(({ id, label }) => ({ id, display: label })));
+    const reserved = new Set([xKey, CHART_BUCKET_ID_KEY]);
+    const identities = new Set(buckets.map(({ id }) => id));
+    return buckets.map(({ id, label }) => ({
+        id,
+        label,
+        dataKey: shared.has(label) || reserved.has(label) || identities.has(label) ? id : label,
+    }));
+}
 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];
         const groupKey = dims[1];
         const measure = vals[0];
         const nullLabel = options?.nullCategoryLabel ?? NULL_CATEGORY_LABEL;
-        const seriesKeys = [];
+        // Every second-dimension group, INCLUDING the null and empty-string ones
+        // the `gId !== ''` gate used to drop on the floor (objectui#4673), each
+        // already carrying the column its measure lands in.
+        const groups = pivotSeriesBuckets(safeRows, groupKey, nullLabel, xKey);
+        const columnById = new Map(groups.map(({ id, dataKey }) => [id, dataKey]));
         const byX = new Map();
         for (const row of safeRows) {
             const xRaw = row[xKey];
-            const xId = String(xRaw ?? '');
-            // The bucket KEY is untouched — `String(xRaw ?? '')` still decides WHICH
-            // rows share a bar, so every existing grouping is byte-identical. What
-            // changes is the DISPLAY value the bucket carries: a null first-dimension
-            // value used to be written into the emitted row raw, so the bar reached
-            // recharts with a null category and drew no mark — the same defect
-            // objectui#4466 fixed one branch below, and the reason key and row value
-            // were two different things here (objectui#4497).
+            // The bucket KEY is the bucket's IDENTITY, not its display string
+            // (objectui#4508). It used to be `String(xRaw ?? '')`, which merged two
+            // groups that are not the same group: a stored `null` and a stored `''`
+            // encoded identically, so they drew ONE bar carrying both groups' series
+            // and the segment belonging to the later one resolved to no row at all.
+            // `chartBucketId` keeps them apart, and every value that can spell the
+            // bucket LABEL apart from the null bucket with it.
+            //
+            // The DISPLAY value stays what objectui#4497 made it: a null
+            // first-dimension value renders under the bucket label rather than
+            // reaching the renderer raw (which drew no mark — the objectui#4466
+            // defect, one branch below). Key and display value are two different
+            // things here, and now they are two different KINDS of thing.
+            //
+            // The bucket takes its label from the first row that CARRIES the key,
+            // exactly as it took the CREATING row's raw value before — the same row
+            // in every bucket a projected dimension produces, because a row whose
+            // `xKey` is absent reads `xRaw === undefined` and therefore lands in the
+            // `[null]` bucket and nowhere else.
+            //
+            // A bucket carries `xKey` exactly when SOME row of it did, and that is
+            // objectui#4507: the write used to be unconditional, so a first dimension
+            // GROUPED BY BUT NEVER PROJECTED (framework#4033 — no row carries the key
+            // at all) reached the renderer as `{ [xKey]: undefined }`, `key in row`
+            // answered true, and `hasNoCategoryKey` could not fire for a pivoted
+            // chart. The defence was dead exactly where the defect it guards against
+            // lands: every row collapsed into one bucket painting a blank tick, which
+            // is the silent shape the placeholder exists to replace. The single-
+            // dimension branch never had the problem — it passes rows through, so
+            // key-absent rows stay key-absent — and this is that same answer here.
             //
-            // The bucket takes its label from the row that CREATED it, exactly as it
-            // took its raw value before.
-            if (!byX.has(xId)) {
-                byX.set(xId, { [xKey]: isNullCategory(row, xKey) ? nullLabel : xRaw });
+            // MEASURED end to end before it was written (objectui#4507): the strategy
+            // that maps engine rows to result rows writes a dimension key only when
+            // the engine actually returned that column (`if (shortName in row)`), the
+            // native-SQL strategy returns driver rows that carry only the columns the
+            // statement selected, and JSON cannot transport `undefined` in the first
+            // place — so an unprojected dimension arrives as an ABSENT key, while an
+            // explicit `null` means the column WAS projected and its value is null.
+            // Those are the two shapes, they are cleanly separated at the source, and
+            // this branch now keeps them apart instead of merging them.
+            //
+            // Why the bug was invisible to every pin that "saw" the emitted row: both
+            // `JSON.stringify` and `toEqual` DROP an undefined-valued key, so the
+            // pivot's output read as key-absent everywhere except in the one test
+            // that decides the placeholder — `key in row`.
+            //
+            // The upgrade in the second clause is not cosmetic. `chartBucketId`
+            // encodes an absent value and a stored `null` identically (`[null]`, by
+            // ADR-0021's normalization), so ONE bucket can collect both key-absent
+            // rows and rows whose category is genuinely null. If any of its rows
+            // carried the key, the bucket is "known to be empty" and draws under the
+            // label; refusing there would tell the author their query never projected
+            // a dimension that it did project — a false sentence, and the mirror of
+            // the false sentence objectui#4497 refused to print by NOT relabelling a
+            // key-absent row `(None)`. Both halves of that doctrine are now live in
+            // this branch: key absent everywhere → the framework#4033 placeholder;
+            // key present with a null value → the bucket label.
+            const xId = chartBucketId(xRaw);
+            let bucket = byX.get(xId);
+            if (!bucket)
+                byX.set(xId, (bucket = {}));
+            if (carriesKey(row, xKey) && !carriesKey(bucket, xKey)) {
+                bucket[xKey] = isNullCategory(row, xKey) ? nullLabel : xRaw;
             }
-            const gId = String(row[groupKey] ?? '');
-            if (gId !== '' && !seriesKeys.includes(gId))
-                seriesKeys.push(gId);
-            byX.get(xId)[gId] = row[measure];
+            // The group's own column, or nothing at all when the row carries no
+            // second dimension to be grouped BY. Nothing at all is the point: the
+            // old code wrote such a row's measure under `''` — a column no series
+            // bound to, and after objectui#4673 the empty-string GROUP's column,
+            // which would hand an unprojected row's number to a real group's bar.
+            const column = carriesKey(row, groupKey)
+                ? columnById.get(chartBucketId(row[groupKey]))
+                : undefined;
+            if (column !== undefined)
+                bucket[column] = row[measure];
         }
+        // Two DISTINCT buckets can still render the same axis text — the null
+        // bucket beside a stored value that literally spells its label. Those, and
+        // only those, carry their identity to the click handler.
+        const ambiguous = ambiguousDisplays(Array.from(byX.entries()).map(([id, bucket]) => ({
+            id,
+            display: bucketDisplayKey(bucket[xKey]),
+        })));
         return {
-            data: Array.from(byX.values()),
+            data: Array.from(byX.entries()).map(([id, bucket]) => ambiguous.has(bucketDisplayKey(bucket[xKey]))
+                ? { ...bucket, [CHART_BUCKET_ID_KEY]: id }
+                : bucket),
             xAxisKey: xKey,
             // Series labels are the second-dimension values themselves (already
-            // server-resolved to display labels by queryDataset).
-            series: seriesKeys.map((k) => ({ dataKey: k, label: k })),
+            // server-resolved to display labels by queryDataset), except the null
+            // group, which says so with the bucket label the renderer supplied. The
+            // key is a separate question from the text — see `pivotSeriesBuckets`.
+            series: groups.map(({ dataKey, label }) => ({ dataKey, label })),
         };
     }
     // Default: first dimension on the x-axis, one series per measure.
@@ -184,16 +532,37 @@ export function relabelDimensions(rows, labelMaps) {
  *    BOTH the x-axis dimension (`category`) and the series dimension (`seriesKey`).
  *  - **otherwise** → match the x-axis (first) dimension only.
  *
- * Comparison is string-wise on the rows' display values (which is what the chart
- * surfaces as `category` / series key). Returns `-1` when nothing matches.
+ * The x-axis comparison is string-wise on the rows' display values (which is
+ * what the chart surfaces as `category`), unless the click carried a bucket
+ * IDENTITY — {@link ChartDrillLookupOptions.bucketId} — in which case that is
+ * authoritative and the display string is not consulted at all. Returns `-1`
+ * when nothing matches.
+ *
+ * The SERIES comparison is not string-wise at all as of objectui#4673: a series
+ * key is a `dataKey` {@link buildChartSeries} assigned, so it is resolved back
+ * through the same {@link pivotSeriesBuckets} assignment (same rows, same
+ * `nullCategoryLabel`) to the group IDENTITY it names, and rows are matched on
+ * that. A null-valued second dimension had no series at all before, so its
+ * segment could not be clicked; now it can, and `String(r[gDim] ?? '')` would
+ * have answered that click with an empty-string group's rows — the same
+ * conflation objectui#4508 removed on the x-axis.
  *
  * The NULL-category bucket {@link buildChartSeries} renders (objectui#4466) is
  * matched back to its row here, and it has to be: the caller passes the rows it
  * charted FROM (still carrying the raw null) while the click event carries the
  * bucket LABEL, so without this the one bar the fix made visible would resolve
  * to `-1` and its drill-through would silently no-op. Pass the same
- * `nullCategoryLabel` both helpers were given. The pre-existing `''` spelling
- * of "no group value" still matches too — `computeDrillFilter` writes that one.
+ * `nullCategoryLabel` both helpers were given.
+ *
+ * **A null category reads as its bucket LABEL and nothing else** (objectui#4508).
+ * It used to read as the label OR the empty string, on the stated grounds that
+ * `''` is the drill layer's own spelling of "no group value" — but no producer
+ * of this function's `category` argument writes that spelling (the one
+ * production caller feeds it a chart click's category, and `computeDrillFilter`
+ * is downstream of the drill, not upstream of this lookup), while `''` IS what
+ * a genuine empty-string group paints. So the tolerance cost that group its own
+ * drill and gave it a null group's records instead — a WRONG click, not a dead
+ * one. `''` now means the empty-string group, which is what it says.
  *
  * **`xOf` covers BOTH arms, which is what let objectui#4497 bucket the pivot
  * branch without touching this function.** Worth stating because the reverse
@@ -216,15 +585,35 @@ export function findChartSeriesRow(rows, dimensions, values, category, seriesKey
         return -1;
     const c = String(category ?? '');
     const nullLabel = options?.nullCategoryLabel ?? NULL_CATEGORY_LABEL;
-    // A null x reads as BOTH its rendered bucket label and the legacy '' — the
-    // two spellings of the same fact, neither of which a stored value can be.
-    const xOf = (r) => r[xDim] == null ? (c === nullLabel ? nullLabel : '') : String(r[xDim]);
+    const bucketId = options?.bucketId;
+    // Identity wins outright when the click carried one: it is the ONE thing that
+    // survives two buckets painting the same axis text, which is the case the
+    // display string provably cannot answer.
+    const matchesX = typeof bucketId === 'string' && bucketId !== ''
+        ? (r) => chartBucketId(r[xDim]) === bucketId
+        // Otherwise the bucket's own display string, exactly: a null category
+        // reads as its rendered label, every other value as itself.
+        : (r) => (r[xDim] == null ? nullLabel : String(r[xDim])) === c;
     if (dims.length >= 2 && vals.length === 1) {
         const gDim = dims[1];
-        const s = String(seriesKey ?? '');
-        return safeRows.findIndex((r) => xOf(r) === c && String(r[gDim] ?? '') === s);
+        // The clicked series key is a `dataKey` `buildChartSeries` ASSIGNED, so it
+        // is resolved the way it was assigned — through the same buckets, rebuilt
+        // from the same raw rows (`DatasetWidget.handleChartDrill`, the one
+        // production caller, hands both helpers the same array and the same
+        // `nullCategoryLabel`). Matching then compares IDENTITIES, which is
+        // objectui#4508's answer extended to the series axis: `String(r[gDim] ?? '')`
+        // was display-string matching, and it spelled a null group and an
+        // empty-string group alike — the tolerance #4508 removed one dimension over.
+        const groups = pivotSeriesBuckets(safeRows, gDim, nullLabel, xDim);
+        const gId = groups.find(({ dataKey }) => dataKey === String(seriesKey ?? ''))?.id;
+        // No bucket answers to that key: these rows have no such group, so no row
+        // can belong to it. `-1` is the documented "nothing matched" — widening to
+        // a string comparison here would put back exactly what #4508 measured out.
+        if (gId === undefined)
+            return -1;
+        return safeRows.findIndex((r) => matchesX(r) && carriesKey(r, gDim) && chartBucketId(r[gDim]) === gId);
     }
-    return safeRows.findIndex((r) => xOf(r) === c);
+    return safeRows.findIndex((r) => matchesX(r));
 }
 /**
  * Build a per-category colour map from a select/lookup field's `options`.
@@ -423,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
@@ -439,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
@@ -541,7 +965,6 @@ export async function resolveDimensionFieldMeta(baseSchema, fieldPaths, loadObje
                 walked = false;
                 break;
             }
-            // eslint-disable-next-line no-await-in-loop
             schema = await load(target);
             if (!schema) {
                 walked = false;