@shohojdhara/atomix 0.3.4 → 0.3.6

package/src/lib/theme/types.ts

@@ -4,7 +4,6 @@
  * TypeScript types and interfaces for the Atomix Design System theme management system.
  */
 
-import type { ThemeManager as ThemeManagerType } from './runtime/ThemeManager';
 import type { PartStyleProps } from '../types/partProps';
 
 /**
@@ -42,39 +41,6 @@ export interface ThemeMetadata {
     dependencies?: string[];
 }
 
-/**
- * Theme manager configuration options
- */
-export interface ThemeManagerConfig {
-    /** Available themes metadata */
-    themes: Record<string, ThemeMetadata>;
-    /** Default theme to use */
-    defaultTheme?: string | Theme;
-    /** Base path for theme CSS files */
-    basePath?: string;
-    /** CDN path for theme CSS files (optional) */
-    cdnPath?: string | null;
-    /** Themes to preload on initialization */
-    preload?: string[];
-    /** Enable lazy loading of themes */
-    lazy?: boolean;
-    /** localStorage key for persistence */
-    storageKey?: string;
-    /** Data attribute name for theme */
-    dataAttribute?: string;
-    /** Enable persistence */
-    enablePersistence?: boolean;
-    /** Custom CSS file extension */
-    cssExtension?: string;
-    /** Use minified CSS files */
-    useMinified?: boolean;
-    /** Callback when theme changes */
-    onThemeChange?: (theme: string | Theme) => void;
-    /** Callback when theme load fails */
-    onError?: (error: Error, themeName: string) => void;
-    /** RTL configuration */
-    rtl?: import('./i18n/rtl').RTLConfig;
-}
 
 /**
  * Theme change event payload
@@ -160,7 +126,7 @@ export interface UseThemeOptions {
     /** Custom storage key */
     storageKey?: string;
     /** Callback when theme changes */
-    onChange?: (theme: string | Theme) => void;
+    onChange?: (theme: string | Theme | import('./tokens').DesignTokens) => void;
 }
 
 /**
@@ -171,8 +137,8 @@ export interface UseThemeReturn {
     theme: string;
     /** Current active theme object (for JS themes) */
     activeTheme: Theme | null;
