@object-ui/layout 17.6.0 → 18.0.0

package/README.md

@@ -23,10 +23,9 @@ pnpm add @object-ui/layout
 
 ## Registration
 
-Importing this package registers its component keys (`page-header`, `page:card`,
-`responsive-grid`, `navigation-renderer`, `app-schema-renderer`) on the
-`ComponentRegistry` as a module load side effect, so the side-effect-only import
-is enough:
+Importing this package registers its component keys (`page:card`,
+`app-schema-renderer`) on the `ComponentRegistry` as a module load side effect,
+so the side-effect-only import is enough:
 
 ```typescript
 import '@object-ui/layout';
@@ -39,6 +38,16 @@ used to say `"sideEffects": false`, and a bundler honouring it dropped the
 registration silently). `registerLayout()` is also exported for hosts that
 prefer to register explicitly.
 
+The `page-header` key is retired (objectui#10859): author `page:header`, which
+`@object-ui/components` registers, with the secondary line as `subtitle`. `PageHeader`
+stays an export for JSX composition.
+
+The `responsive-grid` and `navigation-renderer` keys are retired too (objectui#11441).
+A breakpoint grid is the `grid` node with a breakpoint `columns` object
+(`{ "type": "grid", "columns": { "xs": 1, "md": 2 }, "gap": 4 }`), and navigation is
+application metadata: the app's `navigation` items, drawn by the shell.
+`ResponsiveGrid` and `NavigationRenderer` stay exports for JSX composition.
+
 ## Components
 
 ### AppShell
@@ -199,10 +208,22 @@ composed in JSX rather than authored as a JSON node. Full guide:
 The layout components are designed to work seamlessly with React Router:
 
 ```typescript
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import type { ComponentType, ReactNode } from 'react';
 import { AppShell, SidebarNav } from '@object-ui/layout';
 import { Home, Users } from 'lucide-react';
 
