@vvedantb/ui 0.2.1 → 0.2.2

package/README.md

@@ -4,9 +4,9 @@ Shared React 19 web UI. Source-exported: no build step.
 
 | Import | What it is |
 | --- | --- |
-| `@vvedantb/ui` | Primitives (Radix-based) and AI elements. |
+| `@vvedantb/ui` | Primitives (Radix-based), AI elements, `playChime` and `useReplyChime`. |
 | `@vvedantb/ui/cn` | `cn` class helper (clsx + tailwind-merge). |
-| `@vvedantb/ui/shell` | Router-free `SidebarHeader` and `PillTabs`. |
+| `@vvedantb/ui/shell` | Router-free `SidebarHeader`, `PillTabs` and `SessionsHoverCard`. |
 | `@vvedantb/ui/app` | Alt-click confirm skip, update watcher, settings chrome, `useStableAuth`. See `app/README.md` in the repository. |
 | `@vvedantb/ui/tokens` | `tokens.css`: colour, radius, shadow, ease and font tokens for Tailwind v4. |
 | `@vvedantb/ui/tokens/css/*.css` | `index`, `base`, `dialog`, `modal`, `tabs`, `tabs-pills`, `utilities`, `scrollbar-thin`, `animations`, `compat-shadcn-rgb`. |
