@charcuterie/ui 0.1.0 → 0.2.0

package/src/Toast/Toast.stories.tsx

@@ -0,0 +1,192 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import { intentArgType } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { Toast } from "./Toast.tsx"
+import type { ToastRecord } from "./ToastRegion.tsx"
+import { ToastRegion } from "./ToastRegion.tsx"
+
+const noop = () => undefined
+
+/**
+ * `duration={0}` throughout the boards. A toast that removes itself
+ * after five seconds makes a screenshot a race, and pinning it open
+ * is the documented way to hold one for an action anyway.
+ */
+const meta = {
+  title: "Components/Toast",
+  component: Toast,
+  parameters: { layout: "padded" },
+  argTypes: { intent: intentArgType },
+  args: {
+    duration: 0,
+    intent: "neutral",
+    onRemove: noop,
+    title: "Rip finished",
+  },
+} satisfies Meta<typeof Toast>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const ToastList = ({
+  children,
+}: {
+  children: ReactNode
+}): ReactNode => (
+  <ul className="flex w-full max-w-sm list-none flex-col gap-2 p-0">
+    {children}
+  </ul>
+)
+
+export const Default: Story = {
+  args: {
+    children: "Blade Runner (1982) · 9 titles.",
+    title: "Rip finished",
+  },
+  render: (args) => (
+    <ToastList>
+      <Toast {...args} />
+    </ToastList>
+  ),
+}
+
+export const AllVariants: Story = {
+  args: { title: "Rip finished" },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="success">
+        <ToastList>
+          <Toast
+            duration={0}
+            intent="success"
+            onRemove={noop}
+            title="Rip finished"
+          >
+            Blade Runner (1982) · 9 titles.
+          </Toast>
+        </ToastList>
+      </StoryCell>
+
+      <StoryCell label="warning">
+        <ToastList>
+          <Toast
+            duration={0}
+            intent="warning"
+            onRemove={noop}
+            title="Retried title 4"
+          >
+            Two read errors, recovered.
+          </Toast>
+        </ToastList>
+      </StoryCell>
+
+      <StoryCell label="danger">
+        <ToastList>
+          <Toast
+            duration={0}
+            intent="danger"
+            onRemove={noop}
+            title="Bay 3 offline"
+          />
+        </ToastList>
+      </StoryCell>
+
+      <StoryCell label="no description">
+        <ToastList>
+          <Toast
+            duration={0}
+            intent="info"
+            onRemove={noop}
+            title="Order saved"
+          />
+        </ToastList>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * The lifecycle, laid out. `entering` and `exiting` are both
+ * *painted* states — a toast that is leaving still occupies its
+ * slot — which is exactly what a boolean cannot express and why
+ * this is a `Status`.
+ */
+export const AllStates: Story = {
+  args: { title: "Rip finished" },
+  render: () => (
+    <ToastList>
+      <Toast
+        duration={0}
+        intent="success"
+        onRemove={noop}
+        title="Pinned open"
+      >
+        `duration={0}` — stays until dismissed, which is
+        what a toast carrying an action has to do.
+      </Toast>
+
+      <Toast
+        duration={60_000}
+        intent="info"
+        onRemove={noop}
+        title="Timed"
+      >
+        Hovering pauses it, which is why `exiting → visible`
+        is a legal transition.
+      </Toast>
+    </ToastList>
+  ),
+}
+
+/**
+ * The region, doing its actual job. Add a few and watch them stack;
+ * each removes itself when its own machine reaches `removed`, and
+ * the list belongs to the app rather than to this library.
+ */
+export const Interactive: Story = {
+  args: { title: "Rip finished" },
+  render: function InteractiveRegion() {
+    const [toasts, setToasts] = useState<ToastRecord[]>([])
+
+    const [count, setCount] = useState(0)
+
+    return (
+      <>
+        <Button
+          onClick={() => {
+            setCount((previous) => previous + 1)
+
+            setToasts((previous) => [
+              ...previous,
+              {
+                description: `Bay ${count + 1} finished.`,
+                intent: "success",
+                key: `rip-${count}`,
+                title: `Rip ${count + 1} finished`,
+              },
+            ])
+          }}
+        >
+          Finish a rip
+        </Button>
+
+        <ToastRegion
+          onDismiss={(key) => {
+            setToasts((previous) =>
+              previous.filter((one) => one.key !== key),
+            )
+          }}
+          toasts={toasts}
+        />
+      </>
+    )
+  },
+}

package/src/Toast/Toast.test.tsx

@@ -0,0 +1,217 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test, expect as vitestExpect } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Toast.stories.tsx"
+import { toastTransitions } from "./toastLifecycle.ts"
+
+const { AllStates, AllVariants, Default, Interactive } =
+  composeStories(stories)
+
+/**
+ * The illegal transitions are the specification, so they are
+ * asserted as a property of the table rather than by trying to drive
+ * a component into a state it refuses to enter.
+ */
+test("a toast cannot skip its exit, and `removed` is terminal", () => {
+  // Skipping straight to `removed` is the flicker every hand-rolled
+  // toast stack has: the node disappears mid-animation.
+  vitestExpect(toastTransitions.visible).not.toContain(
+    "removed",
+  )
+
+  // Terminal, which is what lets the region call `onDismiss`
+  // exactly once. `createStatus` throws on an illegal transition, so
+  // a second timer firing after the first is a loud failure rather
+  // than a duplicate removal.
+  vitestExpect(toastTransitions.removed).toEqual([])
+
+  // And the one that looks like an oddity until you know why:
+  // pointing at a toast that is already sliding away has to bring
+  // it back, or the user is chasing a disappearing message.
+  vitestExpect(toastTransitions.exiting).toContain(
+    "visible",
+  )
+})
+
+test("the region names itself, and does not re-read the stack", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Finish a rip",
+      role: "button",
+    }),
+  )
+
+  const region = expectAgentDrivable(canvas, {
+    name: "Notifications",
+    role: "status",
+  })
+
+  // `role="status"` is polite *and atomic by default*, and atomic is
+  // wrong here — it re-reads the entire stack every time one
+  // arrives. Spelling `false` beside it is what makes a second toast
+  // announce only itself.
+  await expect(region).toHaveAttribute(
+    "aria-atomic",
+    "false",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("each toast's dismiss button is named for its own toast", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  // A stack of three all offering "Dismiss" gives one query three
+  // matches, which `expectAgentDrivable` treats as a failure —
+  // correctly, since an agent would be picking one at random. This
+  // is why `title` is a string rather than a `ReactNode`.
+  expectAgentDrivable(canvas, {
+    name: "Dismiss Pinned open",
+    role: "button",
+  })
+
+  expectAgentDrivable(canvas, {
+    name: "Dismiss Timed",
+    role: "button",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("dismissing runs the exit and then removes, once", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Finish a rip",
+      role: "button",
+    }),
+  )
+
+  const dismiss = await waitFor(() =>
+    expectAgentDrivable(canvas, {
+      name: "Dismiss Rip 1 finished",
+      role: "button",
+    }),
+  )
+
+  await userEvent.click(dismiss)
+
+  // It leaves through `exiting`, so it is still in the DOM for the
+  // exit duration — and then gone. `onDismiss` firing twice would
+  // throw inside `createStatus` rather than removing a second toast.
+  await waitFor(() => {
+    expect(
+      canvas.queryAllByRole("button", {
+        name: "Dismiss Rip 1 finished",
+      }),
+    ).toHaveLength(0)
+  })
+})
+
+/**
+ * The enter frame is scheduled once and never cancelled — `is` and
+ * `transitionTo` are stable, so the effect that schedules it does not
+ * re-run when the status changes. Dismissing before that frame lands
+ * is therefore a real race, and it lost: `exiting → visible` is legal
+ * (hover-to-pause needs it), so the frame put the dismissed toast
+ * back and restarted its five-second duration.
+ *
+ * Holding the frame is what makes that deterministic. Left to real
+ * timing it reproduces only under load, which is how it first
+ * appeared — as a different test failing, once, in a full run.
+ */
+test("a dismiss during the enter frame is not undone by it", async () => {
+  const heldFrames: FrameRequestCallback[] = []
+
+  const realRequestAnimationFrame =
+    globalThis.requestAnimationFrame
+
+  globalThis.requestAnimationFrame = ((
+    callback: FrameRequestCallback,
+  ) => {
+    heldFrames.push(callback)
+
+    return 0
+  }) as typeof globalThis.requestAnimationFrame
+
+  const { canvas } = await mountStory(Interactive)
+
+  try {
+    await userEvent.click(
+      expectAgentDrivable(canvas, {
+        name: "Finish a rip",
+        role: "button",
+      }),
+    )
+
+    const dismiss = await waitFor(() =>
+      expectAgentDrivable(canvas, {
+        name: "Dismiss Rip 1 finished",
+        role: "button",
+      }),
+    )
+
+    await userEvent.click(dismiss)
+
+    for (const frame of heldFrames.splice(0)) {
+      frame(globalThis.performance.now())
+    }
+  } finally {
+    globalThis.requestAnimationFrame =
+      realRequestAnimationFrame
+  }
+
+  await waitFor(() => {
+    expect(
+      canvas.queryAllByRole("button", {
+        name: "Dismiss Rip 1 finished",
+      }),
+    ).toHaveLength(0)
+  })
+})
+
+test("a pinned toast stays put", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const dismiss = expectAgentDrivable(canvas, {
+    name: "Dismiss Rip finished",
+    role: "button",
+  })
+
+  // `duration={0}` is WCAG 2.2.1's answer for a toast carrying an
+  // action: a moving deadline the user cannot meet is not a
+  // deadline, it is a disappearing message.
+  await new Promise((resolve) => {
+    globalThis.setTimeout(resolve, 300)
+  })
+
+  await expect(dismiss).toBeInTheDocument()
+})
+
+test("intent is a semantic role, not a colour", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllVariants)
+
+  // Four toasts, four intents, four distinct names — the board is
+  // one proposition (every intent renders) rather than four
+  // assertions, which is the distinction M4's review settled.
+  for (const name of [
+    "Dismiss Rip finished",
+    "Dismiss Retried title 4",
+    "Dismiss Bay 3 offline",
+    "Dismiss Order saved",
+  ]) {
+    expectAgentDrivable(canvas, { name, role: "button" })
+  }
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/Toast/Toast.tsx

