@charcuterie/ui 2.4.1 → 2.6.0

package/src/RadioGroup/RadioGroup.test.tsx

@@ -0,0 +1,232 @@
+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 "./RadioGroup.stories.tsx"
+
+const { AllStates, Default, Interactive } =
+  composeStories(stories)
+
+/**
+ * `querySelectorAll` rather than `getAllByRole("radio")`: a board
+ * renders several groups, and "exactly one tab stop" is only the
+ * roving rule when it is scoped to **one** group.
+ */
+const getOptions = (group: HTMLElement) =>
+  Array.from(
+    group.querySelectorAll<HTMLButtonElement>(
+      '[role="radio"]',
+    ),
+  )
+
+test("it is a radio group with exactly one option checked", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Naming scheme",
+    role: "radiogroup",
+  })
+
+  const options = getOptions(group)
+
+  await expect(options).toHaveLength(4)
+
+  await waitFor(() => {
+    expect(
+      options.filter(
+        (one) =>
+          one.getAttribute("aria-checked") === "true",
+      ),
+    ).toHaveLength(1)
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("Tab enters the group once, and the arrows move within it", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const options = getOptions(
+    expectAgentDrivable(canvas, {
+      name: "Naming scheme",
+      role: "radiogroup",
+    }),
+  )
+
+  // Exactly one tab stop is the roving rule, read straight out of
+  // `selectTabIndex`. Zero strands the widget; several mean the
+  // pattern was never implemented.
+  await expect(
+    options.filter((one) => one.tabIndex === 0),
+  ).toHaveLength(1)
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expect(options[0]).toHaveFocus()
+  })
+
+  await userEvent.keyboard("{ArrowDown}")
+
+  await waitFor(() => {
+    expect(options[1]).toHaveFocus()
+  })
+})
+
+test("selection follows focus, and wraps", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const options = getOptions(
+    expectAgentDrivable(canvas, {
+      name: "Naming scheme",
+      role: "radiogroup",
+    }),
+  )
+
+  options[0]?.focus()
+
+  await userEvent.keyboard("{ArrowDown}")
+
+  await waitFor(() => {
+    expect(options[1]).toHaveAttribute(
+      "aria-checked",
+      "true",
+    )
+  })
+
+  await expect(options[0]).toHaveAttribute(
+    "aria-checked",
+    "false",
+  )
+
+  // End then wrap — both from `RovingFocus`, neither written in the
+  // component.
+  await userEvent.keyboard("{End}")
+
+  await waitFor(() => {
+    expect(options[3]).toHaveAttribute(
+      "aria-checked",
+      "true",
+    )
+  })
+
+  await userEvent.keyboard("{ArrowDown}")
+
+  await waitFor(() => {
+    expect(options[0]).toHaveAttribute(
+      "aria-checked",
+      "true",
+    )
+  })
+})
+
+test("a pointer press checks the option it landed on", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const custom = expectAgentDrivable(canvas, {
+    name: "Use a custom pattern",
+    role: "radio",
+  })
+
+  await userEvent.click(custom)
+
+  await waitFor(() => {
+    expect(custom).toHaveAttribute("aria-checked", "true")
+  })
+})
+
+test("the arrow keys skip a disabled option", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Naming scheme with original unavailable",
+    role: "radiogroup",
+  })
+
+  const options = getOptions(group)
+
+  const [first, , original, custom] = options as [
+    HTMLButtonElement,
+    HTMLButtonElement,
+    HTMLButtonElement,
+    HTMLButtonElement,
+  ]
+
+  await expect(original).toBeDisabled()
+
+  first.focus()
+
+  await userEvent.keyboard("{ArrowDown}{ArrowDown}")
+
+  // Two presses from the first option lands on `custom`, skipping
+  // the disabled `original` — registration is membership, and a
+  // disabled option never joined the focus group.
+  await waitFor(() => {
+    expect(custom).toHaveFocus()
+  })
+
+  await expect(original).not.toHaveFocus()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("selectedValue decides the first render and nothing after", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Naming scheme starting on custom",
+    role: "radiogroup",
+  })
+
+  await waitFor(() => {
+    expect(
+      group.querySelector('[aria-checked="true"]'),
+    ).toHaveTextContent("Use a custom pattern")
+  })
+})
+
+test("a read-only group is announced and its choice cannot move", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Naming scheme, read-only",
+    role: "radiogroup",
+  })
+
+  await expect(group).toHaveAttribute(
+    "aria-readonly",
+    "true",
+  )
+
+  // The checked option shows at full contrast; that is the value the
+  // read-only group is displaying.
+  await waitFor(() => {
+    expect(
+      group.querySelector('[aria-checked="true"]'),
+    ).toHaveTextContent("Match AniDB titles")
+  })
+
+  const other = Array.from(
+    group.querySelectorAll<HTMLButtonElement>(
+      '[role="radio"]',
+    ),
+  ).find(
+    (one) => one.textContent === "Use a custom pattern",
+  )
+
+  await userEvent.click(other ?? group)
+
+  // Selection-follows-focus is severed when read-only — a click on
+  // another option does not move the choice.
+  await expect(
+    group.querySelector('[aria-checked="true"]'),
+  ).toHaveTextContent("Match AniDB titles")
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/RadioGroup/RadioGroup.tsx

