@charcuterie/ui 0.1.0

package/src/SegmentedControl/SegmentedControl.test.tsx

@@ -0,0 +1,208 @@
+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 "./SegmentedControl.stories.tsx"
+
+const { AllStates, Default, Interactive } =
+  composeStories(stories)
+
+/**
+ * `querySelectorAll` rather than `getAllByRole("radio")`, and not
+ * for typing convenience: a board renders several groups, and an
+ * assertion about "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: "Columns",
+    role: "radiogroup",
+  })
+
+  const options = getOptions(group)
+
+  await expect(options).toHaveLength(5)
+
+  await waitFor(() => {
+    expect(
+      options.filter(
+        (one) =>
+          one.getAttribute("aria-checked") === "true",
+      ),
+    ).toHaveLength(1)
+  })
+
+  // The state kind's invariant, visible in the DOM: `SinglePicker`
+  // holds one intent field, so "at most one checked" is true by
+  // representation rather than by bookkeeping.
+  await expect(group).toContainElement(options[0] ?? null)
+
+  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: "Columns",
+      role: "radiogroup",
+    }),
+  )
+
+  // Zero tab stops strands the widget; several mean the roving
+  // pattern was never implemented. Exactly one is the rule, read
+  // straight out of `selectTabIndex`.
+  await expect(
+    options.filter((one) => one.tabIndex === 0),
+  ).toHaveLength(1)
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expect(options[0]).toHaveFocus()
+  })
+
+  await userEvent.keyboard("{ArrowRight}")
+
+  await waitFor(() => {
+    expect(options[1]).toHaveFocus()
+  })
+})
+
+/**
+ * The radio-group rule, and the thing that makes this component a
+ * different composition from `Tabs` rather than a restyle of it:
+ * moving focus **checks**. `Tabs` has two activation modes because a
+ * panel can cost a network request; there is nothing behind an
+ * option here to be expensive.
+ */
+test("selection follows focus, and wraps", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const options = getOptions(
+    expectAgentDrivable(canvas, {
+      name: "Columns",
+      role: "radiogroup",
+    }),
+  )
+
+  options[0]?.focus()
+
+  await userEvent.keyboard("{ArrowRight}")
+
+  await waitFor(() => {
+    expect(options[1]).toHaveAttribute(
+      "aria-checked",
+      "true",
+    )
+  })
+
+  await expect(options[0]).toHaveAttribute(
+    "aria-checked",
+    "false",
+  )
+
+  // Home and End, then wrapping — all three from `RovingFocus`,
+  // none of them written here.
+  await userEvent.keyboard("{End}")
+
+  await waitFor(() => {
+    expect(options[4]).toHaveAttribute(
+      "aria-checked",
+      "true",
+    )
+  })
+
+  await userEvent.keyboard("{ArrowRight}")
+
+  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 four = expectAgentDrivable(canvas, {
+    name: "4",
+    role: "radio",
+  })
+
+  await userEvent.click(four)
+
+  await waitFor(() => {
+    expect(four).toHaveAttribute("aria-checked", "true")
+  })
+})
+
+test("the arrow keys skip a disabled option", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const group = expectAgentDrivable(canvas, {
+    name: "Columns with 2 unavailable",
+    role: "radiogroup",
+  })
+
+  const options = getOptions(group)
+
+  const [first, , two, three] = options as [
+    HTMLButtonElement,
+    HTMLButtonElement,
+    HTMLButtonElement,
+    HTMLButtonElement,
+  ]
+
+  await expect(two).toBeDisabled()
+
+  first.focus()
+
+  await userEvent.keyboard("{ArrowRight}{ArrowRight}")
+
+  // Two presses from `auto` lands on `3`, not on the disabled `2` —
+  // registration is membership, and a disabled option never joined
+  // the focus group.
+  await waitFor(() => {
+    expect(three).toHaveFocus()
+  })
+
+  await expect(two).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: "Columns starting on 3",
+    role: "radiogroup",
+  })
+
+  // A controlled prop is the thing this library refuses to have —
+  // and reading it on the first paint is why the component falls
+  // back to `pendingValue`: members register from an effect, so
+  // `selectedValue` is still null when the group first paints.
+  await waitFor(() => {
+    expect(
+      group.querySelector('[aria-checked="true"]'),
+    ).toHaveTextContent("3")
+  })
+})

package/src/SegmentedControl/SegmentedControl.tsx

