@saasflare/ui 3.1.2 → 3.3.0

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 import { ClassValue } from 'clsx';
+import * as React$1 from 'react';
+import { Ref, MutableRefObject, RefCallback, ReactNode, JSX, ComponentProps } from 'react';
 import { Transition } from 'motion/react';
-import { I as Intent, B as Button } from './button-0Bdl7Nqm.js';
-export { a as ButtonProps, b as buttonVariants } from './button-0Bdl7Nqm.js';
+import { I as Intent, B as Button, a as ButtonProps } from './button-Bfg2Tnvx.js';
+export { b as buttonVariants } from './button-Bfg2Tnvx.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import * as React$1 from 'react';
-import { ReactNode, JSX } from 'react';
-import { P as Palette, S as Surface, R as RadiusProp, a as StyleVariant, b as Radius, c as SaasflareComponentProps } from './use-saasflare-props-NrM2Glmp.js';
-export { C as CustomPalette, d as PALETTES, e as PaletteId, f as RADII, g as ResolvedSaasflareProps, h as STYLES, u as useSaasflareProps } from './use-saasflare-props-NrM2Glmp.js';
-export { D as Dialog, a as DialogClose, b as DialogContent, c as DialogDescription, d as DialogFooter, e as DialogHeader, f as DialogOverlay, g as DialogPortal, h as DialogTitle, i as DialogTrigger } from './dialog-BmY55WSX.js';
+import { I as IconWeight, P as PhosphorIconProps, a as Palette, S as Surface, R as RadiusProp, b as StyleVariant, c as Radius, d as SaasflareComponentProps } from './use-saasflare-props-BrjMhU0U.js';
+export { C as CustomPalette, e as IconBase, f as PALETTES, g as PaletteId, h as RADII, i as ResolvedSaasflareProps, j as STYLES, u as useSaasflareProps } from './use-saasflare-props-BrjMhU0U.js';
+export { D as Dialog, a as DialogClose, b as DialogContent, c as DialogDescription, d as DialogFooter, e as DialogHeader, f as DialogOverlay, g as DialogPortal, h as DialogTitle, i as DialogTrigger } from './dialog-CZRwrqDa.js';
 import * as AlertDialogPrimitive from '@radix-ui/react-alert-dialog';
 import * as AccordionPrimitive from '@radix-ui/react-accordion';
 import * as class_variance_authority_types from 'class-variance-authority/types';
