@kerfjs/ui 4.4.1 → 4.5.0-beta.1

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

@@ -0,0 +1,183 @@
+import '@kerfjs/ui/layout.css';
+import './recipes.css';
+
+import { EmptyState } from '@kerfjs/ui/empty-state';
+import { LoadingSpinner } from '@kerfjs/ui/loading-spinner';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { StateBanner } from '@kerfjs/ui/state-banner';
+import { signal } from 'kerfjs';
+
+import type { RecipeFactory } from './types.js';
+
+type ListState = 'loading' | 'empty' | 'populated' | 'stale' | 'error';
+const items = [
+  'Audit keyboard focus order',
+  'Verify 200% zoom layout',
+  'Publish package migration notes',
+];
+
+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 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()}
+      </>
+    );
+  };
+  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

@@ -0,0 +1,36 @@
+import type { RecipeFactory } from './types.js';
+
+export const recipeIds = [
+  'recipe-app-shell',
+  'recipe-navigation-sidebar',
+  'recipe-workspace-header',
+  'recipe-list-detail-dialog',
+  'recipe-composer-form',
+  'recipe-list-workspace-states',
+  'recipe-compact-toolbar',
+  'recipe-navigation-stack',
+  'recipe-loading-inspector',
+  'recipe-collapsible-sidebar',
+] as const;
+
+export type RecipeId = (typeof recipeIds)[number];
+
+export const recipeLoaders: Record<
+  RecipeId,
+  () => Promise<{ createRecipe: RecipeFactory }>
+> = {
+  'recipe-app-shell': () => import('./app-shell.js'),
+  'recipe-navigation-sidebar': () => import('./navigation-sidebar.js'),
+  'recipe-workspace-header': () => import('./workspace-header.js'),
+  'recipe-list-detail-dialog': () => import('./list-detail-dialog.js'),
+  'recipe-composer-form': () => import('./composer-form.js'),
+  'recipe-list-workspace-states': () => import('./list-workspace-states.js'),
+  '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 {
+  return (recipeIds as readonly string[]).includes(value);
+}

package/ux-demo/recipes/loading-inspector.tsx

