@charcuterie/ui 2.2.0 → 2.3.0

package/dist/controlStyles.js

@@ -35,6 +35,14 @@ export const ICON_CONTROL_SIZE_CLASS = {
  * 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)";
 /**

package/dist/controlStyles.js.map

@@ -1 +1 @@
-{"version":3,"file":"controlStyles.js","sourceRoot":"","sources":["../src/controlStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,CAAC,MAAM,kBAAkB,GAG3B;IACF,EAAE,EAAE,yFAAyF;IAC7F,EAAE,EAAE,yFAAyF;IAC7F,EAAE,EAAE,yFAAyF;CAC9F,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAGhC;IACF,EAAE,EAAE,yCAAyC;IAC7C,EAAE,EAAE,yCAAyC;IAC7C,EAAE,EAAE,yCAAyC;CAC9C,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GACjC,uEAAuE,CAAA;AAEzE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,EAAE,EAAE,2BAA2B;IAC/B,EAAE,EAAE,6BAA6B;CACzB,CAAA;AAIV,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,EAAE,EAAE,UAAU;IACd,EAAE,EAAE,QAAQ;IACZ,EAAE,EAAE,UAAU;CACN,CAAA;AAEV,MAAM,CAAC,MAAM,kBAAkB,GAG3B;IACF,EAAE,EAAE,mBAAmB;IACvB,EAAE,EAAE,iBAAiB;IACrB,EAAE,EAAE,iBAAiB;CACtB,CAAA"}
+{"version":3,"file":"controlStyles.js","sourceRoot":"","sources":["../src/controlStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,CAAC,MAAM,kBAAkB,GAG3B;IACF,EAAE,EAAE,yFAAyF;IAC7F,EAAE,EAAE,yFAAyF;IAC7F,EAAE,EAAE,yFAAyF;CAC9F,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAGhC;IACF,EAAE,EAAE,yCAAyC;IAC7C,EAAE,EAAE,yCAAyC;IAC7C,EAAE,EAAE,yCAAyC;CAC9C,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,sBAAsB,GACjC,uEAAuE,CAAA;AAEzE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,EAAE,EAAE,2BAA2B;IAC/B,EAAE,EAAE,6BAA6B;CACzB,CAAA;AAIV,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,EAAE,EAAE,UAAU;IACd,EAAE,EAAE,QAAQ;IACZ,EAAE,EAAE,UAAU;CACN,CAAA;AAEV,MAAM,CAAC,MAAM,kBAAkB,GAG3B;IACF,EAAE,EAAE,mBAAmB;IACvB,EAAE,EAAE,iBAAiB;IACrB,EAAE,EAAE,iBAAiB;CACtB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "The Charcuterie components. Tokens for look, @charcuterie/logic for state, ARIA that agents can actually drive.",
   "license": "MIT",
   "type": "module",

package/src/Combobox/Combobox.mdx

@@ -58,6 +58,36 @@ removable chips rather than filling the input, and keeps the popup open.
 
 <Canvas of={ComboboxStories.AllStates} />
 
+## Attached input & drill-down
+
+Supply `inputRef` and Combobox stops rendering its own input: it anchors a **list-only**
+popup to the consumer's `<input>`, mirrors the combobox ARIA (`role`, `aria-controls`,
+`aria-activedescendant`) onto it, and drives arrows/Enter/Tab/Escape off it while focus
+stays put. Use it when the field is **both the value and the query** — a path field whose
+text you type *and* filter by, the shape `PathPicker` needs.
+
+The consumer owns the input's `value`/`onChange` (wire them to the controlled `query`,
+which is then required) **and** `isVisible`. Because of that, **a select does not
+auto-dismiss** in this mode: `onSelect` fires and the consumer decides what happens next —
+append the folder and leave `isVisible` on to drill deeper (the popup re-queries from the
+new path and stays open), or call its own `close()` to finish. Enter and Tab both accept
+the active option; Escape closes outright. Single-select only (`isMultiple` is classic-mode
+only, and it stays the only mode that keeps the popup open on a normal select).
+
+```tsx
+<input ref={inputRef} value={path} onChange={(e) => setPath(e.target.value)} />
+<Combobox
+  inputRef={inputRef}
+  isVisible={isVisible}
+  query={path}
+  options={folders}                 // pre-filtered by the trailing segment
+  onSelect={(name) => setPath(`${parentPath}${name}/`)}  // drills; stays open
+  onDismiss={() => setIsVisible(false)}
+/>
+```
+
+<Canvas of={ComboboxStories.AttachedInputDrillDown} />
+
 ## Virtualization, and why `aria-setsize` is not optional
 
 Above ~100 options (or with `isVirtualized`), the list is windowed with

package/src/Combobox/Combobox.stories.tsx

@@ -1,7 +1,7 @@
 import { useVisibility } from "@charcuterie/logic"
 import type { Meta, StoryObj } from "@storybook/react"
 import type { ReactNode } from "react"
-import { useState } from "react"
+import { useRef, useState } from "react"
 
 import { Button } from "../Button/Button.tsx"
 import type { ListboxItem } from "../Listbox/Listbox.tsx"
@@ -153,10 +153,11 @@ export const AllStates: Story = {
 }
 
 /**
- * Multi-select renders the chosen values as removable chips rather
- * than filling the input, with a sticky footer hint — the
- * `LanguageCodeField` and `LinkPicker` shapes. `isCreatable` lets Enter
- * commit the raw query.
+ * Multi-select renders the chosen values as an always-visible row of
+ * removable chips **above the trigger** — they stay on screen after the
+ * popup closes, and each carries its option's human label (not its raw
+ * value) and an ✕ to remove it. The `LanguageCodeField` and `LinkPicker`
+ * shapes. `isCreatable` lets Enter commit the raw query.
  */
 export const AllVariants: Story = {
   args: {
@@ -227,6 +228,150 @@ export const Interactive: Story = {
  * first option to the first enabled one — and Enter must never commit the
  * disabled value.
  */
+// A tiny in-memory directory tree for the attached-input demo: keys are
+// parent paths (with trailing slash), values their child folders.
+const TREE: Record<string, string[]> = {
+  "/": ["apps", "config", "media"],
+  "/apps/": ["mux-magic", "charcuterie"],
+  "/config/": ["hosts", "secrets"],
+  "/media/": ["movies", "music"],
+}
+
+const AttachedInputHarness = (): ReactNode => {
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const [value, setValue] = useState("/")
+
+  const [isVisible, setIsVisible] = useState(true)
+
+  const lastSlash = value.lastIndexOf("/")
+
+  const parentPath = value.slice(0, lastSlash + 1) || "/"
+
+  const tail = value.slice(lastSlash + 1)
+
+  const options: ListboxItem[] = (TREE[parentPath] ?? [])
+    .filter((name) => name.startsWith(tail))
+    .map((name) => ({
+      label: `📁 ${name}`,
+      textValue: name,
+      value: name,
+    }))
+
+  return (
+    <>
+      <input
+        aria-label="Path"
+        className="w-80 rounded-md border border-border-default bg-surface-raised px-2 py-1.5 font-mono text-content-primary text-sm outline-none"
+        onChange={(changeEvent) => {
+          setValue(changeEvent.target.value)
+
+          setIsVisible(true)
+        }}
+        ref={inputRef}
+        value={value}
+      />
+
+      <Combobox
+        emptyLabel="No matching entries."
+        inputRef={inputRef}
+        isVisible={isVisible}
+        onDismiss={() => {
+          setIsVisible(false)
+        }}
+        onSelect={(name) => {
+          // Drill in: append the picked folder + separator. The changed
+          // query refetches the new directory; the popup stays open
+          // because we never flip `isVisible`.
+          setValue(`${parentPath}${name}/`)
+        }}
+        options={options}
+        query={value}
+      />
+    </>
+  )
+}
+
+/**
+ * Attached-input mode: the consumer renders its own `<input>` (both the
+ * committed value and the query) and Combobox anchors a list-only popup
+ * to it. Type a path; picking a folder appends it and re-queries that
+ * folder's children **without closing** — a shell-style drill-down. This
+ * is `PathPicker`'s shape.
+ */
+export const AttachedInputDrillDown: Story = {
+  args: {
+    inputRef: { current: null },
+    isVisible: true,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: [],
+    query: "/",
+  },
+  render: () => <AttachedInputHarness />,
+}
+
+// Long, space-separated names — the real-world case (a media library of
+// long folder names) the short demo tree does not show.
+const LONG_OPTIONS: ListboxItem[] = [
+  "Armored Trooper Votoms - Brilliantly Shining Heresy [anidb-7910]",
+  "Armored Trooper Votoms - Case;Irvine [anidb-7911]",
+  "Armored Trooper Votoms - Chirico's Return [anidb-1234]",
+  "Armored Trooper Votoms - Deadworld Sunsa [anidb-5678]",
+  "Armored Trooper Votoms - Pailsen Files - The Movie [anidb-9012]",
+].map((name) => ({
+  label: `📁 ${name}`,
+  textValue: name,
+  value: name,
+}))
+
+const LongOptionsHarness = (): ReactNode => {
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const [isVisible, setIsVisible] = useState(true)
+
+  return (
+    <>
+      <input
+        aria-label="Path"
+        className="w-80 rounded-md border border-border-default bg-surface-raised px-2 py-1.5 font-mono text-content-primary text-sm outline-none"
+        readOnly
+        ref={inputRef}
+        value="/media/Media-Storage/Anime/"
+      />
+
+      <Combobox
+        emptyLabel="No matching entries."
+        inputRef={inputRef}
+        isVisible={isVisible}
+        onDismiss={() => {
+          setIsVisible(false)
+        }}
+        onSelect={() => {}}
+        options={LONG_OPTIONS}
+        query="/media/Media-Storage/Anime/"
+      />
+    </>
+  )
+}
+
+/**
+ * How the attached-input popup handles **long option labels** — a media
+ * library of long folder names, the case the short drill-down demo hides.
+ * Shows how the panel sizes and how each option row treats overflow.
+ */
+export const AttachedInputLongOptions: Story = {
+  args: {
+    inputRef: { current: null },
+    isVisible: true,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LONG_OPTIONS,
+    query: "/media/Media-Storage/Anime/",
+  },
+  render: () => <LongOptionsHarness />,
+}
+
 export const DisabledFirstOption: Story = {
   args: {
     isVisible: false,

package/src/Combobox/Combobox.test.tsx

@@ -9,6 +9,7 @@ import * as stories from "./Combobox.stories.tsx"
 
 const {
   AllVariants,
+  AttachedInputDrillDown,
   Default,
   DisabledFirstOption,
   Interactive,
@@ -224,8 +225,10 @@ test("removing a chip reports the removal through onSelect", async () => {
     ).toBeInTheDocument()
   })
 
+  // The chip's face and accessible name are the option's human label,
+  // not its `value` — "English", not "eng".
   await userEvent.click(
-    body.getByRole("button", { name: "Remove eng" }),
+    body.getByRole("button", { name: "Remove English" }),
   )
 
   // The removal flowed back through `onSelect`, so the parent cleared it
@@ -269,6 +272,122 @@ test("a disabled first option is skipped, never active or committed", async () =
   ).toBeInTheDocument()
 })
 
+test("attached mode: the consumer input is the combobox and options are shown", async () => {
+  const { body, canvas } = await mountStory(
+    AttachedInputDrillDown,
+  )
+
+  const input = canvas.getByLabelText("Path")
+
+  // The a11y is mirrored onto the consumer's own input.
+  await waitFor(() => {
+    expect(input).toHaveAttribute("role", "combobox")
+  })
+
+  await expect(input).toHaveAttribute(
+    "aria-autocomplete",
+    "list",
+  )
+
+  const listbox = body.getByRole("listbox")
+
+  await expect(input).toHaveAttribute(
+    "aria-controls",
+    listbox.id,
+  )
+
+  // The three top-level folders, from the pre-filtered options.
+  await expect(body.getAllByRole("option")).toHaveLength(3)
+
+  await expectNoAxeViolations(listbox)
+})
+
+test("attached mode: selecting a folder drills in and keeps the popup open", async () => {
+  const { body, canvas } = await mountStory(
+    AttachedInputDrillDown,
+  )
+
+  const input = canvas.getByLabelText("Path")
+
+  await userEvent.click(input)
+
+  await waitFor(() => {
+    expect(input).toHaveFocus()
+  })
+
+  // Enter commits the active option ("apps") — but does not close.
+  await userEvent.keyboard("{Enter}")
+
+  await waitFor(() => {
+    expect(
+      body.getByRole("option", { name: /mux-magic/ }),
+    ).toBeInTheDocument()
+  })
+
+  // The field drilled in, the popup is still open, and focus never left.
+  await expect(input).toHaveValue("/apps/")
+
+  await expect(
+    body.getByRole("listbox"),
+  ).toBeInTheDocument()
+
+  await expect(input).toHaveFocus()
+})
+
+test("attached mode: Tab also accepts the active option and drills", async () => {
+  const { body, canvas } = await mountStory(
+    AttachedInputDrillDown,
+  )
+
+  const input = canvas.getByLabelText("Path")
+
+  await userEvent.click(input)
+
+  await waitFor(() => {
+    expect(input).toHaveFocus()
+  })
+
+  await userEvent.keyboard("{Tab}")
+
+  await waitFor(() => {
+    expect(input).toHaveValue("/apps/")
+  })
+
+  // Tab drilled rather than moving focus out; the popup stays open.
+  await expect(
+    body.getByRole("listbox"),
+  ).toBeInTheDocument()
+
+  await expect(input).toHaveFocus()
+})
+
+test("attached mode: Escape closes the popup outright", async () => {
+  const { body, canvas } = await mountStory(
+    AttachedInputDrillDown,
+  )
+
+  const input = canvas.getByLabelText("Path")
+
+  await userEvent.click(input)
+
+  await waitFor(() => {
+    expect(input).toHaveFocus()
+  })
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(body.queryByRole("listbox")).toBeNull()
+  })
+
+  // The consumer's input persists (Combobox never rendered it); it just
+  // reports itself collapsed.
+  await expect(input).toHaveAttribute(
+    "aria-expanded",
+    "false",
+  )
+})
+
 test("a windowed list carries aria-setsize and aria-posinset", async () => {
   const { body } = await mountStory(Virtualized)