@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

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

@@ -1,103 +1,49 @@
 import '@kerfjs/ui/layout.css';
-import './recipes.css';
 
+import { ContentItem } from '@kerfjs/ui/content-item';
+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 { Pane } from '@kerfjs/ui/pane';
+import { Text } from '@kerfjs/ui/text';
 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';
+import type { RecipeFactory, RecipePresentation } from './types.js';
+
+export const presentation: RecipePresentation = {
+  viewport: {
+    layout: 'grid',
+    width: 'compact',
+    minHeight: 'medium',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: 'The recipe owns pane, content-item, and toolbar geometry. The app owns routes, permissions, labels, and disclosure state.',
+};
 
 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">
+    <Pane
+      element="aside"
+      label="Workspace Navigation"
+      rootAttributes={{ 'data-recipe': 'recipe-navigation-sidebar' }}
+      footer={
         <Toolbar
-          label="Sidebar actions"
-          dividerSides=""
+          label="Sidebar Actions"
+          dividerSides="t"
           leading={
             <ToolbarControlGroup appearance="borderless" single>
               <button
                 type="button"
-                aria-label="Add project"
+                aria-label="Add Project"
                 data-action="recipe-action"
                 data-recipe-command="add"
               >
@@ -109,7 +55,7 @@ export const createRecipe: RecipeFactory = (announce) => {
             <ToolbarControlGroup appearance="borderless" single>
               <button
                 type="button"
-                aria-label="Workspace settings"
+                aria-label="Workspace Settings"
                 data-action="recipe-action"
                 data-recipe-command="settings"
               >
@@ -118,8 +64,77 @@ export const createRecipe: RecipeFactory = (announce) => {
             </ToolbarControlGroup>
           }
         />
-      </footer>
-    </aside>
+      }
+    >
+      <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"
+            />
+            <ContentItem>
+              <List gap="2xs">
+                <Text variant="span">
+                  <strong>Quarterly Goal</strong>
+                </Text>
+                <Text variant="span" tone="quiet" size="compact">
+                  Ship accessible navigation patterns to every workspace.
+                </Text>
+              </List>
+            </ContentItem>
+          </>
+        )}
+      </section>
+    </Pane>
   );
   return {
     render,

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

@@ -1,16 +1,32 @@
 import '@kerfjs/ui/layout.css';
 import '@kerfjs/ui/nav-stack.css';
 import '@kerfjs/ui/toolbar-text.css';
-import './recipes.css';
 
+import { ContentItem } from '@kerfjs/ui/content-item';
+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 { Row } from '@kerfjs/ui/row';
+import { Text } from '@kerfjs/ui/text';
 import { signal } from 'kerfjs';
 import { ChevronRight, FileText, Folder } from 'lucide';
 
-import type { RecipeFactory } from './types.js';
+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: 'The recipe owns the stack as a signal of views and pushes/pops it; NavStack renders the stack and wireNavStack slides the content and settles the chrome. The app owns selection, data, and routing.',
+};
 
 interface LibraryItem {
   id: string;
@@ -21,19 +37,19 @@ interface LibraryItem {
 const ITEMS: LibraryItem[] = [
   {
     id: 'tokens',
-    label: 'Design tokens',
+    label: 'Design Tokens',
     detail:
       'Semantic color, spacing, and radius scales shared across every surface.',
   },
   {
     id: 'controls',
-    label: 'Toolbar controls',
+    label: 'Toolbar Controls',
     detail:
       'Control groups and segmented controls with their hover and pressed contracts.',
   },
   {
     id: 'layouts',
-    label: 'App layouts',
+    label: 'App Layouts',
     detail:
       'Navigation stacks, split views, workbench, and bottom-tab scaffolds.',
   },
@@ -42,9 +58,9 @@ const ITEMS: LibraryItem[] = [
 export const createRecipe: RecipeFactory = (announce) => {
   const listView = (): NavStackView => ({
     key: 'library',
-    title: 'Library',
+    toolbar: { title: 'Library' },
     content: (
-      <div class="recipe-navstack__view kui-pane__content kui-content">
+      <List>
         <section>
           <ListHeader label="Components" />
           {ITEMS.map((item) => (
@@ -57,26 +73,29 @@ export const createRecipe: RecipeFactory = (announce) => {
             />
           ))}
         </section>
-        <p class="kui-recipe__ownership kui-content-item">
-          The recipe owns the stack as a signal of views and pushes/pops it;
-          `NavStack` renders the stack and `wireNavStack` slides the content and
-          settles the chrome. The app owns selection, data, and routing.
-        </p>
-      </div>
+      </List>
     ),
   });
 
   const detailView = (item: LibraryItem): NavStackView => ({
     key: item.id,
-    title: item.label,
+    toolbar: { title: item.label },
     content: (
-      <div class="recipe-navstack__view kui-pane__content kui-content">
-        <div class="kui-content-item">
-          <LucideIcon icon={FileText} name="file-text" />
-          <strong>{item.label}</strong>
-          <p class="kui-recipe__muted">{item.detail}</p>
-        </div>
-      </div>
+      <List controlInsets="t">
+        <ContentItem>
+          <Row gap="xs">
+            <LucideIcon icon={FileText} name="file-text" />
+            <List gap="2xs">
+              <Text variant="span">
+                <strong>{item.label}</strong>
+              </Text>
+              <Text variant="span" tone="quiet" size="compact">
+                {item.detail}
+              </Text>
+            </List>
+          </Row>
+        </ContentItem>
+      </List>
     ),
   });
 
@@ -84,16 +103,10 @@ export const createRecipe: RecipeFactory = (announce) => {
 
   const render = () => (
     <section
-      class="kui-recipe recipe-navstack kui-recipe__surface"
       data-recipe="recipe-navigation-stack"
+      aria-label="Component Library"
     >
-      <div class="recipe-navstack__stage">
-        <NavStack
-          id="recipe-nav"
-          label="Component library"
-          views={views.value}
-        />
-      </div>
+      <NavStack id="recipe-nav" label="Component Library" views={views.value} />
     </section>
   );
 

package/ux-demo/recipes/types.ts

@@ -1,3 +1,4 @@
+import type { CatalogExampleViewport } from '@kerfjs/ui/catalog';
 import type { SafeHtml } from 'kerfjs';
 
 export interface RecipeController {
@@ -5,7 +6,6 @@ export interface RecipeController {
   action(command: string, element: HTMLElement): void;
   change?(element: HTMLElement): void;
   afterHide?(element: HTMLElement): void;
-  resize?(id: string, size: number): void;
   /**
    * Install any imperative wiring the recipe owns on its mounted root (e.g.
    * `wireSidebar` for a collapsible rail/drawer), returning a disposer. The
@@ -17,3 +17,16 @@ export interface RecipeController {
 export type RecipeFactory = (
   announce: (message: string) => void,
 ) => RecipeController;
+
+/**
+ * Catalog-only presentation for one recipe. The UX catalog frames the recipe in
+ * a `CatalogExample` viewport and shows `note` when recipe notes are toggled on;
+ * an application that copies the recipe ignores this export and mounts the
+ * controller into its own container.
+ */
+export interface RecipePresentation {
+  /** Catalog-owned specimen frame: width, height, surface, and border. */
+  viewport?: CatalogExampleViewport;
+  /** Ownership note: what the recipe owns versus what the application owns. */
+  note: string;
+}

package/ux-demo/recipes/workspace-header.tsx

@@ -1,64 +1,90 @@
 import '@kerfjs/ui/layout.css';
-import './recipes.css';
 
-import { PanelHeader } from '@kerfjs/ui/panel-header';
+import { List } from '@kerfjs/ui/list';
+import { ListInsetText } from '@kerfjs/ui/list-inset-text';
 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 type { RecipeFactory } from './types.js';
+import type { RecipeFactory, RecipePresentation } from './types.js';
+
+export const presentation: RecipePresentation = {
+  viewport: {
+    width: 'full',
+    frame: 'solid',
+    surface: 'default',
+    overflow: 'hidden',
+    shadow: true,
+  },
+  note: 'The recipe owns page hierarchy and action relocation. The app owns authorization, command behavior, breadcrumbs, and product copy.',
+};
 
 export const createRecipe: RecipeFactory = (announce) => ({
   render: () => (
     <section
-      class="kui-recipe recipe-header kui-recipe__surface kui-content"
       data-recipe="recipe-workspace-header"
+      aria-labelledby="recipe-workspace-title"
     >
-      <p class="recipe-header__context kui-inline-metadata kui-content-item">
-        <span>Northstar workspace</span>
-        <span>·</span>
-        <span>Product planning</span>
-      </p>
-      <PanelHeader
-        title="Accessibility readiness and responsive navigation rollout"
-        titleId="recipe-workspace-title"
-        actions={
-          <div class="kui-control-cluster">
-            <button
-              class="kui-recipe__button"
-              type="button"
-              data-action="recipe-action"
-              data-recipe-command="share"
-            >
-              Share
-            </button>
-            <button
-              class="kui-recipe__button"
-              type="button"
-              data-action="recipe-action"
-              data-recipe-command="more"
-            >
-              More actions
-            </button>
-            <button
-              class="kui-recipe__button"
-              data-primary="true"
-              type="button"
-              data-action="recipe-action"
-              data-recipe-command="publish"
-            >
-              Publish update
-            </button>
-          </div>
-        }
-      />
-      <StateBanner
-        title="Ready for review"
-        detail="All required checks passed 18 minutes ago."
-        tone="success"
-      />
-      <p class="kui-recipe__ownership kui-content-item">
-        The recipe owns page hierarchy and action relocation. The app owns
-        authorization, command behavior, breadcrumbs, and product copy.
-      </p>
+      <List gap="l" controlInsets="tb">
+        <List>
+          <ListInsetText sides="rl">
+            <Text variant="span" tone="quiet" size="compact">
+              Northstar workspace · Product planning
+            </Text>
+          </ListInsetText>
+          <Toolbar
+            label="Workspace Heading"
+            responsive="stack"
+            responsiveAt="compact"
+            leading={
+              <ToolbarText
+                text="Accessibility Readiness and Responsive Navigation Rollout"
+                size="xlarge"
+                id="recipe-workspace-title"
+                headingLevel={1}
+                wrap
+                maxLines={2}
+              />
+            }
+            trailing={
+              <ToolbarControlGroup
+                appearance="borderless"
+                buttonAppearance="push"
+                content="text"
+              >
+                <button
+                  type="button"
+                  data-action="recipe-action"
+                  data-recipe-command="share"
+                >
+                  Share
+                </button>
+                <button
+                  type="button"
+                  data-action="recipe-action"
+                  data-recipe-command="more"
+                >
+                  More Actions
+                </button>
+                <button
+                  type="button"
+                  data-action="recipe-action"
+                  data-recipe-command="publish"
+                >
+                  Publish Update
+                </button>
+              </ToolbarControlGroup>
+            }
+          />
+        </List>
+        <StateBanner
+          title="Ready for Review"
+          detail="All required checks passed 18 minutes ago."
+          tone="success"
+        />
+      </List>
     </section>
   ),
   action(command) {

package/vite-ux-review.d.mts

@@ -0,0 +1,83 @@
+/** Where the endpoint lives, relative to the catalog page. */
+export declare const UX_REVIEW_PROJECT_PATH: '__ux-review/project.json';
+
+export interface UxReviewPluginOptions {
+  /**
+   * The project directory UX Review files captures under, resolved against
+   * Vite's `root`. Default: the nearest ancestor of `root` holding `.git`,
+   * or `root` itself.
+   */
+  projectDirectory?: string;
+}
+
+/** The connect-style middleware stack of a Vite dev or preview server. */
+export interface UxReviewMiddlewareServer {
+  middlewares: {
+    use(
+      handler: (
+        request: { url?: string; method?: string },
+        response: {
+          statusCode: number;
+          setHeader(name: string, value: string): void;
+          end(body?: string): void;
+        },
+        next: () => void,
+      ) => void,
+    ): unknown;
+  };
+}
+
+/** A Vite plugin; structurally typed so this module needs no `vite` import. */
+export interface UxReviewPlugin {
+  name: 'kerf-ux-review';
+  configResolved(config: { root: string }): void;
+  configureServer(server: UxReviewMiddlewareServer): void;
+  configurePreviewServer(server: UxReviewMiddlewareServer): void;
+}
+
+/** The nearest directory at or above `start` that holds `.git`, else `start`. */
+export declare function findProjectDirectory(start: string): string;
+
+export interface ResolveUxReviewProjectOptions {
+  /** The directory to start from. Default: `process.cwd()`. */
+  root?: string;
+  /**
+   * An explicit project directory, resolved against `root`. Default: the
+   * nearest ancestor of `root` holding `.git`, or `root` itself.
+   */
+  projectDirectory?: string;
+}
+
+/** The real path of the UX Review project directory for a server. */
+export declare function resolveUxReviewProject(
+  options?: ResolveUxReviewProjectOptions,
+): string;
+
+/**
+ * Answer a Fetch API request for `…/__ux-review/project.json` at any base
+ * path: the project JSON for a GET, 405 for another method, or `null` for any
+ * other path so the server handles it as usual. Mount it on a development
+ * server only.
+ */
+export declare function uxReviewProjectResponse(
+  request: Request,
+  projectDirectory: string,
+): Response | null;
+
+/** A Node / connect `(request, response, next)` handler for a server's middleware stack. */
+export type UxReviewMiddleware = Parameters<
+  UxReviewMiddlewareServer['middlewares']['use']
+>[0];
+
+/**
+ * A Node / connect-style handler for `…/__ux-review/project.json` at any base
+ * path; other requests go to `next`. Mount it on a development server only.
+ */
+export declare function uxReviewMiddleware(
+  projectDirectory: string,
+): UxReviewMiddleware;
+
+/** Serve the UX Review project directory to catalog pages on dev and preview servers. */
+export declare function uxReviewPlugin(
+  options?: UxReviewPluginOptions,
+): UxReviewPlugin;