@shohojdhara/atomix 0.4.8 → 0.5.0

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: '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: 'text',
+    description: 'Additional CSS class names',
+    table: {
+      category: 'Style' as ArgTypeCategory,
+      defaultValue: { summary: '-' },
+    },
+  },
+  style: {
+    control: '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: 'boolean',
+    description: 'Disable responsive breakpoint system (default: false)',
+    table: {
+      category: 'Performance' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+
+  // Animation category (Phase 1)
+  withTimeAnimation: {
+    control: '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: '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: 'boolean',
+    description: 'Enable performance monitoring dashboard (development only)',
+    table: {
+      category: 'Debug' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+  debugBorderRadius: {
+    control: 'boolean',
+    description: 'Debug mode for corner radius extraction',
+    table: {
+      category: 'Debug' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+
+  // Accessibility category
+  'aria-label': {
+    control: 'text',
+    description: 'ARIA label for accessibility',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: '-' },
+    },
+  },
+  'aria-describedby': {
+    control: 'text',
+    description: 'ARIA describedby attribute for additional description',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: '-' },
+    },
+  },
+  role: {
+    control: 'text',
+    description: 'ARIA role attribute',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  tabIndex: {
+    control: 'number',
+    description: 'Tab index for keyboard navigation',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: '0' },
+    },
+  },
+  reducedMotion: {
+    control: 'boolean',
+    description: 'Override for reduced motion preference (default: false)',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+  highContrast: {
+    control: 'boolean',
+    description: 'Override for high contrast preference (default: false)',
+    table: {
+      category: 'Accessibility' as ArgTypeCategory,
+      defaultValue: { summary: 'false' },
+    },
+  },
+  withoutEffects: {
+    control: '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: 'object',
+    description: 'External global mouse position { x: number; y: number }',
+    table: {
+      category: 'Interaction' as ArgTypeCategory,
+      defaultValue: { summary: 'undefined' },
+    },
+  },
+  mouseOffset: {
+    control: '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;
+    }
+  });
+  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;
+    }
+  });
+  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
@@ -97,6 +98,9 @@ export const BackgroundWrapper: React.FC<BackgroundWrapperProps> = ({
             backgroundColor: overlayColor,
             opacity: overlayOpacity,
             padding,
+            objectPosition: 'center',
+            objectFit: 'cover',
+            backgroundPosition: 'fixed'
           }}
         />
       )}
@@ -193,8 +197,94 @@ 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',
   'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?q=80&w=2940&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
   '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 };
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+    console.error('Story rendering error:', error, errorInfo);
+    if (this.props.onError) {
+      this.props.onError(error, errorInfo);
+    }
+  }
+
+  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: Record<string, unknown>;
+  description: string;
+  table: {
+    category?: ArgTypeCategory;
+    defaultValue?: { summary: string };
+    type?: { summary: string };
+  };
+  options?: string[];
+  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[];
+}

package/src/components/Avatar/Avatar.tsx

@@ -6,7 +6,7 @@ import { Icon } from '../Icon/Icon';
 export const Avatar: React.FC<AvatarProps> = memo(
   ({
     src,
-    alt = 'Avatar',
+    alt = 'User avatar',
     initials,
     icon,
     size = 'md',

package/src/components/Button/Button.stories.disabled-link.tsx

@@ -0,0 +1,10 @@
+import { Button } from './Button';
+
+export const DisabledLinkExample = {
+  render: () => (
+    <div style={{ padding: '20px', display: 'flex', gap: '10px' }}>
+      <Button href="/home" disabled>Disabled Link Button</Button>
+      <Button href="/home">Normal Link Button</Button>
+    </div>
+  ),
+};

package/src/components/Button/Button.stories.tsx

@@ -406,6 +406,16 @@ export const DisabledState: Story = {
   },
 };
 
+export const DisabledLinkState: Story = {
+  args: {
+    label: 'Disabled Link Button',
+    variant: 'primary',
+    size: 'md',
+    disabled: true,
+    href: '/home',
+  },
+};
+
 /**
  * Shows button in active state
  */

package/src/components/Button/Button.test.tsx

@@ -75,22 +75,27 @@ describe('Button Component', () => {
   });
 
   it('renders as disabled link when disabled and href provided', () => {
-    // Current implementation might be buggy here, let's see
     render(
       <Button href="/home" disabled>
         Home
       </Button>
     );
-    const link = screen.queryByRole('link');
-    const button = screen.queryByRole('button');
-
-    // If it renders as button when disabled (which logic suggested), then:
-    if (button) {
-      expect(button).toBeDisabled();
-    } else if (link) {
-      expect(link).toHaveAttribute('aria-disabled', 'true');
-      // Should not navigate
-    }
+
+    // An anchor tag without an href attribute is not considered a 'link' role.
+    // It's considered a generic text element, but in our component it has role='link' implicitly? No.
+    // Actually, an anchor without href is generic. But it might have button styles.
+    // Let's get it by text and assert it's an anchor without href.
+    const element = screen.getByText('Home').closest('a');
+    expect(element).toBeInTheDocument();
+
+    // It shouldn't have an href attribute because it's disabled.
+    expect(element).not.toHaveAttribute('href');
+
+    // It should have aria-disabled true
+    expect(element).toHaveAttribute('aria-disabled', 'true');
+
+    // It should have disabled class
+    expect(element).toHaveClass('c-btn--disabled');
   });
 
   it('forwards ref', () => {