@@ -20,6 +20,67 @@ Shared React 19 web UI. Source-exported: no build step.
 @source "../node_modules/@vvedantb/ui/src/**/*.{ts,tsx}";
 ```
 
+## Reply chime
+
+```tsx
+import { playChime, useReplyChime } from "@vvedantb/ui";
+
+useReplyChime({ enabled: soundOn, isStreaming, threadId });
+```
+
+- `playChime()`: soft rising two-note chime (WebAudio). One shared `AudioContext`, created on first use. It is a no-op on the server and when autoplay blocks audio. Calls less than 1 second apart play once.
+- `useReplyChime`: chimes once when `isStreaming` goes from `true` to `false` for the same `threadId`. It is silent on the first sight of a thread, when `threadId` changes, and when `threadId` is null or undefined. While `enabled` is `false` it still tracks the edge, so enabling mid-turn does not replay a finish.
+
+## Sessions hover card
+
+```tsx
+import { SessionsHoverCard } from "@vvedantb/ui/shell";
+
+<SessionsHoverCard
+  header="Session title"
+  loadContent={() => fetchPreview(id)}
+  footer="Updated today"
+>
+  <button type="button">Row</button>
+</SessionsHoverCard>
+```
+
+`children` is the trigger. Defaults: `openDelay` 400 ms, `closeDelay` 150 ms, `side="right"`, `align="start"`, `sideOffset` 8, width and padding `w-64 p-3` (override with `className`). `body` is a node or a function of `{ open }`. `loadContent` runs only while the card is open. Control the state with `open`, `defaultOpen` and `onOpenChange`. Fixture: `shell/examples/sessions-hover-card/`.
+
+## Toaster
+
+```tsx
+import { toast } from "sonner";
+import { SonnerToaster } from "@vvedantb/ui";
+
+<SonnerToaster
+  theme={theme}
+  toastRadius="surface"
+  toastIcons="filled24"
+  closeButtonStyle="hoverChip"
+  sonnerVars
+  descriptionMuted
+/>;
+```
+
+With no new props the toaster looks as it did in 0.2.1. Caller props merge with the package defaults instead of replacing them:
+
+- `toastOptions.classNames`: per key, the package classes come first and the caller classes follow, so callers can override utilities. Other `toastOptions` fields (such as `duration`) take the caller value.
+- `icons`: merged per key. With `toastIcons="filled24"` the caller overrides single icons and keeps the rest.
+- `style`: merged over the package style. `className` is appended.
+
+Opt-in props (all default to the current look):
+
+| Prop | Values | Effect |
+| --- | --- | --- |
+| `toastRadius` | `"lg"` (default), `"surface"` | `rounded-lg` or `rounded-surface` (from `tokens/css/utilities.css`). |
+| `toastIcons` | `"default"`, `"filled24"` | Sonner icons or 24px filled success, info, warning and error icons, a matching loader and a 14px close cross. |
+| `closeButtonStyle` | `"default"`, `"hoverChip"` | Text-style close button or a round chip at the top-right, shown on hover and always on small screens. It turns on `closeButton` unless you set it. |
+| `sonnerVars` | `false` (default), `true` | Sets `--normal-bg`, `--normal-border`, `--normal-text`, `--normal-bg-hover` and `--normal-border-hover` from `--color-card`, `--color-border`, `--color-foreground` and `--color-muted`, and `font-family: inherit`. |
+| `descriptionMuted` | `false` (default), `true` | Description uses `text-muted-foreground!`, which beats sonner's dark-theme rule. |
+
+Helpers: `createToasterClassNames`, `mergeToastClassNames`, `mergeToastOptions`, `mergeToasterStyle`, `filledToastIcons`. Fixture: `tokens/examples/toaster/`.
+
 ## Colour names in components
 
 Components use `text-muted-foreground`, `primary` and `--color-*` theme variables. They no longer use `text-muted`, `*-accent` or raw `var(--muted)` reads, which clash with shadcn names. `tokens.css` still defines `--color-muted` and `--color-accent`. `pnpm --filter @vvedantb/ui check:tokens` fails if a component brings the old names back (it also runs in `build`, `test` and `verify`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: primitives, shell pieces, app helpers, design tokens, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",
@@ -61,7 +61,9 @@
     "tokens/src",
     "tokens/examples",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
   ],
   "sideEffects": [
     "./src/ui/sonner.css"

package/shell/src/SessionsHoverCard.tsx

@@ -0,0 +1,148 @@
+import { useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import {
+  HoverCard,
+  HoverCardContent,
+  HoverCardTrigger,
+} from "../../src/ui/hover-card";
+import { cn } from "../../src/utils/cn";
+
+export type SessionsHoverCardContext = { open: boolean };
+
+export type SessionsHoverCardProps = {
+  /** The element that triggers the card, such as a list row. Rendered with `asChild`. */
+  children: ReactNode;
+  header?: ReactNode;
+  /**
+   * Body slot. A function runs only while the card is open, so it can start
+   * fetches for preview data.
+   */
+  body?: ReactNode | ((ctx: SessionsHoverCardContext) => ReactNode);
+  /** Runs each time the card opens. Its result replaces `body`. */
+  loadContent?: () => Promise<ReactNode> | ReactNode;
+  /** Shown while `loadContent` is pending. */
+  loadingFallback?: ReactNode;
+  footer?: ReactNode;
+  /** Controlled open state. */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Delay before opening, in milliseconds. */
+  openDelay?: number;
+  /** Delay before closing, in milliseconds. */
+  closeDelay?: number;
+  side?: "top" | "right" | "bottom" | "left";
+  align?: "start" | "center" | "end";
+  sideOffset?: number;
+  /** Merged over the default `w-64 p-3`. */
+  className?: string;
+};
+
+type LoadState = { status: "loading" } | { status: "ready"; node: ReactNode };
+
+/** Mounts only while the card is open, so `loadContent` never runs while closed. */
+function LoadedBody({
+  loadContent,
+  fallback,
+}: {
+  loadContent: () => Promise<ReactNode> | ReactNode;
+  fallback: ReactNode;
+}) {
+  const [state, setState] = useState<LoadState>({ status: "loading" });
+
+  useEffect(() => {
+    let cancelled = false;
+    Promise.resolve()
+      .then(loadContent)
+      .then((node) => {
+        if (!cancelled) setState({ status: "ready", node });
+      })
+      .catch(() => {
+        if (!cancelled) setState({ status: "ready", node: null });
+      });
+    return () => {
+      cancelled = true;
+    };
+    // Run once per open. A new `loadContent` identity must not refetch.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return <>{state.status === "ready" ? state.node : fallback}</>;
+}
+
+/** Calls the render prop. Mounts only inside open content, never while closed. */
+function RenderBody({
+  render,
+  open,
+}: {
+  render: (ctx: SessionsHoverCardContext) => ReactNode;
+  open: boolean;
+}) {
+  return <>{render({ open })}</>;
+}
+
+/**
+ * Hover card shell for list rows such as a sessions sidebar. It sets delay,
+ * position, width and padding, and gives header, body and footer slots. The
+ * app supplies the content.
+ */
+export function SessionsHoverCard({
+  children,
+  header,
+  body,
+  loadContent,
+  loadingFallback = null,
+  footer,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  openDelay = 400,
+  closeDelay = 150,
+  side = "right",
+  align = "start",
+  sideOffset = 8,
+  className,
+}: SessionsHoverCardProps) {
+  const [openState, setOpenState] = useState(defaultOpen);
+  const open = openProp ?? openState;
+
+  const handleOpenChange = (next: boolean) => {
+    setOpenState(next);
+    onOpenChange?.(next);
+  };
+
+  const bodyNode = loadContent ? (
+    <LoadedBody loadContent={loadContent} fallback={loadingFallback} />
+  ) : typeof body === "function" ? (
+    <RenderBody render={body} open={open} />
+  ) : (
+    body
+  );
+
+  return (
+    <HoverCard
+      open={open}
+      onOpenChange={handleOpenChange}
+      openDelay={openDelay}
+      closeDelay={closeDelay}
+    >
+      <HoverCardTrigger asChild>{children}</HoverCardTrigger>
+      <HoverCardContent
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        className={cn("w-64 p-3", className)}
+      >
+        {header ? (
+          <div className="mb-2 text-sm font-medium text-foreground">{header}</div>
+        ) : null}
+        {bodyNode != null ? (
+          <div className="text-sm text-muted-foreground">{bodyNode}</div>
+        ) : null}
+        {footer ? (
+          <div className="mt-2 text-xs text-muted-foreground">{footer}</div>
+        ) : null}
+      </HoverCardContent>
+    </HoverCard>
+  );
+}

package/shell/src/index.ts

@@ -4,3 +4,8 @@ export { PillTabs } from "./PillTabs.js";
 export type { PillTabItem, PillTabsProps } from "./PillTabs.js";
 export { cn } from "./cn.js";
 export type { ClassValue } from "./cn.js";
+export { SessionsHoverCard } from "./SessionsHoverCard.js";
+export type {
+  SessionsHoverCardContext,
+  SessionsHoverCardProps,
+} from "./SessionsHoverCard.js";

package/src/audio/index.ts

@@ -0,0 +1,3 @@
+export { playChime } from "./playChime";
+export { useReplyChime, nextReplyChimeState } from "./useReplyChime";
+export type { ReplyChimeInput, ReplyChimeWatch } from "./useReplyChime";

package/src/audio/playChime.ts

@@ -0,0 +1,76 @@
+type Tone = {
+  frequency: number;
+  startOffsetS: number;
+  durationS: number;
+  peakGain: number;
+};
+
+/** A soft rising interval (A5 then D6). The second note overlaps the first. */
+const REPLY_CHIME: readonly Tone[] = [
+  { frequency: 880, startOffsetS: 0, durationS: 0.28, peakGain: 0.14 },
+  { frequency: 1174.66, startOffsetS: 0.09, durationS: 0.28, peakGain: 0.14 },
+];
+
+/** Long enough to avoid a click on attack. */
+const ATTACK_S = 0.012;
+
+/** Calls closer together than this are dropped, so overlapping events sound once. */
+const MIN_INTERVAL_S = 1;
+
+let sharedContext: AudioContext | null = null;
+let lastPlayedAtS: number | null = null;
+
+function getAudioContext(): AudioContext | null {
+  if (sharedContext) return sharedContext;
+  if (typeof window === "undefined" || !window.AudioContext) return null;
+  try {
+    sharedContext = new window.AudioContext();
+  } catch {
+    return null;
+  }
+  return sharedContext;
+}
+
+/**
+ * Plays a soft rising two-note chime with WebAudio.
+ *
+ * The context is created on first use and shared. The call is a no-op on the
+ * server, without WebAudio, or while autoplay policy blocks audio.
+ */
+export function playChime(): void {
+  const context = getAudioContext();
+  if (!context) return;
+
+  if (context.state === "suspended") {
+    try {
+      context.resume().catch(() => undefined);
+    } catch {
+      return;
+    }
+  }
+
+  const start = context.currentTime;
+  if (lastPlayedAtS !== null && start - lastPlayedAtS < MIN_INTERVAL_S) return;
+  lastPlayedAtS = start;
+
+  try {
+    for (const tone of REPLY_CHIME) {
+      const oscillator = context.createOscillator();
+      const envelope = context.createGain();
+      oscillator.type = "sine";
+      oscillator.frequency.value = tone.frequency;
+
+      const toneStart = start + tone.startOffsetS;
+      const toneEnd = toneStart + tone.durationS;
+      envelope.gain.setValueAtTime(0, toneStart);
+      envelope.gain.linearRampToValueAtTime(tone.peakGain, toneStart + ATTACK_S);
+      envelope.gain.exponentialRampToValueAtTime(0.0001, toneEnd);
+
+      oscillator.connect(envelope).connect(context.destination);
+      oscillator.start(toneStart);
+      oscillator.stop(toneEnd);
+    }
+  } catch {
+    // Audio is optional. Stay silent on any failure.
+  }
+}

package/src/audio/useReplyChime.ts

@@ -0,0 +1,62 @@
+import { useEffect, useRef } from "react";
+import { playChime } from "./playChime";
+
+export type ReplyChimeWatch = {
+  threadId: string;
+  wasStreaming: boolean;
+};
+
+export type ReplyChimeInput = {
+  enabled: boolean;
+  isStreaming: boolean;
+  threadId: string | null | undefined;
+};
+
+/**
+ * Pure transition for the reply chime. Returns the state to remember and
+ * whether to chime.
+ *
+ * - No thread id: reset tracking and stay silent.
+ * - First observation of a thread (or a new thread): silent.
+ * - Chime only on streaming to finished for the same thread, while enabled.
+ * - The edge is tracked while disabled, so enabling mid-turn does not replay
+ *   a finish that already happened.
+ */
+export function nextReplyChimeState(
+  previous: ReplyChimeWatch | null,
+  { enabled, isStreaming, threadId }: ReplyChimeInput,
+): { next: ReplyChimeWatch | null; chime: boolean } {
+  if (threadId == null || threadId === "") {
+    return { next: null, chime: false };
+  }
+  const next = { threadId, wasStreaming: isStreaming };
+  if (!previous || previous.threadId !== threadId) {
+    return { next, chime: false };
+  }
+  const finished = previous.wasStreaming && !isStreaming;
+  return { next, chime: finished && enabled };
+}
+
+/**
+ * Plays the reply chime once when a thread finishes streaming.
+ *
+ * Silent on the first observation of a thread, so opening a settled thread
+ * does not chime for an earlier turn.
+ */
+export function useReplyChime({
+  enabled,
+  isStreaming,
+  threadId,
+}: ReplyChimeInput): void {
+  const watchedRef = useRef<ReplyChimeWatch | null>(null);
+
+  useEffect(() => {
+    const { next, chime } = nextReplyChimeState(watchedRef.current, {
+      enabled,
+      isStreaming,
+      threadId,
+    });
+    watchedRef.current = next;
+    if (chime) playChime();
+  }, [enabled, isStreaming, threadId]);
+}

package/src/index.ts

@@ -96,3 +96,5 @@ export * from "./ai-elements/shimmer";
 export * from "./ai-elements/sources";
 export * from "./ai-elements/speech-input";
 export * from "./ai-elements/suggestion";
+
+export * from "./audio";

package/src/ui/sonner-icons.tsx

@@ -0,0 +1,94 @@
+import { Spinner } from "./spinner";
+
+// 24px filled icons for `SonnerToaster` (`toastIcons="filled24"`). Self-contained
+// SVGs, tinted with package colour tokens. Sonner wraps each in its `data-icon` slot.
+
+function InfoIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      className="h-6 w-6 fill-current text-primary"
+      fill="none"
+      viewBox="0 0 24 24"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="M12 22C17.51 22 22 17.51 22 12C22 6.49 17.51 2 12 2C6.49 2 2 6.49 2 12C2 17.51 6.49 22 12 22ZM12.75 16C12.75 16.41 12.41 16.75 12 16.75C11.59 16.75 11.25 16.41 11.25 16L11.25 11C11.25 10.59 11.59 10.25 12 10.25C12.41 10.25 12.75 10.59 12.75 11L12.75 16ZM11.08 7.62C11.13 7.49 11.2 7.39 11.29 7.29C11.39 7.2 11.5 7.13 11.62 7.08C11.74 7.03 11.87 7 12 7C12.13 7 12.26 7.03 12.38 7.08C12.5 7.13 12.61 7.2 12.71 7.29C12.8 7.39 12.87 7.49 12.92 7.62C12.97 7.74 13 7.87 13 8C13 8.13 12.97 8.26 12.92 8.38C12.87 8.5 12.8 8.61 12.71 8.71C12.61 8.8 12.5 8.87 12.38 8.92C12.14 9.02 11.86 9.02 11.62 8.92C11.5 8.87 11.39 8.8 11.29 8.71C11.2 8.61 11.13 8.5 11.08 8.38C11.03 8.26 11 8.13 11 8C11 7.87 11.03 7.74 11.08 7.62Z" />
+    </svg>
+  );
+}
+
+function SuccessIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      className="h-6 w-6 fill-current text-success"
+      fill="none"
+      viewBox="0 0 24 24"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="M12 2C6.49 2 2 6.49 2 12C2 17.51 6.49 22 12 22C17.51 22 22 17.51 22 12C22 6.49 17.51 2 12 2ZM16.78 9.7L11.11 15.37C10.97 15.51 10.78 15.59 10.58 15.59C10.38 15.59 10.19 15.51 10.05 15.37L7.22 12.54C6.93 12.25 6.93 11.77 7.22 11.48C7.51 11.19 7.99 11.19 8.28 11.48L10.58 13.78L15.72 8.64C16.01 8.35 16.49 8.35 16.78 8.64C17.07 8.93 17.07 9.4 16.78 9.7Z" />
+    </svg>
+  );
+}
+
+function WarningIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      className="h-6 w-6 fill-current text-warning"
+      fill="none"
+      viewBox="0 0 24 24"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        clipRule="evenodd"
+        d="M3 10.417C3 7.219 3 5.62 3.378 5.082C3.755 4.545 5.258 4.03 8.265 3.001L8.838 2.805C10.405 2.268 11.188 2 12 2C12.812 2 13.595 2.268 15.162 2.805L15.735 3.001C18.742 4.03 20.245 4.545 20.622 5.082C21 5.62 21 7.22 21 10.417V11.991C21 17.629 16.761 20.366 14.101 21.527C13.38 21.842 13.02 22 12 22C10.98 22 10.62 21.842 9.899 21.527C7.239 20.365 3 17.63 3 11.991V10.417ZM12 7.25C12.1989 7.25 12.3897 7.32902 12.5303 7.46967C12.671 7.61032 12.75 7.80109 12.75 8V12C12.75 12.1989 12.671 12.3897 12.5303 12.5303C12.3897 12.671 12.1989 12.75 12 12.75C11.8011 12.75 11.6103 12.671 11.4697 12.5303C11.329 12.3897 11.25 12.1989 11.25 12V8C11.25 7.80109 11.329 7.61032 11.4697 7.46967C11.6103 7.32902 11.8011 7.25 12 7.25ZM12 16C12.2652 16 12.5196 15.8946 12.7071 15.7071C12.8946 15.5196 13 15.2652 13 15C13 14.7348 12.8946 14.4804 12.7071 14.2929C12.5196 14.1054 12.2652 14 12 14C11.7348 14 11.4804 14.1054 11.2929 14.2929C11.1054 14.4804 11 14.7348 11 15C11 15.2652 11.1054 15.5196 11.2929 15.7071C11.4804 15.8946 11.7348 16 12 16Z"
+        fillRule="evenodd"
+      />
+    </svg>
+  );
+}
+
+function ErrorIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      className="h-6 w-6 fill-current text-destructive"
+      fill="none"
+      viewBox="0 0 20 20"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="M17.51 3.85L11.57 0.42C10.6 -0.14 9.4 -0.14 8.42 0.42L2.49 3.85C1.52 4.41 0.919998 5.45 0.919998 6.58V13.42C0.919998 14.54 1.52 15.58 2.49 16.15L8.43 19.58C9.4 20.14 10.6 20.14 11.58 19.58L17.52 16.15C18.49 15.59 19.09 14.55 19.09 13.42V6.58C19.08 5.45 18.48 4.42 17.51 3.85ZM9.25 5.75C9.25 5.34 9.59 5 10 5C10.41 5 10.75 5.34 10.75 5.75V11C10.75 11.41 10.41 11.75 10 11.75C9.59 11.75 9.25 11.41 9.25 11V5.75ZM10.92 14.63C10.87 14.75 10.8 14.86 10.71 14.96C10.52 15.15 10.27 15.25 10 15.25C9.87 15.25 9.74 15.22 9.62 15.17C9.49 15.12 9.39 15.05 9.29 14.96C9.2 14.86 9.13 14.75 9.07 14.63C9.02 14.51 9 14.38 9 14.25C9 13.99 9.1 13.73 9.29 13.54C9.39 13.45 9.49 13.38 9.62 13.33C9.99 13.17 10.43 13.26 10.71 13.54C10.8 13.64 10.87 13.74 10.92 13.87C10.97 13.99 11 14.12 11 14.25C11 14.38 10.97 14.51 10.92 14.63Z" />
+    </svg>
+  );
+}
+
+function CloseIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      className="h-3.5 w-3.5"
+      fill="none"
+      stroke="currentColor"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth={2}
+      viewBox="0 0 24 24"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="M18 6L6 18M6 6l12 12" />
+    </svg>
+  );
+}
+
+/** 24px success / info / warning / error icons, a matching loader and a 14px close cross. */
+const filledToastIcons = {
+  success: <SuccessIcon />,
+  info: <InfoIcon />,
+  warning: <WarningIcon />,
+  error: <ErrorIcon />,
+  loading: <Spinner size="md" aria-hidden="true" />,
+  close: <CloseIcon />,
+};
+
+export { filledToastIcons };

package/src/ui/sonner.tsx

@@ -1,47 +1,180 @@
+import type { CSSProperties } from "react";
 import { Toaster, type ToasterProps } from "sonner";
+import { filledToastIcons } from "./sonner-icons";
 import "./sonner.css";
 
-// sonner toaster aligned with flat tonal surfaces `unstyled: true` strips sonner's default visual styling so our classes are
-// the single source of truth toast surfaces use `glass, panel, strong` (flat
-// popover fill) plus `smooth-shadow-ring-md` `!font, sans` is forced on the toaster section because sonner sets its own
-// `font, family` on `[data, sonner, toaster]` from a stylesheet that ships with
-// the package (loaded after our globals), so plain inheritance from `<body>`
-// loses the cascade the `!important` here guarantees instrument sans wins, toasts inherit from the section, so this single class covers everything variant icons (success / error / warning / info) are tinted via a
-// `data, icon` descendant selector, leaving the rest of the toast neutral callers should pass `theme` from `next, themes` so sonner's internal
-// `data, theme` attribute matches the active app theme (used by its focus
-// ring and a few internal states that aren't reachable via classnames) stacking: `expand={false}` keeps toasts collapsed (offset + scale) hovering
-// the stack expands them `sonner.css` hides back, toast content while collapsed
-// because `unstyled` disables sonner's built, in `data, styled` stack rules
-function SonnerToaster(props: ToasterProps) {
+// Sonner toaster aligned with flat tonal surfaces. `unstyled: true` strips
+// sonner's default visual styling so our classes are the single source of
+// truth. Toast surfaces use `glass-panel-strong` (flat popover fill) plus
+// `smooth-shadow-ring-md`. `!font-sans` is forced on the toaster section because
+// sonner sets its own `font-family` on `[data-sonner-toaster]` from a stylesheet
+// that loads after app globals. Variant icons (success / error / warning / info)
+// are tinted via a `data-icon` descendant selector, leaving the rest of the toast
+// neutral. Callers should pass `theme` so sonner's internal `data-theme`
+// attribute matches the active app theme.
+//
+// Stacking: `expand={false}` keeps toasts collapsed (offset + scale). Hovering
+// the stack expands them. `sonner.css` hides back-toast content while collapsed
+// because `unstyled` disables sonner's built-in `data-styled` stack rules.
+//
+// Caller props merge with these defaults instead of replacing them: see
+// `mergeToastClassNames`, `mergeToasterStyle` and the `SonnerToaster` props.
+
+type ToastClassNames = NonNullable<
+  NonNullable<ToasterProps["toastOptions"]>["classNames"]
+>;
+type ToasterStyle = CSSProperties & Record<`--${string}`, string>;
+
+type SonnerToasterOptions = {
+  /** `"lg"` (default) uses `rounded-lg`. `"surface"` uses `rounded-surface`. */
+  toastRadius?: "lg" | "surface";
+  /** `"default"` keeps sonner's icons. `"filled24"` uses 24px filled icons. */
+  toastIcons?: "default" | "filled24";
+  /**
+   * `"default"` keeps the text-style close button. `"hoverChip"` uses a round chip at the
+   * top-right, shown on hover (always on small screens) and enables sonner's `closeButton`
+   * unless the caller sets it.
+   */
+  closeButtonStyle?: "default" | "hoverChip";
+  /** When true, set sonner's `--normal-*` variables from `--color-*` tokens and `font-family: inherit`. */
+  sonnerVars?: boolean;
+  /** When true, descriptions use `text-muted-foreground!` so sonner's dark rule cannot win. */
+  descriptionMuted?: boolean;
+};
+
+const hoverChipCloseButtonClassName =
+  "pointer-events-none absolute -right-2 -top-2 z-10 flex h-6 w-6 items-center justify-center rounded-full border border-border bg-card/95 text-muted-foreground opacity-0 transition-opacity hover:text-foreground focus-visible:pointer-events-auto focus-visible:opacity-100 focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring group-hover:pointer-events-auto group-hover:opacity-100 max-sm:pointer-events-auto max-sm:opacity-100 max-sm:hit-target";
+
+const defaultCloseButtonClassName =
+  "rounded-lg bg-default px-2.5 py-1 text-xs font-medium text-foreground transition-colors hover:bg-default/78";
+
+/** Default `classNames`, with the opt-in variants applied. No options gives the 0.2.1 defaults. */
+function createToasterClassNames({
+  toastRadius = "lg",
+  closeButtonStyle = "default",
+  descriptionMuted = false,
+}: Pick<
+  SonnerToasterOptions,
+  "toastRadius" | "closeButtonStyle" | "descriptionMuted"
+> = {}): ToastClassNames {
+  const radius = toastRadius === "surface" ? "rounded-surface" : "rounded-lg";
+  return {
+    toast: `group toast glass-panel-strong flex w-full items-center gap-3 ${radius} px-4 py-3 text-sm text-foreground smooth-shadow-ring-md`,
+    title: "font-medium leading-snug",
+    description: descriptionMuted
+      ? "text-[13px] leading-snug text-muted-foreground!"
+      : "text-[13px] leading-snug text-muted-foreground",
+    actionButton:
+      "rounded-lg bg-primary px-2.5 py-1 text-xs font-medium text-primary-foreground transition-opacity hover:opacity-90",
+    cancelButton:
+      "rounded-lg bg-surface-secondary px-2.5 py-1 text-xs font-medium text-muted-foreground transition-colors hover:bg-surface-tertiary",
+    closeButton:
+      closeButtonStyle === "hoverChip"
+        ? hoverChipCloseButtonClassName
+        : defaultCloseButtonClassName,
+    loader: "text-muted-foreground",
+    success: "[&_[data-icon]]:text-success",
+    error: "[&_[data-icon]]:text-danger",
+    warning: "[&_[data-icon]]:text-warning",
+    info: "[&_[data-icon]]:text-primary",
+  };
+}
+
+/** Per key, joins the default class string and the caller string (defaults first, so callers win). */
+function mergeToastClassNames(
+  defaults: ToastClassNames,
+  overrides?: ToastClassNames,
+): ToastClassNames {
+  if (!overrides) return defaults;
+  const merged: Record<string, string | undefined> = { ...defaults };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!value) continue;
+    const base = merged[key];
+    merged[key] = base ? `${base} ${value}` : value;
+  }
+  return merged as ToastClassNames;
+}
+
+/** Sonner variables read from `--color-*` tokens. Work with `tokens.css` and the compat file. */
+const sonnerVarsStyle: ToasterStyle = {
+  fontFamily: "inherit",
+  "--normal-bg": "var(--color-card)",
+  "--normal-border": "var(--color-border)",
+  "--normal-text": "var(--color-foreground)",
+  "--normal-bg-hover": "var(--color-muted)",
+  "--normal-border-hover": "var(--color-border)",
+};
+
+/** `{ ...defaults, ...overrides }`. The package adds no style keys unless `sonnerVars` is on. */
+function mergeToasterStyle(
+  defaults: CSSProperties | undefined,
+  overrides: CSSProperties | undefined,
+): CSSProperties | undefined {
+  if (!defaults) return overrides;
+  return overrides ? { ...defaults, ...overrides } : defaults;
+}
+
+/** Package defaults first. Caller wins per field, except `classNames`, which merge. */
+function mergeToastOptions(
+  defaults: NonNullable<ToasterProps["toastOptions"]>,
+  overrides?: ToasterProps["toastOptions"],
+): NonNullable<ToasterProps["toastOptions"]> {
+  const { classNames, ...rest } = overrides ?? {};
+  return {
+    ...defaults,
+    ...rest,
+    classNames: mergeToastClassNames(defaults.classNames ?? {}, classNames),
+  };
+}
+
+function SonnerToaster({
+  toastRadius,
+  toastIcons = "default",
+  closeButtonStyle = "default",
+  sonnerVars = false,
+  descriptionMuted,
+  toastOptions,
+  icons,
+  style,
+  className,
+  closeButton,
+  ...props
+}: ToasterProps & SonnerToasterOptions) {
+  const mergedIcons =
+    toastIcons === "filled24" ? { ...filledToastIcons, ...icons } : icons;
   return (
     <Toaster
       expand={false}
       visibleToasts={4}
       gap={12}
-      className="toaster group !font-sans"
-      toastOptions={{
-        unstyled: true,
-        classNames: {
-          toast:
-            "group toast glass-panel-strong flex w-full items-center gap-3 rounded-lg px-4 py-3 text-sm text-foreground smooth-shadow-ring-md",
-          title: "font-medium leading-snug",
-          description: "text-[13px] leading-snug text-muted-foreground",
-          actionButton:
-            "rounded-lg bg-primary px-2.5 py-1 text-xs font-medium text-primary-foreground transition-opacity hover:opacity-90",
-          cancelButton:
-            "rounded-lg bg-surface-secondary px-2.5 py-1 text-xs font-medium text-muted-foreground transition-colors hover:bg-surface-tertiary",
-          closeButton:
-            "rounded-lg bg-default px-2.5 py-1 text-xs font-medium text-foreground transition-colors hover:bg-default/78",
-          loader: "text-muted-foreground",
-          success: "[&_[data-icon]]:text-success",
-          error: "[&_[data-icon]]:text-danger",
-          warning: "[&_[data-icon]]:text-warning",
-          info: "[&_[data-icon]]:text-primary",
-        },
-      }}
       {...props}
+      closeButton={closeButton ?? (closeButtonStyle === "hoverChip" ? true : undefined)}
+      className={className ? `toaster group !font-sans ${className}` : "toaster group !font-sans"}
+      icons={mergedIcons}
+      style={mergeToasterStyle(sonnerVars ? sonnerVarsStyle : undefined, style)}
+      toastOptions={mergeToastOptions(
+        {
+          unstyled: true,
+          classNames: createToasterClassNames({
+            toastRadius,
+            closeButtonStyle,
+            descriptionMuted,
+          }),
+        },
+        toastOptions,
+      )}
     />
   );
 }
 
-export { SonnerToaster };
+export {
+  SonnerToaster,
+  createToasterClassNames,
+  hoverChipCloseButtonClassName,
+  mergeToastClassNames,
+  mergeToastOptions,
+  mergeToasterStyle,
+  sonnerVarsStyle,
+};
+export { filledToastIcons } from "./sonner-icons";
+export type { SonnerToasterOptions };

package/tokens/README.md

@@ -13,7 +13,7 @@ Design tokens and shared Tailwind v4 CSS for the vvedantb web apps, plus JS toke
 | `@vvedantb/ui/tokens/css/modal.css` | `src/css/modal.css` | `.t-modal`, `.is-open`, `.is-closing` and `t-modal-presence-wait` (`@layer components`). |
 | `@vvedantb/ui/tokens/css/tabs.css` | `src/css/tabs.css` | `.t-tab`, active colour, `.t-tabs-pill`, small-screen `.t-tabs` scrolling. |
 | `@vvedantb/ui/tokens/css/tabs-pills.css` | `src/css/tabs-pills.css` | `--tabs-*` colour variables, `.t-tabs--segmented`, `.t-tabs--pills` and pill hover / active fills. |
-| `@vvedantb/ui/tokens/css/utilities.css` | `src/css/utilities.css` | `@utility hit-target` and `@utility reveal-on-hover`. |
+| `@vvedantb/ui/tokens/css/utilities.css` | `src/css/utilities.css` | `@utility hit-target`, `@utility reveal-on-hover` and `@utility rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`). |
 | `@vvedantb/ui/tokens/css/scrollbar-thin.css` | `src/css/scrollbar-thin.css` | `.scrollbar-thin` (`@layer utilities`, always emitted). |
 | `@vvedantb/ui/tokens/css/animations.css` | `src/css/animations.css` | `animate-aurora`, `animate-fade-in-up`, `animate-indeterminate` as `@theme` (CSS-first apps). |
 | `@vvedantb/ui/tokens/css/compat-shadcn-rgb.css`, `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | `src/css/compat-shadcn-rgb.css` | Replaces `tokens.css` for apps with shadcn-style `R G B` channel variables. Defines only the UI-only `--color-*` names as `rgb(var(--x) / alpha)` references, `--radius-field`, `--scrollbar`, `--field-radius` and a `glass-panel-strong` fallback. Import it **or** `tokens.css`, never both. |

