@sovereignfs/ui 0.37.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sovereignfs/ui",
-  "version": "0.37.0",
+  "version": "0.40.0",
   "type": "module",
   "description": "Sovereign Design System — design tokens and React components.",
   "keywords": [

package/src/components/FileDropzone/FileDropzone.module.css

@@ -0,0 +1,63 @@
+.dropzone {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-4);
+  width: 100%;
+  box-sizing: border-box;
+  padding: var(--sv-space-4) var(--sv-space-5);
+  border: 1.5px dashed var(--sv-color-border);
+  border-radius: var(--sv-radius-md);
+  background-color: var(--sv-color-surface-raised);
+  cursor: pointer;
+  transition:
+    background-color 0.12s ease,
+    border-color 0.12s ease;
+}
+
+@media (hover: hover) {
+  .dropzone:hover {
+    background-color: var(--sv-color-surface-sunken);
+    border-color: var(--sv-color-border-strong);
+  }
+}
+
+.dropzoneActive {
+  background-color: var(--sv-color-surface-sunken);
+  border-color: var(--sv-color-border-strong);
+}
+
+.dropzoneDisabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.icon {
+  display: inline-flex;
+  flex-shrink: 0;
+  color: var(--sv-color-text-muted);
+}
+
+.text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+
+.title {
+  font-size: var(--sv-font-size-sm);
+  font-weight: var(--sv-font-weight-medium);
+  color: var(--sv-color-text-primary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hint {
+  font-size: var(--sv-font-size-xs);
+  color: var(--sv-color-text-muted);
+}
+
+.hiddenInput {
+  display: none;
+}

package/src/components/FileDropzone/FileDropzone.tsx

@@ -0,0 +1,109 @@
+'use client';
+
+import type { DragEvent, ReactNode } from 'react';
+import { useRef, useState } from 'react';
+import { Icon } from '../Icon/Icon';
+import styles from './FileDropzone.module.css';
+
+export interface FileDropzoneProps {
+  /** Native `<input type="file">` `name` attribute — set this to submit the
+   * file as part of a native `<form action={...}>` (Server Action) request. */
+  name?: string;
+  /** Native `<input type="file">` `accept` attribute, e.g. `".zip,application/zip"`. */
+  accept?: string;
+  /** Icon shown beside the label — a file-type glyph. Defaults to a generic file icon. */
+  icon?: ReactNode;
+  /** Primary label — e.g. "Choose a ZIP file", or the selected file's name. */
+  label: string;
+  /** Secondary hint — e.g. "or drag and drop here", or the selected file's size. */
+  hint?: string;
+  /** Called with the picked or dropped file, or `null` if the input is cleared. */
+  onFileSelect: (file: File | null) => void;
+  /** Accessible name for the control — describe what will be uploaded. */
+  ariaLabel: string;
+  disabled?: boolean;
+  className?: string;
+}
+
+/**
+ * A styled drag-and-drop file picker: a dashed-border dropzone wrapping a
+ * visually-hidden native `<input type="file">`, so the native picker still
+ * opens on click and the field participates in normal form semantics. A
+ * dropped file is written into the input's own `FileList` (via `DataTransfer`)
+ * so `name` + native `<form action>` submission sees it exactly like a
+ * click-picked file — not just the `onFileSelect` callback.
+ *
+ * Caller owns the selected-file state and passes `label`/`hint` accordingly
+ * (e.g. swap to the picked file's name/size) — this component is otherwise
+ * uncontrolled and stateless beyond its own drag-hover visual.
+ *
+ * Do not pass `required` through to a wrapping form's validation via this
+ * field — `display: none` on the hidden input does not exempt it from HTML5
+ * constraint validation, so a `required` hidden input can block submission
+ * with no visible field for the user to focus. Validate `onFileSelect`'s
+ * result in application code instead.
+ */
+export function FileDropzone({
+  name,
+  accept,
+  icon,
+  label,
+  hint,
+  onFileSelect,
+  ariaLabel,
+  disabled,
+  className,
+}: FileDropzoneProps) {
+  const [dragging, setDragging] = useState(false);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  return (
+    <label
+      className={[
+        styles.dropzone,
+        dragging ? styles.dropzoneActive : '',
+        disabled ? styles.dropzoneDisabled : '',
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      onDragOver={(event: DragEvent) => {
+        if (disabled) return;
+        event.preventDefault();
+        setDragging(true);
+      }}
+      onDragLeave={() => setDragging(false)}
+      onDrop={(event: DragEvent) => {
+        if (disabled) return;
+        event.preventDefault();
+        setDragging(false);
+        const dropped = event.dataTransfer.files[0];
+        if (!dropped) return;
+        if (inputRef.current && typeof DataTransfer !== 'undefined') {
+          const transfer = new DataTransfer();
+          transfer.items.add(dropped);
+          inputRef.current.files = transfer.files;
+        }
+        onFileSelect(dropped);
+      }}
+    >
+      <span className={styles.icon} aria-hidden="true">
+        {icon ?? <Icon name="file" size="lg" aria-hidden />}
+      </span>
+      <span className={styles.text}>
+        <span className={styles.title}>{label}</span>
+        {hint && <span className={styles.hint}>{hint}</span>}
+      </span>
+      <input
+        ref={inputRef}
+        type="file"
+        name={name}
+        aria-label={ariaLabel}
+        accept={accept}
+        disabled={disabled}
+        onChange={(event) => onFileSelect(event.target.files?.[0] ?? null)}
+        className={styles.hiddenInput}
+      />
+    </label>
+  );
+}

package/src/components/FileDropzone/__tests__/FileDropzone.test.tsx

@@ -0,0 +1,67 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { FileDropzone } from '../FileDropzone';
+
+afterEach(cleanup);
+
+describe('FileDropzone', () => {
+  it('renders the label and hint', () => {
+    render(
+      <FileDropzone
+        label="Choose a ZIP file"
+        hint="or drag and drop here"
+        ariaLabel="Upload ZIP file"
+        onFileSelect={vi.fn()}
+      />,
+    );
+    expect(screen.getByText('Choose a ZIP file')).toBeDefined();
+    expect(screen.getByText('or drag and drop here')).toBeDefined();
+  });
+
+  it('exposes an accessible name via aria-label', () => {
+    render(
+      <FileDropzone label="Choose a file" ariaLabel="Upload font file" onFileSelect={vi.fn()} />,
+    );
+    expect(screen.getByLabelText('Upload font file')).toBeDefined();
+  });
+
+  it('forwards accept to the native file input', () => {
+    render(
+      <FileDropzone
+        label="Choose a file"
+        ariaLabel="Upload"
+        accept=".zip"
+        onFileSelect={vi.fn()}
+      />,
+    );
+    const input = screen.getByLabelText('Upload') as HTMLInputElement;
+    expect(input.accept).toBe('.zip');
+  });
+
+  it('calls onFileSelect with the picked file', () => {
+    const onFileSelect = vi.fn();
+    render(<FileDropzone label="Choose a file" ariaLabel="Upload" onFileSelect={onFileSelect} />);
+    const input = screen.getByLabelText('Upload') as HTMLInputElement;
+    const file = new File(['content'], 'font.woff2');
+    fireEvent.change(input, { target: { files: [file] } });
+    expect(onFileSelect).toHaveBeenCalledWith(file);
+  });
+
+  it('calls onFileSelect with the dropped file', () => {
+    const onFileSelect = vi.fn();
+    render(<FileDropzone label="Choose a file" ariaLabel="Upload" onFileSelect={onFileSelect} />);
+    const dropzone = screen.getByLabelText('Upload').closest('label');
+    if (!dropzone) throw new Error('dropzone label not found');
+    const file = new File(['content'], 'font.woff2');
+    fireEvent.drop(dropzone, { dataTransfer: { files: [file] } });
+    expect(onFileSelect).toHaveBeenCalledWith(file);
+  });
+
+  it('is disabled when the disabled prop is set', () => {
+    render(
+      <FileDropzone label="Choose a file" ariaLabel="Upload" disabled onFileSelect={vi.fn()} />,
+    );
+    expect((screen.getByLabelText('Upload') as HTMLInputElement).disabled).toBe(true);
+  });
+});

package/src/components/Icon/icons/external-link.tsx

@@ -0,0 +1,22 @@
+// Generated by scripts/generate-icons.ts — do not edit.
+// Source: Lucide (https://lucide.dev) — ISC license, see packages/ui/NOTICE.
+import type { SVGProps } from 'react';
+
+export function ExternalLinkIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <path d="M15 3h6v6" />
+      <path d="M10 14 21 3" />
+      <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />
+    </svg>
+  );
+}

package/src/components/Icon/icons/file.tsx

@@ -0,0 +1,21 @@
+// Generated by scripts/generate-icons.ts — do not edit.
+// Source: Lucide (https://lucide.dev) — ISC license, see packages/ui/NOTICE.
+import type { SVGProps } from 'react';
+
+export function FileIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <path d="M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z" />
+      <path d="M14 2v5a1 1 0 0 0 1 1h5" />
+    </svg>
+  );
+}

