@object-ui/react 17.6.0 → 18.0.0

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,
  *   });

package/dist/hooks/useNavigationOverlay.js

@@ -14,8 +14,80 @@
  *
  * Used by plugin-grid, plugin-list, plugin-detail and any component that needs
  * NavigationConfig support.
+ *
+ * ## The RETIRED `view` key (objectui#9874)
+ *
+ * `view.list.navigation.view` was removed in `@objectstack/spec` 17.5.0 under
+ * ADR-0049 (enforce-or-remove). This hook was its one shipped consumer, and the
+ * spec's own tombstone describes THIS file: the authored value "was passed
+ * straight into the navigation-MODE argument of the console's `onNavigate`,
+ * where anything other than `edit` or `view` matched no branch, so the key
+ * selected nothing and could silently deaden the row click."
+ *
+ * ⭐ The point that is one character wide in the source and total in meaning:
+ * `onNavigate`'s second argument is the navigation MODE token, not a view name.
+ * An authored `view` did not SELECT a view, it SUBSTITUTED for the mode — so
+ * `{ mode: 'page', view: 'summary_view' }` dispatched `'summary_view'` into the
+ * slot a host reads against its closed `edit`/`view` vocabulary, matching
+ * neither branch. Two reads (`view ?? 'view'`, in the no-config and the `page`
+ * branch) are now the literal `'view'`, which is what every config without the
+ * key already dispatched and what every config dispatches now.
+ *
+ * The replacement route is NOT in this hook and no fallback belongs here. Per
+ * the same tombstone: to choose what opens for a record, assign a `record` page
+ * to the object and let `isDefault` pick the one that opens — page assignment
+ * is the machinery that resolves a detail layout, and a list view's
+ * `navigation` block only decides HOW the detail is surfaced (`mode`, `size`).
+ *
+ * ⚠️ `NavigationOverlayState` lost its `view` member with the read. It could
+ * only ever carry the retired key, so keeping it would publish a field that is
+ * permanently `undefined` — the same "declared, consumed, and wrong" state the
+ * retirement exists to end. Measured before removing it: zero readers of that
+ * member in this repository (`(navOverlay|nav|state).view` → no lines, against
+ * a lit control on its sibling members in the same command). Hosts outside this
+ * repository were NOT measured.
+ *
+ * ## `page` with no `onNavigate`: the HOST's record navigator (objectui#11293)
+ *
+ * `page` is the spec's default `mode`, so it is what `{ mode: 'page' }` and
+ * every authored block written without `mode` (`{ size: 'lg' }`) resolve to.
+ * The branch used to call `onNavigate` and nothing else, and a host that
+ * renders a block without wiring one — a board, a calendar, a gallery or a
+ * grid placed on a page as a standalone block — has no `onNavigate`: the
+ * click did nothing at all. Measured before the change: a standalone
+ * `object-kanban` / `object-calendar` with either spelling opened no overlay,
+ * called no navigation and no `window.open`, and a standalone `object-grid`
+ * did the same, because the grid's own `onNavigate` is host-supplied too.
+ *
+ * So when no `onNavigate` is supplied, a `page` click is handed to the record
+ * navigator the host PUBLISHES on `RelatedRecordActionsContext`
+ * (`openRecord(objectName, recordId)`). That is the seam the grid's link
+ * column and the lookup cells already read: the route is built by the host
+ * that owns it and never re-derived here, which is why this file still builds
+ * no record URL for `page`. Precedence is unchanged above it: an `onRowClick`
+ * takes the click first, and a supplied `onNavigate` wins over the published
+ * navigator, so every host that wires one (the grid's, the console's list
+ * views) behaves exactly as before. A host that publishes no navigator (the
+ * Studio preview, a bare React mount) has no record page to open, and the
+ * click still opens nothing: the context's documented absent state.
+ *
+ * ⚠️ Scoped to an AUTHORED block that resolves to `page`. An absent
+ * `navigation` stays the host's call (`onNavigate`, or nothing), and that is
+ * load-bearing rather than cautious: a host WITHHOLDS navigation by passing
+ * neither callback. `RelatedList` renders its mobile rows as an
+ * `object-gallery` with no `navigation` and an `onRowClick` that is undefined
+ * when the bridge withheld `onView`; reading the published navigator on the
+ * absent-key path would open those records anyway, under the very bridge that
+ * withheld them. So `{}` and no config still agree whenever an `onNavigate`
+ * is supplied, and part only where a host published a navigator but wired no
+ * callback. The kanban, calendar and gantt default an absent key to a drawer
+ * before it reaches this hook in any case. Modifier clicks and `new_window`
+ * are untouched as well. Pinned by
+ * `__tests__/useNavigationOverlay.hostRecordNavigator-11293.test.tsx` here and
+ * at the mounts by the kanban's and calendar's `NavigationMembers-8652` pins.
  */
 import { useState, useCallback, useMemo } from 'react';
