@charcuterie/ui 2.7.0 → 2.8.0

package/src/TextLink/TextLink.stories.tsx

@@ -0,0 +1,260 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+
+import { intentArgType } from "../argTypes.storyHelpers.ts"
+import {
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import {
+  ArrowLeftIcon,
+  ExternalIcon,
+} from "../icons.storyHelpers.tsx"
+import { RouterLinkProvider } from "../RouterLink/RouterLinkProvider.tsx"
+import type { RouterLinkProps } from "../RouterLink/routerLink.ts"
+import { TextLink } from "./TextLink.tsx"
+
+/**
+ * A stand-in for react-router's `<Link>` — the marker attribute is
+ * how the boards (and `TextLink.test.tsx`) show which destinations
+ * the injected router was handed and which ones went straight to the
+ * platform.
+ */
+const SoftRouterLink = ({
+  href,
+  ...linkProps
+}: RouterLinkProps): ReactNode => (
+  <a {...linkProps} data-router="soft" href={href} />
+)
+
+const INTENTS = [
+  "neutral",
+  "accent",
+  "success",
+  "warning",
+  "danger",
+  "info",
+] as const
+
+const meta = {
+  title: "Components/TextLink",
+  component: TextLink,
+  parameters: { layout: "padded" },
+  argTypes: {
+    intent: intentArgType,
+  },
+  // The component's own defaults, restated. Storybook has not
+  // seeded `args` from a docgen `defaultValue` since v7, so without
+  // this the props table prints `"inline"` in the Default column
+  // while the radio beside it has nothing selected.
+  args: {
+    appearance: "inline",
+    href: "/library",
+    intent: "accent",
+    isDisabled: false,
+    isExternal: false,
+  },
+} satisfies Meta<typeof TextLink>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { children: "the rip queue" },
+}
+
+/**
+ * The two modes, in the layouts that tell them apart — an inline link
+ * has to be seen *inside* a sentence, and a standalone one has to be
+ * seen on its own line with an icon beside it.
+ */
+export const AllAppearances: Story = {
+  args: { children: "the rip queue" },
+  render: (linkProps) => (
+    <StorySection title="Inline lives in a sentence and stays underlined. Standalone is its own element and underlines on hover.">
+      <StoryGrid columns={2}>
+        <StoryCell label="inline">
+          <p className="max-w-prose text-content-secondary text-md">
+            Discs land in{" "}
+            <TextLink {...linkProps} appearance="inline" />{" "}
+            as soon as the drive reports them, and stay
+            there until a profile finishes.
+          </p>
+        </StoryCell>
+
+        <StoryCell label="standalone">
+          <TextLink
+            {...linkProps}
+            appearance="standalone"
+            iconStart={<ArrowLeftIcon />}
+          >
+            Back to all discs
+          </TextLink>
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * The back-link seven repos hand-roll, each with its own `←`, its own
+ * hover rule, and its own idea of whether focus is visible.
+ *
+ * The glyph is still the app's — the library ships no icons — but the
+ * anchor, the focus ring, and the hover are the same three everywhere
+ * now.
+ */
+export const BackLink: Story = {
+  args: {
+    appearance: "standalone",
+    children: "Back to all discs",
+    href: "/discs",
+    iconStart: <ArrowLeftIcon />,
+  },
+}
+
+export const AllIntents: Story = {
+  args: { children: "the rip queue" },
+  render: (linkProps) => (
+    <StorySection title="Six intents. Navigation is almost always accent or neutral — danger belongs on a Button, because deleting is an action.">
+      <StoryGrid columns={3}>
+        {INTENTS.map((intent) => (
+          <StoryCell key={intent} label={intent}>
+            <TextLink {...linkProps} intent={intent}>
+              {intent}
+            </TextLink>
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * Hover, focus, and the disabled treatment, forced by the
+ * pseudo-states addon rather than driven — a board that has to be
+ * *driven* to show its states is a test wearing a demo's clothes.
+ */
+export const AllStates: Story = {
+  args: { children: "the rip queue" },
+  parameters: {
+    pseudo: {
+      focusVisible: ["#focus-target"],
+      hover: ["#hover-inline", "#hover-standalone"],
+    },
+  },
+  render: (linkProps) => (
+    <StoryGrid columns={3}>
+      <StoryCell label="inline">
+        <TextLink {...linkProps} />
+      </StoryCell>
+
+      <StoryCell label="inline · hover (forced)">
+        <TextLink {...linkProps} id="hover-inline" />
+      </StoryCell>
+
+      <StoryCell label="inline · focus-visible (forced)">
+        <TextLink {...linkProps} id="focus-target" />
+      </StoryCell>
+
+      <StoryCell label="standalone">
+        <TextLink {...linkProps} appearance="standalone" />
+      </StoryCell>
+
+      <StoryCell label="standalone · hover (forced)">
+        <TextLink
+          {...linkProps}
+          appearance="standalone"
+          id="hover-standalone"
+        />
+      </StoryCell>
+
+      <StoryCell label="disabled">
+        <TextLink {...linkProps} isDisabled />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * `isExternal` is three things at once: `target="_blank"`,
+ * `rel="noopener noreferrer"`, and a visually-hidden *"(opens in a
+ * new tab)"* so the surprise is announced rather than only
+ * discovered.
+ *
+ * The `↗` is the app's, passed as `iconEnd` — the fleet's existing
+ * convention, and the library ships no glyphs.
+ */
+export const External: Story = {
+  args: {
+    children: "the MakeMKV forum thread",
+    href: "https://forum.makemkv.com",
+    iconEnd: <ExternalIcon />,
+    isExternal: true,
+  },
+}
+
+/**
+ * The seam, and the three destinations it deliberately does **not**
+ * take.
+ *
+ * With a `RouterLinkProvider` at the root, an in-app path renders
+ * through the injected component and navigates softly. An external
+ * URL and a same-page fragment fall back to a plain `<a>` — a router
+ * pushing `https://…` onto its history stack lands the SPA on a route
+ * that does not exist, and `#credits` is the browser's own
+ * scroll-to-id, not a route change.
+ */
+export const Routed: Story = {
+  args: { appearance: "standalone" },
+  decorators: [
+    (Story) => (
+      <RouterLinkProvider link={SoftRouterLink}>
+        <Story />
+      </RouterLinkProvider>
+    ),
+  ],
+  render: (linkProps) => (
+    <StorySection title="Injected router on the left; the two the seam hands back to the platform on the right.">
+      <StoryRow>
+        <TextLink {...linkProps} href="/library">
+          Routed to /library
+        </TextLink>
+
+        <TextLink
+          {...linkProps}
+          href="https://forum.makemkv.com"
+          iconEnd={<ExternalIcon />}
+          isExternal
+        >
+          External to makemkv.com
+        </TextLink>
+
+        <TextLink {...linkProps} href="#credits">
+          Fragment to #credits
+        </TextLink>
+      </StoryRow>
+    </StorySection>
+  ),
+}
+
+export const InProse: Story = {
+  args: { children: "the rip queue" },
+  render: (linkProps) => (
+    <StorySection title="An inline link inherits the type it sits in and wraps with it — the reason it is not an inline-flex box.">
+      <StoryRow>
+        <p className="max-w-[18rem] text-content-secondary text-sm">
+          A long paragraph, set small, in which{" "}
+          <TextLink {...linkProps}>
+            a link long enough to wrap across two lines
+          </TextLink>{" "}
+          keeps its underline on both of them and never
+          takes the line height with it.
+        </p>
+      </StoryRow>
+    </StorySection>
+  ),
+}

package/src/TextLink/TextLink.test.tsx

@@ -0,0 +1,230 @@
+import {
+  composeStories,
+  composeStory,
+} from "@storybook/react"
+import { expect, userEvent } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import meta, * as stories from "./TextLink.stories.tsx"
+
+const {
+  AllAppearances,
+  AllStates,
+  BackLink,
+  Default,
+  External,
+  Routed,
+} = composeStories(stories)
+
+/**
+ * Nothing here **clicks** a link. A real `<a href>` in a real browser
+ * navigates, and navigating the test page away is not a failure mode
+ * worth reproducing — so the contract asserted is the one that
+ * matters: the element, its `href`, and its place in the tab order.
+ * That the browser then navigates is the browser's job, and getting
+ * it for free is the entire argument for rendering an anchor.
+ */
+test("is drivable by role and name", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const link = expectAgentDrivable(canvas, {
+    name: "the rip queue",
+    role: "link",
+  })
+
+  await expect(link).toHaveAttribute("href", "/library")
+})
+
+test("Tab reaches it", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const link = canvas.getByRole("link", {
+    name: "the rip queue",
+  })
+
+  await userEvent.tab()
+
+  await expect(link).toHaveFocus()
+})
+
+/**
+ * The whole difference between the two appearances, measured rather
+ * than eyeballed: an inline link is `display: inline` so it wraps
+ * with the prose around it, and it carries a permanent underline
+ * because colour alone cannot mark a link inside a paragraph
+ * (WCAG 1.4.1). A standalone one is a flex box with a gap for its
+ * icon, and underlines only on hover.
+ */
+test("inline flows with prose; standalone is its own box", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllAppearances)
+
+  const inline = canvas.getByRole("link", {
+    name: "the rip queue",
+  })
+
+  const standalone = canvas.getByRole("link", {
+    name: "Back to all discs",
+  })
+
+  await expect(getComputedStyle(inline).display).toBe(
+    "inline",
+  )
+
+  await expect(
+    getComputedStyle(inline).textDecorationLine,
+  ).toBe("underline")
+
+  // `display` is asserted as *containing* flex rather than equalling
+  // `inline-flex`: this cell is itself a flex container, and CSS
+  // blockifies a flex item's outer display, so `inline-flex` computes
+  // to `flex` here and would compute to `inline-flex` one story over.
+  // `align-items` is the property that survives blockification and is
+  // the one doing the work — it is what puts a back-arrow on the
+  // text's centre line.
+  await expect(
+    getComputedStyle(standalone).display,
+  ).toContain("flex")
+
+  await expect(
+    getComputedStyle(standalone).alignItems,
+  ).toBe("center")
+
+  await expect(
+    getComputedStyle(standalone).textDecorationLine,
+  ).toBe("none")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a back-link is one anchor, not an icon beside a link", async () => {
+  const { canvas } = await mountStory(BackLink)
+
+  // The `←` is *inside* the anchor, so the arrow is part of the tap
+  // target rather than a decoration sitting next to it — which is
+  // what makes the hand-rolled version in seven repos a 40px target
+  // instead of a 12px one.
+  const link = expectAgentDrivable(canvas, {
+    name: "Back to all discs",
+    role: "link",
+  })
+
+  await expect(link.querySelector("svg")).not.toBeNull()
+  await expect(link).toHaveAttribute("href", "/discs")
+})
+
+/**
+ * `target="_blank"` without `rel="noopener"` hands the destination a
+ * live `window.opener` into the app, and a new tab with no warning is
+ * a WCAG 3.2.5 surprise. Both are the component's job, not the
+ * caller's.
+ */
+test("an external link opens safely and says so", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(External)
+
+  const link = expectAgentDrivable(canvas, {
+    name: /the MakeMKV forum thread/,
+    role: "link",
+  })
+
+  await expect(link).toHaveAttribute("target", "_blank")
+  await expect(link).toHaveAttribute(
+    "rel",
+    "noopener noreferrer",
+  )
+  await expect(link).toHaveAccessibleName(
+    /opens in a new tab/,
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * A disabled link is not a platform concept, so the component builds
+ * one out of the two things that are: **no `href`** — which is what
+ * takes an anchor out of the tab order and makes it inert — and
+ * `aria-disabled`, which is what keeps it announced as a link rather
+ * than disappearing into a `<span>`.
+ *
+ * The alternative every hand-rolled version ships is a focusable
+ * `<a href>` with a click handler that returns early: reachable,
+ * pressable, and silently does nothing.
+ */
+test("a disabled link has no href, is skipped by Tab, and still names itself", async () => {
+  const { canvas, canvasElement } = await mountStory(
+    composeStory(
+      {
+        args: {
+          children: "the rip queue",
+          isDisabled: true,
+        },
+      },
+      meta,
+    ),
+  )
+
+  const link = canvas.getByRole("link", {
+    name: "the rip queue",
+  })
+
+  await expect(link).not.toHaveAttribute("href")
+  await expect(link).toHaveAttribute(
+    "aria-disabled",
+    "true",
+  )
+
+  await userEvent.tab()
+
+  await expect(link).not.toHaveFocus()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The seam, and the two destinations it hands back to the platform.
+ */
+test("an injected router takes in-app paths and nothing else", async () => {
+  const { canvas } = await mountStory(Routed)
+
+  await expect(
+    canvas.getByRole("link", {
+      name: "Routed to /library",
+    }),
+  ).toHaveAttribute("data-router", "soft")
+
+  await expect(
+    canvas.getByRole("link", {
+      name: /External to makemkv\.com/,
+    }),
+  ).not.toHaveAttribute("data-router")
+
+  await expect(
+    canvas.getByRole("link", {
+      name: "Fragment to #credits",
+    }),
+  ).not.toHaveAttribute("data-router")
+})
+
+test("with no provider it is still a real anchor", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const link = canvas.getByRole("link", {
+    name: "the rip queue",
+  })
+
+  // The default seam is `AnchorLink`, so an app with no router
+  // installed gets a working link rather than a runtime error or a
+  // dead `<span>`.
+  await expect(link.tagName).toBe("A")
+  await expect(link).not.toHaveAttribute("data-router")
+})
+
+test("the states board is axe-clean in every state it forces", async () => {
+  const { canvasElement } = await mountStory(AllStates)
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/TextLink/TextLink.tsx

@@ -0,0 +1,194 @@
+import type { IntentName } from "@charcuterie/tokens"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import {
+  FOCUS_RING_CLASS,
+  INTENT_CONTENT_CLASS,
+} from "../intentStyles.ts"
+import { useRouterLink } from "../RouterLink/RouterLinkProvider.tsx"
+import { getIsRoutedHref } from "../RouterLink/routerLink.ts"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+
+/**
+ * Two ways a link sits in a layout, and the difference is real rather
+ * than decorative.
+ *
+ *  - `inline` lives **inside a sentence**. It is `display: inline`, so
+ *    it wraps across lines with the prose around it, it inherits the
+ *    surrounding font size rather than declaring one, and it is
+ *    underlined — because inside a paragraph, colour alone is the
+ *    thing WCAG 1.4.1 says cannot carry the meaning on its own.
+ *  - `standalone` is **its own element**: a back-link, a nav item, a
+ *    "view all" beside a heading. It is an inline flex box so an
+ *    `iconStart` sits on the text's centre line with a real gap, and
+ *    it underlines on hover instead of permanently — a column of
+ *    permanently-underlined nav items reads as a mistake.
+ */
+export type TextLinkAppearance = "inline" | "standalone"
+
+export type TextLinkProps = Omit<
+  ComponentPropsWithRef<"a">,
+  "href"
+> & {
+  appearance?: TextLinkAppearance
+  /**
+   * Required, and required even when disabled — a navigation that
+   * cannot say where it goes is a button wearing a link's clothes.
+   */
+  href: string
+  iconEnd?: ReactNode
+  /**
+   * The back-arrow, supplied by the app. The library ships no glyphs
+   * — see
+   * `docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md`
+   * — and the seven repos that hand-roll a `← Back` today already own
+   * the character they want.
+   */
+  iconStart?: ReactNode
+  intent?: IntentName
+  isDisabled?: boolean
+  isExternal?: boolean
+  /** What `isExternal` announces. Not shown. */
+  newTabLabel?: string
+}
+
+const TEXT_LINK_APPEARANCE_CLASS: Record<
+  TextLinkAppearance,
+  string
+> = {
+  // No `text-*` of its own: an inline link that resized itself would
+  // be a hole in whatever type scale the paragraph is set in.
+  inline:
+    "underline decoration-1 underline-offset-2 hover:decoration-2",
+  standalone:
+    "inline-flex items-center gap-1 font-medium no-underline underline-offset-2 hover:underline",
+}
+
+/**
+ * Hover changes the **underline**, never the colour, and there is no
+ * hover-tinted background either.
+ *
+ * A text link has no box to fill, so `INTENT_HOVER_CLASS` — which
+ * lands on the intent's tinted surface — would paint a coloured
+ * rectangle around a word mid-sentence. And there is no
+ * `intent.*.content-hover` token to shift the text to: the ramp goes
+ * `surface` / `surface-hover` / `border` / `content` / `solid` /
+ * `solid-hover` / `on-solid`, so a hover colour here would have to be
+ * invented, and an invented colour is one the contrast gate has never
+ * measured. Underline weight is free of both problems and shifts no
+ * layout.
+ */
+const TEXT_LINK_BASE_CLASS = "cursor-pointer rounded-xs"
+
+/**
+ * The disabled paint, keyed off `aria-disabled` because an `<a>` has
+ * no `:disabled` to match. See `ARIA_DISABLED_CLASS` — this is its
+ * text-shaped twin, minus the box treatment a run of prose has no
+ * room for.
+ */
+const TEXT_LINK_ARIA_DISABLED_CLASS =
+  "aria-disabled:pointer-events-none aria-disabled:text-content-disabled aria-disabled:no-underline"
+
+/**
+ * Navigation that looks like a link.
+ *
+ * The fleet has **seven repos** hand-rolling a back-link — each with
+ * its own `←`, its own hover rule, and its own idea of whether focus
+ * is visible — and points-market's header title is a clickable
+ * `<div>`. This is the thing to reach for instead, and the reason the
+ * split with `ButtonLink` exists at all: the two differ in **paint,
+ * not semantics**. Both render a real `<a href>`; picking between
+ * them is picking how it looks, which is a decision an agent can make
+ * correctly from the name alone
+ * ([decision](../../../docs/decisions/2026-08-10-buttons-are-actions-links-are-navigation.md)).
+ *
+ * What it does not do is as load-bearing as what it does:
+ *
+ *  - **No `onClick`-only mode.** If it does not navigate, it is a
+ *    `Button` with `appearance="ghost"`, not a link.
+ *  - **No `size`.** Text takes the size of the text around it. A
+ *    standalone link that wants `text-sm` gets it from the block it
+ *    sits in, or from `className`.
+ *  - **No colour change on hover.** See `TEXT_LINK_BASE_CLASS`.
+ *
+ * `isDisabled` drops `href` rather than shipping a focusable anchor
+ * that ignores clicks; `role="link"` + `aria-disabled` keeps it
+ * announced. Rarer here than on `ButtonLink` — a dead link in a
+ * sentence is usually better written as plain text.
+ */
+export const TextLink = ({
+  appearance = "inline",
+  children,
+  className,
+  href,
+  iconEnd,
+  iconStart,
+  intent = "accent",
+  isDisabled = false,
+  isExternal = false,
+  newTabLabel = "(opens in a new tab)",
+  ...anchorProps
+}: TextLinkProps): ReactNode => {
+  const RouterLink = useRouterLink()
+
+  // An external destination or a fragment is never the router's, and
+  // a disabled one goes nowhere at all — each falls back to the plain
+  // anchor below rather than through the injected component.
+  const LinkElement =
+    isExternal || !getIsRoutedHref(href) ? "a" : RouterLink
+
+  const linkClassName = toClassName(
+    TEXT_LINK_BASE_CLASS,
+    TEXT_LINK_APPEARANCE_CLASS[appearance],
+    INTENT_CONTENT_CLASS[intent],
+    FOCUS_RING_CLASS,
+    TEXT_LINK_ARIA_DISABLED_CLASS,
+    className,
+  )
+
+  const content = (
+    <>
+      {iconStart}
+
+      {children}
+
+      {iconEnd}
+
+      {isExternal ? (
+        <VisuallyHidden>{newTabLabel}</VisuallyHidden>
+      ) : null}
+    </>
+  )
+
+  if (isDisabled) {
+    return (
+      <a
+        {...anchorProps}
+        aria-disabled="true"
+        className={linkClassName}
+        role="link"
+      >
+        {content}
+      </a>
+    )
+  }
+
+  return (
+    <LinkElement
+      {...anchorProps}
+      className={linkClassName}
+      href={href}
+      // `noreferrer` alongside `noopener` on purpose: `noopener`
+      // closes the `window.opener` hole, and `noreferrer` is what
+      // keeps a private app's URL out of the destination's logs.
+      rel={isExternal ? "noopener noreferrer" : undefined}
+      target={isExternal ? "_blank" : undefined}
+    >
+      {content}
+    </LinkElement>
+  )
+}