@stonedogcode/style 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "A Panda CSS design system: a themeable Panda preset plus the React components built on it.",
   "license": "Apache-2.0",
   "author": "StoneDogCode L.L.C.",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/stonedog-code/stonedog-style.git"
   },
-  "//publishConfig": "A SCOPED package defaults to access: restricted. Publishing one without this succeeds, prints nothing unusual, and then 404s for every consumer \u2014 which reads as a missing package rather than as a private one. It was not needed while the name was unscoped (those default to public), so it is new as of the scope migration and it is the single thing most likely to be forgotten in one.",
+  "//publishConfig": "A SCOPED package defaults to access: restricted. Publishing one without this succeeds, prints nothing unusual, and then 404s for every consumer — which reads as a missing package rather than as a private one. It was not needed while the name was unscoped (those default to public), so it is new as of the scope migration and it is the single thing most likely to be forgotten in one.",
   "publishConfig": {
     "access": "public"
   },
@@ -20,7 +20,7 @@
     "./preset": "./src/preset/index.ts",
     "./package.json": "./package.json"
   },
-  "//files": "The package ships SOURCE, so `src` has to go out whole \u2014 but only the part a consumer imports. Tests, Playwright component tests and their harnesses were 57 of 130 entries and never resolvable from any export, so every one of them was a file a consumer's Panda run had to be told to skip. `src/__tests__/published-package.test.ts` asserts this listing rather than this array: npm's own resolution of these negations is the only thing that decides what ships.",
+  "//files": "The package ships SOURCE, so `src` has to go out whole — but only the part a consumer imports. Tests, Playwright component tests and their harnesses were 57 of 130 entries and never resolvable from any export, so every one of them was a file a consumer's Panda run had to be told to skip. `src/__tests__/published-package.test.ts` asserts this listing rather than this array: npm's own resolution of these negations is the only thing that decides what ships.",
   "files": [
     "src",
     "!src/**/__tests__/**",
@@ -38,7 +38,7 @@
     "pretype-check": "npm run panda:prepare",
     "type-check": "tsc --noEmit",
     "lint": "eslint . --ext ts,tsx",
-    "//pretest": "panda:build, not panda:prepare \u2014 the token-contract suite asserts against the generated stylesheet, which cssgen produces and codegen alone does not.",
+    "//pretest": "panda:build, not panda:prepare — the token-contract suite asserts against the generated stylesheet, which cssgen produces and codegen alone does not.",
     "pretest": "npm run panda:build",
     "test": "jest",
     "pretest:ct": "npm run panda:build",
@@ -46,7 +46,7 @@
     "test:ct:ui": "playwright test --config playwright-ct.config.ts --ui",
     "test:coverage": "jest --coverage",
     "gate": "npm run type-check && npm run lint && npm run test",
-    "//publish:stonedog-style": "Publish to npm, end to end. Run from a terminal, interactively \u2014 npm prompts for the 2FA one-time password and the login flow needs a browser. It refuses a checkout that is detached, dirty, or behind origin/main: a submodule sits detached at the consumer's gitlink by default, and publishing from one commit behind ships a tarball missing the very thing you are publishing for while looking like a success (it did, on 2026-08-04, without TitleLogo.tsx). Runs the gate, prints the tarball listing, then proves the result by installing from the registry into a temp directory.",
+    "//publish:stonedog-style": "Publish to npm, end to end. Run from a terminal, interactively — npm prompts for the 2FA one-time password and the login flow needs a browser. It refuses a checkout that is detached, dirty, or behind origin/main: a submodule sits detached at the consumer's gitlink by default, and publishing from one commit behind ships a tarball missing the very thing you are publishing for while looking like a success (it did, on 2026-08-04, without TitleLogo.tsx). Runs the gate, prints the tarball listing, then proves the result by installing from the registry into a temp directory.",
     "publish:stonedog-style": "bash scripts/publish-package.sh",
     "version:bump:patch": "npm version patch --no-git-tag-version",
     "version:bump:minor": "npm version minor --no-git-tag-version",

package/src/components/StyledCollapsible.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import React, { useId, useState } from "react";
+import React from "react";
 import { styled } from "styled-system/jsx";
+import { useDisclosure } from "./useDisclosure";
 
 /**
  * A disclosure: a trigger that shows and hides a region.
@@ -82,41 +83,27 @@ const StyledCollapsible: React.FC<StyledCollapsibleProps> = ({
   triggerTestId,
   contentTestId,
 }) => {
-  const [uncontrolled, setUncontrolled] = useState(defaultOpen);
-
-  // Controlled the moment `open` is supplied, and uncontrolled otherwise —
-  // decided per render rather than latched at mount, because a host that
-  // switches between the two mid-life has a bug we should not paper over by
-  // silently ignoring the prop.
-  const isControlled = open !== undefined;
-  const isOpen = isControlled ? open : uncontrolled;
-
-  const contentId = useId();
-
-  const toggle = () => {
-    const next = !isOpen;
-    // The internal state moves even when controlled. If the host ignores the
-    // callback the component would otherwise appear dead to the pointer, and a
-    // control that does nothing when pressed is indistinguishable from a broken
-    // one — for this audience, the reader concludes the app is broken, not that
-    // they misread the affordance.
-    if (!isControlled) setUncontrolled(next);
-    onOpenChange?.(next);
-  };
+  // The mechanics live in `useDisclosure`, not here. This component is one
+  // ARRANGEMENT of a disclosure — a button with the trigger inside it, above
+  // the region — and a host whose control is already a button composes the
+  // same hook into its own layout instead of nesting one button in another
+  // (NEH-1100). Two arrangements, one implementation.
+  const { triggerProps, contentProps } = useDisclosure({
+    open,
+    defaultOpen,
+    onOpenChange,
+  });
 
   return (
     <>
       <CollapsibleTrigger
-        type="button"
-        onClick={toggle}
-        aria-expanded={isOpen}
-        aria-controls={contentId}
+        {...triggerProps}
         aria-label={ariaLabel}
         data-testid={triggerTestId}
       >
         {trigger}
       </CollapsibleTrigger>
-      <div id={contentId} hidden={!isOpen} data-testid={contentTestId}>
+      <div {...contentProps} data-testid={contentTestId}>
         {children}
       </div>
     </>

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/toaster-store.ts

@@ -0,0 +1,334 @@
+/**
+ * The toast queue: a subscribable store, with no React and no DOM in it.
+ *
+ * ## Why this is a store and not a component
+ *
+ * A toast is created from places that are not rendering — an event handler, a
+ * `.catch()`, a module-level helper called before anything has mounted. So the
+ * thing callers reach for cannot be a hook. It has to be a plain object with a
+ * `create()` on it, and the component that draws toasts has to *subscribe* to
+ * that object rather than own it.
+ *
+ * That shape is what `useSyncExternalStore` exists for, and the three methods
+ * below (`subscribe`, `getSnapshot`, `getServerSnapshot`) are exactly its
+ * contract. Two of its rules are easy to break and fail loudly but obscurely:
+ *
+ * - **`getSnapshot` must return the identical reference when nothing changed.**
+ *   Returning a fresh array each call makes React re-render forever. `toasts`
+ *   below is therefore replaced only on mutation, never rebuilt on read.
+ * - **`getServerSnapshot` is mandatory** for anything server-rendered, and must
+ *   also be reference-stable. `EMPTY` is a single frozen array shared by every
+ *   call for that reason.
+ *
+ * ## Why `create()` does nothing on the server
+ *
+ * A module-level array lives for the lifetime of the Node process, not the
+ * request. A toast created during SSR would therefore still be sitting in the
+ * queue when the *next* user is served by that same instance — one person's
+ * "Saved." announced to a stranger. There is no request boundary available here
+ * to scope it to, and a toast has no meaning without a browser to show it in,
+ * so the honest answer is to refuse to queue one at all.
+ *
+ * `create()` still returns the id it would have used, so a caller that stores
+ * or logs the result behaves identically in both environments.
+ *
+ * ## Timers are deliberately NOT here
+ *
+ * Auto-dismiss lives in the renderer, per toast, starting when that toast first
+ * mounts. Putting it here would start the clock at `create()` time — so a toast
+ * fired before the toaster mounted (a redirect, a slow hydration, a `create()`
+ * in a module body) could expire before it was ever drawn. It would look like
+ * the toast was silently dropped, which is the failure this whole component is
+ * most likely to be blamed for and least likely to be caught doing.
+ *
+ * What *is* here is the exit delay, because it is a property of leaving the
+ * queue rather than of being on screen: `remove()` marks a toast `dismissed`
+ * and purges it `removeDelay` ms later, so the renderer has a state to animate
+ * out of.
+ */
+
+import type { ReactNode } from "react";
+
+/**
+ * The kinds of toast, matching what the extracted application already used.
+ *
+ * `default` is a toast with no status at all — no accent, no glyph. It is not a
+ * synonym for `info`; a message that means something should say which thing it
+ * means.
+ */
+export type ToastType =
+  | "success"
+  | "error"
+  | "warning"
+  | "info"
+  | "loading"
+  | "default";
+
+/** A single button on a toast. Rendered after the message. */
+export interface ToastAction {
+  label: string;
+  onClick: () => void;
+}
+
+export interface ToastOptions {
+  /**
+   * Supply one to make `create()` idempotent — creating with an id that is
+   * already on screen updates that toast in place rather than stacking a
+   * duplicate. Useful for progress ("Uploading…" → "Uploaded").
+   */
+  id?: string | undefined;
+  title?: ReactNode;
+  description?: ReactNode;
+  type?: ToastType | undefined;
+  /**
+   * Milliseconds on screen. Omit to use the per-type default below.
+   * `Infinity` pins the toast until it is dismissed.
+   */
+  duration?: number | undefined;
+  action?: ToastAction | undefined;
+  /** Render a close control. */
+  closable?: boolean | undefined;
+}
+
+export interface Toast extends ToastOptions {
+  id: string;
+  type: ToastType;
+  duration: number;
+  /**
+   * Set the moment `remove()` is called and the toast starts animating out.
+   * It stays in the snapshot while true so the renderer has something to
+   * animate; it is purged `removeDelay` ms later.
+   */
+  dismissed: boolean;
+}
+
+export interface ToasterStoreOptions {
+  /**
+   * How many toasts may be on screen at once. Further ones wait in a queue and
+   * are admitted as room appears.
+   *
+   * 24 is not a considered number — it is the value the store this replaces
+   * used, kept so that the behaviour at overflow does not change silently along
+   * with everything else.
+   */
+  max?: number;
+  /** How long a dismissed toast stays in the snapshot so it can animate out. */
+  removeDelay?: number;
+}
+
+export interface ToasterStore {
+  /**
+   * Show a toast. Returns its id.
+   *
+   * Named `create` rather than `show` or `toast` because that is the name the
+   * 345 call sites in the application this was extracted from already use.
+   */
+  create: (options: ToastOptions) => string;
+  /**
+   * Dismiss one toast, or every toast when called with no argument.
+   *
+   * The toast animates out first — it is marked `dismissed` immediately and
+   * leaves the snapshot `removeDelay` ms later.
+   */
+  remove: (id?: string) => void;
+  subscribe: (listener: () => void) => () => void;
+  getSnapshot: () => readonly Toast[];
+  getServerSnapshot: () => readonly Toast[];
+}
+
+/**
+ * How long each kind stays up, in milliseconds.
+ *
+ * These are not invented. They are the values `@zag-js/toast` uses, read out of
+ * the installed package rather than guessed, so that swapping the
+ * implementation underneath an application does not quietly retime every
+ * message in it. Note `success` is much shorter than the rest — a confirmation
+ * has been read the moment it is seen, whereas a warning is asking for a
+ * decision.
+ */
+export const DEFAULT_DURATIONS: Record<ToastType, number> = {
+  success: 2000,
+  error: 5000,
+  warning: 5000,
+  info: 5000,
+  loading: Infinity,
+  default: 5000,
+};
+
+/**
+ * Which toast wins a place on screen when more than `max` are pending.
+ *
+ * Lower sorts first. Errors outrank confirmations because a failure the user
+ * never sees is the expensive one, and within a type an *actionable* toast
+ * outranks a passive one — there is nothing to miss on a toast with no button.
+ *
+ * Only consulted past `max` simultaneous toasts, which in practice means a loop
+ * that has gone wrong. It exists so that what survives that is the half worth
+ * reading.
+ */
+const PRIORITY: Record<ToastType, [actionable: number, passive: number]> = {
+  error: [1, 2],
+  warning: [3, 6],
+  loading: [4, 5],
+  success: [5, 7],
+  info: [6, 8],
+  default: [6, 8],
+};
+
+const priorityOf = (toast: Toast): number =>
+  PRIORITY[toast.type][toast.action ? 0 : 1];
+
+/**
+ * One frozen array, returned by every server render and by any snapshot taken
+ * of an empty store. `useSyncExternalStore` compares snapshots by reference, so
+ * a fresh `[]` here would be a new value on every read.
+ */
+const EMPTY: readonly Toast[] = Object.freeze([]);
+
+/** `window` is the only reliable "is there a user in front of this" signal. */
+const inBrowser = (): boolean => typeof window !== "undefined";
+
+export function createToaster(options: ToasterStoreOptions = {}): ToasterStore {
+  const { max = 24, removeDelay = 200 } = options;
+
+  let toasts: readonly Toast[] = EMPTY;
+  let queued: Toast[] = [];
+  let listeners: Array<() => void> = [];
+  let counter = 0;
+
+  /**
+   * Ids are a counter, not a random or time-based value, so that a test can
+   * assert on one and so two toasts created in the same millisecond cannot
+   * collide. They are scoped to this store and never leave it.
+   */
+  const nextId = (): string => `toast-${++counter}`;
+
+  const emit = (): void => {
+    // Copied before iterating: a listener that unsubscribes itself while being
+    // notified would otherwise shorten the array mid-loop and skip its
+    // neighbour.
+    for (const listener of [...listeners]) listener();
+  };
+
+  /** Admit queued toasts until the screen is full again. */
+  const drain = (): void => {
+    if (queued.length === 0 || toasts.length >= max) return;
+    queued.sort((a, b) => priorityOf(a) - priorityOf(b));
+    const admitted = queued.splice(0, max - toasts.length);
+    // Queued toasts were created after everything on screen, so they go in
+    // front; among themselves the highest priority leads.
+    toasts = [...admitted, ...toasts];
+  };
+
+  const purge = (id: string): void => {
+    const next = toasts.filter((toast) => toast.id !== id);
+    if (next.length === toasts.length) return;
+    toasts = next.length === 0 ? EMPTY : next;
+    drain();
+    emit();
+  };
+
+  const create = (options: ToastOptions): string => {
+    const id = options.id ?? nextId();
+
+    // See the header: never queue on the server.
+    if (!inBrowser()) return id;
+
+    const existing = toasts.find((toast) => toast.id === id);
+    if (existing) {
+      const type = options.type ?? existing.type;
+      const updated: Toast = {
+        ...existing,
+        ...options,
+        id,
+        type,
+        // A change of TYPE re-derives the duration, and that is the whole point
+        // of this branch. The progress case — `loading` ("Uploading…") updated
+        // in place to `success` ("Uploaded.") — carries no explicit duration,
+        // and `loading` means `Infinity`. Simply keeping the old value leaves
+        // the finished toast pinned to the screen forever, which reads as the
+        // upload never having completed. Only an explicit `duration` overrides.
+        duration:
+          options.duration ??
+          (type === existing.type ? existing.duration : DEFAULT_DURATIONS[type]),
+        // Re-creating an id that is on its way out brings it back.
+        dismissed: false,
+      };
+      toasts = toasts.map((toast) => (toast.id === id ? updated : toast));
+      emit();
+      return id;
+    }
+
+    const type = options.type ?? "info";
+    const toast: Toast = {
+      ...options,
+      id,
+      type,
+      duration: options.duration ?? DEFAULT_DURATIONS[type],
+      dismissed: false,
+    };
+
+    if (toasts.length >= max) {
+      queued.push(toast);
+      return id;
+    }
+
+    toasts = [toast, ...toasts];
+    emit();
+    return id;
+  };
+
+  const remove = (id?: string): void => {
+    if (id === undefined) {
+      queued = [];
+      if (toasts.length === 0) return;
+      toasts = toasts.map((toast) => ({ ...toast, dismissed: true }));
+      emit();
+      const ids = toasts.map((toast) => toast.id);
+      schedulePurge(() => ids.forEach(purge));
+      return;
+    }
+
+    const target = toasts.find((toast) => toast.id === id);
+    if (!target) {
+      // It may still be waiting for a slot; drop it before it ever appears.
+      queued = queued.filter((toast) => toast.id !== id);
+      return;
+    }
+    if (target.dismissed) return;
+
+    toasts = toasts.map((toast) =>
+      toast.id === id ? { ...toast, dismissed: true } : toast,
+    );
+    emit();
+    schedulePurge(() => purge(id));
+  };
+
+  /**
+   * The exit delay, skipped entirely off-browser.
+   *
+   * A `setTimeout` on the server would keep the event loop alive and fire into
+   * a store nothing is subscribed to. There is nothing to animate there, so the
+   * removal is immediate.
+   */
+  const schedulePurge = (run: () => void): void => {
+    if (!inBrowser() || removeDelay <= 0) {
+      run();
+      return;
+    }
+    setTimeout(run, removeDelay);
+  };
+
+  return {
+    create,
+    remove,
+    subscribe: (listener) => {
+      listeners = [...listeners, listener];
+      return () => {
+        listeners = listeners.filter((candidate) => candidate !== listener);
+      };
+    },
+    getSnapshot: () => toasts,
+    getServerSnapshot: () => EMPTY,
+  };
+}

package/src/components/useDisclosure.ts

@@ -0,0 +1,139 @@
+"use client";
+
+import { useCallback, useId, useState } from "react";
+
+/**
+ * The mechanics of a disclosure, with no markup attached.
+ *
+ * ## Why this exists as a hook and not only as a component
+ *
+ * `StyledCollapsible` renders its own `<button>` with the trigger inside it.
+ * That is the right default and it is the wrong shape for a host whose control
+ * is *already* a button — an icon button with a tooltip, say, sitting in a
+ * header row opposite a title. Handed such a control as `trigger`, the
+ * component would wrap one `<button>` in another: invalid HTML that React warns
+ * will break hydration, and one affordance split into two, with the accessible
+ * name on the inner element and `aria-expanded` on the outer one. A screen
+ * reader then announces a button that says nothing, containing a button that
+ * says nothing about its state.
+ *
+ * The alternative — the host hand-rolling `useState`, a `useId`, the two ARIA
+ * attributes and the `hidden` decision — is how one product ends up with two
+ * disclosures that disagree, which is exactly what NEH-1100 records happening.
+ *
+ * So the mechanics live here, and both the component below and any host
+ * composition are built on the same three lines. There is one implementation of
+ * *a disclosure*; there are as many arrangements of it as there are layouts.
+ *
+ * ```tsx
+ * const { open, triggerProps, contentProps } = useDisclosure();
+ *
+ * <header>
+ *   <h2>Vitals</h2>
+ *   <MyIconButton {...triggerProps} aria-label={open ? "Hide" : "Show"} />
+ * </header>
+ * <section {...contentProps}>…</section>
+ * ```
+ *
+ * ## `hidden`, never unmounted
+ *
+ * `contentProps.hidden` is the whole opinion this hook carries, and it is not
+ * negotiable by a prop. Unmounting collapsed content looks tidier and discards
+ * focus, scroll position and anything part-typed — so a mis-press destroys work
+ * rather than merely hiding it. `hidden` also keeps the region addressable by
+ * `aria-controls` at all times, which is what lets `aria-expanded` mean
+ * anything: a control that claims to expand something must point at something
+ * that exists while it is collapsed.
+ *
+ * A host that genuinely wants unmounting can render `{open && …}` itself. It
+ * should then know it is giving that up.
+ */
+
+export interface UseDisclosureOptions {
+  /** Controlled. Omit to let the hook own the state. */
+  open?: boolean | undefined;
+  /** Initial state when uncontrolled. Default `false`. */
+  defaultOpen?: boolean | undefined;
+  onOpenChange?: ((next: boolean) => void) | undefined;
+  /**
+   * The id linking trigger to content. Generated when omitted.
+   *
+   * Supply one only when something outside this pair must reference the region
+   * by id; two disclosures given the same id will produce two triggers pointing
+   * at one region.
+   */
+  id?: string | undefined;
+}
+
+/** Spread onto the ONE element that is the control. It must be a `<button>`. */
+export interface DisclosureTriggerProps {
+  type: "button";
+  "aria-expanded": boolean;
+  "aria-controls": string;
+  onClick: () => void;
+}
+
+/** Spread onto the region the control shows and hides. */
+export interface DisclosureContentProps {
+  id: string;
+  hidden: boolean;
+}
+
+export interface Disclosure {
+  open: boolean;
+  toggle: () => void;
+  setOpen: (next: boolean) => void;
+  triggerProps: DisclosureTriggerProps;
+  contentProps: DisclosureContentProps;
+}
+
+export function useDisclosure(options: UseDisclosureOptions = {}): Disclosure {
+  const { open: controlled, defaultOpen = false, onOpenChange, id } = options;
+
+  const [uncontrolled, setUncontrolled] = useState(defaultOpen);
+
+  // Controlled the moment `open` is supplied, and uncontrolled otherwise —
+  // decided per render rather than latched at mount, because a host that
+  // switches between the two mid-life has a bug we should not paper over by
+  // silently ignoring the prop.
+  const isControlled = controlled !== undefined;
+  const open = isControlled ? controlled : uncontrolled;
+
+  const generatedId = useId();
+  const contentId = id ?? generatedId;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      // The internal state moves even when controlled. If the host ignores the
+      // callback the control would otherwise appear dead to the pointer, and a
+      // control that does nothing when pressed is indistinguishable from a
+      // broken one.
+      if (!isControlled) setUncontrolled(next);
+      onOpenChange?.(next);
+    },
+    [isControlled, onOpenChange],
+  );
+
+  const toggle = useCallback(() => setOpen(!open), [setOpen, open]);
+
+  return {
+    open,
+    toggle,
+    setOpen,
+    triggerProps: {
+      // `type="button"` because the commonest place a disclosure lives is
+      // inside a form, where an untyped button submits it. The symptom is a
+      // page reload on the first press of a "show more" control.
+      type: "button",
+      "aria-expanded": open,
+      "aria-controls": contentId,
+      onClick: toggle,
+    },
+    contentProps: {
+      id: contentId,
+      hidden: !open,
+    },
+  };
+}
+
+export default useDisclosure;