@@ -0,0 +1,223 @@
+import {
+  selectTabIndex,
+  useRovingFocus,
+  useSinglePicker,
+} from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+import { useCallback, useEffect, useRef } from "react"
+
+import { toClassName } from "../toClassName.ts"
+import { RadioGroupOption } from "./RadioGroupOption.tsx"
+
+export type RadioItem = {
+  /**
+   * A disabled option is simply **not registered** with the roving
+   * group, so the arrow keys skip it without any command in
+   * `RovingFocus` having to know what "disabled" means. It stays
+   * registered with the picker: it is still one of the options.
+   */
+  isDisabled?: boolean
+  label: ReactNode
+  value: string
+}
+
+export type RadioGroupProps = {
+  className?: string
+  items: readonly RadioItem[]
+  /**
+   * Shows which option is chosen at full contrast but refuses to move
+   * the choice — the arrow keys and clicks no longer select, and the
+   * group announces `aria-readonly`. Focus can still travel the
+   * options so a keyboard user can read them.
+   */
+  isReadOnly?: boolean
+  /** The group's accessible name. Required. */
+  label: string
+  onChange?: (selectedValue: string | null) => void
+  /** **Initial** only. Charcuterie owns it from then on. */
+  selectedValue?: string
+  size?: ControlSize
+}
+
+const GAP_CLASS: Record<ControlSize, string> = {
+  sm: "gap-1",
+  md: "gap-1.5",
+  lg: "gap-2",
+}
+
+/**
+ * One choice out of many, each on its own row with a label the size
+ * of prose — the stacked sibling of `SegmentedControl`.
+ *
+ * The two are the *same* composition — `SinglePicker` + `RovingFocus`,
+ * a `radiogroup` of `radio`s where selection follows focus — and a
+ * different shape. `SegmentedControl` is a compact strip for a
+ * handful of short options that share a control row; `RadioGroup` is
+ * the form-length list where each option carries a real sentence and
+ * an in-line strip would wrap. Picking between them is layout, not
+ * behaviour, which is why the keyboard model here is identical and
+ * lives in the same two hooks.
+ *
+ * ### `radiogroup`, not a stack of checkboxes
+ *
+ * A column of `<input type="checkbox">` is the **independent
+ * toggles** pattern: nothing says the options are mutually
+ * exclusive, and a screen reader never announces "1 of 4". A single
+ * choice from a named set is a radio group, and its arrow keys both
+ * move focus and check — APG's one activation mode, the same reason
+ * `SegmentedControl` has no `manual` prop.
+ */
+export const RadioGroup = ({
+  className,
+  items,
+  isReadOnly = false,
+  label,
+  onChange,
+  selectedValue,
+  size = "md",
+}: RadioGroupProps): ReactNode => {
+  const groupRef = useRef<HTMLDivElement>(null)
+
+  const optionElements = useRef(
+    new Map<string, HTMLButtonElement>(),
+  )
+
+  const initialValue =
+    selectedValue ??
+    items.find((one) => !one.isDisabled)?.value ??
+    null
+
+  const selection = useSinglePicker<string>({
+    onChange,
+    selectedValue: initialValue,
+  })
+
+  const focus = useRovingFocus<string>({
+    activeValue: initialValue,
+  })
+
+  const { select } = selection
+
+  const { activeValue, setActiveValue } = focus
+
+  /**
+   * Selected **or** pending. Members register from an effect, so on
+   * the first paint `selectedValue` is still null and the intent
+   * lives in `pendingValue` — reading only the former renders a
+   * group with nothing checked, then corrects itself a frame later.
+   */
+  const checkedValue =
+    selection.selectedValue ?? selection.pendingValue
+
+  const chooseOption = useCallback(
+    (value: string) => {
+      // Focus may still land on the option so it can be read; only the
+      // choice is frozen when read-only.
+      setActiveValue(value)
+
+      if (!isReadOnly) {
+        select(value)
+      }
+    },
+    [isReadOnly, select, setActiveValue],
+  )
+
+  useEffect(() => {
+    // Selection follows focus — the radio-group rule, and the one
+    // line a `manual` mode this component deliberately lacks would
+    // remove. Read-only severs exactly this link: focus still travels
+    // for reading, but moving it no longer moves the choice.
+    if (activeValue !== null && !isReadOnly) {
+      select(activeValue)
+    }
+  }, [activeValue, isReadOnly, select])
+
+  useEffect(() => {
+    const group = groupRef.current
+
+    if (
+      !group ||
+      activeValue === null ||
+      !group.contains(document.activeElement)
+    ) {
+      return
+    }
+
+    optionElements.current.get(activeValue)?.focus()
+  }, [activeValue])
+
+  return (
+    <div
+      aria-label={label}
+      aria-readonly={isReadOnly || undefined}
+      className={toClassName(
+        "flex flex-col",
+        GAP_CLASS[size],
+        className,
+      )}
+      onKeyDown={(keyEvent) => {
+        const commands: Record<string, () => void> = {
+          ArrowDown: focus.next,
+          ArrowLeft: focus.previous,
+          ArrowRight: focus.next,
+          ArrowUp: focus.previous,
+          End: focus.last,
+          Home: focus.first,
+        }
+
+        const command = commands[keyEvent.key]
+
+        if (command) {
+          // Arrow keys scroll the page by default, and a control
+          // that scrolls the window while it moves focus is the
+          // hand-rolled version of this component.
+          keyEvent.preventDefault()
+
+          command()
+
+          return
+        }
+
+        // Space checks the focused option. Selection already follows
+        // focus, so this is almost always a no-op — one idempotent
+        // command, not a second code path — and read-only skips it.
+        if (
+          keyEvent.key === " " &&
+          activeValue !== null &&
+          !isReadOnly
+        ) {
+          keyEvent.preventDefault()
+
+          select(activeValue)
+        }
+      }}
+      ref={groupRef}
+      role="radiogroup"
+    >
+      {items.map((item) => (
+        <RadioGroupOption
+          isChecked={checkedValue === item.value}
+          isReadOnly={isReadOnly}
+          item={item}
+          key={item.value}
+          onChoose={chooseOption}
+          registerFocus={focus.register}
+          registerSelection={selection.register}
+          size={size}
+          // The roving-tabindex rule read from the core rather than
+          // restated here: exactly one option is in the tab order, so
+          // Tab enters and leaves the group once.
+          tabIndex={selectTabIndex(focus, item.value)}
+          trackElement={(value, element) => {
+            if (element) {
+              optionElements.current.set(value, element)
+            } else {
+              optionElements.current.delete(value)
+            }
+          }}
+        />
+      ))}
+    </div>
+  )
+}

