@charcuterie/ui 3.9.0 → 3.10.0

package/src/Badge/useBadgeShape.tsx

@@ -0,0 +1,142 @@
+import type {
+  CategoricalIndex,
+  IntentName,
+} from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+
+import { CATEGORICAL_APPEARANCE_CLASS } from "../categoricalStyles.ts"
+import type { BadgeSize } from "../controlStyles.ts"
+import { BADGE_SIZE_CLASS } from "../controlStyles.ts"
+import type { IntentAppearance } from "../intentStyles.ts"
+import { INTENT_APPEARANCE_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import { useIsTextClipped } from "./useIsTextClipped.ts"
+
+/**
+ * The visual half of a badge, shared by the two elements that wear
+ * it.
+ *
+ * `Badge` is a `<span>` and `BadgeButton` is a `<button>`, and the
+ * pill is supposed to be indistinguishable between them — so the
+ * class list, the icon slot, the truncation and the
+ * only-when-clipped `title` are computed **here**, once, exactly as
+ * `Button` and `ButtonLink` both call `getControlClassName`. A
+ * second copy of this arithmetic is how the two drift: the wrapping
+ * pill's `rounded-2xl` and the label's `min-w-0` are each one line,
+ * and each is load-bearing.
+ */
+export type BadgeShapeProps = {
+  appearance?: Exclude<IntentAppearance, "ghost">
+  /**
+   * A numbered, **non-semantic** colour: 1–10, no meaning attached.
+   *
+   * For a badge whose colour the user picked — a Docket label, a
+   * project, a chart series — where `intent` would be a lie.
+   * `getCategoricalIndex(key)` from `@charcuterie/tokens` is the
+   * stable fallback for a row nobody has chosen a colour for yet.
+   *
+   * Mutually exclusive with `intent` **in the type**: a badge is one
+   * colour, and passing both is a question with no answer rather
+   * than a precedence rule to remember.
+   */
+  categorical?: CategoricalIndex
+  children: ReactNode
+  icon?: ReactNode
+  intent?: IntentName
+  /**
+   * What happens when the label is wider than the space it is given.
+   *
+   *  - `truncate` — one line, capped at the container, ellipsis. The
+   *    default, because a status pill that changes its row's height
+   *    when a message gets longer breaks the table it sits in.
+   *  - `wrap` — the pill grows taller and shows everything. For the
+   *    kiosk and any touch context, where the hover readout that
+   *    `truncate` relies on does not exist.
+   */
+  overflow?: "truncate" | "wrap"
+  size?: BadgeSize
+}
+
+export const useBadgeShape = ({
+  appearance = "soft",
+  categorical,
+  children,
+  className,
+  icon,
+  intent = "neutral",
+  overflow = "truncate",
+  size = "md",
+  title,
+}: BadgeShapeProps & {
+  className?: string
+  title?: string
+}): {
+  className: string
+  content: ReactNode
+  title?: string
+} => {
+  const [labelRef, clippedText] = useIsTextClipped()
+
+  return {
+    className: toClassName(
+      "inline-flex shrink-0 items-center border font-medium",
+      // The cap. Without it every other rule here is decoration.
+      "max-w-full",
+      overflow === "wrap"
+        ? // A stadium end-cap on a three-line box reads as a
+          // rendering fault rather than a badge, so the wrapping
+          // pill relaxes to a rounded rectangle.
+          "rounded-2xl"
+        : "rounded-full",
+      BADGE_SIZE_CLASS[size],
+      // A ternary rather than a merged map: the two are indexed
+      // by different keys, and `undefined` is the only honest
+      // discriminant once the type has already refused the case
+      // where both arrive.
+      categorical === undefined
+        ? INTENT_APPEARANCE_CLASS[intent][appearance]
+        : CATEGORICAL_APPEARANCE_CLASS[categorical][
+            appearance
+          ],
+      className,
+    ),
+    content: (
+      <>
+        {icon ? (
+          <span
+            aria-hidden="true"
+            className="contents shrink-0"
+          >
+            {icon}
+          </span>
+        ) : null}
+
+        {/*
+         * The truncation happens here rather than on the pill so the
+         * border and the rounded end-cap stay outside the clip — an
+         * `overflow: hidden` on the pill itself squares off the end
+         * the ellipsis is nearest to.
+         *
+         * `min-w-0` because a flex item's automatic minimum size is
+         * its content, which would win against `max-w-full` on the
+         * parent and put the overflow back.
+         */}
+        <span
+          className={
+            overflow === "wrap"
+              ? "min-w-0"
+              : "min-w-0 overflow-hidden text-ellipsis whitespace-nowrap"
+          }
+          ref={labelRef}
+        >
+          {children}
+        </span>
+      </>
+    ),
+    // Only when something is actually hidden. A tooltip on every
+    // short pill in a bay list is noise, and a `title` that
+    // duplicates fully-visible text is a screen-reader duplicate
+    // for no gain.
+    title: title ?? clippedText,
+  }
+}

package/src/BadgeButton/BadgeButton.mdx

@@ -0,0 +1,67 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as BadgeButtonStories from "./BadgeButton.stories";
+
+<Meta of={BadgeButtonStories} />
+
+# BadgeButton
+
+**A badge you can press.** It takes `Badge`'s visual props and paints identically to it —
+and it is a real `<button>`.
+
+QueuePilot is where this came from. Its poster tiles carry per-entry settings as *tags*: a
+default entry says nothing, and every tag you do see is a deviation worth reading. Each one
+opens the panel that changes it, so each one is pressable — and all six were spelled
+`<button className="badge tagbtn …">`, a hand-painted pill in app CSS, because the library
+had no way to make `Badge` pressable. The same shape turns up on a start-point chip, a
+group chip and a pool's Exclude chip.
+
+<Canvas of={BadgeButtonStories.Default} />
+
+## Props
+
+<Controls />
+
+## It is the same pill, not a copy of it
+
+`Badge` and `BadgeButton` both build their pill through `useBadgeShape`, so the class list,
+the icon slot, the truncation and the only-when-clipped `title` are read once rather than
+duplicated. `BadgeButton.test.tsx` then compares the two elements' **computed** styles in
+the real browser, which is the version of that claim a refactor cannot quietly break.
+
+<Canvas of={BadgeButtonStories.BesideABadge} />
+
+<Canvas of={BadgeButtonStories.AllVariants} />
+
+## What the element buys, and none of it is paint
+
+Focus, the tab order, Enter **and** Space, `:disabled`, form participation, and a `button`
+role a screen reader announces as pressable. A `<span onClick>` has none of them, and
+`getByRole("button", { name })` — what every test and every agent driving the app matches
+on — finds nothing at all.
+
+<Canvas of={BadgeButtonStories.AllStates} />
+
+## Why not `asChild`, and why not `Badge` growing an `onClick`
+
+This library has no polymorphism pattern and has not needed one. Adding `asChild` here would
+make every future component answer "can it be something else?" instead of "what is it?",
+and the precedent already exists in the other direction: `ButtonLink` is a sibling of
+`Button` for exactly this reason.
+
+An element type that changes as a **side effect** of passing a handler is worse. Forget the
+handler and the control silently ships as a `<span>` — not focusable, not in the tab order,
+invisible to `getByRole`, with no error anywhere. `onClick` is required here instead, so a
+pill nobody can press is a `Badge` by construction.
+
+## Two defaults worth knowing
+
+**`type="button"`.** These chips sit inside forms — QueuePilot's entry sheet is one — and
+the platform's default of `submit` would make a "change the start point" chip save the whole
+dialog. It is overridable, because a badge-shaped submit is a real thing.
+
+**`ghost` is excluded**, inherited from `Badge`: a pill that paints nothing until hovered
+has no pill left, and a control that only advertises itself on hover cannot be found by
+touch.
+
+<Canvas of={BadgeButtonStories.InATileFooter} />

package/src/BadgeButton/BadgeButton.stories.tsx

@@ -0,0 +1,199 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import {
+  categoricalArgType,
+  intentArgType,
+} from "../argTypes.storyHelpers.ts"
+import { Badge } from "../Badge/Badge.tsx"
+import {
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { DotIcon } from "../icons.storyHelpers.tsx"
+import { BadgeButton } from "./BadgeButton.tsx"
+
+const INTENTS = [
+  "neutral",
+  "accent",
+  "success",
+  "warning",
+  "danger",
+  "info",
+] as const
+
+const meta = {
+  title: "Components/Actions/BadgeButton",
+  component: BadgeButton,
+  parameters: { layout: "padded" },
+  argTypes: {
+    categorical: categoricalArgType,
+    intent: intentArgType,
+  },
+  // The component's own defaults, restated — Storybook does not
+  // seed `args` from docgen, so an unstated default shows in the
+  // props table with nothing selected in its control.
+  args: {
+    appearance: "soft",
+    intent: "neutral",
+    isDisabled: false,
+    onClick: () => {},
+    overflow: "truncate",
+    size: "md",
+  },
+} satisfies Meta<typeof BadgeButton>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * A pill with a `button` role, so `getByRole("button", { name })`
+ * finds it — which is what an agent, and every test in the fleet,
+ * actually matches on.
+ */
+export const Default: Story = {
+  args: { children: "1 episode", intent: "accent" },
+}
+
+/**
+ * The claim this component exists to make, side by side: a
+ * `BadgeButton` and a `Badge` with identical visual props are the
+ * same pill, and one of them is a real `<button>`.
+ *
+ * `BadgeButton.test.tsx` compares their computed styles rather than
+ * trusting this board — but the board is where a human sees it.
+ */
+export const BesideABadge: Story = {
+  args: { children: "1 episode" },
+  render: ({ categorical, ...badgeButtonProps }) => (
+    <StorySection title="Same pill, different element. Tab reaches the left one and Enter fires it; the right one is a word about something else.">
+      <StoryRow>
+        <StoryCell label="BadgeButton — a <button>">
+          <BadgeButton {...badgeButtonProps} />
+        </StoryCell>
+
+        <StoryCell label="Badge — a <span>">
+          <Badge
+            appearance={badgeButtonProps.appearance}
+            intent={badgeButtonProps.intent}
+            size={badgeButtonProps.size}
+          >
+            1 episode
+          </Badge>
+        </StoryCell>
+      </StoryRow>
+    </StorySection>
+  ),
+}
+
+export const AllVariants: Story = {
+  args: { children: "1 episode" },
+  // `categorical` is destructured out rather than spread: this board
+  // is about intents, and the type refuses a pill holding both — a
+  // badge is one colour.
+  render: ({ categorical, ...badgeButtonProps }) => (
+    <StorySection title="Six intents x three appearances — the same maps Badge indexes, because they are the same maps. `ghost` is excluded: a pill that paints nothing until hovered has no pill left.">
+      <StoryGrid columns={6}>
+        {(["soft", "solid", "outline"] as const).flatMap(
+          (appearance) =>
+            INTENTS.map((intent) => (
+              <StoryCell
+                key={`${appearance}-${intent}`}
+                label={`${appearance} · ${intent}`}
+              >
+                <BadgeButton
+                  {...badgeButtonProps}
+                  appearance={appearance}
+                  intent={intent}
+                >
+                  {intent}
+                </BadgeButton>
+              </StoryCell>
+            )),
+        )}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * The states a `Badge` does not have, which is the whole reason not
+ * to solve this with a `className`.
+ */
+export const AllStates: Story = {
+  args: { children: "1 episode" },
+  render: ({ categorical, ...badgeButtonProps }) => (
+    <StorySection title="Hover, focus and disabled — hover one, Tab to one, and read the third.">
+      <StoryGrid columns={2}>
+        <StoryCell label="sm">
+          <BadgeButton {...badgeButtonProps} size="sm" />
+        </StoryCell>
+
+        <StoryCell label="md">
+          <BadgeButton {...badgeButtonProps} size="md" />
+        </StoryCell>
+
+        <StoryCell label="with a glyph">
+          <BadgeButton
+            {...badgeButtonProps}
+            icon={<DotIcon />}
+            intent="success"
+          >
+            verified
+          </BadgeButton>
+        </StoryCell>
+
+        <StoryCell label="disabled">
+          <BadgeButton {...badgeButtonProps} isDisabled>
+            1 episode
+          </BadgeButton>
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * Where it came from: QueuePilot's poster tile, whose per-entry
+ * settings are TAGS. A default entry says nothing and every tag you
+ * do see is a deviation worth reading — and each one opens the panel
+ * that changes it, which is why they are pressable.
+ */
+export const InATileFooter: Story = {
+  args: { children: "Edit" },
+  render: ({ categorical, ...badgeButtonProps }) => (
+    <StorySection title="A row of chips under a poster: three settings and the editor that changes them.">
+      <div className="flex max-w-64 flex-wrap items-center gap-1 rounded-md border border-border-subtle bg-surface-raised p-2">
+        <span className="w-full text-content-primary text-sm">
+          Blade Runner (1982)
+        </span>
+
+        <BadgeButton
+          {...badgeButtonProps}
+          intent="accent"
+          size="sm"
+        >
+          3 episodes
+        </BadgeButton>
+
+        <BadgeButton
+          {...badgeButtonProps}
+          intent="info"
+          size="sm"
+        >
+          2x weight
+        </BadgeButton>
+
+        <BadgeButton
+          {...badgeButtonProps}
+          appearance="outline"
+          size="sm"
+        >
+          Edit
+        </BadgeButton>
+      </div>
+    </StorySection>
+  ),
+}

package/src/BadgeButton/BadgeButton.test.tsx

@@ -0,0 +1,164 @@
+import {
+  composeStories,
+  composeStory,
+} from "@storybook/react"
+import { expect, fn, 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 "./BadgeButton.stories.tsx"
+
+const { BesideABadge, Default, InATileFooter } =
+  composeStories(stories)
+
+/**
+ * The properties a `<span onClick>` cannot have, and the reason this
+ * is a component rather than a `className` on `Badge`.
+ */
+test("is a button, not a span", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const chip = expectAgentDrivable(canvas, {
+    name: "1 episode",
+    role: "button",
+  })
+
+  await expect(chip.tagName).toBe("BUTTON")
+  // Never `submit`: these chips sit inside forms, and the platform's
+  // default would make "change the start point" save the dialog.
+  await expect(chip).toHaveAttribute("type", "button")
+})
+
+test("Tab reaches it and Enter fires it", async () => {
+  const onClick = fn()
+
+  const { canvas } = await mountStory(
+    composeStory(
+      { args: { children: "1 episode", onClick } },
+      meta,
+    ),
+  )
+
+  const chip = canvas.getByRole("button", {
+    name: "1 episode",
+  })
+
+  await userEvent.tab()
+  await expect(chip).toHaveFocus()
+
+  await userEvent.keyboard("{Enter}")
+  await expect(onClick).toHaveBeenCalledTimes(1)
+
+  // Space too — the second half of what the platform gives a
+  // `<button>` and gives a pressable `<span>` never.
+  await userEvent.keyboard(" ")
+  await expect(onClick).toHaveBeenCalledTimes(2)
+})
+
+/**
+ * The claim the component is named for, measured.
+ *
+ * `Badge` and `BadgeButton` both assemble their pill through
+ * `useBadgeShape`, so there is one source — but a shared hook 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.
+ *
+ * `cursor` is deliberately NOT in this list: the pressable one is a
+ * pointer and the static one is not, which is the difference being
+ * asserted elsewhere rather than a drift to catch here.
+ */
+const PAINTED_PROPERTIES = [
+  "background-color",
+  "border-color",
+  "border-radius",
+  "border-width",
+  "color",
+  "display",
+  "font-size",
+  "font-weight",
+  "padding-block-end",
+  "padding-block-start",
+  "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 Badge with the same props", async () => {
+  const { canvas } = await mountStory(BesideABadge)
+
+  const chip = canvas.getByRole("button", {
+    name: "1 episode",
+  })
+
+  // The `Badge` has no role by design, so it is found by its text —
+  // which is the handle its own story asserts on.
+  const badge = canvas.getByText("1 episode", {
+    selector: "span span",
+  })
+
+  await expect(getPaint(chip)).toEqual(
+    getPaint(badge.parentElement as Element),
+  )
+})
+
+test("disabled is the native attribute, and it stops the click", async () => {
+  const onClick = fn()
+
+  const { canvas } = await mountStory(
+    composeStory(
+      {
+        args: {
+          children: "1 episode",
+          isDisabled: true,
+          onClick,
+        },
+      },
+      meta,
+    ),
+  )
+
+  const chip = canvas.getByRole("button", {
+    name: "1 episode",
+  })
+
+  // The NATIVE attribute, not `aria-disabled`: an inert `<button>`
+  // is out of the tab order and ignores a click by the platform's
+  // own rules, which is what a pill wearing `aria-disabled` and a
+  // live handler never gets.
+  await expect(chip).toBeDisabled()
+
+  await userEvent.click(chip, { pointerEventsCheck: 0 })
+
+  await expect(onClick).not.toHaveBeenCalled()
+})
+
+test("a row of chips is drivable and clean", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(InATileFooter)
+
+  for (const name of ["3 episodes", "2x weight", "Edit"]) {
+    expectAgentDrivable(canvas, { name, role: "button" })
+  }
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the story meta names the component", async () => {
+  await expect(meta.title).toBe(
+    "Components/Actions/BadgeButton",
+  )
+})

package/src/BadgeButton/BadgeButton.tsx

@@ -0,0 +1,129 @@
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import type { BadgeShapeProps } from "../Badge/useBadgeShape.tsx"
+import { useBadgeShape } from "../Badge/useBadgeShape.tsx"
+import { CATEGORICAL_HOVER_CLASS } from "../categoricalStyles.ts"
+import {
+  DISABLED_CLASS,
+  FOCUS_RING_CLASS,
+  INTENT_HOVER_CLASS,
+} from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+
+export type BadgeButtonProps = Omit<
+  ComponentPropsWithRef<"button">,
+  "disabled"
+> &
+  BadgeShapeProps & {
+    /**
+     * Required, and that is the component's argument in one line: a
+     * pill nobody can press is a `Badge`, and a pill that looks
+     * pressable and is not is the defect this exists to stop.
+     */
+    onClick: NonNullable<
+      ComponentPropsWithRef<"button">["onClick"]
+    >
+    /**
+     * `isDisabled`, not `disabled` — the same prop `Button` keeps
+     * instead of the native one, so a control's disabled state is
+     * spelled one way across the library.
+     */
+    isDisabled?: boolean
+    /**
+     * See `BadgeShapeProps`. Restated only to refuse the case where
+     * both colours arrive.
+     */
+  } & ({ categorical?: never } | { intent?: never })
+
+/**
+ * A badge you can press.
+ *
+ * A sibling component rather than a prop, exactly as `ButtonLink` is
+ * to `Button`: the paint is shared (both call `useBadgeShape`, so
+ * there is one class list and `BadgeButton.test.tsx` compares the
+ * two elements' *computed* styles rather than trusting that), and
+ * what differs is the element and everything the platform hangs off
+ * it.
+ *
+ * **Why not `asChild`, and why not `Badge` growing an `onClick`.**
+ * This library has no polymorphism pattern and has not needed one;
+ * adding it here would mean every future component answering "can it
+ * be something else?" instead of "what is it?". And an element type
+ * that changes as a *side effect* of passing a handler is a footgun
+ * with no error: forget the handler and a control silently ships as
+ * a `<span>` — not focusable, not in the tab order, invisible to
+ * `getByRole("button")` and to every agent driving the app.
+ *
+ * **What the element buys, and none of it is paint.** Focus, the tab
+ * order, Enter and Space, `:disabled`, form participation, and a
+ * `button` role a screen reader announces as pressable. QueuePilot
+ * had six pills doing all of this with a hand-rolled
+ * `<button className="badge …">`, which is where this came from —
+ * six chips that open an editor, change a start point, or drop a
+ * title from a pool.
+ *
+ * **`type="button"` by default.** These chips sit inside forms —
+ * QueuePilot's entry sheet is one — and the platform's default of
+ * `submit` would make a "change the start point" chip save the whole
+ * dialog. Overridable, because a badge-shaped submit is a real thing
+ * and the default is a safe floor rather than a ban.
+ *
+ * **`ghost` is still excluded**, inherited from `Badge`: a pill that
+ * paints nothing until hovered has no pill left, and a control that
+ * only advertises itself on hover cannot be found by touch.
+ */
+export const BadgeButton = ({
+  appearance = "soft",
+  categorical,
+  children,
+  className,
+  icon,
+  intent = "neutral",
+  isDisabled = false,
+  overflow,
+  size,
+  title,
+  type = "button",
+  ...buttonProps
+}: BadgeButtonProps): ReactNode => {
+  const shape = useBadgeShape({
+    appearance,
+    categorical,
+    children,
+    icon,
+    intent,
+    overflow,
+    size,
+    title,
+  })
+
+  return (
+    <button
+      {...buttonProps}
+      className={toClassName(
+        shape.className,
+        "cursor-pointer",
+        // The three states the `<span>` has no business carrying,
+        // keyed the same way the appearance above was.
+        categorical === undefined
+          ? INTENT_HOVER_CLASS[intent][appearance]
+          : CATEGORICAL_HOVER_CLASS[categorical][
+              appearance
+            ],
+        FOCUS_RING_CLASS,
+        DISABLED_CLASS,
+        // Last, so a caller's layout beats the defaults above — the
+        // same order `getControlClassName` uses.
+        className,
+      )}
+      disabled={isDisabled}
+      title={shape.title}
+      type={type}
+    >
+      {shape.content}
+    </button>
+  )
+}