@charcuterie/ui 0.1.1 → 0.2.0

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} />

package/src/Tooltip/Tooltip.stories.tsx

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { placementArgType } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { IconButton } from "../IconButton/IconButton.tsx"
+import { SettingsIcon } from "../icons.storyHelpers.tsx"
+import { Tooltip } from "./Tooltip.tsx"
+
+const meta = {
+  title: "Components/Tooltip",
+  component: Tooltip,
+  parameters: { layout: "centered" },
+  argTypes: { placement: placementArgType },
+  args: {
+    delay: 200,
+    label: "Re-reads the disc from title 1.",
+    placement: "top",
+  },
+} satisfies Meta<typeof Tooltip>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    children: <Button appearance="outline">Retry</Button>,
+    label: "Re-reads the disc from title 1.",
+  },
+}
+
+/**
+ * A tooltip **adds**; it never *is* the name. The icon button below
+ * still carries its own `aria-label` — the tip is the sentence you
+ * would otherwise have had no room for.
+ */
+export const AllVariants: Story = {
+  args: {
+    children: <Button appearance="outline">Retry</Button>,
+    label: "Re-reads the disc from title 1.",
+  },
+  render: () => (
+    <StoryGrid columns={3}>
+      <StoryCell label="on a button">
+        <Tooltip label="Re-reads the disc from title 1.">
+          <Button appearance="outline">Retry</Button>
+        </Tooltip>
+      </StoryCell>
+
+      <StoryCell label="on an IconButton">
+        <Tooltip label="Opens the bay's rip settings.">
+          <IconButton label="Bay settings">
+            <SettingsIcon />
+          </IconButton>
+        </Tooltip>
+      </StoryCell>
+
+      <StoryCell label="placed below">
+        <Tooltip
+          label="Skips this title and carries on."
+          placement="bottom"
+        >
+          <Button appearance="outline">Skip</Button>
+        </Tooltip>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Closed until something asks for it. There is no "open" prop: a
+ * tooltip's visibility is entirely a consequence of hover or focus,
+ * which is the one piece of state in this library a consumer has no
+ * business holding.
+ */
+export const AllStates: Story = {
+  args: {
+    children: (
+      <Button appearance="outline">
+        Hover or Tab to me
+      </Button>
+    ),
+    label: "Re-reads the disc from title 1.",
+  },
+}
+
+/**
+ * Tab to the button. The tip opens **on focus** — the line
+ * mux-magic's `FieldTooltip` is missing, which makes its version
+ * pointer-only and a WCAG 2.1.1 failure on the control whose
+ * explanation lives there. Escape closes it, per WCAG 1.4.13.
+ */
+export const Interactive: Story = {
+  args: {
+    children: (
+      <Button appearance="outline">Keyboard tip</Button>
+    ),
+    label: "Opened by focus, closed by Escape.",
+  },
+}

package/src/Tooltip/Tooltip.test.tsx

@@ -0,0 +1,138 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Tooltip.stories.tsx"
+
+const { AllVariants, Default, Interactive } =
+  composeStories(stories)
+
+test("nothing is shown until something asks", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  expectAgentDrivable(canvas, {
+    name: "Retry",
+    role: "button",
+  })
+
+  await expect(
+    canvas.queryAllByRole("tooltip"),
+  ).toHaveLength(0)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The defect that matters most in mux-magic's `FieldTooltip`: it
+ * renders `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.
+ */
+test("the trigger is described by the tip that opened", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Keyboard tip",
+    role: "button",
+  })
+
+  await expect(trigger).not.toHaveAttribute(
+    "aria-describedby",
+  )
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expect(trigger).toHaveFocus()
+  })
+
+  const tip = await waitFor(() =>
+    expectAgentDrivable(canvas, { role: "tooltip" }),
+  )
+
+  await expect(trigger).toHaveAttribute(
+    "aria-describedby",
+    tip.id,
+  )
+
+  await expect(tip).toHaveTextContent(
+    "Opened by focus, closed by Escape.",
+  )
+
+  // Audited in the *driven* state, not at mount. The a11y addon
+  // runs axe once, when `run()` resolves — before anything has been
+  // focused — so an open tip would never be seen by it.
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * Focus, not just hover. `useFocus` is the line mux-magic is
+ * missing, and without it the tip is pointer-only — a WCAG 2.1.1
+ * failure on the one control whose explanation lives there.
+ */
+test("focus opens it and blur closes it", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expectAgentDrivable(canvas, { role: "tooltip" })
+  })
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expect(canvas.queryAllByRole("tooltip")).toHaveLength(0)
+  })
+})
+
+test("Escape dismisses it", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  await userEvent.tab()
+
+  await waitFor(() => {
+    expectAgentDrivable(canvas, { role: "tooltip" })
+  })
+
+  // WCAG 1.4.13 requires content shown on hover or focus to be
+  // dismissable without moving the pointer or the caret.
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(canvas.queryAllByRole("tooltip")).toHaveLength(0)
+  })
+})
+
+/**
+ * A tooltip **adds**; it is never the name. An `IconButton` still
+ * carries its own `aria-label`, and the tip is the sentence there
+ * was no room for — so the button stays findable by the same query
+ * whether or not the tip is open.
+ */
+test("the tip does not become the control's name", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  const iconButton = expectAgentDrivable(canvas, {
+    name: "Bay settings",
+    role: "button",
+  })
+
+  await userEvent.hover(iconButton)
+
+  await waitFor(() => {
+    expectAgentDrivable(canvas, { role: "tooltip" })
+  })
+
+  // Still "Bay settings", not "Opens the bay's rip settings."
+  expectAgentDrivable(canvas, {
+    name: "Bay settings",
+    role: "button",
+  })
+})

package/src/Tooltip/Tooltip.tsx

@@ -0,0 +1,169 @@
+import {
+  useClonedChild,
+  useVisibility,
+} from "@charcuterie/logic"
+import type { Placement } from "@floating-ui/react"
+import {
+  autoUpdate,
+  flip,
+  offset,
+  shift,
+  useDismiss,
+  useFloating,
+  useFocus,
+  useHover,
+  useInteractions,
+  useRole,
+} from "@floating-ui/react"
+import type { ReactElement, ReactNode } from "react"
+
+import { toClassName } from "../toClassName.ts"
+
+export type TooltipProps = {
+  /**
+   * The control the tip describes. **Cloned, not wrapped** — the
+   * same slot contract as `Popover`'s trigger.
+   *
+   * It has to be something focusable. A tooltip on a `<span>` is
+   * pointer-only, which is the state mux-magic's is in today.
+   */
+  children: ReactElement
+  className?: string
+  /** Milliseconds of hover before it opens. */
+  delay?: number
+  /**
+   * Text, and text only. `role="tooltip"` has no way to move focus
+   * into itself, so a link or a button inside one is unreachable by
+   * keyboard and unreadable by touch — if it needs a control, it is
+   * a `Popover`.
+   */
+  label: string
+  placement?: Placement
+}
+
+/**
+ * Replaces mux-magic's `FieldTooltip`, which is 130 lines of
+ * hand-rolled positioning — a `computePosition` that reimplements
+ * `flip` and `shift` against `window.innerHeight` — and has three
+ * defects that all 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. A screen reader reads the button, says
+ *     nothing about the tip, and the tip itself is a floating node
+ *     nobody is pointed at. `role="tooltip"` is not a live region;
+ *     it does nothing on its own.
+ *  2. **Pointer only.** `onPointerEnter`/`onPointerLeave` with no
+ *     `onFocus`/`onBlur`, so a keyboard user cannot open it at all.
+ *  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.
+ *
+ * ### Not a `title`, and not a substitute for a name
+ *
+ * A `title` attribute is unstyleable, has a ~1s delay nobody can
+ * change, and does not exist on touch. `Badge` still uses one — for
+ * a *truncation* readout, where the full text is already in
+ * `textContent` and the tip is a convenience
+ * ([decision](../../../docs/decisions/2026-07-30-a-badge-truncates-with-text-overflow.md)).
+ * That is the line: a `title` may repeat something already
+ * available, and a `Tooltip` may add something, but **neither may be
+ * the only place a control's name exists**. An icon button still
+ * needs its `aria-label`; the tip is extra.
+ *
+ * ### Touch has no hover, and this component does not pretend
+ *
+ * There is no long-press fallback here. 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.
+ */
+export const Tooltip = ({
+  children,
+  className,
+  delay = 200,
+  label,
+  placement = "top",
+}: TooltipProps): ReactNode => {
+  const { isVisible, setIsVisible } = useVisibility()
+
+  const { context, floatingStyles, refs } = useFloating({
+    // Read-only, as everywhere: floating-ui is told what is true and
+    // never decides it.
+    open: isVisible,
+    onOpenChange: setIsVisible,
+    placement,
+    middleware: [offset(6), flip(), shift({ padding: 8 })],
+    strategy: "fixed",
+    whileElementsMounted: autoUpdate,
+  })
+
+  const { getFloatingProps, getReferenceProps } =
+    useInteractions([
+      useHover(context, {
+        // `move: false` — a tooltip that re-opens because the
+        // pointer twitched inside the trigger is the flicker every
+        // hand-rolled one has.
+        move: false,
+        restMs: delay,
+      }),
+      // The line mux-magic is missing. Without it the tip is
+      // pointer-only, which is a WCAG 2.1.1 failure on a control
+      // whose explanation lives there.
+      useFocus(context),
+      useDismiss(context, { referencePress: false }),
+      useRole(context, { role: "tooltip" }),
+    ])
+
+  const clonedTrigger = useClonedChild(children, {
+    ...getReferenceProps(),
+    ref: refs.setReference,
+  })
+
+  return (
+    <>
+      {clonedTrigger}
+
+      {isVisible ? (
+        <div
+          {...getFloatingProps()}
+          className={toClassName(
+            // `intent-neutral-solid` + its own `on-solid`, rather
+            // than `surface-inverse` + `content-on-accent`. The
+            // second pair looks like the obvious one and is not a
+            // *pair* at all — nothing in the token set promises those
+            // two contrast, and in `daylight` dark they land at
+            // 2.9:1. The `solid`/`on-solid` roles exist precisely to
+            // be a guaranteed couple, and the contrast gate checks
+            // them as one.
+            "inset-auto m-0 max-w-xs rounded-md bg-intent-neutral-solid px-2 py-1 text-intent-neutral-on-solid text-xs shadow-medium",
+            className,
+          )}
+          // No `popover="manual"` and no `FloatingFocusManager`,
+          // unlike `Popover`. Both exist to manage focus, and focus
+          // never enters a tooltip — moving it here is what makes
+          // one unescapable. The trade is that a tooltip is not in
+          // the top layer, so it can be clipped by an
+          // `overflow: hidden` ancestor; `strategy: "fixed"` keeps
+          // that to ancestors that actually clip fixed descendants.
+          ref={refs.setFloating}
+          // Duplicated from `getFloatingProps()` deliberately, and
+          // the two cannot differ — `useRole(context, { role:
+          // "tooltip" })` above is where it comes from. Stated here
+          // because a linter cannot see a role through a spread, and
+          // neither can the next reader.
+          role="tooltip"
+          style={floatingStyles}
+        >
+          {label}
+        </div>
+      ) : null}
+    </>
+  )
+}