@charcuterie/ui 3.18.0 → 3.19.1

package/dist/viewport.testHelpers.js

@@ -11,17 +11,23 @@ import { page } from "@vitest/browser/context";
  * fails intermittently — which is the worst possible property for
  * the one gate that says the shell does not scroll sideways.
  *
- * Polling `innerWidth` is the honest wait: it is the same number
- * the media queries and the layout resolved against, so when it
- * matches, the thing under test really is at the width the test
- * claims.
+ * Polling `innerWidth`/`innerHeight` is the honest wait: they are the
+ * same numbers the media queries and the layout resolved against, so
+ * when they match, the thing under test really is at the size the
+ * test claims.
+ *
+ * **Height counts too**, and it did not used to. A panel row's size
+ * steps down under `(height <= 40rem)` (`usePanelItemSize`), so a test
+ * that shrinks only the height would have raced the resize with
+ * nothing to wait on and measured the tall rows about half the time.
  */
 export const setViewport = async ({ height, width, }) => {
     await page.viewport(width, height);
     const deadline = Date.now() + 2000;
-    while (globalThis.innerWidth !== width) {
+    while (globalThis.innerWidth !== width ||
+        globalThis.innerHeight !== height) {
         if (Date.now() > deadline) {
-            throw new Error(`The viewport never reached ${width}px — it is ${globalThis.innerWidth}px. Every width assertion after this point would be measuring the wrong page.`);
+            throw new Error(`The viewport never reached ${width}x${height}px — it is ${globalThis.innerWidth}x${globalThis.innerHeight}px. Every size assertion after this point would be measuring the wrong page.`);
         }
         await new Promise((resolve) => {
             globalThis.requestAnimationFrame(resolve);
@@ -31,4 +37,10 @@ export const setViewport = async ({ height, width, }) => {
 /** A phone in portrait — the width plex-channels scrolls at. */
 export const PHONE = { height: 844, width: 390 };
 export const DESKTOP = { height: 900, width: 1440 };
+/**
+ * A window short enough to trip `usePanelItemSize`'s first step-down
+ * (`height <= 40rem`, so 640px) and wide enough that nothing else
+ * about the layout changes with it.
+ */
+export const SHORT_WINDOW = { height: 600, width: 1440 };
 //# sourceMappingURL=viewport.testHelpers.js.map

package/dist/viewport.testHelpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"viewport.testHelpers.js","sourceRoot":"","sources":["../src/viewport.testHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AAE9C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,EAChC,MAAM,EACN,KAAK,GAIN,EAAiB,EAAE;IAClB,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;IAElC,OAAO,UAAU,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,8BAA8B,KAAK,cAAc,UAAU,CAAC,UAAU,+EAA+E,CACtJ,CAAA;QACH,CAAC;QAED,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC5B,UAAU,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAA;QAC3C,CAAC,CAAC,CAAA;IACJ,CAAC;AACH,CAAC,CAAA;AAED,gEAAgE;AAChE,MAAM,CAAC,MAAM,KAAK,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;AAEhD,MAAM,CAAC,MAAM,OAAO,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA"}
+{"version":3,"file":"viewport.testHelpers.js","sourceRoot":"","sources":["../src/viewport.testHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,EAChC,MAAM,EACN,KAAK,GAIN,EAAiB,EAAE;IAClB,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;IAElC,OACE,UAAU,CAAC,UAAU,KAAK,KAAK;QAC/B,UAAU,CAAC,WAAW,KAAK,MAAM,EACjC,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,8BAA8B,KAAK,IAAI,MAAM,cAAc,UAAU,CAAC,UAAU,IAAI,UAAU,CAAC,WAAW,8EAA8E,CACzL,CAAA;QACH,CAAC;QAED,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC5B,UAAU,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAA;QAC3C,CAAC,CAAC,CAAA;IACJ,CAAC;AACH,CAAC,CAAA;AAED,gEAAgE;AAChE,MAAM,CAAC,MAAM,KAAK,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;AAEhD,MAAM,CAAC,MAAM,OAAO,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AAEnD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "3.18.0",
+  "version": "3.19.1",
   "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

@@ -99,3 +99,29 @@ for a 4,000-item list. Below the threshold the list is plain DOM.
 <Canvas of={ComboboxStories.Virtualized} />
 
 <Canvas of={ComboboxStories.Interactive} />
+
+## One panel, one row size
+
+`itemSize` drives the search field **and** the options together, from the same
+density-aware `--control-height-*` tokens a `Button` reads. It defaults to `md`, so at the
+default a trigger, the search field and every option are all 2.25rem.
+
+Covering the search row is the point rather than a bonus. The report that started this was
+that a `Combobox`'s trigger was bigger than the options under it — but the panel's own
+field was bigger than them too, and **two sizes inside one panel** is the defect rather
+than either number being wrong.
+
+It also retires a hand-picked number. The search row used to carry `px-3` to line its caret
+up with the option labels below it, which worked only while the option padding was a
+hardcoded `px-2`; it is now wrapped in the list's own `p-1` and given the same row-size
+class, so the two cannot drift apart again.
+
+`lg` is the fat one — 2.75rem, the 44px WCAG 2.5.5 target. A window shorter than 40rem
+steps each size down one step on its own.
+
+The virtualizer's `estimateSize` tracks `itemSize` too. Every row is re-measured
+immediately, so the estimate only decides how far the scrollbar lies before the first
+measurement lands — but a `lg` list opening with a scrollbar a third too short and visibly
+settling is exactly the kind of thing nobody files a bug about.
+
+<Canvas of={ComboboxStories.ItemSizes} />

package/src/Combobox/Combobox.stories.tsx

@@ -1,9 +1,15 @@
 import { useVisibility } from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
 import type { Meta, StoryObj } from "@storybook/react"
 import type { ReactNode } from "react"
 import { useRef, useState } from "react"
 
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
 import { Button } from "../Button/Button.tsx"
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
 import type { ListboxItem } from "../Listbox/Listbox.tsx"
 import { Combobox } from "./Combobox.tsx"
 
@@ -49,6 +55,8 @@ const meta = {
   title: "Components/Controls/Combobox",
   component: Combobox,
   parameters: { layout: "padded" },
+  argTypes: { itemSize: controlSizeArgType },
+  args: { itemSize: "md" },
 } satisfies Meta<typeof Combobox>
 
 export default meta
@@ -65,6 +73,7 @@ const ComboboxHarness = ({
   isLoading,
   isMultiple,
   isVirtualized,
+  itemSize,
   options,
   selectedValue,
   triggerLabel,
@@ -78,6 +87,7 @@ const ComboboxHarness = ({
   isLoading?: boolean
   isMultiple?: boolean
   isVirtualized?: boolean
+  itemSize?: ControlSize
   options: ListboxItem[]
   selectedValue?: readonly string[] | string
   triggerLabel: string
@@ -105,6 +115,7 @@ const ComboboxHarness = ({
         isLoading={isLoading}
         isMultiple={isMultiple}
         isVirtualized={isVirtualized}
+        itemSize={itemSize}
         isVisible={isVisible}
         onDismiss={hide}
         onSelect={(value) => {
@@ -589,3 +600,57 @@ export const VirtualizedChosenValue: Story = {
     />
   ),
 }
+
+/**
+ * The three row sizes — and the fix the owner's screenshot asked for.
+ *
+ * The report was that a `Combobox`'s trigger was visibly bigger than
+ * the options under it. Two things were true at once: the option row
+ * was a hardcoded `px-2 py-1.5 text-sm` that no control shares, and
+ * the panel's **own** search field was bigger than the options it
+ * filters — two sizes inside one panel, which is the defect rather
+ * than either number being wrong.
+ *
+ * `itemSize` now drives the search row and the options together, from
+ * the same `--control-height-*` a `Button` reads. At the `md` default
+ * a trigger, the search field and every option are all 2.25rem.
+ */
+export const ItemSizes: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Search languages</Button>,
+  },
+  render: () => (
+    <StoryGrid columns={3}>
+      <StoryCell label="sm — the old option">
+        <ComboboxHarness
+          isInitiallyVisible
+          itemSize="sm"
+          options={LANGUAGES}
+          triggerLabel="Search languages"
+        />
+      </StoryCell>
+
+      <StoryCell label="md — the default, matches the trigger">
+        <ComboboxHarness
+          isInitiallyVisible
+          itemSize="md"
+          options={LANGUAGES}
+          triggerLabel="Search languages"
+        />
+      </StoryCell>
+
+      <StoryCell label="lg — the fat option (44px)">
+        <ComboboxHarness
+          isInitiallyVisible
+          itemSize="lg"
+          options={LANGUAGES}
+          triggerLabel="Search languages"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}

package/src/Combobox/Combobox.test.tsx

@@ -705,3 +705,49 @@ test("a windowed list reseeds its window on every open, not just the first", asy
     mounted.body.queryByRole("option", { name: "Track 1" }),
   ).toBeNull()
 })
+
+/**
+ * One panel, one row size.
+ *
+ * The owner's report was that the search field was visibly bigger
+ * than the options it filters — *"the button is huge, but the options
+ * don't match it"* — and two sizes inside one panel is the defect,
+ * not the field being wrong or the option being wrong. `itemSize`
+ * drives both, so this measures the pair rather than either number.
+ */
+test("the search row and an option are the same height", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Search languages",
+      role: "button",
+    }),
+  )
+
+  const input = body.getByRole("combobox")
+
+  await waitFor(() => {
+    expect(input).toHaveFocus()
+  })
+
+  // The row is the input's *parent*: the input itself is a bare
+  // `flex-1` field, and the box that carries the row-size class — the
+  // height, the inline padding, the type — is the wrapper around it.
+  const searchRow = input.closest("div")
+
+  const [option] = body.getAllByRole("option")
+
+  expect(option).toBeDefined()
+
+  expect(searchRow?.getBoundingClientRect().height).toBe(
+    option?.getBoundingClientRect().height,
+  )
+
+  // And the query reads at the size of the options it is filtering,
+  // which is inherited from that wrapper rather than set on the input.
+  expect(globalThis.getComputedStyle(input).fontSize).toBe(
+    globalThis.getComputedStyle(option as HTMLElement)
+      .fontSize,
+  )
+})

package/src/Combobox/Combobox.tsx

@@ -1,3 +1,4 @@
+import type { ControlSize } from "@charcuterie/tokens"
 import {
   FloatingFocusManager,
   FloatingPortal,
@@ -11,9 +12,11 @@ import type {
 } from "react"
 import { useEffect, useRef, useState } from "react"
 
+import { PANEL_ITEM_SIZE_CLASS } from "../controlStyles.ts"
 import type { ListboxItem } from "../Listbox/Listbox.tsx"
 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 { ComboboxOption } from "./ComboboxOption.tsx"
 
@@ -48,6 +51,18 @@ export type ComboboxProps = {
   /** Windowing. Auto-on above ~100 options when left undefined. */
   isVirtualized?: boolean
   isVisible: boolean
+  /**
+   * How tall each option — and the search field above them — is, from
+   * the same density-aware tokens a `Button` reads.
+   *
+   * It covers the search row deliberately. The owner's report was that
+   * the panel's own field was visibly bigger than the options under it
+   * (*"the button is huge, but the options don't match it"*), and two
+   * sizes inside one panel is the defect. One prop drives both.
+   *
+   * A short window steps it back down on its own (`usePanelItemSize`).
+   */
+  itemSize?: ControlSize
   onDismiss: () => void
   onSelect: (value: string) => void
   /**
@@ -71,6 +86,20 @@ export type ComboboxProps = {
 
 const AUTO_VIRTUALIZE_THRESHOLD = 100
 
+/**
+ * The virtualizer's pre-measurement guess per row size, in px at
+ * `comfortable` density — `--control-height-*` plus the row's own
+ * `py-*`. Hardcoded because a virtualizer wants a number before the
+ * first paint, which is the one place a token cannot reach; every row
+ * is measured immediately afterwards, so a density that disagrees
+ * costs a frame rather than a wrong layout.
+ */
+const ROW_ESTIMATE_PX: Record<ControlSize, number> = {
+  sm: 40,
+  md: 48,
+  lg: 60,
+}
+
 /**
  * How many frames the open seed will wait for the panel to be capped
  * before it gives up on centring the chosen row. A few is all
@@ -130,6 +159,7 @@ export const Combobox = ({
   isMultiple = false,
   isVirtualized,
   isVisible,
+  itemSize: requestedItemSize = "md",
   onDismiss,
   onQueryChange,
   onSelect,
@@ -139,6 +169,8 @@ export const Combobox = ({
   selectedValue,
   trigger,
 }: ComboboxProps): ReactNode => {
+  const itemSize = usePanelItemSize(requestedItemSize)
+
   // Attached-input mode: the consumer's `<input>` is the reference,
   // query source, focus holder and keyboard target; Combobox renders the
   // list-only panel.
@@ -254,7 +286,12 @@ export const Combobox = ({
 
   const rowVirtualizer = useVirtualizer({
     count: filtered.length,
-    estimateSize: () => 36,
+    // An *estimate*: every row is re-measured (`measureElement` on the
+    // wrapper below), so this only decides how far the scrollbar lies
+    // before the first measurement lands. It still has to track
+    // `itemSize`, or a `lg` list opens with a scrollbar a third too
+    // short and visibly settles.
+    estimateSize: () => ROW_ESTIMATE_PX[itemSize],
     getScrollElement: () => listElement.current,
     overscan: 8,
   })
@@ -735,6 +772,7 @@ export const Combobox = ({
       isActive={index === resolvedActiveIndex}
       isSelected={selected.includes(option.value)}
       item={option}
+      itemSize={itemSize}
       key={option.value}
       onSelect={commitValue}
       posInSet={isWindowed ? index + 1 : undefined}
@@ -806,29 +844,43 @@ export const Combobox = ({
               style={floatingStyles}
             >
               {isAttached ? null : (
-                // px-3 aligns the input's text start with the options
-                // below: each option sits at 0.75rem (listbox p-1 + option
-                // px-2), so the search row needs the same 0.75rem inset.
-                <div className="flex items-center gap-1 border-border-subtle border-b px-3 py-2">
-                  <input
-                    aria-activedescendant={
-                      activeDescendantId
-                    }
-                    aria-autocomplete="list"
-                    aria-controls={listboxId}
-                    aria-expanded="true"
-                    aria-labelledby={triggerId}
-                    className="min-w-24 flex-1 bg-transparent text-content-primary text-sm outline-none placeholder:text-content-muted"
-                    onChange={(changeEvent) => {
-                      setQuery(changeEvent.target.value)
-                    }}
-                    onKeyDown={handleKeyDown}
-                    placeholder={placeholder}
-                    ref={internalInputElement}
-                    role="combobox"
-                    type="text"
-                    value={currentQuery}
-                  />
+                // The `p-1` is the list container's own padding, repeated
+                // here so the search caret starts exactly where the option
+                // labels below it do — the alignment a hand-picked `px-3`
+                // used to approximate, and which broke the moment the row
+                // padding became a token. The border stays on the outer
+                // element, so it still spans the whole panel.
+                <div className="border-border-subtle border-b p-1">
+                  <div
+                    className={toClassName(
+                      "flex items-center",
+                      PANEL_ITEM_SIZE_CLASS[itemSize],
+                    )}
+                  >
+                    <input
+                      aria-activedescendant={
+                        activeDescendantId
+                      }
+                      aria-autocomplete="list"
+                      aria-controls={listboxId}
+                      aria-expanded="true"
+                      aria-labelledby={triggerId}
+                      // No `text-*` of its own: the wrapper's row-size
+                      // class sets the font size, and the input inherits
+                      // it — so the query reads at exactly the size of
+                      // the options it is filtering.
+                      className="min-w-24 flex-1 bg-transparent text-content-primary outline-none placeholder:text-content-muted"
+                      onChange={(changeEvent) => {
+                        setQuery(changeEvent.target.value)
+                      }}
+                      onKeyDown={handleKeyDown}
+                      placeholder={placeholder}
+                      ref={internalInputElement}
+                      role="combobox"
+                      type="text"
+                      value={currentQuery}
+                    />
+                  </div>
                 </div>
               )}
 

package/src/Combobox/ComboboxOption.tsx

@@ -1,5 +1,7 @@
+import type { ControlSize } from "@charcuterie/tokens"
 import type { ReactNode } from "react"
 
+import { PANEL_ITEM_SIZE_CLASS } from "../controlStyles.ts"
 import type { ListboxItem } from "../Listbox/Listbox.tsx"
 import { toClassName } from "../toClassName.ts"
 
@@ -8,6 +10,8 @@ export type ComboboxOptionProps = {
   id: string
   isActive: boolean
   isSelected: boolean
+  /** Already stepped down for a short window by `usePanelItemSize`. */
+  itemSize: ControlSize
   item: ListboxItem
   onSelect: (value: string) => void
   /**
@@ -41,6 +45,7 @@ export const ComboboxOption = ({
   isActive,
   isSelected,
   item,
+  itemSize,
   onSelect,
   posInSet,
   setSize,
@@ -60,7 +65,12 @@ export const ComboboxOption = ({
         // fill and the keyboard cursor was invisible (it read as "arrows
         // do nothing"). A button's background is transparent by default;
         // the tint classes only ever add one.
-        "flex w-full cursor-pointer items-center justify-between gap-2 rounded-sm px-2 py-1.5 text-start text-sm",
+        "flex w-full cursor-pointer items-center justify-between rounded-sm text-start",
+        // Height, inline padding, gap and type from the row-size system,
+        // so an option matches the search field above it and the trigger
+        // that opened it, rather than being visibly the smaller thing in
+        // its own panel.
+        PANEL_ITEM_SIZE_CLASS[itemSize],
         // The base sets no text colour: a plain `text-content-primary`
         // clobbers a conditional `text-content-disabled` at equal
         // specificity (Tailwind emits the base last), so a disabled option

package/src/Listbox/Listbox.mdx

@@ -66,3 +66,27 @@ is no `heading` prop; the button names the widget. The panel height is clamped t
 viewport by floating-ui's `size` middleware and scrolls within it.
 
 <Canvas of={ListboxStories.Interactive} />
+
+## An option is the size of the control that opened it
+
+`itemSize` takes the same `sm` / `md` / `lg` a `Button` takes, from the same
+density-aware `--control-height-*` tokens. It **defaults to `md`** — 2.25rem, the height a
+default `Button` and a `Select` already take — so a picker's options measure the same as
+its trigger.
+
+That default is a fix, not a preference. The rows were a hardcoded `px-2 py-1.5 text-sm`
+that no control in the library shares, so an option was visibly the smaller thing inside
+its own panel; the owner's report was *"the button is huge, but the options don't match
+it"*.
+
+`lg` is the fat one: 2.75rem, the 44px WCAG 2.5.5 target, for a list that is aimed at
+rather than scanned. `sm` is what this component rendered before, kept for a genuinely
+dense list.
+
+The floor is a **minimum**, not a fixed height (`min-h-`, where a `Button` uses `h-`) — the
+rich option below, with a flag and a trailing `Badge`, still grows past it.
+
+A window shorter than 40rem steps each size down one step on its own, and one shorter than
+30rem takes them to `sm`.
+
+<Canvas of={ListboxStories.ItemSizes} />

package/src/Listbox/Listbox.stories.tsx

@@ -1,12 +1,20 @@
 import { useVisibility } from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
 import type { Meta, StoryObj } from "@storybook/react"
 import type { ReactNode } from "react"
 import { useState } from "react"
 
-import { placementArgType } from "../argTypes.storyHelpers.ts"
+import {
+  controlSizeArgType,
+  placementArgType,
+} from "../argTypes.storyHelpers.ts"
 import { Badge } from "../Badge/Badge.tsx"
 import { Button } from "../Button/Button.tsx"
-import { StoryRow } from "../board.storyHelpers.tsx"
+import {
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+} from "../board.storyHelpers.tsx"
 import type { ListboxItem } from "./Listbox.tsx"
 import { Listbox } from "./Listbox.tsx"
 
@@ -73,8 +81,11 @@ const meta = {
   title: "Components/Controls/Listbox",
   component: Listbox,
   parameters: { layout: "padded" },
-  argTypes: { placement: placementArgType },
-  args: { placement: "bottom-start" },
+  argTypes: {
+    itemSize: controlSizeArgType,
+    placement: placementArgType,
+  },
+  args: { itemSize: "md", placement: "bottom-start" },
 } satisfies Meta<typeof Listbox>
 
 export default meta
@@ -83,14 +94,20 @@ type Story = StoryObj<typeof meta>
 
 const ListboxHarness = ({
   initialSelected,
+  isInitiallyVisible = false,
+  itemSize,
   options,
   triggerLabel,
 }: {
   initialSelected?: string
+  isInitiallyVisible?: boolean
+  itemSize?: ControlSize
   options: ListboxItem[]
   triggerLabel: string
 }): ReactNode => {
-  const { hide, isVisible, toggle } = useVisibility()
+  const { hide, isVisible, toggle } = useVisibility({
+    isVisible: isInitiallyVisible,
+  })
 
   const [selected, setSelected] = useState<
     string | undefined
@@ -111,6 +128,7 @@ const ListboxHarness = ({
   return (
     <Listbox
       isVisible={isVisible}
+      itemSize={itemSize}
       onDismiss={hide}
       onSelect={setSelected}
       options={options}
@@ -203,3 +221,61 @@ export const Interactive: Story = {
     />
   ),
 }
+
+/**
+ * The three option sizes, open side by side.
+ *
+ * `md` is the default, and the reason is the report that started this
+ * work: an option that is smaller than the control which opened it
+ * reads as a different, lesser thing inside its own panel. `md` is
+ * `--control-height-md` — the same 2.25rem a default `Button` and a
+ * `Select` take — so a picker's options now measure the same as its
+ * trigger.
+ *
+ * `lg` is the fat one: 2.75rem, the 44px target, for a list that is
+ * aimed at rather than scanned. `sm` is what this component rendered
+ * before, kept for a genuinely dense list.
+ *
+ * The floor is a **minimum**, not a fixed height — the rich option
+ * below (flag, name, badge) still grows past it, which is why this is
+ * `min-h-` and a `Button`'s is `h-`.
+ */
+export const ItemSizes: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Language</Button>,
+  },
+  render: () => (
+    <StoryGrid columns={3}>
+      <StoryCell label="sm — the old option">
+        <ListboxHarness
+          isInitiallyVisible
+          itemSize="sm"
+          options={LANGUAGES}
+          triggerLabel="Language"
+        />
+      </StoryCell>
+
+      <StoryCell label="md — the default, matches the trigger">
+        <ListboxHarness
+          isInitiallyVisible
+          itemSize="md"
+          options={LANGUAGES}
+          triggerLabel="Language"
+        />
+      </StoryCell>
+
+      <StoryCell label="lg — the fat option (44px)">
+        <ListboxHarness
+          isInitiallyVisible
+          itemSize="lg"
+          options={LANGUAGES}
+          triggerLabel="Language"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}

package/src/Listbox/Listbox.tsx

@@ -3,6 +3,7 @@ import {
   useRovingFocus,
   useSinglePicker,
 } from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
 import type { Placement } from "@floating-ui/react"
 import {
   FloatingFocusManager,
@@ -13,6 +14,7 @@ import { useEffect, useRef } from "react"
 
 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 { ListboxOption } from "./ListboxOption.tsx"
 
@@ -31,6 +33,17 @@ export type ListboxItem = {
 export type ListboxProps = {
   className?: string
   isVisible: boolean
+  /**
+   * How tall each option is, from the same density-aware tokens a
+   * `Button` reads — so a `md` option is exactly as tall as the `md`
+   * trigger that opened it. `lg` is the fat one: 2.75rem at
+   * `comfortable` density, and a bigger target to aim at.
+   *
+   * A short window steps it back down on its own
+   * (`usePanelItemSize`), so a `lg` list is never the reason the last
+   * option is off-screen.
+   */
+  itemSize?: ControlSize
   /** Outside press and Escape both land here. */
   onDismiss: () => void
   onSelect: (value: string) => void
@@ -79,6 +92,7 @@ const getOptionText = (item: ListboxItem) =>
 export const Listbox = ({
   className,
   isVisible,
+  itemSize: requestedItemSize = "md",
   onDismiss,
   onSelect,
   options,
@@ -86,6 +100,8 @@ export const Listbox = ({
   selectedValue,
   trigger,
 }: ListboxProps): ReactNode => {
+  const itemSize = usePanelItemSize(requestedItemSize)
+
   const optionElements = useRef(
     new Map<string, HTMLButtonElement>(),
   )
@@ -266,6 +282,7 @@ export const Listbox = ({
                     picker.selectedValue === option.value
                   }
                   item={option}
+                  itemSize={itemSize}
                   key={option.value}
                   onSelect={chooseValue}
                   registerFocus={focus.register}