@kerfjs/ui 4.4.1 → 5.0.0-beta.10

package/ux-demo/recipes/compact-toolbar.tsx

@@ -0,0 +1,43 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/select/register';
+import './recipes.css';
+
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { SegmentedControl } from '@kerfjs/ui/segmented-control';
+import { Select } from '@kerfjs/ui/select';
+import { Toolbar } from '@kerfjs/ui/toolbar';
+import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
+import { ToolbarText } from '@kerfjs/ui/toolbar-text';
+import { signal } from 'kerfjs';
+import { Filter, MoreHorizontal, RefreshCw } from 'lucide';
+
+import type { RecipeFactory } from './types.js';
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const view = signal('list');
+  const sort = signal('updated');
+  const filtered = signal(false);
+  const render = () => <section class="kui-recipe recipe-compact-toolbar kui-recipe__surface kui-layout" data-recipe="recipe-compact-toolbar">
+    <Toolbar
+      label="Task workspace controls"
+      leading={<ToolbarControlGroup appearance="borderless" single><ToolbarText text="Tasks" size="small" /></ToolbarControlGroup>}
+      center={<ToolbarControlGroup><SegmentedControl id="recipe-view" label="View" value={view.value} action="recipe-action" appearance="toolbar" shape="pill" size="small" choices={[{ value: 'list', label: 'List' }, { value: 'board', label: 'Board' }, { value: 'timeline', label: 'Timeline' }]} /></ToolbarControlGroup>}
+      trailing={<div class="kui-control-cluster"><Select name="recipe-sort" value={sort.value} ariaLabel="Sort tasks" fitMenu choices={[{ value: 'updated', label: 'Recently updated' }, { value: 'priority', label: 'Priority' }, { value: 'owner', label: 'Owner' }, { value: 'created', label: 'Created date' }]} /><ToolbarControlGroup label="Task actions" buttonAppearance="push"><button type="button" aria-label="Toggle filters" aria-pressed={String(filtered.value)} data-action="recipe-action" data-recipe-command="filter"><LucideIcon icon={Filter} name="filter" /></button><button type="button" aria-label="Refresh tasks" data-action="recipe-action" data-recipe-command="refresh"><LucideIcon icon={RefreshCw} name="refresh-cw" /></button></ToolbarControlGroup><button class="kui-recipe__button" type="button" aria-label="More task actions" data-action="recipe-action" data-recipe-command="more"><LucideIcon icon={MoreHorizontal} name="more-horizontal" /></button></div>}
+    />
+    <div class="recipe-compact-toolbar__guide kui-content-item"><div><strong>ToolbarControlGroup</strong><span class="kui-recipe__muted">Related commands or pressed tools.</span></div><div><strong>SegmentedControl</strong><span class="kui-recipe__muted">A few visible exclusive choices.</span></div><div><strong>Select</strong><span class="kui-recipe__muted">A longer controlled value list.</span></div><div><strong>Ordinary button</strong><span class="kui-recipe__muted">One independent command.</span></div></div>
+    <p class="kui-recipe__ownership kui-content-item">The recipe owns control semantics and wrapping. The app owns values, actions, persistence, and responsive priority.</p>
+  </section>;
+  return {
+    render,
+    action(command, element) {
+      const value = element.dataset.segmentValue;
+      if (value) view.value = value;
+      if (command === 'filter') filtered.value = !filtered.value;
+      announce(value ? `View: ${value}` : command === 'filter' ? `Filters ${filtered.value ? 'on' : 'off'}` : `${command} requested`);
+    },
+    change(element) {
+      const value = (element as HTMLElement & { value?: string }).value;
+      if (element.getAttribute('name') === 'recipe-sort' && value) { sort.value = value; announce(`Sort: ${value}`); }
+    },
+  };
+};

package/ux-demo/recipes/composer-form.tsx

