@object-ui/core 17.5.0 → 17.7.0

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

@@ -5,32 +5,42 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/**
- * chart-series — shape a semantic-layer `queryDataset` result into the
- * `{ data, xAxisKey, series }` triple a chart renderer consumes (ADR-0021, #1759).
- *
- * Shared by `ObjectChart` (plugin-charts) and `DatasetWidget` (plugin-dashboard)
- * so multi-dimension charts visualise identically across surfaces.
- *
- * Rules:
- *  - **2+ dimensions, single measure** → pivot the SECOND dimension into one
- *    series per distinct value (grouped/coloured bars). `xAxisKey` = first
- *    dimension; each output row is one first-dimension bucket with a column per
- *    second-dimension value holding the measure. This makes the second dimension
- *    visible instead of just repeating the x-axis label.
- *  - **otherwise** (single dimension, or multiple measures) → first dimension is
- *    the x-axis and each measure is its own series (long format passes through).
- *
- * BOTH branches map a NULL first-dimension VALUE to an explicit bucket label
- * ({@link NULL_CATEGORY_LABEL}) so the group renders instead of vanishing —
- * objectui#4466 for the single-dimension branch, objectui#4497 for the pivot.
- * One doctrine, one predicate (`isNullCategory`), two call sites.
- */
 export interface ChartResultField {
     name: string;
     label?: string;
     format?: string;
 }
+/**
+ * The OPTIONAL wire discriminator naming which server-side BUILT-IN default
+ * measure a result column is (objectui#7258; producer half objectstack#14492).
+ * The analytics service sets it ONLY on the measures it minted itself with a
+ * hard-coded English default label (`count` → `'Count'`, …); an author-declared
+ * measure never carries it, so its `label` stays the author's verbatim text
+ * (objectui#4106). {@link resolveMeasureLabel} is the one reader.
+ *
+ * Declared BESIDE {@link ChartResultField} rather than on it, deliberately:
+ * `dataset-result-field-spec-parity` pins every key of `ChartResultField` as a
+ * key of the spec's `AnalyticsResult.fields[]`, and the `@objectstack/spec`
+ * this package is built against does not carry `builtinAggregate` yet. The
+ * intersection {@link ChartMeasureField} is what the helpers accept, so a
+ * spec-typed field flows in unchanged today and carries the key the moment
+ * the spec does — structurally, with no cast at the call sites.
+ *
+ * Typed as `string` rather than the closed {@link BuiltinAggregate} union on
+ * purpose: a JSON response is handed here as-is, so the value is validated at
+ * the lookup ({@link isBuiltinAggregate}) instead of trusted at the type.
+ *
+ * TODO(objectstack#14492): once the spec dependency is bumped past the release
+ * that adds `AnalyticsResult.fields[].builtinAggregate`, fold this key into
+ * `ChartResultField` as `DatasetResultField['builtinAggregate']` (pinning the
+ * two closed vocabularies to each other in the parity suite) and retire the
+ * carrier.
+ */
+export interface BuiltinAggregateCarrier {
+    builtinAggregate?: string;
+}
+/** A result field as the series helpers read it: the renderer shape plus the optional discriminator. */
+export type ChartMeasureField = ChartResultField & BuiltinAggregateCarrier;
 /**
  * One renderer-internal series binding produced by {@link buildChartSeries}:
  * WHICH result-set column to draw and what to call it.
@@ -52,6 +62,47 @@ export interface ChartSeriesResult {
     xAxisKey: string | undefined;
     series: ChartSeriesBinding[];
 }
+/**
+ * The closed vocabulary of server-side built-in default measures a result field
+ * can declare itself as (objectui#7258 / objectstack#14492) — the spec's own
+ * measure-aggregate enum spelling (`count_distinct`, not `countDistinct`), so
+ * there is exactly ONE spelling on the wire and this list never grows on its
+ * own: a value outside it is not "a new aggregate", it is an unrecognised one,
+ * and {@link resolveMeasureLabel} treats it as absent.
+ */
+export declare const BUILTIN_AGGREGATES: readonly ["count", "sum", "avg", "min", "max", "count_distinct"];
+/** One member of {@link BUILTIN_AGGREGATES}. */
+export type BuiltinAggregate = (typeof BUILTIN_AGGREGATES)[number];
+/** Runtime membership test for {@link BUILTIN_AGGREGATES}, over an untrusted wire value. */
+export declare function isBuiltinAggregate(value: unknown): value is BuiltinAggregate;
+/**
+ * The LOCALIZED display label per built-in aggregate, as the layer that holds
+ * the i18n provider resolved them (`@object-ui/i18n`'s
+ * `builtinAggregateLabels(tt)`). Partial on purpose: an aggregate the caller
+ * did not resolve falls back to the wire `label`, exactly as if the field had
+ * carried no discriminator.
+ */
+export type BuiltinAggregateLabels = Partial<Record<BuiltinAggregate, string>>;
+/**
+ * The display label of ONE result field, for a legend / axis / tooltip.
+ *
+ * Resolution order (objectui#7258, maintainer ruling B of 2026-09-02):
+ *  1. the field declares itself a built-in default measure
+ *     (`builtinAggregate` ∈ {@link BUILTIN_AGGREGATES}) AND the caller resolved
+ *     a locale label for it → that label. This is the only path that can
+ *     replace a wire `label`, and it is keyed by a STRUCTURAL discriminator —
+ *     never by matching the label's text or the field's name, both of which
+ *     the ruling rejected (a real author measure literally named `count`, or
+ *     labelled `Count`, must keep its own label);
+ *  2. otherwise the wire `label` verbatim — the objectui#4106 contract for an
+ *     author-declared measure (`'Tasks'` reaches the legend untouched);
+ *  3. otherwise the field's `name`.
+ *
+ * So a discriminator the caller has no label for (a provider-less host, or a
+ * value outside the closed vocabulary) costs nothing: the field renders exactly
+ * what it rendered before the discriminator existed.
+ */
+export declare function resolveMeasureLabel(field: ChartMeasureField, labels?: BuiltinAggregateLabels): string;
 /**
  * The bucket a NULL/undefined category VALUE renders under, when the caller
  * supplies no localized label of its own (objectui#4466).
@@ -69,6 +120,57 @@ export interface ChartSeriesResult {
  * clicked bucket bar resolve back to its (raw null) dataset row.
  */
 export declare 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 declare function chartBucketId(rawValue: unknown): string;
