@lovett/ui 0.0.10 → 0.1.0

package/src/select.tsx

@@ -0,0 +1,646 @@
+/**
+ * Select — a single-value picker: a button that opens a real listbox.
+ *
+ * WAI-ARIA APG "select-only combobox": the trigger is `role="combobox"`
+ * with `aria-haspopup="listbox"`, the popup is `role="listbox"` of
+ * `role="option"` rows with `aria-selected`. DOM focus STAYS on the trigger
+ * while the list is open; the highlighted row is announced through the
+ * trigger's `aria-activedescendant`, and a mousedown inside the listbox is
+ * prevented so a click never pulls focus out of the trigger. The trigger
+ * wears the `.input-shell` chrome at the `sm` / `md` control heights, so a
+ * Select sits flush beside an `<Input>` in the same form row.
+ *
+ * Keyboard, closed: ArrowDown / ArrowUp / Enter / Space open with the
+ * selected option highlighted; Home / End open on the first / last option;
+ * a printable character opens and type-ahead jumps to the first label that
+ * starts with it. Open: ArrowDown / ArrowUp move the highlight (no wrap;
+ * disabled options are skipped), Home / End jump, Enter / Space commit,
+ * type-ahead (a repeated letter cycles through its matches, a typed prefix
+ * narrows), Escape closes without changing the value. Tab closes WITHOUT
+ * committing — a deliberate departure from the APG example, because in a
+ * data-editing table an accidental write on Tab is the worse failure.
+ *
+ * Promoted per ADR-0030 Decision G (meta-ads-audit-dashboard task manager:
+ * status / priority / role pickers in the table, sheet and modal; that
+ * repo's `client/src/pages/Users.tsx` hand-rolled a native `<select>` with a
+ * comment saying the package ships none — this replaces it). Second
+ * consumer is the workspace app, which has 26 native `<select>`s today,
+ * among them `lenses/products/product-form.tsx`, whose header says the same
+ * thing. FilterDropdown stays a sibling: it is a pill-shaped FILTER chip
+ * ("Platform: Facebook") with a neutral value, not a form control.
+ *
+ * Token discipline: the trigger is `.input-shell` (styles.css owns the
+ * INTERNAL `--bg-input` / `--border-input`); the listbox shares
+ * `POPOVER_SURFACE_STYLE` with Popover and DropdownMenu; option hover is
+ * public `--surface-overlay`, the check mark public `--accent`, secondary
+ * text `--text-tertiary` / `--text-muted`. Geometry comes from
+ * `useAnchoredPosition` (the list flips above the trigger at the bottom of
+ * the viewport); motion is `.ds-enter-pop` gated on `positioned`, which
+ * honours prefers-reduced-motion in styles.css. Escape goes through the
+ * shared layer stack, so a Select inside a Popover inside a Modal peels one
+ * layer per keypress.
+ *
+ * TODO(tokens): the type literals (`text-[12.5px]` / `text-[13.5px]` value,
+ * `text-[13px]` / `text-[11.5px]` rows, `max-h-[min(60vh,20rem)]`) mirror
+ * `.input-shell` and dropdown-menu.tsx and sit off the spacing scale; snap
+ * them once a type-scale token exists (review 2026-09-05, MINOR).
+ *
+ * Usage:
+ *
+ *   <Select
+ *     aria-label="Status"
+ *     value={status}
+ *     onValueChange={setStatus}
+ *     options={[
+ *       { value: 'todo', label: 'To do', icon: <Circle className="h-3.5 w-3.5" /> },
+ *       { value: 'doing', label: 'In progress', description: 'Actively being worked' },
+ *       { value: 'done', label: 'Done', disabled: !canClose },
+ *     ]}
+ *   />
+ *
+ *   <Select size="sm" placeholder="Assignee…" defaultValue={null} options={people} />
+ */
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactElement,
+  type ReactNode,
+  type RefAttributes,
+} from 'react'
+import { createPortal } from 'react-dom'
+import { Check, ChevronDown } from 'lucide-react'
+import { cn } from './lib/utils'
+import { composeRefs } from './lib/refs'
+import { useLayer } from './lib/layer-stack'
+import {
+  useAnchoredPosition,
+  useOutsideClick,
+  type AnchorAlign,
+  type AnchorSide,
+} from './lib/anchor'
+import { POPOVER_SURFACE_STYLE } from './popover'
+
+export type SelectSize = 'sm' | 'md'
+
+export interface SelectOption<T extends string = string> {
+  value: T
+  label: string
+  /** Secondary line under the label. */
+  description?: string
+  /** Leading adornment — a Lucide icon, an avatar, a colour dot. */
+  icon?: ReactNode
+  /** Rendered but not selectable; skipped by the arrow keys and type-ahead. */
+  disabled?: boolean
+}
+
+export interface SelectProps<T extends string = string>
+  extends Omit<
+    ButtonHTMLAttributes<HTMLButtonElement>,
+    'value' | 'defaultValue' | 'onChange' | 'role'
+  > {
+  options: ReadonlyArray<SelectOption<T>>
+  /** Controlled value; `null` = nothing selected. Omit for internal state. */
+  value?: T | null
+  defaultValue?: T | null
+  /** Fires when the user picks a DIFFERENT option. */
+  onValueChange?: (value: T) => void
+  /** Shown while nothing is selected. Default "Select…". */
+  placeholder?: string
+  /** Control height — matches `<Input inputSize>`. Default `md`. */
+  size?: SelectSize
+  /** Error chrome (`is-error`) + `aria-invalid` on the trigger. A caller's own `aria-invalid` wins. */
+  error?: boolean
+  /** Controlled open state. Omit for internal state. */
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** Preferred side for the listbox. Default `bottom`; flips when it cannot fit. */
+  side?: AnchorSide
+  /** Alignment along the trigger's edge. Default `start`. */
+  align?: AnchorAlign
+  /** Extra classes on the listbox surface. */
+  listboxClassName?: string
+}
+
+const SHELL_SIZE_CLASS: Record<SelectSize, string> = {
+  sm: 'size-sm',
+  md: '',
+}
+
+/** Mirrors `.input-shell input` / `.input-shell.size-sm input` typography. */
+const VALUE_SIZE_CLASS: Record<SelectSize, string> = {
+  sm: 'gap-2 pl-2.5 text-[12.5px]',
+  md: 'gap-2 pl-3 text-[13.5px]',
+}
+
+/**
+ * The listbox popup chrome, shared with Combobox so the two lists read as
+ * one family (Popover / DropdownMenu share `POPOVER_SURFACE_STYLE` the same
+ * way).
+ */
+export const LISTBOX_CLASS =
+  'fixed z-[100] max-h-[min(60vh,20rem)] overflow-y-auto rounded-[var(--radius-lg)] p-1.5 outline-none'
+
+/** Type-ahead buffer lifetime: a pause this long starts a fresh search. */
+const TYPEAHEAD_RESET_MS = 500
+
+function isPrintableKey(event: ReactKeyboardEvent): boolean {
+  return event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey
+}
+
+function sanitizeId(id: string): string {
+  return id.replace(/[^a-zA-Z0-9_-]/g, '')
+}
+
+export interface ListboxOptionProps {
+  id: string
+  label: string
+  description?: string | undefined
+  icon?: ReactNode
+  /** Trailing count — tabular, muted. */
+  count?: number | undefined
+  selected: boolean
+  highlighted: boolean
+  disabled?: boolean | undefined
+  onSelect: () => void
+  onHighlight: () => void
+  /** Replaces the default body (icon / label / description / count). The check mark stays. */
+  children?: ReactNode
+}
+
+/**
+ * One row of a listbox — used by Select and Combobox. A `<button>` rather
+ * than a `<div role="option">` so it is clickable without a keyboard handler
+ * of its own; `tabIndex={-1}` keeps it out of the tab order (the trigger /
+ * input owns the keyboard, per `aria-activedescendant`). Disabled rows use
+ * `aria-disabled`, NOT the `disabled` attribute: a disabled control swallows
+ * the mousedown the listbox prevents to keep focus on the trigger / in the
+ * input, so clicking one would blur the Combobox and close the list.
+ */
+export function ListboxOption({
+  id,
+  label,
+  description,
+  icon,
+  count,
+  selected,
+  highlighted,
+  disabled,
+  onSelect,
+  onHighlight,
+  children,
+}: ListboxOptionProps) {
+  return (
+    <button
+      type="button"
+      role="option"
+      id={id}
+      aria-selected={selected}
+      aria-disabled={disabled ? true : undefined}
+      tabIndex={-1}
+      data-slot="listbox-option"
+      data-highlighted={highlighted ? '' : undefined}
+      data-selected={selected ? '' : undefined}
+      data-disabled={disabled ? '' : undefined}
+      className={cn(
+        'flex w-full cursor-default items-center gap-2.5 text-left',
+        'rounded-[var(--radius-md)] px-2.5 py-2 text-[13px] font-medium',
+        'outline-none transition-colors',
+        'aria-disabled:pointer-events-none aria-disabled:opacity-50',
+      )}
+      style={{
+        background: highlighted ? 'rgb(var(--surface-overlay))' : 'transparent',
+        color: 'rgb(var(--foreground))',
+      }}
+      onClick={() => {
+        if (!disabled) onSelect()
+      }}
+      // pointermove, not mouseenter: when the arrow keys scroll the list
+      // under a resting pointer, mouseenter fires and steals the highlight.
+      onPointerMove={() => {
+        if (!disabled && !highlighted) onHighlight()
+      }}
+    >
+      {children ?? (
+        <>
+          {icon ? <span className="inline-flex shrink-0 items-center">{icon}</span> : null}
+          <span className="min-w-0 flex-1">
+            <span className="block truncate">{label}</span>
+            {description ? (
+              <span
+                className="block truncate text-[11.5px] font-normal"
+                style={{ color: 'rgb(var(--text-tertiary))' }}
+              >
+                {description}
+              </span>
+            ) : null}
+          </span>
+          {typeof count === 'number' ? (
+            <span
+              className="shrink-0 text-[11px] font-medium tabular-nums"
+              style={{ color: 'rgb(var(--text-muted))' }}
+            >
+              {count.toLocaleString()}
+            </span>
+          ) : null}
+        </>
+      )}
+      {/* Reserved slot, so rows do not shift when the selection moves. */}
+      <span className="inline-flex h-3.5 w-3.5 shrink-0 items-center justify-center" aria-hidden="true">
+        {selected ? (
+          <Check className="h-3.5 w-3.5" style={{ color: 'rgb(var(--accent))' }} />
+        ) : null}
+      </span>
+    </button>
+  )
+}
+
+const SelectImpl = forwardRef<HTMLButtonElement, SelectProps<string>>(function Select(
+  {
+    options,
+    value: valueProp,
+    defaultValue = null,
+    onValueChange,
+    placeholder = 'Select…',
+    size = 'md',
+    error,
+    open: openProp,
+    defaultOpen,
+    onOpenChange,
+    side = 'bottom',
+    align = 'start',
+    listboxClassName,
+    id,
+    className,
+    style,
+    disabled,
+    onClick,
+    onKeyDown,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledby,
+    ...rest
+  },
+  forwardedRef,
+) {
+  const [uncontrolledValue, setUncontrolledValue] = useState<string | null>(defaultValue)
+  const isControlledValue = valueProp !== undefined
+  const value = isControlledValue ? valueProp : uncontrolledValue
+
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(Boolean(defaultOpen))
+  const isControlledOpen = openProp !== undefined
+  const open = isControlledOpen ? Boolean(openProp) : uncontrolledOpen
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!isControlledOpen) setUncontrolledOpen(next)
+      onOpenChange?.(next)
+    },
+    [isControlledOpen, onOpenChange],
+  )
+
+  const triggerRef = useRef<HTMLButtonElement | null>(null)
+  const listboxRef = useRef<HTMLDivElement | null>(null)
+
+  const baseId = sanitizeId(useId())
+  const triggerId = id ?? `select-${baseId}`
+  const listboxId = `select-listbox-${baseId}`
+  const optionId = (index: number) => `${listboxId}-opt-${index}`
+
+  const selectedIndex = useMemo(
+    () => options.findIndex((option) => option.value === value),
+    [options, value],
+  )
+  const selected = selectedIndex >= 0 ? options[selectedIndex] : undefined
+  const firstEnabled = options.findIndex((option) => !option.disabled)
+  let lastEnabled = -1
+  for (let i = options.length - 1; i >= 0; i--) {
+    if (!options[i]?.disabled) {
+      lastEnabled = i
+      break
+    }
+  }
+
+  // `null` = "no explicit highlight yet": the selected option, else the
+  // first enabled one. Reset on every open so a stale index never survives
+  // a controlled close.
+  const [highlight, setHighlight] = useState<number | null>(null)
+  const activeIndex =
+    highlight !== null && highlight < options.length
+      ? highlight
+      : selectedIndex >= 0
+        ? selectedIndex
+        : firstEnabled
+
+  const openList = useCallback(
+    (initial: number | null) => {
+      setHighlight(initial)
+      setOpen(true)
+    },
+    [setOpen],
+  )
+  const closeList = useCallback(() => {
+    setOpen(false)
+    setHighlight(null)
+  }, [setOpen])
+
+  const commit = (index: number) => {
+    const option = options[index]
+    if (!option || option.disabled) return
+    if (option.value !== value) {
+      if (!isControlledValue) setUncontrolledValue(option.value)
+      onValueChange?.(option.value)
+    }
+    closeList()
+    triggerRef.current?.focus()
+  }
+
+  /** Next enabled index in `direction`, or `from` when there is none. */
+  const step = (from: number, direction: 1 | -1): number => {
+    for (let i = from + direction; i >= 0 && i < options.length; i += direction) {
+      if (!options[i]?.disabled) return i
+    }
+    return from
+  }
+
+  const typeaheadRef = useRef<{ text: string; timer: number | null }>({ text: '', timer: null })
+  useEffect(() => {
+    const state = typeaheadRef.current
+    return () => {
+      if (state.timer !== null) window.clearTimeout(state.timer)
+    }
+  }, [])
+
+  /** APG type-ahead: repeated letters cycle through their matches, a prefix narrows. */
+  const typeahead = (char: string, from: number): number | null => {
+    const state = typeaheadRef.current
+    if (state.timer !== null) window.clearTimeout(state.timer)
+    state.text += char.toLowerCase()
+    state.timer = window.setTimeout(() => {
+      state.text = ''
+      state.timer = null
+    }, TYPEAHEAD_RESET_MS)
+
+    const typed = state.text
+    const first = typed.charAt(0)
+    const repeated = typed.length > 1 && typed.split('').every((c) => c === first)
+    const needle = repeated ? first : typed
+    const count = options.length
+    if (count === 0) return null
+    const startAt = needle.length === 1 ? from + 1 : Math.max(from, 0)
+    for (let k = 0; k < count; k++) {
+      const i = (startAt + k) % count
+      const option = options[i]
+      if (option && !option.disabled && option.label.toLowerCase().startsWith(needle)) return i
+    }
+    return null
+  }
+
+  const handleKeyDown = (event: ReactKeyboardEvent<HTMLButtonElement>) => {
+    onKeyDown?.(event)
+    if (event.defaultPrevented) return
+    const { key } = event
+
+    if (!open) {
+      if (key === 'ArrowDown' || key === 'ArrowUp' || key === 'Enter' || key === ' ') {
+        event.preventDefault()
+        openList(null)
+        return
+      }
+      if (key === 'Home' || key === 'End') {
+        event.preventDefault()
+        openList(key === 'Home' ? firstEnabled : lastEnabled)
+        return
+      }
+      if (isPrintableKey(event)) {
+        event.preventDefault()
+        openList(typeahead(key, selectedIndex))
+      }
+      return
+    }
+
+    switch (key) {
+      case 'ArrowDown':
+        event.preventDefault()
+        setHighlight(step(activeIndex, 1))
+        return
+      case 'ArrowUp':
+        event.preventDefault()
+        setHighlight(step(activeIndex, -1))
+        return
+      case 'Home':
+        event.preventDefault()
+        setHighlight(firstEnabled)
+        return
+      case 'End':
+        event.preventDefault()
+        setHighlight(lastEnabled)
+        return
+      case 'Enter':
+      case ' ':
+        event.preventDefault()
+        commit(activeIndex)
+        return
+      case 'Tab':
+        // Close without committing; let focus move on.
+        closeList()
+        return
+      case 'Escape':
+        // The shared layer stack answers Escape (topmost layer only).
+        return
+      default:
+        if (isPrintableKey(event)) {
+          event.preventDefault()
+          const match = typeahead(key, activeIndex)
+          if (match !== null) setHighlight(match)
+        }
+    }
+  }
+
+  const {
+    ref: positionRef,
+    style: positionStyle,
+    placement,
+    positioned,
+  } = useAnchoredPosition<HTMLDivElement>({
+    anchorRef: triggerRef,
+    side,
+    align,
+    enabled: open,
+  })
+
+  const layer = useLayer({
+    enabled: open,
+    kind: 'popover',
+    elementRef: listboxRef,
+    onEscape: () => {
+      closeList()
+      triggerRef.current?.focus()
+    },
+  })
+
+  useOutsideClick([triggerRef, listboxRef], closeList, { enabled: open, layer })
+
+  // The list is at least as wide as its trigger, like a native select.
+  const [triggerWidth, setTriggerWidth] = useState<number | null>(null)
+  useLayoutEffect(() => {
+    if (!open) return
+    setTriggerWidth(triggerRef.current?.offsetWidth ?? null)
+  }, [open])
+
+  useEffect(() => {
+    if (!open) return
+    listboxRef.current
+      ?.querySelector<HTMLElement>('[data-highlighted]')
+      ?.scrollIntoView({ block: 'nearest' })
+  }, [open, activeIndex])
+
+  const triggerRefs = useMemo(
+    () => composeRefs<HTMLButtonElement>(forwardedRef, triggerRef),
+    [forwardedRef],
+  )
+  const listboxRefs = useMemo(
+    () => composeRefs<HTMLDivElement>(listboxRef, positionRef),
+    [positionRef],
+  )
+
+  return (
+    <>
+      <button
+        ref={triggerRefs}
+        id={triggerId}
+        type="button"
+        role="combobox"
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        aria-controls={open ? listboxId : undefined}
+        aria-activedescendant={open && activeIndex >= 0 ? optionId(activeIndex) : undefined}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledby}
+        aria-invalid={error ? true : undefined}
+        disabled={disabled}
+        data-slot="select-trigger"
+        data-state={open ? 'open' : 'closed'}
+        data-size={size}
+        data-placeholder={selected ? undefined : ''}
+        className={cn(
+          'input-shell appearance-none p-0 text-left',
+          SHELL_SIZE_CLASS[size],
+          error && 'is-error',
+          disabled && 'is-disabled',
+          className,
+        )}
+        // `.input-shell` is unlayered CSS and sets `align-items: stretch`;
+        // a (layered) Tailwind utility cannot override it, so the one
+        // override is inline. Caller style spreads last.
+        style={{ alignItems: 'center', ...style }}
+        onClick={(event) => {
+          onClick?.(event)
+          if (event.defaultPrevented) return
+          if (open) closeList()
+          else openList(null)
+        }}
+        onKeyDown={handleKeyDown}
+        {...rest}
+      >
+        <span
+          data-slot="select-value"
+          className={cn(
+            'flex min-w-0 flex-1 items-center font-medium leading-[1.4]',
+            VALUE_SIZE_CLASS[size],
+          )}
+        >
+          {selected?.icon ? (
+            <span className="inline-flex shrink-0 items-center">{selected.icon}</span>
+          ) : null}
+          <span
+            className="truncate"
+            style={{
+              color: selected ? 'rgb(var(--foreground))' : 'rgb(var(--text-tertiary))',
+            }}
+          >
+            {selected ? selected.label : placeholder}
+          </span>
+        </span>
+        <span className="affix" aria-hidden="true">
+          <ChevronDown
+            className={cn(
+              'h-4 w-4 transition-transform duration-[var(--dur-fast)] ease-[var(--ease-out)] motion-reduce:transition-none',
+              open && 'rotate-180',
+            )}
+          />
+        </span>
+      </button>
+
+      {open && typeof document !== 'undefined'
+        ? createPortal(
+            <div
+              ref={listboxRefs}
+              id={listboxId}
+              role="listbox"
+              aria-label={ariaLabelledby ? undefined : ariaLabel}
+              aria-labelledby={ariaLabelledby ?? (ariaLabel ? undefined : triggerId)}
+              tabIndex={-1}
+              data-slot="select-listbox"
+              data-state="open"
+              data-side={placement?.side}
+              data-align={placement?.align}
+              data-positioned={positioned ? 'true' : 'false'}
+              className={cn(LISTBOX_CLASS, positioned && 'ds-enter-pop', listboxClassName)}
+              style={{
+                ...positionStyle,
+                ...POPOVER_SURFACE_STYLE,
+                ...(triggerWidth ? { minWidth: triggerWidth } : undefined),
+              }}
+              // Keep DOM focus on the trigger: a click in the list must not
+              // blur it (the keyboard model lives there).
+              onMouseDown={(event) => event.preventDefault()}
+            >
+              {options.length === 0 ? (
+                <div
+                  data-slot="select-empty"
+                  className="px-2.5 py-2 text-[12.5px]"
+                  style={{ color: 'rgb(var(--text-tertiary))' }}
+                >
+                  No options
+                </div>
+              ) : (
+                options.map((option, index) => (
+                  <ListboxOption
+                    key={option.value}
+                    id={optionId(index)}
+                    label={option.label}
+                    description={option.description}
+                    icon={option.icon}
+                    selected={option.value === value}
+                    highlighted={index === activeIndex}
+                    disabled={option.disabled}
+                    onSelect={() => commit(index)}
+                    onHighlight={() => setHighlight(index)}
+                  />
+                ))
+              )}
+            </div>,
+            document.body,
+          )
+        : null}
+    </>
+  )
+})
+
+/**
+ * `forwardRef` erases the component's type parameter (it is instantiated at
+ * `string` above). This assertion restores the generic signature so
+ * `onValueChange` narrows to the union of the option values a caller
+ * passed; it changes nothing at runtime.
+ */
+export const Select = SelectImpl as <T extends string = string>(
+  props: SelectProps<T> & RefAttributes<HTMLButtonElement>,
+) => ReactElement | null