@vvedantb/ui 0.2.2 → 0.2.3

package/README.md

@@ -5,6 +5,8 @@ Shared React 19 web UI. Source-exported: no build step.
 | Import | What it is |
 | --- | --- |
 | `@vvedantb/ui` | Primitives (Radix-based), AI elements, `playChime` and `useReplyChime`. |
+| `@vvedantb/ui/sonner` | `SonnerToaster`, its helpers and `toast`. |
+| `@vvedantb/ui/audio` | `playChime`, `useReplyChime`, `playTone` and the shared audio floor. |
 | `@vvedantb/ui/cn` | `cn` class helper (clsx + tailwind-merge). |
 | `@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. |
@@ -29,6 +31,9 @@ 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.
+- `playTone(tone | tones)`: plays `{ frequency, startOffsetS?, durationS?, peakGain?, type? }` through the same floor.
+- Audio floor: every package sound shares one 1 second minimum gap. Route your own sounds through it with `withAudioFloor(() => play())` or `if (tryAcquireAudioFloor()) play()`.
+- These are also available from `@vvedantb/ui/audio`, which does not load the rest of the root barrel.
 - `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
@@ -45,13 +50,13 @@ import { SessionsHoverCard } from "@vvedantb/ui/shell";
 </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/`.
+`children` is the trigger. It is rendered with `asChild` by default, so it keeps its own handlers (such as a context menu). Extra props and the ref go to it. Use `asChild={false}` for a default trigger element. The content portals to `document.body` by default, so `overflow:hidden` ancestors do not clip it. Pass `portal={false}` to opt out. `surface` is `"overlay"` (default), `"surface"` (`rounded-surface`) or `"glass"` (`glass-panel-strong`, `rounded-surface`). `className` merges over the surface without `!`. 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";
+import { SonnerToaster } from "@vvedantb/ui"; // or "@vvedantb/ui/sonner"
 
 <SonnerToaster
   theme={theme}
@@ -73,7 +78,8 @@ 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`). |
+| `toastRadius` | `"lg"` (default), `"surface"`, `"control"` | `rounded-lg`, `rounded-surface` (from `tokens/css/utilities.css`) or `rounded-field` (the input radius). |
+| `density` | `"default"`, `"compact"` | Current padding and text, or `gap-2 px-3 py-2 text-xs` with `text-xs` descriptions. |
 | `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`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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",
@@ -21,6 +21,14 @@
       "types": "./src/utils/cn.ts",
       "default": "./src/utils/cn.ts"
     },
