@object-ui/core 17.2.0 → 17.5.0

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>>;