@kerfjs/ui 5.0.0-beta.49 → 5.0.0-beta.51

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

@@ -1,28 +1,44 @@
 import '@kerfjs/ui/layout.css';
 import '@kerfjs/ui/collapsible-panel.css';
-import './recipes.css';
 
 import {
   CollapsiblePanel,
   CollapsiblePanelToggle,
 } from '@kerfjs/ui/collapsible-panel';
 import { deviceClass } from '@kerfjs/ui/device-class';
+import { Grid } from '@kerfjs/ui/grid';
+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 { Row } from '@kerfjs/ui/row';
 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 { ValueTable, ValueTableRow } from '@kerfjs/ui/value-table';
 import { type SidebarStorage, wireSidebar } from '@kerfjs/ui/wire-sidebar';
 import { signal } from 'kerfjs';
 import { Bell, Folder, Inbox, Users } from 'lucide';
 
-import type { RecipeFactory } from './types.js';
+import type { RecipeFactory, RecipePresentation } from './types.js';
 
 const RAIL_ACTION = 'recipe-sidebar-rail';
 const DRAWER_ACTION = 'recipe-sidebar-drawer';
 
+export const presentation: RecipePresentation = {
+  viewport: {
+    width: 'full',
+    height: 'app',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: "The app owns each panel's collapsed signal, sizes, and content; wireSidebar owns the toggle, focus move/restore, the compact overlay, and persistence.",
+};
+
 /**
  * A memory-backed store so the recipe demonstrates the persistence hook without
  * writing to the shared `localStorage` the catalog page runs in.
@@ -37,23 +53,31 @@ function memoryStorage(): SidebarStorage {
   };
 }
 
+const labels: Record<string, string> = {
+  inbox: 'Inbox',
+  projects: 'Projects',
+  shared: 'Shared with me',
+};
+
 export const createRecipe: RecipeFactory = (announce) => {
   const selected = signal('inbox');
-  const railCollapsed = signal(false);
-  const drawerCollapsed = signal(true);
-  const storage = memoryStorage();
   // A shared window-backed device class: when the viewport is compact the wire
   // switches the rail/drawer to a dismissable overlay presentation.
   const device = deviceClass();
+  // A compact overlay only opens on a user action, so the first render already
+  // matches: collapsed on a compact device, open inline otherwise. The wire's
+  // `inlineCollapsed` keeps the open inline default for a later wide crossing.
+  const railCollapsed = signal(device.value.compact);
+  const drawerCollapsed = signal(true);
+  const storage = memoryStorage();
 
-  const railToggle = (inPanel: boolean) => (
+  const railToggle = () => (
     <CollapsiblePanelToggle
       side="left"
       collapsed={railCollapsed.value}
       action={RAIL_ACTION}
       panelId="sidebar-rail"
       label={railCollapsed.value ? 'Show navigation' : 'Hide navigation'}
-      className={inPanel ? '' : 'recipe-collapsible-sidebar__reveal'}
     />
   );
   const drawerToggle = () => (
@@ -66,133 +90,167 @@ export const createRecipe: RecipeFactory = (announce) => {
     />
   );
 
-  const render = () => (
-    <section
-      class="kui-recipe recipe-collapsible-sidebar kui-recipe__surface"
-      data-recipe="recipe-collapsible-sidebar"
-      data-rail-collapsed={String(railCollapsed.value)}
-      data-drawer-collapsed={String(drawerCollapsed.value)}
+  const rail = () => (
+    <CollapsiblePanel
+      id="sidebar-rail"
+      side="left"
+      size={232}
+      collapsed={railCollapsed.value}
+      label="Workspace navigation"
     >
-      <CollapsiblePanel
-        id="sidebar-rail"
-        side="left"
-        size={232}
-        collapsed={railCollapsed.value}
-        label="Workspace navigation"
-        className="recipe-collapsible-sidebar__rail kui-pane"
+      <Pane
+        contentElement="nav"
+        contentLabel="Workspace"
+        header={
+          <Toolbar
+            label="Workspace navigation"
+            dividerSides=""
+            leading={<ToolbarText text="Atlas" />}
+            trailing={
+              <ToolbarControlGroup appearance="borderless" single>
+                {railToggle()}
+              </ToolbarControlGroup>
+            }
+          />
+        }
       >
-        <div class="recipe-collapsible-sidebar__rail-head">
-          <ToolbarText text="Atlas" />
-          <ToolbarControlGroup appearance="borderless" single>
-            {railToggle(true)}
-          </ToolbarControlGroup>
-        </div>
-        <nav
-          class="recipe-collapsible-sidebar__nav kui-pane__content kui-content"
-          aria-label="Workspace"
-        >
-          <section>
-            <ListHeader label="Workspace" />
-            <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="projects"
-              label="Projects"
-              icon={<LucideIcon icon={Folder} name="folder" />}
-              selected={selected.value === 'projects'}
-            />
-            <ListItem
-              action="recipe-action"
-              itemId="shared"
-              label="Shared with me"
-              icon={<LucideIcon icon={Users} name="users" />}
-              selected={selected.value === 'shared'}
-            />
-          </section>
-        </nav>
-      </CollapsiblePanel>
-      <main class="recipe-collapsible-sidebar__main kui-pane">
+        <section>
+          <ListHeader label="Workspace" />
+          <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="projects"
+            label="Projects"
+            icon={<LucideIcon icon={Folder} name="folder" />}
+            selected={selected.value === 'projects'}
+          />
+          <ListItem
+            action="recipe-action"
+            itemId="shared"
+            label="Shared with me"
+            icon={<LucideIcon icon={Users} name="users" />}
+            selected={selected.value === 'shared'}
+          />
+        </section>
+      </Pane>
+    </CollapsiblePanel>
+  );
+
+  // Each panel's own header holds its collapse toggle; the always-visible main
+  // header holds its expand toggle only while it is collapsed, so exactly one
+  // control owns each action. wireSidebar hands focus between them.
+  const main = () => (
+    <Pane
+      element="main"
+      header={
         <Toolbar
           label="Current navigation view"
           dividerSides=""
           leading={
             <>
-              <ToolbarControlGroup appearance="borderless" single>
-                {railToggle(false)}
-              </ToolbarControlGroup>
+              {railCollapsed.value ? (
+                <ToolbarControlGroup appearance="borderless" single>
+                  {railToggle()}
+                </ToolbarControlGroup>
+              ) : null}
               <ToolbarText
-                text={
-                  selected.value === 'projects'
-                    ? 'Projects'
-                    : selected.value === 'shared'
-                      ? 'Shared with me'
-                      : 'Inbox'
-                }
+                text={labels[selected.value] ?? 'Inbox'}
                 size="xlarge"
                 id="recipe-collapsible-main-title"
               />
             </>
           }
           trailing={
-            <ToolbarControlGroup appearance="borderless" single>
-              {drawerToggle()}
-            </ToolbarControlGroup>
+            drawerCollapsed.value ? (
+              <ToolbarControlGroup appearance="borderless" single>
+                {drawerToggle()}
+              </ToolbarControlGroup>
+            ) : undefined
           }
         />
-        <div class="recipe-collapsible-sidebar__body kui-pane__content kui-content">
-          <Text class="kui-recipe__ownership kui-content-item">
-            The app owns each panel's <code>collapsed</code> signal, sizes, and
-            content; <code>wireSidebar</code> owns the toggle, focus
-            move/restore, the compact overlay, and persistence.
-          </Text>
-          <article class="recipe-collapsible-sidebar__card kui-content-item">
+      }
+    >
+      <div class="kui-content-item">
+        <List gap="2xs">
+          <Text variant="span">
             <strong>Narrow the window to a compact width</strong>
-            <Text class="kui-recipe__muted">
-              The rail and drawer become a dismissable overlay: a backdrop,
-              Escape, and a trapped Tab ring, all managed by the wire.
-            </Text>
-          </article>
-        </div>
-      </main>
-      <CollapsiblePanel
-        id="sidebar-console"
-        side="bottom"
-        size={168}
-        collapsed={drawerCollapsed.value}
-        label="Activity"
-        className="recipe-collapsible-sidebar__drawer kui-pane"
+          </Text>
+          <Text variant="span" tone="quiet" size="compact">
+            The rail and drawer start closed and open as a dismissable overlay:
+            a backdrop, Escape, and a trapped Tab ring, all managed by the wire.
+          </Text>
+        </List>
+      </div>
+    </Pane>
+  );
+
+  const drawer = () => (
+    <CollapsiblePanel
+      id="sidebar-console"
+      side="bottom"
+      size={168}
+      collapsed={drawerCollapsed.value}
+      label="Activity"
+    >
+      <Pane
+        header={
+          <Toolbar
+            label="Activity"
+            dividerSides="b"
+            leading={<ToolbarText text="Activity" size="small" />}
+            trailing={
+              <ToolbarControlGroup appearance="borderless" single>
+                {drawerToggle()}
+              </ToolbarControlGroup>
+            }
+          />
+        }
       >
-        <Toolbar
-          label="Activity"
-          dividerSides="b"
-          leading={<ToolbarText text="Activity" size="small" />}
-          trailing={
-            <ToolbarControlGroup appearance="borderless" single>
-              {drawerToggle()}
-            </ToolbarControlGroup>
-          }
-        />
-        <div class="recipe-collapsible-sidebar__drawer-body kui-pane__content kui-content">
-          <ul class="recipe-collapsible-sidebar__log">
-            <li>
-              <LucideIcon icon={Bell} name="bell" />
-              Deploy finished · 2m ago
-            </li>
-            <li>
-              <LucideIcon icon={Bell} name="bell" />
-              Review requested · 9m ago
-            </li>
-          </ul>
-        </div>
-      </CollapsiblePanel>
-    </section>
+        <ValueTable label="Recent activity">
+          <ValueTableRow
+            label="Deploy finished"
+            value="2m ago"
+            icon={<LucideIcon icon={Bell} name="bell" />}
+          />
+          <ValueTableRow
+            label="Review requested"
+            value="9m ago"
+            icon={<LucideIcon icon={Bell} name="bell" />}
+          />
+        </ValueTable>
+      </Pane>
+    </CollapsiblePanel>
+  );
+
+  // The root Row fills the frame's definite height with the rail beside a
+  // column whose main pane grows above the bottom drawer. Each CollapsiblePanel
+  // docks to a real frame edge, so it paints through that edge's safe area and
+  // hands the edge back to its siblings when it collapses.
+  const render = () => (
+    <Row
+      gap="none"
+      fill
+      rootAttributes={{
+        'data-recipe': 'recipe-collapsible-sidebar',
+        'data-rail-collapsed': String(railCollapsed.value),
+        'data-drawer-collapsed': String(drawerCollapsed.value),
+      }}
+    >
+      {rail()}
+      <List flex>
+        <Grid columns={1} gap="none" flex>
+          {main()}
+        </Grid>
+        {drawer()}
+      </List>
+    </Row>
   );
 
   return {
@@ -216,6 +274,7 @@ export const createRecipe: RecipeFactory = (announce) => {
             collapsed: railCollapsed,
             toggleAction: RAIL_ACTION,
             storageKey: 'recipe-sidebar-rail',
+            inlineCollapsed: false,
           },
           {
             id: 'sidebar-console',

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

@@ -1,7 +1,10 @@
 import '@kerfjs/ui/layout.css';
 import '@kerfjs/ui/select/register';
-import './recipes.css';
 
+import { deviceClass } from '@kerfjs/ui/device-class';
+import { Grid } from '@kerfjs/ui/grid';
+import { List } from '@kerfjs/ui/list';
+import { ListInsetText } from '@kerfjs/ui/list-inset-text';
 import { LucideIcon } from '@kerfjs/ui/lucide-icon';
 import { SegmentedControl } from '@kerfjs/ui/segmented-control';
 import { Select } from '@kerfjs/ui/select';
@@ -12,114 +15,128 @@ import { ToolbarText } from '@kerfjs/ui/toolbar-text';
 import { signal } from 'kerfjs';
 import { Filter, MoreHorizontal, RefreshCw } from 'lucide';
 
-import type { RecipeFactory } from './types.js';
+import type { RecipeFactory, RecipePresentation } from './types.js';
+
+const guide = [
+  ['ToolbarControlGroup', 'Related commands or pressed tools.'],
+  ['SegmentedControl', 'A few visible exclusive choices.'],
+  ['Select', 'A longer controlled value list.'],
+  ['Ordinary button', 'One independent command.'],
+] as const;
+
+export const presentation: RecipePresentation = {
+  viewport: {
+    width: 'full',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: 'The recipe owns control semantics and wrapping. The app owns values, actions, persistence, and responsive priority.',
+};
 
 export const createRecipe: RecipeFactory = (announce) => {
   const view = signal('list');
   const sort = signal('updated');
   const filtered = signal(false);
+  const device = deviceClass();
   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<string>
-              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<string>
-              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>
-            <ToolbarControlGroup label="More task actions" single>
-              <button
-                type="button"
-                aria-label="More task actions"
-                data-action="recipe-action"
-                data-recipe-command="more"
-              >
-                <LucideIcon icon={MoreHorizontal} name="more-horizontal" />
-              </button>
+    <section data-recipe="recipe-compact-toolbar" aria-label="Task workspace">
+      <List gap="l" controlInsets="b">
+        <Toolbar
+          label="Task workspace controls"
+          responsive="stack"
+          responsiveAt="compact"
+          leading={<ToolbarText text="Tasks" size="small" />}
+          center={
+            <ToolbarControlGroup>
+              <SegmentedControl<string>
+                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>
-          </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>
-      <Text class="kui-recipe__ownership kui-content-item">
-        The recipe owns control semantics and wrapping. The app owns values,
-        actions, persistence, and responsive priority.
-      </Text>
+          }
+          trailing={
+            <>
+              <ToolbarControlGroup single focusRing="outline">
+                <Select<string>
+                  name="recipe-sort"
+                  value={sort.value}
+                  ariaLabel="Sort tasks"
+                  fitMenu
+                  presentation="toolbar-borderless"
+                  size="compact"
+                  focusRingOwner="group"
+                  choices={[
+                    { value: 'updated', label: 'Recently updated' },
+                    { value: 'priority', label: 'Priority' },
+                    { value: 'owner', label: 'Owner' },
+                    { value: 'created', label: 'Created date' },
+                  ]}
+                />
+              </ToolbarControlGroup>
+              <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>
+              <ToolbarControlGroup label="More task actions" single>
+                <button
+                  type="button"
+                  aria-label="More task actions"
+                  data-action="recipe-action"
+                  data-recipe-command="more"
+                >
+                  <LucideIcon icon={MoreHorizontal} name="more-horizontal" />
+                </button>
+              </ToolbarControlGroup>
+            </>
+          }
+        />
+        <Grid
+          columns={
+            device.value.compact ? 1 : device.value.atLeast('desktop') ? 4 : 2
+          }
+          gap="none"
+        >
+          {guide.map(([name, use]) => (
+            <ListInsetText>
+              <List gap="2xs">
+                <Text variant="span">
+                  <strong>{name}</strong>
+                </Text>
+                <Text variant="span" tone="quiet" size="compact">
+                  {use}
+                </Text>
+              </List>
+            </ListInsetText>
+          ))}
+        </Grid>
+      </List>
     </section>
   );
   return {