@object-ui/core 17.3.0 → 17.5.0

package/dist/theme/ThemeEngine.js

@@ -116,41 +116,33 @@ export function generateColorVars(colors) {
 /**
  * Generate CSS custom properties from a Theme's typography config.
  */
+// ----------------------------------------------------------------------------
+// RETIRED THEME BLOCKS — @objectstack/spec 17.0.0-rc.3 (objectstack#5021 option
+// 2, PR objectstack#5289), objectui#3361.
+//
+// `theme.animation`, `theme.zIndex` and five typography groups
+// (`fontSize` / `fontWeight` / `lineHeight` / `letterSpacing`, plus
+// `fontFamily.heading` / `fontFamily.mono`) became TOMBSTONES: the schema now
+// rejects them by name and their prescription points at `theme.customVars`, the
+// declared — and since #5021 the only — door for a custom property. A
+// `--z-modal` or a `--duration-fast` is authored there now, emitted verbatim as
+// `--<key>: <value>`.
+//
+// The emission code below them was therefore structurally dead: no author can
+// produce the input that would reach it. It is removed rather than left behind
+// a cast, because the tombstoned keys type as `never` and any cast that made
+// them compile would fossilize a shape the contract has withdrawn (AGENTS.md
+// #0.1). LIVE emission — `colors`, `borderRadius`, `shadows`,
+// `typography.fontFamily.base` (→ `--font-sans`) and `customVars` — is
+// untouched, byte for byte.
+// ----------------------------------------------------------------------------
 export function generateTypographyVars(typography) {
     const vars = {};
+    // `fontFamily.base` is the only surviving typography input — see the RETIRED
+    // THEME BLOCKS note above for where the other five groups went.
     if (typography.fontFamily?.base) {
         vars['--font-sans'] = typography.fontFamily.base;
     }
-    if (typography.fontFamily?.heading) {
-        vars['--font-heading'] = typography.fontFamily.heading;
-    }
-    if (typography.fontFamily?.mono) {
-        vars['--font-mono'] = typography.fontFamily.mono;
-    }
-    if (typography.fontSize) {
-        for (const [key, value] of Object.entries(typography.fontSize)) {
-            if (value)
-                vars[`--font-size-${key}`] = value;
-        }
-    }
-    if (typography.fontWeight) {
-        for (const [key, value] of Object.entries(typography.fontWeight)) {
-            if (value != null)
-                vars[`--font-weight-${key}`] = String(value);
-        }
-    }
-    if (typography.lineHeight) {
-        for (const [key, value] of Object.entries(typography.lineHeight)) {
-            if (value)
-                vars[`--line-height-${key}`] = value;
-        }
-    }
-    if (typography.letterSpacing) {
-        for (const [key, value] of Object.entries(typography.letterSpacing)) {
-            if (value)
-                vars[`--letter-spacing-${key}`] = value;
-        }
-    }
     return vars;
 }
 /**
@@ -197,36 +189,6 @@ export function generateShadowVars(shadows) {
     }
     return vars;
 }
-/**
- * Generate CSS custom properties from a Theme's animation config.
- */
-export function generateAnimationVars(animation) {
-    const vars = {};
-    if (animation.duration) {
-        for (const [key, value] of Object.entries(animation.duration)) {
-            if (value)
-                vars[`--duration-${key}`] = value;
-        }
-    }
-    if (animation.timing) {
-        for (const [key, value] of Object.entries(animation.timing)) {
-            if (value)
-                vars[`--timing-${key}`] = value;
-        }
-    }
-    return vars;
-}
-/**
- * Generate CSS custom properties from a Theme's z-index config.
- */
-export function generateZIndexVars(zIndex) {
-    const vars = {};
-    for (const [key, value] of Object.entries(zIndex)) {
-        if (value != null)
-            vars[`--z-${key}`] = String(value);
-    }
-    return vars;
-}
 /**
  * Generate ALL CSS custom properties from a complete Theme.
  * This is the main entry point for theme → CSS conversion.
@@ -247,14 +209,6 @@ export function generateThemeVars(theme) {
     if (theme.shadows) {
         Object.assign(vars, generateShadowVars(theme.shadows));
     }
-    // Animation
-    if (theme.animation) {
-        Object.assign(vars, generateAnimationVars(theme.animation));
-    }
-    // Z-Index
-    if (theme.zIndex) {
-        Object.assign(vars, generateZIndexVars(theme.zIndex));
-    }
     // Custom CSS variables (passthrough)
     if (theme.customVars) {
         for (const [key, value] of Object.entries(theme.customVars)) {
@@ -290,22 +244,6 @@ export function mergeThemes(parent, child) {
                     ...parent.typography?.fontFamily,
                     ...child.typography?.fontFamily,
                 },
-                fontSize: {
-                    ...parent.typography?.fontSize,
-                    ...child.typography?.fontSize,
-                },
-                fontWeight: {
-                    ...parent.typography?.fontWeight,
-                    ...child.typography?.fontWeight,
-                },
-                lineHeight: {
-                    ...parent.typography?.lineHeight,
-                    ...child.typography?.lineHeight,
-                },
-                letterSpacing: {
-                    ...parent.typography?.letterSpacing,
-                    ...child.typography?.letterSpacing,
-                },
             }
             : undefined,
         // Deep-merge border radius
@@ -316,25 +254,6 @@ export function mergeThemes(parent, child) {
         shadows: child.shadows || parent.shadows
             ? { ...parent.shadows, ...child.shadows }
             : undefined,
-        // Deep-merge animation
-        animation: child.animation || parent.animation
-            ? {
-                ...parent.animation,
-                ...child.animation,
-                duration: {
-                    ...parent.animation?.duration,
-                    ...child.animation?.duration,
-                },
-                timing: {
-                    ...parent.animation?.timing,
-                    ...child.animation?.timing,
-                },
-            }
-            : undefined,
-        // Deep-merge zIndex
-        zIndex: child.zIndex || parent.zIndex
-            ? { ...parent.zIndex, ...child.zIndex }
-            : undefined,
         // Deep-merge customVars
         customVars: child.customVars || parent.customVars
             ? { ...parent.customVars, ...child.customVars }

package/dist/theme/index.d.ts

@@ -5,4 +5,4 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateAnimationVars, generateZIndexVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';
+export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';

package/dist/theme/index.js

@@ -5,4 +5,10 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, generateAnimationVars, generateZIndexVars, generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';
+export { hexToHSL, toCSSColor, generateColorVars, generateTypographyVars, generateBorderRadiusVars, generateShadowVars, 
+// `generateAnimationVars` / `generateZIndexVars` removed with the
+// `theme.animation` / `theme.zIndex` tombstones in @objectstack/spec
+// 17.0.0-rc.3 (objectstack#5021) — see ThemeEngine's RETIRED THEME BLOCKS
+// note. `theme.customVars` is the declared door for a `--duration-*` or
+// `--z-*` now.
+generateThemeVars, mergeThemes, resolveThemeInheritance, resolveMode, contrastRatio, meetsContrastLevel, } from './ThemeEngine';

package/dist/types/index.d.ts

@@ -5,14 +5,48 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export interface SchemaNode {
-    type: string;
-    id?: string;
-    className?: string;
-    data?: any;
-    body?: SchemaNode | SchemaNode[];
-    [key: string]: any;
-}
+/**
+ * One `SchemaNode` (objectui#4580).
+ *
+ * This package used to hand-declare `interface SchemaNode { type: string; …
+ * [key: string]: any }` here, while `@object-ui/types` exported
+ * `type SchemaNode = BaseSchema | string | number | boolean | null | undefined`
+ * — two different types under one name, from two packages the same consumers
+ * import together. Which declaration a call site got depended on which package
+ * it happened to import from, and #4548's option-A canary measured **19 of 35**
+ * errors as exactly that collision:
+ *
+ * ```
+ * Type 'import(".../packages/types/dist/base").SchemaNode' is not assignable to
+ * type 'import(".../packages/core/dist/types/index").SchemaNode'
+ * ```
+ *
+ * PR #4578 sidestepped it — `SchemaRenderer` states its own component-level
+ * union rather than picking a side — and left the reconciliation to this card.
+ *
+ * **`@object-ui/types`' union wins**, per #4580's ruling 1: it is the spec of
+ * record (its own doc comment names `'Plain string'` a valid node), and it is
+ * the side the measured collisions resolve toward. The declaration is RE-EXPORTED
+ * rather than restated, so there is exactly one declaration left to disagree
+ * with — a structural copy would reproduce the defect the moment either side
+ * moved. This package already depends on `@object-ui/types`, so the edge exists
+ * and adds no cycle, and core's own entry surface is unchanged (`dist/index.d.ts`
+ * is byte-identical across the change — measured, both rounds).
+ *
+ * The collision is only observable from a package that resolves BOTH through
+ * `node_modules`; the pin therefore lives in `@object-ui/react`
+ * (`src/__tests__/SchemaNode.reconciliation.test.ts`), not here.
+ */
+export type { SchemaNode } from '@object-ui/types';
+import type { SchemaNode } from '@object-ui/types';
+/**
+ * ⛔ Deliberately NOT reconciled with `@object-ui/types`' `ComponentRendererProps`
+ * (objectui#4594). The two declarations differ — types' is generic
+ * (`< TSchema extends BaseSchema = BaseSchema >`), this one is not — but that
+ * card measured **zero consumers** of this declaration, so reconciling it here
+ * would be an unmeasured change riding a card that was scoped to `SchemaNode`.
+ * It stays dual-declared until #4594 is dispatched on its own evidence.
+ */
 export interface ComponentRendererProps {
     schema: SchemaNode;
     [key: string]: any;

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

@@ -20,6 +20,11 @@
  *    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.
  */
 export interface ChartResultField {
     name: string;
@@ -47,7 +52,36 @@ export interface ChartSeriesResult {
     xAxisKey: string | undefined;
     series: ChartSeriesBinding[];
 }
-export declare function buildChartSeries(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, fields?: ChartResultField[] | null): ChartSeriesResult;
+/**
+ * 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 declare const NULL_CATEGORY_LABEL = "(None)";
+/** Per-call knobs shared by {@link buildChartSeries} / {@link findChartSeriesRow}. */
+export interface ChartSeriesOptions {
+    /**
+     * Display label for a category whose value is `null`/`undefined`. Defaults to
+     * {@link NULL_CATEGORY_LABEL}.
+     *
+     * Pass the SAME value to both helpers: `buildChartSeries` writes it into the
+     * rendered rows and `findChartSeriesRow` matches a clicked category against
+     * it, so a mismatch costs the null bucket its drill-through.
+     */
+    nullCategoryLabel?: string;
+}
+export declare function buildChartSeries(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, fields?: ChartResultField[] | null, options?: ChartSeriesOptions): ChartSeriesResult;
 /**
  * Resolve select/enum dimension VALUES to display LABELS in chart rows.
  *
@@ -85,8 +119,28 @@ export declare function relabelDimensions(rows: Array<Record<string, unknown>> |
  *
  * 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 declare function findChartSeriesRow(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, category: string | undefined, seriesKey?: string): number;
+export declare function findChartSeriesRow(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, category: string | undefined, seriesKey?: string, options?: ChartSeriesOptions): number;
 /**
  * Build a per-category colour map from a select/lookup field's `options`.
  *
@@ -129,14 +183,213 @@ export declare function buildCategoryOrder(options: unknown): string[] | null;
  * after the declared ones rather than dropping them).
  */
 export declare function buildCategoryRank(order: string[] | null | undefined): Map<string, number> | null;
+/**
+ * The i18n seam of the analytics label net (objectui#4030).
+ *
+ * `(storedValue, authoredLabel) => displayLabel` — the SAME signature
+ * `resolveGroupByLabels` (plugin-charts) already takes for the legacy aggregate
+ * path, which callers bind to `useSafeFieldLabel().fieldOptionLabel(object,
+ * field, …)`. That resolver reads `{ns}.fieldOptions.<object>.<field>.<value>`,
+ * the one convention list and form surfaces already translate select options
+ * through (`useObjectLabel.translateOptions`, and `@objectstack/spec` names
+ * objectui as its reader). Analytics reuses that channel rather than growing a
+ * chart-side per-locale dialect.
+ *
+ * Omitted everywhere it isn't available (no i18n provider, an unresolvable
+ * owning object): every helper below then behaves exactly as it did before this
+ * seam existed.
+ */
+export type OptionLabelTranslator = (value: string, authoredLabel: string) => string;
+/**
+ * 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 declare function localizeFieldOptions(options: unknown, translate?: OptionLabelTranslator): unknown;
 /**
  * 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 declare function buildDimensionLabelMap(options: unknown, translate?: OptionLabelTranslator): Record<string, string> | 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 declare function resolveRelationshipTarget(fieldDef: unknown): string | 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 declare function resolveDimensionFieldOptions(baseSchema: unknown, fieldPaths: Array<string | undefined | null>, loadObjectSchema: (objectName: string) => Promise<unknown>): Promise<Record<string, unknown>>;
+/**
+ * What {@link resolveDimensionFieldOptions} found for ONE dimension field path
+ * — the options AND the identity of the field they belong to.
+ */
+export interface DimensionFieldMeta {
+    /**
+     * The object that OWNS the terminal field: the dataset's base object for a
+     * local path, the last relationship's TARGET for a dotted one. `undefined`
+     * only when the base schema carries no `name` and the path is local.
+     */
+    object: string | undefined;
+    /** The terminal field's own name — the LAST path segment, never the path. */
+    field: string;
+    /** The terminal field's `options`, exactly as the metadata doc carries them. */
+    options: unknown;
+}
+/**
+ * {@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 declare function resolveDimensionFieldMeta(baseSchema: unknown, fieldPaths: Array<string | undefined | null>, loadObjectSchema: (objectName: string) => Promise<unknown>): Promise<Record<string, DimensionFieldMeta>>;
+/**
+ * The locale-bundle resolver a caller supplies to translate one option label —
+ * `useSafeFieldLabel().fieldOptionLabel` in every current caller, i.e. the
+ * `{ns}.fieldOptions.<object>.<field>.<value>` convention list and form
+ * surfaces already translate select options through (objectui#4030).
+ *
+ * Taken as a plain function so this package needs no knowledge of i18n, React,
+ * or which provider is mounted — the same reason {@link OptionLabelTranslator}
+ * is a bare function type.
+ */
+export type FieldOptionLabelResolver = (object: string, field: string, value: string, authoredLabel: string) => string;
+/**
+ * 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 declare function dimensionOptionTranslator(meta: DimensionFieldMeta | undefined, fieldOptionLabel?: FieldOptionLabelResolver): OptionLabelTranslator | undefined;
+/** One dimension paired with the field path its values resolve through. */
+export interface DimensionRelabelTarget {
+    /** The dimension name as the surface renders it (the row key). */
+    dim: string;
+    /** That dimension's underlying field path, as the dataset query reported it. */
+    path: string;
+}
+/**
+ * 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 declare function deriveDimensionLabelMaps(metaByPath: Record<string, DimensionFieldMeta> | null | undefined, relabel: readonly DimensionRelabelTarget[] | null | undefined, fieldOptionLabel?: FieldOptionLabelResolver): Record<string, Record<string, string>> | 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 declare function buildDimensionLabelMap(options: unknown): Record<string, string> | null;
+export declare function loadDimensionFieldMeta(loadObjectSchema: (objectName: string) => Promise<unknown>, object: string, fieldPaths: Array<string | undefined | null>): Promise<Record<string, DimensionFieldMeta>>;