@charcuterie/ui 3.30.0 → 3.32.0

package/src/Tabs/Tabs.tsx

@@ -1,33 +1,22 @@
-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"
+import { PanelTabs } from "./PanelTabs.tsx"
+import { RoutedTabs } from "./RoutedTabs.tsx"
+import type {
+  TabItem,
+  TabLinkItem,
+  TabsActivation,
+  TabsOrientation,
+} from "./tabItems.ts"
 
-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
+type TabsCommonProps = {
+  className?: string
+  /** The tab bar's accessible name. Required. */
+  label: string
+  orientation?: TabsOrientation
 }
 
-export type TabsProps = {
+export type TabsPanelProps = TabsCommonProps & {
   /** **Initial** only. Charcuterie owns it from then on. */
   activeKey?: string
   /**
@@ -42,292 +31,101 @@ export type TabsProps = {
    * 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[]
+  tabs: readonly TabItem[]
 }
 
-const ORIENTATION_KEYS: Record<
-  TabsOrientation,
-  { next: string; previous: string }
-> = {
-  horizontal: {
-    next: "ArrowRight",
-    previous: "ArrowLeft",
-  },
-  vertical: { next: "ArrowDown", previous: "ArrowUp" },
+export type TabsLinkProps = TabsCommonProps & {
+  /**
+   * The address the app is at — usually `location.pathname`. The tab
+   * whose `href` matches wears `aria-current="page"`.
+   *
+   * **Required, and it is the discriminant.** `Nav` leaves the
+   * equivalent optional because a top-level bar is honest about
+   * naming nothing on a screen it does not contain. A routed tab bar
+   * is drawn *inside* the section it divides, so "none of these" is
+   * not a state it has; an app that wants it passes a path that
+   * matches no tab.
+   */
+  activeHref: string
+  tabs: readonly TabLinkItem[]
 }
 
 /**
- * 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:
+ * The union splits on `activeHref`, which only the routed member
+ * has. `tabs` alone could not carry the split — TypeScript does not
+ * narrow a union by the shape of an array's elements, so a mixed bar
+ * would type-check and then render half a navigation.
+ */
+export type TabsProps = TabsLinkProps | TabsPanelProps
+
+const getIsRoutedProps = (
+  props: TabsProps,
+): props is TabsLinkProps => "activeHref" in props
+
+/**
+ * One choice out of a handful, all of them on screen at once — and
+ * the choice is either a **panel** this component reveals or a
+ * **place** the router goes to.
  *
- * ```ts
- * const selection = useSinglePicker({ selectedValue: initialKey })
- * const focus = useRovingFocus({ activeValue: initialKey })
+ * ```tsx
+ * // A section of this screen. Nothing outside knows about it.
+ * <Tabs label="Bay 3" tabs={[{ key: "log", label: "Log", content: … }]} />
  *
- * // `automatic` is this line, and `manual` is its absence.
- * if (activation === "automatic") selection.select(focus.activeValue)
+ * // A section that has an address.
+ * <Tabs
+ *   activeHref={pathname}
+ *   label="Bay 3 sections"
+ *   tabs={[{ href: "/projects/1/tasks", label: "Tasks" }]}
+ * />
+ * <Outlet />
  * ```
  *
- * ### Selection, not visibility — and the difference is not cosmetic
+ * ## Which one, and the question is not "how does it look"
  *
- * 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.
+ * **Does this section have an address?** If reloading the page, or
+ * opening it in a second tab, or pressing Back has to land the
+ * reader back on the same section, it is routed and every tab is an
+ * `<a href>`. If the section is a disclosure inside one screen —
+ * Settings' groups, a card's detail — it is a panel and every tab is
+ * a `<button>`.
  *
- * 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).
+ * The two are drawn identically on purpose, through
+ * `toTabTriggerClass`. Docket had one of each on adjacent screens
+ * wearing different paint, because the routed one had to be built
+ * out of `Nav` and `Nav`'s current item is a filled pill
+ * ([decision](../../../../docs/decisions/2026-08-31-a-routed-tab-is-a-tab-with-an-href.md)).
  *
- * ### What it does not use, and why that is the right answer
+ * ## `Nav` is still the app's destinations
  *
- * 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.
+ * This is **sub**-navigation: the sections of the screen you are
+ * already on. The app's own destinations — the header row, the side
+ * rail, 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` renders no rail, no fold and no menu, because a
+ * bar dividing one screen has nowhere to fold to.
  *
- * ### Focus is moved deliberately, and only then
+ * ## The routed bar is not a `tablist`, and that is deliberate
  *
- * `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.
+ * `role="tab"` on an anchor overrides the link role, so a screen
+ * reader announces a disclosure and the address changes instead. See
+ * `TabLink`. The routed bar is a `<nav>` of links with
+ * `aria-current="page"`; the panel bar below keeps the full APG
+ * pattern, `aria-controls` and all.
+ *
+ * ## The panel bar: 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. `PanelTabs` is where that lives.
  */
-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],
+export const Tabs = (props: TabsProps): ReactNode =>
+  getIsRoutedProps(props) ? (
+    <RoutedTabs {...props} />
+  ) : (
+    <PanelTabs {...props} />
   )
