@object-ui/core 17.2.0 → 17.5.0

package/dist/utils/filter-converter.d.ts

@@ -5,12 +5,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/**
- * Filter Converter Utilities
- *
- * Shared utilities for converting MongoDB-like filter operators
- * to ObjectStack FilterNode AST format.
- */
 /**
  * FilterNode AST type definition
  * Represents a filter condition or a logical combination of conditions
@@ -83,6 +77,36 @@ export declare function convertFiltersToAST(filter: Record<string, any>): Filter
  * `table.defaultFilters` (declared `Record<string, any>`) was DROPPED and the
  * view returned every record. Silently: no error, just a wider answer.
  *
+ * The FIRST never worked at all (objectui#3431). The array branch returned
+ * every array VERBATIM, so a saved view's `ViewFilterRule[]` travelled to
+ * `$filter` as bare rule objects — which the server refuses: `isFilterAST` is
+ * false for an array of objects, and the wire face answers `400
+ * INVALID_FILTER`. Verified against a real backend on the showcase's SHIPPED
+ * `showcase_task.in_progress` view (`filter: [{field:'status',
+ * operator:'equals', value:'in_progress'}]`): 400 as sent, 200 with its 2 rows
+ * once lowered to `[['status','equals','in_progress']]`. Every saved view
+ * carrying a filter was a failed list. `mergeFilterNodes` below has warned
+ * about exactly this hazard since it was written — the warning was accurate,
+ * and the sink it warns for never implemented the lowering it describes.
+ *
+ * **Why the fold lives HERE and not at the producer.** `ListViewSchema.filter`
+ * / `ViewTab.filter` are spec-declared `z.array(ViewFilterRuleSchema)`, and a
+ * view hands a renderer a `ListViewSchema` — so folding one hop earlier (in
+ * `app-shell`'s ObjectView, say) would write ObjectQL AST triples INTO a
+ * spec-declared rule-array slot: an off-spec value in a spec field, AGENTS.md
+ * #0.1 inverted. This function is the last hop before the wire, where the value
+ * legitimately leaves the spec's view vocabulary and becomes an ObjectQL AST.
+ * It is also the single sink both producers already share — `plugin-list`'s
+ * `buildEffectiveFilter` (which feeds the grid AND the export) and
+ * `plugin-view`'s ObjectView (calendar / kanban / gallery / timeline). One
+ * lowering, one place; the same reason the MongoDB-style shape is lowered here
+ * rather than at each of its callers.
+ *
+ * Mixed arrays fold ELEMENT-WISE, because that is what reaches this function in
+ * practice: `ObjectView` concatenates a saved view's rules with the
+ * `?filter[<field>]=<value>` URL triples into one array. Triples pass through
+ * untouched.
+ *
  * Returns `undefined` for an absent or empty source, so callers can skip
  * `$filter` rather than sending an empty array.
  */
@@ -92,11 +116,15 @@ export declare function toFilterNode(source: unknown): FilterNode | Record<strin
  *
  * Wrapping rather than spreading, on purpose. `['and', ...rules]` looks
  * equivalent and is not: spreading a `ViewFilterRule[]` puts bare rule OBJECTS