package/src/index.ts

@@ -315,3 +315,27 @@ export { DL_VARIANTS } from "./components/StyledDefinitionList";
 
 export { default as StyledSparkLine } from "./components/StyledSparkLine";
 export type { StyledSparkLineProps } from "./components/StyledSparkLine";
+
+// ---------------------------------------------------------------------------
+// Notifications
+// ---------------------------------------------------------------------------
+export { default as StyledToaster, StyledToaster as Toaster } from "./components/StyledToaster";
+export type { StyledToasterProps } from "./components/StyledToaster";
+
+export { createToaster, DEFAULT_DURATIONS } from "./components/toaster-store";
+export type {
+  Toast,
+  ToastAction,
+  ToastOptions,
+  ToastType,
+  ToasterStore,
+  ToasterStoreOptions,
+} from "./components/toaster-store";
+
+export { default as useDisclosure } from "./components/useDisclosure";
+export type {
+  Disclosure,
+  DisclosureContentProps,
+  DisclosureTriggerProps,
+  UseDisclosureOptions,
+} from "./components/useDisclosure";

package/src/preset/index.ts

@@ -27,6 +27,7 @@ import { stackRecipe } from "./recipes/stack";
 import { stripedRecipe } from "./recipes/striped";
 import { tagRecipe } from "./recipes/tag";
 import { textRecipe } from "./recipes/text";
