@object-ui/core 17.6.0 → 18.0.0

package/dist/utils/dataset-format.d.ts

@@ -17,6 +17,7 @@
  */
 import type { AnalyticsResult } from '@objectstack/spec/contracts';
 import type { PercentScale } from '@objectstack/spec/data';
+import { type BuiltinAggregateLabels } from './chart-series.js';
 /**
  * Column metadata the analytics server returns alongside the rows — the spec's
  * `AnalyticsResult.fields[]` element BY REFERENCE, never a local restatement of
@@ -59,28 +60,35 @@ export type DatasetResultField = AnalyticsResult['fields'][number];
  */
 export type { PercentScale } from '@objectstack/spec/data';
 /**
- * Scale a stored `percent`-field value to its DISPLAY magnitude.
- *
- * Percent fields store a FRACTION (0–1) by convention — a stored `0.75` means
- * 75% (see the percent edit widget `PercentField`, which divides input by 100).
- * A value already in whole-percent form (magnitude ≥ 1, e.g. a `progress` /
- * `completion` field storing `57`) is passed through unchanged. This is the
- * SINGLE source of truth for percent display scaling, shared by the list-view
- * percent cell renderer (`formatPercent` in `@object-ui/fields`) and the dataset
- * measure formatter ({@link formatMeasure}) so a percent renders identically as
- * a row value and as an aggregated metric — the two surfaces can never drift.
- *
- * ⚠️ That last sentence was briefly FALSE, and objectui#4576 is what made it
- * true again. Sharing the SCALING was never enough on its own: between #4553
- * and #4576 the cell renderer got the locale's percent CONVENTION from `Intl`
- * while {@link formatMeasure} appended a literal '%', so a German session read
- * `1.234,5 %` in a list cell and `1.234,5%` in a dashboard measure — the same
- * number, scaled identically, rendered under two conventions. Both ends now go
- * through the locale's own percent affix. If a third surface ever needs percent
- * display, it takes BOTH halves from here — the scaling AND the convention —
- * or this promise breaks again in the same place.
+ * Scale a stored percentage to its DISPLAY magnitude (percentage points), at
+ * the storage the caller STATES.
+ *
+ * `percentScale` is the spec's `PercentScale`: `fraction` is a 0–1 ratio
+ * (`0.75` ⇒ 75, `1` ⇒ 100), `whole` is already in percentage points (`75` ⇒
+ * 75, `1` ⇒ 1). A caller holding a field definition reads it with the spec's
+ * `percentScaleOf` (`@objectstack/spec/data`): a `percent` field stores a
+ * fraction unless it declares a `max` above 1. A caller with no field (a
+ * computed ratio, a server measure column) states the storage it knows: a
+ * `derived: { op: 'ratio' }` measure is a fraction by definition, and the
+ * server annotates a measure column with its `percentScale`.
+ *
+ * ⛔ No storage is inferred from the VALUE any more (objectui#11475). This
+ * function used to be `value > -1 && value < 1 ? value * 100 : value`, a guess
+ * from the magnitude that read neither the field nor its `max`. A fraction-
+ * stored `1` (100%) therefore read `1%` in the list cell while the read-only
+ * form, which reads the declaration, read `100%`; a whole-stored `0.5` read
+ * `50%`. objectui#3136 was the same guess on a dashboard measure. The
+ * parameter is REQUIRED, so every caller says which storage it holds, and a
+ * value outside the union throws rather than falling to a branch silently.
+ *
+ * ⭐ The contract a third percent surface still owes is BOTH halves: this
+ * scaling, at the stored scale, AND the locale's percent convention
+ * (`style: 'percentPoints'`, see {@link formatMeasure} and `formatPercent` in
+ * `@object-ui/fields`). Between objectui#4553 and objectui#4576 the two ends
+ * shared the scaling and not the convention, so a German session read
+ * `1.234,5 %` in a list cell and `1.234,5%` in a dashboard measure.
  */
