@charcuterie/ui 2.2.0 → 2.4.0

package/src/Combobox/Combobox.tsx

@@ -3,7 +3,12 @@ import {
   FloatingPortal,
 } from "@floating-ui/react"
 import { useVirtualizer } from "@tanstack/react-virtual"
-import type { ReactElement, ReactNode } from "react"
+import type {
+  ReactElement,
+  KeyboardEvent as ReactKeyboardEvent,
+  ReactNode,
+  RefObject,
+} from "react"
 import { useEffect, useRef, useState } from "react"
 
 import type { ListboxItem } from "../Listbox/Listbox.tsx"
@@ -20,6 +25,20 @@ export type ComboboxProps = {
   error?: ReactNode
   /** A sticky footer hint (`LinkPicker`'s "type a path directly"). */
   footer?: ReactNode
+  /**
+   * Attached-input mode. Supply the consumer's own `<input>` and
+   * Combobox stops rendering its internal input/chip bar: it anchors the
+   * popup to this element, drives arrow/Enter/Tab/Escape off it, and
+   * mirrors the active option onto it for a screen reader. The consumer
+   * owns the input's `value`/`onChange` (wire them to the controlled
+   * `query`, which is then required) **and** `isVisible` — so a select
+   * does NOT auto-dismiss in this mode; staying open (a folder-picker
+   * drilling in) or closing (`onSelect` calls the consumer's own close)
+   * is the consumer's call. Options arrive pre-filtered (as with
+   * `onQueryChange`). Single-select only; `isMultiple` is not supported
+   * here.
+   */
+  inputRef?: RefObject<HTMLInputElement | null>
   /** Enter commits the raw query as a value (`AssFieldPicker`). */
   isCreatable?: boolean
   /** The loading panel state. */
@@ -42,8 +61,12 @@ export type ComboboxProps = {
   /** Controlled query; uncontrolled when absent. */
   query?: string
   selectedValue?: readonly string[] | string
-  /** The control the popup hangs off. **Cloned, not wrapped.** */
-  trigger: ReactElement
+  /**
+   * The control the popup hangs off. **Cloned, not wrapped.** Omit only
+   * in attached-input mode (`inputRef`), where the consumer's `<input>`
+   * is the anchor.
+   */
+  trigger?: ReactElement
 }
 
 const AUTO_VIRTUALIZE_THRESHOLD = 100
@@ -94,6 +117,7 @@ export const Combobox = ({
   emptyLabel = "No matches",
   error,
   footer,
+  inputRef,
   isCreatable = false,
   isLoading = false,
   isMultiple = false,
@@ -108,7 +132,19 @@ export const Combobox = ({
   selectedValue,
   trigger,
 }: ComboboxProps): ReactNode => {
-  const inputElement = useRef<HTMLInputElement>(null)
+  // Attached-input mode: the consumer's `<input>` is the reference,
+  // query source, focus holder and keyboard target; Combobox renders the
+  // list-only panel.
+  const isAttached = inputRef !== undefined
+
+  const internalInputElement =
+    useRef<HTMLInputElement>(null)
+
+  // The input Combobox drives — the consumer's in attached mode, its own
+  // otherwise.
+  const inputElement = isAttached
+    ? inputRef
+    : internalInputElement
 
   const listElement = useRef<HTMLDivElement>(null)
 
@@ -128,10 +164,11 @@ export const Combobox = ({
         : [...selectedValue],
   )
 
-  // The consumer owns filtering when it owns the query; otherwise it is
-  // a plain `textValue` contains-match.
+  // The consumer owns filtering when it owns the query or drives an
+  // attached input (the query is a full path, not an option-label match);
+  // otherwise it is a plain `textValue` contains-match.
   const filtered =
-    onQueryChange === undefined
+    onQueryChange === undefined && !isAttached
       ? options.filter((option) =>
           getOptionText(option).includes(
             currentQuery.toLowerCase(),
@@ -151,6 +188,9 @@ export const Combobox = ({
     setFloating,
     triggerId,
   } = useAnchoredOverlay({
+    // Attached mode anchors to the consumer's input; classic mode clones
+    // the trigger.
+    anchorRef: isAttached ? inputRef : undefined,
     // Escape is handled here so it can clear the query before closing.
     isEscapeDismissable: false,
     isVisible,
@@ -158,7 +198,7 @@ export const Combobox = ({
     offsetValue: 4,
     onDismiss,
     role: "listbox",
-    trigger,
+    trigger: isAttached ? undefined : trigger,
   })
 
   // The panel wraps an input *and* a listbox, so the wrapper is a
@@ -185,10 +225,21 @@ export const Combobox = ({
   }
 
   useEffect(() => {
-    if (isVisible) {
+    // In attached mode focus stays where the user is typing (the
+    // consumer's input); Combobox never grabs it.
+    if (isVisible && !isAttached) {
       inputElement.current?.focus()
     }
-  }, [isVisible])
+  }, [isVisible, isAttached, inputElement])
+
+  // Attached mode's query lives on the consumer's input, so `setQuery`
+  // (which reseeds the highlight) never runs on a keystroke — reseed here
+  // when the controlled query changes.
+  useEffect(() => {
+    if (isAttached) {
+      setActiveIndex(0)
+    }
+  }, [isAttached])
 
   const rowVirtualizer = useVirtualizer({
     count: filtered.length,
@@ -236,6 +287,22 @@ export const Combobox = ({
       return
     }
 
+    if (isAttached) {
+      // The consumer owns the value, the query and `isVisible`: report the
+      // pick and let it update the controlled query (→ refetch) and decide
+      // whether to stay open (drill-down) or close. No `onDismiss`, no
+      // `setQuery` (that would double-fire the consumer's query), no
+      // `setSelected` (the picked row leaves the list on refetch).
+      onSelect(value)
+
+      // Reseed the highlight for the list that is about to arrive.
+      setActiveIndex(0)
+
+      inputElement.current?.focus()
+
+      return
+    }
+
     setSelected([value])
 
     onSelect(value)
@@ -243,8 +310,42 @@ export const Combobox = ({
     onDismiss()
   }
 
+  // A chip's face is the option's human label, not its `value` — a
+  // language chip reads "English", not "eng". `textValue` (the rich-label
+  // fallback) wins, then a plain-string `label`, then the raw value only
+  // when the option has since left `options`.
+  const chipLabel = (value: string) => {
+    const item = options.find(
+      (option) => option.value === value,
+    )
+
+    if (item === undefined) {
+      return value
+    }
+
+    return (
+      item.textValue ??
+      (typeof item.label === "string" ? item.label : value)
+    )
+  }
+
+  const removeValue = (value: string) => {
+    setSelected((previous) =>
+      previous.filter((one) => one !== value),
+    )
+
+    // The parent tracks selection through `onSelect`, so removing a chip
+    // reports the same value the list toggle would — a symmetric toggle.
+    onSelect(value)
+  }
+
+  // Typed as either event so the same logic serves the classic mode's
+  // React `onKeyDown` and attached mode's native `keydown` listener —
+  // both carry `key`/`shiftKey`/`preventDefault`.
   const handleKeyDown = (
-    keyEvent: React.KeyboardEvent<HTMLInputElement>,
+    keyEvent:
+      | ReactKeyboardEvent<HTMLInputElement>
+      | KeyboardEvent,
   ) => {
     if (keyEvent.key === "ArrowDown") {
       keyEvent.preventDefault()
@@ -299,6 +400,17 @@ export const Combobox = ({
     }
 
     if (keyEvent.key === "Escape") {
+      // Attached mode's query lives on the consumer's input, which
+      // `setQuery` cannot clear — so Escape closes outright (the
+      // `PathPicker` contract).
+      if (isAttached) {
+        keyEvent.preventDefault()
+
+        onDismiss()
+
+        return
+      }
+
       // Clears the query first, closes only when it is already empty.
       if (currentQuery.length > 0) {
         keyEvent.preventDefault()
@@ -341,6 +453,80 @@ export const Combobox = ({
     rowVirtualizer.scrollToIndex,
   ])
 
+  // ─── Attached mode: drive the consumer's input ──────────────────────
+  //
+  // Combobox does not render the input, so its keyboard handler and ARIA
+  // are applied to the consumer's element. A ref-to-latest keeps the
+  // native listener stable across keystrokes (the `PathPicker` pattern).
+  const handleKeyDownRef = useRef(handleKeyDown)
+  handleKeyDownRef.current = handleKeyDown
+
+  useEffect(() => {
+    if (!isAttached || !isVisible) {
+      return
+    }
+
+    const element = inputRef.current
+
+    if (!element) {
+      return
+    }
+
+    const listener = (keyEvent: KeyboardEvent) => {
+      handleKeyDownRef.current(keyEvent)
+    }
+
+    element.addEventListener("keydown", listener)
+
+    return () => {
+      element.removeEventListener("keydown", listener)
+    }
+  }, [isAttached, isVisible, inputRef])
+
+  // Mirror the combobox ARIA onto the consumer's input. It owns
+  // `value`/`onChange`; these attributes are React-unmanaged, so setting
+  // them imperatively is stable across the consumer's re-renders.
+  useEffect(() => {
+    if (!isAttached) {
+      return
+    }
+
+    const element = inputRef.current
+
+    if (!element) {
+      return
+    }
+
+    element.setAttribute("role", "combobox")
+    element.setAttribute("aria-autocomplete", "list")
+
+    if (isVisible) {
+      element.setAttribute("aria-expanded", "true")
+      element.setAttribute("aria-controls", listboxId)
+
+      if (activeValue === undefined) {
+        element.removeAttribute("aria-activedescendant")
+      } else {
+        // Inlined rather than via `optionDomId` so the effect depends on
+        // the stable `listboxId`, not a per-render closure.
+        element.setAttribute(
+          "aria-activedescendant",
+          `${listboxId}-opt-${activeValue}`,
+        )
+      }
+    } else {
+      element.setAttribute("aria-expanded", "false")
+      element.removeAttribute("aria-controls")
+      element.removeAttribute("aria-activedescendant")
+    }
+  }, [
+    isAttached,
+    isVisible,
+    activeValue,
+    listboxId,
+    inputRef,
+  ])
+
   const renderOption = (
     option: ListboxItem,
     index: number,
@@ -359,12 +545,54 @@ export const Combobox = ({
 
   return (
     <>
+      {/*
+        Multi-select chips live *here*, above the trigger and outside the
+        `isVisible` gate — so a picked value stays on screen as a removable
+        tag after the popup closes. The previous build rendered them inside
+        the panel, where they vanished with it and the field read as empty
+        (the "no way to see or remove what I picked" report). Attached mode
+        is single-select, so it never grows a chip row.
+      */}
+      {isMultiple && !isAttached && selected.length > 0 ? (
+        <div className="mb-1 flex flex-wrap items-center gap-1">
+          {selected.map((value) => (
+            // The whole chip is the remove control, not just the ✕ — a
+            // bigger target, and removal is the chip's only action. One
+            // `<button>` (the ✕ is decorative) rather than a chip wrapping
+            // a button, so there is no nested interactive element and the
+            // accessible name is just "Remove <label>". Hover tints danger
+            // to signal the click removes.
+            <button
+              aria-label={`Remove ${chipLabel(value)}`}
+              className="inline-flex cursor-pointer items-center gap-1 rounded-sm bg-intent-neutral-surface-hover px-1.5 py-0.5 text-content-primary text-xs transition-colors duration-(--duration-fast) ease-standard hover:bg-intent-danger-surface hover:text-intent-danger-content"
+              key={value}
+              onClick={() => {
+                removeValue(value)
+              }}
+              type="button"
+            >
+              {chipLabel(value)}
+
+              <span
+                aria-hidden="true"
+                className="text-content-secondary"
+              >
+                ✕
+              </span>
+            </button>
+          ))}
+        </div>
+      ) : null}
+
       {clonedTrigger}
 
       {isVisible ? (
         <FloatingPortal>
           <FloatingFocusManager
             context={context}
+            // Attached mode keeps focus in the consumer's input — the
+            // panel must never grab it.
+            disabled={isAttached}
             initialFocus={inputElement}
             modal={false}
           >
@@ -378,69 +606,42 @@ export const Combobox = ({
               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>
+              {isAttached ? null : (
+                <div className="flex items-center gap-1 border-border-subtle border-b p-2">
+                  <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={internalInputElement}
+                    role="combobox"
+                    type="text"
+                    value={currentQuery}
+                  />
+                </div>
+              )}
 
               <div
-                aria-labelledby={triggerId}
+                // Classic mode names the listbox after its trigger;
+                // attached mode has no rendered trigger to point at, so it
+                // carries its own label.
+                aria-label={
+                  isAttached ? "Suggestions" : undefined
+                }
+                aria-labelledby={
+                  isAttached ? undefined : triggerId
+                }
                 className="min-h-0 flex-1 overflow-auto p-1"
                 id={listboxId}
                 ref={listElement}

package/src/Combobox/ComboboxOption.tsx

@@ -53,11 +53,36 @@ export const ComboboxOption = ({
       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",
+        // No base `bg-transparent`: it is a plain `background-color`
+        // utility at the same specificity as the state tints below, and
+        // Tailwind emits it *after* them, so it silently won every row —
+        // the active option and the selected option both rendered with no
+        // fill and the keyboard cursor was invisible (it read as "arrows
+        // do nothing"). A button's background is transparent by default;
+        // the tint classes only ever add one.
+        "flex w-full cursor-pointer items-center justify-between gap-2 rounded-sm px-2 py-1.5 text-start text-sm",
+        // The base sets no text colour: a plain `text-content-primary`
+        // clobbers a conditional `text-content-disabled` at equal
+        // specificity (Tailwind emits the base last), so a disabled option
+        // rendered full-strength instead of greyed. Pick one colour.
+        isDisabled
+          ? "text-content-disabled"
+          : "text-content-primary",
+        // The row highlight sits on `surface-overlay`, and on that panel
+        // `intent-neutral-surface` is *darker* than the surface in every
+        // dark scheme (it is a base-surface tint) — so the visible token
+        // is `-hover`. Active is the keyboard cursor; hover is the
+        // pointer's; both use it.
+        !isDisabled &&
+          "hover:bg-intent-neutral-surface-hover",
+        isActive && "bg-intent-neutral-surface-hover",
+        // The accent tint marks selection when the cursor is elsewhere;
+        // the active row keeps its own highlight (the ✓ still marks it as
+        // selected), so the two are never fighting for one row's fill.
+        isSelected &&
+          !isActive &&
+          "bg-intent-accent-surface",
+        isDisabled && "cursor-not-allowed",
       )}
       disabled={isDisabled}
       id={id}

package/src/EmptyState/EmptyState.stories.tsx

@@ -181,3 +181,18 @@ export const Interactive: Story = {
     />
   ),
 }
+
+/**
+ * Nested inside an already-deep section, an empty state is not an
+ * `<h2>`. The level goes to `6` so the outline never has to skip —
+ * the cap was a guess about document depth the consumer knows
+ * better than the component does.
+ */
+export const DeeplyNested: Story = {
+  args: {
+    description:
+      "Insert a disc and rip-deck will pick it up automatically.",
+    heading: "No discs queued",
+    headingLevel: 6,
+  },
+}

package/src/EmptyState/EmptyState.test.tsx

@@ -6,7 +6,8 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./EmptyState.stories.tsx"
 
-const { Default, Interactive } = composeStories(stories)
+const { Default, DeeplyNested, Interactive } =
+  composeStories(stories)
 
 test("the heading is the handle", async () => {
   const { canvas } = await mountStory(Default)
@@ -39,3 +40,17 @@ test("the heading level is the caller's, and Tab reaches the way out", async ()
 
   await expect(action).toHaveFocus()
 })
+
+test("the heading level reaches h6 for a deeply nested section", async () => {
+  const { canvas } = await mountStory(DeeplyNested)
+
+  // An empty state nested past four sections needs 5 or 6; the old
+  // `2 | 3 | 4` cap was a guess about depth the caller knows, and
+  // `` `h${headingLevel}` `` never had an upper bound to begin with.
+  await expect(
+    canvas.getByRole("heading", {
+      level: 6,
+      name: "No discs queued",
+    }),
+  ).toBeVisible()
+})

package/src/EmptyState/EmptyState.tsx

@@ -19,8 +19,13 @@ export type EmptyStateProps = Omit<
    * only the caller knows what it sits under. Getting this wrong
    * breaks a screen reader's document outline, which is how the
    * fleet's `<h2>`-with-a-`<button>`-inside pattern happened.
+   *
+   * The full `2–6` range because the cap is a guess about document
+   * structure the consumer knows better than we do — an empty state
+   * nested inside an already-deep section needs `5` or `6`, and
+   * `` `h${headingLevel}` `` never cared about the upper bound.
    */
-  headingLevel?: 2 | 3 | 4
+  headingLevel?: 2 | 3 | 4 | 5 | 6
   heading: string
   icon?: ReactNode
   size?: EmptyStateSize

package/src/Listbox/ListboxOption.tsx

@@ -69,11 +69,29 @@ export const ListboxOption = ({
     <button
       aria-selected={isSelected}
       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 transition-colors duration-(--duration-fast) ease-standard",
-        "hover:bg-intent-neutral-surface",
+        // No base `bg-transparent`: it is emitted after the state tints
+        // and silently won at equal specificity, so the selected option's
+        // accent fill never showed (only its ✓ did). Default is
+        // transparent anyway; the tints below add a fill.
+        "flex w-full cursor-pointer items-center justify-between gap-2 rounded-sm px-2 py-1.5 text-start text-sm transition-colors duration-(--duration-fast) ease-standard",
+        // The base sets no text colour: a plain `text-content-primary` in
+        // it clobbers a conditional `text-content-disabled` at equal
+        // specificity (Tailwind emits the base last), so a disabled option
+        // rendered full-strength and did not look disabled — it read as a
+        // normal row the arrow keys "wrongly" skipped. Pick one colour.
+        isDisabled
+          ? "text-content-disabled"
+          : "text-content-primary",
+        // The active (roving-focused) row gets a fill on **`:focus`**, not
+        // `:focus-visible` — so it is visible even when the listbox was
+        // opened by mouse. The ring is keyboard-only, so on a mouse-open
+        // the initial option had no indicator and the first ArrowDown
+        // looked like it skipped it. `-hover`, not the plain tint, because
+        // that is darker than `surface-overlay` in dark schemes.
+        !isDisabled &&
+          "hover:bg-intent-neutral-surface-hover focus:bg-intent-neutral-surface-hover",
         isSelected && "bg-intent-accent-surface",
-        isDisabled &&
-          "cursor-not-allowed text-content-disabled hover:bg-transparent",
+        isDisabled && "cursor-not-allowed",
         FOCUS_RING_CLASS,
       )}
       disabled={isDisabled}