@charcuterie/ui 2.10.2 → 2.12.0

package/src/Combobox/Combobox.stories.tsx

@@ -54,6 +54,7 @@ const ComboboxHarness = ({
   isMultiple,
   isVirtualized,
   options,
+  selectedValue,
   triggerLabel,
 }: {
   className?: string
@@ -66,13 +67,20 @@ const ComboboxHarness = ({
   isMultiple?: boolean
   isVirtualized?: boolean
   options: ListboxItem[]
+  selectedValue?: readonly string[] | string
   triggerLabel: string
 }): ReactNode => {
   const { hide, isVisible, toggle } = useVisibility({
     isVisible: isInitiallyVisible,
   })
 
-  const [chosen, setChosen] = useState<string[]>([])
+  const [chosen, setChosen] = useState<string[]>(
+    selectedValue === undefined
+      ? []
+      : typeof selectedValue === "string"
+        ? [selectedValue]
+        : [...selectedValue],
+  )
 
   return (
     <>
@@ -104,6 +112,7 @@ const ComboboxHarness = ({
           })
         }}
         options={options}
+        selectedValue={selectedValue}
         trigger={
           <Button appearance="outline" onClick={toggle}>
             {triggerLabel}
@@ -134,6 +143,76 @@ export const Default: Story = {
   ),
 }
 
+// Rich labels that pin a trailing category tag to the row's right edge:
+// the label is a full-width flex row, so its tag sits just inside the
+// always-reserved ✓ gutter. Selecting a row must not shift the tag — the
+// checkmark is always laid out, only made `invisible` when unselected.
+const TAGGED_LANGUAGES: ListboxItem[] = [
+  { name: "English", tag: "Germanic", value: "eng" },
+  { name: "Spanish", tag: "Romance", value: "spa" },
+  { name: "French", tag: "Romance", value: "fra" },
+  { name: "German", tag: "Germanic", value: "deu" },
+].map(({ name, tag, value }) => ({
+  label: (
+    <span className="flex flex-1 items-center justify-between gap-2">
+      <span>{name}</span>
+
+      <span className="rounded-sm bg-intent-neutral-surface-hover px-1.5 py-0.5 text-content-secondary text-xs">
+        {tag}
+      </span>
+    </span>
+  ),
+  textValue: name,
+  value,
+}))
+
+/**
+ * Rich option rows that pin a **trailing category tag** to the right
+ * edge, with the first option pre-selected. The ✓ gutter is always laid
+ * out (only made `invisible` when a row is unselected), so selecting a
+ * row is a paint-only change and the trailing tag never jumps left.
+ */
+export const TrailingElement: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: TAGGED_LANGUAGES,
+    trigger: <Button>Search languages</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      isInitiallyVisible
+      options={TAGGED_LANGUAGES}
+      selectedValue="eng"
+      triggerLabel="Search languages"
+    />
+  ),
+}
+
+/**
+ * A very long, full-sentence `footer`. The panel is width-capped
+ * (`maxWidthPx`), so the footer **wraps** to multiple lines instead of
+ * stretching the popup to the width of the sentence.
+ */
+export const LongFooter: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Search languages</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      footer="Type a BCP-47 language code and press Enter to add it directly — this hint is a full sentence on purpose, to prove the panel caps its width and wraps the footer instead of stretching to fit it."
+      isInitiallyVisible
+      options={LANGUAGES}
+      triggerLabel="Search languages"
+    />
+  ),
+}
+
 /**
  * The loading and error panel states — the ones only `PathPicker` had
  * all of, and every fleet picker did differently. Both keep the popup

package/src/Combobox/Combobox.test.tsx

@@ -13,6 +13,8 @@ const {
   Default,
   DisabledFirstOption,
   Interactive,
+  LongFooter,
+  TrailingElement,
   Virtualized,
 } = composeStories(stories)
 
@@ -388,6 +390,59 @@ test("attached mode: Escape closes the popup outright", async () => {
   )
 })
 
+test("the ✓ gutter is always laid out, only hidden when a row is unselected", async () => {
+  const { body } = await mountStory(TrailingElement)
+
+  const options = body.getAllByRole("option")
+
+  // Every option — selected or not — renders the ✓ span, so the label's
+  // width (and any trailing element it pins) never changes on selection.
+  for (const option of options) {
+    const check = option.querySelector(
+      '[aria-hidden="true"]',
+    )
+
+    expect(check).not.toBeNull()
+    expect(check).toHaveTextContent("✓")
+  }
+
+  // The pre-selected first row (English) shows its ✓; the rest keep the
+  // gutter but mark it `invisible`.
+  const selected = options.find((option: HTMLElement) =>
+    option.textContent?.includes("English"),
+  )
+
+  expect(selected).toHaveAttribute("aria-selected", "true")
+
+  expect(
+    selected?.querySelector('[aria-hidden="true"]'),
+  ).not.toHaveClass("invisible")
+
+  const unselected = options.find((option: HTMLElement) =>
+    option.textContent?.includes("Spanish"),
+  )
+
+  expect(unselected).toHaveAttribute(
+    "aria-selected",
+    "false",
+  )
+
+  expect(
+    unselected?.querySelector('[aria-hidden="true"]'),
+  ).toHaveClass("invisible")
+})
+
+test("a long footer is allowed to wrap rather than force the panel wide", async () => {
+  const { body } = await mountStory(LongFooter)
+
+  const footer = body.getByText(/BCP-47 language code/)
+
+  // The footer container permits wrapping (paired with the panel's
+  // `maxWidthPx` cap) instead of laying the sentence out on one line.
+  expect(footer).toHaveClass("whitespace-normal")
+  expect(footer).toHaveClass("break-words")
+})
+
 test("a windowed list carries aria-setsize and aria-posinset", async () => {
   const { body } = await mountStory(Virtualized)
 

package/src/Combobox/Combobox.tsx

@@ -195,6 +195,10 @@ export const Combobox = ({
     isEscapeDismissable: false,
     isVisible,
     maxHeightPx: 384,
+    // Cap the width so an overlong footer sentence or option label wraps
+    // instead of dragging the whole panel absurdly wide; the `min-w-64`
+    // floor still holds the low end. Content wider than this wraps.
+    maxWidthPx: 384,
     offsetValue: 4,
     onDismiss,
     role: "listbox",
@@ -716,7 +720,7 @@ export const Combobox = ({
               </div>
 
               {footer ? (
-                <div className="shrink-0 border-border-subtle border-t p-2 text-content-secondary text-xs">
+                <div className="shrink-0 whitespace-normal break-words border-border-subtle border-t p-2 text-content-secondary text-xs [overflow-wrap:anywhere]">
                   {footer}
                 </div>
               ) : null}

package/src/Combobox/ComboboxOption.tsx

@@ -100,14 +100,25 @@ export const ComboboxOption = ({
     >
       {label}
 
-      {isSelected ? (
-        <span
-          aria-hidden="true"
-          className="shrink-0 text-intent-accent-content"
-        >
-          ✓
-        </span>
-      ) : null}
+      {/*
+        The ✓ is rendered **always**, only hidden with `invisible` when
+        the row is unselected — never unmounted. If it appeared only on
+        selection the label's available width would change the instant a
+        row became selected, and a consumer whose label pins a trailing
+        element (a category tag) to the row's right edge would see it jump
+        left. A fixed-width, always-present gutter keeps selection a
+        paint-only change. `aria-hidden` throughout: selection is conveyed
+        by the button's `aria-selected`, so the glyph is decoration.
+      */}
+      <span
+        aria-hidden="true"
+        className={toClassName(
+          "flex w-4 shrink-0 justify-center text-intent-accent-content",
+          !isSelected && "invisible",
+        )}
+      >
+        ✓
+      </span>
     </button>
   )
 }

