@flikk/ui 1.0.0-beta.27 → 1.0.0-beta.29

package/dist/components/data-display/Timeline/Timeline.types.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { TimelineTheme } from "./Timeline.theme";
 /**
  * Layout orientation for the Timeline
  */
@@ -18,12 +19,44 @@ export interface TimelineThemeOverrides {
     baseStyleHorizontal?: string;
     itemStyle?: string;
     itemStyleHorizontal?: string;
-    lineStyle?: string;
-    lineStyleHorizontal?: string;
+    connectorStyle?: string;
+    connectorStyleHorizontal?: string;
+    connectorCompletedStyle?: string;
     markerStyle?: string;
     markerStatuses?: Partial<Record<TimelineItemStatus, string>>;
     contentStyle?: string;
     contentStyleHorizontal?: string;
+    titleStyle?: string;
+    descriptionStyle?: string;
+    timestampStyle?: string;
+}
+/**
+ * A single timeline item for the data-driven (`items`) API.
+ * Maps internally to `Timeline.Item` → `Timeline.Marker` + `Timeline.Content`,
+ * so it stays fully serializable (no JSX composition required). This is the
+ * generative-UI / model-friendly entry path; the compound API remains for
+ * hand-authored timelines that need full control.
+ */
+export interface TimelineItemData {
+    /** @default 'pending' */
+    status?: TimelineItemStatus;
+    /** Heading line (rendered with the theme's `titleStyle`) */
+    title?: React.ReactNode;
+    /** Body line (rendered with the theme's `descriptionStyle`) */
+    description?: React.ReactNode;
+    /** Trailing meta line, e.g. a date (rendered with the theme's `timestampStyle`) */
+    timestamp?: React.ReactNode;
+    /** Icon element shown inside the marker. Pass a ReactNode (resolve name→icon upstream). */
+    icon?: React.ReactNode;
+    /**
+     * Escape hatch — when provided, replaces the default title/description/timestamp
+     * rendering with arbitrary content (matches the compound `Timeline.Content` body).
+     */
+    content?: React.ReactNode;
+    /** Optional className forwarded to the item wrapper */
+    className?: string;
+    /** Stable React key (falls back to the array index) */
+    key?: string | number;
 }
 /**
  * Timeline root component props
@@ -34,32 +67,26 @@ export interface TimelineProps extends React.HTMLAttributes<HTMLDivElement> {
      * @default 'vertical'
      */
     layout?: TimelineLayout;
+    /**
+     * Data-driven items. When provided, the timeline renders from this array and
+     * any `children` are ignored (dev-warns). Omit it to use the compound API.
+     */
+    items?: TimelineItemData[];
     /**
      * Theme overrides for customizing styles
      */
     theme?: TimelineThemeOverrides;
     /**
-     * Children - should be Timeline.Item components
+     * Children — `Timeline.Item` components (compound API). Optional when `items` is used.
      */
-    children: React.ReactNode;
+    children?: React.ReactNode;
 }
 /**
  * Context value shared between Timeline compound components
  */
 export interface TimelineContextValue {
     layout: TimelineLayout;
-    theme: TimelineThemeOverrides & {
-        baseStyle: string;
-        baseStyleHorizontal: string;
-        itemStyle: string;
-        itemStyleHorizontal: string;
-        lineStyle: string;
-        lineStyleHorizontal: string;
-        markerStyle: string;
-        markerStatuses: Record<TimelineItemStatus, string>;
-        contentStyle: string;
-        contentStyleHorizontal: string;
-    };
+    theme: TimelineTheme;
     totalItems: number;
 }
 /**
@@ -79,6 +106,11 @@ export interface TimelineItemProps extends React.HTMLAttributes<HTMLDivElement>
      * Item content - should include Timeline.Marker and Timeline.Content
      */
     children: React.ReactNode;
+    /**
+     * @internal Index within the timeline, injected by the root via cloneElement.
+     * Do not set this manually.
+     */
+    _index?: number;
 }
 /**
  * Context value for individual Timeline items

package/dist/components/data-display/Timeline/Timeline.utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Strip the DOM drag/animation handlers that collide with `motion.*` element
+ * props, so the remaining `...rest` can be safely spread onto a motion element.
+ * Shared by TimelineItem and TimelineMarker (both render a `motion.div`).
+ */
+export declare function stripMotionConflicts<T extends Record<string, unknown>>(props: T): Omit<T, "onDrag" | "onDragEnd" | "onDragStart" | "onAnimationStart" | "onAnimationEnd">;