@@ -164,6 +164,32 @@ type UseMeasureReturn<T extends Element = HTMLElement> = readonly [
  */
 declare function useMeasure<T extends Element = HTMLElement>(): UseMeasureReturn<T>;
 
+/** Options for useLocalStorage. */
+interface UseLocalStorageOptions<T> {
+    /** Custom serializer (default: JSON.stringify). */
+    serializer?: (value: T) => string;
+    /** Custom deserializer (default: JSON.parse). */
+    deserializer?: (raw: string) => T;
+    /** Called when read/write/remove fails. Falls back to console.warn if omitted. */
+    onError?: (error: unknown, operation: 'read' | 'write' | 'remove') => void;
+}
+/**
+ * Persists state to localStorage with automatic serialization,
+ * SSR safety, and same-tab + cross-tab synchronization.
+ *
+ * @param key - The localStorage key
+ * @param initialValue - Default value when key doesn't exist
+ * @param options - Optional serializer, deserializer, and error handler
+ * @returns Tuple of [value, setter, remover]
+ *
+ * @example
+ * const [lang, setLang, removeLang] = useLocalStorage('language', 'en');
+ * setLang('de');                    // sets and persists
+ * setLang(prev => prev + '-US');    // functional update
+ * removeLang();                     // removes key, reverts to 'en'
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T, options?: UseLocalStorageOptions<T>): [T, (value: T | ((prev: T) => T)) => void, () => void];
+
 /** An item in the pagination range — either a page number or an ellipsis marker */
 type PaginationRangeItem = number | 'dots';
 /** Options for usePagination */
@@ -221,6 +247,141 @@ interface UsePaginationReturn {
  */
 declare function usePagination(options: UsePaginationOptions): UsePaginationReturn;
 
+/**
+ * @fileoverview Combine multiple refs (callback refs and ref objects) into a
+ * single ref callback. Required whenever a component both forwards a ref AND
+ * needs its own internal ref to the same DOM node.
+ * @author Saasflare™
+ * @module packages/ui/hooks/use-merged-ref
+ * @package ui
+ *
+ * @example
+ * const Card = forwardRef<HTMLDivElement, Props>(function Card(props, forwardedRef) {
+ *   const internalRef = useRef<HTMLDivElement>(null);
+ *   const ref = useMergedRef(internalRef, forwardedRef);
+ *   return <div ref={ref}>…</div>;
+ * });
+ */
+
+/** Anything React accepts as a ref slot. */
+type PossibleRef<T> = Ref<T> | MutableRefObject<T | null> | null | undefined;
+/**
+ * Merges any number of refs into a single ref callback. The callback is
+ * memoized on the identity of the input refs — if you pass new ref objects
+ * on every render, the callback identity will change and React will
+ * detach/reattach. In practice pass stable ref objects.
+ *
+ * @param refs - One or more refs (object refs or callback refs).
+ * @returns A stable ref callback that writes the node to every input ref.
+ *
+ * @example
+ * const ref = useMergedRef(forwardedRef, internalRef);
+ * <div ref={ref} />
+ */
+declare function useMergedRef<T>(...refs: PossibleRef<T>[]): RefCallback<T>;
+
+/** Return value of {@link useInterval}. */
+interface UseIntervalReturn {
+    /** Whether the interval is currently running. */
+    active: boolean;
+    /** Start (or restart) the interval. */
+    start: () => void;
+    /** Stop the interval. */
+    stop: () => void;
+    /** Toggle the interval. */
+    toggle: () => void;
+}
+/** Options for {@link useInterval}. */
+interface UseIntervalOptions {
+    /** If `true`, start the interval immediately. Default: `true`. */
+    autoInvoke?: boolean;
+}
+/**
+ * Calls `callback` every `delay` milliseconds. The latest callback is always
+ * invoked even if the callback identity changes between renders. Pass
+ * `delay = null` to pause.
+ *
+ * @param callback - Function to invoke on each tick.
+ * @param delay - Interval in milliseconds, or `null` to pause.
+ * @param options - Configuration.
+ * @returns Controls for starting/stopping the interval.
+ */
+declare function useInterval(callback: () => void, delay: number | null, options?: UseIntervalOptions): UseIntervalReturn;
+
+/**
+ * Returns a ref to attach to a container. While `active` is `true`:
+ *   - Initial focus moves to the first focusable child (or the container itself
+ *     if it has `tabindex`).
+ *   - Tab and Shift+Tab cycle within the container.
+ *   - On deactivate, focus is restored to whatever was focused before.
+ *
+ * @param active - Whether the trap is engaged.
+ * @returns A ref callback to attach to the container element.
+ *
+ * @example
+ * const trapRef = useFocusTrap<HTMLDivElement>(open);
+ * <div ref={trapRef}>…</div>
+ */
+declare function useFocusTrap<T extends HTMLElement = HTMLElement>(active: boolean): (node: T | null) => void;
+
+/** Return value of the useCountdown hook. */
+interface CountdownValue {
+    /** Days remaining. */
+    days: number;
+    /** Hours remaining (0–23). */
+    hours: number;
+    /** Minutes remaining (0–59). */
+    minutes: number;
+    /** Seconds remaining (0–59). */
+    seconds: number;
+    /** Total milliseconds remaining. */
+    totalMs: number;
+    /** Whether the target date has passed. */
+    isExpired: boolean;
+}
+/**
+ * Returns a live countdown to a target date, updating every second.
+ *
+ * @param {Date | string | number} target - The target date/time
+ * @returns {CountdownValue} The current countdown values
+ *
+ * @example
+ * const { days, hours, minutes, seconds } = useCountdown('2026-12-31T00:00:00');
+ */
+declare function useCountdown(target: Date | string | number): CountdownValue;
+
+/** Options for {@link useFileDialog}. */
+interface UseFileDialogOptions {
+    /** MIME types or extensions to filter (matches `<input accept>`). */
+    accept?: string;
+    /** Allow multiple selection. Default: `false`. */
+    multiple?: boolean;
+    /** Restrict to a folder picker (only supported in Chromium). */
+    directory?: boolean;
+    /** Camera capture mode for mobile (`"user"` | `"environment"`). */
+    capture?: "user" | "environment";
+    /** Called after the user picks files. */
+    onChange?: (files: File[]) => void;
+}
+/** Return value of {@link useFileDialog}. */
+interface UseFileDialogReturn {
+    /** Most recently picked files (empty array if reset/never opened). */
+    files: File[];
+    /** Open the native file picker. */
+    open: () => void;
+    /** Clear the current selection. */
+    reset: () => void;
+}
+/**
+ * Returns an `open()` trigger that pops the native file picker, plus the
+ * selected `files`. No DOM rendered by the consumer is required — the hook
+ * mounts a hidden `<input>` lazily on first call.
+ *
+ * @param options - Configuration mirroring `<input type="file">` attributes.
+ * @returns The selected files and control callbacks.
+ */
+declare function useFileDialog(options?: UseFileDialogOptions): UseFileDialogReturn;
+
 /**
  * @fileoverview Shared motion presets for premium UI components.
  * @module packages/core/components/ui/motion-config
@@ -234,7 +395,7 @@ declare function usePagination(options: UsePaginationOptions): UsePaginationRetu
  *   Use `useReducedMotion()` to disable springs when the user prefers reduced motion.
  *
  * @example
- * import { spring, useReducedMotion } from "@saasflare/core";
+ * import { spring, useReducedMotion } from "@saasflare/ui";
  * const reduced = useReducedMotion();
  * <motion.div transition={reduced ? { duration: 0 } : spring} />
  */
@@ -430,6 +591,77 @@ type Size = "xs" | "sm" | "md" | "lg" | "xl";
  */
 type Density = "compact" | "normal" | "comfortable";
 
+/**
+ * @fileoverview Base primitive for brand-logo Phosphor icons.
+ *
+ * Brand logos extend the standard four Phosphor weights with a fifth,
+ * `"colorful"` — the canonical multi-color brand mark from Iconify's `logos:`
+ * set. The colorful path can't reuse {@link IconBase} because brand SVGs
+ * have non-square viewBoxes (Apple is 256×315, Discord is 256×199, …) and
+ * use hardcoded brand colors instead of `currentColor`.
+ *
+ * BrandIconBase forks the render at the top:
+ *   - weight === "colorful" → emit own `<svg>` with the brand viewBox + content
+ *   - otherwise              → delegate to {@link IconBase}
+ *
+ * @module @saasflare/ui/components/ui/phosphor/brand-icon-base
+ */
+
+/** Brand-logo weight set: standard Phosphor weights + the colored brand variant. */
+type BrandIconWeight = IconWeight | "colorful";
+
+declare const ArrowLeftIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const ArrowRightIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const ArrowUpIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const CaretDownIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const CaretLeftIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const CaretRightIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const CaretUpIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const CheckIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const CheckCircleIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const CircleIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const CircleNotchIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const DotsSixVerticalIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const DotsThreeIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const InfoIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const MagnifyingGlassIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const MinusIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const MonitorIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const MoonIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const PauseIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const PlayIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const QuotesIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const SidebarSimpleIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const SunIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const WarningIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const XIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
+declare const XCircleIcon: React$1.ForwardRefExoticComponent<PhosphorIconProps & React$1.RefAttributes<SVGSVGElement>>;
+
 /** Context value exposed by useSaasflareTheme(). */
 interface SaasflareThemeContextType {
     /** Active brand palette id, or null when using baseline. */
@@ -438,12 +670,16 @@ interface SaasflareThemeContextType {
     surface: StyleVariant;
     /** Active radius preset. */
     radius: Radius;
+    /** Active icon weight for component-rendered Phosphor icons. */
+    iconWeight: IconWeight;
     /** Set the active brand palette (persists to localStorage). */
     setPalette: (id: string) => void;
     /** Set the active surface style (persists to localStorage). */
     setSurface: (style: StyleVariant) => void;
     /** Set the active radius preset (persists to localStorage). */
     setRadius: (radius: Radius) => void;
+    /** Set the active icon weight (persists to localStorage). */
+    setIconWeight: (weight: IconWeight) => void;
 }
 /**
  * Access the Saasflare theme context.
@@ -478,9 +714,19 @@ interface SaasflareProviderProps {
      * - Omit to defer: uses persisted preference if any, otherwise "rounded"
      */
     radius?: RadiusProp;
-    /** Global animation kill switch. @default true */
+    /**
+     * Default icon weight for component-rendered Phosphor icons.
+     * - IconWeight ("regular" | "bold" | "fill" | "duotone") → forces the value
+     * - Omit to defer: uses persisted preference if any, otherwise "regular"
+     */
+    iconWeight?: IconWeight;
+    /**
+     * Global animation kill switch.
+     * - boolean → forces the value
+     * - Omit to defer: uses persisted preference if any, otherwise `true`
+     */
     animated?: boolean;
-    /** Enable smooth scrolling site-wide. @default false */
+    /** Enable smooth scrolling site-wide. @default true */
     smoothScrolling?: boolean;
     /**
      * Skip rendering the pre-hydration FOUT-prevention script.
@@ -520,7 +766,7 @@ interface SaasflareProviderProps {
  * @component
  * @package ui
  */
-declare function SaasflareProvider({ children, theme, palette, surface, radius, animated, smoothScrolling, disableScript, scriptNonce, storageKey, themeStorageKey, }: SaasflareProviderProps): react_jsx_runtime.JSX.Element;
+declare function SaasflareProvider({ children, theme, palette, surface, radius, iconWeight, animated, smoothScrolling, disableScript, scriptNonce, storageKey, themeStorageKey, }: SaasflareProviderProps): react_jsx_runtime.JSX.Element;
 
 /** Props for {@link SaasflareShell}. */
 interface SaasflareShellProps extends Omit<SaasflareProviderProps, "children" | "disableScript" | "scriptNonce"> {
@@ -665,7 +911,7 @@ declare function AlertDialogCancel({ className, ...props }: React$1.ComponentPro
 declare function Accordion({ ...props }: React$1.ComponentProps<typeof AccordionPrimitive.Root>): react_jsx_runtime.JSX.Element;
 interface AccordionItemProps extends Omit<React$1.ComponentProps<typeof AccordionPrimitive.Item>, keyof SaasflareComponentProps>, SaasflareComponentProps {
 }
-declare function AccordionItem({ className, surface, radius, animated, ...props }: AccordionItemProps): react_jsx_runtime.JSX.Element;
+declare function AccordionItem({ className, surface, radius, animated, iconWeight, ...props }: AccordionItemProps): react_jsx_runtime.JSX.Element;
 /**
  * Accordion trigger with animated chevron indicator.
  *
@@ -711,7 +957,7 @@ declare function Textarea({ className, surface, radius, animated, ...props }: Te
 
 interface CheckboxProps extends Omit<React$1.ComponentProps<typeof CheckboxPrimitive.Root>, keyof SaasflareComponentProps>, SaasflareComponentProps {
 }
-declare function Checkbox({ className, surface, radius, animated, ...props }: CheckboxProps): react_jsx_runtime.JSX.Element;
+declare function Checkbox({ className, surface, radius, animated, iconWeight, ...props }: CheckboxProps): react_jsx_runtime.JSX.Element;
 
 interface SwitchProps extends Omit<React$1.ComponentProps<typeof SwitchPrimitive.Root>, keyof SaasflareComponentProps>, SaasflareComponentProps {
     size?: "sm" | "default";
@@ -733,6 +979,41 @@ interface ProgressProps extends Omit<React$1.ComponentProps<typeof ProgressPrimi
  */
 declare function Progress({ className, value, surface, radius, animated, ...props }: ProgressProps): react_jsx_runtime.JSX.Element;
 
+declare const SIZE_PX$1: {
+    readonly sm: 48;
+    readonly md: 64;
+    readonly lg: 96;
+    readonly xl: 128;
+};
+type ProgressCircleSize = keyof typeof SIZE_PX$1;
+/** Props for the ProgressCircle component. */
+interface ProgressCircleProps extends SaasflareComponentProps {
+    /** Current value in the range `[0, max]`. */
+    value: number;
+    /** Maximum value. Default: `100`. */
+    max?: number;
+    /** Size preset. Default: `"md"`. */
+    size?: ProgressCircleSize;
+    /** Ring stroke width in pixels. Default: derived from `size`. */
+    strokeWidth?: number;
+    /** Center content (e.g. the numeric label). */
+    children?: ReactNode;
+    /** Additional class names on the outer wrapper. */
+    className?: string;
+    /** Accessible label. Default: `"<value>%"`. */
+    "aria-label"?: string;
+}
+/**
+ * Circular progress indicator. Drop-in radial counterpart to Progress.
+ *
+ * @component
+ * @layer core
+ *
+ * @example
+ * <ProgressCircle value={72} />
+ */
+declare function ProgressCircle({ value, max, size, strokeWidth, children, className, surface, radius, animated, "aria-label": ariaLabel, }: ProgressCircleProps): react_jsx_runtime.JSX.Element;
+
 /**
  * Badge variant definitions.
  *
@@ -799,7 +1080,7 @@ declare function SelectTrigger({ className, size, children, ...props }: React$1.
 }): react_jsx_runtime.JSX.Element;
 interface SelectContentProps extends Omit<React$1.ComponentProps<typeof SelectPrimitive.Content>, keyof SaasflareComponentProps>, SaasflareComponentProps {
 }
-declare function SelectContent({ className, children, position, surface, radius, animated, ...props }: SelectContentProps): react_jsx_runtime.JSX.Element;
+declare function SelectContent({ className, children, position, surface, radius, animated, iconWeight, ...props }: SelectContentProps): react_jsx_runtime.JSX.Element;
 declare function SelectLabel({ className, ...props }: React$1.ComponentProps<typeof SelectPrimitive.Label>): react_jsx_runtime.JSX.Element;
 declare function SelectItem({ className, children, ...props }: React$1.ComponentProps<typeof SelectPrimitive.Item>): react_jsx_runtime.JSX.Element;
 declare function SelectSeparator({ className, ...props }: React$1.ComponentProps<typeof SelectPrimitive.Separator>): react_jsx_runtime.JSX.Element;
@@ -814,7 +1095,7 @@ declare function DropdownMenuSub({ ...props }: React$1.ComponentProps<typeof Dro
 declare function DropdownMenuRadioGroup({ ...props }: React$1.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>): react_jsx_runtime.JSX.Element;
 interface DropdownMenuContentProps extends Omit<React$1.ComponentProps<typeof DropdownMenuPrimitive.Content>, keyof SaasflareComponentProps>, SaasflareComponentProps {
 }
-declare function DropdownMenuContent({ className, sideOffset, surface, radius, animated, ...props }: DropdownMenuContentProps): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuContent({ className, sideOffset, surface, radius, animated, iconWeight, ...props }: DropdownMenuContentProps): react_jsx_runtime.JSX.Element;
 declare function DropdownMenuItem({ className, inset, variant, ...props }: React$1.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
     inset?: boolean;
     variant?: "default" | "destructive";
@@ -838,7 +1119,7 @@ interface SheetContentProps extends Omit<React$1.ComponentProps<typeof DialogPri
     side?: "top" | "right" | "bottom" | "left";
     showCloseButton?: boolean;
 }
-declare function SheetContent({ className, children, side, showCloseButton, surface, radius, animated, ...props }: SheetContentProps): react_jsx_runtime.JSX.Element;
+declare function SheetContent({ className, children, side, showCloseButton, surface, radius, animated, iconWeight, ...props }: SheetContentProps): react_jsx_runtime.JSX.Element;
 declare function SheetHeader({ className, ...props }: React$1.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
 declare function SheetFooter({ className, ...props }: React$1.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
 declare function SheetTitle({ className, ...props }: React$1.ComponentProps<typeof DialogPrimitive.Title>): react_jsx_runtime.JSX.Element;
@@ -880,7 +1161,7 @@ interface AlertProps extends Omit<React$1.ComponentProps<"div">, keyof Saasflare
  *   <AlertDescription>Something went wrong.</AlertDescription>
  * </Alert>
  */
-declare function Alert({ className, intent: intentProp, variant, surface, radius, animated, ...props }: AlertProps): react_jsx_runtime.JSX.Element;
+declare function Alert({ className, intent: intentProp, variant, surface, radius, animated, iconWeight, ...props }: AlertProps): react_jsx_runtime.JSX.Element;
 /**
  * Alert title text.
  *
@@ -918,7 +1199,7 @@ declare function ContextMenuSubTrigger({ className, inset, children, ...props }:
 declare function ContextMenuSubContent({ className, ...props }: React$1.ComponentProps<typeof ContextMenuPrimitive.SubContent>): react_jsx_runtime.JSX.Element;
 interface ContextMenuContentProps extends Omit<React$1.ComponentProps<typeof ContextMenuPrimitive.Content>, keyof SaasflareComponentProps>, SaasflareComponentProps {
 }
-declare function ContextMenuContent({ className, surface, radius, animated, ...props }: ContextMenuContentProps): react_jsx_runtime.JSX.Element;
+declare function ContextMenuContent({ className, surface, radius, animated, iconWeight, ...props }: ContextMenuContentProps): react_jsx_runtime.JSX.Element;
 declare function ContextMenuItem({ className, inset, variant, ...props }: React$1.ComponentProps<typeof ContextMenuPrimitive.Item> & {
     inset?: boolean;
     variant?: "default" | "destructive";
@@ -933,7 +1214,7 @@ declare function ContextMenuShortcut({ className, ...props }: React$1.ComponentP
 
 interface MenubarProps extends Omit<React$1.ComponentProps<typeof MenubarPrimitive.Root>, keyof SaasflareComponentProps>, SaasflareComponentProps {
 }
-declare function Menubar({ className, surface, radius, animated, ...props }: MenubarProps): react_jsx_runtime.JSX.Element;
+declare function Menubar({ className, surface, radius, animated, iconWeight, ...props }: MenubarProps): react_jsx_runtime.JSX.Element;
 declare function MenubarMenu({ ...props }: React$1.ComponentProps<typeof MenubarPrimitive.Menu>): react_jsx_runtime.JSX.Element;
 declare function MenubarGroup({ ...props }: React$1.ComponentProps<typeof MenubarPrimitive.Group>): react_jsx_runtime.JSX.Element;
 declare function MenubarPortal({ ...props }: React$1.ComponentProps<typeof MenubarPrimitive.Portal>): react_jsx_runtime.JSX.Element;
@@ -941,7 +1222,7 @@ declare function MenubarRadioGroup({ ...props }: React$1.ComponentProps<typeof M
 declare function MenubarTrigger({ className, ...props }: React$1.ComponentProps<typeof MenubarPrimitive.Trigger>): react_jsx_runtime.JSX.Element;
 interface MenubarContentProps extends Omit<React$1.ComponentProps<typeof MenubarPrimitive.Content>, keyof SaasflareComponentProps>, SaasflareComponentProps {
 }
-declare function MenubarContent({ className, align, alignOffset, sideOffset, surface, radius, animated, ...props }: MenubarContentProps): react_jsx_runtime.JSX.Element;
+declare function MenubarContent({ className, align, alignOffset, sideOffset, surface, radius, animated, iconWeight, ...props }: MenubarContentProps): react_jsx_runtime.JSX.Element;
 declare function MenubarItem({ className, inset, variant, ...props }: React$1.ComponentProps<typeof MenubarPrimitive.Item> & {
     inset?: boolean;
     variant?: "default" | "destructive";
@@ -962,7 +1243,7 @@ declare function MenubarSubContent({ className, ...props }: React$1.ComponentPro
 interface NavigationMenuProps extends Omit<React$1.ComponentProps<typeof NavigationMenuPrimitive.Root>, keyof SaasflareComponentProps>, SaasflareComponentProps {
     viewport?: boolean;
 }
-declare function NavigationMenu({ className, children, viewport, surface, radius, animated, ...props }: NavigationMenuProps): react_jsx_runtime.JSX.Element;
+declare function NavigationMenu({ className, children, viewport, surface, radius, animated, iconWeight, ...props }: NavigationMenuProps): react_jsx_runtime.JSX.Element;
 declare function NavigationMenuList({ className, ...props }: React$1.ComponentProps<typeof NavigationMenuPrimitive.List>): react_jsx_runtime.JSX.Element;
 declare function NavigationMenuItem({ className, ...props }: React$1.ComponentProps<typeof NavigationMenuPrimitive.Item>): react_jsx_runtime.JSX.Element;
 declare const navigationMenuTriggerStyle: (props?: class_variance_authority_types.ClassProp | undefined) => string;
@@ -1012,7 +1293,7 @@ declare function ToggleGroupItem({ className, children, variant, size, ...props
 
 interface RadioGroupProps extends Omit<React$1.ComponentProps<typeof RadioGroupPrimitive.Root>, keyof SaasflareComponentProps>, SaasflareComponentProps {
 }
-declare function RadioGroup({ className, surface, radius, animated, ...props }: RadioGroupProps): react_jsx_runtime.JSX.Element;
+declare function RadioGroup({ className, surface, radius, animated, iconWeight, ...props }: RadioGroupProps): react_jsx_runtime.JSX.Element;
 declare function RadioGroupItem({ className, ...props }: React$1.ComponentProps<typeof RadioGroupPrimitive.Item>): react_jsx_runtime.JSX.Element;
 
 interface CollapsibleContentProps extends Omit<React$1.ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>, keyof SaasflareComponentProps>, SaasflareComponentProps {
@@ -1032,13 +1313,13 @@ declare function ScrollBar({ className, orientation, ...props }: React$1.Compone
 
 interface SaasflareToasterProps extends Omit<ToasterProps, keyof SaasflareComponentProps>, SaasflareComponentProps {
 }
-declare const Toaster: ({ surface, radius, animated, ...props }: SaasflareToasterProps) => react_jsx_runtime.JSX.Element;
+declare const Toaster: ({ surface, radius, animated, iconWeight, ...props }: SaasflareToasterProps) => react_jsx_runtime.JSX.Element;
 
 declare function AspectRatio({ ...props }: React.ComponentProps<typeof AspectRatioPrimitive.Root>): react_jsx_runtime.JSX.Element;
 
 interface BreadcrumbProps extends Omit<React$1.ComponentProps<"nav">, keyof SaasflareComponentProps>, SaasflareComponentProps {
 }
-declare function Breadcrumb({ surface, radius, animated, ...props }: BreadcrumbProps): react_jsx_runtime.JSX.Element;
+declare function Breadcrumb({ surface, radius, animated, iconWeight, ...props }: BreadcrumbProps): react_jsx_runtime.JSX.Element;
 declare function BreadcrumbList({ className, ...props }: React$1.ComponentProps<"ol">): react_jsx_runtime.JSX.Element;
 declare function BreadcrumbItem({ className, ...props }: React$1.ComponentProps<"li">): react_jsx_runtime.JSX.Element;
 declare function BreadcrumbLink({ asChild, className, ...props }: React$1.ComponentProps<"a"> & {
@@ -1221,7 +1502,7 @@ declare function KbdGroup({ className, ...props }: React.ComponentProps<"div">):
 interface NativeSelectProps extends Omit<React$1.ComponentProps<"select">, "size" | keyof SaasflareComponentProps>, SaasflareComponentProps {
     size?: "sm" | "default";
 }
-declare function NativeSelect({ className, size, surface, radius, animated, ...props }: NativeSelectProps): react_jsx_runtime.JSX.Element;
+declare function NativeSelect({ className, size, surface, radius, animated, iconWeight, ...props }: NativeSelectProps): react_jsx_runtime.JSX.Element;
 declare function NativeSelectOption({ ...props }: React$1.ComponentProps<"option">): react_jsx_runtime.JSX.Element;
 declare function NativeSelectOptGroup({ className, ...props }: React$1.ComponentProps<"optgroup">): react_jsx_runtime.JSX.Element;
 
@@ -1478,6 +1759,480 @@ interface MetricCardProps extends Omit<React$1.ComponentProps<"div">, keyof Saas
  */
 declare function MetricCard({ label, value, trend, icon, className, surface, radius, animated, ...props }: MetricCardProps): react_jsx_runtime.JSX.Element;
 
+/** A single row in the list. */
+interface BarListItem {
+    /** Row label. */
+    name: string;
+    /** Numeric value driving the bar width. */
+    value: number;
+    /** Optional icon shown left of the label. */
+    icon?: ReactNode;
+    /** Optional click target for the row label (wraps in `<a>`). */
+    href?: string;
+    /** Optional per-row color override (any CSS color). */
+    color?: string;
+}
+/** Props for the BarList component. */
+interface BarListProps extends SaasflareComponentProps {
+    /** Rows to render. */
+    data: BarListItem[];
+    /** Formats the numeric value on the right edge. Default: `String(n)`. */
+    valueFormatter?: (value: number) => string;
+    /** Sort rows by value descending. Default: `true`. */
+    sortDescending?: boolean;
+    /** Maximum rows rendered (truncates after sort). */
+    limit?: number;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Horizontal bar list — common dashboard "top N" rankings pattern.
+ *
+ * @component
+ * @layer core
+ */
+declare function BarList({ data, valueFormatter, sortDescending, limit, className, surface, radius, animated, }: BarListProps): react_jsx_runtime.JSX.Element;
+
+/** Visual variant of the spark chart. */
+type SparkChartVariant = "line" | "area" | "bar";
+/** Props for the SparkChart component. */
+interface SparkChartProps extends SaasflareComponentProps {
+    /** Series of numeric points (length ≥ 2). */
+    data: number[];
+    /** Visual treatment. Default: `"area"`. */
+    variant?: SparkChartVariant;
+    /** Stroke / fill color (any CSS color). Default: `var(--primary)`. */
+    color?: string;
+    /** SVG width in pixels. Default: `64`. */
+    width?: number;
+    /** SVG height in pixels. Default: `24`. */
+    height?: number;
+    /** Line stroke width in pixels. Default: `1.5`. */
+    strokeWidth?: number;
+    /** Additional class names. */
+    className?: string;
+    /** Accessible label. */
+    "aria-label"?: string;
+}
+/**
+ * Inline mini chart for KPI tiles, table cells, and metric cards.
+ *
+ * @component
+ * @layer core
+ */
+declare function SparkChart({ data, variant, color, width, height, strokeWidth, className, surface, radius, animated, "aria-label": ariaLabel, }: SparkChartProps): react_jsx_runtime.JSX.Element | null;
+
+/** A single tracker block. */
+interface TrackerBlock {
+    /** Named color key (emerald|teal|blue|amber|red|rose|gray) or any CSS color. */
+    color?: string;
+    /** Tooltip text shown on hover. */
+    tooltip?: ReactNode;
+    /** Custom key (helps React when blocks rearrange). */
+    key?: string | number;
+}
+/** Props for the Tracker component. */
+interface TrackerProps extends SaasflareComponentProps {
+    /** Blocks to render, left-to-right. */
+    data: TrackerBlock[];
+    /** Height of each block in px. Default: `32`. */
+    blockHeight?: number;
+    /** Gap between blocks in px. Default: `2`. */
+    gap?: number;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Status segment grid (uptime/incident timeline).
+ *
+ * @component
+ * @layer core
+ */
+declare function Tracker({ data, blockHeight, gap, className, surface, radius, animated, }: TrackerProps): react_jsx_runtime.JSX.Element;
+
+/** Reason a file was rejected by the dropzone's built-in validation. */
+type DropzoneRejectionReason = "too-large" | "type-mismatch";
+/** A rejected file with the reason. */
+interface DropzoneRejection {
+    file: File;
+    reason: DropzoneRejectionReason;
+}
+/** Props for the Dropzone component. */
+interface DropzoneProps extends SaasflareComponentProps {
+    /** Called with `(accepted, rejected)` when the user drops or picks files. */
+    onDrop?: (accepted: File[], rejected: DropzoneRejection[]) => void;
+    /** MIME types or extensions to accept (matches `<input accept>`). */
+    accept?: string;
+    /** Maximum file size in bytes. */
+    maxSize?: number;
+    /** Allow multiple file selection. Default: `true`. */
+    multiple?: boolean;
+    /** Disable the dropzone. */
+    disabled?: boolean;
+    /** Render-prop body. Receives `isDragActive`. Falls back to the default UI. */
+    children?: ReactNode | ((state: {
+        isDragActive: boolean;
+    }) => ReactNode);
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Drag-and-drop file upload area with click-to-open fallback.
+ *
+ * @component
+ * @layer core
+ */
+declare function Dropzone({ onDrop, accept, maxSize, multiple, disabled, children, className, surface, radius, animated, }: DropzoneProps): react_jsx_runtime.JSX.Element;
+
+/** Inclusive date range, identical shape to react-day-picker's `DateRange`. */
+interface DateRange {
+    from: Date | undefined;
+    to?: Date | undefined;
+}
+/** Props for the DateRangePicker component. */
+interface DateRangePickerProps extends SaasflareComponentProps {
+    /** Controlled value. */
+    value?: DateRange;
+    /** Uncontrolled default value. */
+    defaultValue?: DateRange;
+    /** Called when the user picks a new range. */
+    onChange?: (range: DateRange | undefined) => void;
+    /** Placeholder shown in the trigger when no range is set. */
+    placeholder?: string;
+    /** Number of months shown side-by-side. Default: `2`. */
+    numberOfMonths?: number;
+    /** Earliest pickable date. */
+    minDate?: Date;
+    /** Latest pickable date. */
+    maxDate?: Date;
+    /** Disable the trigger. */
+    disabled?: boolean;
+    /** Format function for the trigger label. Default: locale-aware `toLocaleDateString`. */
+    formatRange?: (range: DateRange) => string;
+    /** Additional class names on the trigger. */
+    className?: string;
+}
+/**
+ * Date-range input + popover calendar. Composes Button + Popover + Calendar.
+ *
+ * @component
+ * @layer core
+ */
+declare function DateRangePicker({ value, defaultValue, onChange, placeholder, numberOfMonths, minDate, maxDate, disabled, formatRange, className, surface, radius, animated, iconWeight, }: DateRangePickerProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the DatePicker component. */
+interface DatePickerProps extends SaasflareComponentProps {
+    /** Controlled value. */
+    value?: Date;
+    /** Uncontrolled default value. */
+    defaultValue?: Date;
+    /** Called when the user picks a date. */
+    onChange?: (date: Date | undefined) => void;
+    /** Placeholder shown when no date is set. */
+    placeholder?: string;
+    /** Earliest pickable date. */
+    minDate?: Date;
+    /** Latest pickable date. */
+    maxDate?: Date;
+    /** Disable the trigger. */
+    disabled?: boolean;
+    /** Format function for the trigger label. Default: locale-aware. */
+    formatDate?: (date: Date) => string;
+    /** Additional class names on the trigger. */
+    className?: string;
+}
+/**
+ * Single-date input + popover calendar. Composes Button + Popover + Calendar.
+ *
+ * @component
+ * @layer core
+ */
+declare function DatePicker({ value, defaultValue, onChange, placeholder, minDate, maxDate, disabled, formatDate, className, surface, radius, animated, iconWeight, }: DatePickerProps): react_jsx_runtime.JSX.Element;
+
+declare const INTENTS: readonly ["primary", "neutral", "success", "warning", "danger", "info"];
+type CalloutIntent = (typeof INTENTS)[number];
+/** Props for the Callout component. */
+interface CalloutProps extends SaasflareComponentProps {
+    /** Color intent. Default: `"info"`. */
+    intent?: CalloutIntent;
+    /** Bold title rendered above the body. */
+    title?: ReactNode;
+    /** Leading icon (rendered in the same color as the intent stripe). */
+    icon?: ReactNode;
+    /** Body content. */
+    children?: ReactNode;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Inline emphasized message box with intent-driven coloring.
+ *
+ * @component
+ * @layer core
+ *
+ * @example
+ * <Callout intent="success" title="Saved">Your changes are live.</Callout>
+ */
+declare function Callout({ intent, title, icon, children, className, surface, radius, animated, iconWeight, }: CalloutProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the TagInput component. */
+interface TagInputProps extends SaasflareComponentProps {
+    /** Controlled list of tags. */
+    value?: string[];
+    /** Uncontrolled initial tags. */
+    defaultValue?: string[];
+    /** Called whenever the tag list changes. */
+    onChange?: (tags: string[]) => void;
+    /** Placeholder shown in the input. */
+    placeholder?: string;
+    /** Maximum number of tags accepted. */
+    maxTags?: number;
+    /** Characters that commit the current input as a tag. Default: `[",", "Enter"]`. */
+    separators?: string[];
+    /** Reject duplicate tags. Default: `true`. */
+    unique?: boolean;
+    /** Disable the input. */
+    disabled?: boolean;
+    /** Custom renderer for each pill. Falls back to the default pill UI. */
+    renderTag?: (tag: string, onRemove: () => void) => ReactNode;
+    /** Additional class names on the outer wrapper. */
+    className?: string;
+    /** Accessible label. */
+    "aria-label"?: string;
+}
+/**
+ * Input field that converts text into removable tag pills.
+ *
+ * @component
+ * @layer core
+ */
+declare function TagInput({ value, defaultValue, onChange, placeholder, maxTags, separators, unique, disabled, renderTag, className, surface, radius, animated, "aria-label": ariaLabel, }: TagInputProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the NumberInput component. */
+interface NumberInputProps extends SaasflareComponentProps {
+    /** Controlled value. */
+    value?: number;
+    /** Uncontrolled initial value. */
+    defaultValue?: number;
+    /** Called when the value changes (after clamp). */
+    onChange?: (value: number) => void;
+    /** Minimum allowed value. */
+    min?: number;
+    /** Maximum allowed value. */
+    max?: number;
+    /** Step for stepper buttons + arrow keys. Default: `1`. */
+    step?: number;
+    /** Decimal precision for display. Default: derived from `step`. */
+    precision?: number;
+    /** Placeholder shown when empty. */
+    placeholder?: string;
+    /** Disable the input. */
+    disabled?: boolean;
+    /** Read-only input. */
+    readOnly?: boolean;
+    /** Hide the stepper buttons. */
+    hideSteppers?: boolean;
+    /** Additional class names on the outer wrapper. */
+    className?: string;
+    /** Name attribute (for form submission). */
+    name?: string;
+    /** Accessible label. */
+    "aria-label"?: string;
+}
+/**
+ * Numeric input with stepper buttons and clamping.
+ *
+ * @component
+ * @layer core
+ */
+declare function NumberInput({ value, defaultValue, onChange, min, max, step, precision, placeholder, disabled, readOnly, hideSteppers, className, name, surface, radius, animated, "aria-label": ariaLabel, }: NumberInputProps): react_jsx_runtime.JSX.Element;
+
+declare const SIZE_PX: {
+    readonly sm: 14;
+    readonly md: 20;
+    readonly lg: 28;
+    readonly xl: 36;
+};
+type RatingSize = keyof typeof SIZE_PX;
+/** Props for the Rating component. */
+interface RatingProps extends SaasflareComponentProps {
+    /** Controlled value (0..count). */
+    value?: number;
+    /** Uncontrolled initial value. */
+    defaultValue?: number;
+    /** Called when the user clicks a star. */
+    onChange?: (value: number) => void;
+    /** Number of stars. Default: `5`. */
+    count?: number;
+    /** Allow half-star granularity. Default: `false`. */
+    allowHalf?: boolean;
+    /** Read-only display mode (no interaction, no hover preview). */
+    readOnly?: boolean;
+    /** Disable the rating. */
+    disabled?: boolean;
+    /** Star size. Default: `"md"`. */
+    size?: RatingSize;
+    /** Star color (any CSS color). Default: `var(--warning)` — brand-independent gold. */
+    color?: string;
+    /** Additional class names. */
+    className?: string;
+    /** Accessible label. */
+    "aria-label"?: string;
+}
+/**
+ * Star rating input with half-star and read-only support.
+ *
+ * @component
+ * @layer core
+ */
+declare function Rating({ value, defaultValue, onChange, count, allowHalf, readOnly, disabled, size, color, className, surface, radius, animated, "aria-label": ariaLabel, }: RatingProps): react_jsx_runtime.JSX.Element;
+
+/** A single segment of the bar. */
+interface CategoryBarSegment {
+    /** Numeric value driving the segment width (auto-normalized). */
+    value: number;
+    /** Any CSS color. Falls back to a derived primary tint. */
+    color?: string;
+    /** Optional label shown below the segment when `showLabels` is true. */
+    label?: string;
+}
+/** Props for the CategoryBar component. */
+interface CategoryBarProps extends SaasflareComponentProps {
+    /** Segments to render, left-to-right. */
+    segments: CategoryBarSegment[];
+    /** Bar height in pixels. Default: `8`. */
+    height?: number;
+    /** Render labels + percentages under each segment. */
+    showLabels?: boolean;
+    /** Formats the percentage text. Default: `"NN%"`. */
+    valueFormatter?: (percent: number) => string;
+    /** Additional class names. */
+    className?: string;
+    /** Accessible label for the bar group. */
+    "aria-label"?: string;
+}
+/**
+ * Segmented progress bar with optional labels.
+ *
+ * @component
+ * @layer core
+ */
+declare function CategoryBar({ segments, height, showLabels, valueFormatter, className, surface, radius, animated, "aria-label": ariaLabel, }: CategoryBarProps): react_jsx_runtime.JSX.Element | null;
+
+/** A single tree node. */
+interface TreeNode {
+    /** Unique node id (stable across renders). */
+    id: string;
+    /** Display label or any ReactNode. */
+    label: ReactNode;
+    /** Leading icon (e.g. file/folder glyph). */
+    icon?: ReactNode;
+    /** Child nodes (omit for leaves). */
+    children?: TreeNode[];
+    /** Disable interaction for this node. */
+    disabled?: boolean;
+}
+/** Props for the TreeView component. */
+interface TreeViewProps extends SaasflareComponentProps {
+    /** Tree data, top-level nodes. */
+    data: TreeNode[];
+    /** Controlled expanded ids. */
+    expanded?: string[];
+    /** Uncontrolled initial expansion. */
+    defaultExpanded?: string[];
+    /** Called when a node is expanded/collapsed. */
+    onExpand?: (ids: string[]) => void;
+    /** Controlled selected id. */
+    selected?: string | null;
+    /** Uncontrolled initial selection. */
+    defaultSelected?: string | null;
+    /** Called when selection changes. */
+    onSelect?: (id: string | null) => void;
+    /** Additional class names on the root. */
+    className?: string;
+}
+/**
+ * Recursive expand/collapse tree with keyboard navigation.
+ *
+ * @component
+ * @layer core
+ */
+declare function TreeView({ data, expanded, defaultExpanded, onExpand, selected, defaultSelected, onSelect, className, surface, radius, animated, iconWeight, }: TreeViewProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the CodeBlock component. */
+interface CodeBlockProps extends SaasflareComponentProps {
+    /** Plain source code (rendered as monospace, no highlighting). */
+    code?: string;
+    /** Pre-highlighted HTML — e.g. output from Shiki's `codeToHtml`. */
+    highlighted?: string;
+    /** Language label shown in the header (purely cosmetic). */
+    language?: string;
+    /** Filename shown left of the language badge. */
+    filename?: string;
+    /** Show 1-based line numbers in the gutter. */
+    showLineNumbers?: boolean;
+    /** Hide the top bar (copy button still floats inside the block). */
+    hideHeader?: boolean;
+    /** Hide the copy-to-clipboard button. */
+    hideCopyButton?: boolean;
+    /** Additional class names on the outer wrapper. */
+    className?: string;
+}
+/**
+ * Code block with filename header, language badge, copy button, and optional
+ * line numbers. Highlighting is BYO (pass `highlighted` HTML or `code` text).
+ *
+ * @component
+ * @layer core
+ */
+declare function CodeBlock({ code, highlighted, language, filename, showLineNumbers, hideHeader, hideCopyButton, className, surface, radius, animated, }: CodeBlockProps): react_jsx_runtime.JSX.Element;
+
+/** A single notification item. */
+interface NotificationItem {
+    /** Stable unique id. */
+    id: string;
+    /** Bold title line. */
+    title: ReactNode;
+    /** Secondary body line. */
+    description?: ReactNode;
+    /** Display timestamp (already formatted — e.g. "5m ago"). */
+    timestamp?: string;
+    /** Whether the notification has been read. */
+    read?: boolean;
+    /** Optional leading icon. */
+    icon?: ReactNode;
+    /** Optional href — wraps the row in `<a>`. */
+    href?: string;
+}
+/** Props for the NotificationCenter component. */
+interface NotificationCenterProps extends SaasflareComponentProps {
+    /** Notifications to display. */
+    items: NotificationItem[];
+    /** Header title in the popover. Default: `"Notifications"`. */
+    title?: string;
+    /** Called when the user clicks a row (also passes the item). */
+    onItemClick?: (item: NotificationItem) => void;
+    /** Called when "Mark as read" is tapped on a row. */
+    onMarkRead?: (id: string) => void;
+    /** Called when "Mark all as read" is tapped. Hide the action by omitting this. */
+    onMarkAllRead?: () => void;
+    /** Custom empty-state content. */
+    emptyState?: ReactNode;
+    /** Maximum items rendered (older ones truncated). */
+    limit?: number;
+    /** Additional class names on the trigger button. */
+    triggerClassName?: string;
+    /** Additional class names on the popover content. */
+    contentClassName?: string;
+}
+/**
+ * Bell trigger + dropdown inbox of notifications.
+ *
+ * @component
+ * @layer core
+ */
+declare function NotificationCenter({ items, title, onItemClick, onMarkRead, onMarkAllRead, emptyState, limit, triggerClassName, contentClassName, surface, radius, animated, iconWeight, }: NotificationCenterProps): react_jsx_runtime.JSX.Element;
+
 /** Props for the EmptyState component */
 interface EmptyStateProps extends Omit<React$1.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {
     /** Icon or illustration element */
@@ -1536,7 +2291,7 @@ interface SearchFieldProps extends Omit<React$1.ComponentProps<"input">, "type"
  *   loading={isSearching}
  * />
  */
-declare function SearchField({ className, loading, onClear, value, surface, radius, animated, ...props }: SearchFieldProps): react_jsx_runtime.JSX.Element;
+declare function SearchField({ className, loading, onClear, value, surface, radius, animated, iconWeight, ...props }: SearchFieldProps): react_jsx_runtime.JSX.Element;
 
 /** Props for the SettingsSection component */
 interface SettingsSectionProps extends Omit<React$1.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {
@@ -1606,7 +2361,7 @@ interface PricingCardProps extends Omit<React$1.ComponentProps<"div">, keyof Saa
  *   featured
  * />
  */
-declare function PricingCard({ name, price, period, description, features, cta, featured, className, surface, radius, animated, ...props }: PricingCardProps): react_jsx_runtime.JSX.Element;
+declare function PricingCard({ name, price, period, description, features, cta, featured, className, surface, radius, animated, iconWeight, ...props }: PricingCardProps): react_jsx_runtime.JSX.Element;
 
 interface DataToolbarProps extends Omit<React$1.ComponentProps<"div">, keyof SaasflareComponentProps>, SaasflareComponentProps {
 }
@@ -1647,51 +2402,1368 @@ declare function DataToolbarFilters({ className, ...props }: React$1.ComponentPr
  */
 declare function DataToolbarActions({ className, ...props }: React$1.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
 
+/** Props for the AuroraBackground component. */
+interface AuroraBackgroundProps extends Omit<ComponentProps<"div">, keyof SaasflareComponentProps | "color">, SaasflareComponentProps {
+    /**
+     * Three ambient blob colors in order: top-left, right, bottom-left.
+     * Default: curated peach + blue + violet showcase palette.
+     */
+    colors?: readonly [string, string, string];
+    /** Overall blob opacity (0–1). Default: `0.55`. Auto-halved in dark mode via `dark:` modifier. */
+    intensity?: number;
+}
 /**
- * Props for the ScrollToTopButton component.
+ * Soft multi-color gradient backdrop for showcase, demo, and marketing sections.
  *
- * @interface
- * @package ui
+ * Renders three blurred radial blobs positioned at corners around the children
+ * slot. Default palette is a fixed showcase combination (peach / blue / violet)
+ * so the visual stays consistent across brand palettes; pass `colors` to switch
+ * to brand-rotating tokens. Drift animation is on by default and respects
+ * `prefers-reduced-motion`.
+ *
+ * @component
+ * @layer core
  */
-interface ScrollToTopButtonProps extends SaasflareComponentProps {
-    /**
-     * Optional scroll container element ID.
-     * If not provided, falls back to the global `window`.
-     */
-    scrollContainerId?: string;
-    /**
-     * Vertical scroll offset (in pixels) after which the button is shown.
-     * @default 300
-     */
-    scrollOffset?: number;
-    /** Additional class names merged onto the root button. */
+declare function AuroraBackground({ colors, intensity, className, children, surface, radius, animated, ...props }: AuroraBackgroundProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the AudioPlayer component. */
+interface AudioPlayerProps extends SaasflareComponentProps {
+    /** Audio source URL. */
+    src: string;
+    /** Track title. */
+    title?: string;
+    /** Additional class names. */
     className?: string;
 }
 /**
- * A floating button that appears after scrolling down and smoothly scrolls
- * the user back to the top of the container (or window).
+ * Styled audio player with play/pause, seek, and time display.
  *
  * @component
+ * @package ui
  */
-declare function ScrollToTopButton({ scrollContainerId, scrollOffset, className, ...sfProps }: ScrollToTopButtonProps): JSX.Element;
+declare function AudioPlayer({ src, title, className, surface, radius, animated, }: AudioPlayerProps): react_jsx_runtime.JSX.Element;
 
+/** Props for the BentoGrid container. */
+interface BentoGridProps {
+    /** Grid items. */
+    children: ReactNode;
+    /** Number of columns at md+ breakpoint. Default: `3` */
+    columns?: 2 | 3 | 4;
+    /** Gap between items in Tailwind spacing units (4 = 1rem). Default: `4` */
+    gap?: number;
+    /** Additional class names. */
+    className?: string;
+}
 /**
- * Theme mode toggle button with Sun/Moon icons.
+ * Responsive bento-style grid container with staggered item entrance.
+ *
+ * - Items animate in with a staggered fade+slide
+ * - Supports 2, 3, or 4 column layouts (1 column on mobile)
+ * - Items can span multiple columns/rows via BentoGridItem
  *
  * @component
- * @layer core
+ * @package ui
+ */
+declare function BentoGrid({ children, columns, gap, className, }: BentoGridProps): react_jsx_runtime.JSX.Element;
+/** Props for a BentoGridItem. */
+interface BentoGridItemProps extends SaasflareComponentProps {
+    /** Item content. */
+    children: ReactNode;
+    /** Number of columns to span (1–4). Default: `1` */
+    colSpan?: 1 | 2 | 3 | 4;
+    /** Number of rows to span (1–3). Default: `1` */
+    rowSpan?: 1 | 2 | 3;
+    /** Stagger delay index (multiply by 0.08 for delay). Default: `0` */
+    index?: number;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Individual item within a BentoGrid.
  *
- * @param {object} props - Component props
- * @param {boolean} [props.showText=false] - Whether to show the label text visibly
- * @param {string} [props.text] - Custom label text override
- * @param {string} [props.className] - Additional CSS class names
- * @returns {JSX.Element | null} The toggle button, or null before hydration
+ * - Supports column and row spanning
+ * - Animates in with a staggered fade + vertical slide
+ * - Pass `index` for stagger ordering
+ *
+ * @component
+ * @package ui
  */
-declare function ThemeModeToggle({ showText, text, className, }: {
-    showText?: boolean;
-    text?: string;
+declare function BentoGridItem({ children, colSpan, rowSpan, index, className, surface, radius, animated, }: BentoGridItemProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the BlurFade component. */
+interface BlurFadeProps {
+    /** Content to animate. */
+    children: ReactNode;
+    /** Animation delay in seconds (use for staggering). Default: `0` */
+    delay?: number;
+    /** Initial blur amount in pixels. Default: `8` */
+    blur?: number;
+    /** Vertical offset in pixels. Default: `12` */
+    yOffset?: number;
+    /** Animation duration in seconds. Default: `0.5` */
+    duration?: number;
+    /** Whether animation triggers only once. Default: `true` */
+    once?: boolean;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Entrance animation that combines blur, opacity, and vertical slide.
+ *
+ * - Great for staggered reveals: pass incrementing `delay` values
+ * - Blur clears simultaneously with the fade for a cohesive effect
+ * - Renders children statically when reduced motion is preferred
+ * - Uses Intersection Observer to trigger on viewport entry
+ *
+ * @component
+ * @package ui
+ */
+declare function BlurFade({ children, delay, blur, yOffset, duration, once, className, }: BlurFadeProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the BorderBeam component. */
+interface BorderBeamProps {
+    /** Beam color. Default: `"hsl(var(--primary))"` */
+    color?: string;
+    /** Tail fade color. Default: `"transparent"` */
+    colorFrom?: string;
+    /** Animation cycle duration in seconds. Default: `6` */
+    duration?: number;
+    /** Beam length in pixels. Default: `150` */
+    size?: number;
+    /** Border radius to follow (CSS value). Default: `"inherit"` */
+    borderRadius?: string;
+    /** Additional class names. */
     className?: string;
-}): JSX.Element | null;
+}
+/**
+ * Glowing beam that orbits the border of its parent container.
+ *
+ * - Place inside a `position: relative; overflow: hidden` parent
+ * - CSS-only animation (no JS animation loop)
+ * - Renders nothing when reduced motion is preferred
+ *
+ * @component
+ * @package ui
+ */
+declare function BorderBeam({ color, colorFrom, duration, size, borderRadius, className, }: BorderBeamProps): react_jsx_runtime.JSX.Element | null;
+
+/** Props for the Compare component. */
+interface CompareProps {
+    /** Content shown on the left (before) side. */
+    before: ReactNode;
+    /** Content shown on the right (after) side. */
+    after: ReactNode;
+    /** Label for the before side. */
+    beforeLabel?: string;
+    /** Label for the after side. */
+    afterLabel?: string;
+    /** Initial divider position as percentage (0–100). Default: `50` */
+    initialPosition?: number;
+    /** CSS aspect-ratio for the container. Default: `"16/9"` */
+    aspectRatio?: string;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Draggable before/after comparison slider.
+ *
+ * - Pointer-based dragging (works on mouse and touch)
+ * - Optional before/after labels
+ * - Content is clipped, not resized
+ * - Fully accessible with keyboard support
+ *
+ * @component
+ * @package ui
+ */
+declare function Compare({ before, after, beforeLabel, afterLabel, initialPosition, aspectRatio, className, }: CompareProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the Confetti component. */
+interface ConfettiProps {
+    /** Whether the confetti burst is active. */
+    active: boolean;
+    /** Number of confetti particles. Default: `40` */
+    count?: number;
+    /** Array of CSS colors for particles. */
+    colors?: string[];
+    /** Duration in milliseconds before auto-cleanup. Default: `3000` */
+    duration?: number;
+    /** Callback when animation completes. */
+    onComplete?: () => void;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Confetti burst animation overlay.
+ *
+ * - CSS-only particles with randomized trajectories
+ * - Fires once when `active` becomes `true`
+ * - Calls `onComplete` when the animation finishes
+ * - Renders nothing when reduced motion is preferred
+ *
+ * @component
+ * @package ui
+ */
+declare function Confetti({ active, count, colors, duration, onComplete, className, }: ConfettiProps): react_jsx_runtime.JSX.Element | null;
+
+/** Props for the Countdown component. */
+interface CountdownProps {
+    /** Number of days remaining. */
+    days: number;
+    /** Number of hours remaining (0–23). */
+    hours: number;
+    /** Number of minutes remaining (0–59). */
+    minutes: number;
+    /** Number of seconds remaining (0–59). */
+    seconds: number;
+    /** Show the labels below each box. Default: `true` */
+    showLabels?: boolean;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Countdown display with segmented boxes for each time unit.
+ *
+ * @component
+ * @package ui
+ */
+declare function Countdown({ days, hours, minutes, seconds, showLabels, className, }: CountdownProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the SafariMock component. */
+interface SafariMockProps {
+    /** Content to display inside the browser frame. */
+    children: ReactNode;
+    /** URL text shown in the address bar. Default: `"https://example.com"` */
+    url?: string;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Safari-style browser frame for wrapping screenshots.
+ *
+ * - CSS-only traffic lights (red/yellow/green dots)
+ * - Address bar with optional URL text
+ * - Rounded corners matching macOS window chrome
+ *
+ * @component
+ * @package ui
+ */
+declare function SafariMock({ children, url, className, }: SafariMockProps): react_jsx_runtime.JSX.Element;
+/** Props for the IPhoneMock component. */
+interface IPhoneMockProps {
+    /** Content to display inside the phone frame. */
+    children: ReactNode;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * iPhone-style device frame for wrapping mobile screenshots.
+ *
+ * - CSS-only frame with rounded corners and notch
+ * - Status bar with time and signal indicators
+ * - Aspect ratio matches iPhone 15 Pro proportions
+ *
+ * @component
+ * @package ui
+ */
+declare function IPhoneMock({ children, className, }: IPhoneMockProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the Dock container. */
+interface DockProps extends SaasflareComponentProps {
+    /** Dock items. */
+    children: ReactNode;
+    /** Maximum scale factor for magnified items. Default: `1.5` */
+    magnification?: number;
+    /** Mouse proximity distance in pixels that triggers magnification. Default: `100` */
+    distance?: number;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Horizontal dock bar with proximity-based item magnification.
+ *
+ * - Items scale up as the mouse approaches them
+ * - Uses spring physics for smooth, elastic scaling
+ * - Falls back to a static icon bar when reduced motion is preferred
+ * - Tracks mouse X position across the entire dock
+ *
+ * @component
+ * @package ui
+ */
+declare function Dock({ children, magnification, distance, className, surface, radius, animated, }: DockProps): react_jsx_runtime.JSX.Element;
+/** Props for a DockItem. */
+interface DockItemProps {
+    /** Icon or content inside the dock item. */
+    children: ReactNode;
+    /** Tooltip label for the item. */
+    label: string;
+    /** Click handler. */
+    onClick?: () => void;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Individual item within a Dock.
+ *
+ * - Magnifies based on mouse proximity using spring interpolation
+ * - Shows a tooltip label on hover
+ * - Renders at static base size when reduced motion is preferred
+ *
+ * @component
+ * @package ui
+ */
+declare function DockItem({ children, label, onClick, className, }: DockItemProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the FeatureCard component. */
+interface FeatureCardProps extends SaasflareComponentProps {
+    /** Icon element displayed at the top. */
+    icon?: ReactNode;
+    /** Feature title. */
+    title: string;
+    /** Feature description text. */
+    description: string;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Feature card with icon, title, and description.
+ *
+ * @component
+ * @package ui
+ */
+declare function FeatureCard({ icon, title, description, className, surface, radius, animated, }: FeatureCardProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the FlipWords component. */
+interface FlipWordsProps {
+    /** Array of words to cycle through. */
+    words: string[];
+    /** Cycle interval in milliseconds. Default: `2500` */
+    interval?: number;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Inline word rotator with vertical flip animation.
+ *
+ * - Words flip upward with a spring transition
+ * - Container width matches the longest word to prevent layout shifts
+ * - Falls back to showing the first word statically when reduced motion is preferred
+ * - Renders inline, so it can be placed mid-sentence
+ *
+ * @component
+ * @package ui
+ */
+declare function FlipWords({ words, interval, className, }: FlipWordsProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the GalleryLightbox component. */
+interface GalleryLightboxProps {
+    /** Array of image URLs. */
+    images: string[];
+    /** Whether the lightbox is open. */
+    open: boolean;
+    /** Current image index. */
+    index: number;
+    /** Called when the lightbox should close. */
+    onClose: () => void;
+    /** Called when the index changes. */
+    onIndexChange: (index: number) => void;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Fullscreen image lightbox with keyboard navigation.
+ *
+ * @component
+ * @package ui
+ */
+declare function GalleryLightbox({ images, open, index, onClose, onIndexChange, className, }: GalleryLightboxProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the GlowingEffect component. */
+interface GlowingEffectProps {
+    /** Glow color. Default: `"hsl(var(--primary))"` */
+    color?: string;
+    /** Glow spread diameter in pixels. Default: `150` */
+    spread?: number;
+    /** Blur radius in pixels. Default: `20` */
+    blur?: number;
+    /** Glow opacity (0–1). Default: `0.4` */
+    opacity?: number;
+    /** Border radius to match parent (CSS value). Default: `"inherit"` */
+    borderRadius?: string;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Mouse-following glow effect for container borders.
+ *
+ * - Tracks mouse position and renders a radial gradient at cursor
+ * - Only glows along the border (uses inset mask to hollow out center)
+ * - Fades out when the mouse leaves
+ * - Renders nothing when reduced motion is preferred
+ *
+ * @component
+ * @package ui
+ */
+declare function GlowingEffect({ color, spread, blur, opacity, borderRadius, className, }: GlowingEffectProps): react_jsx_runtime.JSX.Element | null;
+
+/** Props for the GradientText component. */
+interface GradientTextProps {
+    /** Text content to apply the gradient to. */
+    children: ReactNode;
+    /** Gradient color stops. Default: primary → chart-1 → chart-2 tokens */
+    colors?: string[];
+    /** Whether to animate the gradient position. Default: `true` */
+    animate?: boolean;
+    /** Animation cycle duration in seconds. Default: `6` */
+    speed?: number;
+    /** Gradient direction in degrees. Default: `90` */
+    angle?: number;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Text with a vibrant gradient fill, optionally animated.
+ *
+ * - Uses `background-clip: text` for the gradient effect
+ * - Animates via CSS `@keyframes` (no JS frames)
+ * - Falls back to primary color when reduced motion is preferred
+ * - Renders as an inline `<span>` to nest inside any heading or paragraph
+ *
+ * @component
+ * @package ui
+ */
+declare function GradientText({ children, colors, animate, speed, angle, className, }: GradientTextProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the HeroVideoDialog component. */
+interface HeroVideoDialogProps {
+    /** Video embed URL (YouTube/Vimeo embed or direct video URL). */
+    videoSrc: string;
+    /** Poster thumbnail image URL. */
+    thumbnailSrc: string;
+    /** Alt text for the thumbnail image. */
+    thumbnailAlt: string;
+    /** CSS aspect-ratio for the thumbnail. Default: `"16/9"` */
+    aspectRatio?: string;
+    /** Additional class names for the container. */
+    className?: string;
+}
+/**
+ * Hero video section with click-to-play dialog.
+ *
+ * - Shows a thumbnail with a centered play button
+ * - Opens a modal dialog with the embedded video on click
+ * - Animated with spring physics (scale + fade)
+ * - Accessible: focus management, keyboard close, aria labels
+ *
+ * @component
+ * @package ui
+ */
+declare function HeroVideoDialog({ videoSrc, thumbnailSrc, thumbnailAlt, aspectRatio, className, }: HeroVideoDialogProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the Hotspot container. */
+interface HotspotProps {
+    /** Background content (image, illustration, etc.) plus HotspotMarker children. */
+    children: ReactNode;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Container for positioned hotspot markers.
+ *
+ * @component
+ * @package ui
+ */
+declare function Hotspot({ children, className }: HotspotProps): react_jsx_runtime.JSX.Element;
+/** Props for a HotspotMarker. */
+interface HotspotMarkerProps {
+    /** Horizontal position as percentage (0–100). */
+    x: number;
+    /** Vertical position as percentage (0–100). */
+    y: number;
+    /** Tooltip label text. */
+    label: string;
+    /** Detailed description shown in the tooltip. */
+    description?: string;
+    /** Marker dot color. Default: `"hsl(var(--primary))"` */
+    color?: string;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Pulsing dot marker with hover tooltip at an absolute position.
+ *
+ * @component
+ * @package ui
+ */
+declare function HotspotMarker({ x, y, label, description, color, className, }: HotspotMarkerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * @fileoverview Image that swaps to an alternate source on hover.
+ * @author Saasflare™
+ * Crossfades between a primary and alternate image on mouse hover.
+ * @module packages/ui/components/ui/image-swap-hover
+ * @package ui
+ *
+ * @component
+ * @example
+ * import { ImageSwapHover } from '@saasflare/ui';
+ * <ImageSwapHover
+ *   src="/product-front.jpg"
+ *   hoverSrc="/product-back.jpg"
+ *   alt="Product view"
+ * />
+ */
+/** Props for the ImageSwapHover component. */
+interface ImageSwapHoverProps {
+    /** Default image source. */
+    src: string;
+    /** Image source to show on hover. */
+    hoverSrc: string;
+    /** Alt text for both images. */
+    alt: string;
+    /** CSS aspect-ratio. Default: `"1/1"` */
+    aspectRatio?: string;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Image that crossfades to an alternate source on hover.
+ *
+ * @component
+ * @package ui
+ */
+declare function ImageSwapHover({ src, hoverSrc, alt, aspectRatio, className, }: ImageSwapHoverProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the Marquee component. */
+interface MarqueeProps {
+    /** Items to scroll infinitely. */
+    children: ReactNode;
+    /** Reverse scroll direction. Default: `false` */
+    reverse?: boolean;
+    /** Scroll duration in seconds for one full cycle. Default: `40` */
+    speed?: number;
+    /** Pause scrolling on hover. Default: `true` */
+    pauseOnHover?: boolean;
+    /** Gap between items in pixels. Default: `48` */
+    gap?: number;
+    /** Number of times to duplicate the content strip. Default: `2` */
+    repeat?: number;
+    /** Enable vertical scrolling instead of horizontal. Default: `false` */
+    vertical?: boolean;
+    /** Additional class names for the container. */
+    className?: string;
+}
+/**
+ * Infinite-scrolling content ticker.
+ *
+ * - Pure CSS animation (no JS frames, no Framer Motion overhead)
+ * - Duplicates children to create a seamless loop
+ * - Pauses on hover for readability (configurable)
+ * - Falls back to static flex row when reduced motion is preferred
+ *
+ * @component
+ * @package ui
+ */
+declare function Marquee({ children, reverse, speed, pauseOnHover, gap, repeat, vertical, className, }: MarqueeProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the MouseGradientBlob component. */
+interface MouseGradientBlobProps {
+    /** Diameter of the blob in pixels. Default: `500` */
+    size?: number;
+    /** Gradient color stops. Default: primary + chart-2 tokens */
+    colors?: [string, string];
+    /** Opacity of the blob (0–1). Default: `0.15` */
+    opacity?: number;
+    /** Blur radius in pixels. Default: `80` */
+    blur?: number;
+    /** Additional class names for the container */
+    className?: string;
+}
+/**
+ * Ambient gradient blob that follows the mouse.
+ *
+ * - Uses spring physics for smooth, organic motion
+ * - Fades out when the mouse leaves the container
+ * - Renders nothing when reduced motion is preferred
+ * - Uses `pointer-events: none` so it never blocks interaction
+ *
+ * @component
+ * @package ui
+ */
+declare function MouseGradientBlob({ size, colors, opacity, blur, className, }: MouseGradientBlobProps): react_jsx_runtime.JSX.Element | null;
+
+/** Props for the MovingBorder component. */
+interface MovingBorderProps {
+    /** Content inside the border. */
+    children: ReactNode;
+    /** Gradient colors for the rotating border. */
+    colors?: string[];
+    /** Rotation cycle duration in seconds. Default: `6` */
+    duration?: number;
+    /** Border width in pixels. Default: `1.5` */
+    borderWidth?: number;
+    /** Border radius (CSS value). Default: `"0.75rem"` */
+    borderRadius?: string;
+    /** Additional class names for the outer wrapper. */
+    className?: string;
+}
+/**
+ * Wrapper with a continuously rotating gradient border.
+ *
+ * - Uses a conic-gradient that rotates via CSS animation
+ * - Inner content sits on top with a solid background
+ * - Renders a static border when reduced motion is preferred
+ * - Works on any element (buttons, cards, containers)
+ *
+ * @component
+ * @package ui
+ */
+declare function MovingBorder({ children, colors, duration, borderWidth, borderRadius, className, }: MovingBorderProps): react_jsx_runtime.JSX.Element;
+
+/** Animation variant presets for page transitions. */
+declare const VARIANTS: {
+    readonly fade: {
+        readonly initial: {
+            readonly opacity: 0;
+        };
+        readonly animate: {
+            readonly opacity: 1;
+        };
+        readonly exit: {
+            readonly opacity: 0;
+        };
+    };
+    readonly slideUp: {
+        readonly initial: {
+            readonly opacity: 0;
+            readonly y: 16;
+        };
+        readonly animate: {
+            readonly opacity: 1;
+            readonly y: 0;
+        };
+        readonly exit: {
+            readonly opacity: 0;
+            readonly y: -16;
+        };
+    };
+    readonly slideDown: {
+        readonly initial: {
+            readonly opacity: 0;
+            readonly y: -16;
+        };
+        readonly animate: {
+            readonly opacity: 1;
+            readonly y: 0;
+        };
+        readonly exit: {
+            readonly opacity: 0;
+            readonly y: 16;
+        };
+    };
+    readonly scale: {
+        readonly initial: {
+            readonly opacity: 0;
+            readonly scale: 0.96;
+        };
+        readonly animate: {
+            readonly opacity: 1;
+            readonly scale: 1;
+        };
+        readonly exit: {
+            readonly opacity: 0;
+            readonly scale: 0.96;
+        };
+    };
+};
+/** Props for the PageTransition component. */
+interface PageTransitionProps {
+    /** Child content to animate. */
+    children: ReactNode;
+    /** Animation preset. Default: `"fade"` */
+    variant?: keyof typeof VARIANTS;
+    /** Transition duration in seconds. Default: `0.3` */
+    duration?: number;
+    /** Unique key for AnimatePresence (use pathname). Default: none */
+    transitionKey?: string;
+    /** Additional class names for the motion wrapper. */
+    className?: string;
+}
+/**
+ * Page transition wrapper with configurable enter/exit animations.
+ *
+ * - Provides `fade`, `slideUp`, `slideDown`, and `scale` presets
+ * - Renders children directly (no animation) when reduced motion is preferred
+ * - Use `transitionKey` (typically the pathname) to trigger re-animation on route changes
+ *
+ * @component
+ * @package ui
+ */
+declare function PageTransition({ children, variant, duration, transitionKey, className, }: PageTransitionProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the ParallaxSection component. */
+interface ParallaxSectionProps {
+    /** Content to apply parallax to. */
+    children: ReactNode;
+    /** Parallax speed factor. 0 = fixed, 0.5 = half speed, 1 = no parallax. Default: `0.5` */
+    speed?: number;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Section wrapper that applies scroll-based parallax to its children.
+ *
+ * - Children translate vertically based on scroll position and speed factor
+ * - Falls back to static rendering when reduced motion is preferred
+ * - Overflow hidden to prevent content leaking during parallax
+ *
+ * @component
+ * @package ui
+ */
+declare function ParallaxSection({ children, speed, className, }: ParallaxSectionProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the ParticlesBackground component. */
+interface ParticlesBackgroundProps {
+    /** Number of particles. Default: `20` */
+    count?: number;
+    /** CSS color of particles. Default: `"hsl(var(--primary))"` */
+    color?: string;
+    /** Maximum particle diameter in pixels. Default: `4` */
+    maxSize?: number;
+    /** Minimum particle diameter in pixels. Default: `1` */
+    minSize?: number;
+    /** Maximum particle opacity (0–1). Default: `0.3` */
+    maxOpacity?: number;
+    /** Animation speed multiplier. Default: `1` */
+    speed?: number;
+    /** Additional class names for the container. */
+    className?: string;
+}
+/**
+ * Ambient floating particles background.
+ *
+ * - CSS-only animation (no JS animation loop, GPU-composited)
+ * - Deterministic positions (no layout shift between renders)
+ * - Renders nothing when reduced motion is preferred
+ * - Lightweight: no canvas, no WebGL
+ *
+ * @component
+ * @package ui
+ */
+declare function ParticlesBackground({ count, color, maxSize, minSize, maxOpacity, speed, className, }: ParticlesBackgroundProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * @fileoverview Perspective grid background with retro/cyberpunk aesthetic.
+ * @author Saasflare™
+ * A CSS-only perspective grid that fades toward the horizon. Ideal for
+ * hero sections and feature backgrounds.
+ * @module packages/ui/components/ui/retro-grid
+ * @package ui
+ *
+ * @component
+ * @example
+ * import { RetroGrid } from '@saasflare/ui';
+ * <div className="relative min-h-[500px]">
+ *   <RetroGrid />
+ *   <div className="relative z-10">Hero content</div>
+ * </div>
+ *
+ * @example
+ * // Custom grid color and size
+ * <RetroGrid gridColor="hsl(var(--primary))" gridSize={40} angle={70} />
+ */
+/** Props for the RetroGrid component. */
+interface RetroGridProps {
+    /** Grid line color. Default: `"hsl(var(--border))"` */
+    gridColor?: string;
+    /** Grid cell size in pixels. Default: `60` */
+    gridSize?: number;
+    /** Perspective tilt angle in degrees. Default: `65` */
+    angle?: number;
+    /** Grid line opacity (0–1). Default: `0.4` */
+    opacity?: number;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Perspective grid background with vanishing-point effect.
+ *
+ * - CSS-only (repeating linear gradients + perspective transform)
+ * - Fades to transparent at the horizon via mask-image
+ * - No JS, no canvas, no animation — pure visual
+ *
+ * @component
+ * @package ui
+ */
+declare function RetroGrid({ gridColor, gridSize, angle, opacity, className, }: RetroGridProps): react_jsx_runtime.JSX.Element;
+
+/** Direction the element slides in from. */
+type RevealDirection = "up" | "down" | "left" | "right" | "none";
+/** Props for the RevealOnScroll component. */
+interface RevealOnScrollProps {
+    /** Content to reveal. */
+    children: ReactNode;
+    /** Direction the element slides in from. Default: `"up"` */
+    direction?: RevealDirection;
+    /** Animation delay in seconds. Default: `0` */
+    delay?: number;
+    /** Intersection Observer root margin. Default: `"-80px"` */
+    rootMargin?: string;
+    /** Whether the animation triggers only once. Default: `true` */
+    once?: boolean;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Wrapper that animates children into view on scroll intersection.
+ *
+ * - Fades in with an optional directional slide
+ * - Uses a gentle spring for natural motion
+ * - Renders children statically when reduced motion is preferred
+ * - Triggers once by default (configurable via `once`)
+ *
+ * @component
+ * @package ui
+ */
+declare function RevealOnScroll({ children, direction, delay, rootMargin, once, className, }: RevealOnScrollProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the ShimmerButton component. */
+interface ShimmerButtonProps extends ComponentProps<"button"> {
+    /** Button content. */
+    children: ReactNode;
+    /** Color of the shimmer highlight. Default: `"rgba(255,255,255,0.2)"` */
+    shimmerColor?: string;
+    /** Shimmer cycle duration in seconds. Default: `2.5` */
+    speed?: number;
+    /** Background color. Default: `"hsl(var(--primary))"` */
+    background?: string;
+}
+/**
+ * CTA button with a continuously sweeping shimmer effect.
+ *
+ * - Diagonal light sweep loops infinitely
+ * - CSS-only animation (no JS frames)
+ * - Falls back to a static button when reduced motion is preferred
+ * - Inherits standard button props (onClick, disabled, etc.)
+ *
+ * @component
+ * @package ui
+ */
+declare function ShimmerButton({ children, shimmerColor, speed, background, className, ...props }: ShimmerButtonProps): react_jsx_runtime.JSX.Element;
+
+/** Supported social login providers. */
+type SocialProvider$1 = "google" | "apple" | "github" | "microsoft" | "twitter";
+/** Props for the SocialButton component. */
+interface SocialButtonProps extends Omit<ComponentProps<"button">, "children"> {
+    /** Social provider to render. */
+    provider: SocialProvider$1;
+    /** Override the default label text. */
+    label?: string;
+    /** Show only the icon (no text). Default: `false` */
+    iconOnly?: boolean;
+}
+/**
+ * Branded social login button. Visual only — no auth wiring.
+ *
+ * @component
+ * @package ui
+ */
+declare function SocialButton({ provider, label: labelOverride, iconOnly, className, ...props }: SocialButtonProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the SpotlightCard component. */
+interface SpotlightCardProps extends SaasflareComponentProps {
+    /** Card content. */
+    children: ReactNode;
+    /** Spotlight gradient color. Default: `"hsl(var(--primary))"` */
+    spotlightColor?: string;
+    /** Spotlight diameter in pixels. Default: `250` */
+    spotlightSize?: number;
+    /** Spotlight opacity (0–1). Default: `0.08` */
+    spotlightOpacity?: number;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Card with a radial gradient that follows the mouse cursor.
+ *
+ * - Gradient overlay tracks the mouse within the card boundaries
+ * - Fades out when the mouse leaves
+ * - Uses CSS for the gradient (no canvas, no heavy re-renders)
+ * - Falls back to a plain card when reduced motion is preferred
+ *
+ * @component
+ * @package ui
+ */
+declare function SpotlightCard({ children, spotlightColor, spotlightSize, spotlightOpacity, className, surface, radius, animated, }: SpotlightCardProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the StatCard component. */
+interface StatCardProps extends SaasflareComponentProps {
+    /** The stat value (e.g. "10K+", "99.9%", "$2.4M"). */
+    value: string;
+    /** Label describing the stat. */
+    label: string;
+    /** Optional icon displayed above the value. */
+    icon?: ReactNode;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Simple statistic display card for marketing sections.
+ *
+ * @component
+ * @package ui
+ */
+declare function StatCard({ value, label, icon, className, surface, radius, animated, }: StatCardProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the Steps container. */
+interface StepsProps {
+    /** Step children. */
+    children: ReactNode;
+    /** Index of the current active step (0-based). Default: `0` */
+    current?: number;
+    /** Layout direction. Default: `"horizontal"` */
+    direction?: "horizontal" | "vertical";
+    /** Additional class names. */
+    className?: string;
+}
+/** Props for an individual Step. */
+interface StepProps {
+    /** Step title text. */
+    title: string;
+    /** Optional description below the title. */
+    description?: string;
+    /** Optional icon to replace the step number. */
+    icon?: ReactNode;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Step sequence indicator with numbered circles and connector lines.
+ *
+ * @component
+ * @package ui
+ */
+declare function Steps({ children, current, direction, className, }: StepsProps): react_jsx_runtime.JSX.Element;
+/**
+ * Individual step within a Steps container.
+ * This component is a data carrier — it renders nothing on its own.
+ *
+ * @component
+ * @package ui
+ */
+declare function Step(_props: StepProps): null;
+
+/** A single item in the sticky scroll reveal. */
+interface StickyScrollItem {
+    /** Section title. */
+    title: string;
+    /** Section description text. */
+    description: string;
+    /** Visual content (image, component, etc.) shown in the right column. */
+    content?: ReactNode;
+}
+/** Props for the StickyScrollReveal component. */
+interface StickyScrollRevealProps {
+    /** Array of scroll items. */
+    items: StickyScrollItem[];
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Split layout with sticky left text and scrolling right content.
+ *
+ * - Left column text stays fixed during scroll
+ * - Right column content transitions between items
+ * - Each item fades in based on scroll position
+ * - Falls back to stacked layout when reduced motion is preferred
+ *
+ * @component
+ * @package ui
+ */
+declare function StickyScrollReveal({ items, className, }: StickyScrollRevealProps): react_jsx_runtime.JSX.Element;
+
+/** A social link entry. */
+interface SocialLink {
+    /** Accessible label for the link. */
+    label: string;
+    /** URL to the social profile. */
+    url: string;
+    /** Icon element. */
+    icon: ReactNode;
+}
+/** Props for the TeamCard component. */
+interface TeamCardProps extends SaasflareComponentProps {
+    /** Person's name. */
+    name: string;
+    /** Role or job title. */
+    role: string;
+    /** Photo URL. */
+    photo?: string;
+    /** Short bio text. */
+    bio?: string;
+    /** Social media links. */
+    socials?: SocialLink[];
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Team member card with photo, name, role, and social links.
+ *
+ * @component
+ * @package ui
+ */
+declare function TeamCard({ name, role, photo, bio, socials, className, surface, radius, animated, }: TeamCardProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the TestimonialCard component. */
+interface TestimonialCardProps extends SaasflareComponentProps {
+    /** The testimonial quote text. */
+    quote: string;
+    /** Name of the person. */
+    name: string;
+    /** Role/title of the person. */
+    role?: string;
+    /** Avatar image URL. */
+    avatar?: string;
+    /** Star rating (1–5). Omit to hide stars. */
+    rating?: 1 | 2 | 3 | 4 | 5;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Testimonial card with avatar, quote, attribution, and optional star rating.
+ *
+ * @component
+ * @package ui
+ */
+declare function TestimonialCard({ quote, name, role, avatar, rating, className, surface, radius, animated, }: TestimonialCardProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the TextGenerateEffect component. */
+interface TextGenerateEffectProps {
+    /** Text string to animate word by word. */
+    text: string;
+    /** Delay between each word in seconds. Default: `0.05` */
+    stagger?: number;
+    /** Duration per word fade-in in seconds. Default: `0.4` */
+    duration?: number;
+    /** Whether animation triggers only once. Default: `true` */
+    once?: boolean;
+    /** HTML element to render. Default: `"p"` */
+    as?: "p" | "h1" | "h2" | "h3" | "h4" | "span";
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Text that reveals word by word with staggered fade-in.
+ *
+ * - Each word fades from transparent to opaque sequentially
+ * - Triggers when the element scrolls into view
+ * - Renders full text immediately when reduced motion is preferred
+ * - Preserves natural text wrapping and spacing
+ *
+ * @component
+ * @package ui
+ */
+declare function TextGenerateEffect({ text, stagger, duration, once, as: Tag, className, }: TextGenerateEffectProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the Timeline container. */
+interface TimelineProps {
+    /** TimelineItem children. */
+    children: ReactNode;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Vertical timeline with a scroll-driven progress beam.
+ *
+ * - Beam fills as the user scrolls through the timeline
+ * - Each item fades in on scroll intersection
+ * - Falls back to a static timeline when reduced motion is preferred
+ *
+ * @component
+ * @package ui
+ */
+declare function Timeline({ children, className }: TimelineProps): react_jsx_runtime.JSX.Element;
+/** Props for a TimelineItem. */
+interface TimelineItemProps {
+    /** Item title. */
+    title: string;
+    /** Date or time label. */
+    date?: string;
+    /** Item content/description. */
+    children: ReactNode;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Individual item within a Timeline.
+ *
+ * - Positioned alternating left/right on desktop, left-aligned on mobile
+ * - Dot indicator on the timeline track
+ * - Fades in when scrolled into view
+ *
+ * @component
+ * @package ui
+ */
+declare function TimelineItem({ title, date, children, className, }: TimelineItemProps): react_jsx_runtime.JSX.Element;
+
+/** Props for the TracingBeam component. */
+interface TracingBeamProps {
+    /** Content alongside the beam. */
+    children: ReactNode;
+    /** Beam color. Default: `"hsl(var(--primary))"` */
+    color?: string;
+    /** Track (background line) color. Default: `"hsl(var(--border))"` */
+    trackColor?: string;
+    /** Additional class names. */
+    className?: string;
+}
+/**
+ * Vertical scroll-progress beam alongside content.
+ *
+ * - Fills from top to bottom as the user scrolls
+ * - Renders on the left side with content offset
+ * - Includes a dot indicator at the current scroll position
+ * - Falls back to a simple left border when reduced motion is preferred
+ *
+ * @component
+ * @package ui
+ */
+declare function TracingBeam({ children, color, trackColor, className, }: TracingBeamProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for the ScrollToTopButton component.
+ *
+ * @interface
+ * @package ui
+ */
+interface ScrollToTopButtonProps extends SaasflareComponentProps {
+    /**
+     * Optional scroll container element ID.
+     * If not provided, falls back to the global `window`.
+     */
+    scrollContainerId?: string;
+    /**
+     * Vertical scroll offset (in pixels) after which the button is shown.
+     * @default 300
+     */
+    scrollOffset?: number;
+    /** Additional class names merged onto the root button. */
+    className?: string;
+}
+/**
+ * A floating button that appears after scrolling down and smoothly scrolls
+ * the user back to the top of the container (or window).
+ *
+ * @component
+ */
+declare function ScrollToTopButton({ scrollContainerId, scrollOffset, className, ...sfProps }: ScrollToTopButtonProps): JSX.Element;
+
+/**
+ * Props for {@link StatefulButton}. Extends {@link ButtonProps} with two
+ * orthogonal stateful concerns. `asChild` is intentionally excluded — a
+ * Slot-rendered button cannot own its own DOM children, so the spinner /
+ * loading-text swap would be ambiguous.
+ */
+interface StatefulButtonProps extends Omit<ButtonProps, "asChild"> {
+    /** Pending state: forces disabled, shows spinner, swaps label when `loadingText` is set. */
+    loading?: boolean;
+    /** Optional label to show in place of children while `loading` is true. */
+    loadingText?: React$1.ReactNode;
+}
+/**
+ * Button with built-in loading state.
+ *
+ * `loading` is the single source of truth for pending UI:
+ *   - sets `disabled` (forwarded to native button)
+ *   - sets `aria-busy="true"` for assistive tech
+ *   - prepends an animated spinner before the label
+ *   - replaces `children` with `loadingText` if provided (otherwise label stays)
+ *
+ * @component
+ * @layer composed
+ *
+ * @param {boolean} loading - Pending state.
+ * @param {React.ReactNode} loadingText - Optional override label while loading.
+ * @param disabled
+ * @param children
+ * @param rest
+ */
+declare function StatefulButton({ loading, loadingText, disabled, children, ...rest }: StatefulButtonProps): react_jsx_runtime.JSX.Element;
+
+declare const PROVIDERS: readonly ["google", "github", "apple", "microsoft", "x", "discord", "facebook", "linkedin", "medium", "slack", "reddit", "paypal", "stripe", "gitlab", "dribbble", "tiktok"];
+type SocialProvider = (typeof PROVIDERS)[number];
+/**
+ * Props for {@link SocialAuthButton}. Inherits {@link StatefulButtonProps},
+ * but widens `iconWeight` to {@link BrandIconWeight} so the colored brand
+ * variant can be requested per-instance.
+ *
+ * The visible label is resolved with the precedence:
+ *   `children` > `label` > `"Continue with {Provider}"`
+ */
+interface SocialAuthButtonProps extends Omit<StatefulButtonProps, "iconWeight"> {
+    /** Identity provider — drives icon and default label. */
+    provider: SocialProvider;
+    /** Override the visible label. Default: "Continue with {Provider}". */
+    label?: React$1.ReactNode;
+    /**
+     * Icon weight. Accepts the four Phosphor weights (theme-aware via the
+     * Saasflare provider chain) plus the brand-locked `"colorful"` variant.
+     */
+    iconWeight?: BrandIconWeight;
+}
+/**
+ * Generic provider-branded auth button.
+ *
+ * Defaults: `variant="outline"` `intent="neutral"`.
+ *
+ * The Phosphor weights (`regular | bold | fill | duotone`) inherit from
+ * `<SaasflareProvider iconWeight="…">` via {@link useSaasflareProps}; the
+ * `colorful` weight is opt-in per-instance and bypasses the provider chain
+ * because brand colors are not themable.
+ *
+ * @component
+ * @layer brand
+ */
+declare function SocialAuthButton({ provider, label, variant, intent, fullWidth, surface, radius, animated, iconWeight, children, ...rest }: SocialAuthButtonProps): react_jsx_runtime.JSX.Element;
+type ProviderShortcutProps = Omit<SocialAuthButtonProps, "provider">;
+declare const GoogleAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const GitHubAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const AppleAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const MicrosoftAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const XAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const DiscordAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const FacebookAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const LinkedInAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const MediumAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const SlackAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const RedditAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const PayPalAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const StripeAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const GitLabAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const DribbbleAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+declare const TikTokAuthButton: (props: ProviderShortcutProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Theme mode toggle button with Sun/Moon icons.
+ *
+ * @component
+ * @layer core
+ *
+ * @param {object} props - Component props
+ * @param {boolean} [props.showText=false] - Whether to show the label text visibly
+ * @param {string} [props.textLight] - Label shown while in light mode (prompting switch to dark)
+ * @param {string} [props.textDark] - Label shown while in dark mode (prompting switch to light)
+ * @param {string} [props.className] - Additional CSS class names
+ * @returns {JSX.Element | null} The toggle button, or null before hydration
+ */
+interface ThemeModeToggleProps extends SaasflareComponentProps {
+    /** Whether to show the label text visibly. */
+    showText?: boolean;
+    /** Label shown while in light mode (prompting switch to dark). */
+    textLight?: string;
+    /** Label shown while in dark mode (prompting switch to light). */
+    textDark?: string;
+    /** Additional CSS class names. */
+    className?: string;
+    /**
+     * SSR-known resolved theme (`"dark"` or `"light"`) — typically read from a
+     * cookie in the parent server component. When provided, the button skips
+     * its internal mount-gate and renders the correct sun/moon glyph on the
+     * very first paint, eliminating the brief blank frame caused by
+     * `next-themes` returning `undefined` during SSR.
+     *
+     * Leave undefined for the legacy mount-gated behaviour.
+     */
+    initialResolvedTheme?: 'light' | 'dark';
+}
+declare function ThemeModeToggle({ showText, textLight, textDark, className, surface, radius, animated, iconWeight, initialResolvedTheme, }: ThemeModeToggleProps): JSX.Element | null;
+
+/**
+ * @fileoverview Three-segment theme toggle (light / dark / system).
+ *
+ * Pill-shaped segmented control with Sun, Moon, and Monitor icons. Built on
+ * the design-system `ToggleGroup` primitive (Pattern B — CSS-motion).
+ *
+ * Three appearances:
+ *   - `"icon"` (default) — segments are small circles floating inside the
+ *     rail. The active segment is filled with `--background` and a subtle
+ *     ring. Segment shape is always pill, independent of the rail's
+ *     `radius`.
+ *   - `"icon-inherit"` — same compact icon footprint as `"icon"`, but each
+ *     segment's border-radius matches the rail's `radius`. Use this when
+ *     `radius="sharp"` should propagate to the segments too.
+ *   - `"button"` — segments fill the rail end-to-end. The active segment
+ *     matches the rail's outer corner radius on its outer edge and stays
+ *     flat on its inner edge so it slots cleanly into the rail.
+ *
+ * The `radius` prop drives the rail's outer border-radius. Default is
+ * `"pill"` (`rounded-full`). Override with `radius="sharp" | "soft" |
+ * "rounded" | "pill"` — segment corners adapt automatically in
+ * `"icon-inherit"` and `"button"` appearances.
+ *
+ * Supports `next-themes` natively. Renders `null` until hydrated to avoid
+ * SSR/CSR mismatch on the active segment. When the System segment is
+ * active, its `title` reflects the OS-resolved theme (e.g.
+ * "System mode (currently dark)") so users see what their preference
+ * resolves to.
+ *
+ * @module packages/ui/components/composed/theme-mode-multi-toggle
+ * @package ui
+ *
+ * @component
+ * @example
+ * import { ThemeModeMultiToggle } from '@saasflare/ui';
+ * <ThemeModeMultiToggle />
+ *
+ * @example
+ * // Inherit-radius icons (segments adopt the rail's radius)
+ * <ThemeModeMultiToggle appearance="icon-inherit" radius="sharp" />
+ *
+ * @example
+ * // Button appearance with rounded geometry
+ * <ThemeModeMultiToggle appearance="button" radius="rounded" />
+ */
+
+/** Available theme modes — mirrors next-themes' `theme` prop. */
+type ThemeMode = "light" | "dark" | "system";
+/** Visual appearance of the segments. */
+type ThemeModeMultiToggleAppearance = "icon" | "icon-inherit" | "button";
+interface ThemeModeMultiToggleProps extends SaasflareComponentProps {
+    /** Override the default screen-reader labels per segment. */
+    labels?: Partial<Record<ThemeMode, string>>;
+    /** Additional class names applied to the rail. */
+    className?: string;
+    /** Segment size — matches the Toggle/ToggleGroup `size` axis. */
+    size?: "sm" | "default" | "lg";
+    /**
+     * Visual appearance of the segments.
+     *
+     * - `"icon"` (default): small floating circles, always pill.
+     * - `"icon-inherit"`: small floating shapes that match the rail's `radius`.
+     * - `"button"`: segments fill the rail; outer corners match the rail's
+     *   `radius`, inner corners stay flat so the segment slots in.
+     *
+     * @default "icon"
+     */
+    appearance?: ThemeModeMultiToggleAppearance;
+    /**
+     * SSR-known theme mode (typically read from a cookie in the parent server
+     * component). When provided, the component skips its internal mount-gate
+     * and renders the matching segment as active on the very first paint —
+     * eliminating the brief invisible / wrong-segment frame caused by
+     * `next-themes` returning `undefined` during SSR.
+     *
+     * Leave undefined for the legacy mount-gated behaviour (renders `null`
+     * until mounted).
+     */
+    initialMode?: ThemeMode;
+}
+/**
+ * Three-segment theme switcher (light / dark / system).
+ *
+ * @component
+ * @layer ui
+ */
+declare function ThemeModeMultiToggle({ labels, className, size, appearance, surface, radius, animated, iconWeight, initialMode, }: ThemeModeMultiToggleProps): React$1.JSX.Element | null;
 
 /**
  * Props for the TopLoadingBar component.
@@ -1739,4 +3811,4 @@ interface UserAvatarProps {
  */
 declare function UserAvatar({ src, name, initials, size, className }: UserAvatarProps): react_jsx_runtime.JSX.Element;
 
-export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, type AlertProps, AlertTitle, AnimatedTooltip, AspectRatio, Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage, Badge, type BadgeProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, Collapsible, CollapsibleContent, CollapsibleTrigger, Combobox, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxInput, ComboboxItem, ComboboxList, ComboboxSeparator, ComboboxTrigger, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, DataToolbar, DataToolbarActions, DataToolbarFilters, DataToolbarSearch, type Density, DirectionProvider, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyState, type EmptyStateProps, EmptyTitle, Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, HoverCard, HoverCardContent, HoverCardTrigger, Icons, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, Intent, Item, ItemActions, ItemContent, ItemDescription, ItemFooter, ItemGroup, ItemHeader, ItemMedia, ItemSeparator, ItemTitle, Kbd, KbdGroup, Label, type Measurement, Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger, MetricCard, type MetricCardProps, type MetricTrend, NativeSelect, NativeSelectOptGroup, NativeSelectOption, NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, PageHeader, type PageHeaderProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, type PaginationRangeItem, Palette, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, PricingCard, type PricingCardProps, Progress, RadioGroup, RadioGroupItem, Radius, RadiusProp, SaasflareComponentProps, type SaasflareMotion, SaasflareProvider, type SaasflareProviderProps, SaasflareScript, type SaasflareScriptProps, SaasflareShell, type SaasflareShellProps, ScrollArea, ScrollBar, ScrollToTopButton, SearchField, type SearchFieldProps, SectionCard, type SectionCardProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, SettingsSection, type SettingsSectionProps, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, type Size, Skeleton, Slider, SmoothScrollProvider, type SmoothScrollProviderProps, Spinner, StyleVariant, Surface, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, ThemeModeToggle, Toaster, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, type TooltipItem, TooltipProvider, TooltipTrigger, TopLoadingBar, type TopLoadingBarProps, TypewriterText, type UseDisclosureOptions, type UseDisclosureReturn, type UseMeasureReturn, type UsePaginationOptions, type UsePaginationReturn, UserAvatar, type UserAvatarProps, badgeVariants, buttonGroupVariants, cn, fadeIn, navigationMenuTriggerStyle, noMotion, scaleIn, slideDown, slideUp, spring, springBouncy, springGentle, springStiff, toggleVariants, useAnimation, useDirection, useDisclosure, useFormField, useIsMobile, useMeasure, usePagination, useReducedMotion, useSaasflareMotion, useSaasflareTheme, useSidebar };
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, type AlertProps, AlertTitle, AnimatedTooltip, AppleAuthButton, ArrowLeftIcon, ArrowRightIcon, ArrowUpIcon, AspectRatio, AudioPlayer, type AudioPlayerProps, AuroraBackground, type AuroraBackgroundProps, Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage, Badge, type BadgeProps, BarList, type BarListItem, type BarListProps, BentoGrid, BentoGridItem, type BentoGridItemProps, type BentoGridProps, BlurFade, type BlurFadeProps, BorderBeam, type BorderBeamProps, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText, ButtonProps, Callout, type CalloutIntent, type CalloutProps, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CaretDownIcon, CaretLeftIcon, CaretRightIcon, CaretUpIcon, CategoryBar, type CategoryBarProps, type CategoryBarSegment, CheckCircleIcon, CheckIcon, Checkbox, CircleIcon, CircleNotchIcon, CodeBlock, type CodeBlockProps, Collapsible, CollapsibleContent, CollapsibleTrigger, Combobox, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxInput, ComboboxItem, ComboboxList, ComboboxSeparator, ComboboxTrigger, Compare, type CompareProps, Confetti, type ConfettiProps, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, Countdown, type CountdownProps, type CountdownValue, DataToolbar, DataToolbarActions, DataToolbarFilters, DataToolbarSearch, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, type Density, DirectionProvider, DiscordAuthButton, Dock, DockItem, type DockItemProps, type DockProps, DotsSixVerticalIcon, DotsThreeIcon, DribbbleAuthButton, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Dropzone, type DropzoneProps, type DropzoneRejection, type DropzoneRejectionReason, Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyState, type EmptyStateProps, EmptyTitle, FacebookAuthButton, FeatureCard, type FeatureCardProps, Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle, FlipWords, type FlipWordsProps, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, GalleryLightbox, type GalleryLightboxProps, GitHubAuthButton, GitLabAuthButton, GlowingEffect, type GlowingEffectProps, GoogleAuthButton, GradientText, type GradientTextProps, HeroVideoDialog, type HeroVideoDialogProps, Hotspot, HotspotMarker, type HotspotMarkerProps, type HotspotProps, HoverCard, HoverCardContent, HoverCardTrigger, IPhoneMock, type IPhoneMockProps, IconWeight, Icons, ImageSwapHover, type ImageSwapHoverProps, InfoIcon, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, Intent, Item, ItemActions, ItemContent, ItemDescription, ItemFooter, ItemGroup, ItemHeader, ItemMedia, ItemSeparator, ItemTitle, Kbd, KbdGroup, Label, LinkedInAuthButton, MagnifyingGlassIcon, Marquee, type MarqueeProps, type Measurement, MediumAuthButton, Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger, MetricCard, type MetricCardProps, type MetricTrend, MicrosoftAuthButton, MinusIcon, MonitorIcon, MoonIcon, MouseGradientBlob, type MouseGradientBlobProps, MovingBorder, type MovingBorderProps, NativeSelect, NativeSelectOptGroup, NativeSelectOption, NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, NotificationCenter, type NotificationCenterProps, type NotificationItem, NumberInput, type NumberInputProps, PageHeader, type PageHeaderProps, PageTransition, type PageTransitionProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, type PaginationRangeItem, Palette, ParallaxSection, type ParallaxSectionProps, ParticlesBackground, type ParticlesBackgroundProps, PauseIcon, PayPalAuthButton, PhosphorIconProps, PlayIcon, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, type PossibleRef, PricingCard, type PricingCardProps, Progress, ProgressCircle, type ProgressCircleProps, type ProgressCircleSize, QuotesIcon, RadioGroup, RadioGroupItem, Radius, RadiusProp, Rating, type RatingProps, type RatingSize, RedditAuthButton, RetroGrid, type RetroGridProps, RevealOnScroll, type RevealOnScrollProps, PROVIDERS as SOCIAL_AUTH_PROVIDERS, SaasflareComponentProps, type SaasflareMotion, SaasflareProvider, type SaasflareProviderProps, SaasflareScript, type SaasflareScriptProps, SaasflareShell, type SaasflareShellProps, SafariMock, type SafariMockProps, ScrollArea, ScrollBar, ScrollToTopButton, SearchField, type SearchFieldProps, SectionCard, type SectionCardProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, SettingsSection, type SettingsSectionProps, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, ShimmerButton, type ShimmerButtonProps, Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarSimpleIcon, SidebarTrigger, type Size, Skeleton, SlackAuthButton, Slider, SmoothScrollProvider, type SmoothScrollProviderProps, SocialAuthButton, type SocialAuthButtonProps, SocialButton, type SocialButtonProps, type SocialLink, type SocialProvider, SparkChart, type SparkChartProps, type SparkChartVariant, Spinner, SpotlightCard, type SpotlightCardProps, StatCard, type StatCardProps, StatefulButton, type StatefulButtonProps, Step, type StepProps, Steps, type StepsProps, type StickyScrollItem, StickyScrollReveal, type StickyScrollRevealProps, StripeAuthButton, StyleVariant, SunIcon, Surface, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, TagInput, type TagInputProps, TeamCard, type TeamCardProps, TestimonialCard, type TestimonialCardProps, TextGenerateEffect, type TextGenerateEffectProps, Textarea, ThemeModeMultiToggle, type ThemeModeMultiToggleAppearance, type ThemeModeMultiToggleProps, ThemeModeToggle, TikTokAuthButton, Timeline, TimelineItem, type TimelineItemProps, type TimelineProps, Toaster, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, type TooltipItem, TooltipProvider, TooltipTrigger, TopLoadingBar, type TopLoadingBarProps, TracingBeam, type TracingBeamProps, Tracker, type TrackerBlock, type TrackerProps, type TreeNode, TreeView, type TreeViewProps, TypewriterText, type UseDisclosureOptions, type UseDisclosureReturn, type UseFileDialogOptions, type UseFileDialogReturn, type UseIntervalOptions, type UseIntervalReturn, type UseLocalStorageOptions, type UseMeasureReturn, type UsePaginationOptions, type UsePaginationReturn, UserAvatar, type UserAvatarProps, WarningIcon, XAuthButton, XCircleIcon, XIcon, badgeVariants, buttonGroupVariants, cn, fadeIn, navigationMenuTriggerStyle, noMotion, scaleIn, slideDown, slideUp, spring, springBouncy, springGentle, springStiff, toggleVariants, useAnimation, useCountdown, useDirection, useDisclosure, useFileDialog, useFocusTrap, useFormField, useInterval, useIsMobile, useLocalStorage, useMeasure, useMergedRef, usePagination, useReducedMotion, useSaasflareMotion, useSaasflareTheme, useSidebar };