@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/components/effects/PaperTexture/PaperTexture.shaders.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PaperTexture fragment shader — adapted from paper-design/shaders'
+ * `paper-texture.ts` (https://github.com/paper-design/shaders, Apache
+ * License 2.0). An image filter: normal-maps a source image with a
+ * paper-grain fiber/roughness texture and re-lights it.
+ *
+ * Simplified from the original: image UV computed via the shared
+ * `getImageCoverUV` cover-fit helper (see shared/imageUV.glsl.ts) instead of
+ * paper-design's ShaderSizingParams fit engine; pure-hash GLSL instead of
+ * pre-generated noise-texture sampling.
+ *
+ * Trimmed for v1: keeps the core `fiber`/`roughness`/`contrast` normal-map
+ * layers (the essential "paper grain" look) and drops the elaborate
+ * `crumples`/`folds`/`drops`/`fade` secondary normal-perturbation layers —
+ * those are the most GLSL-dense part of the original and least essential to
+ * "paper texture" reading as itself. May be added later as a follow-up.
+ *
+ * `fiberNoise` below is an original approximation (directional streaked
+ * value-noise), NOT a port — paper-design's own `fiberNoise` implementation
+ * wasn't available in the extracted source material for this port.
+ */
+export declare const paperTextureFragmentShader = "#version 300 es\nprecision mediump float;\n\nuniform vec2 iResolution;\n\nuniform vec4 u_colorFront;\nuniform vec4 u_colorBack;\n\nuniform sampler2D u_image;\nuniform float u_imageAspectRatio;\n\nuniform float u_contrast;\nuniform float u_roughness;\nuniform float u_fiber;\nuniform float u_fiberSize;\n\nout vec4 fragColor;\n\n\nvec2 rotate(vec2 v, float angle) {\n  float s = sin(angle);\n  float c = cos(angle);\n  return mat2(c, -s, s, c) * v;\n}\n\n\nfloat randomR(vec2 st) {\n  return fract(sin(dot(st, vec2(12.9898, 78.233))) * 43758.5453123);\n}\n\n\nvec2 getImageCoverUV(vec2 fragUV, vec2 resolution, float imageAspectRatio) {\n  float containerAspect = resolution.x / resolution.y;\n  // Container wider (relative to its height) than the image: sample a\n  // narrower vertical slice of the image (crop top/bottom) so it fills the\n  // container width with no letterboxing. Container narrower/taller than\n  // the image: sample a narrower horizontal slice (crop left/right) instead.\n  vec2 scale = containerAspect > imageAspectRatio\n    ? vec2(1.0, imageAspectRatio / containerAspect)\n    : vec2(containerAspect / imageAspectRatio, 1.0);\n  return (fragUV - 0.5) * scale + 0.5;\n}\n\n\nfloat getUvFrame(vec2 uv) {\n  float aax = 2. * fwidth(uv.x);\n  float aay = 2. * fwidth(uv.y);\n  float left = smoothstep(0., aax, uv.x);\n  float right = 1. - smoothstep(1. - aax, 1., uv.x);\n  float bottom = smoothstep(0., aay, uv.y);\n  float top = 1. - smoothstep(1. - aay, 1., uv.y);\n  return left * right * bottom * top;\n}\n\nfloat roughnessTex(vec2 p) {\n  p *= .1;\n  float o = 0.;\n  for (float i = 0.; ++i < 4.; p *= 2.1) {\n    vec4 w = vec4(floor(p), ceil(p));\n    vec2 f = fract(p);\n    o += mix(mix(randomR(w.xy), randomR(w.xw), f.y), mix(randomR(w.zy), randomR(w.zw), f.y), f.x);\n    o += .2 / exp(2. * abs(sin(.2 * p.x + .5 * p.y)));\n  }\n  return o / 3.;\n}\n\nfloat valueNoise(vec2 st) {\n  vec2 i = floor(st);\n  vec2 f = fract(st);\n  float a = randomR(i);\n  float b = randomR(i + vec2(1.0, 0.0));\n  float c = randomR(i + vec2(0.0, 1.0));\n  float d = randomR(i + vec2(1.0, 1.0));\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  float x1 = mix(a, b, u.x);\n  float x2 = mix(c, d, u.x);\n  return mix(x1, x2, u.y);\n}\n\nfloat fiberNoise(vec2 p, vec2 seed) {\n  p += seed;\n  float n = 0.0;\n  float amp = 1.0;\n  for (int i = 0; i < 3; i++) {\n    float stretch = 6.0 + float(i) * 4.0;\n    vec2 sp = vec2(p.x * stretch, p.y * 1.5);\n    n += amp * valueNoise(sp);\n    amp *= 0.5;\n    p = rotate(p, 0.3);\n  }\n  return n;\n}\n\nvoid main() {\n  vec2 fragUV = gl_FragCoord.xy / iResolution.xy;\n  vec2 imageUV = getImageCoverUV(fragUV, iResolution, u_imageAspectRatio);\n  vec2 patternUV = imageUV - .5;\n  patternUV = 5. * (patternUV * vec2(u_imageAspectRatio, 1.));\n\n  vec2 roughnessUv = 1.5 * (gl_FragCoord.xy - .5 * iResolution.xy);\n  float roughnessVal = roughnessTex(roughnessUv + vec2(1., 0.)) - roughnessTex(roughnessUv - vec2(1., 0.));\n\n  vec2 fiberUV = 2. / max(u_fiberSize, 0.01) * patternUV;\n  float fiber = fiberNoise(fiberUV, vec2(0.));\n  fiber = .5 * u_fiber * (fiber - 1.);\n\n  vec2 normal = vec2(0.);\n  vec2 normalImage = vec2(0.);\n\n  normal.xy += u_roughness * 1.5 * roughnessVal;\n  normal.xy += fiber;\n  normalImage += u_roughness * .75 * roughnessVal;\n  normalImage += .2 * fiber;\n\n  vec3 lightPos = vec3(1., 2., 1.);\n  float res = dot(normalize(vec3(normal, 9.5 - 9. * pow(u_contrast, .1))), normalize(lightPos));\n\n  vec3 fgColor = u_colorFront.rgb * u_colorFront.a;\n  float fgOpacity = u_colorFront.a;\n  vec3 bgColor = u_colorBack.rgb * u_colorBack.a;\n  float bgOpacity = u_colorBack.a;\n\n  imageUV += .02 * normalImage;\n  float frame = getUvFrame(imageUV);\n  vec4 image = texture(u_image, imageUV);\n  image.rgb += .6 * pow(u_contrast, .4) * (res - .7);\n  frame *= image.a;\n\n  vec3 color = fgColor * res;\n  float opacity = fgOpacity * res;\n  color += bgColor * (1. - opacity);\n  opacity += bgOpacity * (1. - opacity);\n  opacity = mix(opacity, 1., frame);\n\n  color.rgb = mix(color, image.rgb, frame);\n\n  fragColor = vec4(color, opacity);\n}\n";

