@sovereignfs/ui 0.33.1 → 0.37.0

package/src/components/QuantityStepper/QuantityStepper.tsx

@@ -0,0 +1,107 @@
+'use client';
+
+import { useId, type ChangeEvent } from 'react';
+import styles from './QuantityStepper.module.css';
+
+export interface QuantityStepperProps {
+  value: number;
+  onChange: (value: number) => void;
+  /** Smallest selectable value. Default `0`. */
+  min?: number;
+  /** Largest selectable value. Default unbounded. */
+  max?: number;
+  /** Amount +/- adjusts by. Default `1` — pass e.g. `0.5` for fractional
+   *  quantities (kg, L). */
+  step?: number;
+  /** Read-only suffix shown after the number, e.g. "pcs" or "kg" — for
+   *  compact contexts (a list row) where a separate unit selector doesn't
+   *  fit. Editable unit selection (a `<Select>` of units) lives outside
+   *  this component. */
+  unit?: string;
+  'aria-label': string;
+  disabled?: boolean;
+  id?: string;
+  className?: string;
+}
+
+/**
+ * QuantityStepper — a numeric input with +/- buttons and an optional
+ * read-only unit suffix. Built for grocery/inventory-style quantities
+ * (Sovereign Shopper, SHP-06) — supports fractional `step` values since
+ * quantities like "1.5 kg" are common, unlike a typical integer counter.
+ *
+ * The middle field is a real `<input type="number">` so keyboard entry,
+ * paste, and the browser's native numeric affordances all work — the
+ * buttons are a convenience on top, not the only way to change the value.
+ */
+export function QuantityStepper({
+  value,
+  onChange,
+  min = 0,
+  max,
+  step = 1,
+  unit,
+  'aria-label': ariaLabel,
+  disabled = false,
+  id,
+  className,
+}: QuantityStepperProps) {
+  const generatedId = useId();
+  const inputId = id ?? generatedId;
+
+  function clamp(next: number): number {
+    let result = next;
+    if (min !== undefined) result = Math.max(min, result);
+    if (max !== undefined) result = Math.min(max, result);
+    // Avoid float drift (0.1 + 0.2 style errors) from repeated +/- clicks.
+    return Math.round(result * 1000) / 1000;
+  }
+
+  function handleInputChange(e: ChangeEvent<HTMLInputElement>) {
+    const parsed = Number.parseFloat(e.target.value);
+    if (!Number.isNaN(parsed)) onChange(clamp(parsed));
+  }
+
+  const decrementDisabled = disabled || (min !== undefined && value <= min);
+  const incrementDisabled = disabled || (max !== undefined && value >= max);
+
+  return (
+    <div className={[styles.root, className].filter(Boolean).join(' ')}>
+      <button
+        type="button"
+        className={styles.button}
+        onClick={() => onChange(clamp(value - step))}
+        disabled={decrementDisabled}
+        aria-label={`Decrease ${ariaLabel}`}
+      >
+        −
+      </button>
+      <input
+        id={inputId}
+        type="number"
+        className={styles.input}
+        value={value}
+        onChange={handleInputChange}
+        min={min}
+        max={max}
+        step={step}
+        disabled={disabled}
+        aria-label={ariaLabel}
+      />
+      {unit && (
+        <span className={styles.unit} aria-hidden>
+          {unit}
+        </span>
+      )}
+      <button
+        type="button"
+        className={styles.button}
+        onClick={() => onChange(clamp(value + step))}
+        disabled={incrementDisabled}
+        aria-label={`Increase ${ariaLabel}`}
+      >
+        +
+      </button>
+    </div>
+  );
+}

package/src/components/SuggestionInput/SuggestionInput.module.css

