@charcuterie/ui 3.30.0 → 3.32.0

package/src/RadioGroup/RadioGroupOption.tsx

@@ -3,6 +3,12 @@ import type { ReactNode } from "react"
 import { useEffect } from "react"
 
 import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import {
+  TILE_BOX_CLASS,
+  TILE_HINT_TEXT_CLASS,
+  TILE_PADDING_CLASS,
+  TILE_TEXT_SIZE_CLASS,
+} from "../tileStyles.ts"
 import { toClassName } from "../toClassName.ts"
 import type {
   RadioItem,
@@ -42,42 +48,6 @@ const DOT_SIZE_CLASS: Record<ControlSize, string> = {
   lg: "size-2.5",
 }
 
-const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
-  sm: "text-sm",
-  md: "text-md",
-  lg: "text-lg",
-}
-
-/**
- * One step down from the option's own text, and never below `xs`:
- * a hint that keeps shrinking with the density axis is the 11px
- * caption the 2026-08-10 ramp rebuild exists to have removed.
- */
-const HINT_TEXT_CLASS: Record<ControlSize, string> = {
-  sm: "text-xs",
-  md: "text-xs",
-  lg: "text-sm",
-}
-
-/**
- * A tile is a card, so its padding is a card's rather than a
- * control's — enough that the border reads as a box around content
- * and not as an outline on a line of text.
- */
-const TILE_PADDING_CLASS: Record<ControlSize, string> = {
-  sm: "px-3 py-2.5",
-  md: "px-3.5 py-3",
-  lg: "px-4 py-3.5",
-}
-
-/**
- * The box, and only the box. Every state below it is a **border and
- * a surface**, never colour alone — the same reason `Stepper`
- * refuses to say "done" with a hue.
- */
-const TILE_BOX_CLASS =
-  "rounded-lg border border-border-subtle bg-surface-raised"
-
 /**
  * Its own file for the same reason `SegmentedOption` is: **both
  * registrations are effects**, and an effect cannot run in a loop.
@@ -152,7 +122,7 @@ export const RadioGroupOption = ({
                 ? "items-center"
                 : "items-start",
             ),
-        TEXT_SIZE_CLASS[size],
+        TILE_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.
@@ -252,7 +222,7 @@ export const RadioGroupOption = ({
             <span
               className={toClassName(
                 "font-normal text-content-muted",
-                HINT_TEXT_CLASS[size],
+                TILE_HINT_TEXT_CLASS[size],
               )}
             >
               {hint}

package/src/Tabs/PanelTabs.tsx

@@ -0,0 +1,260 @@
+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 type { TabsPanelProps } from "./Tabs.tsx"
+import { TabTrigger } from "./TabTrigger.tsx"
+import type { TabsOrientation } from "./tabItems.ts"
+import { toTabListClass } from "./tabStyles.ts"
+
+const ORIENTATION_KEYS: Record<
+  TabsOrientation,
+  { next: string; previous: string }
+> = {
+  horizontal: {
+    next: "ArrowRight",
+    previous: "ArrowLeft",
+  },
+  vertical: { next: "ArrowDown", previous: "ArrowUp" },
+}
+
+/**
+ * The panel bar — every tab a `<button>`, every section a
+ * `role="tabpanel"` this component renders and hides. See `Tabs`
+ * for which of the two bars a screen wants.
+ *
+ * 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 PanelTabs = ({
+  activation = "automatic",
+  activeKey,
+  className,
+  label,
+  onChange,
+  orientation = "horizontal",
+  tabs,
+}: TabsPanelProps): 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={toTabListClass(orientation)}
+        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/Tabs/RoutedTabs.tsx

@@ -0,0 +1,58 @@
+import type { ReactNode } from "react"
+
+import {
+  getNavItemKey,
+  resolveActiveKey,
+} from "../Nav/navItems.ts"
+import { toClassName } from "../toClassName.ts"
+import { TabLink } from "./TabLink.tsx"
+import type { TabsLinkProps } from "./Tabs.tsx"
+import { toTabListClass } from "./tabStyles.ts"
+
+/**
+ * The routed bar: a named `<nav>` of real links wearing the tab
+ * paint.
+ *
+ * There is **no state here at all**, and that is the difference that
+ * matters rather than a saving. A panel bar owns its choice because
+ * nothing else knows it; a routed bar's choice is the address, so
+ * owning a copy would give the app two answers that can disagree —
+ * the Back button being the first thing to prove it.
+ *
+ * `resolveActiveKey` is `Nav`'s rule, imported rather than restated:
+ * whole-segment matching, the deepest match wins, the root is exact,
+ * an external item is never current, and the query string is not
+ * part of the answer.
+ */
+export const RoutedTabs = ({
+  activeHref,
+  className,
+  label,
+  orientation = "horizontal",
+  tabs,
+}: TabsLinkProps): ReactNode => {
+  const activeKey = resolveActiveKey(tabs, activeHref)
+
+  return (
+    <nav
+      aria-label={label}
+      className={toClassName(
+        toTabListClass(orientation),
+        className,
+      )}
+    >
+      {tabs.map((tab) => {
+        const key = getNavItemKey(tab)
+
+        return (
+          <TabLink
+            isCurrent={key === activeKey}
+            item={tab}
+            key={key}
+            orientation={orientation}
+          />
+        )
+      })}
+    </nav>
+  )
+}