+import { toastRecipe } from "./recipes/toast";
 import { tooltipRecipe } from "./recipes/tooltip";
 
 import {
@@ -56,8 +57,9 @@ export interface StonedogStylePresetOptions {
 /**
  * Every recipe, keyed by the name it is exported under in `styled-system/recipes`.
  *
- * Five of these (`alertRecipe`, `listRecipe`, `menuRecipe`, `inputBoolRecipe`,
- * `inputRadioRootRecipe`) are slot recipes declared with `defineSlotRecipe`.
+ * Six of these (`alertRecipe`, `listRecipe`, `menuRecipe`, `inputBoolRecipe`,
+ * `inputRadioRootRecipe`, `toastRecipe`) are slot recipes declared with
+ * `defineSlotRecipe`.
  * Panda accepts them here rather than under `slotRecipes` and generates them
  * correctly — verified against HopperGuard's own generated output. Moving them
  * to `slotRecipes` would be more "correct" by the docs and would change the
@@ -87,6 +89,7 @@ const recipes = {
   stripedRecipe,
   tagRecipe,
   textRecipe,
+  toastRecipe,
   tooltipRecipe,
 };
 

package/src/preset/recipes/toast.ts

@@ -0,0 +1,161 @@
+import { defineSlotRecipe } from "@pandacss/dev";
+
+/**
+ * A transient message: the region it lives in, and the card itself.
+ *
+ * Extracted from HopperGuard, where the card was a `cva` in the component file
+ * and the region was a nine-cell CSS grid of which one cell was ever used. Both
+ * are here now, for the reason every recipe is: a `cva` inside a component is
+ * invisible to a consumer's Panda run unless that consumer globs this package's
+ * source, whereas a recipe is emitted from config with no parsing at all.
+ *
+ * ## The accent is a border, not a background
+ *
+ * Status is carried by a 4px bar down the leading edge rather than by tinting
+ * the whole card. Two reasons, and the second is the load-bearing one:
+ *
+ * - A toast sits over arbitrary page content, so it needs an opaque surface of
+ *   its own to stay readable. A tint would fight that.
+ * - **Colour is never the only cue.** The accent says the same thing as the
+ *   glyph the component renders beside the message, so a reader who cannot
+ *   distinguish the hues loses nothing — WCAG 1.4.1, Level A. Deleting the
+ *   glyph "because the colour already says it" is the regression this note
+ *   exists to stop.
+ *
+ * `borderInlineStart` rather than `borderLeft`: in a right-to-left document the
+ * accent belongs on the right, and the logical property is what moves it there.
+ */
+export const toastRecipe = defineSlotRecipe({
+  className: "toast",
+  description: "A transient message and the region that stacks them",
+  slots: [
+    "region",
+    "root",
+    "indicator",
+    "content",
+    "title",
+    "description",
+    "action",
+    "close",
+  ],
+  base: {
+    region: {
+      position: "fixed",
+      // Anchored to one corner rather than laid out in a grid of nine cells:
+      // the extracted version declared all nine and rendered into exactly one,
+      // so eight of them were markup nothing could ever reach.
+      insetBlockEnd: "4",
+      insetInlineEnd: "4",
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "flex-end",
+      gap: "3",
+      // The region spans far enough to stack wide toasts but must not swallow
+      // clicks meant for the page beneath it — `none` here, `auto` on each
+      // card. Without this pairing a dismissed-but-still-animating toast
+      // leaves an invisible plate over the corner of the app.
+      pointerEvents: "none",
+      maxWidth: "calc(100vw - {spacing.8})",
+      zIndex: "toast",
+    },
+    root: {
+      pointerEvents: "auto",
+      display: "flex",
+      alignItems: "center",
+      gap: "4",
+      borderRadius: "md",
+      boxShadow: "lg",
+      paddingInline: "4",
+      paddingBlock: "3",
+      minWidth: { base: "320px", lg: "600px" },
+      maxWidth: { base: "400px", lg: "700px" },
+      fontSize: "md",
+      // Stated, not inherited: a themed typeface otherwise reaches the page and
+      // stops at the edge of the component (NEH-289).
+      fontFamily: "body",
+      borderWidth: "1px",
+      borderStyle: "solid",
+      // `borderBgPrimary`, not the `borderSubtle` this was first written with:
+      // that token belongs to HopperGuard's vocabulary, not this package's, and
+      // Panda passes an unknown token through as a literal — the card would
+      // have rendered with `border-color: borderSubtle`, which the browser
+      // discards, so the toast would have had no border at all and nothing
+      // would have said so. The package's own token-contract test caught it.
+      borderColor: "borderBgPrimary",
+      backgroundColor: "boxBgPrimary",
+      color: "textPrimary",
+      transition: "opacity 200ms ease, transform 200ms ease",
+      // `data-state` rather than a class: the renderer flips one attribute and
+      // the same rule drives both directions, so there is no window in which a
+      // toast has neither state.
+      "&[data-state='closed']": {
+        opacity: "0",
+        transform: "translateY(0.5rem)",
+      },
+      "&[data-state='open']": {
+        opacity: "1",
+        transform: "translateY(0)",
+      },
+    },
+    indicator: {
+      flexShrink: 0,
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      lineHeight: "1",
+      fontSize: "lg",
+    },
+    content: {
+      flex: "1",
+      minWidth: "0",
+      display: "flex",
+      flexDirection: "column",
+      gap: "1",
+    },
+    title: {
+      fontWeight: "bold",
+    },
+    description: {
+      display: "block",
+    },
+    action: {
+      flexShrink: 0,
+    },
+    close: {
+      flexShrink: 0,
+      display: "inline-flex",
+      alignItems: "center",
+      justifyContent: "center",
+      // 48px, matching every other interactive floor in this package. A close
+      // control is the one thing on a toast a person is *aiming* at, often
+      // while it is animating, so it is the last place to shave a target down
+      // to the size of its glyph.
+      minWidth: "48px",
+      minHeight: "48px",
+      borderRadius: "md",
+      borderWidth: "1px",
+      borderStyle: "solid",
+      borderColor: "transparent",
+      background: "transparent",
+      color: "inherit",
+      cursor: "pointer",
+    },
+  },
+  variants: {
+    /**
+     * The status accent. `default` deliberately has none — a toast that means
+     * nothing in particular should not borrow a colour that means something.
+     */
+    type: {
+      success: { root: { borderInlineStartWidth: "4px", borderInlineStartColor: "borderSuccess" } },
+      error: { root: { borderInlineStartWidth: "4px", borderInlineStartColor: "borderError" } },
+      warning: { root: { borderInlineStartWidth: "4px", borderInlineStartColor: "borderWarning" } },
+      info: { root: { borderInlineStartWidth: "4px", borderInlineStartColor: "borderBgAccent" } },
+      loading: { root: { borderInlineStartWidth: "4px", borderInlineStartColor: "borderBgAccent" } },
+      default: {},
+    },
+  },
+  defaultVariants: {
+    type: "default",
+  },
+});