@object-ui/core 17.2.0 → 17.5.0

package/dist/utils/chart-series.js

@@ -5,7 +5,64 @@
  * 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) {
+/**
+ * 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)';
+/**
+ * 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 (!!row &&
+        typeof row === 'object' &&
+        key in row &&
+        row[key] == null);
+}
+/**
+ * Map a null/undefined category VALUE to its bucket label, for the
+ * single-dimension branch (objectui#4466).
+ *
+ * Returns the input array itself when nothing was null, 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.
+ */
+function bucketNullCategories(rows, key, label) {
+    let changed = false;
+    const next = rows.map((row) => {
+        if (!isNullCategory(row, key))
+            return row;
+        changed = true;
+        return { ...row, [key]: label };
+    });
+    return changed ? next : rows;
+}
+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,13 +72,25 @@ export function buildChartSeries(rows, dimensions, values, fields) {
         const xKey = dims[0];
         const groupKey = dims[1];
         const measure = vals[0];
+        const nullLabel = options?.nullCategoryLabel ?? NULL_CATEGORY_LABEL;
         const seriesKeys = [];
         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 });
+            // 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 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 });
+            }
             const gId = String(row[groupKey] ?? '');
             if (gId !== '' && !seriesKeys.includes(gId))
                 seriesKeys.push(gId);
@@ -36,9 +105,25 @@ export function buildChartSeries(rows, dimensions, values, fields) {
         };
     }
     // 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) })),
     };
 }
