harebear-ui 0.6.0 → 0.8.0

package/AGENTS.md

@@ -14,6 +14,7 @@ Consumers get compiled ESM + types from `dist/` and a Tailwind stylesheet (`hare
 | `pnpm gen`               | Regenerate `src/index.ts` from component export lists. Run after adding or renaming exports.      |
 | `pnpm format`            | Biome format + safe fixes.                                                                        |
 | `pnpm shadcn add <name>` | Pull a new shadcn component into `src/components/ui/`.                                            |
+| `pnpm shots [filter]`    | Regenerate README images in `.github/assets/` (needs `pnpm dev` running, Chrome and `cwebp`).     |
 
 ## Layout
 
@@ -24,27 +25,46 @@ src/
   index.ts              Generated barrel. Do not edit by hand.
   components/ui/        shadcn primitives (radix-nova style), restyled. Keep upstream structure.
   components/theme/     ThemeProvider, ThemeToggle, ThemeScript.
-  components/admin/     Layout and dashboard composites (AppShell, StatCard, PageHeader...).
-  components/data/      DataTable, TrendChart, Sparkline, BarList, StatusBars.
-  components/ai/        Chat composites (ChatThread, ChatMessage, PromptInput, ModelPicker, CodeSnippet...).
+  components/admin/     Layout and dashboard composites (AppShell, AppNav, FocusLayout, SettingsSection, StatCard...).
+  components/data/      DataTable, TrendChart, Sparkline, BarList, StatusBars, TaskRow, SectionedList.
+  components/ai/        Chat composites (ChatThread, ChatMessage, PromptInput...) and the assistant layer (AssistantProvider, AssistantDock, AskBox, DictationButton, ActionReceipt).
   components/auth/      AuthLayout, LoginForm, SignupForm (parameterized shadcn login/signup blocks).
+  components/layout/    Prop-driven layout and text (Stack, Text, Metric, ShowMore, Collapse).
   hooks/, lib/utils.ts  Shared hooks and cn().
-playground/screens/     Reference screens that use only public exports (#admin, #chat, #records, #home, #auth, #catalog). Visual spec and usage examples.
-docs/COMPONENTS.md      Consumer-facing catalog. Shipped. Test-enforced to mention every export.
+playground/screens/     Reference screens that use only public exports (#admin, #chat, #agent, #records, #home, #household, #settings, #auth, #catalog). Visual spec and usage examples.
+docs/COMPONENTS.md      Consumer-facing catalog. Shipped. Test-enforced to mention every export. "Agent-first apps" is the recipe for household/assistant apps.
+docs/ROADMAP.md         Proposed and built components for household and agent-first apps. Mark items built when they land.
+docs/guides/            Getting started (per framework), theming, working with agents. Shipped.
 llms.txt, skills/       Consumer-facing agent docs. Shipped.
-bin/harebear-ui.mjs     `npx harebear-ui init|docs` for consuming apps.
+bin/harebear-ui.mjs     `npx harebear-ui init|docs [name...]` for consuming apps. Zero dependencies.
+scripts/screenshots.mjs `pnpm shots`: captures playground screens and renders .github/assets/art/*.html to images.
+.github/assets/         README imagery (not shipped): logo.svg, screens/*.webp, hero/light-dark/agents art, social.png.
 test/                   Vitest: API snapshot, docs coverage, token integrity, behavior.
 ```
 
 ## Adding a component
 
-1. Pick the folder by purpose (`admin`, `data`, `ai`, `auth`; `ui` only for shadcn primitives).
+1. Pick the folder by purpose (`admin`, `layout`, `data`, `ai`, `auth`; `ui` only for shadcn primitives and small harebear primitives such as `CheckCircle`).
 2. Follow the existing files: `"use client"` first line, named function component, props interface exported as `<Name>Props`, `data-slot="<kebab-name>"` on the root, `className` merged last with `cn()`, rest props spread on the root.
-3. Style only with tokens (`bg-card`, `text-muted-foreground`, `bg-primary-soft`, `shadow-card`, `rounded-xl`). No hex, no palette colors. Status takes a `tone` (`success | warning | danger | info | neutral`).
-4. `pnpm gen`, then add the component to `docs/COMPONENTS.md` (the docs test fails otherwise) and to the index in `llms.txt`.
-5. Use it in a playground screen if it is visual, and look at it in light and dark mode and at 375px width.
-6. Add a behavior test in `test/components.test.tsx` if it has logic. `pnpm test -u` to accept the new export in the snapshot.
-7. `pnpm check`.
+3. Style only with tokens (`bg-card`, `text-muted-foreground`, `bg-primary-soft`, `shadow-card`, `rounded-xl`). No hex, no palette colors. Status takes a `tone` (`success | warning | danger | info | neutral`); categories (members, lists) use `category-1..6`. A box around a bare field uses `focus-box`. Motion is CSS only and off under `prefers-reduced-motion` (`motion-reduce:`; `Collapse` for height changes).
+4. Floors: checks 24px, phone touch targets 44px, no text under 12px, icon-only buttons have `aria-label`.
+5. `pnpm gen`, then add the component to `docs/COMPONENTS.md` (the docs test fails otherwise) and to the index in `llms.txt`. Use a heading like ``### `Name` `` or a table row with the name in backticks, so `npx harebear-ui docs Name` finds it.
+6. Use it in a playground screen if it is visual, and look at it in light and dark mode and at 375px width.
+7. Add a behavior test in `test/` if it has logic (`components.test.tsx`, `building-blocks.test.tsx`, `household.test.tsx` for the household and assistant layer). `pnpm test -u` to accept the new export in the snapshot.
+8. `pnpm check`.
+
+## Looking at your work
+
+- `pnpm dev`, then open http://localhost:5199/#admin (or `#chat`, `#agent`, `#records`, `#home`, `#household`, `#settings`, `#auth`, `#catalog`).
+- `?mode=dark` or `?mode=light` pins the theme without touching localStorage; `?shot` hides the screen switcher. Example: http://localhost:5199/?mode=dark&shot#agent
+- A headless capture: `pnpm shots admin` writes `.github/assets/screens/admin-*.webp`.
+
+## README imagery
+
+- `.github/assets/logo.svg` is the mark. It is hand-written SVG; edit it directly. `logo.png` is exported from it.
+- Screens are real playground captures. Art (`hero`, `light-dark`, `agents`) is HTML in `.github/assets/art/` that composes those captures, rendered by `pnpm shots`. `social.png` is the hero at 1x for GitHub's social preview (upload it by hand in repo Settings).
+- After a visible change to a screen or the theme, run `pnpm shots` and commit the images with the change. Check the results by eye before committing.
+- If `npx harebear-ui init` output changes, update the terminal text in `art/agents.html` to match.
 
 ## Changing shadcn primitives
 

package/README.md

@@ -1,28 +1,72 @@
-# harebear-ui
-
-Pre-themed React components for admin tools, data apps, and AI chat. shadcn/ui primitives restyled to one opinionated design system, plus the composites you end up building every time: app shell, KPI cards, data table, trend charts, chat thread, prompt composer, model picker.
-
-React 19 · Tailwind CSS v4 · Radix · TanStack Table v9 · Recharts 3 · TypeScript
-
-## Install
+<p align="center">
+  <img src=".github/assets/logo.svg" width="72" height="72" alt="harebear-ui logo" />
+</p>
+
+<h1 align="center">harebear-ui</h1>
+
+<p align="center">
+  Pre-themed React components for admin tools, data apps and AI chat.<br />
+  shadcn/ui restyled to one design system, plus the composites you build every time. Agent-ready out of the box.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/harebear-ui"><img src="https://img.shields.io/npm/v/harebear-ui?style=flat-square&color=5b84ff&labelColor=101012" alt="npm version" /></a>
+  <a href="https://github.com/HMilbradt/harebear-ui/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/HMilbradt/harebear-ui/ci.yml?branch=main&style=flat-square&labelColor=101012&label=CI" alt="CI status" /></a>
+  <img src="https://img.shields.io/badge/React-19-5b84ff?style=flat-square&labelColor=101012" alt="React 19" />
+  <img src="https://img.shields.io/badge/Tailwind_CSS-v4-a98ae0?style=flat-square&labelColor=101012" alt="Tailwind CSS v4" />
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/harebear-ui?style=flat-square&color=3cb8a8&labelColor=101012" alt="MIT license" /></a>
+</p>
+
+<p align="center">
+  <img src=".github/assets/hero.webp" alt="harebear-ui: an admin dashboard, an agent chat with approvals and a records table, all in dark mode" />
+</p>
+
+<p align="center">
+  <a href="docs/guides/getting-started.md"><b>Get started</b></a> ·
+  <a href="docs/COMPONENTS.md"><b>Components</b></a> ·
+  <a href="docs/guides/theming.md"><b>Theming</b></a> ·
+  <a href="docs/guides/agents.md"><b>AI agents</b></a> ·
+  <a href="playground/screens"><b>Reference screens</b></a>
+</p>
+
+## Why
+
+Every internal tool, dashboard and chat app ends up needing the same pieces: an app shell with a collapsible sidebar, KPI cards, a sortable table with a detail panel, trend charts, a chat thread with a composer and tool calls. shadcn/ui gives you primitives to build them. harebear-ui gives you them built, in one consistent look, so you (or your agent) spend the time on the product.
+
+- **Every shadcn/ui primitive**, same names and props, restyled to one set of tokens.
+- **Composites on top:** `AppShell`, `StatCard`, `DataTable`, `TrendChart`, `ChatShell`, `PromptInput`, `ToolStep`, `ApprovalCard`, `LoginForm` and more.
+- **Light and dark from one accent.** Change the brand color, radius and font with props or CSS variables.
+- **Docs agents can use.** `npx harebear-ui init` installs project rules and a Claude Code skill; `npx harebear-ui docs DataTable` prints one component's API.
+
+## Screens
+
+Built only from public exports. Each one is a file in [`playground/screens/`](playground/screens) you can copy from.
+
+<table>
+  <tr>
+    <td width="50%"><a href="playground/screens/admin.tsx"><img src=".github/assets/screens/admin-dark.webp" alt="Admin dashboard with KPI cards, a visitors trend chart and traffic sources" /></a><br /><b>Admin dashboard</b>: <code>AppShell</code>, <code>StatCard</code>, <code>TrendChart</code>, <code>BarList</code></td>
+    <td width="50%"><a href="playground/screens/agent.tsx"><img src=".github/assets/screens/agent-dark.webp" alt="Agent chat waiting on a command approval, with a details panel" /></a><br /><b>Agent with approvals</b>: <code>ChatShell</code>, <code>ToolGroup</code>, <code>ApprovalCard</code></td>
+  </tr>
+  <tr>
+    <td width="50%"><a href="playground/screens/chat.tsx"><img src=".github/assets/screens/chat-dark.webp" alt="AI chat with a conversation list, highlighted code and a prompt composer" /></a><br /><b>AI chat</b>: <code>ChatPanel</code>, <code>ChatMessage</code>, <code>CodeSnippet</code>, <code>PromptInput</code></td>
+    <td width="50%"><a href="playground/screens/records.tsx"><img src=".github/assets/screens/records-dark.webp" alt="Customer table with status badges and a detail panel for the selected row" /></a><br /><b>Records</b>: <code>DataTable</code>, <code>KeyValueGrid</code>, <code>Timeline</code></td>
+  </tr>
+  <tr>
+    <td width="50%"><a href="playground/screens/home.tsx"><img src=".github/assets/screens/home-dark.webp" alt="Status home page with service tiles and uptime bars" /></a><br /><b>Status home</b>: <code>LinkTile</code>, <code>StatusBars</code>, <code>Sparkline</code></td>
+    <td width="50%"><a href="playground/screens/auth.tsx"><img src=".github/assets/screens/auth-dark.webp" alt="Sign-in page" /></a><br /><b>Auth</b>: <code>AuthLayout</code>, <code>LoginForm</code>, <code>SignupForm</code></td>
+  </tr>
+</table>
+
+## Quick start
+
+Needs React 19 and Tailwind CSS v4.
 
 ```bash
 npm i harebear-ui
-```
-
-```bash
 npx harebear-ui init
 ```
 
-`init` adds the stylesheet import to your Tailwind entry CSS, writes a harebear-ui section into `AGENTS.md` (or `CLAUDE.md`), and installs a Claude Code skill in `.claude/skills/`. Flags: `--css <file>`, `--no-agents`, `--no-skill`.
-
-Manual setup, if you prefer:
-
-```css
-/* app.css */
-@import "tailwindcss";
-@import "harebear-ui/styles.css";
-```
+`init` adds the stylesheet import after `@import "tailwindcss"`, writes a harebear-ui section into `AGENTS.md` (or `CLAUDE.md`), and installs a Claude Code skill. Then wrap your root:
 
 ```tsx
 import { ThemeProvider, Toaster, TooltipProvider } from "harebear-ui"
@@ -39,24 +83,26 @@ export function Root() {
 }
 ```
 
-Requires Tailwind CSS v4 in the app. Geist and Geist Mono are bundled.
-
-## Use
+And build:
 
 ```tsx
-import { AppShell, PageHeader, StatCard, Button, DataTable } from "harebear-ui"
+import { AppShell, Button, DataTable, PageHeader, StatCard } from "harebear-ui"
 ```
 
-Everything imports from the package root. Primitives keep shadcn/ui names and props.
+Everything imports from the package root. Geist and Geist Mono are bundled.
 
-- **Component catalog:** [docs/COMPONENTS.md](docs/COMPONENTS.md), also at `node_modules/harebear-ui/docs/COMPONENTS.md` or `npx harebear-ui docs`.
-- **Reference screens:** [playground/screens](playground/screens) has an admin dashboard, an AI chat, a data table with detail panel, and a status home page built only from public exports.
+Step-by-step setup for **Vite**, **Next.js** and **React Router**, plus troubleshooting: [Getting started](docs/guides/getting-started.md).
 
 ## Theming
 
-Light and dark mode, accent, radius, and font are runtime props on `ThemeProvider` (`useTheme()` changes them live). Every component reads shadcn-named tokens, so you can override any of them in CSS:
+<img src=".github/assets/light-dark.webp" alt="The same admin dashboard split diagonally between light and dark mode" />
+
+Light, dark and system modes, accent, radius and font are `ThemeProvider` props, changeable live with `useTheme()`. Every component reads shadcn-named tokens, so you can override any of them in CSS:
 
 ```css
+@import "tailwindcss";
+@import "harebear-ui/styles.css";
+
 :root {
   --brand: #0f8a7e;
   --radius: 0.625rem;
@@ -66,19 +112,43 @@ Light and dark mode, accent, radius, and font are runtime props on `ThemeProvide
 }
 ```
 
-For SSR apps, render `<ThemeScript />` in `<head>` to avoid a flash of the wrong mode.
+SSR apps render `<ThemeScript />` in `<head>` to avoid a flash of the wrong mode. More in [Theming](docs/guides/theming.md).
 
-## For AI agents
+## Built for AI agents
 
-The package ships its own agent docs:
+<img src=".github/assets/agents.webp" alt="Terminal running harebear-ui init and docs, with the four agent files it sets up" />
 
-| File                          | For                                                    |
-| ----------------------------- | ------------------------------------------------------ |
-| `llms.txt`                    | Short index: setup, rules, component list.             |
-| `docs/COMPONENTS.md`          | Every export with props and examples.                  |
-| `skills/harebear-ui/SKILL.md` | Claude Code skill; `npx harebear-ui init` installs it. |
+The package carries its own agent docs, so Claude Code, Codex, Cursor and friends know what exists and how to use it:
 
-Working on this repo with an agent: see [AGENTS.md](AGENTS.md).
+| File                          | For                                                                   |
+| ----------------------------- | --------------------------------------------------------------------- |
+| `llms.txt`                    | Short index: setup, rules, every export by group.                     |
+| `docs/COMPONENTS.md`          | Every export with props and examples. Test-enforced to stay complete. |
+| `docs/guides/`                | Setup per framework, theming, working with agents.                    |
+| `skills/harebear-ui/SKILL.md` | Claude Code skill; `npx harebear-ui init` installs it.                |
+
+Agents look up one component at a time instead of reading the whole catalog:
+
+```bash
+npx harebear-ui docs DataTable StatCard   # exports
+npx harebear-ui docs Prompt               # prefix: PromptInput, PromptInputChip, PromptInputSelect
+npx harebear-ui docs Tokens               # a section
+```
+
+Prompts that work, and what to check before you accept an agent's UI: [Working with AI agents](docs/guides/agents.md).
+
+## What's inside
+
+| Group         | Exports                                                                                                                                       |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Layout, admin | `SidebarLayout`, `AppShell`, `AppNav`, `FocusLayout`, `SettingsSection`, `PageHeader`, `StatCard`, `StatusBadge`, `UserMenu`, `ConfirmDialog` |
+| Data          | `SectionedList`, `TaskRow`, `DataTable`, `TrendChart`, `BarList`, `Sparkline`, `StatusBars`                                                   |
+| Assistant     | `AssistantProvider`, `AssistantDock`, `AskBox`, `DictationButton`, `ActionReceipt`, `toastUndo`                                               |
+| AI and chat   | `ChatShell`, `ChatPanel`, `ChatMessage`, `PromptInput`, `ModelPicker`, `ToolGroup`, `ApprovalCard`, `CodeSnippet`, `Prose`                    |
+| Auth          | `AuthLayout`, `LoginForm`, `SignupForm`                                                                                                       |
+| Primitives    | The full shadcn/ui registry: `Button`, `Dialog`, `Select`, `Sidebar`, `Tabs`, `Command`, `Chart`, and the rest                                |
+
+The full list with props: [docs/COMPONENTS.md](docs/COMPONENTS.md).
 
 ## Develop
 
@@ -86,8 +156,11 @@ Working on this repo with an agent: see [AGENTS.md](AGENTS.md).
 pnpm install
 pnpm dev     # playground on :5199
 pnpm check   # lint, typecheck, test, build, package lint
+pnpm shots   # regenerate the README images (needs pnpm dev running, Chrome and cwebp)
 ```
 
