@stonedogcode/style 0.16.0 → 0.19.0

package/src/components/StyledToaster.tsx

@@ -0,0 +1,325 @@
+"use client";
+
+import React, { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+import { toastRecipe } from "styled-system/recipes";
+import { cx } from "styled-system/css";
+
+import StyledButton from "./StyledButton";
+import StyledSpinner from "./StyledSpinner";
+import StyledText from "./StyledText";
+import type { Toast, ToasterStore, ToastType } from "./toaster-store";
+
+/**
+ * Draws whatever is in a toaster store.
+ *
+ * Mount **one** of these, once, near the root of the application, and hand it
+ * the same store your `create()` calls go to. It renders nothing until there is
+ * something to show.
+ *
+ * ```tsx
+ * export const toaster = createToaster();
+ * // …somewhere near the root:
+ * <StyledToaster toaster={toaster} />
+ * // …anywhere at all:
+ * toaster.create({ title: "Saved.", type: "success" });
+ * ```
+ *
+ * ## The three things that make this SSR-safe
+ *
+ * All three were failure modes before they were requirements, and none of them
+ * shows up in a client-only test:
+ *
+ * 1. **`getServerSnapshot`** — `useSyncExternalStore` throws during hydration
+ *    without one. The store supplies a frozen empty array, the same reference
+ *    every time, so React sees no change between the server render and the
+ *    first client one.
+ * 2. **The portal waits for mount.** `createPortal(…, document.body)` is a
+ *    `document is not defined` crash on the server. `mounted` below is false
+ *    for the server render *and* for the first client render, which is what
+ *    keeps the two identical — checking `typeof document` instead would make
+ *    them differ and produce a hydration mismatch rather than a crash.
+ * 3. **The store refuses to queue on the server**, so a toast created during a
+ *    render cannot leak into the next request. That one lives in the store; see
+ *    its header.
+ *
+ * ## Timers start here, not in the store
+ *
+ * A toast created before this component mounts — during a redirect, a slow
+ * hydration, an early event handler — must still be seen. Because each toast's
+ * countdown is an effect *in the toast's own element*, it cannot start before
+ * that element exists, so an early toast waits rather than expiring unseen.
+ */
+export interface StyledToasterProps {
+  /** The store to draw. Create it with `createToaster()`. */
+  toaster: ToasterStore;
+  /**
+   * The glyph for each kind of toast.
+   *
+   * **This package ships no icon artwork**, deliberately — see CLAUDE.md. The
+   * defaults are text characters, which work everywhere and are nobody's
+   * favourite. Pass your own icon set here to replace them; pass `null` for a
+   * type to render no glyph at all.
+   *
+   * Whatever you pass is `aria-hidden`: the toast's role already tells a screen
+   * reader what kind of message it is, and reading "check mark" before the text
+   * is the same information twice.
+   */
+  icons?: Partial<Record<ToastType, React.ReactNode>> | undefined;
+  /** The glyph inside the close control. Text by default, for the same reason. */
+  closeIcon?: React.ReactNode;
+  /**
+   * The close control's accessible name. It is a button whose only content is a
+   * glyph, so without a name it announces as "button" and nothing else.
+   */
+  closeLabel?: string;
+  /**
+   * Names the region for a screen reader listing landmarks.
+   *
+   * Not the toasts themselves — those announce individually as they arrive.
+   */
+  regionLabel?: string;
+}
+
+/**
+ * Text stand-ins for the artwork this package will not ship.
+ *
+ * `default` has none on purpose: it is the type for a message with no status,
+ * and inventing a glyph for "no particular kind" would say something the
+ * message does not.
+ */
+const DEFAULT_ICONS: Partial<Record<ToastType, React.ReactNode>> = {
+  success: "✓",
+  error: "✕",
+  warning: "!",
+  info: "i",
+};
+
+/**
+ * One toast, and the only place a dismissal timer exists.
+ *
+ * The timer is an effect keyed on `paused`, which gives pause-and-resume for
+ * free: pausing tears the effect down, and the cleanup subtracts the elapsed
+ * time from what is left, so resuming schedules the remainder rather than
+ * restarting the whole duration. Unmounting runs the same cleanup, so a toast
+ * removed mid-countdown cannot fire a state update into a component that is no
+ * longer there.
+ */
+function ToastItem({
+  toast,
+  paused,
+  onDismiss,
+  icons,
+  closeIcon,
+  closeLabel,
+}: {
+  toast: Toast;
+  paused: boolean;
+  onDismiss: (id: string) => void;
+  icons: Partial<Record<ToastType, React.ReactNode>>;
+  closeIcon: React.ReactNode;
+  closeLabel: string;
+}) {
+  /**
+   * Resolved PER TOAST, with this toast's type.
+   *
+   * The first version called `toastRecipe()` once for the whole region and
+   * shared the result, so every card came out as `toast__root--type_default`
+   * and no status accent was ever painted — the recipe was correct, its
+   * stylesheet was correct, and nothing rendered it. Neither the unit tier
+   * (which asserts roles and text) nor the token-contract test (which reads the
+   * stylesheet) could see it; the component test comparing three computed
+   * accent colours found all three identical.
+   */
+  const classes = toastRecipe({ type: toast.type });
+
+  const remaining = useRef(toast.duration);
+
+  useEffect(() => {
+    // `loading` and anything given `Infinity` stay until something dismisses
+    // them. Scheduling a timeout for Infinity is not merely pointless — the
+    // value overflows a 32-bit delay and fires immediately, which would make
+    // "stays until dismissed" mean "vanishes at once".
+    if (paused || toast.dismissed || !Number.isFinite(remaining.current)) return;
+
+    const startedAt = Date.now();
+    const timer = setTimeout(() => onDismiss(toast.id), remaining.current);
+
+    return () => {
+      clearTimeout(timer);
+      remaining.current -= Date.now() - startedAt;
+    };
+  }, [paused, toast.dismissed, toast.id, onDismiss]);
+
+  const glyph = icons[toast.type];
+
+  return (
+    <div
+      // `status` rather than `alert`: polite, so it waits for a gap in whatever
+      // the reader is already saying instead of cutting across it. An
+      // interruption is right for a fire alarm and wrong for "Saved."
+      //
+      // `aria-atomic` makes the whole toast read as one message. Without it a
+      // reader announces only the part of the subtree that changed, which for a
+      // toast updated in place is a fragment with no context.
+      role="status"
+      aria-atomic="true"
+      data-state={toast.dismissed ? "closed" : "open"}
+      data-type={toast.type}
+      className={classes.root}
+    >
+      {/*
+        `aria-hidden` on the whole indicator, spinner included.
+
+        The glyph is hidden because the toast's role has already told the reader
+        what kind of message this is, and "check mark, Saved." is the same thing
+        twice. The SPINNER is hidden for a sharper reason: `StyledSpinner`
+        carries its own `role="status"`, so rendering it bare nests one live
+        region inside another — the message is announced twice, and the outer
+        `aria-atomic` no longer describes one coherent thing. What tells a
+        reader the work is still going is the toast's own text ("Uploading…"),
+        which is the part worth reading anyway.
+      */}
+      {(toast.type === "loading" || glyph != null) && (
+        <div className={classes.indicator} aria-hidden="true">
+          {toast.type === "loading" ? <StyledSpinner loadText="" /> : glyph}
+        </div>
+      )}
+
+      <div className={classes.content}>
+        {toast.title != null && (
+          <StyledText className={classes.title}>{toast.title}</StyledText>
+        )}
+        {toast.description != null && (
+          <StyledText className={classes.description}>
+            {toast.description}
+          </StyledText>
+        )}
+      </div>
+
+      {toast.action && (
+        <div className={classes.action}>
+          <StyledButton
+            onClick={() => {
+              toast.action?.onClick();
+              // A toast whose button has been pressed has done its job. Leaving
+              // it up invites a second press on an action that has already run.
+              onDismiss(toast.id);
+            }}
+          >
+            {toast.action.label}
+          </StyledButton>
+        </div>
+      )}
+
+      {toast.closable && (
+        <button
+          type="button"
+          aria-label={closeLabel}
+          className={classes.close}
+          onClick={() => onDismiss(toast.id)}
+        >
+          <span aria-hidden="true">{closeIcon}</span>
+        </button>
+      )}
+    </div>
+  );
+}
+
+export const StyledToaster: React.FC<StyledToasterProps> = ({
+  toaster,
+  icons,
+  closeIcon = "✕",
+  closeLabel = "Dismiss notification",
+  regionLabel = "Notifications",
+}) => {
+  const toasts = useSyncExternalStore(
+    toaster.subscribe,
+    toaster.getSnapshot,
+    toaster.getServerSnapshot,
+  );
+
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+
+  /**
+   * Pointer or keyboard inside the region, and the tab being hidden, all stop
+   * the clock. They are one boolean rather than three because the resume
+   * condition is "none of them", and three independent flags is how a toast
+   * ends up pinned forever by a hover the pointer left through a portal.
+   */
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+  const [pageHidden, setPageHidden] = useState(false);
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    // A countdown that runs in a background tab is a message the user never had
+    // the chance to read. Chakra's store called this `pauseOnPageIdle` and had
+    // it on; this keeps that, without the option, because no consumer wanted
+    // the other behaviour.
+    const sync = () => setPageHidden(document.hidden);
+    sync();
+    document.addEventListener("visibilitychange", sync);
+    return () => document.removeEventListener("visibilitychange", sync);
+  }, []);
+
+  const paused = hovered || focused || pageHidden;
+
+  // Stable identity so it is not a fresh dependency on every render of every
+  // toast — each toast's timer effect lists it.
+  const onDismiss = React.useCallback(
+    (id: string) => toaster.remove(id),
+    [toaster],
+  );
+
+  // Only the region slot is read here; every card resolves its own, above.
+  const classes = toastRecipe();
+  const resolvedIcons = icons ?? DEFAULT_ICONS;
+
+  if (!mounted) return null;
+
+  return createPortal(
+    <div
+      className={cx(classes.region)}
+      // The region is present from mount and stays, whether or not it holds
+      // anything. A live region created at the same moment as its content is
+      // announced inconsistently across screen readers; one that was already
+      // there is not.
+      aria-label={regionLabel}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+      onFocus={() => setFocused(true)}
+      onBlur={(event) => {
+        // Only when focus has actually left the region — moving between the
+        // action and the close button inside one toast fires blur too, and
+        // treating that as "focus left" would restart the countdown under the
+        // keyboard user's hands.
+        if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
+          setFocused(false);
+        }
+      }}
+    >
+      {/*
+        Rendered oldest-last so the newest toast sits nearest the corner, which
+        is where the eye already is. The store keeps them newest-first because
+        that is the order its priority rules work in; the reversal is a
+        presentation decision and belongs here.
+      */}
+      {[...toasts].reverse().map((toast) => (
+        <ToastItem
+          key={toast.id}
+          toast={toast}
+          paused={paused}
+          onDismiss={onDismiss}
+          icons={resolvedIcons}
+          closeIcon={closeIcon}
+          closeLabel={closeLabel}
+        />
+      ))}
+    </div>,
+    document.body,
+  );
+};
+
+export default StyledToaster;