@@ -101,8 +186,28 @@ export function relabelDimensions(rows, labelMaps) {
  *
  * 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 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.
+ *
+ * **`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 +215,16 @@ export function findChartSeriesRow(rows, dimensions, values, category, seriesKey
     if (!xDim)
         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]);
     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);
+        return safeRows.findIndex((r) => xOf(r) === c && String(r[gDim] ?? '') === s);
     }
-    return safeRows.findIndex((r) => String(r[xDim] ?? '') === c);
+    return safeRows.findIndex((r) => xOf(r) === c);
 }
 /**
  * Build a per-category colour map from a select/lookup field's `options`.
@@ -202,30 +311,324 @@ 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;
+            }
+            // eslint-disable-next-line no-await-in-loop
+            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);
 }

package/dist/utils/compare-to.d.ts

@@ -8,23 +8,50 @@
 /**
  * Period-over-period comparison config for dashboard widgets.
  *
- * - `'previousPeriod'` — substitute `current_*` / `today` date macro tokens
- *   with their `last_*` / `yesterday` counterparts (e.g. `current_quarter_start`
- *   → `last_quarter_start`). Best when the filter uses date macros.
- * - `'previousYear'` — re-resolve date macros against a `now` shifted back
- *   one calendar year (same week / month / quarter, one year earlier).
- * - `{ offset: '7d' | '4w' | '1M' | '1y' }` — re-resolve macros against a
- *   `now` shifted by the given duration. Units: `d` (day), `w` (week),
- *   `M` (month), `y` (year).
+ * Converged (objectstack#5011) onto the contract the analytics executor
+ * already implements — `DatasetSelection.compareTo`, i.e. `DatasetCompareTo`
+ * in `@objectstack/spec` (`contracts/analytics-service.ts`). This type is that
+ * contract's thin projection, so the same widget key means the same thing on
+ * the ADR-0021 dataset path and on this legacy inline object-provider path.
+ *
+ * - `kind: 'previousPeriod'` — the equal-length window immediately before the
+ *   current one. On the inline path that is done by substituting `current_*` /
+ *   `today` date macro tokens with their `last_*` / `yesterday` counterparts
+ *   (`current_quarter_start` → `last_quarter_start`), so it works best when the
+ *   filter is written with date macros.
+ * - `kind: 'previousYear'` — re-resolve the filter's date macros against a
+ *   `now` shifted back one calendar year (same week / month / quarter, one year
+ *   earlier).
+ * - `dimension` — OPTIONAL, and deliberately never read on this path. It names
+ *   the dataset time dimension whose `dateRange` the EXECUTOR shifts. That
+ *   resolution lives at the producer of the comparison so that every caller
+ *   gets the same answer or the same loud error; a renderer that guessed a
+ *   dimension would trade "loud error" for "quietly wrong window" — precisely
+ *   the failure class this convergence exists to end.
+ *
+ * **Design note — a plain strict object, NOT a union** (objectstack#5011,
+ * framework#5014). The retired shape was a three-branch union
+ * (`'previousPeriod' | 'previousYear' | { offset }`); zod collapses a failed
+ * union into a bare `Invalid input`, so the prescriptions written inside each
+ * arm never reached the author. One strict object keeps the rejection specific.
+ * It also leaves this renderer with exactly one contract to read — no second
+ * de-facto dialect to be tolerant about (AGENTS.md #0.1).
+ *
+ * The `{ offset: '7d' | '1M' | '1y' }` arm went with the union: `{ offset: '1y' }`
+ * IS `kind: 'previousYear'` (rewritten deterministically upstream), while
+ * `'7d'` / `'1M'` have no faithful target — an author restates that window on
+ * the widget's own `filter` and asks for `kind: 'previousPeriod'` (registered
+ * semantic migration `dashboard-widget-compareto-offset`).
  */
-export type CompareToConfig = 'previousPeriod' | 'previousYear' | {
-    offset: string;
-};
+export interface CompareToConfig {
+    kind: 'previousPeriod' | 'previousYear';
+    dimension?: string;
+}
 /**
- * Resolve a filter for a period-over-period comparison query.
+ * Resolve a filter for a period-over-period comparison query. Dispatches on
+ * `compareTo.kind` — the only discriminator the converged shape has:
  *
  * - `previousYear` — re-resolve date macros against a `now` shifted back by one year.
- * - `{ offset }` — re-resolve date macros against a `now` shifted by the given duration.
  * - `previousPeriod` — substitute `current_*` / `today` tokens with `last_*` / `yesterday`
  *   before resolving.
  */

package/dist/utils/compare-to.js

@@ -44,44 +44,19 @@ function substituteTokens(value, map) {
     }
     return value;
 }
-function shiftNow(now, offset) {
-    const m = offset.match(/^(\d+)([dwMy])$/);
-    if (!m)
-        return null;
-    const n = parseInt(m[1], 10);
-    const unit = m[2];
-    const x = new Date(now);
-    if (unit === 'd')
-        x.setDate(x.getDate() - n);
-    else if (unit === 'w')
-        x.setDate(x.getDate() - n * 7);
-    else if (unit === 'M')
-        x.setMonth(x.getMonth() - n);
-    else if (unit === 'y')
-        x.setFullYear(x.getFullYear() - n);
-    else
-        return null;
-    return x;
-}
 /**
- * Resolve a filter for a period-over-period comparison query.
+ * Resolve a filter for a period-over-period comparison query. Dispatches on
+ * `compareTo.kind` — the only discriminator the converged shape has:
  *
  * - `previousYear` — re-resolve date macros against a `now` shifted back by one year.
- * - `{ offset }` — re-resolve date macros against a `now` shifted by the given duration.
  * - `previousPeriod` — substitute `current_*` / `today` tokens with `last_*` / `yesterday`
  *   before resolving.
  */
 export function shiftFilterByCompareTo(filter, compareTo, now = new Date()) {
-    if (compareTo === 'previousYear') {
+    if (compareTo.kind === 'previousYear') {
         const shifted = new Date(now.getFullYear() - 1, now.getMonth(), now.getDate(), now.getHours(), now.getMinutes(), now.getSeconds());
         return resolveDateMacros(filter, shifted);
     }
-    if (typeof compareTo === 'object' && compareTo && 'offset' in compareTo) {
-        const shifted = shiftNow(now, compareTo.offset);
-        if (!shifted)
-            return resolveDateMacros(filter, now);
-        return resolveDateMacros(filter, shifted);
-    }
     // previousPeriod
     const substituted = substituteTokens(filter, CURRENT_TO_LAST_TOKENS);
     return resolveDateMacros(substituted, now);
@@ -91,11 +66,8 @@ export function shiftFilterByCompareTo(filter, compareTo, now = new Date()) {
  * comparison window. Used by metric widgets to label the trend delta.
  */
 export function compareToTrendLabelKey(compareTo, filter) {
-    if (compareTo === 'previousYear')
+    if (compareTo.kind === 'previousYear')
         return 'vsLastYear';
-    if (typeof compareTo === 'object' && compareTo && 'offset' in compareTo) {
-        return 'vsPreviousPeriod';
-    }
     // previousPeriod — sniff the dominant token in the filter
     const json = filter ? JSON.stringify(filter) : '';
     if (/current_year_|year_start|year_end/.test(json))