@charcuterie/ui 1.0.1 → 2.0.0

package/src/Combobox/Combobox.tsx

@@ -0,0 +1,513 @@
+import {
+  FloatingFocusManager,
+  FloatingPortal,
+} from "@floating-ui/react"
+import { useVirtualizer } from "@tanstack/react-virtual"
+import type { ReactElement, ReactNode } from "react"
+import { useEffect, useRef, useState } from "react"
+
+import type { ListboxItem } from "../Listbox/Listbox.tsx"
+import { PANEL_SURFACE_CLASS } from "../Overlay/overlayPanelClass.ts"
+import { useAnchoredOverlay } from "../Overlay/useAnchoredOverlay.ts"
+import { toClassName } from "../toClassName.ts"
+import { ComboboxOption } from "./ComboboxOption.tsx"
+
+export type ComboboxProps = {
+  className?: string
+  /** Shown when nothing matches. Default "No matches". */
+  emptyLabel?: string
+  /** The error panel state (`PathPicker`). */
+  error?: ReactNode
+  /** A sticky footer hint (`LinkPicker`'s "type a path directly"). */
+  footer?: ReactNode
+  /** Enter commits the raw query as a value (`AssFieldPicker`). */
+  isCreatable?: boolean
+  /** The loading panel state. */
+  isLoading?: boolean
+  /** Multi-select, rendered as removable chips (`LanguageCodeField`). */
+  isMultiple?: boolean
+  /** Windowing. Auto-on above ~100 options when left undefined. */
+  isVirtualized?: boolean
+  isVisible: boolean
+  onDismiss: () => void
+  onSelect: (value: string) => void
+  /**
+   * Omit to filter internally by `textValue`; supply to own the query
+   * (a react-query search, say), in which case `options` arrives
+   * pre-filtered.
+   */
+  onQueryChange?: (query: string) => void
+  options: readonly ListboxItem[]
+  placeholder?: string
+  /** Controlled query; uncontrolled when absent. */
+  query?: string
+  selectedValue?: readonly string[] | string
+  /** The control the popup hangs off. **Cloned, not wrapped.** */
+  trigger: ReactElement
+}
+
+const AUTO_VIRTUALIZE_THRESHOLD = 100
+
+const getOptionText = (item: ListboxItem) =>
+  (
+    item.textValue ??
+    (typeof item.label === "string" ? item.label : "")
+  ).toLowerCase()
+
+const nextEnabledIndex = (
+  options: readonly ListboxItem[],
+  from: number,
+  step: number,
+) => {
+  for (
+    let index = from + step;
+    index >= 0 && index < options.length;
+    index += step
+  ) {
+    if (!options[index]?.isDisabled) {
+      return index
+    }
+  }
+
+  return from
+}
+
+/**
+ * The searchable, filtering, virtualized picker — the other half of
+ * the picker family, and the one that consolidates the fleet's
+ * hand-rolled dropdowns.
+ *
+ * The ARIA contract differs from `Listbox` and the difference is
+ * forced, not stylistic: **focus stays in the text input**, so the
+ * active option is tracked with `aria-activedescendant`, not roving
+ * tabindex. The input is the `role="combobox"`; the popup is a
+ * `role="listbox"`. Arrows move the active descendant while the caret
+ * stays put; Enter selects; Escape clears the query before it closes.
+ *
+ * Filtering is the consumer's when `onQueryChange` is supplied (the
+ * `options` then arrive pre-filtered — a react-query search owns the
+ * debounce, the request token, the cache), and internal on `textValue`
+ * otherwise.
+ */
+export const Combobox = ({
+  className,
+  emptyLabel = "No matches",
+  error,
+  footer,
+  isCreatable = false,
+  isLoading = false,
+  isMultiple = false,
+  isVirtualized,
+  isVisible,
+  onDismiss,
+  onQueryChange,
+  onSelect,
+  options,
+  placeholder = "Search…",
+  query,
+  selectedValue,
+  trigger,
+}: ComboboxProps): ReactNode => {
+  const inputElement = useRef<HTMLInputElement>(null)
+
+  const listElement = useRef<HTMLDivElement>(null)
+
+  const isQueryControlled = query !== undefined
+
+  const [internalQuery, setInternalQuery] = useState("")
+
+  const currentQuery = query ?? internalQuery
+
+  const [activeIndex, setActiveIndex] = useState(0)
+
+  const [selected, setSelected] = useState<string[]>(
+    selectedValue === undefined
+      ? []
+      : typeof selectedValue === "string"
+        ? [selectedValue]
+        : [...selectedValue],
+  )
+
+  // The consumer owns filtering when it owns the query; otherwise it is
+  // a plain `textValue` contains-match.
+  const filtered =
+    onQueryChange === undefined
+      ? options.filter((option) =>
+          getOptionText(option).includes(
+            currentQuery.toLowerCase(),
+          ),
+        )
+      : options
+
+  const isWindowed =
+    isVirtualized ??
+    filtered.length > AUTO_VIRTUALIZE_THRESHOLD
+
+  const {
+    clonedTrigger,
+    context,
+    floatingStyles,
+    getFloatingProps,
+    setFloating,
+    triggerId,
+  } = useAnchoredOverlay({
+    // Escape is handled here so it can clear the query before closing.
+    isEscapeDismissable: false,
+    isVisible,
+    maxHeightPx: 384,
+    offsetValue: 4,
+    onDismiss,
+    role: "listbox",
+    trigger,
+  })
+
+  // The panel wraps an input *and* a listbox, so the wrapper is a
+  // plain div: the `role="listbox"`/`id` `useRole` produced go on the
+  // inner list, which is what the trigger's and input's `aria-controls`
+  // then resolve to.
+  const {
+    id: listboxId,
+    role: _discardedPanelRole,
+    ...floatingProps
+  } = getFloatingProps() as {
+    id: string
+    role?: string
+  } & Record<string, unknown>
+
+  const setQuery = (nextQuery: string) => {
+    if (!isQueryControlled) {
+      setInternalQuery(nextQuery)
+    }
+
+    setActiveIndex(0)
+
+    onQueryChange?.(nextQuery)
+  }
+
+  useEffect(() => {
+    if (isVisible) {
+      inputElement.current?.focus()
+    }
+  }, [isVisible])
+
+  const rowVirtualizer = useVirtualizer({
+    count: filtered.length,
+    estimateSize: () => 36,
+    getScrollElement: () => listElement.current,
+    overscan: 8,
+  })
+
+  const optionDomId = (value: string) =>
+    `${listboxId}-opt-${value}`
+
+  // `activeIndex` is seeded at 0 on open and on every query reset, which
+  // can land on a disabled option; arrowing skips disabled but the seed
+  // does not. Resolve to the nearest enabled row and drive the highlight,
+  // `aria-activedescendant`, arrow moves and commit off *this* — never the
+  // raw index — so a disabled option is neither announced nor committable.
+  const resolvedActiveIndex =
+    filtered.length === 0
+      ? -1
+      : filtered[activeIndex] !== undefined &&
+          !filtered[activeIndex]?.isDisabled
+        ? activeIndex
+        : nextEnabledIndex(filtered, -1, 1)
+
+  const activeValue =
+    resolvedActiveIndex < 0
+      ? undefined
+      : filtered[resolvedActiveIndex]?.value
+
+  const commitValue = (value: string) => {
+    if (isMultiple) {
+      setSelected((previous) =>
+        previous.includes(value)
+          ? previous.filter((one) => one !== value)
+          : [...previous, value],
+      )
+
+      onSelect(value)
+
+      // Multi-select stays open and clears the query for the next one.
+      setQuery("")
+
+      inputElement.current?.focus()
+
+      return
+    }
+
+    setSelected([value])
+
+    onSelect(value)
+
+    onDismiss()
+  }
+
+  const handleKeyDown = (
+    keyEvent: React.KeyboardEvent<HTMLInputElement>,
+  ) => {
+    if (keyEvent.key === "ArrowDown") {
+      keyEvent.preventDefault()
+
+      setActiveIndex(
+        nextEnabledIndex(filtered, resolvedActiveIndex, 1),
+      )
+
+      return
+    }
+
+    if (keyEvent.key === "ArrowUp") {
+      keyEvent.preventDefault()
+
+      setActiveIndex(
+        nextEnabledIndex(filtered, resolvedActiveIndex, -1),
+      )
+
+      return
+    }
+
+    if (
+      keyEvent.key === "Enter" ||
+      // Tab-to-accept (`PathPicker`): the active suggestion is taken.
+      // Single-select only — in multi-select `commitValue` refocuses the
+      // input, so accepting on Tab would trap forward focus in the field.
+      (keyEvent.key === "Tab" &&
+        !keyEvent.shiftKey &&
+        !isMultiple &&
+        activeValue !== undefined)
+    ) {
+      if (activeValue !== undefined) {
+        keyEvent.preventDefault()
+
+        commitValue(activeValue)
+
+        return
+      }
+
+      // Creatable: Enter on a query with no match commits it raw.
+      if (
+        isCreatable &&
+        keyEvent.key === "Enter" &&
+        currentQuery.trim().length > 0
+      ) {
+        keyEvent.preventDefault()
+
+        commitValue(currentQuery.trim())
+      }
+
+      return
+    }
+
+    if (keyEvent.key === "Escape") {
+      // Clears the query first, closes only when it is already empty.
+      if (currentQuery.length > 0) {
+        keyEvent.preventDefault()
+
+        setQuery("")
+
+        return
+      }
+
+      onDismiss()
+    }
+  }
+
+  // Keep the active row in view — a real bug in every fleet picker:
+  // arrowing past the panel edge did not scroll.
+  useEffect(() => {
+    if (!isVisible) {
+      return
+    }
+
+    if (isWindowed) {
+      rowVirtualizer.scrollToIndex(resolvedActiveIndex)
+
+      return
+    }
+
+    if (activeValue !== undefined) {
+      listElement.current
+        ?.querySelector(
+          `#${CSS.escape(`${listboxId}-opt-${activeValue}`)}`,
+        )
+        ?.scrollIntoView({ block: "nearest" })
+    }
+  }, [
+    resolvedActiveIndex,
+    activeValue,
+    isVisible,
+    isWindowed,
+    listboxId,
+    rowVirtualizer.scrollToIndex,
+  ])
+
+  const renderOption = (
+    option: ListboxItem,
+    index: number,
+  ) => (
+    <ComboboxOption
+      id={optionDomId(option.value)}
+      isActive={index === resolvedActiveIndex}
+      isSelected={selected.includes(option.value)}
+      item={option}
+      key={option.value}
+      onSelect={commitValue}
+      posInSet={isWindowed ? index + 1 : undefined}
+      setSize={isWindowed ? filtered.length : undefined}
+    />
+  )
+
+  return (
+    <>
+      {clonedTrigger}
+
+      {isVisible ? (
+        <FloatingPortal>
+          <FloatingFocusManager
+            context={context}
+            initialFocus={inputElement}
+            modal={false}
+          >
+            <div
+              {...floatingProps}
+              className={toClassName(
+                PANEL_SURFACE_CLASS,
+                "z-[var(--layer-modal)] flex min-w-64 flex-col overflow-hidden",
+                className,
+              )}
+              ref={setFloating}
+              style={floatingStyles}
+            >
+              <div className="flex flex-wrap items-center gap-1 border-border-subtle border-b p-2">
+                {isMultiple
+                  ? selected.map((value) => {
+                      const chip = options.find(
+                        (option) => option.value === value,
+                      )
+
+                      return (
+                        <span
+                          className="inline-flex items-center gap-1 rounded-sm bg-intent-neutral-surface px-1.5 py-0.5 text-content-primary text-xs"
+                          key={value}
+                        >
+                          {chip?.textValue ?? value}
+
+                          <button
+                            aria-label={`Remove ${chip?.textValue ?? value}`}
+                            className="cursor-pointer text-content-secondary hover:text-content-primary"
+                            onClick={() => {
+                              setSelected((previous) =>
+                                previous.filter(
+                                  (one) => one !== value,
+                                ),
+                              )
+
+                              // Mirror the list toggle-off: the parent
+                              // tracks selection through `onSelect`, so a
+                              // chip removal must report the same value.
+                              onSelect(value)
+                            }}
+                            type="button"
+                          >
+                            ✕
+                          </button>
+                        </span>
+                      )
+                    })
+                  : null}
+
+                <input
+                  aria-activedescendant={
+                    activeValue === undefined
+                      ? undefined
+                      : optionDomId(activeValue)
+                  }
+                  aria-autocomplete="list"
+                  aria-controls={listboxId}
+                  aria-expanded="true"
+                  aria-labelledby={triggerId}
+                  className="min-w-24 flex-1 bg-transparent text-content-primary text-sm outline-none placeholder:text-content-muted"
+                  onChange={(changeEvent) => {
+                    setQuery(changeEvent.target.value)
+                  }}
+                  onKeyDown={handleKeyDown}
+                  placeholder={placeholder}
+                  ref={inputElement}
+                  role="combobox"
+                  type="text"
+                  value={currentQuery}
+                />
+              </div>
+
+              <div
+                aria-labelledby={triggerId}
+                className="min-h-0 flex-1 overflow-auto p-1"
+                id={listboxId}
+                ref={listElement}
+                role="listbox"
+              >
+                {isLoading ? (
+                  <p className="px-2 py-3 text-center text-content-secondary text-sm">
+                    Loading…
+                  </p>
+                ) : error ? (
+                  <div className="px-2 py-3 text-center text-intent-danger-content text-sm">
+                    {error}
+                  </div>
+                ) : filtered.length === 0 ? (
+                  <p className="px-2 py-3 text-center text-content-secondary text-sm">
+                    {emptyLabel}
+                  </p>
+                ) : isWindowed ? (
+                  <div
+                    className="relative w-full"
+                    style={{
+                      height: `${rowVirtualizer.getTotalSize()}px`,
+                    }}
+                  >
+                    {rowVirtualizer
+                      .getVirtualItems()
+                      .map((virtualRow) => {
+                        const option =
+                          filtered[virtualRow.index]
+
+                        if (!option) {
+                          return null
+                        }
+
+                        return (
+                          <div
+                            className="absolute start-0 top-0 w-full"
+                            key={option.value}
+                            style={{
+                              height: `${virtualRow.size}px`,
+                              transform: `translateY(${virtualRow.start}px)`,
+                            }}
+                          >
+                            {renderOption(
+                              option,
+                              virtualRow.index,
+                            )}
+                          </div>
+                        )
+                      })}
+                  </div>
+                ) : (
+                  filtered.map((option, index) =>
+                    renderOption(option, index),
+                  )
+                )}
+              </div>
+
+              {footer ? (
+                <div className="shrink-0 border-border-subtle border-t p-2 text-content-secondary text-xs">
+                  {footer}
+                </div>
+              ) : null}
+            </div>
+          </FloatingFocusManager>
+        </FloatingPortal>
+      ) : null}
+    </>
+  )
+}