@@ -0,0 +1,103 @@
+.input {
+  display: block;
+  width: 100%;
+  padding: var(--sv-space-2) var(--sv-space-3);
+  font-family: var(--sv-font-family);
+  font-size: var(--sv-font-size-sm);
+  line-height: 1.5;
+  color: var(--sv-color-text-primary);
+  background-color: var(--sv-color-surface);
+  border: 1px solid var(--sv-color-border-strong);
+  border-radius: var(--sv-radius-md);
+  transition:
+    border-color 0.15s ease,
+    box-shadow 0.15s ease;
+}
+
+/* iOS Safari auto-zooms on focused inputs under 16px — see Input.module.css
+   for the full rationale; kept in sync here since this isn't built on Input. */
+@media (pointer: coarse) {
+  .input {
+    font-size: var(--sv-font-size-md);
+  }
+}
+
+.input::placeholder {
+  color: var(--sv-color-text-muted);
+}
+
+.input:focus-visible {
+  outline: none;
+  border-color: var(--sv-color-accent);
+  box-shadow: 0 0 0 2px var(--sv-color-focus-ring);
+}
+
+.input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.list {
+  list-style: none;
+  margin: 0;
+  padding: var(--sv-space-1);
+  max-height: 320px;
+  overflow-y: auto;
+}
+
+.status {
+  padding: var(--sv-space-2) var(--sv-space-3);
+  font-size: var(--sv-font-size-sm);
+  color: var(--sv-color-text-muted);
+}
+
+.option {
+  display: flex;
+  align-items: center;
+  gap: var(--sv-space-2);
+  width: 100%;
+  padding: var(--sv-space-2) var(--sv-space-3);
+  border: none;
+  border-radius: var(--sv-radius-sm);
+  background: transparent;
+  font-family: var(--sv-font-family);
+  font-size: var(--sv-font-size-sm);
+  color: var(--sv-color-text-primary);
+  text-align: left;
+  cursor: pointer;
+}
+
+.option:hover,
+.optionActive {
+  background: var(--sv-color-surface-sunken);
+}
+
+.optionIcon {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.optionLabel {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.optionMeta {
+  flex-shrink: 0;
+  font-size: var(--sv-font-size-xs);
+  color: var(--sv-color-text-subtle);
+}
+
+.optionCreate {
+  font-style: italic;
+  color: var(--sv-color-text-muted);
+}
+
+.divider {
+  margin: var(--sv-space-1) var(--sv-space-2);
+  border-top: 1px solid var(--sv-color-border);
+}

package/src/components/SuggestionInput/SuggestionInput.stories.tsx

@@ -0,0 +1,144 @@
+import { useMemo, useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { SuggestionInput, type SuggestionOption } from './SuggestionInput';
+
+const meta = {
+  title: 'Components/SuggestionInput',
+  component: SuggestionInput,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'A text field with an anchored, keyboard-navigable list of async suggestions, plus an optional trailing "create new" row so free text is always a valid commit.',
+      },
+    },
+  },
+  args: {
+    value: '',
+    onChange: () => {},
+    options: [],
+    onSelect: () => {},
+    'aria-label': 'Add an item',
+  },
+} satisfies Meta<typeof SuggestionInput>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const CATALOG: SuggestionOption[] = [
+  { id: '1', label: 'Bananas', icon: '🍌', meta: 'bought 4× recently' },
+  { id: '2', label: 'Banana bread mix', icon: '🍞' },
+  { id: '3', label: 'Milk', icon: '🥛' },
+  { id: '4', label: 'Eggs', icon: '🥚' },
+  { id: '5', label: 'Olive oil', icon: '🫒' },
+];
+
+function ControlledSuggestionInput({ withCreateRow = true }: { withCreateRow?: boolean }) {
+  const [value, setValue] = useState('');
+  const [selected, setSelected] = useState<string | null>(null);
+  const options = useMemo(
+    () =>
+      value.trim()
+        ? CATALOG.filter((c) => c.label.toLowerCase().includes(value.trim().toLowerCase()))
+        : [],
+    [value],
+  );
+
+  return (
+    <div style={{ width: 320 }}>
+      <SuggestionInput
+        value={value}
+        onChange={setValue}
+        options={options}
+        onSelect={(option) => {
+          setSelected(option.label);
+          setValue('');
+        }}
+        placeholder="Add an item…"
+        aria-label="Add an item"
+        createLabel={withCreateRow ? (v) => `Add "${v}" as a new item` : undefined}
+        onCreate={
+          withCreateRow
+            ? (v) => {
+                setSelected(v);
+                setValue('');
+              }
+            : undefined
+        }
+      />
+      {selected && <p style={{ marginTop: 12, fontSize: 13 }}>Added: {selected}</p>}
+    </div>
+  );
+}
+
+export const Default: Story = {
+  render: () => <ControlledSuggestionInput />,
+};
+
+export const NoCreateRow: Story = {
+  name: 'Without create row (matched options only)',
+  render: () => <ControlledSuggestionInput withCreateRow={false} />,
+};
+
+export const OpenWithOptions: Story = {
+  render: () => (
+    <div style={{ width: 320 }}>
+      <SuggestionInput
+        value="ban"
+        onChange={() => {}}
+        options={CATALOG.slice(0, 2)}
+        onSelect={() => {}}
+        aria-label="Add an item"
+        createLabel={(v) => `Add "${v}" as a new item`}
+        onCreate={() => {}}
+      />
+    </div>
+  ),
+};
+
+export const Loading: Story = {
+  render: () => (
+    <div style={{ width: 320 }}>
+      <SuggestionInput
+        value="ban"
+        onChange={() => {}}
+        options={[]}
+        onSelect={() => {}}
+        loading
+        aria-label="Add an item"
+      />
+    </div>
+  ),
+};
+
+export const Empty: Story = {
+  name: 'Empty (no matches, no create row)',
+  render: () => (
+    <div style={{ width: 320 }}>
+      <SuggestionInput
+        value="xyz"
+        onChange={() => {}}
+        options={[]}
+        onSelect={() => {}}
+        aria-label="Add an item"
+      />
+    </div>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div style={{ width: 320 }}>
+      <SuggestionInput
+        value=""
+        onChange={() => {}}
+        options={[]}
+        onSelect={() => {}}
+        disabled
+        placeholder="Add an item…"
+        aria-label="Add an item"
+      />
+    </div>
+  ),
+};

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/index.ts

@@ -75,6 +75,17 @@ 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 { 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 } from './hooks';
 export { MOBILE_BREAKPOINT_PX } from './hooks';
 export type { UseLongPressOptions, LongPressHandlers } from './hooks';