+import { useRelatedRecordActions } from '../context/RelatedRecordActionsContext.js';
 /**
  * Pixel cap per overlay `size` bucket, clamped to the viewport at render —
  * mirrors `plugin-view/src/recordSurface.ts` (`OVERLAY_SIZE_PX`), which owns
@@ -53,12 +125,36 @@ export function resolveOverlayWidth(navigation) {
 /**
  * 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,
  *   });
@@ -79,11 +175,13 @@ export function resolveOverlayWidth(navigation) {
  */
 export function useNavigationOverlay(options) {
     const { navigation, objectName, onNavigate, onRowClick } = options;
+    // The host's published record navigator — read for the `page` branch only,
+    // and only when no `onNavigate` was supplied (objectui#11293).
+    const openRecord = useRelatedRecordActions()?.openRecord;
     const [isOpen, setIsOpen] = useState(false);
     const [selectedRecord, setSelectedRecord] = useState(null);
     const mode = navigation?.mode ?? 'page';
     const width = resolveOverlayWidth(navigation);
-    const view = navigation?.view;
     const isOverlay = mode === 'drawer' || mode === 'modal' || mode === 'split' || mode === 'popover';
     const close = useCallback(() => {
         setIsOpen(false);
@@ -97,6 +195,12 @@ export function useNavigationOverlay(options) {
         // External onRowClick takes full priority. Forward the modifier event
         // so parent handlers (e.g. ObjectView) can still implement Cmd/Ctrl/
         // middle-click → open in new tab.
+        //
+        // Called straight through the declaration (objectui#9357). This used to
+        // carry a type assertion widening the option to two parameters at the
+        // call — the producer paying for its own understated declaration, which
+        // AGENTS.md #0.1 sends back to the producer. The producer is this file,
+        // and the option above now declares what this line passes.
         if (onRowClick) {
             onRowClick(record, event);
             return;
@@ -117,7 +221,7 @@ export function useNavigationOverlay(options) {
         if (!navigation) {
             const recordId = record.id || record._id;
             if (onNavigate && recordId != null) {
-                onNavigate(recordId, view ?? 'view');
+                onNavigate(recordId, 'view');
             }
             return;
         }
@@ -143,11 +247,18 @@ export function useNavigationOverlay(options) {
             window.open(url, '_blank');
             return;
         }
-        // page — delegate to onNavigate callback
+        // page — delegate to onNavigate; with none supplied, to the record
+        // navigator the host publishes (objectui#11293). No URL is built here.
         if (mode === 'page') {
             const recordId = record.id || record._id;
-            if (onNavigate && recordId != null) {
-                onNavigate(recordId, view ?? 'view');
+            if (recordId == null)
+                return;
+            if (onNavigate) {
+                onNavigate(recordId, 'view');
+                return;
+            }
+            if (objectName && openRecord) {
+                openRecord(objectName, recordId);
             }
             return;
         }
@@ -157,7 +268,7 @@ export function useNavigationOverlay(options) {
             setIsOpen(true);
             return;
         }
-    }, [onRowClick, navigation, mode, objectName, onNavigate, isOverlay, view]);
+    }, [onRowClick, navigation, mode, objectName, onNavigate, openRecord, isOverlay]);
     return useMemo(() => ({
         isOpen,
         selectedRecord,
@@ -167,7 +278,6 @@ export function useNavigationOverlay(options) {
         setIsOpen,
         handleClick,
         width,
-        view,
         isOverlay,
-    }), [isOpen, selectedRecord, mode, close, open, handleClick, width, view, isOverlay]);
+    }), [isOpen, selectedRecord, mode, close, open, handleClick, width, isOverlay]);
 }