@object-ui/react 17.6.0 → 18.0.0

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

package/dist/hooks/useSettledSchema.js

@@ -0,0 +1,186 @@
+/**
+ * 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 { useEffect, useState } from 'react';
+/**
+ * Is this refetch's answer the SAME answer, by value, as the one already
+ * published?
+ *
+ * Used for exactly one decision — whether a settle republishes or keeps the
+ * object consumers already hold — and its failure direction is chosen for
+ * that decision. A false NEGATIVE (two encodings of the same metadata that
+ * serialise differently, e.g. with the keys in another order) republishes,
+ * which is precisely what this hook did for every answer before
+ * objectui#10106: no consumer can be worse off than it already was. A false
+ * POSITIVE would withhold a genuinely new definition from consumers, so the
+ * comparison is deliberately a whole-payload one and never a sampled or
+ * shallow test.
+ *
+ * ⚠️ An answer JSON cannot express — a cycle, a `BigInt` — makes
+ * `JSON.stringify` throw; that is answered as "not equal" rather than allowed
+ * to escape into a state updater, which lands on the safe side above.
+ */
+function isEqualPayload(a, b) {
+    if (Object.is(a, b))
+        return true;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function useSettledSchema(key, dataSource) {
+    const [resolution, setResolution] = useState(null);
+    useEffect(() => {
+        let isMounted = true;
+        const settleKey = key;
+        /**
+         * Settle THIS effect run's resolution — and, when the answer is one
+         * consumers already hold, settle it as the object they already hold.
+         *
+         * This is the PRODUCER half of `AGENTS.md` §5 commandment #10: *"a
+         * provider that refetches may not republish an equal payload as a new
+         * object, and a consumer that needs stability keys on the data, not on a
+         * cache"*. This hook refetches whenever the adapter identity changes, and
+         * the consumers its own `@example` instructs do exactly what the other
+         * half of that sentence asks — they key their record fetch on `def`, the
+         * payload, never on a memo identity. So a fresh object for an unchanged
+         * answer is not a wasted allocation; it is a DUPLICATE RECORD QUERY at
+         * every one of them, carrying the same expand set as the one before it.
+         * Pinned with its control in
+         * `useSettledSchema.equalPayload-10106.test.tsx` (objectui#10106).
+         *
+         * ⛔ The cure may NOT be moved to the consumer — the same sentence names
+         * keying on a cache as the wrong one, and a consumer that stopped keying
+         * on `def` would also stop re-querying when the definition genuinely
+         * changes, which the control case in that pin holds open.
+         *
+         * Bailing out is only ever safe for the SAME key: `resolution` is one
+         * piece of state whose `key` decides `ready`, so a settle for a different
+         * key must always publish (see the hook doc comment above).
+         */
+        const settle = (settledDef) => {
+            setResolution((prev) => prev && prev.key === settleKey && isEqualPayload(prev.def, settledDef)
+                ? prev
+                : { key: settleKey, def: settledDef });
+        };
+        const resolve = async () => {
+            if (!dataSource || !settleKey || typeof dataSource.getObjectSchema !== 'function') {
+                // No source for a definition: settle with none, so anything gated on
+                // `ready` still runs (unexpanded — with no schema there is no expand
+                // set to derive).
+                if (isMounted)
+                    settle(null);
+                return;
+            }
+            try {
+                const def = await dataSource.getObjectSchema(settleKey);
+                if (isMounted)
+                    settle(def);
+            }
+            catch (err) {
+                console.error('[useSettledSchema] getObjectSchema failed for', settleKey, err);
+                if (isMounted)
+                    settle(null);
+            }
+        };
+        resolve();
+        return () => {
+            isMounted = false;
+        };
+    }, [key, dataSource]);
+    const ready = resolution !== null && resolution.key === key;
+    const def = ready ? resolution.def : null;
+    return { ready, def };
+}

package/dist/hooks/useViewData.d.ts

@@ -37,8 +37,13 @@ export interface UseViewDataResult<T = any> {
     dataSource: DataSource<T> | null;
     /** Re-fetch data with current or new params */
     refresh: (newParams?: QueryParams) => Promise<void>;
-    /** Fetch a single record by ID */
-    fetchOne: (id: string | number) => Promise<T | null>;
+    /**
+     * Fetch a single record by ID. The id is a `string`, as every record door on
+     * `DataSource` declares it — this hook hands the value straight to
+     * `DataSource.findOne`, so the union it used to admit was a claim the
+     * protocol never made (objectui#9511).
+     */
+    fetchOne: (id: string) => Promise<T | null>;
     /** Whether more records are available */
     hasMore: boolean;
 }
@@ -50,8 +55,10 @@ export interface UseViewDataResult<T = any> {
  *
  * 1. Resolves the ViewData config to the right DataSource adapter
  *    - `provider: 'object'` → context DataSource (ObjectStackAdapter)
- *    - `provider: 'api'`    → ApiDataSource (raw HTTP)
  *    - `provider: 'value'`  → ValueDataSource (in-memory)
+ *    The view-level `provider: 'api'` is retired in `@objectstack/spec`
+ *    (objectstack#23082) and has no arm in `resolveDataSource`: a block that
+ *    still names it is an unknown provider there (objectui#12325).
  * 2. Fetches data automatically on mount
  * 3. Provides loading/error states and refresh capability
  *

package/dist/hooks/useViewData.js

@@ -22,8 +22,10 @@ import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
  *
  * 1. Resolves the ViewData config to the right DataSource adapter
  *    - `provider: 'object'` → context DataSource (ObjectStackAdapter)
- *    - `provider: 'api'`    → ApiDataSource (raw HTTP)
  *    - `provider: 'value'`  → ValueDataSource (in-memory)
+ *    The view-level `provider: 'api'` is retired in `@objectstack/spec`
+ *    (objectstack#23082) and has no arm in `resolveDataSource`: a block that
+ *    still names it is an unknown provider there (objectui#12325).
  * 2. Fetches data automatically on mount
  * 3. Provides loading/error states and refresh capability
  *
@@ -44,30 +46,19 @@ import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
  */
 export function useViewData(options) {
     const { viewData, resource = '', params, dataSource: explicitDataSource, adapterOptions, skip = false, } = options;
-    // Get context DataSource + host-authenticated fetch
+    // Get context DataSource
     const context = useContext(SchemaRendererContext);
     const contextDataSource = context?.dataSource ?? null;
-    const contextApiFetch = context?.apiFetch;
     // Resolve the DataSource — memoize to prevent re-creation on every render.
     // We key on the viewData provider + config identity.
     const resolvedDataSource = useMemo(() => {
         if (explicitDataSource)
             return explicitDataSource;
-        // Default the 'api' provider's fetch to the host's authenticated fetch
-        // (SchemaRendererContext.apiFetch) so custom endpoints carry the same
-        // credentials as native requests; explicit adapterOptions still win.
-        return resolveDataSource(viewData, contextDataSource, {
-            fetch: contextApiFetch,
-            ...adapterOptions,
-        });
+        return resolveDataSource(viewData, contextDataSource, adapterOptions);
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [
         explicitDataSource,
-        contextApiFetch,
         viewData?.provider,
-        // For 'api' provider, key on read/write URLs
-        viewData?.provider === 'api' ? viewData.read?.url : undefined,
-        viewData?.provider === 'api' ? viewData.write?.url : undefined,
         // For 'value' provider, key on items reference (or length as proxy)
         viewData?.provider === 'value' ? viewData.items?.length : undefined,
         contextDataSource,

package/dist/index.d.ts

@@ -10,10 +10,18 @@ export * from './schema-input.js';
 export * from './hooks/index.js';
 export * from './context/index.js';
 export * from './LazyPluginLoader.js';
-export * from './spec-bridge/index.js';
 export * from './data-invalidation.js';
 export * from './element-data-source/ElementDataSourceGate.js';
+export * from './element-data-source/useElementApiDataSource.js';
 export { resolveKeyedI18nLabel } from './utils/i18n.js';
+export { resolveInlineAriaProps } from './utils/inlineAria.js';
+export { isConfigBag } from './utils/configBag.js';
+export { reportUnresolvableVisibilityPredicate, formatUnresolvableVisibilityMessage, UNRESOLVABLE_VISIBILITY_PREFIX, UNRESOLVABLE_ENABLEMENT_PREFIX, __resetVisibilityPredicateWarnings, } from './utils/visibilityDiagnostic.js';
+export type { PredicateScopeTier } from './utils/visibilityDiagnostic.js';
+export type { PredicateGateKind } from './utils/visibilityDiagnostic.js';
 export { extractWriteErrorMessage, isPermissionError, extractFieldErrors, classifyLoadError, declaredUserMessage } from './utils/error-message.js';
 export type { WriteFieldError, LoadErrorKind } from './utils/error-message.js';
 export { I18nProvider, useObjectTranslation, useSafeTranslate, useObjectLabel, useSafeFieldLabel, useI18nContext, createI18n, getDirection, getAvailableLanguages, formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type I18nConfig, type I18nProviderProps, type TranslationKeys, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from '@object-ui/i18n';
+export { NON_GRID_ROW_CEILING, applyNonGridRowCeiling } from '@object-ui/core';
+export type { NonGridCeilingResult } from '@object-ui/core';
+export { NonGridRowCeilingNote } from './utils/nonGridRowCeiling.js';