@object-ui/react 17.6.0 → 18.0.0

package/dist/hooks/useOffline.js

@@ -5,7 +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 { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { useCallback, useEffect, useInsertionEffect, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
 // ---------------------------------------------------------------------------
 // Online/offline external store (SSR-safe)
 // ---------------------------------------------------------------------------
@@ -93,7 +93,31 @@ export function useOffline(config = {}) {
     const [queue, setQueue] = useState(loadQueue);
     const [syncState, setSyncState] = useState('idle');
     const syncConfigRef = useRef(syncConfig);
-    syncConfigRef.current = syncConfig;
+    // `sync` below is keyed on `[enabled, queue]`, so a config-only change keeps
+    // the SAME `sync` closure alive — and the auto-sync effect deliberately
+    // captures one and fires it 100ms later. The ref is how those retained
+    // closures still read the newest `sync` config; putting `syncConfig` in
+    // `sync`'s deps instead would rebuild `sync` (and the memoised result) on
+    // every render, because callers pass `sync: { ... }` as an inline literal.
+    // Only the write moves out of the render body: `useInsertionEffect` runs in
+    // the mutation phase, ahead of every layout effect and paint, so no caller
+    // that could legally reach `sync()` observes a different value than before.
+    useInsertionEffect(() => {
+        syncConfigRef.current = syncConfig;
+    });
+    // The queue reaches `sync` through the SAME commit-phase mirror the sync
+    // config uses (objectui#6818). It used to come from `sync`'s own closure
+    // while `batchSize` came from the ref above, so the two halves of one call
+    // disagreed about how current they were: a retained `sync` — and the
+    // auto-sync effect below deliberately retains one and fires it 100ms later —
+    // batched a queue snapshot from an older render against the newest
+    // `batchSize`. Mirroring the queue makes both halves the newest COMMITTED
+    // value, and it is what takes `queue` out of `sync`'s dependency list, so
+    // `sync` stops changing identity on every queued mutation.
+    const queueRef = useRef(queue);
+    useInsertionEffect(() => {
+        queueRef.current = queue;
+    });
     // Persist queue to localStorage whenever it changes
     useEffect(() => {
         persistQueue(queue);
@@ -130,14 +154,16 @@ export function useOffline(config = {}) {
         setQueue([]);
     }, []);
     const sync = useCallback(async () => {
-        if (!enabled || queue.length === 0)
+        // Newest committed queue, not this closure's snapshot — see `queueRef`.
+        const pending = queueRef.current;
+        if (!enabled || pending.length === 0)
             return;
         setSyncState('syncing');
         try {
             // In a real implementation, this would batch-send mutations to the server.
             // For now, we simulate a successful sync by clearing the queue.
-            const batchSize = syncConfigRef.current?.batchSize ?? queue.length;
-            const batch = queue.slice(0, batchSize);
+            const batchSize = syncConfigRef.current?.batchSize ?? pending.length;
+            const batch = pending.slice(0, batchSize);
             // Simulate network round-trip
             await new Promise((resolve) => setTimeout(resolve, 0));
             // Remove synced mutations from queue
@@ -147,18 +173,46 @@ export function useOffline(config = {}) {
         catch {
             setSyncState('error');
         }
-    }, [enabled, queue]);
-    // Auto-sync when coming back online (short stabilization delay)
+    }, [enabled]);
+    // Auto-sync while online and holding queued mutations (short stabilization
+    // delay).
+    //
+    // The dependency list used to be `[isOnline, enabled]` with
+    // `react-hooks/exhaustive-deps` suppressed, on the stated grounds that
+    // re-running "on every queue change" would restart the 100ms timer once per
+    // queued mutation. That reason is real and is preserved below — the
+    // dependency is the BOOLEAN `hasPendingMutations`, never `queue` and never
+    // `queue.length`, so queueing a second mutation while a timer is already
+    // armed does not re-run this effect and does not restart the timer.
+    //
+    // What the suppression also did, and never justified, was evaluate the
+    // emptiness guard against a queue snapshot from whenever `isOnline` or
+    // `enabled` last changed. `queueMutation` accepts entries whenever the hook
+    // is enabled — it has never been conditional on being offline — so anything
+    // queued while ALREADY online found this effect asleep and had no auto-sync
+    // path at all; only an explicit `sync()` drained it (objectui#6818). Keying
+    // on the boolean re-evaluates the guard exactly when it can change answer.
+    //
+    // `sync` is now stable across queue changes (it reads the queue through
+    // `queueRef`), so naming it here costs no extra timer restart and the array
+    // is genuinely exhaustive — the suppression is gone rather than reworded.
+    //
+    // Known remaining edge, deliberately not widened here: a `batchSize` smaller
+    // than the queue drains one batch and leaves `hasPendingMutations` true, so
+    // the remainder waits for the next transition rather than chaining a second
+    // batch. That is the pre-existing behaviour, not a regression. Whether one
+    // auto-sync should drain the whole queue batch-by-batch is a semantics
+    // question about `batchSize` rather than a bug in this guard, and it is
+    // filed separately as objectui#6857.
+    const hasPendingMutations = queue.length > 0;
     useEffect(() => {
-        if (!enabled || !isOnline || queue.length === 0)
+        if (!enabled || !isOnline || !hasPendingMutations)
             return;
         const timer = setTimeout(() => {
             void sync();
         }, 100);
         return () => clearTimeout(timer);
-        // Only trigger on isOnline changes, not on every queue change
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [isOnline, enabled]);
+    }, [isOnline, enabled, hasPendingMutations, sync]);
     return useMemo(() => ({
         isOnline,
         enabled,

package/dist/hooks/usePageAssignment.d.ts

@@ -6,9 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  *
  * `usePageAssignment` — resolve the record PageSchema that should be rendered
- * for a given object. Walks the metadata cache exposed by `<MetadataProvider>`
- * and returns the first PageSchema whose `pageType === 'record'` and `object`
- * matches the requested name.
+ * for a given object. Walks the metadata cache exposed by `<MetadataProvider>`,
+ * keeps the PageSchemas whose `type === 'record'` and `object` matches the
+ * requested name, and returns the object's DEFAULT record page among them
+ * (`isDefault: true`), else the first of them.
  *
  * Returns a discriminated result by `PageSchema.kind`:
  *   - `kind === 'full'` (default): the schema fully describes the page;
@@ -18,10 +19,17 @@
  *     `buildDefaultPageSchema(objectDef, { slots })` so omitted slots
  *     fall through to synthesized defaults.
  *
- * Future work (deferred): recordType / profile / app / formFactor filtering
- * and priority-based selection. For now we return the first match so that
- * callers can deterministically fall back to the auto-generated DetailView
- * when no record Page is authored.
+ * Selection is by the declared `PageSchema.isDefault`, then by DECLARATION
+ * ORDER among pages that are not the default: the spec allows one default
+ * record page per object, so the flag needs no tie-break here, and with no
+ * default the first matching page wins. No match returns null, so callers can
+ * deterministically fall back to the auto-generated DetailView when no record
+ * Page is authored.
+ *
+ * Future work (deferred): recordType / profile / app / formFactor filtering.
+ * Any further author-driven ordering would have to be DECLARED on
+ * `PageSchema` in `@objectstack/spec` first — see the note on the selection
+ * itself below.
  */
 export interface PageAssignmentOptions {
     /** Salesforce-style record type filter (reserved for future use). */
@@ -59,6 +67,24 @@ export interface PageAssignmentResult {
     /** Loader error, if any. */
     error: Error | null;
 }
+/**
+ * True when `page` is a record page bound to `objectName`: its `type` is
+ * `'record'` and its `object` names that object.
+ *
+ * This is the ONE reading of "a record page of object O" in the console. The
+ * object-based lookup below filters its candidates with it, and a route that
+ * names a page explicitly (the console's named record page route,
+ * objectui#12715) asks it before rendering the named page for a record of O,
+ * so a name that is a page of another object, or not a record page at all, is
+ * refused rather than rendered. The `pageName` override of
+ * {@link usePageAssignment} does not ask it: that option returns the page with
+ * that name whatever it is, and a caller that renders a record on the page it
+ * gets back asks this first.
+ *
+ * `type` is the one discriminator, as the lookup's own comment explains
+ * (objectui#9674): `pageType` is a key `PageSchema` refuses, so it is not read.
+ */
+export declare function isRecordPageOf(page: unknown, objectName: string | undefined | null): boolean;
 /**
  * Resolve the record PageSchema for the given object name. Returns `null`
  * when no record Page is configured, signalling the caller to fall back

package/dist/hooks/usePageAssignment.js

@@ -6,9 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  *
  * `usePageAssignment` — resolve the record PageSchema that should be rendered
- * for a given object. Walks the metadata cache exposed by `<MetadataProvider>`
- * and returns the first PageSchema whose `pageType === 'record'` and `object`
- * matches the requested name.
+ * for a given object. Walks the metadata cache exposed by `<MetadataProvider>`,
+ * keeps the PageSchemas whose `type === 'record'` and `object` matches the
+ * requested name, and returns the object's DEFAULT record page among them
+ * (`isDefault: true`), else the first of them.
  *
  * Returns a discriminated result by `PageSchema.kind`:
  *   - `kind === 'full'` (default): the schema fully describes the page;
@@ -18,13 +19,44 @@
  *     `buildDefaultPageSchema(objectDef, { slots })` so omitted slots
  *     fall through to synthesized defaults.
  *
- * Future work (deferred): recordType / profile / app / formFactor filtering
- * and priority-based selection. For now we return the first match so that
- * callers can deterministically fall back to the auto-generated DetailView
- * when no record Page is authored.
+ * Selection is by the declared `PageSchema.isDefault`, then by DECLARATION
+ * ORDER among pages that are not the default: the spec allows one default
+ * record page per object, so the flag needs no tie-break here, and with no
+ * default the first matching page wins. No match returns null, so callers can
+ * deterministically fall back to the auto-generated DetailView when no record
+ * Page is authored.
+ *
+ * Future work (deferred): recordType / profile / app / formFactor filtering.
+ * Any further author-driven ordering would have to be DECLARED on
+ * `PageSchema` in `@objectstack/spec` first — see the note on the selection
+ * itself below.
  */
 import { useEffect, useMemo, useState } from 'react';
+import { defaultRecordPageObject } from '@objectstack/spec/ui';
 import { useMetadata } from '../context/AppShellContext.js';
+/**
+ * True when `page` is a record page bound to `objectName`: its `type` is
+ * `'record'` and its `object` names that object.
+ *
+ * This is the ONE reading of "a record page of object O" in the console. The
+ * object-based lookup below filters its candidates with it, and a route that
+ * names a page explicitly (the console's named record page route,
+ * objectui#12715) asks it before rendering the named page for a record of O,
+ * so a name that is a page of another object, or not a record page at all, is
+ * refused rather than rendered. The `pageName` override of
+ * {@link usePageAssignment} does not ask it: that option returns the page with
+ * that name whatever it is, and a caller that renders a record on the page it
+ * gets back asks this first.
+ *
+ * `type` is the one discriminator, as the lookup's own comment explains
+ * (objectui#9674): `pageType` is a key `PageSchema` refuses, so it is not read.
+ */
+export function isRecordPageOf(page, objectName) {
+    if (!page || typeof page !== 'object' || !objectName)
+        return false;
+    const p = page;
+    return p.type === 'record' && p.object === objectName;
+}
 function matchesAssignment(_page, _opts) {
     // Placeholder — every page matches until rules-based assignment lands.
     return true;
@@ -75,25 +107,57 @@ export function usePageAssignment(objectName, opts = {}) {
         const candidates = pages.filter(p => {
             if (!p)
                 return false;
-            // Only `pageType: 'record'` (or bare `type: 'record'`) is a
-            // user-facing record-detail page. Any other `pageType` — notably the
-            // designer-side `'record_detail'`, dropped from `PageType` in
-            // framework#2265 but still expressible in raw metadata — must NOT be
-            // picked up here, otherwise opening any record would render it.
-            const pt = p.pageType ?? (p.type === 'record' ? 'record' : undefined);
-            const isRecord = pt === 'record';
-            if (!isRecord)
-                return false;
-            if (p.object !== objectName)
+            // `type` is the ONE discriminator: only `type: 'record'` is a
+            // user-facing record-detail page, and every other page type
+            // (`home` / `app` / `utility` / `list`) is skipped.
+            //
+            // `pageType` is deliberately NOT read (objectui#9674). `PageSchema` is
+            // a `strictObject` that refuses `pageType` by name — it is a declared
+            // ALIAS of `type`, and a page carrying it is a hard parse error that
+            // names `type` as the key to write — so no page that parses carries it,
+            // and reading it would teach the refused spelling onward. A consumer-side
+            // alias for a refused key is the fallback AGENTS.md #0.1 rules out. The
+            // designer-side `'record_detail'` is not expressible either: it left
+            // `PageTypeSchema` (framework#2265), so `type: 'record_detail'` is an
+            // invalid enum value.
+            if (!isRecordPageOf(p, objectName))
                 return false;
             return matchesAssignment(p, opts);
         });
         if (!candidates.length)
             return null;
-        // Stable ordering: respect explicit `priority` if present (higher wins),
-        // otherwise fall back to declaration order.
-        candidates.sort((a, b) => (b?.priority ?? 0) - (a?.priority ?? 0));
-        return candidates[0];
+        // The object's DEFAULT record page decides; with none, declaration order.
+        //
+        // At most one `isDefault: true` record page may exist for an object in a
+        // deployment. That is the spec's rule on `PageSchema.isDefault` (maintainer
+        // ruling A on objectstack#23015, record 6134056653), and the platform
+        // refuses a second default, naming both pages, at every door that can add
+        // one: `defineStack` / `composeStacks` (so `os validate` and a source boot),
+        // package registration, and metadata save. So this hook honours the flag
+        // with NO tie-break of its own. It asks `defaultRecordPageObject`, the one
+        // reading of "the default record page of an object" each of those doors
+        // asks, so the page the platform judges to be the default is the page that
+        // opens. Replacing a platform record page stays an ADR-0005 overlay by name
+        // (the same page, not a second default) or host composition; neither a
+        // second default nor an earlier position in the served list overrides one.
+        //
+        // Boundary, stated rather than left implicit: at a cold boot every package
+        // registers before the environment's stored pages hydrate, so a stored
+        // default saved while no package held that object's default, and a package
+        // that adds one later, both reach the registry unrefused
+        // (objectstack#23213, closed not_planned). This hook invents no precedence
+        // for that pair (no layer, package or recency rung); served order stays the
+        // only order it has, so the first default served wins.
+        //
+        // Among pages that are not the default, declaration order is the last
+        // resort: the first match wins. This used to sort on a `priority` key read
+        // off the candidate. No author could ever set it: `PageSchema` is a
+        // `strictObject` and does not declare `priority`, so a page carrying one is
+        // a HARD PARSE ERROR, not a page that sorts first. Every candidate therefore
+        // read `0`, the comparator returned `0` for every pair, and a stable sort
+        // left declaration order untouched — the sort documented an affordance the
+        // schema refuses (objectui#7298).
+        return candidates.find(p => defaultRecordPageObject(p) === objectName) ?? candidates[0];
     }, [meta.pages, objectName, opts.pageName, opts.recordType, opts.profile, opts.app, opts.formFactor]);
     // Discriminate by `kind`: full pages populate `page`, slotted pages
     // populate `slots`. Missing `kind` defaults to 'full' for backwards

package/dist/hooks/useRecordSearch.d.ts

@@ -23,7 +23,10 @@ export interface RecordSearchHit {
      * objects. Stable across runs for the same (query, display) pair.
      */
     score: number;
-    /** Raw record payload, for callers that want extra context. */
+    /**
+     * Raw record payload, for callers that want extra context. It is the row as
+     * served: `fieldReadPolicy` gates the `display` label, not this payload.
+     */
     raw: any;
 }
 export interface UseRecordSearchOptions {
@@ -60,8 +63,38 @@ export interface UseRecordSearchOptions {
      * Optional display-name resolver. Defaults to the same `titleFormat`
      * fallback chain used by app-shell. Pass `getRecordDisplayName` from
      * `@object-ui/app-shell` to share that implementation exactly.
+     *
+     * Safe to pass inline: the resolver's identity never re-runs the search.
+     * Each run reads the resolver of the latest render, so a swapped resolver
+     * labels the hits of the next run; results already shown keep their labels.
      */
     getDisplayName?: (objectDef: any, record: any) => string;
+    /**
+     * Optional field-level read policy: pass `usePermissions()` from
+     * `@object-ui/permissions` (objectui#10500). Once it is loaded, a hit is
+     * labelled from its record with the fields the policy denies on the hit's
+     * object removed, `id` and `_id` kept. The row is gated BEFORE
+     * `getDisplayName` reads it, so a caller-supplied resolver is gated too. A
+     * denied field then reads exactly as an absent one and the resolver falls
+     * through to its next rung, the label a backend that strips denied fields
+     * (ObjectStack's `FieldMasker`) already yields. The rule is
+     * `withoutDeniedFields` from `@object-ui/core` (objectui#10594), the one the
+     * record title (objectui#10434) and the lookup option label (objectui#10411)
+     * call too.
+     *
+     * Omitted, or not loaded yet, the row is labelled as served. A title the
+     * server computed (`searchAll`'s `hit.title`) is the server's answer and is
+     * not re-judged here.
+     *
+     * Safe to pass inline: only `isLoaded` decides whether a run happens. When
+     * it changes the search re-runs, so hits labelled before the policy loaded
+     * are relabelled from the gated row. Otherwise each run reads the policy of
+     * the latest render, as it does `getDisplayName`.
+     */
+    fieldReadPolicy?: {
+        isLoaded: boolean;
+        checkField: (object: string, field: string, action: 'read') => boolean;
+    };
 }
 export interface UseRecordSearchResult {
     results: RecordSearchHit[];

package/dist/hooks/useRecordSearch.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useEffect, useMemo, useRef, useState } from 'react';
-import { getRecordDisplayName as defaultDisplayName } from '@object-ui/core';
+import { getRecordDisplayName as defaultDisplayName, withoutDeniedFields } from '@object-ui/core';
 import { errorCodeIs } from '@object-ui/types';
 // ADR-0079: the global-search default display-name resolver is now the ONE
 // shared `getRecordDisplayName` from `@object-ui/core` (honors titleFormat →
@@ -74,7 +74,10 @@ function scoreHit(query, display, recordId) {
  * `$filter` translation.
  */
 export function useRecordSearch(opts) {
-    const { query, objects, dataSource, objectNames, maxObjectsQueried = 8, topPerObject = 3, minLength = 2, debounceMs = 250, enabled = true, getDisplayName = defaultDisplayName, } = opts;
+    const { query, objects, dataSource, objectNames, maxObjectsQueried = 8, topPerObject = 3, minLength = 2, debounceMs = 250, enabled = true, getDisplayName = defaultDisplayName, fieldReadPolicy, } = opts;
+    // The one member of the read policy that decides whether a run happens: a
+    // primitive, so an inline policy object never re-runs the search by identity.
+    const policyLoaded = fieldReadPolicy?.isLoaded === true;
     const [results, setResults] = useState([]);
     const [isSearching, setIsSearching] = useState(false);
     const [error, setError] = useState(undefined);
@@ -111,11 +114,41 @@ export function useRecordSearch(opts) {
         }
         return pool;
     }, [objects, objectNames]);
+    // The object NAME is the whole signature: it is the only field of an object
+    // definition this effect consumes (`dataSource.find(obj.name, …)` and the
+    // `objects` whitelist sent to `searchAll`); `label` / `icon` are read per hit
+    // at render time and never decide whether the fanout re-runs.
+    //
+    // An `o?.titleField ?? ''` half used to be appended to each entry. It could
+    // never vary: `@objectstack/spec`'s object schema is a `strictObject` that
+    // REJECTS `titleField` with `unrecognized_keys` (objectui#6531), so no legal
+    // object metadata carries it and the half was permanently `''` — a constant
+    // suffix in a cache key, which also read as evidence that some producer ships
+    // the key. Removed in objectui#6557; the display name comes from
+    // `getRecordDisplayName`, which does not consult it either.
     const candidateSignature = useMemo(() => {
-        return candidates.map((o) => `${o?.name}:${o?.titleField ?? ''}`).join('|');
+        return candidates.map((o) => String(o?.name)).join('|');
     }, [candidates]);
     // Run ID for racing-request guarding. Stable across renders.
     const runIdRef = useRef(0);
+    // `getDisplayName` is caller-supplied and read only INSIDE a run, to label
+    // hits — it never decides whether a run happens. So the search effect reads
+    // the latest resolver through this ref and does not key on its identity
+    // (AGENTS.md §5 #10, objectui#10044). Keyed on it, an inline resolver (a new
+    // function every render) re-ran the effect on each render, and the cleanup
+    // cleared the pending debounce timer: renders faster than `debounceMs` never
+    // searched, and sparser renders issued a second identical request. Declared
+    // before the search effect, so it is current before any timer is armed.
+    //
+    // `fieldReadPolicy` is read the same way (objectui#10500): the run reads the
+    // latest policy through a ref, and only its `isLoaded` primitive
+    // (`policyLoaded`) is a dependency of the search effect.
+    const getDisplayNameRef = useRef(getDisplayName);
+    const fieldReadPolicyRef = useRef(fieldReadPolicy);
+    useEffect(() => {
+        getDisplayNameRef.current = getDisplayName;
+        fieldReadPolicyRef.current = fieldReadPolicy;
+    });
     useEffect(() => {
         if (!enabled || !dataSource || candidates.length === 0) {
             setResults([]);
@@ -142,7 +175,7 @@ export function useRecordSearch(opts) {
             // per-object `find({ $search })` fanout below only runs each object's
             // metadata-driven search (ADR-0061) and can miss records the global
             // search index knows about — the command-palette symptom in framework
-            // #3371, where `/api/v1/search` returned an account/opportunity the
+            // objectstack-ai/objectstack#3371, where `/api/v1/search` returned an account/opportunity the
             // palette never showed. When `searchAll` is absent (mock/test adapters,
             // non-ObjectStack backends) we fall back to the fanout.
             const searchAll = dataSource.searchAll;
@@ -184,7 +217,9 @@ export function useRecordSearch(opts) {
                             continue;
                         const objDef = byName.get(objectName) ?? { name: objectName };
                         const title = typeof h?.title === 'string' && h.title.trim() !== '' ? h.title.trim() : '';
-                        const display = title || getDisplayName(objDef, h?.record ?? {}) || `Record #${recordId}`;
+                        const display = title ||
+                            getDisplayNameRef.current(objDef, withoutDeniedFields(h?.record ?? {}, fieldReadPolicyRef.current, objectName)) ||
+                            `Record #${recordId}`;
                         const snippet = typeof h?.snippet === 'string' ? h.snippet.trim() : '';
                         hits.push({
                             objectName,
@@ -256,7 +291,7 @@ export function useRecordSearch(opts) {
                         const recordId = record?.id ?? record?._id;
                         if (recordId == null)
                             continue;
-                        const display = getDisplayName(obj, record);
+                        const display = getDisplayNameRef.current(obj, withoutDeniedFields(record, fieldReadPolicyRef.current, obj.name));
                         hits.push({
                             objectName: obj.name,
                             objectLabel: typeof obj.label === 'string' && obj.label.length > 0
@@ -290,7 +325,7 @@ export function useRecordSearch(opts) {
         maxObjectsQueried,
         minLength,
         debounceMs,
-        getDisplayName,
+        policyLoaded,
     ]);
     return { results, isSearching, error };
 }

package/dist/hooks/useResolvedFilter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 { type FilterTokenScope } from '@object-ui/core';
+/**
+ * Resolve a data node's own authored `filter` ONCE, and hold the result.
+ *
+ * Every context token the spec defines for filters (`{current_user_id}`,
+ * `{current_org_id}`, `{record_id}` where a record is in view, and the date
+ * macros such as `{today}`) is expanded by `@object-ui/core`'s shared
+ * `resolveFilterPlaceholders`, against the scope `useFilterScope()` reads: the
+ * session scope the host provides plus the mounted record's id
+ * (objectui#7297). Pass `useFilterScope()` as `scope`:
+ *
+ * ```tsx
+ * const filterScope = useFilterScope();
+ * const filter = useResolvedFilter(schema.filter, filterScope);
+ * // query with `filter`, and key the fetch effect on `filter`, never on schema.filter
+ * ```
+ *
+ * ⛔ Not a second resolver, and no fallback: a token the scope cannot resolve
+ * is whatever `resolveFilterPlaceholders` makes of it (left intact, with one
+ * warning naming it).
+ *
+ * The result is HELD against its inputs, the shape `plugin-view`'s
+ * `useResolvedFilterSegments` uses. A fetch effect keys on this filter, so a
+ * resolved copy minted on every render would refetch on every render; and a
+ * date macro such as `{now}` resolves to a new value at every call, so
+ * comparing OUTPUTS cannot stop that. The key is the authored filter, compared
+ * by structure (a host that rebuilds an equal filter inline must not
+ * re-query), plus each scope member read one by one (`recordId` among them,
+ * so moving to another record resolves again), never the scope object's
+ * identity (AGENTS.md #10). The held pair lives in state, so the
+ * value handed out is always the one React committed. A structurally different
+ * filter, or a changed scope member, resolves again and hands out a new value.
+ *
+ * A filter the resolver leaves unchanged (no token, or only tokens the scope
+ * cannot resolve) is handed out as the authored value itself, not as the
+ * resolver's equal copy, so a token-free filter reaches the query exactly as
+ * it did before any resolution.
+ */
+export declare function useResolvedFilter<T>(authored: T, scope: FilterTokenScope): T;

package/dist/hooks/useResolvedFilter.js

@@ -0,0 +1,130 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The ONE hold every data node uses to resolve its OWN authored `filter`
+ * (objectui#10666). PR objectui#10656 wrote it for `list-view`
+ * (`useResolvedAuthoredFilter`, local to `ListView.tsx`); PR objectui#10705
+ * moved it into a module of `plugin-list` for `object-gallery`; the sweep that
+ * closed objectui#10666 moved it here, beside `useFilterScope`, so the nine
+ * packages whose nodes send their own filter share one copy instead of growing
+ * nine. The hold, its key and its comparator moved unchanged; the one addition
+ * is that a filter the resolver leaves unchanged is handed out as authored (see
+ * `resolveHeldFilter`).
+ */
+import * as React from 'react';
+import { resolveFilterPlaceholders } from '@object-ui/core';
+function resolveHeldFilter(authored, scope) {
+    const resolved = resolveFilterPlaceholders(authored, scope);
+    return {
+        authored,
+        currentUserId: scope.currentUserId,
+        currentOrgId: scope.currentOrgId,
+        recordId: scope.recordId,
+        onUnresolved: scope.onUnresolved,
+        // `resolveFilterPlaceholders` copies every array and plain object it walks,
+        // so a filter with nothing to resolve comes back EQUAL but not the same
+        // reference. Such a filter is handed out as authored: a node whose filter
+        // carries no token sends the very value it was given, as it did before it
+        // resolved anything (the `object-kanban` / `object-calendar` / `object-tree`
+        // member pins read `$filter` by identity). Only a filter the resolver
+        // actually changed is handed out as the resolved copy.
+        resolved: isSameAuthoredFilter(resolved, authored) ? authored : resolved,
+    };
+}
+/** Depth past which {@link isSameAuthoredFilter} gives up and answers "changed". */
+const AUTHORED_FILTER_MAX_DEPTH = 12;
+function isPlainFilterObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Compare two authored filters by structure, never by serialising them.
+ *
+ * The same rules as `plugin-view`'s `isStructurallyEqual` (objectui#6460):
+ * primitives by `Object.is`, a `Date` by its instant, arrays element by
+ * element and in order, plain objects by key set and value. Anything else is
+ * equal only as the same reference, and a structure deeper than the bound is
+ * "changed". Every uncertainty answers "changed", which re-resolves and
+ * re-queries; the comparison can drop a redundant query, never a needed one.
+ */
+function isSameAuthoredFilter(a, b, depth = 0) {
+    if (Object.is(a, b))
+        return true;
+    if (depth >= AUTHORED_FILTER_MAX_DEPTH)
+        return false;
+    if (a instanceof Date || b instanceof Date) {
+        return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+    }
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, i) => isSameAuthoredFilter(item, b[i], depth + 1));
+    }
+    if (isPlainFilterObject(a) && isPlainFilterObject(b)) {
+        const keys = Object.keys(a);
+        if (keys.length !== Object.keys(b).length)
+            return false;
+        return keys.every((key) => (Object.prototype.hasOwnProperty.call(b, key) && isSameAuthoredFilter(a[key], b[key], depth + 1)));
+    }
+    return false;
+}
+/**
+ * Resolve a data node's own authored `filter` ONCE, and hold the result.
+ *
+ * Every context token the spec defines for filters (`{current_user_id}`,
+ * `{current_org_id}`, `{record_id}` where a record is in view, and the date
+ * macros such as `{today}`) is expanded by `@object-ui/core`'s shared
+ * `resolveFilterPlaceholders`, against the scope `useFilterScope()` reads: the
+ * session scope the host provides plus the mounted record's id
+ * (objectui#7297). Pass `useFilterScope()` as `scope`:
+ *
+ * ```tsx
+ * const filterScope = useFilterScope();
+ * const filter = useResolvedFilter(schema.filter, filterScope);
+ * // query with `filter`, and key the fetch effect on `filter`, never on schema.filter
+ * ```
+ *
+ * ⛔ Not a second resolver, and no fallback: a token the scope cannot resolve
+ * is whatever `resolveFilterPlaceholders` makes of it (left intact, with one
+ * warning naming it).
+ *
+ * The result is HELD against its inputs, the shape `plugin-view`'s
+ * `useResolvedFilterSegments` uses. A fetch effect keys on this filter, so a
+ * resolved copy minted on every render would refetch on every render; and a
+ * date macro such as `{now}` resolves to a new value at every call, so
+ * comparing OUTPUTS cannot stop that. The key is the authored filter, compared
+ * by structure (a host that rebuilds an equal filter inline must not
+ * re-query), plus each scope member read one by one (`recordId` among them,
+ * so moving to another record resolves again), never the scope object's
+ * identity (AGENTS.md #10). The held pair lives in state, so the
+ * value handed out is always the one React committed. A structurally different
+ * filter, or a changed scope member, resolves again and hands out a new value.
+ *
+ * A filter the resolver leaves unchanged (no token, or only tokens the scope
+ * cannot resolve) is handed out as the authored value itself, not as the
+ * resolver's equal copy, so a token-free filter reaches the query exactly as
+ * it did before any resolution.
+ */
+export function useResolvedFilter(authored, scope) {
+    const [held, setHeld] = React.useState(() => resolveHeldFilter(authored, scope));
+    if (held.currentUserId !== scope.currentUserId
+        || held.currentOrgId !== scope.currentOrgId
+        || held.recordId !== scope.recordId
+        || held.onUnresolved !== scope.onUnresolved
+        || !isSameAuthoredFilter(held.authored, authored)) {
+        // React's documented "information from previous renders" shape: a set
+        // during render re-renders this component at once, before any child sees
+        // the discarded pass, and the re-render finds the inputs equal.
+        const next = resolveHeldFilter(authored, scope);
+        setHeld(next);
+        return next.resolved;
+    }
+    return held.resolved;
+}