@@ -0,0 +1,224 @@
+import { useStatus } from "@charcuterie/logic"
+import type { IntentName } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+import { useEffect, useRef } from "react"
+
+import { IconButton } from "../IconButton/IconButton.tsx"
+import {
+  INTENT_APPEARANCE_CLASS,
+  INTENT_CONTENT_CLASS,
+} from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import type { ToastStatus } from "./toastLifecycle.ts"
+import { toastTransitions } from "./toastLifecycle.ts"
+
+export type ToastProps = {
+  /** Detail under the title. Optional — many toasts are one line. */
+  children?: ReactNode
+  className?: string
+  /**
+   * Milliseconds at `visible` before it starts leaving. `0` pins it
+   * open, which is what a toast carrying an action has to do — WCAG
+   * 2.2.1 gives a user the right to finish reading.
+   */
+  duration?: number
+  /** How long `exiting` lasts, matched to the transition below. */
+  exitDuration?: number
+  intent?: IntentName
+  /** Called once, when the machine reaches its terminal state. */
+  onRemove: () => void
+  /**
+   * A string, not a `ReactNode`. It is what the region announces and
+   * what names this toast's own dismiss button — a stack of three
+   * toasts all offering "Dismiss" is three matches for one query,
+   * which `expectAgentDrivable` treats as a failure.
+   */
+  title: string
+}
+
+const ENTER_CLASS: Record<ToastStatus, string> = {
+  entering: "translate-y-2 opacity-0",
+  exiting: "translate-y-1 opacity-0",
+  removed: "opacity-0",
+  visible: "translate-y-0 opacity-100",
+}
+
+/**
+ * One toast, and its whole job is the four-state machine the plan
+ * specified and M2 left unbuilt.
+ *
+ * ### Why a `Status`, when a boolean and a timeout would do
+ *
+ * Because a boolean cannot express *why* the node is still mounted.
+ * A toast that is leaving is still painted, still occupies its slot,
+ * and must not be announced again — and `isVisible === false` says
+ * none of that. The states are what a reader needs to know the
+ * difference between "arriving", "leaving", and "gone but not yet
+ * unmounted", and `createStatus` makes the illegal ones throw:
+ * `visible → removed` skips the exit and is rejected, and `removed`
+ * is terminal so a late timer cannot remove the same toast twice.
+ *
+ * That last one is not hypothetical. Hover-to-pause plus a dismiss
+ * button means two independent timers can be in flight, and the
+ * hand-rolled version of this component reconciles them with a
+ * `clearTimeout` and a ref. Here the second one throws.
+ *
+ * ### It does not announce itself
+ *
+ * No `role="status"` and no `aria-live` on this element — the
+ * `ToastRegion` around it owns that, and a live region inside a live
+ * region is a message announced twice. See that component for the
+ * reason there is only ever one, and it is polite.
+ */
+export const Toast = ({
+  children,
+  className,
+  duration = 5000,
+  exitDuration = 200,
+  intent = "neutral",
+  onRemove,
+  title,
+}: ToastProps): ReactNode => {
+  const { is, status, transitionTo } =
+    useStatus<ToastStatus>({
+      initialState: "entering",
+      transitions: toastTransitions,
+    })
+
+  const onRemoveRef = useRef(onRemove)
+
+  onRemoveRef.current = onRemove
+
+  useEffect(() => {
+    if (!is("entering")) {
+      return
+    }
+
+    // A frame, not zero. The element has to be painted in its
+    // `entering` position before the class changes, or the browser
+    // coalesces both into one style recalculation and there is no
+    // transition to see — the single most common reason a CSS
+    // enter-animation "does nothing".
+    const frame = globalThis.requestAnimationFrame(() => {
+      // Guarded, because `is` and `transitionTo` are stable — this
+      // effect runs once, so the frame is *not* cancelled when the
+      // status changes underneath it. A dismiss during the enter
+      // frame moves the toast to `exiting`, and `exiting → visible`
+      // is a legal transition (it is how hover-to-pause works), so
+      // an unguarded write here brings a dismissed toast straight
+      // back and restarts its duration timer.
+      if (is("entering")) {
+        transitionTo("visible")
+      }
+    })
+
+    return () => {
+      globalThis.cancelAnimationFrame(frame)
+    }
+  }, [is, transitionTo])
+
+  useEffect(() => {
+    if (status !== "visible" || duration === 0) {
+      return
+    }
+
+    const timer = globalThis.setTimeout(() => {
+      transitionTo("exiting")
+    }, duration)
+
+    return () => {
+      globalThis.clearTimeout(timer)
+    }
+  }, [duration, status, transitionTo])
+
+  useEffect(() => {
+    if (status !== "exiting") {
+      return
+    }
+
+    const timer = globalThis.setTimeout(() => {
+      transitionTo("removed")
+    }, exitDuration)
+
+    return () => {
+      globalThis.clearTimeout(timer)
+    }
+  }, [exitDuration, status, transitionTo])
+
+  useEffect(() => {
+    if (status === "removed") {
+      onRemoveRef.current()
+    }
+  }, [status])
+
+  return (
+    <li
+      className={toClassName(
+        "pointer-events-auto flex items-start gap-3 rounded-md border p-3 shadow-medium transition-[opacity,transform] duration-(--duration-normal) ease-standard",
+        INTENT_APPEARANCE_CLASS[intent].soft,
+        ENTER_CLASS[status],
+        className,
+      )}
+      // Pausing on hover is WCAG 2.2.1's "pause" for a moving
+      // deadline, and it is the reason `exiting → visible` is a
+      // legal transition rather than an oddity in the table.
+      onMouseEnter={() => {
+        if (status === "exiting") {
+          transitionTo("visible")
+        }
+      }}
+    >
+      <div className="flex min-w-0 flex-col gap-0.5">
+        <span
+          className={toClassName(
+            "font-medium text-sm",
+            INTENT_CONTENT_CLASS[intent],
+          )}
+        >
+          {title}
+        </span>
+
+        {children === undefined ? null : (
+          <span className="text-content-secondary text-xs">
+            {children}
+          </span>
+        )}
+      </div>
+
+      <IconButton
+        appearance="ghost"
+        className="ms-auto shrink-0"
+        // The name has to be distinct per toast, or a stack of three
+        // gives `getByRole("button", { name: "Dismiss" })` three
+        // matches and `expectAgentDrivable` fails the story — which
+        // is the point of that helper: an agent picking one of three
+        // at random is worse than finding none.
+        label={`Dismiss ${title}`}
+        onClick={() => {
+          if (
+            status !== "exiting" &&
+            status !== "removed"
+          ) {
+            transitionTo("exiting")
+          }
+        }}
+        size="sm"
+      >
+        <svg
+          aria-hidden="true"
+          className="size-[1.15em] shrink-0"
+          fill="none"
+          focusable={false}
+          stroke="currentColor"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth={1.75}
+          viewBox="0 0 24 24"
+          xmlns="http://www.w3.org/2000/svg"
+        >
+          <path d="m6 6 12 12M18 6 6 18" />
+        </svg>
+      </IconButton>
+    </li>
+  )
+}