@shohojdhara/atomix 0.4.9 → 0.5.1

package/src/components/AtomixGlass/stories/argTypes.ts

@@ -0,0 +1,384 @@
+/**
+ * argTypes.ts
+ *
+ * Shared argType definitions for AtomixGlass Storybook stories.
+ * Provides consistent control configurations across all story files.
+ *
+ * @package Atomix
+ * @component AtomixGlass
+ */
+
+import type { ArgTypeDefinition, ArgTypeCategory } from './types';
+
+/**
+ * Base argTypes that are common to all AtomixGlass stories
+ */
+export const baseArgTypes = {
+  // Content category
+  children: {
+    control: { type: 'text' },
+    description: 'Content to display inside the glass effect',
+    table: {
+      category: 'Content' as ArgTypeCategory,
+      defaultValue: { summary: '-' },
+    },
+  },
+
+  // Visual category
+  displacementScale: {
+    control: { type: 'range', min: 0, max: 100, step: 1 },
+    description: 'Displacement scale for the glass effect (default: 70)',
+    table: {
+      category: 'Visual' as ArgTypeCategory,
+      defaultValue: { summary: '70' },
+    },
+  },
+  blurAmount: {
+    control: { type: 'range', min: 0, max: 10, step: 0.5 },
+    description: 'Blur amount for the backdrop (default: 0.0625)',
+    table: {
+      category: 'Visual' as ArgTypeCategory,
+      defaultValue: { summary: '0.0625' },
+    },
+  },
+  saturation: {
+    control: { type: 'range', min: 100, max: 300, step: 5 },
+    description: 'Saturation percentage for the backdrop (default: 140)',
+    table: {
+      category: 'Visual' as ArgTypeCategory,
+      defaultValue: { summary: '140' },
+    },
+  },
+  aberrationIntensity: {
+    control: { type: 'range', min: 0, max: 10, step: 0.1 },
+    description: 'Chromatic aberration intensity (default: 2)',
+    table: {
+      category: 'Visual' as ArgTypeCategory,
+      defaultValue: { summary: '2' },
+    },
+  },
+  elasticity: {
+    control: { type: 'range', min: 0, max: 1, step: 0.01 },
+    description: 'Elasticity factor for mouse interactions (default: 0.15)',
+    table: {
+      category: 'Visual' as ArgTypeCategory,
+      defaultValue: { summary: '0.15' },
+    },
+  },
+  borderRadius: {
+    control: { type: 'range', min: 0, max: 50, step: 1 },
+    description: 'Corner radius in pixels (default: 20)',
+    table: {
+      category: 'Visual' as ArgTypeCategory,
+      defaultValue: { summary: '20' },
+    },
+  },
+  overLight: {
+    control: {
+      type: 'select',
+      labels: {
+        false: 'false (Dark Background)',
+        true: 'true (Light Background)',
+        auto: 'auto (Auto-detect)',
+      },
+    },
+    options: [false, true, 'auto'],
+    description: 'OverLight configuration mode',
+    table: {
+      category: 'Visual' as ArgTypeCategory,
+      defaultValue: { summary: '"auto"' },
+      type: { summary: 'boolean | "auto"' },
+    },
+  },
+  mode: {
+    control: { type: 'inline-radio', options: ['standard', 'polar', 'prominent', 'shader'] },
+    description: 'Glass effect mode (default: "standard")',
+    table: {
+      category: 'Visual' as ArgTypeCategory,
+      defaultValue: { summary: '"standard"' },
+    },
+  },
+
+  // Style category
+  padding: {
+    control: { type: 'text' },
+    description: 'Padding for the glass component',
+    table: {
+      category: 'Style' as ArgTypeCategory,
+      defaultValue: { summary: '0' },
+    },
+  },
+  height: {
+    control: { type: 'text' },
+    description: 'Height of the glass component',
+    table: {
+      category: 'Style' as ArgTypeCategory,
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  width: {
+    control: { type: 'text' },
+    description: 'Width of the glass component',
+    table: {
+      category: 'Style' as ArgTypeCategory,
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  className: {
+    control: { type: 'text' },
+    description: 'Additional CSS class names',
+    table: {
+      category: 'Style' as ArgTypeCategory,
+      defaultValue: { summary: '-' },
+    },
+  },
+  style: {
+    control: { type: 'object' },
+    description: 'CSS style object',
+    table: {
+      category: 'Style' as ArgTypeCategory,
+      defaultValue: { summary: '{}' },
+    },
+  },
+
+  // Interaction category
+  onClick: {
+    action: 'clicked',
+    description: 'Click event handler',
+    table: {
+      category: 'Interaction' as ArgTypeCategory,
+      defaultValue: { summary: '-' },
+    },
+  },
+
+  // Performance category
+  devicePreset: {
+    control: { type: 'inline-radio', options: ['performance', 'balanced', 'quality'] },
+    description: 'Device preset for responsive optimization (default: "balanced")',
+    table: {
+      category: 'Performance' as ArgTypeCategory,
+      defaultValue: { summary: '"balanced"' },
+    },
+  },
+  disableResponsiveBreakpoints: {
+    control: { type: 'boolean' },
+    description: 'Disable responsive breakpoint system (default: false)',
+    table: {
+      category: 'Performance' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+
+  // Animation category (Phase 1)
+  withTimeAnimation: {
+    control: { type: 'boolean' },
+    description: 'Enable time-based animation (Phase 1, default: true)',
+    table: {
+      category: 'Animation' as ArgTypeCategory,
+      defaultValue: { summary: 'true' },
+    },
+  },
+  animationSpeed: {
+    control: { type: 'range', min: 0, max: 3, step: 0.1 },
+    description: 'Animation speed multiplier (Phase 1, default: 1.0)',
+    table: {
+      category: 'Animation' as ArgTypeCategory,
+      defaultValue: { summary: '1.0' },
+    },
+  },
+  withMultiLayerDistortion: {
+    control: { type: 'boolean' },
+    description: 'Enable multi-layer distortion using FBM (Phase 1, default: false)',
+    table: {
+      category: 'Animation' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+  distortionOctaves: {
+    control: { type: 'range', min: 1, max: 8, step: 1 },
+    description: 'Number of octaves for FBM distortion (Phase 1, default: 5)',
+    table: {
+      category: 'Animation' as ArgTypeCategory,
+      defaultValue: { summary: '5' },
+    },
+  },
+  distortionLacunarity: {
+    control: { type: 'range', min: 1, max: 4, step: 0.1 },
+    description: 'Lacunarity for FBM distortion (Phase 1, default: 2.0)',
+    table: {
+      category: 'Animation' as ArgTypeCategory,
+      defaultValue: { summary: '2.0' },
+    },
+  },
+  distortionGain: {
+    control: { type: 'range', min: 0.1, max: 1, step: 0.1 },
+    description: 'Gain for FBM distortion (Phase 1, default: 0.5)',
+    table: {
+      category: 'Animation' as ArgTypeCategory,
+      defaultValue: { summary: '0.5' },
+    },
+  },
+  distortionQuality: {
+    control: { type: 'select', options: ['low', 'medium', 'high', 'ultra'] },
+    description: 'Quality preset for FBM distortion (Phase 1, default: "high")',
+    table: {
+      category: 'Animation' as ArgTypeCategory,
+      defaultValue: { summary: '"high"' },
+    },
+  },
+
+  // Debug category
+  debugPerformance: {
+    control: { type: 'boolean' },
+    description: 'Enable performance monitoring dashboard (development only)',
+    table: {
+      category: 'Debug' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+  debugBorderRadius: {
+    control: { type: 'boolean' },
+    description: 'Debug mode for corner radius extraction',
+    table: {
+      category: 'Debug' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+
+  // Accessibility category
+  'aria-label': {
+    control: { type: 'text' },
+    description: 'ARIA label for accessibility',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: '-' },
+    },
+  },
+  'aria-describedby': {
+    control: { type: 'text' },
+    description: 'ARIA describedby attribute for additional description',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: '-' },
+    },
+  },
+  role: {
+    control: { type: 'text' },
+    description: 'ARIA role attribute',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  tabIndex: {
+    control: { type: 'number' },
+    description: 'Tab index for keyboard navigation',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: '0' },
+    },
+  },
+  reducedMotion: {
+    control: { type: 'boolean' },
+    description: 'Override for reduced motion preference (default: false)',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+  highContrast: {
+    control: { type: 'boolean' },
+    description: 'Override for high contrast preference (default: false)',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+  withoutEffects: {
+    control: { type: 'boolean' },
+    description: 'Disable all visual effects (default: false)',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+} satisfies Record<string, ArgTypeDefinition>;
+
+/**
+ * Minimal argTypes for simple stories (excludes advanced features)
+ */
+export const minimalArgTypes = {
+  children: baseArgTypes.children,
+  displacementScale: baseArgTypes.displacementScale,
+  blurAmount: baseArgTypes.blurAmount,
+  saturation: baseArgTypes.saturation,
+  aberrationIntensity: baseArgTypes.aberrationIntensity,
+  borderRadius: baseArgTypes.borderRadius,
+  mode: baseArgTypes.mode,
+  padding: baseArgTypes.padding,
+  className: baseArgTypes.className,
+  onClick: baseArgTypes.onClick,
+} satisfies Record<string, ArgTypeDefinition>;
+
+/**
+ * Advanced argTypes for playground and testing stories (includes all features)
+ */
+export const advancedArgTypes = {
+  ...baseArgTypes,
+  globalMousePosition: {
+    control: { type: 'object' },
+    description: 'External global mouse position { x: number; y: number }',
+    table: {
+      category: 'Interaction' as ArgTypeCategory,
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  mouseOffset: {
+    control: { type: 'object' },
+    description: 'External mouse offset { x: number; y: number }',
+    table: {
+      category: 'Interaction' as ArgTypeCategory,
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  mouseContainer: {
+    control: false,
+    description: 'React ref object for mouse container element',
+    table: {
+      category: 'Interaction' as ArgTypeCategory,
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+} satisfies Record<string, ArgTypeDefinition>;
+
+/**
+ * Helper function to pick specific argType categories
+ */
+export function pickArgTypeCategories<T extends Record<string, ArgTypeDefinition>>(
+  argTypes: T,
+  categories: ArgTypeCategory[]
+): Partial<T> {
+  const result: Partial<T> = {};
+  Object.entries(argTypes).forEach(([key, value]) => {
+    if (value.table?.category && categories.includes(value.table.category)) {
+      result[key as keyof T] = value as any;
+    }
+  });
+  return result;
+}
+
+/**
+ * Helper function to exclude specific argType categories
+ */
+export function excludeArgTypeCategories<T extends Record<string, ArgTypeDefinition>>(
+  argTypes: T,
+  categories: ArgTypeCategory[]
+): Partial<T> {
+  const result: Partial<T> = {};
+  Object.entries(argTypes).forEach(([key, value]) => {
+    if (value.table?.category && !categories.includes(value.table.category)) {
+      result[key as keyof T] = value as any;
+    }
+  });
+  return result;
+}

package/src/components/AtomixGlass/stories/shared-components.tsx

@@ -10,7 +10,8 @@
  */
 
 import React, { useState, useEffect, useCallback, useRef } from 'react';
-import type { RefObject } from 'react';
+import type { RefObject, ErrorInfo } from 'react';
+import type { StoryErrorBoundaryProps } from './types';
 
 /**
  * Enhanced BackgroundWrapper Component
@@ -78,6 +79,7 @@ export const BackgroundWrapper: React.FC<BackgroundWrapperProps> = ({
     backgroundSize: 'cover',
     backgroundPosition: 'center',
     backgroundRepeat: 'no-repeat',
+    backgroundAttachment: 'fixed',
     height,
     width,
     borderRadius,
@@ -99,7 +101,7 @@ export const BackgroundWrapper: React.FC<BackgroundWrapperProps> = ({
             padding,
             objectPosition: 'center',
             objectFit: 'cover',
-            backgroundPosition: 'fixed'
+            backgroundPosition: 'fixed',
           }}
         />
       )}
@@ -196,7 +198,6 @@ export const StoryContainer: React.FC<StoryContainerProps> = ({
  * Collection of high-quality background images for different moods and scenarios
  */
 export const backgroundImages = [
-  'https://images.unsplash.com/photo-1773609108583-4f0040c75e7f?q=80&w=2532&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
   'https://images.unsplash.com/photo-1593433073755-4233a78ee359?q=80&w=987&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
   'https://images.unsplash.com/photo-1637825891028-564f672aa42c?ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&q=80&w=2670',
   'https://images.unsplash.com/photo-1773062278803-0643c4782445?q=80&w=2070&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
@@ -204,3 +205,81 @@ export const backgroundImages = [
   'https://images.unsplash.com/photo-1519681393784-d120267933ba?ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&q=80&w=2670',
   'https://images.unsplash.com/photo-1441974231531-c6227db76b6e?q=80&w=2940&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
 ];
+
+/**
+ * StoryErrorBoundary Component
+ *
+ * Error boundary wrapper for stories to gracefully handle rendering errors.
+ * Provides a fallback UI and error logging for better developer experience.
+ */
+export class StoryErrorBoundary extends React.Component<
+  StoryErrorBoundaryProps,
+  { hasError: boolean; error?: Error }
+> {
+  constructor(props: StoryErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true, error };
+  }
+
+  override componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+    console.error('Story Error:', error, errorInfo);
+    this.setState({ hasError: true, error });
+  }
+
+  override render() {
+    if (this.state.hasError) {
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+
+      return (
+        <div
+          className="u-flex u-items-center u-justify-center u-p-5"
+          style={{
+            minHeight: '400px',
+            backgroundColor: 'rgba(239, 68, 68, 0.1)',
+            borderRadius: '12px',
+            border: '2px solid rgba(239, 68, 68, 0.3)',
+          }}
+        >
+          <div className="u-text-center">
+            <h3 className="u-mb-2 u-text-xl u-font-bold" style={{ color: '#dc2626' }}>
+              Story Rendering Error
+            </h3>
+            <p className="u-mb-4 u-text-sm" style={{ color: '#7f1d1d' }}>
+              {this.state.error?.message || 'An unexpected error occurred'}
+            </p>
+            <button
+              onClick={() => this.setState({ hasError: false })}
+              className="u-px-4 u-py-2 u-bg-red-600 u-text-white u-rounded u-cursor-pointer u-border-none u-transition-color u-hover-bg-red-700"
+            >
+              Try Again
+            </button>
+          </div>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+/**
+ * FallbackBackground Component
+ *
+ * Provides a gradient fallback when background images fail to load.
+ * Used as a safety net for broken external image URLs.
+ */
+export const FallbackBackground: React.FC<{ className?: string }> = ({ className = '' }) => (
+  <div
+    className={`u-absolute u-inset-0 ${className}`}
+    style={{
+      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+      zIndex: -1,
+    }}
+  />
+);

package/src/components/AtomixGlass/stories/types.ts

@@ -0,0 +1,127 @@
+/**
+ * types.ts
+ *
+ * Shared type definitions for AtomixGlass Storybook stories.
+ * Provides consistent TypeScript types across all story files.
+ *
+ * @package Atomix
+ * @component AtomixGlass
+ */
+
+import type { StoryObj, Meta } from '@storybook/react';
+import type { ComponentType, ReactNode } from 'react';
+import type AtomixGlass from '../AtomixGlass';
+
+/**
+ * Type helper for story props without children requirement
+ * Used to create flexible story configurations
+ */
+export type AtomixGlassStoryProps = Omit<React.ComponentProps<typeof AtomixGlass>, 'children'> & {
+  children?: ReactNode;
+};
+
+/**
+ * Story configuration object for reusable story setups
+ */
+export interface StoryConfig {
+  /** Story title/description */
+  description?: string;
+  /** Layout mode: centered, fullscreen, or padded */
+  layout?: 'centered' | 'fullscreen' | 'padded';
+  /** Background image URL or index */
+  backgroundImage?: string;
+  /** Enable overlay */
+  overlay?: boolean;
+  /** Overlay opacity (0-1) */
+  overlayOpacity?: number;
+  /** Custom CSS class names */
+  className?: string;
+}
+
+/**
+ * ArgType category definitions for organized controls panel
+ */
+export type ArgTypeCategory =
+  | 'Content'
+  | 'Visual'
+  | 'Interaction'
+  | 'Style'
+  | 'Performance'
+  | 'Animation'
+  | 'Debug'
+  | 'Accessibility'
+  | 'Events';
+
+/**
+ * Enhanced argType definition with category support
+ */
+export interface ArgTypeDefinition {
+  control?: { type: 'text' | 'boolean' | 'object' | 'range' | 'number' | 'color' | 'select' | 'radio' | 'inline-radio' | 'check' | 'inline-check' | 'multi-select' | 'date' | 'file'; [key: string]: unknown } | boolean;
+  description?: string;
+  table: {
+    category?: ArgTypeCategory;
+    defaultValue?: { summary: string };
+    type?: { summary: string };
+  };
+  options?: unknown[];
+  action?: string;
+}
+
+/**
+ * Background image item for story wrappers
+ */
+export interface BackgroundImageItem {
+  url: string;
+  label: string;
+  tag: 'dark' | 'colorful' | 'light' | 'nature' | 'abstract';
+}
+
+/**
+ * Error boundary props for story error handling
+ */
+export interface StoryErrorBoundaryProps {
+  children: ReactNode;
+  fallback?: ReactNode;
+  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+
+/**
+ * Preset configuration for quick story setup
+ */
+export interface GlassPreset {
+  name: string;
+  description: string;
+  args: Partial<AtomixGlassStoryProps>;
+}
+
+/**
+ * Performance metrics for monitoring story rendering
+ */
+export interface PerformanceMetrics {
+  renderTime: number;
+  fps?: number;
+  memoryUsage?: number;
+  timestamp: number;
+}
+
+/**
+ * Story decorator function type
+ */
+export type StoryDecorator<T = unknown> = (
+  Story: ComponentType,
+  context: { args?: T; globals?: Record<string, unknown> }
+) => ReactNode;
+
+/**
+ * Helper type for creating typed story objects
+ */
+export type TypedStory<T extends ComponentType = typeof AtomixGlass> = StoryObj<Meta<T>>;
+
+/**
+ * Validation result for story configurations
+ */
+export interface StoryValidationResult {
+  isValid: boolean;
+  errors: string[];
+  warnings: string[];
+}