@charcuterie/ui 2.4.0 → 2.5.0

package/src/Checkbox/Checkbox.stories.tsx

@@ -0,0 +1,100 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Checkbox } from "./Checkbox.tsx"
+
+const meta = {
+  title: "Components/Checkbox",
+  component: Checkbox,
+  parameters: { layout: "padded" },
+  argTypes: { size: controlSizeArgType },
+  // The component's own defaults, restated — Storybook does not seed
+  // `args` from docgen, so an unstated default shows in the props
+  // table with nothing selected in its control.
+  args: { isChecked: false, isDisabled: false, size: "md" },
+} satisfies Meta<typeof Checkbox>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { label: "Delete originals after import" },
+}
+
+export const AllVariants: Story = {
+  args: { label: "Delete originals after import" },
+  render: (controlProps) => (
+    <StorySection title="Three control heights, all reading the density axis rather than hardcoding a length.">
+      <StoryGrid columns={3}>
+        {(["sm", "md", "lg"] as const).map((size) => (
+          <StoryCell key={size} label={size}>
+            <Checkbox
+              {...controlProps}
+              isChecked
+              label={`Enabled at ${size}`}
+              size={size}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * `isChecked` seeds the first paint and nothing after — the `<input>`
+ * owns its state from then on, so a disabled-and-checked box is a
+ * saved preference the user cannot currently change, not a bug.
+ */
+export const AllStates: Story = {
+  args: { label: "Delete originals after import" },
+  render: (controlProps) => (
+    <StorySection title="What varies is whether the box is checked and whether it can be changed.">
+      <StoryGrid columns={2}>
+        <StoryCell label="unchecked">
+          <Checkbox {...controlProps} label="Unchecked" />
+        </StoryCell>
+
+        <StoryCell label="checked">
+          <Checkbox
+            {...controlProps}
+            isChecked
+            label="Checked"
+          />
+        </StoryCell>
+
+        <StoryCell label="disabled, unchecked">
+          <Checkbox
+            {...controlProps}
+            isDisabled
+            label="Disabled"
+          />
+        </StoryCell>
+
+        <StoryCell label="disabled, checked">
+          <Checkbox
+            {...controlProps}
+            isChecked
+            isDisabled
+            label="Disabled and checked"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * The whole keyboard path is the browser's: Tab reaches the box,
+ * Space toggles it. A `<label>` wrapping the control is what makes a
+ * pointer press on the *text* toggle it too.
+ */
+export const Interactive: Story = {
+  args: { label: "Delete originals after import" },
+}

package/src/Checkbox/Checkbox.test.tsx

@@ -0,0 +1,80 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Checkbox.stories.tsx"
+
+const { AllStates, Default, Interactive } =
+  composeStories(stories)
+
+test("it is a checkbox a screen reader can name", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  const checkbox = expectAgentDrivable(canvas, {
+    name: "Delete originals after import",
+    role: "checkbox",
+  })
+
+  await expect(checkbox).not.toBeChecked()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a press toggles it, and the label is part of the target", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const checkbox = expectAgentDrivable(canvas, {
+    name: "Delete originals after import",
+    role: "checkbox",
+  })
+
+  // The label wraps the control, so a click on the text is a click
+  // on the box — which is the association `<label htmlFor>` gets
+  // wrong half the time in the fleet and this cannot.
+  await userEvent.click(checkbox)
+
+  await waitFor(() => {
+    expect(checkbox).toBeChecked()
+  })
+
+  await userEvent.click(checkbox)
+
+  await waitFor(() => {
+    expect(checkbox).not.toBeChecked()
+  })
+})
+
+test("a disabled box cannot be toggled", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const disabled = expectAgentDrivable(canvas, {
+    name: "Disabled",
+    role: "checkbox",
+  })
+
+  await expect(disabled).toBeDisabled()
+
+  await expect(disabled).not.toBeChecked()
+
+  await userEvent.click(disabled)
+
+  await expect(disabled).not.toBeChecked()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("isChecked decides the first render", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Checked",
+      role: "checkbox",
+    }),
+  ).toBeChecked()
+})

package/src/Checkbox/Checkbox.tsx

@@ -0,0 +1,146 @@
+import type { ControlSize } from "@charcuterie/tokens"
+import type { ChangeEvent, ReactNode } from "react"
+
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+
+export type CheckboxProps = {
+  className?: string
+  /**
+   * The caller's own id, when it has one — a stable target for an
+   * autofill hint or a deep link. Left to React's `useId` on the
+   * `<input>` otherwise, which is enough for the wrapping `<label>`.
+   */
+  id?: string
+  /**
+   * **Initial** only. The `<input>` is the store from then on — the
+   * DOM owns a checkbox's checkedness, and a controlled `checked`
+   * prop is the thing this library refuses to have
+   * (`SegmentedControl` says the same about `selectedValue`).
+   */
+  isChecked?: boolean
+  isDisabled?: boolean
+  /**
+   * The visible text beside the box, and the checkbox's accessible
+   * name — the `<label>` wraps the control, so there is no `for` to
+   * get wrong. A box with no label is a control a screen reader
+   * cannot announce, which is why this is required.
+   */
+  label: ReactNode
+  onChange?: (isChecked: boolean) => void
+  size?: ControlSize
+}
+
+const BOX_SIZE_CLASS: Record<ControlSize, string> = {
+  sm: "size-3.5",
+  md: "size-4",
+  lg: "size-5",
+}
+
+const CHECK_SIZE_CLASS: Record<ControlSize, string> = {
+  sm: "size-2.5",
+  md: "size-3",
+  lg: "size-3.5",
+}
+
+const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
+  sm: "text-sm",
+  md: "text-md",
+  lg: "text-lg",
+}
+
+/**
+ * A single boolean, on or off, that owns nothing but itself.
+ *
+ * This is the primitive mux-magic's `BooleanField` hand-rolled in
+ * `bg-slate-700 accent-blue-500` because the library had no checkbox
+ * to reach for — palette colours with no light mode, the exact M6
+ * defect the token layer exists to delete. Here the box is
+ * `bg-surface-sunken` and the fill is `bg-intent-accent-solid`, so
+ * one control reads correctly in `daylight`, `midnight`, and on the
+ * kiosk with no per-app override.
+ *
+ * ### The `<label>` wraps the control
+ *
+ * A checkbox reads to the *left* of its text, which is why it is not
+ * a `Field` — `Field` stacks label above control in a `flex-col`,
+ * right for a text input and wrong for a boolean, and stacking every
+ * checkbox in a step card would double the card's height. Wrapping is
+ * also the one label association that needs no `for` at all, so there
+ * is no minted-then-dropped id to get wrong.
+ *
+ * ### The `<input>` is the store
+ *
+ * `defaultChecked`, not `checked`. The DOM owns a checkbox's state
+ * natively, so there is no second copy to keep in step and no
+ * controlled-prop round-trip — `onChange` reports the new state to a
+ * consumer that wants to persist it, and reading it back is the
+ * `<input>`'s job. `isChecked` seeds the first paint and nothing
+ * after.
+ */
+export const Checkbox = ({
+  className,
+  id,
+  isChecked = false,
+  isDisabled = false,
+  label,
+  onChange,
+  size = "md",
+}: CheckboxProps): ReactNode => (
+  <label
+    className={toClassName(
+      "inline-flex cursor-pointer items-center gap-2 text-content-secondary select-none",
+      TEXT_SIZE_CLASS[size],
+      isDisabled &&
+        "cursor-not-allowed text-content-disabled",
+      className,
+    )}
+  >
+    <span className="relative grid shrink-0 place-items-center">
+      <input
+        className={toClassName(
+          "peer cursor-pointer appearance-none rounded-sm border border-border-strong bg-surface-sunken transition-colors duration-(--duration-fast) ease-standard",
+          "checked:border-intent-accent-solid checked:bg-intent-accent-solid",
+          // Disabled mutes the border and the cursor, and — unlike the
+          // shared `DISABLED_CLASS` — does *not* touch the background.
+          // The generic bundle repaints the box `surface-sunken`, which
+          // erased both the checked accent fill (white tick on grey)
+          // and, in a light scheme, the unchecked box entirely: a
+          // `border-subtle` outline on `surface-sunken` on
+          // `surface-base` is three near-identical creams. A disabled
+          // box is still a box the user has to see.
+          "disabled:cursor-not-allowed disabled:border-border-default",
+          BOX_SIZE_CLASS[size],
+          FOCUS_RING_CLASS,
+        )}
+        defaultChecked={isChecked}
+        disabled={isDisabled}
+        id={id}
+        onChange={(
+          event: ChangeEvent<HTMLInputElement>,
+        ) => {
+          onChange?.(event.target.checked)
+        }}
+        type="checkbox"
+      />
+
+      <svg
+        aria-hidden="true"
+        className={toClassName(
+          "pointer-events-none invisible absolute text-intent-accent-on-solid peer-checked:visible",
+          CHECK_SIZE_CLASS[size],
+        )}
+        fill="none"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={3}
+        viewBox="0 0 24 24"
+      >
+        <path d="M20 6 9 17l-5-5" />
+      </svg>
+    </span>
+
+    <span>{label}</span>
+  </label>
+)