+Working on this repo with an agent: see [AGENTS.md](AGENTS.md).
+
 ## License
 
 MIT

package/bin/harebear-ui.mjs

@@ -24,6 +24,7 @@ const AGENT_BLOCK = `${START}
 All UI in this project uses the \`harebear-ui\` component library (pre-themed shadcn/ui on Tailwind v4, plus admin, data table, chart, and AI chat components).
 
 - Read \`node_modules/harebear-ui/docs/COMPONENTS.md\` before building UI. It lists every component with props and examples.
+- Look up single entries with \`npx harebear-ui docs DataTable PromptInput\` (export names, a prefix, or a section such as \`Tokens\`).
 - Import from the package root: \`import { Button, Card, DataTable } from "harebear-ui"\`.
 - Style only with theme tokens (\`bg-card\`, \`bg-muted\`, \`text-muted-foreground\`, \`bg-primary-soft\`, \`text-success\`, \`shadow-card\`, \`rounded-xl\`). No hex or Tailwind palette colors.
 - Check new screens in light and dark mode and at phone width.
@@ -86,6 +87,50 @@ function installSkill() {
   console.log(`✓ Installed Claude Code skill to ${relative(cwd, destDir)}/SKILL.md`)
 }
 
+// Backticked identifiers in a heading or table cell: "`ChatMessage`" -> "chatmessage".
+const namesIn = (text) => [...text.matchAll(/`([A-Za-z]\w*)/g)].map((m) => m[1].toLowerCase())
+
+// The parts of the catalog about one export or section: "### `Name`" sections, primitive table rows
+// (with their table header), or a whole "## Section" by title. Exact names first, then prefix matches.
+function lookup(catalog, query) {
+  const q = query.toLowerCase()
+  const blocks = catalog.split(/^(?=#{2,3} )/m)
+  const section = blocks.find((b) => b.startsWith("## ") && b.split("\n", 1)[0].slice(3).toLowerCase() === q)
+  if (section) {
+    // A "## Section" block stops at its first "###"; take the subsections that follow it too.
+    const start = blocks.indexOf(section)
+    const end = blocks.findIndex((b, i) => i > start && b.startsWith("## "))
+    return blocks
+      .slice(start, end < 0 ? undefined : end)
+      .join("")
+      .trimEnd()
+  }
+  for (const match of [(n) => n === q, (n) => n.startsWith(q)]) {
+    const out = blocks.filter((b) => b.startsWith("### ") && namesIn(b.split("\n", 1)[0]).some(match))
+    let header = []
+    let headerShown = null
+    const rows = []
+    for (const line of catalog.split("\n")) {
+      if (!line.startsWith("|")) {
+        header = []
+        continue
+      }
+      if (header.length < 2) {
+        header.push(line)
+        continue
+      }
+      const [, first = "", second = ""] = line.split("|")
+      if (!namesIn(first + second).some(match)) continue
+      if (headerShown !== header) rows.push(...header)
+      headerShown = header
+      rows.push(line)
+    }
+    if (rows.length) out.push(rows.join("\n"))
+    if (out.length) return out.map((b) => b.trimEnd()).join("\n\n")
+  }
+  return undefined
+}
+
 switch (cmd) {
   case "init": {
     if (!existsSync(join(cwd, "package.json"))) {
@@ -109,9 +154,25 @@ Next: wrap your app root.
 `)
     break
   }
-  case "docs":
-    process.stdout.write(readFileSync(join(pkgRoot, "docs/COMPONENTS.md"), "utf8"))
+  case "docs": {
+    const catalog = readFileSync(join(pkgRoot, "docs/COMPONENTS.md"), "utf8")
+    const queries = args.filter((a) => !a.startsWith("--"))
+    if (queries.length === 0) {
+      process.stdout.write(catalog)
+      break
+    }
+    let missed = false
+    for (const q of queries) {
+      const found = lookup(catalog, q)
+      if (found) process.stdout.write(`${found}\n\n`)
+      else {
+        missed = true
+        console.error(`! Nothing in the catalog for "${q}". Run \`npx harebear-ui docs\` for the full catalog.`)
+      }
+    }
+    if (missed) process.exitCode = 1
     break
+  }
   default:
     console.log(`harebear-ui
 
@@ -119,7 +180,9 @@ Next: wrap your app root.
       Add the stylesheet import after @import "tailwindcss", add a harebear-ui
       section to AGENTS.md (or CLAUDE.md), and install the Claude Code skill.
 
-  npx harebear-ui docs
+  npx harebear-ui docs [name...]
       Print the component catalog (props and examples for every export).
+      With names, print only those entries: an export (DataTable, Button),
+      a name prefix (Prompt), or a section title (Tokens, Auth).
 `)
 }

