@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.111

package/ux-demo/recipes/media-detail.tsx

@@ -0,0 +1,272 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/nav-stack.css';
+import '@kerfjs/ui/pane.css';
+import '@kerfjs/ui/backdrop-image.css';
+import '@kerfjs/ui/toolbar.css';
+import '@kerfjs/ui/toolbar-text.css';
+import '@kerfjs/ui/toolbar-control-group.css';
+
+import { BackdropImage } from '@kerfjs/ui/backdrop-image';
+import { fillColor, uiColor } from '@kerfjs/ui/css-values';
+import { List } from '@kerfjs/ui/list';
+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 { Text } from '@kerfjs/ui/text';
+import { Toolbar } from '@kerfjs/ui/toolbar';
+import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
+import { ToolbarText } from '@kerfjs/ui/toolbar-text';
+import { wireScrollDividers } from '@kerfjs/ui/wire-scroll-dividers';
+import { signal } from 'kerfjs';
+import { ChevronRight, Disc3, Ellipsis, Play, Share, Shuffle } from 'lucide';
+
+import type { RecipeFactory, RecipePresentation } from './types.js';
+
+export const presentation: RecipePresentation = {
+  viewport: {
+    layout: 'grid',
+    width: 'compact',
+    height: 'tall',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: "An Apple-Music-style detail page composed only from components: a NavStack with clear chrome and the scroll-edge material, a scoped tint from the artwork's bottom color, an underChrome BackdropImage with parallax and progressive blur that fades into the tinted surface, and glass control groups. The app owns the artwork, its two colors (the tint and its scheme), the stack, playback, and data.",
+};
+
+interface Album {
+  id: string;
+  title: string;
+  artist: string;
+  /** The artwork's bottom color, which the app already knows. */
+  tint: string;
+  tracks: readonly (readonly [title: string, length: string])[];
+}
+
+const ALBUMS: readonly Album[] = [
+  {
+    id: 'night-harbor',
+    title: 'Night Harbor',
+    artist: 'The Lanterns',
+    tint: '#2a1a3d',
+    tracks: [
+      ['Low Tide', '3:42'],
+      ['Harbor Lights', '4:05'],
+      ['Northbound', '3:18'],
+      ['Glass Coast', '5:01'],
+      ['Undertow', '3:56'],
+      ['Night Ferry', '4:27'],
+      ['Salt Air', '2:59'],
+      ['Last Call', '4:12'],
+      ['Lantern', '3:33'],
+      ['Morning Swell', '4:48'],
+    ],
+  },
+];
+
+// Generated artwork, so the recipe needs no network or binary assets: a dusk
+// sky over three ridge lines whose depth makes the parallax legible.
+const ARTWORK = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1200" preserveAspectRatio="xMidYMid slice">
+<defs><linearGradient id="s" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#1b2a5c"/><stop offset=".5" stop-color="#c2577a"/><stop offset="1" stop-color="#f4b36b"/></linearGradient>
+<radialGradient id="g" cx=".5" cy=".5" r=".5"><stop offset="0" stop-color="#fff3c4"/><stop offset="1" stop-color="#fff3c4" stop-opacity="0"/></radialGradient></defs>
+<rect width="1600" height="1200" fill="url(#s)"/>
+<circle cx="1080" cy="560" r="240" fill="url(#g)"/><circle cx="1080" cy="560" r="96" fill="#ffe9b0"/>
+<path d="M0 680 L180 540 L330 640 L520 470 L700 620 L880 510 L1060 660 L1260 490 L1440 620 L1600 530 V1200 H0Z" fill="#7a3f6e"/>
+<path d="M0 820 L220 700 L400 790 L600 660 L820 810 L1000 720 L1200 830 L1400 720 L1600 810 V1200 H0Z" fill="#4b2a5a"/>
+<path d="M0 960 L260 850 L480 940 L720 840 L940 960 L1180 880 L1400 970 L1600 900 V1200 H0Z" fill="#2a1a3d"/>
+</svg>`;
+
+// A blob URL rather than a data URL: older kerf releases this package still
+// supports screen `data:image/svg+xml` out of every URL attribute; current kerf
+// allows it in `<img src>`. Created once and
+// reused, so re-renders do not leak blob URLs.
+let artworkUrl: string | undefined;
+const artwork = () =>
+  (artworkUrl ??= URL.createObjectURL(
+    new Blob([ARTWORK], { type: 'image/svg+xml' }),
+  ));
+
+const command = (name: string, label: string, icon: SafeIcon) => (
+  <button
+    type="button"
+    aria-label={label}
+    data-action="recipe-action"
+    data-recipe-command={name}
+  >
+    {icon}
+  </button>
+);
+
+type SafeIcon = ReturnType<typeof LucideIcon>;
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const libraryView = (): NavStackView => ({
+    key: 'library',
+    toolbar: { title: 'Library' },
+    content: (
+      <List>
+        <section>
+          <ListHeader label="Albums" />
+          {ALBUMS.map((album) => (
+            <ListItem
+              action="recipe-action"
+              itemId={album.id}
+              label={album.title}
+              description={album.artist}
+              icon={<LucideIcon icon={Disc3} name="disc-3" />}
+              trailing={<LucideIcon icon={ChevronRight} name="chevron-right" />}
+            />
+          ))}
+        </section>
+      </List>
+    ),
+  });
+
+  const albumView = (album: Album): NavStackView => ({
+    key: album.id,
+    toolbar: {
+      title: '',
+      trailing: (
+        <ToolbarControlGroup
+          label="Album Actions"
+          content="icon"
+          material="glass"
+        >
+          {command('share', 'Share', <LucideIcon icon={Share} name="share" />)}
+          {command(
+            'more',
+            'More',
+            <LucideIcon icon={Ellipsis} name="ellipsis" />,
+          )}
+        </ToolbarControlGroup>
+      ),
+    },
+    pane: { safeAreaEdges: [] },
+    content: (
+      <BackdropImage
+        src={artwork()}
+        alt={`${album.title} artwork: ridges at dusk under a low sun`}
+        position="bottom"
+        parallax="subtle"
+        blur={{ dim: 0.2 }}
+        fadeTo={uiColor('surface')}
+        underChrome
+        overlay={
+          <Toolbar
+            label={album.title}
+            leading={
+              <ToolbarText
+                text={album.title}
+                description={album.artist}
+                size="xlarge"
+                headingLevel={2}
+              />
+            }
+            trailing={
+              <ToolbarControlGroup
+                label="Playback"
+                content="mixed"
+                material="glass"
+              >
+                {command(
+                  'play',
+                  'Play',
+                  <>
+                    <LucideIcon icon={Play} name="play" />
+                    <span>Play</span>
+                  </>,
+                )}
+                {command(
+                  'shuffle',
+                  'Shuffle',
+                  <LucideIcon icon={Shuffle} name="shuffle" />,
+                )}
+              </ToolbarControlGroup>
+            }
+          />
+        }
+      >
+        <List>
+          <section>
+            <ListHeader
+              label="Songs"
+              count={album.tracks.length}
+              countLabel={`${String(album.tracks.length)} songs`}
+            />
+            {album.tracks.map(([title, length], index) => (
+              <ListItem
+                action="recipe-action"
+                itemId={`${album.id}-track-${String(index + 1)}`}
+                label={title}
+                trailing={
+                  <Text variant="span" tone="quiet">
+                    {length}
+                  </Text>
+                }
+              />
+            ))}
+          </section>
+        </List>
+      </BackdropImage>
+    ),
+  });
+
+  const views = signal<NavStackView[]>([libraryView(), albumView(ALBUMS[0]!)]);
+  const current = () =>
+    ALBUMS.find((album) => album.id === views.value.at(-1)?.key);
+
+  const render = () => {
+    const album = current();
+    return (
+      <section data-recipe="recipe-media-detail" aria-label="Music">
+        <NavStack
+          id="recipe-media"
+          label="Music"
+          views={views.value}
+          chromePresentation="clear"
+          scrollEdge="material"
+          tint={
+            album === undefined
+              ? undefined
+              : { color: fillColor(album.tint), scheme: 'dark' }
+          }
+        />
+      </section>
+    );
+  };
+
+  return {
+    render,
+    action(name, element) {
+      if (name === 'nav-back') {
+        if (views.value.length > 1) {
+          views.value = views.value.slice(0, -1);
+          announce('Navigated back');
+        }
+        return;
+      }
+      const album = ALBUMS.find(
+        (candidate) => candidate.id === element.dataset.itemId,
+      );
+      if (album) {
+        views.value = [...views.value, albumView(album)];
+        announce(`Opened ${album.title}`);
+        return;
+      }
+      if (element.dataset.itemId) {
+        announce(
+          `Playing ${element.querySelector('.kui-list-item__primary-label')?.textContent ?? 'song'}`,
+        );
+        return;
+      }
+      announce(`${name} requested`);
+    },
+    wire(root) {
+      // The clear chrome's scroll-edge material and the view Pane's chrome
+      // clearance follow the scroll state this reports.
+      return wireScrollDividers(root);
+    },
+  };
+};

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

@@ -1,6 +1,5 @@
 import { wireNavStack } from '@kerfjs/ui/wire-nav-stack';
-import { wireResizableRegions } from '@kerfjs/ui/wire-resizable-regions';
-import { delegate, mount } from 'kerfjs';
+import { delegate, delegateCapture, mount } from 'kerfjs';
 import { delegateActions } from 'kerfjs/actions';
 
 import type { RecipeController } from './types.js';
@@ -9,7 +8,10 @@ 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 {
+export function mountRecipe(
+  root: HTMLElement,
+  controller: RecipeController,
+): () => void {
   const stopMount = mount(root, controller.render);
   const stopActions = delegateActions(root, 'click', {
     'recipe-action': (_event, element) => {
@@ -17,14 +19,30 @@ export function mountRecipe(root: HTMLElement, controller: RecipeController): ()
       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 dispatchChange = (_event: Event, element: Element) =>
+    controller.change?.(element as HTMLElement);
+  const stopChanges = delegate(
+    root,
+    'change',
+    'kui-select, .kui-text-field__input',
+    dispatchChange,
+  );
+  const stopInputs = delegate(
+    root,
+    'input',
+    '.kui-text-field__input',
+    dispatchChange,
+  );
+  // A DialogSurface's native `close` does not bubble, so listen in capture.
+  const stopDialogs = delegateCapture(
+    root,
+    'close',
+    'dialog.kui-dialog-surface',
+    (_event, element) => controller.afterHide?.(element as HTMLElement),
+  );
+  const stopNav = wireNavStack(root, {
+    onBack: () => controller.action('nav-back', root),
   });
-  const stopNav = wireNavStack(root, { onBack: () => controller.action('nav-back', root) });
   const stopWire = controller.wire?.(root);
 
   let disposed = false;
@@ -33,7 +51,6 @@ export function mountRecipe(root: HTMLElement, controller: RecipeController): ()
     disposed = true;
     stopWire?.();
     stopNav();
-    stopResize();
     stopDialogs();
     stopInputs();
     stopChanges();

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

@@ -1,26 +1,152 @@
 import '@kerfjs/ui/layout.css';
-import './recipes.css';
 
+import { ContentItem } from '@kerfjs/ui/content-item';
+import { List } from '@kerfjs/ui/list';
 import { ListHeader } from '@kerfjs/ui/list-header';
 import { ListItem } from '@kerfjs/ui/list-item';
 import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { Pane } from '@kerfjs/ui/pane';
+import { Text } from '@kerfjs/ui/text';
 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';
+import type { RecipeFactory, RecipePresentation } from './types.js';
+
+export const presentation: RecipePresentation = {
+  viewport: {
+    layout: 'grid',
+    width: 'compact',
+    minHeight: 'medium',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: 'The recipe owns pane, content-item, and toolbar geometry. The app owns routes, permissions, labels, and disclosure state.',
+};
 
 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`); } };