package/src/components/Icon/icons/index.ts

@@ -29,6 +29,9 @@ import { AlertTriangleIcon } from './alert-triangle';
 import { CalendarIcon } from './calendar';
 import { SlidersHorizontalIcon } from './sliders-horizontal';
 import { EllipsisVerticalIcon } from './ellipsis-vertical';
+import { FileIcon } from './file';
+import { UploadIcon } from './upload';
+import { ExternalLinkIcon } from './external-link';
 import { BananaIcon } from './banana';
 import { AppleIcon } from './apple';
 import { CarrotIcon } from './carrot';
@@ -80,6 +83,9 @@ export type IconName =
   | 'calendar'
   | 'sliders-horizontal'
   | 'ellipsis-vertical'
+  | 'file'
+  | 'upload'
+  | 'external-link'
   | 'banana'
   | 'apple'
   | 'carrot'
@@ -133,6 +139,9 @@ export const ICONS: Record<IconName, IconComponent> = {
   calendar: CalendarIcon,
   'sliders-horizontal': SlidersHorizontalIcon,
   'ellipsis-vertical': EllipsisVerticalIcon,
+  file: FileIcon,
+  upload: UploadIcon,
+  'external-link': ExternalLinkIcon,
   banana: BananaIcon,
   apple: AppleIcon,
   carrot: CarrotIcon,
@@ -184,6 +193,9 @@ export { AlertTriangleIcon } from './alert-triangle';
 export { CalendarIcon } from './calendar';
 export { SlidersHorizontalIcon } from './sliders-horizontal';
 export { EllipsisVerticalIcon } from './ellipsis-vertical';
+export { FileIcon } from './file';
+export { UploadIcon } from './upload';
+export { ExternalLinkIcon } from './external-link';
 export { BananaIcon } from './banana';
 export { AppleIcon } from './apple';
 export { CarrotIcon } from './carrot';

package/src/components/Icon/icons/upload.tsx

@@ -0,0 +1,22 @@
+// Generated by scripts/generate-icons.ts — do not edit.
+// Source: Lucide (https://lucide.dev) — ISC license, see packages/ui/NOTICE.
+import type { SVGProps } from 'react';
+
+export function UploadIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...props}
+    >
+      <path d="M12 3v12" />
+      <path d="m17 8-5-5-5 5" />
+      <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+    </svg>
+  );
+}