package/tokens/examples/toaster/Fixture.tsx

@@ -0,0 +1,53 @@
+import { useEffect, useState } from "react";
+import { toast } from "sonner";
+import { Button } from "../../../src/ui/button";
+import { SonnerToaster } from "../../../src/ui/sonner";
+
+function initialDark(): boolean {
+  return new URLSearchParams(window.location.search).get("theme") === "dark";
+}
+
+function fire() {
+  toast.success("Changes saved", {
+    description: "Your settings were updated and will apply to new sessions.",
+    duration: Infinity,
+  });
+}
+
+export function Fixture() {
+  const [dark, setDark] = useState(initialDark);
+
+  // Sonner portals toasts onto `document.body`, so `.dark` must live on `<html>`
+  // (not an inner wrapper) for token / Tailwind dark styles to reach them.
+  useEffect(() => {
+    document.documentElement.classList.toggle("dark", dark);
+    return () => {
+      document.documentElement.classList.remove("dark");
+    };
+  }, [dark]);
+
+  // Fire one sample toast on load so a screenshot captures it.
+  useEffect(() => {
+    const id = window.setTimeout(fire, 150);
+    return () => window.clearTimeout(id);
+  }, []);
+
+  return (
+    <>
+      <main className="min-h-screen bg-background p-8 text-foreground">
+        <div className="flex gap-3">
+          <Button onClick={() => setDark((d) => !d)}>Toggle theme</Button>
+          <Button onClick={fire}>Show toast</Button>
+        </div>
+      </main>
+      <SonnerToaster
+        theme={dark ? "dark" : "light"}
+        toastRadius="surface"
+        toastIcons="filled24"
+        closeButtonStyle="hoverChip"
+        sonnerVars
+        descriptionMuted
+      />
+    </>
+  );
+}