package/src/components/StyledTooltip.tsx

@@ -44,7 +44,6 @@ const HelpTrigger = styled("button", {
     // is hard to hit is a help control that does not get used.
     minWidth: "48px",
     minHeight: "48px",
-    marginLeft: "4px",
     borderRadius: "9999px",
     borderWidth: "1px",
     borderStyle: "solid",
@@ -53,6 +52,17 @@ const HelpTrigger = styled("button", {
     lineHeight: "1",
     verticalAlign: "middle",
   },
+  variants: {
+    // Which side of the children the control sits on — see helpGoesFirst
+    // below for how that is decided. The gap has to follow the side, or the
+    // control touches its subject on one side and floats away from it on the
+    // other, which is exactly the ambiguity this fix is about.
+    side: {
+      before: { marginRight: "4px" },
+      after: { marginLeft: "4px" },
+    },
+  },
+  defaultVariants: { side: "after" },
 });
 
 /**
@@ -111,7 +121,7 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   "aria-label": ariaLabel,
   variant,
   trigger = "hover",
-  helpLabel = "More information",
+  helpLabel,
   ...rest
 }) => {
   // Caller's variant, else the app-wide one, else `solid` — and anything the
@@ -182,6 +192,7 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   const canHover = useCanHover();
   const isClick = trigger === "click" || !canHover;
 
+
   // The child may be any component (StyledIconButton, a link, a bare span), so
   // whether it is focusable can only be known from the rendered DOM — React
   // cannot see inside a child component's output. Starts as "yes" so the common
@@ -233,9 +244,36 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   // a duplicated one is a new bug.
   const [needsFallbackName, setNeedsFallbackName] = useState(false);
 
+  /**
+   * The child's own visible text, used to name the help control after the
+   * thing it explains (NEH-769).
+   *
+   * A screen carrying twenty tooltips carried twenty buttons all called "More
+   * information", which names nothing: a reader tabbing through hears the same
+   * four words twenty times and cannot tell which one answers their question.
+   * "Help: Require PIN" is the same control with a name that distinguishes it.
+   *
+   * Measured from the DOM rather than read from `children` because the child
+   * may be any component — React cannot see the text inside a child component's
+   * output, only the element it was handed.
+   */
+  const [subjectLabel, setSubjectLabel] = useState("");
+
   useLayoutEffect(() => {
     const node = triggerRef.current;
-    const found = node?.querySelector<HTMLElement>(FOCUSABLE_SELECTOR) ?? null;
+    const help = helpRef.current;
+
+    // The help control is itself a `button`, so it matches FOCUSABLE_SELECTOR
+    // and must be excluded from every question asked about the CHILD. This was
+    // already wrong before the control could be rendered first — with a
+    // non-focusable child the query returned the help button, so
+    // aria-describedby landed on the button that already names itself instead
+    // of on the thing being described. Once the control renders first it would
+    // have matched every time (NEH-769).
+    const found =
+      Array.from(node?.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR) ?? []).find(
+        (candidate) => candidate !== help,
+      ) ?? null;
     // Same-value setState is a no-op in React, so this cannot loop.
     setFocusableChild((prev) => (prev === found ? prev : found));
     setHasFocusableChild(found !== null);
@@ -251,6 +289,20 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
     setFocusableAncestor((prev) => (prev === ancestor ? prev : ancestor));
 
     if (!node) return;
+
+    // The child's own text — the help control's "?" deliberately excluded, or
+    // every subject would be named "… ?" and a text-free child would look as
+    // though it had text.
+    const ownText = Array.from(node.childNodes)
+      .filter((child) => child !== help)
+      .map((child) => child.textContent ?? "")
+      .join(" ")
+      .replace(/\s+/g, " ")
+      .trim();
+    // Long enough to distinguish twenty controls, short enough that a screen
+    // reader does not read a paragraph before the reader can act on it.
+    setSubjectLabel(ownText.length > 80 ? `${ownText.slice(0, 80).trimEnd()}…` : ownText);
+
     // parentElement, not the node itself: closest() would match our own
     // aria-label once we set one, and the answer would flip every render.
     const namedByAncestor = Boolean(
@@ -259,12 +311,12 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
     // Text content names an element for free; so does a labelled descendant
     // (an icon carrying its own aria-label, an <img alt>).
     const namedByContent =
-      (node.textContent ?? "").trim().length > 0 ||
-      Boolean(
-        node.querySelector('[aria-label], [aria-labelledby], img[alt]:not([alt=""])'),
-      );
+      ownText.length > 0 ||
+      Array.from(
+        node.querySelectorAll('[aria-label], [aria-labelledby], img[alt]:not([alt=""])'),
+      ).some((el) => el !== help);
     setNeedsFallbackName(!namedByAncestor && !namedByContent);
-  }, [children]);
+  }, [children, isClick]);
 
   // aria-describedby has to sit on whatever actually receives focus, or a screen
   // reader announces the control with no description. Set imperatively rather
