@kerfjs/ui 5.0.0-beta.8 → 5.0.0-beta.80

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

@@ -1,43 +1,164 @@
 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 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 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 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><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>
-  </section>;
+  const device = deviceClass();
+  const render = () => (
+    <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>
+          }
+          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 {
     render,
     action(command, element) {
       const value = element.dataset.segmentValue;
       if (value) view.value = value;
       if (command === 'filter') filtered.value = !filtered.value;
-      announce(value ? `View: ${value}` : command === 'filter' ? `Filters ${filtered.value ? 'on' : 'off'}` : `${command} requested`);
+      announce(
+        value
+          ? `View: ${value}`
+          : command === 'filter'
+            ? `Filters ${filtered.value ? 'on' : 'off'}`
+            : `${command} requested`,
+      );
     },
     change(element) {
       const value = (element as HTMLElement & { value?: string }).value;
-      if (element.getAttribute('name') === 'recipe-sort' && value) { sort.value = value; announce(`Sort: ${value}`); }
+      if (element.getAttribute('name') === 'recipe-sort' && value) {
+        sort.value = value;
+        announce(`Sort: ${value}`);
+      }
     },
   };
 };

package/ux-demo/recipes/composer-form.tsx

@@ -4,19 +4,40 @@ import '@kerfjs/ui/webawesome.css';
 import '@awesome.me/webawesome/dist/components/button/button.js';
 import '@awesome.me/webawesome/dist/components/input/input.js';
 import '@awesome.me/webawesome/dist/components/textarea/textarea.js';
-import './recipes.css';
 
-import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { Spacer } from '@kerfjs/ui';
+import { List } from '@kerfjs/ui/list';
+import { ListInsetText } from '@kerfjs/ui/list-inset-text';
+import { Row } from '@kerfjs/ui/row';
 import { Select } from '@kerfjs/ui/select';
 import { StateBanner } from '@kerfjs/ui/state-banner';
+import { Text } from '@kerfjs/ui/text';
+import { Toolbar } from '@kerfjs/ui/toolbar';
+import { ToolbarText } from '@kerfjs/ui/toolbar-text';
 import { signal } from 'kerfjs';
 
