@charcuterie/ui 0.1.0

package/src/Tabs/Tabs.tsx

@@ -0,0 +1,333 @@
+import {
+  selectTabIndex,
+  useRovingFocus,
+  useSinglePicker,
+  useUniqueId,
+} from "@charcuterie/logic"
+import type { ReactNode } from "react"
+import { useCallback, useEffect, useRef } from "react"
+
+import { toClassName } from "../toClassName.ts"
+import { TabTrigger } from "./TabTrigger.tsx"
+
+export type TabsActivation = "automatic" | "manual"
+
+export type TabsOrientation = "horizontal" | "vertical"
+
+export type TabItem = {
+  content: ReactNode
+  /**
+   * A disabled tab is simply **not registered** with the roving
+   * group. Registration is membership, so the arrow keys skip it
+   * without any command in `RovingFocus` having to know what
+   * "disabled" means.
+   */
+  isDisabled?: boolean
+  key: string
+  label: ReactNode
+}
+
+export type TabsProps = {
+  /** **Initial** only. Charcuterie owns it from then on. */
+  activeKey?: string
+  /**
+   * `automatic` — the ARIA Authoring Practices default — shows a
+   * panel as soon as the arrow keys reach its tab. `manual` moves
+   * focus only, and Enter or Space commits.
+   *
+   * The distinction exists because **focus is not selection**, and
+   * it is the entire reason `RovingFocus` is its own state kind. A
+   * tab whose panel costs a network request wants `manual`, and
+   * the two modes differ by one line below — because two kinds are
+   * composed rather than one kind doing both jobs badly.
+   */
+  activation?: TabsActivation
+  className?: string
+  /** The tablist's accessible name. Required. */
+  label: string
+  onChange?: (activeKey: string | null) => void
+  orientation?: TabsOrientation
+  tabs: TabItem[]
+}
+
+const ORIENTATION_KEYS: Record<
+  TabsOrientation,
+  { next: string; previous: string }
+> = {
+  horizontal: {
+    next: "ArrowRight",
+    previous: "ArrowLeft",
+  },
+  vertical: { next: "ArrowDown", previous: "ArrowUp" },
+}
+
+/**
+ * Kept at P0 as the **state layer's falsification test**, not on
+ * duplication grounds — the fifteen ad-hoc tab bars that used to
+ * justify it were in the withdrawn evidence. What it has to prove
+ * is that two kinds compose: one says which tab is **chosen**, the
+ * other says which tab is **tabbable**, and a tab bar needs both
+ * at once *and* needs them to disagree on purpose while a user
+ * arrows around in `manual` mode.
+ *
+ * The composition is two hooks and one decision:
+ *
+ * ```ts
+ * const selection = useSinglePicker({ selectedValue: initialKey })
+ * const focus = useRovingFocus({ activeValue: initialKey })
+ *
+ * // `automatic` is this line, and `manual` is its absence.
+ * if (activation === "automatic") selection.select(focus.activeValue)
+ * ```
+ *
+ * ### Selection, not visibility — and the difference is not cosmetic
+ *
+ * M4 built this on `VisibilityGroup`, and the panels do end up
+ * one-at-a-time either way, because the two cores are the same
+ * shape. But the thing that **registers** here is the tab, not the
+ * panel, and what a tab bar is asking is *which one did you pick*.
+ * `SinglePicker` is the kind that answers that; the panel's
+ * `hidden` is derived from the answer.
+ *
+ * Reading it the other way round cost something concrete: it made
+ * `aria-selected` a report about a *panel's* visibility, so a
+ * consumer wanting a tab bar with no panels at all — a segmented
+ * filter, a view switcher that swaps a route — had to model its
+ * choice as a group of visibilities it did not have. `Alert`'s
+ * sibling `SegmentedControl` is exactly that consumer, and it now
+ * shares this component's core rather than hand-rolling a fourth
+ * one.
+ * [Decision](../../../../docs/decisions/2026-07-30-tab-selection-is-a-single-picker.md).
+ *
+ * ### What it does not use, and why that is the right answer
+ *
+ * The plan expected `createLinkedIds` here as well. It does not
+ * fit, and forcing it would have been the wrong call: that kind
+ * exists for a **dynamic** trigger↔target pair — a `Popover` whose
+ * panel mounts and unmounts, where the multiset is what stops
+ * `aria-controls` pointing at a node React has already removed. A
+ * tab bar's pairing is static and known at render, so the ids come
+ * from one `useUniqueId` and cannot get out of step at all.
+ *
+ * ### Focus is moved deliberately, and only then
+ *
+ * `RovingFocus` is state; something still has to call `.focus()`.
+ * That happens only while the tablist already contains the focused
+ * element — otherwise mounting a tab bar, or any parent re-render
+ * that moved `activeValue`, yanks the caret out of whatever the
+ * user was actually doing.
+ */
+export const Tabs = ({
+  activation = "automatic",
+  activeKey,
+  className,
+  label,
+  onChange,
+  orientation = "horizontal",
+  tabs,
+}: TabsProps): ReactNode => {
+  const baseId = useUniqueId()
+
+  const tablistRef = useRef<HTMLDivElement>(null)
+
+  const tabElements = useRef(
+    new Map<string, HTMLButtonElement>(),
+  )
+
+  const initialKey =
+    activeKey ??
+    tabs.find((one) => !one.isDisabled)?.key ??
+    null
+
+  const selection = useSinglePicker<string>({
+    onChange,
+    selectedValue: initialKey,
+  })
+
+  const focus = useRovingFocus<string>({
+    activeValue: initialKey,
+  })
+
+  const { select } = selection
+
+  const { activeValue, setActiveValue } = focus
+
+  /**
+   * Selected **or** pending, and the fallback is load-bearing.
+   *
+   * Members register from an effect, so on the first paint
+   * `selectedValue` is still null and the intent lives in
+   * `pendingValue` — a tab bar reading only the former renders with
+   * no tab selected and no panel shown, then corrects itself a
+   * frame later. It is a flash on a fast machine and a visible
+   * blank on a kiosk Pi.
+   *
+   * The core distinguishes the two on purpose, which is why this
+   * belongs here rather than in the selector — unlike
+   * `RovingFocus`, where the equivalent first-paint hole was in
+   * `selectTabIndex` itself and got fixed there.
+   */
+  const shownKey =
+    selection.selectedValue ?? selection.pendingValue
+
+  const selectTab = useCallback(
+    (key: string) => {
+      // Both, because a pointer press moves focus *and* chooses.
+      // Only selecting would leave `automatic`'s effect below to
+      // put the old panel straight back.
+      setActiveValue(key)
+
+      select(key)
+    },
+    [select, setActiveValue],
+  )
+
+  useEffect(() => {
+    // Automatic activation, and the only behaviour that differs
+    // between the two modes. `select` is idempotent, so this is a
+    // no-op on every render where focus did not actually move.
+    if (
+      activation === "automatic" &&
+      activeValue !== null
+    ) {
+      select(activeValue)
+    }
+  }, [activation, activeValue, select])
+
+  useEffect(() => {
+    const tablist = tablistRef.current
+
+    if (
+      !tablist ||
+      activeValue === null ||
+      !tablist.contains(document.activeElement)
+    ) {
+      return
+    }
+
+    tabElements.current.get(activeValue)?.focus()
+  }, [activeValue])
+
+  const keys = ORIENTATION_KEYS[orientation]
+
+  return (
+    <div
+      className={toClassName(
+        "flex flex-col gap-3",
+        className,
+      )}
+    >
+      <div
+        aria-label={label}
+        aria-orientation={orientation}
+        className={toClassName(
+          "flex gap-1 border-border-subtle",
+          // A tab bar **scrolls**; it does not wrap and it does not
+          // paint outside its container. Without an `overflow`, a
+          // bar narrower than its tabs simply spilled across
+          // whatever sat beside it — visible in the `Responsive`
+          // board since M4, and invisible to a test asserting only
+          // that `scrollWidth > clientWidth`, which is true of a
+          // *spilling* bar too.
+          //
+          // The scrollbar is hidden rather than thin: a classic
+          // scrollbar takes layout space inside the scroll
+          // container, so the narrow bar would grow ~15px taller
+          // than the wide one and the underline would stop lining
+          // up across a board. Keyboard users never need it —
+          // `RovingFocus` calls `.focus()`, and the browser scrolls
+          // a focused tab into view.
+          "[scrollbar-width:none]",
+          // An `overflow` other than `visible` clips its
+          // descendants' **outlines**, and this component's focus
+          // ring is an outline sitting 2px *outside* the tab. The
+          // tab fills the bar's content box, so the ring would be
+          // clipped away on exactly the axis that now scrolls.
+          // Re-pointing the shared token inward keeps one ring
+          // definition — `FOCUS_RING_CLASS` already reads this
+          // variable — rather than appending a competing
+          // `outline-offset` utility and letting Tailwind's
+          // ordering decide the winner.
+          "[--focus-ring-offset:calc(var(--focus-ring-width)*-1)]",
+          orientation === "horizontal"
+            ? "flex-row overflow-x-auto border-b"
+            : "flex-col items-stretch overflow-y-auto border-e",
+        )}
+        onKeyDown={(keyEvent) => {
+          const commands: Record<string, () => void> = {
+            [keys.next]: focus.next,
+            [keys.previous]: focus.previous,
+            End: focus.last,
+            Home: focus.first,
+          }
+
+          const command = commands[keyEvent.key]
+
+          if (command) {
+            // Arrow keys scroll the page by default, and a tab bar
+            // that scrolls the window while it moves focus is the
+            // hand-rolled version of this component.
+            keyEvent.preventDefault()
+
+            command()
+
+            return
+          }
+
+          // `manual`'s commit. In `automatic` the panel is showing
+          // already, so this is the no-op that makes Enter behave
+          // identically in both modes.
+          if (
+            (keyEvent.key === "Enter" ||
+              keyEvent.key === " ") &&
+            activeValue !== null
+          ) {
+            keyEvent.preventDefault()
+
+            select(activeValue)
+          }
+        }}
+        ref={tablistRef}
+        role="tablist"
+      >
+        {tabs.map((tab, index) => (
+          <TabTrigger
+            id={`${baseId}-tab-${index}`}
+            isSelected={shownKey === tab.key}
+            key={tab.key}
+            onSelect={selectTab}
+            panelId={`${baseId}-panel-${index}`}
+            registerFocus={focus.register}
+            orientation={orientation}
+            registerSelection={selection.register}
+            tab={tab}
+            // The roving-tabindex rule read from the core rather
+            // than restated here: exactly one member is in the tab
+            // order, so Tab enters and leaves the bar once while
+            // the arrow keys move inside it.
+            tabIndex={selectTabIndex(focus, tab.key)}
+            trackElement={(key, element) => {
+              if (element) {
+                tabElements.current.set(key, element)
+              } else {
+                tabElements.current.delete(key)
+              }
+            }}
+          />
+        ))}
+      </div>
+
+      {tabs.map((tab, index) => (
+        <div
+          aria-labelledby={`${baseId}-tab-${index}`}
+          hidden={shownKey !== tab.key}
+          id={`${baseId}-panel-${index}`}
+          key={tab.key}
+          role="tabpanel"
+        >
+          {tab.content}
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/VisuallyHidden/VisuallyHidden.mdx

@@ -0,0 +1,29 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as VisuallyHiddenStories from "./VisuallyHidden.stories";
+
+<Meta of={VisuallyHiddenStories} />
+
+# VisuallyHidden
+
+Text for assistive technology and for nobody else. A Layer-0 primitive, and the one every
+other component in M3 leans on: it is how a `Spinner` says "Loading…" without printing it,
+how a `ProgressBar`'s label stays discoverable when the design does not show it, and how an
+`IconButton`'s glyph gets a name.
+
+<Canvas of={VisuallyHiddenStories.Default} />
+
+## Props
+
+<Controls />
+
+## Nothing to own
+
+`sr-only` is Tailwind's own — the clip-rect technique, unchanged since it was
+`.visuallyhidden` in HTML5 Boilerplate. Never `display: none` and never
+`visibility: hidden`: both remove the node from the accessibility tree, which is the exact
+opposite of the requirement. The `Interactive` story asserts both halves — present to a
+query, one pixel to the layout.
+
+This component's story set is deliberately short. It has no variants, no states, and no
+container-query behaviour; the mandated five would be four empty boards.

package/src/VisuallyHidden/VisuallyHidden.stories.tsx

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { IconButton } from "../IconButton/IconButton.tsx"
+import { VisuallyHidden } from "./VisuallyHidden.tsx"
+
+/**
+ * A Layer-0 primitive with a deliberately short story set: it has no
+ * variants, no states, and no container-query behaviour — the whole
+ * component is "in the accessibility tree, out of the layout". The
+ * mandated five-story set would be four empty boards.
+ *
+ * It ships in M3 because `Spinner`, `ProgressBar`, and
+ * `LiveStatusIndicator` all need it and the alternative is
+ * `aria-label` everywhere, which cannot hold markup and silently
+ * loses translation.
+ */
+const meta = {
+  title: "Foundation/VisuallyHidden",
+  component: VisuallyHidden,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof VisuallyHidden>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { children: "Announced, never printed." },
+  render: (visuallyHiddenProps) => (
+    <StoryGrid columns={2}>
+      <StoryCell label="hidden text, next to visible text">
+        <p className="text-content-primary text-sm">
+          Ripping title 4
+          <VisuallyHidden {...visuallyHiddenProps} />
+        </p>
+      </StoryCell>
+
+      <StoryCell label="an icon button's name comes from one">
+        <IconButton label="Undo" size="sm">
+          ↶
+        </IconButton>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Present to a query, absent from the layout — the whole component.
+ * There is nothing to see here on purpose; the assertions are in
+ * `VisuallyHidden.test.tsx`.
+ */
+export const Interactive: Story = {
+  args: { children: "Announced, never printed." },
+}

package/src/VisuallyHidden/VisuallyHidden.test.tsx

@@ -0,0 +1,31 @@
+import { composeStories } from "@storybook/react"
+import { expect } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import * as stories from "./VisuallyHidden.stories.tsx"
+
+const { Interactive } = composeStories(stories)
+
+test("it is in the accessibility tree and out of the layout", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  // `display: none` would fail the first assertion; a plain `<span>`
+  // would fail the second. Both halves, or the component is either
+  // useless or visible.
+  const hidden = canvas.getByText(
+    "Announced, never printed.",
+  )
+
+  await expect(hidden).toBeInTheDocument()
+
+  const { height, width } = hidden.getBoundingClientRect()
+
+  await expect(width).toBeLessThanOrEqual(1)
+  await expect(height).toBeLessThanOrEqual(1)
+
+  await expect(canvasElement.textContent).toContain(
+    "Announced, never printed.",
+  )
+})

package/src/VisuallyHidden/VisuallyHidden.tsx

@@ -0,0 +1,43 @@
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { toClassName } from "../toClassName.ts"
+
+export type VisuallyHiddenProps =
+  ComponentPropsWithRef<"span"> & {
+    children: ReactNode
+  }
+
+/**
+ * Text for assistive technology and for nobody else.
+ *
+ * A Layer-0 primitive, and the one every other component in M3
+ * leans on: it is how a `Spinner` says "Loading…" without printing
+ * it, how an `IconButton`'s glyph gets a name, and how a
+ * `ProgressBar`'s label stays discoverable when the design does not
+ * show it. Without it the alternative is `aria-label` everywhere,
+ * which silently loses translation and cannot hold markup.
+ *
+ * `sr-only` is Tailwind's own — the clip-rect technique, unchanged
+ * since it was `.visuallyhidden` in HTML5 Boilerplate. There is
+ * nothing to own here, and owning it would mean maintaining a
+ * clip-rect against browsers that have already agreed.
+ *
+ * Never `display: none` and never `visibility: hidden`: both remove
+ * the node from the accessibility tree, which is the exact opposite
+ * of the requirement.
+ */
+export const VisuallyHidden = ({
+  children,
+  className,
+  ...spanProps
+}: VisuallyHiddenProps): ReactNode => (
+  <span
+    {...spanProps}
+    className={toClassName("sr-only", className)}
+  >
+    {children}
+  </span>
+)

package/src/argTypes.storyHelpers.ts

@@ -0,0 +1,115 @@
+import { connectionTransitions } from "@charcuterie/logic"
+import type { InputType } from "storybook/internal/types"
+
+import { CONTROL_SIZE_CLASS } from "./controlStyles.ts"
+import { INTENT_APPEARANCE_CLASS } from "./intentStyles.ts"
+
+/**
+ * Controls for the props Storybook's docgen cannot see through.
+ *
+ * `react-docgen` follows **relative** imports and stops at bare
+ * package specifiers. So `appearance?: IntentAppearance` — imported
+ * from `../intentStyles.ts` — arrives as a resolved union and gets a
+ * radio for free, while `size?: ControlSize` and `intent?: IntentName`
+ * — imported from `@charcuterie/tokens` — arrive as the bare names
+ * `ControlSize` and `IntentName`, which Storybook cannot enumerate.
+ * Its fallback for an unknown type is the **object control**: a JSON
+ * textarea containing `{}`, on a prop whose only legal values are
+ * three strings. Typing in it renders the component with an object
+ * where a string belongs.
+ *
+ * The other half of the same problem is that Storybook has not seeded
+ * `args` from a docgen `defaultValue` since v7 — the props table
+ * prints `"control"` in the Default column while the radio beside it
+ * has nothing selected. Only an explicit `args` fixes that, so every
+ * meta states the component's own defaults.
+ *
+ * Switching the whole project to `react-docgen-typescript` would
+ * resolve the imports and is the wrong trade: it expands
+ * `ComponentPropsWithRef<"button">` too, turning a nine-row props
+ * table into every HTML attribute React knows.
+ *
+ * The option lists are derived from the `Record<Union, …>` maps the
+ * components already index, never retyped — so a new intent or a new
+ * size is a compile error in the map and a longer radio here, rather
+ * than a control that silently omits it.
+ */
+
+const toOptions = <Key extends string>(
+  map: Record<Key, unknown>,
+): Key[] => Object.keys(map) as Key[]
+
+/**
+ * A radio under five options, a select at five or more — past four
+ * the radio column is taller than the props row it belongs to.
+ */
+const toChoiceArgType = <Key extends string>(
+  options: readonly Key[],
+): InputType => ({
+  control: {
+    type: options.length < 5 ? "radio" : "select",
+  },
+  options: [...options],
+  table: {
+    type: {
+      summary: options
+        .map((option) => `"${option}"`)
+        .join(" | "),
+    },
+  },
+})
+
+export const INTENT_OPTIONS = toOptions(
+  INTENT_APPEARANCE_CLASS,
+)
+
+export const CONTROL_SIZE_OPTIONS = toOptions(
+  CONTROL_SIZE_CLASS,
+)
+
+export const CONNECTION_STATUS_OPTIONS = toOptions(
+  connectionTransitions,
+)
+
+/**
+ * floating-ui's own union, which is not a `Record` anywhere we own —
+ * so this is the one list written out by hand, and the one a
+ * dependency bump could silently outdate.
+ * `storyControls.test.ts` pins it against the placements `Popover`
+ * actually accepts.
+ */
+export const PLACEMENT_OPTIONS = [
+  "top",
+  "top-start",
+  "top-end",
+  "right",
+  "right-start",
+  "right-end",
+  "bottom",
+  "bottom-start",
+  "bottom-end",
+  "left",
+  "left-start",
+  "left-end",
+] as const
+
+export const intentArgType = toChoiceArgType(INTENT_OPTIONS)
+
+export const controlSizeArgType = toChoiceArgType(
+  CONTROL_SIZE_OPTIONS,
+)
+
+export const connectionStatusArgType = toChoiceArgType(
+  CONNECTION_STATUS_OPTIONS,
+)
+
+export const placementArgType = toChoiceArgType(
+  PLACEMENT_OPTIONS,
+)
+
+/**
+ * Exported for the one control whose map is private to its own
+ * component — `Card`'s `ELEVATION_CLASS`. Its story derives the
+ * options there rather than this file importing a component.
+ */
+export const toStoryChoice = toChoiceArgType