-    /** Function to change theme */
-    setTheme: (theme: string | Theme, options?: ThemeLoadOptions) => Promise<void>;
+    /** Function to change theme (supports string, Theme, or DesignTokens) */
+    setTheme: (theme: string | Theme | import('./tokens').DesignTokens | Partial<import('./tokens').DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
     /** Available themes */
     availableThemes: ThemeMetadata[];
     /** Whether a theme is currently loading */
@@ -268,7 +234,7 @@ export interface ThemeProviderProps {
     /** Use minified CSS */
     useMinified?: boolean;
     /** Callback when theme changes */
-    onThemeChange?: (theme: string | Theme) => void;
+    onThemeChange?: (theme: string | Theme | import('./tokens').DesignTokens) => void;
     /** Callback on error */
     onError?: (error: Error, themeName: string) => void;
 }
@@ -281,8 +247,8 @@ export interface ThemeContextValue {
     theme: string;
     /** Current active theme object (for JS themes) */
     activeTheme: Theme | null;
-    /** Set theme function */
-    setTheme: (theme: string | Theme, options?: ThemeLoadOptions) => Promise<void>;
+    /** Set theme function (supports string, Theme, or DesignTokens) */
+    setTheme: (theme: string | Theme | import('./tokens').DesignTokens | Partial<import('./tokens').DesignTokens>, options?: ThemeLoadOptions) => Promise<void>;
     /** Available themes */
     availableThemes: ThemeMetadata[];
     /** Loading state */
@@ -293,8 +259,6 @@ export interface ThemeContextValue {
     isThemeLoaded: (themeName: string) => boolean;
     /** Preload theme */
     preloadTheme: (themeName: string) => Promise<void>;
-    /** Theme manager instance */
-    themeManager: ThemeManagerType;
 }
 
 // ============================================================================

package/src/lib/theme/{utils.ts → utils/domUtils.ts}

@@ -5,8 +5,8 @@
  * and theme validation.
  */
 
-import type { ThemeMetadata, ThemeValidationResult } from './types';
-import { THEME_LINK_ID_PREFIX } from './constants';
+import type { ThemeMetadata, ThemeValidationResult } from '../types';
+import { THEME_LINK_ID_PREFIX } from '../constants/constants';
 
 /**
  * Check if code is running in a browser environment

package/src/lib/theme/utils/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Theme Utilities
+ * 
+ * Utility functions for theme operations
+ */
+
+export * from './themeHelpers';
+export * from './themeUtils';
+export * from './domUtils';
+export * from './injectCSS';
+

package/src/lib/theme/utils/injectCSS.ts

@@ -0,0 +1,90 @@
+/**
+ * CSS Injection Utilities
+ * 
+ * Inject CSS into HTML head via <style> element.
+ */
+
+/**
+ * Check if running in browser environment
+ */
+function isBrowser(): boolean {
+  return typeof document !== 'undefined';
+}
+
+/**
+ * Inject CSS into HTML head via <style> element
+ * 
+ * Creates or updates a style element in the document head.
+ * If an element with the same ID exists, it will be updated.
+ * 
+ * @param css - CSS string to inject
+ * @param id - Style element ID (default: 'atomix-theme')
+ * 
+ * @example
+ * ```typescript
+ * const css = ':root { --atomix-color-primary: #7AFFD7; }';
+ * injectCSS(css);
+ * 
+ * // With custom ID
+ * injectCSS(css, 'my-custom-theme');
+ * ```
+ */
+export function injectCSS(
+  css: string,
+  id: string = 'atomix-theme'
+): void {
+  if (!isBrowser()) {
+    console.warn('injectCSS: Not in browser environment, CSS not injected');
+    return;
+  }
+
+  let styleElement = document.getElementById(id) as HTMLStyleElement | null;
+
+  if (!styleElement) {
+    styleElement = document.createElement('style');
+    styleElement.id = id;
+    styleElement.setAttribute('data-atomix-theme', 'true');
+    document.head.appendChild(styleElement);
+  }
+
+  styleElement.textContent = css;
+}
+
+/**
+ * Remove injected CSS from DOM
+ * 
+ * Removes the style element with the given ID from the document head.
+ * 
+ * @param id - Style element ID to remove (default: 'atomix-theme')
+ * 
+ * @example
+ * ```typescript
+ * removeCSS(); // Removes default 'atomix-theme'
+ * removeCSS('my-custom-theme'); // Removes custom ID
+ * ```
+ */
+export function removeCSS(id: string = 'atomix-theme'): void {
+  if (!isBrowser()) {
+    return;
+  }
+
+  const styleElement = document.getElementById(id);
+  if (styleElement) {
+    styleElement.remove();
+  }
+}
+
+/**
+ * Check if CSS is already injected
+ * 
+ * @param id - Style element ID to check (default: 'atomix-theme')
+ * @returns True if style element exists
+ */
+export function isCSSInjected(id: string = 'atomix-theme'): boolean {
+  if (!isBrowser()) {
+    return false;
+  }
+
+  return document.getElementById(id) !== null;
+}
+

package/src/lib/theme/utils/themeHelpers.ts

@@ -0,0 +1,78 @@
+/**
+ * Theme Helper Functions
+ * 
+ * Utility functions for working with themes and DesignTokens
+ */
+
+import type { Theme } from '../types';
+import type { DesignTokens } from '../tokens/tokens';
+import { createDesignTokensFromTheme } from '../adapters/themeAdapter';
+
+/**
+ * Get DesignTokens from current theme
+ * 
+ * Converts a Theme object to DesignTokens. Useful when you need to
+ * work with DesignTokens but have a Theme object.
+ * 
+ * @param theme - Theme object to convert
+ * @returns DesignTokens object
+ * 
+ * @example
+ * ```typescript
+ * // If you have a Theme object, convert it to DesignTokens
+ * const tokens = getDesignTokensFromTheme(theme);
+ * // Now you can use tokens with unified theme system
+ * const css = createTheme(tokens);
+ * ```
+ */
+export function getDesignTokensFromTheme(theme: Theme | null): DesignTokens | null {
+  if (!theme) return null;
+  return createDesignTokensFromTheme(theme);
+}
+
+/**
+ * Check if a value is DesignTokens
+ * 
+ * Type guard to check if an object is DesignTokens format.
+ * 
+ * @param value - Value to check
+ * @returns True if value is DesignTokens
+ */
+export function isDesignTokens(value: unknown): value is DesignTokens {
+  if (!value || typeof value !== 'object') return false;
+  
+  // DesignTokens is a flat object with string keys, no nested structures
+  const obj = value as Record<string, unknown>;
+  
+  // Check for absence of Theme-specific properties
+  if ('palette' in obj || 'typography' in obj || '__isJSTheme' in obj) {
+    return false;
+  }
+  
+  // Check if it has DesignTokens-like structure (flat string keys)
+  const keys = Object.keys(obj);
+  if (keys.length === 0) return false;
+  
+  // Check if keys look like DesignTokens (kebab-case, no nesting)
+  const hasDesignTokenKeys = keys.some(key => 
+    /^[a-z]+(-[a-z0-9]+)*$/.test(key) && 
+    typeof obj[key] === 'string'
+  );
+  
+  return hasDesignTokenKeys;
+}
+
+/**
+ * Check if a value is a Theme object
+ * 
+ * Type guard to check if an object is a Theme.
+ * 
+ * @param value - Value to check
+ * @returns True if value is Theme
+ */
+export function isThemeObject(value: unknown): value is Theme {
+  if (!value || typeof value !== 'object') return false;
+  const obj = value as Record<string, unknown>;
+  return '__isJSTheme' in obj || ('palette' in obj && 'typography' in obj);
+}
+

package/src/lib/theme/{themeUtils.ts → utils/themeUtils.ts}

@@ -5,7 +5,7 @@
  * spacing helpers, and theme value accessors.
  */
 
-import type { Theme, SpacingFunction, SpacingOptions } from './types';
+import type { Theme, SpacingFunction, SpacingOptions } from '../types';
 
 // ============================================================================
 // Color Manipulation Utilities

package/src/lib/theme-tools.ts

@@ -5,15 +5,15 @@
  */
 
 import { Theme, ThemeMetadata } from './theme/types';
-import { createTheme } from './theme/createTheme';
-import { extendTheme, mergeTheme } from './theme/composeTheme';
-import { generateCSSVariables } from './theme/generateCSSVariables';
+import { createThemeObject } from './theme/core/createThemeObject';
+import { extendTheme, mergeTheme } from './theme/core/composeTheme';
+import { generateCSSVariables } from './theme/generators/generateCSSVariables';
 
 /**
  * Quick theme creator with sensible defaults
  */
 export function quickTheme(name: string, primaryColor: string, secondaryColor?: string): Theme {
-  return createTheme({
+  return createThemeObject({
     name,
     palette: {
       primary: { main: primaryColor },
@@ -32,7 +32,7 @@ export function createDarkVariant(lightTheme: Theme): Theme {
       mode: 'dark',
       background: {
         default: '#121212',
-        paper: '#1e1e1e',
+        subtle: '#1e1e1e',
       },
       text: {
         primary: '#ffffff',
@@ -119,7 +119,6 @@ export function importTheme(json: string): Theme {
   }
 }
 
-// Re-export commonly used functions
-export { createTheme, extendTheme, mergeTheme };
-export { generateCSSVariables };
-export { RTLManager } from './theme/i18n/rtl';
+// 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.

package/src/lib/types/components.ts

@@ -560,6 +560,36 @@ export interface ButtonProps extends BaseComponentProps {
   style?: React.CSSProperties;
 }
 
+/**
+ * ButtonGroup component properties
+ */
+export interface ButtonGroupProps extends BaseComponentProps {
+  /**
+   * ButtonGroup children (should be Button components)
+   */
+  children?: ReactNode;
+
+  /**
+   * Additional CSS class names
+   */
+  className?: string;
+
+  /**
+   * Inline style for the component root element
+   */
+  style?: React.CSSProperties;
+
+  /**
+   * ARIA label for accessibility
+   */
+  'aria-label'?: string;
+
+  /**
+   * ARIA role for the button group
+   */
+  role?: string;
+}
+
 /**
  * Badge component properties
  */
@@ -716,6 +746,27 @@ export interface AccordionProps extends BaseComponentProps {
    */
   icon?: ReactNode;
 
+  /**
+   * Whether the accordion is open
+   */
+  isOpen?: boolean;
+
+  /**
+   * Whether the accordion is disabled
+   */
+  disabled?: boolean;
+
+  onOpenChange?: (open: boolean) => void;
+
+  /**
+   * Optional open handler
+   */
+  onOpen?: () => void;
+
+  /**
+   * Optional close handler
+   */
+  onClose?: () => void;
   /**
    * Glass morphism effect for the accordion
    * Can be a boolean to enable with default settings, or an object with AtomixGlassProps to customize the effect
@@ -996,6 +1047,24 @@ export interface SpinnerProps extends BaseComponentProps {
   glass?: AtomixGlassProps | boolean;
 }
 
+/**
+ * Icon size options
+ */
+export type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * Icon weight/style options
+ */
+export type IconWeight = 'thin' | 'light' | 'regular' | 'bold' | 'fill' | 'duotone';
+
+/**
+ * Phosphor icon type - excludes internal Phosphor exports
+ */
+export type PhosphorIconsType = Exclude<
+  keyof typeof import('@phosphor-icons/react'),
+  'IconContext' | 'IconBase' | 'createIcon' | 'default' | 'SSR'
+>;
+
 /**
  * Navbar position options
  */
@@ -1702,6 +1771,16 @@ export interface PaginationProps extends BaseComponentProps {
    */
   showPrevNextButtons?: boolean;
 
+  /**
+   * Whether to show search input for jumping to a specific page
+   */
+  showSearch?: boolean;
+
+  /**
+   * Placeholder text for the search input
+   */
+  searchPlaceholder?: string;
+
   /**
    * Custom class for the pagination container
    */
@@ -2728,18 +2807,28 @@ export interface BreadcrumbItem {
   active?: boolean;
 
   /**
-   * Icon name from Phosphor Icons
+   * Icon name from Phosphor Icons or ReactNode
    */
-  icon?: string;
+  icon?: string | ReactNode;
 
   /**
    * Optional click handler
    */
-  onClick?: (event: MouseEvent) => void;
+  onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+
+  /**
+   * Custom style for the breadcrumb item
+   */
+  style?: React.CSSProperties;
+
+  /**
+   * Additional className
+   */
+  className?: string;
 }
 
 /**
- * Breadcrumb options interface
+ * Breadcrumb options interface (for vanilla JS)
  */
 export interface BreadcrumbOptions {
   /**
@@ -6227,36 +6316,6 @@ export interface FooterSocialLinkProps extends BaseComponentProps {
  */
 export type GlassMode = 'standard' | 'polar' | 'prominent' | 'shader';
 
-/**
- * Glass container size configuration
- */
-export interface GlassSize {
-  /**
-   * Width of the glass container
-   */
-  width: number;
-
-  /**
-   * Height of the glass container
-   */
-  height: number;
-}
-
-/**
- * Mouse position coordinates
- */
-export interface MousePosition {
-  /**
-   * X coordinate
-   */
-  x: number;
-
-  /**
-   * Y coordinate
-   */
-  y: number;
-}
-
 /**
  * Glass container component properties
  */

package/src/lib/types/partProps.ts

@@ -384,22 +384,6 @@ export function mergePartStyles(
   };
 }
 
-/**
- * Utility function to apply part styles to props
- */
-export function applyPartStyles<T extends Record<string, any>>(
-  props: T,
-  part?: PartStyleProps
-): T {
-  if (!part) return props;
-
-  return {
-    ...props,
-    className: [props.className, part.className].filter(Boolean).join(' '),
-    style: { ...props.style, ...part.style },
-  };
-}
-
 /**
  * Map of component names to their part types
  */

package/src/lib/utils/componentUtils.ts

@@ -6,7 +6,7 @@
 
 import React from 'react';
 import type { PartStyleProps } from '../types/partProps';
-import { cssVarsToStyle } from '../theme/cssVariableMapper';
+import { cssVarsToStyle } from '../theme/adapters/cssVariableMapper';
 
 /**
  * Merge multiple class names

package/src/lib/utils/fontPreloader.ts

@@ -0,0 +1,148 @@
+/**
+ * Font Preloading Utilities
+ * 
+ * Provides utilities for preloading fonts to improve performance
+ * and prevent Flash of Invisible Text (FOIT).
+ */
+
+export interface FontPreloadConfig {
+  /**
+   * Font family name
+   */
+  family: string;
+  /**
+   * Font file path (relative to public/assets/fonts or absolute URL)
+   */
+  path: string;
+  /**
+   * Font weight
+   */
+  weight?: string | number;
+  /**
+   * Font style
+   */
+  style?: 'normal' | 'italic';
+  /**
+   * Font format (woff2 is preferred)
+   */
+  format?: 'woff2' | 'woff';
+  /**
+   * Cross-origin setting
+   */
+  crossorigin?: 'anonymous' | 'use-credentials';
+}
+
+/**
+ * Creates a preload link element for a font
+ * 
+ * @param config - Font preload configuration
+ * @returns HTML link element for preloading
+ * 
+ * @example
+ * ```tsx
+ * const preloadLink = createFontPreloadLink({
+ *   family: 'Nunito Sans',
+ *   path: '/fonts/nunito-sans/nunito-sans-regular.woff2',
+ *   weight: 400
+ * });
+ * document.head.appendChild(preloadLink);
+ * ```
+ */
+export function createFontPreloadLink(config: FontPreloadConfig): HTMLLinkElement {
+  const {
+    path,
+    format = 'woff2',
+    crossorigin = 'anonymous',
+  } = config;
+
+  const link = document.createElement('link');
+  link.rel = 'preload';
+  link.as = 'font';
+  link.href = path;
+  link.type = `font/${format}`;
+  link.crossOrigin = crossorigin;
+
+  return link;
+}
+
+/**
+ * Preloads multiple fonts
+ * 
+ * @param fonts - Array of font configurations to preload
+ * @returns Array of created link elements
+ * 
+ * @example
+ * ```tsx
+ * const links = preloadFonts([
+ *   { family: 'Nunito Sans', path: '/fonts/nunito-sans/nunito-sans-regular.woff2', weight: 400 },
+ *   { family: 'Nunito Sans', path: '/fonts/nunito-sans/nunito-sans-bold.woff2', weight: 700 },
+ * ]);
+ * links.forEach(link => document.head.appendChild(link));
+ * ```
+ */
+export function preloadFonts(fonts: FontPreloadConfig[]): HTMLLinkElement[] {
+  return fonts.map(createFontPreloadLink);
+}
+
+/**
+ * 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([
+ *   { family: 'Nunito Sans', path: '/fonts/nunito-sans/nunito-sans-regular.woff2' },
+ * ]);
+ * // Returns: ['<link rel="preload" as="font" href="/fonts/..." type="font/woff2" crossorigin="anonymous">']
+ * ```
+ */
+export function generateFontPreloadTags(fonts: FontPreloadConfig[]): string[] {
+  return fonts.map((config) => {
+    const {
+      path,
+      format = 'woff2',
+      crossorigin = 'anonymous',
+    } = config;
+
+    return `<link rel="preload" as="font" href="${path}" type="font/${format}" crossorigin="${crossorigin}">`;
+  });
+}
+
+/**
+ * Default font configurations for Atomix Design System
+ * These can be used as a starting point for font preloading
+ */
+export const DEFAULT_ATOMIX_FONTS: FontPreloadConfig[] = [
+  {
+    family: 'Nunito Sans',
+    path: '/fonts/nunito-sans/nunito-sans-regular.woff2',
+    weight: 400,
+    style: 'normal',
+    format: 'woff2',
+  },
+  {
+    family: 'Nunito Sans',
+    path: '/fonts/nunito-sans/nunito-sans-bold.woff2',
+    weight: 700,
+    style: 'normal',
+    format: 'woff2',
+  },
+  {
+    family: 'Nunito Sans',
+    path: '/fonts/nunito-sans/nunito-sans-italic.woff2',
+    weight: 400,
+    style: 'italic',
+    format: 'woff2',
+  },
+  {
+    family: 'Nunito Sans',
+    path: '/fonts/nunito-sans/nunito-sans-bold-italic.woff2',
+    weight: 700,
+    style: 'italic',
+    format: 'woff2',
+  },
+];
+