@charcuterie/ui 2.4.1 → 2.5.0

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

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

package/src/Menu/Menu.test.tsx

@@ -10,6 +10,8 @@ import * as stories from "./Menu.stories.tsx"
 const {
   AllStates,
   AllVariants,
+  Empty,
+  Grouped,
   Interactive,
   SharedTrigger,
 } = composeStories(stories)
@@ -320,3 +322,103 @@ test("the tooltip sharing that trigger is anchored to it too", async () => {
     )
   })
 })
+
+test("a group is a named group and a separator is a separator", async () => {
+  const { body } = await mountStory(Grouped)
+
+  const menu = expectAgentDrivable(body, {
+    name: "Bay 6",
+    role: "menu",
+  })
+
+  // Each group is a `role="group"` named by its heading, so a screen
+  // reader announces "Danger, group" before its members.
+  expectAgentDrivable(body, {
+    name: "Disc",
+    role: "group",
+  })
+
+  expectAgentDrivable(body, {
+    name: "Danger",
+    role: "group",
+  })
+
+  // A native `<hr>`, which carries the implicit `role="separator"`.
+  await expect(menu.querySelectorAll("hr")).toHaveLength(1)
+
+  await expect(body.getAllByRole("separator")).toHaveLength(
+    1,
+  )
+
+  await expectNoAxeViolations(menu)
+})
+
+test("arrow keys skip group headings and separators", async () => {
+  const { body } = await mountStory(Grouped)
+
+  const retry = expectAgentDrivable(body, {
+    name: "Retry title",
+    role: "menuitem",
+  })
+
+  const skip = expectAgentDrivable(body, {
+    name: "Skip title",
+    role: "menuitem",
+  })
+
+  const eject = expectAgentDrivable(body, {
+    name: "Eject disc",
+    role: "menuitem",
+  })
+
+  // Opening lands on the first item, and arrow-down walks the items
+  // in DOM order across the group boundary — the heading and the
+  // separator register nothing, so there is nothing between Skip
+  // (end of group one) and Eject (start of group two) to stop on.
+  await waitFor(() => {
+    expect(retry).toHaveFocus()
+  })
+
+  await userEvent.keyboard("{ArrowDown}")
+
+  await waitFor(() => {
+    expect(skip).toHaveFocus()
+  })
+
+  await userEvent.keyboard("{ArrowDown}")
+
+  await waitFor(() => {
+    expect(eject).toHaveFocus()
+  })
+})
+
+test("an empty menu shows a disabled note, not an actionable item", async () => {
+  const { body } = await mountStory(Empty)
+
+  const menu = expectAgentDrivable(body, {
+    name: "Bay 7",
+    role: "menu",
+  })
+
+  await expect(menu).toHaveTextContent(
+    "No actions available",
+  )
+
+  // The note is the menu's one `menuitem` — a `role="menu"` must own
+  // one — but it is `aria-disabled` and carries no tab stop, so a
+  // keyboard user is told the menu is empty and cannot land on it.
+  const items = menu.querySelectorAll<HTMLElement>(
+    '[role="menuitem"]',
+  )
+
+  await expect(items).toHaveLength(1)
+
+  await expect(items[0]).toHaveAttribute(
+    "aria-disabled",
+    "true",
+  )
+
+  await expect(items[0]?.tabIndex).toBe(-1)
+
+  await expectNoAxeViolations(menu)
+})