+    "./sonner": {
+      "types": "./src/sonner.ts",
+      "default": "./src/sonner.ts"
+    },
+    "./audio": {
+      "types": "./src/audio/index.ts",
+      "default": "./src/audio/index.ts"
+    },
     "./shell": {
       "types": "./shell/src/index.ts",
       "default": "./shell/src/index.ts"

package/shell/src/SessionsHoverCard.tsx

@@ -1,17 +1,49 @@
-import { useEffect, useState } from "react";
-import type { ReactNode } from "react";
-import {
-  HoverCard,
-  HoverCardContent,
-  HoverCardTrigger,
-} from "../../src/ui/hover-card";
+import { forwardRef, useEffect, useState } from "react";
+import type { ComponentPropsWithoutRef, ComponentRef, ReactNode } from "react";
+import * as HoverCardPrimitive from "@radix-ui/react-hover-card";
+import { HoverCard, HoverCardTrigger } from "../../src/ui/hover-card";
+import { floatingSurfaceAnimateClass, floatingSurfaceClass } from "../../src/ui/_menu-classes";
 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`. */
+export type SessionsHoverCardSurface = "overlay" | "surface" | "glass";
+
+/**
+ * Surface classes. Only `overlay` carries the shared floating surface, so the
+ * others need no `!` overrides, and `className` merges over all of them.
+ */
+const surfaceClasses: Record<SessionsHoverCardSurface, string> = {
+  overlay: floatingSurfaceClass,
+  surface: "rounded-surface bg-overlay text-overlay-foreground smooth-shadow-ring-lg",
+  glass: "rounded-surface glass-panel-strong text-foreground smooth-shadow-ring-lg",
+};
+
+export type SessionsHoverCardProps = Omit<
+  ComponentPropsWithoutRef<typeof HoverCardTrigger>,
+  "className" | "children"
+> & {
+  /**
+   * The trigger. With `asChild` (default) it is the element that triggers the
+   * card, such as a list row. Trigger props and the ref go to that element,
+   * which keeps its own handlers. With `asChild={false}` the children render
+   * inside a default trigger element.
+   */
   children: ReactNode;
+  /** Default `true`. */
+  asChild?: boolean;
+  /**
+   * Render the content in a portal on `document.body`, so `overflow:hidden`
+   * ancestors do not clip it. Default `true`. Use `false` to keep the content
+   * in place in the DOM.
+   */
+  portal?: boolean;
+  /**
+   * `"overlay"` (default): floating overlay, `rounded-lg`. `"surface"`: same
+   * fill with `rounded-surface`. `"glass"`: `glass-panel-strong` with
+   * `rounded-surface`.
+   */
+  surface?: SessionsHoverCardSurface;
   header?: ReactNode;
   /**
    * Body slot. A function runs only while the card is open, so it can start
@@ -34,7 +66,7 @@ export type SessionsHoverCardProps = {
   side?: "top" | "right" | "bottom" | "left";
   align?: "start" | "center" | "end";
   sideOffset?: number;
-  /** Merged over the default `w-64 p-3`. */
+  /** Merged over the default `w-64 p-3` and the surface classes. */
   className?: string;
 };
 
@@ -86,8 +118,14 @@ function RenderBody({
  * position, width and padding, and gives header, body and footer slots. The
  * app supplies the content.
  */
-export function SessionsHoverCard({
+export const SessionsHoverCard = forwardRef<
+  ComponentRef<typeof HoverCardTrigger>,
+  SessionsHoverCardProps
+>(function SessionsHoverCard({
   children,
+  asChild = true,
+  portal = true,
+  surface = "overlay",
   header,
   body,
   loadContent,
@@ -102,7 +140,8 @@ export function SessionsHoverCard({
   align = "start",
   sideOffset = 8,
   className,
-}: SessionsHoverCardProps) {
+  ...triggerProps
+}, ref) {
   const [openState, setOpenState] = useState(defaultOpen);
   const open = openProp ?? openState;
 
@@ -119,6 +158,31 @@ export function SessionsHoverCard({
     body
   );
 
+  const content = (
+    <HoverCardPrimitive.Content
+      side={side}
+      align={align}
+      sideOffset={sideOffset}
+      className={cn(
+        "z-50 outline-none max-sm:max-h-[85dvh] max-sm:max-w-[calc(100vw-2rem)] max-sm:overflow-y-auto",
+        surfaceClasses[surface],
+        floatingSurfaceAnimateClass,
+        "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}
+    </HoverCardPrimitive.Content>
+  );
+
   return (
     <HoverCard
       open={open}
@@ -126,23 +190,10 @@ export function SessionsHoverCard({
       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>
+      <HoverCardTrigger ref={ref} asChild={asChild} {...triggerProps}>
+        {children}
+      </HoverCardTrigger>
+      {portal ? <HoverCardPrimitive.Portal>{content}</HoverCardPrimitive.Portal> : content}
     </HoverCard>
   );
-}
+});

package/shell/src/index.ts

@@ -8,4 +8,5 @@ export { SessionsHoverCard } from "./SessionsHoverCard.js";
 export type {
   SessionsHoverCardContext,
   SessionsHoverCardProps,
+  SessionsHoverCardSurface,
 } from "./SessionsHoverCard.js";

package/src/audio/audioFloor.ts

@@ -0,0 +1,37 @@
+/** Calls closer together than this are dropped, so overlapping events sound once. */
+export const AUDIO_FLOOR_MIN_GAP_S = 1;
+
+let lastAcquiredAtS: number | null = null;
+
+function nowS(): number {
+  return performance.now() / 1000;
+}
+
+/**
+ * Takes the shared audio floor. Returns `true` when at least 1 second has
+ * passed since the last sound that took it, and starts a new gap. Returns
+ * `false` otherwise, and the caller should stay silent.
+ *
+ * Every package sound (`playChime`, `playTone`) goes through this one floor.
+ * Apps can route their own sounds through it too.
+ */
+export function tryAcquireAudioFloor(): boolean {
+  const now = nowS();
+  if (lastAcquiredAtS !== null && now - lastAcquiredAtS < AUDIO_FLOOR_MIN_GAP_S) {
+    return false;
+  }
+  lastAcquiredAtS = now;
+  return true;
+}
+
+/** Runs `play` only if the shared floor is free. Returns whether it ran. */
+export function withAudioFloor(play: () => void): boolean {
+  if (!tryAcquireAudioFloor()) return false;
+  play();
+  return true;
+}
+
+/** Clears the floor. For tests. */
+export function resetAudioFloor(): void {
+  lastAcquiredAtS = null;
+}

package/src/audio/index.ts

@@ -1,3 +1,10 @@
 export { playChime } from "./playChime";
+export { playTone } from "./playTone";
+export type { Tone } from "./playTone";
+export {
+  AUDIO_FLOOR_MIN_GAP_S,
+  tryAcquireAudioFloor,
+  withAudioFloor,
+} from "./audioFloor";
 export { useReplyChime, nextReplyChimeState } from "./useReplyChime";
 export type { ReplyChimeInput, ReplyChimeWatch } from "./useReplyChime";

package/src/audio/playChime.ts

@@ -1,9 +1,4 @@
-type Tone = {
-  frequency: number;
-  startOffsetS: number;
-  durationS: number;
-  peakGain: number;
-};
+import { playTone, type Tone } from "./playTone";
 
 /** A soft rising interval (A5 then D6). The second note overlaps the first. */
 const REPLY_CHIME: readonly Tone[] = [
@@ -11,66 +6,13 @@ const REPLY_CHIME: readonly Tone[] = [
   { 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.
+ * server, without WebAudio, or while autoplay policy blocks audio. It shares
+ * the 1 second floor with every other package sound.
  */
 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.
-  }
+  playTone(REPLY_CHIME);
 }

package/src/audio/playTone.ts

@@ -0,0 +1,73 @@
+import { tryAcquireAudioFloor } from "./audioFloor";
+
+export type Tone = {
+  /** Pitch in Hz. */
+  frequency: number;
+  /** Delay from the start of the call, in seconds. Default 0. */
+  startOffsetS?: number;
+  /** Length in seconds. Default 0.28. */
+  durationS?: number;
+  /** Peak gain from 0 to 1. Default 0.14. */
+  peakGain?: number;
+  /** Default "sine". */
+  type?: OscillatorType;
+};
+
+/** Long enough to avoid a click on attack. */
+const ATTACK_S = 0.012;
+
+let sharedContext: AudioContext | 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 one tone or a sequence of overlapping tones with WebAudio, through the
+ * shared 1 second floor (see `tryAcquireAudioFloor`). 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 playTone(tones: Tone | readonly Tone[]): void {
+  const context = getAudioContext();
+  if (!context) return;
+
+  if (context.state === "suspended") {
+    try {
+      context.resume().catch(() => undefined);
+    } catch {
+      return;
+    }
+  }
+
+  if (!tryAcquireAudioFloor()) return;
+
+  try {
+    const start = context.currentTime;
+    for (const tone of Array.isArray(tones) ? tones : [tones as Tone]) {
+      const oscillator = context.createOscillator();
+      const envelope = context.createGain();
+      oscillator.type = tone.type ?? "sine";
+      oscillator.frequency.value = tone.frequency;
+
+      const toneStart = start + (tone.startOffsetS ?? 0);
+      const toneEnd = toneStart + (tone.durationS ?? 0.28);
+      envelope.gain.setValueAtTime(0, toneStart);
+      envelope.gain.linearRampToValueAtTime(tone.peakGain ?? 0.14, 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/sonner.ts

@@ -0,0 +1,2 @@
+export * from "./ui/sonner";
+export { toast } from "sonner";

package/src/ui/sonner.tsx

@@ -26,8 +26,13 @@ type ToastClassNames = NonNullable<
 type ToasterStyle = CSSProperties & Record<`--${string}`, string>;
 
 type SonnerToasterOptions = {
-  /** `"lg"` (default) uses `rounded-lg`. `"surface"` uses `rounded-surface`. */
-  toastRadius?: "lg" | "surface";
+  /**
+   * `"lg"` (default) uses `rounded-lg`. `"surface"` uses `rounded-surface`.
+   * `"control"` uses `rounded-field`, the radius of inputs and selects.
+   */
+  toastRadius?: "lg" | "surface" | "control";
+  /** `"default"` keeps the current padding and text size. `"compact"` tightens padding, gap and text. */
+  density?: "default" | "compact";
   /** `"default"` keeps sonner's icons. `"filled24"` uses 24px filled icons. */
   toastIcons?: "default" | "filled24";
   /**
@@ -48,22 +53,31 @@ const hoverChipCloseButtonClassName =
 const defaultCloseButtonClassName =
   "rounded-lg bg-default px-2.5 py-1 text-xs font-medium text-foreground transition-colors hover:bg-default/78";
 
+const toastRadiusClasses = {
+  lg: "rounded-lg",
+  surface: "rounded-surface",
+  control: "rounded-field",
+} as const;
+
 /** Default `classNames`, with the opt-in variants applied. No options gives the 0.2.1 defaults. */
 function createToasterClassNames({
   toastRadius = "lg",
+  density = "default",
   closeButtonStyle = "default",
   descriptionMuted = false,
 }: Pick<
   SonnerToasterOptions,
-  "toastRadius" | "closeButtonStyle" | "descriptionMuted"
+  "toastRadius" | "density" | "closeButtonStyle" | "descriptionMuted"
 > = {}): ToastClassNames {
-  const radius = toastRadius === "surface" ? "rounded-surface" : "rounded-lg";
+  const radius = toastRadiusClasses[toastRadius];
+  const compact = density === "compact";
+  const descriptionSize = compact ? "text-xs" : "text-[13px]";
   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`,
+    toast: `group toast glass-panel-strong flex w-full items-center ${compact ? "gap-2" : "gap-3"} ${radius} ${compact ? "px-3 py-2 text-xs" : "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",
+      ? `${descriptionSize} leading-snug text-muted-foreground!`
+      : `${descriptionSize} 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:
@@ -129,6 +143,7 @@ function mergeToastOptions(
 
 function SonnerToaster({
   toastRadius,
+  density,
   toastIcons = "default",
   closeButtonStyle = "default",
   sonnerVars = false,
@@ -157,6 +172,7 @@ function SonnerToaster({
           unstyled: true,
           classNames: createToasterClassNames({
             toastRadius,
+            density,
             closeButtonStyle,
             descriptionMuted,
           }),

package/tokens/examples/toaster/Fixture.tsx

@@ -7,6 +7,10 @@ function initialDark(): boolean {
   return new URLSearchParams(window.location.search).get("theme") === "dark";
 }
 
+const compact =
+  typeof window !== "undefined" &&
+  new URLSearchParams(window.location.search).get("variant") === "compact";
+
 function fire() {
   toast.success("Changes saved", {
     description: "Your settings were updated and will apply to new sessions.",
@@ -42,7 +46,8 @@ export function Fixture() {
       </main>
       <SonnerToaster
         theme={dark ? "dark" : "light"}
-        toastRadius="surface"
+        toastRadius={compact ? "control" : "surface"}
+        density={compact ? "compact" : "default"}
         toastIcons="filled24"
         closeButtonStyle="hoverChip"
         sonnerVars

package/tokens/examples/toaster/README.md

@@ -15,4 +15,4 @@ Run it from this folder (it is not a workspace member, and React resolves from t
 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.
+Open the printed URL plus `/tokens.html` or `/compat.html`. Add `?variant=compact` for the compact density with `toastRadius="control"`. Add `?theme=dark` for dark mode (combine with `&`), or use "Toggle theme". Hover the toast to see the close chip. `Fixture.tsx` is not part of the package typecheck.