+  const render = () => (
+    <Pane
+      element="aside"
+      label="Workspace Navigation"
+      rootAttributes={{ 'data-recipe': 'recipe-navigation-sidebar' }}
+      footer={
+        <Toolbar
+          label="Sidebar Actions"
+          dividerSides="t"
+          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>
+          }
+        />
+      }
+    >
+      <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"
+            />
+            <ContentItem>
+              <List gap="2xs">
+                <Text variant="span">
+                  <strong>Quarterly Goal</strong>
+                </Text>
+                <Text variant="span" tone="quiet" size="compact">
+                  Ship accessible navigation patterns to every workspace.
+                </Text>
+              </List>
+            </ContentItem>
+          </>
+        )}
+      </section>
+    </Pane>
+  );
+  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

@@ -1,16 +1,32 @@
 import '@kerfjs/ui/layout.css';
 import '@kerfjs/ui/nav-stack.css';
 import '@kerfjs/ui/toolbar-text.css';
-import './recipes.css';
 
+import { ContentItem } from '@kerfjs/ui/content-item';
+import { List } from '@kerfjs/ui/list';
 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 { Row } from '@kerfjs/ui/row';
+import { Text } from '@kerfjs/ui/text';
 import { signal } from 'kerfjs';
 import { ChevronRight, FileText, Folder } from 'lucide';
 
