@charcuterie/ui 3.18.0 → 3.19.2

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`
           }

package/src/Overlay/usePanelItemSize.ts

@@ -0,0 +1,71 @@
+import { useMediaQuery } from "@charcuterie/logic"
+import { matchMediaMatcher } from "@charcuterie/logic/browser"
+import type { ControlSize } from "@charcuterie/tokens"
+
+/**
+ * The requested row size, stepped down when the window is too short
+ * to spend the height.
+ *
+ * A fat option row is a bigger click target, which is the whole point
+ * of `itemSize` — but a nine-item menu at `lg` is 400px of panel, and
+ * on a half-height window that is the difference between a menu you
+ * read at a glance and a menu you scroll. So the size a panel asks
+ * for is a *ceiling*: below 40rem of viewport height it drops one
+ * step, and below 30rem it drops to the floor.
+ *
+ * ### Why a hook and not a media query in CSS
+ *
+ * Both were written. CSS is the library's usual answer — the density
+ * axis rewrites `--control-height-*` and nothing re-renders — but it
+ * cannot step *`text-sm` to `text-md`*: those are Tailwind bridges
+ * onto `--font-size-*` rather than variables a media query can
+ * reassign, and the alternative (`text-(length:--panel-item-font-size-lg)`
+ * everywhere, over nine new tokens) is the indirection
+ * `buildCss.ts` explicitly argues against. Stepping the whole
+ * `ControlSize` in JS keeps one literal class string per size, which
+ * is also what `tailwindCandidates.test.ts` can see.
+ *
+ * The re-render this costs happens on a window resize, not on a
+ * scheme or density flip — those stay repaints.
+ *
+ * ### `height`, not `width`
+ *
+ * Rows stack down the panel, so height is the axis that runs out.
+ * The Narrow View is a separate question and this is not it: a 390px
+ * phone held upright has plenty of height, and its menu stays fat.
+ */
+const SHORT_VIEWPORT_QUERY = "(height <= 40rem)"
+
+const VERY_SHORT_VIEWPORT_QUERY = "(height <= 30rem)"
+
+const STEP_DOWN: Record<ControlSize, ControlSize> = {
+  sm: "sm",
+  md: "sm",
+  lg: "md",
+}
+
+export const usePanelItemSize = (
+  itemSize: ControlSize,
+): ControlSize => {
+  // Both hooks run unconditionally and the *narrower* one wins, so
+  // the two queries never disagree about which step applies.
+  const { isMatching: isShortViewport } = useMediaQuery({
+    matcher: matchMediaMatcher(SHORT_VIEWPORT_QUERY),
+  })
+
+  const { isMatching: isVeryShortViewport } = useMediaQuery(
+    {
+      matcher: matchMediaMatcher(VERY_SHORT_VIEWPORT_QUERY),
+    },
+  )
+
+  if (isVeryShortViewport) {
+    return "sm"
+  }
+
+  if (isShortViewport) {
+    return STEP_DOWN[itemSize]
+  }
+
+  return itemSize
+}

package/src/controlStyles.ts

@@ -38,6 +38,44 @@ export const CONTROL_SIZE_CLASS: Record<
   lg: "h-(--control-height-lg) gap-(--control-gap-lg) px-(--control-padding-inline-lg) text-lg",
 }
 
+/**
+ * A row inside an overlay panel — a `Menu` item, a `Listbox` option,
+ * a `Combobox` option. The same three sizes as a control, read from
+ * the same density-aware tokens, so a `md` option row and a `md`
+ * `Button` are the same height.
+ *
+ * ### Why this is not `CONTROL_SIZE_CLASS`
+ *
+ * Two differences, and both are load-bearing.
+ *
+ * `min-h-`, not `h-`. A control on a form row holds one line by
+ * contract; an option may be rich — an icon, two lines, a trailing
+ * badge — and a fixed height clips it. The token is a **floor** here,
+ * which is what makes the row at least as big as the button that
+ * opened it while still growing for a label that wraps.
+ *
+ * `py-*`, which a control has none of. It is what a wrapped second
+ * line breathes on once `min-h-` stops being the binding constraint.
+ *
+ * ### The sizes are click targets, not decoration
+ *
+ * The owner's request is the whole reason this exists: *"I personally
+ * like larger click areas because it makes it easier to not mess up a
+ * click. I can be much faster the less precise I need to be when
+ * clicking."* At `comfortable` density `lg` is 2.75rem — 44px, the
+ * WCAG 2.5.5 target — and on the kiosk density it is 3.75rem with no
+ * prop change. See
+ * `docs/decisions/2026-08-25-a-panel-row-is-sized-by-itemsize-and-menus-default-to-lg.md`.
+ */
+export const PANEL_ITEM_SIZE_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "min-h-(--control-height-sm) gap-(--control-gap-sm) px-(--control-padding-inline-sm) py-1 text-sm",
+  md: "min-h-(--control-height-md) gap-(--control-gap-md) px-(--control-padding-inline-md) py-1.5 text-md",
+  lg: "min-h-(--control-height-lg) gap-(--control-gap-lg) px-(--control-padding-inline-lg) py-2 text-lg",
+}
+
 /**
  * Square, and sized by the *height* token on both axes so an icon
  * button lines up with the text button beside it in a toolbar. No