@kerfjs/ui 5.0.0-beta.9 → 5.0.0-beta.90

package/ux-demo/recipes/list-detail-dialog.tsx

@@ -1,45 +1,286 @@
+import '@kerfjs/ui/surface-scaffold/register';
 import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/nav-stack.css';
+import '@kerfjs/ui/split-view.css';
 import '@kerfjs/ui/webawesome.css';
 import '@awesome.me/webawesome/dist/components/button/button.js';
 import '@awesome.me/webawesome/dist/components/dialog/dialog.js';
-import './recipes.css';
 
-import { ListHeader } from '@kerfjs/ui/list-header';
+import { remify } from '@kerfjs/ui/css-values';
+import { deviceClass } from '@kerfjs/ui/device-class';
+import { List } from '@kerfjs/ui/list';
 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 { Spacer } from '@kerfjs/ui/spacer';
+import { SplitView } from '@kerfjs/ui/split-view';
+import { DialogSurface } from '@kerfjs/ui/surface-scaffold';
+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 { FileText } from 'lucide';
+import { ChevronRight, FileText, X } from 'lucide';
 
-import type { RecipeFactory } from './types.js';
+import type { RecipeFactory, RecipePresentation } from './types.js';
 
 const records = {
-  alpha: { name: 'Northstar migration', owner: 'Mara Chen', state: 'In review', updated: 'Today, 09:42' },
-  beta: { name: 'Tablet navigation', owner: 'Sam Rivera', state: 'Ready', updated: 'Yesterday, 16:20' },
-  gamma: { name: 'Contrast audit', owner: 'Inez Okafor', state: 'Blocked', updated: 'Monday, 11:05' },
+  alpha: {
+    name: 'Northstar migration',
+    owner: 'Mara Chen',
+    state: 'In review',
+    updated: 'Today, 09:42',
+  },
+  beta: {
+    name: 'Tablet navigation',
+    owner: 'Sam Rivera',
+    state: 'Ready',
+    updated: 'Yesterday, 16:20',
+  },
+  gamma: {
+    name: 'Contrast audit',
+    owner: 'Inez Okafor',
+    state: 'Blocked',
+    updated: 'Monday, 11:05',
+  },
 } as const;
 
+type RecordId = keyof typeof records;
+
 interface RecipeDialogElement extends HTMLElement {
   open: boolean;
 }
 
