@charcuterie/ui 2.11.0 → 2.12.0

package/src/Toolbar/chooseVisibleCount.ts

@@ -0,0 +1,92 @@
+/**
+ * The collapse rule: how many of a toolbar's items fit, given what
+ * they measured.
+ *
+ * Pure arithmetic, in its own file for the same reason
+ * `chooseColumns` is — the rule is a table of numbers anyone can
+ * check in Node, and everything that needs a browser is quarantined
+ * in `useToolbarOverflow`.
+ *
+ * ## Priority is the array order
+ *
+ * `itemInlineSizes` is in **priority order, highest first**, which
+ * is also paint order: the toolbar collapses from the end. One axis
+ * rather than two, because a separate `priority` number and a
+ * separate display order is a pair a caller can put out of step,
+ * and neither mux-magic nor plex-channels has *any* ordering — they
+ * hardcode which controls live in the bar and which live in the
+ * popover, at every width.
+ *
+ * ## Why the trigger's width is an input
+ *
+ * The overflow trigger only exists once something has collapsed, so
+ * the question is not "how many fit" but "how many fit **beside a
+ * trigger** — unless all of them fit without one". Ignoring that is
+ * how an overflow control ends up wrapping to a second line at
+ * exactly the width where it first appears.
+ */
+
+export const chooseVisibleCount = ({
+  availableInlineSize,
+  gapInlineSize,
+  itemInlineSizes,
+  triggerInlineSize,
+}: {
+  /** The room the bar has, in CSS px. */
+  availableInlineSize: number
+  /** The row's `column-gap`, in CSS px. */
+  gapInlineSize: number
+  /** Each item's measured inline size, priority order, in CSS px. */
+  itemInlineSizes: readonly number[]
+  /** The overflow trigger's inline size, in CSS px. */
+  triggerInlineSize: number
+}): number => {
+  const itemCount = itemInlineSizes.length
+
+  if (itemCount === 0) {
+    return 0
+  }
+
+  /**
+   * Nothing measured yet — show everything.
+   *
+   * The safe direction to be wrong in for one frame, and the same
+   * one `useAdaptiveColumns` argues from the other end: a bar that
+   * starts whole and collapses over-draws, where a bar that starts
+   * collapsed hides controls that were there. It is also what makes
+   * the first measurement possible at all, because an item that was
+   * never mounted has no width to read.
+   */
+  if (availableInlineSize <= 0) {
+    return itemCount
+  }
+
+  const measure = (count: number, extra: number) =>
+    itemInlineSizes
+      .slice(0, count)
+      .reduce((total, size) => total + size, 0) +
+    gapInlineSize *
+      Math.max(count + (extra > 0 ? 1 : 0) - 1, 0) +
+    extra
+
+  if (measure(itemCount, 0) <= availableInlineSize) {
+    return itemCount
+  }
+
+  // Everything below here has an overflow trigger in the row, so
+  // every candidate pays for it. Counting down rather than up
+  // because the answer is usually near the top.
+  for (let count = itemCount - 1; count > 0; count -= 1) {
+    if (
+      measure(count, triggerInlineSize) <=
+      availableInlineSize
+    ) {
+      return count
+    }
+  }
+
+  // Not even one item and the trigger fit. Everything collapses;
+  // the trigger alone may still overflow, and a bar narrower than
+  // one control is a layout problem no collapse rule can solve.
+  return 0
+}

package/src/Toolbar/useToolbarOverflow.ts