package/dist/components/admin/app-nav.d.ts

@@ -0,0 +1,57 @@
+import { AppNavItem } from "./app-shell.js";
+import { SidebarLayoutProps } from "./sidebar-layout.js";
+import * as React from "react";
+export interface AppNavPlace extends Omit<AppNavItem, "badge"> {
+  /** Count at the right in the sidebar and on the icon in the tab bar, e.g. open to-dos. Hidden when 0. */
+  count?: number;
+  /** Show in the phone tab bar. Default true; the first 5 that are not false are shown. */
+  tab?: boolean;
+}
+export interface AppNavGroup {
+  /** Group heading, e.g. "Lists". */
+  label: string;
+  items: AppNavPlace[];
+  /** Expanded at first. Default true. */
+  defaultOpen?: boolean;
+  /** Shows an add button next to the heading. */
+  onAdd?: () => void;
+  /** Accessible label of the add button, e.g. "New list". Default "Add". */
+  addLabel?: string;
+}
+export interface AppNavAction {
+  label: string;
+  icon: React.ReactNode;
+  onSelect: () => void;
+}
+export interface AppNavProps {
+  /** Product mark at the top of the sidebar, usually <AppBrand />. */
+  brand?: React.ReactNode;
+  /** Top-level places (Today, Calendar, Docs). Sidebar items on desktop, tabs on phones. */
+  places: AppNavPlace[];
+  /** One collapsible group under the places, e.g. Lists with an add button. Desktop sidebar only. */
+  group?: AppNavGroup;
+  /** Sidebar bottom, usually <UserMenu />. Desktop sidebar only. */
+  footer?: React.ReactNode;
+  /** Primary action: a button under the brand on desktop, a round floating button above the tab bar on phones. */
+  action?: AppNavAction;
+  /** Accessible name of the navigation. Default "Main". */
+  label?: string;
+  /** Component used for links. Default "a". Pass Next.js Link or React Router Link. */
+  linkComponent?: React.ElementType;
+  collapsible?: SidebarLayoutProps["collapsible"];
+  storageKey?: string;
+  defaultOpen?: boolean;
+  /** Sidebar width. Default "15.75rem". */
+  width?: string;
+  /** Classes for the main column. */
+  className?: string;
+  children?: React.ReactNode;
+}
+/**
+ * App navigation from one config. Desktop (768px and up): SidebarLayout with the brand, action, places, a
+ * collapsible group and the footer; the active place is a raised card. Phones: a bottom tab bar with up to 5 places
+ * and an optional round action button. The main column gets bottom padding and sets `--hb-bottom-inset` (and
+ * `--hb-fab-inset`) so an AssistantDock rendered inside sits above the tab bar and the action button.
+ */
+declare function AppNav({ brand, places, group, footer, action, label, linkComponent, collapsible, storageKey, defaultOpen, width, className, children }: AppNavProps): React.JSX.Element;
+export { AppNav };

