@object-ui/react 17.5.0 → 17.7.0

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;
+}

package/dist/hooks/useSchemaPersistence.d.ts

@@ -63,6 +63,13 @@ export declare function createLocalStorageAdapter(prefix?: string): SchemaPersis
  * Accepts a pluggable adapter for connecting to any backend.
  * Falls back to a localStorage adapter for development use.
  *
+ * `save()` refuses a schema carrying function-valued keys anywhere in it —
+ * every adapter ends in a `JSON.stringify`, which drops callables silently, so
+ * the save would report success and the reload would hand back a schema that
+ * lost them. The refusal sets `error` (naming the offending key paths and both
+ * escapes), returns `null`, leaves `lastSavedAt` untouched, and never reaches
+ * the adapter. Fully declarative schemas are unaffected.
+ *
  * @example
  * ```tsx
  * // With default localStorage adapter

package/dist/hooks/useSchemaPersistence.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 { useState, useCallback, useRef, useMemo } from 'react';
+import { useState, useCallback, useRef, useMemo, useInsertionEffect } from 'react';
 /**
  * Default localStorage adapter for schema persistence.
  * Useful for development and demos.
@@ -51,6 +51,96 @@ export function createLocalStorageAdapter(prefix = 'objectui-schema') {
         },
     };
 }
+/**
+ * Cap on how many offending paths the refusal message spells out in full. A
+ * schema that puts callables on every row would otherwise produce an error
+ * string nobody can read; the count is always reported exactly.
+ */
+const MAX_REPORTED_CALLABLE_PATHS = 20;
+/**
+ * Collect the path of every function-valued property reachable in `value`.
+ *
+ * Walks own enumerable properties — the same set `JSON.stringify` serializes —
+ * so what this finds is exactly what `JSON.stringify` would fail to preserve.
+ * It fails in TWO different ways, and neither says a word. Both are visible in
+ * a single document:
+ *
+ *     JSON.stringify({ columns: [{ name: 'c', cell: fn }, fn] })
+ *     // => {"columns":[{"name":"c"},null]}
+ *     //    the object key `cell` is DROPPED; the array element is COERCED to null
+ *
+ * The array case is arguably the worse of the two. A dropped key at least
+ * disappears, so a reader of the stored document can see something is missing;
+ * a coerced `null` survives as a plausible-looking value and reads as real data
+ * on reload. That is why arrays are walked by index (`columns[2].cell`) rather
+ * than skipped — and it is the realistic shape besides, since handlers live on
+ * column/field entries, not only at the top level.
+ *
+ * A `seen` set keeps a cyclic schema from recursing forever (`JSON.stringify`
+ * throws on those; this guard runs first and must not hang before it can). It
+ * also means a subtree reachable by two paths is reported at the first one
+ * only — the refusal is still correct, the path list is just not exhaustive for
+ * shared references.
+ */
+function collectCallablePaths(value, path, out, seen) {
+    if (typeof value === 'function') {
+        out.push(path || '(root)');
+        return;
+    }
+    if (value === null || typeof value !== 'object')
+        return;
+    if (seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => collectCallablePaths(item, `${path}[${index}]`, out, seen));
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        collectCallablePaths(child, path ? `${path}.${key}` : key, out, seen);
+    }
+}
+/**
+ * The paths of the function-valued keys anywhere in a schema, in walk order.
+ * Empty means the schema is fully declarative and serializes without loss.
+ *
+ * Two corners worth knowing, both measured, neither a reason to loosen this:
+ *
+ * - `Object.entries` INVOKES getters. A schema with a throwing getter therefore
+ *   throws inside this guard rather than inside the adapter's `JSON.stringify`.
+ *   Different call site, same outcome: `save()` refuses and surfaces the
+ *   getter's own error.
+ * - A schema carrying its own `toJSON` method is refused, even though
+ *   `JSON.stringify` would have serialized it THROUGH that method. That is a
+ *   deliberate false positive: the method itself cannot survive the round trip,
+ *   so what `load()` hands back would not be the object that was saved.
+ */
+function findCallablePaths(schema) {
+    const out = [];
+    collectCallablePaths(schema, '', out, new Set());
+    return out;
+}
+/**
+ * The refusal an author sees instead of a save that quietly lost their handler.
+ *
+ * It names the exact offending paths and both escapes, because an error that
+ * only says "no" leaves the author guessing at a defect whose symptom would
+ * otherwise have surfaced at render or click time, in another component, with
+ * no link back to the save that caused it.
+ */
+function callableRefusalMessage(id, paths) {
+    const shown = paths.slice(0, MAX_REPORTED_CALLABLE_PATHS);
+    const listed = shown.join(', ');
+    const elided = paths.length > shown.length ? ` (and ${paths.length - shown.length} more)` : '';
+    const plural = paths.length === 1 ? 'key is' : 'keys are';
+    return (`useSchemaPersistence: refusing to save schema "${id}" — ` +
+        `${paths.length} function-valued ${plural} not serializable: JSON.stringify ` +
+        `silently drops an object key, or coerces an array element to null. ` +
+        `Offending paths: ${listed}${elided}. ` +
+        'Two ways forward: strip the callables before saving (persist only the serializable ' +
+        'data and re-attach the handlers after load), or express the behaviour in the ' +
+        'declarative form of these keys so it survives the round trip.');
+}
 /**
  * Hook for persisting designer schemas (save/load/list/delete).
  * Implements schema persistence for @object-ui/plugin-designer.
@@ -58,6 +148,13 @@ export function createLocalStorageAdapter(prefix = 'objectui-schema') {
  * Accepts a pluggable adapter for connecting to any backend.
  * Falls back to a localStorage adapter for development use.
  *
+ * `save()` refuses a schema carrying function-valued keys anywhere in it —
+ * every adapter ends in a `JSON.stringify`, which drops callables silently, so
+ * the save would report success and the reload would hand back a schema that
+ * lost them. The refusal sets `error` (naming the offending key paths and both
+ * escapes), returns `null`, leaves `lastSavedAt` untouched, and never reaches
+ * the adapter. Fully declarative schemas are unaffected.
+ *
  * @example
  * ```tsx
  * // With default localStorage adapter
