@stonedogcode/style 0.16.0 → 0.19.0

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/config/font-size.ts

@@ -147,3 +147,28 @@ export function stepUpFontSize(size: FontSizeKey, steps = 1): FontSizeKey {
   // clamp fails safe instead of returning undefined to a caller typed otherwise.
   return next ?? size;
 }
+
+/**
+ * The next size DOWN, clamped at the bottom of the scale.
+ *
+ * The counterpart to `stepUpFontSize`, added for `StyledFieldHelp` (NEH-972),
+ * and the clamp is the load-bearing half. Inline help is deliberately one tier
+ * below the text it accompanies — but "one tier below" must never mean "below
+ * the smallest tier the host offers", because the reader who has turned their
+ * text size all the way down is the reader with the least room to spare. At
+ * `xs` this returns `xs`, so help matches the body text rather than shrinking
+ * past it.
+ *
+ * Steps through `FONT_SIZE_ORDER`, so it moves through whatever scale the host
+ * has pinned its `--font-sizes-*` properties to rather than through a fixed set
+ * of pixel values.
+ */
+export function stepDownFontSize(size: FontSizeKey, steps = 1): FontSizeKey {
+  const index = FONT_SIZE_ORDER.indexOf(size);
+  if (index === -1) return size;
+  const next = FONT_SIZE_ORDER[Math.max(index - steps, 0)];
+  // Clamped into range above, so this cannot miss — but staying total means a
+  // future change to the clamp fails safe rather than handing a caller
+  // `undefined` from a function typed otherwise. Same shape as stepUpFontSize.
+  return next ?? size;
+}

package/src/index.ts

@@ -48,6 +48,7 @@ export {
   getFontSizeLabel,
   getFontSizeValue,
   stepUpFontSize,
+  stepDownFontSize,
   FONT_SIZE_ORDER,
 } from "./config/font-size";
 
@@ -197,6 +198,18 @@ export type { StyledTooltipProps } from "./components/StyledTooltip";
 export { default as StyledFormLabel } from "./components/StyledFormLabel";
 export type { StyledFormLabelProps } from "./components/StyledFormLabel";
 
+/**
+ * Permanent inline help for a field — PRD-0037's replacement for the hover
+ * tooltip and its `?` button. `fieldHelpId` is exported so a host can put the
+ * `aria-describedby` association in server-rendered HTML.
+ */
+export {
+  default as StyledFieldHelp,
+  StyledFieldHelp as FieldHelp,
+  fieldHelpId,
+} from "./components/StyledFieldHelp";
+export type { StyledFieldHelpProps } from "./components/StyledFieldHelp";
+
 // ---------------------------------------------------------------------------
 // Components that were blocked on a runtime dependency until NEH-430 gave each
 // a seam with a working default. None of them adds a dependency; the host
@@ -302,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,
 };