@charcuterie/ui 2.7.0 → 2.9.0

package/src/ButtonLink/ButtonLink.stories.tsx

@@ -0,0 +1,281 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+
+import {
+  controlSizeArgType,
+  intentArgType,
+} from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import {
+  ArrowRightIcon,
+  ExternalIcon,
+} from "../icons.storyHelpers.tsx"
+import type { IntentAppearance } from "../intentStyles.ts"
+import { RouterLinkProvider } from "../RouterLink/RouterLinkProvider.tsx"
+import type { RouterLinkProps } from "../RouterLink/routerLink.ts"
+import { ButtonLink } from "./ButtonLink.tsx"
+
+/**
+ * A stand-in for react-router's `<Link>` — the marker attribute is
+ * how the board (and `ButtonLink.test.tsx`) shows which destinations
+ * the injected router was handed.
+ */
+const SoftRouterLink = ({
+  href,
+  ...linkProps
+}: RouterLinkProps): ReactNode => (
+  <a {...linkProps} data-router="soft" href={href} />
+)
+
+const INTENTS = [
+  "neutral",
+  "accent",
+  "success",
+  "warning",
+  "danger",
+  "info",
+] as const
+
+const APPEARANCES: IntentAppearance[] = [
+  "solid",
+  "soft",
+  "outline",
+  "ghost",
+]
+
+const meta = {
+  title: "Components/ButtonLink",
+  component: ButtonLink,
+  parameters: { layout: "padded" },
+  argTypes: {
+    intent: intentArgType,
+    size: controlSizeArgType,
+  },
+  // The component's own defaults, restated. Storybook has not
+  // seeded `args` from a docgen `defaultValue` since v7, so without
+  // this the props table prints `"solid"` in the Default column
+  // while the radio beside it has nothing selected.
+  args: {
+    appearance: "solid",
+    href: "/channels/settings",
+    intent: "accent",
+    isDisabled: false,
+    isExternal: false,
+    isFullWidth: false,
+    size: "md",
+  },
+} satisfies Meta<typeof ButtonLink>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { children: "Configure" },
+}
+
+/**
+ * The claim this component exists to make, side by side: a
+ * `ButtonLink` and a `Button` with identical visual props are the
+ * same pixels, and one of them is an `<a href>`.
+ *
+ * `ButtonLink.test.tsx` compares their computed styles rather than
+ * trusting this board — but the board is where a human sees it.
+ */
+export const BesideAButton: Story = {
+  args: { children: "Configure" },
+  render: (buttonLinkProps) => (
+    <StorySection title="Same paint, different element. Middle-click the left one and it opens a tab; middle-click the right one and nothing happens.">
+      <StoryRow>
+        <StoryCell label="ButtonLink — an <a href>">
+          <ButtonLink {...buttonLinkProps} />
+        </StoryCell>
+
+        <StoryCell label="Button — a <button>">
+          <Button
+            appearance={buttonLinkProps.appearance}
+            intent={buttonLinkProps.intent}
+            size={buttonLinkProps.size}
+          >
+            Configure
+          </Button>
+        </StoryCell>
+      </StoryRow>
+    </StorySection>
+  ),
+}
+
+export const AllVariants: Story = {
+  args: { children: "Configure" },
+  render: (buttonLinkProps) => (
+    <StorySection title="Six intents x four appearances — the same maps Button indexes, because they are the same maps.">
+      <StoryGrid columns={4}>
+        {APPEARANCES.flatMap((appearance) =>
+          INTENTS.map((intent) => (
+            <StoryCell
+              key={`${appearance}-${intent}`}
+              label={`${appearance} · ${intent}`}
+            >
+              <ButtonLink
+                {...buttonLinkProps}
+                appearance={appearance}
+                intent={intent}
+              >
+                {intent}
+              </ButtonLink>
+            </StoryCell>
+          )),
+        )}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const AllSizes: Story = {
+  args: { children: "Configure" },
+  render: (buttonLinkProps) => (
+    <StorySection title="Sizes come from the density axis — flip Density in the toolbar and every one of these changes with no prop change and no re-render.">
+      <StoryRow>
+        <ButtonLink {...buttonLinkProps} size="sm">
+          Small
+        </ButtonLink>
+
+        <ButtonLink {...buttonLinkProps} size="md">
+          Medium
+        </ButtonLink>
+
+        <ButtonLink {...buttonLinkProps} size="lg">
+          Large
+        </ButtonLink>
+      </StoryRow>
+    </StorySection>
+  ),
+}
+
+/**
+ * Hover, active, and focus are real here, not simulated: the
+ * pseudo-states addon forces them, which is the only way to review a
+ * hover colour in a static board.
+ *
+ * There is no `loading` cell, and that is the design: a navigation has
+ * no pending state this component owns.
+ */
+export const AllStates: Story = {
+  args: { children: "Configure" },
+  parameters: {
+    pseudo: {
+      active: ["#active"],
+      focusVisible: ["#focus-target"],
+      hover: ["#hover"],
+    },
+  },
+  render: (buttonLinkProps) => (
+    <StoryGrid columns={3}>
+      <StoryCell label="default">
+        <ButtonLink {...buttonLinkProps} />
+      </StoryCell>
+
+      <StoryCell label="hover (forced)">
+        <ButtonLink {...buttonLinkProps} id="hover" />
+      </StoryCell>
+
+      <StoryCell label="active (forced)">
+        <ButtonLink {...buttonLinkProps} id="active" />
+      </StoryCell>
+
+      <StoryCell label="focus-visible (forced)">
+        <ButtonLink
+          {...buttonLinkProps}
+          id="focus-target"
+        />
+      </StoryCell>
+
+      <StoryCell label="disabled">
+        <ButtonLink {...buttonLinkProps} isDisabled />
+      </StoryCell>
+
+      <StoryCell label="with an iconEnd">
+        <ButtonLink
+          {...buttonLinkProps}
+          iconEnd={<ArrowRightIcon />}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Plex Channels' actual control. It reads as the primary action on the
+ * card and it goes to another page, so it is an `<a>` — today it is a
+ * `<button onClick={() => navigate("#/settings")}>`, which cannot be
+ * middle-clicked, ctrl-clicked, opened in a new tab, or copied.
+ */
+export const ConfigureCard: Story = {
+  args: {
+    children: "Configure",
+    href: "/channels/settings",
+    iconEnd: <ArrowRightIcon />,
+  },
+}
+
+export const External: Story = {
+  args: {
+    children: "Open MakeMKV docs",
+    href: "https://makemkv.com/developers",
+    iconEnd: <ExternalIcon />,
+    isExternal: true,
+  },
+}
+
+/**
+ * The seam. An in-app path renders through the injected router
+ * component; an external URL falls back to a plain `<a>`, because a
+ * router pushing `https://…` onto its history stack lands the SPA on
+ * a route that does not exist.
+ */
+export const Routed: Story = {
+  args: { children: "Configure" },
+  decorators: [
+    (Story) => (
+      <RouterLinkProvider link={SoftRouterLink}>
+        <Story />
+      </RouterLinkProvider>
+    ),
+  ],
+  render: (buttonLinkProps) => (
+    <StoryRow>
+      <ButtonLink
+        {...buttonLinkProps}
+        href="/channels/settings"
+      >
+        Routed to /channels/settings
+      </ButtonLink>
+
+      <ButtonLink
+        {...buttonLinkProps}
+        appearance="outline"
+        href="https://makemkv.com/developers"
+        iconEnd={<ExternalIcon />}
+        isExternal
+      >
+        External to makemkv.com
+      </ButtonLink>
+    </StoryRow>
+  ),
+}
+
+export const Responsive: Story = {
+  args: { children: "Configure", isFullWidth: true },
+  render: (buttonLinkProps) => (
+    <ContainerBoard>
+      <ButtonLink {...buttonLinkProps} />
+    </ContainerBoard>
+  ),
+}

package/src/ButtonLink/ButtonLink.test.tsx

@@ -0,0 +1,203 @@
+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 "./ButtonLink.stories.tsx"
+
+const {
+  AllStates,
+  AllVariants,
+  BesideAButton,
+  Default,
+  External,
+  Routed,
+} = composeStories(stories)
+
+/**
+ * The properties a `<button onClick={navigate}>` cannot have, and the
+ * reason this component exists rather than a `Button` with an
+ * `onClick`.
+ *
+ * Nothing here clicks: a real anchor in a real browser navigates, and
+ * that it does is the browser's job — getting it for free is the
+ * whole argument.
+ */
+test("is a link, not a button", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const link = expectAgentDrivable(canvas, {
+    name: "Configure",
+    role: "link",
+  })
+
+  await expect(link.tagName).toBe("A")
+  await expect(link).toHaveAttribute(
+    "href",
+    "/channels/settings",
+  )
+
+  // Middle-click, ctrl-click, "open in new tab", "copy link address"
+  // and the status bar all come from *this* — an `href` on an `<a>` —
+  // and none of them can be added to a `<button>`.
+  await expect(
+    canvas.queryByRole("button", { name: "Configure" }),
+  ).toBeNull()
+})
+
+test("Tab reaches it", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const link = canvas.getByRole("link", {
+    name: "Configure",
+  })
+
+  await userEvent.tab()
+
+  await expect(link).toHaveFocus()
+})
+
+/**
+ * The claim the component is named for, measured.
+ *
+ * `Button` and `ButtonLink` both assemble their class list through
+ * `getControlClassName`, so there is one source — but a shared
+ * function still leaves room for a stray utility, a different base
+ * string, or a wrapper element that changes the box. Comparing
+ * **computed** styles is the version of "paints identically" that a
+ * refactor cannot quietly break, and it is measured in the same
+ * chromium the boards screenshot in.
+ */
+const PAINTED_PROPERTIES = [
+  "background-color",
+  "block-size",
+  "border-color",
+  "border-radius",
+  "border-width",
+  "color",
+  "display",
+  "font-size",
+  "font-weight",
+  "padding-inline-end",
+  "padding-inline-start",
+]
+
+const getPaint = (element: Element) => {
+  const computed = getComputedStyle(element)
+
+  return Object.fromEntries(
+    PAINTED_PROPERTIES.map((property) => [
+      property,
+      computed.getPropertyValue(property),
+    ]),
+  )
+}
+
+test("paints identically to a Button with the same props", async () => {
+  const { canvas } = await mountStory(BesideAButton)
+
+  const link = canvas.getByRole("link", {
+    name: "Configure",
+  })
+
+  const button = canvas.getByRole("button", {
+    name: "Configure",
+  })
+
+  await expect(getPaint(link)).toEqual(getPaint(button))
+})
+
+test("an external link opens safely and says so", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(External)
+
+  const link = expectAgentDrivable(canvas, {
+    name: /Open MakeMKV docs/,
+    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)
+})
+
+/**
+ * `href` is dropped rather than kept-and-ignored: an anchor with no
+ * `href` is out of the tab order and inert by the platform's own
+ * rules, and `aria-disabled` is what keeps it announced as a link
+ * that is currently unavailable.
+ */
+test("a disabled link has no href, is skipped by Tab, and still names itself", async () => {
+  const { canvas, canvasElement } = await mountStory(
+    composeStory(
+      { args: { children: "Configure", isDisabled: true } },
+      meta,
+    ),
+  )
+
+  const link = canvas.getByRole("link", {
+    name: "Configure",
+  })
+
+  await expect(link).not.toHaveAttribute("href")
+  await expect(link).toHaveAttribute(
+    "aria-disabled",
+    "true",
+  )
+
+  await userEvent.tab()
+
+  await expect(link).not.toHaveFocus()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * There is no `isLoading`, and the absence is the design: a
+ * navigation has no pending state this component owns.
+ */
+test("it has no loading state to get wrong", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  await expect(canvas.queryByRole("status")).toBeNull()
+
+  for (const link of canvas.getAllByRole("link", {
+    name: "Configure",
+  })) {
+    await expect(link).not.toHaveAttribute("aria-busy")
+  }
+})
+
+test("an injected router takes in-app paths and not external ones", async () => {
+  const { canvas } = await mountStory(Routed)
+
+  await expect(
+    canvas.getByRole("link", {
+      name: "Routed to /channels/settings",
+    }),
+  ).toHaveAttribute("data-router", "soft")
+
+  await expect(
+    canvas.getByRole("link", {
+      name: /External to makemkv\.com/,
+    }),
+  ).not.toHaveAttribute("data-router")
+})
+
+test("the full variant board is axe-clean", async () => {
+  const { canvasElement } = await mountStory(AllVariants)
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/ButtonLink/ButtonLink.tsx

@@ -0,0 +1,149 @@
+import type {
+  ControlSize,
+  IntentName,
+} from "@charcuterie/tokens"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { getControlClassName } from "../controlStyles.ts"
+import type { IntentAppearance } from "../intentStyles.ts"
+import { ARIA_DISABLED_CLASS } from "../intentStyles.ts"
+import { useRouterLink } from "../RouterLink/RouterLinkProvider.tsx"
+import { getIsRoutedHref } from "../RouterLink/routerLink.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+
+export type ButtonLinkProps = Omit<
+  ComponentPropsWithRef<"a">,
+  "href"
+> & {
+  appearance?: IntentAppearance
+  /**
+   * 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
+  iconStart?: ReactNode
+  intent?: IntentName
+  isDisabled?: boolean
+  isExternal?: boolean
+  isFullWidth?: boolean
+  /** What `isExternal` announces. Not shown. */
+  newTabLabel?: string
+  size?: ControlSize
+}
+
+/**
+ * A navigation that looks like a button.
+ *
+ * This is Plex Channels' "Configure ›": it reads as the primary
+ * action on the card, and it goes to another page — so it must be an
+ * `<a href>` (middle-click, ctrl-click, "open in new tab", "copy link
+ * address", and the status bar all come from the element, not from
+ * the paint) while looking exactly like `Button`. Today that control
+ * is a `<button onClick={() => navigate(…)}>`, which has none of
+ * them.
+ *
+ * **Exactly like `Button` is structural, not aspirational.** Both
+ * call `getControlClassName` with the same arguments, so there is one
+ * class list, and `ButtonLink.test.tsx` compares the two elements'
+ * *computed* styles rather than trusting that.
+ *
+ * Three things `Button` has that this deliberately does not:
+ *
+ *  - **`isLoading`.** A navigation has no pending state this
+ *    component owns. The wait belongs to the destination — a router's
+ *    transition, a `Suspense` boundary, a `ProgressBar` on the page
+ *    being entered — and a spinner here would be this component
+ *    lying about work it is not doing.
+ *  - **`type`.** There is no form to submit.
+ *  - **`sizing="icon"`.** An icon-only navigation is an `IconButton`
+ *    problem — a glyph is not an accessible name — and solving it
+ *    here would mean a second name-enforcing type.
+ *
+ * `isDisabled` drops `href` entirely rather than shipping a
+ * focusable `<a>` that silently ignores clicks: an anchor with no
+ * `href` is inert and out of the tab order by the platform's own
+ * rules, and the explicit `role="link"` + `aria-disabled` keeps it
+ * *announced* as a link that is currently unavailable rather than
+ * vanishing from the accessibility tree. Reach for it rarely — a
+ * destination that does not exist yet is usually better absent than
+ * present-but-dead.
+ */
+export const ButtonLink = ({
+  appearance = "solid",
+  children,
+  className,
+  href,
+  iconEnd,
+  iconStart,
+  intent = "accent",
+  isDisabled = false,
+  isExternal = false,
+  isFullWidth = false,
+  newTabLabel = "(opens in a new tab)",
+  size = "md",
+  ...anchorProps
+}: ButtonLinkProps): 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 controlClassName = getControlClassName({
+    appearance,
+    className,
+    disabledClass: ARIA_DISABLED_CLASS,
+    intent,
+    isFullWidth,
+    size,
+    sizing: "control",
+  })
+
+  const content = (
+    <>
+      {iconStart}
+
+      {children}
+
+      {iconEnd}
+
+      {isExternal ? (
+        <VisuallyHidden>{newTabLabel}</VisuallyHidden>
+      ) : null}
+    </>
+  )
+
+  if (isDisabled) {
+    return (
+      <a
+        {...anchorProps}
+        aria-disabled="true"
+        className={controlClassName}
+        role="link"
+      >
+        {content}
+      </a>
+    )
+  }
+
+  return (
+    <LinkElement
+      {...anchorProps}
+      className={controlClassName}
+      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>
+  )
+}

package/src/Combobox/Combobox.tsx

@@ -607,7 +607,10 @@ export const Combobox = ({
               style={floatingStyles}
             >
               {isAttached ? null : (
-                <div className="flex items-center gap-1 border-border-subtle border-b p-2">
+                // px-3 aligns the input's text start with the options
+                // below: each option sits at 0.75rem (listbox p-1 + option
+                // px-2), so the search row needs the same 0.75rem inset.
+                <div className="flex items-center gap-1 border-border-subtle border-b px-3 py-2">
                   <input
                     aria-activedescendant={
                       activeValue === undefined

package/src/Dialog/Dialog.tsx

@@ -99,7 +99,7 @@ export const Dialog = ({
       isVisible={isVisible}
       onClose={onClose}
     >
-      <header className="flex shrink-0 items-start justify-between gap-3 border-b border-border-subtle p-4">
+      <header className="flex shrink-0 items-center justify-between gap-3 border-b border-border-subtle p-4">
         <Heading
           className="font-semibold text-lg leading-tight"
           id={headingId}
@@ -119,7 +119,23 @@ export const Dialog = ({
         ) : null}
       </header>
 
-      <div className="min-h-0 flex-1 overflow-auto p-4">
+      {/*
+        `tabIndex={0}` is load-bearing, not decoration. This region
+        scrolls, and a scrollable region that cannot be focused cannot
+        be scrolled by anyone driving the keyboard — there is nothing
+        to put the caret in and no way to reach the overflow. axe
+        gates it as `scrollable-region-focusable` (serious).
+
+        It only surfaced once the body actually overflowed, which is
+        why it could land green: the rule fires on a region that is
+        scrollable *right now*, so a dialog whose content happened to
+        fit stayed silent.
+      */}
+      <div
+        className="min-h-0 flex-1 overflow-auto p-4"
+        // biome-ignore lint/a11y/noNoninteractiveTabindex: a scroll container must be focusable or a keyboard user can see the pane and cannot scroll it — axe's `scrollable-region-focusable`, which fails this component without the line. Same call, and the same wording, as `LogViewer`'s scroll pane. The rule is right about `<div>`s in general and wrong about scrollers.
+        tabIndex={0}
+      >
         {children}
       </div>
 

package/src/Field/Field.tsx

@@ -202,9 +202,17 @@ export const Field = ({
 
       {clonedControl}
 
+      {/*
+        Both of these are `text-sm`, not `text-xs`, since 2026-08-10.
+        A field description is the instruction for the input directly
+        above it, and an error is the one thing the user has to read
+        to get unstuck — neither survives being the smallest text on
+        the page. `aria-describedby` already ties them to the control;
+        the size is what decides whether a sighted user reads them.
+      */}
       {description === undefined ? null : (
         <p
-          className="text-content-secondary text-xs"
+          className="text-content-secondary text-sm"
           id={descriptionId}
         >
           {description}
@@ -213,7 +221,7 @@ export const Field = ({
 
       {error === undefined ? null : (
         <p
-          className="text-intent-danger-content text-xs"
+          className="text-intent-danger-content text-sm"
           id={errorId}
         >
           {error}