@@ -0,0 +1,63 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/select/register';
+import '@kerfjs/ui/webawesome.css';
+import '@awesome.me/webawesome/dist/components/button/button.js';
+import '@awesome.me/webawesome/dist/components/input/input.js';
+import '@awesome.me/webawesome/dist/components/textarea/textarea.js';
+import './recipes.css';
+
+import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { Select } from '@kerfjs/ui/select';
+import { StateBanner } from '@kerfjs/ui/state-banner';
+import { signal } from 'kerfjs';
+
+import type { RecipeFactory } from './types.js';
+
+type ValueField = HTMLElement & { value: string };
+
+const syncControlledFieldValues = (action: HTMLElement, values: Record<string, string>) => {
+  const form = action.closest<HTMLElement>('[data-recipe="recipe-composer-form"]');
+  if (!form) return;
+  for (const [name, value] of Object.entries(values)) {
+    const field = form.querySelector<ValueField>(`[name="${name}"]`);
+    if (field && field.value !== value) field.value = value;
+  }
+};
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const title = signal('');
+  const body = signal('The tablet layout now keeps navigation, content, and inspector focus order aligned.');
+  const audience = signal('team');
+  const status = signal<'idle' | 'error' | 'saved'>('idle');
+  const render = () => <form class="kui-recipe recipe-form kui-recipe__surface kui-content" data-recipe="recipe-composer-form" aria-labelledby="recipe-composer-title" aria-describedby="recipe-composer-summary" noValidate>
+    <PanelHeader title="Publish workspace update" titleId="recipe-composer-title" summary="Share a concise, actionable update with collaborators." summaryId="recipe-composer-summary" />
+    {status.value === 'error' && <StateBanner title="Add a title before publishing" detail="The update body and audience are preserved." tone="danger" urgency="alert" />}
+    {status.value === 'saved' && <StateBanner title="Update published" detail="The team audience can now read it." tone="success" />}
+    <div class="recipe-form__section recipe-form__fields">
+      <wa-input name="recipe-title" label="Update title" hint="Summarize the outcome in one line." required value={title.value}></wa-input>
+      <wa-textarea name="recipe-body" label="Details" hint="Include decisions, owners, and the next checkpoint." rows="5" maxlength="400" with-count value={body.value}></wa-textarea>
+      <Select name="recipe-audience" value={audience.value} label="Audience" choices={[{ value: 'team', label: 'Workspace team' }, { value: 'reviewers', label: 'Reviewers' }, { value: 'organization', label: 'Entire organization' }]} />
+    </div>
+    <footer class="recipe-form__section recipe-form__footer"><div class="recipe-form__actions kui-control-cluster"><wa-button appearance="outlined" data-action="recipe-action" data-recipe-command="reset">Reset</wa-button><wa-button variant="brand" appearance="accent" data-action="recipe-action" data-recipe-command="submit">Publish update</wa-button></div><p class="kui-recipe__ownership">The recipe owns field, message, and action rhythm. The app owns validation rules, draft persistence, permissions, and transport.</p></footer>
+  </form>;
+  return {
+    render,
+    action(command, element) {
+      if (command === 'reset') {
+        title.value = '';
+        body.value = '';
+        status.value = 'idle';
+        syncControlledFieldValues(element, { 'recipe-title': title.value, 'recipe-body': body.value });
+        announce('Draft reset');
+        return;
+      }
+      if (command === 'submit') { status.value = title.value.trim() ? 'saved' : 'error'; announce(status.value === 'saved' ? 'Update published' : 'Title required'); }
+    },
+    change(element) {
+      const value = (element as HTMLElement & { value?: string | null }).value ?? '';
+      if (element.getAttribute('name') === 'recipe-title') title.value = value;
+      if (element.getAttribute('name') === 'recipe-body') body.value = value;
+      if (element.getAttribute('name') === 'recipe-audience') audience.value = value;
+    },
+  };
+};

package/ux-demo/recipes/list-detail-dialog.tsx

