@object-ui/core 16.1.0 → 17.2.0

package/dist/utils/filter-converter.js

@@ -11,6 +11,32 @@
  * @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 class FilterOperatorError extends Error {
+    constructor(message) {
+        super(message);
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'INVALID_FILTER'
+        });
+        Object.defineProperty(this, "httpStatus", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 400
+        });
+        this.name = 'FilterOperatorError';
+    }
+}
 export function convertOperatorToAST(operator) {
     // Spec reference: framework/packages/spec/src/data/filter.zod.ts
     // Canonical MongoDB-style keys are camelCase ($startsWith, $endsWith, $notContains).
@@ -69,14 +95,22 @@ export function convertFiltersToAST(filter) {
         if (typeof value === 'object' && !Array.isArray(value)) {
             // Handle operator-based filters
             for (const [operator, operatorValue] of Object.entries(value)) {
-                // Special handling for $regex - warn users about limited support
+                // `$regex` is refused, not downgraded. It used to become `contains`
+                // behind a `console.warn` — but substring matching is a DIFFERENT
+                // QUESTION, not a weaker version of the same one: `$regex: 'a.c'`
+                // matches "abc", `contains 'a.c'` does not, and neither result looks
+                // wrong on screen. A warning is not an error channel; nobody reads the
+                // console of a deployed app.
+                //
+                // The spec has no `$regex` (`FILTER_OPERATORS`, data/filter.zod.ts), so
+                // there is nothing to translate it INTO. Same treatment the unknown
+                // operator below already gets, and for the same stated reason.
                 if (operator === '$regex') {
-                    console.warn(`[ObjectUI] Warning: $regex operator is not fully supported. ` +
-                        `Converting to 'contains' which only supports substring matching, not regex patterns. ` +
+                    throw new FilterOperatorError(`[ObjectUI] The '$regex' filter operator is not supported. It used to be ` +
+                        `converted to 'contains', which matches a literal substring rather than a ` +
+                        `pattern — a different result, not a degraded one. ` +
                         `Field: '${field}', Value: ${JSON.stringify(operatorValue)}. ` +
-                        `Consider using $contains or $startsWith instead.`);
-                    conditions.push([field, 'contains', operatorValue]);
-                    continue;
+                        `Use $contains, $startsWith or $endsWith.`);
                 }
                 // $null / $exists translate based on their boolean value (per spec semantics).
                 // $null: true  → IS NULL    | $null: false  → IS NOT NULL
@@ -95,7 +129,7 @@ export function convertFiltersToAST(filter) {
                 }
                 else {
                     // Unknown operator - throw error to avoid silent failure
-                    throw new Error(`[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. ` +
+                    throw new FilterOperatorError(`[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. ` +
                         `Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $between, ` +
                         `$contains, $notContains, $startsWith, $endsWith, $null, $exists. ` +
                         `If you need exact object matching, use the value directly without an operator.`);
@@ -118,3 +152,56 @@ export function convertFiltersToAST(filter) {
     // Multiple conditions: combine with 'and'
     return ['and', ...conditions];
 }
+/**
+ * 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 function toFilterNode(source) {
+    if (source === null || source === undefined)
+        return undefined;
+    if (Array.isArray(source))
+        return source.length > 0 ? source : undefined;
+    if (typeof source !== 'object')
+        return undefined;
+    const obj = source;
+    if (Object.keys(obj).length === 0)
+        return undefined;
+    // MongoDB-style → AST, so it can sit beside the other shapes under one `and`.
+    return convertFiltersToAST(obj);
+}
+/**
+ * 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 function mergeFilterNodes(...sources) {
+    const nodes = sources.map(toFilterNode).filter((n) => n !== undefined);
+    if (nodes.length === 0)
+        return undefined;
+    if (nodes.length === 1)
+        return nodes[0];
+    return ['and', ...nodes];
+}

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

@@ -0,0 +1,108 @@
+/**
+ * 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.
+ */
+import { CONTEXT_TOKENS } from '@objectstack/spec/data';
+/**
+ * Session-scoped filter placeholders — the sibling vocabulary to
+ * `{date-macros}`.
+ *
+ * Filter values travel as JSON, so a user-scoped slice cannot call
+ * `currentUser().id` inline; it writes a placeholder that this module expands
+ * immediately before the filter reaches the data source:
+ *
+ *     { owner_id: '{current_user_id}' }
+ *
+ * ## Why this module exists (framework #3574)
+ *
+ * There used to be no shared resolver. Three ad-hoc implementations had grown
+ * up independently — one in `ObjectView` for list views, one in
+ * `ObjectDataPage` for URL filter triples, one in `NavigationRenderer` for
+ * hrefs — and each handled only the shape its own surface happened to use.
+ * Dashboard widgets never got one at all, so `{current_user_id}` in a widget
+ * filter reached SQL as a literal, matched no row, and the widget rendered
+ * `0` with no error in the console or the server log.
+ *
+ * The failure mode is the point: a metric reading `0` is indistinguishable
+ * from a metric that is legitimately zero, so the bug survived review and
+ * shipped. Any *new* surface that resolves placeholders itself will
+ * eventually reproduce it, which is why resolution lives here, once, and
+ * every surface calls {@link resolveFilterPlaceholders}.
+ *
+ * ## Presentation scope, NOT a security boundary
+ *
+ * These tokens scope what a surface *shows*. They do not decide what a caller
+ * is *allowed* to read — that is RLS, enforced server-side against a
+ * different vocabulary rooted at `current_user` (`owner_id = current_user.id`).
+ * Dropping a `{current_user_id}` filter widens a view; it must never widen
+ * access. Never use a context token as an access control.
+ *
+ * ## Contract source
+ *
+ * The canonical vocabulary is published as part of the platform contract at
+ * `@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 (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 {
+    /** The signed-in user's id. */
+    currentUserId?: string | null;
+    /** The active organization id. */
+    currentOrgId?: string | null;
+    /**
+     * Called when a placeholder cannot be resolved — either a recognised token
+     * with no value in scope (signed out), or a near-miss spelling that resolves
+     * in no vocabulary. Defaults to a `console.warn`; pass `null` to silence.
+     */
+    onUnresolved?: ((message: string) => void) | null;
+}
+/**
+ * Expand `{current_user_id}` / `{current_org_id}` inside a filter.
+ *
+ * Walks arrays and plain objects recursively, which is what makes one
+ * resolver cover both platform filter shapes: the MongoDB-style object a
+ * dashboard widget carries (`{ owner_id: '{current_user_id}' }`) and the
+ * condition/triple arrays a list view carries (`[{ field, operator, value }]`
+ * / `[['owner','=','…']]`). The predecessor helper in `ObjectView` bailed on
+ * non-arrays (`if (!Array.isArray(filter)) return filter`), which is why
+ * lifting it into the dashboard would have been a silent no-op.
+ *
+ * Only whole-string placeholders are substituted — an id is an opaque value,
+ * so embedding it in a larger string (`'user-{current_user_id}'`) is never
+ * what an author means, and substituting there would silently produce a value
+ * that matches nothing. Unknown tokens are passed through untouched so that
+ * date macros and nav-only `AppContextSelector` ids survive this pass.
+ *
+ * An unresolvable *known* token is deliberately left as-is rather than
+ * dropped: leaving it yields an empty result, whereas dropping the clause
+ * would widen the result set — and a filter that silently widens is far worse
+ * than one that silently narrows.
+ */
+export declare function resolveContextTokens<T = any>(filter: T, scope?: FilterTokenScope): T;
+/**
+ * Resolve **every** placeholder vocabulary a filter value understands — date
+ * macros and context tokens — in one call.
+ *
+ * This is the function surfaces should call. Calling only one of the two
+ * resolvers is the defect behind framework #3574: dashboard widgets called
+ * `resolveDateMacros` alone, so `{today}` worked and `{current_user_id}`
+ * silently did not.
+ *
+ * Order is irrelevant (the vocabularies are disjoint) but fixed here so
+ * behaviour is identical everywhere.
+ */
+export declare function resolveFilterPlaceholders<T = any>(filter: T, scope?: FilterTokenScope, now?: Date): T;

package/dist/utils/filter-tokens.js

@@ -0,0 +1,180 @@
+/**
+ * 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.
+ */
+import { CONTEXT_TOKENS } from '@objectstack/spec/data';
+import { resolveDateMacros } from './date-macros.js';
+/**
+ * Session-scoped filter placeholders — the sibling vocabulary to
+ * `{date-macros}`.
+ *
+ * Filter values travel as JSON, so a user-scoped slice cannot call
+ * `currentUser().id` inline; it writes a placeholder that this module expands
+ * immediately before the filter reaches the data source:
+ *
+ *     { owner_id: '{current_user_id}' }
+ *
+ * ## Why this module exists (framework #3574)
+ *
+ * There used to be no shared resolver. Three ad-hoc implementations had grown
+ * up independently — one in `ObjectView` for list views, one in
+ * `ObjectDataPage` for URL filter triples, one in `NavigationRenderer` for
+ * hrefs — and each handled only the shape its own surface happened to use.
+ * Dashboard widgets never got one at all, so `{current_user_id}` in a widget
+ * filter reached SQL as a literal, matched no row, and the widget rendered
+ * `0` with no error in the console or the server log.
+ *
+ * The failure mode is the point: a metric reading `0` is indistinguishable
+ * from a metric that is legitimately zero, so the bug survived review and
+ * shipped. Any *new* surface that resolves placeholders itself will
+ * eventually reproduce it, which is why resolution lives here, once, and
+ * every surface calls {@link resolveFilterPlaceholders}.
+ *
+ * ## Presentation scope, NOT a security boundary
+ *
+ * These tokens scope what a surface *shows*. They do not decide what a caller
+ * is *allowed* to read — that is RLS, enforced server-side against a
+ * different vocabulary rooted at `current_user` (`owner_id = current_user.id`).
+ * Dropping a `{current_user_id}` filter widens a view; it must never widen
+ * access. Never use a context token as an access control.
+ *
+ * ## Contract source
+ *
+ * The canonical vocabulary is published as part of the platform contract at
+ * `@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 (spec-owned, re-exported). */
+export { CONTEXT_TOKENS };
+/**
+ * Near-miss spellings → the token the author meant.
+ *
+ * Every entry is a real authoring mistake, and each is a correct spelling
+ * *somewhere else* in the platform, which is exactly why authors reach for it:
+ * `current_user` is the RLS expression root, `{user_id}` is valid
+ * `titleFormat` field interpolation, `organization_id` is a real column name.
+ *
+ * Mirrors `CONTEXT_TOKEN_SUGGESTIONS` in `@objectstack/spec`. Used only to
+ * make the runtime warning actionable; the authoring-time gate
+ * (`validateFilterTokens` in `@objectstack/lint`) is what actually prevents
+ * these from shipping.
+ */
+const CONTEXT_TOKEN_SUGGESTIONS = {
+    current_user: 'current_user_id',
+    current_user_email: 'current_user_id',
+    user_id: 'current_user_id',
+    userid: 'current_user_id',
+    me: 'current_user_id',
+    current_organization_id: 'current_org_id',
+    org_id: 'current_org_id',
+    organization_id: 'current_org_id',
+    current_tenant_id: 'current_org_id',
+};
+/** Whole-string placeholder: `{token}` or `${token}`, anchored. */
+const WHOLE_TOKEN_RE = /^\$?\{([a-zA-Z0-9_]+)\}$/;
+function isContextToken(token) {
+    return CONTEXT_TOKENS.includes(token);
+}
+/**
+ * Expand `{current_user_id}` / `{current_org_id}` inside a filter.
+ *
+ * Walks arrays and plain objects recursively, which is what makes one
+ * resolver cover both platform filter shapes: the MongoDB-style object a
+ * dashboard widget carries (`{ owner_id: '{current_user_id}' }`) and the
+ * condition/triple arrays a list view carries (`[{ field, operator, value }]`
+ * / `[['owner','=','…']]`). The predecessor helper in `ObjectView` bailed on
+ * non-arrays (`if (!Array.isArray(filter)) return filter`), which is why
+ * lifting it into the dashboard would have been a silent no-op.
+ *
+ * Only whole-string placeholders are substituted — an id is an opaque value,
+ * so embedding it in a larger string (`'user-{current_user_id}'`) is never
+ * what an author means, and substituting there would silently produce a value
+ * that matches nothing. Unknown tokens are passed through untouched so that
+ * date macros and nav-only `AppContextSelector` ids survive this pass.
+ *
+ * An unresolvable *known* token is deliberately left as-is rather than
+ * dropped: leaving it yields an empty result, whereas dropping the clause
+ * would widen the result set — and a filter that silently widens is far worse
+ * than one that silently narrows.
+ */
+export function resolveContextTokens(filter, scope = {}) {
+    if (filter == null)
+        return filter;
+    const { currentUserId, currentOrgId } = scope;
+    const warn = scope.onUnresolved === null
+        ? () => { }
+        : scope.onUnresolved ??
+            ((message) => {
+                // eslint-disable-next-line no-console
+                console.warn(`[object-ui] ${message}`);
+            });
+    const values = {
+        current_user_id: currentUserId,
+        current_org_id: currentOrgId,
+    };
+    const walk = (value) => {
+        if (value == null)
+            return value;
+        if (typeof value === 'string') {
+            const m = value.match(WHOLE_TOKEN_RE);
+            if (!m)
+                return value;
+            const token = m[1];
+            if (isContextToken(token)) {
+                const resolved = values[token];
+                if (resolved != null && resolved !== '')
+                    return resolved;
+                warn(`Filter placeholder "{${token}}" could not be resolved — no ${token === 'current_user_id' ? 'signed-in user' : 'active organization'} in scope. The filter will match no records.`);
+                return value;
+            }
+            // Not ours. Warn only for near-misses, which resolve in no vocabulary
+            // at all and would otherwise fail silently; genuine date macros and
+            // nav context-selector ids must pass through quietly.
+            const suggestion = CONTEXT_TOKEN_SUGGESTIONS[token.toLowerCase()];
+            if (suggestion) {
+                warn(`Filter placeholder "{${token}}" is not a recognised token — did you mean ` +
+                    `"{${suggestion}}"? It is sent to the server as a literal string and will ` +
+                    `match no records.`);
+            }
+            return value;
+        }
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (typeof value === 'object') {
+            const out = {};
+            for (const k of Object.keys(value))
+                out[k] = walk(value[k]);
+            return out;
+        }
+        return value;
+    };
+    return walk(filter);
+}
+/**
+ * Resolve **every** placeholder vocabulary a filter value understands — date
+ * macros and context tokens — in one call.
+ *
+ * This is the function surfaces should call. Calling only one of the two
+ * resolvers is the defect behind framework #3574: dashboard widgets called
+ * `resolveDateMacros` alone, so `{today}` worked and `{current_user_id}`
+ * silently did not.
+ *
+ * Order is irrelevant (the vocabularies are disjoint) but fixed here so
+ * behaviour is identical everywhere.
+ */
+export function resolveFilterPlaceholders(filter, scope = {}, now = new Date()) {
+    if (filter == null)
+        return filter;
+    return resolveContextTokens(resolveDateMacros(filter, now), scope);
+}

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;

package/dist/utils/freeze-schema.js

@@ -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.
  *
@@ -86,11 +86,19 @@ export function deepFreeze(value, seen = new WeakSet()) {
 /**
  * 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' }],
@@ -103,9 +111,9 @@ export function deepFreeze(value, seen = new WeakSet()) {
  * To produce a mutable derivative (Tenant or User View), call
  * `cloneAsOverride(userListView)`.
  */
-export function defineView(schema) {
+export function defineSystemView(schema) {
     if (schema == null || typeof schema !== 'object') {
-        throw new TypeError('[ObjectUI] defineView() expects a non-null object schema.');
+        throw new TypeError('[ObjectUI] defineSystemView() expects a non-null object schema.');
     }
     // Stamp the marker on the root only — nested nodes share origin via lineage.
     // Non-enumerable keeps it out of JSON, spreads, and Object.keys.
@@ -120,7 +128,7 @@ export function defineView(schema) {
     return deepFreeze(schema);
 }
 /**
- * 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 function isSystemView(value) {