@@ -80,10 +177,45 @@ export function createLocalStorageAdapter(prefix = 'objectui-schema') {
  * ```
  */
 export function useSchemaPersistence(adapter) {
-    const defaultAdapter = useRef(createLocalStorageAdapter());
-    const adapterRef = useRef(adapter ?? defaultAdapter.current);
-    // Keep the ref up to date if the adapter prop changes
-    adapterRef.current = adapter ?? defaultAdapter.current;
+    // Built once per hook instance. `useRef(createLocalStorageAdapter())` ran the
+    // factory on EVERY render and discarded all but the first result; `useMemo`
+    // runs it once and — unlike a ref — needs no `.current` read during render.
+    // Re-creating it would be harmless either way: the adapter is a stateless
+    // facade over `localStorage`, so a fresh one behaves identically to the one
+    // it replaces, and nothing outside this hook ever sees its identity.
+    const defaultAdapter = useMemo(() => createLocalStorageAdapter(), []);
+    const resolvedAdapter = adapter ?? defaultAdapter;
+    // The four callbacks below are created once (`[]` deps) and read the adapter
+    // at CALL time, so the latest adapter must reach them without changing their
+    // identity. That is the whole job of this ref.
+    //
+    // The write lives in `useInsertionEffect` — not in the render body, where it
+    // used to be, and not in `useEffect`/`useLayoutEffect`:
+    //
+    //   - Render body: a render React discards or replays (StrictMode, a
+    //     Suspense retry, a concurrent interruption) still performed the write,
+    //     so a save could be routed through an adapter from a render that never
+    //     committed. That is what `react-hooks/refs` flags.
+    //   - `useEffect`: runs after paint, so a call made from any layout effect in
+    //     the same commit would still reach the PREVIOUS adapter.
+    //   - `useLayoutEffect`: a child's layout effects run BEFORE its parent's, so
+    //     a child calling `save()` from its own layout effect would still see the
+    //     previous adapter.
+    //
+    // Insertion effects run in the mutation phase — before every layout effect in
+    // the tree, before paint, and before any event handler can fire — so every
+    // call site that may legally invoke `save`/`load`/`list`/`remove` observes
+    // exactly what the old render-body write gave it. The single window that did
+    // change is a read during the render phase itself, which no legal consumer
+    // has: these calls are side effects and are never allowed during render.
+    //
+    // `useSchemaPersistence.adapterTracking.test.tsx` pins both halves — that a
+    // changed `adapter` prop is tracked, and that it is already in place by the
+    // time a child's layout effect runs in that same commit.
+    const adapterRef = useRef(resolvedAdapter);
+    useInsertionEffect(() => {
+        adapterRef.current = resolvedAdapter;
+    }, [resolvedAdapter]);
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
     const [isDirty, setIsDirty] = useState(false);
@@ -92,6 +224,13 @@ export function useSchemaPersistence(adapter) {
         setLoading(true);
         setError(null);
         try {
+            // Refuse BEFORE the adapter runs, so the guard covers a host-injected or
+            // REST adapter too — every one of them ends in a `JSON.stringify` that
+            // drops callables without a word (objectui#6658).
+            const callablePaths = findCallablePaths(schema);
+            if (callablePaths.length > 0) {
+                throw new Error(callableRefusalMessage(id, callablePaths));
+            }
             const result = await adapterRef.current.save(id, schema);
             setIsDirty(false);
             setLastSavedAt(new Date());

package/dist/hooks/useSettledSchema.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 { DataSource } from '@object-ui/types';
+/**
+ * The settled result of `{@link useSettledSchema}`: whether the object
+ * definition for the CURRENT key has finished resolving, and the definition
+ * itself once it has.
+ *
+ * `ready` is never a fact about "a fetch completed" in isolation — it is
+ * "a fetch completed FOR THE OBJECT THIS RENDER IS ASKING ABOUT". See the
+ * hook's own doc comment for why that distinction is the entire point.
+ */
+export interface SettledSchema<TDef = unknown> {
+    /**
+     * `true` once the object definition for the key passed to this render has
+     * settled — successfully, with a thrown read, or because there was no
+     * source to read from. `false` while it is still in flight, and also
+     * `false` for exactly one render right after `key` changes, even if a
+     * PREVIOUS key's resolution is sitting in state (objectui#6481's defect,
+     * made unwritable — see the hook doc comment).
+     */
+    ready: boolean;
+    /**
+     * The resolved definition once `ready` is `true`, otherwise `null`.
+     * `null` while `ready` is `true` is a legitimate, DISTINCT outcome from
+     * "not ready yet" — it means the resolution settled with nothing (no
+     * `dataSource`, no `getObjectSchema`, no key, or a read that threw), not
+     * that the read never happened.
+     */
+    def: TDef | null;
+}
+/**
+ * Resolves an object's schema/definition and tracks whether that resolution
+ * has SETTLED for the object CURRENTLY being asked about — one piece of
+ * state a caller cannot observe half of.
+ *
+ * ## The shape, and why it is exactly this one
+ *
+ * This is the RESOLUTION half of the settled-schema gate four views
+ * (`ObjectKanban`, `ObjectView`, `ObjectCalendar`, and — pre-fix —
+ * `ObjectTree`) each hand-wrote (objectui#6271, #6419, #6453, #6014). Ruled
+ * objectui#6482 (maintainer, 2026-08-27, Option A): extract the resolution
+ * half as a shared, published hook; leave GATE PLACEMENT — deciding which
+ * effect branch actually waits on `ready` — to each component, because that
+ * part is genuinely component-private (`ObjectCalendar` gates only its
+ * `object`-provider branch and keys on the object the block RESOLVES rather
+ * than on `schema.objectName`, because an inline `value` data set issues no
+ * metadata read at all — a whole-effect gate would hold its query open on a
+ * resolution nothing was ever going to produce).
+ *
+ * `ready` is DERIVED at render time — `resolution !== null && resolution.key
+ * === key` — from a SINGLE piece of state, `{ key, def } | null`, rather than
+ * stored as a second, independent boolean. That is not a style choice; it is
+ * the fix for the defect this card exists to close. objectui#6481's
+ * `ObjectTree` carried the definition (`objectSchema`) and "has it settled"
+ * (`schemaSettled`) as two SEPARATE `useState`s. `schemaSettled` was a
+ * one-way latch — set `true` on first settle and never reset — so when the
+ * host swapped `objectName` mid-life, the fetch effect re-ran and started
+ * refetching the NEW object's schema, but `schemaSettled` stayed `true` from
+ * the OLD object's settle. The gated effect read `schemaSettled === true`
+ * and `objectSchema` still holding the OLD object's fields, and queried with
+ * the WRONG `$expand` — a stale key reading as ready.
+ *
+ * With one state value and a render-time key comparison, that failure mode
+ * is not merely fixed, it is UNREPRESENTABLE: the instant `key` changes,
+ * `resolution.key === key` is false in that very render (no effect needs to
+ * run first), so `ready` flips to `false` in the same commit the key
+ * changed — there is no window, and no second piece of state a caller could
+ * read out of sync with the first, because there is no second piece of
+ * state. A caller cannot spell "ready for the wrong object": `ready` and
+ * `def` are two views of one value, never independently settable.
+ *
+ * Every exit of the internal fetch effect settles the resolution — success,
+ * a thrown read, and "there is no source to read from" alike — because a
+ * caller's gated effect WAITS on `ready`. An exit that returned without
+ * settling would not merely skip the expansion; it would hold that gated
+ * query open forever.
+ *
+ * ## What this hook does NOT do
+ *
+ * It does not decide when to fetch beyond "when `key` or `dataSource`
+ * change", and it does not decide what a caller's OTHER effects should wait
+ * on. A caller that should not fetch at all for the current render (e.g.
+ * `ObjectCalendar`'s inline `value` provider, which issues no metadata read)
+ * passes `dataSource: undefined` for that render rather than a new "should
+ * fetch" flag — the hook already settles-with-`null` whenever `dataSource`
+ * is absent, which is the exact "no source to read from" outcome that case
+ * needs.
+ *
+ * @param key - The identity of the object THIS render is asking about — for a
+ *   record-bound view, `resolveRecordSourceObjectName(schema, dataConfig) ?? ''`
+ *   from `@object-ui/core`. ⛔ Do NOT re-spell that ladder inline here: six view
+ *   plugins each carried their own copy and had drifted, which is the whole of
+ *   what `b041b9c0c` collapsed. Choosing the key is still the caller's job — it is the
+ *   component-private half of the original hand copies, not something this hook
+ *   can infer — but the ladder behind it is published and shared.
+ * @param dataSource - The data source to read the definition from. Pass
+ *   `undefined`/`null` for a render that should settle immediately with no
+ *   definition (no source, or a provider that needs none) rather than adding
+ *   a separate enable flag.
+ * @returns `{ ready, def }` — see {@link SettledSchema}.
+ *
+ * @example
+ * ```tsx
+ * const schemaKey = resolveRecordSourceObjectName(schema, dataConfig); // @object-ui/core
+ * const { ready: objectSchemaReady, def: objectSchema } =
+ *   useSettledSchema(schemaKey ?? '', hasInlineData ? undefined : dataSource);
+ *
+ * useEffect(() => {
+ *   // A PROVIDER test, not an object-name read — it asks "is there metadata to
+ *   // wait for at all", which the shared reader deliberately does not answer.
+ *   // Gate placement stays local (objectui#6482); the ladder does not.
+ *   if (dataConfig?.provider === 'object' && !objectSchemaReady) return;
+ *   // ...issue the record query, `buildExpandFields(objectSchema?.fields)`
+ * }, [objectSchemaReady, objectSchema, /* ... *\/]);
+ * ```
+ */
+export declare function useSettledSchema<TDef = unknown>(key: string, dataSource: DataSource<any> | null | undefined): SettledSchema<TDef>;