package/src/Overlay/useAnchoredOverlay.ts

@@ -91,6 +91,14 @@ export type UseAnchoredOverlayOptions = {
   isVisible: boolean
   /** Clamps the panel to `min(this, available viewport space)`. */
   maxHeightPx?: number
+  /**
+   * Caps the panel's width at `min(this, available viewport space)`,
+   * symmetric with `maxHeightPx`. Without it a picker grows to its
+   * widest content — a long `Combobox` footer sentence or option label
+   * drags the whole panel absurdly wide; the cap lets that content wrap
+   * instead. Omit for width-follows-content (the default).
+   */
+  maxWidthPx?: number
   /** Popover 8, Menu/Listbox/Combobox 4. */
   offsetValue?: number
   onDismiss: () => void
@@ -116,6 +124,7 @@ export const useAnchoredOverlay = ({
   isTriggerWidthMatched = false,
   isVisible,
   maxHeightPx,
+  maxWidthPx,
   offsetValue = 8,
   onDismiss,
   placement = "bottom-start",
@@ -128,17 +137,35 @@ export const useAnchoredOverlay = ({
     shift({ padding: 8 }),
   ]
 
-  if (isTriggerWidthMatched || maxHeightPx !== undefined) {
+  if (
+    isTriggerWidthMatched ||
+    maxHeightPx !== undefined ||
+    maxWidthPx !== undefined
+  ) {
     middleware.push(
       size({
         padding: 8,
-        apply({ availableHeight, elements, rects }) {
-          const cap =
+        apply({
+          availableHeight,
+          availableWidth,
+          elements,
+          rects,
+        }) {
+          const heightCap =
             maxHeightPx === undefined
               ? availableHeight
               : Math.min(maxHeightPx, availableHeight)
 
-          elements.floating.style.maxHeight = `${cap}px`
+          elements.floating.style.maxHeight = `${heightCap}px`
+
+          if (maxWidthPx !== undefined) {
+            const widthCap = Math.min(
+              maxWidthPx,
+              availableWidth,
+            )
+
+            elements.floating.style.maxWidth = `${widthCap}px`
+          }
 
           if (isTriggerWidthMatched) {
             elements.floating.style.width = `${rects.reference.width}px`

package/src/Toolbar/Toolbar.mdx

@@ -0,0 +1,126 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ToolbarStories from "./Toolbar.stories";
+
+<Meta of={ToolbarStories} />
+
+# Toolbar
+
+A row of controls that collapses into an overflow when it runs out of room — measured, not
+breakpointed, with **exactly one instance** of every control in the document.
+
+<Canvas of={ToolbarStories.Default} />
+
+## Props
+
+<Controls />
+
+## What four repos got wrong
+
+mux-magic's `PageHeader` is the fleet's original, and plex-channels' `Header` names it in
+its own comments as the thing it copied. Both inherit all of this:
+
+| Defect | There | Here |
+| --- | --- | --- |
+| `role="toolbar"`, no toolbar keyboard model | six sequential tab stops | one tab stop, arrow keys, `RovingFocus` |
+| Toggles with no state | `Switch` is an `aria-hidden` `<span>`; Dry Run announces identically on and off | the control is the app's own, and `Switch` carries `role="switch"` |
+| Triggers advertise nothing | zero `aria-expanded` / `aria-haspopup` / `aria-controls` in the file | written by `useRole`, inside `Menu` / `Popover` |
+| No focus management | no focus-on-open, no return-to-trigger | `Menu` seeds the first item; `FloatingFocusManager` returns focus |
+| Collapse by DOM duplication | every action rendered twice, one copy hidden by a documented CSS specificity coin-flip | one instance, relocated |
+| Nothing decides what collapses | two hardcoded media queries at 480/481px, ⋮ shown at every width | measured, priority-ordered, trigger only when something overflowed |
+
+## The overflow's role is a **type**, not a flag
+
+`role="menu"` permits only `menuitem`, `menuitemradio`, `menuitemcheckbox`, `group` and
+`separator`. A header overflow usually is not a menu — it holds toggles — and
+plex-channels puts a `ColorSchemeSwitcher` inside one today, which is invalid ARIA that no
+gate catches.
+
+So the caller cannot get it wrong:
+
+```tsx
+// Every row is an action → a real `role="menu"`.
+<Toolbar overflow="menu" items={[{ key: "retry", label: "Retry", onSelect }]} label="Deck actions" />
+
+// A control in the array → this is a compile error with `overflow="menu"`,
+// and requires `overflow="panel"`, which opens a `Popover`
+// (`role="dialog"`, `aria-haspopup="dialog"`).
+<Toolbar
+  overflow="panel"
+  items={[
+    { key: "retry", label: "Retry", onSelect },
+    { element: <DryRunSwitch />, key: "dry-run", type: "control" },
+  ]}
+  label="Deck controls"
+/>
+```
+
+Same instinct as
+[`Menu`'s items being a discriminated union](../../../docs/decisions/2026-08-05-menu-items-is-a-discriminated-union.md):
+the kinds are told apart by the type system, in the data, rather than by a boolean prop or
+a runtime warning.
+
+<Canvas of={ToolbarStories.AllVariants} />
+
+## Priority is the array order
+
+`items[0]` is the last thing to collapse, and it is also paint order. One axis rather than
+two, because a separate `priority` number beside a separate display order is a pair a
+caller can put out of step.
+
+<Canvas of={ToolbarStories.Responsive} />
+
+## Measured, not breakpointed
+
+There is no `collapseAt` prop. The bar reads the widths its items actually have, so a
+longer label, a different font, or `data-density="kiosk"` moves the collapse point on its
+own — where `480px` is wrong the moment any of those change.
+
+Two consequences worth knowing:
+
+- **The root is `flex-1 min-w-0`, and must stay sized by its container.** A bar that
+  shrink-wraps its items would narrow when one collapsed, which would collapse another —
+  a loop with no error anywhere. `useAdaptiveColumns` documents the same trap from the
+  other end.
+- **A collapsed item's width is remembered, not re-read.** It is not in the DOM to
+  measure. The first paint mounts everything, measures it, and collapses *before paint* in
+  a layout effect.
+
+## The keyboard model
+
+Tab **once** to enter, then:
+
+| Key | Does |
+| --- | --- |
+| `ArrowRight` / `ArrowLeft` | move to the next / previous member |
+| `Home` / `End` | jump to the first / last member |
+| `Tab` | leaves the toolbar entirely |
+
+The overflow trigger is the group's last member, so the arrow keys reach it. Clicking a
+member, or tabbing into the group, makes that member active — so the next arrow key
+continues from where the user is.
+
+A **disabled** action is simply not registered with the roving group, so the arrows skip it
+while it stays in the DOM and stays announced — the same mechanism `Menu` and
+`SegmentedControl` use.
+
+<Canvas of={ToolbarStories.AllStates} />
+
+## Controls the toolbar does not render
+
+A `control` item is the app's own element, and the tab stop is written onto the first
+focusable in its subtree rather than cloned in as a prop: most components in this library
+forward no `tabIndex`, so a clone would compile, do nothing, and leave the bar with one tab
+stop per control.
+
+A control holding **more than one** focusable is a nested composite this component does not
+manage — only the first gets the tab stop. Put a `SegmentedControl` in a toolbar and it
+brings its own arrow-key model; that is the APG's expectation too.
+
+## Relocating is a different job
+
+Progressive collapse answers *what fits*. On a phone the whole bar often wants to leave the
+header, which is a layout decision — `useMediaQuery` from `@charcuterie/logic`, over the
+`matchMediaMatcher` seam, and one instance mounted in one place or the other.
+
+<Canvas of={ToolbarStories.InAppShell} />