@kerfjs/ui 4.4.1 → 4.5.0-beta.1

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

@@ -0,0 +1,223 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/collapsible-panel.css';
+import './recipes.css';
+
+import {
+  CollapsiblePanel,
+  CollapsiblePanelToggle,
+} from '@kerfjs/ui/collapsible-panel';
+import { deviceClass } from '@kerfjs/ui/device-class';
+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 { Toolbar } from '@kerfjs/ui/toolbar';
+import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
+import { ToolbarText } from '@kerfjs/ui/toolbar-text';
+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';
+
+const RAIL_ACTION = 'recipe-sidebar-rail';
+const DRAWER_ACTION = 'recipe-sidebar-drawer';
+
+/**
+ * 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);
+    },
+  };
+}
+
+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();
+
+  const railToggle = (inPanel: boolean) => (
+    <CollapsiblePanelToggle
+      side="left"
+      collapsed={railCollapsed.value}
+      action={RAIL_ACTION}
+      panelId="sidebar-rail"
+      label={railCollapsed.value ? 'Show navigation' : 'Hide navigation'}
+      className={inPanel ? '' : 'recipe-collapsible-sidebar__reveal'}
+    />
+  );
+  const drawerToggle = () => (
+    <CollapsiblePanelToggle
+      side="bottom"
+      collapsed={drawerCollapsed.value}
+      action={DRAWER_ACTION}
+      panelId="sidebar-console"
+      label={drawerCollapsed.value ? 'Show activity' : 'Hide activity'}
+    />
+  );
+
+  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)}
+    >
+      <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>
+  );
+
+  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',
+          },
+          {
+            id: 'sidebar-console',
+            collapsed: drawerCollapsed,
+            toggleAction: DRAWER_ACTION,
+            storageKey: 'recipe-sidebar-console',
+          },
+        ],
+      });
+    },
+  };
+};

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

@@ -0,0 +1,145 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/select/register';
+import './recipes.css';
+
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { SegmentedControl } from '@kerfjs/ui/segmented-control';
+import { Select } from '@kerfjs/ui/select';
+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';
+
+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<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>
+            </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>
+  );
+  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`,
+      );
+    },
+    change(element) {
+      const value = (element as HTMLElement & { value?: string }).value;
+      if (element.getAttribute('name') === 'recipe-sort' && value) {
+        sort.value = value;
+        announce(`Sort: ${value}`);
+      }
+    },
+  };
+};

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

@@ -0,0 +1,151 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/select/register';
+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 { Select } from '@kerfjs/ui/select';
+import { StateBanner } from '@kerfjs/ui/state-banner';
+import { signal } from 'kerfjs';
+
+import type { RecipeFactory } from './types.js';
+
+type ValueField = HTMLElement & { value: string };
+
+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}"]`);
+    if (field && field.value !== value) field.value = value;
+  }
+};
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const title = signal('');
+  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<string>
+          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>
+  );
+  return {
+    render,
+    action(command, element) {
+      if (command === 'reset') {
+        title.value = '';
+        body.value = '';
+        status.value = 'idle';
+        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',
+        );
+      }
+    },
+    change(element) {
+      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;
+    },
+  };
+};

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

@@ -0,0 +1,181 @@
+import '@kerfjs/ui/layout.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 { ListItem } from '@kerfjs/ui/list-item';
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { ValueTable, ValueTableRow } from '@kerfjs/ui/value-table';
+import { signal } from 'kerfjs';
+import { FileText } from 'lucide';
+
+import type { RecipeFactory } 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;
+
+interface RecipeDialogElement extends HTMLElement {
+  open: boolean;
+}
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const selected = signal<keyof typeof records>('alpha');
+  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>
+  );
+  return {
+    render,
+    action(command, element) {
+      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;
+      }
+      announce(`${command} requested`);
+    },
+    afterHide() {
+      open.value = false;
+    },
+  };
+};