-export declare function percentDisplayValue(value: number): number;
+export declare function percentDisplayValue(value: number, percentScale: PercentScale): number;
 /**
  * Format a MEASURE value. Currency comes from the field's declared `currency`
  * (locale-correct symbol via `Intl`), NOT from a "$" baked into the format
@@ -118,8 +126,54 @@ export declare function percentDisplayValue(value: number): number;
  * is pure, so it moved DOWN into this package (`./number-display.ts`) and
  * `@object-ui/i18n` re-exports it. The duplicate implementation this file used
  * to carry is gone, and with it the drift that duplicate produced — see the
- * percent note in the body, and {@link percentDisplayValue}'s promise, which
- * is true again.
+ * percent note in the body, and the both-halves contract
+ * {@link percentDisplayValue}'s doc comment states.
+ *
+ * ── Date-valued measures (objectui#7178) ──
+ * `min` / `max` over a date or datetime field is a legitimate measure, and it
+ * used to render its stored value verbatim: the guard above returned
+ * `String(v)` for anything non-numeric BEFORE `format` was read, so a KPI tile
+ * showed `2026-07-04T07:00:00.000Z` in `text-2xl` and wrapped it over two
+ * lines. A date-shaped value now routes through {@link formatMeasureDate} to
+ * the display path list cells use; nothing about the numeric path moved.
+ *
+ * ⚠️ What `format` can and cannot say for those values, measured rather than
+ * assumed, and stated PER ARM — a date-shaped measure takes one of two arms in
+ * {@link formatMeasureDate}, and this paragraph used to describe only one of
+ * them while reading as though it described both. That cost a card: an
+ * objectui triage pass read the undifferentiated claim, concluded the defect
+ * was already fixed, and downgraded objectui#8352, which a driven browser run
+ * then refuted. The two arms agree TODAY, but only because #8352 made them; a
+ * universal sentence here is what hid the disagreement before, so it is not
+ * coming back even now that it would be true.
+ *
+ * The shared date path takes a named STYLE, not a date pattern. On BOTH arms
+ * the honoured vocabulary is `'short'` and `'relative'`:
+ *
+ *   - `Field.date` (`2026-09-08`) — honoured by threading `format` into
+ *     `formatDate`'s style parameter. The same words `DateCellRenderer`
+ *     honours from `field.format` for the same field.
+ *   - `Field.datetime` (`2026-09-01T00:00:00.000Z`) — honoured by SELECTING a
+ *     formatter, because `formatDateTime` has no style parameter to thread
+ *     into (objectui#8352). Before that card this arm honoured NOTHING: it
+ *     dropped `format` entirely, so `'relative'` rendered the absolute face.
+ *
+ * Every other string falls to that arm's default face — a PATTERN like
+ * `format: 'YYYY-MM-DD'` is accepted by the schema, reaches this function, and
+ * renders the locale default, and so does `'compact'`, which is
+ * `formatDateTime`'s own vocabulary but not this path's. The pattern part is
+ * not new behaviour introduced here: `plugin-dashboard`'s `recordFields`
+ * already routes a date-shaped `format` into the same style slot and gets the
+ * same locale default. Closing it would mean teaching the shared path a
+ * pattern grammar, which is a change to the path itself and to every list cell
+ * that reads it — not a measure concern, and not either card.
+ *
+ * ⚠️ `'relative'` renders the ABSOLUTE face for a value more than ±7 days from
+ * today, on both arms, by `formatRelativeDate`'s own design. That is correct
+ * output, not a regression — but it also means an out-of-window value is
+ * useless for testing this path, because it renders identically whether
+ * `format` is honoured or dropped. Both readings that missed #8352 were taken
+ * on 40–60-day-old data.
  */
 export declare function formatMeasure(v: unknown, format?: string, currency?: string, percentScale?: PercentScale, locale?: string): string;
 /**
@@ -140,13 +194,31 @@ export declare function formatDimensionValue(v: unknown, locale?: string): strin
  *
  * `fieldLabel` is injected (rather than imported) so this stays React/i18n-free;
  * callers pass `useSafeFieldLabel().fieldLabel`.
+ *
+ * ## `builtinAggregateLabels` (objectui#7534, sibling of #7258)
+ *
+ * A result field the analytics service minted as a BUILT-IN default measure
+ * carries `builtinAggregate` (objectstack#14492) and a hard-coded English
+ * `label` ('Count'). {@link resolveMeasureLabel} is the ONE resolver for that —
+ * #7258 wired it into `buildChartSeries()`, so a chart legend already read
+ * `计数` on a zh console while the table underneath it, the KPI caption, the
+ * pivot header and the dataset preview all still said `Count`, because they
+ * resolve their titles through here instead.
+ *
+ * Passing the caller's resolved labels closes that gap without a second
+ * resolution order: the discriminator is consulted FIRST (exactly as on the
+ * chart seam), the existing `fieldLabel` convention still applies on top, and
+ * the raw name is still the floor. Omitting the argument reproduces the
+ * previous output byte for byte — an author-declared measure carries no
+ * discriminator and keeps its wire `label` verbatim (objectui#4106), and a
+ * provider-less host resolves no labels and so changes nothing.
  */
