@elabs-ai/components-ui 4.0.0

package/src/components/slider-number/slider-number.test.tsx

@@ -0,0 +1,165 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { SliderNumber } from "./slider-number";
+
+describe("SliderNumber", () => {
+  it("renders a slider and a synced number input", () => {
+    render(<SliderNumber aria-label="Temperature" min={0} max={1} step={0.1} defaultValue={0.5} />);
+    expect(screen.getByRole("slider", { name: "Temperature" })).toHaveAttribute(
+      "aria-valuenow",
+      "0.5",
+    );
+    expect(screen.getByRole("spinbutton", { name: "Temperature" })).toHaveValue(0.5);
+  });
+
+  it("rounds slider-driven and typed values identically (lockstep)", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <SliderNumber
+        aria-label="Temperature"
+        min={0}
+        max={1}
+        step={0.1}
+        defaultValue={0}
+        onValueChange={onValueChange}
+      />,
+    );
+    const thumb = screen.getByRole("slider", { name: "Temperature" });
+    thumb.focus();
+    await userEvent.keyboard("{ArrowRight}{ArrowRight}{ArrowRight}");
+    expect(onValueChange).toHaveBeenLastCalledWith(0.3);
+
+    const numberInput = screen.getByRole("spinbutton", { name: "Temperature" });
+    await userEvent.clear(numberInput);
+    await userEvent.type(numberInput, "0.3");
+    await userEvent.tab();
+    expect(onValueChange).toHaveBeenLastCalledWith(0.3);
+  });
+
+  it("null is a real state distinct from 0, reachable via reset", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <SliderNumber
+        aria-label="Temperature"
+        min={0}
+        max={1}
+        step={0.1}
+        defaultValue={0.6}
+        onValueChange={onValueChange}
+      />,
+    );
+    await userEvent.click(screen.getByRole("button", { name: "Reset" }));
+    expect(onValueChange).toHaveBeenCalledWith(null);
+  });
+
+  it("disables the reset control once the value is already null", () => {
+    render(<SliderNumber aria-label="Temperature" defaultValue={null} />);
+    expect(screen.getByRole("button", { name: "Reset" })).toBeDisabled();
+  });
+
+  it("shows the slider thumb as dimmed/inactive while value is the provider default (null)", () => {
+    render(
+      <SliderNumber aria-label="Temperature" min={0} max={1} step={0.1} defaultValue={null} />,
+    );
+    const classes = screen.getByRole("slider", { name: "Temperature" }).className.split(/\s+/);
+    // Exact token match — `disabled:opacity-50` is always present as a base
+    // (disabled-state) utility, so a substring match would false-positive.
+    expect(classes).toContain("opacity-50");
+    expect(classes).toContain("border-dashed");
+  });
+
+  it("shows the slider thumb as active (not dimmed) once a real value is set", () => {
+    render(<SliderNumber aria-label="Temperature" min={0} max={1} step={0.1} defaultValue={0.4} />);
+    const classes = screen.getByRole("slider", { name: "Temperature" }).className.split(/\s+/);
+    expect(classes).not.toContain("opacity-50");
+    expect(classes).not.toContain("border-dashed");
+  });
+
+  it("round-trips null -> non-null -> reset -> null", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <SliderNumber
+        aria-label="Temperature"
+        min={0}
+        max={1}
+        step={0.1}
+        defaultValue={null}
+        onValueChange={onValueChange}
+      />,
+    );
+    const thumb = screen.getByRole("slider", { name: "Temperature" });
+    thumb.focus();
+    await userEvent.keyboard("{ArrowRight}");
+    expect(onValueChange).toHaveBeenLastCalledWith(0.1);
+
+    const resetBtn = screen.getByRole("button", { name: "Reset" });
+    await userEvent.click(resetBtn);
+    expect(onValueChange).toHaveBeenLastCalledWith(null);
+    expect(resetBtn).toBeDisabled();
+  });
+
+  it("supports the controlled mode via value/onValueChange", async () => {
+    const onValueChange = vi.fn();
+    render(
+      <SliderNumber
+        aria-label="Temperature"
+        min={0}
+        max={1}
+        step={0.1}
+        value={0.2}
+        onValueChange={onValueChange}
+      />,
+    );
+    const numberInput = screen.getByRole("spinbutton", { name: "Temperature" });
+    await userEvent.clear(numberInput);
+    await userEvent.type(numberInput, "0.9");
+    await userEvent.tab();
+    expect(onValueChange).toHaveBeenLastCalledWith(0.9);
+  });
+
+  it.each([
+    ["rounds to the value already held", "0.44", "0.4"],
+    ["rounds to a different value", "0.66", "0.7"],
+    ["is clamped to max", "9", "1"],
+  ])(
+    "input display never disagrees with the slider when a typed value %s",
+    async (_case, typed, expected) => {
+      render(<SliderNumber aria-label="T" min={0} max={1} step={0.1} defaultValue={0.4} />);
+      await userEvent.clear(screen.getByRole("spinbutton", { name: "T" }));
+      await userEvent.type(screen.getByRole("spinbutton", { name: "T" }), typed);
+      await userEvent.tab();
+      // Re-query: correcting the display can remount the input, so a node
+      // captured before the blur would be a detached copy.
+      const shown = (screen.getByRole("spinbutton", { name: "T" }) as HTMLInputElement).value;
+      const announced = screen.getByRole("slider", { name: "T" }).getAttribute("aria-valuenow");
+      expect(announced).toBe(expected);
+      // The "rounds to the value already held" row is the one that regressed:
+      // `NumberInput` only re-derives its text when the controlled value
+      // CHANGES, so it kept showing "0.44" beside a slider reading 0.4.
+      expect(shown).toBe(expected);
+    },
+  );
+
+  it("keeps its default width shrinkable and caller-overridable", () => {
+    const { container, rerender } = render(<SliderNumber aria-label="Temperature" />);
+    const root = () => container.querySelector('[data-slot="slider-number"]')!;
+    // `w-80` is a PREFERRED width — `max-w-full` stops it overflowing a
+    // narrower container instead of forcing a horizontal scrollbar.
+    expect(root()).toHaveClass("w-80", "max-w-full");
+
+    rerender(<SliderNumber aria-label="Temperature" className="w-full" />);
+    expect(root()).toHaveClass("w-full");
+    expect(root()).not.toHaveClass("w-80");
+  });
+
+  it("is disabled when disabled prop is set", () => {
+    render(<SliderNumber aria-label="Temperature" defaultValue={0.5} disabled />);
+    expect(screen.getByRole("slider", { name: "Temperature" })).toHaveAttribute(
+      "data-disabled",
+      "",
+    );
+    expect(screen.getByRole("spinbutton", { name: "Temperature" })).toBeDisabled();
+    expect(screen.getByRole("button", { name: "Reset" })).toBeDisabled();
+  });
+});

