@charcuterie/ui 2.7.0 → 2.9.0

package/src/Field/FieldGroup.tsx

@@ -116,9 +116,11 @@ export const FieldGroup = ({
 
       {children}
 
+      {/* `text-sm` since 2026-08-10, matching `Field` — same reasoning,
+          and the two must not disagree about how big a description is. */}
       {description === undefined ? null : (
         <p
-          className="text-content-secondary text-xs"
+          className="text-content-secondary text-sm"
           id={descriptionId}
         >
           {description}
@@ -127,7 +129,7 @@ export const FieldGroup = ({
 
       {error === undefined ? null : (
         <p
-          className="text-intent-danger-content text-xs"
+          className="text-intent-danger-content text-sm"
           id={errorId}
         >
           {error}

package/src/LogViewer/LogViewer.test.tsx

@@ -67,6 +67,53 @@ test("a full pane is scrolled to the bottom", async () => {
   })
 })
 
+/**
+ * The browser's own contribution to defect 1, and the reason this is
+ * asserted rather than commented.
+ *
+ * Chromium picks an anchor node inside a scroll container and moves
+ * `scrollTop` to hold it still across a relayout. For a log pane that
+ * is the browser undoing the follow: `@charcuterie/tokens` ships
+ * Victor Mono `font-display: swap`, so a pane mounted before the face
+ * arrives is laid out twice, and the anchor drags a followed pane a
+ * pixel off the end. Measured on this story with the font request
+ * held back — 722 (at the end) with anchoring off, 721 (a pixel
+ * short) with it on.
+ *
+ * Whether the swap beats the mount is a race, so it presented as
+ * visual-regression flake on exactly one story rather than as a bug.
+ * The behavioural assertions above cannot catch it: their four pixels
+ * of slack exist for fractional device pixel ratios, and the drift
+ * fits inside them. So this asserts the opt-out itself — invisible in
+ * a screenshot, invisible in the DOM, and one `--write --unsafe` pass
+ * from being tidied away.
+ */
+test("a following pane opts out of the browser's scroll anchoring", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const pane = expectAgentDrivable(canvas, {
+    name: "Bay 8 rip log",
+    role: "log",
+  })
+
+  await expect(getComputedStyle(pane).overflowAnchor).toBe(
+    "none",
+  )
+
+  // And it hands anchoring back when the user takes over. `maxLines`
+  // drops old lines off the top of a live log, and anchoring is what
+  // stops that shoving the line they scrolled up to read.
+  pane.scrollTop = 0
+
+  pane.dispatchEvent(new Event("scroll", { bubbles: true }))
+
+  await waitFor(() => {
+    expect(getComputedStyle(pane).overflowAnchor).toBe(
+      "auto",
+    )
+  })
+})
+
 /**
  * The same defect, rebuilt out of two components that are each
  * individually right — and the reason `LogViewer` watches its own box

package/src/LogViewer/LogViewer.tsx

@@ -199,7 +199,41 @@ export const LogViewer = ({
         // `off` unless asked. See the note above; this is the
         // difference between an accessible log and an unusable page.
         aria-live={isAnnounced ? "polite" : "off"}
-        className="max-h-64 overflow-y-auto rounded-md border border-border-subtle bg-surface-sunken p-2 font-mono text-content-secondary text-xs"
+        className={toClassName(
+          "max-h-64 overflow-y-auto rounded-md border border-border-subtle bg-surface-sunken p-2 font-mono text-content-secondary text-xs",
+          // A sixth defect, and this one is nobody's code: scroll
+          // anchoring is the browser quietly *undoing* the follow
+          // above, and only sometimes.
+          //
+          // Chromium picks an anchor node in a scroll container and
+          // adjusts `scrollTop` to hold it still across a relayout.
+          // That is right for an article and wrong for a log: the
+          // whole contract here is "the bottom stays the bottom".
+          // `@charcuterie/tokens` ships Victor Mono `font-display:
+          // swap`, so a pane that mounts before the face arrives is
+          // laid out in the fallback and re-laid-out a moment later —
+          // and the anchor drags a followed pane off the end.
+          // Measured on the 60-line `Interactive` story, holding the
+          // font request back:
+          //
+          //   anchoring on,  font before mount : scrollTop 722, at the end
+          //   anchoring on,  font after mount  : scrollTop 721, a pixel short
+          //   anchoring off, either            : scrollTop 722, at the end
+          //
+          // Whether the swap beats the mount is a race, so the pane
+          // followed correctly on some renders and not others. It
+          // read as visual-regression flake for a week — one story,
+          // `components-logviewer--interactive`, shifted a pixel —
+          // because a race is what it is. The DOM test missed it: its
+          // four pixels of slack are there for fractional device
+          // pixel ratios, and one pixel fits inside them.
+          //
+          // Only while following. A user who scrolled up to read an
+          // error *wants* the anchor — `maxLines` drops old lines off
+          // the top, and anchoring is what stops that shoving the
+          // line they are reading up the pane.
+          isFollowing ? "[overflow-anchor:none]" : null,
+        )}
         onScroll={(scrollEvent) => {
           const pane = scrollEvent.currentTarget
 

package/src/RouterLink/AnchorLink.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode } from "react"
+
+import type { RouterLinkProps } from "./routerLink.ts"
+
+/**
+ * A plain `<a href>`, and the default every link component falls
+ * back to.
+ *
+ * It is the context's default value rather than a `null` check at
+ * each call site, which is what makes "no router installed" a
+ * configuration rather than a code path: `TextLink` and `ButtonLink`
+ * render `useRouterLink()` unconditionally and behave identically
+ * with and without a provider.
+ *
+ * It is also what a routed component falls back *to* for a
+ * destination the router must not intercept — see `getIsRoutedHref`.
+ */
+export const AnchorLink = ({
+  href,
+  ...anchorProps
+}: RouterLinkProps): ReactNode => (
+  <a {...anchorProps} href={href} />
+)

package/src/RouterLink/RouterLink.mdx

@@ -0,0 +1,178 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Guides/Routing" />
+
+# Routing
+
+`TextLink` and `ButtonLink` render a real `<a href>`. That is already correct with no setup
+at all — it navigates, it can be middle-clicked, ctrl-clicked, opened in a new tab and
+copied — it just reloads the page. **One provider at the app root** upgrades every link in
+the tree to the app's own soft navigation, with no change at any call site.
+
+## Why the library does not just import a router
+
+The fleet runs five answers at once: react-router v8 (mux-magic), react-router-dom v7
+(bambuddy), wouter-preact (spoolbuddy), two hand-rolled routers, and five apps with no
+router at all. A `react-router` dependency in `@charcuterie/ui` would be a package every
+consumer installs and most of them do not use — so the router is **injected**, the same way
+`ColorSchemeSwitcher` takes its `resolver` / `persistence` / `apply` seams, and the default
+is a working plain anchor rather than a throw.
+
+## react-router (v7 or v8)
+
+`react-router` is an **optional peer dependency**, and the adapter is a separate entry
+point — so an app that never imports this path never resolves it.
+
+```bash
+yarn add @charcuterie/ui react-router
+```
+
+```tsx
+// src/main.tsx
+import { RouterLinkProvider } from "@charcuterie/ui"
+import { ReactRouterLink } from "@charcuterie/ui/react-router"
+import { StrictMode } from "react"
+import { createRoot } from "react-dom/client"
+import {
+  createBrowserRouter,
+  RouterProvider,
+} from "react-router"
+
+import { routes } from "./routes.tsx"
+
+const router = createBrowserRouter(routes)
+
+createRoot(document.getElementById("root")).render(
+  <StrictMode>
+    <RouterLinkProvider link={ReactRouterLink}>
+      <RouterProvider router={router} />
+    </RouterLinkProvider>
+  </StrictMode>,
+)
+```
+
+`RouterLinkProvider` goes **outside** `RouterProvider` here on purpose: it is plain React
+context and needs no router of its own, and putting it outermost means a link rendered by a
+route element and a link rendered by an app-level chrome component both see it.
+
+Already on `react-router-dom` v7, as bambuddy is? Nothing changes. `react-router-dom` v7 is
+a re-export shim over `react-router`, and the adapter imports `Link` from the latter, so one
+import covers both installs.
+
+That is the whole integration. Every link in the app is now soft:
+
+```tsx
+import { ButtonLink, TextLink } from "@charcuterie/ui"
+
+export const ChannelCard = ({ channel }) => (
+  <Card>
+    <TextLink appearance="standalone" href="/channels">
+      Back to all channels
+    </TextLink>
+
+    <ButtonLink href={`/channels/${channel.id}/settings`}>
+      Configure
+    </ButtonLink>
+  </Card>
+)
+```
+
+## Any other router
+
+The seam's contract is **a component that takes `href`**, so an adapter is a rename. There
+is nothing to publish for wouter, TanStack Router, or a hand-rolled router — four lines in
+the app is the whole thing.
+
+```tsx
+// src/routing/WouterLink.tsx
+import type { RouterLinkComponent } from "@charcuterie/ui"
+import { Link } from "wouter-preact"
+
+export const WouterLink: RouterLinkComponent = ({
+  href,
+  ...linkProps
+}) => <Link {...linkProps} to={href} />
+```
+
+```tsx
+// src/main.tsx
+import { RouterLinkProvider } from "@charcuterie/ui"
+
+import { WouterLink } from "./routing/WouterLink.tsx"
+
+<RouterLinkProvider link={WouterLink}>
+  <App />
+</RouterLinkProvider>
+```
+
+A hand-rolled router — plex-channels' and gallery-downloader's shape — injects its own
+push:
+
+```tsx
+// src/routing/HashRouterLink.tsx
+import type { RouterLinkComponent } from "@charcuterie/ui"
+
+export const HashRouterLink: RouterLinkComponent = ({
+  href,
+  ...linkProps
+}) => (
+  <a
+    {...linkProps}
+    href={href}
+    onClick={(clickEvent) => {
+      // Let the browser have every click that is *asking* for the
+      // browser: a new tab, a new window, a download, a middle-click.
+      // Swallowing these is exactly what a `<button onClick>` gets
+      // wrong, and re-implementing them is what this component is
+      // avoiding.
+      if (
+        clickEvent.defaultPrevented ||
+        clickEvent.button !== 0 ||
+        clickEvent.altKey ||
+        clickEvent.ctrlKey ||
+        clickEvent.metaKey ||
+        clickEvent.shiftKey
+      ) {
+        return
+      }
+
+      clickEvent.preventDefault()
+
+      window.location.hash = href
+    }}
+  />
+)
+```
+
+## What the seam will not route
+
+Three destinations always fall through to a plain `<a>`, whatever is injected:
+
+| Destination | Why |
+| --- | --- |
+| `isExternal` | A router pushing `https://…` onto its history stack lands the SPA on a route that does not exist. |
+| Another scheme or origin — `https://`, `mailto:`, `tel:`, `//cdn…` | Same. `getIsRoutedHref` is the test, and it is exported. |
+| A fragment — `#credits` | The browser's own scroll-to-id is what a reader expects; a router turns it into a route change. |
+
+It is a test on the **destination** rather than a prop, deliberately: a component that
+routed whatever it was given would make `isExternal` a correctness switch instead of a
+presentation one, and an app that forgot it would ship a broken link rather than a slightly
+plain one.
+
+## Testing an app that uses this
+
+Nothing to mock. Without a provider the components render `AnchorLink`, so a component test
+asserts `getByRole("link", { name: … })` and its `href` with no router in the tree at all.
+With a provider, inject a stand-in that marks what it was handed — `TextLink.stories.tsx`'s
+`Routed` story is exactly that, and `TextLink.test.tsx` reads it.
+
+## API
+
+| Export | From | What |
+| --- | --- | --- |
+| `RouterLinkProvider` | `@charcuterie/ui` | The seam. `link` is the app's link component. |
+| `useRouterLink()` | `@charcuterie/ui` | The injected component, or `AnchorLink`. For an app building its own link-shaped component. |
+| `RouterLinkComponent` / `RouterLinkProps` | `@charcuterie/ui` | The contract: `ComponentPropsWithRef<"a">` with `href` required. |
+| `AnchorLink` | `@charcuterie/ui` | The plain `<a href>` default. |
+| `getIsRoutedHref(href)` | `@charcuterie/ui` | The destination test above. |
+| `ReactRouterLink` | `@charcuterie/ui/react-router` | The one shipped adapter. Optional peer. |

package/src/RouterLink/RouterLinkProvider.tsx

@@ -0,0 +1,68 @@
+import type { ReactNode } from "react"
+import { createContext, useContext } from "react"
+
+import { AnchorLink } from "./AnchorLink.tsx"
+import type { RouterLinkComponent } from "./routerLink.ts"
+
+/**
+ * The router seam: one injection at the app root, and every
+ * `TextLink` / `ButtonLink` in the tree navigates the app's own way.
+ *
+ * ### Why the library cannot just pick a router
+ *
+ * The fleet has five answers at once — react-router v8 (mux-magic),
+ * react-router-dom v7 (bambuddy), wouter-preact (spoolbuddy), two
+ * hand-rolled routers, and five apps with no router at all. A
+ * dependency on any one of them would be wrong for four of the five,
+ * and `@charcuterie/ui` taking a router as a runtime dependency is a
+ * thing every consumer inherits.
+ *
+ * So the shape is the one `ColorSchemeSwitcher` already uses for the
+ * browser: **the seam has a working default**. Nothing injected means
+ * `AnchorLink` — a real `<a href>` that navigates by reloading, which
+ * is correct, just not soft. An app that wants soft navigation
+ * injects its router's link once:
+ *
+ * ```tsx
+ * import { RouterLinkProvider } from "@charcuterie/ui"
+ * import { ReactRouterLink } from "@charcuterie/ui/react-router"
+ *
+ * <RouterLinkProvider link={ReactRouterLink}>
+ *   <App />
+ * </RouterLinkProvider>
+ * ```
+ *
+ * A router with no adapter here needs no adapter *from* here — the
+ * contract is a component taking `href`, so a four-line wrapper in
+ * the app is the whole integration. `Guides/Routing` shows both.
+ *
+ * ### It is deliberately not a hook the app calls
+ *
+ * `useNavigate` + `onClick` is what mux-magic and plex-channels do
+ * today, and it is how a nav item stops being a link: no middle-click,
+ * no ctrl-click, no "open in new tab", no status bar, nothing to copy.
+ * Injecting a *component* keeps the `<a href>` — the router only gets
+ * to intercept the plain-left-click that it can actually improve.
+ */
+const RouterLinkContext =
+  createContext<RouterLinkComponent>(AnchorLink)
+
+export const useRouterLink = (): RouterLinkComponent =>
+  useContext(RouterLinkContext)
+
+export const RouterLinkProvider = ({
+  children,
+  link,
+}: {
+  children: ReactNode
+  /**
+   * The app's link component, taking `href`. `ReactRouterLink` from
+   * `@charcuterie/ui/react-router`, or the app's own four-line
+   * wrapper around whatever it routes with.
+   */
+  link: RouterLinkComponent
+}): ReactNode => (
+  <RouterLinkContext.Provider value={link}>
+    {children}
+  </RouterLinkContext.Provider>
+)

package/src/RouterLink/routerLink.ts

@@ -0,0 +1,56 @@
+/**
+ * The shape of the thing a router injects, and the one question the
+ * link components ask before they use it.
+ *
+ * Types live here rather than beside either implementation so
+ * `AnchorLink` (the default) and `RouterLinkProvider` (which defaults
+ * to it) can both name them without importing each other.
+ */
+
+import type {
+  ComponentPropsWithRef,
+  ComponentType,
+} from "react"
+
+/**
+ * `href`, not `to`.
+ *
+ * The library is router-agnostic and the platform's word for a
+ * destination is `href` — so the contract is the DOM's, and each
+ * adapter renames it on the way in (`ReactRouterLink` maps `href` to
+ * react-router's `to`). Injecting a component whose prop is `to`
+ * would make `@charcuterie/ui`'s own API a mirror of one router's.
+ */
+export type RouterLinkProps = Omit<
+  ComponentPropsWithRef<"a">,
+  "href"
+> & {
+  href: string
+}
+
+export type RouterLinkComponent =
+  ComponentType<RouterLinkProps>
+
+/**
+ * Whether this destination is the injected router's to handle.
+ *
+ * A router's `<Link>` intercepts the click and pushes history, which
+ * is right for `/settings` and wrong for three cases it cannot serve:
+ *
+ *  - **Another origin or another scheme** — `https://…`, `mailto:`,
+ *    `tel:`, protocol-relative `//cdn…`. Pushing those onto the
+ *    history stack navigates the SPA to a route that does not exist.
+ *  - **A same-page fragment** — `#credits`. The browser's own
+ *    scroll-to-id is the behaviour a reader expects; a router turns
+ *    it into a route change.
+ *
+ * Everything else — `/x`, `x`, `?sort=name` — is the router's.
+ *
+ * Deliberately a *destination* test rather than a prop: a component
+ * that routed whatever it was given would make `isExternal` a
+ * correctness switch instead of a presentation one, and an app that
+ * forgot it would ship a broken link rather than a slightly plain
+ * one.
+ */
+export const getIsRoutedHref = (href: string): boolean =>
+  !/^(?:[a-z][a-z\d+\-.]*:|\/\/|#)/i.test(href)

package/src/SortableTableHeader/SortableTableHeader.tsx

@@ -90,7 +90,12 @@ export const SortableTableHeader = ({
   >
     <button
       className={toClassName(
-        "flex w-full cursor-pointer items-center gap-1.5 bg-transparent px-3 py-2 text-start font-medium text-content-secondary text-xs uppercase tracking-wide transition-colors duration-(--duration-fast) ease-standard",
+        // `text-sm` since 2026-08-10. This was the single most
+        // fragile combination in the package: `text-xs` at 12px,
+        // uppercased and letterspaced, which strips the word shapes
+        // readers use at small sizes. A column header is the label
+        // for everything under it, so it is content.
+        "flex w-full cursor-pointer items-center gap-1.5 bg-transparent px-3 py-2 text-start font-medium text-content-secondary text-sm uppercase tracking-wide transition-colors duration-(--duration-fast) ease-standard",
         "hover:text-content-primary",
         FOCUS_RING_CLASS,
       )}

package/src/TextLink/TextLink.mdx

@@ -0,0 +1,93 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as TextLinkStories from "./TextLink.stories";
+
+<Meta of={TextLinkStories} />
+
+# TextLink
+
+**Navigation that looks like a link.** Reach for it whenever pressing the thing takes the
+user somewhere — another route, another page, another site. If it changes something on the
+page instead, that is a `Button`
+([decision](https://github.com/Sawtaytoes/charcuterie/blob/master/docs/decisions/2026-08-10-buttons-are-actions-links-are-navigation.md)).
+
+Measured across the fleet before this shipped: **seven repos** hand-roll a back-link with a
+literal `←`, each with its own hover rule and its own idea of whether focus is visible — and
+points-market, which already consumes this library, reaches for a ghost `Button` for its
+header home link because there was nothing else to reach for. All of them are an `<a href>`
+here, so middle-click, ctrl-click, "open in new tab", "copy link address", and the browser's
+status bar work without anybody implementing them.
+
+<Canvas of={TextLinkStories.Default} />
+
+## Props
+
+<Controls />
+
+## Two appearances
+
+<Canvas of={TextLinkStories.AllAppearances} />
+
+| | `inline` | `standalone` |
+| --- | --- | --- |
+| Where it lives | inside a sentence | on its own — a back-link, a nav item, a "view all" |
+| Display | `inline`, so it wraps with the prose | `inline-flex`, with a gap for an icon |
+| Underline | always | on hover |
+| Type size | inherited — never its own | inherited |
+
+The permanent underline on `inline` is not a taste call: inside a paragraph, colour alone
+cannot be the only thing marking a link (WCAG 1.4.1). A standalone nav column has position
+and spacing doing that work, so it underlines on hover instead — a column of permanently
+underlined items reads as a mistake.
+
+There is deliberately **no `size` prop**. Text takes the size of the text around it; a link
+that resized itself would be a hole in whatever type scale it landed in.
+
+<Canvas of={TextLinkStories.BackLink} />
+
+<Canvas of={TextLinkStories.InProse} />
+
+## What it fixes
+
+| Fleet behaviour today | Here |
+| --- | --- |
+| `<div onClick>` or `<button onClick={() => navigate(…)}>` as a nav item | a real `<a href>`, with everything the browser gives one |
+| A `←` and its label as two siblings, so only the label is the tap target | one anchor, arrow inside it |
+| `outline-none` with nothing put back | `focus-visible` at the variant's own ring width |
+| `target="_blank"` with no `rel` and no warning | `isExternal` does all three |
+| Seven spellings of the same hover | one |
+
+## Accessibility contract
+
+- The accessible name is the children. An `iconStart`/`iconEnd` is decoration inside the
+  same anchor, so the name stays the words.
+- `isExternal` adds a visually-hidden **"(opens in a new tab)"** to the name, because a new
+  tab with no warning is a WCAG 3.2.5 surprise — and `rel="noopener noreferrer"`, because
+  `target="_blank"` alone hands the destination a live `window.opener` into the app.
+- `isDisabled` **drops `href`** and sets `aria-disabled` with an explicit `role="link"`. An
+  anchor with no `href` is inert and out of the tab order by the platform's own rules,
+  which is the honest version of a state the platform does not have; the role keeps it
+  announced as an unavailable link rather than vanishing into a `<span>`. Reach for it
+  rarely — a dead link in a sentence usually reads better as plain text.
+- Hover changes the **underline**, never the colour. There is no `intent.*.content-hover`
+  token, and an invented colour is one the contrast gate has never measured.
+
+<Canvas of={TextLinkStories.AllStates} />
+
+<Canvas of={TextLinkStories.External} />
+
+## Icons are the app's
+
+The library ships **zero** SVGs and no symbol glyphs in a default
+([decision](https://github.com/Sawtaytoes/charcuterie/blob/master/docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md)) —
+`←` and `↗` measure blank in this repo's headless Chromium and on the kiosk Pis, so the
+component takes a `ReactNode` and the app passes the arrow it already owns.
+
+## Routing
+
+`TextLink` renders through whatever link component the app injected at its root, and a
+plain `<a>` when nothing is injected. See **Guides/Routing**.
+
+<Canvas of={TextLinkStories.Routed} />
+
+<Canvas of={TextLinkStories.AllIntents} />