package/dist/components/effects/PaperTexture/PaperTexture.shaders.js

@@ -0,0 +1,145 @@
+import 'react/jsx-runtime';
+import 'react';
+import { glslRotate2, glslHashFloat } from '../shared/shaderNoise.glsl.js';
+import { glslImageCoverUV } from '../shared/imageUV.glsl.js';
+
+/**
+ * PaperTexture fragment shader — adapted from paper-design/shaders'
+ * `paper-texture.ts` (https://github.com/paper-design/shaders, Apache
+ * License 2.0). An image filter: normal-maps a source image with a
+ * paper-grain fiber/roughness texture and re-lights it.
+ *
+ * Simplified from the original: image UV computed via the shared
+ * `getImageCoverUV` cover-fit helper (see shared/imageUV.glsl.ts) instead of
+ * paper-design's ShaderSizingParams fit engine; pure-hash GLSL instead of
+ * pre-generated noise-texture sampling.
+ *
+ * Trimmed for v1: keeps the core `fiber`/`roughness`/`contrast` normal-map
+ * layers (the essential "paper grain" look) and drops the elaborate
+ * `crumples`/`folds`/`drops`/`fade` secondary normal-perturbation layers —
+ * those are the most GLSL-dense part of the original and least essential to
+ * "paper texture" reading as itself. May be added later as a follow-up.
+ *
+ * `fiberNoise` below is an original approximation (directional streaked
+ * value-noise), NOT a port — paper-design's own `fiberNoise` implementation
+ * wasn't available in the extracted source material for this port.
+ */
+const paperTextureFragmentShader = `#version 300 es
+precision mediump float;
+
+uniform vec2 iResolution;
+
+uniform vec4 u_colorFront;
+uniform vec4 u_colorBack;
+
+uniform sampler2D u_image;
+uniform float u_imageAspectRatio;
+
+uniform float u_contrast;
+uniform float u_roughness;
+uniform float u_fiber;
+uniform float u_fiberSize;
+
+out vec4 fragColor;
+
+${glslRotate2}
+${glslHashFloat}
+${glslImageCoverUV}
+
+float getUvFrame(vec2 uv) {
+  float aax = 2. * fwidth(uv.x);
+  float aay = 2. * fwidth(uv.y);
+  float left = smoothstep(0., aax, uv.x);
+  float right = 1. - smoothstep(1. - aax, 1., uv.x);
+  float bottom = smoothstep(0., aay, uv.y);
+  float top = 1. - smoothstep(1. - aay, 1., uv.y);
+  return left * right * bottom * top;
+}
+
+float roughnessTex(vec2 p) {
+  p *= .1;
+  float o = 0.;
+  for (float i = 0.; ++i < 4.; p *= 2.1) {
+    vec4 w = vec4(floor(p), ceil(p));
+    vec2 f = fract(p);
+    o += mix(mix(randomR(w.xy), randomR(w.xw), f.y), mix(randomR(w.zy), randomR(w.zw), f.y), f.x);
+    o += .2 / exp(2. * abs(sin(.2 * p.x + .5 * p.y)));
+  }
+  return o / 3.;
+}
+
+float valueNoise(vec2 st) {
+  vec2 i = floor(st);
+  vec2 f = fract(st);
+  float a = randomR(i);
+  float b = randomR(i + vec2(1.0, 0.0));
+  float c = randomR(i + vec2(0.0, 1.0));
+  float d = randomR(i + vec2(1.0, 1.0));
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float x1 = mix(a, b, u.x);
+  float x2 = mix(c, d, u.x);
+  return mix(x1, x2, u.y);
+}
+
+float fiberNoise(vec2 p, vec2 seed) {
+  p += seed;
+  float n = 0.0;
+  float amp = 1.0;
+  for (int i = 0; i < 3; i++) {
+    float stretch = 6.0 + float(i) * 4.0;
+    vec2 sp = vec2(p.x * stretch, p.y * 1.5);
+    n += amp * valueNoise(sp);
+    amp *= 0.5;
+    p = rotate(p, 0.3);
+  }
+  return n;
+}
+
+void main() {
+  vec2 fragUV = gl_FragCoord.xy / iResolution.xy;
+  vec2 imageUV = getImageCoverUV(fragUV, iResolution, u_imageAspectRatio);
+  vec2 patternUV = imageUV - .5;
+  patternUV = 5. * (patternUV * vec2(u_imageAspectRatio, 1.));
+
+  vec2 roughnessUv = 1.5 * (gl_FragCoord.xy - .5 * iResolution.xy);
+  float roughnessVal = roughnessTex(roughnessUv + vec2(1., 0.)) - roughnessTex(roughnessUv - vec2(1., 0.));
+
+  vec2 fiberUV = 2. / max(u_fiberSize, 0.01) * patternUV;
+  float fiber = fiberNoise(fiberUV, vec2(0.));
+  fiber = .5 * u_fiber * (fiber - 1.);
+
+  vec2 normal = vec2(0.);
+  vec2 normalImage = vec2(0.);
+
+  normal.xy += u_roughness * 1.5 * roughnessVal;
+  normal.xy += fiber;
+  normalImage += u_roughness * .75 * roughnessVal;
+  normalImage += .2 * fiber;
+
+  vec3 lightPos = vec3(1., 2., 1.);
+  float res = dot(normalize(vec3(normal, 9.5 - 9. * pow(u_contrast, .1))), normalize(lightPos));
+
+  vec3 fgColor = u_colorFront.rgb * u_colorFront.a;
+  float fgOpacity = u_colorFront.a;
+  vec3 bgColor = u_colorBack.rgb * u_colorBack.a;
+  float bgOpacity = u_colorBack.a;
+
+  imageUV += .02 * normalImage;
+  float frame = getUvFrame(imageUV);
+  vec4 image = texture(u_image, imageUV);
+  image.rgb += .6 * pow(u_contrast, .4) * (res - .7);
+  frame *= image.a;
+
+  vec3 color = fgColor * res;
+  float opacity = fgOpacity * res;
+  color += bgColor * (1. - opacity);
+  opacity += bgOpacity * (1. - opacity);
+  opacity = mix(opacity, 1., frame);
+
+  color.rgb = mix(color, image.rgb, frame);
+
+  fragColor = vec4(color, opacity);
+}
+`;
+
+export { paperTextureFragmentShader };

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