package/src/RadioGroup/RadioGroupOption.tsx

@@ -0,0 +1,148 @@
+import type { ControlSize } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+import { useEffect } from "react"
+
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import type { RadioItem } from "./RadioGroup.tsx"
+
+export type RadioGroupOptionProps = {
+  isChecked: boolean
+  isReadOnly: boolean
+  item: RadioItem
+  onChoose: (value: string) => void
+  /** `RovingFocus.register` — membership of the arrow-key group. */
+  registerFocus: (value: string) => () => void
+  /** `SinglePicker.register` — membership of the choice. */
+  registerSelection: (value: string) => () => void
+  size: ControlSize
+  tabIndex: number
+  trackElement: (
+    value: string,
+    element: HTMLButtonElement | null,
+  ) => void
+}
+
+// Deliberately the `Switch`'s `THUMB_SIZE_CLASS`, value for value — a
+// radio's ring and a switch's knob are then the same circle at every
+// density, which is what makes the family read as one set.
+const RING_SIZE_CLASS: Record<ControlSize, string> = {
+  sm: "size-3",
+  md: "size-4",
+  lg: "size-5",
+}
+
+const DOT_SIZE_CLASS: Record<ControlSize, string> = {
+  sm: "size-1.5",
+  md: "size-2",
+  lg: "size-2.5",
+}
+
+const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
+  sm: "text-sm",
+  md: "text-md",
+  lg: "text-lg",
+}
+
+/**
+ * Its own file for the same reason `SegmentedOption` is: **both
+ * registrations are effects**, and an effect cannot run in a loop.
+ *
+ * The ring and the dot are two elements rather than a bordered box
+ * with a background, so the checked dot can be centred by the grid
+ * and sized independently of the ring — a filled `bg-intent-accent`
+ * ring with no inner dot reads as a checkbox, not a radio.
+ */
+export const RadioGroupOption = ({
+  isChecked,
+  isReadOnly,
+  item,
+  onChoose,
+  registerFocus,
+  registerSelection,
+  size,
+  tabIndex,
+  trackElement,
+}: RadioGroupOptionProps): ReactNode => {
+  const { isDisabled = false, label, value } = item
+
+  useEffect(
+    () => registerSelection(value),
+    [registerSelection, value],
+  )
+
+  useEffect(() => {
+    if (isDisabled) {
+      return
+    }
+
+    return registerFocus(value)
+  }, [isDisabled, registerFocus, value])
+
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: `<input type="radio">` owns `checked` *and* owns arrow-key navigation within a `name` group — the same self-owning-control conflict `SegmentedOption` documents, where the browser and `SinglePicker` would each believe they hold the choice and native roving would fight `RovingFocus`. APG's radio-group pattern is built for exactly this.
+    <button
+      aria-checked={isChecked}
+      className={toClassName(
+        "inline-flex items-center gap-2 rounded-sm text-content-secondary text-start transition-colors duration-(--duration-fast) ease-standard",
+        TEXT_SIZE_CLASS[size],
+        // Disabled turns the whole option down with `opacity-60`, the
+        // same family treatment as `Checkbox` and `Switch`, rather than
+        // fading the ring to a token that disappeared on a pale theme.
+        // Read-only keeps full contrast — only the cursor and the hover
+        // affordance say it will not move.
+        isDisabled
+          ? "cursor-not-allowed opacity-60"
+          : isReadOnly
+            ? "cursor-default"
+            : "cursor-pointer hover:text-content-primary",
+        FOCUS_RING_CLASS,
+      )}
+      disabled={isDisabled}
+      onClick={() => {
+        onChoose(value)
+      }}
+      ref={(element) => {
+        trackElement(value, element)
+      }}
+      role="radio"
+      tabIndex={tabIndex}
+      type="button"
+    >
+      <span
+        className={toClassName(
+          // `border-2` matches the `Switch` thumb's ring weight and the
+          // `Checkbox` box, and `RING_SIZE_CLASS` matches the thumb's
+          // diameter — so a radio dot and a switch knob are the same
+          // circle. A disabled ring holds `border-default` rather than
+          // fading to the `border-subtle` that vanished on a pale theme.
+          "grid shrink-0 place-items-center rounded-full border-2 transition-colors duration-(--duration-fast) ease-standard",
+          // Read-only wears the neutral intent and a softer resting edge
+          // — the same "readable but not an actionable accent" language
+          // as `Checkbox` and `Switch`.
+          isReadOnly
+            ? isChecked
+              ? "border-intent-neutral-solid"
+              : "border-border-default"
+            : isChecked
+              ? "border-intent-accent-solid"
+              : "border-border-strong",
+          RING_SIZE_CLASS[size],
+        )}
+      >
+        <span
+          className={toClassName(
+            "rounded-full transition-transform duration-(--duration-fast) ease-standard",
+            isReadOnly
+              ? "bg-intent-neutral-solid"
+              : "bg-intent-accent-solid",
+            isChecked ? "scale-100" : "scale-0",
+            DOT_SIZE_CLASS[size],
+          )}
+        />
+      </span>
+
+      <span>{label}</span>
+    </button>
+  )
+}

