@shohojdhara/atomix 0.3.15 → 0.4.0

package/src/lib/theme-tools.ts

@@ -1,6 +1,6 @@
 /**
  * Theme Tools for Library Users
- * 
+ *
  * Developer-friendly utilities for working with Atomix themes
  */
 
@@ -49,7 +49,7 @@ export function createDarkVariant(lightTheme: Theme): Theme {
       },
     },
   };
-  
+
   // Create a new theme by extending the light theme with the dark variant
   const extendedTheme: Theme = {
     ...lightTheme,
@@ -67,7 +67,7 @@ export function createDarkVariant(lightTheme: Theme): Theme {
       },
     },
   };
-  
+
   return extendedTheme;
 }
 
@@ -125,9 +125,11 @@ export function getThemeMetadata(theme: Theme): ThemeMetadata {
  * Check if theme supports dark mode
  */
 export function supportsDarkMode(theme: Theme): boolean {
-  return theme.palette?.mode === 'dark' ||
+  return (
+    theme.palette?.mode === 'dark' ||
     theme.supportsDarkMode === true ||
-    Boolean(theme.a11y?.modes?.includes('dark'));
+    Boolean(theme.a11y?.modes?.includes('dark'))
+  );
 }
 
 /**
@@ -150,4 +152,4 @@ export function importTheme(json: string): Theme {
 
 // Note: createTheme, extendTheme, mergeTheme, and generateCSSVariables
 // are already exported from './theme' module. Import them directly from there.
-// This file only exports theme-tools specific utilities.
+// This file only exports theme-tools specific utilities.

package/src/lib/types/components.ts

@@ -1,7 +1,44 @@
 import { ReactNode } from 'react';
-import type { ButtonParts, CardParts, InputParts, ModalParts, DropdownParts, BadgeParts, ProgressParts, CheckboxParts, RadioParts } from './partProps';
-import type { SlotProps, ButtonRootSlotProps, ButtonIconSlotProps, ButtonLabelSlotProps, ButtonSpinnerSlotProps, BadgeRootSlotProps, BadgeIconSlotProps, BadgeLabelSlotProps, ProgressRootSlotProps, ProgressBarSlotProps, CheckboxRootSlotProps, CheckboxInputSlotProps, CheckboxLabelSlotProps, RadioRootSlotProps, RadioInputSlotProps, RadioLabelSlotProps } from '../patterns/slots';
-import type { ButtonCSSVariable, CardCSSVariable, InputCSSVariable, ModalCSSVariable, DropdownCSSVariable, BadgeCSSVariable, ProgressCSSVariable, CheckboxCSSVariable, RadioCSSVariable } from '../constants/cssVariables';
+import type {
+  ButtonParts,
+  CardParts,
+  InputParts,
+  ModalParts,
+  DropdownParts,
+  BadgeParts,
+  ProgressParts,
+  CheckboxParts,
+  RadioParts,
+} from './partProps';
+import type {
+  SlotProps,
+  ButtonRootSlotProps,
+  ButtonIconSlotProps,
+  ButtonLabelSlotProps,
+  ButtonSpinnerSlotProps,
+  BadgeRootSlotProps,
+  BadgeIconSlotProps,
+  BadgeLabelSlotProps,
+  ProgressRootSlotProps,
+  ProgressBarSlotProps,
+  CheckboxRootSlotProps,
+  CheckboxInputSlotProps,
+  CheckboxLabelSlotProps,
+  RadioRootSlotProps,
+  RadioInputSlotProps,
+  RadioLabelSlotProps,
+} from '../patterns/slots';
+import type {
+  ButtonCSSVariable,
+  CardCSSVariable,
+  InputCSSVariable,
+  ModalCSSVariable,
+  DropdownCSSVariable,
+  BadgeCSSVariable,
+  ProgressCSSVariable,
+  CheckboxCSSVariable,
+  RadioCSSVariable,
+} from '../constants/cssVariables';
 
 // ============================================================================
 // AtomixGlass Types
@@ -199,7 +236,14 @@ export interface AtomixGlassProps {
   /**
    * Shader variant for shader mode
    */
-  shaderVariant?: 'liquidGlass' | 'premiumGlass' | 'appleFluid' | 'liquidMetal' | 'plasma' | 'waves' | 'noise';
+  shaderVariant?:
+    | 'liquidGlass'
+    | 'premiumGlass'
+    | 'appleFluid'
+    | 'liquidMetal'
+    | 'plasma'
+    | 'waves'
+    | 'noise';
 
   /**
    * Accessibility props
@@ -914,14 +958,40 @@ export interface HeroBackgroundSliderConfig {
   customTransition?: (currentIndex: number, nextIndex: number) => string | React.CSSProperties;
 }
 
+/**
+ * Hero component parts for granular styling
+ */
+export interface HeroParts {
+  root?: { className?: string; style?: React.CSSProperties };
+  container?: { className?: string; style?: React.CSSProperties };
+  grid?: { className?: string; style?: React.CSSProperties };
+  content?: { className?: string; style?: React.CSSProperties };
+  title?: { className?: string; style?: React.CSSProperties };
+  subtitle?: { className?: string; style?: React.CSSProperties };
+  text?: { className?: string; style?: React.CSSProperties };
+  actions?: { className?: string; style?: React.CSSProperties };
+  imageWrapper?: { className?: string; style?: React.CSSProperties };
+  image?: { className?: string; style?: React.CSSProperties };
+  background?: { className?: string; style?: React.CSSProperties };
+  overlay?: { className?: string; style?: React.CSSProperties };
+}
+
 /**
  * Hero component properties
  */
-export interface HeroProps extends BaseComponentProps {
+export interface HeroProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title' | 'content'>,
+    BaseComponentProps {
   /**
    * Hero title
    */
-  title: string;
+  title: ReactNode;
+
+  /**
+   * HTML Heading level for the title
+   * @default 'h1'
+   */
+  headingLevel?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'div';
 
   /**
    * Hero subtitle
@@ -973,11 +1043,31 @@ export interface HeroProps extends BaseComponentProps {
    */
   imageColSize?: number;
 
+  /**
+   * Custom grid column class name for image
+   */
+  imageColClassName?: string;
+
+  /**
+   * Custom inline style for image column
+   */
+  imageColStyle?: React.CSSProperties;
+
   /**
    * Custom grid column size for content (default is 5)
    */
   contentColSize?: number;
 
+  /**
+   * Custom grid column class name for content
+   */
+  contentColClassName?: string;
+
+  /**
+   * Custom inline style for content column
+   */
+  contentColStyle?: React.CSSProperties;
+
   /**
    * Custom width for the hero content (overrides the default CSS variable)
    */
@@ -1039,6 +1129,17 @@ export interface HeroProps extends BaseComponentProps {
    * Takes precedence over backgroundImageSrc and videoBackground props
    */
   backgroundSlider?: HeroBackgroundSliderConfig;
+
+  /**
+   * Reverse the stacking order of content and image on mobile devices
+   * @default false
+   */
+  reverseOnMobile?: boolean;
+
+  /**
+   * Granular part-based styling
+   */
+  parts?: HeroParts;
 }
 
 /**
@@ -1468,16 +1569,16 @@ export interface SideMenuProps extends BaseComponentProps {
       active?: boolean | undefined;
       disabled?: boolean | undefined;
       as?:
-      | React.ComponentType<{
-        href?: string;
-        to?: string;
-        children: React.ReactNode;
-        className?: string;
-        onClick?: (event: React.MouseEvent) => void;
-        target?: string;
-        rel?: string;
-      }>
-      | undefined;
+        | React.ComponentType<{
+            href?: string;
+            to?: string;
+            children: React.ReactNode;
+            className?: string;
+            onClick?: (event: React.MouseEvent) => void;
+            target?: string;
+            rel?: string;
+          }>
+        | undefined;
     }>;
   }>;
 }
@@ -3677,17 +3778,17 @@ export interface VideoPlayerProps extends BaseComponentProps {
    * - object: Custom glass configuration
    */
   glass?:
-  | boolean
-  | {
-    displacementScale?: number;
-    blurAmount?: number;
-    saturation?: number;
-    aberrationIntensity?: number;
-    elasticity?: number;
-    cornerRadius?: number;
-    mode?: 'standard' | 'polar' | 'prominent' | 'shader';
-    overLight?: boolean;
-  };
+    | boolean
+    | {
+        displacementScale?: number;
+        blurAmount?: number;
+        saturation?: number;
+        aberrationIntensity?: number;
+        elasticity?: number;
+        cornerRadius?: number;
+        mode?: 'standard' | 'polar' | 'prominent' | 'shader';
+        overLight?: boolean;
+      };
 
   /**
    * Glass overlay opacity (0-1) when glass variant is enabled
@@ -5075,23 +5176,23 @@ export interface SliderProps extends BaseComponentProps {
    * Whether to enable mouse wheel control
    */
   mousewheel?:
-  | boolean
-  | {
-    forceToAxis?: boolean;
-    sensitivity?: number;
-    releaseOnEdges?: boolean;
-  };
+    | boolean
+    | {
+        forceToAxis?: boolean;
+        sensitivity?: number;
+        releaseOnEdges?: boolean;
+      };
 
   /**
    * Whether to enable keyboard control
    */
   keyboard?:
-  | boolean
-  | {
-    enabled?: boolean;
-    onlyInViewport?: boolean;
-    pageUpDown?: boolean;
-  };
+    | boolean
+    | {
+        enabled?: boolean;
+        onlyInViewport?: boolean;
+        pageUpDown?: boolean;
+      };
 
   /**
    * Whether to grab cursor on hover (default: true)
@@ -5154,16 +5255,16 @@ export interface SliderProps extends BaseComponentProps {
    * Whether to free mode (no snap to slides)
    */
   freeMode?:
-  | boolean
-  | {
-    enabled?: boolean;
-    sticky?: boolean;
-    momentumRatio?: number;
-    momentumVelocityRatio?: number;
-    momentumBounce?: boolean;
-    momentumBounceRatio?: number;
-    minimumVelocity?: number;
-  };
+    | boolean
+    | {
+        enabled?: boolean;
+        sticky?: boolean;
+        momentumRatio?: number;
+        momentumVelocityRatio?: number;
+        momentumBounce?: boolean;
+        momentumBounceRatio?: number;
+        minimumVelocity?: number;
+      };
 
   /**
    * Whether to watch for slides and wrapper size changes
@@ -5199,23 +5300,23 @@ export interface SliderProps extends BaseComponentProps {
    * Hash navigation
    */
   hashNavigation?:
-  | boolean
-  | {
-    watchState?: boolean;
-    replaceState?: boolean;
-  };
+    | boolean
+    | {
+        watchState?: boolean;
+        replaceState?: boolean;
+      };
 
   /**
    * History navigation
    */
   history?:
-  | boolean
-  | {
-    enabled?: boolean;
-    root?: string;
-    replaceState?: boolean;
-    key?: string;
-  };
+    | boolean
+    | {
+        enabled?: boolean;
+        root?: string;
+        replaceState?: boolean;
+        key?: string;
+      };
 
   /**
    * Controller configuration
@@ -5230,16 +5331,16 @@ export interface SliderProps extends BaseComponentProps {
    * A11y configuration
    */
   a11y?:
-  | boolean
-  | {
-    enabled?: boolean;
-    prevSlideMessage?: string;
-    nextSlideMessage?: string;
-    firstSlideMessage?: string;
-    lastSlideMessage?: string;
-    paginationBulletMessage?: string;
-    notificationClass?: string;
-  };
+    | boolean
+    | {
+        enabled?: boolean;
+        prevSlideMessage?: string;
+        nextSlideMessage?: string;
+        firstSlideMessage?: string;
+        lastSlideMessage?: string;
+        paginationBulletMessage?: string;
+        notificationClass?: string;
+      };
 
   /**
    * Slide change callback

package/src/lib/types/partProps.ts

@@ -1,6 +1,6 @@
 /**
  * Part-Based Styling Props
- * 
+ *
  * Type definitions for styling individual component parts with className and style props.
  * This enables granular customization of component internals.
  */

package/src/lib/utils/__tests__/csv.test.ts

@@ -40,6 +40,6 @@ describe('sanitizeCSVCell', () => {
 
   it('should handle mixed cases', () => {
     // Dangerous character + quotes + newlines
-    expect(sanitizeCSVCell('=cmd|\' /C calc\'!A0\n')).toBe("'=cmd|' /C calc'!A0 ");
+    expect(sanitizeCSVCell("=cmd|' /C calc'!A0\n")).toBe("'=cmd|' /C calc'!A0 ");
   });
 });

package/src/lib/utils/componentUtils.ts

@@ -1,6 +1,6 @@
 /**
  * Component Utilities
- * 
+ *
  * Helper functions for component development with the new customization system
  */
 
@@ -39,7 +39,7 @@ export function createCSSVarStyle(
   baseStyle?: React.CSSProperties
 ): React.CSSProperties {
   if (!cssVars) return baseStyle || {};
-  
+
   const varStyle = cssVarsToStyle(cssVars);
   return { ...varStyle, ...baseStyle };
 }
@@ -102,11 +102,7 @@ export function createPartProps<T extends { className?: string; style?: React.CS
 /**
  * Check if component has customization
  */
-export function hasCustomization(props: {
-  parts?: any;
-  cssVars?: any;
-  slots?: any;
-}): boolean {
+export function hasCustomization(props: { parts?: any; cssVars?: any; slots?: any }): boolean {
   return Boolean(props.parts || props.cssVars || props.slots);
 }
 
@@ -115,7 +111,7 @@ export function hasCustomization(props: {
  */
 export function createDebugAttrs(componentName: string, variant?: string): Record<string, string> {
   if (typeof process === 'undefined' || process.env?.NODE_ENV !== 'development') return {};
-  
+
   return {
     'data-component': componentName,
     ...(variant && { 'data-variant': variant }),
@@ -126,7 +122,7 @@ export function createDebugAttrs(componentName: string, variant?: string): Recor
  * Generate a UUID v4
  */
 export function generateUUID(): string {
-  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
     const r = (Math.random() * 16) | 0;
     const v = c === 'x' ? r : (r & 0x3) | 0x8;
     return v.toString(16);
@@ -146,18 +142,18 @@ export function isYouTubeUrl(url: string): boolean {
  */
 export function extractYouTubeId(url: string): string | null {
   if (!isYouTubeUrl(url)) return null;
-  
+
   const patterns = [
     /(?:youtube\.com\/watch\?v=|youtu\.be\/|youtube\.com\/embed\/)([^&\n?#]+)/,
     /youtube\.com\/.*[?&]v=([^&\n?#]+)/,
   ];
-  
+
   for (const pattern of patterns) {
     const match = url.match(pattern);
     if (match && match[1]) {
       return match[1];
     }
   }
-  
+
   return null;
 }

package/src/lib/utils/csv.ts

@@ -10,7 +10,9 @@
  * to prevent formula injection.
  */
 export function sanitizeCSVCell(cell: any): string {
-  const sanitized = String(cell ?? '').replace(/[\r\n\t]/g, ' ').replace(/"/g, '""');
+  const sanitized = String(cell ?? '')
+    .replace(/[\r\n\t]/g, ' ')
+    .replace(/"/g, '""');
   // Prevent formula injection by prefixing dangerous characters
   const dangerous = /^[=+\-@]/;
   return dangerous.test(sanitized) ? `'${sanitized}` : sanitized;

package/src/lib/utils/dataTableExport.ts

@@ -46,10 +46,7 @@ export function exportToCSV(
 /**
  * Export data as JSON
  */
-export function exportToJSON(
-  data: any[],
-  filename: string = 'data-table.json'
-): void {
+export function exportToJSON(data: any[], filename: string = 'data-table.json'): void {
   if (!data.length) return;
 
   const jsonContent = JSON.stringify(data, null, 2);
@@ -131,4 +128,3 @@ export function exportData(
       console.warn(`Unsupported export format: ${format}`);
   }
 }
-

package/src/lib/utils/fontPreloader.ts

@@ -1,6 +1,6 @@
 /**
  * Font Preloading Utilities
- * 
+ *
  * Provides utilities for preloading fonts to improve performance
  * and prevent Flash of Invisible Text (FOIT).
  */
@@ -34,10 +34,10 @@ export interface FontPreloadConfig {
 
 /**
  * Creates a preload link element for a font
- * 
+ *
  * @param config - Font preload configuration
  * @returns HTML link element for preloading
- * 
+ *
  * @example
  * ```tsx
  * const preloadLink = createFontPreloadLink({
@@ -49,11 +49,7 @@ export interface FontPreloadConfig {
  * ```
  */
 export function createFontPreloadLink(config: FontPreloadConfig): HTMLLinkElement {
-  const {
-    path,
-    format = 'woff2',
-    crossorigin = 'anonymous',
-  } = config;
+  const { path, format = 'woff2', crossorigin = 'anonymous' } = config;
 
   const link = document.createElement('link');
   link.rel = 'preload';
@@ -67,10 +63,10 @@ export function createFontPreloadLink(config: FontPreloadConfig): HTMLLinkElemen
 
 /**
  * Preloads multiple fonts
- * 
+ *
  * @param fonts - Array of font configurations to preload
  * @returns Array of created link elements
- * 
+ *
  * @example
  * ```tsx
  * const links = preloadFonts([
@@ -87,10 +83,10 @@ export function preloadFonts(fonts: FontPreloadConfig[]): HTMLLinkElement[] {
 /**
  * Generates preload link HTML tags as strings
  * Useful for server-side rendering or static HTML generation
- * 
+ *
  * @param fonts - Array of font configurations
  * @returns Array of HTML string representations
- * 
+ *
  * @example
  * ```tsx
  * const htmlTags = generateFontPreloadTags([
@@ -100,12 +96,8 @@ export function preloadFonts(fonts: FontPreloadConfig[]): HTMLLinkElement[] {
  * ```
  */
 export function generateFontPreloadTags(fonts: FontPreloadConfig[]): string[] {
-  return fonts.map((config) => {
-    const {
-      path,
-      format = 'woff2',
-      crossorigin = 'anonymous',
-    } = config;
+  return fonts.map(config => {
+    const { path, format = 'woff2', crossorigin = 'anonymous' } = config;
 
     return `<link rel="preload" as="font" href="${path}" type="font/${format}" crossorigin="${crossorigin}">`;
   });
@@ -145,4 +137,3 @@ export const DEFAULT_ATOMIX_FONTS: FontPreloadConfig[] = [
     format: 'woff2',
   },
 ];
-

package/src/lib/utils/icons.ts

@@ -35,7 +35,10 @@ export function createPhosphorIcon(name: string, size: number = 16): string {
   const path = ICON_PATHS[name] || '';
 
   if (!path) {
-    console.warn('Icon not found in icon library:', typeof name === 'string' ? name.replace(/[^a-zA-Z0-9_-]/g, '_') : 'invalid_name');
+    console.warn(
+      'Icon not found in icon library:',
+      typeof name === 'string' ? name.replace(/[^a-zA-Z0-9_-]/g, '_') : 'invalid_name'
+    );
   }
 
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" fill="currentColor" viewBox="0 0 256 256">

package/src/lib/utils/index.ts

@@ -16,9 +16,7 @@ export {
   extractYouTubeId,
 } from './componentUtils';
 
-export type {
-  MergePropsOptions,
-} from './componentUtils';
+export type { MergePropsOptions } from './componentUtils';
 
 export {
   createFontPreloadLink,
@@ -27,6 +25,4 @@ export {
   DEFAULT_ATOMIX_FONTS,
 } from './fontPreloader';
 
-export type {
-  FontPreloadConfig,
-} from './fontPreloader';
+export type { FontPreloadConfig } from './fontPreloader';

package/src/lib/utils/memoryMonitor.ts

@@ -1,6 +1,6 @@
 /**
  * Memory Monitoring Utilities
- * 
+ *
  * Detects memory leaks and tracks component lifecycle memory usage
  * Only available in development mode
  */
@@ -40,7 +40,7 @@ export function isMemoryMonitoringAvailable(): boolean {
 
 /**
  * Get current memory usage snapshot
- * 
+ *
  * @returns Memory snapshot or null if not available
  */
 export function getMemorySnapshot(): MemorySnapshot | null {
@@ -60,7 +60,7 @@ export function getMemorySnapshot(): MemorySnapshot | null {
 
 /**
  * Format bytes to human-readable string
- * 
+ *
  * @param bytes - Number of bytes
  * @returns Formatted string (e.g., "1.5 MB")
  */
@@ -76,7 +76,7 @@ export function formatBytes(bytes: number): string {
 
 /**
  * Compare two memory snapshots and detect potential leaks
- * 
+ *
  * @param before - Snapshot before operation
  * @param after - Snapshot after operation
  * @param threshold - Threshold in bytes to consider a leak (default: 5MB)
@@ -114,7 +114,7 @@ export function detectMemoryLeak(
 
 /**
  * Monitor memory usage over time
- * 
+ *
  * @param interval - Interval in milliseconds to check memory
  * @param callback - Callback function called with each snapshot
  * @returns Function to stop monitoring
@@ -156,7 +156,7 @@ export function monitorMemoryUsage(
 
 /**
  * Track component lifecycle memory usage
- * 
+ *
  * @param componentName - Name of the component
  * @returns Object with start and end tracking functions
  */
@@ -175,7 +175,10 @@ export function trackComponentMemory(componentName: string) {
       const after = getMemorySnapshot();
       if (before && after) {
         const leakInfo = detectMemoryLeak(before, after);
-        if (leakInfo.hasLeak && (typeof process === 'undefined' || process.env?.NODE_ENV === 'development')) {
+        if (
+          leakInfo.hasLeak &&
+          (typeof process === 'undefined' || process.env?.NODE_ENV === 'development')
+        ) {
           console.warn(
             `[Memory Monitor] Potential memory leak detected in ${componentName}:`,
             leakInfo
@@ -186,4 +189,3 @@ export function trackComponentMemory(componentName: string) {
     },
   };
 }
-