@object-ui/react 17.6.0 → 17.7.0

package/dist/hooks/useExpression.js

@@ -6,12 +6,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { createContext, createElement, useContext, useMemo } from 'react';
-import { ExpressionEvaluator, evalRowPredicate, isLegacyDialectSource, warnNonCanonicalRowSpelling, } from '@object-ui/core';
+import { ExpressionEvaluator, evalRowPredicate } from '@object-ui/core';
 /**
  * Global predicate scope — populated by host shells (e.g. app-shell's
  * `ExpressionProvider`) so renderers like action buttons can resolve
- * deployment-level flags (`features`, `user`, `app`, …) without needing
- * to import the host shell directly.
+ * deployment-level flags (`features`, `user`, …) without needing
+ * to import the host shell directly. (⛔ Not `app`: objectui#8155 removed that
+ * root from `buildExpressionScope`, so no host shell in this repo publishes
+ * one.)
  *
  * `useCondition` / `useExpression` merge this scope under the
  * locally-passed `context`, so per-row `record` overrides still win.
@@ -74,56 +76,49 @@ export { toPredicateInput } from '@object-ui/core';
  * Build the predicate context for a **row record** — the bag to hand
  * {@link useCondition} when the thing being gated is scoped to one record.
  *
- * The row is bound the THREE ways the platform's row surfaces bind it:
- * `record.status` (spec/canonical), bare `status` (row-action shorthand), and
- * `data.status` (legacy). This is not three dialects; it is one rule, and it is
- * `evalRowPredicate`'s rule (`core/evaluator/listConditional.ts` — the record
- * header, list rows, the row kebab and conditional formatting all evaluate
- * through it), restated here for the `useCondition` tier so both tiers answer
- * an author's `visible:` the same way.
+ * The row is bound ONE way: `record.status` — the canon (objectui#5330, ruled
+ * 2026-08-20; Phase 2 executed by `83fe6e741`). This is not a dialect choice;
+ * it is one rule, and it is `evalRowPredicate`'s rule
+ * (`core/evaluator/listConditional.ts` — the record header, list rows, the row
+ * kebab and conditional formatting all evaluate through it), restated here for
+ * the `useCondition` tier so both tiers answer an author's `visible:` the same
+ * way.
  *
- * ## Why a helper and not "just spread the row" (objectui#4075)
+ * ## The two retired spellings (`83fe6e741`)
  *
- * `useCondition` evaluates on `new ExpressionEvaluator({ ...scope, ...context })`,
- * so a caller that passes the row spread flat resolves the shorthand spelling
- * and NOTHING else. The canonical spelling is the `record.` root — it is what
- * `ExpressionEvaluator`'s CEL path binds (`bag.record` as the record
- * namespace), what `evalRowPredicate` binds, and what the server enforces
- * with. Under a root-only bag `record.viewer.can_act` does not read as `false`:
- * the evaluator throws `record is not defined`, and a fail-closed `visible`
- * turns that throw into "hidden". A correctly-authored predicate then deletes
- * its own button, indistinguishably from the gate having said no.
+ * Until Phase 2 this bag also carried the row spread flat (bare `status`, the
+ * row-action shorthand) and as `data` (legacy), and `useCondition` below warned
+ * once per non-canonical spelling (Phase 1, `d1ab06f0f`). Both bindings and the
+ * warning are gone. A bare-field or `data.*` predicate against this bag now
+ * faults exactly as it always did on the server (`buildScope({ record })`
+ * mounts exactly `['record']`: `Unknown variable: status` / `Unknown variable:
+ * data`), and each `useCondition` leg applies its EXISTING fault policy — the
+ * throwing legs (`throwOnError`: every action `visible` — `action:button`,
+ * `action:menu`, `action:bar`, `DeclaredActionsBar`, and since objectui#11212
+ * `action:group`, `action:icon` and the related-list toolbar) hide and report
+ * `was hidden/disabled: its predicate threw`, naming the variable; the
+ * non-throwing legs fail soft to `true`. The same holds for a legacy `${data.x}` / `${x}` string: one bag
+ * shape, both dialects. Nothing detects a retired spelling here; it is simply
+ * unbound. `@object-ui/core`'s `evaluator/rowPredicateCanon.ts` carries the
+ * canon statement, the server measurement, the layer scoping (`data` stays
+ * canonical one layer over, in a metadata-editing form — ADR-0089 D3) and the
+ * offline detector.
  *
- * That was live, not theoretical: every declared action on framework's
- * `sys_approval_request` gates on `record.viewer.*` (framework#3310 / #3424),
- * so the whole server-declared approval decision set was invisible wherever
- * `DeclaredActionsBar` rendered until objectui#4077 bound the row this way —
- * and the four generic action renderers carried the same root-only binding
- * until objectui#4075.
+ * ## Why a helper and not "just `{ record }`" (objectui#4075 / #4080)
  *
- * ## The canon is `record.*` (objectui#5330, ruled 2026-08-20)
+ * Because the rule has two halves and every predicate face has to get both:
+ * the SHAPE — `record` is the row's one name, so `record.viewer.can_act`, what
+ * every declared action on framework's `sys_approval_request` gates on
+ * (framework#3310 / objectstack-ai/objectstack#3424), reaches the row — and the NO-ROW case below.
+ * `DeclaredActionsBar` and the four generic action renderers once carried
+ * inline copies of this bag and drifted (objectui#4077 / #4079); one named
+ * helper is what keeps a fifth copy from drifting again.
  *
- * All three spellings are bound here, and that is unchanged — but they are NOT
- * peers. `record.*` is the CONTRACT; the bare shorthand and `data.*` are
- * tolerances in a deprecation window, kept because stored metadata carries
- * them, reported once by `warnNonCanonicalRowSpelling` from `useCondition`
- * below, and removable only after a stored-metadata survey sizes the window
- * (⛔ no removal before the survey — part of the same ruling).
- *
- * The canon states the SERVER's accept set, which is narrower than this bag:
- * measured on `@objectstack/formula@17.1.0`, `buildScope({ record })` mounts
- * exactly `['record']`, so of the three spellings this helper binds, only
- * `record.*` evaluates server-side — a bare field faults `Unknown variable:
- * status` and `data.*` faults `Unknown variable: data`. This three-way bag has
- * no server counterpart at all, which is exactly why the warning belongs on
- * this side. `@object-ui/core`'s `evaluator/rowPredicateCanon.ts` carries the
- * full measurement and the layer scoping (`data` stays canonical one layer
- * over, in a metadata-editing form — ADR-0089 D3).
- *
- * `record` and `data` are written AFTER the spread deliberately: a row that
- * happens to carry a field literally named `record` or `data` must not shadow
- * the root every predicate is written against. Same precedence as
- * `evalRowPredicate`.
+ * Note the direction of the merge: `useCondition` evaluates on
+ * `new ExpressionEvaluator({ ...scope, ...context })`, so this bag's `record`
+ * shadows an ambient `record` a host put in the predicate scope — the row is
+ * the subject — while every OTHER ambient key (`features`, `user`, a host's own
+ * `data`) survives to the predicate as the host's own.
  *
  * This is the BINDING rule only. It deliberately does not touch the evaluation
  * entry — `useCondition` / `toPredicateInput` / `hasDeclaredVisibilityGate`
@@ -135,10 +130,10 @@ export { toPredicateInput } from '@object-ui/core';
  * ## No row → bind NOTHING, do not bind an empty one
  *
  * `null` / `undefined` / a non-object returns an EMPTY bag, not
- * `{ record: {}, data: {} }`. The difference is load-bearing: `useCondition`
- * merges this context OVER the ambient predicate scope, so binding an empty
- * record would blank out a `record` that a host had put in the scope itself —
- * which is exactly how `action:group`'s dropdown leaf is driven in
+ * `{ record: {} }`. The difference is load-bearing: `useCondition` merges this
+ * context OVER the ambient predicate scope, so binding an empty record would
+ * blank out a `record` that a host had put in the scope itself — which is
+ * exactly how `action:group`'s dropdown leaf is driven in
  * `action-group-dropdown-visible.test.tsx`, and it is a legitimate way for a
  * host to supply the row. "This surface has no row of its own" must stay
  * distinct from "this surface's row is empty"; only the latter is entitled to
@@ -150,8 +145,7 @@ export function usePredicateRecordContext(record) {
     return useMemo(() => {
         if (record == null || typeof record !== 'object' || Array.isArray(record))
             return {};
-        const row = record;
-        return { ...row, record: row, data: row };
+        return { record: record };
     }, [record]);
 }
 /**
@@ -188,37 +182,11 @@ export function useCondition(condition, context = {}, options) {
     const scope = usePredicateScope();
     // We evaluate directly without caching the evaluator to avoid issues with context changes
     return useMemo(() => {
-        // objectui#5330 Phase 1 — report a deprecated row-predicate spelling on
-        // the `useCondition` tier. This is the BINDING half's evaluation entry:
-        // `usePredicateRecordContext` sees the row but never the predicate text,
-        // so it structurally cannot detect a spelling, and this is the first
-        // point where the two meet.
-        //
-        // Two guards, both of which can only remove a report:
-        //  - the bag must carry the `usePredicateRecordContext` signature, `data`
-        //    and `record` being the SAME object by identity. A host scope that
-        //    merely happens to carry a `data` key cannot satisfy that, so a
-        //    non-row `useCondition` call is never judged as a row predicate.
-        //  - the source must be CEL. In this tier's legacy `${…}` dialect
-        //    (`'${data.status === "active"}'` — this hook's own doc example)
-        //    `data.*` is the NORMAL spelling, and reporting it would be a false
-        //    positive on every legacy predicate.
-        const bag = context;
-        const boundRow = bag.record != null && typeof bag.record === 'object' && bag.record === bag.data
-            ? bag.record
-            : undefined;
-        if (boundRow !== undefined) {
-            const celSource = typeof condition === 'string'
-                ? isLegacyDialectSource(condition)
-                    ? undefined
-                    : condition
-                : condition && typeof condition === 'object' && condition.dialect === 'cel'
-                    ? condition.source
-                    : undefined;
-            if (typeof celSource === 'string') {
-                warnNonCanonicalRowSpelling(celSource, boundRow, true, options?.label);
-            }
-        }
+        // No row-spelling detector on this tier (`83fe6e741` removed the
+        // Phase-1 warning with the bindings): a retired bare-field / `data.*`
+        // spelling against a `usePredicateRecordContext` bag is simply unbound
+        // and faults like any other unknown variable, and each leg's existing
+        // fault report below is what names it.
         const evaluator = new ExpressionEvaluator({ ...scope, ...context });
         if (options?.throwOnError) {
             // Fail-closed: a predicate that can't be evaluated hides/disables
@@ -256,11 +224,11 @@ export function useCondition(condition, context = {}, options) {
  * routes to `@object-ui/core`'s `evalRowPredicate`: a bare string is CEL (the
  * spec contract for `ActionSchema.visible`), a `{ dialect: 'cel', source }`
  * envelope is always CEL, and only a legacy-dialect string falls back to the
- * old engine (with a deprecation warning). The row is bound as `record.*` — the
- * CANON (objectui#5330) — and, for stored metadata only, as bare fields and
- * `data.*`, both of which now warn once; the ambient predicate scope
- * (`features` / `user` / …) is merged alongside so deployment-level gates keep
- * resolving.
+ * old engine (with a deprecation warning). The row is bound as `record.*` only
+ * — the canon (objectui#5330; the bare-field and `data.*` spellings retired in
+ * `83fe6e741` and fault here like any unknown variable); the ambient
+ * predicate scope (`features` / `user` / …) is merged alongside so
+ * deployment-level gates keep resolving.
  *
  * @param pred     The raw predicate: `boolean` (returned as-is), a CEL string,
  *                 an `{ dialect, source }` envelope, or `null`/`undefined`/`''`.

package/dist/hooks/useFilterScope.d.ts

@@ -20,11 +20,31 @@ export declare function FilterScopeProvider({ currentUserId, currentOrgId, child
     children: ReactNode;
 }): import("react").FunctionComponentElement<import("react").ProviderProps<FilterTokenScope>>;
 /**
- * Read the session scope for filter placeholder resolution.
+ * Read the scope for filter placeholder resolution: the session scope the host
+ * mounted, plus the id of the record in view when there is one.
  *
  * Pass the result straight to `resolveFilterPlaceholders(filter, scope)` from
  * `@object-ui/core` — that helper expands every placeholder vocabulary in one
  * call, which is the point: resolving only some of them is the defect behind
- * #3574.
+ * objectstack-ai/objectstack#3574.
+ *
+ * ## `{record_id}` reads the MOUNTED record (objectui#7297)
+ *
+ * `recordId` comes from the nearest `RecordContextProvider` — the record a
+ * `type: 'record'` page is showing, the same provider whose row a component's
+ * `visibleWhen` binds as `record` — and from nowhere else: ⛔ not a URL
+ * parameter, not a page variable, and not a prop of `FilterScopeProvider`,
+ * which stays session-only. Every data node that already resolves its filter
+ * through this hook therefore resolves `{record_id}` on a record page without
+ * a line of its own, and refuses it by name everywhere else (a list view, a
+ * dashboard, a page that is not a record page), because there the member is
+ * simply absent.
+ *
+ * Outside a record context the session scope is handed back as the very
+ * object the provider published, so nothing changes for a surface that shows
+ * no record. Inside one, the combined scope is rebuilt only when the session
+ * scope or the record id changes. A consumer that holds a resolution compares
+ * the members one by one — `recordId` among them — never this object's
+ * identity (AGENTS.md #10).
  */
 export declare function useFilterScope(): FilterTokenScope;

