@kerfjs/ui 5.0.0-beta.7 → 5.0.0-beta.71

package/ux-demo/recipes/app-shell.tsx

@@ -1,32 +1,220 @@
 import '@kerfjs/ui/layout.css';
-import './recipes.css';
+import '@kerfjs/ui/workbench.css';
 
+import { List } from '@kerfjs/ui/list';
+import { ListItem } from '@kerfjs/ui/list-item';
 import { LucideIcon } from '@kerfjs/ui/lucide-icon';
-import { MenuHeader } from '@kerfjs/ui/menu-header';
-import { MenuItem } from '@kerfjs/ui/menu-item';
-import { PanelHeader } from '@kerfjs/ui/panel-header';
-import { ResizableRegion } from '@kerfjs/ui/resizable-region';
 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 { signal } from 'kerfjs';
+import { wireWorkbench } from '@kerfjs/ui/wire-workbench';
+import { Workbench } from '@kerfjs/ui/workbench';
+import { delegate, signal } from 'kerfjs';
 import { Bell, Folder, Inbox, Settings } from 'lucide';
 
-import type { RecipeFactory } from './types.js';
+import type { RecipeFactory, RecipePresentation } from './types.js';
+
+const NAVIGATION_ACTION = 'recipe-shell-toggle-navigation';
+const INSPECTOR_ACTION = 'recipe-shell-toggle-inspector';
+
+const tasks = [
+  ['Release accessibility audit', 'Interface systems · due this week'],
+  ['Prepare tablet navigation', 'Interface systems · due this week'],
+  ['Review stale-data states', 'Platform · due next week'],
+  ['Confirm package boundaries', 'Platform · due next week'],
+] as const;
+
+export const presentation: RecipePresentation = {
+  viewport: {
+    width: 'full',
+    height: 'app',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: 'The recipe is a Workbench under an app bar: resizable navigation and inspector rails beside the task list, each rail toggled by its standard control, which moves into the work-area toolbar while the rail is hidden. On a small screen the rails overlay the task list one at a time. The app owns routing, data, rail visibility, sizes, and persistence.',
+};
 
 export const createRecipe: RecipeFactory = (announce) => {
   const selected = signal('inbox');
   const navigationSize = signal(224);
   const inspectorSize = signal(240);
-  const responsivePane = signal<'content' | 'navigation' | 'inspector'>('content');
-  const render = () => <section class="kui-recipe recipe-shell kui-recipe__surface kui-layout" data-recipe="recipe-app-shell" data-responsive-pane={responsivePane.value}>
-    <Toolbar label="Atlas workspace" leading={<ToolbarControlGroup appearance="borderless" single><ToolbarText text="Atlas" /></ToolbarControlGroup>} trailing={<div class="recipe-shell__toolbar-actions"><ToolbarControlGroup className="recipe-shell__responsive-controls" appearance="borderless" label="Workspace panes"><button type="button" aria-label="Show navigation" aria-controls="recipe-shell-navigation" aria-pressed={String(responsivePane.value === 'navigation')} data-action="recipe-action" data-recipe-command="show-navigation"><LucideIcon icon={Folder} name="folder" /></button><button type="button" aria-label="Show content" aria-controls="recipe-shell-content" aria-pressed={String(responsivePane.value === 'content')} data-action="recipe-action" data-recipe-command="show-content"><LucideIcon icon={Inbox} name="inbox" /></button><button type="button" aria-label="Show inspector" aria-controls="recipe-shell-inspector" aria-pressed={String(responsivePane.value === 'inspector')} data-action="recipe-action" data-recipe-command="show-inspector"><LucideIcon icon={Settings} name="settings" /></button></ToolbarControlGroup><ToolbarControlGroup appearance="borderless" label="Workspace controls"><button type="button" aria-label="Notifications" data-action="recipe-action" data-recipe-command="notify"><LucideIcon icon={Bell} name="bell" /></button><button type="button" aria-label="Settings" data-action="recipe-action" data-recipe-command="settings"><LucideIcon icon={Settings} name="settings" /></button></ToolbarControlGroup></div>} />
-    <div class="recipe-shell__body">
-      <div id="recipe-shell-navigation" class="recipe-shell__nav-region"><ResizableRegion id="recipe-navigation" label="Navigation" size={navigationSize.value} min={180} max={320}><aside class="recipe-shell__nav kui-pane"><MenuHeader label="Workspace" /><nav class="recipe-shell__nav-list kui-pane__content kui-content" aria-label="Workspace"><section><MenuItem action="recipe-action" itemId="inbox" label="Inbox" icon={<LucideIcon icon={Inbox} name="inbox" />} selected={selected.value === 'inbox'} /><MenuItem action="recipe-action" itemId="projects" label="Projects with a deliberately wrapping title" icon={<LucideIcon icon={Folder} name="folder" />} selected={selected.value === 'projects'} multiline /></section></nav></aside></ResizableRegion></div>
-      <main id="recipe-shell-content" class="recipe-shell__main kui-pane"><PanelHeader title={selected.value === 'inbox' ? 'Inbox triage' : 'Active projects'} titleId="recipe-shell-main-title" actions={<button class="kui-recipe__button" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="new">New task</button>} /><div class="recipe-shell__main-body kui-pane__content kui-content"><p class="kui-recipe__ownership kui-content-item">Recipe owns pane geometry and one scroll owner per pane. The app owns routing, data, pane visibility, sizes, and persistence.</p><div class="recipe-shell__cards">{['Release accessibility audit', 'Prepare tablet navigation', 'Review stale-data states', 'Confirm package boundaries'].map((title) => <article class="recipe-shell__card kui-content-item"><strong>{title}</strong><p class="kui-recipe__muted">Assigned to the interface systems team · due this week</p></article>)}</div></div></main>
-      <div id="recipe-shell-inspector" class="recipe-shell__inspector-region"><ResizableRegion id="recipe-inspector" label="Inspector" size={inspectorSize.value} min={200} max={360} edge="start"><aside class="recipe-shell__inspector kui-pane"><PanelHeader title="Inspector" titleId="recipe-shell-inspector-title" /><div class="recipe-shell__inspector-body kui-pane__content kui-content"><ValueTable label="Selected task"><ValueTableRow label="Status" value="In review" /><ValueTableRow label="Owner" value="Mara Chen" /><ValueTableRow label="Priority" value="High" /></ValueTable></div></aside></ResizableRegion></div>
-    </div>
-  </section>;
-  return { render, action(command, element) { const pane = command.match(/^show-(navigation|content|inspector)$/)?.[1] as typeof responsivePane.value | undefined; if (pane) responsivePane.value = pane; const id = element.dataset.itemId; if (id) selected.value = id; announce(id ? `Opened ${id}` : pane ? `Showing ${pane}` : command === 'new' ? 'New task requested' : `${command} requested`); }, resize(id, size) { if (id === 'recipe-navigation') navigationSize.value = size; if (id === 'recipe-inspector') inspectorSize.value = size; announce(`${id} resized to ${size}px`); } };
+  const navigationCollapsed = signal(false);
+  const inspectorCollapsed = signal(false);
+
+  const navigation = () => (
+    <nav aria-label="Workspace">
+      <List gap="2xs">
+        <ListItem
+          action="recipe-action"
+          itemId="inbox"
+          label="Inbox"
+          icon={<LucideIcon icon={Inbox} name="inbox" />}
+          selected={selected.value === 'inbox'}
+        />
+        <ListItem
+          action="recipe-action"
+          itemId="projects"
+          label="Projects with a deliberately wrapping title"
+          icon={<LucideIcon icon={Folder} name="folder" />}
+          selected={selected.value === 'projects'}
+          multiline
+        />
+      </List>
+    </nav>
+  );
+
+  const render = () => (
+    <List fill rootAttributes={{ 'data-recipe': 'recipe-app-shell' }}>
+      <Toolbar
+        label="Atlas workspace"
+        safeAreaEdges={['block-start', 'inline-start', 'inline-end']}
+        dividerSides="b"
+        leading={<ToolbarText text="Atlas" />}
+        trailing={
+          <ToolbarControlGroup
+            appearance="borderless"
+            label="Workspace controls"
+          >
+            <button
+              type="button"
+              aria-label="Notifications"
+              data-action="recipe-action"
+              data-recipe-command="notify"
+            >
+              <LucideIcon icon={Bell} name="bell" />
+            </button>
+            <button
+              type="button"
+              aria-label="Settings"
+              data-action="recipe-action"
+              data-recipe-command="settings"
+            >
+              <LucideIcon icon={Settings} name="settings" />
+            </button>
+          </ToolbarControlGroup>
+        }
+      />
+      <List flex>
+        <Workbench
+          id="recipe-shell"
+          label="Atlas workspace panes"
+          leftRail={{
+            label: 'Navigation',
+            size: navigationSize.value,
+            resizable: { min: 180, max: 320 },
+            collapsed: navigationCollapsed.value,
+            toolbar: {
+              label: 'Navigation',
+              title: <ToolbarText text="Workspace" />,
+              toggle: { action: NAVIGATION_ACTION, name: 'navigation' },
+            },
+            content: navigation(),
+          }}
+          mainToolbar={{
+            label: 'Current workspace view',
+            title: (
+              <ToolbarText
+                text={
+                  selected.value === 'inbox'
+                    ? 'Inbox triage'
+                    : 'Active projects'
+                }
+                size="xlarge"
+                id="recipe-shell-main-title"
+              />
+            ),
+            responsive: 'wrap',
+            trailing: (
+              <ToolbarControlGroup
+                appearance="borderless"
+                content="text"
+                single
+              >
+                <button
+                  type="button"
+                  data-action="recipe-action"
+                  data-recipe-command="new"
+                >
+                  New task
+                </button>
+              </ToolbarControlGroup>
+            ),
+          }}
+          main={
+            <section aria-label="Tasks">
+              {tasks.map(([title, detail]) => (
+                <ListItem
+                  action="recipe-action"
+                  label={title}
+                  description={detail}
+                  multiline
+                  rootAttributes={{ 'data-recipe-command': 'open-task' }}
+                />
+              ))}
+            </section>
+          }
+          rightRail={{
+            label: 'Inspector',
+            size: inspectorSize.value,
+            resizable: { min: 200, max: 360 },
+            collapsed: inspectorCollapsed.value,
+            toolbar: {
+              label: 'Inspector',
+              title: <ToolbarText text="Inspector" />,
+              toggle: { action: INSPECTOR_ACTION, name: 'inspector' },
+            },
+            content: (
+              <ValueTable label="Selected task">
+                <ValueTableRow label="Status" value="In review" />
+                <ValueTableRow label="Owner" value="Mara Chen" />
+                <ValueTableRow label="Priority" value="High" />
+              </ValueTable>
+            ),
+          }}
+        />
+      </List>
+    </List>
+  );
+
+  return {
+    render,
+    action(command, element) {
+      const id = element.dataset.itemId;
+      if (id) selected.value = id;
+      announce(
+        id
+          ? `Opened ${id}`
+          : command === 'new'
+            ? 'New task requested'
+            : `${command} requested`,
+      );
+    },
+    wire(root) {
+      const toggle = (action: string, collapsed: typeof navigationCollapsed) =>
+        delegate(root, 'click', `[data-action="${action}"]`, () => {
+          collapsed.value = !collapsed.value;
+        });
+      const stops = [
+        toggle(NAVIGATION_ACTION, navigationCollapsed),
+        toggle(INSPECTOR_ACTION, inspectorCollapsed),
+        wireWorkbench(root, {
+          id: 'recipe-shell',
+          panels: {
+            leftRail: { size: navigationSize, collapsed: navigationCollapsed },
+            rightRail: { size: inspectorSize, collapsed: inspectorCollapsed },
+          },
+          onResize: ({ panel, size }) =>
+            announce(
+              `${panel === 'leftRail' ? 'Navigation' : 'Inspector'} resized to ${size}px`,
+            ),
+        }),
+      ];
+      return () => {
+        for (const stop of stops) stop();
+      };
+    },
+  };
 };

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

@@ -0,0 +1,260 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/collapsible-panel.css';
+import '@kerfjs/ui/floating-toolbar.css';
+
+import {
+  CollapsiblePanel,
+  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 { Pane } from '@kerfjs/ui/pane';
+import { Row } from '@kerfjs/ui/row';
+import { Text } from '@kerfjs/ui/text';
+import { Toolbar } from '@kerfjs/ui/toolbar';
+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, 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.
+ */
+function memoryStorage(): SidebarStorage {
+  const map = new Map<string, string>();
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => {
+      map.set(key, value);
+    },
+  };
+}
+
+const labels: Record<string, string> = {
+  inbox: 'Inbox',
+  projects: 'Projects',
+  shared: 'Shared with me',
+};
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const selected = signal('inbox');
+  // 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();
+
+  // 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}
+      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 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>Narrow the window to a compact width</strong>
+          </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>
+      </ContentItem>
+    </Pane>
+  );
+
+  const drawer = () => (
+    <CollapsiblePanel
+      id="sidebar-console"
+      side="bottom"
+      size={168}
+      collapsed={drawerCollapsed.value}
+      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 = () => (
+    <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 {
+    render,
+    action(command, element) {
+      const id = element.dataset.itemId;
+      if (id) {
+        selected.value = id;
+        announce(`Opened ${id}`);
+        return;
+      }
+      announce(`${command} requested`);
+    },
+    wire(root) {
+      return wireSidebar(root, {
+        deviceClass: device,
+        storage,
+        panels: [
+          {
+            id: 'sidebar-rail',
+            collapsed: railCollapsed,
+            toggleAction: RAIL_ACTION,
+            storageKey: 'recipe-sidebar-rail',
+            inlineCollapsed: false,
+          },
+          {
+            id: 'sidebar-console',
+            collapsed: drawerCollapsed,
+            toggleAction: DRAWER_ACTION,
+            storageKey: 'recipe-sidebar-console',
+          },
+        ],
+      });
+    },
+  };
+};