@charcuterie/ui 3.29.1 → 3.31.0

package/src/Main/useScrollMemory.ts

@@ -0,0 +1,164 @@
+import { useCallback, useLayoutEffect, useRef } from "react"
+
+import {
+  recallScrollOffset,
+  rememberScrollOffset,
+} from "./scrollMemory.ts"
+
+/**
+ * How long a restore keeps trying while the content is still
+ * arriving.
+ *
+ * The offset cannot be applied until the scrollport is tall enough
+ * to hold it, and on a client-rendered page it is not: the commit
+ * that changes the route draws a skeleton, and the rows land a
+ * fetch later. So the restore re-applies as the content grows, and
+ * gives up after this. A page that takes longer than three seconds
+ * to fill has already been read from the top, and moving it then
+ * is a worse answer than leaving it where the reader put it.
+ */
+const RESTORE_WINDOW_MS = 3000
+
+/** A scroll the reader asked for. It ends the restore at once. */
+const READER_INTENT_EVENTS = [
+  "keydown",
+  "pointerdown",
+  "touchstart",
+  "wheel",
+] as const
+
+/**
+ * Remember where this history entry was scrolled to, and put it
+ * back when the reader returns to it.
+ *
+ * `scrollMemory.ts` says why the browser will not. This is the
+ * part that has to survive the two things a real page does:
+ *
+ *  1. **The content arrives late.** An offset applied against a
+ *     600px skeleton clamps to `0` and looks like it did nothing.
+ *     A `ResizeObserver` on the scrollport and on its content
+ *     column re-applies the offset every time either grows, until
+ *     the offset lands or the window closes.
+ *  2. **The reader scrolls during all that.** Any wheel, touch,
+ *     key or pointer press ends the restore immediately. The
+ *     alternative is a page that jumps out from under somebody who
+ *     has already started reading.
+ *
+ * The save is a passive `scroll` listener, suppressed while a
+ * restore is in flight. Without that suppression the feature eats
+ * itself: writing `scrollTop` on a still-short page clamps to `0`
+ * and fires a `scroll` event reading `0`, which would be saved
+ * over the very offset being restored.
+ *
+ * @param scrollKey Identifies the history entry — react-router's
+ *   `useLocation().key`. `undefined` turns the memory off, which is
+ *   what an app with no router gets.
+ */
+export const useScrollMemory = (
+  scrollKey: string | undefined,
+) => {
+  const elementRef = useRef<HTMLElement | null>(null)
+  const isRestoringRef = useRef(false)
+
+  // A ref rather than a query for the `<main>` id: the effect
+  // below runs in the same commit that mounts the node, and only a
+  // ref can say which node that was.
+  //
+  // `unknown` in, narrowed here, so the returned function is both a
+  // `RefCallback<HTMLElement>` and something `mergeRefs` accepts —
+  // that library's merge is typed for the prop-merging path, where
+  // every value is `unknown`.
+  const setElement = useCallback((node: unknown) => {
+    elementRef.current =
+      node instanceof HTMLElement ? node : null
+  }, [])
+
+  useLayoutEffect(() => {
+    const element = elementRef.current
+
+    if (!element || scrollKey === undefined) {
+      return undefined
+    }
+
+    const offset = recallScrollOffset(scrollKey)
+
+    // The arrow defers the read of `applyOffset`, so the three
+    // pieces can be declared in the order they depend on each
+    // other rather than in the order they are used.
+    const observer = new ResizeObserver(() => {
+      applyOffset()
+    })
+
+    const deadline = globalThis.setTimeout(() => {
+      stopRestoring()
+    }, RESTORE_WINDOW_MS)
+
+    const stopRestoring = () => {
+      if (!isRestoringRef.current) {
+        return
+      }
+
+      isRestoringRef.current = false
+      observer.disconnect()
+      globalThis.clearTimeout(deadline)
+
+      for (const eventName of READER_INTENT_EVENTS) {
+        element.removeEventListener(
+          eventName,
+          stopRestoring,
+        )
+      }
+    }
+
+    const applyOffset = () => {
+      if (!isRestoringRef.current) {
+        return
+      }
+
+      element.scrollTop = offset
+
+      // Landed. Anything further would only fight the reader.
+      if (element.scrollTop === offset) {
+        stopRestoring()
+      }
+    }
+
+    const onScroll = () => {
+      if (isRestoringRef.current) {
+        return
+      }
+
+      rememberScrollOffset(scrollKey, element.scrollTop)
+    }
+
+    isRestoringRef.current = true
+
+    for (const eventName of READER_INTENT_EVENTS) {
+      element.addEventListener(eventName, stopRestoring, {
+        passive: true,
+      })
+    }
+
+    // The scrollport's own height changes with the window; its
+    // content column's changes when the rows land. Both move the
+    // ceiling the offset is clamped against.
+    observer.observe(element)
+
+    for (const child of Array.from(element.children)) {
+      observer.observe(child)
+    }
+
+    element.addEventListener("scroll", onScroll, {
+      passive: true,
+    })
+
+    applyOffset()
+
+    return () => {
+      stopRestoring()
+      element.removeEventListener("scroll", onScroll)
+    }
+  }, [scrollKey])
+
+  return setElement
+}

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}