@object-ui/core 16.1.0 → 17.2.0

package/dist/utils/column-identity.d.ts

@@ -0,0 +1,110 @@
+/**
+ * ObjectUI — column identity canonicalization
+ * 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 spec's canonical key for "which object field this column shows".
+ * `ListColumnSchema` (`@objectstack/spec/view`) declares `field: z.ZodString`
+ * as its ONLY required key — there is no `name`, no `fieldName`, no
+ * `accessorKey` on it. So `field` is not one dialect among several: it is the
+ * contract, and everything else is objectui-side legacy (AGENTS.md #0).
+ *
+ * Note this is the exact opposite of the FORM layer, where the runtime key is
+ * `name` (objectui#3090). The two surfaces sit next to each other and mean the
+ * opposite thing by the same pair of key names, which is why copy-paste between
+ * them keeps producing the defect this module exists to close.
+ */
+export declare const CANONICAL_COLUMN_IDENTITY_KEY = "field";
+/**
+ * Legacy identity spellings, in the order a canonicalizing read falls back
+ * through them. `field` wins over both, always.
+ *
+ * `fieldName` is here for defence, not because objectui emits it: as of
+ * objectui#3104 a repo-wide scan finds NO writer of a column-level `fieldName`
+ * — every `fieldName:` occurrence in the tree is a function parameter or an
+ * unrelated interface member (`AIFieldSuggestion.fieldName`). It survives
+ * purely in READERS that were written defensively, and stored host metadata
+ * could still carry it, so the fold accepts it and the ratchet counts it.
+ */
+export declare const LEGACY_COLUMN_IDENTITY_KEYS: readonly ["name", "fieldName"];
+/**
+ * NOT an identity key — deliberately excluded from everything in this module.
+ *
+ * `accessorKey` is TanStack Table's own column key (`TableColumn.accessorKey`,
+ * `packages/types/src/data-display.ts`, "Data accessor key"). It names a slot in
+ * the table LIBRARY's column model, not a field in ObjectStack metadata. Reads
+ * like `RelatedList`'s `accessorKey || field || name` therefore merge two
+ * different vocabularies in one expression; canonicalizing across that boundary
+ * would fossilize the merge, which is precisely the mistake this battle exists
+ * to undo. The fold neither reads nor writes it.
+ */
+export declare const TABLE_ADAPTER_COLUMN_KEY = "accessorKey";
+/**
+ * Read a column entry's field identity — the ONE reader every consumer should
+ * converge onto (objectui#3104 PR2).
+ *
+ * Accepts the three shapes a `columns` array actually holds: a bare string
+ * (`'stage'`), a spec column (`{ field: 'stage' }`), and the legacy objectui
+ * shapes (`{ name }` / `{ fieldName }`). Resolution is canonical-first, so it
+ * agrees with `buildExpandFields` and with the `$select` projection rather than
+ * with whichever half of a mixed-key column happened to be read.
+ *
+ * Returns `undefined` — not `''` — when nothing is resolvable, so callers can
+ * tell "no identity" from "identity is the empty string" and drop the entry
+ * instead of requesting a nameless column.
+ */
+export declare function columnIdentity(entry: unknown): string | undefined;
+/**
+ * True when a column entry carries more than one identity key AND they
+ * disagree — the shape that makes the renderer and the data request resolve
+ * two different fields. Exported for the "say who wins, loudly" step
+ * (objectui#3104 PR3) and used by the tests to name the defect precisely.
+ */
+export declare function hasConflictingColumnIdentity(entry: unknown): boolean;
+/** Reset the warn-once memo. Exported for tests. */
+export declare function resetColumnIdentityWarnings(): void;
+/**
+ * Stamp the canonical identity onto one column entry.
+ *
+ * The transitional strategy (objectui#3104 PR1) is **mirror, don't delete**:
+ *
+ *  - `field` is written with the resolved identity, so the request path — which
+ *    reads `field` and ONLY `field` in `ListView`'s `$expand`/`$select`
+ *    builders and in `ObjectGrid.getSelectFields` — always finds one.
+ *  - a legacy key that is ALREADY PRESENT is overwritten with that same
+ *    identity, so the name-first read sites still standing (`ListView` ×8,
+ *    `ObjectGrid`, `ObjectTree`, the detail renderers) resolve to exactly what
+ *    the request asked for.
+ *  - a legacy key that is ABSENT is never invented. A spec-clean
+ *    `{ field: 'stage' }` comes back untouched, by reference; the fold does not
+ *    manufacture the legacy vocabulary it is trying to retire.
+ *
+ * This differs on purpose from `normalizeListViewSchema`'s other folds, which
+ * DELETE the legacy key so a missed read-site fails loudly. Deleting works
+ * inside this repo — every name-first read here falls through to `field` — but
+ * `columns` entries cross the package boundary into host applications and
+ * third-party renderers, and dropping `name` from under them is a breaking
+ * change we have no inventory for. Mirroring is behaviour-preserving for every
+ * reader, in or out of the repo; the deletion is PR3's call to make once the
+ * in-repo consumers have converged onto {@link columnIdentity}.
+ *
+ * The result: for any single-key column the resolved identity is unchanged at
+ * every read site. The only entries whose behaviour moves are the ones where
+ * two sites already disagreed — which is the defect, not a regression.
+ */
+export declare function normalizeColumnIdentity<T>(entry: T): T;
+/**
+ * Stamp the canonical identity across a `columns` array.
+ *
+ * Non-mutating and allocation-frugal in the same way as
+ * `normalizeListViewSchema`: when every entry is already canonical the INPUT
+ * array is returned by reference, so `ListView`'s downstream `useMemo`s keep a
+ * stable dependency identity on the common path and nothing re-renders.
+ *
+ * String entries pass through untouched — a bare `'stage'` is unambiguous and
+ * every consumer already special-cases it.
+ */
+export declare function normalizeColumnIdentities<T>(columns: T): T;