@@ -0,0 +1,45 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/webawesome.css';
+import '@awesome.me/webawesome/dist/components/button/button.js';
+import '@awesome.me/webawesome/dist/components/dialog/dialog.js';
+import './recipes.css';
+
+import { ListHeader } from '@kerfjs/ui/list-header';
+import { ListItem } from '@kerfjs/ui/list-item';
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { ValueTable, ValueTableRow } from '@kerfjs/ui/value-table';
+import { signal } from 'kerfjs';
+import { FileText } from 'lucide';
+
+import type { RecipeFactory } from './types.js';
+
+const records = {
+  alpha: { name: 'Northstar migration', owner: 'Mara Chen', state: 'In review', updated: 'Today, 09:42' },
+  beta: { name: 'Tablet navigation', owner: 'Sam Rivera', state: 'Ready', updated: 'Yesterday, 16:20' },
+  gamma: { name: 'Contrast audit', owner: 'Inez Okafor', state: 'Blocked', updated: 'Monday, 11:05' },
+} as const;
+
+interface RecipeDialogElement extends HTMLElement {
+  open: boolean;
+}
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const selected = signal<keyof typeof records>('alpha');
+  const open = { value: false };
+  const render = () => <section class="kui-recipe kui-content" data-recipe="recipe-list-detail-dialog"><button class="kui-recipe__button kui-content-item" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="open">Open project details</button><p class="kui-recipe__ownership kui-content-item">Web Awesome owns modal focus and dismissal. The recipe owns header/body/list-detail anatomy; the app owns open state, selection, and policy.</p><wa-dialog class="recipe-dialog" label="Project details" without-header open={open.value}><div class="recipe-dialog__pane kui-pane"><div class="recipe-list-detail kui-pane__content"><nav class="recipe-list-detail__list kui-pane" aria-label="Projects"><ListHeader label="Recent projects" /><div class="kui-pane__content kui-content"><section>{Object.entries(records).map(([id, record]) => <ListItem action="recipe-action" itemId={id} label={record.name} selected={selected.value === id} multiline />)}</section></div></nav><section class="recipe-list-detail__detail kui-pane"><PanelHeader title="Project details" titleId="recipe-dialog-title" summary="Compare delivery state without leaving the workspace." summaryId="recipe-dialog-summary" icon={<LucideIcon icon={FileText} name="file-text" />} actions={<wa-button appearance="plain" data-action="recipe-action" data-recipe-command="close">Close</wa-button>} /><div class="recipe-list-detail__body kui-pane__content kui-content" aria-live="polite"><h3 class="recipe-list-detail__title kui-recipe__pane-title kui-content-item">{records[selected.value].name}</h3><ValueTable label="Project details"><ValueTableRow label="Owner" value={records[selected.value].owner} /><ValueTableRow label="Status" value={records[selected.value].state} /><ValueTableRow label="Updated" value={records[selected.value].updated} /></ValueTable><div class="recipe-list-detail__actions kui-control-cluster"><wa-button appearance="outlined" data-action="recipe-action" data-recipe-command="archive">Archive</wa-button><wa-button variant="brand" appearance="accent" data-action="recipe-action" data-recipe-command="open-record">Open project</wa-button></div></div></section></div></div></wa-dialog></section>;
+  return {
+    render,
+    action(command, element) {
+      const id = element.dataset.itemId;
+      if (id && id in records) { selected.value = id as keyof typeof records; announce(`Selected ${records[selected.value].name}`); return; }
+      const dialog = element.closest('[data-recipe]')?.querySelector<RecipeDialogElement>('wa-dialog');
+      if (command === 'open' && dialog) { element.focus(); open.value = true; dialog.open = true; return; }
+      if (command === 'close' && dialog) { dialog.open = false; return; }
+      announce(`${command} requested`);
+    },
+    afterHide() {
+      open.value = false;
+    },
+  };
+};

package/ux-demo/recipes/list-workspace-states.tsx

