@charcuterie/ui 3.17.0 → 3.19.1

package/src/Menu/Menu.mdx

@@ -122,3 +122,52 @@ an anchored panel and an unanchored one land in the same place, and the test ass
 padding is still there before it asserts anything else.
 
 <Canvas of={MenuStories.SharedTrigger} />
+
+## The row is a click target, so it is `lg` by default
+
+`itemSize` takes the same `sm` / `md` / `lg` a `Button` takes, from the same
+density-aware `--control-height-*` tokens — so a `md` menu item and a `md` `Button`
+measure the same, and the `kiosk` density grows both together.
+
+It **defaults to `lg`**, which nothing else in the library does. The asymmetry is the
+decision rather than an oversight: a menu item is a *pointer* target before it is a list
+row. It is read once and then aimed at, usually in a hurry, and a menu rarely holds more
+than about eight items — so it can spend the height a dense list cannot. At `comfortable`
+density `lg` is 2.75rem, which is also the 44px WCAG 2.5.5 target; on the `kiosk` density
+it is 3.75rem with no prop change.
+
+The floor is a **minimum**, not a fixed height (`min-h-`, where a `Button` uses `h-`), so a
+long label that wraps to a second line still grows past it.
+
+<Canvas of={MenuStories.ItemSizes} />
+
+## A short window steps the size back down, and the panel scrolls
+
+Two separate protections, because they answer different failures.
+
+A window shorter than **40rem** drops every panel row one step, and one shorter than
+**30rem** takes them to `sm` — so a `lg` menu is never the reason its own last item is off
+the screen. That is `usePanelItemSize`, a `matchMedia` read rather than a CSS media query:
+`text-sm` → `text-md` is a Tailwind bridge onto `--font-size-*` rather than a variable a
+media query can reassign, so stepping the whole `ControlSize` in JS is what keeps one
+literal class string per size. It costs a re-render on resize, which is not the axis the
+library keeps as a repaint.
+
+Independently, the panel is now clamped to the space the viewport actually left it and
+scrolls inside that. A menu had **no** clamp before — survivable at a 32px row, and not at
+44px, where nine items are 400px and the panel simply ran off the bottom of the screen with
+no way to reach the last one.
+
+## A long label wraps, rather than pushing the panel off screen
+
+A portalled panel is `position: fixed`, so its shrink-to-fit width stops at the
+**viewport** — not at the space `shift` left it. A label long enough to reach that cap
+therefore produced a menu exactly as wide as the window, positioned 8px in, with 8px of
+itself off the right edge: clipped and unreachable. Measured at 390px.
+
+That was pre-existing and size-independent, but a `lg` row's larger type is what makes a
+real label reach it, so the clamp lands in the same change. `isWidthClamped` caps the panel
+at floating-ui's shifted `availableWidth`, and the label wraps inside its row — which is
+also why a row's height is a `min-h-` rather than an `h-`.
+
+<Canvas of={MenuStories.LongLabel} />

package/src/Menu/Menu.stories.tsx

@@ -1,8 +1,12 @@
 import { useVisibility } from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
 import type { Meta, StoryObj } from "@storybook/react"
 import type { ReactNode } from "react"
 