package/dist/components/admin/app-nav.js

@@ -0,0 +1,172 @@
+"use client";
+import { SidebarLayout } from "./sidebar-layout.js";
+import { Badge } from "../ui/badge.js";
+import { Button } from "../ui/button.js";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/collapsible.js";
+import { SidebarMenu, SidebarMenuButton, SidebarMenuItem } from "../ui/sidebar.js";
+import { cn } from "../../lib/utils.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { ChevronDownIcon, PlusIcon } from "lucide-react";
+// src/components/admin/app-nav.tsx
+const TAB_LIMIT = 5;
+/**
+* App navigation from one config. Desktop (768px and up): SidebarLayout with the brand, action, places, a
+* collapsible group and the footer; the active place is a raised card. Phones: a bottom tab bar with up to 5 places
+* and an optional round action button. The main column gets bottom padding and sets `--hb-bottom-inset` (and
+* `--hb-fab-inset`) so an AssistantDock rendered inside sits above the tab bar and the action button.
+*/
+function AppNav({ brand, places, group, footer, action, label = "Main", linkComponent = "a", collapsible, storageKey, defaultOpen, width = "15.75rem", className, children }) {
+	const tabs = places.filter((p) => p.tab !== false).slice(0, TAB_LIMIT);
+	return /* @__PURE__ */ jsxs(SidebarLayout, {
+		brand,
+		collapsible,
+		storageKey,
+		defaultOpen,
+		width,
+		sidebarFooter: footer,
+		sidebarActions: action && /* @__PURE__ */ jsxs(Button, {
+			type: "button",
+			"aria-label": action.label,
+			onClick: action.onSelect,
+			className: "w-full justify-start group-data-[collapsible=icon]:size-10 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0",
+			children: [action.icon, /* @__PURE__ */ jsx("span", {
+				className: "group-data-[collapsible=icon]:hidden",
+				children: action.label
+			})]
+		}),
+		sidebar: /* @__PURE__ */ jsxs("nav", {
+			"aria-label": label,
+			"data-slot": "app-nav",
+			className: "flex flex-col gap-5",
+			children: [/* @__PURE__ */ jsx(SidebarMenu, {
+				className: "gap-1 group-data-[collapsible=icon]:items-center",
+				children: places.map((place) => /* @__PURE__ */ jsx(PlaceItem, {
+					place,
+					Link: linkComponent
+				}, place.label))
+			}), group && /* @__PURE__ */ jsx(NavGroup, {
+				group,
+				Link: linkComponent
+			})]
+		}),
+		className: cn("max-md:pb-[calc(4.5rem+env(safe-area-inset-bottom))] max-md:[--hb-bottom-inset:calc(4.5rem+env(safe-area-inset-bottom))]", action && "max-md:[--hb-fab-inset:4.5rem]", className),
+		children: [
+			children,
+			tabs.length > 0 && /* @__PURE__ */ jsx(TabBar, {
+				tabs,
+				label,
+				Link: linkComponent
+			}),
+			action && /* @__PURE__ */ jsx(Button, {
+				type: "button",
+				"data-slot": "app-nav-fab",
+				size: "icon-lg",
+				shape: "pill",
+				"aria-label": action.label,
+				onClick: action.onSelect,
+				className: "fixed right-4 bottom-[calc(4.5rem+env(safe-area-inset-bottom)+1rem)] z-30 size-14 shadow-card md:hidden [&_svg:not([class*='size-'])]:size-6",
+				children: action.icon
+			})
+		]
+	});
+}
+function PlaceItem({ place, Link }) {
+	const content = /* @__PURE__ */ jsxs(Fragment, { children: [
+		place.icon,
+		/* @__PURE__ */ jsx("span", {
+			className: "flex-1",
+			children: place.label
+		}),
+		!!place.count && /* @__PURE__ */ jsx(Badge, {
+			variant: "soft",
+			className: "h-5 px-2 group-data-[collapsible=icon]:hidden",
+			children: place.count
+		})
+	] });
+	return /* @__PURE__ */ jsx(SidebarMenuItem, { children: /* @__PURE__ */ jsx(SidebarMenuButton, {
+		asChild: !!place.href,
+		isActive: place.active,
+		"aria-current": place.active ? "page" : void 0,
+		onClick: place.onSelect,
+		tooltip: place.label,
+		children: place.href ? /* @__PURE__ */ jsx(Link, {
+			href: place.href,
+			children: content
+		}) : content
+	}) });
+}
+function NavGroup({ group, Link }) {
+	const [open, setOpen] = React.useState(group.defaultOpen ?? true);
+	return /* @__PURE__ */ jsxs(Collapsible, {
+		open,
+		onOpenChange: setOpen,
+		"data-slot": "app-nav-group",
+		className: "flex flex-col gap-1 group-data-[collapsible=icon]:hidden",
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex items-center gap-1 pr-1",
+			children: [/* @__PURE__ */ jsxs(CollapsibleTrigger, {
+				className: "flex h-8 min-w-0 flex-1 items-center gap-1.5 rounded-md px-3 text-xs font-medium text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/40",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "truncate",
+					children: group.label
+				}), /* @__PURE__ */ jsx(ChevronDownIcon, {
+					"aria-hidden": "true",
+					className: cn("size-3.5 transition-transform motion-reduce:transition-none", !open && "-rotate-90")
+				})]
+			}), group.onAdd && /* @__PURE__ */ jsx(Button, {
+				type: "button",
+				variant: "ghost",
+				size: "icon-sm",
+				"aria-label": group.addLabel ?? "Add",
+				onClick: group.onAdd,
+				children: /* @__PURE__ */ jsx(PlusIcon, {})
+			})]
+		}), /* @__PURE__ */ jsx(CollapsibleContent, { children: /* @__PURE__ */ jsx(SidebarMenu, {
+			className: "gap-1",
+			children: group.items.map((place) => /* @__PURE__ */ jsx(PlaceItem, {
+				place,
+				Link
+			}, place.label))
+		}) })]
+	});
+}
+function TabBar({ tabs, label, Link }) {
+	return /* @__PURE__ */ jsx("nav", {
+		"aria-label": label,
+		"data-slot": "app-nav-tabs",
+		className: "fixed inset-x-0 bottom-0 z-30 border-t border-border bg-background/95 px-2 pt-1.5 pb-[max(0.375rem,env(safe-area-inset-bottom))] backdrop-blur md:hidden",
+		children: /* @__PURE__ */ jsx("ul", {
+			className: "mx-auto flex max-w-lg",
+			children: tabs.map((tab) => {
+				const Comp = tab.href ? Link : "button";
+				return /* @__PURE__ */ jsx("li", {
+					className: "flex min-w-0 flex-1",
+					children: /* @__PURE__ */ jsxs(Comp, {
+						...tab.href ? { href: tab.href } : {
+							type: "button",
+							onClick: tab.onSelect
+						},
+						"aria-current": tab.active ? "page" : void 0,
+						className: "flex min-h-14 min-w-0 flex-1 flex-col items-center justify-center gap-1 rounded-xl px-1 text-xs font-medium text-muted-foreground outline-none hover:text-foreground focus-visible:ring-4 focus-visible:ring-ring/20 aria-[current=page]:text-primary",
+						children: [/* @__PURE__ */ jsxs("span", {
+							className: "relative [&_svg]:size-6",
+							children: [tab.icon, !!tab.count && /* @__PURE__ */ jsx("span", {
+								"aria-hidden": "true",
+								className: "absolute -top-1.5 left-[calc(100%-0.5rem)] grid h-4.5 min-w-4.5 place-items-center rounded-full bg-primary px-1 text-xs leading-none font-semibold text-primary-foreground",
+								children: tab.count > 99 ? "99+" : tab.count
+							})]
+						}), /* @__PURE__ */ jsxs("span", {
+							className: "max-w-full truncate",
+							children: [tab.label, !!tab.count && /* @__PURE__ */ jsxs("span", {
+								className: "sr-only",
+								children: [", ", tab.count]
+							})]
+						})]
+					})
+				}, tab.label);
+			})
+		})
+	});
+}
+export { AppNav };

