@charcuterie/ui 2.4.0 → 2.5.0

package/src/RadioGroup/RadioGroup.test.tsx

@@ -0,0 +1,191 @@
+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")
+  })
+})

package/src/RadioGroup/RadioGroup.tsx

@@ -0,0 +1,204 @@
+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[]
+  /** 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,
+  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) => {
+      setActiveValue(value)
+
+      select(value)
+    },
+    [select, setActiveValue],
+  )
+
+  useEffect(() => {
+    // Selection follows focus — the radio-group rule, and the one
+    // line a `manual` mode this component deliberately lacks would
+    // remove.
+    if (activeValue !== null) {
+      select(activeValue)
+    }
+  }, [activeValue, 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}
+      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.
+        if (keyEvent.key === " " && activeValue !== null) {
+          keyEvent.preventDefault()
+
+          select(activeValue)
+        }
+      }}
+      ref={groupRef}
+      role="radiogroup"
+    >
+      {items.map((item) => (
+        <RadioGroupOption
+          isChecked={checkedValue === item.value}
+          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,126 @@
+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
+  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
+}
+
+const RING_SIZE_CLASS: Record<ControlSize, string> = {
+  sm: "size-3.5",
+  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,
+  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 cursor-pointer items-center gap-2 rounded-sm text-start transition-colors duration-(--duration-fast) ease-standard",
+        TEXT_SIZE_CLASS[size],
+        isDisabled
+          ? "cursor-not-allowed text-content-disabled"
+          : "text-content-secondary 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(
+          "grid shrink-0 place-items-center rounded-full border transition-colors duration-(--duration-fast) ease-standard",
+          isDisabled
+            ? "border-border-subtle"
+            : isChecked
+              ? "border-intent-accent-solid"
+              : "border-border-strong",
+          RING_SIZE_CLASS[size],
+        )}
+      >
+        <span
+          className={toClassName(
+            "rounded-full transition-transform duration-(--duration-fast) ease-standard",
+            isChecked ? "scale-100" : "scale-0",
+            isDisabled
+              ? "bg-content-disabled"
+              : "bg-intent-accent-solid",
+            DOT_SIZE_CLASS[size],
+          )}
+        />
+      </span>
+
+      <span>{label}</span>
+    </button>
+  )
+}

package/src/Switch/Switch.mdx

@@ -0,0 +1,53 @@
+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} />
+
+## One that is off is still reachable
+
+`disabled` removes it from the tab order and the pointer, and `aria-disabled` is left to the
+native `disabled` the `<button>` already carries. A disabled-and-on switch is a setting the
+user cannot currently change — a policy forced from above, say — not a broken control, and
+it reads that way to a screen reader.
+
+<Canvas of={SwitchStories.Interactive} />

package/src/Switch/Switch.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Switch } from "./Switch.tsx"
+
+const meta = {
+  title: "Components/Switch",
+  component: Switch,
+  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 Switch>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { label: "Automatic imports" },
+}
+
+export const AllVariants: Story = {
+  args: { label: "Automatic imports" },
+  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}>
+            <Switch
+              {...controlProps}
+              isChecked
+              label={`On at ${size}`}
+              size={size}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * The thumb changes colour as well as position, so the state reads at
+ * a glance in `daylight` sunlight — a thumb that only moved would not.
+ */
+export const AllStates: Story = {
+  args: { label: "Automatic imports" },
+  render: (controlProps) => (
+    <StorySection title="What varies is whether the switch is on and whether it can be changed.">
+      <StoryGrid columns={2}>
+        <StoryCell label="off">
+          <Switch {...controlProps} label="Off" />
+        </StoryCell>
+
+        <StoryCell label="on">
+          <Switch {...controlProps} isChecked label="On" />
+        </StoryCell>
+
+        <StoryCell label="disabled, off">
+          <Switch
+            {...controlProps}
+            isDisabled
+            label="Disabled"
+          />
+        </StoryCell>
+
+        <StoryCell label="disabled, on">
+          <Switch
+            {...controlProps}
+            isChecked
+            isDisabled
+            label="Disabled and on"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * A `button role="switch"`, so its keyboard path is the button's:
+ * Tab reaches it, Space and Enter flip it.
+ */
+export const Interactive: Story = {
+  args: { label: "Automatic imports" },
+}