@charcuterie/ui 0.1.0

package/src/Badge/Badge.stories.tsx

@@ -0,0 +1,229 @@
+import {
+  asyncTransitions,
+  useStatus,
+} from "@charcuterie/logic"
+import type { Meta, StoryObj } from "@storybook/react"
+import { intentArgType } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { DotIcon } from "../icons.storyHelpers.tsx"
+import {
+  getAsyncIntent,
+  getAsyncLabel,
+} from "../statusIntent.ts"
+import { Badge } from "./Badge.tsx"
+
+const INTENTS = [
+  "neutral",
+  "accent",
+  "success",
+  "warning",
+  "danger",
+  "info",
+] as const
+
+const meta = {
+  title: "Components/Badge",
+  component: Badge,
+  parameters: { layout: "padded" },
+  argTypes: { 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",
+    overflow: "truncate",
+    size: "md",
+  },
+} satisfies Meta<typeof Badge>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * A badge has no role by design — it is a word about something
+ * else, not a live region — so the handle an agent reads off the row
+ * is its text.
+ */
+export const Default: Story = {
+  args: { children: "running", intent: "info" },
+}
+
+export const AllVariants: Story = {
+  args: { children: "running" },
+  render: (badgeProps) => (
+    <StorySection title="Six intents x three appearances. rip-deck declares this map twice, in two files, with hardcoded hexes.">
+      <StoryGrid columns={6}>
+        {(["soft", "solid", "outline"] as const).flatMap(
+          (appearance) =>
+            INTENTS.map((intent) => (
+              <StoryCell
+                key={`${appearance}-${intent}`}
+                label={`${appearance} · ${intent}`}
+              >
+                <Badge
+                  {...badgeProps}
+                  appearance={appearance}
+                  intent={intent}
+                >
+                  {intent}
+                </Badge>
+              </StoryCell>
+            )),
+        )}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const AllStates: Story = {
+  args: { children: "running" },
+  render: (badgeProps) => (
+    <StorySection title="A badge is static — no hover, no focus, no disabled. What varies is size, an optional glyph, and how it sits in a real row.">
+      <StoryGrid columns={2}>
+        <StoryCell label="sm">
+          <Badge {...badgeProps} size="sm" />
+        </StoryCell>
+
+        <StoryCell label="md">
+          <Badge {...badgeProps} size="md" />
+        </StoryCell>
+
+        <StoryCell label="with a glyph">
+          <Badge
+            {...badgeProps}
+            icon={<DotIcon />}
+            intent="success"
+          >
+            verified
+          </Badge>
+        </StoryCell>
+
+        <StoryCell label="in a job row">
+          <div className="flex items-center gap-2 rounded-md border border-border-subtle bg-surface-raised p-2">
+            <span className="text-content-primary text-sm">
+              Blade Runner (1982)
+            </span>
+
+            <Badge intent="success" size="sm">
+              completed
+            </Badge>
+          </div>
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * A label longer than the space it is given, which is the case that
+ * shipped broken: `shrink-0` plus `whitespace-nowrap` and no cap let
+ * the pill paint straight across the next column.
+ *
+ * `truncate` keeps the row height fixed and paints an ellipsis —
+ * and because that ellipsis is painted rather than inserted, a
+ * triple-click still selects the whole string and a screen reader
+ * still reads it. Hovering a clipped pill shows the rest.
+ *
+ * `wrap` is the answer where hover does not exist. The kiosk is a
+ * touch context, so a pill whose full text matters wraps there
+ * rather than hiding half of itself behind an affordance nobody can
+ * reach.
+ */
+export const Responsive: Story = {
+  args: {
+    children: "quarantined — checksum mismatch on title 4",
+    intent: "warning",
+  },
+  render: (badgeProps) => (
+    <div className="flex flex-col gap-8">
+      <StorySection title="overflow: truncate (default) — one line, capped, hover for the rest">
+        <ContainerBoard>
+          <Badge {...badgeProps} />
+        </ContainerBoard>
+      </StorySection>
+
+      <StorySection title="overflow: wrap — the pill grows instead">
+        <ContainerBoard>
+          <Badge {...badgeProps} overflow="wrap" />
+        </ContainerBoard>
+      </StorySection>
+    </div>
+  ),
+}
+
+const AsyncStatusBadge = () => {
+  const { reset, status, transitionTo } = useStatus({
+    initialState: "idle",
+    transitions: asyncTransitions,
+  })
+
+  return (
+    <StoryRow>
+      <Badge intent={getAsyncIntent(status)}>
+        {getAsyncLabel(status)}
+      </Badge>
+
+      <Button
+        appearance="soft"
+        onClick={() => {
+          transitionTo("loading")
+        }}
+        size="sm"
+      >
+        Start
+      </Button>
+
+      <Button
+        appearance="soft"
+        intent="success"
+        onClick={() => {
+          transitionTo("success")
+        }}
+        size="sm"
+      >
+        Succeed
+      </Button>
+
+      <Button
+        appearance="soft"
+        intent="danger"
+        onClick={() => {
+          transitionTo("error")
+        }}
+        size="sm"
+      >
+        Fail
+      </Button>
+
+      <Button appearance="ghost" onClick={reset} size="sm">
+        Reset
+      </Button>
+    </StoryRow>
+  )
+}
+
+/**
+ * The M2 join, live: one `asyncTransitions` machine, one
+ * `getAsyncIntent`, and a badge that cannot render a state the
+ * machine does not have.
+ *
+ * Press *Succeed* before *Start* and the badge does not move:
+ * `idle → success` is not a legal edge, so the core throws (loudly,
+ * in the console) rather than painting a green pill over a job that
+ * never ran. That is the difference between this and mux-magic's
+ * `Record<string, string>`, which renders whatever string it is
+ * handed and colours an unknown one as nothing at all.
+ */
+export const Interactive: Story = {
+  args: { children: "running" },
+  render: () => <AsyncStatusBadge />,
+}

package/src/Badge/Badge.test.tsx

@@ -0,0 +1,153 @@
+import {
+  composeStories,
+  composeStory,
+} from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import meta, * as stories from "./Badge.stories.tsx"
+
+const { Default, Interactive, Responsive } =
+  composeStories(stories)
+
+test("the text is queryable, which is what an agent matches on", async () => {
+  const { canvas } = await mountStory(Default)
+
+  // No role, deliberately — a badge is a word about something else,
+  // not a live region. So there is nothing to `getByRole` and the
+  // text is the whole contract.
+  await expect(canvas.getByText("running")).toBeVisible()
+})
+
+/**
+ * The M2 join, driven: one `asyncTransitions` machine, one
+ * `getAsyncIntent`, and a badge that cannot render a state the
+ * machine does not have.
+ */
+test("the badge follows the status machine through a full cycle", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  await expect(canvas.getByText("Idle")).toBeVisible()
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Start" }),
+  )
+
+  await expect(canvas.getByText("Loading…")).toBeVisible()
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Succeed" }),
+  )
+
+  await expect(canvas.getByText("Done")).toBeVisible()
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "Reset" }),
+  )
+
+  await expect(canvas.getByText("Idle")).toBeVisible()
+})
+
+const LONG_LABEL =
+  "quarantined — checksum mismatch on title 4"
+
+/**
+ * A container narrower than the label needs, which is the whole
+ * point. The width goes on the canvas rather than on the badge —
+ * constraining the badge itself would prove nothing about
+ * `max-inline-size: 100%`, which is the fix under test.
+ */
+const mountInPanel = async (
+  overflow: "truncate" | "wrap",
+) => {
+  const { canvasElement } = await mountStory(
+    composeStory(
+      { args: { children: LONG_LABEL, overflow } },
+      meta,
+    ),
+  )
+
+  canvasElement.style.inlineSize = "10rem"
+
+  return {
+    badge: canvasElement.firstElementChild as HTMLElement,
+    container: canvasElement,
+  }
+}
+
+test("a truncated badge never paints outside its container", async () => {
+  const { badge, container } =
+    await mountInPanel("truncate")
+
+  const label = badge.firstElementChild as HTMLElement
+
+  await waitFor(() => {
+    expect(
+      badge.getBoundingClientRect().width,
+    ).toBeLessThanOrEqual(
+      container.getBoundingClientRect().width,
+    )
+  })
+
+  // Clipped — so an ellipsis is being painted.
+  await expect(label.scrollWidth).toBeGreaterThan(
+    label.clientWidth,
+  )
+
+  // …and yet the whole string is still there. `text-overflow` paints
+  // the ellipsis, it does not insert one, so selection, copy, and
+  // every screen reader still get all of it. This is the assertion
+  // that would fail if anyone ever "fixed" truncation by slicing the
+  // string in JavaScript.
+  await expect(badge.textContent).toBe(LONG_LABEL)
+
+  // And the visual half of the readout, for the pointer users who
+  // cannot select it to find out.
+  await waitFor(() => {
+    expect(badge).toHaveAttribute("title", LONG_LABEL)
+  })
+})
+
+test("a short badge gets no tooltip", async () => {
+  const { canvasElement } = await mountStory(Default)
+
+  // The measurement has to be able to say *no*, or `title` is just
+  // unconditional and every pill in a bay list grows a tooltip.
+  await waitFor(() => {
+    expect(
+      canvasElement.querySelector("[title]"),
+    ).toBeNull()
+  })
+})
+
+test("a wrapping badge grows taller rather than wider", async () => {
+  const truncated = await mountInPanel("truncate")
+
+  const truncatedHeight = truncated.badge.clientHeight
+
+  const wrapped = await mountInPanel("wrap")
+
+  await expect(wrapped.badge.clientHeight).toBeGreaterThan(
+    truncatedHeight,
+  )
+
+  await expect(
+    wrapped.badge.getBoundingClientRect().width,
+  ).toBeLessThanOrEqual(
+    wrapped.container.getBoundingClientRect().width,
+  )
+
+  // Nothing is hidden in this mode, so nothing needs a tooltip.
+  await waitFor(() => {
+    expect(wrapped.badge).not.toHaveAttribute("title")
+  })
+})
+
+test("the responsive board shows both modes at three widths", async () => {
+  const { canvas } = await mountStory(Responsive)
+
+  await expect(
+    canvas.getAllByText(LONG_LABEL),
+  ).toHaveLength(6)
+})

