@object-ui/core 17.5.0 → 17.6.0

package/dist/utils/chart-series.js

@@ -5,6 +5,45 @@
  * 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 bucket a NULL/undefined category VALUE renders under, when the caller
  * supplies no localized label of its own (objectui#4466).
@@ -22,6 +61,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,29 +136,162 @@ 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);
@@ -73,35 +303,106 @@ export function buildChartSeries(rows, dimensions, values, fields, options) {
         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.
+            //
+            // 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 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 });
+            // 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 +485,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 +538,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`.
@@ -541,7 +883,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;

package/dist/utils/column-identity.d.ts

@@ -108,3 +108,46 @@ export declare function normalizeColumnIdentity<T>(entry: T): T;
  * every consumer already special-cases it.
  */
 export declare function normalizeColumnIdentities<T>(columns: T): T;
+/**
+ * The spec's canonical key for "what this column is CALLED on screen".
+ *
+ * `ListColumnSchema` (`@objectstack/spec/view`) spells a column's display text
+ * `label`, next to its `field`. It is metadata vocabulary, exactly like
+ * {@link CANONICAL_COLUMN_IDENTITY_KEY} — not an objectui legacy spelling, and
+ * not something to amputate.
+ */
+export declare const CANONICAL_COLUMN_LABEL_KEY = "label";
+/**
+ * NOT metadata — the display half of the same boundary
+ * {@link TABLE_ADAPTER_COLUMN_KEY} draws for identity.
+ *
+ * `header` is `TableColumn.header` (`packages/types/src/data-display.ts`), the
+ * data-table ADAPTER's own key for a column's rendered title. The adapter
+ * declares `header` and does not declare `label`; the spec declares `label` and
+ * does not declare `header`. Those are two vocabularies, and the translation
+ * between them belongs at the producer — one translation, one place
+ * (objectui#5068) — never as a tolerated `col.header || col.label` alias inside
+ * the adapter (objectui#5351).
+ */
+export declare const TABLE_ADAPTER_HEADER_KEY = "header";
+/**
+ * Read a column entry's display text on its way INTO the data-table adapter —
+ * the header counterpart of {@link columnIdentity} (objectui#5351).
+ *
+ * Adapter-first, which is the opposite order from {@link columnIdentity} and is
+ * deliberate. `columnIdentity` folds several METADATA spellings of one metadata
+ * concept, so the canonical metadata key wins. This reader crosses a boundary
+ * between two vocabularies instead: an author who wrote the adapter's own
+ * `header` addressed the table directly, and a producer must not overwrite that
+ * — the same rule `RelatedList` and `ObjectDataTable` already state for an
+ * author-supplied `accessorKey` (objectui#5022).
+ *
+ * Returns `undefined` — not `''` — when neither key carries text, so a caller
+ * can tell "no header authored" from "the header is deliberately blank" and
+ * stamp nothing rather than stamping an empty string.
+ *
+ * A bare-string column entry has no display text of its own; producers derive
+ * one from the field key (`humanizeFieldKey`) or the object schema's label, and
+ * that derivation is theirs, not this reader's.
+ */
+export declare function columnHeader(entry: unknown): string | undefined;

package/dist/utils/column-identity.js

@@ -125,7 +125,6 @@ function warnOnConflictingIdentity(entry, identity, losing) {
         if (warnedConflicts.has(memo))
             continue;
         warnedConflicts.add(memo);
-        // eslint-disable-next-line no-console
         console.warn(`[ObjectUI] Column carries two identities: \`${CANONICAL_COLUMN_IDENTITY_KEY}: ` +
             `'${identity}'\` and \`${key}: '${String(entry[key])}'\`. ` +
             `\`${CANONICAL_COLUMN_IDENTITY_KEY}\` wins — it is the only key ` +
@@ -208,3 +207,50 @@ export function normalizeColumnIdentities(columns) {
     });
     return (changed ? next : columns);
 }
+/**
+ * The spec's canonical key for "what this column is CALLED on screen".
+ *
+ * `ListColumnSchema` (`@objectstack/spec/view`) spells a column's display text
+ * `label`, next to its `field`. It is metadata vocabulary, exactly like
+ * {@link CANONICAL_COLUMN_IDENTITY_KEY} — not an objectui legacy spelling, and
+ * not something to amputate.
+ */
+export const CANONICAL_COLUMN_LABEL_KEY = 'label';
+/**
+ * NOT metadata — the display half of the same boundary
+ * {@link TABLE_ADAPTER_COLUMN_KEY} draws for identity.
+ *
+ * `header` is `TableColumn.header` (`packages/types/src/data-display.ts`), the
+ * data-table ADAPTER's own key for a column's rendered title. The adapter
+ * declares `header` and does not declare `label`; the spec declares `label` and
+ * does not declare `header`. Those are two vocabularies, and the translation
+ * between them belongs at the producer — one translation, one place
+ * (objectui#5068) — never as a tolerated `col.header || col.label` alias inside
+ * the adapter (objectui#5351).
+ */
+export const TABLE_ADAPTER_HEADER_KEY = 'header';
+/**
+ * Read a column entry's display text on its way INTO the data-table adapter —
+ * the header counterpart of {@link columnIdentity} (objectui#5351).
+ *
+ * Adapter-first, which is the opposite order from {@link columnIdentity} and is
+ * deliberate. `columnIdentity` folds several METADATA spellings of one metadata
+ * concept, so the canonical metadata key wins. This reader crosses a boundary
+ * between two vocabularies instead: an author who wrote the adapter's own
+ * `header` addressed the table directly, and a producer must not overwrite that
+ * — the same rule `RelatedList` and `ObjectDataTable` already state for an
+ * author-supplied `accessorKey` (objectui#5022).
+ *
+ * Returns `undefined` — not `''` — when neither key carries text, so a caller
+ * can tell "no header authored" from "the header is deliberately blank" and
+ * stamp nothing rather than stamping an empty string.
+ *
+ * A bare-string column entry has no display text of its own; producers derive
+ * one from the field key (`humanizeFieldKey`) or the object schema's label, and
+ * that derivation is theirs, not this reader's.
+ */
+export function columnHeader(entry) {
+    if (!isRecord(entry))
+        return undefined;
+    return (asIdentity(entry[TABLE_ADAPTER_HEADER_KEY]) ?? asIdentity(entry[CANONICAL_COLUMN_LABEL_KEY]));
+}

package/dist/utils/dataset-format.js

@@ -172,12 +172,24 @@ export function formatMeasure(v, format, currency, percentScale, locale) {
     //
     // `style: 'percentPoints'` is what closes it, and the choice of route is
     // measured, not incidental. `display` is already in percentage POINTS, while
-    // `Intl`'s `style: 'percent'` wants a fraction — so routing through that (the
-    // way `formatPercent` does) would mean dividing by 100 for `Intl` to multiply
-    // straight back, and that round trip is lossy at rounding TIES: 27,581 of
-    // 1,200,013 ordinary-magnitude en-US forms move (`0.175` at 2 decimals goes
-    // from `0.18%` to `0.17%`), plus `MAX_SAFE_INTEGER` and everything from 1e23
-    // up. Formatting the points directly with the percent UNIT was measured to
+    // `Intl`'s `style: 'percent'` wants a fraction — so routing through that
+    // would mean dividing by 100 for `Intl` to multiply straight back, and that
+    // round trip is lossy at rounding TIES: 27,581 of 1,200,013
+    // ordinary-magnitude en-US forms move (`0.175` at 2 decimals goes from
+    // `0.18%` to `0.17%`), plus `MAX_SAFE_INTEGER` and everything from 1e23 up.
+    // That count is #4576's tie-dense grid — 0.005 steps to 2,000, precisions
+    // 0/1/2 — measured on THIS formatter's call shape. #4590 re-measured the same
+    // route through `formatPercent` and reports 27,577 of 1,200,003: a different
+    // form set, not a correction of this one.
+    //
+    // No caller in this repo takes the divide-by-100 route today. `formatPercent`
+    // was the last one and moved to `style: 'percentPoints'` in #4590; the two
+    // `style: 'percent'` sites left (`element:number`'s format options and the
+    // report exporter's Excel options) hand `Intl` a FRACTION, which is that
+    // style's own contract and not this trap. The route now survives only where a
+    // test constructs it in order to show it disagreeing.
+    //
+    // Formatting the points directly with the percent UNIT was measured to
     // produce a byte-identical percent affix to `style: 'percent'` across all 171
     // locale tags tested, while moving ZERO of those 1,200,013 en forms — the
     // same convention by a route that does not touch the value.