package/tokens/examples/toaster/README.md

@@ -0,0 +1,18 @@
+# toaster fixture
+
+Renders `SonnerToaster` with every opt-in prop on (`toastRadius="surface"`, `toastIcons="filled24"`, `closeButtonStyle="hoverChip"`, `sonnerVars`, `descriptionMuted`). It fires one sample toast with a title and a description on load. The toast stays open. Use "Show toast" to fire another.
+
+| Page | Stylesheet |
+| --- | --- |
+| `/tokens.html` | `tokens.css` plus `utilities.css` (`styles-tokens.css`) |
+| `/compat.html` | `compat-shadcn-rgb.css` plus `utilities.css`, with sample `R G B` variables (`styles-compat.css`) |
+
+Each stylesheet declares `glass-panel-strong` (tokens page only) and `smooth-shadow-ring-md`. The app owns those toast classes. The compat page also defines `--success` and `--warning` and maps them to `--color-success` and `--color-warning`.
+
+Run it from this folder (it is not a workspace member, and React resolves from the parent `packages/ui` install):
+
+```sh
+pnpm install --ignore-workspace && pnpm dev
+```
+
+Open the printed URL plus `/tokens.html` or `/compat.html`. Add `?theme=dark` for dark mode, or use "Toggle theme". Hover the toast to see the close chip. `Fixture.tsx` is not part of the package typecheck.

