@charcuterie/ui 2.4.1 → 2.6.0

package/src/Checkbox/Checkbox.stories.tsx

@@ -0,0 +1,122 @@
+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,
+    isReadOnly: 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>
+
+        <StoryCell label="read-only, unchecked">
+          <Checkbox
+            {...controlProps}
+            isReadOnly
+            label="Read-only"
+          />
+        </StoryCell>
+
+        <StoryCell label="read-only, checked">
+          <Checkbox
+            {...controlProps}
+            isChecked
+            isReadOnly
+            label="Read-only 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,109 @@
+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()
+})
+
+test("a read-only box is announced and cannot be toggled", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const readOnly = expectAgentDrivable(canvas, {
+    name: "Read-only",
+    role: "checkbox",
+  })
+
+  // Full contrast, not `disabled` — a read-only value stays readable,
+  // and it is focusable so a screen reader reaches it. The state is
+  // carried by `aria-readonly`, not by removing it from the tree.
+  await expect(readOnly).toHaveAttribute(
+    "aria-readonly",
+    "true",
+  )
+
+  await expect(readOnly).not.toBeDisabled()
+
+  await expect(readOnly).not.toBeChecked()
+
+  await userEvent.click(readOnly)
+
+  // The pointer block held — the box did not flip.
+  await expect(readOnly).not.toBeChecked()
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/Checkbox/Checkbox.tsx

@@ -0,0 +1,205 @@
+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
+  /**
+   * Shows the value at full contrast but refuses to change it — a
+   * setting you may read here and edit elsewhere. Distinct from
+   * `isDisabled`, which dims: a read-only box is not turned down,
+   * because the whole point is that you can still read it. Announced
+   * as `aria-readonly`, and the toggle is blocked on both pointer and
+   * `Space`.
+   */
+  isReadOnly?: 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,
+  isReadOnly = false,
+  label,
+  onChange,
+  size = "md",
+}: CheckboxProps): ReactNode => (
+  <label
+    className={toClassName(
+      "inline-flex items-center gap-2 text-content-secondary select-none",
+      TEXT_SIZE_CLASS[size],
+      // One cursor, chosen by state — two cursor utilities of the same
+      // specificity do not resolve by class-list order.
+      isDisabled
+        ? "cursor-not-allowed"
+        : isReadOnly
+          ? "cursor-default"
+          : "cursor-pointer",
+      // Disabled dims the whole control with opacity rather than fading
+      // the box to a quieter token. The token scale has no step between
+      // `border-default` and `border-strong`, so a muted outline was
+      // either invisible or indistinguishable from enabled; `opacity-60`
+      // keeps the full shape and colour and just turns them down, which
+      // is the "present but inactive" the box actually is. Read-only is
+      // *not* dimmed — its whole point is that the value stays readable.
+      // The same treatment is on `Switch` and `RadioGroup`.
+      isDisabled && "opacity-60",
+      className,
+    )}
+  >
+    <span className="relative grid shrink-0 place-items-center">
+      <input
+        aria-readonly={isReadOnly || undefined}
+        className={toClassName(
+          // `border-2` is the family's shared weight — the `Switch`
+          // track's `ring-2` and the `RadioGroup` ring match it, so the
+          // three read as one set — and a 2px edge is also what keeps a
+          // disabled box visible where a 1px one washed out.
+          "peer appearance-none rounded-sm border-2 bg-surface-sunken transition-colors duration-(--duration-fast) ease-standard",
+          // Read-only wears the **neutral** intent, not the accent: full
+          // contrast (so the value reads) but plainly not an actionable
+          // accent control, with a softer `border-default` resting edge.
+          // Three distinct states result — enabled (accent, crisp),
+          // disabled (accent, dimmed by the wrapper), read-only (neutral).
+          // No `disabled:` colour override; the wrapper's `opacity-60`
+          // does the dimming, and doubling it on the box is what made a
+          // disabled checkbox vanish.
+          isReadOnly
+            ? "border-border-default checked:border-intent-neutral-solid checked:bg-intent-neutral-solid"
+            : "border-border-strong checked:border-intent-accent-solid checked:bg-intent-accent-solid",
+          isDisabled
+            ? "cursor-not-allowed"
+            : isReadOnly
+              ? "cursor-default"
+              : "cursor-pointer",
+          BOX_SIZE_CLASS[size],
+          FOCUS_RING_CLASS,
+        )}
+        defaultChecked={isChecked}
+        disabled={isDisabled}
+        id={id}
+        onChange={(
+          event: ChangeEvent<HTMLInputElement>,
+        ) => {
+          if (isReadOnly) {
+            return
+          }
+
+          onChange?.(event.target.checked)
+        }}
+        onClick={(clickEvent) => {
+          // Native checkboxes have no `readonly`, so the toggle is
+          // blocked here — `preventDefault` on the click stops the
+          // checked flip a pointer would make.
+          if (isReadOnly) {
+            clickEvent.preventDefault()
+          }
+        }}
+        onKeyDown={(keyEvent) => {
+          // …and Space, the keyboard toggle a click block does not
+          // cover.
+          if (isReadOnly && keyEvent.key === " ") {
+            keyEvent.preventDefault()
+          }
+        }}
+        type="checkbox"
+      />
+
+      <svg
+        aria-hidden="true"
+        className={toClassName(
+          "pointer-events-none invisible absolute peer-checked:visible",
+          // Matches whichever fill the box wears, so the tick keeps its
+          // guaranteed on-solid contrast in either intent.
+          isReadOnly
+            ? "text-intent-neutral-on-solid"
+            : "text-intent-accent-on-solid",
+          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

@@ -88,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={
@@ -415,6 +424,11 @@ const MANY_LONG: ListboxItem[] = Array.from(
  * 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: {
@@ -428,6 +442,7 @@ export const VirtualizedLongOptions: Story = {
     <ComboboxHarness
       className="w-72"
       isInitiallyVisible
+      isMultiple
       options={MANY_LONG}
       triggerLabel="Search folders"
     />

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"
+    />
+  ),
+}