-export declare function buildDatasetFieldHelpers(fields: DatasetResultField[] | undefined, object: string | undefined, fieldLabel?: (objectName: string, fieldName: string, fallback: string) => string): {
+export declare function buildDatasetFieldHelpers(fields: DatasetResultField[] | undefined, object: string | undefined, fieldLabel?: (objectName: string, fieldName: string, fallback: string) => string, builtinAggregateLabels?: BuiltinAggregateLabels): {
     measureField: (name: string) => DatasetResultField | undefined;
     headerLabel: (name: string) => string;
 };
 /**
- * A half-open date-range drill scope for one time-bucketed dimension (#1752):
+ * A half-open date-range drill scope for one time-bucketed dimension (objectstack-ai/objectstack#1752):
  * the object FIELD to filter and its inclusive `gte` / exclusive `lt` bounds
  * (the server's `drillRanges` sidecar entry).
  */
@@ -161,18 +233,127 @@ export interface DatasetDrillRange {
  * Each drillable dimension maps to its underlying object field, filtered by the
  * dimension's RAW grouped value (from the server's parallel `drillRawRows`, NOT
  * the visible row which carries the display LABEL — a select/lookup label would
- * mis-filter). An empty/undefined raw value normalizes to `null` (an explicit
- * "is empty" filter). The render-time `runtimeFilter` is ANDed in so the drilled
- * list stays within the same slice the aggregate was computed over.
+ * mis-filter). The render-time `runtimeFilter` is ANDed in so the drilled list
+ * stays within the same slice the aggregate was computed over.
+ *
+ * ## What the EMPTY bucket means, and why it is spelled `{ $null: true }`
  *
