@charcuterie/ui 4.5.0 → 4.6.0

package/src/Toolbar/Toolbar.stories.tsx

@@ -1,5 +1,6 @@
 import { useMediaQuery } from "@charcuterie/logic"
 import { matchMediaMatcher } from "@charcuterie/logic/browser"
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 import type { ReactNode } from "react"
 import { useState } from "react"
@@ -150,7 +151,8 @@ type Story = StoryObj<typeof meta>
  * collapse is not progressive: almost everything lives in the
  * popover permanently.
  */
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   render: (toolbarProps) => (
     <Frame inlineSize="34rem">
       <Toolbar {...toolbarProps} />

package/src/Toolbar/Toolbar.test.tsx

@@ -15,13 +15,13 @@ import * as stories from "./Toolbar.stories.tsx"
 const {
   AllStates,
   AllVariants,
-  Default,
+  Playground,
   InAppShell,
   Interactive,
 } = composeStories(stories)
 
 test("the toolbar is named, and its actions are buttons", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const toolbar = expectAgentDrivable(canvas, {
     name: "Deck actions",
@@ -43,7 +43,7 @@ test("the toolbar is named, and its actions are buttons", async () => {
  * popover permanently.
  */
 test("a bar with room shows no overflow trigger", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const toolbar = expectAgentDrivable(canvas, {
     name: "Deck actions",
@@ -73,7 +73,7 @@ test("a bar with room shows no overflow trigger", async () => {
  * the app's own component and most of them forward no `tabIndex`.
  */
 test("the toolbar is one tab stop", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const toolbar = expectAgentDrivable(canvas, {
     name: "Deck actions",
@@ -98,7 +98,7 @@ test("the toolbar is one tab stop", async () => {
 })
 
 test("the arrow keys move along the row", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const start = expectAgentDrivable(canvas, {
     name: "Start rip",
@@ -284,3 +284,87 @@ test("the shell mounts exactly one toolbar", async () => {
     }),
   ).toHaveLength(1)
 })
+
+/**
+ * The font race, which is latent rather than observed: it needs the
+ * two faces to disagree across a collapse boundary, and no story in
+ * the library crosses one today. The test builds that boundary on
+ * purpose, so the mechanism is checked rather than waited for.
+ *
+ * Every width the bar measures is a **text** width. On a cold cache
+ * the first measurement is taken in the fallback face, and when the
+ * real face swaps in the items change size — but the container does
+ * not, so the `ResizeObserver` stays quiet, and nothing re-renders,
+ * so the layout effect does not run either. The bar keeps an answer
+ * computed against a font that is no longer on screen.
+ *
+ * The stub below is that swap with the timing made explicit: the bar
+ * mounts while `document.fonts.ready` is still pending, the items
+ * are widened with no change to the container's box, and the
+ * promise is then resolved. A bar that only measures on mount and
+ * on resize sees neither event and stays wrong.
+ */
+test("the bar re-measures once the webfont has loaded", async () => {
+  const realFonts = document.fonts
+
+  let markFontsReady = () => {}
+
+  const fontsReady = new Promise<FontFaceSet>((resolve) => {
+    markFontsReady = () => {
+      resolve(realFonts)
+    }
+  })
+
+  // Layered over the real set rather than replacing it, so anything
+  // else that reads `document.fonts` during the mount still works.
+  Object.defineProperty(document, "fonts", {
+    configurable: true,
+    value: Object.create(realFonts, {
+      ready: {
+        get: () => fontsReady,
+      },
+    }),
+  })
+
+  // Widens every action without touching the bar's own box — the
+  // `Frame` around `Playground` is a fixed `34rem`. That is exactly
+  // what a font swap does, and it is why the `ResizeObserver` is
+  // not a substitute for this effect.
+  const widenActions = document.createElement("style")
+
+  widenActions.textContent = `[role="toolbar"] button { padding-inline: 4rem; }`
+
+  try {
+    const { canvas } = await mountStory(Playground)
+
+    const toolbar = expectAgentDrivable(canvas, {
+      name: "Deck actions",
+      role: "toolbar",
+    })
+
+    // It fits in the fallback face.
+    await expect(
+      within(toolbar).queryByRole("button", {
+        name: "More actions",
+      }),
+    ).toBeNull()
+
+    document.head.append(widenActions)
+
+    markFontsReady()
+
+    await waitFor(() => {
+      expect(
+        within(toolbar).getByRole("button", {
+          name: "More actions",
+        }),
+      ).toBeInTheDocument()
+    })
+  } finally {
+    widenActions.remove()
+
+    // Back to the prototype getter — the stub was an own property
+    // shadowing it.
+    Reflect.deleteProperty(document, "fonts")
+  }
+})

package/src/Toolbar/useToolbarOverflow.ts

@@ -159,6 +159,49 @@ export const useToolbarOverflow = ({
    */
   useLayoutEffect(measure)
 
+  /**
+   * Measure again once the webfont has actually arrived.
+   *
+   * Every width above is a **text** width, so it is only as correct
+   * as the font that was loaded when it was read. On a cold cache
+   * the first measurement happens in the fallback face, the items
+   * come out a few pixels off, and `chooseVisibleCount` keeps or
+   * drops one action it should not have — then never revisits it,
+   * because swapping a font changes no box the `ResizeObserver`
+   * watches and triggers no render.
+   *
+   * The user-visible symptom is a bar that settles one button wrong
+   * and stays there. It needs the two faces to disagree across a
+   * collapse boundary, so it is latent rather than observed: no
+   * story in the library crosses one today, which is why `vrt`
+   * reports nothing either way. That makes it a gap to close, not a
+   * regression to chase — the bar is supposed to measure what is on
+   * screen, and until now it could not.
+   *
+   * `document.fonts.ready` resolves immediately when the fonts are
+   * already in, so a warm load pays one microtask and
+   * `setVisibleCount` bails on the unchanged answer.
+   */
+  useLayoutEffect(() => {
+    // jsdom has no `document.fonts`, and neither does a very old
+    // browser. Nothing to wait for is not an error.
+    if (!document.fonts) {
+      return
+    }
+
+    let isActive = true
+
+    document.fonts.ready.then(() => {
+      if (isActive) {
+        measure()
+      }
+    })
+
+    return () => {
+      isActive = false
+    }
+  }, [measure])
+
   useLayoutEffect(() => {
     const container = containerRef.current
 

package/src/Tooltip/Tooltip.mdx

@@ -9,7 +9,7 @@ import * as TooltipStories from "./Tooltip.stories";
 Replaces mux-magic's `FieldTooltip` — 130 lines of hand-rolled positioning, including a
 `computePosition` that reimplements `flip` and `shift` against `window.innerHeight`.
 
-<Canvas of={TooltipStories.Default} />
+<Canvas of={TooltipStories.Playground} />
 
 ## Props
 

package/src/Tooltip/Tooltip.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 
 import { placementArgType } from "../argTypes.storyHelpers.ts"
@@ -26,7 +27,8 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: {
     children: <Button appearance="outline">Retry</Button>,
     label: "Re-reads the disc from title 1.",

package/src/Tooltip/Tooltip.test.tsx

@@ -7,12 +7,12 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Tooltip.stories.tsx"
 
-const { AllVariants, Default, Interactive } =
+const { AllVariants, Playground, Interactive } =
   composeStories(stories)
 
 test("nothing is shown until something asks", async () => {
   const { body, canvas, canvasElement } =
-    await mountStory(Default)
+    await mountStory(Playground)
 
   expectAgentDrivable(canvas, {
     name: "Retry",

package/src/VirtualizedGrid/VirtualizedGrid.mdx

@@ -10,7 +10,7 @@ import * as VirtualizedGridStories from "./VirtualizedGrid.stories";
 two-box structure, same content cap. The one difference is that a list of 2,000 costs
 about as much as a list of 40.
 
-<Canvas of={VirtualizedGridStories.Default} />
+<Canvas of={VirtualizedGridStories.Playground} />
 
 ## Props
 

package/src/VirtualizedGrid/VirtualizedGrid.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"
 
@@ -107,7 +108,9 @@ type Story = StoryObj<typeof meta>
  * Inspect the DOM and count: the row elements are the ones on
  * screen plus `overscanRows` above and below.
  */
-export const Default: Story = {}
+export const Playground: Story = {
+  parameters: playgroundParameters,
+}
 
 /**
  * The app-shell contract: `Main` is the one vertical scroll region,

package/src/VirtualizedGrid/VirtualizedGrid.test.tsx

@@ -38,7 +38,7 @@ import * as stories from "./VirtualizedGrid.stories.tsx"
 
 const {
   AllStates,
-  Default,
+  Playground,
   InHiddenTabPanel,
   InShellScrollRegion,
 } = composeStories(stories)
@@ -84,7 +84,7 @@ const getRowIndexes = (canvasElement: HTMLElement) => [
 ]
 
 test("2,000 items mount as a few dozen cells", async () => {
-  const { canvasElement } = await mountStory(Default)
+  const { canvasElement } = await mountStory(Playground)
 
   await waitFor(async () => {
     await expect(
@@ -102,7 +102,7 @@ test("2,000 items mount as a few dozen cells", async () => {
 })
 
 test("the page is still as tall as the whole list", async () => {
-  const { canvasElement } = await mountStory(Default)
+  const { canvasElement } = await mountStory(Playground)
 
   await waitFor(async () => {
     await expect(
@@ -123,7 +123,7 @@ test("the page is still as tall as the whole list", async () => {
 })
 
 test("scrolling changes which rows exist", async () => {
-  const { canvasElement } = await mountStory(Default)
+  const { canvasElement } = await mountStory(Playground)
 
   await waitFor(async () => {
     await expect(
@@ -325,7 +325,7 @@ test("a grid inside a hidden panel mounts nothing and reveals without scrolling"
 })
 
 test("a screen reader is told the real length", async () => {
-  const { canvasElement } = await mountStory(Default)
+  const { canvasElement } = await mountStory(Playground)
 
   await waitFor(async () => {
     await expect(

package/src/VisuallyHidden/VisuallyHidden.mdx

@@ -11,7 +11,7 @@ other component in M3 leans on: it is how a `Spinner` says "Loading…" without
 how a `ProgressBar`'s label stays discoverable when the design does not show it, and how an
 `IconButton`'s glyph gets a name.
 
-<Canvas of={VisuallyHiddenStories.Default} />
+<Canvas of={VisuallyHiddenStories.Playground} />
 
 ## Props
 

package/src/VisuallyHidden/VisuallyHidden.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 
 import {
@@ -28,7 +29,8 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: { children: "Announced, never printed." },
   render: (visuallyHiddenProps) => (
     <StoryGrid columns={2}>

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.mdx

@@ -16,7 +16,7 @@ It is **opt-in**, from a subpath:
 import { MarkdownEditorCodeMirror } from "@charcuterie/ui/markdown-editor-codemirror"
 ```
 
-<Canvas of={MarkdownEditorCodeMirrorStories.Default} />
+<Canvas of={MarkdownEditorCodeMirrorStories.Playground} />
 
 ## Props
 

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 
 import {
@@ -91,7 +92,8 @@ type Story = StoryObj<typeof meta>
  * genuinely larger, `**` is nowhere on screen, the checkboxes are
  * checkboxes, and the bare URL is a link.
  */
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: {
     defaultValue: SAMPLE,
     label: "Description",

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.test.tsx

@@ -5,7 +5,7 @@ import { test } from "vitest"
 import { mountStory } from "../mountStory.testHelpers.ts"
 import * as stories from "./MarkdownEditorCodeMirror.stories.tsx"
 
-const { AllStates, CaretReveal, Default, Uploading } =
+const { AllStates, CaretReveal, Playground, Uploading } =
   composeStories(stories)
 
 type Canvas = Awaited<
@@ -169,7 +169,7 @@ test("a click low in an empty field lands in the document", async () => {
  * anywhere in this stack would have quietly taken away.
  */
 test("a document taller than the frame grows it", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const content = canvas.getByRole("textbox", {
     name: "Description",
@@ -235,7 +235,7 @@ test("the toolbar offers Image when uploads are wired", async () => {
 /** A button that opens a file picker and then has nowhere to send
  * the file is worse than no button. */
 test("the toolbar hides Image when nothing can take the file", async () => {
-  const { body, canvas } = await mountStory(Default)
+  const { body, canvas } = await mountStory(Playground)
 
   const overflow = canvas.queryByRole("button", {
     name: "More actions",

package/src/markdownEditorCodeMirror/MarkdownView.mdx

@@ -15,7 +15,7 @@ It is **opt-in**, from the same subpath as the editor:
 import { MarkdownView } from "@charcuterie/ui/markdown-editor-codemirror"
 ```
 
-<Canvas of={MarkdownViewStories.Default} />
+<Canvas of={MarkdownViewStories.Playground} />
 
 ## Props
 

package/src/markdownEditorCodeMirror/MarkdownView.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"
 
@@ -183,7 +184,9 @@ type Story = StoryObj<typeof meta>
  * `getAllByRole("toolbar")` returns nothing, because nothing in this
  * component can render one.
  */
-export const Default: Story = {}
+export const Playground: Story = {
+  parameters: playgroundParameters,
+}
 
 /**
  * The same string, in both surfaces, side by side.

package/src/markdownEditorCodeMirror/MarkdownView.test.tsx

@@ -9,7 +9,7 @@ import * as stories from "./MarkdownView.stories.tsx"
 
 const {
   AllStates,
-  Default,
+  Playground,
   HostileMarkdown,
   Interactive,
   NestedLinkText,
@@ -26,7 +26,7 @@ const {
  * there is the fix.
  */
 test("there is no toolbar, not a hidden one", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   await expect(canvas.queryAllByRole("toolbar")).toEqual([])
 
@@ -47,7 +47,7 @@ test("there is no toolbar, not a hidden one", async () => {
  * asserted together.
  */
 test("it is an article whose headings are headings", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const article = expectAgentDrivable(canvas, {
     name: "Description",
@@ -86,12 +86,28 @@ test("it is an article whose headings are headings", async () => {
 test("it renders what the editor renders", async () => {
   const { canvas } = await mountStory(SameAsTheEditor)
 
-  const [viewTable, editorTable] =
-    canvas.getAllByRole("table")
-
-  await expect(viewTable).toBeDefined()
-
-  await expect(editorTable).toBeDefined()
+  // ⚠️ WAIT FOR THE COUNT, not for "a table".
+  //
+  // This test is the only one in the file that mounts a story with
+  // BOTH surfaces, so it is the only one that has to wait for
+  // CodeMirror. `MarkdownView` paints its table in the first commit;
+  // CodeMirror parses and decorates the document afterwards. A
+  // synchronous `getAllByRole("table")` therefore returned ONE table
+  // on a slow runner, `editorTable` was `undefined`, and the failure
+  // read "expected undefined to be defined" — which says nothing
+  // about the real cause (CI, 2026-09-14).
+  //
+  // ⚠️ A bare `findAllByRole` does NOT fix it. `findAllBy*` retries
+  // until the query matches AT LEAST ONE element, and one element is
+  // exactly the broken state: the view's table is there from the
+  // start. The count is the condition, so the count goes in the wait.
+  const [viewTable, editorTable] = await waitFor(() => {
+    const tables = canvas.getAllByRole("table")
+
+    expect(tables).toHaveLength(2)
+
+    return tables
+  })
 
   const toCellText = (table: HTMLElement) =>
     Array.from(table.querySelectorAll("th, td")).map(
@@ -103,10 +119,16 @@ test("it renders what the editor renders", async () => {
   ).toEqual(toCellText(editorTable as HTMLElement))
 
   // Three task boxes in each, and the first one ticked in each.
-  const checkboxes: HTMLInputElement[] =
-    canvas.getAllByRole("checkbox")
+  // Same wait, same reason: CodeMirror's boxes arrive with its
+  // decorations, so a count taken too early sees only the view's.
+  const checkboxes = await waitFor(() => {
+    const boxes: HTMLInputElement[] =
+      canvas.getAllByRole("checkbox")
 
-  await expect(checkboxes).toHaveLength(6)
+    expect(boxes).toHaveLength(6)
+
+    return boxes
+  })
 
   await expect(
     checkboxes.filter((checkbox) => checkbox.checked),
@@ -114,11 +136,13 @@ test("it renders what the editor renders", async () => {
 
   // The bare URL, autolinked on both sides with nothing typed
   // around it.
-  await expect(
-    canvas.getAllByText(
-      "https://example.invalid/product?id=1234",
-    ).length,
-  ).toBe(2)
+  await waitFor(() => {
+    expect(
+      canvas.getAllByText(
+        "https://example.invalid/product?id=1234",
+      ),
+    ).toHaveLength(2)
+  })
 })
 
 /**
@@ -265,7 +289,7 @@ test("hostile markdown renders as characters, not as behaviour", async () => {
  * else noticing.
  */
 test("the text can be selected", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const article = canvas.getByRole("article")
 
@@ -360,7 +384,7 @@ test.each([
  * survives a change to the base font size.
  */
 test("the document is set at prose leading", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const article = canvas.getByRole("article")
 
@@ -379,7 +403,7 @@ test("the document is set at prose leading", async () => {
  * backticks comes out as a wall of emphasis nobody asked for.
  */
 test("a code span is smaller than the prose it sits in", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const article = canvas.getByRole("article")
 

package/src/reactRouter/ReactRouterAdapter.stories.tsx

@@ -1,3 +1,4 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
 import {
   MemoryRouter,
@@ -92,7 +93,8 @@ const EpisodePage = () => (
  * `TextLink` becomes a soft navigation and `Main` keeps the
  * reader's place because `ReactRouterAdapter` is above them both.
  */
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   render: () => (
     <MemoryRouter initialEntries={["/library"]}>
       <ReactRouterAdapter>

package/src/reactRouter/ReactRouterAdapter.test.tsx

@@ -11,7 +11,7 @@ import {
 } from "../viewport.testHelpers.ts"
 import * as stories from "./ReactRouterAdapter.stories.tsx"
 
-const { Default } = composeStories(stories)
+const { Playground } = composeStories(stories)
 
 // The offsets are module state, so they outlive a mount. A test
 // must not.
@@ -33,7 +33,7 @@ afterEach(() => {
 test("an app renders one component and gets both seams", async () => {
   await setViewport(DESKTOP)
 
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const main = canvas.getByRole("main")