@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

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',
@@ -11,11 +11,18 @@ export const recipeIds = [
   'recipe-navigation-stack',
   'recipe-loading-inspector',
   'recipe-collapsible-sidebar',
+  'recipe-media-detail',
 ] 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'),
@@ -26,6 +33,7 @@ export const recipeLoaders: Record<RecipeId, () => Promise<{ createRecipe: Recip
   'recipe-navigation-stack': () => import('./navigation-stack.js'),
   'recipe-loading-inspector': () => import('./loading-inspector.js'),
   'recipe-collapsible-sidebar': () => import('./collapsible-sidebar.js'),
+  'recipe-media-detail': () => import('./media-detail.js'),
 };
 
 export function isRecipeId(value: string): value is RecipeId {

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

@@ -1,20 +1,40 @@
 import '@kerfjs/ui/layout.css';
 import '@kerfjs/ui/select/register';
-import './recipes.css';
 
+import { Row } from '@kerfjs/ui';
+import { em } from '@kerfjs/ui/css-values';
+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 { SegmentedControl } from '@kerfjs/ui/segmented-control';
 import { Select } from '@kerfjs/ui/select';
+import { Skeleton } from '@kerfjs/ui/skeleton';
 import { StateBanner } from '@kerfjs/ui/state-banner';
+import { Text } from '@kerfjs/ui/text';
+import { Toolbar } from '@kerfjs/ui/toolbar';
+import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
+import { ToolbarText } from '@kerfjs/ui/toolbar-text';
 import { ValueTable, ValueTableRow } from '@kerfjs/ui/value-table';
 import { signal } from 'kerfjs';
-import { Columns3, FileText, Inbox, List } from 'lucide';
+import { Columns3, FileText, Inbox, List as ListIcon } from 'lucide';
 
-import type { RecipeFactory } from './types.js';
+import type { RecipeFactory, RecipePresentation } from './types.js';
 
-const icon = (node: Parameters<typeof LucideIcon>[0]['icon'], name: string) => <LucideIcon icon={node} name={name} />;
+export const presentation: RecipePresentation = {
+  viewport: {
+    width: 'medium',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: "Each value-bearing component's placeholder 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.",
+};
+
+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
@@ -27,47 +47,150 @@ 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">
+    return (
+      <Pane
+        element="section"
+        label="Ticket Inspector"
+        rootAttributes={{
+          'data-recipe': 'recipe-loading-inspector',
+          'data-inspector-loading': String(p),
+        }}
+        header={
+          <>
+            <Toolbar
+              label="Ticket Inspector"
+              responsive="wrap"
+              leading={
+                <>
+                  <ToolbarControlGroup appearance="borderless" single>
+                    {icon(FileText, 'file-text')}
+                  </ToolbarControlGroup>
+                  <ToolbarText
+                    text="Ticket · KF-2048"
+                    size="xlarge"
+                    id="recipe-inspector-title"
+                    placeholder={p}
+                  />
+                </>
+              }
+              trailing={
+                <ToolbarControlGroup
+                  appearance="borderless"
+                  content="text"
+                  single
+                >
+                  <button
+                    type="button"
+                    data-action="recipe-action"
+                    data-recipe-command="toggle"
+                  >
+                    {p ? 'Show Loaded' : 'Show Loading'}
+                  </button>
+                </ToolbarControlGroup>
+              }
+            />
+            <Row controlInsets="trbl">
+              <Text tone="quiet" id="recipe-inspector-summary">
+                {p ? (
+                  <Skeleton width={em(18)} />
+                ) : (
+                  'Restore keyboard focus after a dialog closes'
+                )}
+              </Text>
+            </Row>
+          </>
+        }
+      >
         <section>
-          <ValueTable label="Ticket details">
-            <ValueTableRow label="Status" value="In review" icon={icon(Inbox, 'inbox')} placeholder={p} />
+          <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} />
+            <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>
+        <List gap="xs" controlInsets="rl">
+          <Select
+            name="recipe-inspector-status"
+            value="review"
+            label="Status"
+            hint="Where this ticket sits in the review workflow."
+            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(ListIcon, 'list'),
+              },
+              {
+                value: 'activity',
+                label: 'Activity',
+                content: icon(Columns3, 'columns-3'),
+              },
+              {
+                value: 'files',
+                label: 'Files',
+                content: icon(FileText, 'file-text'),
+              },
+            ]}
+          />
+        </List>
         <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} />
+          <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>;
+        {p ? (
+          <StateBanner
+            tone="info"
+            title="Up to Date"
+            detail="All checks passed on the latest revision."
+            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')}
+          />
+        )}
+      </Pane>
+    );
   };
   return {
     render,