package/dist/components/admin/focus-layout.d.ts

@@ -0,0 +1,14 @@
+import * as React from "react";
+export interface FocusLayoutProps extends Omit<React.ComponentProps<"div">, "title"> {
+  /** Page title in the top bar. */
+  title?: React.ReactNode;
+  /** Leading control, usually a close or back link: <Button asChild variant="ghost" size="icon"><a aria-label="Close">…</a></Button>. */
+  back?: React.ReactNode;
+  /** Trailing top bar controls, e.g. a Save button. */
+  actions?: React.ReactNode;
+  /** Column width. Default "md" (42rem). */
+  width?: "sm" | "md" | "lg";
+}
+/** A page outside the app frame (settings, onboarding, setup): slim top bar with back link and title, one centred column. */
+declare function FocusLayout({ title, back, actions, width, className, children, ...props }: FocusLayoutProps): React.JSX.Element;
+export { FocusLayout };

package/dist/components/admin/focus-layout.js

@@ -0,0 +1,36 @@
+"use client";
+import { cn } from "../../lib/utils.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+// src/components/admin/focus-layout.tsx
+const widthClass = {
+	sm: "max-w-xl",
+	md: "max-w-2xl",
+	lg: "max-w-4xl"
+};
+/** A page outside the app frame (settings, onboarding, setup): slim top bar with back link and title, one centred column. */
+function FocusLayout({ title, back, actions, width = "md", className, children, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "focus-layout",
+		className: cn("flex min-h-dvh flex-col bg-background", className),
+		...props,
+		children: [/* @__PURE__ */ jsxs("header", {
+			className: "sticky top-0 z-20 flex min-h-14 items-center gap-2 bg-background/90 px-3 pt-[env(safe-area-inset-top)] backdrop-blur sm:px-4",
+			children: [
+				back,
+				title && /* @__PURE__ */ jsx("h1", {
+					className: "min-w-0 flex-1 truncate text-[15px] font-semibold",
+					children: title
+				}),
+				!title && /* @__PURE__ */ jsx("div", { className: "flex-1" }),
+				actions && /* @__PURE__ */ jsx("div", {
+					className: "flex items-center gap-2",
+					children: actions
+				})
+			]
+		}), /* @__PURE__ */ jsx("main", {
+			className: cn("mx-auto flex w-full flex-col gap-6 px-4 pt-4 pb-[max(3rem,env(safe-area-inset-bottom))]", widthClass[width]),
+			children
+		})]
+	});
+}
+export { FocusLayout };