package/src/Combobox/ComboboxOption.tsx

@@ -0,0 +1,88 @@
+import type { ReactNode } from "react"
+
+import type { ListboxItem } from "../Listbox/Listbox.tsx"
+import { toClassName } from "../toClassName.ts"
+
+export type ComboboxOptionProps = {
+  /** The stable DOM id `aria-activedescendant` points at. */
+  id: string
+  isActive: boolean
+  isSelected: boolean
+  item: ListboxItem
+  onSelect: (value: string) => void
+  /**
+   * `aria-posinset`/`aria-setsize`, required when the list is
+   * virtualized: most of it is not in the DOM, so a screen reader
+   * would otherwise announce "2 of 12" for a 4,000-item list.
+   */
+  posInSet?: number
+  setSize?: number
+}
+
+/**
+ * `role="option"` with **`tabIndex={-1}`**, and both halves matter.
+ * The APG combobox keeps focus in the text input and tracks the
+ * active option with `aria-activedescendant`, so no option is ever a
+ * tab stop — `tabIndex={-1}` is that. It is a `<button>` (which
+ * ARIA-in-HTML allows `role="option"` on, and `Listbox` uses too)
+ * rather than a `<div>`, so `onClick` carries its own keyboard route
+ * and the package keeps its no-Biome-suppression record.
+ *
+ * The one caveat is not to run `expectAgentDrivable` on an individual
+ * option: its roving-tabindex rule would (correctly) reject a native
+ * control with `tabIndex={-1}`, and a combobox legitimately has zero
+ * tab stops in its popup. Tests query the options with `getByRole`.
+ *
+ * "Active" is a visual state only — the option the arrow keys have
+ * moved to, highlighted because nothing here holds real focus.
+ */
+export const ComboboxOption = ({
+  id,
+  isActive,
+  isSelected,
+  item,
+  onSelect,
+  posInSet,
+  setSize,
+}: ComboboxOptionProps): ReactNode => {
+  const { isDisabled = false, label, value } = item
+
+  return (
+    <button
+      aria-posinset={posInSet}
+      aria-selected={isSelected}
+      aria-setsize={setSize}
+      className={toClassName(
+        "flex w-full cursor-pointer items-center justify-between gap-2 rounded-sm bg-transparent px-2 py-1.5 text-start text-content-primary text-sm",
+        isActive && "bg-intent-neutral-surface",
+        isSelected && "bg-intent-accent-surface",
+        isDisabled &&
+          "cursor-not-allowed text-content-disabled",
+      )}
+      disabled={isDisabled}
+      id={id}
+      // `onMouseDown` rather than `onClick`: the input holds focus, and
+      // a click would blur it first. Prevented default keeps the caret
+      // in the input while the choice is made.
+      onMouseDown={(mouseEvent) => {
+        mouseEvent.preventDefault()
+
+        onSelect(value)
+      }}
+      role="option"
+      tabIndex={-1}
+      type="button"
+    >
+      {label}
+
+      {isSelected ? (
+        <span
+          aria-hidden="true"
+          className="shrink-0 text-intent-accent-content"
+        >
+          ✓
+        </span>
+      ) : null}
+    </button>
+  )
+}

