@charcuterie/ui 3.18.0 → 3.19.2

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.
@@ -155,6 +187,26 @@ export const Combobox = ({
 
   const listElement = useRef<HTMLDivElement>(null)
 
+  /**
+   * The same node as `listElement`, held in state as well as a ref.
+   *
+   * The panel's children mount a render *later* than `isVisible` flips —
+   * floating-ui's `FloatingPortal` renders nothing until its portal node
+   * exists — so an effect keyed on `isVisible` runs while the ref is
+   * still null. Anything that has to touch the list the moment it
+   * appears keys on this instead.
+   */
+  const [listNode, setListNode] =
+    useState<HTMLDivElement | null>(null)
+
+  const attachListElement = (
+    node: HTMLDivElement | null,
+  ) => {
+    listElement.current = node
+
+    setListNode(node)
+  }
+
   const isQueryControlled = query !== undefined
 
   const [internalQuery, setInternalQuery] = useState("")
@@ -254,7 +306,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,
   })
@@ -284,6 +341,49 @@ export const Combobox = ({
             !option.isDisabled,
         )
 
+  /**
+   * The virtualizer outlives the panel, and its scroll offset does not
+   * come back with it.
+   *
+   * `Combobox` stays mounted while the list element is created and
+   * destroyed on every open, so `useVirtualizer` keeps the offset from
+   * the last time the list was on screen. The freshly mounted element is
+   * at 0. The window it renders is then the one for a scroll position
+   * that no longer exists: a blank band down the top of the panel, with
+   * the rows for the old offset stranded below it.
+   *
+   * Re-sync once per open, before the seed's own scroll (which lands a
+   * frame later, so it still wins where there is a chosen row to centre).
+   */
+  const hasResyncedVirtualizer = useRef(false)
+
+  useEffect(() => {
+    if (!isVisible) {
+      hasResyncedVirtualizer.current = false
+
+      return
+    }
+
+    if (
+      hasResyncedVirtualizer.current ||
+      !isWindowed ||
+      listNode === null
+    ) {
+      return
+    }
+
+    hasResyncedVirtualizer.current = true
+
+    // A `scroll` event, because that is the only thing the virtualizer
+    // listens to. `observeOffset` attaches its listener and never reads
+    // the element it just attached to, so a replaced element sitting at 0
+    // cannot correct an instance that still believes it is at 500 —
+    // nothing moves, so nothing fires. `scrollToOffset(0)` does not help
+    // for the same reason: it asks for a position the element already
+    // holds, which raises no event either.
+    listNode.dispatchEvent(new Event("scroll"))
+  }, [isVisible, isWindowed, listNode])
+
   const hasSeededOnOpen = useRef(false)
 
   /**
@@ -735,6 +835,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 +907,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>
               )}
 
@@ -844,7 +959,7 @@ export const Combobox = ({
                 }
                 className="min-h-0 flex-1 overflow-auto p-1"
                 id={listboxId}
-                ref={listElement}
+                ref={attachListElement}
                 role="listbox"
               >
                 {isLoading ? (

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}

package/src/Listbox/ListboxOption.tsx

@@ -1,12 +1,16 @@
+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 { ListboxItem } from "./Listbox.tsx"
 
 export type ListboxOptionProps = {
   isSelected: boolean
+  /** Already stepped down for a short window by `usePanelItemSize`. */
+  itemSize: ControlSize
   item: ListboxItem
   onSelect: (value: string) => void
   /** `RovingFocus.register` — membership of the arrow-key group. */
@@ -44,6 +48,7 @@ export type ListboxOptionProps = {
 export const ListboxOption = ({
   isSelected,
   item,
+  itemSize,
   onSelect,
   registerFocus,
   registerSelection,
@@ -73,7 +78,11 @@ export const ListboxOption = ({
         // and silently won at equal specificity, so the selected option's
         // accent fill never showed (only its ✓ did). Default is
         // transparent anyway; the tints below add a fill.
-        "flex w-full cursor-pointer items-center justify-between gap-2 rounded-sm px-2 py-1.5 text-start text-sm transition-colors duration-(--duration-fast) ease-standard",
+        "flex w-full cursor-pointer items-center justify-between rounded-sm text-start transition-colors duration-(--duration-fast) ease-standard",
+        // Height, inline padding, gap and type from the row-size system,
+        // so an option is at least as tall as the control that opened it
+        // and a rich two-line label still grows past that floor.
+        PANEL_ITEM_SIZE_CLASS[itemSize],
         // The base sets no text colour: a plain `text-content-primary` in
         // it clobbers a conditional `text-content-disabled` at equal
         // specificity (Tailwind emits the base last), so a disabled option

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