@charcuterie/ui 4.5.1 → 4.7.0

package/src/Overlay/OverlayPanel.tsx

@@ -117,13 +117,55 @@ export const OverlayPanel = ({
       // `outsidePress` on a *lower* modal would close it too, so it is
       // scoped to the top — which is also why the scrim needs no click
       // handler of its own.
-      outsidePress: isDismissable && isTop,
+      outsidePress: (event) => {
+        if (!isDismissable || !isTop) return false
+        /*
+         * ⚠️ A press on a toast is NOT an outside press.
+         *
+         * A `ToastRegion` renders in the page, so floating-ui sees a
+         * press on its Undo as a press outside the floating element
+         * — and closing the modal on the way to taking an action
+         * back is the opposite of what the button says. The region
+         * marks itself with `data-charcuterie-toast-region`; nothing
+         * else in the fleet carries that attribute.
+         *
+         * ⚠️ Do not delete this on the evidence of a small story.
+         * floating-ui has a *second*, accidental guard that hides
+         * this one: `closeOnPressOutside` bails out early when the
+         * press target's body-level ancestor contains none of the
+         * `[data-floating-ui-inert]` markers `markOthers` left
+         * behind, on the theory that such an element was injected
+         * after the panel opened. A page that is nothing but a
+         * region takes that branch and never reaches this predicate
+         * at all. A page with content beside the region — every real
+         * app — does reach it. `Toast.stories.tsx`'s
+         * `OverStackedModals` carries a heading and a paragraph for
+         * exactly that reason, and `ToastRegion.test.tsx` fails
+         * without this predicate only because they are there.
+         */
+        const target = event.target as Element | null
+        return (
+          target?.closest?.(
+            "[data-charcuterie-toast-region]",
+          ) == null
+        )
+      },
     }),
     useRole(context, { role }),
   ])
 
   const { register, unregister } = stack
 
+  /**
+   * Where this panel sits in the stack, and therefore how far above
+   * `--layer-modal` it paints. `0` when unprovided — a lone `Modal`
+   * is the only thing open.
+   */
+  const stackIndex = Math.max(
+    stack.orderedIds.indexOf(id),
+    0,
+  )
+
   useEffect(() => {
     if (!isVisible) {
       return
@@ -169,7 +211,26 @@ export const OverlayPanel = ({
       )}
 
       <FloatingPortal>
-        <div className="fixed inset-0 z-[var(--layer-modal)] flex items-center justify-center">
+        <div
+          className="fixed inset-0 flex items-center justify-center"
+          /*
+           * ⚠️ Cascading, not one shared layer.
+           *
+           * Every panel used to render at the one `--layer-modal`, and
+           * which of two open modals painted on top fell out of the
+           * order their portals happened to be appended in. A modal
+           * opened from inside another is the case that made this
+           * visible. The index in the stack is the answer the stack
+           * already knows.
+           *
+           * The scale's gaps are 100, so a cascade this deep is
+           * arithmetic nobody has to think about — and the toast sits
+           * at `--layer-toast` plus the same depth, above all of it.
+           */
+          style={{
+            zIndex: `calc(var(--layer-modal) + ${stackIndex})`,
+          }}
+        >
           <FloatingFocusManager
             context={context}
             // `undefined` keeps the manager's own default (the first

package/src/Overlay/OverlayStack.tsx

@@ -40,6 +40,11 @@ export type OverlayStackEntry = {
 
 export type OverlayStackValue = {
   depth: number
+  /**
+   * The open ids, oldest first. A panel reads its own index out of
+   * this to cascade its z-index above the one below it.
+   */
+  orderedIds: string[]
   /**
    * `false` in the context default. An `OverlayPanel` reads this to
    * decide whether to render its own scrim (unprovided) or defer to
@@ -56,6 +61,7 @@ export type OverlayStackValue = {
 const DEFAULT_STACK: OverlayStackValue = {
   depth: 0,
   isProvided: false,
+  orderedIds: [],
   register: () => {},
   requestCloseTop: () => {},
   topId: null,
@@ -76,7 +82,6 @@ export const OverlayStackProvider = ({
   const [entries, setEntries] = useState<
     OverlayStackEntry[]
   >([])
-
   // Read through a ref so `requestCloseTop` stays stable while still
   // seeing the live top.
   const entriesRef = useLatestRef(entries)
@@ -112,6 +117,7 @@ export const OverlayStackProvider = ({
     () => ({
       depth: entries.length,
       isProvided: true,
+      orderedIds: entries.map((one) => one.id),
       register,
       requestCloseTop,
       topId: entries.at(-1)?.id ?? null,

package/src/Toast/Toast.stories.tsx

@@ -9,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"
@@ -192,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/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>
+  )
+}