@flikk/ui 1.0.0-beta.2 → 1.0.0-beta.21

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

@@ -0,0 +1,2 @@
+export { Aurora } from './Aurora';
+export type { AuroraProps } from './Aurora.types';

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

@@ -1,5 +1,5 @@
-import * as React from 'react';
-import type { CustomCursorContextType, CustomCursorProviderProps, CustomCursorProps, CustomCursorFollowProps } from './CustomCursor.types';
+import * as React from "react";
+import type { CustomCursorContextType, CustomCursorProviderProps, CustomCursorProps, CustomCursorFollowProps } from "./CustomCursor.types";
 /**
  * Hook to access CustomCursor context
  * @throws Error if used outside CustomCursorProvider
@@ -31,5 +31,5 @@ export declare const CustomCursorProvider: React.ForwardRefExoticComponent<Omit<
  * </CustomCursor>
  * ```
  */
-export declare const CustomCursor: React.ForwardRefExoticComponent<Omit<CustomCursorProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export declare const CustomCursorFollow: React.ForwardRefExoticComponent<Omit<CustomCursorFollowProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const CustomCursor: React.ForwardRefExoticComponent<CustomCursorProps & React.RefAttributes<HTMLDivElement>>;
+export declare const CustomCursorFollow: React.ForwardRefExoticComponent<CustomCursorFollowProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/effects/CustomCursor/CustomCursor.js

@@ -18,7 +18,7 @@ const CustomCursorContext = React.createContext(undefined);
 const useCustomCursor = () => {
     const context = React.useContext(CustomCursorContext);
     if (!context) {
-        throw new Error('useCustomCursor must be used within a CustomCursorProvider');
+        throw new Error("useCustomCursor must be used within a CustomCursorProvider");
     }
     return context;
 };