package/src/Switch/Switch.mdx

@@ -0,0 +1,55 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as SwitchStories from "./Switch.stories";
+
+<Meta of={SwitchStories} />
+
+# Switch
+
+A boolean that takes effect the moment it is flipped — a setting, not a form value.
+
+A `Switch` and a [`Checkbox`](/docs/components-checkbox--docs) are the **same state kind and
+a different affordance**, and the split is meaning rather than looks. A checkbox is a value
+you submit — "delete originals", "I agree". A switch is a state you toggle and live with
+immediately — "automatic imports on". ARIA gives the second its own role, and a screen
+reader announces "on/off" for a `switch` where it announces "checked/unchecked" for a
+checkbox.
+
+<Canvas of={SwitchStories.Default} />
+
+## Props
+
+<Controls />
+
+## A `button role="switch"`, not an `input`
+
+The sliding track and thumb are the whole affordance, and a `<button>` styles them without
+fighting a native control's own rendering. It carries `aria-checked` and `aria-labelledby`
+and nothing else the browser would try to own, so its keyboard path is the button's: Tab
+reaches it, Space and Enter flip it.
+
+The value lives in React state seeded once from `isChecked` — the switch is the store, the
+same way the DOM is for `Checkbox`, and the same refusal of a controlled prop.
+
+<Canvas of={SwitchStories.AllVariants} />
+
+## The thumb changes colour, not just position
+
+On `bg-intent-accent-solid`, off on `bg-surface-sunken`, and the thumb picks the token that
+contrasts with whichever it is sitting on. A switch whose only signal was the thumb's
+*position* loses that signal to a `daylight` theme in sunlight or to a colour-blind reader;
+a filled track plus a contrasting thumb survives both, which is the same reason
+`SegmentedControl` fills its checked option rather than tinting it.
+
+<Canvas of={SwitchStories.AllStates} />
+
+## Disabled dims, read-only does not
+
+`isDisabled` removes the switch from the tab order and the pointer and turns the whole
+control down with `opacity-60` — a setting the user cannot currently change, a policy
+forced from above, still fully visible. `isReadOnly` is the other half: full contrast so
+the state stays legible, but the accent gives way to the **neutral** intent and the flip
+is refused (`aria-readonly`, the `onClick` guarded). A read-only switch is a value you may
+read here and change elsewhere; a disabled one is a control that is simply off-limits now.
+
+<Canvas of={SwitchStories.Interactive} />