@object-ui/core 17.1.0 → 17.3.0

package/dist/utils/dashboard-filters.js

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { resolveDateMacros } from './date-macros.js';
 /** Reserved filter name for the dashboard's built-in date range. */
 export const DATE_RANGE_FILTER_NAME = 'dateRange';
 /** Default target field for the built-in date range filter. */
@@ -31,6 +32,72 @@ const PRESET_RANGES = {
 };
 /** Preset keys the filter bar offers, in display order. */
 export const DATE_RANGE_PRESETS = Object.keys(PRESET_RANGES);
+/**
+ * ISO calendar date, optionally carrying a time part — `2026-01-15`,
+ * `2026-01-15T08:30:00Z`. Deliberately narrower than `Date.parse`, which
+ * also accepts locale prose (`March 5, 2026`) and bare years (`2026`);
+ * neither is a value the backend compares a date column against usefully.
+ */
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(?:[T ][\d:.]+(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+/**
+ * True when a bare string value can legitimately reach a query as a date
+ * (#3151). Two spellings qualify:
+ *
+ *  - a **date-macro token** (`{today}`, `${current_month_start}`,
+ *    `{7_days_ago}`) — it stays symbolic in the generated condition and is
+ *    resolved at query time by `resolveDateMacros`, exactly like the bounds
+ *    `PRESET_RANGES` emits. The check asks that resolver itself instead of
+ *    restating its grammar here: one token vocabulary, no second dialect to
+ *    drift — and a token it does not know is precisely the typo this guard
+ *    exists to catch;
+ *  - an **ISO date**, which means equality on that day (documented behaviour).
+ */
+function isUsableDateString(value) {
+    if (resolveDateMacros(value) !== value)
+        return true;
+    return ISO_DATE_RE.test(value) && !Number.isNaN(Date.parse(value));
+}
+/** `today, yesterday, …` — quoted in every rejection so the fix is in reach. */
+function presetList() {
+    return DATE_RANGE_PRESETS.join(', ');
+}
+function warnDateFilter(message) {
+    if (typeof console !== 'undefined')
+        console.warn(`[dashboard-filters] ${message}`);
+}
+/**
+ * Normalize a date filter's DECLARED default into the `DateRangeValue` shape
+ * every date consumer in this module reads (framework#4475).
+ *
+ * The built-in `dateRange` declaration has always been normalized this way —
+ * `schema.dateRange.defaultRange` is a preset NAME and
+ * `resolveDashboardFilterDefs` lifts it to `{ preset }`. A `globalFilters`
+ * entry of `type: 'date'` was passed through raw instead, and that asymmetry
+ * is the whole bug: `@objectstack/spec`'s `GlobalFilterSchema.defaultValue` is
+ * `string | number | boolean`, so a bare preset name is the ONLY spelling an
+ * author can write, yet nothing ever mapped it. Both symptoms of Setup's
+ * System Overview reading 0 across every KPI tile follow from that:
+ *
+ *  - `buildFilterCondition` fell through to its "a bare string date means
+ *    equality on that day" branch and emitted `created_at = 'last_7_days'`,
+ *    which matches no row — a query the backend answers `200 OK` with a 0;
+ *  - `DateRangeFilter` reads `value.preset` / `.from` / `.to`, all `undefined`
+ *    on a bare string, so the control displayed "All time" while sending that
+ *    equality — the tiles looked deliberately unfiltered and merely empty.
+ *
+ * Only a name this module actually knows is lifted. A genuine ISO date string
+ * still means equality on that day (the documented behaviour), and a number /
+ * boolean / unrecognised string is left exactly as declared — an unrecognised
+ * string then never reaches a query at all: `buildFilterCondition` skips it
+ * with a warning rather than comparing a column against it (#3151).
+ */
+function normalizeDateDefault(type, defaultValue) {
+    if (type !== 'date' && type !== 'dateRange')
+        return defaultValue;
+    if (typeof defaultValue !== 'string')
+        return defaultValue;
+    return defaultValue in PRESET_RANGES ? { preset: defaultValue } : defaultValue;
+}
 /**
  * Normalize a filter's static `options` declaration to `{ value, label }`
  * pairs. The @objectstack/spec `GlobalFilterSchema.options` form is
@@ -88,14 +155,18 @@ export function resolveDashboardFilterDefs(schema) {
         if (byName.has(name) && typeof console !== 'undefined') {
             console.warn(`[dashboard-filters] duplicate filter name "${name}" — the later definition wins`);
         }
+        const type = f.type ?? 'text';
         byName.set(name, {
             name,
             field: f.field,
             label: f.label,
-            type: f.type ?? 'text',
+            type,
             options: normalizeFilterOptions(f.options),
             optionsFrom: f.optionsFrom,
-            defaultValue: f.defaultValue,
+            // framework#4475 — same preset-name lifting the built-in `dateRange`
+            // above already does; see normalizeDateDefault for why a bare string is
+            // the only thing an author can declare here.
+            defaultValue: normalizeDateDefault(type, f.defaultValue),
             targetWidgets: f.targetWidgets,
         });
     }
@@ -134,6 +205,15 @@ function isEmptyValue(def, value) {
  * Build the operator shape (the value side of a `FilterCondition` entry) for
  * one filter's current value. Returns `undefined` when the value imposes no
  * constraint. The caller keys the result by the bound field name.
+ *
+ * A `date`/`dateRange` value is held to three spellings (#3151): a known
+ * preset name → range bounds; a date-macro token or ISO date → equality on
+ * that day; **anything else → skipped with a console warning**, never
+ * silently downgraded to an equality nothing can match. That last branch is
+ * the same strictness `buildWidgetScopedFilter` applies to a default binding
+ * on an unknown field name, for the same reason: a query the backend answers
+ * `200 OK` with zero rows is indistinguishable from "this range has no data",
+ * so the typo has to be said out loud somewhere.
  */
 export function buildFilterCondition(def, value) {
     if (isEmptyValue(def, value))
@@ -141,9 +221,18 @@ export function buildFilterCondition(def, value) {
     if (def.type === 'dateRange' || def.type === 'date') {
         const v = value;
         if (typeof v === 'object') {
-            const range = v.preset ? PRESET_RANGES[v.preset] : undefined;
+            const preset = typeof v.preset === 'string' && v.preset ? v.preset : undefined;
+            const range = preset ? PRESET_RANGES[preset] : undefined;
             const from = range?.from ?? v.from;
             const to = range?.to ?? v.to;
+            if (preset && !range) {
+                // Was already dropped here — but silently, which reads as "no data".
+                warnDateFilter(from || to
+                    ? `filter "${def.name}": ignoring unknown date range preset "${preset}" — ` +
+                        `using the explicit from/to bounds instead; known presets: ${presetList()}`
+                    : `skipping filter "${def.name}": unknown date range preset "${preset}" — ` +
+                        `expected one of: ${presetList()}`);
+            }
             if (!from && !to)
                 return undefined;
             return {
@@ -151,7 +240,13 @@ export function buildFilterCondition(def, value) {
                 ...(to ? { $lte: to } : {}),
             };
         }
-        // A bare string date means equality on that day.
+        if (typeof v === 'string' && !isUsableDateString(v)) {
+            warnDateFilter(`skipping filter "${def.name}": value "${v}" is neither a known date range preset ` +
+                `nor an ISO date — expected one of: ${presetList()}, an ISO date (YYYY-MM-DD), ` +
+                `or a date macro such as {today}`);
+            return undefined;
+        }
+        // A bare string date (or date macro) means equality on that day.
         return value;
     }
     if (def.type === 'select' || def.type === 'lookup') {

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

@@ -15,6 +15,7 @@
  * Pure (no React / i18n) so it can live in `@object-ui/core` and be imported
  * by both `@object-ui/plugin-dashboard` and `@object-ui/plugin-report`.
  */
+import type { PercentScale } from '@objectstack/spec/data';
 /**
  * Column metadata the analytics server returns alongside the rows: a display
  * `label` for both dimensions and measures, plus a measure's numeral `format`
@@ -27,7 +28,23 @@ export interface DatasetResultField {
     label?: string;
     format?: string;
     currency?: string;
+    percentScale?: PercentScale;
 }
+/**
+ * How a percentage column's stored number relates to its displayed percentage —
+ * the server's answer to a question a `%` format string cannot express:
+ * `fraction` is a 0–1 ratio (`1` ⇒ "100%"), `whole` is already percentage
+ * points (`1` ⇒ "1%"). Resolved from metadata server-side (a `ratio` measure is
+ * a fraction by definition; a measure over a `percent` field inherits that
+ * field's scale) and carried on the result column, so display never has to
+ * infer it from the value's magnitude — the inference that printed a ratio of
+ * exactly 1 as "1.0%" (#3136).
+ *
+ * Spec-owned since 17.0.0-rc.2 (`@objectstack/spec/data` exports the identical
+ * union); re-exported here so existing `@object-ui/core` consumers keep their
+ * import path.
+ */
+export type { PercentScale } from '@objectstack/spec/data';
 /**
  * Scale a stored `percent`-field value to its DISPLAY magnitude.
  *
@@ -49,7 +66,7 @@ export declare function percentDisplayValue(value: number): number;
  * controls grouping / decimals / percent; it can't be baked into the row value
  * server-side (the same number feeds charts), so it is applied here.
  */
-export declare function formatMeasure(v: unknown, format?: string, currency?: string): string;
+export declare function formatMeasure(v: unknown, format?: string, currency?: string, percentScale?: PercentScale): string;
 /**
  * Format a non-measure (dimension / label) value — the server already resolves
  * dimension display labels, so this only tidies numbers and nulls.

package/dist/utils/dataset-format.js

@@ -28,7 +28,7 @@ export function percentDisplayValue(value) {
  * controls grouping / decimals / percent; it can't be baked into the row value
  * server-side (the same number feeds charts), so it is applied here.
  */
-export function formatMeasure(v, format, currency) {
+export function formatMeasure(v, format, currency, percentScale) {
     if (v == null)
         return '—';
     if (typeof v !== 'number')
@@ -59,7 +59,15 @@ export function formatMeasure(v, format, currency) {
     // (0.75 ⇒ 75%). Scale to display magnitude the SAME way the list-view cell
     // renderer does — otherwise an avg of 0.608 renders as "0.6%" instead of
     // "60.8%", disagreeing with the per-row "75%" the list already shows.
-    const display = isPercent ? percentDisplayValue(v) : v;
+    //
+    // A DECLARED `percentScale` from the server wins outright: the value-magnitude
+    // heuristic below cannot tell a 0–1 ratio of exactly 1 from 1 percentage point
+    // (both are the number 1) and resolves it as "1%", so an SLA rate of full
+    // compliance rendered as "1.0%" instead of "100.0%" (#3136). The heuristic
+    // stays as the fallback for columns that arrive without the annotation.
+    const display = isPercent
+        ? (percentScale ? (percentScale === 'fraction' ? v * 100 : v) : percentDisplayValue(v))
+        : v;
     const body = display.toLocaleString(undefined, { minimumFractionDigits: decimals ?? 0, maximumFractionDigits: decimals ?? 0 });
     return `${legacyDollar}${body}${isPercent ? '%' : ''}`;
 }

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

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+/**
+ * dataset-pivot — the lookup-key encoders every cross-tab over a semantic-layer
+ * `queryDataset` result shares (ADR-0021).
+ *
+ * A pivot keys three lookups off dimension-value tuples: the DOWN bucket, the
+ * ACROSS bucket, and the cell where the two meet. Every one of them used to be
+ * spelled by concatenating values with a character the data was ASSUMED never
+ * to contain — an empty string, a plain space, U+0001 — and each assumption
+ * failed on ordinary data: `"x"` + `"yz"` and `"xy"` + `"z"` are one id under an
+ * empty join, and `"New"` × `"York Q1"` and `"New York"` × `"Q1"` are one cell
+ * key under a space join. The later row silently overwrote the earlier one, so
+ * the cell showed a different row's measure, the overwritten row's value was
+ * unreachable, and drill-through followed the same wrong index into the wrong
+ * records — all without an error (objectstack#5473, objectstack#5665).
+ *
+ * `JSON.stringify` carries the boundary in its own quoting rather than in a
+ * character the values must avoid, so these are unambiguous for ANY value a
+ * dimension can hold. The ids are opaque lookup keys, never displayed — visible
+ * text comes from the separately-formatted labels.
+ *
+ * Both encoders live here, in `@object-ui/core`, because the same pivot is
+ * rendered by two packages (`plugin-dashboard`'s `DatasetWidget` and
+ * `plugin-report`'s `DatasetReportRenderer`). Each having written its own is
+ * exactly why both carried the defect and why fixing one left the other broken.
+ * The same rule applies WITHIN a renderer: the cell index and the subtotal
+ * lookups key the same buckets, so they must all call these — a second
+ * hand-rolled encoding of the same id agrees with the first only for the
+ * dimension counts someone happened to test, which is what kept the original
+ * bug invisible.
+ *
+ * Pure (no React / i18n), like its `dataset-format` neighbour.
+ *
+ * Known residual, tracked separately in objectstack#5666: callers encode a
+ * null/undefined dimension value as a placeholder string, so it still collides
+ * with a value that literally equals that placeholder. That is a property of
+ * the placeholder, not of the encoding below.
+ */
+/**
+ * Encode a pivot BUCKET id from its dimension values.
+ *
+ * Axis-neutral on purpose: a DOWN bucket and an ACROSS bucket are the same kind
+ * of thing (a dimension-value tuple), and a cross-tab with multiple across
+ * dimensions collides on that axis just as readily as on the down axis.
+ */
+export declare const pivotBucketId: (dimensionValues: string[]) => string;
+/**
+ * Encode the cell key for a (down bucket, across bucket) pair — the key of the
+ * map a renderer reads to place a measure and to resolve a drill-through.
+ */
+export declare const pivotCellKey: (rowId: string, colId: string) => string;

package/dist/utils/dataset-pivot.js

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+/**
+ * dataset-pivot — the lookup-key encoders every cross-tab over a semantic-layer
+ * `queryDataset` result shares (ADR-0021).
+ *
+ * A pivot keys three lookups off dimension-value tuples: the DOWN bucket, the
+ * ACROSS bucket, and the cell where the two meet. Every one of them used to be
+ * spelled by concatenating values with a character the data was ASSUMED never
+ * to contain — an empty string, a plain space, U+0001 — and each assumption
+ * failed on ordinary data: `"x"` + `"yz"` and `"xy"` + `"z"` are one id under an
+ * empty join, and `"New"` × `"York Q1"` and `"New York"` × `"Q1"` are one cell
+ * key under a space join. The later row silently overwrote the earlier one, so
+ * the cell showed a different row's measure, the overwritten row's value was
+ * unreachable, and drill-through followed the same wrong index into the wrong
+ * records — all without an error (objectstack#5473, objectstack#5665).
+ *
+ * `JSON.stringify` carries the boundary in its own quoting rather than in a
+ * character the values must avoid, so these are unambiguous for ANY value a
+ * dimension can hold. The ids are opaque lookup keys, never displayed — visible
+ * text comes from the separately-formatted labels.
+ *
+ * Both encoders live here, in `@object-ui/core`, because the same pivot is
+ * rendered by two packages (`plugin-dashboard`'s `DatasetWidget` and
+ * `plugin-report`'s `DatasetReportRenderer`). Each having written its own is
+ * exactly why both carried the defect and why fixing one left the other broken.
+ * The same rule applies WITHIN a renderer: the cell index and the subtotal
+ * lookups key the same buckets, so they must all call these — a second
+ * hand-rolled encoding of the same id agrees with the first only for the
+ * dimension counts someone happened to test, which is what kept the original
+ * bug invisible.
+ *
+ * Pure (no React / i18n), like its `dataset-format` neighbour.
+ *
+ * Known residual, tracked separately in objectstack#5666: callers encode a
+ * null/undefined dimension value as a placeholder string, so it still collides
+ * with a value that literally equals that placeholder. That is a property of
+ * the placeholder, not of the encoding below.
+ */
+/**
+ * Encode a pivot BUCKET id from its dimension values.
+ *
+ * Axis-neutral on purpose: a DOWN bucket and an ACROSS bucket are the same kind
+ * of thing (a dimension-value tuple), and a cross-tab with multiple across
+ * dimensions collides on that axis just as readily as on the down axis.
+ */
+export const pivotBucketId = (dimensionValues) => JSON.stringify(dimensionValues);
+/**
+ * Encode the cell key for a (down bucket, across bucket) pair — the key of the
+ * map a renderer reads to place a measure and to resolve a drill-through.
+ */
+export const pivotCellKey = (rowId, colId) => JSON.stringify([rowId, colId]);

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/filter-tokens.d.ts

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { CONTEXT_TOKENS } from '@objectstack/spec/data';
 /**
  * Session-scoped filter placeholders — the sibling vocabulary to
  * `{date-macros}`.
@@ -42,13 +43,19 @@
  * ## Contract source
  *
  * The canonical vocabulary is published as part of the platform contract at
- * `@objectstack/spec` → `CONTEXT_TOKENS` / `classifyFilterToken`. It is
- * mirrored here — exactly as `date-macros.ts` mirrors `DATE_MACRO_TOKENS` —
- * because the installed `@objectstack/spec` predates that export. Keep the two
- * in sync; the duplication is temporary until the next coordinated release.
+ * `@objectstack/spec/data` → `CONTEXT_TOKENS`. This module used to carry a
+ * hand-written copy of that tuple under the spec's own name, with a comment
+ * saying the duplication was "temporary until the next coordinated release"
+ * — the installed spec (17.0.0-rc.0) has exported it for some time, so the
+ * copy was simply a fork wearing the spec's name (objectstack#4115).
+ *
+ * It is now a **re-export**, which is the only form that cannot drift: the
+ * copy was byte-identical, so every value comparison and every behavioural
+ * test passed while it sat here. Reference identity is the one check that
+ * distinguishes a re-export from a fork (objectui#3003).
  */
-/** The complete set of session-scoped filter tokens. */
-export declare const CONTEXT_TOKENS: readonly ["current_user_id", "current_org_id"];
+/** The complete set of session-scoped filter tokens (spec-owned, re-exported). */
+export { CONTEXT_TOKENS };
 export type ContextTokenName = (typeof CONTEXT_TOKENS)[number];
 /** Session values a filter placeholder can resolve against. */
 export interface FilterTokenScope {

package/dist/utils/filter-tokens.js

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { CONTEXT_TOKENS } from '@objectstack/spec/data';
 import { resolveDateMacros } from './date-macros.js';
 /**
  * Session-scoped filter placeholders — the sibling vocabulary to
@@ -43,13 +44,19 @@ import { resolveDateMacros } from './date-macros.js';
  * ## Contract source
  *
  * The canonical vocabulary is published as part of the platform contract at
- * `@objectstack/spec` → `CONTEXT_TOKENS` / `classifyFilterToken`. It is
- * mirrored here — exactly as `date-macros.ts` mirrors `DATE_MACRO_TOKENS` —
- * because the installed `@objectstack/spec` predates that export. Keep the two
- * in sync; the duplication is temporary until the next coordinated release.
+ * `@objectstack/spec/data` → `CONTEXT_TOKENS`. This module used to carry a
+ * hand-written copy of that tuple under the spec's own name, with a comment
+ * saying the duplication was "temporary until the next coordinated release"
+ * — the installed spec (17.0.0-rc.0) has exported it for some time, so the
+ * copy was simply a fork wearing the spec's name (objectstack#4115).
+ *
+ * It is now a **re-export**, which is the only form that cannot drift: the
+ * copy was byte-identical, so every value comparison and every behavioural
+ * test passed while it sat here. Reference identity is the one check that
+ * distinguishes a re-export from a fork (objectui#3003).
  */
-/** The complete set of session-scoped filter tokens. */
-export const CONTEXT_TOKENS = ['current_user_id', 'current_org_id'];
+/** The complete set of session-scoped filter tokens (spec-owned, re-exported). */
+export { CONTEXT_TOKENS };
 /**
  * Near-miss spellings → the token the author meant.
  *

package/dist/utils/freeze-schema.d.ts

@@ -9,7 +9,7 @@
  * System View immutability layer.
  *
  * A "System View" is any UI schema authored in source code (imported `.ts`/`.json`,
- * `as const` literals, or returned from a `defineView()` call). Such schemas are
+ * `as const` literals, or returned from a `defineSystemView()` call). Such schemas are
  * part of the product contract and MUST NOT be mutated at runtime. Mutation
  * would cause behavior drift, break TypeScript inference, and bypass code review.
  *
@@ -37,7 +37,7 @@ export type DeepReadonly<T> = T extends (...args: any[]) => any ? T : T extends
     readonly [K in keyof T]: DeepReadonly<T[K]>;
 } : T;
 /**
- * A schema that has been frozen by `defineView()`. The marker symbol is
+ * A schema that has been frozen by `defineSystemView()`. The marker symbol is
  * non-enumerable and therefore invisible to consumers, but its presence
  * lets us discriminate at runtime.
  */
@@ -52,11 +52,19 @@ export declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): DeepRea
 /**
  * Mark and freeze a code-loaded schema as a System View.
  *
+ * Named `defineView` until objectstack#4115, which is a name `@objectstack/spec`
+ * owns for something else entirely: the spec's `defineView(config)` is the
+ * VIEW-DOCUMENT factory — it parses a `ViewSchema` (`{ list, form, listViews,
+ * formViews }`) and returns a validated `View`. This one takes an arbitrary
+ * object, stamps the System-View marker and deep-freezes it; it validates
+ * nothing. An app-shell comment already conflated the two, which is precisely
+ * the planted-premise failure the guard exists to stop.
+ *
  * @example
  * ```ts
- * import { defineView } from '@object-ui/core';
+ * import { defineSystemView } from '@object-ui/core';
  *
- * export const userListView = defineView({
+ * export const userListView = defineSystemView({
  *   type: 'list',
  *   data: { object: 'User' },
  *   columns: [{ name: 'email' }],
@@ -69,9 +77,9 @@ export declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): DeepRea
  * To produce a mutable derivative (Tenant or User View), call
  * `cloneAsOverride(userListView)`.
  */
-export declare function defineView<T extends object>(schema: T): SystemView<T>;
+export declare function defineSystemView<T extends object>(schema: T): SystemView<T>;
 /**
- * Runtime check: was this object produced by `defineView()` (or loaded from a
+ * Runtime check: was this object produced by `defineSystemView()` (or loaded from a
  * source that forwards the marker)?
  */
 export declare function isSystemView(value: unknown): boolean;