@@ -0,0 +1,26 @@
+import '@kerfjs/ui/layout.css';
+import './recipes.css';
+
+import { EmptyState } from '@kerfjs/ui/empty-state';
+import { LoadingSpinner } from '@kerfjs/ui/loading-spinner';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { StateBanner } from '@kerfjs/ui/state-banner';
+import { signal } from 'kerfjs';
+
+import type { RecipeFactory } from './types.js';
+
+type ListState = 'loading' | 'empty' | 'populated' | 'stale' | 'error';
+const items = ['Audit keyboard focus order', 'Verify 200% zoom layout', 'Publish package migration notes'];
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const state = signal<ListState>('loading');
+  const populated = () => <ul class="recipe-list__items" aria-label="Release tasks">{items.map((item, index) => <li><strong>{item}</strong><span class="kui-recipe__muted">{index === 0 ? 'In review · Mara' : index === 1 ? 'Ready · Sam' : 'Draft · Inez'}</span></li>)}</ul>;
+  const renderBody = () => {
+    if (state.value === 'loading') return <EmptyState title="Loading release tasks" detail="The current workspace will appear when data is ready." busy action={<button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="load">Complete load</button>} />;
+    if (state.value === 'empty') return <EmptyState title="No release tasks" detail="Create the first task for this milestone." action={<button class="kui-recipe__button" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="create">Create task</button>} />;
+    if (state.value === 'error') return <StateBanner title="Release tasks could not be refreshed" detail="Existing filters are preserved. Try again when the connection recovers." tone="danger" urgency="alert" action={<button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="retry">Retry</button>} />;
+    return <>{state.value === 'stale' && <StateBanner title="Showing saved results" detail="Refreshing in the background." tone="warning" action={<span class="kui-inline-metadata"><LoadingSpinner label="Refreshing release tasks" /><button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="finish">Finish refresh</button></span>} />}{populated()}</>;
+  };
+  const render = () => <section class="kui-recipe recipe-list kui-recipe__surface kui-pane" data-recipe="recipe-list-workspace-states" data-list-state={state.value}><PanelHeader title="Release tasks" titleId="recipe-list-title" actions={<div class="kui-control-cluster"><button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="empty">Clear</button><button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="fail">Simulate failure</button><button class="kui-recipe__button" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="refresh">Refresh</button></div>} /><div class="recipe-list__body kui-pane__content kui-content">{renderBody()}<p class="kui-recipe__ownership kui-content-item">The recipe owns feedback placement and stable content. The app owns fetching, cache age, retry policy, and domain rows.</p></div></section>;
+  return { render, action(command) { const next: Record<string, ListState> = { load: 'populated', empty: 'empty', create: 'populated', fail: 'error', retry: 'populated', refresh: 'stale', finish: 'populated' }; if (command in next) state.value = next[command]!; announce(`List state: ${state.value}`); } };
+};

package/ux-demo/recipes/loaders.ts

@@ -0,0 +1,33 @@
+import type { RecipeFactory } from './types.js';
+
+export const recipeIds = [
+  'recipe-app-shell',
+  'recipe-navigation-sidebar',
+  'recipe-workspace-header',
+  'recipe-list-detail-dialog',
+  'recipe-composer-form',
+  'recipe-list-workspace-states',
+  'recipe-compact-toolbar',
+  'recipe-navigation-stack',
+  'recipe-loading-inspector',
+  'recipe-collapsible-sidebar',
+] as const;
+
+export type RecipeId = typeof recipeIds[number];
+
+export const recipeLoaders: Record<RecipeId, () => Promise<{ createRecipe: RecipeFactory }>> = {
+  'recipe-app-shell': () => import('./app-shell.js'),
+  'recipe-navigation-sidebar': () => import('./navigation-sidebar.js'),
+  'recipe-workspace-header': () => import('./workspace-header.js'),
+  'recipe-list-detail-dialog': () => import('./list-detail-dialog.js'),
+  'recipe-composer-form': () => import('./composer-form.js'),
+  'recipe-list-workspace-states': () => import('./list-workspace-states.js'),
+  'recipe-compact-toolbar': () => import('./compact-toolbar.js'),
+  'recipe-navigation-stack': () => import('./navigation-stack.js'),
+  'recipe-loading-inspector': () => import('./loading-inspector.js'),
+  'recipe-collapsible-sidebar': () => import('./collapsible-sidebar.js'),
+};
+
+export function isRecipeId(value: string): value is RecipeId {
+  return (recipeIds as readonly string[]).includes(value);
+}

package/ux-demo/recipes/loading-inspector.tsx