@@ -0,0 +1,164 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/select/register';
+import './recipes.css';
+
+import { ListItem } from '@kerfjs/ui/list-item';
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { SegmentedControl } from '@kerfjs/ui/segmented-control';
+import { Select } from '@kerfjs/ui/select';
+import { StateBanner } from '@kerfjs/ui/state-banner';
+import { ValueTable, ValueTableRow } from '@kerfjs/ui/value-table';
+import { signal } from 'kerfjs';
+import { Columns3, FileText, Inbox, List } from 'lucide';
+
+import type { RecipeFactory } from './types.js';
+
+const icon = (node: Parameters<typeof LucideIcon>[0]['icon'], name: string) => (
+  <LucideIcon icon={node} name={name} />
+);
+
+/**
+ * A record inspector whose per-record values load asynchronously. Every
+ * value-bearing component takes `placeholder` from one loading flag, so the same
+ * chrome renders a faithful loading state and then the populated record — no
+ * separate skeleton markup. The composition is the point; `Skeleton` is the
+ * primitive it is built on (see the Skeleton component demo).
+ */
+export const createRecipe: RecipeFactory = (announce) => {
+  const loading = signal(true);
+  const render = () => {
+    const p = loading.value;
+    return (
+      <section
+        class="kui-recipe recipe-inspector kui-recipe__surface kui-pane"
+        data-recipe="recipe-loading-inspector"
+        data-inspector-loading={String(p)}
+      >
+        <PanelHeader
+          title="Ticket · KF-2048"
+          titleId="recipe-inspector-title"
+          summary="Restore keyboard focus after a dialog closes"
+          summaryId="recipe-inspector-summary"
+          icon={icon(FileText, 'file-text')}
+          placeholder={p}
+          actions={
+            <button
+              class="kui-recipe__button"
+              data-primary="true"
+              type="button"
+              data-action="recipe-action"
+              data-recipe-command="toggle"
+            >
+              {p ? 'Show loaded' : 'Show loading'}
+            </button>
+          }
+        />
+        <div class="recipe-inspector__body kui-pane__content kui-content">
+          <section>
+            <ValueTable label="Ticket details">
+              <ValueTableRow
+                label="Status"
+                value="In review"
+                icon={icon(Inbox, 'inbox')}
+                placeholder={p}
+              />
+              <ValueTableRow label="Owner" value="Mara Lopez" placeholder={p} />
+              <ValueTableRow label="Priority" value="High" placeholder={p} />
+              <ValueTableRow
+                label="Updated"
+                value="2 hours ago"
+                placeholder={p}
+              />
+            </ValueTable>
+          </section>
+          <div class="recipe-inspector__controls">
+            <Select
+              name="recipe-inspector-status"
+              value="review"
+              label="Status"
+              placeholder={p}
+              choices={[
+                { value: 'review', label: 'In review' },
+                { value: 'ready', label: 'Ready' },
+                { value: 'done', label: 'Done' },
+              ]}
+            />
+            <SegmentedControl
+              id="recipe-inspector-view"
+              label="Inspector view"
+              value="details"
+              appearance="toolbar"
+              shape="pill"
+              size="small"
+              placeholder={p}
+              choices={[
+                {
+                  value: 'details',
+                  label: 'Details',
+                  content: icon(List, 'list'),
+                },
+                {
+                  value: 'activity',
+                  label: 'Activity',
+                  content: icon(Columns3, 'columns-3'),
+                },
+                {
+                  value: 'files',
+                  label: 'Files',
+                  content: icon(FileText, 'file-text'),
+                },
+              ]}
+            />
+          </div>
+          <section>
+            <ListItem
+              action="recipe-action"
+              itemId="reassign"
+              label="Reassign ticket"
+              icon={icon(Inbox, 'inbox')}
+              placeholder={p}
+            />
+            <ListItem
+              action="recipe-action"
+              itemId="watch"
+              label="Watch for changes"
+              placeholder={p}
+            />
+          </section>
+          {p ? (
+            <StateBanner
+              tone="info"
+              title=""
+              detail=""
+              icon={icon(FileText, 'file-text')}
+              placeholder
+            />
+          ) : (
+            <StateBanner
+              tone="success"
+              title="Up to date"
+              detail="All checks passed on the latest revision."
+              icon={icon(FileText, 'file-text')}
+            />
+          )}
+          <p class="kui-recipe__ownership kui-content-item">
+            Each value-bearing component's <code>placeholder</code> prop renders
+            skeletons in its value slots while loading, so the recipe composes a
+            faithful loading inspector from real chrome. The app owns the
+            loading lifecycle and which values are still unknown.
+          </p>
+        </div>
+      </section>
+    );
+  };
+  return {
+    render,
+    action(command) {
+      if (command === 'toggle') {
+        loading.value = !loading.value;
+        announce(loading.value ? 'Inspector is loading' : 'Inspector loaded');
+      }
+    },
+  };
+};

package/ux-demo/recipes/mount-recipe.ts

@@ -0,0 +1,64 @@
+import { wireNavStack } from '@kerfjs/ui/wire-nav-stack';
+import { wireResizableRegions } from '@kerfjs/ui/wire-resizable-regions';
+import { delegate, mount } from 'kerfjs';
+import { delegateActions } from 'kerfjs/actions';
+
+import type { RecipeController } from './types.js';
+
+/**
+ * Copyable application boundary for a recipe. The caller owns one stable root
+ * and retains the returned disposer for that root's lifetime.
+ */
+export function mountRecipe(
+  root: HTMLElement,
+  controller: RecipeController,
+): () => void {
+  const stopMount = mount(root, controller.render);
+  const stopActions = delegateActions(root, 'click', {
+    'recipe-action': (_event, element) => {
+      const target = element as HTMLElement;
+      controller.action(target.dataset.recipeCommand ?? '', target);
+    },
+  });
+  const dispatchChange = (_event: Event, element: Element) =>
+    controller.change?.(element as HTMLElement);
+  const stopChanges = delegate(
+    root,
+    'change',
+    'wa-select, wa-input, wa-textarea',
+    dispatchChange,
+  );
+  const stopInputs = delegate(
+    root,
+    'input',
+    'wa-input, wa-textarea',
+    dispatchChange,
+  );
+  const stopDialogs = delegate(
+    root,
+    'wa-after-hide',
+    'wa-dialog',
+    (_event, element) => controller.afterHide?.(element as HTMLElement),
+  );
+  const stopResize = wireResizableRegions(root, {
+    onCommit: ({ id, size }) => controller.resize?.(id, size),
+  });
+  const stopNav = wireNavStack(root, {
+    onBack: () => controller.action('nav-back', root),
+  });
+  const stopWire = controller.wire?.(root);
+
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    stopWire?.();
+    stopNav();
+    stopResize();
+    stopDialogs();
+    stopInputs();
+    stopChanges();
+    stopActions();
+    stopMount();
+  };
+}

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