package/src/hooks/index.ts

@@ -2,3 +2,5 @@ export { useLongPress } from './useLongPress';
 export type { UseLongPressOptions, LongPressHandlers } from './useLongPress';
 export { useDoubleTapHandler, useSingleOrDoubleTap } from './useDoubleTap';
 export { useIsMobile, MOBILE_BREAKPOINT_PX } from './useIsMobile';
+export { useCommitOnEnterOrBlur } from './useCommitOnEnterOrBlur';
+export type { CommitOnEnterOrBlurHandlers } from './useCommitOnEnterOrBlur';

package/src/hooks/useCommitOnEnterOrBlur.ts

@@ -0,0 +1,39 @@
+'use client';
+
+import type { KeyboardEvent } from 'react';
+
+export interface CommitOnEnterOrBlurHandlers {
+  onKeyDown: (e: KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+  onBlur: () => void;
+}
+
+/**
+ * useCommitOnEnterOrBlur — spreads onto a quick-entry input/textarea so
+ * Enter and losing focus both commit through the same callback.
+ *
+ * iOS Safari adds its own "Previous / Next / Done" toolbar above the
+ * software keyboard whenever more than one focusable field is nearby (a
+ * Sheet with several fields, a form, etc.) — there is no supported way to
+ * suppress it, since it's WebKit's own field-detection heuristic, not
+ * something the page controls. Tapping that toolbar's Done/checkmark only
+ * ever fires a native `blur`; it is not a form submit and dispatches no
+ * keydown, so a field that commits only on Enter silently discards whatever
+ * was typed the moment a user dismisses the keyboard that way instead of
+ * pressing the on-screen Return key — the two dismissal paths look
+ * identical to the user but produce different outcomes.
+ *
+ * `onCommit` is called unconditionally on both Enter and blur — it owns any
+ * empty-value no-op itself, matching how every call site's own commit
+ * function already guards against an empty value before doing anything.
+ * Callers needing more key handling (e.g. Escape-to-cancel) compose their
+ * own `onKeyDown` around the returned one rather than this hook growing
+ * options for every caller's own key bindings.
+ */
+export function useCommitOnEnterOrBlur(onCommit: () => void): CommitOnEnterOrBlurHandlers {
+  return {
+    onKeyDown: (e) => {
+      if (e.key === 'Enter') onCommit();
+    },
+    onBlur: onCommit,
+  };
+}

package/src/index.ts

@@ -71,6 +71,8 @@ export { Checkbox } from './components/Checkbox/Checkbox';
 export type { CheckboxProps } from './components/Checkbox/Checkbox';
 export { DragHandleRow } from './components/DragHandleRow/DragHandleRow';
 export type { DragHandleRowProps } from './components/DragHandleRow/DragHandleRow';
+export { FileDropzone } from './components/FileDropzone/FileDropzone';
+export type { FileDropzoneProps } from './components/FileDropzone/FileDropzone';
 export { Calendar } from './components/Calendar/Calendar';
 export type { CalendarProps } from './components/Calendar/Calendar';
 export { DatePicker } from './components/DatePicker/DatePicker';
@@ -86,6 +88,12 @@ export { QuantityStepper } from './components/QuantityStepper/QuantityStepper';
 export type { QuantityStepperProps } from './components/QuantityStepper/QuantityStepper';
 export { CheckableListRow } from './components/CheckableListRow/CheckableListRow';
 export type { CheckableListRowProps } from './components/CheckableListRow/CheckableListRow';
-export { useLongPress, useDoubleTapHandler, useSingleOrDoubleTap, useIsMobile } from './hooks';
+export {
+  useLongPress,
+  useDoubleTapHandler,
+  useSingleOrDoubleTap,
+  useIsMobile,
+  useCommitOnEnterOrBlur,
+} from './hooks';
 export { MOBILE_BREAKPOINT_PX } from './hooks';
-export type { UseLongPressOptions, LongPressHandlers } from './hooks';
+export type { UseLongPressOptions, LongPressHandlers, CommitOnEnterOrBlurHandlers } from './hooks';

package/src/stories/DesignSystemOverview.stories.tsx

@@ -34,6 +34,7 @@ import { Toggle } from '../components/Toggle/Toggle';
 import { Tooltip } from '../components/Tooltip/Tooltip';
 import { Checkbox } from '../components/Checkbox/Checkbox';
 import { DragHandleRow } from '../components/DragHandleRow/DragHandleRow';
+import { FileDropzone } from '../components/FileDropzone/FileDropzone';
 import { OverlayHeader } from '../components/OverlayHeader/OverlayHeader';
 import { Sheet } from '../components/Sheet/Sheet';
 import { ConfirmDialog } from '../components/ConfirmDialog/ConfirmDialog';
@@ -755,6 +756,21 @@ function CheckableListRowDemo() {
   );
 }
 