+/**
+ * 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 declare 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 declare function chartRowBucketId(row: unknown): string | undefined;
 /** Per-call knobs shared by {@link buildChartSeries} / {@link findChartSeriesRow}. */
 export interface ChartSeriesOptions {
     /**
@@ -80,8 +182,81 @@ export interface ChartSeriesOptions {
      * it, so a mismatch costs the null bucket its drill-through.
      */
     nullCategoryLabel?: string;
+    /**
+     * Locale labels for the server's BUILT-IN default measures, keyed by the
+     * wire discriminator a result field carries as `builtinAggregate`
+     * (objectui#7258). Same division of labour as `nullCategoryLabel`: this
+     * package is React-free and i18n-free, so the renderer that holds the
+     * provider resolves the strings (`builtinAggregateLabels(tt)` in
+     * `@object-ui/i18n`) and passes them in. Absent ⇒ every measure keeps its
+     * wire `label`, which for a built-in default is the server's English.
+     */
+    builtinAggregateLabels?: BuiltinAggregateLabels;
+}
+/** Per-CLICK knobs for {@link findChartSeriesRow}, on top of the shared ones. */
+export interface ChartDrillLookupOptions extends ChartSeriesOptions {
+    /**
+     * The clicked bucket's {@link chartBucketId}, when the renderer could read one
+     * off the row the segment was drawn from ({@link chartRowBucketId} over
+     * {@link CHART_BUCKET_ID_KEY}) — objectui#4508.
+     *
+     * Supplied ⇒ AUTHORITATIVE: the lookup matches on identity and ignores
+     * `category` entirely, which is what lets two bars painting the same axis
+     * text drill to their own rows instead of both resolving to the first.
+     * Absent ⇒ the bucket's display string identified it on its own (that is
+     * exactly when `buildChartSeries` writes no id), or the rows were not built
+     * by `buildChartSeries` at all, and the display match answers.
+     */
+    bucketId?: string;
+}
+/**
+ * What a chart renderer hands a drill handler when a segment is clicked.
+ *
+ * Declared HERE, beside the two helpers that write and read a bucket, rather
+ * than re-spelled inline in each of the three packages that pass it along
+ * (`AdvancedChartImpl` builds it, `ChartRenderer` and `ObjectChart` forward it,
+ * `DatasetWidget` consumes it). It was three inline literals when
+ * {@link ChartDrillLookupOptions.bucketId} needed a carrier, and a field added
+ * to one of three copies reaches the consumer as `undefined` with nothing red.
+ */
+export interface ChartSegmentClickEvent {
+    /** The clicked bucket's axis TEXT — what the user sees on the tick. */
+    category?: string;
+    /**
+     * The clicked bucket's IDENTITY, when its row carried one (objectui#4508).
+     * Feed it straight to {@link ChartDrillLookupOptions.bucketId}; it is the
+     * only field that survives two buckets painting the same `category`.
+     */
+    categoryId?: string;
+    /** The clicked series' key — a measure, or a pivoted second-dimension value. */
+    series?: string;
+    /**
+     * The clicked series' DISPLAY LABEL, when the renderer knew one
+     * (objectui#4682) — `series[].label` as {@link buildChartSeries} assigned it.
+     *
+     * {@link ChartSegmentClickEvent.series} stays the LOOKUP key and this never
+     * substitutes for it: {@link findChartSeriesRow} resolves a key through the
+     * same assignment `buildChartSeries` made, and a label cannot be resolved
+     * that way — it is not unique (that is precisely why the colliding groups key
+     * by identity instead). This field exists for what a key cannot do: be SHOWN.
+     *
+     * The two strings are equal for every ordinary group, which is why reading
+     * the key as a title went unnoticed. They part company when a group's label
+     * cannot name it — objectui#4508's collision on the series axis — and the key
+     * becomes an opaque `chartBucketId`. A drawer titled `Backlog / [null]` over
+     * a segment the user saw labelled `(None)` reads as broken DATA rather than
+     * as a broken title, which is why the label travels with the click rather
+     * than being re-derived by the consumer.
+     *
+     * Absent when the renderer resolved no series, or when the series carries no
+     * label distinct from its key; a consumer titles itself from
+     * `seriesLabel ?? series` and so is unchanged wherever it is absent.
+     */
+    seriesLabel?: string;
+    /** The measure value at the click point. */
+    value?: number;
 }