@@ -0,0 +1,219 @@
+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 { SegmentedOption } from "./SegmentedOption.tsx"
+
+export type SegmentedItem = {
+  /**
+   * 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 SegmentedControlProps = {
+  className?: string
+  items: readonly SegmentedItem[]
+  /** 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-0.5",
+  md: "gap-1",
+  lg: "gap-1",
+}
+
+/**
+ * One choice out of a handful, all of them on screen at once.
+ *
+ * This is `Tabs`' composition — `SinglePicker` + `RovingFocus` —
+ * with the panels taken away, and it exists because taking the
+ * panels away used to be impossible. Under M4's model a tab bar's
+ * selection *was* a group of visibilities, so a control that chooses
+ * something without revealing anything had nothing to reuse and
+ * hand-rolled its own state. rip-deck's `ColumnPicker` is that
+ * hand-roll
+ * ([decision](../../../docs/decisions/2026-07-30-tab-selection-is-a-single-picker.md)).
+ *
+ * ### `radiogroup`, not a row of pressed buttons
+ *
+ * rip-deck's version is five `<button aria-pressed>` in a
+ * `<fieldset>`, which is the **toolbar of independent toggles**
+ * pattern: nothing in it says the five are mutually exclusive, so a
+ * screen reader announces "auto, pressed" with no "1 of 5" and no
+ * clue that pressing another un-presses this one. A single choice
+ * from a named set is a radio group, and ARIA has a pattern for it.
+ *
+ * ### Selection follows focus, and here that is correct
+ *
+ * `Tabs` has two activation modes because a tab panel can cost a
+ * network request. A radio group has one: APG says the arrow keys
+ * both move focus and check, and there is nothing behind an option
+ * here to be expensive. So the mode is `automatic` and there is no
+ * prop — a `manual` segmented control would be a control the arrow
+ * keys appear to do nothing in.
+ *
+ * The two kinds are still separate underneath, which is what makes
+ * Space's behaviour trivial rather than a special case: it checks
+ * whatever focus is on, whether or not focus moved there by arrow.
+ */
+export const SegmentedControl = ({
+  className,
+  items,
+  label,
+  onChange,
+  selectedValue,
+  size = "md",
+}: SegmentedControlProps): 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.
+   * A flash on a desktop; a visible blank on a kiosk Pi.
+   */
+  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 that would be absent in a `manual` mode this component
+    // deliberately does not have.
+    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(
+        "inline-flex items-center rounded-md border border-border-subtle bg-surface-sunken p-0.5",
+        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. In a group where
+        // selection already follows focus this is almost always a
+        // no-op — which is the point: it is one command, not a
+        // second code path, because `select` is idempotent.
+        if (keyEvent.key === " " && activeValue !== null) {
+          keyEvent.preventDefault()
+
+          select(activeValue)
+        }
+      }}
+      ref={groupRef}
+      role="radiogroup"
+    >
+      {items.map((item) => (
+        <SegmentedOption
+          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 while the arrow
+          // keys move inside it.
+          tabIndex={selectTabIndex(focus, item.value)}
+          trackElement={(value, element) => {
+            if (element) {
+              optionElements.current.set(value, element)
+            } else {
+              optionElements.current.delete(value)
+            }
+          }}
+        />
+      ))}
+    </div>
+  )
+}

package/src/SegmentedControl/SegmentedOption.tsx

@@ -0,0 +1,94 @@
+import type { ControlSize } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+import { useEffect } from "react"
+
+import { CONTROL_SIZE_CLASS } from "../controlStyles.ts"
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import type { SegmentedItem } from "./SegmentedControl.tsx"
+
+export type SegmentedOptionProps = {
+  isChecked: boolean
+  item: SegmentedItem
+  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
+}
+
+/**
+ * Its own file for the same reason `TabTrigger` is: **both
+ * registrations are effects**, and an effect cannot run in a loop.
+ * Any member of a registering group ends up shaped like this.
+ *
+ * The checked option is filled rather than merely tinted. A
+ * segmented control's whole job is to be readable at a glance from
+ * across a room — rip-deck's lives above a nine-bay grid on a wall
+ * display — and a one-shade difference does not survive that or a
+ * `daylight` theme in sunlight.
+ */
+export const SegmentedOption = ({
+  isChecked,
+  item,
+  onChoose,
+  registerFocus,
+  registerSelection,
+  size,
+  tabIndex,
+  trackElement,
+}: SegmentedOptionProps): 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. That is the self-owning-control conflict `Modal` already has with `<dialog>`, except here it collides with both state kinds at once — the browser and `SinglePicker` would each believe they hold the choice, and native roving would fight `RovingFocus`. APG's radio-group pattern exists for exactly this case.
+    <button
+      aria-checked={isChecked}
+      className={toClassName(
+        "cursor-pointer rounded-sm border border-transparent font-medium tabular-nums transition-colors duration-(--duration-fast) ease-standard",
+        CONTROL_SIZE_CLASS[size],
+        // Two entries rather than one interpolated string:
+        // `tailwindCandidates.test.ts` rejects a template literal in
+        // a className outright, because Tailwind's scanner cannot
+        // see a class that only exists at runtime.
+        isChecked
+          ? "bg-intent-accent-solid text-intent-accent-on-solid"
+          : "text-content-secondary hover:bg-intent-neutral-surface hover:text-content-primary",
+        isDisabled &&
+          "cursor-not-allowed text-content-disabled hover:bg-transparent hover:text-content-disabled",
+        FOCUS_RING_CLASS,
+      )}
+      disabled={isDisabled}
+      onClick={() => {
+        onChoose(value)
+      }}
+      ref={(element) => {
+        trackElement(value, element)
+      }}
+      role="radio"
+      tabIndex={tabIndex}
+      type="button"
+    >
+      {label}
+    </button>
+  )
+}