- * where the AST expects nodes, and the server neither understands nor rejects
- * that cleanly — `isFilterAST` says no (a 400 since objectstack#4121), while
- * `parseFilterAST` reads the rule as a Mongo condition and filters on columns
- * literally named `field` / `operator` / `value`. Spreading is only correct
- * when the source happens to be an array of nodes, which is why it survived.
+ * where the AST expects nodes, and the server does not accept that —
+ * `isFilterAST` says no and the wire face answers `400 INVALID_FILTER`
+ * (objectstack#4121). Spreading is only correct when the source happens to be
+ * an array of nodes, which is why it survived.
+ *
+ * Since objectui#3431 the rule objects never reach that position anyway:
+ * `toFilterNode` lowers a `ViewFilterRule[]` to AST nodes on the way in. The
+ * paragraph above is kept because it is why each source stays its own child —
+ * and because it correctly diagnosed the bug the sink itself was carrying.
  *
  * Sources that normalize to nothing are skipped; one surviving source is
  * returned as-is rather than wrapped in a pointless `and`.

package/dist/utils/filter-converter.js

@@ -5,6 +5,13 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * Filter Converter Utilities
+ *
+ * Shared utilities for converting MongoDB-like filter operators
+ * to ObjectStack FilterNode AST format.
+ */
+import { normalizeFilterOperator } from '@objectstack/spec/ui';
 /**
  * Map MongoDB-like operators to ObjectStack filter operators.
  *
@@ -152,6 +159,37 @@ export function convertFiltersToAST(filter) {
     // Multiple conditions: combine with 'and'
     return ['and', ...conditions];
 }
+function isViewFilterRule(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const field = value.field;
+    return typeof field === 'string' && field !== '';
+}
+/**
+ * Lower ONE spec `ViewFilterRule` to an ObjectQL AST comparison node.
+ *
+ * The operator goes through the spec's OWN {@link normalizeFilterOperator} —
+ * the exact exit the WRITE side uses (`app-shell/views/viewFilterFold.ts`), so
+ * the two directions cannot drift into two dialects. No second canonical map is
+ * introduced, and none is needed: all 19 `VIEW_FILTER_OPERATORS` are already
+ * members of the wire's `VALID_AST_OPERATORS`, so the lowering is purely
+ * structural. An operator the spec does not know is passed through VERBATIM, so
+ * `isFilterAST` still refuses it and the server still answers `400
+ * INVALID_FILTER` — a misspelling must not be coerced into a valid one.
+ *
+ * `value` is emitted only when the rule carries one. A rule that omits it
+ * (`is_empty` / `is_null`, whose direction comes from the operator NAME) would
+ * otherwise gain an invented `null` the author never wrote — `JSON.stringify`
+ * turns a hole in an array into `null`, and `['x', 'equals', null]` is a real
+ * `{x: null}` predicate, i.e. a silently-wrong filter. Same rule the write side
+ * applies (`if (c.value !== undefined)`).
+ */
+function viewFilterRuleToNode(rule) {
+    const operator = normalizeFilterOperator(rule.operator);
+    return (rule.value === undefined
+        ? [rule.field, operator]
+        : [rule.field, operator, rule.value]);
+}
 /**
  * Normalize ONE filter source into a single filter node.
  *
@@ -167,14 +205,52 @@ export function convertFiltersToAST(filter) {
  * `table.defaultFilters` (declared `Record<string, any>`) was DROPPED and the
  * view returned every record. Silently: no error, just a wider answer.
  *
+ * The FIRST never worked at all (objectui#3431). The array branch returned
+ * every array VERBATIM, so a saved view's `ViewFilterRule[]` travelled to
+ * `$filter` as bare rule objects — which the server refuses: `isFilterAST` is
+ * false for an array of objects, and the wire face answers `400
+ * INVALID_FILTER`. Verified against a real backend on the showcase's SHIPPED
+ * `showcase_task.in_progress` view (`filter: [{field:'status',
+ * operator:'equals', value:'in_progress'}]`): 400 as sent, 200 with its 2 rows
+ * once lowered to `[['status','equals','in_progress']]`. Every saved view
+ * carrying a filter was a failed list. `mergeFilterNodes` below has warned
+ * about exactly this hazard since it was written — the warning was accurate,
+ * and the sink it warns for never implemented the lowering it describes.
+ *
+ * **Why the fold lives HERE and not at the producer.** `ListViewSchema.filter`
+ * / `ViewTab.filter` are spec-declared `z.array(ViewFilterRuleSchema)`, and a
+ * view hands a renderer a `ListViewSchema` — so folding one hop earlier (in
+ * `app-shell`'s ObjectView, say) would write ObjectQL AST triples INTO a
+ * spec-declared rule-array slot: an off-spec value in a spec field, AGENTS.md
+ * #0.1 inverted. This function is the last hop before the wire, where the value
+ * legitimately leaves the spec's view vocabulary and becomes an ObjectQL AST.
+ * It is also the single sink both producers already share — `plugin-list`'s
+ * `buildEffectiveFilter` (which feeds the grid AND the export) and
+ * `plugin-view`'s ObjectView (calendar / kanban / gallery / timeline). One
+ * lowering, one place; the same reason the MongoDB-style shape is lowered here
+ * rather than at each of its callers.
+ *
+ * Mixed arrays fold ELEMENT-WISE, because that is what reaches this function in
+ * practice: `ObjectView` concatenates a saved view's rules with the
+ * `?filter[<field>]=<value>` URL triples into one array. Triples pass through
+ * untouched.
+ *
  * Returns `undefined` for an absent or empty source, so callers can skip
  * `$filter` rather than sending an empty array.
  */
 export function toFilterNode(source) {
     if (source === null || source === undefined)
         return undefined;
-    if (Array.isArray(source))
-        return source.length > 0 ? source : undefined;
+    if (Array.isArray(source)) {
+        if (source.length === 0)
+            return undefined;
+        // Spec `ViewFilterRule[]` (possibly mixed with AST nodes) → AST nodes. Left
+        // untouched when the array holds no rule objects, which is the common case:
+        // user-filter conditions and URL triples are already nodes.
+        return (source.some(isViewFilterRule)
+            ? source.map((el) => (isViewFilterRule(el) ? viewFilterRuleToNode(el) : el))
+            : source);
+    }
     if (typeof source !== 'object')
         return undefined;
     const obj = source;
@@ -188,11 +264,15 @@ export function toFilterNode(source) {
  *
  * Wrapping rather than spreading, on purpose. `['and', ...rules]` looks
  * equivalent and is not: spreading a `ViewFilterRule[]` puts bare rule OBJECTS
- * where the AST expects nodes, and the server neither understands nor rejects
- * that cleanly — `isFilterAST` says no (a 400 since objectstack#4121), while
- * `parseFilterAST` reads the rule as a Mongo condition and filters on columns
- * literally named `field` / `operator` / `value`. Spreading is only correct
- * when the source happens to be an array of nodes, which is why it survived.
+ * where the AST expects nodes, and the server does not accept that —
+ * `isFilterAST` says no and the wire face answers `400 INVALID_FILTER`
+ * (objectstack#4121). Spreading is only correct when the source happens to be
+ * an array of nodes, which is why it survived.
+ *
+ * Since objectui#3431 the rule objects never reach that position anyway:
+ * `toFilterNode` lowers a `ViewFilterRule[]` to AST nodes on the way in. The
+ * paragraph above is kept because it is why each source stays its own child —
+ * and because it correctly diagnosed the bug the sink itself was carrying.
  *
  * Sources that normalize to nothing are skipped; one surviving source is
  * returned as-is rather than wrapped in a pointless `and`.

package/dist/utils/normalize-list-view.d.ts

@@ -35,13 +35,33 @@ export declare const DENSITY_MODE_TO_ROW_HEIGHT: Record<DensityMode, RowHeight>;
  */
 export declare const ROW_HEIGHT_TO_DENSITY_MODE: Record<RowHeight, DensityMode>;
 /**
- * Tolerant reader for {@link ROW_HEIGHT_TO_DENSITY_MODE}. View metadata is
- * user-authored, so `rowHeight` is not guaranteed to be one of the five spec
- * values — an unknown one lands on `comfortable` rather than rendering an
- * undefined density. Keeping the fallback here means every surface collapses
- * the same way.
+ * Runtime reader for {@link ROW_HEIGHT_TO_DENSITY_MODE}: the spec's five row
+ * heights narrowed onto the renderer's three densities, and **nothing else**.
+ *
+ * The parameter stays `unknown` because this is the boundary user-authored view
+ * metadata actually crosses — `ListViewSchema.rowHeight` is statically a
+ * `RowHeight`, but the value arrives from stored view definitions TypeScript
+ * never saw (`ObjectView`: `viewDef.rowHeight ?? listSchema.rowHeight`). The
+ * type-level half of the guarantee is the `Record<RowHeight, …>` on the table
+ * above, which fails the build when the spec grows a row height.
+ *
+ * An off-spec value gets NO density (objectui#4440). It used to be coerced to
+ * `comfortable`, which is the opposite of what `@object-ui/react`'s spec bridge
+ * answers for the same string after objectui#4352 — one metadata-driven system
+ * holding two answers for one input. AGENTS.md #0.1 decides which one survives:
+ * a renderer-side rehabilitation of off-spec metadata is a second de-facto
+ * contract, and one strict contract beats N. The producer is where a bad
+ * `rowHeight` gets fixed.
+ *
+ * Callers apply their own "nothing was said" default to `undefined`, so an
+ * off-spec row height now renders exactly like an absent one — `'compact'` in
+ * both `ListView` and `ObjectGrid`.
+ *
+ * `hasOwnProperty`, not `in`: `in` walks the prototype chain, so `'toString'`
+ * used to come back as `Object.prototype.toString` — a FUNCTION returned from
+ * something typed `DensityMode`.
  */
-export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode;
+export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode | undefined;
 /**
  * ObjectUI's `list-view` node historically used a different vocabulary from
  * `@objectstack/spec` for the same concepts (`fields` where the spec says

package/dist/utils/normalize-list-view.js

@@ -32,17 +32,39 @@ export const ROW_HEIGHT_TO_DENSITY_MODE = {
     extra_tall: 'spacious',
 };
 /**
- * Tolerant reader for {@link ROW_HEIGHT_TO_DENSITY_MODE}. View metadata is
- * user-authored, so `rowHeight` is not guaranteed to be one of the five spec
- * values — an unknown one lands on `comfortable` rather than rendering an
- * undefined density. Keeping the fallback here means every surface collapses
- * the same way.
+ * Runtime reader for {@link ROW_HEIGHT_TO_DENSITY_MODE}: the spec's five row
+ * heights narrowed onto the renderer's three densities, and **nothing else**.
+ *
+ * The parameter stays `unknown` because this is the boundary user-authored view
+ * metadata actually crosses — `ListViewSchema.rowHeight` is statically a
+ * `RowHeight`, but the value arrives from stored view definitions TypeScript
+ * never saw (`ObjectView`: `viewDef.rowHeight ?? listSchema.rowHeight`). The
+ * type-level half of the guarantee is the `Record<RowHeight, …>` on the table
+ * above, which fails the build when the spec grows a row height.
+ *
+ * An off-spec value gets NO density (objectui#4440). It used to be coerced to
+ * `comfortable`, which is the opposite of what `@object-ui/react`'s spec bridge
+ * answers for the same string after objectui#4352 — one metadata-driven system
+ * holding two answers for one input. AGENTS.md #0.1 decides which one survives:
+ * a renderer-side rehabilitation of off-spec metadata is a second de-facto
+ * contract, and one strict contract beats N. The producer is where a bad
+ * `rowHeight` gets fixed.
+ *
+ * Callers apply their own "nothing was said" default to `undefined`, so an
+ * off-spec row height now renders exactly like an absent one — `'compact'` in
+ * both `ListView` and `ObjectGrid`.
+ *
+ * `hasOwnProperty`, not `in`: `in` walks the prototype chain, so `'toString'`
+ * used to come back as `Object.prototype.toString` — a FUNCTION returned from
+ * something typed `DensityMode`.
  */
 export function rowHeightToDensityMode(rowHeight) {
-    if (typeof rowHeight === 'string' && rowHeight in ROW_HEIGHT_TO_DENSITY_MODE) {
-        return ROW_HEIGHT_TO_DENSITY_MODE[rowHeight];
+    if (typeof rowHeight !== 'string')
+        return undefined;
+    if (!Object.prototype.hasOwnProperty.call(ROW_HEIGHT_TO_DENSITY_MODE, rowHeight)) {
+        return undefined;
     }
-    return 'comfortable';
+    return ROW_HEIGHT_TO_DENSITY_MODE[rowHeight];
 }
 const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 /**

package/dist/utils/number-display.d.ts

@@ -0,0 +1,151 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * `formatDisplayNumber` — the ONE number-display formatter behind every field
+ * cell, field widget, metric renderer and dataset measure in the console.
+ *
+ * It exists because the same `new Intl.NumberFormat('en-US', …)` construction
+ * had been copied into the number cell renderer, the currency cell renderer,
+ * the currency widget, the compact `formatNumber` helper and the dashboard
+ * metric widget. Two defects therefore had five homes each, and fixing "the"
+ * renderer never changed the answer (objectui#4033, source thread
+ * objectstack#5067):
+ *
+ *  1. the locale was hardcoded to `en-US`, so a `zh-CN` / `de-DE` console still
+ *     grouped and pointed decimals the US way; and
+ *  2. `useGrouping` was never set, so a four-digit YEAR stored as
+ *     `Field.number({ scale: 0 })` rendered as `2,026` — in every locale, with
+ *     no field property able to turn it off.
+ *
+ * Both policies now live here and nowhere else. Call sites bring the value and
+ * the display width; they do not bring a locale default and they do not decide
+ * grouping.
+ *
+ * ── Why this module lives in `@object-ui/core` (objectui#4576) ──
+ * It used to live in `@object-ui/i18n`, and that home cost the repo a real
+ * defect. `@object-ui/core`'s `utils/dataset-format.ts` could not import it —
+ * `core` is the React-free engine (AGENTS.md §3: "No UI-lib deps. Logic only.")
+ * and is a runtime dependency of React-FREE consumers (the `object-ui` VS Code
+ * extension, `@object-ui/data-objectstack`), while `i18n` depends on
+ * `i18next`/`react-i18next` and peer-depends on React. So `formatMeasure` kept
+ * a parallel `Intl` implementation, the two drifted, and a German session read
+ * `1.234,5 %` from a list cell beside `1.234,5%` from a dashboard measure
+ * (objectui#4576). #4577 measured the option mapping LOSSLESS across 32,760
+ * combinations and recorded the duplication at both ends rather than routing
+ * through a boundary it could not cross.
+ *
+ * The function is pure — no React, no i18next, no DOM — so the boundary was
+ * never a property of the CODE, only of where the code sat. Moving it DOWN to
+ * the lower layer removes the obstacle instead of working around it:
+ * `@object-ui/i18n` now RE-EXPORTS these three names, so every existing import
+ * path keeps compiling and `import { formatDisplayNumber } from '@object-ui/i18n'`
+ * and `from '@object-ui/core'` are the SAME symbol (pinned in
+ * `packages/i18n/src/__tests__/number-display.reexport-identity.test.ts`).
+ * `core` imports `i18n` nowhere, so the new edge introduces no cycle.
+ */
+export interface DisplayNumberFormatOptions {
+    /**
+     * BCP-47 tag for the ACTIVE display locale — in React, whatever
+     * `useDisplayLocale()` returns.
+     *
+     * `undefined` means "follow the runtime default", which is the honest answer
+     * for a non-React caller that has no locale in hand. It never means `en-US`:
+     * assuming US conventions for the whole world is the defect this module was
+     * created to remove.
+     */
+    locale?: string;
+    /**
+     * ISO 4217 code. When present the value is formatted as money — which also
+     * means grouping is kept, because a grouped amount is what every currency
+     * convention expects and an ordinal amount of money is not a thing.
+     *
+     * Money wins over {@link DisplayNumberFormatOptions.style}: a call that sets
+     * both gets a currency rendering. Nothing in the repo does that, and the
+     * combination has no meaning to express.
+     */
+    currency?: string;
+    /**
+     * The FIELD's declared `scale` — the `s` of a `decimal(p, s)` column — and
+     * nothing else. This is a POLICY input, not a display width: pass it only
+     * when a field declaration actually said so.
+     *
+     * `scale: 0` with no currency declares a discrete integer (a year, a fiscal
+     * period, an ordinal), and those are not grouped. Leave `scale` undefined and
+     * grouping is kept — which is correct for the two cases that look similar but
+     * are not:
+     *
+     *   - an UNDECLARED scale (`scale` is optional in the spec, so absent means
+     *     "decimals unknown", not "integer"); and
+     *   - a caller whose zero-decimal display comes from something other than a
+     *     field declaration — e.g. the dashboard `MetricWidget`, whose decimals
+     *     come from a numeral.js format pattern and whose large KPI aggregates
+     *     are *documented* to want separators ("`1,930,000` not `1930000`").
+     *
+     * ⚠️ INTERIM DEFAULT (objectui#4033, PM ruling 2026-08-11). Suppressing
+     * grouping for every scale-0 number is a transitional policy with a known,
+     * accepted cost: a large scale-0 COUNT loses its separators too. It is the
+     * better trade only until the spec gains an authorable presentation hint
+     * (`useGrouping` / `displayFormat` — being specified separately, contract-first,
+     * in the objectstack repo). When that hint lands it OVERRIDES this default,
+     * and this heuristic should be reduced to the fallback for fields that
+     * declare nothing.
+     */
+    scale?: number;
+    /**
+     * How the number relates to a percentage — the ONE place that distinction is
+     * expressed, because getting it wrong is the whole of objectui#4576.
+     *
+     *  - `'decimal'` (default) — a plain number, no percent sign.
+     *  - `'percent'` — the value is a FRACTION. `Intl` multiplies it by 100 and
+     *    appends the locale's percent convention, so `0.8` renders as `80%`.
+     *  - `'percentPoints'` — the value is ALREADY in percentage points, so `80`
+     *    renders as `80%`. Same locale convention, NO re-scaling.
+     *
+     * The third one exists because "divide by 100 so `Intl` can multiply it back"
+     * is not free, and the round trip is lossy at rounding TIES: measured on this
+     * repo's runner, `80.175` percentage points formatted to 2 decimals renders
+     * `80.18%` when formatted directly and `80.17%` after the divide-and-remultiply
+     * — 27,581 of 1,200,013 ordinary-magnitude en-US forms move, plus every
+     * value at the top of the double range (`MAX_SAFE_INTEGER`, `1e23`). A caller
+     * holding percentage points must therefore NOT reach for `'percent'`; that is
+     * exactly the trap this option removes.
+     *
+     * `'percentPoints'` is implemented with `Intl`'s `style: 'unit'` /
+     * `unit: 'percent'`, which was measured to produce a BYTE-IDENTICAL percent
+     * affix to `style: 'percent'` across all 171 locale tags tested — including
+     * the German/French/Russian no-break space before the sign, Turkish's PREFIX
+     * position (`%1.234,5`), Arabic's own percent sign plus U+061C, and the
+     * Bengali/Marathi percent patterns that group Western-style where their
+     * decimal patterns group by lakh. It is the same CONVENTION by a route that
+     * does not touch the value.
+     */
+    style?: 'decimal' | 'percent' | 'percentPoints';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    notation?: 'standard' | 'compact';
+}
+/**
+ * The grouping policy, alone and testable: does this number get thousands
+ * separators?
+ *
+ * @param scale    the field's declared `scale`, or `undefined` when the caller
+ *                 has no field declaration behind it
+ * @param currency ISO 4217 code when the number is money
+ */
+export declare function shouldGroupDisplayNumber(scale?: number, currency?: string): boolean;
+/**
+ * Format a number for DISPLAY, in the active locale, under the grouping policy
+ * above.
+ *
+ * Throws for a bad `currency` code exactly as `Intl.NumberFormat` does, so the
+ * fallbacks call sites already had (`${currency} ${value.toFixed(n)}`) keep
+ * working unchanged. A bad LOCALE is handled here instead of throwing: `locale`
+ * arrives from a server response (ADR-0053 `localization.locale`), and a
+ * malformed tag from a tenant config must never take a grid cell down.
+ */
+export declare function formatDisplayNumber(value: number, options?: DisplayNumberFormatOptions): string;

package/dist/utils/number-display.js

@@ -0,0 +1,71 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The grouping policy, alone and testable: does this number get thousands
+ * separators?
+ *
+ * @param scale    the field's declared `scale`, or `undefined` when the caller
+ *                 has no field declaration behind it
+ * @param currency ISO 4217 code when the number is money
+ */
+export function shouldGroupDisplayNumber(scale, currency) {
+    // Money always groups — including money whose currency code could not be
+    // resolved, which still renders as an amount (just without a symbol).
+    if (currency)
+        return true;
+    // Only an explicitly declared scale of 0 is an ordinal. `undefined !== 0`.
+    return scale !== 0;
+}
+/**
+ * Format a number for DISPLAY, in the active locale, under the grouping policy
+ * above.
+ *
+ * Throws for a bad `currency` code exactly as `Intl.NumberFormat` does, so the
+ * fallbacks call sites already had (`${currency} ${value.toFixed(n)}`) keep
+ * working unchanged. A bad LOCALE is handled here instead of throwing: `locale`
+ * arrives from a server response (ADR-0053 `localization.locale`), and a
+ * malformed tag from a tenant config must never take a grid cell down.
+ */
+export function formatDisplayNumber(value, options = {}) {
+    const { locale, currency, scale, style, ...passthrough } = options;
+    const intlOptions = { ...passthrough };
+    if (style === 'percentPoints') {
+        // The locale's percent convention WITHOUT `style: 'percent'`'s ×100 — see
+        // the option's doc above for the measurement that separates the two.
+        intlOptions.style = 'unit';
+        intlOptions.unit = 'percent';
+        intlOptions.unitDisplay = 'narrow';
+    }
+    else if (style) {
+        intlOptions.style = style;
+    }
+    if (currency) {
+        intlOptions.style = 'currency';
+        intlOptions.currency = currency;
+        delete intlOptions.unit;
+        delete intlOptions.unitDisplay;
+    }
+    // ⚠️ Set `useGrouping` ONLY to suppress. `useGrouping: true` is NOT the same
+    // as omitting the key: `true` means "always", while omitting it means "auto"
+    // (and "min2" under compact notation), which is the locale's own preference.
+    // Measured — for 1234: es-ES "auto" → `1234` but "always" → `1.234`; pl-PL
+    // "auto" → `1234` but "always" → `1 234`. Writing `true` here would silently
+    // override those locales' conventions in the name of preserving en-US output.
+    if (!shouldGroupDisplayNumber(scale, currency)) {
+        intlOptions.useGrouping = false;
+    }
+    try {
+        return new Intl.NumberFormat(locale, intlOptions).format(value);
+    }
+    catch {
+        // Retry WITHOUT the locale, keeping every other option: this rescues a
+        // malformed tag while still surfacing a genuinely bad `currency` to the
+        // caller's own catch.
+        return new Intl.NumberFormat(undefined, intlOptions).format(value);
+    }
+}

package/dist/utils/predicate-fields.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ObjectUI — predicate field harvesting
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Which record fields a view's PREDICATES read — the half of a view's field
+ * appetite that is not its columns.
+ *
+ * A list view projects what it DISPLAYS: `$select` is built from the column
+ * list (plus `id` and the expanded relation roots). That is correct for
+ * rendering and wrong for gating, because a `visible` / `disabled` /
+ * conditional-formatting predicate reads fields nobody put on screen — gating a
+ * row action on `record.owner` while showing Title / Status is the ordinary
+ * case, not an exotic one.
+ *
+ * The field then simply is not in the payload, and CEL does not treat an absent
+ * key as null: `record.owner == os.user.id` FAULTS with `No such key: owner`.
+ * Fault handling differs per surface and both answers are wrong — fail-CLOSED
+ * on the row kebab and the selection bar (the button silently disappears for
+ * everyone), fail-OPEN on the lenient paths (it appears for everyone). Nothing
+ * in either outcome points at a projection.
+ *
+ * Harvesting the names a predicate mentions and adding them to `$select` is
+ * what closes that. Note what it deliberately does NOT add: `$expand`. A
+ * predicate wants the stored foreign key, which is exactly what an unexpanded
+ * relation column already is — so a predicate-only relation field costs one
+ * more column and no extra round trip. (A relation that IS displayed still gets
+ * expanded for its label, and `toPredicateRecord` collapses it back for the
+ * predicate.)
+ */
+/**
+ * The columns the framework provisions on EVERY business object
+ * (`applySystemFields`) but does not publish in the object's `fields` metadata.
+ *
+ * They matter here because the most ordinary ownership predicate there is —
+ * `record.owner_id == os.user.id` — names one of them. Checking a harvested
+ * name against the declared fields alone would drop it, leaving the predicate
+ * with the same missing key the harvest exists to prevent.
+ *
+ * Deliberately the columns OBSERVED on a live payload rather than
+ * `SYSTEM_MANAGED_FIELD_NAMES` (`@object-ui/types`), which is the broader
+ * DISPLAY-oriented set and carries legacy aliases (`_id`, `createdAt`,
+ * `modified`, `space`) that are not columns anywhere. An alias in `$select` is
+ * exactly the unknown key the guard exists to keep out.
+ */
+export declare const PLATFORM_RECORD_COLUMNS: ReadonlySet<string>;
+/**
+ * Whether a harvested name is safe to put in a `$select` projection: either the
+ * object declares it, or it is one of the platform columns every object has.
+ *
+ * The check is not pedantry — an unknown key is not ignored by every backend
+ * (the cloud multi-tenant runtime answers with an EMPTY result set), so without
+ * it one typo'd predicate could blank a whole list.
+ */
+export declare function isProjectableField(name: string, declaredFields: Record<string, unknown> | null | undefined): boolean;
+/**
+ * Collect the record field names referenced by a set of predicates.
+ *
+ * Accepts predicates in every authored shape (bare CEL string, the
+ * `{ dialect, source }` envelope, `null`/`undefined`/boolean — the last three
+ * contribute nothing). Returns names in first-seen order, deduplicated.
+ *
+ * The result is a set of CANDIDATES, not verified fields: a typo'd predicate
+ * yields a name this object does not have. Callers must intersect it with the
+ * object's declared fields before putting it in a query — an unknown key in
+ * `$select` is not ignored by every backend (the cloud runtime answers with an
+ * empty result set), which would turn a typo into a blank list.
+ */
+export declare function collectPredicateFieldRefs(predicates: readonly unknown[]): string[];
+/**
+ * Every predicate a list-ish view carries, flattened for
+ * {@link collectPredicateFieldRefs}.
+ *
+ * One reader so the projection cannot fall behind the surfaces: each entry here
+ * is a place a predicate is actually evaluated against a row — conditional
+ * formatting, the row kebab (custom defs AND the built-in Edit/Delete
+ * overrides), the selection bar, and the object's declared actions.
+ *
+ * `objectActions` is deliberately the object's WHOLE action set rather than
+ * only the ones this view promotes. Narrowing it would mean re-running the
+ * name resolution `resolveLegacyRowActions` / `resolveBulkActions` already do,
+ * at a point in the fetch where the view's `rowActions` / `bulkActions` lists
+ * have not been folded yet — and the two directions of error are not
+ * symmetric: an extra column costs bytes, a missing one silently breaks the
+ * predicate that needed it.
+ */
+export declare function listViewPredicates(view: {
+    conditionalFormatting?: readonly unknown[] | null;
+    rowActionDefs?: readonly unknown[] | null;
+    bulkActionDefs?: readonly unknown[] | null;
+    objectActions?: readonly unknown[] | null;
+    userActions?: Record<string, unknown> | null;
+}): unknown[];