@@ -0,0 +1,229 @@
+import type { RefObject } from "react"
+import {
+  useCallback,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react"
+
+import { chooseVisibleCount } from "./chooseVisibleCount.ts"
+
+/**
+ * The measuring half of progressive overflow — `chooseVisibleCount`
+ * is the decision, this is the tape measure.
+ *
+ * ## Measured, not breakpointed
+ *
+ * mux-magic collapses at a hardcoded `480px` and plex-channels at a
+ * hardcoded `760px`, and both numbers are wrong the moment a label
+ * gets longer, the density axis changes, or a rail takes half the
+ * row. A measured bar has no number to be wrong: it asks the
+ * elements how wide they actually are, in the font and density they
+ * are actually rendered in.
+ *
+ * ## One instance, and cached widths
+ *
+ * An item that has collapsed is **not in the DOM** — that is the
+ * whole point, against a mechanism that renders every action twice
+ * and hides one with a CSS specificity coin-flip. So its width
+ * cannot be re-read while it is away, and it is remembered from
+ * when it was last in the bar instead.
+ *
+ * The first paint is what seeds the cache: every item starts in the
+ * bar (`chooseVisibleCount` returns all of them for an unmeasured
+ * container), gets measured, and the row collapses **before paint**
+ * because the measuring runs in a layout effect. Any item whose
+ * width is still unknown forces one more all-visible pass rather
+ * than being guessed at — one extra layout pass, and it converges,
+ * because a mounted item always measures.
+ *
+ * ⚠️ **The measured element must not be sized by its own contents.**
+ * If the bar shrink-wraps its items, collapsing one narrows the box,
+ * which collapses another — a loop with no error anywhere.
+ * `Toolbar`'s root is `flex-1 min-w-0` for exactly this reason, the
+ * same trap `useAdaptiveColumns` documents about a container capped
+ * by its own answer.
+ */
+export const useToolbarOverflow = ({
+  itemKeys,
+}: {
+  /** Priority order, highest first. */
+  itemKeys: readonly string[]
+}): {
+  containerRef: RefObject<HTMLDivElement | null>
+  /** Callback ref for each item's box. `null` on unmount. */
+  trackItem: (
+    key: string,
+    element: HTMLElement | null,
+  ) => void
+  /** Callback ref for the overflow trigger's box. */
+  trackTrigger: (element: HTMLElement | null) => void
+  visibleCount: number
+} => {
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  const itemElements = useRef(
+    new Map<string, HTMLElement>(),
+  )
+
+  const triggerElement = useRef<HTMLElement | null>(null)
+
+  const itemInlineSizes = useRef(new Map<string, number>())
+
+  /**
+   * Zero until the trigger has been in the row once.
+   *
+   * A bar that has never overflowed has no trigger to measure, and
+   * the very first decision to collapse is taken without one. It
+   * errs the only safe way: with the trigger costed at nothing, the
+   * chosen count is at worst one item too many, which resolves on
+   * the next pass once the trigger exists and measures.
+   */
+  const triggerInlineSize = useRef(0)
+
+  const [visibleCount, setVisibleCount] = useState(
+    itemKeys.length,
+  )
+
+  /**
+   * Written during render, and deliberately.
+   *
+   * `itemKeys` is a fresh array on every render of the caller, so
+   * depending on it would give `measure` a new identity each time
+   * — which re-subscribes the `ResizeObserver` on every render. A
+   * ref is a pure cache here: a render React throws away and
+   * re-runs writes the same value, and nothing observable happens.
+   * Same reasoning as `useClonedChild`'s `useShallowStable`.
+   */
+  const itemKeysRef = useRef(itemKeys)
+
+  itemKeysRef.current = itemKeys
+
+  const measure = useCallback(() => {
+    const container = containerRef.current
+
+    if (!container) {
+      return
+    }
+
+    const keys = itemKeysRef.current
+
+    for (const [key, element] of itemElements.current) {
+      itemInlineSizes.current.set(
+        key,
+        element.getBoundingClientRect().width,
+      )
+    }
+
+    if (triggerElement.current) {
+      triggerInlineSize.current =
+        triggerElement.current.getBoundingClientRect().width
+    }
+
+    const hasEveryWidth = keys.every((key) =>
+      itemInlineSizes.current.has(key),
+    )
+
+    const next = hasEveryWidth
+      ? chooseVisibleCount({
+          availableInlineSize: container.clientWidth,
+          gapInlineSize:
+            Number.parseFloat(
+              getComputedStyle(container).columnGap,
+            ) || 0,
+          itemInlineSizes: keys.map(
+            (key) => itemInlineSizes.current.get(key) ?? 0,
+          ),
+          triggerInlineSize: triggerInlineSize.current,
+        })
+      : // An item that has never been mounted has no width. Show
+        // everything for one pass so it can be measured, rather
+        // than guessing a number and collapsing around it.
+        keys.length
+
+    setVisibleCount((current) =>
+      current === next ? current : next,
+    )
+  }, [])
+
+  /**
+   * A layout effect, not an effect: it runs after the DOM is
+   * written and **before the browser paints**, so the collapse that
+   * follows the first measurement is never a visible flash of a bar
+   * too wide for its box.
+   *
+   * No dependency array — it re-measures after every render, which
+   * is what keeps a changed label or a new item honest. It is cheap
+   * and it converges: `setVisibleCount` bails on an unchanged
+   * answer, so a stable bar renders once and stops.
+   */
+  useLayoutEffect(measure)
+
+  useLayoutEffect(() => {
+    const container = containerRef.current
+
+    if (!container) {
+      return
+    }
+
+    /**
+     * Only when the **box** changed.
+     *
+     * A `ResizeObserver` delivers a record on observe and again for
+     * every content reflow inside the frame it fired in, and
+     * measuring from each one is what raises chromium's
+     * "ResizeObserver loop completed with undelivered
+     * notifications" — the callback doing work that schedules more
+     * observation. The item-side re-measure is already covered by
+     * the layout effect above; this subscription exists for one
+     * question, which is whether the container got wider or
+     * narrower.
+     */
+    let lastInlineSize = -1
+
+    const observer = new ResizeObserver(([entry]) => {
+      const inlineSize =
+        entry?.contentRect.width ??
+        container.getBoundingClientRect().width
+
+      if (inlineSize === lastInlineSize) {
+        return
+      }
+
+      lastInlineSize = inlineSize
+
+      measure()
+    })
+
+    observer.observe(container)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [measure])
+
+  const trackItem = useCallback(
+    (key: string, element: HTMLElement | null) => {
+      if (element) {
+        itemElements.current.set(key, element)
+      } else {
+        itemElements.current.delete(key)
+      }
+    },
+    [],
+  )
+
+  const trackTrigger = useCallback(
+    (element: HTMLElement | null) => {
+      triggerElement.current = element
+    },
+    [],
+  )
+
+  return {
+    containerRef,
+    trackItem,
+    trackTrigger,
+    visibleCount,
+  }
+}

package/src/icons.storyHelpers.tsx

@@ -168,3 +168,26 @@ export const DotIcon = (): ReactNode => (
     <circle cx="12" cy="12" r="4" />
   </svg>
 )
+
+/**
+ * The overflow glyph — three dots, the ⋮ every header in the fleet
+ * draws as a **character**. Drawn rather than typed, because
+ * `⋮` renders as nothing where the font lacks it: this sandbox's
+ * chromium, the kiosk image, the ePaper build
+ * ([decision](../../../docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md)).
+ * It lives here, in the stories, because the library ships no icons.
+ */
+export const MoreIcon = (): ReactNode => (
+  <svg
+    {...iconProps}
+    aria-hidden="true"
+    fill="currentColor"
+    stroke="none"
+  >
+    <circle cx="12" cy="5" r="1.75" />
+
+    <circle cx="12" cy="12" r="1.75" />
+
+    <circle cx="12" cy="19" r="1.75" />
+  </svg>
+)

package/src/index.ts

@@ -262,6 +262,14 @@ export type {
 export { ToastRegion } from "./Toast/ToastRegion.tsx"
 export type { ToastStatus } from "./Toast/toastLifecycle.ts"
 export { toastTransitions } from "./Toast/toastLifecycle.ts"
+export { chooseVisibleCount } from "./Toolbar/chooseVisibleCount.ts"
+export type {
+  ToolbarAction,
+  ToolbarControl,
+  ToolbarItem,
+  ToolbarProps,
+} from "./Toolbar/Toolbar.tsx"
+export { Toolbar } from "./Toolbar/Toolbar.tsx"
 export type { TooltipProps } from "./Tooltip/Tooltip.tsx"
 export { Tooltip } from "./Tooltip/Tooltip.tsx"
 export { toClassName } from "./toClassName.ts"

package/src/sourceRules.test.ts

@@ -358,7 +358,13 @@ test("the barrel is the only place components are re-exported", async () => {
   // and `shellContext.ts` are `Shell`'s members and stay out of
   // this count by the `<Name>/<Name>.tsx` rule, exactly as
   // `mediaStatus.ts` does.
-  expect(componentNames.length).toBe(42)
+  // `Toolbar` unifies the fourth-largest duplication — four repos
+  // with a toolbar-and-overflow, three of them collapsing by
+  // rendering every action twice: +1 -> 43. `ToolbarSlot.tsx`,
+  // `useToolbarOverflow.ts` and `chooseVisibleCount.ts` are its
+  // members and stay out of this count by the `<Name>/<Name>.tsx`
+  // rule.
+  expect(componentNames.length).toBe(43)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)

package/src/testing/expectAgentDrivable.ts

@@ -86,24 +86,51 @@ const COMPOSITE_MEMBER_ROLES = new Set([
   "treeitem",
 ])
 
+/**
+ * A toolbar's members are ordinary controls.
+ *
+ * Every other composite here names its members by role — a `tab`, an
+ * `option`, a `menuitem`. A `role="toolbar"` names none of them: the
+ * APG's toolbar holds plain buttons, toggle buttons, a radio group,
+ * a menu button, and it is the *container* that declares the
+ * pattern. So `toolbar` sat in `COMPOSITE_ROLES` from M4 and was
+ * unreachable, because nothing inside one ever carried a member
+ * role — a roving toolbar was rejected outright with "has a negative
+ * tabindex", which is the assertion this helper makes for a
+ * *standalone* button and precisely the wrong one here.
+ */
+const TOOLBAR_MEMBER_SELECTOR =
+  "a[href], button, input, select, textarea, [tabindex]"
+
+const getGroupMembers = (group: Element) =>
+  group.getAttribute("role") === "toolbar"
+    ? Array.from(
+        group.querySelectorAll<HTMLElement>(
+          TOOLBAR_MEMBER_SELECTOR,
+        ),
+      )
+    : Array.from(
+        group.querySelectorAll<HTMLElement>("[role]"),
+      ).filter((member) =>
+        COMPOSITE_MEMBER_ROLES.has(
+          member.getAttribute("role") ?? "",
+        ),
+      )
+
 const getCompositeGroup = (element: Element) => {
-  if (
-    !COMPOSITE_MEMBER_ROLES.has(
-      element.getAttribute("role") ?? "",
-    )
-  ) {
-    return null
-  }
+  const isMemberByRole = COMPOSITE_MEMBER_ROLES.has(
+    element.getAttribute("role") ?? "",
+  )
 
   let current = element.parentElement
 
   while (current) {
-    if (
-      COMPOSITE_ROLES.has(
-        current.getAttribute("role") ?? "",
-      )
-    ) {
-      return current
+    const groupRole = current.getAttribute("role") ?? ""
+
+    if (COMPOSITE_ROLES.has(groupRole)) {
+      return groupRole === "toolbar" || isMemberByRole
+        ? current
+        : null
     }
 
     current = current.parentElement
@@ -225,16 +252,19 @@ export const expectAgentDrivable = (
     // *group* reachable, exactly once". Zero tab stops strands the
     // whole widget; several put every member back in the tab
     // order, which is the pattern not being implemented at all.
-    const tabStops = Array.from(
-      group.querySelectorAll("[role]"),
-    ).filter(
+    const tabStops = getGroupMembers(group).filter(
       (member) =>
-        COMPOSITE_MEMBER_ROLES.has(
-          member.getAttribute("role") ?? "",
-        ) &&
         !member.hasAttribute("disabled") &&
         member.getAttribute("aria-disabled") !== "true" &&
-        (member as HTMLElement).tabIndex >= 0,
+        // floating-ui plants `aria-hidden` focus guards
+        // (`<span tabindex="0">`) either side of an overlay's
+        // reference element, and a toolbar holding an overflow
+        // trigger therefore contains two. They are not members of
+        // anything — a screen reader and an agent both skip them —
+        // and counting them reported a correct roving group as
+        // having three tab stops.
+        !getIsHiddenFromAgents(member) &&
+        member.tabIndex >= 0,
     )
 
     if (tabStops.length !== 1) {