@charcuterie/ui 4.5.0 → 4.6.0

package/src/Tabs/Tabs.test.tsx

@@ -10,7 +10,7 @@ import * as stories from "./Tabs.stories.tsx"
 const {
   AllStates,
   AllVariants,
-  Default,
+  Playground,
   Manual,
   Responsive,
   Routed,
@@ -20,7 +20,7 @@ const {
 
 test("selecting a tab wires the panel back to it", async () => {
   const { canvas, canvasElement } =
-    await mountStory(Default)
+    await mountStory(Playground)
 
   const tablist = expectAgentDrivable(canvas, {
     name: "Bay 3",
@@ -256,7 +256,7 @@ test("manual activation moves focus without selecting", async () => {
 })
 
 test("automatic activation selects as focus moves, and wraps", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const tablist = expectAgentDrivable(canvas, {
     name: "Bay 3",

package/src/TextLink/TextLink.mdx

@@ -18,7 +18,7 @@ header home link because there was nothing else to reach for. All of them are an
 here, so middle-click, ctrl-click, "open in new tab", "copy link address", and the browser's
 status bar work without anybody implementing them.
 
-<Canvas of={TextLinkStories.Default} />
+<Canvas of={TextLinkStories.Playground} />
 
 ## Props
 

package/src/TextLink/TextLink.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"
 
@@ -62,7 +63,8 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: { children: "the rip queue" },
 }
 

package/src/TextLink/TextLink.test.tsx

@@ -14,7 +14,7 @@ const {
   AllAppearances,
   AllStates,
   BackLink,
-  Default,
+  Playground,
   External,
   Routed,
 } = composeStories(stories)
@@ -28,7 +28,7 @@ const {
  * it for free is the entire argument for rendering an anchor.
  */
 test("is drivable by role and name", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const link = expectAgentDrivable(canvas, {
     name: "the rip queue",
@@ -39,7 +39,7 @@ test("is drivable by role and name", async () => {
 })
 
 test("Tab reaches it", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const link = canvas.getByRole("link", {
     name: "the rip queue",
@@ -210,7 +210,7 @@ test("an injected router takes in-app paths and nothing else", async () => {
 })
 
 test("with no provider it is still a real anchor", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const link = canvas.getByRole("link", {
     name: "the rip queue",

package/src/TimecodeInput/TimecodeInput.mdx

@@ -11,7 +11,7 @@ for a section of a file. The consumer that shaped it is **QueuePilot**, which pl
 chosen part of a video
 ([decision](../../../../docs/decisions/2026-09-01-a-timecode-is-milliseconds-and-a-section-is-a-mode.md)).
 
-<Canvas of={TimecodeInputStories.Default} />
+<Canvas of={TimecodeInputStories.Playground} />
 
 ## Props
 

package/src/TimecodeInput/TimecodeInput.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"
@@ -113,7 +114,8 @@ const TimecodeHarness = ({
  * Milliseconds are optional both ways: `1:01:00` commits as
  * `01:01:00`, not as `01:01:00.000`.
  */
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: { label: "Start at" },
   render: () => <TimecodeHarness label="Start at" />,
 }

package/src/Toast/Toast.mdx

@@ -16,7 +16,7 @@ machine down and M2 never built it:
 
 > | Toast lifecycle | entering → visible → exiting → removed |
 
-<Canvas of={ToastStories.Default} />
+<Canvas of={ToastStories.Playground} />
 
 ## Props
 

package/src/Toast/Toast.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"
@@ -8,6 +9,8 @@ import {
   StoryCell,
   StoryGrid,
 } from "../board.storyHelpers.tsx"
+import { Modal } from "../Modal/Modal.tsx"
+import { OverlayStackProvider } from "../Overlay/OverlayStack.tsx"
 import { Toast } from "./Toast.tsx"
 import type { ToastRecord } from "./ToastRegion.tsx"
 import { ToastRegion } from "./ToastRegion.tsx"
@@ -46,7 +49,8 @@ const ToastList = ({
   </ul>
 )
 
-export const Default: Story = {
+export const Playground: Story = {
+  parameters: playgroundParameters,
   args: {
     children: "Blade Runner (1982) · 9 titles.",
     title: "Rip finished",
@@ -190,3 +194,155 @@ export const Interactive: Story = {
     )
   },
 }
+
+/**
+ * Twelve at once, which is the case the bottom-anchored column
+ * cannot hold. Without a bound the oldest climb off the top of the
+ * page and take the stack with them; the list is capped, pinned to
+ * its bottom edge, and scrolls. The newest is always the one on
+ * screen.
+ */
+export const ManyAtOnce: Story = {
+  args: { title: "Rip finished" },
+  parameters: { layout: "fullscreen" },
+  render: function ManyRegion() {
+    const [toasts, setToasts] = useState<ToastRecord[]>(
+      Array.from({ length: 12 }, (_, index) => ({
+        description: `Bay ${index + 1} finished.`,
+        duration: 0,
+        intent: "success" as const,
+        key: `rip-${index}`,
+        title: `Rip ${index + 1} finished`,
+      })),
+    )
+
+    return (
+      <div className="h-dvh">
+        <ToastRegion
+          onDismiss={(key) => {
+            setToasts((previous) =>
+              previous.filter((one) => one.key !== key),
+            )
+          }}
+          toasts={toasts}
+        />
+      </div>
+    )
+  },
+}
+
+/**
+ * The story the `z-50` bug needed and never had.
+ *
+ * Two stacked modals and a pinned toast carrying an Undo. Three
+ * things have to be true at once, and each one was false before the
+ * layering change:
+ *
+ * 1. The toast paints **above both modals**, which cascade at
+ *    `--layer-modal + n`.
+ * 2. Pressing its Undo does **not** close the modal — a press on a
+ *    toast is not an outside press.
+ * 3. The toast stays in the accessibility tree while the focus
+ *    manager hides the rest of the page.
+ */
+export const OverStackedModals: Story = {
+  args: { title: "Rip finished" },
+  parameters: { layout: "fullscreen" },
+  render: function OverModalsRegion() {
+    const [isOuterVisible, setIsOuterVisible] =
+      useState(true)
+
+    const [isInnerVisible, setIsInnerVisible] =
+      useState(true)
+
+    const [isUndone, setIsUndone] = useState(false)
+
+    const [toasts, setToasts] = useState<ToastRecord[]>([
+      {
+        description: "Undo",
+        duration: 0,
+        intent: "success",
+        key: "moved",
+        title: "Moved to Done",
+      },
+    ])
+
+    return (
+      <OverlayStackProvider>
+        <div className="h-dvh p-4">
+          {/* Page content beside the region, and load-bearing.
+              `markOthers` marks it, which is what makes
+              `OverlayPanel`'s `outsidePress` predicate decide the
+              press on Undo — a story holding nothing but the
+              region takes a different branch inside floating-ui
+              and passes whether the guard exists or not. */}
+          <h2 className="m-0 text-lg">Rip queue</h2>
+
+          <p className="m-0">
+            Four bays, three of them busy.
+          </p>
+
+          <Modal
+            aria-label="Rip settings"
+            isVisible={isOuterVisible}
+            onClose={() => {
+              setIsOuterVisible(false)
+            }}
+          >
+            <div className="flex flex-col gap-2 p-4">
+              <p className="m-0">The outer modal.</p>
+
+              <Button
+                onClick={() => {
+                  setIsInnerVisible(true)
+                }}
+              >
+                Open the inner modal
+              </Button>
+            </div>
+          </Modal>
+
+          <Modal
+            aria-label="Confirm the rip"
+            isVisible={isOuterVisible && isInnerVisible}
+            onClose={() => {
+              setIsInnerVisible(false)
+            }}
+          >
+            <div className="flex flex-col gap-2 p-4">
+              <p className="m-0">
+                The inner modal, on top of the outer one.
+              </p>
+
+              <p className="m-0">
+                {isUndone ? "Undone" : "Not undone"}
+              </p>
+            </div>
+          </Modal>
+
+          <ToastRegion
+            onDismiss={(key) => {
+              setToasts((previous) =>
+                previous.filter((one) => one.key !== key),
+              )
+            }}
+            toasts={toasts.map((one) => ({
+              ...one,
+              description: (
+                <Button
+                  onClick={() => {
+                    setIsUndone(true)
+                  }}
+                  appearance="ghost"
+                  size="sm"
+                >
+                  Undo
+                </Button>
+              ),
+            }))}
+          />
+        </div>
+      </OverlayStackProvider>
+    )
+  },
+}

package/src/Toast/Toast.test.tsx

@@ -8,7 +8,7 @@ import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Toast.stories.tsx"
 import { toastTransitions } from "./toastLifecycle.ts"
 
-const { AllStates, AllVariants, Default, Interactive } =
+const { AllStates, AllVariants, Playground, Interactive } =
   composeStories(stories)
 
 /**
@@ -180,7 +180,7 @@ test("a dismiss during the enter frame is not undone by it", async () => {
 })
 
 test("a pinned toast stays put", async () => {
-  const { canvas } = await mountStory(Default)
+  const { canvas } = await mountStory(Playground)
 
   const dismiss = expectAgentDrivable(canvas, {
     name: "Dismiss Rip finished",

package/src/Toast/ToastRegion.test.tsx

@@ -0,0 +1,172 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test, expect as vitestExpect } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Toast.stories.tsx"
+
+const { ManyAtOnce, OverStackedModals } =
+  composeStories(stories)
+
+const layerOf = (element: Element): number =>
+  Number.parseInt(
+    globalThis.getComputedStyle(element).zIndex,
+    10,
+  )
+
+/**
+ * The region used to paint at a hand-picked `z-50`, which is below
+ * every overlay token in the scale — so an Undo raised from inside a
+ * modal was drawn *behind* the modal and could not be pressed at
+ * all. These are the three things "the toast is on top" has to mean,
+ * and each one was false.
+ */
+test("the toast paints above a cascade of modals", async () => {
+  const { body, canvasElement } = await mountStory(
+    OverStackedModals,
+  )
+
+  const [outer, inner] = [
+    ...document.querySelectorAll('[role="dialog"]'),
+  ].map((panel) => {
+    const container = panel.closest("[style*='z-index']")
+
+    if (!container) {
+      throw new Error("a panel rendered with no container")
+    }
+
+    return container
+  })
+
+  if (!outer || !inner) {
+    throw new Error("both modals should be open")
+  }
+
+  // Cascading, not one shared `--layer-modal`. Which of the two
+  // painted on top used to fall out of portal append order.
+  vitestExpect(layerOf(inner)).toBeGreaterThan(
+    layerOf(outer),
+  )
+
+  const region = expectAgentDrivable(body, {
+    name: "Notifications",
+    role: "status",
+  })
+
+  // Above the whole stack, not only its first floor.
+  vitestExpect(layerOf(region)).toBeGreaterThan(
+    layerOf(inner),
+  )
+
+  // And painted there, which the z-index alone does not prove: a
+  // region nested inside a panel's stacking context would report the
+  // same number and still be covered.
+  const undo = expectAgentDrivable(body, {
+    name: "Undo",
+    role: "button",
+  })
+
+  const box = undo.getBoundingClientRect()
+
+  const painted = document.elementFromPoint(
+    box.left + box.width / 2,
+    box.top + box.height / 2,
+  )
+
+  vitestExpect(undo.contains(painted)).toBe(true)
+
+  await expect(canvasElement).toBeTruthy()
+})
+
+test("pressing Undo does not dismiss the modal under it", async () => {
+  const { body } = await mountStory(OverStackedModals)
+
+  await userEvent.click(
+    expectAgentDrivable(body, {
+      name: "Undo",
+      role: "button",
+    }),
+  )
+
+  // The action ran...
+  await waitFor(() => {
+    vitestExpect(body.getByText("Undone")).toBeTruthy()
+  })
+
+  // ...and `useDismiss` did not read the press as an outside press.
+  // Closing a modal on the way to taking an action back is the
+  // opposite of what the button says.
+  vitestExpect(
+    document.querySelectorAll('[role="dialog"]'),
+  ).toHaveLength(2)
+})
+
+test("the toast stays in the accessibility tree behind a focus trap", async () => {
+  const { body } = await mountStory(OverStackedModals)
+
+  const region = expectAgentDrivable(body, {
+    name: "Notifications",
+    role: "status",
+  })
+
+  // `FloatingFocusManager`'s `modal` marks the body-level siblings
+  // of its portal `aria-hidden` — but `markOthers` concatenates
+  // `[aria-live],[role="status"],output` onto its keep-list, so a
+  // live region survives where it stands. That is load-bearing: it
+  // is why this region does not have to move inside the panel, and
+  // why it keeps `role="status"` rather than a bare `div`.
+  vitestExpect(region.closest("[aria-hidden='true']")).toBe(
+    null,
+  )
+  vitestExpect(region.closest("[inert]")).toBe(null)
+})
+
+test("a tall stack of toasts scrolls instead of climbing off the page", async () => {
+  const { body } = await mountStory(ManyAtOnce)
+
+  const region = expectAgentDrivable(body, {
+    name: "Notifications",
+    role: "status",
+  })
+
+  const list = region.querySelector("ul")
+
+  if (!list) {
+    throw new Error("the region should render a list")
+  }
+
+  // Bounded, so the column cannot grow past the viewport.
+  vitestExpect(list.scrollHeight).toBeGreaterThan(
+    list.clientHeight,
+  )
+  vitestExpect(
+    list.getBoundingClientRect().top,
+  ).toBeGreaterThanOrEqual(0)
+
+  // Taken to the far end on arrival: the newest toast is the one
+  // carrying the action, and it is the one at the bottom.
+  const newest = body.getByText("Rip 12 finished")
+
+  vitestExpect(
+    newest.getBoundingClientRect().bottom,
+  ).toBeLessThanOrEqual(
+    list.getBoundingClientRect().bottom + 1,
+  )
+
+  // And the oldest is reachable rather than clipped away. This is
+  // the assertion `justify-content: flex-end` fails: chromium does
+  // not make a flex container's start-edge overflow scrollable, so
+  // the toasts above the fold could not be reached at all.
+  list.scrollTop = 0
+
+  await waitFor(() => {
+    const oldest = body.getByText("Rip 1 finished")
+
+    vitestExpect(
+      oldest.getBoundingClientRect().top,
+    ).toBeGreaterThanOrEqual(
+      list.getBoundingClientRect().top - 1,
+    )
+  })
+})

package/src/Toast/ToastRegion.tsx

@@ -1,6 +1,8 @@
 import type { IntentName } from "@charcuterie/tokens"
 import type { ReactNode } from "react"
+import { useEffect, useRef } from "react"
 
+import { useOverlayStack } from "../Overlay/OverlayStack.tsx"
 import { toClassName } from "../toClassName.ts"
 import { Toast } from "./Toast.tsx"
 
@@ -52,47 +54,133 @@ export type ToastRegionProps = {
  * sync. The lifecycle *inside* one toast is state a store cannot
  * see, which is why `Toast` owns that and nothing more.
  *
+ * ### It is the top of the layer scale, and it moves to stay there
+ *
+ * ⚠️ The container was `z-50` — a hand-picked number, in the library
+ * whose whole point is that nobody picks one. It is
+ * `--layer-toast` now, the top of the scale, above `--layer-tooltip`.
+ * The owner's rule: *"I think toast should always exist on top of
+ * everything."*
+ *
+ * The open panels cascade — a modal over a modal paints at
+ * `--layer-modal + n` — so the depth is added here too, and the
+ * toast clears the whole stack rather than only its first floor.
+ * Both numbers come off `useOverlayStack`, so the ordering is
+ * arithmetic rather than portal-append order.
+ *
+ * ### Painting on top is only half of "on top"
+ *
+ * ⚠️ A press on a toast while a `Modal` is open is an **outside**
+ * press as far as floating-ui is concerned, and `useDismiss` would
+ * close the modal on the way to taking an action back. That is why
+ * the container carries `data-charcuterie-toast-region`:
+ * `OverlayPanel`'s `outsidePress` reads it and lets the press
+ * through. Nothing else in the fleet carries that attribute.
+ *
+ * ⚠️ Do **not** move this region inside the panel's portal to solve
+ * that. Two reasons, both measured. `FloatingFocusManager`'s `modal`
+ * already leaves it alone — `markOthers` concatenates
+ * `body.querySelectorAll('[aria-live],[role="status"],output')` onto
+ * its keep-list, and this region is a `role="status"`, so it is
+ * never marked `aria-hidden` where it stands. And the panel's
+ * container sets a z-index, so a region nested inside it would be
+ * trapped in that stacking context and lose to the *next* modal
+ * however high `--layer-toast` climbs.
+ *
  * ### `pointer-events-none` on the container, `auto` on each toast
  *
  * A fixed overlay across the bottom of the viewport swallows every
  * click in that band, including on the app behind it, and it does so
  * invisibly. The container passes clicks through and each toast
  * takes them back.
+ *
+ * The list keeps `pointer-events: none` and still scrolls: a wheel
+ * event over a toast chains to the nearest scrollable **ancestor**,
+ * which is the list, and hit-testing never has to reach it.
+ *
+ * ### Many at once, and the newest is the one you can see
+ *
+ * The column grows upward from the bottom of the viewport, so
+ * without a bound the oldest toasts climb off the top of the page —
+ * clipped by the viewport, and unreachable, because a fixed element
+ * is not something the page can scroll to. The list is capped at
+ * `min(60dvh, 32rem)` and scrolls `overscroll-contain`, so the page
+ * behind never moves because a notification arrived. The owner's
+ * rule: *"if you have multiple toasts, it should accomodate them
+ * somehow."*
+ *
+ * ⚠️ Bottom-pinned with `margin-block-start: auto` on the first
+ * toast, **not** `justify-content: flex-end`. Measured in chromium:
+ * with `justify-end` an overflowing list reports
+ * `scrollHeight === clientHeight` and the toasts above the fold
+ * cannot be scrolled to at all — content overflowing a flex
+ * container's *start* edge is not reachable overflow. An auto margin
+ * resolves to `0` the moment the free space runs out, so the same
+ * rule pins a short list and scrolls a long one.
+ *
+ * The scroll is taken to the bottom whenever the count changes,
+ * because the newest toast is the one with the action on it and it
+ * is the one at the far end.
  */
 export const ToastRegion = ({
   className,
   label = "Notifications",
   onDismiss,
   toasts,
-}: ToastRegionProps): ReactNode => (
-  <div
-    aria-label={label}
-    // `role="status"` is `aria-live="polite"` plus
-    // `aria-atomic="true"` by default — and atomic is wrong here,
-    // because it re-reads the entire stack every time one arrives.
-    // Spelling `aria-atomic="false"` next to it is what makes a
-    // second toast announce only itself.
-    aria-atomic="false"
-    className={toClassName(
-      "pointer-events-none fixed inset-x-0 bottom-0 z-50 flex flex-col items-center gap-2 p-4",
-      className,
-    )}
-    role="status"
-  >
-    <ul className="pointer-events-none flex w-full max-w-sm list-none flex-col gap-2 p-0">
-      {toasts.map((toast) => (
-        <Toast
-          duration={toast.duration}
-          intent={toast.intent}
-          key={toast.key}
-          onRemove={() => {
-            onDismiss(toast.key)
-          }}
-          title={toast.title}
-        >
-          {toast.description}
-        </Toast>
-      ))}
-    </ul>
-  </div>
-)
+}: ToastRegionProps): ReactNode => {
+  const { depth } = useOverlayStack()
+
+  const listRef = useRef<HTMLUListElement>(null)
+
+  const _toastCount = toasts.length
+
+  useEffect(() => {
+    const list = listRef.current
+
+    if (!list) {
+      return
+    }
+
+    list.scrollTop = list.scrollHeight
+  }, [])
+
+  return (
+    <div
+      aria-label={label}
+      data-charcuterie-toast-region=""
+      // `role="status"` is `aria-live="polite"` plus
+      // `aria-atomic="true"` by default — and atomic is wrong here,
+      // because it re-reads the entire stack every time one arrives.
+      // Spelling `aria-atomic="false"` next to it is what makes a
+      // second toast announce only itself.
+      aria-atomic="false"
+      className={toClassName(
+        "pointer-events-none fixed inset-x-0 bottom-0 flex flex-col items-center gap-2 p-4",
+        className,
+      )}
+      role="status"
+      style={{
+        zIndex: `calc(var(--layer-toast) + ${depth})`,
+      }}
+    >
+      <ul
+        ref={listRef}
+        className="charcuterie-scrollbar pointer-events-none flex max-h-[min(60dvh,32rem)] w-full max-w-sm list-none flex-col gap-2 overflow-y-auto overscroll-contain p-0 [&>li]:shrink-0 [&>li:first-child]:mt-auto"
+      >
+        {toasts.map((toast) => (
+          <Toast
+            duration={toast.duration}
+            intent={toast.intent}
+            key={toast.key}
+            onRemove={() => {
+              onDismiss(toast.key)
+            }}
+            title={toast.title}
+          >
+            {toast.description}
+          </Toast>
+        ))}
+      </ul>
+    </div>
+  )
+}

package/src/Toolbar/Toolbar.mdx

@@ -9,7 +9,7 @@ import * as ToolbarStories from "./Toolbar.stories";
 A row of controls that collapses into an overflow when it runs out of room — measured, not
 breakpointed, with **exactly one instance** of every control in the document.
 
-<Canvas of={ToolbarStories.Default} />
+<Canvas of={ToolbarStories.Playground} />
 
 ## Props