@object-ui/react 17.5.0 → 17.7.0

package/dist/hooks/useNavigationOverlay.d.ts

@@ -6,7 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { NavigationConfigSchema, NavigationMode as SpecNavigationMode } from '@objectstack/spec/ui';
-import type { SpecAuthoredInput } from '../spec-input';
+import type { RecordNavigateAction } from '@object-ui/types';
+import type { SpecAuthoredInput } from '../spec-input.js';
 /**
  * The spec's `NavigationConfigSchema`, authoring side — by reference, with no
  * divergence of its own.
@@ -22,8 +23,10 @@ import type { SpecAuthoredInput } from '../spec-input';
  * `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';
  *
  * 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]);
 }

package/dist/hooks/useOffline.js

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

package/dist/hooks/usePageAssignment.d.ts

@@ -7,7 +7,7 @@
  *
  * `usePageAssignment` — resolve the record PageSchema that should be rendered
  * for a given object. Walks the metadata cache exposed by `<MetadataProvider>`
- * and returns the first PageSchema whose `pageType === 'record'` and `object`
+ * and returns the first PageSchema whose `type === 'record'` and `object`
  * matches the requested name.
  *
  * Returns a discriminated result by `PageSchema.kind`:
@@ -18,10 +18,13 @@
  *     `buildDefaultPageSchema(objectDef, { slots })` so omitted slots
  *     fall through to synthesized defaults.
  *
- * Future work (deferred): recordType / profile / app / formFactor filtering
- * and priority-based selection. For now we return the first match so that
- * callers can deterministically fall back to the auto-generated DetailView
- * when no record Page is authored.
+ * Selection is by DECLARATION ORDER: the first matching page wins, so callers
+ * can deterministically fall back to the auto-generated DetailView when no
+ * record Page is authored.
+ *
+ * Future work (deferred): recordType / profile / app / formFactor filtering.
+ * Any author-driven ordering would have to be DECLARED on `PageSchema` in
+ * `@objectstack/spec` first — see the note on the selection itself below.
  */
 export interface PageAssignmentOptions {
     /** Salesforce-style record type filter (reserved for future use). */

package/dist/hooks/usePageAssignment.js

@@ -7,7 +7,7 @@
  *
  * `usePageAssignment` — resolve the record PageSchema that should be rendered
  * for a given object. Walks the metadata cache exposed by `<MetadataProvider>`
- * and returns the first PageSchema whose `pageType === 'record'` and `object`
+ * and returns the first PageSchema whose `type === 'record'` and `object`
  * matches the requested name.
  *
  * Returns a discriminated result by `PageSchema.kind`:
@@ -18,13 +18,16 @@
  *     `buildDefaultPageSchema(objectDef, { slots })` so omitted slots
  *     fall through to synthesized defaults.
  *
- * Future work (deferred): recordType / profile / app / formFactor filtering
- * and priority-based selection. For now we return the first match so that
- * callers can deterministically fall back to the auto-generated DetailView
- * when no record Page is authored.
+ * Selection is by DECLARATION ORDER: the first matching page wins, so callers
+ * can deterministically fall back to the auto-generated DetailView when no
+ * record Page is authored.
+ *
+ * Future work (deferred): recordType / profile / app / formFactor filtering.
+ * Any author-driven ordering would have to be DECLARED on `PageSchema` in
+ * `@objectstack/spec` first — see the note on the selection itself below.
  */
 import { useEffect, useMemo, useState } from 'react';
-import { useMetadata } from '../context/AppShellContext';
+import { useMetadata } from '../context/AppShellContext.js';
 function matchesAssignment(_page, _opts) {
     // Placeholder — every page matches until rules-based assignment lands.
     return true;
@@ -75,14 +78,20 @@ export function usePageAssignment(objectName, opts = {}) {
         const candidates = pages.filter(p => {
             if (!p)
                 return false;
-            // Only `pageType: 'record'` (or bare `type: 'record'`) is a
-            // user-facing record-detail page. Any other `pageType` — notably the
-            // designer-side `'record_detail'`, dropped from `PageType` in
-            // framework#2265 but still expressible in raw metadata — must NOT be
-            // picked up here, otherwise opening any record would render it.
-            const pt = p.pageType ?? (p.type === 'record' ? 'record' : undefined);
-            const isRecord = pt === 'record';
-            if (!isRecord)
+            // `type` is the ONE discriminator: only `type: 'record'` is a
+            // user-facing record-detail page, and every other page type
+            // (`home` / `app` / `utility` / `list`) is skipped.
+            //
+            // `pageType` is deliberately NOT read (objectui#9674). `PageSchema` is
+            // a `strictObject` that refuses `pageType` by name — it is a declared
+            // ALIAS of `type`, and a page carrying it is a hard parse error that
+            // names `type` as the key to write — so no page that parses carries it,
+            // and reading it would teach the refused spelling onward. A consumer-side
+            // alias for a refused key is the fallback AGENTS.md #0.1 rules out. The
+            // designer-side `'record_detail'` is not expressible either: it left
+            // `PageTypeSchema` (framework#2265), so `type: 'record_detail'` is an
+            // invalid enum value.
+            if (p.type !== 'record')
                 return false;
             if (p.object !== objectName)
                 return false;
@@ -90,9 +99,21 @@ export function usePageAssignment(objectName, opts = {}) {
         });
         if (!candidates.length)
             return null;
-        // Stable ordering: respect explicit `priority` if present (higher wins),
-        // otherwise fall back to declaration order.
-        candidates.sort((a, b) => (b?.priority ?? 0) - (a?.priority ?? 0));
+        // Declaration order decides: the first match wins.
+        //
+        // This used to sort on a `priority` key read off the candidate. No author
+        // could ever set it: `PageSchema` is a `strictObject` and does not declare
+        // `priority`, so a page carrying one is a HARD PARSE ERROR, not a page that
+        // sorts first. Every candidate therefore read `0`, the comparator returned
+        // `0` for every pair, and a stable sort left declaration order untouched —
+        // the sort documented an affordance the schema refuses (objectui#7298).
+        //
+        // `isDefault` is not consulted here either. It IS declared on `PageSchema`,
+        // so unlike `priority` it is writable — but nothing in this decision reads
+        // it, which makes the flag on a shipped page (e.g. the platform's
+        // `sys_user_detail`) inert while looking decisive. Reading it would be new
+        // behaviour, not a repair; it is recorded here so the next reader does not
+        // mistake the flag for the thing that picks the page.
         return candidates[0];
     }, [meta.pages, objectName, opts.pageName, opts.recordType, opts.profile, opts.app, opts.formFactor]);
     // Discriminate by `kind`: full pages populate `page`, slotted pages

package/dist/hooks/usePageTransition.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useMemo } from 'react';
-import { useReducedMotion } from './useReducedMotion';
+import { useReducedMotion } from './useReducedMotion.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------

package/dist/hooks/usePageVariableActionBridge.js

@@ -6,8 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import * as React from 'react';
-import { usePageVariables } from './usePageVariables';
-import { useAction } from '../context';
+import { usePageVariables } from './usePageVariables.js';
+import { useAction } from '../context/index.js';
 /**
  * PageVariableActionBridge — publishes the live page-variable snapshot into the
  * shared ActionRunner context as `pageVariables`, so a submit action (`api` /

package/dist/hooks/useRecordSearch.d.ts

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