@@ -36,7 +36,7 @@ const useCustomCursor = () => {
  * </CustomCursorProvider>
  * ```
  */
-const CustomCursorProvider = React.forwardRef(({ children, className, allowedPointerTypes = ['mouse'], ...props }, ref) => {
+const CustomCursorProvider = React.forwardRef(({ children, className, allowedPointerTypes = ["mouse"], ...props }, ref) => {
     const [cursorPos, setCursorPos] = React.useState({ x: 0, y: 0 });
     const [isActive, setIsActive] = React.useState(false);
     const containerRef = React.useRef(null);
@@ -52,12 +52,13 @@ const CustomCursorProvider = React.forwardRef(({ children, className, allowedPoi
         // Ensure parent has positioning context for absolute children
         const computedPosition = getComputedStyle(parent).position;
         const previousInlinePosition = parent.style.position;
-        const shouldOverridePosition = computedPosition === 'static';
+        const shouldOverridePosition = computedPosition === "static";
         if (shouldOverridePosition) {
-            parent.style.position = 'relative';
+            parent.style.position = "relative";
         }
         const handlePointerMove = (event) => {
-            const pointerType = (event.pointerType || 'mouse');
+            const pointerType = (event.pointerType ||
+                "mouse");
             if (!allowedPointerTypesSet.has(pointerType))
                 return;
             const rect = parent.getBoundingClientRect();
@@ -69,7 +70,8 @@ const CustomCursorProvider = React.forwardRef(({ children, className, allowedPoi
             setIsActive(true);
         };
         const handlePointerLeave = (event) => {
-            const pointerType = (event.pointerType || 'mouse');
+            const pointerType = (event.pointerType ||
+                "mouse");
             if (!allowedPointerTypesSet.has(pointerType))
                 return;
             setIsActive(false);
@@ -85,23 +87,23 @@ const CustomCursorProvider = React.forwardRef(({ children, className, allowedPoi
         const handleMouseLeave = () => {
             setIsActive(false);
         };
-        const supportsPointerEvents = typeof window !== 'undefined' && 'PointerEvent' in window;
+        const supportsPointerEvents = typeof window !== "undefined" && "PointerEvent" in window;
         if (supportsPointerEvents) {
-            parent.addEventListener('pointermove', handlePointerMove);
-            parent.addEventListener('pointerleave', handlePointerLeave);
+            parent.addEventListener("pointermove", handlePointerMove);
+            parent.addEventListener("pointerleave", handlePointerLeave);
         }
         else {
-            parent.addEventListener('mousemove', handleMouseMove);
-            parent.addEventListener('mouseleave', handleMouseLeave);
+            parent.addEventListener("mousemove", handleMouseMove);
+            parent.addEventListener("mouseleave", handleMouseLeave);
         }
         return () => {
             if (supportsPointerEvents) {
-                parent.removeEventListener('pointermove', handlePointerMove);
-                parent.removeEventListener('pointerleave', handlePointerLeave);
+                parent.removeEventListener("pointermove", handlePointerMove);
+                parent.removeEventListener("pointerleave", handlePointerLeave);
             }
             else {
-                parent.removeEventListener('mousemove', handleMouseMove);
-                parent.removeEventListener('mouseleave', handleMouseLeave);
+                parent.removeEventListener("mousemove", handleMouseMove);
+                parent.removeEventListener("mouseleave", handleMouseLeave);
             }
             if (shouldOverridePosition) {
                 parent.style.position = previousInlinePosition;
@@ -111,7 +113,7 @@ const CustomCursorProvider = React.forwardRef(({ children, className, allowedPoi
     const contextValue = React.useMemo(() => ({ cursorPos, isActive, containerRef, cursorRef }), [cursorPos, isActive]);
     return (jsx(CustomCursorContext.Provider, { value: contextValue, children: jsx("div", { ref: containerRef, "data-slot": "custom-cursor-provider", className: className, ...props, children: children }) }));
 });
-CustomCursorProvider.displayName = 'CustomCursorProvider';
+CustomCursorProvider.displayName = "CustomCursorProvider";
 /**
  * CustomCursor - Main cursor element component
  * Follows mouse position exactly with instant movement
@@ -123,7 +125,7 @@ CustomCursorProvider.displayName = 'CustomCursorProvider';
  * </CustomCursor>
  * ```
  */
-const CustomCursor = React.forwardRef(({ children, size = 'md', color = 'primary', variant = 'default', shape = 'arrow', className, style, ...props }, ref) => {
+const CustomCursor = React.forwardRef(({ children, size = "md", color = "primary", variant = "default", shape = "arrow", className, style, onAnimationStart: _onAnimationStart, onAnimationEnd: _onAnimationEnd, onDrag: _onDrag, onDragStart: _onDragStart, onDragEnd: _onDragEnd, ...props }, ref) => {
     const { cursorPos, isActive, containerRef, cursorRef } = useCustomCursor();
     React.useImperativeHandle(ref, () => cursorRef.current);
     const x = useMotionValue(0);
@@ -136,7 +138,7 @@ const CustomCursor = React.forwardRef(({ children, size = 'md', color = 'primary
             return;
         }
         const previousInlineCursor = parentElement.style.cursor;
-        parentElement.style.cursor = 'none';
+        parentElement.style.cursor = "none";
         return () => {
             parentElement.style.cursor = previousInlineCursor;
         };
@@ -147,32 +149,32 @@ const CustomCursor = React.forwardRef(({ children, size = 'md', color = 'primary
         y.set(cursorPos.y);
     }, [cursorPos, x, y]);
     // Default content based on shape
-    const defaultContent = shape === 'arrow' ? (jsx(PaperAirplaneIcon, { className: "w-full h-full rotate-180" })) : (jsx("div", { className: "w-full h-full" }));
+    const defaultContent = shape === "arrow" ? (jsx(PaperAirplaneIcon, { className: "w-full h-full rotate-180" })) : (jsx("div", { className: "w-full h-full" }));
     return (jsx(AnimatePresence, { children: isActive && (jsx(motion.div, { ref: cursorRef, "data-slot": "custom-cursor", className: cn(customCursorTheme.baseStyle, customCursorTheme.cursorStyle, customCursorTheme.sizes[size], customCursorTheme.colors[color], customCursorTheme.variants[variant], customCursorTheme.shapes[shape], className), style: { top: y, left: x, ...style }, variants: customCursorVariants, initial: "initial", animate: "animate", exit: "exit", role: "presentation", "aria-hidden": "true", ...props, children: children || defaultContent })) }));
 });
-CustomCursor.displayName = 'CustomCursor';
+CustomCursor.displayName = "CustomCursor";
 /**
  * Calculate offset based on alignment and element dimensions
  */
 const calculateOffset = (align, sideOffset, width, height) => {
     switch (align) {
-        case 'center':
+        case "center":
             return { x: width / 2, y: height / 2 };
-        case 'top':
+        case "top":
             return { x: width / 2, y: height + sideOffset };
-        case 'top-left':
+        case "top-left":
             return { x: width + sideOffset, y: height + sideOffset };
-        case 'top-right':
+        case "top-right":
             return { x: -sideOffset, y: height + sideOffset };
-        case 'bottom':
+        case "bottom":
             return { x: width / 2, y: -sideOffset };
-        case 'bottom-left':
+        case "bottom-left":
             return { x: width + sideOffset, y: -sideOffset };
-        case 'bottom-right':
+        case "bottom-right":
             return { x: -sideOffset, y: -sideOffset };
-        case 'left':
+        case "left":
             return { x: width + sideOffset, y: height / 2 };
-        case 'right':
+        case "right":
             return { x: -sideOffset, y: height / 2 };
         default:
             return { x: 0, y: 0 };
@@ -193,12 +195,12 @@ const calculateOffset = (align, sideOffset, width, height) => {
  */
 /** Available colors for random selection in user variant */
 const userVariantColors = [
-    'primary',
-    'success',
-    'warning',
-    'danger',
+    "primary",
+    "success",
+    "warning",
+    "danger",
 ];
-const CustomCursorFollow = React.forwardRef(({ children, sideOffset = 15, align = 'bottom-right', transition, variant = 'default', avatar, name, color, className, style, ...props }, ref) => {
+const CustomCursorFollow = React.forwardRef(({ children, sideOffset = 15, align = "bottom-right", transition, variant = "default", avatar, name, color, className, style, onAnimationStart: _onAnimationStart2, onAnimationEnd: _onAnimationEnd2, onDrag: _onDrag2, onDragStart: _onDragStart2, onDragEnd: _onDragEnd2, ...props }, ref) => {
     const { cursorPos, isActive, cursorRef } = useCustomCursor();
     const cursorFollowRef = React.useRef(null);
     const shouldReduceMotion = useReducedMotion();
@@ -223,7 +225,7 @@ const CustomCursorFollow = React.forwardRef(({ children, sideOffset = 15, align
     // Apply spring physics for smooth following
     const springConfig = shouldReduceMotion
         ? reducedMotionSpringConfig
-        : transition !== null && transition !== void 0 ? transition : defaultSpringConfig;
+        : (transition !== null && transition !== void 0 ? transition : defaultSpringConfig);
     const springX = useSpring(x, springConfig);
     const springY = useSpring(y, springConfig);
     // Track size changes on the follow element
@@ -244,14 +246,14 @@ const CustomCursorFollow = React.forwardRef(({ children, sideOffset = 15, align
         };
         updateDimensions();
         const cleanupFns = [];
-        if (typeof ResizeObserver !== 'undefined') {
+        if (typeof ResizeObserver !== "undefined") {
             const observer = new ResizeObserver(updateDimensions);
             observer.observe(followElement);
             cleanupFns.push(() => observer.disconnect());
         }
-        if (typeof window !== 'undefined') {
-            window.addEventListener('resize', updateDimensions);
-            cleanupFns.push(() => window.removeEventListener('resize', updateDimensions));
+        if (typeof window !== "undefined") {
+            window.addEventListener("resize", updateDimensions);
+            cleanupFns.push(() => window.removeEventListener("resize", updateDimensions));
         }
         return () => {
             cleanupFns.forEach((cleanup) => cleanup());
@@ -275,14 +277,14 @@ const CustomCursorFollow = React.forwardRef(({ children, sideOffset = 15, align
         };
         updateCursorDimensions();
         const cleanupFns = [];
-        if (typeof ResizeObserver !== 'undefined') {
+        if (typeof ResizeObserver !== "undefined") {
             const observer = new ResizeObserver(updateCursorDimensions);
             observer.observe(cursorElement);
             cleanupFns.push(() => observer.disconnect());
         }
-        if (typeof window !== 'undefined') {
-            window.addEventListener('resize', updateCursorDimensions);
-            cleanupFns.push(() => window.removeEventListener('resize', updateCursorDimensions));
+        if (typeof window !== "undefined") {
+            window.addEventListener("resize", updateCursorDimensions);
+            cleanupFns.push(() => window.removeEventListener("resize", updateCursorDimensions));
         }
         return () => {
             cleanupFns.forEach((cleanup) => cleanup());
@@ -311,13 +313,14 @@ const CustomCursorFollow = React.forwardRef(({ children, sideOffset = 15, align
     ]);
     // Determine content based on variant
     const renderContent = () => {
-        if (variant === 'user') {
-            return (jsxs(Fragment, { children: [avatar && jsx(Avatar, { src: avatar, alt: name || 'User', size: "xs" }), name && (jsx("span", { className: "text-white text-xs font-medium whitespace-nowrap", children: name }))] }));
+        if (variant === "user") {
+            return (jsxs(Fragment, { children: [avatar && jsx(Avatar, { src: avatar, name: name || "User", size: "xs" }), name && (jsx("span", { className: "text-white text-sm font-medium whitespace-nowrap", children: name }))] }));
         }
         return children;
     };
-    return (jsx(AnimatePresence, { children: isActive && (jsx(motion.div, { ref: cursorFollowRef, "data-slot": "custom-cursor-follow", className: cn(customCursorTheme.baseStyle, customCursorTheme.cursorFollowVariants[variant], variant === 'user' && customCursorTheme.cursorFollowColors[resolvedColor], className), style: { top: springY, left: springX, ...style }, variants: customCursorVariants, initial: "initial", animate: "animate", exit: "exit", role: "presentation", "aria-hidden": "true", ...props, children: renderContent() })) }));
+    return (jsx(AnimatePresence, { children: isActive && (jsx(motion.div, { ref: cursorFollowRef, "data-slot": "custom-cursor-follow", className: cn(customCursorTheme.baseStyle, customCursorTheme.cursorFollowVariants[variant], variant === "user" &&
+                customCursorTheme.cursorFollowColors[resolvedColor], className), style: { top: springY, left: springX, ...style }, variants: customCursorVariants, initial: "initial", animate: "animate", exit: "exit", role: "presentation", "aria-hidden": "true", ...props, children: renderContent() })) }));
 });
-CustomCursorFollow.displayName = 'CustomCursorFollow';
+CustomCursorFollow.displayName = "CustomCursorFollow";
 
 export { CustomCursor, CustomCursorFollow, CustomCursorProvider, useCustomCursor };

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

@@ -6,13 +6,14 @@ const customCursorTheme = {
     baseStyle: "pointer-events-none z-[9999] absolute transform-[translate(-50%,-50%)]",
     cursorStyle: "transition-transform duration-150",
     cursorFollowVariants: {
-        default: "rounded-[var(--radius-base)] bg-white dark:bg-[var(--color-background-secondary)] shadow-lg border border-[var(--color-border)] px-3 py-2 text-sm text-[var(--color-text-primary)]",
+        default: "rounded-[var(--radius-base)] bg-white dark:bg-[var(--color-background-secondary)] shadow-lg border border-[var(--color-border)] px-3 py-2 text-base text-[var(--color-text-primary)]",
         user: "flex items-center gap-2 rounded-full pl-1 pr-3 py-1 shadow-xl",
     },
     cursorFollowColors: {
         neutral: "bg-[var(--color-background-secondary)]",
         dark: "bg-[var(--color-text-primary)]",
         primary: "bg-[var(--color-primary)]",
+        secondary: "bg-[var(--color-secondary)]",
         success: "bg-[var(--color-success)]",
         warning: "bg-[var(--color-warning)]",
         danger: "bg-[var(--color-danger)]",
@@ -26,6 +27,7 @@ const customCursorTheme = {
         neutral: "text-[var(--color-background-secondary)]",
         dark: "text-[var(--color-text-primary)]",
         primary: "text-[var(--color-primary)]",
+        secondary: "text-[var(--color-secondary)]",
         success: "text-[var(--color-success)]",
         warning: "text-[var(--color-warning)]",
         danger: "text-[var(--color-danger)]",

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

@@ -1,5 +1,6 @@
 import * as React from 'react';
-import type { HTMLMotionProps, SpringOptions } from 'motion/react';
+import type { SpringOptions } from 'motion/react';
+import { SemanticColor } from '../../../utils/colorUtils';
 /**
  * Alignment positions for CustomCursorFollow relative to the main cursor
  */
@@ -11,7 +12,7 @@ export type CustomCursorSize = 'sm' | 'md' | 'lg';
 /**
  * Color variants for the custom cursor
  */
-export type CustomCursorColor = 'neutral' | 'dark' | 'primary' | 'success' | 'warning' | 'danger';
+export type CustomCursorColor = SemanticColor | 'dark';
 /**
  * Visual variants for the custom cursor
  */
@@ -48,7 +49,7 @@ export interface CustomCursorProviderProps extends React.ComponentProps<'div'> {
 /**
  * Props for CustomCursor component
  */
-export interface CustomCursorProps extends HTMLMotionProps<'div'> {
+export interface CustomCursorProps extends React.HTMLAttributes<HTMLDivElement> {
     children?: React.ReactNode;
     size?: CustomCursorSize;
     color?: CustomCursorColor;
@@ -59,7 +60,7 @@ export interface CustomCursorProps extends HTMLMotionProps<'div'> {
 /**
  * Props for CustomCursorFollow component
  */
-export interface CustomCursorFollowProps extends HTMLMotionProps<'div'> {
+export interface CustomCursorFollowProps extends React.HTMLAttributes<HTMLDivElement> {
     children?: React.ReactNode;
     sideOffset?: number;
     align?: AlignType;

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

@@ -0,0 +1,18 @@
+import React from "react";
+import type { DotPatternProps } from "./DotPattern.types";
+/**
+ * DotPattern renders an SVG-based dot grid background pattern.
+ *
+ * Use it as an absolute-positioned decorative background inside a container
+ * with `position: relative`. The pattern is fully non-interactive
+ * (`pointer-events: none`) and sits at `z-index: 0` by default.
+ *
+ * @example
+ * ```tsx
+ * <div className="relative overflow-hidden h-96">
+ *   <DotPattern spacing={24} dotSize={1.5} fade animated />
+ *   <div className="relative z-10">Your content here</div>
+ * </div>
+ * ```
+ */
+export declare const DotPattern: React.ForwardRefExoticComponent<DotPatternProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,65 @@
+import { jsx, jsxs } from 'react/jsx-runtime';
+import React__default, { useId, useMemo } from 'react';
+import { useReducedMotion, motion } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+
+/**
+ * Build a CSS mask-image value for the given fade direction and size.
+ */
+function buildMaskImage(direction, fadeSize) {
+    const stop = Math.max(0, Math.min(100, fadeSize));
+    if (direction === "radial") {
+        return `radial-gradient(ellipse at center, black ${100 - stop}%, transparent 100%)`;
+    }
+    const directionMap = {
+        top: "to top",
+        bottom: "to bottom",
+        left: "to left",
+        right: "to right",
+    };
+    return `linear-gradient(${directionMap[direction]}, black ${100 - stop}%, transparent 100%)`;
+}
+/**
+ * DotPattern renders an SVG-based dot grid background pattern.
+ *
+ * Use it as an absolute-positioned decorative background inside a container
+ * with `position: relative`. The pattern is fully non-interactive
+ * (`pointer-events: none`) and sits at `z-index: 0` by default.
+ *
+ * @example
+ * ```tsx
+ * <div className="relative overflow-hidden h-96">
+ *   <DotPattern spacing={24} dotSize={1.5} fade animated />
+ *   <div className="relative z-10">Your content here</div>
+ * </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 patternId = useId();
+    const shouldReduceMotion = useReducedMotion();
+    const enableAnimation = animated && !shouldReduceMotion;
+    const maskImage = useMemo(() => (fade ? buildMaskImage(fadeDirection, fadeSize) : undefined), [fade, fadeDirection, fadeSize]);
+    const containerStyle = {
+        ...style,
+        ...(maskImage
+            ? {
+                maskImage,
+                WebkitMaskImage: maskImage,
+            }
+            : {}),
+    };
+    // Center the dot within each cell
+    const cx = spacing / 2;
+    const cy = spacing / 2;
+    const dotElement = enableAnimation ? (jsx(motion.circle, { cx: cx, cy: cy, r: dotSize, fill: color, animate: {
+            opacity: [0.4, 1, 0.4],
+        }, transition: {
+            duration: 4,
+            ease: "easeInOut",
+            repeat: Infinity,
+        } })) : (jsx("circle", { cx: cx, cy: cy, r: dotSize, fill: color }));
+    return (jsx("div", { ref: ref, className: cn("absolute inset-0 pointer-events-none z-0 overflow-hidden", className), style: containerStyle, ...rest, children: jsxs("svg", { "aria-hidden": "true", className: "absolute inset-0 w-full h-full", children: [jsx("defs", { children: jsx("pattern", { id: patternId, x: "0", y: "0", width: spacing, height: spacing, patternUnits: "userSpaceOnUse", children: dotElement }) }), jsx("rect", { width: "100%", height: "100%", fill: `url(#${patternId})` })] }) }));
+});
+DotPattern.displayName = "DotPattern";
+
+export { DotPattern };

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

@@ -0,0 +1,47 @@
+import React from "react";
+/** Direction for the fade gradient mask */
+export type DotPatternFadeDirection = "radial" | "top" | "bottom" | "left" | "right";
+export interface DotPatternProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Distance between dots in pixels (center to center).
+     * @default 20
+     */
+    spacing?: number;
+    /**
+     * Radius of each dot in pixels.
+     * @default 1
+     */
+    dotSize?: number;
+    /**
+     * Fill color of the dots.
+     * Accepts any valid CSS color value or CSS variable.
+     * @default "var(--color-border)"
+     */
+    color?: string;
+    /**
+     * Whether to apply a gradient mask that fades the pattern at the edges.
+     * @default true
+     */
+    fade?: boolean;
+    /**
+     * Direction of the fade gradient.
+     * - "radial" fades from center outward
+     * - "top" | "bottom" | "left" | "right" fades toward that edge
+     * @default "radial"
+     */
+    fadeDirection?: DotPatternFadeDirection;
+    /**
+     * Size of the fade area as a percentage (0-100).
+     * Higher values create a larger transparent region.
+     * @default 50
+     */
+    fadeSize?: number;
+    /**
+     * Whether to apply a subtle pulse animation to the dots.
+     * Respects prefers-reduced-motion automatically.
+     * @default false
+     */
+    animated?: boolean;
+    /** Additional className for style overrides (shadcn pattern). */
+    className?: string;
+}

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

@@ -0,0 +1,2 @@
+export { DotPattern } from "./DotPattern";
+export type { DotPatternProps, DotPatternFadeDirection, } from "./DotPattern.types";

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

@@ -5,4 +5,4 @@ import { GlassSurfaceProps } from "./GlassSurface.types";
  * Creates a realistic chromatic aberration glass effect using SVG filters.
  * Works as a wrapper for any content.
  */
-export declare const GlassSurface: React.FC<GlassSurfaceProps>;
+export declare const GlassSurface: React.ForwardRefExoticComponent<GlassSurfaceProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/effects/GlassSurface/GlassSurface.js

@@ -1,5 +1,5 @@
 import { jsxs, jsx } from 'react/jsx-runtime';
-import { useId, useState, useRef, useMemo, useEffect } from 'react';
+import React__default, { useId, useState, useRef, useMemo, useEffect, useCallback } from 'react';
 import { cn } from '../../../utils/cn.js';
 
 /**
@@ -23,7 +23,7 @@ const useDarkMode = () => {
  * Creates a realistic chromatic aberration glass effect using SVG filters.
  * Works as a wrapper for any content.
  */
-const GlassSurface = ({ children, width, height, borderRadius = 20, borderWidth = 0.07, brightness = 50, opacity = 0.93, blur = 11, displace = 0.7, backgroundOpacity = 0.1, backgroundColor, saturation = 1.8, distortionScale = -180, redOffset = 0, greenOffset = 10, blueOffset = 20, xChannel = "R", yChannel = "G", mixBlendMode = "difference", frosted = false, className = "", style = {}, }) => {
+const GlassSurface = React__default.forwardRef(({ children, width, height, borderRadius = 20, borderWidth = 0.07, brightness: brightnessProp, opacity: opacityProp, blur: blurProp, displace: displaceProp, backgroundOpacity: backgroundOpacityProp, backgroundColor, saturation: saturationProp, distortionScale: distortionScaleProp, redOffset = 0, greenOffset = 10, blueOffset = 20, xChannel = "R", yChannel = "G", mixBlendMode: mixBlendModeProp, colorScheme = "auto", backdropBrightness = 1, frosted = false, className = "", style = {}, }, forwardedRef) => {
     const uniqueId = useId().replace(/:/g, "-");
     const filterId = `glass-filter-${uniqueId}`;
     const redGradId = `red-grad-${uniqueId}`;
@@ -37,6 +37,19 @@ const GlassSurface = ({ children, width, height, borderRadius = 20, borderWidth
     const blueChannelRef = useRef(null);
     const gaussianBlurRef = useRef(null);
     const isDarkMode = useDarkMode();
+    const resolvedDark = colorScheme === "auto" ? isDarkMode : colorScheme === "dark";
+    // Theme-aware defaults: user-provided props always win
+    // Note: brightness/opacity control the displacement map center fill, NOT visual brightness.
+    // brightness=50 + opacity=1 = neutral center (no displacement), only edges refract.
+    // On light backgrounds, high displacement pulls in black out-of-bounds pixels → gray artifacts.
+    const brightness = brightnessProp !== null && brightnessProp !== void 0 ? brightnessProp : 50;
+    const opacity = opacityProp !== null && opacityProp !== void 0 ? opacityProp : (resolvedDark ? 0.93 : 1);
+    const blur = blurProp !== null && blurProp !== void 0 ? blurProp : 11;
+    const displace = displaceProp !== null && displaceProp !== void 0 ? displaceProp : 0.7;
+    const backgroundOpacity = backgroundOpacityProp !== null && backgroundOpacityProp !== void 0 ? backgroundOpacityProp : (resolvedDark ? 0.1 : 0);
+    const saturation = saturationProp !== null && saturationProp !== void 0 ? saturationProp : (resolvedDark ? 1.8 : 1.4);
+    const distortionScale = distortionScaleProp !== null && distortionScaleProp !== void 0 ? distortionScaleProp : (resolvedDark ? -180 : -40);
+    const mixBlendMode = mixBlendModeProp !== null && mixBlendModeProp !== void 0 ? mixBlendModeProp : (resolvedDark ? "difference" : "multiply");
     /**
      * Generates the SVG displacement map as a Data URI
      */
@@ -53,11 +66,11 @@ const GlassSurface = ({ children, width, height, borderRadius = 20, borderWidth
       <svg viewBox="0 0 ${actualWidth} ${actualHeight}" xmlns="http://www.w3.org/2000/svg">
         <defs>
           <linearGradient id="${redGradId}" x1="100%" y1="0%" x2="0%" y2="0%">
-            <stop offset="0%" stop-color="#0000"/>
+            <stop offset="0%" stop-color="#000"/>
             <stop offset="100%" stop-color="red"/>
           </linearGradient>
           <linearGradient id="${blueGradId}" x1="0%" y1="0%" x2="0%" y2="100%">
-            <stop offset="0%" stop-color="#0000"/>
+            <stop offset="0%" stop-color="#000"/>
             <stop offset="100%" stop-color="blue"/>
           </linearGradient>
         </defs>
@@ -157,7 +170,7 @@ const GlassSurface = ({ children, width, height, borderRadius = 20, borderWidth
         const frostedBlur = frosted ? "blur(12px)" : "";
         if (svgSupported) {
             // Determine background color: use prop if provided, otherwise auto-detect based on theme
-            const bgColor = backgroundColor || (isDarkMode ? "hsl(0 0% 0%)" : "hsl(0 0% 100%)");
+            const bgColor = backgroundColor || (resolvedDark ? "hsl(0 0% 0%)" : "hsl(0 0% 100%)");
             // Convert color to rgba if needed to apply opacity
             const getBackgroundWithOpacity = () => {
                 // If backgroundOpacity is 0, return transparent
@@ -173,21 +186,20 @@ const GlassSurface = ({ children, width, height, borderRadius = 20, borderWidth
             return {
                 ...baseStyles,
                 background: getBackgroundWithOpacity(),
-                backdropFilter: `url(#${filterId}) ${frostedBlur} saturate(${saturation})`,
-                WebkitBackdropFilter: `url(#${filterId}) ${frostedBlur} saturate(${saturation})`,
+                backdropFilter: `url(#${filterId}) ${frostedBlur} brightness(${backdropBrightness}) saturate(${saturation})`,
+                WebkitBackdropFilter: `url(#${filterId}) ${frostedBlur} brightness(${backdropBrightness}) saturate(${saturation})`,
+                ...(!resolvedDark && { border: "1px solid rgba(0, 0, 0, 0.06)" }),
                 ...(hasCustomShadow
                     ? {}
                     : {
-                        boxShadow: isDarkMode
+                        boxShadow: resolvedDark
                             ? `0 0 2px 1px color-mix(in oklch, white, transparent 65%) inset,
                0 0 10px 4px color-mix(in oklch, white, transparent 85%) inset,
                0px 4px 16px rgba(17, 17, 26, 0.05),
                0px 8px 24px rgba(17, 17, 26, 0.05),
                0px 16px 56px rgba(17, 17, 26, 0.05)`
-                            : `0 0 1px 1px color-mix(in oklch, white, transparent 40%) inset,
-               0 0 12px 1px color-mix(in oklch, white, transparent 70%) inset,
-               0 8px 24px -12px rgba(0, 0, 0, 0.08),
-               0 4px 12px -4px rgba(0, 0, 0, 0.03)`,
+                            : `0 8px 24px -12px rgba(0, 0, 0, 0.08),
+               0 4px 12px -4px rgba(0, 0, 0, 0.04)`,
                     }),
             };
         }
@@ -197,9 +209,9 @@ const GlassSurface = ({ children, width, height, borderRadius = 20, borderWidth
             // Increase blur significantly for frosted mode in fallback
             const effectiveBlur = frosted ? "20px" : baseBlur;
             const fallbackSaturate = "1.8";
-            const fallbackBrightness = isDarkMode ? "1.2" : "1.1";
+            const fallbackBrightness = resolvedDark ? "1.2" : "1.1";
             const filterStr = `blur(${effectiveBlur}) saturate(${fallbackSaturate}) brightness(${fallbackBrightness})`;
-            if (isDarkMode) {
+            if (resolvedDark) {
                 return {
                     ...baseStyles,
                     background: supportsBackdrop
@@ -234,11 +246,19 @@ const GlassSurface = ({ children, width, height, borderRadius = 20, borderWidth
                 };
             }
         }
-    }, [style, width, height, borderRadius, frosted, svgSupported, backgroundColor, isDarkMode, backgroundOpacity, filterId, saturation, hasCustomShadow, supportsBackdrop]);
-    const focusVisibleClasses = isDarkMode
+    }, [style, width, height, borderRadius, frosted, svgSupported, backgroundColor, resolvedDark, backgroundOpacity, filterId, backdropBrightness, saturation, hasCustomShadow, supportsBackdrop]);
+    const focusVisibleClasses = resolvedDark
         ? "focus-visible:outline-2 focus-visible:outline-[#0A84FF] focus-visible:outline-offset-2"
         : "focus-visible:outline-2 focus-visible:outline-[#007AFF] focus-visible:outline-offset-2";
-    return (jsxs("div", { ref: containerRef, className: cn("relative transition-opacity duration-[260ms] ease-out", focusVisibleClasses, className), style: containerStyles, children: [jsx("svg", { className: "w-full h-full pointer-events-none absolute inset-0 opacity-0 -z-10", xmlns: "http://www.w3.org/2000/svg", children: jsxs("defs", { children: [jsxs("filter", { id: filterId, colorInterpolationFilters: "sRGB", x: "0%", y: "0%", width: "100%", height: "100%", children: [jsx("feImage", { ref: feImageRef, x: "0", y: "0", width: "100%", height: "100%", preserveAspectRatio: "none", result: "map" }), jsx("feDisplacementMap", { ref: redChannelRef, in: "SourceGraphic", in2: "map", id: "redchannel", result: "dispRed" }), jsx("feColorMatrix", { in: "dispRed", type: "matrix", values: "1 0 0 0 0\n                      0 0 0 0 0\n                      0 0 0 0 0\n                      0 0 0 1 0", result: "red" }), jsx("feDisplacementMap", { ref: greenChannelRef, in: "SourceGraphic", in2: "map", id: "greenchannel", result: "dispGreen" }), jsx("feColorMatrix", { in: "dispGreen", type: "matrix", values: "0 0 0 0 0\n                      0 1 0 0 0\n                      0 0 0 0 0\n                      0 0 0 1 0", result: "green" }), jsx("feDisplacementMap", { ref: blueChannelRef, in: "SourceGraphic", in2: "map", id: "bluechannel", result: "dispBlue" }), jsx("feColorMatrix", { in: "dispBlue", type: "matrix", values: "0 0 0 0 0\n                      0 0 0 0 0\n                      0 0 1 0 0\n                      0 0 0 1 0", result: "blue" }), jsx("feBlend", { in: "red", in2: "green", mode: "screen", result: "rg" }), jsx("feBlend", { in: "rg", in2: "blue", mode: "screen", result: "output" }), jsx("feGaussianBlur", { ref: gaussianBlurRef, in: "output", stdDeviation: "0.7" })] }), jsx("filter", { id: noiseFilterId, x: "0%", y: "0%", width: "100%", height: "100%", children: jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.65", numOctaves: "3", stitchTiles: "stitch" }) })] }) }), jsx("div", { className: "relative z-10 rounded-[inherit]", children: children }), jsx("div", { className: "absolute inset-0 pointer-events-none rounded-[inherit] overflow-hidden z-20", children: frosted && (jsx("div", { className: "absolute inset-0 opacity-10 mix-blend-overlay", style: { filter: `url(#${noiseFilterId})` } })) })] }));
-};
+    const mergedRef = useCallback((node) => {
+        containerRef.current = node;
+        if (typeof forwardedRef === "function")
+            forwardedRef(node);
+        else if (forwardedRef)
+            forwardedRef.current = node;
+    }, [forwardedRef]);
+    return (jsxs("div", { ref: mergedRef, className: cn("relative transition-opacity duration-[260ms] ease-out", focusVisibleClasses, className), style: containerStyles, children: [jsx("svg", { className: "w-full h-full pointer-events-none absolute inset-0 opacity-0 -z-10", xmlns: "http://www.w3.org/2000/svg", children: jsxs("defs", { children: [jsxs("filter", { id: filterId, colorInterpolationFilters: "sRGB", x: "0%", y: "0%", width: "100%", height: "100%", children: [jsx("feImage", { ref: feImageRef, x: "0", y: "0", width: "100%", height: "100%", preserveAspectRatio: "none", result: "map" }), jsx("feDisplacementMap", { ref: redChannelRef, in: "SourceGraphic", in2: "map", result: "dispRed" }), jsx("feColorMatrix", { in: "dispRed", type: "matrix", values: "1 0 0 0 0\n                      0 0 0 0 0\n                      0 0 0 0 0\n                      0 0 0 1 0", result: "red" }), jsx("feDisplacementMap", { ref: greenChannelRef, in: "SourceGraphic", in2: "map", result: "dispGreen" }), jsx("feColorMatrix", { in: "dispGreen", type: "matrix", values: "0 0 0 0 0\n                      0 1 0 0 0\n                      0 0 0 0 0\n                      0 0 0 1 0", result: "green" }), jsx("feDisplacementMap", { ref: blueChannelRef, in: "SourceGraphic", in2: "map", result: "dispBlue" }), jsx("feColorMatrix", { in: "dispBlue", type: "matrix", values: "0 0 0 0 0\n                      0 0 0 0 0\n                      0 0 1 0 0\n                      0 0 0 1 0", result: "blue" }), jsx("feBlend", { in: "red", in2: "green", mode: "screen", result: "rg" }), jsx("feBlend", { in: "rg", in2: "blue", mode: "screen", result: "output" }), jsx("feGaussianBlur", { ref: gaussianBlurRef, in: "output", stdDeviation: "0.7" })] }), jsx("filter", { id: noiseFilterId, x: "0%", y: "0%", width: "100%", height: "100%", children: jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.65", numOctaves: "3", stitchTiles: "stitch" }) })] }) }), jsx("div", { className: "relative z-10 h-full rounded-[inherit]", children: children }), jsx("div", { className: "absolute inset-0 pointer-events-none rounded-[inherit] overflow-hidden z-20", children: frosted && (jsx("div", { className: "absolute inset-0 opacity-10 mix-blend-overlay", style: { filter: `url(#${noiseFilterId})` } })) })] }));
+});
+GlassSurface.displayName = "GlassSurface";
 
 export { GlassSurface };

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

@@ -40,6 +40,20 @@ export interface GlassSurfaceProps {
     yChannel?: GlassChannel;
     /** Blend mode for the internal gradient layers */
     mixBlendMode?: GlassMixBlendMode;
+    /**
+     * Color scheme for the glass effect. Controls theme-aware defaults.
+     * - 'auto': detects system preference (default)
+     * - 'dark': force dark mode defaults
+     * - 'light': force light mode defaults
+     * @default 'auto'
+     */
+    colorScheme?: "auto" | "dark" | "light";
+    /**
+     * Brightness multiplier for the backdrop-filter chain.
+     * Values > 1 brighten, < 1 darken. Only applies when SVG filters are supported.
+     * @default 1
+     */
+    backdropBrightness?: number;
     /**
      * Enable frosted glass effect with noise texture
      * @default false

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

@@ -0,0 +1,18 @@
+import React from "react";
+import type { GridPatternProps } from "./GridPattern.types";
+/**
+ * GridPattern renders an SVG-based grid background pattern.
+ *
+ * Use it as an absolute-positioned decorative background inside a container
+ * with `position: relative`. The pattern is fully non-interactive
+ * (`pointer-events: none`) and sits at `z-index: 0` by default.
+ *
+ * @example
+ * ```tsx
+ * <div className="relative overflow-hidden h-96">
+ *   <GridPattern size={48} color="var(--color-border)" fade animated />
+ *   <div className="relative z-10">Your content here</div>
+ * </div>
+ * ```
+ */
+export declare const GridPattern: React.ForwardRefExoticComponent<GridPatternProps & React.RefAttributes<HTMLDivElement>>;