@charcuterie/ui 0.1.1 → 1.0.0

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>
+  )
+}

package/src/Toast/ToastRegion.tsx

@@ -0,0 +1,98 @@
+import type { IntentName } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+
+import { toClassName } from "../toClassName.ts"
+import { Toast } from "./Toast.tsx"
+
+export type ToastRecord = {
+  description?: ReactNode
+  /** `0` pins this one open. See `Toast`'s `duration`. */
+  duration?: number
+  intent?: IntentName
+  key: string
+  title: string
+}
+
+export type ToastRegionProps = {
+  className?: string
+  /**
+   * The region's accessible name. `role="status"` takes **none from
+   * its content** — the trap `Spinner` walked into in M3 and
+   * `Popover` in M4.
+   */
+  label?: string
+  onDismiss: (key: string) => void
+  toasts: ToastRecord[]
+}
+
+/**
+ * The live region, and the list is the caller's.
+ *
+ * ### One region, and it is polite
+ *
+ * Not two. The usual arrangement — a polite region and an assertive
+ * one, so a danger toast interrupts — was rejected because the
+ * interrupting case does not belong in a toast at all. A message
+ * that must be heard *now* is one the user has to be able to go back
+ * and read, and a toast is gone in five seconds; if it matters that
+ * much it is an `Alert` on the page, which this library already
+ * ships and which stays put.
+ *
+ * That is the same line `Field` draws for its error text, and it is
+ * worth keeping the two consistent: **this library announces once,
+ * in the place the user can act on it.**
+ *
+ * ### The stack does not own the toasts
+ *
+ * `toasts` comes in and `onDismiss` goes out — there is no
+ * `toast()` function, no imperative queue, and no context provider.
+ * An app already has a store (mux-magic has Jotai, rip-deck has its
+ * own), and a component library that ships a second one is asking
+ * every consumer to keep two lists of the same notifications in
+ * sync. The lifecycle *inside* one toast is state a store cannot
+ * see, which is why `Toast` owns that and nothing more.
+ *
+ * ### `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.
+ */
+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>
+)

package/src/Toast/toastLifecycle.ts

@@ -0,0 +1,45 @@
+import type { StatusTransitions } from "@charcuterie/logic"
+
+/**
+ * The one machine the plan wrote down and M2 did not build:
+ *
+ * > | Toast lifecycle | entering → visible → exiting → removed |
+ *
+ * It is here rather than in `@charcuterie/logic/core` beside
+ * `asyncTransitions` and `connectionTransitions` on purpose. Those
+ * two describe *data* — a fetch, a socket — and a Preact app with no
+ * components at all still wants them. This one describes an
+ * **animation**, which only exists because something is being
+ * painted, so it belongs to the component layer.
+ */
+export type ToastStatus =
+  | "entering"
+  | "exiting"
+  | "removed"
+  | "visible"
+
+/**
+ * `visible → removed` is deliberately **not** a legal transition,
+ * and neither is anything out of `removed`.
+ *
+ * The first means a toast cannot skip its exit — a dismissal that
+ * unmounts the node immediately is the flicker every hand-rolled
+ * toast stack has, and making it illegal turns that into a thrown
+ * error in a test rather than a jump nobody files.
+ *
+ * The second makes `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 instead of a duplicate removal.
+ *
+ * `exiting → visible` **is** legal: pointing at a toast that is
+ * already sliding away has to bring it back, or the user is chasing
+ * a disappearing message with the cursor.
+ */
+export const toastTransitions: StatusTransitions<ToastStatus> =
+  {
+    entering: ["visible", "exiting"],
+    exiting: ["removed", "visible"],
+    removed: [],
+    visible: ["exiting"],
+  }

package/src/Tooltip/Tooltip.mdx

@@ -0,0 +1,69 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as TooltipStories from "./Tooltip.stories";
+
+<Meta of={TooltipStories} />
+
+# Tooltip
+
+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} />
+
+## Props
+
+<Controls />
+
+## Three defects, all of which render perfectly
+
+1. **Nothing references the tip.** It sets `role="tooltip"` and no `aria-describedby`
+   anywhere, so the control it belongs to never mentions it. `role="tooltip"` is **not** a
+   live region and does nothing on its own — the tip is a floating node nobody is pointed
+   at.
+2. **Pointer only.** `onPointerEnter`/`onPointerLeave` with no `onFocus`/`onBlur`, so a
+   keyboard user cannot open it at all. WCAG 2.1.1.
+3. **No dismiss.** Escape does nothing, which WCAG 1.4.13 requires of any content shown on
+   hover.
+
+All three come from the same place: **the ARIA is written by hand beside the behaviour
+instead of falling out of it.** Here `useRole` writes `aria-describedby` on the trigger and
+`role` + `id` on the tip from one source, `useFocus` is what makes it keyboard-openable, and
+`useDismiss` is Escape.
+
+<Canvas of={TooltipStories.AllVariants} />
+
+## A tooltip adds; it is never the name
+
+| | may be the only place the text exists | why |
+| --- | --- | --- |
+| `aria-label` | **yes** | it *is* the name |
+| `Field` `description` | **yes** | bound with `aria-describedby`, read on focus |
+| `Badge`'s `title` | no | repeats text already in `textContent` |
+| `Tooltip` | **no** | absent on touch, absent when nothing hovers |
+
+An `IconButton` under a tooltip still carries its own `aria-label`. `AllVariants` proves the
+button stays findable by the same query whether or not the tip is open.
+
+## No `popover` and no focus manager
+
+Unlike `Popover`, which is in the top layer and traps nothing. Focus never enters a tooltip
+— moving it there is what makes one inescapable — so there is no `FloatingFocusManager` and
+no `popover="manual"`.
+
+The trade is real and worth stating: a tooltip is therefore **not** in the top layer and can
+be clipped by an `overflow: hidden` ancestor. `strategy: "fixed"` keeps that to ancestors
+which actually clip fixed descendants.
+
+<Canvas of={TooltipStories.AllStates} />
+
+## Touch has no hover, and this does not pretend otherwise
+
+There is no long-press fallback. A tooltip is supplementary by construction, so on the kiosk
+it simply never appears — and anything a touch user *must* read belongs in a `Field`'s
+`description` instead.
+
+Building a long-press would make the tip load-bearing on exactly the surface where it is
+least reliable.
+
+<Canvas of={TooltipStories.Interactive} />