package/src/components/slider-number/slider-number.tsx

@@ -0,0 +1,191 @@
+"use client";
+
+import { forwardRef, useCallback, useState, type HTMLAttributes, type ReactNode } from "react";
+import { cn } from "../../lib/cn";
+import { Button } from "../button";
+import { NumberInput } from "../number-input";
+import { Slider } from "../slider";
+import { useLocale } from "../locale-provider";
+
+export interface SliderNumberProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "onChange" | "defaultValue"
+> {
+  /** Controlled value. Pass `null` for "use the provider default". */
+  value?: number | null;
+  /** Uncontrolled initial value. */
+  defaultValue?: number | null;
+  /** Called when the value changes — always rounded identically on the drag and type paths. */
+  onValueChange?: (value: number | null) => void;
+  /** Minimum allowed value. Defaults to 0. */
+  min?: number;
+  /** Maximum allowed value. Defaults to 100. */
+  max?: number;
+  /** Step increment for both the slider and the number input's arrow keys. Defaults to 1. */
+  step?: number;
+  /**
+   * Number of decimal places to round to. Defaults to the decimal places in
+   * `step` (e.g. `step={0.1}` rounds to 1 decimal). Applied identically on
+   * BOTH the slider path and the number-input path so drag-then-type never
+   * disagrees.
+   */
+  precision?: number;
+  /** Label for the reset-to-provider-default control. Defaults to "Reset". */
+  resetLabel?: ReactNode;
+  /** Disables the whole control. */
+  disabled?: boolean;
+  id?: string;
+  name?: string;
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+}
+
+function getStepDecimals(step: number): number {
+  const str = step.toString();
+  const dot = str.indexOf(".");
+  return dot === -1 ? 0 : str.length - dot - 1;
+}
+
+function clampValue(value: number, min?: number, max?: number): number {
+  let result = value;
+  if (min !== undefined) result = Math.max(min, result);
+  if (max !== undefined) result = Math.min(max, result);
+  return result;
+}
+
+/** Rounds to a fixed decimal precision — the ONE function both paths call. */
+function roundValue(value: number, step: number, precision?: number): number {
+  const decimals = precision ?? getStepDecimals(step);
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+
+/**
+ * SliderNumber — a `Slider` and a `NumberInput` bound to one value, clamped
+ * and rounded in lockstep so they can never disagree, plus an explicit
+ * `null` state meaning "use the provider default" with a reset control.
+ *
+ * The subtle part (#372): both the slider's `onValueChange` and the number
+ * input's `onValueChange` are routed through the SAME `commit` function,
+ * which rounds to a fixed decimal precision before storing — so dragging to
+ * a value and then typing the same value never produces two representations
+ * of the same intent (e.g. floating-point drift like `0.30000000000000004`).
+ */
+export const SliderNumber = forwardRef<HTMLDivElement, SliderNumberProps>(function SliderNumber(
+  {
+    value: valueProp,
+    defaultValue,
+    onValueChange,
+    min = 0,
+    max = 100,
+    step = 1,
+    precision,
+    resetLabel,
+    disabled,
+    id,
+    name,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledby,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const { t } = useLocale();
+  const isControlled = valueProp !== undefined;
+  const [internalValue, setInternalValue] = useState<number | null>(
+    defaultValue !== undefined ? defaultValue : null,
+  );
+  const currentValue = isControlled ? valueProp : internalValue;
+
+  // Bumped whenever this component normalises a typed value back to the value
+  // it ALREADY holds. `NumberInput` only re-derives its display text when the
+  // controlled `value` prop CHANGES, so in that one case it would keep showing
+  // the raw keystrokes ("0.44") while the slider and the committed value read
+  // the rounded one (0.4) — the exact "slider and input disagree" failure this
+  // component exists to prevent. Remounting it re-derives the text from the
+  // value that was actually accepted. It only ever fires on blur, when the
+  // input is no longer focused, so the remount is invisible.
+  const [inputEpoch, setInputEpoch] = useState(0);
+
+  const commit = useCallback(
+    (next: number | null) => {
+      const rounded = next == null ? null : roundValue(clampValue(next, min, max), step, precision);
+      if (next != null && rounded !== next && rounded === currentValue) {
+        setInputEpoch((n) => n + 1);
+      }
+      if (!isControlled) setInternalValue(rounded);
+      onValueChange?.(rounded);
+    },
+    [isControlled, onValueChange, min, max, step, precision, currentValue],
+  );
+
+  const isDefault = currentValue == null;
+  const sliderValue = currentValue ?? min;
+
+  return (
+    <div
+      ref={ref}
+      data-slot="slider-number"
+      // A default FIXED width (matching Slider's own convention — it has no
+      // intrinsic width either, and its stories always pass one via
+      // className) so the Slider's `flex-1` has real space to grow into.
+      // `w-full`/percentage widths are unresolvable inside an ancestor with
+      // no definite width (e.g. Storybook's default "centered" layout, or a
+      // bare inline/flex context), which collapses `flex-1` to near-zero.
+      // Callers in a definite-width layout can still override via `className`
+      // (e.g. `className="w-full"` inside a form field's own fixed-width row).
+      // `max-w-full` keeps the fixed width from OVERFLOWING a container
+      // narrower than 20rem (a settings drawer, a 320px mobile column) — it is
+      // a preferred width, not a floor.
+      className={cn("flex w-80 max-w-full items-center gap-3", className)}
+      {...props}
+    >
+      <Slider
+        data-slot="slider-number-slider"
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledby}
+        min={min}
+        max={max}
+        step={step}
+        disabled={disabled}
+        value={[sliderValue]}
+        onValueChange={(values) => commit(values[0] ?? null)}
+        thumbProps={{
+          // Visually distinct "provider default" thumb — dimmed + dashed,
+          // never confusable with a real value (including 0).
+          className: cn(isDefault && "opacity-50 border-dashed"),
+        }}
+        className="flex-1"
+      />
+      <NumberInput
+        key={inputEpoch}
+        data-slot="slider-number-input"
+        id={id}
+        name={name}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledby}
+        min={min}
+        max={max}
+        step={step}
+        disabled={disabled}
+        value={currentValue}
+        onValueChange={commit}
+        // NumberInput's own default is w-36 (144px); shrinking it below
+        // ~w-32 leaves too little room for the digits once its own
+        // decrease/increase buttons are subtracted, clipping the text.
+        className="w-32 shrink-0"
+      />
+      <Button
+        type="button"
+        variant="ghost"
+        size="sm"
+        data-slot="slider-number-reset"
+        disabled={disabled || isDefault}
+        onClick={() => commit(null)}
+      >
+        {resetLabel ?? t("ui.sliderNumber.reset")}
+      </Button>
+    </div>
+  );
+});