@@ -482,6 +534,51 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
   // would produce "[object Object]" in the accessibility tree.
   const tooltipLabel = typeof tooltip === "string" ? tooltip : undefined;
 
+  /**
+   * `Label → ? → Input` — the help control goes after the label and before the
+   * control it explains, never after it (NEH-769).
+   *
+   * Not aesthetic. A screen-magnifier user reads linearly at high zoom, so a
+   * `?` placed after a long input is pushed off the visible viewport entirely;
+   * before the control, the reader meets the concept, can ask what it means,
+   * and only then enters data.
+   *
+   * Consumers wrap two shapes and both have to obey that rule, which is why
+   * neither a fixed "always before" nor a fixed "always after" is right:
+   *
+   *   `<Tooltip><Label/></Tooltip> <Input/>`      the input is OUTSIDE us, so
+   *                                               the control goes AFTER  →  Label ? | Input
+   *   `<Tooltip><Row><Label/><Toggle/></Row></Tooltip>`
+   *                                               the control is INSIDE us, so
+   *                                               it goes BEFORE          →  ? Label Toggle
+   *
+   * So the side keys on whether the children contain something focusable —
+   * which the component already measures for its own tab-stop logic. It is
+   * measured in a layout effect, so it settles before paint rather than
+   * flickering into place.
+   */
+  const helpGoesFirst = hasFocusableChild;
+
+  /**
+   * Explicit label wins; otherwise name the control after its subject. Only
+   * when there is no text at all does it fall back to the old generic name.
+   */
+  const resolvedHelpLabel =
+    helpLabel ?? (subjectLabel ? `Help: ${subjectLabel}` : "More information");
+
+  const helpControl = isClick ? (
+    <HelpTrigger
+      ref={helpRef}
+      type="button"
+      side={helpGoesFirst ? "before" : "after"}
+      aria-label={resolvedHelpLabel}
+      aria-expanded={visible}
+      aria-controls={visible ? tooltipId : undefined}
+      onClick={() => setVisible((open) => !open)}
+    >
+      ?
+    </HelpTrigger>
+  ) : null;
 
   return (
     <>
@@ -519,24 +616,21 @@ const StyledTooltip: React.FC<StyledTooltipProps> = ({
         onMouseLeave={isClick ? undefined : hide}
         onFocus={isClick ? undefined : show}
         onBlur={isClick ? undefined : hide}
-        aria-describedby={
-          !isClick && !insideFocusable && visible ? tooltipId : undefined
-        }
+        // When something focusable is in play the description is set
+        // imperatively on THAT element instead (see the layout effect above) —
+        // it has to sit on whatever actually receives focus. This wrapper is
+        // the fallback for label-only children, and it applies in click mode
+        // too: help that is reachable but never announced is help a screen
+        // reader user does not know exists (NEH-769).
+        //
+        // `insideFocusable`, not `hasFocusableChild`, so a focusable ANCESTOR
+        // still owns the description rather than this wrapper (NEH-950).
+        aria-describedby={!insideFocusable && visible ? tooltipId : undefined}
         {...rest}
       >
+        {helpGoesFirst && helpControl}
         {children}
-        {isClick && (
-          <HelpTrigger
-            ref={helpRef}
-            type="button"
-            aria-label={helpLabel}
-            aria-expanded={visible}
-            aria-controls={visible ? tooltipId : undefined}
-            onClick={() => setVisible((open) => !open)}
-          >
-            ?
-          </HelpTrigger>
-        )}
+        {!helpGoesFirst && helpControl}
       </TooltipTrigger>
       {visible && typeof document !== "undefined" &&
         createPortal(