@vvedantb/ui 0.17.1 → 0.18.1

package/src/ui/sonner.tsx

@@ -1,6 +1,7 @@
 import type { CSSProperties, ReactNode } from "react";
-import { Toaster, type ToasterProps } from "sonner";
+import { Toaster as SonnerPrimitive, type ToasterProps } from "sonner";
 import { filledToastIcons } from "./sonner-icons";
+import { useUiConfig } from "./ui-config";
 import "./sonner.css";
 
 // Sonner toaster aligned with flat tonal surfaces. `unstyled: true` strips
@@ -55,8 +56,24 @@ type SonnerToasterOptions = {
    * while the stack is collapsed. Default false. `sonner.css` has the same rule.
    */
   hideStackedContent?: boolean;
+  /**
+   * Replaces built-in classes. Toast parts (`toast`, `title`, `loader`, …)
+   * replace the package `classNames` per key (`""` removes one); caller
+   * `toastOptions.classNames` still merge after. `toaster` replaces
+   * `toaster group !font-sans` on the toaster list (`""` removes it).
+   */
+  classes?: ToastClassNames & { toaster?: string };
 };
 
+/**
+ * App defaults for `SonnerToaster` (`UiConfig.SonnerToaster`): every key is a
+ * default for the prop of the same name. An explicit prop wins; a prop passed
+ * as `undefined` keeps the config value.
+ */
+type SonnerToasterConfig = Omit<ToasterProps, "className" | "toastOptions"> & SonnerToasterOptions;
+
+const defaultToasterClassName = "toaster group !font-sans";
+
 const hideStackedContentClassName =
   "[&[data-expanded=false][data-front=false]>*]:opacity-0";
 
@@ -161,23 +178,37 @@ function mergeToastOptions(
   };
 }
 
