@object-ui/layout 17.3.0 → 17.6.0

package/README.md

@@ -17,38 +17,87 @@ pnpm add @object-ui/layout
 ```
 
 **Peer Dependencies:**
-- `react` >= 18.0.0
-- `react-dom` >= 18.0.0
-- `react-router-dom` >= 6.0.0
+- `react` ^18.0.0 || ^19.0.0
+- `react-dom` ^18.0.0 || ^19.0.0
+- `react-router-dom` ^6.0.0 || ^7.0.0
+
+## 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:
+
+```typescript
+import '@object-ui/layout';
+```
+
+That is a supported entry point, not an accident of the build: `package.json`
+declares the registering modules in `sideEffects`, which is what stops a bundler
+from tree-shaking a side-effect-only import away (objectui#3899 — the manifest
+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.
 
 ## 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
@@ -60,17 +109,91 @@ 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:
@@ -78,17 +201,18 @@ The layout components are designed to work seamlessly with React Router:
 ```typescript
 import { BrowserRouter, Routes, Route } from 'react-router-dom';
 import { AppShell, SidebarNav } from '@object-ui/layout';
+import { Home, Users } from 'lucide-react';
 
 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 },
             ]}
           />
         }
@@ -105,36 +229,28 @@ function App() {
 
 ## 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
 <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>
 ```
 
 ## API Reference
 
-For detailed API documentation, visit the [Object UI Documentation](https://www.objectui.org/docs/layout).
-
-<!-- release-metadata:v3.3.0 -->
-
-## Compatibility
-
-- **React:** 18.x or 19.x
-- **Node.js:** ≥ 18
-- **TypeScript:** ≥ 5.0 (strict mode)
-- **`@objectstack/spec`:** ^3.3.0
-- **`@objectstack/client`:** ^3.3.0
-- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
+For detailed API documentation, visit the [Object UI Documentation](https://www.objectui.org/docs/layout/app-shell).
 
 ## Links
 
-- 📚 [Documentation](https://www.objectui.org/docs/layout)
+- 📚 [Documentation](https://www.objectui.org/docs/guide/layout)
 - 📦 [npm package](https://www.npmjs.com/package/@object-ui/layout)
 - 📝 [Changelog](./CHANGELOG.md)
 - 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)

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 } 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;
@@ -52,8 +70,8 @@ export interface AppSchemaRendererProps {
  * - 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

package/dist/AppShell.d.ts

@@ -10,8 +10,6 @@ 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) */
     title?: string;
 }

package/dist/NavigationRenderer.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { NavigationItem } from '@object-ui/types';
+import { NavigationItem, KeyedI18nLabel } from '@object-ui/types';
 /**
  * Callback to evaluate a visibility expression.
  * Return `true` if the item should be visible.
@@ -100,22 +100,6 @@ export interface NavigationRendererProps {
      * 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`.
-     */
-    resolveGroupLabel?: (groupId: string, fallbackLabel: string) => 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.
-     */
-    resolveItemLabel?: (itemId: string, fallbackLabel: string) => string;
     /**
      * Optional i18n translation function for resolving I18nLabel objects
      * (`{ key, defaultValue }`). When provided, labels are translated
@@ -141,14 +125,18 @@ export interface NavigationRendererProps {
 export declare function resolveIcon(name?: string): React.ComponentType<any>;
 /**
  * Resolve a NavigationItem label to a plain string.
- * Handles both plain strings and I18nLabel objects { key, defaultValue }.
- * When a `t` function is provided, I18nLabel objects are translated via i18next.
+ *
+ * Handles both plain strings and the KEYED i18n form
+ * `{ key, defaultValue?, params? }` — named `KeyedI18nLabel` in
+ * `@object-ui/types` since #4581, which is what this signature now states
+ * instead of a third inline copy of the same object literal. When a `t`
+ * function is provided the key is translated via i18next.
+ *
+ * "Keyed", not the spec's `I18nLabel`: that one is the INLINE LOCALE MAP
+ * (`{ en: 'Owner' }`) resolved against a BCP-47 locale, and the two answer
+ * wrongly for each other's input, silently (objectui#4167).
  */
-export declare function resolveLabel(label: string | {
-    key: string;
-    defaultValue?: string;
-    params?: Record<string, any>;
-}, t?: (key: string, options?: any) => string): string;
+export declare function resolveLabel(label: string | KeyedI18nLabel, t?: (key: string, options?: any) => string): string;
 /** Guard callbacks for {@link hasVisibleNavigationItems}. */
 export interface NavigationVisibilityOptions {
     /** Evaluator for item `visible` expressions. Defaults to always-visible. */
@@ -209,6 +197,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`).
  *
@@ -264,4 +271,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, onAction, searchQuery, enablePinning, onPinToggle, enableReorder, onReorder, resolveObjectLabel, resolveDashboardLabel, resolveViewLabel, t: tProp, templateContext, }: NavigationRendererProps): React.JSX.Element;

package/dist/PageHeader.d.ts

@@ -24,12 +24,19 @@ import { default as React } from 'react';
 export interface PageHeaderComponentProps extends React.HTMLAttributes<HTMLDivElement> {
     title: string;
     /**
-     * Optional secondary line under the title. Spec schemas use `subtitle`,
-     * the legacy console pages use `description` — both are supported and
-     * resolve {field.path} tokens against the current record context.
+     * Optional secondary line under the title. `subtitle` is the only spelling:
+     * it is the key `@objectstack/spec/ui`'s `PageHeaderProps` declares, and it
+     * resolves {field.path} tokens against the current record context.
+     *
+     * The legacy `description` alias this component used to read alongside it
+     * 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
+     * `description` is rewritten to `subtitle` before it ever reaches a renderer,
+     * so the second line survives without this side holding a second dialect open.
      */
     subtitle?: string;
-    description?: string;
     /**
      * Optional icon for the header chip. Accepts either a string Lucide icon
      * name (resolved via `LazyIcon`, the standard ObjectUI helper) or a
@@ -66,4 +73,4 @@ export interface PageHeaderComponentProps extends React.HTMLAttributes<HTMLDivEl
         };
     };
 }
-export declare function PageHeader({ title, subtitle, description, icon, action, actions, showBack, schema, className, children, ...props }: PageHeaderComponentProps): React.JSX.Element;
+export declare function PageHeader({ title, subtitle, icon, action, actions, showBack, schema, className, children, ...props }: PageHeaderComponentProps): React.JSX.Element;

package/dist/ResponsiveGrid.d.ts

@@ -1,28 +1,25 @@
 import { default as React } from 'react';
+import { BreakpointColumnMap, BreakpointOrderMap } from '@objectstack/spec/ui';
 /**
- * Spec-aligned breakpoint column map (mirrors @objectstack/spec BreakpointColumnMapSchema).
- * Maps breakpoint names to grid column counts (1-12).
- */
-export interface BreakpointColumnMap {
-    xs?: number;
-    sm?: number;
-    md?: number;
-    lg?: number;
-    xl?: number;
-    '2xl'?: number;
-}
-/**
- * Spec-aligned breakpoint order map (mirrors @objectstack/spec BreakpointOrderMapSchema).
- * Maps breakpoint names to display order numbers.
+ * Breakpoint column map (`BreakpointColumnMapSchema`) and breakpoint order map
+ * (`BreakpointOrderMapSchema`), both re-exported from `@objectstack/spec/ui`.
+ *
+ * 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.
  */
-export interface BreakpointOrderMap {
-    xs?: number;
-    sm?: number;
-    md?: number;
-    lg?: number;
-    xl?: number;
-    '2xl'?: number;
-}
+export type { BreakpointColumnMap, BreakpointOrderMap };
 export interface ResponsiveGridProps {
     /** Grid column map per breakpoint */
     columns?: BreakpointColumnMap;

package/dist/index.d.ts

@@ -2,11 +2,11 @@
  * ObjectUI Layout
  * Copyright (c) 2024-present ObjectStack Inc.
  */
-export * from './PageHeader';
-export * from './AppShell';
-export * from './PageCard';
-export * from './SidebarNav';
-export * from './ResponsiveGrid';
-export * from './NavigationRenderer';
-export * from './AppSchemaRenderer';
+export * from './PageHeader.js';
+export * from './AppShell.js';
+export * from './PageCard.js';
+export * from './SidebarNav.js';
+export * from './ResponsiveGrid.js';
+export * from './NavigationRenderer.js';
+export * from './AppSchemaRenderer.js';
 export declare function registerLayout(): void;