@@ -0,0 +1,137 @@
+import '@kerfjs/ui/layout.css';
+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 { Toolbar } from '@kerfjs/ui/toolbar';
+import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
+import { signal } from 'kerfjs';
+import { Folder, Inbox, Plus, Settings, Users } from 'lucide';
+
+import type { RecipeFactory } from './types.js';
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const selected = signal('inbox');
+  const expanded = signal(true);
+  const render = () => (
+    <aside
+      class="kui-recipe recipe-sidebar kui-recipe__surface kui-pane"
+      data-recipe="recipe-navigation-sidebar"
+    >
+      <div class="recipe-sidebar__body kui-pane__content kui-content">
+        <section>
+          <ListHeader
+            label="Workspace"
+            count={3}
+            countLabel="3 workspaces"
+            action="recipe-action"
+            actionLabel="Add workspace item"
+            actionIcon={<LucideIcon icon={Plus} name="plus" />}
+          />
+          <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="shared"
+            label="Shared with me"
+            icon={<LucideIcon icon={Users} name="users" />}
+            selected={selected.value === 'shared'}
+          />
+          <ListItem
+            action="recipe-action"
+            itemId="drafts"
+            label="Drafts without an icon"
+            selected={selected.value === 'drafts'}
+          />
+        </section>
+        <section>
+          <ListHeader
+            label="Projects"
+            toggle
+            action="recipe-action"
+            expanded={expanded.value}
+          />
+          {expanded.value && (
+            <>
+              <ListItem
+                action="recipe-action"
+                itemId="design"
+                label="Design system rollout across desktop and tablet"
+                icon={<LucideIcon icon={Folder} name="folder" />}
+                selected={selected.value === 'design'}
+                multiline
+              />
+              <ListItem
+                action="recipe-action"
+                itemId="archive"
+                label="Archived"
+                disabled
+                title="Available to administrators"
+              />
+              <div class="kui-content-item">
+                <strong>Quarterly goal</strong>
+                <p class="kui-recipe__muted">
+                  Ship accessible navigation patterns to every workspace.
+                </p>
+              </div>
+            </>
+          )}
+        </section>
+        <p class="kui-recipe__ownership kui-content-item">
+          The recipe owns pane, content-item, and toolbar geometry. The app owns
+          routes, permissions, labels, and disclosure state.
+        </p>
+      </div>
+      <footer class="recipe-sidebar__footer kui-pane__footer">
+        <Toolbar
+          label="Sidebar actions"
+          dividerSides=""
+          leading={
+            <ToolbarControlGroup appearance="borderless" single>
+              <button
+                type="button"
+                aria-label="Add project"
+                data-action="recipe-action"
+                data-recipe-command="add"
+              >
+                <LucideIcon icon={Plus} name="plus" />
+              </button>
+            </ToolbarControlGroup>
+          }
+          trailing={
+            <ToolbarControlGroup appearance="borderless" single>
+              <button
+                type="button"
+                aria-label="Workspace settings"
+                data-action="recipe-action"
+                data-recipe-command="settings"
+              >
+                <LucideIcon icon={Settings} name="settings" />
+              </button>
+            </ToolbarControlGroup>
+          }
+        />
+      </footer>
+    </aside>
+  );
+  return {
+    render,
+    action(command, element) {
+      if (element.matches('.kui-list-header__toggle')) {
+        expanded.value = !expanded.value;
+        announce(expanded.value ? 'Projects expanded' : 'Projects collapsed');
+        return;
+      }
+      const id = element.dataset.itemId;
+      if (id) selected.value = id;
+      announce(id ? `Selected ${id}` : `${command} requested`);
+    },
+  };
+};