package/src/Combobox/Combobox.stories.tsx

@@ -44,6 +44,7 @@ export default meta
 type Story = StoryObj<typeof meta>
 
 const ComboboxHarness = ({
+  className,
   emptyLabel,
   error,
   footer,
@@ -55,6 +56,7 @@ const ComboboxHarness = ({
   options,
   triggerLabel,
 }: {
+  className?: string
   emptyLabel?: string
   error?: ReactNode
   footer?: ReactNode
@@ -75,6 +77,7 @@ const ComboboxHarness = ({
   return (
     <>
       <Combobox
+        className={className}
         emptyLabel={emptyLabel}
         error={error}
         footer={footer}
@@ -85,11 +88,20 @@ const ComboboxHarness = ({
         isVisible={isVisible}
         onDismiss={hide}
         onSelect={(value) => {
-          setChosen((previous) =>
-            previous.includes(value)
+          // Mirror the control's own selection model so the "Chosen"
+          // line never disagrees with the ticks in the list: multi-select
+          // accumulates/toggles, single-select replaces (one value, one
+          // ✓). Toggling into an array in single-select made the line
+          // claim several were chosen while only the last carried a tick.
+          setChosen((previous) => {
+            if (!isMultiple) {
+              return [value]
+            }
+
+            return previous.includes(value)
               ? previous.filter((one) => one !== value)
-              : [...previous, value],
-          )
+              : [...previous, value]
+          })
         }}
         options={options}
         trigger={
@@ -388,3 +400,51 @@ export const DisabledFirstOption: Story = {
     />
   ),
 }
+
+// 150 long folder names: over the ~100 auto-virtualize threshold, and in
+// a narrow (`w-72`) panel each wraps to two lines — the combination that
+// broke. The virtualizer estimates 36px/row, so a fixed-height row clipped
+// the second line and stacked the next row on top of it (overlapping
+// text). This is the regression guard for the measured-row fix.
+const MANY_LONG: ListboxItem[] = Array.from(
+  { length: 150 },
+  (_unused, index) => {
+    const name = `Armored Trooper Votoms - Very Long Chapter Title Number ${index + 1} [anidb-${1000 + index}]`
+
+    return {
+      label: `📁 ${name}`,
+      textValue: name,
+      value: name,
+    }
+  },
+)
+
+/**
+ * The real-world break: **many** long option labels in a **narrow** panel,
+ * so the list both virtualizes (over ~100 options) and wraps each row to
+ * two lines. Rows are measured, not pinned to the 36px estimate, so they
+ * lay out below one another instead of overlapping.
+ *
+ * Multi-select as well, so it exercises the case together: every picked
+ * row keeps its own ✓ (a virtualized row that scrolls out and back is
+ * re-rendered from `selected`, not remembered by the DOM), and the chips
+ * above the trigger stay in sync with the ticks.
+ */
+export const VirtualizedLongOptions: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: MANY_LONG,
+    trigger: <Button>Search folders</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      className="w-72"
+      isInitiallyVisible
+      isMultiple
+      options={MANY_LONG}
+      triggerLabel="Search folders"
+    />
+  ),
+}

package/src/Combobox/Combobox.tsx

@@ -679,9 +679,21 @@ export const Combobox = ({
                         return (
                           <div
                             className="absolute start-0 top-0 w-full"
+                            // Measured, not fixed-height. A long option
+                            // label wraps to two lines (~56px), but the
+                            // estimate is 36px — so pinning the row to
+                            // `virtualRow.size` clipped it to one line's
+                            // worth and stacked the next row on top of it,
+                            // and the popup rendered as overlapping text.
+                            // `measureElement` + `data-index` let the
+                            // virtualizer read each row's real height and
+                            // lay the rest out below it.
+                            data-index={virtualRow.index}
                             key={option.value}
+                            ref={
+                              rowVirtualizer.measureElement
+                            }
                             style={{
-                              height: `${virtualRow.size}px`,
                               transform: `translateY(${virtualRow.start}px)`,
                             }}
                           >

package/src/Field/Field.stories.tsx

@@ -36,6 +36,25 @@ export const Default: Story = {
   },
 }
 
+/**
+ * The control carries its own `id` — `rename-pattern`, the kind of
+ * stable id a deep link or a server-rendered error summary points at.
+ * The `Field` adopts it rather than minting a `-control` id over the
+ * top, so the `<label htmlFor>` and every outside-in reference agree.
+ */
+export const AdoptsChildId: Story = {
+  args: {
+    children: (
+      <input
+        className={TEXT_INPUT_CLASS}
+        id="rename-pattern"
+        type="text"
+      />
+    ),
+    label: "Rename pattern",
+  },
+}
+
 /**
  * The control is a slot, not a hardcoded `<input>` — `Select` goes
  * in the same hole, and so does an app's own control. The `id`,

package/src/Field/Field.test.tsx

@@ -7,8 +7,36 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Field.stories.tsx"
 
-const { AllStates, AllVariants, Default, Group, Nested } =
-  composeStories(stories)
+const {
+  AdoptsChildId,
+  AllStates,
+  AllVariants,
+  Default,
+  Group,
+  Nested,
+} = composeStories(stories)
+
+test("a control's own id is adopted, not overwritten", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AdoptsChildId)
+
+  // The child was written `<input id="rename-pattern" />`. The Field
+  // must keep that id — overwriting it with a minted `-control` id is
+  // what broke the outside-in references the id exists for — and the
+  // `<label htmlFor>` must agree, so the control is still findable by
+  // its label's text.
+  const control = expectAgentDrivable(canvas, {
+    name: "Rename pattern",
+    role: "textbox",
+  })
+
+  await expect(control).toHaveAttribute(
+    "id",
+    "rename-pattern",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
 
 test("the label names the control it points at", async () => {
   const { canvas, canvasElement } =

package/src/Field/Field.tsx

@@ -126,9 +126,21 @@ export const Field = ({
    * link, a server-rendered error summary linking to the control.
    * `useUniqueId` is still called: hooks are unconditional, and it
    * costs one counter read.
+   *
+   * Precedence is `Field` prop → **the child's own `id`** →
+   * generated. The child's is read because a control written as
+   * `<input id="rename-pattern" />` puts the id where the author can
+   * see it, not on the `Field`; overwriting it with a minted
+   * `-control` id used to break exactly the outside-in references the
+   * `Field` prop exists to keep — a deep link, an autofill hint, a
+   * consumer's own selector. The `Field` prop still wins when both
+   * are set: it is the outer, later declaration, and last-writer-wins
+   * is the slot's rule for a value.
    */
+  const childId = (children.props as { id?: string }).id
+
   const controlId =
-    receivedSlotProps.id ?? `${baseId}-control`
+    receivedSlotProps.id ?? childId ?? `${baseId}-control`
 
   const descriptionId = `${baseId}-description`
 

package/src/Menu/Menu.stories.tsx

@@ -14,7 +14,7 @@ import {
   UndoIcon,
 } from "../icons.storyHelpers.tsx"
 import { Tooltip } from "../Tooltip/Tooltip.tsx"
-import type { MenuItem } from "./Menu.tsx"
+import type { MenuEntry, MenuItem } from "./Menu.tsx"
 import { Menu } from "./Menu.tsx"
 
 const noop = () => undefined
@@ -41,18 +41,50 @@ const BAY_ACTIONS: MenuItem[] = [
   },
 ]
 
+const GROUPED_ACTIONS: MenuEntry[] = [
+  {
+    items: [
+      {
+        key: "retry",
+        label: "Retry title",
+        onSelect: noop,
+      },
+      { key: "skip", label: "Skip title", onSelect: noop },
+    ],
+    key: "disc",
+    label: "Disc",
+    type: "group",
+  },
+  { key: "sep", type: "separator" },
+  {
+    items: [
+      {
+        icon: <SettingsIcon />,
+        key: "eject",
+        label: "Eject disc",
+        onSelect: noop,
+      },
+    ],
+    key: "danger",
+    label: "Danger",
+    type: "group",
+  },
+]
+
 /**
  * A menu's visibility belongs to the app, exactly like `Popover`'s —
  * so the stories hold it in a `useVisibility`, which is what a
  * consumer writes too.
  */
 const MenuHarness = ({
+  emptyState,
   isInitiallyVisible = false,
   items = BAY_ACTIONS,
   triggerLabel,
 }: {
+  emptyState?: ReactNode
   isInitiallyVisible?: boolean
-  items?: MenuItem[]
+  items?: MenuEntry[]
   triggerLabel: string
 }): ReactNode => {
   const { hide, isVisible, toggle } = useVisibility({
@@ -61,6 +93,7 @@ const MenuHarness = ({
 
   return (
     <Menu
+      emptyState={emptyState}
       isVisible={isVisible}
       items={items}
       onDismiss={hide}
@@ -226,3 +259,48 @@ export const Interactive: Story = {
     <MenuHarness triggerLabel="Open bay 4 menu" />
   ),
 }
+
+/**
+ * `items` is a union — a `group` (`role="group"`, named by its
+ * label) and a `separator` (`role="separator"`) opt in by their
+ * `type`, and a bare item still works unchanged. Neither the
+ * separator nor the group headings register with the roving group,
+ * so arrow-down goes Retry → Skip → Eject, straight past both
+ * headings and the rule between them.
+ */
+export const Grouped: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: noop,
+    trigger: <Button appearance="outline">Actions</Button>,
+  },
+  render: () => (
+    <MenuHarness
+      isInitiallyVisible
+      items={GROUPED_ACTIONS}
+      triggerLabel="Bay 6"
+    />
+  ),
+}
+
+/**
+ * No actions to show. The `emptyState` renders as a **disabled**
+ * `menuitem` — a `role="menu"` must own one — so it is announced but
+ * takes no tab stop and no roving-focus membership, and a keyboard
+ * user can still Escape out of it.
+ */
+export const Empty: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: noop,
+    trigger: <Button appearance="outline">Actions</Button>,
+  },
+  render: () => (
+    <MenuHarness
+      emptyState="No actions available"
+      isInitiallyVisible
+      items={[]}
+      triggerLabel="Bay 7"
+    />
+  ),
+}