@charcuterie/ui 2.2.0 → 2.3.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,47 @@ 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) => (
+            <span
+              className="inline-flex items-center gap-1 rounded-sm bg-intent-neutral-surface-hover px-1.5 py-0.5 text-content-primary text-xs"
+              key={value}
+            >
+              {chipLabel(value)}
+
+              <button
+                aria-label={`Remove ${chipLabel(value)}`}
+                className="cursor-pointer text-content-secondary hover:text-content-primary"
+                onClick={() => {
+                  removeValue(value)
+                }}
+                type="button"
+              >
+                ✕
+              </button>
+            </span>
+          ))}
+        </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 +599,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,9 +53,28 @@ 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",
+        // 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-content-primary text-sm",
+        // 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 text-content-disabled",
       )}

package/src/Listbox/ListboxOption.tsx

@@ -69,11 +69,19 @@ 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-content-primary text-sm transition-colors duration-(--duration-fast) ease-standard",
+        // `-hover`, not plain `intent-neutral-surface`: on the
+        // `surface-overlay` panel the plain tint is darker than the
+        // surface in dark schemes and the hover reads as no change.
+        !isDisabled &&
+          "hover:bg-intent-neutral-surface-hover",
         isSelected && "bg-intent-accent-surface",
         isDisabled &&
-          "cursor-not-allowed text-content-disabled hover:bg-transparent",
+          "cursor-not-allowed text-content-disabled",
         FOCUS_RING_CLASS,
       )}
       disabled={isDisabled}

package/src/Overlay/useAnchoredOverlay.ts

@@ -14,7 +14,8 @@ import {
   useInteractions,
   useRole,
 } from "@floating-ui/react"
-import type { ReactElement } from "react"
+import type { ReactElement, RefObject } from "react"
+import { createElement, useEffect } from "react"
 
 /**
  * The floating-ui block every anchored overlay — `Popover`, `Menu`,
@@ -67,6 +68,15 @@ export type AnchoredOverlayRole =
   | "menu"
 
 export type UseAnchoredOverlayOptions = {
+  /**
+   * Anchor the panel to a **pre-existing** element the consumer already
+   * rendered, instead of cloning a `trigger`. For the attached-input
+   * `Combobox`, whose reference is the consumer's own `<input>` (both the
+   * value and the query) — there is nothing to clone. Supply exactly one
+   * of `anchorRef` / `trigger`; with `anchorRef`, `clonedTrigger` is
+   * `null`.
+   */
+  anchorRef?: RefObject<HTMLElement | null>
   /**
    * Both default **on** — Escape and outside-press are what makes an
    * overlay an overlay. Switch one off for the honest exception (a
@@ -86,11 +96,21 @@ export type UseAnchoredOverlayOptions = {
   onDismiss: () => void
   placement?: Placement
   role: AnchoredOverlayRole
-  /** The control the panel hangs off. **Cloned, not wrapped.** */
-  trigger: ReactElement
+  /**
+   * The control the panel hangs off. **Cloned, not wrapped.** Omit only
+   * when `anchorRef` is supplied instead.
+   */
+  trigger?: ReactElement
 }
 
+// `useClonedChild` insists on exactly one element, and hooks cannot be
+// called conditionally — so in `anchorRef` mode we still call it, on this
+// throwaway, and discard the result. It is never rendered and never
+// receives the floating reference (that goes to `anchorRef`).
+const PLACEHOLDER_TRIGGER = createElement("span")
+
 export const useAnchoredOverlay = ({
+  anchorRef,
   isEscapeDismissable = true,
   isOutsidePressDismissable = true,
   isTriggerWidthMatched = false,
@@ -128,6 +148,8 @@ export const useAnchoredOverlay = ({
     )
   }
 
+  const isAnchored = anchorRef !== undefined
+
   const { context, floatingStyles, refs } = useFloating({
     // Read-only. Charcuterie remains the sole owner; floating-ui is
     // told what is true and never decides it.
@@ -180,11 +202,30 @@ export const useAnchoredOverlay = ({
     (referenceProps.id as string | undefined) ??
     generatedTriggerId
 
-  const clonedTrigger = useClonedChild(trigger, {
-    ...referenceProps,
-    id: triggerId,
-    ref: refs.setReference,
-  })
+  // In anchor mode floating-ui's reference is the consumer's element, set
+  // imperatively — there is no cloned trigger to carry `refs.setReference`.
+  // `setReference` is stable; re-running on `isVisible` re-applies it when
+  // the panel opens (and after the anchor element mounts).
+  useEffect(() => {
+    if (!isAnchored) {
+      return
+    }
+
+    refs.setReference(anchorRef.current)
+  }, [isAnchored, anchorRef, refs])
+
+  const clonedChild = useClonedChild(
+    trigger ?? PLACEHOLDER_TRIGGER,
+    {
+      ...referenceProps,
+      id: triggerId,
+      // The anchor element already exists; the clone (a discarded
+      // placeholder here) must not also claim the floating reference.
+      ...(isAnchored ? {} : { ref: refs.setReference }),
+    },
+  )
+
+  const clonedTrigger = isAnchored ? null : clonedChild
 
   return {
     clonedTrigger,

package/src/Select/Select.tsx

@@ -5,10 +5,7 @@ import type {
   ReactNode,
 } from "react"
 
-import {
-  CONTROL_SIZE_CLASS,
-  MIN_TOUCH_TARGET_CLASS,
-} from "../controlStyles.ts"
+import { CONTROL_SIZE_CLASS } from "../controlStyles.ts"
 import {
   DISABLED_CLASS,
   FOCUS_RING_CLASS,
@@ -139,8 +136,12 @@ export const Select = ({
         // removes, and forgetting to put one back leaves a control
         // that looks exactly like a text input.
         "pe-9",
+        // Height comes from the shared control-size/density system ONLY —
+        // no per-component touch-target floor. Touch is the density axis's
+        // job (`[data-density]` scales `--control-height-*` past 44px on a
+        // kiosk), so forcing 44px here made Select taller than Button et al.
+        // at desktop density. See the controls-share-one-height decision.
         CONTROL_SIZE_CLASS[size],
-        MIN_TOUCH_TARGET_CLASS,
         "hover:border-border-strong",
         FOCUS_RING_CLASS,
         DISABLED_CLASS,

package/src/controlStyles.ts

@@ -46,6 +46,14 @@ export const ICON_CONTROL_SIZE_CLASS: Record<
  * density — a finger does not get smaller because the list is
  * dense — so this is opt-in per control rather than baked into the
  * size classes, which would make `compact` a lie.
+ *
+ * **Do NOT add this to a control that shares a form row** (`Button`,
+ * `Select`, a `Listbox`/`Combobox` trigger, `SegmentedControl`, …). It
+ * overrides the shared `CONTROL_SIZE_CLASS` height and makes that one
+ * control taller than its neighbours at desktop density — touch sizing is
+ * the density axis's job. Reserve this for a genuinely standalone tap
+ * target. See
+ * `docs/decisions/2026-08-05-controls-share-one-height-no-per-component-touch-floor.md`.
  */
 export const MIN_TOUCH_TARGET_CLASS =
   "min-h-(--control-min-touch-target) min-w-(--control-min-touch-target)"