+export const presentation: RecipePresentation = {
+  viewport: { layout: 'grid', width: 'full' },
+  note: 'On roomy devices the dialog body is a workbench: a full-height list sidebar with its own toolbar beside a full-height detail column that carries the primary title, close control, and record actions. Compact devices get a full-screen sheet that drills from the list into the detail. Web Awesome owns modal focus and Escape; DialogSurface owns dialog geometry; SplitView owns the panes and the compact drill-down. The app owns open state, selection, and record actions.',
+};
+
 export const createRecipe: RecipeFactory = (announce) => {
-  const selected = signal<keyof typeof records>('alpha');
+  const selected = signal<RecordId>('alpha');
+  // Compact devices drill from the list into the detail; this flag is the
+  // pushed detail view. Roomy devices show both panes side by side.
+  const detailOpen = signal(false);
   const open = { value: false };
-  const render = () => <section class="kui-recipe kui-content" data-recipe="recipe-list-detail-dialog"><button class="kui-recipe__button kui-content-item" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="open">Open project details</button><p class="kui-recipe__ownership kui-content-item">Web Awesome owns modal focus and dismissal. The recipe owns header/body/list-detail anatomy; the app owns open state, selection, and policy.</p><wa-dialog class="recipe-dialog" label="Project details" without-header open={open.value}><div class="recipe-dialog__pane kui-pane"><div class="recipe-list-detail kui-pane__content"><nav class="recipe-list-detail__list kui-pane" aria-label="Projects"><ListHeader label="Recent projects" /><div class="kui-pane__content kui-content"><section>{Object.entries(records).map(([id, record]) => <ListItem action="recipe-action" itemId={id} label={record.name} selected={selected.value === id} multiline />)}</section></div></nav><section class="recipe-list-detail__detail kui-pane"><PanelHeader title="Project details" titleId="recipe-dialog-title" summary="Compare delivery state without leaving the workspace." summaryId="recipe-dialog-summary" icon={<LucideIcon icon={FileText} name="file-text" />} actions={<wa-button appearance="plain" data-action="recipe-action" data-recipe-command="close">Close</wa-button>} /><div class="recipe-list-detail__body kui-pane__content kui-content" aria-live="polite"><h3 class="recipe-list-detail__title kui-recipe__pane-title kui-content-item">{records[selected.value].name}</h3><ValueTable label="Project details"><ValueTableRow label="Owner" value={records[selected.value].owner} /><ValueTableRow label="Status" value={records[selected.value].state} /><ValueTableRow label="Updated" value={records[selected.value].updated} /></ValueTable><div class="recipe-list-detail__actions kui-control-cluster"><wa-button appearance="outlined" data-action="recipe-action" data-recipe-command="archive">Archive</wa-button><wa-button variant="brand" appearance="accent" data-action="recipe-action" data-recipe-command="open-record">Open project</wa-button></div></div></section></div></div></wa-dialog></section>;
+  const device = deviceClass();
+
+  const projectRows = (compact: boolean) => (
+    <section aria-label="Projects">
+      {Object.entries(records).map(([id, record]) => (
+        <ListItem
+          action="recipe-action"
+          itemId={id}
+          label={record.name}
+          description={`${record.owner} · ${record.state}`}
+          icon={<LucideIcon icon={FileText} name="file-text" />}
+          trailing={
+            compact ? (
+              <LucideIcon icon={ChevronRight} name="chevron-right" />
+            ) : undefined
+          }
+          selected={!compact && selected.value === id}
+          multiline
+        />
+      ))}
+    </section>
+  );
+
+  const recordActions = () => (
+    <Row gap="xs" wrap controlInsets="trbl">
+      <Spacer flex />
+      <wa-button
+        appearance="outlined"
+        data-action="recipe-action"
+        data-recipe-command="archive"
+      >
+        Archive
+      </wa-button>
+      <wa-button
+        variant="brand"
+        appearance="accent"
+        data-action="recipe-action"
+        data-recipe-command="open-record"
+      >
+        Open project
+      </wa-button>
+    </Row>
+  );
+
+  // Roomy: a workbench. The list is a full-height sidebar with its own top
+  // toolbar; the detail column carries the dialog's primary title, the close
+  // control, and the record actions, and runs the full dialog height too.
+  const sidebar = () => (
+    <Pane
+      label="Recent projects"
+      header={
+        <Toolbar
+          label="Recent projects"
+          leading={<ToolbarText text="Recent projects" />}
+        />
+      }
+    >
+      <List controlInsets="tb">{projectRows(false)}</List>
+    </Pane>
+  );
+
+  const detailColumn = () => {
+    const record = records[selected.value];
+    return (
+      <Pane
+        label={record.name}
+        header={
+          <Toolbar
+            label="Project details"
+            leading={
+              <ToolbarText
+                text={record.name}
+                size="xlarge"
+                id="recipe-project-title"
+                headingLevel={2}
+              />
+            }
+            trailing={
+              <ToolbarControlGroup appearance="borderless" single>
+                <button type="button" aria-label="Close" data-dialog="close">
+                  <LucideIcon icon={X} name="x" />
+                </button>
+              </ToolbarControlGroup>
+            }
+          />
+        }
+        footer={recordActions()}
+      >
+        <List controlInsets="tb">
+          <ValueTable label="Project details">
+            <ValueTableRow label="Owner" value={record.owner} />
+            <ValueTableRow label="Status" value={record.state} />
+            <ValueTableRow label="Updated" value={record.updated} />
+          </ValueTable>
+        </List>
+      </Pane>
+    );
+  };
+
+  const compactDetail = () => {
+    const record = records[selected.value];
+    return (
+      <List>
+        <ValueTable label="Project details">
+          <ValueTableRow label="Owner" value={record.owner} />
+          <ValueTableRow label="Status" value={record.state} />
+          <ValueTableRow label="Updated" value={record.updated} />
+        </ValueTable>
+      </List>
+    );
+  };
+
+  const render = () => {
+    const compact = device.value.compact;
+    return (
+      <section
+        data-recipe="recipe-list-detail-dialog"
+        aria-label="Project details dialog"
+      >
+        <Row hAlign="center">
+          <DialogSurface
+            size="large"
+            presentation={compact ? 'fullscreen' : 'modal'}
+            viewportGutter={remify(16)}
+            maxHeight="viewport"
+            bodyInset="none"
+            footerInset="comfortable"
+          >
+            <wa-button
+              variant="brand"
+              appearance="accent"
+              data-action="recipe-action"
+              data-recipe-command="open"
+            >
+              Open project details
+            </wa-button>
+            {compact ? (
+              <wa-dialog label="Project details" open={open.value} with-footer>
+                <SplitView
+                  id="recipe-projects"
+                  label="Projects"
+                  compact
+                  detailActive={detailOpen.value}
+                  listTitle="Recent projects"
+                  detailTitle={records[selected.value].name}
+                  backLabel="Back to projects"
+                  list={<List>{projectRows(true)}</List>}
+                  detail={compactDetail()}
+                />
+                <wa-button
+                  slot="footer"
+                  appearance="outlined"
+                  data-action="recipe-action"
+                  data-recipe-command="archive"
+                >
+                  Archive
+                </wa-button>
+                <wa-button
+                  slot="footer"
+                  variant="brand"
+                  appearance="accent"
+                  data-action="recipe-action"
+                  data-recipe-command="open-record"
+                >
+                  Open project
+                </wa-button>
+              </wa-dialog>
+            ) : (
+              <wa-dialog
+                label="Project details"
+                open={open.value}
+                without-header
+              >
+                <SplitView
+                  id="recipe-projects"
+                  label="Projects"
+                  compact={false}
+                  listTitle="Recent projects"
+                  detailTitle={records[selected.value].name}
+                  list={sidebar()}
+                  detail={detailColumn()}
+                />
+              </wa-dialog>
+            )}
+          </DialogSurface>
+        </Row>
+      </section>
+    );
+  };
   return {
     render,
     action(command, element) {
+      if (command === 'nav-back') {
+        detailOpen.value = false;
+        announce('Back to projects');
+        return;
+      }
       const id = element.dataset.itemId;
-      if (id && id in records) { selected.value = id as keyof typeof records; announce(`Selected ${records[selected.value].name}`); return; }
-      const dialog = element.closest('[data-recipe]')?.querySelector<RecipeDialogElement>('wa-dialog');
-      if (command === 'open' && dialog) { element.focus(); open.value = true; dialog.open = true; return; }
-      if (command === 'close' && dialog) { dialog.open = false; return; }
+      if (id && id in records) {
+        selected.value = id as RecordId;
+        detailOpen.value = true;
+        announce(`Selected ${records[selected.value].name}`);
+        return;
+      }
+      const dialog = element
+        .closest('[data-recipe]')
+        ?.querySelector<RecipeDialogElement>('wa-dialog');
+      if (command === 'open' && dialog) {
+        element.focus();
+        open.value = true;
+        dialog.open = true;
+        return;
+      }
       announce(`${command} requested`);
     },
     afterHide() {
       open.value = false;
+      detailOpen.value = false;
     },
   };
 };

