@charcuterie/ui 3.9.0 → 3.11.0

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>
+  )
+}

package/src/Card/Card.mdx

@@ -51,3 +51,24 @@ The header stacks below `--cq-sm` and sits on one row above it, and the containe
 cannot tell apart, and it is where the fleet's poster grids look wrong today.
 
 <Canvas of={CardStories.Responsive} />
+
+## The accent edge follows the corner
+
+`accentEdge` draws a coloured bar down the leading edge. `{ categorical: 3 }` is a colour a
+user picked, from the ten-wide contrast-audited family; `{ color }` is one the app computed,
+for the case where ten indices are not enough — Folio hashes a repo's name so a repo added
+tomorrow already has a hue and nobody maintains a palette.
+
+> **It is a pseudo-element, not a border, and that is the whole point.** Three apps grew this
+> shape independently and all three drew a straight border beside a rounded box, so the bar
+> ran past the curve and stopped square while the card was round. A border is painted on the
+> border box; it cannot follow a corner. The overlay here takes `border-radius: inherit`, so
+> the bar reads the radius off whatever card it is on and nobody states one twice.
+
+Two shapes this deliberately is not. **Not `box-shadow: inset` on the card itself** — `Card`
+carries `shadow-low` from the elevation scale, and a `box-shadow` at the call site outranks
+that utility and takes the elevation with it. **Not a 3px-wide pseudo-element with a rounded
+leading edge** — a `0.5rem` radius on a 3px box is clamped to fit, so it caps the bar instead
+of following the curve.
+
+<Canvas of={CardStories.AccentEdge} />

package/src/Card/Card.stories.tsx

@@ -13,12 +13,18 @@ import { IconButton } from "../IconButton/IconButton.tsx"
 import { SettingsIcon } from "../icons.storyHelpers.tsx"
 import { ProgressBar } from "../ProgressBar/ProgressBar.tsx"
 import { Card, ELEVATION_CLASS } from "./Card.tsx"
+import { ACCENT_EDGE_CATEGORICAL_CLASS } from "./cardAccentEdge.ts"
 
 const meta = {
   title: "Components/Layout/Card",
   component: Card,
   parameters: { layout: "padded" },
   argTypes: {
+    // An object union, so an object control is the right one — but
+    // it is stated rather than inferred, because docgen's fallback
+    // for a type it cannot read is also an object control and the
+    // two are indistinguishable in the panel.
+    accentEdge: { control: "object" },
     elevation: toStoryChoice(
       Object.keys(
         ELEVATION_CLASS,
@@ -205,3 +211,88 @@ export const Interactive: Story = {
     </div>
   ),
 }
+
+/**
+ * The leading edge, and the two answers the fleet has for what
+ * colour it is.
+ *
+ * A **categorical index** is a colour a user picked — Docket's
+ * project colours come from this ten-wide family, and every pair in
+ * it is contrast-audited. An explicit **colour** is one the app
+ * computed: Folio hashes a repo's name so a repo added tomorrow
+ * already has a hue and nobody maintains a palette, which is 360
+ * answers rather than ten.
+ *
+ * Both bars follow the card's own corner, because the treatment
+ * inherits its radius instead of naming one. Every app that grew
+ * this shape by hand drew it as a straight border beside a rounded
+ * box, and a border cannot follow a curve.
+ */
+export const AccentEdge: Story = {
+  args: { children: "Content" },
+  render: () => (
+    <StorySection title="A categorical index, and an app's own colour. Both take the card's radius.">
+      <StoryGrid columns={3}>
+        {(
+          Object.keys(
+            ACCENT_EDGE_CATEGORICAL_CLASS,
+          ) as unknown as (keyof typeof ACCENT_EDGE_CATEGORICAL_CLASS)[]
+        ).map((index) => (
+          <StoryCell
+            align="stretch"
+            key={index}
+            label={`categorical ${index}`}
+          >
+            <Card
+              accentEdge={{
+                categorical: Number(index) as 1,
+              }}
+              heading={`Project ${index}`}
+            >
+              <p className="text-content-secondary text-sm">
+                A colour the user picked.
+              </p>
+            </Card>
+          </StoryCell>
+        ))}
+
+        <StoryCell align="stretch" label="a hashed hue">
+          <Card
+            accentEdge={{ color: "hsl(287 55% 52%)" }}
+            heading="home-assistant"
+          >
+            <p className="text-content-secondary text-sm">
+              A hue hashed from the name, not an index.
+            </p>
+          </Card>
+        </StoryCell>
+
+        <StoryCell
+          align="stretch"
+          label="a rounder card, same rule"
+        >
+          <Card
+            accentEdge={{ color: "hsl(24 55% 52%)" }}
+            className="rounded-3xl"
+            heading="A wider radius"
+          >
+            <p className="text-content-secondary text-sm">
+              The bar reads the radius off the card rather
+              than naming one, so an override still lines
+              up.
+            </p>
+          </Card>
+        </StoryCell>
+
+        <StoryCell align="stretch" label="a link inside it">
+          <Card
+            accentEdge={{ categorical: 4 }}
+            heading="Still clickable"
+          >
+            <Button size="sm">Open</Button>
+          </Card>
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}