package/src/components/sonner/index.ts

@@ -0,0 +1 @@
+export { Toaster, toast, type ToasterProps } from "./sonner";

package/src/components/sonner/sonner.stories.tsx

@@ -0,0 +1,124 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor, within } from "storybook/test";
+import { Button } from "../button";
+import { Toaster, toast } from "./sonner";
+const meta = {
+  title: "Feedback/Toast",
+  component: Toaster,
+  tags: ["autodocs"],
+  argTypes: {
+    position: {
+      description: "Where the toast stack appears on screen.",
+      control: { type: "select" },
+      options: [
+        "top-left",
+        "top-center",
+        "top-right",
+        "bottom-left",
+        "bottom-center",
+        "bottom-right",
+      ],
+      table: { category: "Layout" },
+    },
+    expand: {
+      description: "Expand all toasts in the stack by default.",
+      control: "boolean",
+      table: { category: "Behaviour" },
+    },
+    richColors: {
+      description: "Use rich semantic colours for success/error/warning toasts.",
+      control: "boolean",
+      table: { category: "Appearance" },
+    },
+    closeButton: {
+      description: "Show an explicit close button on each toast.",
+      control: "boolean",
+      table: { category: "Behaviour" },
+    },
+    duration: {
+      description: "Auto-dismiss duration in milliseconds. Default 4000.",
+      control: "number",
+      table: { category: "Behaviour" },
+    },
+    visibleToasts: {
+      description: "Maximum number of toasts visible at one time.",
+      control: "number",
+      table: { category: "Behaviour" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the Toaster root.",
+      control: "text",
+      table: { category: "Styling" },
+    },
+    toastOptions: {
+      description: "Default options applied to every toast (classNames, style, etc.).",
+      control: false,
+      table: { category: "Behaviour" },
+    },
+  },
+} satisfies Meta<typeof Toaster>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <div>
+      <Button onClick={() => toast("Deployment started", { description: "billing@v1.4.2" })}>
+        Show toast
+      </Button>
+      <Toaster duration={4000} />
+    </div>
+  ),
+  // Clicks the trigger button, then confirms the toast message appears in the
+  // document body (Sonner renders outside the story canvas in a portal).
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    await userEvent.click(canvas.getByRole("button", { name: /show toast/i }));
+    const body = within(canvasElement.ownerDocument.body);
+    const toastEl = await body.findByText("Deployment started");
+    await waitFor(() => expect(toastEl).toBeVisible());
+  },
+};
+
+export const CustomizedWithClassName: Story = {
+  render: () => (
+    <div>
+      <Button
+        onClick={() => toast("Hello", { description: "Custom className is merged with defaults" })}
+      >
+        Show toast
+      </Button>
+      <Toaster className="custom-wrapper-class" duration={4000} />
+    </div>
+  ),
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    await userEvent.click(canvas.getByRole("button", { name: /show toast/i }));
+    const body = within(canvasElement.ownerDocument.body);
+    const toastEl = await body.findByText("Hello");
+    await waitFor(() => expect(toastEl).toBeVisible());
+  },
+};
+
+export const CustomizedWithToastOptions: Story = {
+  render: () => (
+    <div>
+      <Button
+        onClick={() => toast("Success!", { description: "Custom toast styles via toastOptions" })}
+      >
+        Show toast
+      </Button>
+      <Toaster
+        toastOptions={{
+          classNames: {
+            toast: "group-[.toaster]:bg-primary group-[.toaster]:text-primary-foreground",
+          },
+        }}
+        duration={4000}
+      />
+    </div>
+  ),
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    await userEvent.click(canvas.getByRole("button", { name: /show toast/i }));
+    const body = within(canvasElement.ownerDocument.body);
+    const toastEl = await body.findByText("Success!");
+    await waitFor(() => expect(toastEl).toBeVisible());
+  },
+};