@@ -0,0 +1,19 @@
+import type React from "react";
+import type { ShaderTextureSource } from "../shared";
+export interface PaperTextureProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Source image (URL or an existing HTMLImageElement). Required. */
+    image: ShaderTextureSource;
+    /** Shadow-side color mixed into the paper-grain lighting. Default: 'var(--color-text-primary)'. */
+    colorFront?: string;
+    /** Highlight-side color mixed into the paper-grain lighting. Default: 'var(--color-background)'. */
+    colorBack?: string;
+    /** Lighting contrast, 0-1+. Default: 0.5. */
+    contrast?: number;
+    /** Fine paper roughness strength, 0-1+. Default: 0.5. */
+    roughness?: number;
+    /** Fiber streak strength, 0-1+. Default: 0.5. */
+    fiber?: number;
+    /** Fiber streak scale. Default: 1. */
+    fiberSize?: number;
+    className?: string;
+}

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

@@ -0,0 +1,2 @@
+export { PaperTexture } from "./PaperTexture";
+export type { PaperTextureProps } from "./PaperTexture.types";

package/dist/components/effects/Particles/Particles.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { Canvas } from '@react-three/fiber';
 import { useReducedMotion } from 'motion/react';

package/dist/components/effects/Particles/Particles.scene.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import { useRef, useMemo, useEffect, useCallback } from 'react';
 import { useThree, useFrame } from '@react-three/fiber';

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,120 @@
+"use client";
+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';