package/dist/components/data-display/Timeline/Timeline.utils.js

@@ -0,0 +1,11 @@
+/**
+ * Strip the DOM drag/animation handlers that collide with `motion.*` element
+ * props, so the remaining `...rest` can be safely spread onto a motion element.
+ * Shared by TimelineItem and TimelineMarker (both render a `motion.div`).
+ */
+function stripMotionConflicts(props) {
+    const { onDrag: _onDrag, onDragEnd: _onDragEnd, onDragStart: _onDragStart, onAnimationStart: _onAnimationStart, onAnimationEnd: _onAnimationEnd, ...rest } = props;
+    return rest;
+}
+
+export { stripMotionConflicts };

package/dist/components/data-display/Timeline/TimelineItem.js

@@ -4,6 +4,7 @@ import { useReducedMotion, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { useTimelineContext } from './Timeline.js';
 import { timelineHorizontalItemVariants, timelineItemVariants } from './Timeline.animations.js';
+import { stripMotionConflicts } from './Timeline.utils.js';
 
 // Create context for TimelineItem
 const TimelineItemContext = createContext(undefined);
@@ -14,26 +15,22 @@ const useTimelineItemContext = () => {
         throw new Error("Timeline.Marker and Timeline.Content must be used within Timeline.Item");
     return ctx;
 };
-const TimelineItem = React__default.forwardRef(({ children, className, status = "pending", ...props }, ref) => {
+const TimelineItem = React__default.forwardRef(({ children, className, status = "pending", _index = 0, ...props }, ref) => {
     const { layout, theme, totalItems } = useTimelineContext();
     const shouldReduceMotion = useReducedMotion();
     const itemRef = useRef(null);
     const [isVisible, setIsVisible] = useState(false);
-    // Determine item index from parent
+    // Index/first/last come from the root (single source of truth), not the DOM.
+    const index = _index;
+    const isFirst = index === 0;
+    const isLast = index === totalItems - 1;
+    const isHorizontal = layout === "horizontal";
     const resolvedRef = ref || itemRef;
-    // Find index among siblings for alternate layout
-    const [index, setIndex] = useState(0);
-    useEffect(() => {
-        const element = resolvedRef && "current" in resolvedRef ? resolvedRef.current : itemRef.current;
-        if (element === null || element === void 0 ? void 0 : element.parentElement) {
-            const siblings = Array.from(element.parentElement.children);
-            const idx = siblings.indexOf(element);
-            setIndex(idx);
-        }
-    }, [resolvedRef]);
-    // IntersectionObserver for scroll-triggered animation
+    // IntersectionObserver for scroll-triggered entry animation
     useEffect(() => {
-        const element = resolvedRef && "current" in resolvedRef ? resolvedRef.current : itemRef.current;
+        const element = resolvedRef && "current" in resolvedRef
+            ? resolvedRef.current
+            : itemRef.current;
         if (!element)
             return;
         const observer = new IntersectionObserver(([entry]) => {
@@ -45,9 +42,6 @@ const TimelineItem = React__default.forwardRef(({ children, className, status =
         observer.observe(element);
         return () => observer.disconnect();
     }, [resolvedRef]);
-    const isFirst = index === 0;
-    const isLast = index === totalItems - 1;
-    const isHorizontal = layout === "horizontal";
     // Select animation variants based on layout
     const getVariants = () => {
         if (shouldReduceMotion)
@@ -63,10 +57,9 @@ const TimelineItem = React__default.forwardRef(({ children, className, status =
         isFirst,
         isLast,
     };
-    // Filter out conflicting motion props from rest
-    const { onDrag, onDragEnd, onDragStart, onAnimationStart, onAnimationEnd, ...safeProps } = props;
+    const safeProps = stripMotionConflicts(props);
     const variants = getVariants();
-    return (jsx(TimelineItemContext.Provider, { value: contextValue, children: jsx(motion.div, { ref: ref || itemRef, className: cn(isHorizontal ? theme.itemStyleHorizontal : theme.itemStyle, className), "data-status": status, "data-layout": layout, role: "listitem", initial: variants ? "hidden" : undefined, animate: variants && isVisible ? "visible" : variants ? "hidden" : undefined, variants: variants, ...safeProps, children: children }) }));
+    return (jsx(TimelineItemContext.Provider, { value: contextValue, children: jsx(motion.div, { ref: ref || itemRef, className: cn(isHorizontal ? theme.itemStyleHorizontal : theme.itemStyle, className), "data-status": status, "data-layout": layout, role: "listitem", "aria-current": status === "active" ? "step" : undefined, initial: variants ? "hidden" : undefined, animate: variants && isVisible ? "visible" : variants ? "hidden" : undefined, variants: variants, ...safeProps, children: children }) }));
 });
 TimelineItem.displayName = "TimelineItem";
 

package/dist/components/data-display/Timeline/TimelineMarker.js

@@ -6,7 +6,14 @@ import { cn } from '../../../utils/cn.js';
 import { useTimelineContext } from './Timeline.js';
 import { useTimelineItemContext } from './TimelineItem.js';
 import { timelineMarkerVariants } from './Timeline.animations.js';
+import { stripMotionConflicts } from './Timeline.utils.js';
 
+// Screen-reader status text so status isn't conveyed by color/icon alone.
+const STATUS_LABEL = {
+    completed: "Completed",
+    active: "In progress",
+    pending: "Pending",
+};
 const TimelineMarker = React__default.forwardRef(({ icon, className, ...props }, ref) => {
     const { theme, layout } = useTimelineContext();
     const { status, isLast } = useTimelineItemContext();
@@ -19,20 +26,15 @@ const TimelineMarker = React__default.forwardRef(({ icon, className, ...props },
             return jsx(CheckIcon, { className: "w-4 h-4" });
         }
         if (status === "active") {
-            return jsx("span", { className: "w-2 h-2 rounded-full bg-white" });
+            return (jsx("span", { className: "w-2 h-2 rounded-full bg-[var(--color-primary)]" }));
         }
         // Pending: small neutral dot
         return (jsx("span", { className: "w-2 h-2 rounded-full bg-[var(--color-text-muted)]" }));
     };
     const isHorizontal = layout === "horizontal";
     const variants = shouldReduceMotion ? undefined : timelineMarkerVariants;
-    // Filter out conflicting motion props
-    const { onDrag, onDragEnd, onDragStart, onAnimationStart, onAnimationEnd, ...safeProps } = props;
-    return (jsxs("div", { className: cn("relative flex flex-col items-center", isHorizontal && "w-full"), children: [jsx(motion.div, { ref: ref, className: cn(theme.markerStyle, theme.markerStatuses[status], className), "data-status": status, "aria-label": `${status} step`, initial: variants ? "hidden" : undefined, animate: variants ? "visible" : undefined, variants: variants, ...safeProps, children: renderIcon() }), !isLast && !isHorizontal && (jsx("div", { className: cn("w-0.5 flex-1 min-h-4", status === "completed"
-                    ? "bg-[var(--color-success)]"
-                    : "bg-[var(--color-border)]"), "aria-hidden": "true" })), !isLast && isHorizontal && (jsx("div", { className: cn("absolute top-1/2 -translate-y-1/2 left-1/2 h-0.5 w-full", status === "completed"
-                    ? "bg-[var(--color-success)]"
-                    : "bg-[var(--color-border)]"), "aria-hidden": "true" }))] }));
+    const safeProps = stripMotionConflicts(props);
+    return (jsxs("div", { className: cn("relative flex flex-col items-center", isHorizontal && "w-full"), children: [jsxs(motion.div, { ref: ref, className: cn(theme.markerStyle, theme.markerStatuses[status], className), "data-status": status, initial: variants ? "hidden" : undefined, animate: variants ? "visible" : undefined, variants: variants, ...safeProps, children: [jsx("span", { className: "sr-only", children: STATUS_LABEL[status] }), jsx("span", { "aria-hidden": "true", className: "flex items-center justify-center", children: renderIcon() })] }), !isLast && !isHorizontal && (jsx("div", { className: cn(theme.connectorStyle, status === "completed" && theme.connectorCompletedStyle), "aria-hidden": "true" })), !isLast && isHorizontal && (jsx("div", { className: cn(theme.connectorStyleHorizontal, status === "completed" && theme.connectorCompletedStyle), "aria-hidden": "true" }))] }));
 });
 TimelineMarker.displayName = "TimelineMarker";
 

package/dist/components/data-display/Timeline/index.d.ts

@@ -1,4 +1,4 @@
 import { Timeline } from "./Timeline";
-import { TimelineProps, TimelineItemProps, TimelineMarkerProps, TimelineContentProps, TimelineContextValue, TimelineItemContextValue, TimelineThemeOverrides, TimelineLayout, TimelineItemStatus } from "./Timeline.types";
+import { TimelineProps, TimelineItemProps, TimelineItemData, TimelineMarkerProps, TimelineContentProps, TimelineContextValue, TimelineItemContextValue, TimelineThemeOverrides, TimelineLayout, TimelineItemStatus } from "./Timeline.types";
 export { Timeline };
-export type { TimelineProps, TimelineItemProps, TimelineMarkerProps, TimelineContentProps, TimelineContextValue, TimelineItemContextValue, TimelineThemeOverrides, TimelineLayout, TimelineItemStatus, };
+export type { TimelineProps, TimelineItemProps, TimelineItemData, TimelineMarkerProps, TimelineContentProps, TimelineContextValue, TimelineItemContextValue, TimelineThemeOverrides, TimelineLayout, TimelineItemStatus, };

package/dist/components/effects/3d/index.d.ts

@@ -2,5 +2,3 @@ export { AIOrb } from "../AIOrb";
 export type { AIOrbProps, OrbState, DotSphereProps, LiquidProps, AuraProps } from "../AIOrb";
 export { Particles } from "../Particles";
 export type { ParticlesProps } from "../Particles";
-export { SpotlightBorder } from "../SpotlightBorder";
-export type { SpotlightBorderProps, SpotlightBorderVariation, } from "../SpotlightBorder";

package/dist/components/effects/3d/index.js

@@ -1,3 +1,2 @@
 export { AIOrb } from '../AIOrb/AIOrb.js';
 export { Particles } from '../Particles/Particles.js';
-export { SpotlightBorder } from '../SpotlightBorder/SpotlightBorder.js';

package/dist/components/effects/DotPattern/DotPattern.js

@@ -34,7 +34,7 @@ function buildMaskImage(direction, fadeSize) {
  * </div>
  * ```
  */
-const DotPattern = React__default.forwardRef(({ spacing = 20, dotSize = 1, color = "var(--color-border)", fade = true, fadeDirection = "radial", fadeSize = 50, animated = false, className, style, ...rest }, ref) => {
+const DotPattern = React__default.forwardRef(({ spacing = 20, dotSize = 1, color = "var(--color-border-secondary)", fade = true, fadeDirection = "radial", fadeSize = 50, animated = false, className, style, ...rest }, ref) => {
     const patternId = useId();
     const shouldReduceMotion = useReducedMotion();
     const enableAnimation = animated && !shouldReduceMotion;

package/dist/components/effects/Overlay/Overlay.theme.js

@@ -1,7 +1,6 @@
 const overlayTheme = {
     /** Full-screen backdrop with blur */
-    backdrop: "fixed inset-0 bg-[var(--overlay-bg)] z-50 ",
-    // backdrop-blur-[var(--overlay-blur)]
+    backdrop: "fixed inset-0 bg-[var(--overlay-bg)] z-50 backdrop-blur-[var(--overlay-blur)] ",
     /** Dots / pattern layer behind content */
     pattern: "absolute inset-0 w-full h-full z-0 pointer-events-none",
     /** Content wrapper (sits above pattern) */

package/dist/components/effects/Preloader/Preloader.animations.d.ts

@@ -0,0 +1,23 @@
+import type React from 'react';
+import type { PreloaderDirection, PreloaderType } from './Preloader.types';
+import type { Variants } from 'motion/react';
+export declare const CURTAIN_EASE: readonly [0.76, 0, 0.24, 1];
+export declare const buildCurtainVariants: (direction: PreloaderDirection, duration: number) => Variants;
+export declare const buildLogoParallaxVariants: (direction: PreloaderDirection, duration: number) => Variants;
+export declare const buildLogoFadeVariants: (duration: number) => Variants;
+export interface PanelDescriptor {
+    key: string;
+    style: React.CSSProperties;
+    variants: Variants;
+    /** Resolved fill for this panel (layers color ladder). Falls back to the `color` prop, then the default class. */
+    backgroundColor?: string;
+}
+export interface PanelEngineOptions {
+    type: PreloaderType;
+    direction: PreloaderDirection;
+    duration: number;
+    panels: number;
+    stagger: number;
+    color?: string;
+}
+export declare const buildPanelDescriptors: (opts: PanelEngineOptions) => PanelDescriptor[];

package/dist/components/effects/Preloader/Preloader.animations.js

@@ -0,0 +1,150 @@
+const CURTAIN_EASE = [0.76, 0, 0.24, 1];
+const exitTransition = (duration, delay = 0) => ({
+    duration,
+    ease: CURTAIN_EASE,
+    delay,
+});
+const exitMap = {
+    up: { y: '-100%', x: 0 },
+    down: { y: '100%', x: 0 },
+    left: { x: '-100%', y: 0 },
+    right: { x: '100%', y: 0 },
+};
+const buildCurtainVariants = (direction, duration) => ({
+    covered: { y: 0, x: 0 },
+    exit: {
+        ...exitMap[direction],
+        transition: exitTransition(duration),
+    },
+});
+// Logo is rendered INSIDE the curtain. These are relative offsets that
+// counteract ~30% of the curtain's motion, making the logo appear to
+// move at ~70% of the curtain's speed (parallax lag effect). It also
+// fades out so the mark dissolves while lagging instead of riding the
+// curtain edge off-screen.
+const logoInnerOffsetMap = {
+    up: { y: '30vh', x: 0 },
+    down: { y: '-30vh', x: 0 },
+    left: { x: '30vw', y: 0 },
+    right: { x: '-30vw', y: 0 },
+};
+const buildLogoParallaxVariants = (direction, duration) => ({
+    covered: { y: 0, x: 0, opacity: 1 },
+    exit: {
+        ...logoInnerOffsetMap[direction],
+        opacity: 0,
+        transition: exitTransition(duration),
+    },
+});
+// Plain fade-out for logos that don't translate on their own: every
+// non-slide type renders the logo in a static centered layer over the
+// panels, so it must fade or it would linger over the revealed page.
+// Slightly faster than the panels so the mark is gone before the
+// reveal completes.
+const buildLogoFadeVariants = (duration) => ({
+    covered: { opacity: 1 },
+    exit: {
+        opacity: 0,
+        transition: { duration: duration * 0.5, ease: CURTAIN_EASE },
+    },
+});
+// Strips travel slightly past their own span so sub-pixel rounding never
+// leaves a hairline of curtain at the edge.
+const STRIP_EXIT = 102;
+const buildStripDescriptors = ({ type, direction, duration, panels, stagger, }) => {
+    // Strips orient perpendicular to the exit axis: up/down → vertical strips
+    // translating Y; left/right → horizontal strips translating X.
+    const axis = direction === 'left' || direction === 'right' ? 'x' : 'y';
+    const sign = direction === 'up' || direction === 'left' ? -1 : 1;
+    const size = 100 / panels;
+    return Array.from({ length: panels }, (_, i) => {
+        // +0.4% overlap so adjacent strips never show a seam between them
+        const span = `${size + (i < panels - 1 ? 0.4 : 0)}%`;
+        const offset = `${i * size}%`;
+        const panelSign = type === 'shutters' && i % 2 === 1 ? -sign : sign;
+        return {
+            key: `strip-${i}`,
+            style: axis === 'y'
+                ? { top: 0, bottom: 0, left: offset, width: span, willChange: 'transform' }
+                : { left: 0, right: 0, top: offset, height: span, willChange: 'transform' },
+            variants: {
+                covered: { x: 0, y: 0 },
+                exit: {
+                    [axis]: `${panelSign * STRIP_EXIT}%`,
+                    transition: exitTransition(duration, i * stagger),
+                },
+            },
+        };
+    });
+};
+const buildLayerDescriptors = ({ direction, duration, panels, stagger, color, }) => {
+    const base = color !== null && color !== void 0 ? color : 'var(--color-primary)';
+    return Array.from({ length: panels }, (_, i) => ({
+        key: `layer-${i}`,
+        // First-leaving layer sits on top; deeper layers get progressively lighter
+        style: { inset: 0, zIndex: panels - i, willChange: 'transform' },
+        backgroundColor: i === 0 ? color : `color-mix(in oklab, ${base}, white ${Math.min(i * 30, 75)}%)`,
+        variants: {
+            covered: { x: 0, y: 0 },
+            exit: {
+                ...exitMap[direction],
+                transition: exitTransition(duration, i * stagger),
+            },
+        },
+    }));
+};
+const buildSplitDescriptors = ({ direction, duration, }) => {
+    const make = (key, place, exit) => ({
+        key,
+        style: { ...place, willChange: 'transform' },
+        variants: {
+            covered: {},
+            exit: { ...exit, transition: exitTransition(duration) },
+        },
+    });
+    return direction === 'up' || direction === 'down'
+        ? [
+            make('split-1', { top: 0, left: 0, right: 0, height: '50%' }, { y: '-100%' }),
+            make('split-2', { bottom: 0, left: 0, right: 0, height: '50%' }, { y: '100%' }),
+        ]
+        : [
+            make('split-1', { top: 0, bottom: 0, left: 0, width: '50%' }, { x: '-100%' }),
+            make('split-2', { top: 0, bottom: 0, right: 0, width: '50%' }, { x: '100%' }),
+        ];
+};
+const buildPanelDescriptors = (opts) => {
+    switch (opts.type) {
+        case 'blinds':
+        case 'shutters':
+            return buildStripDescriptors(opts);
+        case 'layers':
+            return buildLayerDescriptors(opts);
+        case 'iris':
+            return [
+                {
+                    key: 'iris',
+                    style: { inset: 0 },
+                    variants: {
+                        covered: { clipPath: 'circle(125% at 50% 50%)' },
+                        exit: {
+                            clipPath: 'circle(0% at 50% 50%)',
+                            transition: exitTransition(opts.duration),
+                        },
+                    },
+                },
+            ];
+        case 'split':
+            return buildSplitDescriptors(opts);
+        case 'slide':
+        default:
+            return [
+                {
+                    key: 'curtain',
+                    style: { inset: 0, willChange: 'transform' },
+                    variants: buildCurtainVariants(opts.direction, opts.duration),
+                },
+            ];
+    }
+};
+
+export { CURTAIN_EASE, buildCurtainVariants, buildLogoFadeVariants, buildLogoParallaxVariants, buildPanelDescriptors };

package/dist/components/effects/Preloader/Preloader.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import type { PreloaderProps } from "./Preloader.types";
+export declare const Preloader: React.FC<PreloaderProps>;

package/dist/components/effects/Preloader/Preloader.js

@@ -0,0 +1,119 @@
+import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
+import { useState, useRef, useEffect } from 'react';
+import { useReducedMotion, motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import { buildPanelDescriptors, buildLogoParallaxVariants, buildLogoFadeVariants } from './Preloader.animations.js';
+
+const DEFAULT_COLOR_CLASS = "bg-[var(--color-primary)]";
+const PANEL_DEFAULTS = {
+    blinds: 5,
+    shutters: 4,
+    layers: 3,
+};
+const STAGGER_DEFAULTS = {
+    blinds: 0.08,
+    shutters: 0.08,
+    layers: 0.14,
+};
+const Preloader = ({ children, logo, type = "slide", direction = "up", duration = 0.8, delay = 0.8, color, className, parallax = true, contained = false, panels, stagger, onStart, onComplete, }) => {
+    var _a, _b;
+    const [phase, setPhase] = useState("covered");
+    const [completedPanels, setCompletedPanels] = useState(0);
+    const shouldReduceMotion = useReducedMotion();
+    const isMultiPanel = type === "blinds" || type === "shutters" || type === "layers";
+    let panelCount = (_a = PANEL_DEFAULTS[type]) !== null && _a !== void 0 ? _a : (type === "split" ? 2 : 1);
+    if (isMultiPanel && panels !== undefined) {
+        if (process.env.NODE_ENV !== "production" && (panels < 2 || panels > 12)) {
+            console.warn("[Preloader]: panels must be between 2 and 12; clamping.");
+        }
+        panelCount = Math.min(12, Math.max(2, Math.round(panels)));
+    }
+    const resolvedStagger = isMultiPanel ? (_b = stagger !== null && stagger !== void 0 ? stagger : STAGGER_DEFAULTS[type]) !== null && _b !== void 0 ? _b : 0 : 0;
+    // Stable refs for callbacks/reduced-motion to avoid stale closures without re-running the effect
+    const onStartRef = useRef(onStart);
+    const onCompleteRef = useRef(onComplete);
+    const reducedMotionRef = useRef(shouldReduceMotion);
+    // Guards against re-triggering the exit if the effect re-runs (e.g. `delay` change)
+    const startedRef = useRef(false);
+    useEffect(() => { onStartRef.current = onStart; }, [onStart]);
+    useEffect(() => { onCompleteRef.current = onComplete; }, [onComplete]);
+    useEffect(() => { reducedMotionRef.current = shouldReduceMotion; }, [shouldReduceMotion]);
+    useEffect(() => {
+        if (typeof window === "undefined" || typeof document === "undefined")
+            return;
+        let cancelled = false;
+        let delayTimer;
+        let loadListener;
+        const loadPromise = new Promise((resolve) => {
+            if (document.readyState === "complete") {
+                resolve();
+            }
+            else {
+                loadListener = () => resolve();
+                window.addEventListener("load", loadListener, { once: true });
+            }
+        });
+        const delayPromise = new Promise((resolve) => {
+            delayTimer = setTimeout(resolve, delay * 1000);
+        });
+        Promise.all([loadPromise, delayPromise]).then(() => {
+            var _a, _b;
+            if (cancelled || startedRef.current)
+                return;
+            startedRef.current = true;
+            if (reducedMotionRef.current) {
+                // Skip the animation entirely but keep the callback contract
+                (_a = onStartRef.current) === null || _a === void 0 ? void 0 : _a.call(onStartRef);
+                setPhase("done");
+                (_b = onCompleteRef.current) === null || _b === void 0 ? void 0 : _b.call(onCompleteRef);
+            }
+            else {
+                setPhase("exit");
+            }
+        });
+        return () => {
+            cancelled = true;
+            if (delayTimer !== undefined)
+                clearTimeout(delayTimer);
+            if (loadListener)
+                window.removeEventListener("load", loadListener);
+        };
+    }, [delay]);
+    useEffect(() => {
+        var _a;
+        if (completedPanels >= panelCount) {
+            setPhase("done");
+            (_a = onCompleteRef.current) === null || _a === void 0 ? void 0 : _a.call(onCompleteRef);
+        }
+    }, [completedPanels, panelCount]);
+    if (phase === "done") {
+        return jsx(Fragment, { children: children });
+    }
+    const positionClass = contained ? "absolute inset-0" : "fixed inset-0";
+    const descriptors = buildPanelDescriptors({
+        type,
+        direction,
+        duration,
+        panels: panelCount,
+        stagger: resolvedStagger,
+        color,
+    });
+    const handleExitStart = (def) => {
+        var _a;
+        if (def === "exit")
+            (_a = onStartRef.current) === null || _a === void 0 ? void 0 : _a.call(onStartRef);
+    };
+    // Slide carries its logo inside the curtain (parallax lag or plain fade);
+    // every other type renders it in the static centered layer below.
+    const slideLogoNode = type === "slide" && logo ? (parallax ? (jsx(motion.div, { className: "relative z-10 select-none", variants: buildLogoParallaxVariants(direction, duration), initial: "covered", animate: phase, children: logo })) : (jsx(motion.div, { className: "relative z-10 select-none", variants: buildLogoFadeVariants(duration), initial: "covered", animate: phase, children: logo }))) : null;
+    return (jsxs(Fragment, { children: [children, jsxs("div", { "aria-hidden": "true", className: cn(positionClass, "z-[9999] pointer-events-none"), children: [descriptors.map((d, i) => {
+                        var _a;
+                        const bg = (_a = d.backgroundColor) !== null && _a !== void 0 ? _a : color;
+                        return (jsx(motion.div, { className: cn("absolute pointer-events-auto", type === "slide" && "flex items-center justify-center", !bg && DEFAULT_COLOR_CLASS, className), style: { ...d.style, ...(bg ? { backgroundColor: bg } : undefined) }, variants: d.variants, initial: "covered", animate: phase, onAnimationStart: i === 0 ? handleExitStart : undefined, onAnimationComplete: (def) => {
+                                if (def === "exit")
+                                    setCompletedPanels((n) => n + 1);
+                            }, children: slideLogoNode }, d.key));
+                    }), type !== "slide" && logo && (jsx(motion.div, { className: "absolute inset-0 flex items-center justify-center select-none", style: { zIndex: 50 }, variants: buildLogoFadeVariants(duration), initial: "covered", animate: phase, children: logo }))] })] }));
+};
+
+export { Preloader };

package/dist/components/effects/Preloader/Preloader.types.d.ts

@@ -0,0 +1,63 @@
+export type PreloaderDirection = 'up' | 'down' | 'left' | 'right';
+export type PreloaderType = 'slide' | 'split' | 'blinds' | 'shutters' | 'layers' | 'iris';
+export interface PreloaderProps {
+    /** Page content revealed once the curtain exits. */
+    children: React.ReactNode;
+    /** Decorative mark centered on the curtain (hidden from assistive tech). */
+    logo?: React.ReactNode;
+    /**
+     * `slide` = one full curtain exits; `split` = two half panels part in
+     * opposite directions; `blinds` = staggered strips sweep the same way;
+     * `shutters` = strips alternate directions; `layers` = stacked curtains
+     * trail each other in lightening shades; `iris` = a circular mask closes
+     * on the curtain from the edges to the center.
+     */
+    type?: PreloaderType;
+    /**
+     * Exit direction. For `split`, `up`/`down` split along the horizontal seam
+     * and `left`/`right` along the vertical seam (the two are equivalent per axis).
+     * For `blinds`/`shutters`, strips orient perpendicular to the exit axis.
+     * Ignored by `iris` (always closes to center).
+     */
+    direction?: PreloaderDirection;
+    /**
+     * Exit animation duration in seconds (not ms), per panel. For staggered
+     * types the total exit time is `duration + (panels - 1) * stagger`.
+     */
+    duration?: number;
+    /**
+     * Minimum hold time in seconds (not ms). The curtain exits once BOTH the
+     * window `load` event has fired and this delay has elapsed.
+     */
+    delay?: number;
+    /**
+     * Curtain fill as a CSS color value (e.g. `"var(--color-primary-900)"`, `"#0a0a0a"`).
+     * Applied as an inline `background-color`, so it wins over `className`.
+     * When omitted, the curtain uses `bg-[var(--color-primary)]` as a class,
+     * which `className` background utilities can override.
+     */
+    color?: string;
+    className?: string;
+    /** Slide only: the logo lags behind the curtain for a depth effect. */
+    parallax?: boolean;
+    /**
+     * Position the overlay `absolute` within the nearest positioned ancestor
+     * instead of `fixed` to the viewport. Use when embedding the transition in
+     * a container (demos, hero sections) rather than covering the whole page.
+     */
+    contained?: boolean;
+    /**
+     * Strip/slat/layer count for `blinds` (default 5), `shutters` (default 4),
+     * and `layers` (default 3). Clamped to 2–12. Ignored by other types.
+     */
+    panels?: number;
+    /**
+     * Seconds between successive panels for `blinds`/`shutters` (default 0.08)
+     * and `layers` (default 0.14). Ignored by other types.
+     */
+    stagger?: number;
+    /** Fires when the exit animation starts (immediately if reduced motion is on). */
+    onStart?: () => void;
+    /** Fires once the reveal finishes; the overlay unmounts from the DOM. */
+    onComplete?: () => void;
+}

package/dist/components/effects/Preloader/index.d.ts

@@ -0,0 +1,2 @@
+export { Preloader } from './Preloader';
+export type { PreloaderProps, PreloaderDirection, PreloaderType } from './Preloader.types';