package/dist/hooks/useFilterScope.js

@@ -6,9 +6,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { createContext, createElement, useContext, useMemo } from 'react';
+import { useRecordContext } from '../context/RecordContext.js';
 /**
  * The session values filter placeholders resolve against — `{current_user_id}`
- * and `{current_org_id}` (framework #3574).
+ * and `{current_org_id}` (objectstack-ai/objectstack#3574). The record-scoped
+ * `{record_id}` is not a session value and is not provided here: see
+ * {@link useFilterScope}.
  *
  * ## Why a dedicated context
  *
@@ -43,13 +46,35 @@ export function FilterScopeProvider({ currentUserId, currentOrgId, children, })
     return createElement(FilterScopeContext.Provider, { value }, children);
 }
 /**
- * Read the session scope for filter placeholder resolution.
+ * Read the scope for filter placeholder resolution: the session scope the host
+ * mounted, plus the id of the record in view when there is one.
  *
  * Pass the result straight to `resolveFilterPlaceholders(filter, scope)` from
  * `@object-ui/core` — that helper expands every placeholder vocabulary in one
  * call, which is the point: resolving only some of them is the defect behind
- * #3574.
+ * objectstack-ai/objectstack#3574.
+ *
+ * ## `{record_id}` reads the MOUNTED record (objectui#7297)
+ *
+ * `recordId` comes from the nearest `RecordContextProvider` — the record a
+ * `type: 'record'` page is showing, the same provider whose row a component's
+ * `visibleWhen` binds as `record` — and from nowhere else: ⛔ not a URL
+ * parameter, not a page variable, and not a prop of `FilterScopeProvider`,
+ * which stays session-only. Every data node that already resolves its filter
+ * through this hook therefore resolves `{record_id}` on a record page without
+ * a line of its own, and refuses it by name everywhere else (a list view, a
+ * dashboard, a page that is not a record page), because there the member is
+ * simply absent.
+ *
+ * Outside a record context the session scope is handed back as the very
+ * object the provider published, so nothing changes for a surface that shows
+ * no record. Inside one, the combined scope is rebuilt only when the session
+ * scope or the record id changes. A consumer that holds a resolution compares
+ * the members one by one — `recordId` among them — never this object's
+ * identity (AGENTS.md #10).
  */
 export function useFilterScope() {
-    return useContext(FilterScopeContext);
+    const session = useContext(FilterScopeContext);
+    const recordId = useRecordContext()?.recordId;
+    return useMemo(() => (recordId == null ? session : { ...session, recordId }), [session, recordId]);
 }

