@sovereignfs/ui 0.33.1 → 0.40.0

package/src/components/SuggestionInput/SuggestionInput.tsx

@@ -0,0 +1,207 @@
+'use client';
+
+import { useId, useRef, useState, type KeyboardEvent, type ReactNode } from 'react';
+import { Popover } from '../Popover/Popover';
+import styles from './SuggestionInput.module.css';
+
+export interface SuggestionOption {
+  id: string;
+  label: string;
+  icon?: ReactNode;
+  /** Secondary text shown right-aligned on the row, e.g. "bought 4× recently". */
+  meta?: string;
+}
+
+export interface SuggestionInputProps {
+  value: string;
+  onChange: (value: string) => void;
+  options: SuggestionOption[];
+  onSelect: (option: SuggestionOption) => void;
+  placeholder?: string;
+  'aria-label': string;
+  id?: string;
+  disabled?: boolean;
+  /** Shown in place of the options list while a suggestion fetch is in flight. */
+  loading?: boolean;
+  /**
+   * Label for a trailing, always-selectable row that commits the raw typed
+   * text instead of a matched option — e.g. `(v) => \`Add "${v}" as a new item\`}`.
+   * Shown whenever `value` is non-empty and `onCreate` is provided, even
+   * when `options` is empty, so the input is never a dead end.
+   */
+  createLabel?: (value: string) => string;
+  onCreate?: (value: string) => void;
+  className?: string;
+}
+
+/**
+ * SuggestionInput — a text field with an anchored, keyboard-navigable list
+ * of async suggestions (a combobox), plus an optional trailing "create new"
+ * row so free text is always a valid commit, not just a matched option.
+ *
+ * Fully controlled: the caller owns `value`/`onChange` and supplies
+ * `options` (e.g. debounced server-fetched results) — this component only
+ * handles open/close, keyboard navigation, and selection. Built on `Popover`
+ * for positioning (`width: 'trigger'`, so the panel always matches the
+ * input's own width).
+ */
+export function SuggestionInput({
+  value,
+  onChange,
+  options,
+  onSelect,
+  placeholder,
+  'aria-label': ariaLabel,
+  id,
+  disabled = false,
+  loading = false,
+  createLabel,
+  onCreate,
+  className,
+}: SuggestionInputProps) {
+  const generatedId = useId();
+  const inputId = id ?? generatedId;
+  const listId = `${inputId}-suggestions`;
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [focused, setFocused] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(-1);
+
+  const showCreateRow = Boolean(onCreate && createLabel && value.trim());
+  const rowCount = options.length + (showCreateRow ? 1 : 0);
+  const open = focused && (rowCount > 0 || loading);
+
+  function close() {
+    setFocused(false);
+    setActiveIndex(-1);
+  }
+
+  function commitIndex(index: number) {
+    if (index < 0 || index >= rowCount) return;
+    const option = options[index];
+    if (option) {
+      onSelect(option);
+    } else if (onCreate) {
+      onCreate(value);
+    }
+    close();
+  }
+
+  function handleKeyDown(e: KeyboardEvent<HTMLInputElement>) {
+    if (!open) return;
+    // Some synthetic input sources (seen from automated/CDP-driven key
+    // dispatch) send a keydown with `key`/`code` as "Unidentified" or empty
+    // and no `keyCode` either — nothing here can special-case that further,
+    // but checking the legacy numeric code costs nothing and covers sources
+    // that do populate it even when `key` doesn't (older browsers, some
+    // assistive tech, IME edge cases).
+    const isArrowDown = e.key === 'ArrowDown' || e.keyCode === 40;
+    const isArrowUp = e.key === 'ArrowUp' || e.keyCode === 38;
+    const isEnter = e.key === 'Enter' || e.keyCode === 13;
+    const isEscape = e.key === 'Escape' || e.keyCode === 27;
+
+    if (isArrowDown) {
+      e.preventDefault();
+      setActiveIndex((i) => (i + 1) % rowCount);
+    } else if (isArrowUp) {
+      e.preventDefault();
+      setActiveIndex((i) => (i <= 0 ? rowCount - 1 : i - 1));
+    } else if (isEnter) {
+      e.preventDefault();
+      commitIndex(activeIndex === -1 ? 0 : activeIndex);
+    } else if (isEscape) {
+      close();
+    }
+  }
+
+  const trigger = (
+    <input
+      ref={inputRef}
+      id={inputId}
+      type="text"
+      role="combobox"
+      aria-expanded={open}
+      aria-controls={listId}
+      aria-autocomplete="list"
+      aria-activedescendant={activeIndex >= 0 ? `${listId}-option-${activeIndex}` : undefined}
+      aria-label={ariaLabel}
+      className={[styles.input, className].filter(Boolean).join(' ')}
+      value={value}
+      placeholder={placeholder}
+      disabled={disabled}
+      autoComplete="off"
+      onChange={(e) => {
+        onChange(e.target.value);
+        setActiveIndex(-1);
+      }}
+      onFocus={() => setFocused(true)}
+      onKeyDown={handleKeyDown}
+    />
+  );
+
+  return (
+    <Popover
+      trigger={trigger}
+      open={open}
+      onClose={close}
+      width="trigger"
+      aria-label={`${ariaLabel} suggestions`}
+    >
+      <ul id={listId} role="listbox" className={styles.list}>
+        {loading ? (
+          <li className={styles.status}>Loading…</li>
+        ) : (
+          <>
+            {options.map((option, index) => (
+              <li key={option.id} role="none">
+                <button
+                  id={`${listId}-option-${index}`}
+                  role="option"
+                  aria-selected={index === activeIndex}
+                  type="button"
+                  className={[styles.option, index === activeIndex ? styles.optionActive : '']
+                    .filter(Boolean)
+                    .join(' ')}
+                  // Selecting via mouse fires before the input's blur — use
+                  // onMouseDown (not onClick) so the click doesn't lose focus
+                  // and close the popover before the selection registers.
+                  onMouseDown={(e) => {
+                    e.preventDefault();
+                    commitIndex(index);
+                  }}
+                >
+                  {option.icon && <span className={styles.optionIcon}>{option.icon}</span>}
+                  <span className={styles.optionLabel}>{option.label}</span>
+                  {option.meta && <span className={styles.optionMeta}>{option.meta}</span>}
+                </button>
+              </li>
+            ))}
+            {showCreateRow && createLabel && (
+              <li role="none">
+                {options.length > 0 && <div className={styles.divider} />}
+                <button
+                  id={`${listId}-option-${options.length}`}
+                  role="option"
+                  aria-selected={options.length === activeIndex}
+                  type="button"
+                  className={[
+                    styles.option,
+                    styles.optionCreate,
+                    options.length === activeIndex ? styles.optionActive : '',
+                  ]
+                    .filter(Boolean)
+                    .join(' ')}
+                  onMouseDown={(e) => {
+                    e.preventDefault();
+                    commitIndex(options.length);
+                  }}
+                >
+                  {createLabel(value)}
+                </button>
+              </li>
+            )}
+          </>
+        )}
+      </ul>
+    </Popover>
+  );
+}

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,10 +71,29 @@ 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';
 export type { DatePickerProps } from './components/DatePicker/DatePicker';
