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

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

@@ -0,0 +1,75 @@
+import { jsx, Fragment } from 'react/jsx-runtime';
+import { forwardRef, useMemo } from 'react';
+import { cn } from '../../../utils/cn.js';
+import { progressiveBlurTheme } from './ProgressiveBlur.theme.js';
+
+const DEFAULT_LAYERS = 8;
+const DEFAULT_MAX_BLUR = 64;
+const DEFAULT_SIZE = "30%";
+/**
+ * Generate exponentially distributed blur levels (powers of 2).
+ * e.g. for 8 layers with max 64: [0.5, 1, 2, 4, 8, 16, 32, 64]
+ */
+function generateBlurLevels(layers, maxBlur) {
+    return Array.from({ length: layers }, (_, i) => maxBlur * Math.pow(2, i - (layers - 1)));
+}
+const GRADIENT_DIRECTIONS = {
+    top: "to top",
+    bottom: "to bottom",
+    left: "to left",
+    right: "to right",
+};
+/**
+ * Renders a single blur instance for one position.
+ */
+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) => {
+            // 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 = {
+                maskImage: gradient,
+                WebkitMaskImage: gradient,
+                backdropFilter: `blur(${blur}px)`,
+                WebkitBackdropFilter: `blur(${blur}px)`,
+                zIndex: i + 1,
+            };
+            return (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) => {
+    const theme = useMemo(() => {
+        var _a, _b;
+        return ({
+            baseStyle: (_a = themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.baseStyle) !== null && _a !== void 0 ? _a : progressiveBlurTheme.baseStyle,
+            positions: {
+                ...progressiveBlurTheme.positions,
+                ...themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.positions,
+            },
+            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 positions = Array.isArray(position)
+        ? position
+        : [position];
+    // 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 }));
+    }
+    // Multiple positions — render one BlurInstance per position
+    return (jsx(Fragment, { children: positions.map((pos) => (jsx(BlurInstance, { position: pos, blurLevels: blurLevels, size: size, theme: theme, className: className, ...rest }, pos))) }));
+});
+ProgressiveBlur.displayName = "ProgressiveBlur";
+
+export { ProgressiveBlur };

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

@@ -0,0 +1,7 @@
+import type { ProgressiveBlurPosition } from "./ProgressiveBlur.types";
+export interface ProgressiveBlurTheme {
+    baseStyle: string;
+    positions: Record<ProgressiveBlurPosition, string>;
+    layerStyle: string;
+}
+export declare const progressiveBlurTheme: ProgressiveBlurTheme;

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

@@ -0,0 +1,12 @@
+const progressiveBlurTheme = {
+    baseStyle: "absolute pointer-events-none z-10",
+    positions: {
+        top: "top-0 left-0 right-0",
+        bottom: "bottom-0 left-0 right-0",
+        left: "left-0 top-0 bottom-0",
+        right: "right-0 top-0 bottom-0",
+    },
+    layerStyle: "absolute inset-0",
+};
+
+export { progressiveBlurTheme };

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

@@ -0,0 +1,47 @@
+import React from "react";
+export type ProgressiveBlurPosition = "top" | "bottom" | "left" | "right";
+export interface ProgressiveBlurProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Position(s) where the blur effect should be applied.
+     * Can be a single position or array of positions.
+     * @default "bottom"
+     */
+    position?: ProgressiveBlurPosition | ProgressiveBlurPosition[];
+    /**
+     * Custom blur levels array (in pixels) for fine-grained control.
+     * If provided, overrides `layers` and `blurIntensity`.
+     * @example [0.5, 1, 2, 4, 8, 16, 32, 64]
+     */
+    blurLevels?: number[];
+    /**
+     * Number of blur layers to generate.
+     * More layers = smoother gradient, but more DOM nodes.
+     * Ignored if `blurLevels` is provided.
+     * @default 8
+     */
+    layers?: number;
+    /**
+     * Maximum blur value in pixels for auto-generated levels.
+     * Ignored if `blurLevels` is provided.
+     * @default 64
+     */
+    blurIntensity?: number;
+    /**
+     * Size of the blur region.
+     * Height for top/bottom positions, width for left/right positions.
+     * @default "30%"
+     */
+    size?: string;
+    /** Custom className for styling overrides */
+    className?: string;
+    /** Theme overrides */
+    theme?: ProgressiveBlurThemeOverrides;
+}
+export interface ProgressiveBlurThemeOverrides {
+    /** Base styles for each blur instance container */
+    baseStyle?: string;
+    /** Position-specific styles */
+    positions?: Partial<Record<ProgressiveBlurPosition, string>>;
+    /** Styles for each individual blur layer div */
+    layerStyle?: string;
+}

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

@@ -0,0 +1,2 @@
+export { ProgressiveBlur } from "./ProgressiveBlur";
+export type { ProgressiveBlurProps, ProgressiveBlurPosition, ProgressiveBlurThemeOverrides, } from "./ProgressiveBlur.types";

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

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { ScrollRevealProps } from './ScrollReveal.types';
+/**
+ * ScrollReveal
+ *
+ * Intersection-observer wrapper that triggers an entrance animation when
+ * its children scroll into the viewport.
+ *
+ * Supports six built-in presets, custom variants, stagger-children timing,
+ * and respects the `prefers-reduced-motion` media query.
+ *
+ * @example
+ * ```tsx
+ * <ScrollReveal preset="fadeUp">
+ *   <h2>Hello world</h2>
+ * </ScrollReveal>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Stagger children
+ * <ScrollReveal preset="fadeUp" stagger={0.12}>
+ *   <Card />
+ *   <Card />
+ *   <Card />
+ * </ScrollReveal>
+ * ```
+ */
+export declare const ScrollReveal: React.ForwardRefExoticComponent<ScrollRevealProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/effects/ScrollReveal/ScrollReveal.js

@@ -0,0 +1,121 @@
+import { jsx } from 'react/jsx-runtime';
+import React__default, { useRef } from 'react';
+import { useReducedMotion, useInView, motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+
+/* ------------------------------------------------------------------ */
+/*  Animation presets                                                   */
+/* ------------------------------------------------------------------ */
+const PRESET_VARIANTS = {
+    fadeUp: {
+        hidden: { opacity: 0, y: 32 },
+        visible: { opacity: 1, y: 0 },
+    },
+    fadeDown: {
+        hidden: { opacity: 0, y: -32 },
+        visible: { opacity: 1, y: 0 },
+    },
+    fadeLeft: {
+        hidden: { opacity: 0, x: -32 },
+        visible: { opacity: 1, x: 0 },
+    },
+    fadeRight: {
+        hidden: { opacity: 0, x: 32 },
+        visible: { opacity: 1, x: 0 },
+    },
+    scaleUp: {
+        hidden: { opacity: 0, scale: 0.85 },
+        visible: { opacity: 1, scale: 1 },
+    },
+    blur: {
+        hidden: { opacity: 0, filter: 'blur(8px)' },
+        visible: { opacity: 1, filter: 'blur(0px)' },
+    },
+};
+/* ------------------------------------------------------------------ */
+/*  Component                                                           */
+/* ------------------------------------------------------------------ */
+/**
+ * ScrollReveal
+ *
+ * Intersection-observer wrapper that triggers an entrance animation when
+ * its children scroll into the viewport.
+ *
+ * Supports six built-in presets, custom variants, stagger-children timing,
+ * and respects the `prefers-reduced-motion` media query.
+ *
+ * @example
+ * ```tsx
+ * <ScrollReveal preset="fadeUp">
+ *   <h2>Hello world</h2>
+ * </ScrollReveal>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Stagger children
+ * <ScrollReveal preset="fadeUp" stagger={0.12}>
+ *   <Card />
+ *   <Card />
+ *   <Card />
+ * </ScrollReveal>
+ * ```
+ */
+const ScrollReveal = React__default.forwardRef(({ preset = 'fadeUp', variants: customVariants, threshold = 0.1, rootMargin = '0px 0px -50px 0px', once = true, delay = 0, duration = 0.6, stagger = 0, className, children, 
+// Destructure HTML event handlers that conflict with motion's API
+onDrag: _onDrag, onDragStart: _onDragStart, onDragEnd: _onDragEnd, onAnimationStart: _onAnimationStart, ...restProps }, ref) => {
+    const shouldReduceMotion = useReducedMotion();
+    const internalRef = useRef(null);
+    const isInView = useInView(internalRef, {
+        once,
+        amount: threshold,
+        margin: rootMargin,
+    });
+    // When reduced motion is preferred, render content immediately.
+    if (shouldReduceMotion) {
+        return (jsx("div", { ref: (node) => {
+                internalRef.current = node;
+                if (typeof ref === 'function')
+                    ref(node);
+                else if (ref)
+                    ref.current = node;
+            }, className: className, ...restProps, children: children }));
+    }
+    // Build variants --------------------------------------------------
+    const presetData = customVariants !== null && customVariants !== void 0 ? customVariants : PRESET_VARIANTS[preset];
+    const motionVariants = {
+        hidden: presetData.hidden,
+        visible: {
+            ...presetData.visible,
+            transition: {
+                duration,
+                delay,
+                ease: [0.25, 0.1, 0.25, 1], // cubic-bezier easeOut
+                ...(stagger > 0
+                    ? { staggerChildren: stagger, delayChildren: delay }
+                    : {}),
+            },
+        },
+    };
+    // When stagger is used, each direct child needs to be a motion element.
+    // We wrap each child in a motion.div that inherits parent variants.
+    const content = stagger > 0
+        ? React__default.Children.map(children, (child) => (jsx(motion.div, { variants: {
+                hidden: presetData.hidden,
+                visible: {
+                    ...presetData.visible,
+                    transition: { duration, ease: [0.25, 0.1, 0.25, 1] },
+                },
+            }, children: child })))
+        : children;
+    return (jsx(motion.div, { ref: (node) => {
+            internalRef.current = node;
+            if (typeof ref === 'function')
+                ref(node);
+            else if (ref)
+                ref.current = node;
+        }, className: cn(className), variants: motionVariants, initial: "hidden", animate: isInView ? 'visible' : 'hidden', ...restProps, children: content }));
+});
+ScrollReveal.displayName = 'ScrollReveal';
+
+export { ScrollReveal };

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

@@ -0,0 +1,25 @@
+import type { Variants } from 'motion/react';
+export type ScrollRevealPreset = 'fadeUp' | 'fadeDown' | 'fadeLeft' | 'fadeRight' | 'scaleUp' | 'blur';
+export interface ScrollRevealProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Animation preset (default 'fadeUp') */
+    preset?: ScrollRevealPreset;
+    /** Custom animation variants (overrides preset) */
+    variants?: {
+        hidden: Variants['hidden'];
+        visible: Variants['visible'];
+    };
+    /** Intersection threshold 0-1 (default 0.1) */
+    threshold?: number;
+    /** Root margin for early/late triggering (default '0px 0px -50px 0px') */
+    rootMargin?: string;
+    /** Only animate once (default true) */
+    once?: boolean;
+    /** Animation delay in seconds (default 0) */
+    delay?: number;
+    /** Animation duration in seconds (default 0.6) */
+    duration?: number;
+    /** Stagger children by this amount in seconds (default 0) */
+    stagger?: number;
+    className?: string;
+    children: React.ReactNode;
+}

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

@@ -0,0 +1,2 @@
+export { ScrollReveal } from './ScrollReveal';
+export type { ScrollRevealProps, ScrollRevealPreset, } from './ScrollReveal.types';

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

@@ -0,0 +1,36 @@
+import React from "react";
+import type { SpotlightProps } from "./Spotlight.types";
+/**
+ * Spotlight Component
+ *
+ * A mouse-following radial gradient that creates a subtle surface illumination
+ * effect. Tracks the mouse position within the parent element and renders a
+ * smooth, animated glow that follows the cursor.
+ *
+ * The parent container should have `position: relative` and `overflow: hidden`.
+ *
+ * Unlike SpotlightBorder (which highlights borders), this component illuminates
+ * the surface area itself with a soft radial gradient.
+ *
+ * @example
+ * ```tsx
+ * <div className="relative overflow-hidden bg-gray-900 rounded-lg p-8">
+ *   <Spotlight color="var(--color-primary)" intensity={0.2} />
+ *   <span className="relative z-10">Hover over me</span>
+ * </div>
+ * ```
+ *
+ * @example Custom spring and size
+ * ```tsx
+ * <div className="relative overflow-hidden bg-slate-800 rounded-xl p-12">
+ *   <Spotlight
+ *     size={500}
+ *     color="#8b5cf6"
+ *     intensity={0.25}
+ *     springConfig={{ damping: 20, stiffness: 150 }}
+ *   />
+ *   <h2 className="relative z-10 text-white">Interactive card</h2>
+ * </div>
+ * ```
+ */
+export declare const Spotlight: React.FC<SpotlightProps>;

package/dist/components/effects/Spotlight/Spotlight.js

@@ -0,0 +1,112 @@
+import { jsx } from 'react/jsx-runtime';
+import { useRef, useState, useCallback } from 'react';
+import { useReducedMotion, useMotionValue, useSpring, motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+
+/**
+ * Spotlight Component
+ *
+ * A mouse-following radial gradient that creates a subtle surface illumination
+ * effect. Tracks the mouse position within the parent element and renders a
+ * smooth, animated glow that follows the cursor.
+ *
+ * The parent container should have `position: relative` and `overflow: hidden`.
+ *
+ * Unlike SpotlightBorder (which highlights borders), this component illuminates
+ * the surface area itself with a soft radial gradient.
+ *
+ * @example
+ * ```tsx
+ * <div className="relative overflow-hidden bg-gray-900 rounded-lg p-8">
+ *   <Spotlight color="var(--color-primary)" intensity={0.2} />
+ *   <span className="relative z-10">Hover over me</span>
+ * </div>
+ * ```
+ *
+ * @example Custom spring and size
+ * ```tsx
+ * <div className="relative overflow-hidden bg-slate-800 rounded-xl p-12">
+ *   <Spotlight
+ *     size={500}
+ *     color="#8b5cf6"
+ *     intensity={0.25}
+ *     springConfig={{ damping: 20, stiffness: 150 }}
+ *   />
+ *   <h2 className="relative z-10 text-white">Interactive card</h2>
+ * </div>
+ * ```
+ */
+const Spotlight = ({ size = 300, color = "var(--color-primary)", intensity = 0.15, springConfig = { damping: 30, stiffness: 200 }, className, style, ...props }) => {
+    var _a, _b, _c, _d;
+    const shouldReduceMotion = useReducedMotion();
+    const containerRef = useRef(null);
+    const [isHovered, setIsHovered] = useState(false);
+    // Raw mouse position motion values
+    const mouseX = useMotionValue(0);
+    const mouseY = useMotionValue(0);
+    // Spring-animated values for smooth following
+    const springX = useSpring(mouseX, {
+        damping: (_a = springConfig.damping) !== null && _a !== void 0 ? _a : 30,
+        stiffness: (_b = springConfig.stiffness) !== null && _b !== void 0 ? _b : 200,
+    });
+    const springY = useSpring(mouseY, {
+        damping: (_c = springConfig.damping) !== null && _c !== void 0 ? _c : 30,
+        stiffness: (_d = springConfig.stiffness) !== null && _d !== void 0 ? _d : 200,
+    });
+    // Use raw values when reduced motion is preferred
+    const x = shouldReduceMotion ? mouseX : springX;
+    const y = shouldReduceMotion ? mouseY : springY;
+    const handleMouseMove = useCallback((event) => {
+        var _a;
+        const parent = (_a = containerRef.current) === null || _a === void 0 ? void 0 : _a.parentElement;
+        if (!parent)
+            return;
+        const rect = parent.getBoundingClientRect();
+        mouseX.set(event.clientX - rect.left);
+        mouseY.set(event.clientY - rect.top);
+    }, [mouseX, mouseY]);
+    const handleMouseEnter = useCallback((event) => {
+        var _a;
+        // Set position immediately on enter to avoid animating from origin
+        const parent = (_a = containerRef.current) === null || _a === void 0 ? void 0 : _a.parentElement;
+        if (parent) {
+            const rect = parent.getBoundingClientRect();
+            const posX = event.clientX - rect.left;
+            const posY = event.clientY - rect.top;
+            mouseX.set(posX);
+            mouseY.set(posY);
+            // Jump springs to current position to avoid initial slide-in
+            if (!shouldReduceMotion) {
+                springX.jump(posX);
+                springY.jump(posY);
+            }
+        }
+        setIsHovered(true);
+    }, [mouseX, mouseY, springX, springY, shouldReduceMotion]);
+    const handleMouseLeave = useCallback(() => {
+        setIsHovered(false);
+    }, []);
+    const halfSize = size / 2;
+    return (jsx("div", { ref: containerRef, className: cn("absolute inset-0 pointer-events-none", className), style: {
+            // Re-enable pointer events so we can track mouse within this layer.
+            // The layer itself is visually transparent to interaction.
+            pointerEvents: "auto",
+            ...style,
+        }, onMouseMove: handleMouseMove, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, "aria-hidden": "true", ...props, children: jsx(motion.div, { className: "absolute pointer-events-none", style: {
+                width: size,
+                height: size,
+                borderRadius: "50%",
+                x,
+                y,
+                marginLeft: -halfSize,
+                marginTop: -halfSize,
+                background: `radial-gradient(circle at center, ${color}, transparent 70%)`,
+                opacity: isHovered ? intensity : 0,
+                transition: shouldReduceMotion
+                    ? "opacity 0s"
+                    : "opacity 0.3s ease-in-out",
+            } }) }));
+};
+Spotlight.displayName = "Spotlight";
+
+export { Spotlight };

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

@@ -0,0 +1,29 @@
+import React from "react";
+export interface SpotlightProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Diameter of the spotlight glow in pixels.
+     * @default 300
+     */
+    size?: number;
+    /**
+     * Color of the spotlight glow.
+     * Accepts any valid CSS color value or CSS variable reference.
+     * @default "var(--color-primary)"
+     */
+    color?: string;
+    /**
+     * Peak opacity of the spotlight glow (0-1).
+     * @default 0.15
+     */
+    intensity?: number;
+    /**
+     * Spring animation configuration for the mouse-following behavior.
+     * @default { damping: 30, stiffness: 200 }
+     */
+    springConfig?: {
+        damping?: number;
+        stiffness?: number;
+    };
+    /** Additional className for style overrides (shadcn pattern). */
+    className?: string;
+}

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

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

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

@@ -0,0 +1,30 @@
+import React from 'react';
+import type { StickyScrollProps } from './StickyScroll.types';
+/**
+ * StickyScroll
+ *
+ * Creates an Apple-style sticky scroll experience where one column stays
+ * pinned while the other scrolls.  As each scrolling section enters the
+ * viewport, the sticky content transitions to match.
+ *
+ * @example
+ * ```tsx
+ * <StickyScroll
+ *   sections={[
+ *     {
+ *       id: 'design',
+ *       title: 'Design System',
+ *       description: 'Build consistent interfaces with a shared design language.',
+ *       content: <img src="/design.png" alt="Design system" />,
+ *     },
+ *     {
+ *       id: 'develop',
+ *       title: 'Developer Experience',
+ *       description: 'TypeScript-first components with full IntelliSense.',
+ *       content: <img src="/develop.png" alt="Developer experience" />,
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+export declare const StickyScroll: React.ForwardRefExoticComponent<StickyScrollProps & React.RefAttributes<HTMLDivElement>>;