package/src/components/sonner/sonner.test.tsx

@@ -0,0 +1,76 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { render, waitFor } from "@testing-library/react";
+import { Toaster, toast } from "./sonner";
+
+// jsdom does not provide ResizeObserver, which sonner uses internally to
+// measure each toast's height.
+beforeAll(() => {
+  if (typeof window !== "undefined" && !("ResizeObserver" in window)) {
+    // @ts-expect-error jsdom stub
+    window.ResizeObserver = class ResizeObserver {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    };
+  }
+});
+
+describe("Toaster", () => {
+  it('merges a consumer\'s className with the default "toaster group" wrapper classes (#389)', async () => {
+    render(<Toaster className="my-custom-class" />);
+    toast("Hello world");
+
+    // Wait for the wrapper (ol element) to appear
+    const wrapper = await waitFor(() => {
+      const el = document.querySelector("[data-sonner-toaster]");
+      expect(el).not.toBeNull();
+      return el as HTMLElement;
+    });
+
+    // The wrapper must contain BOTH the default classes AND the consumer's class
+    expect(wrapper).toHaveClass("toaster");
+    expect(wrapper).toHaveClass("group");
+    expect(wrapper).toHaveClass("my-custom-class");
+  });
+
+  it("merges a consumer's toastOptions.classNames into the defaults instead of replacing them (#362)", async () => {
+    render(<Toaster toastOptions={{ classNames: { toast: "extra-class" } }} />);
+    toast("Deployment started", {
+      description: "billing@v1.4.2",
+      action: { label: "Undo", onClick: () => {} },
+      cancel: { label: "Dismiss", onClick: () => {} },
+    });
+
+    const toastEl = await waitFor(() => {
+      const el = document.querySelector("[data-sonner-toast]");
+      expect(el).not.toBeNull();
+      return el as HTMLElement;
+    });
+
+    // The consumer's override is present...
+    expect(toastEl.className).toContain("extra-class");
+    // ...EXTENDING the default `toast` classes, not replacing them.
+    expect(toastEl.className).toContain("group-[.toaster]:bg-card");
+
+    // Sibling classNames the consumer did NOT touch still carry their
+    // library-default token-backed classes — proving the merge is deep
+    // (per-key), not just that `toast` itself survived.
+    expect(document.querySelector("[data-description]")).toHaveClass(
+      "group-[.toast]:text-muted-foreground",
+    );
+    expect(document.querySelector("[data-action]")).toHaveClass("group-[.toast]:bg-primary");
+    expect(document.querySelector("[data-cancel]")).toHaveClass("group-[.toast]:bg-muted");
+  });
+
+  it("<Toaster /> with no toastOptions renders the default classes unchanged (regression guard)", async () => {
+    render(<Toaster />);
+    toast("Plain toast");
+
+    const toastEl = await waitFor(() => {
+      const el = document.querySelector("[data-sonner-toast]");
+      expect(el).not.toBeNull();
+      return el as HTMLElement;
+    });
+    expect(toastEl).toHaveClass("group-[.toaster]:bg-card");
+  });
+});

