@shohojdhara/atomix 0.3.2 → 0.3.4

package/src/lib/composables/useTooltip.ts

@@ -0,0 +1,285 @@
+import { useState, useRef, useEffect, RefObject, useCallback } from 'react';
+
+export type TooltipPosition =
+  | 'top'
+  | 'bottom'
+  | 'left'
+  | 'right'
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right';
+
+export type TooltipTrigger = 'click' | 'hover';
+
+interface UseTooltipProps {
+  position?: TooltipPosition;
+  trigger?: TooltipTrigger;
+  offset?: number;
+  delay?: number;
+}
+
+interface TooltipStyles {
+  tooltip: React.CSSProperties;
+  arrow: React.CSSProperties;
+}
+
+interface UseTooltipResult {
+  isVisible: boolean;
+  isPositioned: boolean;
+  tooltipId: string;
+  triggerRef: RefObject<HTMLDivElement>;
+  tooltipRef: RefObject<HTMLDivElement>;
+  tooltipStyle: React.CSSProperties;
+  arrowStyle: React.CSSProperties;
+  showTooltip: () => void;
+  hideTooltip: () => void;
+  toggleTooltip: () => void;
+  triggerProps: React.HTMLAttributes<HTMLDivElement>;
+  wrapperProps: React.HTMLAttributes<HTMLDivElement>;
+}
+
+/**
+ * Calculate tooltip and arrow positions based on trigger and tooltip dimensions
+ */
+const calculateTooltipPosition = (
+  position: TooltipPosition,
+  triggerRect: DOMRect,
+  tooltipRect: DOMRect,
+  wrapperRect: DOMRect,
+  offset: number,
+  arrowSize: number
+): TooltipStyles => {
+  const tooltipWidth = tooltipRect.width || 0;
+  const tooltipHeight = tooltipRect.height || 0;
+  const triggerWidth = triggerRect.width;
+  const triggerHeight = triggerRect.height;
+
+  const tooltipStyle: React.CSSProperties = {
+    '--atomix-tooltip-offset': `${offset}px`,
+  } as React.CSSProperties;
+
+  const arrowStyle: React.CSSProperties = {};
+
+  switch (position) {
+    case 'top':
+      tooltipStyle.top = `${triggerRect.top - wrapperRect.top - tooltipHeight - offset}px`;
+      tooltipStyle.left = `${triggerRect.left - wrapperRect.left + triggerWidth / 2 - tooltipWidth / 2}px`;
+      arrowStyle.bottom = `${arrowSize / -2}px`;
+      arrowStyle.left = `${tooltipWidth / 2 - arrowSize / 2}px`;
+      break;
+
+    case 'bottom':
+      tooltipStyle.top = `${triggerRect.bottom - wrapperRect.top + offset}px`;
+      tooltipStyle.left = `${triggerRect.left - wrapperRect.left + triggerWidth / 2 - tooltipWidth / 2}px`;
+      arrowStyle.top = `${arrowSize / -2}px`;
+      arrowStyle.left = `${tooltipWidth / 2 - arrowSize / 2}px`;
+      break;
+
+    case 'left':
+      tooltipStyle.right = `${wrapperRect.right - triggerRect.left + offset}px`;
+      tooltipStyle.top = `${triggerRect.top - wrapperRect.top + triggerHeight / 2 - tooltipHeight / 2}px`;
+      arrowStyle.right = `${arrowSize / -2}px`;
+      arrowStyle.top = `${tooltipHeight / 2 - arrowSize / 2}px`;
+      break;
+
+    case 'right':
+      tooltipStyle.left = `${triggerRect.right - wrapperRect.left + offset}px`;
+      tooltipStyle.top = `${triggerRect.top - wrapperRect.top + triggerHeight / 2 - tooltipHeight / 2}px`;
+      arrowStyle.left = `${arrowSize / -2}px`;
+      arrowStyle.top = `${tooltipHeight / 2 - arrowSize / 2}px`;
+      break;
+
+    case 'top-left':
+      tooltipStyle.bottom = `${wrapperRect.bottom - triggerRect.top + offset}px`;
+      tooltipStyle.left = `${triggerRect.left - wrapperRect.left}px`;
+      arrowStyle.bottom = `${arrowSize / -2}px`;
+      arrowStyle.left = `${arrowSize}px`;
+      break;
+
+    case 'top-right':
+      tooltipStyle.bottom = `${wrapperRect.bottom - triggerRect.top + offset}px`;
+      tooltipStyle.right = `${wrapperRect.right - triggerRect.right}px`;
+      arrowStyle.bottom = `${arrowSize / -2}px`;
+      arrowStyle.right = `${arrowSize}px`;
+      break;
+
+    case 'bottom-left':
+      tooltipStyle.top = `${triggerRect.bottom - wrapperRect.top + offset}px`;
+      tooltipStyle.left = `${triggerRect.left - wrapperRect.left}px`;
+      arrowStyle.top = `${arrowSize / -2}px`;
+      arrowStyle.left = `${arrowSize}px`;
+      break;
+
+    case 'bottom-right':
+      tooltipStyle.top = `${triggerRect.bottom - wrapperRect.top + offset}px`;
+      tooltipStyle.right = `${wrapperRect.right - triggerRect.right}px`;
+      arrowStyle.top = `${arrowSize / -2}px`;
+      arrowStyle.right = `${arrowSize}px`;
+      break;
+  }
+
+  return { tooltip: tooltipStyle, arrow: arrowStyle };
+};
+
+/**
+ * Get arrow size from CSS custom property
+ */
+const getArrowSize = (element: HTMLElement): number => {
+  const arrowSizeValue = getComputedStyle(element)
+    .getPropertyValue('--atomix-tooltip-arrow-size')
+    .trim();
+
+  if (!arrowSizeValue) return 8; // Default fallback
+
+  // Try to parse as rem (e.g., "0.5rem")
+  const remMatch = arrowSizeValue.match(/([\d.]+)rem/);
+  if (remMatch?.[1]) {
+    return parseFloat(remMatch[1]) * 16; // Convert rem to px
+  }
+
+  // Try to parse as px (e.g., "8px")
+  const pxMatch = arrowSizeValue.match(/([\d.]+)px/);
+  if (pxMatch?.[1]) {
+    return parseFloat(pxMatch[1]);
+  }
+
+  return 8; // Default fallback
+};
+
+/**
+ * Hook for managing tooltip state and positioning logic
+ */
+export const useTooltip = ({
+  position = 'top',
+  trigger = 'hover',
+  offset = 10,
+  delay = 200,
+}: UseTooltipProps): UseTooltipResult => {
+  const [isVisible, setIsVisible] = useState(false);
+  const [isPositioned, setIsPositioned] = useState(false);
+  const [tooltipStyle, setTooltipStyle] = useState<React.CSSProperties>({});
+  const [arrowStyle, setArrowStyle] = useState<React.CSSProperties>({});
+  
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const triggerRef = useRef<HTMLDivElement>(null);
+  const tooltipRef = useRef<HTMLDivElement>(null);
+  const tooltipId = `tooltip-${Math.random().toString(36).slice(2, 11)}`;
+
+  const showTooltip = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+
+    if (delay > 0) {
+      timeoutRef.current = setTimeout(() => {
+        setIsVisible(true);
+      }, delay);
+    } else {
+      setIsVisible(true);
+    }
+  }, [delay]);
+
+  const hideTooltip = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+    setIsVisible(false);
+    setIsPositioned(false);
+  }, []);
+
+  const toggleTooltip = useCallback(() => {
+    if (isVisible) {
+      hideTooltip();
+    } else {
+      showTooltip();
+    }
+  }, [isVisible, showTooltip, hideTooltip]);
+
+  // Calculate and update tooltip position
+  const updatePosition = useCallback(() => {
+    if (!triggerRef.current || !tooltipRef.current) return;
+
+    const triggerRect = triggerRef.current.getBoundingClientRect();
+    const tooltipRect = tooltipRef.current.getBoundingClientRect();
+    const wrapperElement = triggerRef.current.parentElement;
+
+    if (!wrapperElement) return;
+
+    const wrapperRect = wrapperElement.getBoundingClientRect();
+    const arrowSize = getArrowSize(tooltipRef.current);
+
+    const styles = calculateTooltipPosition(
+      position,
+      triggerRect,
+      tooltipRect,
+      wrapperRect,
+      offset,
+      arrowSize
+    );
+
+    setTooltipStyle(styles.tooltip);
+    setArrowStyle(styles.arrow);
+    setIsPositioned(true);
+  }, [position, offset]);
+
+  // Position tooltip when visible
+  useEffect(() => {
+    if (!isVisible || !triggerRef.current || !tooltipRef.current) {
+      return;
+    }
+
+    // Use single RAF to ensure tooltip is rendered before calculating
+    const rafId = requestAnimationFrame(() => {
+      updatePosition();
+    });
+
+    // Recalculate on window resize and scroll
+    const handleUpdate = () => {
+      updatePosition();
+    };
+
+    window.addEventListener('resize', handleUpdate);
+    window.addEventListener('scroll', handleUpdate, true);
+
+    return () => {
+      cancelAnimationFrame(rafId);
+      window.removeEventListener('resize', handleUpdate);
+      window.removeEventListener('scroll', handleUpdate, true);
+    };
+  }, [isVisible, updatePosition]);
+
+  // Setup trigger props
+  const triggerProps: React.HTMLAttributes<HTMLDivElement> = {
+    'aria-describedby': isVisible ? tooltipId : undefined,
+  };
+
+  const wrapperProps: React.HTMLAttributes<HTMLDivElement> = {};
+
+  if (trigger === 'hover') {
+    wrapperProps.onMouseEnter = showTooltip;
+    wrapperProps.onMouseLeave = hideTooltip;
+    triggerProps.onFocus = showTooltip;
+    triggerProps.onBlur = hideTooltip;
+  } else if (trigger === 'click') {
+    triggerProps.onClick = toggleTooltip;
+  }
+
+  return {
+    isVisible,
+    isPositioned,
+    tooltipId,
+    triggerRef,
+    tooltipRef,
+    tooltipStyle,
+    arrowStyle,
+    showTooltip,
+    hideTooltip,
+    toggleTooltip,
+    triggerProps,
+    wrapperProps,
+  };
+};
+
+export default useTooltip;
+