-import type { RecipeFactory } from './types.js';
+import type { RecipeFactory, RecipePresentation } from './types.js';
+
+export const presentation: RecipePresentation = {
+  viewport: {
+    layout: 'grid',
+    width: 'compact',
+    height: 'tall',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: '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.',
+};
 
 interface LibraryItem {
   id: string;
@@ -19,41 +35,80 @@ interface LibraryItem {
 }
 
 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.' },
+  {
+    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>,
+    toolbar: { title: 'Library' },
+    content: (
+      <List>
+        <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>
+      </List>
+    ),
   });
 
   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>,
+    toolbar: { title: item.label },
+    content: (
+      <List controlInsets="t">
+        <ContentItem>
+          <Row gap="xs">
+            <LucideIcon icon={FileText} name="file-text" />
+            <List gap="2xs">
+              <Text variant="span">
+                <strong>{item.label}</strong>
+              </Text>
+              <Text variant="span" tone="quiet" size="compact">
+                {item.detail}
+              </Text>
+            </List>
+          </Row>
+        </ContentItem>
+      </List>
+    ),
   });
 
   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>;
+  const render = () => (
+    <section
+      data-recipe="recipe-navigation-stack"
+      aria-label="Component Library"
+    >
+      <NavStack id="recipe-nav" label="Component Library" views={views.value} />
+    </section>
+  );
 
   return {
     render,

package/ux-demo/recipes/types.ts

@@ -1,11 +1,12 @@
+import type { CatalogExampleViewport } from '@kerfjs/ui/catalog';
 import type { SafeHtml } from 'kerfjs';
 
 export interface RecipeController {
   render(): SafeHtml;
   action(command: string, element: HTMLElement): void;
   change?(element: HTMLElement): void;
+  /** Runs after a recipe's DialogSurface closes (its native `close`). */
   afterHide?(element: HTMLElement): void;
-  resize?(id: string, size: number): void;
   /**
    * Install any imperative wiring the recipe owns on its mounted root (e.g.
    * `wireSidebar` for a collapsible rail/drawer), returning a disposer. The
@@ -14,4 +15,19 @@ export interface RecipeController {
   wire?(root: HTMLElement): () => void;
 }
 
-export type RecipeFactory = (announce: (message: string) => void) => RecipeController;
+export type RecipeFactory = (
+  announce: (message: string) => void,
+) => RecipeController;
+
+/**
+ * Catalog-only presentation for one recipe. The UX catalog frames the recipe in
+ * a `CatalogExample` viewport and shows `note` when recipe notes are toggled on;
+ * an application that copies the recipe ignores this export and mounts the
+ * controller into its own container.
+ */
+export interface RecipePresentation {
+  /** Catalog-owned specimen frame: width, height, surface, and border. */
+  viewport?: CatalogExampleViewport;
+  /** Ownership note: what the recipe owns versus what the application owns. */
+  note: string;
+}