package/src/Tabs/TabLink.tsx

@@ -0,0 +1,132 @@
+import type { ReactNode } from "react"
+
+import { useRouterLink } from "../RouterLink/RouterLinkProvider.tsx"
+import { getIsRoutedHref } from "../RouterLink/routerLink.ts"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+import type {
+  TabLinkItem,
+  TabsOrientation,
+} from "./tabItems.ts"
+import { toTabTriggerClass } from "./tabStyles.ts"
+
+export type TabLinkProps = {
+  isCurrent: boolean
+  item: TabLinkItem
+  orientation: TabsOrientation
+}
+
+/**
+ * One routed tab — and it is a real `<a href>`, through the same
+ * `RouterLinkProvider` seam `NavLink` uses.
+ *
+ * ### It carries no `role="tab"`, and that is the whole point
+ *
+ * `role="tab"` on an anchor **overrides** the link role. A screen
+ * reader then announces "tab", the reader expects a panel to appear
+ * beside it, and instead the address changes and the page under it
+ * is replaced. The APG tab pattern describes a disclosure inside one
+ * document; it does not describe navigation, and `aria-controls`
+ * has nothing to point at here because the section's content comes
+ * from the router — an `<Outlet />` the app renders somewhere this
+ * component cannot see.
+ *
+ * So a routed bar is what it actually is: a list of links inside a
+ * named `<nav>`, with `aria-current="page"` on the one you are on.
+ * That is `Nav`'s answer, and reusing it rather than restating it is
+ * why `resolveActiveKey` decides the current item.
+ *
+ * What the tab pattern was *really* supplying here was the paint,
+ * and the paint is shared through `toTabTriggerClass` — so this
+ * looks identical to the `<button>` beside it in Storybook and is
+ * announced correctly.
+ */
+export const TabLink = ({
+  isCurrent,
+  item,
+  orientation,
+}: TabLinkProps): ReactNode => {
+  const RouterLink = useRouterLink()
+
+  const { href, icon, isDisabled = false, label } = item
+
+  const isExternal = item.isExternal === true
+
+  const className = toTabTriggerClass({
+    isDisabled,
+    isSelected: isCurrent,
+    orientation,
+  })
+
+  const content = (
+    <>
+      {icon === undefined ? null : (
+        // Decoration beside the item's own text. An icon that
+        // announces itself turns "Settings" into "gear Settings".
+        <span
+          aria-hidden="true"
+          className="flex shrink-0 text-content-secondary"
+        >
+          {icon}
+        </span>
+      )}
+
+      {label}
+
+      {isExternal ? (
+        <VisuallyHidden>
+          {" "}
+          (opens in a new tab)
+        </VisuallyHidden>
+      ) : null}
+    </>
+  )
+
+  if (isDisabled) {
+    // Not a link at all, rather than a link with a `disabled`
+    // attribute an anchor does not have. `aria-disabled` alone on a
+    // real `<a href>` still navigates on Enter, which is the version
+    // of this that looks right and is not.
+    return (
+      <span
+        aria-disabled="true"
+        className={toClassName(
+          "inline-flex shrink-0 items-center gap-2",
+          className,
+        )}
+      >
+        {content}
+      </span>
+    )
+  }
+
+  const LinkElement =
+    isExternal || !getIsRoutedHref(href) ? "a" : RouterLink
+
+  return (
+    <LinkElement
+      // The platform's own "you are here", and the reason the paint
+      // is never the only signal: an underline is invisible to a
+      // screen reader and to anyone who cannot tell the two colours
+      // apart.
+      aria-current={isCurrent ? "page" : undefined}
+      className={toClassName(
+        "inline-flex shrink-0 items-center gap-2 no-underline",
+        className,
+      )}
+      href={href}
+      // No `onClick`, deliberately — unlike `NavLink`, which has a
+      // panel to close behind the reader. A routed tab bar stays on
+      // screen across the navigation, so there is nothing to react
+      // to and a handler here would only be something to keep.
+      //
+      // `noreferrer` beside `noopener` on purpose: one closes the
+      // `window.opener` hole, the other stops this app's address
+      // leaking as the referrer to a product it does not own.
+      rel={isExternal ? "noopener noreferrer" : undefined}
+      target={isExternal ? "_blank" : undefined}
+    >
+      {content}
+    </LinkElement>
+  )
+}