package/ux-demo/recipes/list-workspace-states.tsx

@@ -1,26 +1,198 @@
 import '@kerfjs/ui/layout.css';
-import './recipes.css';
 
 import { EmptyState } from '@kerfjs/ui/empty-state';
+import { ListItem } from '@kerfjs/ui/list-item';
 import { LoadingSpinner } from '@kerfjs/ui/loading-spinner';
-import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { Pane } from '@kerfjs/ui/pane';
+import { Row } from '@kerfjs/ui/row';
 import { StateBanner } from '@kerfjs/ui/state-banner';
+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 type { RecipeFactory } from './types.js';
+import type { RecipeFactory, RecipePresentation } from './types.js';
 
 type ListState = 'loading' | 'empty' | 'populated' | 'stale' | 'error';
-const items = ['Audit keyboard focus order', 'Verify 200% zoom layout', 'Publish package migration notes'];
+const items = [
+  ['Audit keyboard focus order', 'In review · Mara'],
+  ['Verify 200% zoom layout', 'Ready · Sam'],
+  ['Publish package migration notes', 'Draft · Inez'],
+] as const;
+
+export const presentation: RecipePresentation = {
+  viewport: {
+    layout: 'grid',
+    width: 'full',
+    minHeight: 'medium',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: 'The recipe owns feedback placement and stable content. The app owns fetching, cache age, retry policy, and domain rows.',
+};
 
 export const createRecipe: RecipeFactory = (announce) => {
   const state = signal<ListState>('loading');
-  const populated = () => <ul class="recipe-list__items" aria-label="Release tasks">{items.map((item, index) => <li><strong>{item}</strong><span class="kui-recipe__muted">{index === 0 ? 'In review · Mara' : index === 1 ? 'Ready · Sam' : 'Draft · Inez'}</span></li>)}</ul>;
+  const populated = () => (
+    <section aria-label="Release task list">
+      {items.map(([title, detail]) => (
+        <ListItem
+          action="recipe-action"
+          label={title}
+          description={detail}
+          rootAttributes={{ 'data-recipe-command': 'open-task' }}
+        />
+      ))}
+    </section>
+  );
   const renderBody = () => {
-    if (state.value === 'loading') return <EmptyState title="Loading release tasks" detail="The current workspace will appear when data is ready." busy action={<button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="load">Complete load</button>} />;
-    if (state.value === 'empty') return <EmptyState title="No release tasks" detail="Create the first task for this milestone." action={<button class="kui-recipe__button" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="create">Create task</button>} />;
-    if (state.value === 'error') return <StateBanner title="Release tasks could not be refreshed" detail="Existing filters are preserved. Try again when the connection recovers." tone="danger" urgency="alert" action={<button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="retry">Retry</button>} />;
-    return <>{state.value === 'stale' && <StateBanner title="Showing saved results" detail="Refreshing in the background." tone="warning" action={<span class="kui-inline-metadata"><LoadingSpinner label="Refreshing release tasks" /><button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="finish">Finish refresh</button></span>} />}{populated()}</>;
+    if (state.value === 'loading')
+      return (
+        <EmptyState
+          title="Loading release tasks"
+          detail="The current workspace will appear when data is ready."
+          busy
+          action={
+            <button
+              type="button"
+              data-action="recipe-action"
+              data-recipe-command="load"
+            >
+              Complete load
+            </button>
+          }
+        />
+      );
+    if (state.value === 'empty')
+      return (
+        <EmptyState
+          title="No release tasks"
+          detail="Create the first task for this milestone."
+          action={
+            <button
+              type="button"
+              data-action="recipe-action"
+              data-recipe-command="create"
+            >
+              Create task
+            </button>
+          }
+        />
+      );
+    if (state.value === 'error')
+      return (
+        <StateBanner
+          title="Release tasks could not be refreshed"
+          detail="Existing filters are preserved. Try again when the connection recovers."
+          tone="danger"
+          urgency="alert"
+          action={
+            <button
+              type="button"
+              data-action="recipe-action"
+              data-recipe-command="retry"
+            >
+              Retry
+            </button>
+          }
+        />
+      );
+    return (
+      <>
+        {state.value === 'stale' && (
+          <StateBanner
+            title="Showing saved results"
+            detail="Refreshing in the background."
+            tone="warning"
+            action={
+              <Row gap="xs" vAlign="middle">
+                <LoadingSpinner label="Refreshing release tasks" />
+                <button
+                  type="button"
+                  data-action="recipe-action"
+                  data-recipe-command="finish"
+                >
+                  Finish refresh
+                </button>
+              </Row>
+            }
+          />
+        )}
+        {populated()}
+      </>
+    );
+  };
+  const render = () => (
+    <Pane
+      element="section"
+      label="Release tasks"
+      rootAttributes={{
+        'data-recipe': 'recipe-list-workspace-states',
+        'data-list-state': state.value,
+      }}
+      header={
+        <Toolbar
+          label="Release tasks"
+          responsive="stack"
+          responsiveAt="compact"
+          leading={
+            <ToolbarText
+              text="Release tasks"
+              size="xlarge"
+              id="recipe-list-title"
+            />
+          }
+          trailing={
+            <ToolbarControlGroup
+              appearance="borderless"
+              content="text"
+              buttonAppearance="push"
+            >
+              <button
+                type="button"
+                data-action="recipe-action"
+                data-recipe-command="empty"
+              >
+                Clear
+              </button>
+              <button
+                type="button"
+                data-action="recipe-action"
+                data-recipe-command="fail"
+              >
+                Simulate failure
+              </button>
+              <button
+                type="button"
+                data-action="recipe-action"
+                data-recipe-command="refresh"
+              >
+                Refresh
+              </button>
+            </ToolbarControlGroup>
+          }
+        />
+      }
+    >
+      {renderBody()}
+    </Pane>
+  );
+  return {
+    render,
+    action(command) {
+      const next: Record<string, ListState> = {
+        load: 'populated',
+        empty: 'empty',
+        create: 'populated',
+        fail: 'error',
+        retry: 'populated',
+        refresh: 'stale',
+        finish: 'populated',
+      };
+      if (command in next) state.value = next[command]!;
+      announce(`List state: ${state.value}`);
+    },
   };
-  const render = () => <section class="kui-recipe recipe-list kui-recipe__surface kui-pane" data-recipe="recipe-list-workspace-states" data-list-state={state.value}><PanelHeader title="Release tasks" titleId="recipe-list-title" actions={<div class="kui-control-cluster"><button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="empty">Clear</button><button class="kui-recipe__button" type="button" data-action="recipe-action" data-recipe-command="fail">Simulate failure</button><button class="kui-recipe__button" data-primary="true" type="button" data-action="recipe-action" data-recipe-command="refresh">Refresh</button></div>} /><div class="recipe-list__body kui-pane__content kui-content">{renderBody()}<p class="kui-recipe__ownership kui-content-item">The recipe owns feedback placement and stable content. The app owns fetching, cache age, retry policy, and domain rows.</p></div></section>;
-  return { render, action(command) { const next: Record<string, ListState> = { load: 'populated', empty: 'empty', create: 'populated', fail: 'error', retry: 'populated', refresh: 'stale', finish: 'populated' }; if (command in next) state.value = next[command]!; announce(`List state: ${state.value}`); } };
 };

package/ux-demo/recipes/loaders.ts

@@ -1,4 +1,4 @@
-import type { RecipeFactory } from './types.js';
+import type { RecipeFactory, RecipePresentation } from './types.js';
 
 export const recipeIds = [
   'recipe-app-shell',
@@ -10,11 +10,18 @@ export const recipeIds = [
   'recipe-compact-toolbar',
   'recipe-navigation-stack',
   'recipe-loading-inspector',
+  'recipe-collapsible-sidebar',
 ] as const;
 
-export type RecipeId = typeof recipeIds[number];
+export type RecipeId = (typeof recipeIds)[number];
 
-export const recipeLoaders: Record<RecipeId, () => Promise<{ createRecipe: RecipeFactory }>> = {
+export const recipeLoaders: Record<
+  RecipeId,
+  () => Promise<{
+    createRecipe: RecipeFactory;
+    presentation: RecipePresentation;
+  }>
+> = {
   'recipe-app-shell': () => import('./app-shell.js'),
   'recipe-navigation-sidebar': () => import('./navigation-sidebar.js'),
   'recipe-workspace-header': () => import('./workspace-header.js'),
@@ -24,6 +31,7 @@ export const recipeLoaders: Record<RecipeId, () => Promise<{ createRecipe: Recip
   'recipe-compact-toolbar': () => import('./compact-toolbar.js'),
   'recipe-navigation-stack': () => import('./navigation-stack.js'),
   'recipe-loading-inspector': () => import('./loading-inspector.js'),
+  'recipe-collapsible-sidebar': () => import('./collapsible-sidebar.js'),
 };
 
 export function isRecipeId(value: string): value is RecipeId {