- * A time-bucketed date dimension (#1752) drills by RANGE, not equality — a
+ * A drill must return exactly the rows the clicked bucket COUNTED. The empty
+ * bucket is the one the aggregate grouped rows with NO VALUE for that dimension
+ * into, so the drill means "this dimension has no value" — NOT "this dimension
+ * holds the literal value null". Those are different row sets, and the
+ * difference is measurable rather than theoretical: against `ValueDataSource`'s
+ * matcher over rows `{owner:'alice'}` / `{owner:null}` / `{}` (no `owner` key),
+ * `['owner','is_null',true]` selects the explicit-null row AND the missing-key
+ * row, while an equality test against `null` selects only the explicit-null one
+ * and drops the row that has no `owner` at all. The bucket counted both, so
+ * is-null is the one that agrees with the number the user clicked.
+ *
+ * ⇒ every empty authoring — `''`, `null` and `undefined` alike — becomes ONE
+ * spelling, `{ [field]: { $null: true } }`, which `convertFiltersToAST` lowers
+ * to `[field, 'is_null', true]`. The three are not told apart because the
+ * server already merged them into the single bucket the user clicked; there is
+ * no second bucket here for a second spelling to address.
+ *
+ * ⚠️ This value used to be a bare `null`, and that is the defect objectui#9085
+ * records: `convertFiltersToAST`'s OLDEST pinned behaviour is to SKIP a key
+ * whose value is `null` / `undefined` (pinned as "should skip null and
+ * undefined values"), so the constraint was dropped on the way to the wire and
+ * the empty-bucket drill answered with a SUPERSET — every row, silently. The
+ * repair is here at the PRODUCER and ⛔ not at that converter: the skip is
+ * relied on by other producers, and changing it would move every caller's
+ * meaning at once (objectui#9020 ruled it stays). `$null` is not a new
+ * vocabulary either — it is a declared spec operator this dialect already
+ * lowers, and the one spelling that says the same thing on BOTH of
+ * `ValueDataSource`'s routes, where a bare `null` said "only an explicit null"
+ * on the plain-object route and "no constraint at all" on the AST route.
+ *
+ * ⚠️ Known BOUNDARY, unchanged by this and deliberately not widened: the drill
+ * "escape hatch" (the host's `openRecordList`, which serializes a drill filter
+ * into `filter[...]` URL params) has NO spelling for is-null — its operator
+ * vocabulary is equality plus four range bounds — so it drops this condition
+ * exactly as it already dropped the bare `null`, byte-for-byte the same query
+ * string. That surface is a superset today and stays one; closing it needs a
+ * URL-dialect operator on both the write and the read side, which is its own
+ * card.
+ *
+ * A time-bucketed date dimension (objectstack-ai/objectstack#1752) drills by RANGE, not equality — a
  * humanized bucket ("2026-Q2") can't be exact-matched, so the server sends a
  * half-open `[gte, lt)` per date dim in `rawRanges` instead of a raw value.
  * Each becomes an ObjectQL range operator object (`{ $gte, $lt }`) so the drill
  * scopes the list to the clicked time bucket instead of every bucket (which the
  * old date-dim skip degraded to — a superset).
  *
+ * ## The widget filter is CONJOINED, not spread (objectui#9137)
+ *
+ * ⛔ `runtimeFilter` is composed through {@link composeDrillFilter}, never by
+ * spreading it into the object literal below. Spreading is correct only for the
+ * OBJECT arm; this parameter's declared producer sends the ARRAY arm. The
+ * dashboard's `DashboardWidgetSchema.filter` docblock states it outright —
+ * "objectui passes an ObjectQL FilterNode array here, not the spec's
+ * `FilterCondition` envelope" — and `DatasetWidget`'s guard admits it
+ * (`typeof [] === 'object'` and `Object.keys(['x']).length === 1` are both
+ * true), so the array arm reached this line unfiltered. Spreading an ARRAY
+ * yields INDEX keys: `[['region','=','emea']]` became
+ * `{ '0': ['region','=','emea'] }`, which is not a condition anyone can honour.
+ *
+ * ⚠️ MEASURED, and it is NOT the silent superset the sibling sites had. An
+ * index key is not dropped on the way to the wire — every sink in circulation
+ * refuses it LOUDLY, because a bare array is not a legal equality comparand
+ * (objectui#8530 / objectui#8514): `convertFiltersToAST` THROWS
+ * `FilterOperatorError`, `driver-sql` answers `400 INVALID_FILTER`, and
+ * `ValueDataSource`'s matcher selects NOTHING. Against rows scoped
+ * `region = 'emea'`, drilling the `stage = 'won'` bucket returned `(none)`
+ * where the widget alone returned three rows and the conjunction returns the
+ * right two. So the widget's conditions were not merely lost — the drill was
+ * dead in the array arm. The failure is fail-CLOSED here, and this is the third
+ * site of the class objectui#8944 (chart) and objectui#9024 (pivot) removed.
+ *
+ * Three properties of THIS site, each confirmed rather than assumed — it is not
+ * a copy-paste of the other two:
+ *
+ * 1. The return stays a NON-optional `Record<string, unknown>`, because callers
+ *    do not expect `undefined`. `composeDrillFilter` answers `undefined` when
+ *    both sources are empty, so that one case is spelled `?? {}` — the same
+ *    empty object this function already returned for a bucket with no dims.
+ * 2. Range operators SURVIVE. A time-bucketed dim contributes
+ *    `{ $gte, $lt }`, and the composition re-spells it as two `$and` children
+ *    on the same field (`[{d:{$gte}},{d:{$lt}}]`) rather than losing a bound;
+ *    the selected rows are identical, and `serializeDrillFilterParams` walks
+ *    `$and` (objectui#8944) so both bounds still reach `filter[d][gte|lt]`.
+ * 3. `runtimeFilter` is declared `unknown`, which is what the two consumers
+ *    actually hand it — `any` from the dashboard, `Record<string, unknown>`
+ *    from `DatasetReportRenderer`. Widening the PARAMETER is what admits both
+ *    without a cast; ⛔ neither consumer's own type is changed by this.
+ *
+ * ⚠️ Conjunction changes one behaviour deliberately: a field named by BOTH the
+ * widget filter and the clicked bucket used to be overwritten by the bucket,
+ * and now both conditions apply. That is the point — a drill may narrow the
+ * widget's scope and may never widen it — and it is the posture the chart and
+ * pivot sites already ship.
+ *
+ * ## ⭐ Only the COMPOSING leg moves; the identity leg is left byte-identical
+ *
+ * The sink is asked only when there IS a second source. That is this site's
+ * one departure from `ObjectChart` / `ObjectPivotTable`, which call it
+ * unconditionally, and it is deliberate rather than a shortcut: the spread
+ * this replaces only ever ran when `runtimeFilter` was present, so the
+ * no-widget-filter path carries no defect to repair.
+ *
+ * ⚠️ Routing it anyway was MEASURED and rejected. `composeDrillFilter`'s own
+ * note — "a lone surviving source lowers back to exactly the flat object the
+ * spread produced" — holds only for a source of ONE condition; with two it
+ * lowers to `$and`, because `convertFiltersToAST` emits one node per condition
+ * and `parseFilterAST` cannot fold two nodes back onto one key. A `{ $gte,
+ * $lt }` range is two conditions on its own, so even a single date bucket
+ * re-spells. Sending the identity leg through the sink therefore re-shaped
+ * every multi-condition dataset drill — including the controls objectui#9085,
+ * objectui#4056, objectstack#5473 and objectstack-ai/objectstack#1752 pin on paths this card does not
+ * touch — for ZERO change in the rows selected or the `filter[...]` params
+ * emitted. ⛔ Do not "simplify" this to an unconditional call without redoing
+ * that measurement.
+ *
  * Shared by the dashboard `DatasetWidget` and the report renderer so a drill
  * filters identically (and correctly, including lookups) on both surfaces.
  */
-export declare function buildDatasetDrillFilter(rawRow: Record<string, unknown> | undefined, drillDims: string[], dimensionFields: Record<string, string>, runtimeFilter?: Record<string, unknown>, rawRanges?: Record<string, DatasetDrillRange>): Record<string, unknown>;
+export declare function buildDatasetDrillFilter(rawRow: Record<string, unknown> | undefined, drillDims: string[], dimensionFields: Record<string, string>, runtimeFilter?: unknown, rawRanges?: Record<string, DatasetDrillRange>): Record<string, unknown>;