package/dist/hooks/useGlobalUndo.d.ts

@@ -23,6 +23,16 @@ export interface UseGlobalUndoOptions {
  *
  * Provides reactive undo/redo state, executes data operations through the
  * supplied dataSource, and registers Ctrl+Z / Ctrl+Shift+Z keyboard shortcuts.
+ *
+ * Keyboard: however many instances are mounted, one `window` `keydown`
+ * listener serves them all and one keypress pops at most one operation. It is
+ * answered by the longest-mounted live instance — its `dataSource` runs the
+ * write and its `onUndo` / `onRedo` fires — and by no other. A keypress whose
+ * target is an `input`, `textarea`, `select` or contenteditable region is left
+ * to that field: nothing is popped and the default is not prevented.
+ *
+ * The returned `undo` / `redo` (e.g. a toast's Undo button) always run through
+ * THIS instance's `dataSource` and callbacks.
  */
 export declare function useGlobalUndo(options?: UseGlobalUndoOptions): {
     undo: () => Promise<void>;

package/dist/hooks/useGlobalUndo.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, useSyncExternalStore } from 'react';
+import { useCallback, useEffect, useInsertionEffect, useMemo, useRef, useSyncExternalStore, } from 'react';
 import { globalUndoManager } from '@object-ui/core';
 function getSnapshot() {
     return {
@@ -28,59 +28,125 @@ function subscribe(callback) {
     });
 }
 function getCachedSnapshot() { return cachedSnapshot; }
+async function executeOp(optionsRef, op, data, mode) {
+    const ds = optionsRef.current.dataSource;
+    if (!ds)
+        return;
+    const action = mode === 'undo'
+        ? { create: 'delete', update: 'update', delete: 'create' }[op.type]
+        : op.type;
+    if (action === 'delete')
+        await ds.delete(op.objectName, op.recordId);
+    else if (action === 'update')
+        await ds.update(op.objectName, op.recordId, data);
+    else
+        await ds.create(op.objectName, data);
+}
+async function runUndo(optionsRef) {
+    const op = globalUndoManager.popUndo();
+    if (!op)
+        return;
+    await executeOp(optionsRef, op, op.undoData, 'undo');
+    optionsRef.current.onUndo?.(op);
+}
+async function runRedo(optionsRef) {
+    const op = globalUndoManager.popRedo();
+    if (!op)
+        return;
+    await executeOp(optionsRef, op, op.redoData, 'redo');
+    optionsRef.current.onRedo?.(op);
+}
+// ── Keyboard shortcuts: ONE listener for the one shared stack (objectui#11081) ──
+//
+// Every instance used to add its own `window` `keydown` listener, and each of
+// them popped `globalUndoManager`, so one Ctrl+Z undid one operation PER
+// MOUNTED INSTANCE (the console mounts several at once). Now the instances
+// register here and a single module-level listener answers each keypress,
+// popping at most one operation.
+//
+// Which instance answers is decided once: the longest-mounted live one, the
+// first entry of this insertion-ordered set. An `UndoableOperation` carries
+// nothing that names the instance whose runner pushed it, so "the owner of the
+// operation" is not readable here. The oldest live instance is also exactly
+// the one that answered a keypress before this change whenever a single
+// operation was stacked (its listener was first on `window` and popped it; the
+// rest found the stack empty), so the one-operation keypress behaves as it
+// always did. When it unmounts, the next-oldest takes over.
+const keyboardInstances = new Set();
+/** A field whose own Ctrl+Z (the browser's text undo) must not be taken over. */
+function isEditableTarget(target) {
+    const el = target;
+    if (!el || typeof el.tagName !== 'string')
+        return false;
+    if (el.isContentEditable)
+        return true;
+    const tag = el.tagName.toUpperCase();
+    return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
+}
+function onUndoShortcut(e) {
+    if (!(e.ctrlKey || e.metaKey) || e.key.toLowerCase() !== 'z')
+        return;
+    // Inside a text field Ctrl+Z is the field's own undo: no pop, no preventDefault.
+    if (isEditableTarget(e.target))
+        return;
+    const owner = keyboardInstances.values().next().value;
+    if (!owner)
+        return;
+    e.preventDefault();
+    if (e.shiftKey) {
+        void runRedo(owner);
+    }
+    else {
+        void runUndo(owner);
+    }
+}
+function registerKeyboardInstance(optionsRef) {
+    keyboardInstances.add(optionsRef);
+    if (keyboardInstances.size === 1)
+        window.addEventListener('keydown', onUndoShortcut);
+    return () => {
+        keyboardInstances.delete(optionsRef);
+        if (keyboardInstances.size === 0)
+            window.removeEventListener('keydown', onUndoShortcut);
+    };
+}
 /**
  * React hook that wraps the global UndoManager for use in console components.
  *
  * Provides reactive undo/redo state, executes data operations through the
  * supplied dataSource, and registers Ctrl+Z / Ctrl+Shift+Z keyboard shortcuts.
+ *
+ * Keyboard: however many instances are mounted, one `window` `keydown`
+ * listener serves them all and one keypress pops at most one operation. It is
+ * answered by the longest-mounted live instance — its `dataSource` runs the
+ * write and its `onUndo` / `onRedo` fires — and by no other. A keypress whose
+ * target is an `input`, `textarea`, `select` or contenteditable region is left
+ * to that field: nothing is popped and the default is not prevented.
+ *
+ * The returned `undo` / `redo` (e.g. a toast's Undo button) always run through
+ * THIS instance's `dataSource` and callbacks.
  */
 export function useGlobalUndo(options = {}) {
     const optionsRef = useRef(options);
-    optionsRef.current = options;
+    // Refreshed in the MUTATION phase, never in the render body. Every caller
+    // passes an inline object literal with inline `onUndo` / `onRedo` closures,
+    // so `options` is a new object on every render; `undo` / `redo` and the
+    // keyboard registration hold the ref (whose identity React does keep) and
+    // still reach the newest callbacks. Writing it during render published the
+    // options of renders React discards or replays.
+    // `useInsertionEffect` runs ahead of every layout effect, ref attachment and
+    // paint in the commit, so the only window this moves is the render phase
+    // itself — where `undo` / `redo`, being async data mutations, are not
+    // callable. `useEffectEvent` would be idiomatic but is React 19.2+, and this
+    // package's peer range starts at React 18.
+    useInsertionEffect(() => {
+        optionsRef.current = options;
+    });
     const state = useSyncExternalStore(subscribe, getCachedSnapshot, getServerSnapshot);
-    const executeOp = useCallback(async (op, data, mode) => {
-        const ds = optionsRef.current.dataSource;
-        if (!ds)
-            return;
-        const action = mode === 'undo'
-            ? { create: 'delete', update: 'update', delete: 'create' }[op.type]
-            : op.type;
-        if (action === 'delete')
-            await ds.delete(op.objectName, op.recordId);
-        else if (action === 'update')
-            await ds.update(op.objectName, op.recordId, data);
-        else
-            await ds.create(op.objectName, data);
-    }, []);
-    const undo = useCallback(async () => {
-        const op = globalUndoManager.popUndo();
-        if (!op)
-            return;
-        await executeOp(op, op.undoData, 'undo');
-        optionsRef.current.onUndo?.(op);
-    }, [executeOp]);
-    const redo = useCallback(async () => {
-        const op = globalUndoManager.popRedo();
-        if (!op)
-            return;
-        await executeOp(op, op.redoData, 'redo');
-        optionsRef.current.onRedo?.(op);
-    }, [executeOp]);
-    // Keyboard shortcuts: Ctrl+Z (undo), Ctrl+Shift+Z (redo)
-    useEffect(() => {
-        const handler = (e) => {
-            if (!(e.ctrlKey || e.metaKey) || e.key.toLowerCase() !== 'z')
-                return;
-            e.preventDefault();
-            if (e.shiftKey) {
-                void redo();
-            }
-            else {
-                void undo();
-            }
-        };
-        window.addEventListener('keydown', handler);
-        return () => window.removeEventListener('keydown', handler);
-    }, [undo, redo]);
+    const undo = useCallback(() => runUndo(optionsRef), []);
+    const redo = useCallback(() => runRedo(optionsRef), []);
+    // Registered once per mount, keyed on the ref and on no memoised identity, so
+    // this instance's place in the keyboard order is its mount order.
+    useEffect(() => registerKeyboardInstance(optionsRef), []);
     return useMemo(() => ({ ...state, undo, redo }), [state, undo, redo]);
 }

package/dist/hooks/useNavigationOverlay.d.ts

@@ -6,6 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { NavigationConfigSchema, NavigationMode as SpecNavigationMode } from '@objectstack/spec/ui';
+import type { RecordNavigateAction } from '@object-ui/types';
 import type { SpecAuthoredInput } from '../spec-input.js';
 /**
  * The spec's `NavigationConfigSchema`, authoring side — by reference, with no
@@ -22,8 +23,10 @@ import type { SpecAuthoredInput } from '../spec-input.js';
  * `mode` is OPTIONAL, because the spec says so and this hook agrees.
  * `packages/spec/src/ui/view.zod.ts` declares
  * `mode: NavigationModeSchema.default('page')`, and a `.default()` lands on the
- * AUTHORING side as `| undefined` — so `navigation: { view: 'summary_view' }`
- * is legal authored metadata that lets the mode default.
+ * AUTHORING side as `| undefined` — so `navigation: { size: 'lg' }` is legal
+ * authored metadata that lets the mode default. ⛔ This sentence used to make
+ * the same point with a `view` member; see "The RETIRED `view` key" below for
+ * why no example in this file may spell that key again.
  *
  * Until objectui#4550 this alias `Omit`ted `mode` and re-added it as
  * `NonNullable<…>`, on the stated reasoning that "this hook dispatches on
@@ -51,9 +54,9 @@ import type { SpecAuthoredInput } from '../spec-input.js';
  *
  * Two per-key notes the hand copy carried, kept here because a derived alias
  * has no members to hang them on:
- *  - `size` is the coarse overlay bucket added by #2578; `resolveOverlayWidth`
+ *  - `size` is the coarse overlay bucket added by objectstack-ai/objectstack#2578; `resolveOverlayWidth`
  *    below maps it through {@link OVERLAY_SIZE_WIDTHS}.
- *  - `width` is DEPRECATED by #2578 in favour of `size`. It still wins when
+ *  - `width` is DEPRECATED by objectstack-ai/objectstack#2578 in favour of `size`. It still wins when
  *    present, because app-shell pre-resolves `size` into it.
  */
 export type NavigationConfig = SpecAuthoredInput<typeof NavigationConfigSchema>;
@@ -95,10 +98,50 @@ export interface UseNavigationOverlayOptions {
     navigation?: NavigationConfig;
     /** Object name — used to build default URLs for page/new_window modes */
     objectName?: string;
-    /** External onNavigate callback (e.g., from ActionProvider or parent) */
-    onNavigate?: (recordId: string | number, action?: string) => void;
-    /** External onRowClick callback — if set, takes full priority */
-    onRowClick?: (record: Record<string, unknown>) => void;
+    /**
+     * Called for page-level navigation with the record id and a
+     * {@link RecordNavigateAction} — a navigation-MODE token from a closed
+     * vocabulary: `'view'` opens the record page, `'new_window'` opens it in a
+     * new browser tab.
+     *
+     * `handleClick` below is the one producer of that token, and every call it
+     * makes is typed against this declaration — so a third token is a compile
+     * error here, not a branch a host's handler silently never matches
+     * (objectui#9547). Supplied by the host that renders the list (a
+     * `schema.onNavigate`, a component prop, or the host's own router closure).
+     *
+     * When it is absent, an authored `page` click goes to the record navigator
+     * the host publishes on `RelatedRecordActionsContext` instead
+     * (objectui#11293; see the module docblock). Supplied, it wins.
+     */
+    onNavigate?: (recordId: string | number, action: RecordNavigateAction) => void;
+    /**
+     * External onRowClick callback — if set, takes full priority.
+     *
+     * Declares BOTH arguments `handleClick` hands it: the record, and the
+     * optional modifier payload (`HandleClickModifiers`, declared just below)
+     * that lets a host implement Cmd/Ctrl/middle-click for itself. The second
+     * argument was always delivered; until objectui#9357 this line declared only
+     * the first and `handleClick` asserted the declaration away in order to make
+     * the call — so the payload was invisible on the one line a host reads, and
+     * every consumer that passes its own handler through copied the understated
+     * spelling outward.
+     *
+     * A one-parameter handler stays assignable here, and so does one that leaves
+     * its second parameter unannotated. The exception, and the one class that has
+     * to change: a handler whose second parameter is annotated NARROWER than
+     * `HandleClickModifiers` — React's `MouseEvent` is the shape this hits in
+     * practice, because the payload used to be discoverable only from the
+     * implementation — is refused from this card on with TS2322. The parameter is
+     * checked contravariantly, so the annotation has to ADMIT
+     * `HandleClickModifiers`. The fix is one line at that call site: annotate the
+     * parameter `HandleClickModifiers` (exported from this module, and from
+     * `@object-ui/react`), or drop the annotation and let it be inferred; either
+     * way the handler keeps receiving exactly what it received before. What the
+     * widening buys everyone else is that a caller who WANTS the payload can now
+     * see, from the published type, that it exists.
+     */
+    onRowClick?: (record: Record<string, unknown>, event?: HandleClickModifiers) => void;
 }
 /**
  * Optional event-like payload accepted by `handleClick`. We don't depend on
@@ -139,18 +182,40 @@ export interface NavigationOverlayState {
     width: string | number | undefined;
     /** Whether navigation is an overlay mode (drawer/modal/split/popover) */
     isOverlay: boolean;
-    /** The target view/form name from NavigationConfig */
-    view: string | undefined;
 }
 /**
  * Hook for NavigationConfig-driven navigation overlay.
  *
+ * ## What to hand `objectName`
+ *
+ * The block's RECORD SOURCE — the object the clicked rows actually came from —
+ * and never a bare top-level `schema.objectName` read in its place. `77cb489b4`
+ * published `objectName` as the THIRD RUNG of one record-source ladder (`data`,
+ * then `staticData`, then `objectName`), not as a parallel "page object"
+ * concept, so a block has exactly ONE record source. `handleClick` below builds
+ * the record-page URL `/{objectName}/record/{id}` out of whatever it is handed:
+ * a caller that hands it the top-level key while its rows came from
+ * `data.object` navigates to a record that the URL's own object does not
+ * contain (`2ce2612df`).
+ *
+ * A caller that resolves a data config reads that ladder through the ONE shared
+ * reader — `resolveRecordSourceObjectName` from `@object-ui/core`
+ * (`b041b9c0c`) — as the example does. A caller with NO data config has
+ * nothing above rung three, and its `schema.objectName` already IS its record
+ * source; that spelling is correct there and needs no conversion.
+ *
  * @example
  * ```tsx
+ * import {
+ *   resolveRecordSourceConfig,
+ *   resolveRecordSourceObjectName,
+ * } from '@object-ui/core';
+ *
+ * const dataConfig = useMemo(() => resolveRecordSourceConfig(schema), [schema]);
  * const { handleClick, isOpen, selectedRecord, mode, close, width } =
  *   useNavigationOverlay({
  *     navigation: schema.navigation,
- *     objectName: schema.objectName,
+ *     objectName: resolveRecordSourceObjectName(schema, dataConfig),
  *     onNavigate: schema.onNavigate,
  *     onRowClick: props.onRowClick,
  *   });