@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.101

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,

package/ux-demo/recipes/media-detail.tsx

@@ -0,0 +1,272 @@
+import '@kerfjs/ui/layout.css';
+import '@kerfjs/ui/nav-stack.css';
+import '@kerfjs/ui/pane.css';
+import '@kerfjs/ui/backdrop-image.css';
+import '@kerfjs/ui/toolbar.css';
+import '@kerfjs/ui/toolbar-text.css';
+import '@kerfjs/ui/toolbar-control-group.css';
+
+import { BackdropImage } from '@kerfjs/ui/backdrop-image';
+import { fillColor, uiColor } from '@kerfjs/ui/css-values';
+import { List } from '@kerfjs/ui/list';
+import { ListHeader } from '@kerfjs/ui/list-header';
+import { ListItem } from '@kerfjs/ui/list-item';
+import { LucideIcon } from '@kerfjs/ui/lucide-icon';
+import { NavStack, type NavStackView } from '@kerfjs/ui/nav-stack';
+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 { wireScrollDividers } from '@kerfjs/ui/wire-scroll-dividers';
+import { signal } from 'kerfjs';
+import { ChevronRight, Disc3, Ellipsis, Play, Share, Shuffle } from 'lucide';
+
+import type { RecipeFactory, RecipePresentation } from './types.js';
+
+export const presentation: RecipePresentation = {
+  viewport: {
+    layout: 'grid',
+    width: 'compact',
+    height: 'tall',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: "An Apple-Music-style detail page composed only from components: a NavStack with clear chrome and the scroll-edge material, a scoped tint from the artwork's bottom color, an underChrome BackdropImage with parallax and progressive blur that fades into the tinted surface, and glass control groups. The app owns the artwork, its two colors (the tint and its scheme), the stack, playback, and data.",
+};
+
+interface Album {
+  id: string;
+  title: string;
+  artist: string;
+  /** The artwork's bottom color, which the app already knows. */
+  tint: string;
+  tracks: readonly (readonly [title: string, length: string])[];
+}
+
+const ALBUMS: readonly Album[] = [
+  {
+    id: 'night-harbor',
+    title: 'Night Harbor',
+    artist: 'The Lanterns',
+    tint: '#2a1a3d',
+    tracks: [
+      ['Low Tide', '3:42'],
+      ['Harbor Lights', '4:05'],
+      ['Northbound', '3:18'],
+      ['Glass Coast', '5:01'],
+      ['Undertow', '3:56'],
+      ['Night Ferry', '4:27'],
+      ['Salt Air', '2:59'],
+      ['Last Call', '4:12'],
+      ['Lantern', '3:33'],
+      ['Morning Swell', '4:48'],
+    ],
+  },
+];
+
+// Generated artwork, so the recipe needs no network or binary assets: a dusk
+// sky over three ridge lines whose depth makes the parallax legible.
+const ARTWORK = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 1200" preserveAspectRatio="xMidYMid slice">
+<defs><linearGradient id="s" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#1b2a5c"/><stop offset=".5" stop-color="#c2577a"/><stop offset="1" stop-color="#f4b36b"/></linearGradient>
+<radialGradient id="g" cx=".5" cy=".5" r=".5"><stop offset="0" stop-color="#fff3c4"/><stop offset="1" stop-color="#fff3c4" stop-opacity="0"/></radialGradient></defs>
+<rect width="1600" height="1200" fill="url(#s)"/>
+<circle cx="1080" cy="560" r="240" fill="url(#g)"/><circle cx="1080" cy="560" r="96" fill="#ffe9b0"/>
+<path d="M0 680 L180 540 L330 640 L520 470 L700 620 L880 510 L1060 660 L1260 490 L1440 620 L1600 530 V1200 H0Z" fill="#7a3f6e"/>
+<path d="M0 820 L220 700 L400 790 L600 660 L820 810 L1000 720 L1200 830 L1400 720 L1600 810 V1200 H0Z" fill="#4b2a5a"/>
+<path d="M0 960 L260 850 L480 940 L720 840 L940 960 L1180 880 L1400 970 L1600 900 V1200 H0Z" fill="#2a1a3d"/>
+</svg>`;
+
+// A blob URL rather than a data URL: older kerf releases this package still
+// supports screen `data:image/svg+xml` out of every URL attribute; current kerf
+// allows it in `<img src>`. Created once and
+// reused, so re-renders do not leak blob URLs.
+let artworkUrl: string | undefined;
+const artwork = () =>
+  (artworkUrl ??= URL.createObjectURL(
+    new Blob([ARTWORK], { type: 'image/svg+xml' }),
+  ));
+
+const command = (name: string, label: string, icon: SafeIcon) => (
+  <button
+    type="button"
+    aria-label={label}
+    data-action="recipe-action"
+    data-recipe-command={name}
+  >
+    {icon}
+  </button>
+);
+
+type SafeIcon = ReturnType<typeof LucideIcon>;
+
+export const createRecipe: RecipeFactory = (announce) => {
+  const libraryView = (): NavStackView => ({
+    key: 'library',
+    toolbar: { title: 'Library' },
+    content: (
+      <List>
+        <section>
+          <ListHeader label="Albums" />
+          {ALBUMS.map((album) => (
+            <ListItem
+              action="recipe-action"
+              itemId={album.id}
+              label={album.title}
+              description={album.artist}
+              icon={<LucideIcon icon={Disc3} name="disc-3" />}
+              trailing={<LucideIcon icon={ChevronRight} name="chevron-right" />}
+            />
+          ))}
+        </section>
+      </List>
+    ),
+  });
+
+  const albumView = (album: Album): NavStackView => ({
+    key: album.id,
+    toolbar: {
+      title: '',
+      trailing: (
+        <ToolbarControlGroup
+          label="Album Actions"
+          content="icon"
+          material="glass"
+        >
+          {command('share', 'Share', <LucideIcon icon={Share} name="share" />)}
+          {command(
+            'more',
+            'More',
+            <LucideIcon icon={Ellipsis} name="ellipsis" />,
+          )}
+        </ToolbarControlGroup>
+      ),
+    },
+    pane: { safeAreaEdges: [] },
+    content: (
+      <BackdropImage
+        src={artwork()}
+        alt={`${album.title} artwork: ridges at dusk under a low sun`}
+        position="bottom"
+        parallax="subtle"
+        blur={{ dim: 0.2 }}
+        fadeTo={uiColor('surface')}
+        underChrome
+        overlay={
+          <Toolbar
+            label={album.title}
+            leading={
+              <ToolbarText
+                text={album.title}
+                description={album.artist}
+                size="xlarge"
+                headingLevel={2}
+              />
+            }
+            trailing={
+              <ToolbarControlGroup
+                label="Playback"
+                content="mixed"
+                material="glass"
+              >
+                {command(
+                  'play',
+                  'Play',
+                  <>
+                    <LucideIcon icon={Play} name="play" />
+                    <span>Play</span>
+                  </>,
+                )}
+                {command(
+                  'shuffle',
+                  'Shuffle',
+                  <LucideIcon icon={Shuffle} name="shuffle" />,
+                )}
+              </ToolbarControlGroup>
+            }
+          />
+        }
+      >
+        <List>
+          <section>
+            <ListHeader
+              label="Songs"
+              count={album.tracks.length}
+              countLabel={`${String(album.tracks.length)} songs`}
+            />
+            {album.tracks.map(([title, length], index) => (
+              <ListItem
+                action="recipe-action"
+                itemId={`${album.id}-track-${String(index + 1)}`}
+                label={title}
+                trailing={
+                  <Text variant="span" tone="quiet">
+                    {length}
+                  </Text>
+                }
+              />
+            ))}
+          </section>
+        </List>
+      </BackdropImage>
+    ),
+  });
+
+  const views = signal<NavStackView[]>([libraryView(), albumView(ALBUMS[0]!)]);
+  const current = () =>
+    ALBUMS.find((album) => album.id === views.value.at(-1)?.key);
+
+  const render = () => {
+    const album = current();
+    return (
+      <section data-recipe="recipe-media-detail" aria-label="Music">
+        <NavStack
+          id="recipe-media"
+          label="Music"
+          views={views.value}
+          chromePresentation="clear"
+          scrollEdge="material"
+          tint={
+            album === undefined
+              ? undefined
+              : { color: fillColor(album.tint), scheme: 'dark' }
+          }
+        />
+      </section>
+    );
+  };
+
+  return {
+    render,
+    action(name, element) {
+      if (name === 'nav-back') {
+        if (views.value.length > 1) {
+          views.value = views.value.slice(0, -1);
+          announce('Navigated back');
+        }
+        return;
+      }
+      const album = ALBUMS.find(
+        (candidate) => candidate.id === element.dataset.itemId,
+      );
+      if (album) {
+        views.value = [...views.value, albumView(album)];
+        announce(`Opened ${album.title}`);
+        return;
+      }
+      if (element.dataset.itemId) {
+        announce(
+          `Playing ${element.querySelector('.kui-list-item__primary-label')?.textContent ?? 'song'}`,
+        );
+        return;
+      }
+      announce(`${name} requested`);
+    },
+    wire(root) {
+      // The clear chrome's scroll-edge material and the view Pane's chrome
+      // clearance follow the scroll state this reports.
+      return wireScrollDividers(root);
+    },
+  };
+};

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

@@ -1,5 +1,4 @@
 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';
 
@@ -9,7 +8,10 @@ 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 {
+export function mountRecipe(
+  root: HTMLElement,
+  controller: RecipeController,
+): () => void {
   const stopMount = mount(root, controller.render);
   const stopActions = delegateActions(root, 'click', {
     'recipe-action': (_event, element) => {
@@ -17,14 +19,29 @@ export function mountRecipe(root: HTMLElement, controller: RecipeController): ()
       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 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 stopNav = wireNavStack(root, {
+    onBack: () => controller.action('nav-back', root),
   });
-  const stopNav = wireNavStack(root, { onBack: () => controller.action('nav-back', root) });
   const stopWire = controller.wire?.(root);
 
   let disposed = false;
@@ -33,7 +50,6 @@ export function mountRecipe(root: HTMLElement, controller: RecipeController): ()
     disposed = true;
     stopWire?.();
     stopNav();
-    stopResize();
     stopDialogs();
     stopInputs();
     stopChanges();