@shohojdhara/atomix 0.2.4 → 0.2.6

package/src/components/AtomixGlass/AtomixGlassContainer.tsx

@@ -0,0 +1,399 @@
+import React, { forwardRef, useId, useRef, useState, useEffect, useMemo } from 'react';
+import type { CSSProperties } from 'react';
+import type { DisplacementMode, MousePosition, GlassSize } from '../../lib/types/components';
+import type { FragmentShaderType } from './shader-utils';
+import { ShaderDisplacementGenerator, fragmentShaders } from './shader-utils';
+import { GlassFilter } from './GlassFilter';
+import {
+  calculateElementCenter,
+  calculateDistance,
+  calculateMouseInfluence,
+  clampBlur,
+  validateGlassSize,
+} from './glass-utils';
+import { ATOMIX_GLASS } from '../../lib/constants/components';
+
+const { CONSTANTS } = ATOMIX_GLASS;
+
+interface AtomixGlassContainerProps {
+  className?: string;
+  style?: React.CSSProperties;
+  displacementScale?: number;
+  blurAmount?: number;
+  saturation?: number;
+  aberrationIntensity?: number;
+  mouseOffset?: MousePosition;
+  globalMousePosition?: MousePosition;
+  onMouseLeave?: () => void;
+  onMouseEnter?: () => void;
+  onMouseDown?: () => void;
+  onMouseUp?: () => void;
+  active?: boolean;
+  isHovered?: boolean;
+  isActive?: boolean;
+  overLight?: boolean;
+  cornerRadius?: number;
+  padding?: string;
+  glassSize?: GlassSize;
+  onClick?: () => void;
+  mode?: DisplacementMode;
+  transform?: string;
+  effectiveDisableEffects?: boolean;
+  effectiveReducedMotion?: boolean;
+  shaderVariant?: FragmentShaderType;
+  enableLiquidBlur?: boolean;
+  elasticity?: number;
+  contentRef?: React.RefObject<HTMLDivElement>;
+  children?: React.ReactNode;
+}
+
+/**
+ * AtomixGlassContainer - Internal container component for glass effects
+ * Handles the visual glass morphism layer with filters and backdrop effects
+ */
+export const AtomixGlassContainer = forwardRef<HTMLDivElement, AtomixGlassContainerProps>(
+  (
+    {
+      children,
+      className = '',
+      style,
+      displacementScale = 25,
+      blurAmount = 0.0625,
+      saturation = 180,
+      aberrationIntensity = 2,
+      mouseOffset = { x: 0, y: 0 },
+      globalMousePosition = { x: 0, y: 0 },
+      onMouseEnter,
+      onMouseLeave,
+      onMouseDown,
+      onMouseUp,
+      active = false,
+      isHovered = false,
+      isActive = false,
+      overLight = false,
+      cornerRadius = 0,
+      padding = '0 0',
+      glassSize = { width: 0, height: 0 },
+      onClick,
+      mode = 'standard',
+      effectiveDisableEffects = false,
+      effectiveReducedMotion = false,
+      shaderVariant = 'liquidGlass',
+      enableLiquidBlur = false,
+      elasticity = 0,
+      contentRef,
+    },
+    ref
+  ) => {
+    const filterId = useId();
+    const [shaderMapUrl, setShaderMapUrl] = useState<string>('');
+    const shaderGeneratorRef = useRef<ShaderDisplacementGenerator | null>(null);
+
+    // Generate initial shader map when mode/size/variant changes
+    useEffect(() => {
+      // Enhanced validation for shader mode
+      if (mode === 'shader' && glassSize && validateGlassSize(glassSize)) {
+        try {
+          shaderGeneratorRef.current?.destroy();
+          const selectedShader = fragmentShaders[shaderVariant] || fragmentShaders.liquidGlass;
+          shaderGeneratorRef.current = new ShaderDisplacementGenerator({
+            width: glassSize.width,
+            height: glassSize.height,
+            fragment: selectedShader,
+          });
+          const url = shaderGeneratorRef.current.updateShader();
+          setShaderMapUrl(url);
+        } catch (error) {
+          console.warn('AtomixGlassContainer: Error generating shader map', error);
+          setShaderMapUrl(''); // Fallback to empty string
+        }
+      }
+
+      // Cleanup function with error handling
+      return () => {
+        try {
+          shaderGeneratorRef.current?.destroy();
+        } catch (error) {
+          console.warn('AtomixGlassContainer: Error during shader cleanup', error);
+        } finally {
+          shaderGeneratorRef.current = null;
+        }
+      };
+    }, [mode, glassSize, shaderVariant]);
+
+    useEffect(() => {
+      if (!ref || typeof ref === 'function') return undefined;
+
+      const element = (ref as React.RefObject<HTMLDivElement>).current;
+      if (!element) return undefined;
+
+      const timeoutId = setTimeout(() => {
+        try {
+          // Force reflow to ensure proper sizing
+          element.offsetHeight;
+        } catch (error) {
+          console.warn('AtomixGlassContainer: Error during reflow', error);
+        }
+      }, 0);
+
+      return () => clearTimeout(timeoutId);
+    }, [cornerRadius, glassSize?.width, glassSize?.height, ref]);
+
+    const [rectCache, setRectCache] = useState<DOMRect | null>(null);
+
+    useEffect(() => {
+      if (!ref || typeof ref === 'function') return undefined;
+      const element = (ref as React.RefObject<HTMLDivElement>).current;
+      if (!element) return undefined;
+
+      try {
+        setRectCache(element.getBoundingClientRect());
+      } catch (error) {
+        console.warn('AtomixGlassContainer: Error getting element bounds', error);
+        setRectCache(null);
+      }
+
+      return undefined;
+    }, [ref, glassSize]);
+
+    const liquidBlur = useMemo(() => {
+      const defaultBlur = {
+        baseBlur: blurAmount,
+        edgeBlur: blurAmount * 1.25,
+        centerBlur: blurAmount * 1.1,
+        flowBlur: blurAmount * 1.2,
+      };
+
+      // Enhanced validation for liquid blur
+      if (
+        !enableLiquidBlur ||
+        !rectCache ||
+        !globalMousePosition ||
+        typeof globalMousePosition.x !== 'number' ||
+        typeof globalMousePosition.y !== 'number' ||
+        isNaN(globalMousePosition.x) ||
+        isNaN(globalMousePosition.y)
+      ) {
+        return defaultBlur;
+      }
+
+      try {
+        const center = calculateElementCenter(rectCache);
+        const distance = calculateDistance(globalMousePosition, center);
+        const maxDistance =
+          Math.sqrt(rectCache.width * rectCache.width + rectCache.height * rectCache.height) / 2;
+        const normalizedDistance = Math.min(distance / maxDistance, 1);
+        const mouseInfluence = calculateMouseInfluence(mouseOffset);
+
+        const baseBlur = blurAmount + mouseInfluence * blurAmount * 0.4;
+        const edgeIntensity = normalizedDistance * 1.5 + mouseInfluence * 0.3;
+        const edgeBlur = baseBlur * (0.8 + edgeIntensity * 0.6);
+        const centerIntensity = (1 - normalizedDistance) * 0.3 + mouseInfluence * 0.2;
+        const centerBlur = baseBlur * (0.3 + centerIntensity * 0.4);
+        const deltaX = globalMousePosition.x - center.x;
+        const deltaY = globalMousePosition.y - center.y;
+        const flowDirection = Math.atan2(deltaY, deltaX);
+        const flowIntensity = Math.sin(flowDirection + mouseInfluence * Math.PI) * 0.5 + 0.5;
+        const flowBlur = baseBlur * (0.4 + flowIntensity * 0.6);
+
+        const hoverMultiplier = isHovered ? 1.2 : 1;
+        const activeMultiplier = isActive ? 1.4 : 1;
+        const stateMultiplier = hoverMultiplier * activeMultiplier;
+
+        return {
+          baseBlur: clampBlur(baseBlur * stateMultiplier),
+          edgeBlur: clampBlur(edgeBlur * stateMultiplier),
+          centerBlur: clampBlur(centerBlur * stateMultiplier),
+          flowBlur: clampBlur(flowBlur * stateMultiplier),
+        };
+      } catch (error) {
+        console.warn('AtomixGlassContainer: Error calculating liquid blur', error);
+        return defaultBlur;
+      }
+    }, [
+      enableLiquidBlur,
+      blurAmount,
+      globalMousePosition,
+      mouseOffset,
+      isHovered,
+      isActive,
+      rectCache,
+      style,
+      glassSize,
+    ]);
+
+    const backdropStyle = useMemo(() => {
+      try {
+        const dynamicSaturation = saturation + (liquidBlur.baseBlur || 0) * 20;
+
+        // Validate blur values before using them
+        const validatedBaseBlur =
+          typeof liquidBlur.baseBlur === 'number' && !isNaN(liquidBlur.baseBlur)
+            ? liquidBlur.baseBlur
+            : 0;
+        const validatedEdgeBlur =
+          typeof liquidBlur.edgeBlur === 'number' && !isNaN(liquidBlur.edgeBlur)
+            ? liquidBlur.edgeBlur
+            : 0;
+        const validatedCenterBlur =
+          typeof liquidBlur.centerBlur === 'number' && !isNaN(liquidBlur.centerBlur)
+            ? liquidBlur.centerBlur
+            : 0;
+        const validatedFlowBlur =
+          typeof liquidBlur.flowBlur === 'number' && !isNaN(liquidBlur.flowBlur)
+            ? liquidBlur.flowBlur
+            : 0;
+
+        const blurLayers = [
+          `blur(${validatedBaseBlur}px)`,
+          `blur(${validatedEdgeBlur}px)`,
+          `blur(${validatedCenterBlur}px)`,
+          `blur(${validatedFlowBlur}px)`,
+        ];
+
+        return {
+          backdropFilter: `${blurLayers.join(' ')} saturate(${Math.min(dynamicSaturation, 200)}%) `,
+        };
+      } catch (error) {
+        console.warn('AtomixGlassContainer: Error calculating backdrop style', error);
+        return {
+          backdropFilter: `blur(${blurAmount}px) saturate(${saturation}%)`,
+        };
+      }
+    }, [filterId, liquidBlur, saturation, blurAmount]);
+
+    const containerVars = useMemo(() => {
+      try {
+        // Safe extraction of mouse offset values
+        const mx =
+          mouseOffset && typeof mouseOffset.x === 'number' && !isNaN(mouseOffset.x)
+            ? mouseOffset.x
+            : 0;
+        const my =
+          mouseOffset && typeof mouseOffset.y === 'number' && !isNaN(mouseOffset.y)
+            ? mouseOffset.y
+            : 0;
+        return {
+          '--atomix-glass-container-width': `${glassSize?.width}`,
+          '--atomix-glass-container-height': `${glassSize?.height}`,
+          '--atomix-glass-container-padding': padding || '0 0',
+          '--atomix-glass-container-radius': `${typeof cornerRadius === 'number' && !isNaN(cornerRadius) ? cornerRadius : 0}px`,
+          '--atomix-glass-container-backdrop': backdropStyle?.backdropFilter || 'none',
+          '--atomix-glass-container-shadow': overLight
+            ? [
+                `inset 0 1px 0 rgba(255, 255, 255, ${0.4 + mx * 0.002})`,
+                `inset 0 -1px 0 rgba(0, 0, 0, ${0.2 + Math.abs(my) * 0.001})`,
+                `inset 0 0 20px rgba(0, 0, 0, ${0.08 + Math.abs(mx + my) * 0.001})`,
+                `0 2px 12px rgba(0, 0, 0, ${0.12 + Math.abs(my) * 0.002})`,
+              ].join(', ')
+            : '0 0 20px rgba(0, 0, 0, 0.15) inset, 0 4px 8px rgba(0, 0, 0, 0.08) inset',
+          '--atomix-glass-container-shadow-opacity': effectiveDisableEffects ? 0 : 1,
+          // Background and shadow values use design token-aligned RGB values
+          '--atomix-glass-container-bg': overLight
+            ? `linear-gradient(${180 + mx * 0.5}deg, rgba(255, 255, 255, 0.1) 0%, transparent 20%, transparent 80%, rgba(0, 0, 0, 0.05) 100%)`
+            : 'none',
+          '--atomix-glass-container-text-shadow': overLight
+            ? '0px 2px 12px rgba(0, 0, 0, 0)'
+            : '0px 2px 12px rgba(0, 0, 0, 0.4)',
+          '--atomix-glass-container-box-shadow': overLight
+            ? '0px 16px 70px rgba(0, 0, 0, 0.75)'
+            : '0px 12px 40px rgba(0, 0, 0, 0.25)',
+        } as React.CSSProperties;
+      } catch (error) {
+        console.warn('AtomixGlassContainer: Error generating container variables', error);
+        return {
+          '--atomix-glass-container-padding': '0 0',
+          '--atomix-glass-container-radius': '0px',
+          '--atomix-glass-container-backdrop': 'none',
+          '--atomix-glass-container-shadow': 'none',
+          '--atomix-glass-container-shadow-opacity': 1,
+          '--atomix-glass-container-bg': 'none',
+          '--atomix-glass-container-text-shadow': 'none',
+        } as React.CSSProperties;
+      }
+    }, [
+      glassSize,
+      padding,
+      cornerRadius,
+      backdropStyle,
+      mouseOffset,
+      overLight,
+      effectiveDisableEffects,
+    ]);
+
+    return (
+      <div
+        ref={ref}
+        className={`${ATOMIX_GLASS.CONTAINER_CLASS} ${className} ${active ? ATOMIX_GLASS.CLASSES.ACTIVE : ''} ${overLight ? ATOMIX_GLASS.CLASSES.OVER_LIGHT : ''}`}
+        style={{ ...style, ...containerVars }}
+        onClick={onClick}
+      >
+        <div
+          className={ATOMIX_GLASS.INNER_CLASS}
+          style={{
+            padding: `var(--atomix-glass-container-padding)`,
+            borderRadius: `var(--atomix-glass-container-radius)`,
+            boxShadow: `var(--atomix-glass-container-box-shadow)`,
+          }}
+          onMouseEnter={onMouseEnter}
+          onMouseLeave={onMouseLeave}
+          onMouseDown={onMouseDown}
+          onMouseUp={onMouseUp}
+        >
+          <div className={ATOMIX_GLASS.FILTER_CLASS}>
+            <GlassFilter
+              mode={mode}
+              id={filterId}
+              displacementScale={
+                typeof displacementScale === 'number' && !isNaN(displacementScale)
+                  ? displacementScale
+                  : 0
+              }
+              aberrationIntensity={
+                typeof aberrationIntensity === 'number' && !isNaN(aberrationIntensity)
+                  ? aberrationIntensity
+                  : 0
+              }
+              shaderMapUrl={shaderMapUrl}
+            />
+            {/* Enhanced Apple Liquid Glass Inner Shadow Layer */}
+
+            <span
+              className={ATOMIX_GLASS.FILTER_OVERLAY_CLASS}
+              style={{
+                filter: `url(#${filterId})`,
+                backdropFilter: `var(--atomix-glass-container-backdrop)`,
+                borderRadius: `var(--atomix-glass-container-radius)`,
+              }}
+            />
+
+            <div
+              className={ATOMIX_GLASS.FILTER_SHADOW_CLASS}
+              style={{
+                boxShadow: `var(--atomix-glass-container-shadow)`,
+                opacity: `var(--atomix-glass-container-shadow-opacity)`,
+                background: `var(--atomix-glass-container-bg)`,
+                borderRadius: `var(--atomix-glass-container-radius)`,
+              }}
+            />
+          </div>
+
+          <div
+            ref={contentRef}
+            className={ATOMIX_GLASS.CONTENT_CLASS}
+            style={{
+              position: 'relative',
+              
+              textShadow: `var(--atomix-glass-container-text-shadow)`,
+              ...(elasticity > 0 ? { zIndex: 100 } : {}),
+            }}
+          >
+            {children}
+          </div>
+        </div>
+      </div>
+    );
+  }
+);
+
+AtomixGlassContainer.displayName = 'AtomixGlassContainer';