package/dist/utils/column-identity.js

@@ -0,0 +1,210 @@
+/**
+ * ObjectUI — column identity canonicalization
+ * 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 spec's canonical key for "which object field this column shows".
+ * `ListColumnSchema` (`@objectstack/spec/view`) declares `field: z.ZodString`
+ * as its ONLY required key — there is no `name`, no `fieldName`, no
+ * `accessorKey` on it. So `field` is not one dialect among several: it is the
+ * contract, and everything else is objectui-side legacy (AGENTS.md #0).
+ *
+ * Note this is the exact opposite of the FORM layer, where the runtime key is
+ * `name` (objectui#3090). The two surfaces sit next to each other and mean the
+ * opposite thing by the same pair of key names, which is why copy-paste between
+ * them keeps producing the defect this module exists to close.
+ */
+export const CANONICAL_COLUMN_IDENTITY_KEY = 'field';
+/**
+ * Legacy identity spellings, in the order a canonicalizing read falls back
+ * through them. `field` wins over both, always.
+ *
+ * `fieldName` is here for defence, not because objectui emits it: as of
+ * objectui#3104 a repo-wide scan finds NO writer of a column-level `fieldName`
+ * — every `fieldName:` occurrence in the tree is a function parameter or an
+ * unrelated interface member (`AIFieldSuggestion.fieldName`). It survives
+ * purely in READERS that were written defensively, and stored host metadata
+ * could still carry it, so the fold accepts it and the ratchet counts it.
+ */
+export const LEGACY_COLUMN_IDENTITY_KEYS = ['name', 'fieldName'];
+/**
+ * NOT an identity key — deliberately excluded from everything in this module.
+ *
+ * `accessorKey` is TanStack Table's own column key (`TableColumn.accessorKey`,
+ * `packages/types/src/data-display.ts`, "Data accessor key"). It names a slot in
+ * the table LIBRARY's column model, not a field in ObjectStack metadata. Reads
+ * like `RelatedList`'s `accessorKey || field || name` therefore merge two
+ * different vocabularies in one expression; canonicalizing across that boundary
+ * would fossilize the merge, which is precisely the mistake this battle exists
+ * to undo. The fold neither reads nor writes it.
+ */
+export const TABLE_ADAPTER_COLUMN_KEY = 'accessorKey';
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const asIdentity = (v) => typeof v === 'string' && v.length > 0 ? v : undefined;
+/**
+ * Read a column entry's field identity — the ONE reader every consumer should
+ * converge onto (objectui#3104 PR2).
+ *
+ * Accepts the three shapes a `columns` array actually holds: a bare string
+ * (`'stage'`), a spec column (`{ field: 'stage' }`), and the legacy objectui
+ * shapes (`{ name }` / `{ fieldName }`). Resolution is canonical-first, so it
+ * agrees with `buildExpandFields` and with the `$select` projection rather than
+ * with whichever half of a mixed-key column happened to be read.
+ *
+ * Returns `undefined` — not `''` — when nothing is resolvable, so callers can
+ * tell "no identity" from "identity is the empty string" and drop the entry
+ * instead of requesting a nameless column.
+ */
+export function columnIdentity(entry) {
+    if (typeof entry === 'string')
+        return asIdentity(entry);
+    if (!isRecord(entry))
+        return undefined;
+    const canonical = asIdentity(entry[CANONICAL_COLUMN_IDENTITY_KEY]);
+    if (canonical)
+        return canonical;
+    for (const key of LEGACY_COLUMN_IDENTITY_KEYS) {
+        const legacy = asIdentity(entry[key]);
+        if (legacy)
+            return legacy;
+    }
+    return undefined;
+}
+/**
+ * True when a column entry carries more than one identity key AND they
+ * disagree — the shape that makes the renderer and the data request resolve
+ * two different fields. Exported for the "say who wins, loudly" step
+ * (objectui#3104 PR3) and used by the tests to name the defect precisely.
+ */
+export function hasConflictingColumnIdentity(entry) {
+    if (!isRecord(entry))
+        return false;
+    const resolved = columnIdentity(entry);
+    if (!resolved)
+        return false;
+    for (const key of [CANONICAL_COLUMN_IDENTITY_KEY, ...LEGACY_COLUMN_IDENTITY_KEYS]) {
+        const present = asIdentity(entry[key]);
+        if (present && present !== resolved)
+            return true;
+    }
+    return false;
+}
+// Warn once per (identity, conflicting spelling), not once per fold: columns are
+// re-normalized on every ListView render, and a warning that floods the console
+// is a warning that gets muted. Keyed by the pair rather than by the identity
+// alone so a column carrying two different stale spellings reports both — the
+// author needs to fix every producer, not just the first one seen.
+const warnedConflicts = new Set();
+/** Reset the warn-once memo. Exported for tests. */
+export function resetColumnIdentityWarnings() {
+    warnedConflicts.clear();
+}
+const isDev = () => globalThis.process?.env?.NODE_ENV !==
+    'production';
+/**
+ * Dev-mode only: say which key won, out loud, when a column carries two identity
+ * spellings that disagree.
+ *
+ * This is the audible half of objectui#3104. The fold below makes the two halves
+ * of such a column agree, which is what stops the bug — but silently rewriting
+ * `name` to match `field` also hides that the metadata producer is emitting a
+ * contradiction. The renderer recovering is not the same as the metadata being
+ * right, so the recovery says so.
+ *
+ * Non-breaking by construction: changes no types, rejects nothing, and is a
+ * no-op under `NODE_ENV=production`.
+ */
+function warnOnConflictingIdentity(entry, identity, losing) {
+    if (!isDev() || losing.length === 0)
+        return;
+    for (const key of losing) {
+        const memo = `${identity}:${key}:${String(entry[key])}`;
+        if (warnedConflicts.has(memo))
+            continue;
+        warnedConflicts.add(memo);
+        // eslint-disable-next-line no-console
+        console.warn(`[ObjectUI] Column carries two identities: \`${CANONICAL_COLUMN_IDENTITY_KEY}: ` +
+            `'${identity}'\` and \`${key}: '${String(entry[key])}'\`. ` +
+            `\`${CANONICAL_COLUMN_IDENTITY_KEY}\` wins — it is the only key ` +
+            `\`ListColumnSchema\` declares — and \`${key}\` has been rewritten to match, ` +
+            `so the rendered column and the requested field agree. Fix the producer: ` +
+            `drop \`${key}\` and author \`${CANONICAL_COLUMN_IDENTITY_KEY}\` only. ` +
+            `(objectui#3104)`);
+    }
+}
+/**
+ * Stamp the canonical identity onto one column entry.
+ *
+ * The transitional strategy (objectui#3104 PR1) is **mirror, don't delete**:
+ *
+ *  - `field` is written with the resolved identity, so the request path — which
+ *    reads `field` and ONLY `field` in `ListView`'s `$expand`/`$select`
+ *    builders and in `ObjectGrid.getSelectFields` — always finds one.
+ *  - a legacy key that is ALREADY PRESENT is overwritten with that same
+ *    identity, so the name-first read sites still standing (`ListView` ×8,
+ *    `ObjectGrid`, `ObjectTree`, the detail renderers) resolve to exactly what
+ *    the request asked for.
+ *  - a legacy key that is ABSENT is never invented. A spec-clean
+ *    `{ field: 'stage' }` comes back untouched, by reference; the fold does not
+ *    manufacture the legacy vocabulary it is trying to retire.
+ *
+ * This differs on purpose from `normalizeListViewSchema`'s other folds, which
+ * DELETE the legacy key so a missed read-site fails loudly. Deleting works
+ * inside this repo — every name-first read here falls through to `field` — but
+ * `columns` entries cross the package boundary into host applications and
+ * third-party renderers, and dropping `name` from under them is a breaking
+ * change we have no inventory for. Mirroring is behaviour-preserving for every
+ * reader, in or out of the repo; the deletion is PR3's call to make once the
+ * in-repo consumers have converged onto {@link columnIdentity}.
+ *
+ * The result: for any single-key column the resolved identity is unchanged at
+ * every read site. The only entries whose behaviour moves are the ones where
+ * two sites already disagreed — which is the defect, not a regression.
+ */
+export function normalizeColumnIdentity(entry) {
+    if (typeof entry === 'string' || !isRecord(entry))
+        return entry;
+    const identity = columnIdentity(entry);
+    if (!identity)
+        return entry;
+    const needsCanonical = entry[CANONICAL_COLUMN_IDENTITY_KEY] !== identity;
+    const staleLegacy = LEGACY_COLUMN_IDENTITY_KEYS.filter((key) => entry[key] !== undefined && entry[key] !== identity);
+    if (!needsCanonical && staleLegacy.length === 0)
+        return entry;
+    // Say who won before rewriting, while the losing spelling is still readable.
+    // Only genuine contradictions are reported: a column that merely lacks the
+    // canonical key (`{ name: 'stage' }`) is legacy, not conflicting, and gets
+    // stamped without noise.
+    warnOnConflictingIdentity(entry, identity, staleLegacy);
+    const next = { ...entry };
+    next[CANONICAL_COLUMN_IDENTITY_KEY] = identity;
+    for (const key of staleLegacy)
+        next[key] = identity;
+    return next;
+}
+/**
+ * Stamp the canonical identity across a `columns` array.
+ *
+ * Non-mutating and allocation-frugal in the same way as
+ * `normalizeListViewSchema`: when every entry is already canonical the INPUT
+ * array is returned by reference, so `ListView`'s downstream `useMemo`s keep a
+ * stable dependency identity on the common path and nothing re-renders.
+ *
+ * String entries pass through untouched — a bare `'stage'` is unambiguous and
+ * every consumer already special-cases it.
+ */
+export function normalizeColumnIdentities(columns) {
+    if (!Array.isArray(columns))
+        return columns;
+    let changed = false;
+    const next = columns.map((entry) => {
+        const folded = normalizeColumnIdentity(entry);
+        if (folded !== entry)
+            changed = true;
+        return folded;
+    });
+    return (changed ? next : columns);
+}

