@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

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

@@ -1,28 +1,47 @@
 import '@kerfjs/ui/layout.css';
 import '@kerfjs/ui/collapsible-panel.css';
-import './recipes.css';
+import '@kerfjs/ui/floating-toolbar.css';
 
 import {
   CollapsiblePanel,
-  CollapsiblePanelToggle,
+  CollapsiblePanelRelocated,
+  type CollapsiblePanelToolbar,
 } from '@kerfjs/ui/collapsible-panel';
+import { ContentItem } from '@kerfjs/ui/content-item';
 import { deviceClass } from '@kerfjs/ui/device-class';
+import { FloatingToolbar } from '@kerfjs/ui/floating-toolbar';
+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 { PanelHeader } from '@kerfjs/ui/panel-header';
+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,155 +56,173 @@ 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) => (
-    <CollapsiblePanelToggle
+  // Each panel composes its own toolbar with the standard toggle last. While a
+  // panel is collapsed, CollapsiblePanelRelocated carries that toggle: the
+  // rail's leads the main toolbar, the drawer's floats in its container's
+  // bottom-end corner. wireSidebar hands focus between the two positions.
+  const railToolbar: CollapsiblePanelToolbar = {
+    label: 'Workspace Navigation',
+    title: <ToolbarText text="Atlas" />,
+    toggle: { action: RAIL_ACTION, name: 'Navigation' },
+  };
+  const drawerToolbar: CollapsiblePanelToolbar = {
+    label: 'Activity',
+    title: <ToolbarText text="Activity" size="small" />,
+    toggle: { action: DRAWER_ACTION, name: 'Activity' },
+  };
+
+  const rail = () => (
+    <CollapsiblePanel
+      id="sidebar-rail"
       side="left"
+      size={232}
       collapsed={railCollapsed.value}
-      action={RAIL_ACTION}
-      panelId="sidebar-rail"
-      label={railCollapsed.value ? 'Show navigation' : 'Hide navigation'}
-      className={inPanel ? '' : 'recipe-collapsible-sidebar__reveal'}
-    />
+      label="Workspace Navigation"
+      toolbar={railToolbar}
+    >
+      <nav 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>
   );
-  const drawerToggle = () => (
-    <CollapsiblePanelToggle
+
+  const main = () => (
+    <Pane
+      element="main"
+      header={
+        <Toolbar
+          label="Current Navigation View"
+          leading={
+            <>
+              <CollapsiblePanelRelocated
+                panelId="sidebar-rail"
+                side="left"
+                collapsed={railCollapsed.value}
+                toolbar={railToolbar}
+              />
+              <ToolbarText
+                text={labels[selected.value] ?? 'Inbox'}
+                size="xlarge"
+                id="recipe-collapsible-main-title"
+              />
+            </>
+          }
+        />
+      }
+    >
+      <ContentItem>
+        <List gap="2xs">
+          <Text variant="span">
+            <strong>Compact Width</strong>
+          </Text>
+          <Text variant="span" tone="quiet" size="compact">
+            Narrow the window to a compact width: the rail and drawer start
+            closed and open as a dismissable overlay, with a backdrop, Escape,
+            and a trapped Tab ring, all managed by the wire.
+          </Text>
+        </List>
+      </ContentItem>
+    </Pane>
+  );
+
+  const drawer = () => (
+    <CollapsiblePanel
+      id="sidebar-console"
       side="bottom"
+      size={168}
       collapsed={drawerCollapsed.value}
-      action={DRAWER_ACTION}
-      panelId="sidebar-console"
-      label={drawerCollapsed.value ? 'Show activity' : 'Hide activity'}
-    />
+      label="Activity"
+      toolbar={drawerToolbar}
+      restoreControl={
+        <FloatingToolbar label="Activity Drawer">
+          <CollapsiblePanelRelocated
+            panelId="sidebar-console"
+            side="bottom"
+            collapsed={drawerCollapsed.value}
+            toolbar={drawerToolbar}
+          />
+        </FloatingToolbar>
+      }
+    >
+      <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>
+    </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 = () => (
-    <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)}
+    <Row
+      gap="none"
+      fill
+      rootAttributes={{
+        'data-recipe': 'recipe-collapsible-sidebar',
+        'data-rail-collapsed': String(railCollapsed.value),
+        'data-drawer-collapsed': String(drawerCollapsed.value),
+      }}
     >
-      <CollapsiblePanel
-        id="sidebar-rail"
-        side="left"
-        size={232}
-        collapsed={railCollapsed.value}
-        label="Workspace navigation"
-        className="recipe-collapsible-sidebar__rail kui-pane"
-      >
-        <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">
-        <PanelHeader
-          title={
-            selected.value === 'projects'
-              ? 'Projects'
-              : selected.value === 'shared'
-                ? 'Shared with me'
-                : 'Inbox'
-          }
-          titleId="recipe-collapsible-main-title"
-          icon={railToggle(false)}
-          actions={
-            <ToolbarControlGroup appearance="borderless" single>
-              {drawerToggle()}
-            </ToolbarControlGroup>
-          }
-        />
-        <div class="recipe-collapsible-sidebar__body kui-pane__content kui-content">
-          <p 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.
-          </p>
-          <article class="recipe-collapsible-sidebar__card kui-content-item">
-            <strong>Narrow the window to a compact width</strong>
-            <p 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.
-            </p>
-          </article>
-        </div>
-      </main>
-      <CollapsiblePanel
-        id="sidebar-console"
-        side="bottom"
-        size={168}
-        collapsed={drawerCollapsed.value}
-        label="Activity"
-        className="recipe-collapsible-sidebar__drawer kui-pane"
-      >
-        <Toolbar
-          label="Activity"
-          dividerSides="b"
-          leading={
-            <ToolbarControlGroup appearance="borderless" single>
-              <ToolbarText text="Activity" size="small" />
-            </ToolbarControlGroup>
-          }
-          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>
+      {rail()}
+      <List flex>
+        <Grid columns={1} gap="none" flex>
+          {main()}
+        </Grid>
+        {drawer()}
+      </List>
+    </Row>
   );
 
   return {
@@ -209,6 +246,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,123 +1,142 @@
 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';
+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 { 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>
+    <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>
-            <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>
+          }
+          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 {