@@ -0,0 +1,81 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/select/register';
+import './recipes.css';
+
+import { ListItem } from '@kerfjs/ui/list-item';
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { SegmentedControl } from '@kerfjs/ui/segmented-control';
+import { Select } from '@kerfjs/ui/select';
+import { StateBanner } from '@kerfjs/ui/state-banner';
+import { ValueTable, ValueTableRow } from '@kerfjs/ui/value-table';
+import { signal } from 'kerfjs';
+import { Columns3, FileText, Inbox, List } from 'lucide';
+
+import type { RecipeFactory } from './types.js';
+
+const icon = (node: Parameters<typeof LucideIcon>[0]['icon'], name: string) => <LucideIcon icon={node} name={name} />;
+
+/**
+ * A record inspector whose per-record values load asynchronously. Every
+ * value-bearing component takes `placeholder` from one loading flag, so the same
+ * chrome renders a faithful loading state and then the populated record — no
+ * separate skeleton markup. The composition is the point; `Skeleton` is the
+ * primitive it is built on (see the Skeleton component demo).
+ */
+export const createRecipe: RecipeFactory = (announce) => {
+  const loading = signal(true);
+  const render = () => {
+    const p = loading.value;
+    return <section class="kui-recipe recipe-inspector kui-recipe__surface kui-pane" data-recipe="recipe-loading-inspector" data-inspector-loading={String(p)}>
+      <PanelHeader
+        title="Ticket · KF-2048"
+        titleId="recipe-inspector-title"
+        summary="Restore keyboard focus after a dialog closes"
+        summaryId="recipe-inspector-summary"
+        icon={icon(FileText, 'file-text')}
+        placeholder={p}
+        actions={<button class="kui-recipe__button" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="toggle">{p ? 'Show loaded' : 'Show loading'}</button>}
+      />
+      <div class="recipe-inspector__body kui-pane__content kui-content">
+        <section>
+          <ValueTable label="Ticket details">
+            <ValueTableRow label="Status" value="In review" icon={icon(Inbox, 'inbox')} placeholder={p} />
+            <ValueTableRow label="Owner" value="Mara Lopez" placeholder={p} />
+            <ValueTableRow label="Priority" value="High" placeholder={p} />
+            <ValueTableRow label="Updated" value="2 hours ago" placeholder={p} />
+          </ValueTable>
+        </section>
+        <div class="recipe-inspector__controls">
+          <Select name="recipe-inspector-status" value="review" label="Status" placeholder={p} choices={[
+            { value: 'review', label: 'In review' },
+            { value: 'ready', label: 'Ready' },
+            { value: 'done', label: 'Done' },
+          ]} />
+          <SegmentedControl id="recipe-inspector-view" label="Inspector view" value="details" appearance="toolbar" shape="pill" size="small" placeholder={p} choices={[
+            { value: 'details', label: 'Details', content: icon(List, 'list') },
+            { value: 'activity', label: 'Activity', content: icon(Columns3, 'columns-3') },
+            { value: 'files', label: 'Files', content: icon(FileText, 'file-text') },
+          ]} />
+        </div>
+        <section>
+          <ListItem action="recipe-action" itemId="reassign" label="Reassign ticket" icon={icon(Inbox, 'inbox')} placeholder={p} />
+          <ListItem action="recipe-action" itemId="watch" label="Watch for changes" placeholder={p} />
+        </section>
+        {p
+          ? <StateBanner tone="info" title="" detail="" icon={icon(FileText, 'file-text')} placeholder />
+          : <StateBanner tone="success" title="Up to date" detail="All checks passed on the latest revision." icon={icon(FileText, 'file-text')} />}
+        <p class="kui-recipe__ownership kui-content-item">Each value-bearing component's <code>placeholder</code> prop renders skeletons in its value slots while loading, so the recipe composes a faithful loading inspector from real chrome. The app owns the loading lifecycle and which values are still unknown.</p>
+      </div>
+    </section>;
+  };
+  return {
+    render,
+    action(command) {
+      if (command === 'toggle') {
+        loading.value = !loading.value;
+        announce(loading.value ? 'Inspector is loading' : 'Inspector loaded');
+      }
+    },
+  };
+};

package/ux-demo/recipes/mount-recipe.ts