package/dist/components/effects/ProgressiveBlur/ProgressiveBlur.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx, Fragment } from 'react/jsx-runtime';
 import { forwardRef, useMemo } from 'react';
 import { cn } from '../../../utils/cn.js';
@@ -24,27 +25,27 @@ const GRADIENT_DIRECTIONS = {
  */
 const BlurInstance = forwardRef(({ position, blurLevels, size, theme, className, style, ...rest }, ref) => {
     const isVertical = position === "top" || position === "bottom";
-    const direction = GRADIENT_DIRECTIONS[position];
-    const n = blurLevels.length;
-    const containerStyle = {
-        ...(isVertical ? { height: size } : { width: size }),
-        ...style,
-    };
-    return (jsx("div", { ref: ref, className: cn(theme.baseStyle, theme.positions[position], className), style: containerStyle, ...rest, children: blurLevels.map((blur, i) => {
+    const layerStyles = useMemo(() => {
+        const direction = GRADIENT_DIRECTIONS[position];
+        const step = 100 / blurLevels.length;
+        return blurLevels.map((blur, i) => {
             // MagicUI mask formula: each layer has a 1-step fade-in, 1-step solid,
             // and 1-step fade-out. Adjacent layers overlap by 2 steps, creating
             // smooth transitions. Values beyond 100% are clamped by the browser.
-            const step = 100 / n;
             const gradient = `linear-gradient(${direction}, transparent ${i * step}%, black ${(i + 1) * step}%, black ${(i + 2) * step}%, transparent ${(i + 3) * step}%)`;
-            const layerStyle = {
+            return {
                 maskImage: gradient,
                 WebkitMaskImage: gradient,
                 backdropFilter: `blur(${blur}px)`,
                 WebkitBackdropFilter: `blur(${blur}px)`,
-                zIndex: i + 1,
             };
-            return (jsx("div", { className: theme.layerStyle, style: layerStyle }, i));
-        }) }));
+        });
+    }, [position, blurLevels]);
+    const containerStyle = {
+        ...(isVertical ? { height: size } : { width: size }),
+        ...style,
+    };
+    return (jsx("div", { ref: ref, "aria-hidden": "true", className: cn(theme.baseStyle, theme.positions[position], className), style: containerStyle, ...rest, children: layerStyles.map((layerStyle, i) => (jsx("div", { className: theme.layerStyle, style: layerStyle }, i))) }));
 });
 BlurInstance.displayName = "BlurInstance";
 const ProgressiveBlur = forwardRef(({ position = "bottom", blurLevels: blurLevelsProp, layers = DEFAULT_LAYERS, blurIntensity = DEFAULT_MAX_BLUR, size = DEFAULT_SIZE, className, theme: themeOverrides, ...rest }, ref) => {
@@ -59,10 +60,21 @@ const ProgressiveBlur = forwardRef(({ position = "bottom", blurLevels: blurLevel
             layerStyle: (_b = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.layerStyle) !== null && _b !== void 0 ? _b : progressiveBlurTheme.layerStyle,
         });
     }, [themeOverrides]);
-    const blurLevels = useMemo(() => blurLevelsProp !== null && blurLevelsProp !== void 0 ? blurLevelsProp : generateBlurLevels(layers, blurIntensity), [blurLevelsProp, layers, blurIntensity]);
+    const blurLevels = useMemo(() => {
+        if (blurLevelsProp)
+            return blurLevelsProp;
+        const count = Math.max(1, Math.floor(layers));
+        if (process.env.NODE_ENV !== "production" && count !== layers) {
+            console.warn(`[ProgressiveBlur]: \`layers\` must be a positive integer; received ${layers}, using ${count}.`);
+        }
+        return generateBlurLevels(count, blurIntensity);
+    }, [blurLevelsProp, layers, blurIntensity]);
     const positions = Array.isArray(position)
-        ? position
+        ? Array.from(new Set(position))
         : [position];
+    if (process.env.NODE_ENV !== "production" && ref && positions.length > 1) {
+        console.warn("[ProgressiveBlur]: `ref` is ignored when `position` is an array — render one ProgressiveBlur per position if you need element refs.");
+    }
     // Single position — render directly, forward ref and remaining props
     if (positions.length === 1) {
         return (jsx(BlurInstance, { ref: ref, position: positions[0], blurLevels: blurLevels, size: size, theme: theme, className: className, ...rest }));

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

@@ -4,6 +4,8 @@ export interface ProgressiveBlurProps extends React.HTMLAttributes<HTMLDivElemen
     /**
      * Position(s) where the blur effect should be applied.
      * Can be a single position or array of positions.
+     * With an array, one element renders per position, so `ref` is not
+     * forwarded and `id`/event props apply to every instance.
      * @default "bottom"
      */
     position?: ProgressiveBlurPosition | ProgressiveBlurPosition[];