-function SonnerToaster({
-  toastRadius,
-  density,
-  toastIcons = "default",
-  closeButtonStyle = "default",
-  sonnerVars = false,
-  descriptionMuted,
-  titleLeading,
-  loadingIcon,
-  hideStackedContent,
-  toastOptions,
-  icons,
-  style,
-  className,
-  closeButton,
-  ...props
-}: ToasterProps & SonnerToasterOptions) {
+/** `{ ...defaults, ...props }`, except that a prop set to `undefined` keeps its default. */
+function withConfigDefaults<T extends object>(defaults: Partial<T> | undefined, props: T): T {
+  const merged = { ...defaults, ...props };
+  for (const key in defaults) {
+    const value = defaults[key];
+    if (props[key] === undefined && value !== undefined) merged[key] = value;
+  }
+  return merged;
+}
+
+/** Defaults come from `UiConfig.SonnerToaster` when the app sets it; explicit props win. */
+function SonnerToaster(props: ToasterProps & SonnerToasterOptions) {
+  const {
+    classes,
+    toastRadius,
+    density,
+    toastIcons = "default",
+    closeButtonStyle = "default",
+    sonnerVars = false,
+    descriptionMuted,
+    titleLeading,
+    loadingIcon,
+    hideStackedContent,
+    toastOptions,
+    icons,
+    style,
+    className,
+    closeButton,
+    ...rest
+  } = withConfigDefaults(useUiConfig("SonnerToaster"), props);
+  const { toaster: toasterClassName = defaultToasterClassName, ...toastClasses } = classes ?? {};
   const loadingOverride =
     loadingIcon != null ? { loading: loadingIcon } : undefined;
   const mergedIcons =
@@ -187,26 +218,33 @@ function SonnerToaster({
         ? { ...loadingOverride, ...icons }
         : icons;
   return (
-    <Toaster
+    <SonnerPrimitive
       expand={false}
       visibleToasts={4}
       gap={12}
-      {...props}
+      {...rest}
       closeButton={closeButton ?? (closeButtonStyle === "hoverChip" ? true : undefined)}
-      className={className ? `toaster group !font-sans ${className}` : "toaster group !font-sans"}
+      className={
+        toasterClassName && className
+          ? `${toasterClassName} ${className}`
+          : toasterClassName || className || undefined
+      }
       icons={mergedIcons}
       style={mergeToasterStyle(sonnerVars ? sonnerVarsStyle : undefined, style)}
       toastOptions={mergeToastOptions(
         {
           unstyled: true,
-          classNames: createToasterClassNames({
-            toastRadius,
-            density,
-            closeButtonStyle,
-            descriptionMuted,
-            titleLeading,
-            hideStackedContent,
-          }),
+          classNames: {
+            ...createToasterClassNames({
+              toastRadius,
+              density,
+              closeButtonStyle,
+              descriptionMuted,
+              titleLeading,
+              hideStackedContent,
+            }),
+            ...toastClasses,
+          },
         },
         toastOptions,
       )}
@@ -224,4 +262,4 @@ export {
   sonnerVarsStyle,
 };
 export { filledToastIcons } from "./sonner-icons";
-export type { SonnerToasterOptions };
+export type { SonnerToasterConfig, SonnerToasterOptions };

package/src/ui/spinner.tsx

@@ -1,5 +1,6 @@
 import { IconLoader2 } from "@tabler/icons-react";
-import { cn } from "../utils/cn";
+import { bindRuntimeAnimation } from "../utils/runtimeVisibility";
+import { useCn, useUiConfig } from "./ui-config";
 
 const sizeClasses = {
   sm: "size-4",
@@ -7,35 +8,252 @@ const sizeClasses = {
   lg: "size-8",
 };
 
+/** One outline of a {@link SpinnerMark}: a `<polygon>` (`points`) or a `<path>` (`d`). */
+export type SpinnerMarkShape =
+  | { points: string; stroke: string }
+  | { d: string; stroke: string };
+
+/**
+ * A logo (or any outline) drawn as strokes, with a dash that runs around each
+ * shape forever. Each shape gets `pathLength=1`, so `dashArray` is a fraction
+ * of its perimeter (`"0.28 0.72"`: a dash over 28% of the outline).
+ */
+export interface SpinnerMark {
+  viewBox: string;
+  shapes: readonly SpinnerMarkShape[];
+  strokeWidth: number;
+  dashArray: string;
+}
+
+/** Stroke colours of the `circle` variant. Each defaults to `currentColor`. */
+export interface SpinnerCircleColors {
+  /** The faint full ring (drawn at 20% opacity). */
+  track?: string;
+  /** The longer arc. */
+  arc?: string;
+  /** The shorter arc drawn over the leading half of `arc`. */
+  lead?: string;
+}
+
+export interface SpinnerConfig {
+  /** Default for the `mark` prop: every `<Spinner />` without a `variant` draws this mark. */
+  mark?: SpinnerMark;
+  /** Default for the `colors` prop of the `circle` variant. */
+  circle?: SpinnerCircleColors;
+}
+
 export type SpinnerProps = Omit<React.ComponentPropsWithoutRef<"svg">, "size" | "stroke"> & {
-  /** Named size (a `size-*` class) or a pixel size passed to the icon (no size class). Default `"md"`. */
+  /**
+   * What to draw. Without it: the `mark` (prop, else `UiConfig.Spinner.mark`),
+   * else the loader icon. An explicit `variant` wins over the configured mark.
+   * - `"icon"`: the rotating loader icon.
+   * - `"circle"`: a faint ring with a two-tone arc sweeping around it, for
+   *   small slots (inline buttons, menu rows) where a mark is too small to read.
+   * - `"ring"`: the `Button` loading ring, a fixed 16px (`h-4 w-4`) ring and arc
+   *   in `currentColor`. Unlabelled (the button's `disabled` and `data-loading`
+   *   carry the state); `size`, `tone`, `stroke` and `decorative` do not apply.
+   */
+  variant?: "icon" | "circle" | "ring";
+  /** Named size (a `size-*` class) or a pixel size (`width`/`height`, no size class). Default `"md"`. Not used with `"ring"`. */
   size?: "sm" | "md" | "lg" | number;
-  /** Icon stroke width. Default the icon's own (2). */
+  /** Icon stroke width. Default the icon's own (2). Only for `"icon"`. */
   stroke?: number | string;
-  /** `"muted"` adds `text-muted-foreground`; `"inherit"` adds no colour class, so the icon uses `currentColor`. Default `"muted"`. */
+  /** `"muted"` adds `text-muted-foreground`; `"inherit"` adds no colour class, so the icon uses `currentColor`. Default `"muted"`. Only for `"icon"`. */
   tone?: "muted" | "inherit";
-  /** Hide from assistive tech (`aria-hidden`, no `role="status"` or label), e.g. inside a labelled button. Default `false`. */
+  /** Hide from assistive tech (`aria-hidden`, no `role="status"` or label), e.g. inside a labelled button. Default `false`. Not used with `"ring"`. */
   decorative?: boolean;
+  /** Draw this outline with a running dash instead of the loader icon. Default `UiConfig.Spinner.mark`, else none. Ignored with a `variant`. */
+  mark?: SpinnerMark;
+  /** Stroke colours of the `"circle"` variant. Default `UiConfig.Spinner.circle`, else `currentColor`. */
+  colors?: SpinnerCircleColors;
 };
 
-function Spinner({
+/** Props every variant renderer takes: the svg props plus the shared ones. */
+type VariantProps = Omit<SpinnerProps, "variant" | "mark" | "stroke" | "tone" | "colors">;
+
+function a11yProps(decorative: boolean) {
+  return decorative ? { "aria-hidden": true } : { role: "status", "aria-label": "Loading" };
+}
+
+/**
+ * Runs the dash around one shape: `stroke-dashoffset` 0 → -1 over 2s, forever,
+ * against `pathLength=1`. Web Animations rather than SMIL `<animate>`: SMIL
+ * ticks each shape's animated attribute on its own (a style recalc per shape
+ * per frame); WAAPI folds into the frame's single recalc and needs no app
+ * keyframes. {@link bindRuntimeAnimation} pauses it while the tab is hidden or
+ * the shape is off screen. Module-level so the ref identity is stable across
+ * renders; React 19 runs the returned cleanup on detach.
+ */
+function traceDash(shape: SVGGeometryElement | null): (() => void) | undefined {
+  if (!shape) return undefined;
+  const trace = shape.animate(
+    [{ strokeDashoffset: 0 }, { strokeDashoffset: -1 }],
+    { duration: 2000, iterations: Infinity },
+  );
+  return bindRuntimeAnimation(shape, trace);
+}
+
+function MarkSpinner({
+  mark,
+  size = "md",
+  decorative = false,
+  className,
+  ...props
+}: VariantProps & { mark: SpinnerMark }) {
+  const pixels = typeof size === "number" ? size : undefined;
+  const merge = useCn();
+  return (
+    <svg
+      viewBox={mark.viewBox}
+      {...a11yProps(decorative)}
+      width={pixels}
+      height={pixels}
+      className={merge(typeof size === "number" ? undefined : sizeClasses[size], className)}
+      {...props}
+    >
+      {mark.shapes.map((shape, i) =>
+        "points" in shape ? (
+          <polygon
+            key={i}
+            ref={traceDash}
+            points={shape.points}
+            fill="none"
+            stroke={shape.stroke}
+            strokeWidth={mark.strokeWidth}
+            strokeLinejoin="round"
+            strokeLinecap="round"
+            pathLength={1}
+            strokeDasharray={mark.dashArray}
+          />
+        ) : (
+          <path
+            key={i}
+            ref={traceDash}
+            d={shape.d}
+            fill="none"
+            stroke={shape.stroke}
+            strokeWidth={mark.strokeWidth}
+            strokeLinejoin="round"
+            strokeLinecap="round"
+            pathLength={1}
+            strokeDasharray={mark.dashArray}
+          />
+        ),
+      )}
+    </svg>
+  );
+}
+
+/**
+ * Rotates the arc around the viewBox centre, forever. Web Animations rather
+ * than a CSS class: WAAPI gives {@link bindRuntimeAnimation} a handle to pause
+ * the loop while the tab is hidden or the spinner is off screen, which a CSS
+ * `animate-spin` cannot offer. Module-level so the ref identity is stable.
+ */
+function spinArc(arc: SVGGElement): () => void {
+  const spin = arc.animate(
+    [{ transform: "rotate(0deg)" }, { transform: "rotate(360deg)" }],
+    { duration: 900, iterations: Infinity, easing: "linear" },
+  );
+  return bindRuntimeAnimation(arc, spin);
+}
+
+/**
+ * The `circle` variant: a faint full ring with a two-tone arc sweeping around it.
+ *
+ * The arc is two circles rather than one gradient stroke: a gradient only
+ * samples the slice of its box the arc crosses, so at 12–16px one end washes
+ * out. Drawing `lead` over the leading half of a longer `arc` dash keeps both
+ * colours legible at every size, and needs no per-instance gradient id.
+ */
+function CircleSpinner({
+  colors,
   size = "md",
-  tone = "muted",
   decorative = false,
   className,
   ...props
-}: SpinnerProps) {
+}: VariantProps & { colors: SpinnerCircleColors }) {
+  const merge = useCn();
+  const pixels = typeof size === "number" ? size : undefined;
+  const { track = "currentColor", arc = "currentColor", lead = "currentColor" } = colors;
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      {...a11yProps(decorative)}
+      width={pixels}
+      height={pixels}
+      className={merge(typeof size === "number" ? undefined : sizeClasses[size], className)}
+      {...props}
+    >
+      <circle cx="12" cy="12" r="9" fill="none" stroke={track} strokeWidth={3} opacity={0.2} />
+      <g ref={spinArc} style={{ transformBox: "view-box", transformOrigin: "12px 12px" }}>
+        <circle
+          cx="12"
+          cy="12"
+          r="9"
+          fill="none"
+          stroke={arc}
+          strokeWidth={3}
+          strokeLinecap="round"
+          pathLength={1}
+          strokeDasharray="0.36 0.64"
+        />
+        <circle
+          cx="12"
+          cy="12"
+          r="9"
+          fill="none"
+          stroke={lead}
+          strokeWidth={3}
+          strokeLinecap="round"
+          pathLength={1}
+          strokeDasharray="0.18 0.82"
+        />
+      </g>
+    </svg>
+  );
+}
+
+/** The `ring` variant: the `Button` loading ring, a fixed markup with a CSS `animate-spin`. */
+function RingSpinner({
+  className,
+  size: _size,
+  decorative: _decorative,
+  ...props
+}: VariantProps) {
+  const merge = useCn();
+  return (
+    <svg className={merge("h-4 w-4 animate-spin", className)} xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" {...props}>
+      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c3.042 1.135 5.824 3 7.938l3-2.647z" />
+    </svg>
+  );
+}
+
+/**
+ * The one loading spinner: the loader icon, an app mark with a running dash,
+ * the two-tone `circle`, or the `Button` `ring`. See {@link SpinnerProps.variant}.
+ */
+function Spinner({ variant, mark, colors, stroke, tone = "muted", ...props }: SpinnerProps) {
+  const config = useUiConfig("Spinner");
+  const merge = useCn();
+  if (variant === "ring") return <RingSpinner {...props} />;
+  if (variant === "circle") return <CircleSpinner colors={colors ?? config?.circle ?? {}} {...props} />;
+  const resolvedMark = variant ? undefined : (mark ?? config?.mark);
+  if (resolvedMark) return <MarkSpinner mark={resolvedMark} {...props} />;
+  const { size = "md", decorative = false, className, ...iconProps } = props;
   return (
     <IconLoader2
-      {...(decorative ? { "aria-hidden": true } : { role: "status", "aria-label": "Loading" })}
+      {...a11yProps(decorative)}
       size={typeof size === "number" ? size : undefined}
-      className={cn(
+      stroke={stroke}
+      className={merge(
         "animate-spin",
         tone === "muted" && "text-muted-foreground",
         typeof size === "number" ? undefined : sizeClasses[size],
         className,
       )}
-      {...props}
+      {...iconProps}
     />
   );
 }

package/src/ui/status-dot.tsx

@@ -0,0 +1,84 @@
+import type { HTMLAttributes, Ref } from "react";
+
+import { useCn, useUiConfig } from "./ui-config";
+
+export type StatusTone =
+  | "progress"
+  | "business-review"
+  | "code-review"
+  | "done"
+  | "cancelled"
+  /**
+   * Live/online/enabled. Distinct from `done`: this is a *state* something is
+   * currently in, not a workflow stage it has reached.
+   */
+  | "active"
+  /** Something is wrong and needs attention: a critical finding, a hard error. */
+  | "critical"
+  | "neutral";
+
+export interface StatusDotConfig {
+  /** Replaces the built-in classes of a part. */
+  classes?: {
+    /** Fill class per tone. A tone left out keeps its built-in class. */
+    tone?: Partial<Record<StatusTone, string>>;
+  };
+}
+
+// Plain Record so Tailwind's static-class scanner can see every literal
+// class here — a computed `bg-${tone}` string would not survive the purge.
+const TONE_CLASS: Record<StatusTone, string> = {
+  progress: "bg-warning",
+  "business-review": "bg-primary",
+  "code-review": "bg-primary/70",
+  done: "bg-success",
+  cancelled: "bg-muted-foreground/40",
+  active: "bg-success",
+  critical: "bg-destructive",
+  neutral: "bg-muted-foreground/60",
+};
+
+const SIZE_CLASS: Record<"sm" | "md", string> = {
+  sm: "size-1.5",
+  md: "size-2",
+};
+
+export interface StatusDotProps extends HTMLAttributes<HTMLSpanElement> {
+  tone: StatusTone;
+  /** Slightly larger dot for detail views. Default "sm". */
+  size?: "sm" | "md";
+  ref?: Ref<HTMLSpanElement>;
+}
+
+/**
+ * Linear-style status glyph: a small coloured dot that carries the status,
+ * so the label next to it can stay neutral text instead of a coloured pill.
+ *
+ * `ref` is load-bearing: call sites make the dot the tooltip anchor via
+ * `<TooltipTrigger asChild>`, and Radix composes its ref onto that child to
+ * position the popper.
+ */
+export function StatusDot({
+  tone,
+  size = "sm",
+  className,
+  ref,
+  "aria-hidden": ariaHidden = true,
+  ...props
+}: StatusDotProps) {
+  const config = useUiConfig("StatusDot");
+  const merge = useCn();
+  return (
+    <span
+      ref={ref}
+      aria-hidden={ariaHidden}
+      className={merge(
+        "rounded-full shrink-0",
+        SIZE_CLASS[size],
+        config?.classes?.tone?.[tone] ?? TONE_CLASS[tone],
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/src/ui/surface.tsx

@@ -0,0 +1,49 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { useCn } from "./ui-config";
+import { SURFACE_RADIUS_CLASS } from "../utils/surface-radius";
+
+/**
+ * A panel with the card fill and one of four paddings.
+ *
+ * `Card` splits padding across Header / Content / Footer, which is right for a
+ * titled card and wrong for a box that just needs one padding. Density is a
+ * prop rather than a `className` so the paddings stay a closed set;
+ * `className` still overrides when a layout needs it.
+ */
+const surfaceVariants = cva(
+  `${SURFACE_RADIUS_CLASS} bg-card text-card-foreground`,
+  {
+    variants: {
+      density: {
+        // Dense list items and inline panels.
+        tight: "p-3",
+        // The default box: settings sections, stat cards, banners.
+        default: "p-4",
+        // Standalone cards that carry a heading of their own.
+        comfortable: "p-6",
+        // The caller owns padding entirely — for surfaces with their own
+        // internal regions, such as a table that must reach the edge.
+        none: "",
+      },
+    },
+    defaultVariants: {
+      density: "default",
+    },
+  },
+);
+
+export interface SurfaceProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof surfaceVariants> {}
+
+const Surface = React.forwardRef<HTMLDivElement, SurfaceProps>(
+  ({ className, density, ...props }, ref) => {
+    const merge = useCn();
+    return <div ref={ref} className={merge(surfaceVariants({ density }), className)} {...props} />;
+  },
+);
+Surface.displayName = "Surface";
+
+export { Surface, surfaceVariants };

package/src/ui/switch.tsx

@@ -1,26 +1,40 @@
 import * as React from "react";
 import * as SwitchPrimitive from "@radix-ui/react-switch";
 import { cn } from "../utils/cn";
+import { useCn, useUiConfig } from "./ui-config";
+
+/** `UiConfig.Switch`: `classes` replace the built-in part classes. */
+export interface SwitchConfig {
+  classes?: { root?: string; thumb?: string };
+}
 
 const Switch = React.forwardRef<
   React.ComponentRef<typeof SwitchPrimitive.Root>,
   React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>
->(({ className, ...props }, ref) => (
-  <SwitchPrimitive.Root
-    className={cn(
-      "peer relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border border-border bg-default transition-[background-color,border-color] duration-200 ease-smooth focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=unchecked]:bg-default dark:data-[state=unchecked]:border-muted/60 dark:data-[state=unchecked]:bg-muted/40 before:absolute before:inset-[-8px] before:content-['']",
-      className,
-    )}
-    {...props}
-    ref={ref}
-  >
-    <SwitchPrimitive.Thumb
-      className={cn(
-        "pointer-events-none block size-4 rounded-full bg-background ring-0 transition-[transform,background-color] duration-200 ease-smooth data-[state=checked]:translate-x-4 data-[state=checked]:bg-primary-foreground data-[state=unchecked]:translate-x-0 dark:data-[state=unchecked]:bg-foreground",
+>(({ className, ...props }, ref) => {
+  const classes = useUiConfig("Switch")?.classes;
+  const merge = useCn();
+  return (
+    <SwitchPrimitive.Root
+      className={merge(
+        classes?.root ??
+          "peer relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border border-border bg-default transition-[background-color,border-color] duration-200 ease-smooth focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=unchecked]:bg-default dark:data-[state=unchecked]:border-muted/60 dark:data-[state=unchecked]:bg-muted/40 before:absolute before:inset-[-8px] before:content-['']", // check-tokens-allow: muted
+        className,
       )}
-    />
-  </SwitchPrimitive.Root>
-));
+      {...props}
+      ref={ref}
+    >
+      <SwitchPrimitive.Thumb
+        className={
+          classes?.thumb ??
+          cn(
+            "pointer-events-none block size-4 rounded-full bg-background ring-0 transition-[transform,background-color] duration-200 ease-smooth data-[state=checked]:translate-x-4 data-[state=checked]:bg-primary-foreground data-[state=unchecked]:translate-x-0 dark:data-[state=unchecked]:bg-foreground",
+          )
+        }
+      />
+    </SwitchPrimitive.Root>
+  );
+});
 Switch.displayName = SwitchPrimitive.Root.displayName;
 
 export { Switch };