-
-  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/Tabs/tabItems.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from "react"
+
+import type { NavItem } from "../Nav/navItems.ts"
+
+export type TabsActivation = "automatic" | "manual"
+
+export type TabsOrientation = "horizontal" | "vertical"
+
+/**
+ * A tab that reveals a panel this component renders. The section
+ * lives in memory, so leaving the screen and coming back starts over
+ * — which is correct for a disclosure and wrong for a place.
+ */
+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
+}
+
+/**
+ * A tab that is a **place** — it has an address, and choosing it
+ * changes the address.
+ *
+ * It is a `NavItem` with `isDisabled` added, and that is not
+ * convenience: it means `resolveActiveKey` decides which routed tab
+ * is current with the exact rule `Nav` uses, rather than a second
+ * implementation of segment matching that drifts from it. `label`
+ * narrows to `string` for the same reason it does on `NavItem` — it
+ * is the accessible name of a link.
+ */
+export type TabLinkItem = NavItem & {
+  isDisabled?: boolean
+}

package/src/Tabs/tabStyles.ts

@@ -0,0 +1,107 @@
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import type { TabsOrientation } from "./tabItems.ts"
+
+/**
+ * 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<
+  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",
+  },
+}
+
+/**
+ * One tab's paint, shared by the `<button>` a panel tab renders and
+ * the `<a href>` a routed tab renders.
+ *
+ * **This file is the reason the two cannot drift.** Docket's project
+ * bar and Docket's Settings bar are the same shape doing the same
+ * job, and before the routed mode existed the first was a `Nav`
+ * wearing a filled pill while the second was a `Tabs` wearing this
+ * underline — two answers to one question, in one app, on adjacent
+ * screens
+ * ([decision](../../../../docs/decisions/2026-08-31-a-routed-tab-is-a-tab-with-an-href.md)).
+ *
+ * The caller adds the one class that is genuinely its own: a button
+ * needs `cursor-pointer`, an anchor needs `no-underline`.
+ */
+export const toTabTriggerClass = ({
+  isDisabled,
+  isSelected,
+  orientation,
+}: {
+  isDisabled: boolean
+  isSelected: boolean
+  orientation: TabsOrientation
+}): string => {
+  const edge = ORIENTATION_EDGE_CLASS[orientation]
+
+  return toClassName(
+    "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,
+  )
+}
+
+/**
+ * The list's own box — the border the selected marker sits on, and
+ * the scroll rule.
+ *
+ * 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 — a panel
+ * bar's `RovingFocus` calls `.focus()`, a routed bar's links are in
+ * the tab order, and the browser scrolls a focused element into view.
+ */
+export const toTabListClass = (
+  orientation: TabsOrientation,
+): string =>
+  toClassName(
+    "flex gap-1 border-border-subtle",
+    "[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",
+  )

package/src/index.ts

@@ -37,6 +37,11 @@ export type {
   AccordionProps,
 } from "./Accordion/Accordion.tsx"
 export { Accordion } from "./Accordion/Accordion.tsx"
+export type {
+  ActionTileItem,
+  ActionTilesProps,
+} from "./ActionTiles/ActionTiles.tsx"
+export { ActionTiles } from "./ActionTiles/ActionTiles.tsx"
 export type { AdaptiveGridProps } from "./AdaptiveGrid/AdaptiveGrid.tsx"
 export { AdaptiveGrid } from "./AdaptiveGrid/AdaptiveGrid.tsx"
 export type { ColumnChoice } from "./AdaptiveGrid/chooseColumns.ts"
@@ -427,12 +432,17 @@ export {
   getIsConnectionBusy,
 } from "./statusIntent.ts"
 export type {
-  TabItem,
-  TabsActivation,
-  TabsOrientation,
+  TabsLinkProps,
+  TabsPanelProps,
   TabsProps,
 } from "./Tabs/Tabs.tsx"
 export { Tabs } from "./Tabs/Tabs.tsx"
+export type {
+  TabItem,
+  TabLinkItem,
+  TabsActivation,
+  TabsOrientation,
+} from "./Tabs/tabItems.ts"
 export type {
   TextLinkAppearance,
   TextLinkProps,

package/src/sourceRules.test.ts

@@ -537,7 +537,15 @@ test("the barrel is the only place components are re-exported", async () => {
   // active-path rule an app's tests want to assert directly, and
   // `useNavLayout.ts`, because the app has to read the width rule to
   // know which corner to render into.
-  expect(componentNames.length).toBe(61)
+  //
+  // `ActionTiles` is +1 -> 62. It is `RadioGroup itemShape="tile"`
+  // with the radio taken away: the box is shared through
+  // `tileStyles.ts`, and nothing else is. The 2026-08-25 record that
+  // made the choice tile a `RadioGroup` shape named this case under
+  // what it deliberately does not cover — a tile that navigates is
+  // not a radio, and giving one `aria-checked` would be worse than
+  // the paint it replaced.
+  expect(componentNames.length).toBe(62)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)