package/src/lib/config/index.ts

@@ -0,0 +1,275 @@
+/**
+ * Atomix Configuration System
+ * 
+ * Tailwind-like configuration for customizing the Atomix Design System.
+ * 
+ * External developers can create `atomix.config.ts` in their project root
+ * to customize design tokens, similar to Tailwind's tailwind.config.js
+ * 
+ * @example
+ * ```typescript
+ * // atomix.config.ts (in your project)
+ * import { defineConfig } from '@shohojdhara/atomix/config';
+ * 
+ * export default defineConfig({
+ *   theme: {
+ *     extend: {
+ *       colors: {
+ *         primary: { main: '#7AFFD7' },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+
+import type { Theme } from '../theme/types';
+
+/**
+ * Color Scale (1-10)
+ */
+export interface ColorScale {
+    1?: string;
+    2?: string;
+    3?: string;
+    4?: string;
+    5?: string;
+    6?: string;
+    7?: string;
+    8?: string;
+    9?: string;
+    10?: string;
+    [key: string]: string | undefined;
+}
+
+/**
+ * Palette Color Options
+ */
+export interface PaletteColorOptions {
+    main: string;
+    light?: string;
+    dark?: string;
+    contrastText?: string;
+}
+
+/**
+ * Design Tokens Schema (Tailwind-like)
+ */
+export interface ThemeTokens {
+    /** Color palette */
+    colors?: Record<string, string | PaletteColorOptions | ColorScale | Record<string, string>>;
+    /** Spacing scale */
+    spacing?: Record<string, string>;
+    /** Border radius scale */
+    borderRadius?: Record<string, string>;
+    /** Typography scale and settings */
+    typography?: {
+        fontFamilies?: Record<string, string>;
+        fontSizes?: Record<string, string>;
+        fontWeights?: Record<string, string | number>;
+        lineHeights?: Record<string, string | number>;
+        letterSpacings?: Record<string, string>;
+    };
+    /** Shadow scale */
+    shadows?: Record<string, string>;
+    /** Z-index scale */
+    zIndex?: Record<string, string | number>;
+    /** Breakpoints scale */
+    breakpoints?: Record<string, string | number>;
+    /** Transitions settings */
+    transitions?: {
+        durations?: Record<string, string>;
+        easings?: Record<string, string>;
+    };
+}
+
+/**
+ * CSS Theme Definition
+ */
+export interface CSSThemeDefinition {
+    type: 'css';
+    name: string;
+    class?: string;
+    description?: string;
+    author?: string;
+    version?: string;
+    tags?: string[];
+    supportsDarkMode?: boolean;
+    status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
+    a11y?: {
+        contrastTarget?: number;
+        modes?: string[];
+    };
+    color?: string;
+    features?: string[];
+    dependencies?: string[];
+    cssPath?: string;
+}
+
+/**
+ * JavaScript Theme Definition
+ */
+export interface JSThemeDefinition {
+    type: 'js';
+    name: string;
+    class?: string;
+    description?: string;
+    author?: string;
+    version?: string;
+    tags?: string[];
+    supportsDarkMode?: boolean;
+    status?: 'stable' | 'beta' | 'experimental' | 'deprecated';
+    a11y?: {
+        contrastTarget?: number;
+        modes?: string[];
+    };
+    color?: string;
+    features?: string[];
+    dependencies?: string[];
+    createTheme: () => Theme;
+}
+
+/**
+ * Theme Definition (CSS or JS)
+ */
+export type ThemeDefinition = CSSThemeDefinition | JSThemeDefinition;
+
+/**
+ * Build configuration (migrated from theme.config.ts)
+ */
+export interface BuildConfig {
+    output?: {
+        directory?: string;
+        formats?: {
+            expanded?: string;
+            compressed?: string;
+        };
+    };
+    sass?: {
+        style?: 'expanded' | 'compressed';
+        sourceMap?: boolean;
+        loadPaths?: string[];
+    };
+}
+
+/**
+ * Runtime configuration (migrated from theme.config.ts)
+ */
+export interface RuntimeConfig {
+    basePath?: string;
+    cdnPath?: string | null;
+    preload?: string[];
+    lazy?: boolean;
+    defaultTheme?: string;
+    storageKey?: string;
+    dataAttribute?: string;
+    enablePersistence?: boolean;
+    useMinified?: boolean;
+}
+
+/**
+ * Integration settings (migrated from theme.config.ts)
+ */
+export interface IntegrationConfig {
+    cssVariables?: Record<string, string>;
+    classNames?: {
+        theme?: string;
+        colorMode?: string;
+    };
+}
+
+/**
+ * Atomix Configuration Interface
+ * 
+ * Tailwind-like configuration for external developers.
+ * Focus on theme customization - build/runtime configs are internal only.
+ */
+export interface AtomixConfig {
+    /** 
+     * CSS variable prefix (default: 'atomix')
+     * 
+     * Change this to customize all CSS variable names.
+     * Example: prefix: 'myapp' → --myapp-primary instead of --atomix-primary
+     */
+    prefix?: string;
+    
+    /** 
+     * Theme customization (Tailwind-like)
+     * 
+     * Use `extend` to add or override design tokens.
+     * Use `tokens` to completely replace the default token system (advanced).
+     */
+    theme?: {
+        /** 
+         * Extend the default design tokens
+         * 
+         * This is the recommended way to customize Atomix.
+         * Your values will override or extend the base tokens.
+         */
+        extend?: ThemeTokens;
+        
+        /** 
+         * Override the default tokens entirely (advanced)
+         * 
+         * Use with caution - this replaces the entire token system.
+         * Most users should use `extend` instead.
+         */
+        tokens?: ThemeTokens;
+        
+        /** 
+         * Register custom themes (optional)
+         * 
+         * Define CSS or JavaScript themes that can be loaded dynamically.
+         */
+        themes?: Record<string, ThemeDefinition>;
+    };
+    
+    // Internal configurations (for library development only)
+    // These are not needed for external developers
+    /** @internal Build configuration (internal use only) */
+    build?: BuildConfig;
+    /** @internal Runtime configuration (internal use only) */
+    runtime?: RuntimeConfig;
+    /** @internal Integration settings (internal use only) */
+    integration?: IntegrationConfig;
+    /** @internal Theme dependencies mapping (internal use only) */
+    dependencies?: Record<string, string[]>;
+}
+
+/**
+ * Helper function to define Atomix configuration with type safety
+ * 
+ * @param config - Atomix configuration object
+ * @returns The configuration object
+ */
+/**
+ * Helper function to define Atomix configuration with type safety
+ * 
+ * Similar to Tailwind's defineConfig, provides autocomplete and type checking.
+ * 
+ * @param config - Atomix configuration object
+ * @returns The configuration object
+ * 
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@shohojdhara/atomix/config';
+ * 
+ * export default defineConfig({
+ *   theme: {
+ *     extend: {
+ *       colors: {
+ *         primary: { main: '#7AFFD7' },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function defineConfig(config: AtomixConfig): AtomixConfig {
+    return config;
+}
+
+// Export loader functions
+export { loadAtomixConfig, resolveConfigPath } from './loader';
+
+export default AtomixConfig;

package/src/lib/config/loader.ts

@@ -0,0 +1,105 @@
+/**
+ * Atomix Config Loader
+ * 
+ * Helper functions to load atomix.config.ts from external projects.
+ * Similar to how Tailwind loads tailwind.config.js
+ */
+
+import type { AtomixConfig } from './index';
+
+/**
+ * Load Atomix configuration from project root
+ * 
+ * Attempts to load atomix.config.ts from the current working directory.
+ * Falls back to default config if file doesn't exist.
+ * 
+ * @param options - Loader options
+ * @returns Loaded configuration or default
+ * 
+ * @example
+ * ```typescript
+ * import { loadAtomixConfig } from '@shohojdhara/atomix/config';
+ * 
+ * const config = loadAtomixConfig();
+ * const theme = createThemeFromConfig(config);
+ * ```
+ */
+export function loadAtomixConfig(
+    options: {
+        /** Custom config path (default: 'atomix.config.ts') */
+        configPath?: string;
+        /** Whether to throw error if config not found (default: false) */
+        required?: boolean;
+    } = {}
+): AtomixConfig {
+    const { configPath = 'atomix.config.ts', required = false } = options;
+
+    // Default config
+    const defaultConfig: AtomixConfig = {
+        prefix: 'atomix',
+        theme: {
+            extend: {},
+        },
+    };
+
+    // In browser environments, config loading is not supported
+    if (typeof window !== 'undefined') {
+        if (required) {
+            throw new Error('Config loading not supported in browser environment');
+        }
+        return defaultConfig;
+    }
+
+    // Try to load config file
+    try {
+        // Use dynamic import for ESM compatibility
+        const configModule = require(configPath);
+        const config = configModule.default || configModule;
+        
+        // Validate it's an AtomixConfig
+        if (config && typeof config === 'object') {
+            return config as AtomixConfig;
+        }
+        
+        throw new Error('Invalid config format');
+    } catch (error: any) {
+        if (required) {
+            throw new Error(`Failed to load config from ${configPath}: ${error.message}`);
+        }
+        
+        // Return default config if not required
+        return defaultConfig;
+    }
+}
+
+/**
+ * Resolve config path
+ * 
+ * Finds atomix.config.ts in the project, checking common locations.
+ */
+export function resolveConfigPath(): string | null {
+    if (typeof process === 'undefined' || !process.cwd) {
+        return null;
+    }
+
+    const fs = require('fs');
+    const path = require('path');
+    
+    const cwd = process.cwd();
+    const possiblePaths = [
+        path.join(cwd, 'atomix.config.ts'),
+        path.join(cwd, 'atomix.config.js'),
+        path.join(cwd, 'atomix.config.mjs'),
+    ];
+
+    for (const configPath of possiblePaths) {
+        if (fs.existsSync(configPath)) {
+            return configPath;
+        }
+    }
+
+    return null;
+}
+
+export default loadAtomixConfig;
+