+// `react-router-dom` is a PEER dependency (see Installation above): your app
+// installs it, this package does not. These three stand in for what you would
+// import from it, so the composition below is still checked against the shipped
+// `@object-ui/layout` types.
+declare const BrowserRouter: ComponentType<{ children?: ReactNode }>;
+declare const Routes: ComponentType<{ children?: ReactNode }>;
+declare const Route: ComponentType<{ path: string; element: ReactNode }>;
+
+// Your own page components, one per route.
+declare const Dashboard: ComponentType;
+declare const UsersPage: ComponentType;
+
 function App() {
   return (
     <BrowserRouter>
@@ -219,7 +240,7 @@ function App() {
       >
         <Routes>
           <Route path="/" element={<Dashboard />} />
-          <Route path="/users" element={<Users />} />
+          <Route path="/users" element={<UsersPage />} />
         </Routes>
       </AppShell>
     </BrowserRouter>
@@ -227,6 +248,12 @@ function App() {
 }
 ```
 
+A route's `element` takes **your page component**, never the `lucide-react` icon
+of the same name. This example used to route `/users` to `Users` — the icon it
+imports for the sidebar — so the page rendered a 24-pixel glyph where its content
+belonged. Nothing catches that for you: an icon is a valid component, so the
+route type-checks either way, which is why the two are named apart here.
+
 ## Customization
 
 `AppShell` takes a single `className`, and it lands on the `<main>` content
@@ -235,6 +262,8 @@ per-slot `headerClassName` / `sidebarClassName` — the navbar and the sidebar a
 nodes **you** build, so style them where you build them:
 
 ```typescript
+import { AppShell } from '@object-ui/layout';
+
 <AppShell
   className="bg-gray-50"
   navbar={<div className="border-b px-4">My App</div>}

package/dist/AppSchemaRenderer.d.ts

@@ -1,6 +1,6 @@
 import { default as React } from 'react';
 import { AppComponentSchema, NavigationItem } from '@object-ui/types';
-import { VisibilityEvaluator, PermissionChecker, CapabilityChecker } from './NavigationRenderer.js';
+import { VisibilityEvaluator, PermissionChecker, CapabilityChecker, DocTargetChecker } from './NavigationRenderer.js';
 /**
  * Mobile navigation display mode — the two modes this renderer implements.
  *
@@ -34,6 +34,8 @@ export interface AppSchemaRendererProps {
     checkPermission?: PermissionChecker;
     /** Optional capability checker passed to NavigationRenderer (gates `requiresObject` / `requiresService`) */
     checkCapability?: CapabilityChecker;
+    /** Optional member-readability checker for `doc` entries, passed to NavigationRenderer (objectui#10188) */
+    checkDocTarget?: DocTargetChecker;
     /** Called when an action-type navigation item is clicked */
     onAction?: (item: NavigationItem) => void;
     /** Slot: top navbar content (rendered beside the sidebar trigger) */
@@ -56,16 +58,12 @@ export interface AppSchemaRendererProps {
     enablePinning?: boolean;
     /** Called when a navigation item is pinned or unpinned */
     onPinToggle?: (itemId: string, pinned: boolean, item?: NavigationItem, basePath?: string) => void;
-    /** Enable drag-to-reorder for navigation items */
-    enableReorder?: boolean;
-    /** Called when navigation items are reordered via drag */
-    onReorder?: (reorderedItems: NavigationItem[]) => void;
 }
 /**
  * Renders a complete application shell from an `AppSchema` JSON document.
  *
  * Responsibilities:
- * - Reads `name`, `title`, `description`, `logo`, `favicon` for branding
+ * - Reads `name`, `title`, `description`, `icon`, `branding.logo`, `branding.favicon` for branding
  * - Renders sidebar navigation from `navigation` or `areas[].navigation`
  * - Area switcher when multiple areas are VISIBLE — area visibility is
  *   derived from the items inside, not authored (objectui#3311): an area
@@ -87,4 +85,4 @@ export interface AppSchemaRendererProps {
  * </AppSchemaRenderer>
  * ```
  */
-export declare function AppSchemaRenderer({ schema, basePath, mobileNavMode, evaluateVisibility: evalVisProp, checkPermission: checkPermProp, checkCapability: checkCapProp, onAction, navbar, sidebarHeader, sidebarFooter, sidebarExtra, children, className, defaultOpen, enableSearch, enablePinning, onPinToggle, enableReorder, onReorder, }: AppSchemaRendererProps): React.JSX.Element;
+export declare function AppSchemaRenderer({ schema, basePath, mobileNavMode, evaluateVisibility: evalVisProp, checkPermission: checkPermProp, checkCapability: checkCapProp, checkDocTarget, onAction, navbar, sidebarHeader, sidebarFooter, sidebarExtra, children, className, defaultOpen, enableSearch, enablePinning, onPinToggle, }: AppSchemaRendererProps): React.JSX.Element;

package/dist/AppShell.d.ts

@@ -10,7 +10,11 @@ export interface AppShellBranding {
     accentColor?: string;
     /** Favicon URL — replaces the <link rel="icon"> href */
     favicon?: string;
-    /** Page title suffix (sets document.title) */
+    /**
+     * Assigned to `document.title` as given. It is the whole title, not a suffix:
+     * the caller composes the string it wants (the console passes
+     * `"App label — Product name"`).
+     */
     title?: string;
 }
 export interface AppShellProps {
@@ -32,6 +36,29 @@ export interface AppShellProps {
 /**
  * Apply branding CSS custom properties to the document root.
  * This is extracted as a standalone hook so it can be re-used independently.
+ *
+ * It is also the ONE writer of `document.title` for as long as a shell is
+ * mounted (objectui#8637). Ownership is scoped, not permanent: the hook
+ * captures whatever the tab already said, writes `title` over it, and puts the
+ * captured string back when the shell unmounts or `title` changes. So a host
+ * that mounts a shell for part of its route tree gets the specific title while
+ * it is there and its previous title back when it leaves, without a second
+ * writer keyed on navigation — which is what the console used to do, and what
+ * reverted the composed title to the bare product name on every in-app
+ * navigation.
+ *
+ * ⚠️ The capture is a read of the live `document.title`, so a host that lets
+ * something else write the tab title WHILE a shell is mounted hands this hook a
+ * value it did not put there, and that value is what comes back on unmount.
+ * Nesting a second title-writing surface inside a mounted shell is the shape to
+ * avoid; the console's own auth surfaces sit outside the shell for this reason.
+ *
+ * The favicon is scoped the same way (objectui#10040): when `branding.favicon`
+ * is set and the page has an icon link, the hook captures that link's `href`
+ * attribute, writes the branded URL, and puts the captured attribute back (or
+ * removes it, if there was none) when the shell unmounts or the effect re-runs
+ * on changed inputs. The same replay caveat applies — an icon written by something else
+ * while the shell is mounted is overwritten by the restore.
  */
 export declare function useAppShellBranding(branding?: AppShellBranding, title?: string): void;
 export declare function AppShell({ sidebar, navbar, children, className, defaultOpen, branding, rightRail, }: AppShellProps): React.JSX.Element;

package/dist/NavigationRenderer.d.ts

@@ -4,8 +4,20 @@ import { NavigationItem, KeyedI18nLabel } from '@object-ui/types';
  * Callback to evaluate a visibility expression.
  * Return `true` if the item should be visible.
  * When not provided, all items default to visible.
+ *
+ * The parameter is the item's own `visible` type, so the spec's
+ * `{ dialect, source }` envelope reaches the evaluator as authored
+ * (objectui#13075).
+ *
+ * `entry` is the navigation entry whose `visible` this is (objectui#13029).
+ * The item guard always passes it. An entry may declare the spec's API
+ * `dataSource` (`{ provider: 'api', read: { url }, path? }`), whose selected
+ * value its `visible` reads as `data`; reading that binding is the host's job,
+ * so an evaluator that answers such an entry reads it through `entry`. The
+ * default evaluator reads no binding, so it hides an entry that declares one:
+ * a value nobody read is unknown, and an unknown navigation gate is closed.
  */
-export type VisibilityEvaluator = (expression: string | boolean | undefined) => boolean;
+export type VisibilityEvaluator = (expression: NavigationItem['visible'], entry?: NavigationItem) => boolean;
 /**
  * Callback to check whether the current user satisfies **all** of the
  * given permission strings.  Each string is opaque — the consumer decides
@@ -27,6 +39,77 @@ export type PermissionChecker = (permissions: string[]) => boolean;
  * runtime capability probe yet.
  */
 export type CapabilityChecker = (kind: 'object' | 'service', name: string) => boolean;
+/** What a `type: 'doc'` navigation entry opens: a book, a page, or that page in that book. */
+export interface DocNavTarget {
+    book?: string;
+    doc?: string;
+}
+/**
+ * Answers whether the signed-in member may read what a `type: 'doc'` entry
+ * opens (objectui#10188). `false` hides the entry.
+ *
+ * The server is the enforcer (ADR-0046 §6.7): its app read already drops a
+ * `doc` entry the caller may not read (objectstack#19790), and this checker is
+ * the renderer's defence in depth behind it (that ruling's point 2). This layer
+ * holds no audience rules, so the host answers from the member's own doc / book
+ * reads and never re-derives an audience. Kept apart from
+ * {@link CapabilityChecker} on purpose: that one asks whether the RUNTIME has a
+ * target, this one whether the MEMBER may read it.
+ *
+ * When not provided, `doc` entries pass — the server's answer stands.
+ */
+export type DocTargetChecker = (target: DocNavTarget) => boolean;
+/**
+ * What an UNLABELLED navigation entry inherits its text from (objectui#9868).
+ *
+ * `@objectstack/spec` 17.5.0 made a nav entry's `label` optional with a
+ * declared semantic: absent ⇒ the entry shows, at RENDER time, the CURRENT label
+ * of what it opens — the view's label when it names a view and that view is
+ * labelled, else the object's / dashboard's label. These are the three targets
+ * that sentence names; `resolveNavItemLabel` walks them in that order and asks a
+ * {@link NavTargetLabelResolver} about each one.
+ */
+export type NavLabelTarget = {
+    kind: 'view';
+    objectName: string;
+    viewName: string;
+} | {
+    kind: 'object';
+    objectName: string;
+} | {
+    kind: 'dashboard';
+    dashboardName: string;
+};
+/**
+ * Answers the CURRENT display label of a nav target from the host's metadata —
+ * the object schema's `label`, the named view's `label`, the dashboard's
+ * `label` — or `undefined` when the target carries none (or is not loaded).
+ *
+ * This layer holds no metadata, so the host supplies it: the console shell
+ * reads the metadata cache it already loads (`useNavTargetLabel` in
+ * `@object-ui/app-shell`). Because it is asked on every render and nothing is
+ * stored, a renamed target shows its new name on the next render. Without it,
+ * an unlabelled entry falls through to its target's machine name.
+ */
+export type NavTargetLabelResolver = (target: NavLabelTarget) => string | undefined;
+/**
+ * What a host's per-entry control is told about the row it sits in
+ * (objectui#12427, {@link NavigationRendererProps.renderItemAction}).
+ */
+export interface NavItemActionContext {
+    /**
+     * The row's href, as its link renders it ({@link resolveHref}). Absent for an
+     * `action` entry, which runs something and navigates nowhere, and for an
+     * entry whose target resolves to no address (`#`).
+     */
+    href?: string;
+    /** `href` leaves the console: the row opens it in a new tab. */
+    external: boolean;
+    /** The text the row shows ({@link resolveNavItemLabel}). */
+    label: string;
+    /** The renderer's `basePath`. */
+    basePath: string;
+}
 export interface NavigationRendererProps {
     /** Navigation items to render */
     items: NavigationItem[];
@@ -41,6 +124,8 @@ export interface NavigationRendererProps {
     checkPermission?: PermissionChecker;
     /** Optional runtime-capability checker for `requiresObject` / `requiresService` */
     checkCapability?: CapabilityChecker;
+    /** Optional member-readability checker for `doc` entries — see {@link DocTargetChecker} */
+    checkDocTarget?: DocTargetChecker;
     /**
      * Called when an `action`-type item is clicked.
      *
@@ -67,43 +152,76 @@ export interface NavigationRendererProps {
      * working unchanged.
      */
     onPinToggle?: (itemId: string, pinned: boolean, item?: NavigationItem, basePath?: string) => void;
-    /** Enable drag-to-reorder for navigation items */
-    enableReorder?: boolean;
-    /** Called when navigation items are reordered via drag */
-    onReorder?: (reorderedItems: NavigationItem[]) => void;
     /**
-     * Optional label resolver for object-type navigation items.
-     * When provided, called with `(objectName, fallbackLabel)` for items
-     * where `item.type === 'object'` and `item.label` is a plain string.
-     * Enables convention-based i18n auto-resolution without coupling
-     * the layout package to i18n.
+     * The host's control for one entry (objectui#12427), drawn on every leaf and
+     * `action` row where the pin action sits, IN PLACE of it: a row this fills
+     * draws no pin action, so the host's control owns pinning (the console's ⋯
+     * menu offers Add to / Remove from favorites, through the same pin store).
+     * The control is a `SidebarMenuAction` (or renders one), so it sits where the
+     * pin action sat and follows the row's hover.
+     *
+     * Drawn whatever `enablePinning` says, which keeps deciding the Favorites
+     * section alone: a host that wants no control on a screen (a phone) does not
+     * pass this there. Omitted ⇒ the pin action under `enablePinning` +
+     * `onPinToggle`, as before. Groups and separators get none.
+     */
+    renderItemAction?: (item: NavigationItem, context: NavItemActionContext) => React.ReactNode;
+    /**
+     * Rows the host appends to the Favorites section, after the pinned entries
+     * (objectui#12427): favorites that are not navigation entries, such as a
+     * record. Each row is a `SidebarMenuItem`; the renderer lists them in a
+     * `SidebarMenu` of their own, outside the pinned entries' drag order. The
+     * section renders when it has a pinned entry (under `enablePinning`) or one
+     * of these rows; `null`, `false` and an empty array are no rows. Omitted ⇒
+     * the section holds pinned entries only, as before.
+     */
+    extraFavorites?: React.ReactNode;
+    /**
+     * The ids of the pinned entries in the user's order (objectui#12059). The
+     * pinned section draws its entries in this order; a pinned entry it does not
+     * name follows, in menu order. Omitted ⇒ the pinned section follows the menu.
      */
-    resolveObjectLabel?: (objectName: string, fallbackLabel: string) => string;
+    pinnedOrder?: string[];
     /**
-     * Optional label resolver for dashboard-type navigation items.
-     * Called with `(dashboardName, fallbackLabel)` for items where
-     * `item.type === 'dashboard'` and `item.label` is a plain string.
-     * Mirrors `resolveObjectLabel` for the convention-based i18n hook
-     * `useObjectLabel().dashboardLabel`.
+     * Makes the pinned section reorderable (objectui#12059): a pinned row is
+     * dragged by the row itself, with no grip at rest (`cursor: grab`, and an
+     * insertion line while dragging), or from the keyboard with dnd-kit's
+     * keyboard sensor (Space picks the focused row up, the arrow keys move it,
+     * Space drops it, Escape cancels). Called on a drop with the ids of the rows
+     * the section draws, in their new order. Only the pinned section reorders;
+     * the menu itself never does.
      */
-    resolveDashboardLabel?: (dashboardName: string, fallbackLabel: string) => string;
+    onPinnedReorder?: (pinnedIds: string[]) => void;
     /**
-     * Optional label resolver for object-type navigation items that target a
-     * specific view (i.e. `viewName` is set). Called with
-     * `(objectName, viewName, fallbackLabel)`. Mirrors
-     * `useObjectLabel().viewLabel` and resolves
-     * `{ns}.objects.{objectName}._views.{viewName}.label`.
+     * The viewer's locale (a BCP-47 tag such as `zh-CN`), for a PRESENT label
+     * written as an inline locale map (`{ en: 'Accounts', 'zh-CN': '客户' }`,
+     * the spec's `I18nLabel`): the map renders this locale's entry, through the
+     * spec's own `resolveI18nLabel`. When the map has no entry for this locale,
+     * the fallback order is that resolver's and is not restated here
+     * (objectui#11299).
      *
-     * Without this resolver, an object item with a `viewName` falls back to
-     * its schema-provided explicit label (which keeps it distinct from a bare
-     * object-list entry under the same group — avoids visual duplicates such
-     * as two `商机` rows where one is the list and the other is a Kanban view).
+     * Injected, like `t`: this layer carries no i18n dependency, so the host that
+     * knows the language passes it (the console passes its active UI language,
+     * the same value its sidebar resolves area labels in). Omitted ⇒ the
+     * resolver's documented no-locale default, `en`. A plain-string label and an
+     * absent one are unaffected.
      */
-    resolveViewLabel?: (objectName: string, viewName: string, fallbackLabel: string) => string;
+    locale?: string;
     /**
-     * Optional i18n translation function for resolving I18nLabel objects
-     * (`{ key, defaultValue }`). When provided, labels are translated
-     * through i18next; otherwise falls back to `defaultValue`.
+     * Resolver for the text an entry with NO `label` inherits (objectui#9868):
+     * the current label of its view / object / dashboard, read from the host's
+     * metadata at render time. Consulted ONLY for an absent `label` — an authored
+     * label is never replaced by the target's metadata label, not even one
+     * spelled like the target's machine name (the ruling refused that sentinel).
+     * See {@link NavTargetLabelResolver} and {@link resolveNavItemLabel}.
+     */
+    resolveTargetLabel?: NavTargetLabelResolver;
+    /**
+     * Optional i18n translation function for resolving KEYED label objects
+     * (`{ key, defaultValue }`, see {@link resolveLabel}). When provided, labels
+     * are translated through i18next; otherwise falls back to `defaultValue`.
+     * An inline locale map (`{ en, 'zh-CN' }`) is not keyed and never reaches
+     * it — {@link resolveNavItemLabel} reads a map itself, in {@link locale}.
      */
     t?: (key: string, options?: any) => string;
     /**
@@ -137,6 +255,45 @@ export declare function resolveIcon(name?: string): React.ComponentType<any>;
  * wrongly for each other's input, silently (objectui#4167).
  */
 export declare function resolveLabel(label: string | KeyedI18nLabel, t?: (key: string, options?: any) => string): string;
+/**
+ * Resolve a navigation item's display text, in the spec's one order
+ * (`@objectstack/spec` `BaseNavItemSchema.label`, objectstack#20849):
+ *
+ * 1. The id-keyed bundle entry `apps.APP.navigation.ID.label`. That rung runs
+ *    UPSTREAM of this function, at the server-side `/meta` boundary:
+ *    `translateApp` in `@objectstack/spec` (`src/system/i18n-resolver.ts`)
+ *    rewrites a node's `label` by its `id` before the metadata reaches this
+ *    renderer. App-navigation localization has that one owner — localize nav
+ *    labels there, never here.
+ * 2. A PRESENT label, as authored ({@link presentNavItemLabel}): an inline
+ *    locale map reads the entry for `locale` (the viewer's), and a string
+ *    renders verbatim.
+ * 3. An ABSENT label inherits its target's CURRENT label (objectui#9868 —
+ *    `@objectstack/spec` 17.5.0 made it optional, cloud#2021 letter-A ruling),
+ *    resolved here at render time and never written back — see
+ *    {@link inheritedNavItemLabel} for the ladder. That arm is keyed on
+ *    ABSENCE alone, so an authored label is never swapped for the target's
+ *    metadata label, however it is spelled.
+ *
+ * ⛔ Nothing here matches a label's text against a name (objectui#11201,
+ * ruling B). A present label equal to its target's machine name (`account`)
+ * renders `account` in every locale: text cannot tell a deliberate `account`
+ * from a machine-written one, so translation is keyed on identity (rung 1) or
+ * comes through inheritance (rung 3). The three convention resolvers that
+ * the retired rule consulted, and the three arguments that carried them, are
+ * gone (objectui#11299).
+ *
+ * EXPORTED since `969ba84f4`, for the same reason {@link resolveHref} is: a
+ * second surface now renders the same `NavigationItem[]`. `nav:menu` is the
+ * app's navigation tree as PAGE CONTENT (`app-shell/src/views/nav-menu-renderer.tsx`),
+ * and it cannot mount `NavigationRenderer` itself — that renders through
+ * `SidebarMenuButton`, whose `useSidebar()` throws outside the shell's
+ * `SidebarProvider`. Re-deriving the label rules there would put one nav entry
+ * under two names on two surfaces of one app, which is exactly the drift the
+ * "single source of truth" note on `resolveHref` exists to prevent. Nothing
+ * about the behaviour changed with the keyword.
+ */
+export declare function resolveNavItemLabel(item: NavigationItem, t?: (key: string, options?: any) => string, targetLabel?: NavTargetLabelResolver, locale?: string): string;
 /** Guard callbacks for {@link hasVisibleNavigationItems}. */
 export interface NavigationVisibilityOptions {
     /** Evaluator for item `visible` expressions. Defaults to always-visible. */
@@ -145,6 +302,8 @@ export interface NavigationVisibilityOptions {
     checkPermission?: PermissionChecker;
     /** Checker for `requiresObject` / `requiresService`. Defaults to pass. */
     checkCapability?: CapabilityChecker;
+    /** Checker for what a `doc` entry opens ({@link DocTargetChecker}). Defaults to pass. */
+    checkDocTarget?: DocTargetChecker;
     /**
      * Whether the host wires an `onAction` dispatcher. Without one, `action`
      * items are not rendered at all (framework#4509 — a nav entry that looks
@@ -240,21 +399,30 @@ export declare function resolveActiveNavItem(items: NavigationItem[], pathname:
 /**
  * Recursively filter navigation items by search query (case-insensitive label match).
  * Groups are kept if any child matches, with non-matching children pruned.
+ *
+ * Matches the text the row SHOWS: `labelOf` defaults to
+ * {@link resolveNavItemLabel} with no resolvers, and `NavigationRenderer` passes
+ * its own resolvers and locale so an unlabelled entry is found by the label it
+ * inherits (objectui#9868), not by a `label` it does not have, and a map-valued
+ * one by its entry in the viewer's locale (objectui#11299).
  */
-export declare function filterNavigationItems(items: NavigationItem[], query: string): NavigationItem[];
+export declare function filterNavigationItems(items: NavigationItem[], query: string, labelOf?: (item: NavigationItem) => string): NavigationItem[];
 /**
  * Renders a `NavigationItem[]` tree into Shadcn Sidebar components.
  *
  * Features:
- * - 7 navigation item types + separators
+ * - Every navigation item type + separators
  * - Nested collapsible groups
  * - Badge indicators
  * - Visibility expression evaluation
  * - RBAC permission guards
  * - Active-route highlighting
  * - Search filtering across navigation tree
- * - Pin/favorite items with dedicated "Favorites" section
- * - Drag-to-reorder navigation items
+ * - Pin/favorite items with dedicated "Favorites" section, in the user's
+ *   order and reorderable by dragging a pinned row (objectui#12059)
+ * - A host control on every entry in place of the pin action
+ *   (`renderItemAction`), and host rows after the pinned ones in the Favorites
+ *   section (`extraFavorites`) (objectui#12427)
  *
  * @example
  * ```tsx
@@ -266,9 +434,9 @@ export declare function filterNavigationItems(items: NavigationItem[], query: st
  *   searchQuery={searchTerm}
  *   enablePinning
  *   onPinToggle={(id, pinned) => updatePin(id, pinned)}
- *   enableReorder
- *   onReorder={(items) => saveOrder(items)}
+ *   pinnedOrder={pinnedIds}
+ *   onPinnedReorder={(ids) => savePinOrder(ids)}
  * />
  * ```
  */
-export declare function NavigationRenderer({ items, basePath, evaluateVisibility: evalVis, checkPermission: checkPerm, checkCapability: checkCap, onAction, searchQuery, enablePinning, onPinToggle, enableReorder, onReorder, resolveObjectLabel, resolveDashboardLabel, resolveViewLabel, t: tProp, templateContext, }: NavigationRendererProps): React.JSX.Element;
+export declare function NavigationRenderer({ items, basePath, evaluateVisibility: evalVis, checkPermission: checkPerm, checkCapability: checkCap, checkDocTarget, onAction, searchQuery, enablePinning, onPinToggle, renderItemAction, extraFavorites, pinnedOrder, onPinnedReorder, resolveTargetLabel, locale, t: tProp, templateContext, }: NavigationRendererProps): React.JSX.Element;

package/dist/PageHeader.d.ts

@@ -3,10 +3,11 @@ import { default as React } from 'react';
  * Props of this package's `<PageHeader>` React component.
  *
  * Named `PageHeaderComponentProps`, not `PageHeaderProps` (objectui#3161,
- * objectstack#4115 ledger batch 7) — the same name `@object-ui/app-shell`
- * settled on for its own header props in objectui#3169, deliberately reused
- * rather than re-invented, so one concept does not end up with two dialect
- * names one package apart.
+ * objectstack#4115 ledger batch 7). `@object-ui/app-shell` once used this
+ * name for its own console header (objectui#3169). That header is a different
+ * component, with rendered-node `title`, `subtitle` and `actions`, so since
+ * objectui#6349 (batch 8) it is `ConsolePageHeaderProps`, and this package is
+ * the one authority for this name.
  *
  * `@objectstack/spec/ui` owns `PageHeaderProps` for the AUTHORED `page:header`
  * node: a zod object of `title: string`, `subtitle`, an icon NAME, `breadcrumb`
@@ -17,7 +18,7 @@ import { default as React } from 'react';
  * prop rides along. Authored layer vs rendered layer, which is exactly the
  * one-name-two-layers failure objectstack#4115 exists to end.
  *
- * Pinned by `__tests__/spec-symbol-batch7.test.tsx`, which fails if the spec
+ * Pinned by `__tests__/spec-symbol-batch7.test.ts`, which fails if the spec
  * stops owning `PageHeaderProps` (then this can take the plain name back) or
  * starts owning `PageHeaderComponentProps`.
  */
@@ -32,7 +33,7 @@ export interface PageHeaderComponentProps extends React.HTMLAttributes<HTMLDivEl
      * was retired in objectui#3789, once the ADR-0087 D2 conversion
      * `page-header-subtitle-alias` was measured to reach EVERY spec-valid header
      * position on the load path (regions, slots, and containers nested to any
-     * depth — objectstack#6775 / #6776 / PR #7034). Stored metadata authored with
+     * depth — objectstack#6775 / objectstack-ai/objectstack#6776 / PR objectstack-ai/objectstack#7034). Stored metadata authored with
      * `description` is rewritten to `subtitle` before it ever reaches a renderer,
      * so the second line survives without this side holding a second dialect open.
      */

package/dist/ResponsiveGrid.d.ts

@@ -1,25 +1,59 @@
 import { default as React } from 'react';
-import { BreakpointColumnMap, BreakpointOrderMap } from '@objectstack/spec/ui';
 /**
- * Breakpoint column map (`BreakpointColumnMapSchema`) and breakpoint order map
- * (`BreakpointOrderMapSchema`), both re-exported from `@objectstack/spec/ui`.
+ * Breakpoint column map — grid column counts per Tailwind-style breakpoint,
+ * owned by this package since objectui#7580 (maintainer ruling 2026-09-04,
+ * option A).
  *
  * These were hand copies until objectui#4167, each carrying the word "mirrors"
  * — the doc-comment shape objectstack#4115 catalogues, where the claim is what
- * the next agent reads as canonical and the code is what actually decides. rc.6
- * publishes both names, and both copies happened to still be exact: six
- * optional numbers keyed `xs`…`2xl`, on a `$strict` schema. "Still exact" is
- * the argument FOR binding them, not against — the copies had nothing to
- * protect, so the only thing they could do from here was drift, and a
- * breakpoint the spec adds now arrives instead of silently not existing.
- *
- * `BreakpointOrderMap` has no read point in this package (`ResponsiveGrid`
- * resolves columns only); it is published because `ResponsiveConfigSchema`
- * pairs the two and an author configuring order needs the type. Bound rather
- * than deleted for that reason — deleting a published type is a separate
- * decision from stopping it being a fork.
+ * the next agent reads as canonical and the code is what actually decides. They
+ * were then bound by reference to `@objectstack/spec/ui`, which was right for
+ * as long as the spec published them.
+ *
+ * objectstack#11027 retired the whole `ui/responsive` vocabulary upstream, so
+ * there is no longer anything to bind to — and, unlike the four types that left
+ * with the key, this one has a renderer that implements it:
+ * {@link resolveColumnClasses} applies it on `ResponsiveGrid`'s render path.
+ * The tombstone's own return condition — the vocabulary "returns if and when a
+ * renderer implements it" — is met here, which is why the type is re-homed
+ * rather than deleted.
+ *
+ * The node that once made it authorable from JSON is gone. The
+ * `responsive-grid` registration retired under objectui#11441 (the
+ * maintainer's ruling `5950208338`, letter B), which kept this declaration and
+ * named the `grid` node with a breakpoint `columns` object as the one
+ * authorable spelling. `ResponsiveGrid` is now a React-only export, and this
+ * map is the type of its `columns` prop.
+ *
+ * ⚠️ Members are the retired `BreakpointColumnMapSchema`'s, verbatim: six
+ * optional column counts keyed `xs`…`2xl`. The schema was `$strict`, so no
+ * index signature is restored here either — an unknown breakpoint key was a
+ * parse error upstream and stays a type error here.
+ *
+ * `BreakpointOrderMap` RETIRED with the key (same ruling, item 3) and is NOT
+ * re-homed. Its own comment in this file already recorded the reason: it had no
+ * read point in this package — `ResponsiveGrid` resolves columns only — and it
+ * was published solely because the spec's `ResponsiveConfigSchema` paired the
+ * two, so an author configuring `order` needed the type. That pairing is what
+ * objectstack#11027 deleted; with the schema gone there is no order vocabulary
+ * left for it to be the type OF, and re-homing it would have re-declared a key
+ * nothing reads on either side of the boundary — the declare-without-enforce
+ * shape ADR-0049 removes.
+ *
+ * ⏳ Interim, and it self-expires: the pin is still `@objectstack/spec` 17.2.0,
+ * which PRE-dates the retirement and still exports this name, so the collision
+ * is real today and carries a reasoned entry in
+ * `scripts/check-spec-symbol-derivation.mjs`. The guard's ratchet 3 fails an
+ * ALLOW entry that excuses nothing, so the pin bump is forced to delete it.
  */
-export type { BreakpointColumnMap, BreakpointOrderMap };
+export interface BreakpointColumnMap {
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    '2xl'?: number;
+}
 export interface ResponsiveGridProps {
     /** Grid column map per breakpoint */
     columns?: BreakpointColumnMap;
@@ -31,8 +65,9 @@ export interface ResponsiveGridProps {
     children: React.ReactNode;
 }
 /**
- * ResponsiveGrid — A layout component that consumes @objectstack/spec
- * BreakpointColumnMapSchema for responsive grid layouts.
+ * ResponsiveGrid — A layout component that consumes this package's own
+ * BreakpointColumnMap (the six keys xs, sm, md, lg, xl, '2xl') for
+ * responsive grid layouts.
  *
  * Uses pure Tailwind CSS classes for responsive behavior (no JS resize listeners).
  *