-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;
+export declare function buildChartSeries(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, fields?: ChartMeasureField[] | null, options?: ChartSeriesOptions): ChartSeriesResult;
 /**
  * Resolve select/enum dimension VALUES to display LABELS in chart rows.
  *
@@ -117,16 +292,37 @@ export declare function relabelDimensions(rows: Array<Record<string, unknown>> |
  *    BOTH the x-axis dimension (`category`) and the series dimension (`seriesKey`).
  *  - **otherwise** → match the x-axis (first) dimension only.
  *
- * Comparison is string-wise on the rows' display values (which is what the chart
- * surfaces as `category` / series key). Returns `-1` when nothing matches.
+ * The x-axis comparison is string-wise on the rows' display values (which is
+ * what the chart surfaces as `category`), unless the click carried a bucket
+ * IDENTITY — {@link ChartDrillLookupOptions.bucketId} — in which case that is
+ * authoritative and the display string is not consulted at all. Returns `-1`
+ * when nothing matches.
+ *
+ * The SERIES comparison is not string-wise at all as of objectui#4673: a series
+ * key is a `dataKey` {@link buildChartSeries} assigned, so it is resolved back
+ * through the same {@link pivotSeriesBuckets} assignment (same rows, same
+ * `nullCategoryLabel`) to the group IDENTITY it names, and rows are matched on
+ * that. A null-valued second dimension had no series at all before, so its
+ * segment could not be clicked; now it can, and `String(r[gDim] ?? '')` would
+ * have answered that click with an empty-string group's rows — the same
+ * conflation objectui#4508 removed on the x-axis.
  *
  * The NULL-category bucket {@link buildChartSeries} renders (objectui#4466) is
  * matched back to its row here, and it has to be: the caller passes the rows it
  * charted FROM (still carrying the raw null) while the click event carries the
  * bucket LABEL, so without this the one bar the fix made visible would resolve
  * to `-1` and its drill-through would silently no-op. Pass the same
- * `nullCategoryLabel` both helpers were given. The pre-existing `''` spelling
- * of "no group value" still matches too — `computeDrillFilter` writes that one.
+ * `nullCategoryLabel` both helpers were given.
+ *
+ * **A null category reads as its bucket LABEL and nothing else** (objectui#4508).
+ * It used to read as the label OR the empty string, on the stated grounds that
+ * `''` is the drill layer's own spelling of "no group value" — but no producer
+ * of this function's `category` argument writes that spelling (the one
+ * production caller feeds it a chart click's category, and `computeDrillFilter`
+ * is downstream of the drill, not upstream of this lookup), while `''` IS what
+ * a genuine empty-string group paints. So the tolerance cost that group its own
+ * drill and gave it a null group's records instead — a WRONG click, not a dead
+ * one. `''` now means the empty-string group, which is what it says.
  *
  * **`xOf` covers BOTH arms, which is what let objectui#4497 bucket the pivot
  * branch without touching this function.** Worth stating because the reverse
@@ -140,7 +336,7 @@ export declare function relabelDimensions(rows: Array<Record<string, unknown>> |
  * 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, options?: ChartSeriesOptions): 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?: ChartDrillLookupOptions): number;
 /**
  * Build a per-category colour map from a select/lookup field's `options`.
  *
@@ -248,10 +444,54 @@ export declare function buildDimensionLabelMap(options: unknown, translate?: Opt
  * 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 target lives under `reference` — the ONLY spelling read here, and the same
+ * canonicalization as the dataset designer's `resolveReferenceTo`, which is
+ * narrowed to match in the same pass (objectui#6528). As of objectui#6648 the
+ * CARRIER matches too: a bare string and nothing else. The two helpers are one
+ * doctrine in two files and must never drift — a divergence recreates the
+ * defect one file over.
+ *
+ * The three legacy spellings this dropped (`reference_to` / `referenceTo` /
+ * `reference_to_object`) were censused against every producer, with `reference`
+ * itself as the positive control (445 of 565 lookup / master_detail defs in the
+ * framework tree; ACCEPTED by `ObjectSchema.safeParse` on spec 17.2.0, which
+ * REFUSES all three others BY NAME). No producer emits any of them onto an
+ * object metadata document: `reference_to` was then live only on ObjectUI's own
+ * view/field schema (a different contract, translated INTO from `reference`;
+ * objectui#11070 round 4 moved that contract to `reference` as well),
+ * `referenceTo`'s two producers were retired by objectui#6041, and
+ * `reference_to_object` occurs nowhere in either tree outside this chain and the
+ * test that called it.
+ *
+ * ⚠ Unlike `resolveReferenceTo`, this helper reads the `GET /meta/object/:name`
+ * document DIRECTLY — no `readFields` door strips retired keys on this path. So
+ * the narrowing is load-bearing rather than cosmetic: a stored pre-objectui#6041
+ * row spelling the target `referenceTo` now resolves to `undefined` here, the
+ * walk yields no entry, and the caller keeps the raw value (best-effort by
+ * construction — see {@link resolveDimensionFieldMeta}). That is the intended
+ * outcome: per AGENTS.md #0.1 such a row is a PRODUCER-side defect, and a
+ * lenient consumer here is exactly where it would have stayed hidden. Note
+ * `reference` was already HEAD of the old chain, so any doc carrying both is
+ * unaffected.
+ *
+ * The array and `{ object }` CARRIERS this used to accept were censused on the
+ * same standard and removed with the same reasoning (objectui#6648).
+ * `FieldSchema.reference` is a plain `z.string()`; `ObjectSchema.safeParse`
+ * (spec 17.2.0) ACCEPTS `reference: 'crm_account'` and REFUSES both
+ * `['crm_account']` and `{ object: 'crm_account' }` as `invalid_type`. A
+ * structure-walking, key-position-aware census of both trees found 587
+ * bare-string carriers at the field-def key position and ZERO array or
+ * `{ object }` carriers from any producer — the only ones in either tree were
+ * the green pins asserting this very tolerance. See `resolveReferenceTo` for
+ * the full census, including why a multi-target lookup is NOT what the array
+ * branch was serving: it returned `raw[0]` and discarded the rest, and
+ * polymorphic lookup remains an undeclared, open spec gap.
+ *
+ * This path matters MORE than the designer's for the same reason the spelling
+ * narrowing did: it reads the metadata document directly, with no `readFields`
+ * door in between, so a non-string carrier now degrades visibly (the walk
+ * yields no entry and the caller keeps the raw value) instead of being absorbed
+ * here.
  *
  * 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