-export { useLongPress, useDoubleTapHandler, useSingleOrDoubleTap, useIsMobile } from './hooks';
+export { SuggestionInput } from './components/SuggestionInput/SuggestionInput';
+export type {
+  SuggestionInputProps,
+  SuggestionOption,
+} from './components/SuggestionInput/SuggestionInput';
+export { IconPicker } from './components/IconPicker/IconPicker';
+export type { IconPickerProps } from './components/IconPicker/IconPicker';
+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,
+  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

@@ -10,12 +10,17 @@ import { Drawer } from '../components/Drawer/Drawer';
 import { EmptyState } from '../components/EmptyState/EmptyState';
 import { FormField } from '../components/FormField/FormField';
 import { Icon } from '../components/Icon/Icon';
+import type { IconName } from '../components/Icon/Icon';
+import { IconPicker } from '../components/IconPicker/IconPicker';
+import { QuantityStepper } from '../components/QuantityStepper/QuantityStepper';
+import { CheckableListRow } from '../components/CheckableListRow/CheckableListRow';
 import { Input } from '../components/Input/Input';
 import { CodeTextarea } from '../components/CodeTextarea/CodeTextarea';
 import { Textarea } from '../components/Textarea/Textarea';
 import { StatusBadge } from '../components/StatusBadge/StatusBadge';
 import { SplitPane } from '../components/SplitPane/SplitPane';
 import { TagInput } from '../components/TagInput/TagInput';
