@kerfjs/ui 5.0.0-beta.54 → 5.0.0-beta.55

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

@@ -1,32 +1,22 @@
 import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/workbench.css';
 
-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, type PaneSeparatorSide } from '@kerfjs/ui/pane';
-import { ResizableRegion } from '@kerfjs/ui/resizable-region';
-import { Row } from '@kerfjs/ui/row';
 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, RecipePresentation } from './types.js';
 
-type ShellPane = 'content' | 'navigation' | 'inspector';
-type ScreenEdges = readonly PaneSeparatorSide[];
-
-// Safe areas: the app bar claims the top edge and both sides, so it clears the
-// status area. Each pane below compensates only for the screen edges it
-// actually reaches: the bottom, plus its outer side in the three-pane layout or
-// both sides when it is the only pane shown.
-const appBarEdges: ScreenEdges = ['block-start', 'inline-start', 'inline-end'];
-const soleEdges: ScreenEdges = ['block-end', 'inline-start', 'inline-end'];
+const NAVIGATION_ACTION = 'recipe-shell-toggle-navigation';
+const INSPECTOR_ACTION = 'recipe-shell-toggle-inspector';
 
 const tasks = [
   ['Release accessibility audit', 'Interface systems · due this week'],
@@ -44,46 +34,19 @@ export const presentation: RecipePresentation = {
     overflow: 'hidden',
     shadow: true,
   },
-  note: 'The recipe owns pane geometry and one scroll owner per pane. The app owns routing, data, pane visibility, sizes, and persistence.',
+  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<ShellPane>('content');
-  // Desktop-class viewports show all three panes; smaller ones show one pane
-  // at a time and let the toolbar switch between them.
-  const device = deviceClass();
-
-  const paneButton = (
-    pane: ShellPane,
-    label: string,
-    icon: typeof Folder,
-    iconName: string,
-  ) => (
-    <button
-      type="button"
-      aria-label={label}
-      aria-controls={`recipe-shell-${pane}`}
-      aria-pressed={String(responsivePane.value === pane)}
-      data-action="recipe-action"
-      data-recipe-command={`show-${pane}`}
-    >
-      <LucideIcon icon={icon} name={iconName} />
-    </button>
-  );
+  const navigationCollapsed = signal(false);
+  const inspectorCollapsed = signal(false);
 
-  const navigation = (edges: ScreenEdges) => (
-    <Pane
-      element="aside"
-      safeAreaEdges={edges}
-      id="recipe-shell-navigation"
-      contentElement="nav"
-      contentLabel="Workspace"
-    >
-      <section>
-        <ListHeader label="Workspace" />
+  const navigation = () => (
+    <nav aria-label="Workspace">
+      <List gap="2xs">
         <ListItem
           action="recipe-action"
           itemId="inbox"
@@ -99,204 +62,159 @@ export const createRecipe: RecipeFactory = (announce) => {
           selected={selected.value === 'projects'}
           multiline
         />
-      </section>
-    </Pane>
-  );
-
-  const content = (edges: ScreenEdges) => (
-    <Pane
-      element="main"
-      safeAreaEdges={edges}
-      id="recipe-shell-content"
-      header={
-        <Toolbar
-          label="Current workspace view"
-          dividerSides=""
-          leading={
-            <ToolbarText
-              text={
-                selected.value === 'inbox' ? 'Inbox triage' : 'Active projects'
-              }
-              size="xlarge"
-              id="recipe-shell-main-title"
-            />
-          }
-          trailing={
-            <ToolbarControlGroup appearance="borderless" content="text" single>
-              <button
-                type="button"
-                data-action="recipe-action"
-                data-recipe-command="new"
-              >
-                New task
-              </button>
-            </ToolbarControlGroup>
-          }
-        />
-      }
-    >
-      <section aria-label="Tasks">
-        {tasks.map(([title, detail]) => (
-          <ListItem
-            action="recipe-action"
-            label={title}
-            description={detail}
-            multiline
-            rootAttributes={{ 'data-recipe-command': 'open-task' }}
-          />
-        ))}
-      </section>
-    </Pane>
-  );
-
-  const inspector = (edges: ScreenEdges) => (
-    <Pane
-      element="aside"
-      safeAreaEdges={edges}
-      id="recipe-shell-inspector"
-      header={
-        <Toolbar
-          label="Inspector"
-          dividerSides=""
-          leading={
-            <ToolbarText
-              text="Inspector"
-              size="xlarge"
-              id="recipe-shell-inspector-title"
-            />
-          }
-        />
-      }
-    >
-      <ValueTable label="Selected task">
-        <ValueTableRow label="Status" value="In review" />
-        <ValueTableRow label="Owner" value="Mara Chen" />
-        <ValueTableRow label="Priority" value="High" />
-      </ValueTable>
-    </Pane>
+      </List>
+    </nav>
   );
 
-  const render = () => {
-    const onePane = !device.value.atLeast('desktop');
-    return (
-      <List
-        fill
-        rootAttributes={{
-          'data-recipe': 'recipe-app-shell',
-          'data-responsive-pane': onePane ? responsivePane.value : 'all',
-        }}
-      >
-        <Toolbar
-          label="Atlas workspace"
-          safeAreaEdges={appBarEdges}
-          leading={<ToolbarText text="Atlas" />}
-          trailing={
-            <>
-              {onePane ? (
-                <ToolbarControlGroup
-                  appearance="borderless"
-                  buttonAppearance="push"
-                  label="Workspace panes"
-                >
-                  {paneButton(
-                    'navigation',
-                    'Show navigation',
-                    Folder,
-                    'folder',
-                  )}
-                  {paneButton('content', 'Show content', Inbox, 'inbox')}
-                  {paneButton(
-                    'inspector',
-                    'Show inspector',
-                    Settings,
-                    'settings',
-                  )}
-                </ToolbarControlGroup>
-              ) : null}
+  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"
-                label="Workspace controls"
+                content="text"
+                single
               >
                 <button
                   type="button"
-                  aria-label="Notifications"
                   data-action="recipe-action"
-                  data-recipe-command="notify"
+                  data-recipe-command="new"
                 >
-                  <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" />
+                  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>
+            ),
+          }}
         />
-        {onePane ? (
-          <Grid columns={1} gap="none" flex>
-            {responsivePane.value === 'navigation'
-              ? navigation(soleEdges)
-              : responsivePane.value === 'inspector'
-                ? inspector(soleEdges)
-                : content(soleEdges)}
-          </Grid>
-        ) : (
-          <Row gap="none" flex>
-            <ResizableRegion
-              id="recipe-navigation"
-              label="Navigation"
-              size={navigationSize.value}
-              min={180}
-              max={320}
-            >
-              {navigation(['block-end', 'inline-start'])}
-            </ResizableRegion>
-            <Grid columns={1} gap="none" flex>
-              {content(['block-end'])}
-            </Grid>
-            <ResizableRegion
-              id="recipe-inspector"
-              label="Inspector"
-              size={inspectorSize.value}
-              min={200}
-              max={360}
-              edge="start"
-            >
-              {inspector(['block-end', 'inline-end'])}
-            </ResizableRegion>
-          </Row>
-        )}
       </List>
-    );
-  };
+    </List>
+  );
+
   return {
     render,
     action(command, element) {
-      const pane = command.match(
-        /^show-(navigation|content|inspector)$/,
-      )?.[1] as ShellPane | 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`,
+          : 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`);
+    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

@@ -4,7 +4,8 @@ import '@kerfjs/ui/floating-toolbar.css';
 
 import {
   CollapsiblePanel,
-  CollapsiblePanelToggle,
+  CollapsiblePanelRelocated,
+  type CollapsiblePanelToolbar,
 } from '@kerfjs/ui/collapsible-panel';
 import { deviceClass } from '@kerfjs/ui/device-class';
 import { FloatingToolbar } from '@kerfjs/ui/floating-toolbar';
@@ -17,7 +18,6 @@ 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';
@@ -73,24 +73,20 @@ export const createRecipe: RecipeFactory = (announce) => {
   const drawerCollapsed = signal(true);
   const storage = memoryStorage();
 
-  const railToggle = () => (
-    <CollapsiblePanelToggle
-      side="left"
-      collapsed={railCollapsed.value}
-      action={RAIL_ACTION}
-      panelId="sidebar-rail"
-      label={railCollapsed.value ? 'Show navigation' : 'Hide navigation'}
-    />
-  );
-  const drawerToggle = () => (
-    <CollapsiblePanelToggle
-      side="bottom"
-      collapsed={drawerCollapsed.value}
-      action={DRAWER_ACTION}
-      panelId="sidebar-console"
-      label={drawerCollapsed.value ? 'Show activity' : 'Hide activity'}
-    />
-  );
+  // 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
@@ -99,23 +95,9 @@ export const createRecipe: RecipeFactory = (announce) => {
       size={232}
       collapsed={railCollapsed.value}
       label="Workspace navigation"
+      toolbar={railToolbar}
     >
-      <Pane
-        contentElement="nav"
-        contentLabel="Workspace"
-        header={
-          <Toolbar
-            label="Workspace navigation"
-            dividerSides=""
-            leading={<ToolbarText text="Atlas" />}
-            trailing={
-              <ToolbarControlGroup appearance="borderless" single>
-                {railToggle()}
-              </ToolbarControlGroup>
-            }
-          />
-        }
-      >
+      <nav aria-label="Workspace">
         <section>
           <ListHeader label="Workspace" />
           <ListItem
@@ -141,15 +123,10 @@ export const createRecipe: RecipeFactory = (announce) => {
             selected={selected.value === 'shared'}
           />
         </section>
-      </Pane>
+      </nav>
     </CollapsiblePanel>
   );
 
-  // Each panel's own header holds its collapse toggle; its expand toggle shows
-  // only while it is collapsed, so exactly one control owns each action. The
-  // rail's sits in the main header; the drawer's is the drawer's own
-  // `restoreControl`, which the panel floats in its container's bottom-end
-  // corner. wireSidebar hands focus between them.
   const main = () => (
     <Pane
       element="main"
@@ -159,11 +136,12 @@ export const createRecipe: RecipeFactory = (announce) => {
           dividerSides=""
           leading={
             <>
-              {railCollapsed.value ? (
-                <ToolbarControlGroup appearance="borderless" single>
-                  {railToggle()}
-                </ToolbarControlGroup>
-              ) : null}
+              <CollapsiblePanelRelocated
+                panelId="sidebar-rail"
+                side="left"
+                collapsed={railCollapsed.value}
+                toolbar={railToolbar}
+              />
               <ToolbarText
                 text={labels[selected.value] ?? 'Inbox'}
                 size="xlarge"
@@ -195,39 +173,30 @@ export const createRecipe: RecipeFactory = (announce) => {
       size={168}
       collapsed={drawerCollapsed.value}
       label="Activity"
+      toolbar={drawerToolbar}
       restoreControl={
         <FloatingToolbar label="Activity drawer">
-          <ToolbarControlGroup single>{drawerToggle()}</ToolbarControlGroup>
+          <CollapsiblePanelRelocated
+            panelId="sidebar-console"
+            side="bottom"
+            collapsed={drawerCollapsed.value}
+            toolbar={drawerToolbar}
+          />
         </FloatingToolbar>
       }
     >
-      <Pane
-        header={
-          <Toolbar
-            label="Activity"
-            dividerSides=""
-            leading={<ToolbarText text="Activity" size="small" />}
-            trailing={
-              <ToolbarControlGroup appearance="borderless" single>
-                {drawerToggle()}
-              </ToolbarControlGroup>
-            }
-          />
-        }
-      >
-        <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>
+      <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>
   );