package/src/Skeleton/Skeleton.mdx

@@ -0,0 +1,30 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as SkeletonStories from "./Skeleton.stories";
+
+<Meta of={SkeletonStories} />
+
+# Skeleton
+
+**Also zero fleet-wide.** The counterpart to `Spinner`, and the better answer wherever the
+shape of the incoming content is already known: a poster grid that skeletons does not
+reflow when the images land, and layout shift is what users actually notice.
+
+<Canvas of={SkeletonStories.AllVariants} />
+
+## Props
+
+<Controls />
+
+## `aria-hidden` is the contract, not an optimisation
+
+A skeleton is decoration standing in for content that does not exist yet. Announcing it
+means a screen reader reading three empty bars, and an agent finding a "loading" element it
+cannot act on.
+
+**The load has to be announced by the region that owns it** — a `Spinner`, or `aria-busy`
+on the container. The `Default` story asserts the skeleton is hidden from assistive
+technology, and `Interactive` asserts it contributes no roles at all. Both are assertions
+axe cannot make for you: there is nothing invalid about a visible placeholder.
+
+<Canvas of={SkeletonStories.AllStates} />

package/src/Skeleton/Skeleton.stories.tsx

@@ -0,0 +1,130 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Card } from "../Card/Card.tsx"
+import { Skeleton } from "./Skeleton.tsx"
+
+const meta = {
+  title: "Components/Skeleton",
+  component: Skeleton,
+  parameters: { layout: "padded" },
+  args: { lineCount: 1, shape: "block" },
+} satisfies Meta<typeof Skeleton>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The inverse of every other component's gate. A skeleton is
+ * decoration standing in for content that does not exist yet, so it
+ * is hidden from AT entirely — otherwise a screen reader reads three
+ * empty bars.
+ */
+export const Default: Story = {
+  args: { blockSize: "1.5rem", inlineSize: "12rem" },
+}
+
+export const AllVariants: Story = {
+  args: {},
+  render: () => (
+    <StorySection title="Three shapes, and the multi-line text case — last line short, so a paragraph placeholder reads as prose rather than as a table.">
+      <StoryGrid columns={2}>
+        <StoryCell align="stretch" label="block">
+          <Skeleton blockSize="4rem" inlineSize="12rem" />
+        </StoryCell>
+
+        <StoryCell align="stretch" label="circle">
+          <Skeleton
+            blockSize="3rem"
+            inlineSize="3rem"
+            shape="circle"
+          />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="text (single line)"
+        >
+          <Skeleton inlineSize="14rem" shape="text" />
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="text (four lines)"
+        >
+          <Skeleton
+            inlineSize="14rem"
+            lineCount={4}
+            shape="text"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * A skeleton has no interactive states — no hover, no focus, no
+ * disabled. What it has instead is a *fidelity* obligation: the
+ * placeholder has to occupy the same box the real content will, or
+ * the grid reflows when the data lands and the user loses their
+ * place. So this story is the comparison rather than a state grid.
+ */
+export const AllStates: Story = {
+  args: {},
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="loading">
+        <Card heading="Bay 3 — loading">
+          <Skeleton
+            inlineSize="100%"
+            lineCount={3}
+            shape="text"
+          />
+        </Card>
+      </StoryCell>
+
+      <StoryCell align="stretch" label="loaded — same box">
+        <Card heading="Bay 3 — loaded">
+          <p className="text-content-secondary text-sm">
+            Ripping <em>Blade Runner (1982)</em> — title 4
+            of 9, AACS handshake complete, 38 minutes
+            remaining on this title.
+          </p>
+        </Card>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+export const Responsive: Story = {
+  args: {},
+  render: () => (
+    <ContainerBoard>
+      <Skeleton
+        inlineSize="100%"
+        lineCount={3}
+        shape="text"
+      />
+    </ContainerBoard>
+  ),
+}
+
+/**
+ * Nothing to drive, and that is the point: a skeleton contributes no
+ * roles at all, so an agent sweeping the page never finds a control
+ * it cannot act on.
+ */
+export const Interactive: Story = {
+  args: {
+    inlineSize: "12rem",
+    lineCount: 3,
+    shape: "text",
+  },
+}