+function FileDropzoneDemo() {
+  const [file, setFile] = useState<File | null>(null);
+  return (
+    <div style={{ width: '100%' }}>
+      <FileDropzone
+        ariaLabel="Upload ZIP file"
+        accept=".zip,application/zip"
+        label={file ? file.name : 'Choose a ZIP file'}
+        hint={file ? `${(file.size / 1024).toFixed(0)} KB` : 'or drag and drop here'}
+        onFileSelect={setFile}
+      />
+    </div>
+  );
+}
+
 function IconPickerDemo() {
   const [value, setValue] = useState<IconName | null>('banana');
   const options: IconName[] = [
@@ -1582,7 +1598,7 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
             <ComponentCard
               name="Icon"
               importLine="import { Icon } from '@sovereignfs/ui';"
-              usage="SVG icon primitive. 29 bundled icons. Decorative: aria-hidden. Meaningful: aria-label. Three sizes: sm, md, lg."
+              usage="SVG icon primitive. 52 bundled icons. Decorative: aria-hidden. Meaningful: aria-label. Three sizes: sm, md, lg."
             >
               {(
                 [
@@ -1595,6 +1611,7 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
                   'search',
                   'plus',
                   'trash-2',
+                  'external-link',
                 ] as const
               ).map((n) => (
                 <Icon key={n} name={n} size="md" aria-hidden />
@@ -1946,6 +1963,15 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
                 ))}
               </div>
             </ComponentCard>
+
+            {/* FileDropzone */}
+            <ComponentCard
+              name="FileDropzone"
+              importLine="import { FileDropzone } from '@sovereignfs/ui';"
+              usage="Styled drag-and-drop file picker — a dashed-border dropzone wrapping a visually-hidden native file input. Caller owns selected-file state and passes label/hint accordingly."
+            >
+              <FileDropzoneDemo />
+            </ComponentCard>
           </div>
         </section>
 

package/src/stories/FileDropzone.stories.tsx

@@ -0,0 +1,69 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { FileDropzone } from '../components/FileDropzone/FileDropzone';
+import { Icon } from '../components/Icon/Icon';
+
+const meta: Meta<typeof FileDropzone> = {
+  title: 'Components/FileDropzone',
+  component: FileDropzone,
+  parameters: { layout: 'padded' },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof FileDropzone>;
+
+export const Default: Story = {
+  render: () => {
+    function Demo() {
+      const [file, setFile] = useState<File | null>(null);
+      return (
+        <div style={{ maxWidth: '420px' }}>
+          <FileDropzone
+            ariaLabel="Upload ZIP file"
+            accept=".zip,application/zip"
+            label={file ? file.name : 'Choose a ZIP file'}
+            hint={file ? `${(file.size / 1024).toFixed(0)} KB` : 'or drag and drop here'}
+            onFileSelect={setFile}
+          />
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+export const CustomIcon: Story = {
+  render: () => {
+    function Demo() {
+      const [file, setFile] = useState<File | null>(null);
+      return (
+        <div style={{ maxWidth: '420px' }}>
+          <FileDropzone
+            ariaLabel="Upload font file"
+            accept=".woff2,.woff,.ttf,.otf"
+            icon={<Icon name="upload" size="lg" aria-hidden />}
+            label={file ? file.name : 'Choose a font file'}
+            hint={file ? undefined : '.woff2, .woff, .ttf, or .otf'}
+            onFileSelect={setFile}
+          />
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div style={{ maxWidth: '420px' }}>
+      <FileDropzone
+        ariaLabel="Upload ZIP file"
+        label="Choose a ZIP file"
+        hint="or drag and drop here"
+        disabled
+        onFileSelect={() => {}}
+      />
+    </div>
+  ),
+};

package/src/stories/InteractionHooks.stories.tsx

@@ -1,7 +1,13 @@
 import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Card } from '../components/Card/Card';
-import { useDoubleTapHandler, useIsMobile, useLongPress, useSingleOrDoubleTap } from '../hooks';
+import {
+  useCommitOnEnterOrBlur,
+  useDoubleTapHandler,
+  useIsMobile,
+  useLongPress,
+  useSingleOrDoubleTap,
+} from '../hooks';
 
 // ---------------------------------------------------------------------------
 // Shared primitives (mirrors MobilePatterns.stories.tsx's doc styling)
@@ -268,6 +274,42 @@ function DoubleTapDemo() {
   );
 }
 
+function CommitOnEnterOrBlurDemo() {
+  const [value, setValue] = useState('');
+  const [events, setEvents] = useState<string[]>([]);
+  const log = (msg: string) =>
+    setEvents((e) => [...e, `${new Date().toLocaleTimeString()} — ${msg}`]);
+  const commitHandlers = useCommitOnEnterOrBlur(() => log(`commit: "${value}"`));
+
+  return (
+    <div>
+      <input
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        {...commitHandlers}
+        placeholder="Type, then press Enter or click away…"
+        style={{
+          width: '100%',
+          boxSizing: 'border-box',
+          padding: 'var(--sv-space-2) var(--sv-space-3)',
+          borderRadius: 'var(--sv-radius-md)',
+          border: '1px solid var(--sv-color-border-strong)',
+          background: 'var(--sv-color-surface)',
+          color: 'var(--sv-color-text-primary)',
+          fontFamily: ff,
+          fontSize: 'var(--sv-font-size-sm)',
+        }}
+      />
+      <EventLog events={events} />
+      <Callout type="info">
+        Tries to reproduce the bug this hook fixes: on iOS, tap into the field, type something, then
+        dismiss the keyboard via the native Done/checkmark toolbar instead of the Return key — both
+        now log a commit here, where an Enter-only handler would silently drop the checkmark path.
+      </Callout>
+    </div>
+  );
+}
+
 function IsMobileDemo() {
   const isMobile = useIsMobile();
   return (
@@ -346,6 +388,18 @@ function InteractionHooksDoc() {
         </Callout>
       </section>
 
+      <section style={{ marginBottom: 'var(--sv-space-10)' }}>
+        <SectionHeader
+          title="useCommitOnEnterOrBlur"
+          subtitle="Unifies Enter-to-commit with iOS's native keyboard accessory toolbar, whose Done/checkmark only ever fires a blur, never a keydown."
+        />
+        <Card padding="md">
+          <CommitOnEnterOrBlurDemo />
+        </Card>
+        <CodeBlock>{`const commitHandlers = useCommitOnEnterOrBlur(() => createTask(title));
+<input value={title} onChange={...} {...commitHandlers} />`}</CodeBlock>
+      </section>
+
       <section style={{ marginBottom: 'var(--sv-space-10)' }}>
         <SectionHeader
           title="useIsMobile"