package/tokens/examples/toaster/compat.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>toaster: compat-shadcn-rgb.css</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main-compat.tsx"></script>
+  </body>
+</html>

package/tokens/examples/toaster/main-compat.tsx

@@ -0,0 +1,5 @@
+import { createRoot } from "react-dom/client";
+import { Fixture } from "./Fixture";
+import "./styles-compat.css";
+
+createRoot(document.getElementById("root")!).render(<Fixture />);

package/tokens/examples/toaster/main-tokens.tsx

@@ -0,0 +1,5 @@
+import { createRoot } from "react-dom/client";
+import { Fixture } from "./Fixture";
+import "./styles-tokens.css";
+
+createRoot(document.getElementById("root")!).render(<Fixture />);

package/tokens/examples/toaster/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "toaster-fixture",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "4.3.3",
+    "tailwindcss": "4.3.3",
+    "vite": "^7.0.0"
+  }
+}

package/tokens/examples/toaster/styles-compat.css

@@ -0,0 +1,82 @@
+@import "tailwindcss";
+@import "../../src/css/compat-shadcn-rgb.css";
+@import "../../src/css/utilities.css";
+@source "../../../src/**/*.{ts,tsx}";
+@source "./*.tsx";
+@custom-variant dark (&:where(.dark, .dark *));
+
+/* Sample shadcn-style RGB channel variables owned by the app. */
+:root {
+  --background: 244 245 246;
+  --foreground: 24 24 27;
+  --card: 255 255 255;
+  --card-foreground: 24 24 27;
+  --popover: 255 255 255;
+  --popover-foreground: 24 24 27;
+  --primary: 37 99 235;
+  --primary-foreground: 255 255 255;
+  --secondary: 235 236 238;
+  --secondary-foreground: 24 24 27;
+  --muted: 235 236 238;
+  --muted-foreground: 100 100 110;
+  --accent: 235 236 238;
+  --accent-foreground: 24 24 27;
+  --destructive: 220 38 38;
+  --destructive-foreground: 255 255 255;
+  --border: 224 225 228;
+  --input: 224 225 228;
+  --ring: 37 99 235;
+  --success: 22 163 74;
+  --warning: 217 119 6;
+  --radius: 0.75rem;
+}
+
+.dark {
+  --background: 15 15 17;
+  --foreground: 244 244 245;
+  --card: 28 28 31;
+  --card-foreground: 244 244 245;
+  --popover: 28 28 31;
+  --popover-foreground: 244 244 245;
+  --primary: 96 165 250;
+  --primary-foreground: 15 15 17;
+  --secondary: 39 39 43;
+  --secondary-foreground: 244 244 245;
+  --muted: 39 39 43;
+  --muted-foreground: 161 161 170;
+  --accent: 39 39 43;
+  --accent-foreground: 244 244 245;
+  --destructive: 248 113 113;
+  --destructive-foreground: 15 15 17;
+  --border: 46 46 51;
+  --input: 46 46 51;
+  --ring: 96 165 250;
+  --success: 74 222 128;
+  --warning: 251 191 36;
+}
+
+@theme inline {
+  --color-background: rgb(var(--background));
+  --color-foreground: rgb(var(--foreground));
+  --color-border: rgb(var(--border));
+  --color-primary: rgb(var(--primary));
+  --color-primary-foreground: rgb(var(--primary-foreground));
+  --color-muted-foreground: rgb(var(--muted-foreground));
+  --color-destructive: rgb(var(--destructive));
+  --color-ring: rgb(var(--ring));
+  --color-success: rgb(var(--success));
+  --color-warning: rgb(var(--warning));
+}
+
+/* Toast class the app owns (not part of the compat file). */
+@utility smooth-shadow-ring-md {
+  box-shadow:
+    0 0 0 1px rgb(var(--border) / 0.6),
+    0 4px 12px rgb(0 0 0 / 0.08);
+}
+
+body {
+  background: rgb(var(--background));
+  color: rgb(var(--foreground));
+  font-family: system-ui, sans-serif;
+}