package/src/Badge/Badge.tsx

@@ -0,0 +1,130 @@
+import type { IntentName } from "@charcuterie/tokens"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+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"
+
+export type BadgeProps = ComponentPropsWithRef<"span"> & {
+  appearance?: Exclude<IntentAppearance, "ghost">
+  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
+}
+
+/**
+ * Four repos, and rip-deck declares the **identical** `TONE_CLASS`
+ * map twice — `VerdictBadge.tsx` and `TowerAlerts.tsx`, same five
+ * hardcoded hexes, no relationship to each other beyond
+ * copy-paste. mux-magic's `statusClassMap` is the same idea spelled
+ * a third way, keyed by a bare `string` so an unrecognised status
+ * renders with no colour at all and no error.
+ *
+ * `intent` replaces all of it. The **status** half of the problem —
+ * which state maps to which intent, and what it is called in
+ * English — lives in `statusIntent.ts` as exhaustive switches over
+ * `@charcuterie/logic`'s shared machines, so
+ * `<Badge intent={getAsyncIntent(status)}>{getAsyncLabel(status)}</Badge>`
+ * is the whole of mux-magic's `StatusBadge`, and adding a state to
+ * the machine is a compile error rather than a blank pill.
+ *
+ * **No implicit role.** A badge is a word about something else; it
+ * is not a live region, and giving it `role="status"` would make
+ * every re-render announce itself. Where a status genuinely needs
+ * announcing that is `LiveStatusIndicator`'s job, and where a badge
+ * needs a name beyond its text, `aria-label` still works. The story
+ * asserts the text is queryable, which is what an agent actually
+ * matches on.
+ *
+ * **It is capped at its container.** `shrink-0` and
+ * `whitespace-nowrap` alone let a long label paint straight through
+ * the neighbouring column — no clipping, no error, just a pill lying
+ * across the next cell. `max-inline-size: 100%` is what stops it, and
+ * `overflow` is what happens next.
+ */
+export const Badge = ({
+  appearance = "soft",
+  children,
+  className,
+  icon,
+  intent = "neutral",
+  overflow = "truncate",
+  size = "md",
+  title,
+  ...spanProps
+}: BadgeProps): ReactNode => {
+  const [labelRef, clippedText] = useIsTextClipped()
+
+  return (
+    <span
+      {...spanProps}
+      className={toClassName(
+        "inline-flex shrink-0 items-center rounded-full 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],
+        INTENT_APPEARANCE_CLASS[intent][appearance],
+        className,
+      )}
+      // 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}
+    >
+      {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>
+    </span>
+  )
+}

package/src/Badge/useIsTextClipped.ts

@@ -0,0 +1,77 @@
+import type { RefObject } from "react"
+import { useEffect, useRef, useState } from "react"
+
+/**
+ * The element's full text, but only while that text is wider than
+ * the box it was given — i.e. only while an ellipsis is being
+ * painted. `undefined` the rest of the time.
+ *
+ * `text-overflow: ellipsis` leaves no trace in the DOM: the glyph is
+ * painted by the layout engine and the whole string stays in
+ * `textContent`. That is the good news — selection, copy, and every
+ * screen reader still get all of it — and the reason this hook has
+ * to exist, because nothing in the DOM says "this one is cut off",
+ * so a hover affordance cannot be attached declaratively.
+ *
+ * Measured rather than assumed, since the alternative — always
+ * setting a `title` — puts a tooltip on every short status pill in a
+ * bay list, which is worse than the problem it solves.
+ *
+ * The text is returned rather than a boolean so the caller never
+ * reads `ref.current` during render.
+ */
+export const useIsTextClipped = (): [
+  RefObject<HTMLSpanElement | null>,
+  string | undefined,
+] => {
+  const elementRef = useRef<HTMLSpanElement>(null)
+
+  const [clippedText, setClippedText] = useState<
+    string | undefined
+  >(undefined)
+
+  // No dependency array: `children` is a `ReactNode`, so there is
+  // nothing stable to compare against, and a re-render is exactly
+  // when the text may have changed. `setState` bails out on an equal
+  // value, so the common case costs one `scrollWidth` read.
+  useEffect(() => {
+    const element = elementRef.current
+
+    if (!element) {
+      return
+    }
+
+    setClippedText(
+      element.scrollWidth > element.clientWidth
+        ? (element.textContent ?? undefined)
+        : undefined,
+    )
+  })
+
+  // And a resize of the *container* changes the answer without
+  // re-rendering anything — which is the container-query case this
+  // whole library is built around.
+  useEffect(() => {
+    const element = elementRef.current
+
+    if (!element) {
+      return
+    }
+
+    const observer = new ResizeObserver(() => {
+      setClippedText(
+        element.scrollWidth > element.clientWidth
+          ? (element.textContent ?? undefined)
+          : undefined,
+      )
+    })
+
+    observer.observe(element)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [])
+
+  return [elementRef, clippedText]
+}

package/src/Button/Button.mdx

@@ -0,0 +1,44 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ButtonStories from "./Button.stories";
+
+<Meta of={ButtonStories} />
+
+# Button
+
+Hand-rolled in **seven repos**, each with its own primary/secondary/danger/ghost pair and
+its own idea of what "disabled" looks like. This is the single largest duplication in the
+fleet.
+
+Six intents x four appearances x three sizes, all of it from tier-2 tokens — so a variant
+swap or a density flip repaints every button on the page with no prop change and no
+re-render.
+
+<Canvas of={ButtonStories.Default} />
+
+## Props
+
+<Controls />
+
+## What it fixes
+
+| Fleet behaviour today | Here |
+| --- | --- |
+| `<button>` with no `type`, submitting the form it happens to sit in | `type="button"` by default |
+| `outline-none` with nothing put back, or a ring on mouse click | `focus-visible` only, at the variant's own ring width |
+| A spinner that replaces the label, so you cannot tell what you pressed | Spinner replaces `iconStart`; the label stays, `aria-busy` goes on |
+| A `size="kiosk"` prop, or a second component for touch | `data-density="kiosk"` on `<html>` |
+
+## Accessibility contract
+
+- The accessible name is the children. A glyph is not a name — use `IconButton`, which
+  requires one.
+- `isLoading` disables the button and announces through the `Spinner`'s `role="status"`.
+- `isDisabled` renders a real `disabled` attribute: skipped by Tab, ignored by click, and
+  reported to assistive technology. The `DisabledDoesNotFire` story asserts all three.
+- Contrast on the disabled treatment leans on WCAG 1.4.3's exemption for *inactive*
+  controls, which is honest only on something actually disabled — see `DISABLED_CLASS`.
+
+<Canvas of={ButtonStories.AllVariants} />
+
+<Canvas of={ButtonStories.AllStates} />