@charcuterie/ui 2.4.1 → 2.5.0

package/src/Menu/Menu.tsx

@@ -1,6 +1,7 @@
 import {
   selectTabIndex,
   useRovingFocus,
+  useUniqueId,
 } from "@charcuterie/logic"
 import type { Placement } from "@floating-ui/react"
 import {
@@ -21,12 +22,57 @@ export type MenuItem = {
   key: string
   label: ReactNode
   onSelect: () => void
+  /**
+   * The default kind, and optional so the common `{ key, label,
+   * onSelect }` still type-checks. Present only to discriminate this
+   * from a `separator` or a `group`.
+   */
+  type?: "item"
+}
+
+/**
+ * A rule between groups of items — `role="separator"`, and nothing a
+ * keyboard user lands on. It never registers with the roving group,
+ * so the arrow keys pass straight over it, the same mechanism a
+ * disabled item uses.
+ */
+export type MenuSeparator = {
+  key: string
+  type: "separator"
 }
 
+/**
+ * A named set of items — `role="group"` with the `label` as its
+ * accessible name (a screen reader announces "Danger, group" before
+ * its members). The heading itself is not focusable; only the items
+ * inside it register.
+ */
+export type MenuGroup = {
+  items: MenuItem[]
+  key: string
+  label: ReactNode
+  type: "group"
+}
+
+/**
+ * What a menu is made of. A bare `MenuItem` is still valid on its
+ * own, so existing `items` arrays need no change; a `separator` or a
+ * `group` opts in by its `type`.
+ */
+export type MenuEntry = MenuGroup | MenuItem | MenuSeparator
+
 export type MenuProps = {
   className?: string
+  /**
+   * Shown when there is no item to show — a `group` with no members
+   * and a bare separator list both count as empty. Rendered as a
+   * **disabled** `menuitem` (a `role="menu"` must own one), so it is
+   * announced but never focused. Without it an empty menu renders
+   * nothing.
+   */
+  emptyState?: ReactNode
   isVisible: boolean
-  items: MenuItem[]
+  items: MenuEntry[]
   /** Outside press, Escape, and choosing an item all land here. */
   onDismiss: () => void
   placement?: Placement
@@ -34,6 +80,16 @@ export type MenuProps = {
   trigger: ReactElement
 }
 
+const isMenuItem = (entry: MenuEntry): entry is MenuItem =>
+  entry.type === undefined || entry.type === "item"
+
+const hasAnyItem = (items: MenuEntry[]): boolean =>
+  items.some(
+    (entry) =>
+      isMenuItem(entry) ||
+      (entry.type === "group" && entry.items.length > 0),
+  )
+
 /**
  * A menu is **not** a listbox, and mux-magic's `TypePicker` is the
  * fleet's one attempt at telling them apart — it renders
@@ -86,6 +142,22 @@ export type MenuProps = {
  * focus is whichever one `RovingFocus` says is active, and that is
  * not known until the items have registered.
  *
+ * ### Separators, groups, and an empty state
+ *
+ * `items` is a union, not a flat `MenuItem[]`: a `separator`
+ * (`role="separator"`) and a `group` (`role="group"`, named by its
+ * `label`) opt in by their `type`, and a bare item still type-checks
+ * unchanged. The keyboard model needs no new code for them — a
+ * separator and a group heading register nothing, so the roving
+ * group never sees them and the arrow keys skip straight over, the
+ * same mechanism a disabled item already used. A `group`'s items
+ * register normally, so focus moves through them in DOM order as if
+ * the heading were not there. When there is nothing to show, the
+ * `emptyState` renders as a **disabled** `menuitem` — a `role="menu"`
+ * with no `menuitem` child fails `aria-required-children`, so the
+ * note has to be one, `aria-disabled` and out of the roving group:
+ * announced as "No actions available, dimmed", focusable by nothing.
+ *
  * ### No type-ahead, deliberately
  *
  * The APG lists type-ahead as optional for a menu and required for a
@@ -96,12 +168,15 @@ export type MenuProps = {
  */
 export const Menu = ({
   className,
+  emptyState,
   isVisible,
   items,
   onDismiss,
   placement = "bottom-start",
   trigger,
 }: MenuProps): ReactNode => {
+  const menuId = useUniqueId()
+
   const itemElements = useRef(
     new Map<string, HTMLButtonElement>(),
   )
@@ -160,6 +235,83 @@ export const Menu = ({
     itemElements.current.get(activeValue)?.focus()
   }, [activeValue, isVisible])
 
+  // One member of the roving group, whether it sits at the top level
+  // or inside a `group`. The registration lives in `MenuAction`'s
+  // effect, so an item nested in a group joins the same arrow-key
+  // sequence in DOM order — the heading above it registers nothing.
+  const renderItem = (item: MenuItem) => (
+    <MenuAction
+      item={item}
+      key={item.key}
+      onDismiss={onDismiss}
+      register={focus.register}
+      tabIndex={selectTabIndex(focus, item.key)}
+      trackElement={(key, element) => {
+        if (element) {
+          itemElements.current.set(key, element)
+        } else {
+          itemElements.current.delete(key)
+        }
+      }}
+    />
+  )
+
+  const renderEntry = (entry: MenuEntry) => {
+    if (entry.type === "separator") {
+      // A native `<hr>` — implicit `role="separator"`, and the one
+      // that does *not* need `aria-valuenow` (that is the focusable
+      // splitter kind, not a static rule between menu groups).
+      return (
+        <hr
+          className="-mx-1 my-1 h-px border-0 bg-border-subtle"
+          key={entry.key}
+        />
+      )
+    }
+
+    if (entry.type === "group") {
+      const headingId = `${menuId}-${entry.key}`
+
+      return (
+        // biome-ignore lint/a11y/useSemanticElements: a menu group is `role="group"` (ARIA APG), not a form `<fieldset>` — a fieldset is invalid content inside `role="menu"` and drags legend/border/reset semantics onto it.
+        <div
+          aria-labelledby={headingId}
+          key={entry.key}
+          role="group"
+        >
+          <div
+            className="px-2 pt-1.5 pb-0.5 font-medium text-content-secondary text-xs"
+            id={headingId}
+          >
+            {entry.label}
+          </div>
+
+          {entry.items.map(renderItem)}
+        </div>
+      )
+    }
+
+    return renderItem(entry)
+  }
+
+  // A **disabled** `menuitem`, not inert text: a `role="menu"` with
+  // no `menuitem` child fails `aria-required-children`, so the empty
+  // note has to be one — `aria-disabled` and `tabindex="-1"`, so it
+  // is announced ("No actions available, dimmed") but takes no tab
+  // stop and never joins the roving group. `null` when the consumer
+  // gave no `emptyState`, so an empty menu renders nothing.
+  const emptyElement =
+    emptyState === undefined ? null : (
+      <div
+        aria-disabled="true"
+        className="px-2 py-1.5 text-content-disabled text-sm"
+        role="menuitem"
+        tabIndex={-1}
+      >
+        {emptyState}
+      </div>
+    )
+
   return (
     <>
       {clonedTrigger}
@@ -214,22 +366,9 @@ export const Menu = ({
               role="menu"
               style={floatingStyles}
             >
-              {items.map((item) => (
-                <MenuAction
-                  item={item}
-                  key={item.key}
-                  onDismiss={onDismiss}
-                  register={focus.register}
-                  tabIndex={selectTabIndex(focus, item.key)}
-                  trackElement={(key, element) => {
-                    if (element) {
-                      itemElements.current.set(key, element)
-                    } else {
-                      itemElements.current.delete(key)
-                    }
-                  }}
-                />
-              ))}
+              {hasAnyItem(items)
+                ? items.map(renderEntry)
+                : emptyElement}
             </div>
           </FloatingFocusManager>
         </FloatingPortal>

package/src/RadioGroup/RadioGroup.mdx

@@ -0,0 +1,58 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as RadioGroupStories from "./RadioGroup.stories";
+
+<Meta of={RadioGroupStories} />
+
+# RadioGroup
+
+One choice out of many, each on its own row with a label the size of prose.
+
+`RadioGroup` and [`SegmentedControl`](/docs/components-segmentedcontrol--docs) are the
+**same composition** — `SinglePicker` + `RovingFocus`, a `radiogroup` of `radio`s where
+selection follows focus — and a different shape. The segmented strip is compact, for a
+handful of short options that share a control row; the radio group is form-length, where
+each option carries a real sentence and an in-line strip would wrap. Choosing between them
+is layout, not behaviour, which is why the keyboard model is identical and lives in the same
+two hooks.
+
+<Canvas of={RadioGroupStories.Default} />
+
+## Props
+
+<Controls />
+
+## `radiogroup`, not a stack of checkboxes
+
+A column of `<input type="checkbox">` is the **independent toggles** pattern: nothing in it
+says the options are mutually exclusive, so a screen reader announces each as its own
+on/off with no "1 of 4" and no clue that checking one unchecks the rest. A single choice
+from a named set is a radio group, and ARIA has a pattern for it — which is the same
+correction `SegmentedControl` makes to rip-deck's row of `aria-pressed` buttons.
+
+<Canvas of={RadioGroupStories.AllVariants} />
+
+## Selection follows focus
+
+APG gives a radio group one activation mode: the arrow keys both move focus and check.
+There is nothing behind an option here to be expensive — no panel, no request — so unlike
+`Tabs` there is no `manual` mode and no prop, because a `manual` radio group is one the
+arrow keys appear to do nothing in. Tab enters the group once (the roving-tabindex rule),
+the arrows move and check together, Home and End jump to the ends, and the ends wrap.
+
+A disabled option is simply **not registered** with the roving group, so the arrows skip it
+without any command having to know what "disabled" means. It stays registered with the
+picker — it is still one of the options, and still the one a saved `selectedValue` may point
+at.
+
+<Canvas of={RadioGroupStories.AllStates} />
+
+## `selectedValue` is the initial value, not a controlled one
+
+It decides the first render and nothing after — Charcuterie owns the choice from then on,
+and `onChange` reports it outward. Members register from an effect, so on the first paint
+the value lives in the picker's `pendingValue` and the group paints already showing it
+rather than flashing empty for a frame — a flash on a desktop, a visible blank on a kiosk
+Pi.
+
+<Canvas of={RadioGroupStories.Interactive} />

package/src/RadioGroup/RadioGroup.stories.tsx

@@ -0,0 +1,130 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import type { RadioItem } from "./RadioGroup.tsx"
+import { RadioGroup } from "./RadioGroup.tsx"
+
+/**
+ * Options carrying a real sentence each — the case an in-line
+ * `SegmentedControl` strip would wrap, and the reason to stack.
+ */
+const NAMING_ITEMS: RadioItem[] = [
+  { label: "Match the Plex agent", value: "plex" },
+  { label: "Match AniDB titles", value: "anidb" },
+  {
+    label: "Keep the original filenames",
+    value: "original",
+  },
+  { label: "Use a custom pattern", value: "custom" },
+]
+
+const meta = {
+  title: "Components/RadioGroup",
+  component: RadioGroup,
+  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: { size: "md" },
+} satisfies Meta<typeof RadioGroup>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { items: NAMING_ITEMS, label: "Naming scheme" },
+}
+
+export const AllVariants: Story = {
+  args: { items: NAMING_ITEMS, label: "Naming scheme" },
+  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}>
+            <RadioGroup
+              {...controlProps}
+              label={`Naming scheme at ${size}`}
+              size={size}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+const STATE_ITEMS: RadioItem[] = [
+  { label: "Match the Plex agent", value: "plex" },
+  { label: "Match AniDB titles", value: "anidb" },
+  {
+    isDisabled: true,
+    label: "Keep the original filenames",
+    value: "original",
+  },
+  { label: "Use a custom pattern", value: "custom" },
+]
+
+/**
+ * A disabled option is out of the *focus* group and still one of the
+ * *options* — it can even be the one a consumer names as the initial
+ * `selectedValue`, which is what a saved preference pointing at a
+ * scheme the source no longer supports looks like.
+ */
+export const AllStates: Story = {
+  args: { items: STATE_ITEMS, label: "Naming scheme" },
+  render: (controlProps) => (
+    <StorySection title="What varies is which option is checked and which are reachable.">
+      <StoryGrid columns={2}>
+        <StoryCell label="first option checked">
+          <RadioGroup
+            {...controlProps}
+            label="Naming scheme starting on Plex"
+          />
+        </StoryCell>
+
+        <StoryCell label="starts on the fourth option">
+          <RadioGroup
+            {...controlProps}
+            label="Naming scheme starting on custom"
+            selectedValue="custom"
+          />
+        </StoryCell>
+
+        <StoryCell label="a disabled option">
+          <RadioGroup
+            {...controlProps}
+            label="Naming scheme with original unavailable"
+          />
+        </StoryCell>
+
+        <StoryCell label="two options">
+          <RadioGroup
+            {...controlProps}
+            items={[
+              { label: "Move the files", value: "move" },
+              { label: "Copy the files", value: "copy" },
+            ]}
+            label="On import"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * The complete keyboard path. Tab enters the group **once** — the
+ * roving-tabindex rule — then the arrow keys move and check
+ * together, the same activation model as `SegmentedControl`.
+ */
+export const Interactive: Story = {
+  args: { items: NAMING_ITEMS, label: "Naming scheme" },
+}

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