package/tokens/examples/toaster/styles-tokens.css

@@ -0,0 +1,16 @@
+@import "tailwindcss";
+@import "../../src/tokens.css";
+@import "../../src/css/utilities.css";
+@source "../../../src/**/*.{ts,tsx}";
+@source "./*.tsx";
+
+/* Toast classes the app owns (not part of tokens.css). */
+@utility glass-panel-strong {
+  background-color: color-mix(in oklch, var(--color-card) 95%, transparent);
+  backdrop-filter: blur(12px);
+}
+@utility smooth-shadow-ring-md {
+  box-shadow:
+    0 0 0 1px color-mix(in srgb, var(--color-border) 60%, transparent),
+    0 4px 12px rgb(0 0 0 / 0.08);
+}

package/tokens/examples/toaster/tokens.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>toaster: tokens.css</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main-tokens.tsx"></script>
+  </body>
+</html>

package/tokens/examples/toaster/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true
+  },
+  "include": ["*.ts", "*.tsx"]
+}

package/tokens/examples/toaster/vite.config.ts

@@ -0,0 +1,12 @@
+import tailwindcss from "@tailwindcss/vite";
+import { defineConfig } from "vite";
+
+// React, react-dom and the @vvedantb/ui peers resolve from packages/ui/node_modules
+// (this folder sits inside that package), so the fixture installs only the build tools.
+export default defineConfig({
+  plugins: [tailwindcss()],
+  esbuild: { jsx: "automatic" },
+  resolve: { dedupe: ["react", "react-dom"] },
+  build: { rollupOptions: { input: ["tokens.html", "compat.html"] } },
+  server: { fs: { allow: ["../../.."] } },
+});

package/tokens/src/css/compat-shadcn-rgb.css

@@ -23,11 +23,18 @@
  * --accent, --accent-foreground, --destructive, --destructive-foreground,
  * --border, --input, --ring and --radius (all colours as "R G B").
  *
+ * `--color-card` and `--color-muted` are references to `--card` and `--muted`.
+ * `SonnerToaster sonnerVars` reads them, along with `--color-border` and
+ * `--color-foreground`. An app that already maps those names keeps its own
+ * mapping if it declares them after this import.
+ *
  * Alpha values follow common shadcn-RGB classes (ring/35, ring/50,
  * destructive/20, placeholder /90, scrollbar /35).
  */
 
 @theme inline {
+  --color-card: rgb(var(--card));
+  --color-muted: rgb(var(--muted));
   --color-default: rgb(var(--secondary));
   --color-default-foreground: rgb(var(--secondary-foreground));
   --color-surface: rgb(var(--card));

package/tokens/src/css/utilities.css

@@ -32,3 +32,8 @@
     }
   }
 }
+
+/* Surface radius: follows the theme `--radius`, kept between 0.75rem and 1rem. */
+@utility rounded-surface {
+  border-radius: clamp(0.75rem, var(--radius), 1rem);
+}