package/src/components/sonner/sonner.tsx

@@ -0,0 +1,101 @@
+import { useEffect, useState } from "react";
+import { Toaster as SonnerToaster, toast } from "sonner";
+import { resolveThemeIsDark } from "@elabs-ai/components-tokens";
+import { cn } from "../../lib/cn";
+
+/**
+ * The library's default token-backed toast class names. Kept as a standalone
+ * constant (rather than inline in the JSX) so `Toaster` can merge a
+ * consumer's `toastOptions.classNames` INTO these defaults instead of
+ * shallow-replacing them (#362) — each key is combined via `cn()` so a
+ * consumer's override extends the default class string rather than
+ * discarding it.
+ */
+const DEFAULT_TOAST_CLASS_NAMES = {
+  toast:
+    "group toast group-[.toaster]:bg-card group-[.toaster]:text-card-foreground group-[.toaster]:shadow-ring-lg",
+  description: "group-[.toast]:text-muted-foreground",
+  actionButton: "group-[.toast]:bg-primary group-[.toast]:text-primary-foreground",
+  cancelButton: "group-[.toast]:bg-muted group-[.toast]:text-muted-foreground",
+} as const;
+
+/**
+ * Reads the active theme's light/dark-ness off the document. Uses
+ * `resolveThemeIsDark` — the theme's own `color-scheme` — rather than a registry
+ * lookup, so a consumer-authored dark theme gets dark toasts with no
+ * registration (ADR 0029).
+ */
+function useDocumentThemeMode(): "light" | "dark" {
+  const [mode, setMode] = useState<"light" | "dark">("light");
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const el = document.documentElement;
+    const read = () => setMode(resolveThemeIsDark(el) ? "dark" : "light");
+    read();
+    const obs = new MutationObserver(read);
+    obs.observe(el, { attributes: true, attributeFilter: ["data-theme"] });
+    return () => obs.disconnect();
+  }, []);
+  return mode;
+}
+
+export type ToasterProps = React.ComponentProps<typeof SonnerToaster>;
+
+/**
+ * Toast host. Mount once near the app root. Trigger toasts with the exported
+ * `toast()`. Theme follows the active brand theme (via `data-theme`), so it
+ * works with or without <ThemeProvider>.
+ *
+ * ## Customizing toast styling
+ *
+ * The Toaster wrapper renders with the classes `toaster group` by default.
+ * These classes are **merged** with any consumer-supplied `className`, not
+ * replaced, so that built-in styling (the `.group-[.toaster]:*` selectors
+ * on individual toasts) continues to work.
+ *
+ * To override a built-in toast class, **mirror the variant prefix** when you
+ * pass `toastOptions.classNames`. Built-in toast classes are variant-scoped
+ * (e.g. `group-[.toaster]:bg-card`), so a bare utility override will be
+ * outspecificity'd by the built-in and appear to do nothing. Instead, use:
+ *
+ * ```tsx
+ * <Toaster
+ *   toastOptions={{
+ *     classNames: {
+ *       toast: "group-[.toaster]:bg-primary",  // ✓ mirrors the prefix
+ *     }
+ *   }}
+ * />
+ * ```
+ *
+ * ## Theme handling
+ *
+ * The Toaster's `theme` prop is automatically set from the active theme's own
+ * `color-scheme` declaration, so toasts visually track the app's theme by
+ * default — including a theme you authored yourself. However, you may pass
+ * `theme="light"` or `theme="dark"` directly to override this derivation if needed.
+ */
+export function Toaster({ className, toastOptions, ...rest }: ToasterProps) {
+  const mode = useDocumentThemeMode();
+  const userClassNames = toastOptions?.classNames;
+  // Merge (not replace): every default key is extended with the consumer's
+  // override via cn(); any extra keys the consumer passes (e.g. `success`,
+  // `closeButton`) pass through untouched.
+  const classNames = {
+    ...userClassNames,
+    toast: cn(DEFAULT_TOAST_CLASS_NAMES.toast, userClassNames?.toast),
+    description: cn(DEFAULT_TOAST_CLASS_NAMES.description, userClassNames?.description),
+    actionButton: cn(DEFAULT_TOAST_CLASS_NAMES.actionButton, userClassNames?.actionButton),
+    cancelButton: cn(DEFAULT_TOAST_CLASS_NAMES.cancelButton, userClassNames?.cancelButton),
+  };
+  return (
+    <SonnerToaster
+      theme={mode}
+      className={cn("toaster group", className)}
+      toastOptions={{ ...toastOptions, classNames }}
+      {...rest}
+    />
+  );
+}
+
+export { toast };

package/src/components/spinner/index.ts

@@ -0,0 +1 @@
+export { Spinner, type SpinnerProps } from "./spinner";