package/src/Tabs/TabTrigger.tsx

@@ -1,32 +1,12 @@
 import type { ReactNode } from "react"
 import { useEffect } from "react"
 
-import { FOCUS_RING_CLASS } from "../intentStyles.ts"
 import { toClassName } from "../toClassName.ts"
-import type { TabItem, TabsOrientation } from "./Tabs.tsx"
-
-/**
- * The selected marker runs along the edge the tab list itself
- * sits on — under a horizontal bar, down the inline-end of a
- * vertical rail — and the negative margin pulls it over the
- * list's own border so the two read as one line rather than two.
- *
- * Logical properties throughout, which is the house rule and also
- * the only way a vertical rail lands on the correct side in RTL.
- */
-const ORIENTATION_EDGE_CLASS: Record<
+import type {
+  TabItem,
   TabsOrientation,
-  { base: string; selected: string }
-> = {
-  horizontal: {
-    base: "-mb-px border-b-2",
-    selected: "border-b-intent-accent-solid",
-  },
-  vertical: {
-    base: "-me-px border-e-2 text-start",
-    selected: "border-e-intent-accent-solid",
-  },
-}
+} from "./tabItems.ts"
+import { toTabTriggerClass } from "./tabStyles.ts"
 
 export type TabTriggerProps = {
   id: string
@@ -74,8 +54,6 @@ export const TabTrigger = ({
 }: TabTriggerProps): ReactNode => {
   const { isDisabled = false, key, label } = tab
 
-  const edge = ORIENTATION_EDGE_CLASS[orientation]
-
   useEffect(
     () => registerSelection(key),
     [key, registerSelection],
@@ -94,19 +72,12 @@ export const TabTrigger = ({
       aria-controls={panelId}
       aria-selected={isSelected}
       className={toClassName(
-        "cursor-pointer border-transparent px-3 py-2 font-medium text-sm whitespace-nowrap transition-colors duration-(--duration-fast) ease-standard",
-        edge.base,
-        // 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.
-        isSelected && edge.selected,
-        isSelected
-          ? "text-content-primary"
-          : "text-content-secondary hover:text-content-primary",
-        isDisabled &&
-          "cursor-not-allowed text-content-disabled hover:text-content-disabled",
-        FOCUS_RING_CLASS,
+        "cursor-pointer",
+        toTabTriggerClass({
+          isDisabled,
+          isSelected,
+          orientation,
+        }),
       )}
       disabled={isDisabled}
       id={id}

package/src/Tabs/Tabs.mdx

@@ -19,6 +19,76 @@ It did not come out ugly. The composition is two hooks and one decision.
 
 <Controls />
 
+## Two bars, and the question is not "how does it look"
+
+**Does this section have an address?**
+
+| | Panel tab | Routed tab |
+| --- | --- | --- |
+| The item carries | `content` | `href` |
+| Each trigger is | `<button role="tab">` | `<a href>` |
+| The bar is | `role="tablist"` | `<nav aria-label>` |
+| The section is drawn by | this component | the router, through your `<Outlet />` |
+| Which one is on | `Tabs` owns it | the address does, via `activeHref` |
+| Reload, Back, new tab | start over | land on the same section |
+
+```tsx
+// A disclosure inside one screen. Nothing outside knows about it.
+<Tabs label="Bay 3" tabs={[{ key: "log", label: "Log", content: <Log /> }]} />
+
+// A section that has an address.
+<Tabs
+  activeHref={pathname}
+  label="Bay 3 sections"
+  tabs={[{ href: "/projects/1/tasks", label: "Tasks" }]}
+/>
+<Outlet />
+```
+
+`activeHref` is the discriminant, and it is required in the routed mode. `tabs` alone
+could not carry the split: TypeScript does not narrow a union by the shape of an array's
+elements, so a bar mixing the two would type-check and then render half a navigation.
+
+<Canvas of={TabsStories.Routed} />
+
+### The paint is shared, and that is the point
+
+Docket had one of each on adjacent screens wearing **different paint** — a filled pill on
+the project bar, this underline on Settings — because a routed section switcher had to be
+built out of `Nav`, and `Nav`'s current item is a pill. `toTabTriggerClass` is now the one
+definition both triggers read, and `Tabs.test.tsx` compares the two computed styles
+property by property, because a screenshot cannot tell them apart on purpose.
+[Decision](../../../docs/decisions/2026-08-31-a-routed-tab-is-a-tab-with-an-href.md).
+
+<Canvas of={TabsStories.RoutedAllVariants} />
+
+### The routed bar is not a `tablist`
+
+`role="tab"` on an anchor **overrides** the link role. A screen reader announces a
+disclosure, the reader waits for a panel to appear beside it, and instead the address
+changes and the page under them is replaced. `aria-controls` has nothing to point at
+either — the section's content comes from the router, somewhere this component cannot see.
+
+So the routed bar is what it actually is: a named `<nav>` of real links with
+`aria-current="page"` on the one you are on. Which one that is comes from `Nav`'s
+`resolveActiveKey`, imported rather than restated — whole-segment matching, deepest match
+wins, the root is exact, an external item is never current, and the query string is not
+part of the answer.
+
+<Canvas of={TabsStories.RoutedAllStates} />
+
+A **disabled** routed tab is not a link at all. `<a>` has no `disabled` attribute, so the
+tempting version — a real `href` plus `aria-disabled` — greys out and still navigates on
+Enter and on a middle click; it renders as a `<span aria-disabled>` instead.
+
+### This is sub-navigation. `Nav` is still the app's destinations
+
+The header row, the side rail and the Narrow View's menu are `Nav` + `useNavLayout`, and
+that has not moved.
+[Decision](../../../docs/decisions/2026-08-27-nav-is-the-one-navigation-component-and-navbar-is-deprecated.md).
+A routed `Tabs` divides **one screen** into sections, so it renders no rail, no fold and
+no menu — a bar inside a screen has nowhere to fold to.
+
 ## The composition
 
 ```ts