@@ -0,0 +1,43 @@
+import { wireNavStack } from '@kerfjs/ui/wire-nav-stack';
+import { wireResizableRegions } from '@kerfjs/ui/wire-resizable-regions';
+import { delegate, mount } from 'kerfjs';
+import { delegateActions } from 'kerfjs/actions';
+
+import type { RecipeController } from './types.js';
+
+/**
+ * Copyable application boundary for a recipe. The caller owns one stable root
+ * and retains the returned disposer for that root's lifetime.
+ */
+export function mountRecipe(root: HTMLElement, controller: RecipeController): () => void {
+  const stopMount = mount(root, controller.render);
+  const stopActions = delegateActions(root, 'click', {
+    'recipe-action': (_event, element) => {
+      const target = element as HTMLElement;
+      controller.action(target.dataset.recipeCommand ?? '', target);
+    },
+  });
+  const dispatchChange = (_event: Event, element: Element) => controller.change?.(element as HTMLElement);
+  const stopChanges = delegate(root, 'change', 'wa-select, wa-input, wa-textarea', dispatchChange);
+  const stopInputs = delegate(root, 'input', 'wa-input, wa-textarea', dispatchChange);
+  const stopDialogs = delegate(root, 'wa-after-hide', 'wa-dialog', (_event, element) => controller.afterHide?.(element as HTMLElement));
+  const stopResize = wireResizableRegions(root, {
+    onCommit: ({ id, size }) => controller.resize?.(id, size),
+  });
+  const stopNav = wireNavStack(root, { onBack: () => controller.action('nav-back', root) });
+  const stopWire = controller.wire?.(root);
+
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    stopWire?.();
+    stopNav();
+    stopResize();
+    stopDialogs();
+    stopInputs();
+    stopChanges();
+    stopActions();
+    stopMount();
+  };
+}

package/ux-demo/recipes/navigation-sidebar.tsx

@@ -0,0 +1,26 @@
+import '@kerfjs/ui/layout.css';
+import './recipes.css';
+
+import { ListHeader } from '@kerfjs/ui/list-header';
+import { ListItem } from '@kerfjs/ui/list-item';
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { Toolbar } from '@kerfjs/ui/toolbar';
+import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
+import { signal } from 'kerfjs';
+import { Folder, Inbox, Plus, Settings, Users } from 'lucide';
+
+import type { RecipeFactory } from './types.js';
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const selected = signal('inbox');
+  const expanded = signal(true);
+  const render = () => <aside class="kui-recipe recipe-sidebar kui-recipe__surface kui-pane" data-recipe="recipe-navigation-sidebar">
+    <div class="recipe-sidebar__body kui-pane__content kui-content">
+      <section><ListHeader label="Workspace" count={3} countLabel="3 workspaces" action="recipe-action" actionLabel="Add workspace item" actionIcon={<LucideIcon icon={Plus} name="plus" />} /><ListItem action="recipe-action" itemId="inbox" label="Inbox" icon={<LucideIcon icon={Inbox} name="inbox" />} trailing={<span>12</span>} selected={selected.value === 'inbox'} /><ListItem action="recipe-action" itemId="shared" label="Shared with me" icon={<LucideIcon icon={Users} name="users" />} selected={selected.value === 'shared'} /><ListItem action="recipe-action" itemId="drafts" label="Drafts without an icon" selected={selected.value === 'drafts'} /></section>
+      <section><ListHeader label="Projects" toggle action="recipe-action" expanded={expanded.value} />{expanded.value && <><ListItem action="recipe-action" itemId="design" label="Design system rollout across desktop and tablet" icon={<LucideIcon icon={Folder} name="folder" />} selected={selected.value === 'design'} multiline /><ListItem action="recipe-action" itemId="archive" label="Archived" disabled title="Available to administrators" /><div class="kui-content-item"><strong>Quarterly goal</strong><p class="kui-recipe__muted">Ship accessible navigation patterns to every workspace.</p></div></>}</section>
+      <p class="kui-recipe__ownership kui-content-item">The recipe owns pane, content-item, and toolbar geometry. The app owns routes, permissions, labels, and disclosure state.</p>
+    </div>
+    <footer class="recipe-sidebar__footer kui-pane__footer"><Toolbar label="Sidebar actions" divider={false} leading={<ToolbarControlGroup appearance="borderless" single><button type="button" aria-label="Add project" data-action="recipe-action" data-recipe-command="add"><LucideIcon icon={Plus} name="plus" /></button></ToolbarControlGroup>} trailing={<ToolbarControlGroup appearance="borderless" single><button type="button" aria-label="Workspace settings" data-action="recipe-action" data-recipe-command="settings"><LucideIcon icon={Settings} name="settings" /></button></ToolbarControlGroup>} /></footer>
+  </aside>;
+  return { render, action(command, element) { if (element.matches('.kui-list-header__toggle')) { expanded.value = !expanded.value; announce(expanded.value ? 'Projects expanded' : 'Projects collapsed'); return; } const id = element.dataset.itemId; if (id) selected.value = id; announce(id ? `Selected ${id}` : `${command} requested`); } };
+};