package/src/components/AtomixGlass/GlassFilter.tsx

@@ -0,0 +1,156 @@
+import React from 'react';
+import type { DisplacementMode } from '../../lib/types/components';
+import type { FragmentShaderType } from './shader-utils';
+import { getDisplacementMap } from './glass-utils';
+import { displacementMap, polarDisplacementMap, prominentDisplacementMap } from './utils';
+
+interface GlassFilterProps {
+  id: string;
+  displacementScale: number;
+  aberrationIntensity: number;
+  mode: DisplacementMode;
+  shaderMapUrl?: string;
+}
+
+/**
+ * GlassFilter - SVG filter component for glass morphism effects
+ * Creates chromatic aberration and edge distortion effects using SVG filters
+ */
+export const GlassFilter: React.FC<GlassFilterProps> = ({
+  id,
+  displacementScale,
+  aberrationIntensity,
+  mode,
+  shaderMapUrl,
+}) => (
+  <svg
+    style={{
+      position: 'absolute',
+      width: '100%',
+      height: '100%',
+      inset: 0,
+      visibility: 'hidden',
+      opacity: 0,
+    }}
+    aria-hidden="true"
+  >
+    <defs>
+      <radialGradient id={`${id}-edge-mask`} cx="50%" cy="50%" r="50%">
+        <stop offset="0%" stopColor="black" stopOpacity="0" />
+        <stop
+          offset={`${Math.max(30, 80 - aberrationIntensity * 2)}%`}
+          stopColor="black"
+          stopOpacity="0"
+        />
+        <stop offset="100%" stopColor="white" stopOpacity="1" />
+      </radialGradient>
+      <filter id={id} x="-35%" y="-35%" width="170%" height="170%" colorInterpolationFilters="sRGB">
+        <feImage
+          id="feimage"
+          x="0"
+          y="0"
+          width="100%"
+          height="100%"
+          result="DISPLACEMENT_MAP"
+          href={getDisplacementMap(mode, displacementMap, polarDisplacementMap, prominentDisplacementMap, shaderMapUrl)}
+          preserveAspectRatio="xMidYMid slice"
+        />
+
+        <feColorMatrix
+          in="DISPLACEMENT_MAP"
+          type="matrix"
+          values="0.3 0.3 0.3 0 0
+                 0.3 0.3 0.3 0 0
+                 0.3 0.3 0.3 0 0
+                 0 0 0 1 0"
+          result="EDGE_INTENSITY"
+        />
+        <feComponentTransfer in="EDGE_INTENSITY" result="EDGE_MASK">
+          <feFuncA type="discrete" tableValues={`0 ${aberrationIntensity * 0.05} 1`} />
+        </feComponentTransfer>
+
+        <feOffset in="SourceGraphic" dx="0" dy="0" result="CENTER_ORIGINAL" />
+
+        <feDisplacementMap
+          in="SourceGraphic"
+          in2="DISPLACEMENT_MAP"
+          scale={displacementScale * (mode === 'shader' ? 1 : -1)}
+          xChannelSelector="R"
+          yChannelSelector="B"
+          result="RED_DISPLACED"
+        />
+        <feColorMatrix
+          in="RED_DISPLACED"
+          type="matrix"
+          values="1 0 0 0 0
+                 0 0 0 0 0
+                 0 0 0 0 0
+                 0 0 0 1 0"
+          result="RED_CHANNEL"
+        />
+
+        <feDisplacementMap
+          in="SourceGraphic"
+          in2="DISPLACEMENT_MAP"
+          scale={displacementScale * ((mode === 'shader' ? 1 : -1) - aberrationIntensity * 0.02)}
+          xChannelSelector="R"
+          yChannelSelector="B"
+          result="GREEN_DISPLACED"
+        />
+        <feColorMatrix
+          in="GREEN_DISPLACED"
+          type="matrix"
+          values="0 0 0 0 0
+                 0 1 0 0 0
+                 0 0 0 0 0
+                 0 0 0 1 0"
+          result="GREEN_CHANNEL"
+        />
+
+        <feDisplacementMap
+          in="SourceGraphic"
+          in2="DISPLACEMENT_MAP"
+          scale={displacementScale * ((mode === 'shader' ? 1 : -1) - aberrationIntensity * 0.03)}
+          xChannelSelector="R"
+          yChannelSelector="B"
+          result="BLUE_DISPLACED"
+        />
+        <feColorMatrix
+          in="BLUE_DISPLACED"
+          type="matrix"
+          values="0 0 0 0 0
+                 0 0 0 0 0
+                 0 0 1 0 0
+                 0 0 0 1 0"
+          result="BLUE_CHANNEL"
+        />
+
+        <feBlend in="GREEN_CHANNEL" in2="BLUE_CHANNEL" mode="screen" result="GB_COMBINED" />
+        <feBlend in="RED_CHANNEL" in2="GB_COMBINED" mode="screen" result="RGB_COMBINED" />
+
+        {/* <feGaussianBlur
+          in="RGB_COMBINED"
+          stdDeviation='0'
+          result="ABERRATED_BLURRED"
+        /> */}
+
+        <feComposite
+          in="ABERRATED_BLURRED"
+          in2="EDGE_MASK"
+          operator="in"
+          result="EDGE_ABERRATION"
+        />
+
+        <feComponentTransfer in="EDGE_MASK" result="INVERTED_MASK">
+          <feFuncA type="table" tableValues="1 0" />
+        </feComponentTransfer>
+        <feComposite in="CENTER_ORIGINAL" in2="INVERTED_MASK" operator="in" result="CENTER_CLEAN" />
+
+        <feComposite in="EDGE_ABERRATION" in2="CENTER_CLEAN" operator="over" />
+      </filter>
+    </defs>
+  </svg>
+);
+
+GlassFilter.displayName = 'GlassFilter';
+

