@object-ui/core 17.3.0 → 17.6.0

package/dist/utils/chart-series.js

@@ -5,7 +5,294 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export function buildChartSeries(rows, dimensions, values, fields) {
+/**
+ * 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).
+ *
+ * English by construction and deliberately so: this package is React-free and
+ * i18n-free (see {@link OptionLabelTranslator} for the same reason stated one
+ * layer down), so the locale bundle cannot be read here. Every renderer that
+ * has an i18n provider passes its own resolved label through
+ * {@link ChartSeriesOptions.nullCategoryLabel} — this constant is the floor
+ * that keeps a provider-less host (or a caller that has not been wired yet)
+ * drawing the group rather than dropping it.
+ *
+ * Exported so a consumer can recognise the bucket it will be handed —
+ * {@link findChartSeriesRow} uses the same default, which is what makes a
+ * 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)?
+ *
+ * ONE predicate for both of `buildChartSeries`' branches, so the doctrine
+ * cannot drift between them: the pivot inherited the single-dimension answer in
+ * objectui#4497 and this is the whole of what "the same answer" means.
+ *
+ * The key must be PRESENT: a row that does not carry the category key at all is
+ * a different defect with a different answer — the dimension was grouped by but
+ * never projected — and it belongs to `hasNoCategoryKey` in plugin-charts'
+ * `AdvancedChartImpl`, which names the unprojected key instead of drawing an
+ * axis (framework#4033). Bucketing that shape would relabel "this dimension was
+ * never projected" as "these records have no value", which is a different
+ * sentence and a false one.
+ */
+function isNullCategory(row, key) {
+    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), and give a bucket whose label is
+ * shared with another bucket its own identity (objectui#4508).
+ *
+ * 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 (!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,
+            ...(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 : [];
@@ -15,30 +302,129 @@ export function buildChartSeries(rows, dimensions, values, fields) {
         const xKey = dims[0];
         const groupKey = dims[1];
         const measure = vals[0];
-        const seriesKeys = [];
+        const nullLabel = options?.nullCategoryLabel ?? NULL_CATEGORY_LABEL;
+        // 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 ?? '');
-            if (!byX.has(xId))
-                byX.set(xId, { [xKey]: xRaw });
-            const gId = String(row[groupKey] ?? '');
-            if (gId !== '' && !seriesKeys.includes(gId))
-                seriesKeys.push(gId);
-            byX.get(xId)[gId] = row[measure];
+            // 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 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;
+            }
+            // 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.
+    //
+    // A row whose category VALUE is null renders under an explicit bucket rather
+    // than reaching the renderer with a null category, which draws no mark at all
+    // (objectui#4466). The measured cost of passing it through was not an empty
+    // chart but a quietly WRONG one: `[{user_id: null, event_count: 51},
+    // {user_id: 'Dev Admin', event_count: 2}]` drew one bar, dropping the
+    // dominant group while the y-axis scale still accommodated it.
+    //
+    // The pivot branch above answers this the SAME way as of objectui#4497 — it
+    // was left alone here only until its own bucketing had been measured, which
+    // is what that card did. The two branches differ in WHERE the label lands
+    // (there: the bucket's display value, the map key untouched; here: the row
+    // itself), never in what a null category means.
+    const xKey = dims[0];
     return {
-        data: safeRows,
-        xAxisKey: dims[0],
+        data: xKey
+            ? bucketNullCategories(safeRows, xKey, options?.nullCategoryLabel ?? NULL_CATEGORY_LABEL)
+            : safeRows,
+        xAxisKey: xKey,
         series: vals.map((v) => ({ dataKey: v, label: labelOf(v) })),
     };
 }
@@ -99,10 +485,51 @@ 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.
+ *
+ * **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
+ * would be silent: the pivot's emitted rows are AGGREGATED (`byX` collapses N
+ * raw rows into one bucket per first-dimension value), so they are NOT
+ * index-aligned with anything, and a caller cannot drill by the emitted row's
+ * position. It drills by SEARCHING the raw rows here and indexing
+ * `drillRawRows` with what this returns — see `DatasetWidget.handleChartDrill`,
+ * the one production caller. So the pivot's map key and its emitted display
+ * value being two different things never reached the drill: the raw rows this
+ * searches still carry their null either way, and `xOf` reads the label back to
+ * them in the multi-dimension arm exactly as in the single-dimension one.
  */
-export function findChartSeriesRow(rows, dimensions, values, category, seriesKey) {
+export function findChartSeriesRow(rows, dimensions, values, category, seriesKey, options) {
     const dims = (dimensions ?? []).filter(Boolean);
     const vals = (values ?? []).filter(Boolean);
     const safeRows = Array.isArray(rows) ? rows : [];
@@ -110,12 +537,36 @@ export function findChartSeriesRow(rows, dimensions, values, category, seriesKey
     if (!xDim)
         return -1;
     const c = String(category ?? '');
+    const nullLabel = options?.nullCategoryLabel ?? NULL_CATEGORY_LABEL;
+    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) => String(r[xDim] ?? '') === 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) => String(r[xDim] ?? '') === c);
+    return safeRows.findIndex((r) => matchesX(r));
 }
 /**
  * Build a per-category colour map from a select/lookup field's `options`.
@@ -202,30 +653,323 @@ export function buildCategoryRank(order) {
     });
     return rank.size > 0 ? rank : null;
 }
+/** One option, normalized out of the `{value,label}` / bare-string spellings. */
+function optionValueLabel(opt) {
+    if (typeof opt === 'string' || typeof opt === 'number' || typeof opt === 'boolean') {
+        // A bare-string option IS its own label. Nothing to resolve, but there is
+        // something to TRANSLATE — the bundle is keyed by the stored value.
+        return { value: String(opt), label: String(opt) };
+    }
+    if (opt && typeof opt === 'object') {
+        const o = opt;
+        if (o.value != null && o.label != null)
+            return { value: String(o.value), label: String(o.label) };
+    }
+    return null;
+}
+/**
+ * Run a select field's `options` through the locale bundle, returning options
+ * whose `label` is the translated one (objectui#4030).
+ *
+ * The mirror of `useObjectLabel().translateOptions` — the channel list and form
+ * surfaces localize select options through — kept pure and shape-tolerant so
+ * the analytics net can apply it at the point the resolved options are read.
+ * Everything downstream ({@link buildOptionColorMap},
+ * {@link buildCategoryOrder}) keeps reading `option.label` and needs no
+ * knowledge of i18n, exactly like `SelectCellRenderer` on the list side.
+ *
+ * Colour, order and every other option key survive untouched — only `label`
+ * changes. Returns the input ARRAY ITSELF when there is no translator or
+ * nothing translated, so an untranslated app keeps the identities (and the
+ * memo/render behaviour) it had before.
+ */
+export function localizeFieldOptions(options, translate) {
+    if (!translate || !Array.isArray(options) || options.length === 0)
+        return options;
+    let changed = false;
+    const next = options.map((opt) => {
+        const vl = optionValueLabel(opt);
+        if (!vl)
+            return opt;
+        const display = translate(vl.value, vl.label);
+        if (display === vl.label)
+            return opt;
+        changed = true;
+        // A bare-string option becomes an object so the translation has somewhere
+        // to live; its value is preserved, which is the only identity that matters.
+        return opt && typeof opt === 'object'
+            ? { ...opt, label: display }
+            : { value: vl.value, label: display };
+    });
+    return changed ? next : options;
+}
 /**
  * Build a `{ value → label }` map from a select/enum field's `options`, for
  * resolving a grouped dimension's stored value to its display label (fed to
  * {@link relabelDimensions}). Mirrors {@link buildOptionColorMap}.
  *
  * Options may be `{ value, label }` objects or bare strings (value == label —
- * nothing to relabel). Only entries whose `label` actually differs from the
- * `value` are kept, so the map is empty (→ `null`) when relabeling would be a
+ * nothing to relabel). Only entries whose display label actually differs from
+ * the key are kept, so the map is empty (→ `null`) when relabeling would be a
  * no-op and the caller can skip it entirely.
+ *
+ * **With a `translate` seam (objectui#4030) the map gains a SECOND key per
+ * option: the AUTHORED label.** A dimension's rows reach this net keyed either
+ * way — value-keyed when the server did not resolve the dimension (the whole
+ * reason this net exists), already label-keyed when it did (ADR-0021) — and
+ * the reported symptom is the second case: a chart legend showing the object's
+ * English `label` verbatim beside a related list showing the translation. One
+ * key resolves `orion`, the other re-translates `Orion Engineered Carbons`;
+ * `relabelDimensions` is value-wise and idempotent, so whichever the row
+ * carries lands on the same translated display.
+ *
+ * Value keys win over authored-label keys: a stored value that happens to
+ * equal some other option's label is still that option's value.
+ *
+ * Without a translator this is byte-for-byte the pre-#4030 map — the authored
+ * label then IS the display, so no second key is ever emitted.
  */
-export function buildDimensionLabelMap(options) {
+export function buildDimensionLabelMap(options, translate) {
     if (!Array.isArray(options) || options.length === 0)
         return null;
-    const map = {};
+    const byValue = {};
+    const byAuthoredLabel = {};
     for (const opt of options) {
-        if (opt && typeof opt === 'object') {
-            const o = opt;
-            if (o.value != null && o.label != null) {
-                const v = String(o.value);
-                const l = String(o.label);
-                if (l !== v)
-                    map[v] = l;
+        const vl = optionValueLabel(opt);
+        if (!vl)
+            continue;
+        const display = translate ? translate(vl.value, vl.label) : vl.label;
+        if (display !== vl.value)
+            byValue[vl.value] = display;
+        if (display !== vl.label)
+            byAuthoredLabel[vl.label] = display;
+    }
+    const map = { ...byAuthoredLabel, ...byValue };
+    return Object.keys(map).length > 0 ? map : null;
+}
+/**
+ * Field types that JOIN to another object, so they can be a hop in a dotted
+ * dimension path. Mirrors the dataset designer's allowlist
+ * (`useDatasetFields.ts`), matched case-insensitively so `masterDetail` and
+ * `master_detail` both resolve.
+ */
+const RELATIONSHIP_FIELD_TYPES = new Set(['lookup', 'master_detail', 'masterdetail', 'master-detail']);
+/** The `fields` map of an object metadata doc, or null when it isn't one. */
+function fieldDefsOf(schema) {
+    const fields = schema?.fields;
+    return fields && typeof fields === 'object' && !Array.isArray(fields)
+        ? fields
+        : null;
+}
+/**
+ * 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 **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
+ * fetched speculatively.
+ */
+export function resolveRelationshipTarget(fieldDef) {
+    if (!fieldDef || typeof fieldDef !== 'object')
+        return undefined;
+    const def = 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;
+}
+/**
+ * Resolve each dataset dimension's underlying `field` to that field's select
+ * `options`, following DOTTED relationship paths to the object that actually
+ * owns the terminal field (objectui#4053).
+ *
+ * A dimension's `field` is either a local field name (`industry`) or a
+ * relationship path (`crm_account.industry`, and — per ADR-0071, which the
+ * dataset designer emits — `crm_account.owner.department`). Reading the options
+ * as `baseSchema.fields[path]` only ever works for the local spelling: for a
+ * dotted path the options live on the RELATED object, the lookup missed
+ * silently, and the chart fell through to the raw stored enum while the same
+ * field as a local dimension rendered its labels beside it.
+ *
+ * This is the object-resolution step of that ONE lookup, not a dotted-path
+ * variant beside it: a single-segment path never enters the walk and resolves
+ * exactly as before, so the local path cannot drift away from the joined one.
+ *
+ * `loadObjectSchema` supplies each hop's object metadata doc — the caller's
+ * existing channel (the same `GET /meta/object/:name` read that produced
+ * `baseSchema`), so no new fetch layer is introduced. It is memoized per call,
+ * because sibling dimensions routinely share a prefix (`crm_account.industry`
+ * alongside `crm_account.type` fetches `crm_account` once), and seeded with
+ * `baseSchema` under its own `name` so the base is never re-fetched.
+ *
+ * Best-effort by construction: a hop that is not a relationship, a target that
+ * cannot be loaded, or a terminal field that carries no `options` simply yields
+ * no entry, and the caller keeps the raw value. Returns `{ fieldPath → options }`
+ * for the paths that did resolve.
+ *
+ * Thin wrapper over {@link resolveDimensionFieldMeta}, which is the same ONE
+ * walk keeping the identity of what it found. Callers that translate option
+ * labels need that identity (the i18n key is
+ * `fieldOptions.<owningObject>.<terminalField>.<value>`, and for a dotted path
+ * the owner is the RELATIONSHIP TARGET, not the dataset's base object) — see
+ * objectui#4030.
+ */
+export async function resolveDimensionFieldOptions(baseSchema, fieldPaths, loadObjectSchema) {
+    const meta = await resolveDimensionFieldMeta(baseSchema, fieldPaths, loadObjectSchema);
+    const out = {};
+    for (const [path, entry] of Object.entries(meta))
+        out[path] = entry.options;
+    return out;
+}
+/**
+ * {@link resolveDimensionFieldOptions} keeping what it walked THROUGH.
+ *
+ * Same single walk, same best-effort tolerance, same memoized loader — it just
+ * returns `{ object, field, options }` per resolved path instead of the options
+ * alone. Split out for objectui#4030: applying the locale bundle to a resolved
+ * option label needs the key the bundle is written under
+ * (`fieldOptions.<object>.<field>.<value>`), and for `crm_account.industry`
+ * that object is `crm_account` — the walk already knows it and used to drop it
+ * on the floor. Deriving it at the call site would mean re-walking the
+ * relationship chain a second time, i.e. two derivations of one fact.
+ */
+export async function resolveDimensionFieldMeta(baseSchema, fieldPaths, loadObjectSchema) {
+    const out = {};
+    const paths = Array.from(new Set((fieldPaths ?? []).filter((p) => !!p)));
+    if (paths.length === 0)
+        return out;
+    const cache = new Map();
+    const baseName = baseSchema?.name;
+    if (typeof baseName === 'string' && baseName)
+        cache.set(baseName, Promise.resolve(baseSchema));
+    const load = (name) => {
+        let hit = cache.get(name);
+        if (!hit) {
+            // A rejected hop resolves to null rather than throwing, so one unreachable
+            // relationship costs its own dimension's labels and not the whole chart's.
+            hit = Promise.resolve().then(() => loadObjectSchema(name)).catch(() => null);
+            cache.set(name, hit);
+        }
+        return hit;
+    };
+    for (const path of paths) {
+        const segments = path.split('.');
+        let schema = baseSchema;
+        // The object owning the CURRENT schema — walked forward with it, so the
+        // terminal field's owner is whatever it holds when the walk ends.
+        let owner = typeof baseName === 'string' && baseName ? baseName : undefined;
+        let walked = true;
+        // Every segment but the last must be a relationship; walk to its target.
+        // Hops are sequential by nature — hop N's object is only known once hop
+        // N-1 has been read.
+        for (let i = 0; i < segments.length - 1; i += 1) {
+            const target = resolveRelationshipTarget(fieldDefsOf(schema)?.[segments[i]]);
+            if (!target) {
+                walked = false;
+                break;
             }
+            schema = await load(target);
+            if (!schema) {
+                walked = false;
+                break;
+            }
+            // Prefer the loaded doc's own `name` over the reference's spelling, so a
+            // reference written against an alias still keys the bundle canonically.
+            const loadedName = schema.name;
+            owner = typeof loadedName === 'string' && loadedName ? loadedName : target;
         }
+        if (!walked)
+            continue;
+        const field = segments[segments.length - 1];
+        const terminal = fieldDefsOf(schema)?.[field];
+        if (terminal?.options !== undefined)
+            out[path] = { object: owner, field, options: terminal.options };
     }
-    return Object.keys(map).length > 0 ? map : null;
+    return out;
+}
+/**
+ * Bind a {@link FieldOptionLabelResolver} to ONE resolved dimension field,
+ * yielding the {@link OptionLabelTranslator} the option helpers take.
+ *
+ * The binding is the part that is easy to get wrong, which is why it is stated
+ * once here rather than at each call site: the translator must be bound to the
+ * object that OWNS the terminal field — `crm_account` for `crm_account.industry`,
+ * NOT the dataset's base object — because that owner is the key the locale
+ * bundle is written under. {@link resolveDimensionFieldMeta} already walked the
+ * relationship chain and kept that owner; this just reads it.
+ *
+ * Returns `undefined` — i.e. "no translation, keep the authored labels" — when
+ * the owner could not be resolved or no resolver was supplied. Every helper
+ * downstream then behaves exactly as it did before the #4030 seam existed.
+ */
+export function dimensionOptionTranslator(meta, fieldOptionLabel) {
+    const owner = meta?.object;
+    if (!owner || !fieldOptionLabel)
+        return undefined;
+    const field = meta.field;
+    return (value, authoredLabel) => fieldOptionLabel(owner, field, value, authoredLabel);
+}
+/**
+ * Derive the `{ dimension → { value|authoredLabel → displayLabel } }` maps that
+ * {@link relabelDimensions} consumes, from metadata {@link loadDimensionFieldMeta}
+ * (or {@link resolveDimensionFieldMeta}) already resolved.
+ *
+ * This is the LOCALE-APPLYING step, and keeping it separate from the load is
+ * the whole point of the split (objectui#4030 / PR #4324): the fetched metadata
+ * stays locale-free, so switching language re-derives these maps in a render
+ * memo instead of re-issuing the metadata read. A caller that folds the two
+ * together reintroduces a refetch on every language switch — the defect #4324
+ * fixed, and the property objectui#4389 lifted here so it is stated once.
+ *
+ * Best-effort per dimension, exactly as the longhand copies were: a path that
+ * resolved no metadata, or whose field carries no `options`, contributes no
+ * entry, and `relabelDimensions` then returns the caller's rows by identity.
+ * Returns `null` — never an empty object — when nothing resolved, so callers
+ * can skip the relabel entirely.
+ */
+export function deriveDimensionLabelMaps(metaByPath, relabel, fieldOptionLabel) {
+    if (!metaByPath || !relabel || relabel.length === 0)
+        return null;
+    const labels = {};
+    for (const { dim, path } of relabel) {
+        const meta = metaByPath[path];
+        const map = buildDimensionLabelMap(meta?.options, dimensionOptionTranslator(meta, fieldOptionLabel));
+        if (map)
+            labels[dim] = map;
+    }
+    return Object.keys(labels).length > 0 ? labels : null;
+}
+/**
+ * Load one dataset query's dimension field metadata: fetch the base object's
+ * schema, then resolve every dimension's field path against it.
+ *
+ * The two-step composition every caller wrote out by hand. `loadObjectSchema`
+ * stays the CALLER's channel — this package issues no reads of its own and has
+ * no opinion about transport, which is what keeps it free of React, of
+ * `SchemaRendererContext`, and of the authenticated-`apiFetch` concern
+ * (objectui#4121) that belongs to the layer holding the host context.
+ *
+ * The same loader serves both steps by design: {@link resolveDimensionFieldMeta}
+ * memoizes it per call and seeds the cache with the base schema under its own
+ * `name`, so the base object is read ONCE even when several dotted dimensions
+ * walk back through it. That read count is pinned on both consuming surfaces.
+ */
+export async function loadDimensionFieldMeta(loadObjectSchema, object, fieldPaths) {
+    const baseSchema = await loadObjectSchema(object);
+    return resolveDimensionFieldMeta(baseSchema, fieldPaths, loadObjectSchema);
 }