package/src/Dialog/Dialog.mdx

@@ -0,0 +1,87 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as DialogStories from "./Dialog.stories";
+
+<Meta of={DialogStories} />
+
+# Dialog
+
+`Dialog` is [`Modal`](?path=/docs/components-modal--docs) plus the chrome: a heading, a
+Close button, a scrolling body, an optional footer, and five sizes. This is what `Modal`
+*was* before the M8 rebuild — a dialog is one kind of modal, so it takes the specific name
+and hands the generic one back to the base layer
+([decision](../../../docs/decisions/2026-08-03-modal-is-the-base-layer-and-dialog-is-the-component.md)).
+
+<Canvas of={DialogStories.Default} />
+
+## Props
+
+<Controls />
+
+## Everything modal is `Modal`'s
+
+The portal, the scrim, the focus trap, the scroll lock, Escape, an outside press, and the
+stacking all live in `Modal` (via `OverlayPanel`). `Dialog` is just the box's contents and
+the size it wants — `SIZE_CLASS` composed over `Modal`'s default surface, which is why
+`full` carries `rounded-none` to square off the base's `rounded-lg` at the viewport edge.
+
+```tsx
+const { hide, isVisible, show } = useVisibility()
+
+<Button onClick={show}>Stop the rip</Button>
+
+<Dialog heading="Stop the rip?" isVisible={isVisible} onClose={hide}>
+  …
+</Dialog>
+```
+
+`onClose` is every route out — the close button, Escape, a backdrop press — so there is
+one place to wire and no way to end up with the element shut and the state still open.
+`heading` is required: it names both the visible header and, through `aria-labelledby`,
+the dialog itself.
+
+<Canvas of={DialogStories.AllVariants} />
+
+## Escape is pressable now
+
+The old `Modal` was a native `<dialog>`, whose trusted `cancel` a story's synthetic
+`userEvent` could not fire — so its tests dispatched a fake close request. `useDismiss`
+listens for a plain keydown instead, so `userEvent.keyboard("{Escape}")` is a real close
+request. `isDismissable={false}` disables it at the dismiss layer, so a dialog the app
+still owns cannot be closed behind its back. `AllStates` pairs the refusal with a
+differential — the dialog that ignores Escape is then closed by its own button — because
+"still open" is also true of a dialog nothing can close at all.
+
+<Canvas of={DialogStories.AllStates} />
+
+## Stacking, and the one shared scrim
+
+A lone dialog needs no setup. Stack one over another and an `OverlayStackProvider` at the
+app root renders a **single** scrim behind both, keeps the second on top, marks the first
+`inert`, and closes them top-first on Escape or a backdrop press. The scroll lock
+ref-counts through the stack, so the page frees only when the last closes.
+
+<Canvas of={DialogStories.Stacked} />
+
+## `dvh`, and the scrim token
+
+Every size clamps at `85dvh`; `full` takes the lot. `dvh` rather than `vh` because on a
+phone the two differ by the address bar, and a dialog whose footer is under it is a dialog
+with no buttons.
+
+The scrim reads `--color-scrim`, a **variant** token: `legible` dims at 0.84 and
+`daylight` at 0.66, because how hard a direction separates a dialog from the page is
+exactly the sort of thing a visual direction decides. ePaper's is `transparent` — a panel
+with no opacity cannot dim, so it says so instead of faking it. `Responsive` asserts the
+computed scrim colour is really there, since a `var()` that failed to resolve would just
+look like a design choice.
+
+<Canvas of={DialogStories.Responsive} />
+
+## A dialog is not a container-query citizen
+
+It gets no `ContainerBoard`. Its size is measured against the viewport by definition — it
+is the thing covering the viewport — so boarding it at three container widths would be
+measuring something with no bearing on it.
+
+<Canvas of={DialogStories.Interactive} />