-import { placementArgType } from "../argTypes.storyHelpers.ts"
+import {
+  controlSizeArgType,
+  placementArgType,
+} from "../argTypes.storyHelpers.ts"
 import { Button } from "../Button/Button.tsx"
 import {
   StoryCell,
@@ -79,11 +83,13 @@ const GROUPED_ACTIONS: MenuEntry[] = [
 const MenuHarness = ({
   emptyState,
   isInitiallyVisible = false,
+  itemSize,
   items = BAY_ACTIONS,
   triggerLabel,
 }: {
   emptyState?: ReactNode
   isInitiallyVisible?: boolean
+  itemSize?: ControlSize
   items?: MenuEntry[]
   triggerLabel: string
 }): ReactNode => {
@@ -95,6 +101,7 @@ const MenuHarness = ({
     <Menu
       emptyState={emptyState}
       isVisible={isVisible}
+      itemSize={itemSize}
       items={items}
       onDismiss={hide}
       trigger={
@@ -144,9 +151,13 @@ const meta = {
   title: "Components/Actions/Menu",
   component: Menu,
   parameters: { layout: "centered" },
-  argTypes: { placement: placementArgType },
+  argTypes: {
+    itemSize: controlSizeArgType,
+    placement: placementArgType,
+  },
   args: {
     items: BAY_ACTIONS,
+    itemSize: "lg",
     placement: "bottom-start",
   },
 } satisfies Meta<typeof Menu>
@@ -304,3 +315,103 @@ export const Empty: Story = {
     />
   ),
 }
+
+/**
+ * The three row sizes, open side by side.
+ *
+ * `lg` is the **default** here and nowhere else in the library. The
+ * argument is that a menu item is a pointer target before it is a
+ * list row: it is read once and then aimed at, usually in a hurry,
+ * and a menu rarely holds more than about eight items — so it can
+ * spend the height a dense list cannot. At `comfortable` density `lg`
+ * is 2.75rem, which is also the 44px WCAG 2.5.5 target, and on the
+ * `kiosk` density it is 3.75rem with no prop change.
+ *
+ * `sm` is what every menu in the fleet rendered before this, so it is
+ * the row to compare the other two against rather than a smaller
+ * option nobody wants.
+ *
+ * A window shorter than 40rem steps each of these down one step on
+ * its own, and one shorter than 30rem takes them to `sm` — so a `lg`
+ * menu is never the reason its own last item is off the screen. Drag
+ * the preview's bottom edge up to watch it happen.
+ */
+export const ItemSizes: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: noop,
+    trigger: <Button appearance="outline">Actions</Button>,
+  },
+  parameters: { layout: "padded" },
+  render: () => (
+    <StoryGrid columns={3}>
+      <StoryCell label="sm — the old row">
+        <MenuHarness
+          isInitiallyVisible
+          itemSize="sm"
+          triggerLabel="Bay 1"
+        />
+      </StoryCell>
+
+      <StoryCell label="md — matches a default Button">
+        <MenuHarness
+          isInitiallyVisible
+          itemSize="md"
+          triggerLabel="Bay 2"
+        />
+      </StoryCell>
+
+      <StoryCell label="lg — the default (44px)">
+        <MenuHarness
+          isInitiallyVisible
+          itemSize="lg"
+          triggerLabel="Bay 3"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * A label longer than the panel, at the width it matters.
+ *
+ * A portalled panel is `position: fixed`, so its shrink-to-fit width
+ * stops at the **viewport** rather than at the space `shift` left it
+ * — which produced a menu exactly as wide as a 390px window,
+ * positioned 8px in, with 8px of itself off the right edge. It was
+ * pre-existing and size-independent; a `lg` row's larger type is what
+ * makes a real label reach it.
+ *
+ * The panel is clamped to the shifted `availableWidth` now, and the
+ * label wraps inside its row — which is also why a row's height is a
+ * `min-h-` rather than an `h-`.
+ */
+export const LongLabel: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: noop,
+    trigger: <Button appearance="outline">Actions</Button>,
+  },
+  globals: { viewport: { value: "mobile1" } },
+  parameters: { layout: "padded" },
+  render: () => (
+    <MenuHarness
+      isInitiallyVisible
+      items={[
+        {
+          icon: <SettingsIcon />,
+          key: "forget",
+          label:
+            "Forget every remembered passcode on this device",
+          onSelect: noop,
+        },
+        {
+          key: "skip",
+          label: "Skip title",
+          onSelect: noop,
+        },
+      ]}
+      triggerLabel="Bay 8"
+    />
+  ),
+}

package/src/Menu/Menu.test.tsx

@@ -5,6 +5,12 @@ import { test } from "vitest"
 import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
 import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
+import {
+  DESKTOP,
+  PHONE,
+  SHORT_WINDOW,
+  setViewport,
+} from "../viewport.testHelpers.ts"
 import * as stories from "./Menu.stories.tsx"
 
 const {
@@ -13,6 +19,7 @@ const {
   Empty,
   Grouped,
   Interactive,
+  LongLabel,
   SharedTrigger,
 } = composeStories(stories)
 
@@ -422,3 +429,125 @@ test("an empty menu shows a disabled note, not an actionable item", async () =>
 
   await expectNoAxeViolations(menu)
 })
+
+/**
+ * `--control-height-<size>` in px.
+ *
+ * The token is declared in `rem`, and `getComputedStyle` hands back a
+ * custom property's *declared* value rather than a used length — so
+ * the conversion happens here, against the live root font size. That
+ * keeps the assertions below written against the token instead of
+ * against a `44` typed in this file, so a density change moves them
+ * with it.
+ */
+const getControlHeightPx = (size: "lg" | "md" | "sm") => {
+  const root = globalThis.document.documentElement
+
+  const declared = globalThis
+    .getComputedStyle(root)
+    .getPropertyValue(`--control-height-${size}`)
+
+  return (
+    Number.parseFloat(declared) *
+    Number.parseFloat(
+      globalThis.getComputedStyle(root).fontSize,
+    )
+  )
+}
+
+/**
+ * The click target, measured rather than described.
+ *
+ * `itemSize` defaults to `lg` on a menu and nothing else in the
+ * library, which is the point: a menu item is aimed at in a hurry and
+ * there are rarely more than about eight of them, so it can afford
+ * the height a dense list cannot. `--control-height-lg` is 2.75rem at
+ * `comfortable` density — 44px, the WCAG 2.5.5 target — and the
+ * assertion is against the token rather than against 44, so the kiosk
+ * density does not have to be special-cased here.
+ */
+test("a menu item is as tall as an `lg` control", async () => {
+  await setViewport(DESKTOP)
+
+  const { body } = await mountStory(AllStates)
+
+  const item = expectAgentDrivable(body, {
+    name: "Retry title",
+    role: "menuitem",
+  })
+
+  expect(
+    item.getBoundingClientRect().height,
+  ).toBeGreaterThanOrEqual(getControlHeightPx("lg"))
+})
+
+/**
+ * The other half of the same request: bigger rows, *unless* the
+ * window cannot spend the height. Nine `lg` rows are 400px of panel,
+ * which on a half-height window is the difference between a menu read
+ * at a glance and a menu scrolled.
+ */
+test("a short window steps the item size back down", async () => {
+  await setViewport(SHORT_WINDOW)
+
+  try {
+    const { body } = await mountStory(AllStates)
+
+    const item = expectAgentDrivable(body, {
+      name: "Retry title",
+      role: "menuitem",
+    })
+
+    expect(
+      item.getBoundingClientRect().height,
+    ).toBeLessThan(getControlHeightPx("lg"))
+  } finally {
+    // Every later test in this file measures against the tall rows,
+    // and the viewport is shared across the file.
+    await setViewport(DESKTOP)
+  }
+})
+
+/**
+ * The panel stays inside the window, and the label wraps to do it.
+ *
+ * `position: fixed` makes a panel's shrink-to-fit width stop at the
+ * *viewport* rather than at the space `shift` left it, so a long label
+ * produced a menu exactly as wide as a 390px window at `left: 8` —
+ * with 8px of itself off the right edge, clipped and unreachable. The
+ * assertion is against `shift`'s own 8px padding on both sides, so it
+ * fails if either the clamp or the padding goes away.
+ */
+test("a long label wraps rather than pushing the panel off screen", async () => {
+  await setViewport(PHONE)
+
+  try {
+    const { body } = await mountStory(LongLabel)
+
+    const menu = expectAgentDrivable(body, {
+      name: "Bay 8",
+      role: "menu",
+    })
+
+    const panel = menu.getBoundingClientRect()
+
+    expect(panel.left).toBeGreaterThanOrEqual(8)
+
+    expect(panel.right).toBeLessThanOrEqual(
+      globalThis.innerWidth - 8,
+    )
+
+    // Wrapped, not truncated and not one long line: the row is taller
+    // than the single-line floor it would otherwise sit at.
+    const item = expectAgentDrivable(body, {
+      name: "Forget every remembered passcode on this device",
+      role: "menuitem",
+    })
+
+    expect(
+      item.getBoundingClientRect().height,
+    ).toBeGreaterThan(getControlHeightPx("lg"))
+  } finally {
+    await setViewport(DESKTOP)
+  }
+})

package/src/Menu/Menu.tsx

@@ -3,6 +3,7 @@ import {
   useRovingFocus,
   useUniqueId,
 } from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
 import type { Placement } from "@floating-ui/react"
 import {
   FloatingFocusManager,
@@ -11,8 +12,10 @@ import {
 import type { ReactElement, ReactNode } from "react"
 import { useEffect, useRef } from "react"
 
+import { PANEL_ITEM_SIZE_CLASS } from "../controlStyles.ts"
 import { PANEL_SURFACE_CLASS } from "../Overlay/overlayPanelClass.ts"
 import { useAnchoredOverlay } from "../Overlay/useAnchoredOverlay.ts"
+import { usePanelItemSize } from "../Overlay/usePanelItemSize.ts"
 import { toClassName } from "../toClassName.ts"
 import { MenuAction } from "./MenuAction.tsx"
 
@@ -72,6 +75,19 @@ export type MenuProps = {
    */
   emptyState?: ReactNode
   isVisible: boolean
+  /**
+   * How tall each item is, from the same density-aware tokens a
+   * `Button` reads — so a `md` item and a `md` `Button` measure the
+   * same.
+   *
+   * **Defaults to `lg`**, which no other component in the library does,
+   * and the asymmetry is the decision rather than an oversight. A menu
+   * item is a *pointer* target first: it is read once and then aimed
+   * at, often in a hurry, and there are rarely more than about eight of
+   * them — so the height a dense list cannot spare, a menu can. A short
+   * window steps it back down on its own (`usePanelItemSize`).
+   */
+  itemSize?: ControlSize
   items: MenuEntry[]
   /** Outside press, Escape, and choosing an item all land here. */
   onDismiss: () => void
@@ -80,6 +96,20 @@ export type MenuProps = {
   trigger: ReactElement
 }
 
+/**
+ * A group heading is not a row — it has no height of its own to take
+ * — so it borrows only the inline padding, which is the one thing it
+ * has to share with the items under it.
+ */
+const GROUP_HEADING_INSET_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "px-(--control-padding-inline-sm)",
+  md: "px-(--control-padding-inline-md)",
+  lg: "px-(--control-padding-inline-lg)",
+}
+
 const isMenuItem = (entry: MenuEntry): entry is MenuItem =>
   entry.type === undefined || entry.type === "item"
 
@@ -171,10 +201,13 @@ export const Menu = ({
   emptyState,
   isVisible,
   items,
+  itemSize: requestedItemSize = "lg",
   onDismiss,
   placement = "bottom-start",
   trigger,
 }: MenuProps): ReactNode => {
+  const itemSize = usePanelItemSize(requestedItemSize)
+
   const menuId = useUniqueId()
 
   const itemElements = useRef(
@@ -195,7 +228,20 @@ export const Menu = ({
     getFloatingProps,
     setFloating,
   } = useAnchoredOverlay({
+    // A menu had no clamp at all, which was survivable while a row was
+    // 32px and is not now: nine `lg` rows are 400px, and on a short
+    // window the panel simply ran off the bottom of the screen with no
+    // way to reach the last item. It scrolls instead.
+    isHeightClamped: true,
     isVisible,
+    // And the inline twin. A portalled panel is `position: fixed`, so
+    // its shrink-to-fit width stops at the *viewport* rather than at
+    // the space `shift` left it — measured at 390px, a menu holding
+    // Mail Sifter's "Lock unlocks — forget passcodes on this device"
+    // came out 390px wide at `left: 8`, hanging 8px off the right
+    // edge. Pre-existing and size-independent, but a `lg` row's larger
+    // type is what makes a real label reach it.
+    isWidthClamped: true,
     offsetValue: 4,
     onDismiss,
     placement,
@@ -242,6 +288,7 @@ export const Menu = ({
   const renderItem = (item: MenuItem) => (
     <MenuAction
       item={item}
+      itemSize={itemSize}
       key={item.key}
       onDismiss={onDismiss}
       register={focus.register}
@@ -280,7 +327,13 @@ export const Menu = ({
           role="group"
         >
           <div
-            className="px-2 pt-1.5 pb-0.5 font-medium text-content-secondary text-xs"
+            // The heading is inset to the items' own inline padding so
+            // its text starts where their labels do, which is why it
+            // reads the row-size tokens rather than a fixed `px-2`.
+            className={toClassName(
+              GROUP_HEADING_INSET_CLASS[itemSize],
+              "pt-1.5 pb-0.5 font-medium text-content-secondary text-xs",
+            )}
             id={headingId}
           >
             {entry.label}
@@ -304,7 +357,10 @@ export const Menu = ({
     emptyState === undefined ? null : (
       <div
         aria-disabled="true"
-        className="px-2 py-1.5 text-content-disabled text-sm"
+        className={toClassName(
+          "flex items-center text-content-disabled",
+          PANEL_ITEM_SIZE_CLASS[itemSize],
+        )}
         role="menuitem"
         tabIndex={-1}
       >
@@ -333,7 +389,10 @@ export const Menu = ({
               {...getFloatingProps()}
               className={toClassName(
                 PANEL_SURFACE_CLASS,
-                "z-[var(--layer-modal)] flex min-w-48 flex-col gap-0.5 p-1",
+                // The height is clamped to the space the viewport left,
+                // written straight onto the element by the `size`
+                // middleware; this scrolls inside it.
+                "charcuterie-scrollbar z-[var(--layer-modal)] flex min-w-48 flex-col gap-0.5 overflow-y-auto p-1",
                 className,
               )}
               onKeyDown={(keyEvent) => {

package/src/Menu/MenuAction.tsx

@@ -1,11 +1,15 @@
+import type { ControlSize } from "@charcuterie/tokens"
 import type { ReactNode } from "react"
 import { useEffect } from "react"
 
+import { PANEL_ITEM_SIZE_CLASS } from "../controlStyles.ts"
 import { FOCUS_RING_CLASS } from "../intentStyles.ts"
 import { toClassName } from "../toClassName.ts"
 import type { MenuItem } from "./Menu.tsx"
 
 export type MenuActionProps = {
+  /** Already stepped down for a short window by `usePanelItemSize`. */
+  itemSize: ControlSize
   item: MenuItem
   onDismiss: () => void
   /** `RovingFocus.register` — membership of the arrow-key group. */
@@ -31,6 +35,7 @@ export type MenuActionProps = {
  */
 export const MenuAction = ({
   item,
+  itemSize,
   onDismiss,
   register,
   tabIndex,
@@ -55,10 +60,25 @@ export const MenuAction = ({
   return (
     <button
       className={toClassName(
-        "flex w-full cursor-pointer items-center 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 a plain `background-color`
+        // utility at the same specificity as the hover tint and Tailwind
+        // emits it last, so it wins — the same clobber that made a
+        // `Combobox`'s keyboard cursor invisible. A button's background is
+        // transparent already.
+        "flex w-full cursor-pointer items-center rounded-sm text-start text-content-primary transition-colors duration-(--duration-fast) ease-standard",
+        // Height, inline padding, gap and type all come from the row-size
+        // system, so a `md` menu item is exactly as tall as a `md`
+        // `Button` and the kiosk density grows both together.
+        PANEL_ITEM_SIZE_CLASS[itemSize],
+        // `-hover`, not plain `intent-neutral-surface`: this panel is
+        // `surface-overlay`, which every dark scheme paints *lighter*
+        // than the base-surface tint — so the plain one reads as no
+        // change. `ListboxOption` and `ComboboxOption` were corrected on
+        // 2026-08-05 and this was missed.
+        !isDisabled &&
+          "hover:bg-intent-neutral-surface-hover",
         isDisabled &&
-          "cursor-not-allowed text-content-disabled hover:bg-transparent",
+          "cursor-not-allowed text-content-disabled",
         FOCUS_RING_CLASS,
       )}
       disabled={isDisabled}
@@ -89,7 +109,12 @@ export const MenuAction = ({
         </span>
       )}
 
-      {label}
+      {/*
+        `min-w-0`, so a label longer than the panel wraps instead of
+        forcing the flex line wider than its container. The icon beside
+        it is `shrink-0` and keeps its width.
+      */}
+      <span className="min-w-0">{label}</span>
     </button>
   )
 }

package/src/Overlay/useAnchoredOverlay.ts

@@ -85,9 +85,33 @@ export type UseAnchoredOverlayOptions = {
    * floating-ui `useDismiss` options they carry.
    */
   isEscapeDismissable?: boolean
+  /**
+   * Clamp the panel to the space the viewport actually leaves below
+   * (or above) the trigger, with no fixed cap. The panel owes itself
+   * an `overflow`, or a clamped one simply hides its last rows.
+   *
+   * `maxHeightPx` implies this *and* caps it at a number — a `Listbox`
+   * never wants to be 900px tall even on a monitor that would allow
+   * it. A `Menu` wants the other half only: as tall as its items need,
+   * and never off the bottom of the screen.
+   */
+  isHeightClamped?: boolean
   isOutsidePressDismissable?: boolean
   /** Ports `PortalDropdown`'s anchor-width match, via `size`. */
   isTriggerWidthMatched?: boolean
+  /**
+   * Clamp the panel to the width the viewport actually leaves, with no
+   * fixed cap — the inline twin of `isHeightClamped`, and `maxWidthPx`
+   * without the number.
+   *
+   * A portalled panel is `position: fixed`, so its shrink-to-fit width
+   * already stops at the *viewport*, not at the space `shift` left it
+   * — which means a long label produces a panel exactly as wide as the
+   * window, positioned 8px in, with 8px of itself off the right edge.
+   * `availableWidth` is the shifted number, so this is what makes a
+   * long label wrap instead.
+   */
+  isWidthClamped?: boolean
   isVisible: boolean
   /** Clamps the panel to `min(this, available viewport space)`. */
   maxHeightPx?: number
@@ -120,9 +144,11 @@ const PLACEHOLDER_TRIGGER = createElement("span")
 export const useAnchoredOverlay = ({
   anchorRef,
   isEscapeDismissable = true,
+  isHeightClamped = false,
   isOutsidePressDismissable = true,
   isTriggerWidthMatched = false,
   isVisible,
+  isWidthClamped = false,
   maxHeightPx,
   maxWidthPx,
   offsetValue = 8,
@@ -138,7 +164,9 @@ export const useAnchoredOverlay = ({
   ]
 
   if (
+    isHeightClamped ||
     isTriggerWidthMatched ||
+    isWidthClamped ||
     maxHeightPx !== undefined ||
     maxWidthPx !== undefined
   ) {
@@ -158,11 +186,11 @@ export const useAnchoredOverlay = ({
 
           elements.floating.style.maxHeight = `${heightCap}px`
 
-          if (maxWidthPx !== undefined) {
-            const widthCap = Math.min(
-              maxWidthPx,
-              availableWidth,
-            )
+          if (isWidthClamped || maxWidthPx !== undefined) {
+            const widthCap =
+              maxWidthPx === undefined
+                ? availableWidth
+                : Math.min(maxWidthPx, availableWidth)
 
             elements.floating.style.maxWidth = `${widthCap}px`
           }