package/dist/utils/dashboard-filters.d.ts

@@ -18,7 +18,7 @@
  * Everything in this module is pure and synchronous so the binding rules
  * are unit-testable in isolation from React and the data layer.
  */
-import type { DashboardSchema, DashboardWidgetSchema, PageVariable } from '@object-ui/types';
+import type { DashboardComponentSchema, DashboardWidgetSchema, PageVariable } from '@object-ui/types';
 /** Reserved filter name for the dashboard's built-in date range. */
 export declare const DATE_RANGE_FILTER_NAME = "dateRange";
 export interface DashboardFilterDef {
@@ -66,7 +66,7 @@ export declare const DATE_RANGE_PRESETS: string[];
  * under the reserved name `"dateRange"`; each `globalFilters` entry follows,
  * named by its `name` (defaulting to `field`). Later duplicates win.
  */
-export declare function resolveDashboardFilterDefs(schema: Pick<DashboardSchema, 'globalFilters' | 'dateRange'>): DashboardFilterDef[];
+export declare function resolveDashboardFilterDefs(schema: Pick<DashboardComponentSchema, 'globalFilters' | 'dateRange'>): DashboardFilterDef[];
 /**
  * Derive `PageVariable` definitions for a dashboard's filter values so the
  * dashboard can host them in a `PageVariablesProvider` (the page/dashboard
@@ -78,6 +78,15 @@ export declare function dashboardFilterVariableDefs(defs: DashboardFilterDef[]):
  * 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 declare function buildFilterCondition(def: DashboardFilterDef, value: unknown): Record<string, unknown> | unknown | undefined;
 /**

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

@@ -27,7 +27,19 @@ 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).
+ */
+export type PercentScale = 'fraction' | 'whole';
 /**
  * Scale a stored `percent`-field value to its DISPLAY magnitude.
  *
@@ -49,7 +61,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/expand-fields.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 { columnIdentity } from './column-identity.js';
 /**
  * Relational ("reference-bearing") field types whose stored value is a foreign
  * key into another object — and which therefore benefit from `$expand` so a
@@ -90,14 +91,13 @@ export function buildExpandFields(schemaFields, columns) {
     if (columns && Array.isArray(columns) && columns.length > 0) {
         const columnFieldNames = new Set();
         for (const col of columns) {
-            if (typeof col === 'string') {
-                columnFieldNames.add(col);
-            }
-            else if (col && typeof col === 'object') {
-                const name = col.field ?? col.name ?? col.fieldName;
-                if (name)
-                    columnFieldNames.add(name);
-            }
+            // `columnIdentity` handles all three entry shapes (bare string, spec
+            // `{field}`, legacy `{name}`/`{fieldName}`) and resolves canonical-first
+            // — the same precedence every renderer now uses, so what gets expanded
+            // and what gets rendered can no longer name two different fields (#3104).
+            const name = columnIdentity(col);
+            if (name)
+                columnFieldNames.add(name);
         }
         return referenceFieldNames.filter((f) => columnFieldNames.has(f));
     }

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

@@ -29,6 +29,19 @@ export type FilterNode = [string, string, any] | [string, ...FilterNode[]];
  * @param operator - MongoDB-style operator (e.g., '$gte', '$in')
  * @returns ObjectStack operator or null if not recognized
  */
+/**
+ * A filter operator this layer will not translate.
+ *
+ * Carries the data API's own code and status for the same refusal so a failed
+ * list renders "the filter is malformed" rather than "check your connection" —
+ * `classifyLoadError` reads these, and a bare `Error` classifies as a network
+ * fault, which is the one thing this is definitely not.
+ */
+export declare class FilterOperatorError extends Error {
+    readonly code = "INVALID_FILTER";
+    readonly httpStatus = 400;
+    constructor(message: string);
+}
 export declare function convertOperatorToAST(operator: string): string | null;
 /**
  * Convert object-based filters to ObjectStack FilterNode AST format.
@@ -55,3 +68,37 @@ export declare function convertOperatorToAST(operator: string): string | null;
  * @throws {Error} If an unknown operator is encountered
  */
 export declare function convertFiltersToAST(filter: Record<string, any>): FilterNode | Record<string, any>;
+/**
+ * Normalize ONE filter source into a single filter node.
+ *
+ * A "source" is whatever a view hands a renderer, and there are three shapes in
+ * circulation, all legitimate:
+ *
+ *   - `[{ field, operator, value }, ...]`  a spec `ViewFilterRule[]`
+ *   - `[['stage', '=', 'won'], ...]`       an AST node / legacy flat array
+ *   - `{ status: 'active' }`               a MongoDB-style object
+ *
+ * The third is the one that kept getting lost. Renderers tested `source.length
+ * > 0` before using it, which is `undefined > 0` for an object — so a
+ * `table.defaultFilters` (declared `Record<string, any>`) was DROPPED and the
+ * view returned every record. Silently: no error, just a wider answer.
+ *
+ * Returns `undefined` for an absent or empty source, so callers can skip
+ * `$filter` rather than sending an empty array.
+ */
+export declare function toFilterNode(source: unknown): FilterNode | Record<string, any> | undefined;
+/**
+ * Combine filter sources under a single `and`, each as its OWN child.
+ *
+ * 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.
+ *
+ * Sources that normalize to nothing are skipped; one surviving source is
+ * returned as-is rather than wrapped in a pointless `and`.
+ */
+export declare function mergeFilterNodes(...sources: unknown[]): FilterNode | Record<string, any> | undefined;