@shohojdhara/atomix 0.6.3 → 0.6.5

package/src/components/AtomixGlass/glass-utils.ts

@@ -1,6 +1,6 @@
 import type { CSSProperties } from 'react';
 import React from 'react';
-import type { MousePosition, GlassSize } from '../../lib/types/components';
+import type { DisplacementMode, GlassSize, MousePosition } from '../../lib/types/components';
 import { ATOMIX_GLASS } from '../../lib/constants/components';
 
 const { CONSTANTS } = ATOMIX_GLASS;
@@ -44,7 +44,7 @@ export const calculateMouseInfluence = (mouseOffset: MousePosition): number => {
   if (!mouseOffset || typeof mouseOffset.x !== 'number' || typeof mouseOffset.y !== 'number') {
     return 0;
   }
-  // Bounded calculation — keeps the glass effect subtle and stable
+  // Clamp influence to keep mouse response subtle and stable.
   const influence =
     Math.sqrt(mouseOffset.x * mouseOffset.x + mouseOffset.y * mouseOffset.y) /
     CONSTANTS.MOUSE_INFLUENCE_DIVISOR;
@@ -280,6 +280,409 @@ export const calculateVelocity = (
   return (current - previous) / deltaTime;
 };
 
+/**
+ * Layout, sizing, and effect-resolution utilities for AtomixGlass.
+ *
+ * The root wrapper exposes CSS custom properties; the container owns layout and
+ * backdrop-filter. Helpers in this section keep decorative layers aligned with
+ * the container across fixed, sticky, and in-flow positioning modes.
+ */
+
+/** Subset of CSS layout properties used for glass positioning. */
+export type GlassLayoutPosition = Pick<
+  CSSProperties,
+  'position' | 'top' | 'left' | 'right' | 'bottom' | 'inset'
+>;
+
+/** Inset values formatted for `--atomix-glass-*` custom properties. */
+export interface GlassLayerInsetVars {
+  top: string;
+  left: string;
+  right: string;
+  bottom: string;
+}
+
+/**
+ * Normalizes a layout inset for use in CSS custom properties.
+ *
+ * @param value - Raw inset from `style` (number, px string, or `auto`).
+ * @param fallback - Value used when `value` is undefined.
+ */
+export function formatGlassInsetValue(
+  value: string | number | undefined,
+  fallback: string | number = 'auto'
+): string {
+  if (value === undefined) {
+    return typeof fallback === 'number' ? `${fallback}px` : String(fallback);
+  }
+  if (value === 'auto') {
+    return 'auto';
+  }
+  return typeof value === 'number' ? `${value}px` : value;
+}
+
+/**
+ * Determines whether the glass should use fixed/sticky layout semantics.
+ *
+ * @param explicit - Value of the `isFixedOrSticky` prop.
+ * @param position - `position` from the consumer `style` object.
+ */
+export function isGlassFixedOrSticky(
+  explicit?: boolean,
+  position?: CSSProperties['position']
+): boolean {
+  return Boolean(explicit || position === 'fixed' || position === 'sticky');
+}
+
+/**
+ * Extracts layout-related properties from a React `CSSProperties` object.
+ */
+export function pickGlassLayoutStyle(style: CSSProperties): GlassLayoutPosition {
+  const { position, top, left, right, bottom, inset } = style;
+  return {
+    ...(position != null && { position }),
+    ...(top !== undefined && { top }),
+    ...(left !== undefined && { left }),
+    ...(right !== undefined && { right }),
+    ...(bottom !== undefined && { bottom }),
+    ...(inset !== undefined && { inset }),
+  };
+}
+
+/**
+ * Builds inline layout styles for the root wrapper.
+ *
+ * Reserved for alternate layout strategies. The default implementation applies
+ * layout on `.c-atomix-glass__container` to preserve backdrop-filter behavior.
+ */
+export function pickGlassHoistedRootStyle(style: CSSProperties): CSSProperties {
+  const layout = pickGlassLayoutStyle(style);
+  const resolvedPosition = (layout.position ?? style.position ?? 'fixed') as CSSProperties['position'];
+
+  return {
+    position: resolvedPosition,
+    ...(layout.top !== undefined && { top: layout.top }),
+    ...(layout.left !== undefined && { left: layout.left }),
+    ...(layout.right !== undefined && { right: layout.right }),
+    ...(layout.bottom !== undefined && { bottom: layout.bottom }),
+    ...(layout.inset !== undefined && { inset: layout.inset }),
+  };
+}
+
+/**
+ * Returns `style` without layout properties, preserving visual declarations only.
+ */
+export function omitGlassLayoutStyle(style: CSSProperties): CSSProperties {
+  const {
+    position: _p,
+    top: _t,
+    left: _l,
+    right: _r,
+    bottom: _b,
+    inset: _inset,
+    ...visualStyle
+  } = style;
+  return visualStyle;
+}
+
+/**
+ * Resolves inset custom properties for decorative layers (hover, borders, backgrounds).
+ *
+ * For fixed and sticky modes, insets mirror the container so sibling layers remain
+ * aligned. In-flow modes, insets follow the consumer `style` when a non-default
+ * `position` is provided.
+ */
+export function getGlassLayerInsetVars(
+  isFixedOrSticky: boolean,
+  restStyle: CSSProperties
+): GlassLayerInsetVars {
+  if (isFixedOrSticky) {
+    return {
+      top: formatGlassInsetValue(restStyle.top, 0),
+      left: formatGlassInsetValue(restStyle.left, 0),
+      right: formatGlassInsetValue(restStyle.right, 'auto'),
+      bottom: formatGlassInsetValue(restStyle.bottom, 'auto'),
+    };
+  }
+
+  const position = restStyle.position;
+  const usesCustomPosition =
+    position != null && position !== 'static' && position !== 'relative';
+
+  if (!usesCustomPosition) {
+    return { top: '0px', left: '0px', right: 'auto', bottom: 'auto' };
+  }
+
+  return {
+    top: formatGlassInsetValue(restStyle.top, 0),
+    left: formatGlassInsetValue(restStyle.left, 0),
+    right: formatGlassInsetValue(restStyle.right, 'auto'),
+    bottom: formatGlassInsetValue(restStyle.bottom, 'auto'),
+  };
+}
+
+/**
+ * Resolves the `--atomix-glass-position` value for decorative layers.
+ *
+ * Fixed/sticky layers use the same positioning mode as the container; in-flow
+ * layers default to the internal absolute positioning context.
+ */
+export function getGlassLayerPositionVar(
+  isFixedOrSticky: boolean,
+  positionStyles: GlassLayoutPosition,
+  restStyle: CSSProperties
+): string {
+  if (!isFixedOrSticky) {
+    return `${positionStyles.position}`;
+  }
+  const layout = pickGlassLayoutStyle(restStyle);
+  return `${layout.position ?? restStyle.position ?? 'fixed'}`;
+}
+
+/**
+ * Returns the internal positioning context for effect layers relative to the root.
+ */
+export function getGlassInternalPositionStyles(
+  isFixedOrSticky: boolean,
+  restStyle: CSSProperties
+): GlassLayoutPosition {
+  return {
+    position: (isFixedOrSticky
+      ? 'absolute'
+      : restStyle.position || 'absolute') as CSSProperties['position'],
+    top: 0,
+    left: 0,
+    right: 'auto',
+    bottom: 'auto',
+  };
+}
+
+/**
+ * Computes `--atomix-glass-width` and `--atomix-glass-height` values.
+ *
+ * Fixed/sticky elements prefer explicit dimensions or measured size; in-flow
+ * elements default to `100%`.
+ */
+export function resolveGlassAdjustedSize(options: {
+  width?: string | number;
+  height?: string | number;
+  restStyle: CSSProperties;
+  glassSize: GlassSize;
+  isFixedOrSticky: boolean;
+}): { width: string; height: string } {
+  const { width, height, restStyle, glassSize, isFixedOrSticky } = options;
+
+  const resolveLength = (value: string | number | undefined, measured: number): string => {
+    if (value !== undefined && isFixedOrSticky) {
+      return typeof value === 'number' ? `${value}px` : value;
+    }
+    if (measured > 0 && isFixedOrSticky) {
+      return `${measured}px`;
+    }
+    return '100%';
+  };
+
+  const effectiveWidth = width ?? restStyle.width;
+  const effectiveHeight = height ?? restStyle.height;
+
+  return {
+    width: resolveLength(effectiveWidth, glassSize.width),
+    height: resolveLength(effectiveHeight, glassSize.height),
+  };
+}
+
+/** Input parameters for {@link buildGlassRootCssVariables}. */
+export interface GlassRootCssVarsInput {
+  effectiveBorderRadius: number;
+  transformStyle?: string;
+  adjustedSize: { width: string; height: string };
+  isOverLight: boolean;
+  customZIndex?: string | number;
+  isFixedOrSticky: boolean;
+  positionStyles: GlassLayoutPosition;
+  restStyle: CSSProperties;
+  /** Rim width — maps to `--atomix-glass-border-width`. */
+  borderWidth?: string;
+}
+
+/**
+ * Builds the CSS custom properties applied to the root `.c-atomix-glass` element.
+ *
+ * These variables drive layer geometry, transforms, and stacking offsets. They
+ * must not include layout properties that would interfere with backdrop-filter.
+ */
+export function buildGlassRootCssVariables(input: GlassRootCssVarsInput): CSSProperties {
+  const {
+    effectiveBorderRadius,
+    transformStyle,
+    adjustedSize,
+    isOverLight,
+    customZIndex,
+    isFixedOrSticky,
+    positionStyles,
+    restStyle,
+    borderWidth = ATOMIX_GLASS.BORDER.DEFAULT_WIDTH,
+  } = input;
+
+  const layerPosition = getGlassLayerPositionVar(isFixedOrSticky, positionStyles, restStyle);
+  const layerInsets = getGlassLayerInsetVars(isFixedOrSticky, restStyle);
+
+  return {
+    ...(customZIndex !== undefined && { '--atomix-glass-base-z-index': customZIndex }),
+    '--atomix-glass-radius': `${effectiveBorderRadius}px`,
+    '--atomix-glass-transform': transformStyle || 'none',
+    '--atomix-glass-container-position': layerPosition,
+    '--atomix-glass-position': layerPosition,
+    '--atomix-glass-top': layerInsets.top,
+    '--atomix-glass-left': layerInsets.left,
+    '--atomix-glass-right': layerInsets.right,
+    '--atomix-glass-bottom': layerInsets.bottom,
+    '--atomix-glass-width': adjustedSize.width,
+    '--atomix-glass-height': adjustedSize.height,
+    // Aliases maintained for backward compatibility and consumer overrides.
+    '--atomix-glass-container-width': adjustedSize.width,
+    '--atomix-glass-container-height': adjustedSize.height,
+    [ATOMIX_GLASS.BORDER.WIDTH_CSS_VAR]: borderWidth,
+    '--atomix-glass-blend-mode': isOverLight ? 'multiply' : 'overlay',
+  } as CSSProperties;
+}
+
+/** Resolved visual effect values passed to {@link AtomixGlassContainer}. */
+export interface ResolvedGlassContainerEffects {
+  displacementScale: number;
+  blurAmount: number;
+  saturation: number;
+  aberrationIntensity: number;
+  mouseOffset: MousePosition;
+  globalMousePosition: MousePosition;
+}
+
+/**
+ * Applies mode-specific multipliers and accessibility overrides to container effects.
+ */
+export function resolveGlassContainerEffects(options: {
+  displacementScale: number;
+  blurAmount: number;
+  saturation: number;
+  aberrationIntensity: number;
+  mode: DisplacementMode;
+  effectiveWithoutEffects: boolean;
+  effectiveHighContrast: boolean;
+  isOverLight: boolean;
+  saturationBoost: number;
+  mouseOffset: MousePosition;
+  globalMousePosition: MousePosition;
+}): ResolvedGlassContainerEffects {
+  const { MULTIPLIERS, SATURATION } = ATOMIX_GLASS.CONSTANTS;
+  const zeroMouse: MousePosition = { x: 0, y: 0 };
+
+  const resolveSaturation = (): number => {
+    if (options.effectiveHighContrast) {
+      return SATURATION.HIGH_CONTRAST;
+    }
+    if (options.isOverLight) {
+      return options.saturation * options.saturationBoost;
+    }
+    return options.saturation;
+  };
+
+  if (options.effectiveWithoutEffects) {
+    return {
+      displacementScale: 0,
+      blurAmount: 0,
+      saturation: resolveSaturation(),
+      aberrationIntensity: 0,
+      mouseOffset: zeroMouse,
+      globalMousePosition: zeroMouse,
+    };
+  }
+
+  let resolvedDisplacement = options.displacementScale;
+  if (options.mode === 'shader') {
+    resolvedDisplacement *= MULTIPLIERS.SHADER_DISPLACEMENT;
+  } else if (options.isOverLight) {
+    resolvedDisplacement *= MULTIPLIERS.OVER_LIGHT_DISPLACEMENT;
+  }
+
+  let resolvedAberration = options.aberrationIntensity;
+  if (options.mode === 'shader') {
+    resolvedAberration *= MULTIPLIERS.SHADER_ABERRATION;
+  }
+
+  return {
+    displacementScale: resolvedDisplacement,
+    blurAmount: options.blurAmount,
+    saturation: resolveSaturation(),
+    aberrationIntensity: resolvedAberration,
+    mouseOffset: options.mouseOffset,
+    globalMousePosition: options.globalMousePosition,
+  };
+}
+
+/** Coerces a value to a finite number, returning `fallback` when invalid. */
+export function toSafeNumber(value: unknown, fallback = 0): number {
+  return typeof value === 'number' && !isNaN(value) ? value : fallback;
+}
+
+export type DistortionQuality = 'low' | 'medium' | 'high' | 'ultra';
+
+/**
+ * Calculates the target frame rate for shader time-animation loops.
+ *
+ * Balances visual quality against distortion complexity and `animationSpeed`.
+ */
+export function getShaderAnimationTargetFps(options: {
+  distortionQuality: DistortionQuality | string;
+  animationSpeed?: number;
+  withMultiLayerDistortion?: boolean;
+  distortionOctaves?: number;
+  distortionLacunarity?: number;
+  distortionGain?: number;
+}): number {
+  const {
+    distortionQuality,
+    animationSpeed = 1,
+    withMultiLayerDistortion,
+    distortionOctaves = 3,
+    distortionLacunarity = 2,
+    distortionGain = 0.5,
+  } = options;
+
+  const baseFps =
+    distortionQuality === 'ultra'
+      ? 60
+      : distortionQuality === 'high'
+        ? 30
+        : distortionQuality === 'medium'
+          ? 24
+          : 20;
+
+  const effectiveSpeed = Math.max(0.5, Math.min(2, animationSpeed));
+  const complexity = withMultiLayerDistortion
+    ? Math.max(
+        1,
+        distortionOctaves / 3 +
+          Math.max(0, distortionLacunarity - 2) * 0.25 +
+          Math.max(0, distortionGain - 0.5)
+      )
+    : 1;
+
+  return Math.max(12, Math.min(60, Math.round((baseFps * effectiveSpeed) / complexity)));
+}
+
+/**
+ * Computes per-channel displacement scale for the SVG chromatic-aberration filter.
+ */
+export function getChromaticDisplacementScale(
+  mode: DisplacementMode,
+  displacementScale: number,
+  aberrationIntensity: number,
+  channelFactor: number
+): number {
+  const sign = mode === 'shader' ? 1 : -1;
+  return displacementScale * (sign - aberrationIntensity * channelFactor);
+}
+
 /**
  * Get displacement map URL based on mode
  */
@@ -305,10 +708,12 @@ export const getDisplacementMap = (
   }
 };
 
-// ─── Shader LRU Cache ──────────────────────────────────────────────────────
-// Shared across all AtomixGlassContainer instances so identical shader
-// configurations (same size + variant) are only generated once.
-
+/**
+ * Module-level LRU cache for shader displacement maps.
+ *
+ * Shared across all `AtomixGlassContainer` instances so identical size and
+ * variant combinations are generated once.
+ */
 export const MAX_CACHE_SIZE = 15;
 
 export interface ShaderCacheEntry {