package/src/components/AtomixGlass/README.md

@@ -51,7 +51,9 @@ function MyComponent() {
 | `mouseContainer` | RefObject<HTMLElement> | null | Container to use for mouse position calculation |
 | `padding` | number | 0 | Additional padding around the content |
 | `style` | CSSProperties | {} | Additional CSS styles |
-| `overLight` | boolean | false | Whether the glass is over a light background |
+| `overLight` | boolean \| 'auto' \| OverLightObjectConfig | 'auto' | OverLight configuration. See [OverLight Configuration](#overlight-configuration) section for details |
+| `enableOverLightLayers` | boolean | true | Whether to render additional overlay layers for overLight mode |
+| `debugOverLight` | boolean | false | Enable debug logging for overLight detection and configuration |
 | `mode` | 'standard' \| 'polar' \| 'prominent' \| 'shader' | 'standard' | The glass effect mode |
 | `onClick` | function | undefined | Click handler |
 | `showBorderEffects` | boolean | true | Whether to show border effects |
@@ -90,14 +92,134 @@ AtomixGlass is designed with accessibility in mind:
 - Works with screen readers
 - Includes reduced motion options for users with vestibular disorders
 
+## OverLight Configuration
+
+The `overLight` prop supports three configuration modes for handling glass effects on light backgrounds:
+
+### Boolean Mode (Explicit Control)
+
+Use `true` or `false` for direct control when you know the background state:
+
+```tsx
+// Light background
+<AtomixGlass overLight={true}>
+  <div>Content on light background</div>
+</AtomixGlass>
+
+// Dark background
+<AtomixGlass overLight={false}>
+  <div>Content on dark background</div>
+</AtomixGlass>
+```
+
+**Use Cases:**
+- When you know the background is light/dark
+- When you want explicit control
+- Performance-critical scenarios (avoids detection overhead)
+
+### Auto-Detection Mode
+
+Use `"auto"` to automatically detect background brightness:
+
+```tsx
+<AtomixGlass overLight="auto">
+  <div>Content with auto-detected background</div>
+</AtomixGlass>
+```
+
+**How it works:**
+- Traverses parent elements (up to 20 levels deep)
+- Samples up to 10 background elements
+- Calculates average luminance using: `(0.299 * r + 0.587 * g + 0.114 * b) / 255`
+- Compares against threshold (default: 0.7)
+- Automatically enables overLight mode for light backgrounds
+
+**Limitations:**
+- 150ms delay for detection
+- May not detect complex gradients accurately
+- Image backgrounds assume medium luminance (0.5)
+
+### Object Configuration Mode
+
+Use an object to customize auto-detection with specific settings:
+
+```tsx
+<AtomixGlass 
+  overLight={{
+    threshold: 0.8,        // Detection threshold (0.1 - 1.0)
+    opacity: 0.6,          // Base opacity (0.1 - 1.0)
+    contrast: 1.8,         // Contrast enhancement (0.5 - 2.5)
+    brightness: 1.0,       // Brightness adjustment (0.5 - 2.0)
+    saturationBoost: 1.5  // Saturation multiplier (0.5 - 3.0)
+  }}
+>
+  <div>Content with custom overLight config</div>
+</AtomixGlass>
+```
+
+**Available Properties:**
+
+| Property | Type | Range | Default | Description |
+|----------|------|-------|---------|-------------|
+| `threshold` | number | 0.1 - 1.0 | 0.7 | Luminance threshold for auto-detection |
+| `opacity` | number | 0.1 - 1.0 | 0.5* | Base opacity (multiplied by hover/active intensity) |
+| `contrast` | number | 0.5 - 2.5 | 1.4* | Contrast enhancement multiplier |
+| `brightness` | number | 0.5 - 2.0 | 0.85* | Brightness adjustment multiplier |
+| `saturationBoost` | number | 0.5 - 3.0 | 1.3* | Saturation multiplier |
+
+\* Defaults are dynamic and depend on mouse influence, hover, and active states
+
+**Example - Minimal Config:**
+```tsx
+// Only customize threshold
+<AtomixGlass overLight={{ threshold: 0.8 }}>
+  <div>Content</div>
+</AtomixGlass>
+```
+
+**Example - Full Config:**
+```tsx
+// Customize all properties
+<AtomixGlass 
+  overLight={{
+    threshold: 0.75,
+    opacity: 0.6,
+    contrast: 1.8,
+    brightness: 1.1,
+    saturationBoost: 1.5
+  }}
+>
+  <div>Content</div>
+</AtomixGlass>
+```
+
+### Debug Mode
+
+Enable `debugOverLight` to log detailed information about detection and configuration:
+
+```tsx
+<AtomixGlass overLight="auto" debugOverLight={true}>
+  <div>Content with debug logging</div>
+</AtomixGlass>
+```
+
+This logs to console:
+- Auto-detection results (luminance values, threshold comparison)
+- Final overLight configuration values
+- Detection timing and performance
+
 ## Best Practices
 
 - Use AtomixGlass for important UI elements that need to stand out
 - Avoid overusing glass effects which can create visual noise
 - Ensure text on glass backgrounds has sufficient contrast
-- Consider using the `overLight` prop when placing glass over light backgrounds
+- Use `overLight="auto"` for dynamic backgrounds or when unsure
+- Use `overLight={true}` or `overLight={false}` for known backgrounds (better performance)
+- Use object config to fine-tune detection sensitivity and visual effects
+- Enable `debugOverLight` when troubleshooting auto-detection issues
 - Test glass effects across different devices and screen sizes
 - Use appropriate `cornerRadius` values to match your design language
+- Consider disabling `enableOverLightLayers` for performance optimization
 
 ## Customization