package/ux-demo/recipes/navigation-stack.tsx

@@ -0,0 +1,76 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/nav-stack.css';
+import '@kerfjs/ui/toolbar-text.css';
+import './recipes.css';
+
+import { ListHeader } from '@kerfjs/ui/list-header';
+import { ListItem } from '@kerfjs/ui/list-item';
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { NavStack, type NavStackView } from '@kerfjs/ui/nav-stack';
+import { signal } from 'kerfjs';
+import { ChevronRight, FileText, Folder } from 'lucide';
+
+import type { RecipeFactory } from './types.js';
+
+interface LibraryItem {
+  id: string;
+  label: string;
+  detail: string;
+}
+
+const ITEMS: LibraryItem[] = [
+  { id: 'tokens', label: 'Design tokens', detail: 'Semantic color, spacing, and radius scales shared across every surface.' },
+  { id: 'controls', label: 'Toolbar controls', detail: 'Control groups and segmented controls with their hover and pressed contracts.' },
+  { id: 'layouts', label: 'App layouts', detail: 'Navigation stacks, split views, workbench, and bottom-tab scaffolds.' },
+];
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const listView = (): NavStackView => ({
+    key: 'library',
+    title: 'Library',
+    content: <div class="recipe-navstack__view kui-pane__content kui-content">
+      <section>
+        <ListHeader label="Components" />
+        {ITEMS.map((item) => <ListItem action="recipe-action" itemId={item.id} label={item.label} icon={<LucideIcon icon={Folder} name="folder" />} trailing={<LucideIcon icon={ChevronRight} name="chevron-right" />} />)}
+      </section>
+      <p class="kui-recipe__ownership kui-content-item">The recipe owns the stack as a signal of views and pushes/pops it; `NavStack` renders the stack and `wireNavStack` slides the content and settles the chrome. The app owns selection, data, and routing.</p>
+    </div>,
+  });
+
+  const detailView = (item: LibraryItem): NavStackView => ({
+    key: item.id,
+    title: item.label,
+    content: <div class="recipe-navstack__view kui-pane__content kui-content">
+      <div class="kui-content-item">
+        <LucideIcon icon={FileText} name="file-text" />
+        <strong>{item.label}</strong>
+        <p class="kui-recipe__muted">{item.detail}</p>
+      </div>
+    </div>,
+  });
+
+  const views = signal<NavStackView[]>([listView()]);
+
+  const render = () => <section class="kui-recipe recipe-navstack kui-recipe__surface" data-recipe="recipe-navigation-stack">
+    <div class="recipe-navstack__stage"><NavStack id="recipe-nav" label="Component library" views={views.value} /></div>
+  </section>;
+
+  return {
+    render,
+    action(command, element) {
+      if (command === 'nav-back') {
+        if (views.value.length > 1) {
+          views.value = views.value.slice(0, -1);
+          announce('Navigated back');
+        }
+        return;
+      }
+      const id = element.dataset.itemId;
+      const item = ITEMS.find((candidate) => candidate.id === id);
+      if (item) {
+        views.value = [...views.value, detailView(item)];
+        announce(`Opened ${item.label}`);
+      }
+    },
+  };
+};