-import type { RecipeFactory } from './types.js';
+import type { RecipeFactory, RecipePresentation } from './types.js';
+
+export const presentation: RecipePresentation = {
+  viewport: {
+    width: 'medium',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: 'The recipe owns field, message, and action rhythm. The app owns validation rules, draft persistence, permissions, and transport.',
+};
 
 type ValueField = HTMLElement & { value: string };
 
-const syncControlledFieldValues = (action: HTMLElement, values: Record<string, string>) => {
-  const form = action.closest<HTMLElement>('[data-recipe="recipe-composer-form"]');
+const syncControlledFieldValues = (
+  action: HTMLElement,
+  values: Record<string, string>,
+) => {
+  const form = action.closest<HTMLElement>(
+    '[data-recipe="recipe-composer-form"]',
+  );
   if (!form) return;
   for (const [name, value] of Object.entries(values)) {
     const field = form.querySelector<ValueField>(`[name="${name}"]`);
@@ -26,20 +47,101 @@ const syncControlledFieldValues = (action: HTMLElement, values: Record<string, s
 
 export const createRecipe: RecipeFactory = (announce) => {
   const title = signal('');
-  const body = signal('The tablet layout now keeps navigation, content, and inspector focus order aligned.');
+  const body = signal(
+    'The tablet layout now keeps navigation, content, and inspector focus order aligned.',
+  );
   const audience = signal('team');
   const status = signal<'idle' | 'error' | 'saved'>('idle');
-  const render = () => <form class="kui-recipe recipe-form kui-recipe__surface kui-content" data-recipe="recipe-composer-form" aria-labelledby="recipe-composer-title" aria-describedby="recipe-composer-summary" noValidate>
-    <PanelHeader title="Publish workspace update" titleId="recipe-composer-title" summary="Share a concise, actionable update with collaborators." summaryId="recipe-composer-summary" />
-    {status.value === 'error' && <StateBanner title="Add a title before publishing" detail="The update body and audience are preserved." tone="danger" urgency="alert" />}
-    {status.value === 'saved' && <StateBanner title="Update published" detail="The team audience can now read it." tone="success" />}
-    <div class="recipe-form__section recipe-form__fields">
-      <wa-input name="recipe-title" label="Update title" hint="Summarize the outcome in one line." required value={title.value}></wa-input>
-      <wa-textarea name="recipe-body" label="Details" hint="Include decisions, owners, and the next checkpoint." rows="5" maxlength="400" with-count value={body.value}></wa-textarea>
-      <Select name="recipe-audience" value={audience.value} label="Audience" choices={[{ value: 'team', label: 'Workspace team' }, { value: 'reviewers', label: 'Reviewers' }, { value: 'organization', label: 'Entire organization' }]} />
-    </div>
-    <footer class="recipe-form__section recipe-form__footer"><div class="recipe-form__actions kui-control-cluster"><wa-button appearance="outlined" data-action="recipe-action" data-recipe-command="reset">Reset</wa-button><wa-button variant="brand" appearance="accent" data-action="recipe-action" data-recipe-command="submit">Publish update</wa-button></div><p class="kui-recipe__ownership">The recipe owns field, message, and action rhythm. The app owns validation rules, draft persistence, permissions, and transport.</p></footer>
-  </form>;
+  const render = () => (
+    <form
+      data-recipe="recipe-composer-form"
+      aria-labelledby="recipe-composer-title"
+      aria-describedby="recipe-composer-summary"
+      noValidate
+    >
+      <List gap="l" controlInsets="tb">
+        {/* The title and its supporting line are one heading unit. */}
+        <List>
+          <Toolbar
+            label="Publish workspace update"
+            leading={
+              <ToolbarText
+                text="Publish workspace update"
+                size="xlarge"
+                id="recipe-composer-title"
+              />
+            }
+          />
+          <ListInsetText sides="rl">
+            <Text variant="span" tone="quiet" id="recipe-composer-summary">
+              Share a concise, actionable update with collaborators.
+            </Text>
+          </ListInsetText>
+        </List>
+        {status.value === 'error' && (
+          <StateBanner
+            title="Add a title before publishing"
+            detail="The update body and audience are preserved."
+            tone="danger"
+            urgency="alert"
+          />
+        )}
+        {status.value === 'saved' && (
+          <StateBanner
+            title="Update published"
+            detail="The team audience can now read it."
+            tone="success"
+          />
+        )}
+        <List gap="xs" controlInsets="rl">
+          <wa-input
+            name="recipe-title"
+            label="Update title"
+            hint="Summarize the outcome in one line."
+            required
+            value={title.value}
+          />
+          <wa-textarea
+            name="recipe-body"
+            label="Details"
+            hint="Include decisions, owners, and the next checkpoint."
+            rows="5"
+            maxlength="400"
+            with-count
+            value={body.value}
+          />
+          <Select<string>
+            name="recipe-audience"
+            value={audience.value}
+            label="Audience"
+            choices={[
+              { value: 'team', label: 'Workspace team' },
+              { value: 'reviewers', label: 'Reviewers' },
+              { value: 'organization', label: 'Entire organization' },
+            ]}
+          />
+        </List>
+        <Row gap="xs" wrap controlInsets="rl">
+          <Spacer flex />
+          <wa-button
+            appearance="outlined"
+            data-action="recipe-action"
+            data-recipe-command="reset"
+          >
+            Reset
+          </wa-button>
+          <wa-button
+            variant="brand"
+            appearance="accent"
+            data-action="recipe-action"
+            data-recipe-command="submit"
+          >
+            Publish update
+          </wa-button>
+        </Row>
+      </List>
+    </form>
+  );
   return {
     render,
     action(command, element) {
@@ -47,17 +149,27 @@ export const createRecipe: RecipeFactory = (announce) => {
         title.value = '';
         body.value = '';
         status.value = 'idle';
-        syncControlledFieldValues(element, { 'recipe-title': title.value, 'recipe-body': body.value });
+        syncControlledFieldValues(element, {
+          'recipe-title': title.value,
+          'recipe-body': body.value,
+        });
         announce('Draft reset');
         return;
       }
-      if (command === 'submit') { status.value = title.value.trim() ? 'saved' : 'error'; announce(status.value === 'saved' ? 'Update published' : 'Title required'); }
+      if (command === 'submit') {
+        status.value = title.value.trim() ? 'saved' : 'error';
+        announce(
+          status.value === 'saved' ? 'Update published' : 'Title required',
+        );
+      }
     },
     change(element) {
-      const value = (element as HTMLElement & { value?: string | null }).value ?? '';
+      const value =
+        (element as HTMLElement & { value?: string | null }).value ?? '';
       if (element.getAttribute('name') === 'recipe-title') title.value = value;
       if (element.getAttribute('name') === 'recipe-body') body.value = value;
-      if (element.getAttribute('name') === 'recipe-audience') audience.value = value;
+      if (element.getAttribute('name') === 'recipe-audience')
+        audience.value = value;
     },
   };
 };

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

@@ -0,0 +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 { 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 { 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 { ChevronRight, FileText, X } from 'lucide';
+
+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',
+  },
+} 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<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 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 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;
+    },
+  };
+};