@shohojdhara/atomix 0.3.4 → 0.3.6

package/src/components/AtomixGlass/AtomixGlass.tsx

@@ -118,6 +118,12 @@ export function AtomixGlass({
     opacity0: number;
   } | null>(null);
 
+  // Cache RGB color values from design tokens
+  const rgbCacheRef = useRef<{
+    whiteRgb: string;
+    blackRgb: string;
+  } | null>(null);
+
   // Use composable hook for all state and logic
   const {
     isHovered,
@@ -161,35 +167,63 @@ export function AtomixGlass({
 
   // Read CSS custom properties once on mount and cache them
   useEffect(() => {
-    if (typeof window !== 'undefined' && glassRef.current && !opacityCacheRef.current) {
+    if (typeof window !== 'undefined' && glassRef.current) {
       try {
         const computedStyle = window.getComputedStyle(glassRef.current);
-        const opacity50Value = computedStyle.getPropertyValue('--atomix-opacity-50').trim();
-        const opacity40Value = computedStyle.getPropertyValue('--atomix-opacity-40').trim();
-        const opacity80Value = computedStyle.getPropertyValue('--atomix-opacity-80').trim();
-        const opacity0Value = computedStyle.getPropertyValue('--atomix-opacity-0').trim();
-
-        // Parse opacity values, handling 0 correctly (use NaN check instead of falsy check)
-        const parseOpacity = (value: string, defaultValue: number): number => {
-          if (!value) return defaultValue;
-          const parsed = parseFloat(value);
-          return isNaN(parsed) ? defaultValue : parsed;
-        };
-
-        opacityCacheRef.current = {
-          opacity50: parseOpacity(opacity50Value, 0.5),
-          opacity40: parseOpacity(opacity40Value, 0.4),
-          opacity80: parseOpacity(opacity80Value, 0.8),
-          opacity0: parseOpacity(opacity0Value, 0),
-        };
+        
+        // Cache opacity values
+        if (!opacityCacheRef.current) {
+          const opacity50Value = computedStyle.getPropertyValue('--atomix-opacity-50').trim();
+          const opacity40Value = computedStyle.getPropertyValue('--atomix-opacity-40').trim();
+          const opacity80Value = computedStyle.getPropertyValue('--atomix-opacity-80').trim();
+          const opacity0Value = computedStyle.getPropertyValue('--atomix-opacity-0').trim();
+
+          // Parse opacity values, handling 0 correctly (use NaN check instead of falsy check)
+          const parseOpacity = (value: string, defaultValue: number): number => {
+            if (!value) return defaultValue;
+            const parsed = parseFloat(value);
+            return isNaN(parsed) ? defaultValue : parsed;
+          };
+
+          opacityCacheRef.current = {
+            opacity50: parseOpacity(opacity50Value, 0.5),
+            opacity40: parseOpacity(opacity40Value, 0.4),
+            opacity80: parseOpacity(opacity80Value, 0.8),
+            opacity0: parseOpacity(opacity0Value, 0),
+          };
+        }
+
+        // Cache RGB color values from design tokens
+        if (!rgbCacheRef.current) {
+          // Try to read from design tokens, fallback to defaults
+          const whiteRgbValue = computedStyle.getPropertyValue('--atomix-light-rgb').trim() ||
+                                computedStyle.getPropertyValue('--atomix-white-rgb').trim() ||
+                                '';
+          const blackRgbValue = computedStyle.getPropertyValue('--atomix-dark-rgb').trim() ||
+                               computedStyle.getPropertyValue('--atomix-black-rgb').trim() ||
+                               '';
+
+          rgbCacheRef.current = {
+            whiteRgb: whiteRgbValue || '255, 255, 255', // Fallback to white RGB
+            blackRgb: blackRgbValue || '0, 0, 0', // Fallback to black RGB
+          };
+        }
       } catch (error) {
         // Fallback to defaults if reading fails
-        opacityCacheRef.current = {
-          opacity50: 0.5,
-          opacity40: 0.4,
-          opacity80: 0.8,
-          opacity0: 0,
-        };
+        if (!opacityCacheRef.current) {
+          opacityCacheRef.current = {
+            opacity50: 0.5,
+            opacity40: 0.4,
+            opacity80: 0.8,
+            opacity0: 0,
+          };
+        }
+        if (!rgbCacheRef.current) {
+          rgbCacheRef.current = {
+            whiteRgb: '255, 255, 255',
+            blackRgb: '0, 0, 0',
+          };
+        }
       }
     }
   }, []);
@@ -393,12 +427,12 @@ export function AtomixGlass({
 
   const glassVars = useMemo(() => {
     // RGB color values for rgba() functions
-    // Note: CSS doesn't support rgba(var(--rgb), opacity) syntax, so we use direct values
-    // These values align with design tokens: --atomix-white-rgb and --atomix-black-rgb
-    // The actual RGB values are defined in SCSS and should match these fallbacks
-    // TODO: Consider reading from CSS custom properties if browser support improves
-    const whiteColor = '255, 255, 255'; // Matches --atomix-white-rgb design token
-    const blackColor = '0, 0, 0'; // Matches --atomix-black-rgb design token
+    // Note: CSS doesn't support rgba(var(--rgb), opacity) syntax - this is a CSS specification
+    // limitation, not a browser support issue. We read RGB values from design tokens at mount
+    // and cache them for performance. Falls back to defaults if tokens are not available.
+    // Uses design tokens: --atomix-light-rgb / --atomix-white-rgb and --atomix-dark-rgb / --atomix-black-rgb
+    const whiteColor = rgbCacheRef.current?.whiteRgb || '255, 255, 255';
+    const blackColor = rgbCacheRef.current?.blackRgb || '0, 0, 0';
 
     return {
       // Standard CSS custom properties for dynamic values

package/src/components/AtomixGlass/AtomixGlassContainer.tsx

@@ -130,10 +130,17 @@ export const AtomixGlassContainer = forwardRef<HTMLDivElement, AtomixGlassContai
     },
     ref
   ) => {
-    // Use React's useId() for SSR compatibility
-    // Note: In Next.js, IDs may differ between server and client
-    // We'll suppress hydration warnings on elements that use this ID
-    const filterId = useId();
+    // Generate a stable, deterministic ID for SSR compatibility
+    // React's useId() should produce the same ID on server and client for the same
+    // component position in the tree. We use useState to ensure the ID is only
+    // generated once and remains stable across renders.
+    const baseId = useId();
+    const [filterId] = useState(() => {
+      // Normalize the ID to ensure it's valid and consistent
+      // Remove colons (which useId() uses) and ensure it starts with a letter
+      const normalizedId = baseId.replace(/:/g, '-').replace(/^[^a-z]/i, 'atomix-');
+      return `atomix-glass-filter-${normalizedId}`;
+    });
     
     const [shaderMapUrl, setShaderMapUrl] = useState<string>('');
     const shaderGeneratorRef = useRef<any>(null);

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

@@ -124,7 +124,7 @@ See documentation for detailed examples of each mode.`,
       },
     },
     mode: {
-      control: 'select',
+      control: { type: 'select' },
       options: ['standard', 'polar', 'prominent', 'shader'],
       description: 'Glass effect mode (default: "standard")',
       table: { defaultValue: { summary: '"standard"' } },
@@ -446,37 +446,6 @@ const backgroundImages = [
   'https://images.unsplash.com/photo-1521587760476-6c12a4b040da?q=80&w=2940&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
 ];
 
-/**
- * Legacy backgrounds object for backward compatibility
- * @deprecated Use backgroundImages array instead
- */
-const backgrounds = {
-  // Office and workspace environments
-  blueGradient: backgroundImages[0], // Modern office interior
-  purpleGradient: backgroundImages[1], // Mountain landscape
-  greenGradient: backgroundImages[3], // Forest path
-
-  // Apple-inspired natural scenes
-  macosWallpaper: backgroundImages[1], // Mountain landscape
-  iosWallpaper: backgroundImages[4], // Ocean waves
-
-  // Nature scenes
-  mountains: backgroundImages[1], // Mountain landscape
-  ocean: backgroundImages[4], // Ocean waves
-
-  // Urban environments
-  cityNight: backgroundImages[2], // Urban cityscape
-  cityDay: backgroundImages[5], // Modern architecture
-
-  // Interior spaces
-  abstract1: backgroundImages[6], // Cozy café interior
-  abstract2: backgroundImages[9], // Modern library
-
-  // Video backgrounds
-  videoBackground:
-    'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
-};
-
 /**
  * Default showcase of the AtomixGlass component
  *

package/src/components/AtomixGlass/stories/Examples.stories.tsx

@@ -11,7 +11,7 @@ import React from 'react';
 import { useState, useEffect } from 'react';
 import { Meta, StoryObj } from '@storybook/react';
 import AtomixGlass from '../AtomixGlass';
-import { BackgroundWrapper, backgrounds, backgroundImages } from './shared-components';
+import { BackgroundWrapper, backgroundImages } from './shared-components';
 
 import { Button } from '../../Button';
 import { Badge } from '../../Badge';
@@ -181,7 +181,7 @@ export const VideoBackground: Story = {
             zIndex: -1,
           }}
         >
-          <source src={backgrounds.videoBackground} type="video/mp4" />
+          <source src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4" type="video/mp4" />
         </video>
 
         <div

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

@@ -106,37 +106,6 @@ export const backgroundImages = [
   'https://images.unsplash.com/photo-1521587760476-6c12a4b040da?q=80&w=2940&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D',
 ];
 
-/**
- * Legacy backgrounds object for backward compatibility
- * @deprecated Use backgroundImages array instead
- */
-export const backgrounds = {
-  // Office and workspace environments
-  blueGradient: backgroundImages[0], // Modern office interior
-  purpleGradient: backgroundImages[1], // Mountain landscape
-  greenGradient: backgroundImages[3], // Forest path
-
-  // Apple-inspired natural scenes
-  macosWallpaper: backgroundImages[1], // Mountain landscape
-  iosWallpaper: backgroundImages[4], // Ocean waves
-
-  // Nature scenes
-  mountains: backgroundImages[1], // Mountain landscape
-  ocean: backgroundImages[4], // Ocean waves
-
-  // Urban environments
-  cityNight: backgroundImages[2], // Urban cityscape
-  cityDay: backgroundImages[5], // Modern architecture
-
-  // Interior spaces
-  abstract1: backgroundImages[6], // Cozy café interior
-  abstract2: backgroundImages[9], // Modern library
-
-  // Video backgrounds
-  videoBackground:
-    'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
-};
-
 /**
  * BackgroundWrapper Component Implementation
  *

package/src/components/Avatar/Avatar.stories.tsx

@@ -8,7 +8,14 @@ const meta = {
   component: Avatar,
   parameters: {
     layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'The Avatar component displays user profile images, initials, or icons. It provides a consistent way to represent users throughout the application. Avatars support various sizes, can be circular or square, and gracefully handle missing images by showing initials or icons.',
+      },
+    },
   },
+  tags: ['autodocs'],
   argTypes: {
     src: {
       control: 'text',

package/src/components/Avatar/Avatar.tsx

@@ -1,9 +1,9 @@
-import React, { useState } from 'react';
+import React, { useState, memo } from 'react';
 import { AvatarProps } from '../../lib/types/components';
 import { AVATAR } from '../../lib/constants/components';
 import { Icon } from '../Icon/Icon';
 
-export const Avatar: React.FC<AvatarProps> = ({
+export const Avatar: React.FC<AvatarProps> = memo(({
   src,
   alt = 'Avatar',
   initials,
@@ -62,7 +62,7 @@ export const Avatar: React.FC<AvatarProps> = ({
       )}
     </div>
   );
-};
+});
 
 Avatar.displayName = 'Avatar';
 

package/src/components/Badge/Badge.stories.tsx

@@ -1,3 +1,4 @@
+import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { AtomixGlass } from '../AtomixGlass/AtomixGlass';
 import { BADGE, SIZES, THEME_COLORS } from '../../lib/constants/components';
@@ -11,17 +12,26 @@ const meta = {
   component: Badge,
   parameters: {
     layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'The Badge component displays small pieces of information, status indicators, or labels. It supports multiple variants, sizes, and can include icons. Badges are ideal for highlighting important information or showing status.',
+      },
+    },
   },
+  tags: ['autodocs'],
   argTypes: {
     variant: {
       control: { type: 'select' },
       options: THEME_COLORS,
       description: 'The visual style of the badge',
+      defaultValue: 'primary',
     },
     size: {
       control: { type: 'select' },
       options: SIZES,
       description: 'The size of the badge',
+      defaultValue: 'md',
     },
     disabled: {
       control: 'boolean',
@@ -60,7 +70,9 @@ const Icon = () => (
   </svg>
 );
 
-// Basic Badges
+/**
+ * Primary badge variant - the main badge style.
+ */
 export const Primary: Story = {
   args: {
     label: 'Primary',
@@ -69,6 +81,9 @@ export const Primary: Story = {
   },
 };
 
+/**
+ * Secondary badge variant - used for secondary information.
+ */
 export const Secondary: Story = {
   args: {
     label: 'Secondary',
@@ -77,6 +92,9 @@ export const Secondary: Story = {
   },
 };
 
+/**
+ * Success badge variant - indicates successful or positive status.
+ */
 export const Success: Story = {
   args: {
     label: 'Success',
@@ -85,6 +103,9 @@ export const Success: Story = {
   },
 };
 
+/**
+ * Info badge variant - used for informational status.
+ */
 export const Info: Story = {
   args: {
     label: 'Info',
@@ -93,6 +114,9 @@ export const Info: Story = {
   },
 };
 
+/**
+ * Warning badge variant - indicates caution or warning status.
+ */
 export const Warning: Story = {
   args: {
     label: 'Warning',
@@ -101,7 +125,10 @@ export const Warning: Story = {
   },
 };
 
-export const error: Story = {
+/**
+ * Error badge variant - indicates error or critical status.
+ */
+export const Error: Story = {
   args: {
     label: 'Error',
     variant: 'error',
@@ -109,6 +136,9 @@ export const error: Story = {
   },
 };
 
+/**
+ * Light badge variant - light color scheme.
+ */
 export const Light: Story = {
   args: {
     label: 'Light',
@@ -117,6 +147,9 @@ export const Light: Story = {
   },
 };
 
+/**
+ * Dark badge variant - dark color scheme.
+ */
 export const Dark: Story = {
   args: {
     label: 'Dark',
@@ -125,7 +158,9 @@ export const Dark: Story = {
   },
 };
 
-// Badge Sizes
+/**
+ * Small size badge variant.
+ */
 export const Small: Story = {
   args: {
     label: 'Small',
@@ -134,6 +169,9 @@ export const Small: Story = {
   },
 };
 
+/**
+ * Medium size badge variant (default).
+ */
 export const Medium: Story = {
   args: {
     label: 'Medium',
@@ -142,6 +180,9 @@ export const Medium: Story = {
   },
 };
 
+/**
+ * Large size badge variant.
+ */
 export const Large: Story = {
   args: {
     label: 'Large',
@@ -150,7 +191,9 @@ export const Large: Story = {
   },
 };
 
-// States
+/**
+ * Disabled badge state - non-interactive badge.
+ */
 export const Disabled: Story = {
   args: {
     label: 'Disabled',
@@ -160,7 +203,9 @@ export const Disabled: Story = {
   },
 };
 
-// With Icon
+/**
+ * Badge with icon - displays an icon alongside the label.
+ */
 export const WithIcon: Story = {
   args: {
     label: 'With Icon',
@@ -170,12 +215,21 @@ export const WithIcon: Story = {
   },
 };
 
-// Group of Badge Variants
+/**
+ * Showcase of all badge color variants in a single view.
+ */
 export const AllVariants: Story = {
   args: {
     label: 'Badge',
     variant: 'primary',
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Displays all available badge color variants for easy comparison and selection.',
+      },
+    },
+  },
   render: () => (
     <div className="u-d-flex u-flex-wrap u-gap-2">
       {THEME_COLORS.map(color => (
@@ -185,12 +239,21 @@ export const AllVariants: Story = {
   ),
 };
 
-// Group of Badge Sizes
+/**
+ * Showcase of all badge sizes (small, medium, large) in a single view.
+ */
 export const AllSizes: Story = {
   args: {
     label: 'Badge',
     variant: 'primary',
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Compares all available badge sizes to help choose the appropriate size for your use case.',
+      },
+    },
+  },
   render: () => (
     <div className="u-d-flex u-align-items-center u-gap-2">
       <Badge label="Small" variant="primary" size="sm" />
@@ -200,7 +263,9 @@ export const AllSizes: Story = {
   ),
 };
 
-// With different content
+/**
+ * Badge examples with different content types (numeric, status, with icons).
+ */
 export const WithDifferentContent: Story = {
   args: {
     label: 'Badge with different content',
@@ -241,11 +306,20 @@ export const WithDifferentContent: Story = {
   ),
 };
 
-// Usage examples
+/**
+ * Real-world usage examples showing badges in navigation, cards, and lists.
+ */
 export const UsageExamples: Story = {
   args: {
     label: 'Usage examples',
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Practical examples demonstrating how badges can be used in real-world scenarios such as navigation menus, product cards, and task lists.',
+      },
+    },
+  },
   render: () => (
     <div className="u-d-flex u-flex-column u-gap-6 u-max-width-80">
       <div>
@@ -308,7 +382,9 @@ export const UsageExamples: Story = {
   ),
 };
 
-// Theme-aware demo showing badges in both light and dark mode side by side
+/**
+ * Theme-aware badges demonstrating how they adapt to different theme modes.
+ */
 export const ThemeAwareBadges: Story = {
   args: {
     label: 'Badge',
@@ -359,7 +435,7 @@ export const ThemeAwareBadges: Story = {
           </div>
           <div className="u-d-flex u-align-items-center u-gap-2">
             <span className="u-d-inline-block" style={{ width: '120px' }}>
-              error:
+              Error:
             </span>
             <Badge label="Failed" variant="error" />
           </div>
@@ -375,7 +451,9 @@ export const ThemeAwareBadges: Story = {
   ),
 };
 
-// Glass Variants
+/**
+ * Badge with glass morphism effect - primary variant.
+ */
 export const GlassPrimary: Story = {
   args: {
     label: 'Glass Primary',
@@ -540,7 +618,7 @@ export const GlassCustomSettings: Story = {
       aberrationIntensity: 1,
       cornerRadius: 16,
       mode: 'polar',
-    },
+    } as any,
   },
   decorators: [
     Story => (

package/src/components/Badge/Badge.tsx

@@ -1,10 +1,10 @@
-import React, { useRef } from 'react';
+import React, { useRef, memo } from 'react';
 import { useBadge } from '../../lib/composables/useBadge';
 import { BADGE } from '../../lib/constants/components';
 import { BadgeProps } from '../../lib/types/components';
 import { AtomixGlass } from '../AtomixGlass/AtomixGlass';
 
-export const Badge: React.FC<BadgeProps> = ({
+export const Badge: React.FC<BadgeProps> = memo(({
   label,
   variant = 'primary',
   size = 'md',
@@ -53,7 +53,7 @@ export const Badge: React.FC<BadgeProps> = ({
   }
 
   return badgeElement;
-};
+});
 
 Badge.displayName = 'Badge';
 

package/src/components/Block/Block.stories.tsx

@@ -5,43 +5,27 @@ import { Button } from '../Button/Button';
 import { Card } from '../Card/Card';
 import { Block } from './Block';
 
-const meta: Meta<typeof Block> = {
+const meta = {
   title: 'Components/Block',
   component: Block,
   parameters: {
     layout: 'fullscreen',
     docs: {
       description: {
-        component: `
-The Block component is a flexible layout container designed for creating consistent section layouts.
-It provides standardized spacing, background variants, and container behavior for organizing content
-into distinct sections or blocks.
-
-## Key Features
-- **Flexible spacing**: Multiple spacing sizes (xs, sm, md, lg, xl, none)
-- **Background variants**: Transparent, subtle, muted, primary, secondary, accent
-- **Container integration**: Built-in Container support for responsive layouts
-- **Semantic HTML**: Configurable as section, div, article, aside, or main
-- **Full-width support**: Option for edge-to-edge content
-
-## Usage Guidelines
-Use Block components to:
-- Create consistent section spacing across pages
-- Group related content with appropriate backgrounds
-- Build hero sections, content areas, and feature blocks
-- Maintain visual hierarchy and rhythm in layouts
-        `,
+        component:
+          'The Block component is a flexible layout container designed for creating consistent section layouts. It provides standardized spacing, background variants, and container behavior for organizing content into distinct sections or blocks. Blocks are ideal for hero sections, content areas, feature blocks, and maintaining visual hierarchy.',
       },
     },
   },
+  tags: ['autodocs'],
   argTypes: {
     as: {
-      control: 'select',
+      control: { type: 'select' },
       options: ['section', 'div', 'article', 'aside', 'main'],
       description: 'The HTML element to render as',
     },
     spacing: {
-      control: 'select',
+      control: { type: 'select' },
       options: ['xs', 'sm', 'md', 'lg', 'xl', 'none'],
       description: 'Vertical padding size',
     },
@@ -54,7 +38,7 @@ Use Block components to:
       description: 'Content to render within the block',
     },
   },
-};
+} satisfies Meta<typeof Block>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;

package/src/components/Breadcrumb/Breadcrumb.stories.tsx

@@ -7,7 +7,14 @@ const meta = {
   component: Breadcrumb,
   parameters: {
     layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'The Breadcrumb component provides navigation context by showing the current page location within a site hierarchy. It helps users understand where they are and provides quick navigation to parent pages. Breadcrumbs support custom dividers, icons, and are fully accessible.',
+      },
+    },
   },
+  tags: ['autodocs'],
   argTypes: {
     items: { control: 'object' },
     divider: { control: 'text' },