+import { SuggestionInput } from '../components/SuggestionInput/SuggestionInput';
 import { NavTabs } from '../components/NavTabs/NavTabs';
 import { PageHeader } from '../components/PageHeader/PageHeader';
 import { Popover } from '../components/Popover/Popover';
@@ -29,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';
@@ -730,6 +736,85 @@ function TagInputDemo() {
   return <TagInput value={tags} onChange={setTags} aria-label="Tags" />;
 }
 
+function QuantityStepperDemo() {
+  const [value, setValue] = useState(6);
+  return <QuantityStepper value={value} onChange={setValue} unit="pcs" aria-label="Quantity" />;
+}
+
+function CheckableListRowDemo() {
+  const [checked, setChecked] = useState(false);
+  return (
+    <div style={{ width: '100%' }}>
+      <CheckableListRow
+        checked={checked}
+        onCheckedChange={setChecked}
+        label="Bananas"
+        icon={<Icon name="banana" size="md" aria-hidden />}
+        trailing={<span style={{ fontSize: 13, color: 'var(--sv-color-text-muted)' }}>6 pcs</span>}
+      />
+    </div>
+  );
+}
+
+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[] = [
+    'banana',
+    'apple',
+    'carrot',
+    'egg',
+    'milk',
+    'beef',
+    'drumstick',
+    'fish',
+    'croissant',
+    'cookie',
+  ];
+  return (
+    <IconPicker
+      value={value}
+      onChange={setValue}
+      options={options}
+      aria-label="Item icon"
+      triggerLabel={value ?? 'Choose icon'}
+    />
+  );
+}
+
+function SuggestionInputDemo() {
+  const [value, setValue] = useState('ban');
+  const options = ['Bananas', 'Banana bread mix']
+    .filter((label) => label.toLowerCase().includes(value.trim().toLowerCase()))
+    .map((label, i) => ({ id: String(i), label }));
+  return (
+    <SuggestionInput
+      value={value}
+      onChange={setValue}
+      options={value.trim() ? options : []}
+      onSelect={(o) => setValue(o.label)}
+      placeholder="Add an item…"
+      aria-label="Add an item"
+      createLabel={(v) => `Add "${v}" as a new item`}
+      onCreate={setValue}
+    />
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Main component
 // ---------------------------------------------------------------------------
@@ -1429,6 +1514,35 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               <TagInputDemo />
             </ComponentCard>
 
+            {/* SuggestionInput */}
+            <ComponentCard
+              name="SuggestionInput"
+              importLine="import { SuggestionInput } from '@sovereignfs/ui';"
+              usage="Text field with an anchored, keyboard-navigable async suggestion list, plus an optional trailing 'create new' row. Built on Popover."
+            >
+              <div style={{ width: '100%' }}>
+                <SuggestionInputDemo />
+              </div>
+            </ComponentCard>
+
+            {/* IconPicker */}
+            <ComponentCard
+              name="IconPicker"
+              importLine="import { IconPicker } from '@sovereignfs/ui';"
+              usage="Trigger button + Popover grid for a curated, bounded icon set (e.g. a plugin's category icons) — not the full icon library."
+            >
+              <IconPickerDemo />
+            </ComponentCard>
+
+            {/* QuantityStepper */}
+            <ComponentCard
+              name="QuantityStepper"
+              importLine="import { QuantityStepper } from '@sovereignfs/ui';"
+              usage="Numeric input with +/- buttons and an optional read-only unit suffix. Supports fractional step values (e.g. 0.5 kg)."
+            >
+              <QuantityStepperDemo />
+            </ComponentCard>
+
             {/* Select */}
             <ComponentCard
               name="Select"
@@ -1484,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."
             >
               {(
                 [
@@ -1497,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 />
@@ -1798,6 +1913,15 @@ font-weight: var(--sv-font-weight-bold);      /* 700 */`}</Code>
               </div>
             </ComponentCard>
 
+            {/* CheckableListRow */}
+            <ComponentCard
+              name="CheckableListRow"
+              importLine="import { CheckableListRow } from '@sovereignfs/ui';"
+              usage="Whole-row tap target that toggles a checked state, with strike-through on the label — for 'tap the row to mark it done' lists (not a form checkbox)."
+            >
+              <CheckableListRowDemo />
+            </ComponentCard>
+
             {/* Checkbox */}
             <ComponentCard
               name="Checkbox"
@@ -1839,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"