@charcuterie/ui 4.5.0 → 4.6.0

package/src/ActionTiles/ActionTiles.test.tsx

@@ -11,7 +11,7 @@ const {
   AllStates,
   AutoHues,
   BesideTheRadioTile,
-  Default,
+  Playground,
   Interactive,
   Links,
   NamedHues,
@@ -41,7 +41,7 @@ const getAccentEdgeLayer = (boxShadow: string) =>
 
 test("it is a named group of pressable tiles", async () => {
   const { canvas, canvasElement } =
-    await mountStory(Default)
+    await mountStory(Playground)
 
   const group = expectAgentDrivable(canvas, {
     name: "Queue type",
@@ -64,7 +64,7 @@ test("it is a named group of pressable tiles", async () => {
 })
 
 test("a tile's hint is part of its accessible name", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   // The reason the hint is rendered inside the tile rather than
   // beside it: a hint a screen reader never reads is a hint half the

package/src/AdaptiveGrid/AdaptiveGrid.mdx

@@ -14,7 +14,7 @@ That is the opposite of every wrapping grid in the fleet today. `auto-fill, minm
 takes every column the width allows, which is how you end up with seven items strung
 across an ultrawide and nothing below the fold.
 
-<Canvas of={AdaptiveGridStories.Default} />
+<Canvas of={AdaptiveGridStories.Playground} />
 
 ## Props
 

package/src/AdaptiveGrid/AdaptiveGrid.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 import { useState } from "react"
 
@@ -89,7 +90,8 @@ type Story = StoryObj<typeof meta>
  * carry nine — and the content cap widens from 56rem to 72rem to
  * hold them.
  */
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: { blockSizeResolver: fixedBlockSize(1080) },
 }
 

package/src/AdaptiveGrid/AdaptiveGrid.test.tsx

@@ -36,7 +36,7 @@ import * as stories from "./AdaptiveGrid.stories.tsx"
  * all.
  */
 
-const { AllStates, AllVariants, Default, Responsive } =
+const { AllStates, AllVariants, Playground, Responsive } =
   composeStories(stories)
 
 /**
@@ -109,7 +109,7 @@ test("the grid re-columns when its container resizes", async () => {
   // need two stacks; at 700px wide only one column fits, and at
   // 1280px the second one it wanted is finally allowed.
   const { canvasElement } = await mountAtInlineSize(
-    Default,
+    Playground,
     700,
   )
 
@@ -147,7 +147,7 @@ test("height buys the column, and width only caps it", async () => {
 
 test("the content cap widens with the columns", async () => {
   const { canvasElement } = await mountAtInlineSize(
-    Default,
+    Playground,
     1280,
   )
 
@@ -163,7 +163,7 @@ test("the content cap widens with the columns", async () => {
 
 test("the measured box is never the capped box", async () => {
   const { canvasElement } = await mountAtInlineSize(
-    Default,
+    Playground,
     1280,
   )
 
@@ -203,7 +203,7 @@ test("one item is one column at a reading measure", async () => {
 
 test("a long unbroken string does not push a track wide", async () => {
   const { canvasElement } = await mountAtInlineSize(
-    Default,
+    Playground,
     1280,
   )
 

package/src/Alert/Alert.mdx

@@ -11,7 +11,7 @@ four times — `TowerAlerts`, `UsbAlertBanner`, `LoadedDiscsBanner`, `VerdictBad
 of those carry a byte-identical `TONE_CLASS` map of hardcoded hexes with no light mode.
 mux-magic spells the same idea a third way in `statusClassMap`.
 
-<Canvas of={AlertStories.Default} />
+<Canvas of={AlertStories.Playground} />
 
 ## Props
 

package/src/Alert/Alert.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 
 import {
@@ -47,7 +48,8 @@ type Story = StoryObj<typeof meta>
  * rip-deck's grouped tower alert, verbatim: one trouble, the bays it
  * touches, and whether the house speakers already said it out loud.
  */
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: {
     description: "4 bays · 3, 4, 5, 6 · confirmed",
     heading:

package/src/Alert/Alert.test.tsx

@@ -7,7 +7,7 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Alert.stories.tsx"
 
-const { AllStates, Default, Interactive, Responsive } =
+const { AllStates, Playground, Interactive, Responsive } =
   composeStories(stories)
 
 test("a labelled alert is a landmark an agent can scope to", async () => {
@@ -34,7 +34,7 @@ test("a labelled alert is a landmark an agent can scope to", async () => {
 
 test("an unlabelled alert is not a landmark", async () => {
   const { canvas, canvasElement } =
-    await mountStory(Default)
+    await mountStory(Playground)
 
   // A block, deliberately. Nine bay cards each holding a named
   // region called "Part of the tower-wide problem above." is axe's

package/src/Avatar/Avatar.mdx

@@ -10,7 +10,7 @@ A person, as a coloured chip — a glyph or an initial, with the name attached w
 assistive technology and a hover can reach it. It exists to **delete a printed name**: a
 board whose cards all say "Owner" has spent a column on a word that a colour says faster.
 
-<Canvas of={AvatarStories.Default} />
+<Canvas of={AvatarStories.Playground} />
 
 ## Props
 

package/src/Avatar/Avatar.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 
 import { categoricalArgType } from "../argTypes.storyHelpers.ts"
@@ -75,7 +76,9 @@ type Story = StoryObj<typeof meta>
  * a screen reader and on hover for a pointer, and it is not printed
  * anywhere — `getByRole("img", { name: "Ada Lovelace" })` resolves.
  */
-export const Default: Story = {}
+export const Playground: Story = {
+  parameters: playgroundParameters,
+}
 
 /**
  * The three appearances, and the ten colours the scale holds.

package/src/Avatar/Avatar.test.tsx

@@ -7,7 +7,7 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Avatar.stories.tsx"
 
-const { AllStates, AllVariants, Default, InAList } =
+const { AllStates, AllVariants, Playground, InAList } =
   composeStories(stories)
 
 /**
@@ -18,7 +18,7 @@ const { AllStates, AllVariants, Default, InAList } =
  * text is the one regression that matters.
  */
 test("the name is readable by an agent and never printed", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const avatar = expectAgentDrivable(canvas, {
     name: "Ada Lovelace",

package/src/Badge/Badge.mdx

@@ -11,7 +11,7 @@ Four repos, and rip-deck declares the **identical** `TONE_CLASS` map twice —
 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 and no error.
 
-<Canvas of={BadgeStories.Default} />
+<Canvas of={BadgeStories.Playground} />
 
 ## Props
 

package/src/Badge/Badge.stories.tsx

@@ -2,6 +2,7 @@ import {
   asyncTransitions,
   useStatus,
 } from "@charcuterie/logic"
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import {
   CATEGORICAL_HUES,
   CATEGORICAL_INDEXES,
@@ -64,7 +65,8 @@ type Story = StoryObj<typeof meta>
  * else, not a live region — so the handle an agent reads off the row
  * is its text.
  */
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: { children: "running", intent: "info" },
 }
 

package/src/Badge/Badge.test.tsx

@@ -11,13 +11,13 @@ import meta, * as stories from "./Badge.stories.tsx"
 const {
   Categorical,
   CategoricalLabels,
-  Default,
+  Playground,
   Interactive,
   Responsive,
 } = composeStories(stories)
 
 test("the text is queryable, which is what an agent matches on", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   // No role, deliberately — a badge is a word about something else,
   // not a live region. So there is nothing to `getByRole` and the
@@ -115,7 +115,7 @@ test("a truncated badge never paints outside its container", async () => {
 })
 
 test("a short badge gets no tooltip", async () => {
-  const { canvasElement } = await mountStory(Default)
+  const { canvasElement } = await mountStory(Playground)
 
   // The measurement has to be able to say *no*, or `title` is just
   // unconditional and every pill in a bay list grows a tooltip.

package/src/BadgeButton/BadgeButton.mdx

@@ -16,7 +16,7 @@ opens the panel that changes it, so each one is pressable — and all six were s
 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} />
+<Canvas of={BadgeButtonStories.Playground} />
 
 ## Props
 

package/src/BadgeButton/BadgeButton.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 
 import {
@@ -53,7 +54,8 @@ type Story = StoryObj<typeof meta>
  * finds it — which is what an agent, and every test in the fleet,
  * actually matches on.
  */
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: { children: "1 episode", intent: "accent" },
 }
 

package/src/BadgeButton/BadgeButton.test.tsx

@@ -10,7 +10,7 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import meta, * as stories from "./BadgeButton.stories.tsx"
 
-const { BesideABadge, Default, InATileFooter } =
+const { BesideABadge, Playground, InATileFooter } =
   composeStories(stories)
 
 /**
@@ -18,7 +18,7 @@ const { BesideABadge, Default, InATileFooter } =
  * is a component rather than a `className` on `Badge`.
  */
 test("is a button, not a span", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const chip = expectAgentDrivable(canvas, {
     name: "1 episode",

package/src/Board/Board.mdx

@@ -9,7 +9,7 @@ import * as BoardStories from "./Board.stories";
 Lanes of cards, sized by their **container**, moved by keyboard or by pointer — and with
 **no drag-and-drop dependency**.
 
-<Canvas of={BoardStories.Default} />
+<Canvas of={BoardStories.Playground} />
 
 <Canvas of={BoardStories.CardMenuItems} />
 

package/src/Board/Board.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 import type { ReactNode } from "react"
 import { useState } from "react"
@@ -473,7 +474,9 @@ type Story = StoryObj<typeof meta>
  * a real mode rather than a story convenience: a board on a wall
  * display should not be advertising affordances nobody can use.
  */
-export const Default: Story = {}
+export const Playground: Story = {
+  parameters: playgroundParameters,
+}
 
 /**
  * Parallel project pools as horizontal bands. Every lane stays on

package/src/Board/Board.test.tsx

@@ -16,7 +16,7 @@ const {
   AccentEdge,
   AllStates,
   CardMenuItems,
-  Default,
+  Playground,
   InBoardScreen,
   Interactive,
   MarkdownTitles,
@@ -188,7 +188,7 @@ test("the priority bar's meaning is available as text", async () => {
  * a promise.
  */
 test("a board with no onMove has no move handles", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   await expect(
     canvas.queryAllByRole("button", { name: /^Move / }),

package/src/Button/Button.mdx

@@ -14,7 +14,7 @@ Six intents x four appearances x three sizes, all of it from tier-2 tokens — s
 swap or a density flip repaints every button on the page with no prop change and no
 re-render.
 
-<Canvas of={ButtonStories.Default} />
+<Canvas of={ButtonStories.Playground} />
 
 ## Props
 

package/src/Button/Button.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 
 import {
@@ -57,7 +58,8 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: { children: "Start rip" },
 }
 

package/src/Button/Button.test.tsx

@@ -9,11 +9,11 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import meta, * as stories from "./Button.stories.tsx"
 
-const { AllStates, Default, Loading } =
+const { AllStates, Playground, Loading } =
   composeStories(stories)
 
 test("is drivable by role and name", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   expectAgentDrivable(canvas, {
     name: "Start rip",

package/src/ButtonLink/ButtonLink.mdx

@@ -16,7 +16,7 @@ cannot be middle-clicked, ctrl-clicked, opened in a new tab, or copied — and m
 solves the same problem in the other direction, with 14 raw `<a href="/…">` that force a
 full page reload through its own SPA router.
 
-<Canvas of={ButtonLinkStories.Default} />
+<Canvas of={ButtonLinkStories.Playground} />
 
 ## Props
 

package/src/ButtonLink/ButtonLink.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 import type { ReactNode } from "react"
 
@@ -77,7 +78,8 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: { children: "Configure" },
 }
 

package/src/ButtonLink/ButtonLink.test.tsx

@@ -14,7 +14,7 @@ const {
   AllStates,
   AllVariants,
   BesideAButton,
-  Default,
+  Playground,
   External,
   Routed,
 } = composeStories(stories)
@@ -29,7 +29,7 @@ const {
  * whole argument.
  */
 test("is a link, not a button", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const link = expectAgentDrivable(canvas, {
     name: "Configure",
@@ -51,7 +51,7 @@ test("is a link, not a button", async () => {
 })
 
 test("Tab reaches it", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const link = canvas.getByRole("link", {
     name: "Configure",

package/src/Card/Card.mdx

@@ -11,7 +11,7 @@ a **landmark**, so `getByRole("region", { name: "Bay 3" })` scopes every query i
 Without that, an agent driving a 16-bay tower sees sixteen identical "Start" buttons and no
 way to say which one it means. The `Interactive` story asserts exactly that.
 
-<Canvas of={CardStories.Default} />
+<Canvas of={CardStories.Playground} />
 
 ## Props
 
@@ -35,6 +35,26 @@ all, deliberately — it has nothing to be named.
 `raised` means *more separated from base*, not *lighter*, which is why light mode's base is
 `#F5F7FA` and its raised is white.
 
+### A card the app names itself
+
+Pass `aria-labelledby` and no `heading` when the app draws its own title row — a name beside
+a count is one line that `heading` cannot express, so mail-sifter's tiles render it and point
+at it. The card keeps that pointer.
+
+> **It has to be a fallback, not a default.** The attribute is written after the caller's
+> props are spread, so the obvious `heading ? headingId : undefined` **overwrites** the call
+> site's pointer rather than leaving it alone. React then drops the attribute, the card's name
+> falls back to its entire subtree, and nothing reports it: the markup is valid, the types are
+> satisfied, and axe is content with a name made of everything. Both of mail-sifter's
+> `role="button"` tiles announced their whole contents — "Recent Mail 6 40 arrived in the last
+> 24 hours, 34 done" for a tile called "Recent Mail".
+
+`heading` still wins where both are given, because the heading is text the reader can see and
+this component renders it. `aria-label` needs no fallback at all — `Card` never writes one, so
+the spread carries the caller's through.
+
+<Canvas of={CardStories.CallerNamed} />
+
 <Canvas of={CardStories.AllVariants} />
 
 ## Container queries, not media queries

package/src/Card/Card.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 
 import { toStoryChoice } from "../argTypes.storyHelpers.ts"
@@ -43,7 +44,8 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: {
     children: (
       <p className="text-content-secondary text-sm">
@@ -296,3 +298,91 @@ export const AccentEdge: Story = {
     </StorySection>
   ),
 }
+
+/**
+ * Ids for the two cells that point at their own text. Written out
+ * rather than generated, because a story is a static demo and the
+ * docs page mounts every cell at once — two cells sharing a
+ * generated id would be a duplicate-id violation nobody could see.
+ */
+const CALLER_HEADING_ID = "card-caller-heading"
+const SHADOWED_HEADING_ID = "card-shadowed-heading"
+
+/**
+ * The card is named by a heading the **app** draws, not by
+ * `heading`.
+ *
+ * mail-sifter's tiles put the name and its count on one row, so they
+ * render the title themselves and pass `aria-labelledby` at the call
+ * site. `Card` writes that attribute after the caller's spread, so
+ * it has to fall back to the caller's pointer: without the fallback
+ * the attribute is overwritten with `undefined`, React drops it, and
+ * the tile's name becomes its whole subtree — "Recent Mail 6 40
+ * arrived in the last 24 hours, 34 done" instead of "Recent Mail".
+ * Nothing reports that: it renders, it typechecks, and axe is happy
+ * with a name made of everything.
+ *
+ * `heading` still wins where it is given, and `aria-label` needs no
+ * fallback at all — the component never writes one, so the spread
+ * carries it through.
+ */
+export const CallerNamed: Story = {
+  args: { children: "Content" },
+  render: () => (
+    <StoryGrid columns={3}>
+      <StoryCell
+        align="stretch"
+        label="the call site's own pointer"
+      >
+        <Card aria-labelledby={CALLER_HEADING_ID}>
+          <div className="flex items-baseline justify-between gap-2">
+            <h2
+              className="font-semibold text-md leading-tight"
+              id={CALLER_HEADING_ID}
+            >
+              Recent Mail
+            </h2>
+
+            <Badge intent="info" size="sm">
+              6
+            </Badge>
+          </div>
+
+          <p className="text-content-secondary text-sm">
+            40 arrived in the last 24 hours, 34 done.
+          </p>
+        </Card>
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="a heading beats the pointer"
+      >
+        <Card
+          aria-labelledby={SHADOWED_HEADING_ID}
+          heading="Bay 5"
+        >
+          <p
+            className="text-content-secondary text-sm"
+            id={SHADOWED_HEADING_ID}
+          >
+            Pointed at, and deliberately not the name — the
+            heading is the text the reader can see.
+          </p>
+        </Card>
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="an aria-label passes through"
+      >
+        <Card aria-label="Unread mail">
+          <p className="text-content-secondary text-sm">
+            No heading and no pointer, so the card is named
+            by the label the call site set.
+          </p>
+        </Card>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}

package/src/Card/Card.test.tsx

@@ -6,11 +6,16 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Card.stories.tsx"
 
-const { AccentEdge, AllStates, Default, Interactive } =
-  composeStories(stories)
+const {
+  AccentEdge,
+  AllStates,
+  CallerNamed,
+  Playground,
+  Interactive,
+} = composeStories(stories)
 
 test("a heading turns the card into a named landmark", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   expectAgentDrivable(canvas, {
     name: "Bay 3",
@@ -29,6 +34,58 @@ test("a card with no heading is not a landmark", async () => {
   )
 })
 
+/**
+ * The name the call site set is the fallback, and it is the half the
+ * component used to throw away.
+ *
+ * `aria-labelledby` is written after the caller's spread, so the old
+ * `heading ? headingId : undefined` overwrote the caller's pointer
+ * instead of deferring to it. A tile naming itself from a heading it
+ * draws lost its name and picked up its whole subtree — and this is
+ * the only gate that can see it, because the markup is valid, the
+ * types are satisfied, and a card named by everything is still a
+ * card with a name.
+ */
+test("a card with no heading keeps the caller's own name", async () => {
+  const { canvas } = await mountStory(CallerNamed)
+
+  // Exactly "Recent Mail". Were the subtree naming it, this would be
+  // "Recent Mail 6 40 arrived in the last 24 hours, 34 done" and the
+  // query would match nothing.
+  expectAgentDrivable(canvas, {
+    name: "Recent Mail",
+    role: "region",
+  })
+})
+
+/**
+ * The fallback is a fallback, not a swap: a `heading` is text the
+ * reader can see and the component renders it, so it still wins.
+ */
+test("a heading still names the card over the caller's pointer", async () => {
+  const { canvas } = await mountStory(CallerNamed)
+
+  expectAgentDrivable(canvas, {
+    name: "Bay 5",
+    role: "region",
+  })
+})
+
+/**
+ * `aria-label` needs no fallback — the component never writes one,
+ * so the spread carries the caller's through. Asserted anyway, so
+ * that a future "fix" which starts writing `aria-label` here cannot
+ * take the caller's with it the way this one took `aria-labelledby`.
+ */
+test("a caller's aria-label reaches the card untouched", async () => {
+  const { canvas } = await mountStory(CallerNamed)
+
+  expectAgentDrivable(canvas, {
+    name: "Unread mail",
+    role: "region",
+  })
+})
+
 /**
  * Two identical "Start rip" buttons on one page, disambiguated only
  * by the region each sits in.