@object-ui/layout 17.5.0 → 17.7.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`,
-`app-shell`, `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,34 +38,75 @@ 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
 
-Complete application shell with header, sidebar, and main content area.
+Complete application shell with a top navbar, a sidebar, and a main content area.
 
 ```typescript
 import { AppShell } from '@object-ui/layout';
 
 <AppShell
-  header={<div>Header Content</div>}
+  navbar={<div>Navbar Content</div>}
   sidebar={<div>Sidebar Content</div>}
 >
   <div>Main Content</div>
 </AppShell>
 ```
 
+The top bar's content goes in `navbar`. `AppShell` renders the `<header>`
+element itself (`src/AppShell.tsx:248`) and `{navbar}` is the only thing that
+fills it (`:249`) — there is no `header` prop. This example used to pass one
+(objectui#4817), and because the component destructures a fixed key list with
+**no rest element** (`:233-241`), the node was built and then dropped on the
+floor: copied verbatim, the snippet rendered an empty top bar and said nothing.
+
+Like `SidebarNav` below, `AppShell` is composed in JSX and is **not** on the
+`ComponentRegistry`: four of its seven props are `React.ReactNode` slots that no
+JSON document can fill, so the `app-shell` key was retired in objectui#4841 and
+`{ "type": "app-shell" }` now reports `Unknown component type`. When the whole
+shell has to come from metadata, the key for that is `app-schema-renderer`.
+
+#### `AppShellProps`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `React.ReactNode` | — (required) | Main content, rendered inside the `<main>` element. |
+| `navbar` | `React.ReactNode` | — | Top bar content. `AppShell` supplies the sticky `<header>` around it, so pass only what goes inside. |
+| `sidebar` | `React.ReactNode` | — | Left sidebar node, rendered as a flex sibling of the content. Pass `SidebarNav`, or your own node. |
+| `rightRail` | `React.ReactNode` | — | Optional right-side rail. It reflows the content beside it rather than overlaying it (ADR-0057 P3a); absent → unchanged single-pane layout. |
+| `className` | `string` | — | Tailwind overrides for the `<main>` content element — **not** for the outer container. |
+| `defaultOpen` | `boolean` | `true` | Initial open state of the underlying Shadcn `SidebarProvider`. |
+| `branding` | `AppShellBranding` | — | App branding, applied by `useAppShellBranding`: `primaryColor` / `accentColor` become CSS custom properties on the document root (re-derived for dark mode), `favicon` sets the icon link's `href`, and `title` sets `document.title`. |
+
 ### PageHeader
 
-Page title block with an optional description, used at the top of a page's
+Page title block with an optional subtitle, used at the top of a page's
 content area.
 
 ```typescript
 import { PageHeader } from '@object-ui/layout';
 
-<PageHeader title="Dashboard" description="View your metrics" />
+<PageHeader title="Dashboard" subtitle="View your metrics" />
 ```
 
+`subtitle` is the only spelling for the secondary line — it is the key
+`@objectstack/spec/ui`'s `PageHeaderProps` declares. The legacy `description`
+alias this component used to read as well was retired in objectui#3789; stored
+metadata still carrying it is rewritten to `subtitle` at load time by the
+ADR-0087 D2 conversion `page-header-subtitle-alias`.
+
 > **Rendering a whole `page` node?** That belongs to `PageRenderer` in
 > `@object-ui/components`, which is what the `page` component key resolves to —
 > it handles page types (record/home/app/utility), named regions and page
@@ -78,42 +118,129 @@ import { PageHeader } from '@object-ui/layout';
 Navigation sidebar component with React Router integration.
 
 ```typescript
-import { SidebarNav } from '@object-ui/layout';
+import { SidebarNav, type NavItem } from '@object-ui/layout';
+import { Home, Settings, Users } from 'lucide-react';
 
-const navItems = [
-  { label: 'Dashboard', path: '/dashboard', icon: 'home' },
-  { label: 'Users', path: '/users', icon: 'users' },
-  { label: 'Settings', path: '/settings', icon: 'settings' }
+const navItems: NavItem[] = [
+  { title: 'Dashboard', href: '/dashboard', icon: Home },
+  { title: 'Users', href: '/users', icon: Users },
+  { title: 'Settings', href: '/settings', icon: Settings },
 ];
 
 <SidebarNav items={navItems} />
 ```
 
+An item's label is `title` and its target is `href` — and `icon` is a **component**,
+not an icon name: it is rendered as `<item.icon />` (`src/SidebarNav.tsx:60`, `:109`),
+so pass the imported Lucide component itself. This example used to be written with
+`label` / `path` / `icon: 'home'`, none of which `NavItem` declares (objectui#3999);
+copied as-is it produced rows with no label at all, a `NavLink` whose `to` was
+`undefined`, and the string `'home'` handed to React as an unknown lowercase tag.
+Annotating the array as `NavItem[]` is what turns that whole class of typo back into
+a compile error where it is written, instead of a blank sidebar at runtime.
+
+#### `SidebarNavProps`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `NavItem[] \| NavGroup[]` | — (required) | Flat item list, or grouped sections. The array must be homogeneous: only the **first** element is probed to decide which of the two it is. |
+| `title` | `string` | `'Application'` | Section label shown above a flat `NavItem[]`. Ignored when `items` is a `NavGroup[]` — each group prints its own `label`. |
+| `className` | `string` | — | Tailwind overrides, forwarded to the root `Sidebar`. |
+| `collapsible` | `'offcanvas' \| 'icon' \| 'none'` | `'icon'` | Collapse behaviour of the underlying Shadcn `Sidebar`. |
+| `searchEnabled` | `boolean` | `false` | Renders a search box that filters items by `title` (an item also survives when one of its `children` matches). |
+| `searchPlaceholder` | `string` | `'Search…'` | Placeholder for that search box. |
+
+#### `NavItem`
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | — (required) | The visible label, and what search matches against. |
+| `href` | `string` | — (required) | `NavLink` target; also the React key, so keep it unique within its list. Active state is `pathname === href`. |
+| `icon` | `React.ComponentType<{ className?: string }>` | — | The icon **component** (e.g. `Home` from `lucide-react`), not its name. |
+| `badge` | `string \| number` | — | Trailing badge content. Rendered whenever it is not `null`/`undefined`, so `0` shows. |
+| `badgeVariant` | `'default' \| 'destructive' \| 'outline'` | `'default'` | Badge styling. |
+| `children` | `NavItem[]` | — | Nested sub-items. A non-empty list turns the row into a collapsible group: the parent's own `href` is then no longer a link, only the children are. |
+
+#### `NavGroup`
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `label` | `string` | Section heading printed above the group. |
+| `items` | `NavItem[]` | The group's items — same `NavItem` shape as above, nesting included. |
+
+```typescript
+import { SidebarNav, type NavGroup } from '@object-ui/layout';
+import { FolderOpen, Home, Settings } from 'lucide-react';
+
+const navGroups: NavGroup[] = [
+  {
+    label: 'Workspace',
+    items: [
+      { title: 'Dashboard', href: '/dashboard', icon: Home },
+      {
+        title: 'Projects',
+        href: '/projects',
+        icon: FolderOpen,
+        badge: 3,
+        children: [
+          { title: 'Active', href: '/projects/active' },
+          { title: 'Archived', href: '/projects/archived', badge: 'WIP', badgeVariant: 'outline' },
+        ],
+      },
+    ],
+  },
+  {
+    label: 'System',
+    items: [{ title: 'Settings', href: '/settings', icon: Settings }],
+  },
+];
+
+<SidebarNav items={navGroups} searchEnabled />
+```
+
+Note that `SidebarNav` is a plain React component: unlike the keys listed under
+[Registration](#registration) it is **not** on the `ComponentRegistry`, so it is
+composed in JSX rather than authored as a JSON node. Full guide:
+[SidebarNav docs](https://www.objectui.org/docs/layout/sidebar-nav).
+
 ## Usage with React Router
 
 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>
       <AppShell
-        header={<div className="p-4">My App</div>}
+        navbar={<div className="p-4">My App</div>}
         sidebar={
           <SidebarNav
             items={[
-              { label: 'Dashboard', path: '/', icon: 'home' },
-              { label: 'Users', path: '/users', icon: 'users' }
+              { title: 'Dashboard', href: '/', icon: Home },
+              { title: 'Users', href: '/users', icon: Users },
             ]}
           />
         }
       >
         <Routes>
           <Route path="/" element={<Dashboard />} />
-          <Route path="/users" element={<Users />} />
+          <Route path="/users" element={<UsersPage />} />
         </Routes>
       </AppShell>
     </BrowserRouter>
@@ -121,17 +248,28 @@ 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
 
-All components accept `className` prop for Tailwind customization:
+`AppShell` takes a single `className`, and it lands on the `<main>` content
+element (`src/AppShell.tsx:256`) rather than on the outer container. There is no
+per-slot `headerClassName` / `sidebarClassName` — the navbar and the sidebar are
+nodes **you** build, so style them where you build them:
 
 ```typescript
+import { AppShell } from '@object-ui/layout';
+
 <AppShell
   className="bg-gray-50"
-  headerClassName="border-b"
-  sidebarClassName="bg-white shadow-lg"
+  navbar={<div className="border-b px-4">My App</div>}
+  sidebar={<div className="bg-white shadow-lg">Sidebar Content</div>}
 >
-  {children}
+  <div>Main Content</div>
 </AppShell>
 ```
 

package/dist/AppSchemaRenderer.d.ts

@@ -1,8 +1,26 @@
 import { default as React } from 'react';
 import { AppComponentSchema, NavigationItem } from '@object-ui/types';
-import { VisibilityEvaluator, PermissionChecker, CapabilityChecker } from './NavigationRenderer';
-/** Mobile navigation display mode */
-export type MobileNavMode = 'drawer' | 'bottom_nav' | 'hamburger';
+import { VisibilityEvaluator, PermissionChecker, CapabilityChecker, DocTargetChecker } from './NavigationRenderer.js';
+/**
+ * Mobile navigation display mode — the two modes this renderer implements.
+ *
+ * `drawer` is the default (the sidebar rides in the AppShell's mobile sheet
+ * overlay); `bottom_nav` additionally renders the fixed bottom bar. Those are
+ * the renderer's only two read points for the prop — the default below and the
+ * `=== 'bottom_nav'` comparison that gates the bottom bar — so every value that
+ * is not `bottom_nav` produces drawer behaviour.
+ *
+ * A third member (spelled after the collapsed-sidebar menu button) rode in this
+ * union with a JSDoc line promising "collapsed sidebar" and NO read point
+ * anywhere, which made it behaviourally identical to `drawer` while reading as
+ * a capability. Retired in objectui#3985 under ADR-0049 enforce-or-remove
+ * (maintainer ruling 2026-08-10): it never was behaviour, so it is gone from
+ * this union and from the published vocabulary rather than being documented as
+ * a synonym for the default. Wanting a collapsed-sidebar mode is an
+ * implementation card first, and the value comes back with a read point — never
+ * as a declaration on its own.
+ */
+export type MobileNavMode = 'drawer' | 'bottom_nav';
 export interface AppSchemaRendererProps {
     /** The AppSchema JSON to render */
     schema: AppComponentSchema;
@@ -16,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) */
@@ -47,13 +67,13 @@ export interface AppSchemaRendererProps {
  * 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
  *   whose items are all gated away is hidden and never auto-activated
- * - Mobile modes: `drawer` (sheet overlay, default), `bottom_nav` (fixed
- *   bottom bar), `hamburger` (collapsed sidebar)
+ * - Mobile modes: `drawer` (sheet overlay, default) and `bottom_nav` (fixed
+ *   bottom bar) — see `MobileNavMode` for why that list is two long
  * - Evaluates `visible` expressions and `requiredPermissions` on every item
  *
  * @example
@@ -69,4 +89,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, enableReorder, onReorder, }: AppSchemaRendererProps): React.JSX.Element;

package/dist/AppShell.d.ts

@@ -10,9 +10,11 @@ export interface AppShellBranding {
     accentColor?: string;
     /** Favicon URL — replaces the <link rel="icon"> href */
     favicon?: string;
-    /** Logo URL — passed to sidebar/navbar via context */
-    logo?: 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 {
@@ -34,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

@@ -27,6 +27,59 @@ 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;
 export interface NavigationRendererProps {
     /** Navigation items to render */
     items: NavigationItem[];
@@ -41,6 +94,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.
      *
@@ -72,54 +127,35 @@ export interface NavigationRendererProps {
     /** 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.
-     */
-    resolveObjectLabel?: (objectName: string, fallbackLabel: string) => 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`.
-     */
-    resolveDashboardLabel?: (dashboardName: string, fallbackLabel: string) => string;
-    /**
-     * 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).
-     */
-    resolveViewLabel?: (objectName: string, viewName: string, fallbackLabel: string) => string;
-    /**
-     * Optional label resolver for navigation group items.
-     * Called with `(groupId, fallbackLabel)` for items where
-     * `item.type === 'group'` and `item.label` is a plain string.
-     * Enables convention-based i18n via
-     * `{ns}.apps.{appName}.navigation.{groupId}.label`.
+     * 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.
      */
-    resolveGroupLabel?: (groupId: string, fallbackLabel: string) => string;
+    locale?: string;
     /**
-     * Optional label resolver for non-object/non-dashboard/non-group nav
-     * items (url, page, report, custom). Called with `(itemId, fallbackLabel)`
-     * for items that have a plain-string label and a stable `id`.
-     * Convention: `{ns}.apps.{appName}.navigation.{itemId}.label` — same
-     * key shape as `resolveGroupLabel` so a single i18n helper covers both.
+     * 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}.
      */
-    resolveItemLabel?: (itemId: string, fallbackLabel: string) => string;
+    resolveTargetLabel?: NavTargetLabelResolver;
     /**
-     * Optional i18n translation function for resolving I18nLabel objects
-     * (`{ key, defaultValue }`). When provided, labels are translated
-     * through i18next; otherwise falls back to `defaultValue`.
+     * 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;
     /**
@@ -153,6 +189,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. */
@@ -161,6 +236,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
@@ -213,6 +290,25 @@ export interface NavTemplateContext {
      */
     contextValues?: Record<string, string | null | undefined>;
 }
+/**
+ * The wire encoding of the declared `runAction` nav slot — ONE definition,
+ * sited with `resolveHref` because that is the only thing that writes it.
+ *
+ * `ObjectNavItemSchema.runAction` (objectstack#7253) declares WHICH action an
+ * object nav entry auto-runs on arrival; the URL is how that declaration
+ * survives the navigation, because the list surface mounts in a fresh render
+ * tree with nothing but the location to read. Naming the param after the slot
+ * is deliberate: the slot owns the name, so producer and consumer cannot drift.
+ *
+ * Before this constant existed, the name was a bare `'runAction'` literal
+ * hand-written at both ends — a private convention no schema declared, so
+ * `objectui validate` could not see it, `RESERVED_URL_PARAMS` did not list it,
+ * and a page could have repurposed the name with nothing to catch the
+ * collision. Import this; never re-spell it. `@object-ui/app-shell`'s
+ * `urlParams` re-exports it into the reserved registry rather than restating
+ * it, so there is still exactly one definition.
+ */
+export declare const NAV_RUN_ACTION_PARAM = "runAction";
 /**
  * Resolve a NavigationItem to an absolute href (relative to `basePath`).
  *
@@ -237,13 +333,19 @@ 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
@@ -268,4 +370,4 @@ export declare function filterNavigationItems(items: NavigationItem[], query: st
  * />
  * ```
  */
-export declare function NavigationRenderer({ items, basePath, evaluateVisibility: evalVis, checkPermission: checkPerm, checkCapability: checkCap, onAction, searchQuery, enablePinning, onPinToggle, enableReorder, onReorder, resolveObjectLabel, resolveDashboardLabel, resolveGroupLabel, resolveViewLabel, resolveItemLabel, t: tProp, templateContext, }: NavigationRendererProps): React.JSX.Element;
+export declare function NavigationRenderer({ items, basePath, evaluateVisibility: evalVis, checkPermission: checkPerm, checkCapability: checkCap, checkDocTarget, onAction, searchQuery, enablePinning, onPinToggle, enableReorder, onReorder, resolveTargetLabel, locale, t: tProp, templateContext, }: NavigationRendererProps): React.JSX.Element;