@stacksjs/components 0.2.3

package/dist/utils/i18n.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Create an i18n instance
+ *
+ * @param config - I18n configuration
+ * @returns I18n instance
+ *
+ * @example
+ * ```ts
+ * const i18n = createI18n({
+ *   locale: 'en',
+ *   fallbackLocale: 'en',
+ *   messages: {
+ *     en: {
+ *       welcome: 'Welcome, {name}!',
+ *       items: 'No items | One item | {count} items'
+ *     },
+ *     es: {
+ *       welcome: 'Bienvenido, {name}!',
+ *       items: 'Sin elementos | Un elemento | {count} elementos'
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare function createI18n(config: I18nConfig): I18n;
+/**
+ * Set global i18n instance
+ *
+ * @param i18n - I18n instance
+ */
+export declare function setI18n(i18n: I18n): void;
+/**
+ * Get global i18n instance
+ *
+ * @returns Global i18n instance or null
+ */
+export declare function getI18n(): I18n | null;
+/**
+ * Global translation function
+ * Uses global i18n instance
+ *
+ * @param key - Translation key
+ * @param params - Interpolation parameters
+ * @returns Translated string
+ */
+export declare function t(key: string, params?: Record<string, any>): string;
+/**
+ * Global pluralization function
+ *
+ * @param key - Translation key
+ * @param count - Count for pluralization
+ * @param params - Interpolation parameters
+ * @returns Pluralized translated string
+ */
+export declare function tc(key: string, count: number, params?: Record<string, any>): string;
+/**
+ * Global date formatting function
+ *
+ * @param date - Date to format
+ * @param format - Format name
+ * @returns Formatted date string
+ */
+export declare function d(date: Date | number, format?: string): string;
+/**
+ * Global number formatting function
+ *
+ * @param value - Number to format
+ * @param format - Format name
+ * @returns Formatted number string
+ */
+export declare function n(value: number, format?: string): string;
+/**
+ * RTL (Right-to-Left) language detection
+ *
+ * @param locale - Locale code
+ * @returns Whether locale is RTL
+ */
+export declare function isRTL(locale: string): boolean;
+/**
+ * Load locale messages dynamically
+ *
+ * @param locale - Locale code
+ * @param loadFn - Function to load messages
+ * @returns Promise of messages
+ *
+ * @example
+ * ```ts
+ * const messages = await loadLocaleMessages('es', async () => {
+ *   const module = await import('./locales/es.json')
+ *   return module.default
+ * })
+ * ```
+ */
+export declare function loadLocaleMessages(locale: string, loadFn: () => Promise<Messages>): Promise<Messages>;
+/**
+ * Predefined pluralization rules for common languages
+ */
+export declare const pluralRules: {
+  Finnish
+  en: unknown;
+  de: unknown;
+  nl: unknown;
+  sv: unknown;
+  Brazilian Portuguese
+  fr: unknown;
+  pt_BR: unknown;
+  Croatian
+  ru: (count) => unknown;
+  // Polish
+  pl: (count) => unknown;
+  Slovak
+  cs: (count) => unknown;
+  // Arabic
+  ar: (count) => unknown;
+  Vietnamese
+  ja: () => unknown;
+  ko: () => unknown;
+  zh: () => unknown;
+  th: () => unknown;
+  vi: () => unknown
+};
+/**
+ * Common date/time format presets
+ */
+export declare const dateTimeFormats: {
+  short: {
+  year: 'numeric';
+  month: 'numeric';
+  day: 'numeric'
+};
+  long: {
+  year: 'numeric';
+  month: 'long';
+  day: 'numeric'
+};
+  full: {
+  weekday: 'long';
+  year: 'numeric';
+  month: 'long';
+  day: 'numeric'
+};
+  time: {
+  hour: 'numeric';
+  minute: 'numeric'
+};
+  datetime: {
+  year: 'numeric';
+  month: 'numeric';
+  day: 'numeric';
+  hour: 'numeric';
+  minute: 'numeric'
+}
+};
+/**
+ * Common number format presets
+ */
+export declare const numberFormats: {
+  decimal: {
+  style: 'decimal';
+  minimumFractionDigits: 2;
+  maximumFractionDigits: 2
+};
+  currency: {
+  style: 'currency';
+  currency: 'USD'
+};
+  percent: {
+  style: 'percent';
+  minimumFractionDigits: 0;
+  maximumFractionDigits: 2
+};
+  compact: {
+  notation: 'compact'
+}
+};
+/**
+ * Component-specific i18n messages
+ *
+ * Provides default translations for component library
+ */
+export declare const componentMessages: LocaleMessages;
+/**
+ * I18n configuration
+ */
+export declare interface I18nConfig {
+  locale: string
+  fallbackLocale?: string
+  messages: LocaleMessages
+  pluralRules?: Record<string, PluralRule>
+  dateTimeFormats?: Record<string, Intl.DateTimeFormatOptions>
+  numberFormats?: Record<string, Intl.NumberFormatOptions>
+  missing?: (locale: string, key: string) => string | void
+  warnMissing?: boolean
+}
+/**
+ * I18n instance
+ */
+export declare interface I18n {
+  locale: string
+  availableLocales: string[]
+  setLocale: (locale: string) => void
+  t: (key: string, params?: Record<string, any>) => string
+  tc: (key: string, count: number, params?: Record<string, any>) => string
+  d: (date: Date | number, format?: string) => string
+  n: (value: number, format?: string) => string
+  te: (key: string) => boolean
+  addMessages: (locale: string, messages: Messages) => void
+  removeLocale: (locale: string) => void
+}
+/**
+ * Internationalization (i18n) system for @stacksjs/components
+ *
+ * Provides translation, locale management, pluralization, and date/number formatting
+ *
+ * @example
+ * ```ts
+ * import { createI18n, t } from '@stacksjs/components'
+ *
+ * // Create i18n instance
+ * const i18n = createI18n({
+ *   locale: 'en',
+ *   fallbackLocale: 'en',
+ *   messages: {
+ *     en: { welcome: 'Welcome' },
+ *     es: { welcome: 'Bienvenido' }
+ *   }
+ * })
+ *
+ * // Use translations
+ * t('welcome') // 'Welcome' or 'Bienvenido' based on locale
+ * ```
+ */
+/**
+ * Translation messages structure
+ */
+export type MessageValue = string | { [key: string]: MessageValue }
+export type Messages = Record<string, MessageValue>
+/**
+ * Locale messages
+ */
+export type LocaleMessages = Record<string, Messages>
+/**
+ * Pluralization rules
+ */
+export type PluralRule = (count: number, locale: string) => number

package/dist/utils/keep-alive.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Create a KeepAlive manager
+ *
+ * Implements LRU (Least Recently Used) cache strategy for component instances
+ *
+ * @param options - KeepAlive configuration options
+ * @returns KeepAlive manager instance
+ *
+ * @example
+ * ```ts
+ * const keepAlive = createKeepAlive({
+ *   max: 10,
+ *   ttl: 5 * 60 * 1000, // 5 minutes
+ *   include: ['user-profile', 'dashboard'],
+ *   hooks: {
+ *     onActivate: (comp) => console.log(`Activated: ${comp.id}`),
+ *     onDeactivate: (comp) => console.log(`Deactivated: ${comp.id}`),
+ *   },
+ * })
+ * ```
+ */
+export declare function createKeepAlive(options?: KeepAliveOptions): KeepAlive;
+/**
+ * Create a simple LRU cache (without component-specific features)
+ *
+ * Generic LRU cache implementation for any type of data
+ *
+ * @param maxSize - Maximum number of items to cache
+ * @returns LRU cache instance
+ *
+ * @example
+ * ```ts
+ * const cache = createLRUCache<string>(100)
+ *
+ * cache.set('key1', 'value1')
+ * const value = cache.get('key1') // 'value1'
+ * cache.has('key1') // true
+ * ```
+ */
+export declare function createLRUCache<T = any>(maxSize: number): void;
+/**
+ * State manager for component state preservation
+ *
+ * Manages component state with automatic serialization/deserialization
+ *
+ * @example
+ * ```ts
+ * const stateManager = createStateManager()
+ *
+ * // Save state
+ * stateManager.save('my-component', { count: 5 })
+ *
+ * // Restore state
+ * const state = stateManager.restore('my-component')
+ * console.log(state.count) // 5
+ * ```
+ */
+export declare function createStateManager(): void;
+/**
+ * Create a component pool for object reuse
+ *
+ * Useful for frequently created/destroyed components to reduce GC pressure
+ *
+ * @param factory - Function to create new instances
+ * @param options - Pool configuration
+ * @param options.maxSize - Maximum pool size
+ * @param options.reset - Function to reset instance before reuse
+ * @returns Component pool
+ *
+ * @example
+ * ```ts
+ * const pool = createComponentPool(
+ *   () => ({ id: '', type: '', state: {} }),
+ *   { maxSize: 50 }
+ * )
+ *
+ * const instance = pool.acquire()
+ * // Use instance...
+ * pool.release(instance)
+ * ```
+ */
+export declare function createComponentPool<T>(factory: () => T, options?: { maxSize?: number, reset?: (instance: T) => void }): void;
+/**
+ * KeepAlive utilities for @stacksjs/components
+ *
+ * Provides component caching and state preservation with LRU (Least Recently Used)
+ * cache strategy for optimizing component lifecycle management
+ *
+ * @example
+ * ```ts
+ * import { createKeepAlive } from '@stacksjs/components'
+ *
+ * // Create KeepAlive manager with max 10 components
+ * const keepAlive = createKeepAlive({ max: 10 })
+ *
+ * // Cache component
+ * const cached = keepAlive.cache('my-component', componentInstance, {
+ *   state: { count: 0 },
+ *   onActivate: (comp) => console.log('Component activated'),
+ *   onDeactivate: (comp) => console.log('Component deactivated'),
+ * })
+ *
+ * // Retrieve cached component
+ * const instance = keepAlive.get('my-component')
+ *
+ * // Prune least recently used
+ * keepAlive.prune()
+ * ```
+ */
+/**
+ * Component instance interface
+ */
+export declare interface ComponentInstance {
+  id: string
+  type: string
+  element?: HTMLElement
+  state?: Record<string, any>
+  data?: Record<string, any>
+  hooks?: ComponentHooks
+  createdAt: number
+  lastAccessedAt: number
+}
+/**
+ * Component lifecycle hooks
+ */
+export declare interface ComponentHooks {
+  onMount?: (instance: ComponentInstance) => void
+  onUnmount?: (instance: ComponentInstance) => void
+  onActivate?: (instance: ComponentInstance) => void
+  onDeactivate?: (instance: ComponentInstance) => void
+  onRestore?: (instance: ComponentInstance, state: Record<string, any>) => void
+  onSave?: (instance: ComponentInstance) => Record<string, any>
+}
+/**
+ * KeepAlive cache options
+ */
+export declare interface KeepAliveOptions {
+  max?: number
+  ttl?: number
+  include?: RegExp | string[]
+  exclude?: RegExp | string[]
+  hooks?: ComponentHooks
+  debug?: boolean
+}
+/**
+ * KeepAlive cache statistics
+ */
+export declare interface CacheStats {
+  hits: number
+  misses: number
+  size: number
+  max: number
+  hitRate: number
+  keys: string[]
+}
+/**
+ * KeepAlive manager interface
+ */
+export declare interface KeepAlive {
+  cache: (key: string, instance: ComponentInstance, hooks?: ComponentHooks) => ComponentInstance
+  get: (key: string) => ComponentInstance | null
+  has: (key: string) => boolean
+  remove: (key: string) => boolean
+  clear: () => void
+  prune: () => number
+  activate: (key: string) => ComponentInstance | null
+  deactivate: (key: string) => boolean
+  getStats: () => CacheStats
+  keys: () => string[]
+  size: () => number
+}

package/dist/utils/lazy-loading.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Lazy load a module with caching
+ *
+ * @param importFn - Dynamic import function
+ * @param cacheKey - Optional cache key (defaults to function string)
+ * @returns Promise of module
+ */
+export declare function lazyLoadModule<T = any>(importFn: () => Promise<T>, cacheKey?: string): Promise<T>;
+/**
+ * Create a lazy loaded component
+ *
+ * @param importFn - Dynamic import function
+ * @param options - Lazy load options
+ * @returns Lazy component wrapper
+ *
+ * @example
+ * ```ts
+ * const LazyButton = lazyLoadComponent(
+ *   () => import('./components/Button'),
+ *   { preloadOnHover: true }
+ * )
+ *
+ * // Later, load and use
+ * const button = await LazyButton.load()
+ * ```
+ */
+export declare function lazyLoadComponent<T = any>(importFn: () => Promise<T>, options?: ComponentLazyLoadOptions): LazyComponent<T>;
+/**
+ * Lazy load content when element enters viewport
+ *
+ * @param element - Target element to observe
+ * @param importFn - Dynamic import function
+ * @param options - Lazy load options
+ * @returns Cleanup function
+ *
+ * @example
+ * ```ts
+ * const cleanup = lazyLoad(
+ *   document.getElementById('heavy-component'),
+ *   () => import('./HeavyComponent'),
+ *   {
+ *     rootMargin: '50px',
+ *     placeholder: '<div>Loading...</div>'
+ *   }
+ * )
+ * ```
+ */
+export declare function lazyLoad<T = any>(element: Element | null, importFn: () => Promise<T>, options?: LazyLoadOptions): () => void;
+/**
+ * Lazy load multiple elements
+ *
+ * @param elements - Array of elements or NodeList
+ * @param importFn - Dynamic import function or function that takes element
+ * @param options - Lazy load options
+ * @returns Cleanup function
+ */
+export declare function lazyLoadAll<T = any>(elements: Element[] | NodeListOf<Element>, importFn: ((element: Element) => Promise<T>) | (() => Promise<T>), options?: LazyLoadOptions): () => void;
+/**
+ * Preload a module without executing it
+ *
+ * Useful for prefetching components that will likely be needed soon
+ *
+ * @param importFn - Dynamic import function
+ * @returns Promise of module
+ */
+export declare function preloadModule<T = any>(importFn: () => Promise<T>): Promise<T>;
+/**
+ * Preload multiple modules
+ *
+ * @param importFns - Array of dynamic import functions
+ * @returns Promise of all modules
+ */
+export declare function preloadModules(importFns: Array<() => Promise<any>>): Promise<any[]>;
+/**
+ * Clear module cache
+ *
+ * Useful for testing or forcing re-imports
+ *
+ * @param cacheKey - Optional specific key to clear, or clear all if undefined
+ */
+export declare function clearModuleCache(cacheKey?: string): void;
+/**
+ * Get cache statistics
+ *
+ * @returns Cache size and keys
+ */
+export declare function getCacheStats(): { size: number, keys: string[] };
+/**
+ * Route-based code splitting helper
+ *
+ * Lazy loads components based on route patterns
+ *
+ * @example
+ * ```ts
+ * const routes = {
+ *   '/': () => import('./pages/Home'),
+ *   '/about': () => import('./pages/About'),
+ *   '/blog/:id': () => import('./pages/BlogPost')
+ * }
+ *
+ * const loader = createRouteLoader(routes)
+ * const component = await loader.load('/about')
+ * ```
+ */
+export declare function createRouteLoader(routes: Record<string, () => Promise<any>>): void;
+/**
+ * Image lazy loading helper
+ *
+ * @param img - Image element
+ * @param src - Image source URL
+ * @param options - Lazy load options
+ * @returns Cleanup function
+ */
+export declare function lazyLoadImage(img: HTMLImageElement | null, src: string, options?: LazyLoadOptions): () => void;
+/**
+ * Lazy load all images with data-lazy-src attribute
+ *
+ * @param container - Container element to search within
+ * @param options - Lazy load options
+ * @returns Cleanup function
+ */
+export declare function lazyLoadImages(container?: Element | Document, options?: LazyLoadOptions): () => void;
+/**
+ * Lazy loading utilities for @stacksjs/components
+ *
+ * Provides component-level code splitting and lazy loading with
+ * intersection observer support for on-demand loading
+ *
+ * @example
+ * ```ts
+ * import { lazyLoad, lazyLoadComponent } from '@stacksjs/components'
+ *
+ * // Lazy load a component
+ * const LazyButton = lazyLoadComponent(() => import('./Button'))
+ *
+ * // Lazy load on intersection
+ * lazyLoad(element, () => import('./heavy-component'))
+ * ```
+ */
+/**
+ * Lazy loading options
+ */
+export declare interface LazyLoadOptions {
+  root?: Element | null
+  rootMargin?: string
+  threshold?: number | number[]
+  placeholder?: string | HTMLElement
+  errorContent?: string | HTMLElement
+  onLoading?: () => void
+  onLoaded?: (module: any) => void
+  onError?: (error: Error) => void
+}
+/**
+ * Component lazy load options
+ */
+export declare interface ComponentLazyLoadOptions extends LazyLoadOptions {
+  preloadOnHover?: boolean
+  retryAttempts?: number
+  retryDelay?: number
+}
+/**
+ * Lazy loaded component wrapper
+ */
+export declare interface LazyComponent<T = any> {
+  state: LazyLoadState
+  module?: T
+  error?: Error
+  load: () => Promise<T>
+  preload: () => Promise<T>
+}
+/**
+ * Lazy load state
+ */
+export type LazyLoadState = 'idle' | 'loading' | 'loaded' | 'error'

package/dist/utils/prop-validation.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Validate props against schema
+ *
+ * @param componentName - Name of component being validated
+ * @param props - Props object to validate
+ * @param schema - Prop schema definition
+ * @param options - Validation options
+ * @param options.throwOnError - Whether to throw on validation failure
+ * @param options.logWarnings - Whether to log warnings to console
+ * @returns Validation result
+ */
+export declare function validateProps(componentName: string, props: Record<string, any>, schema: PropSchema, options?: {
+    /** Whether to throw on validation failure (default: false) */
+    throwOnError?: boolean
+    /** Whether to log warnings to console (default: true in dev) */
+    logWarnings?: boolean
+  }): ValidationResult;
+/**
+ * Create a prop validator function for a component
+ *
+ * @param componentName - Name of component
+ * @param schema - Prop schema definition
+ * @returns Validator function
+ *
+ * @example
+ * ```ts
+ * const validateButtonProps = createPropValidator('Button', {
+ *   size: PropTypes.oneOf(['sm', 'md', 'lg']),
+ *   disabled: PropTypes.boolean,
+ *   onClick: PropTypes.func.required
+ * })
+ *
+ * // In component
+ * validateButtonProps(props)
+ * ```
+ */
+export declare function createPropValidator(componentName: string, schema: PropSchema, options?: { throwOnError?: boolean, logWarnings?: boolean }): (props: Record<string, any>) => ValidationResult;
+/**
+ * Assert that a value matches a validator
+ *
+ * @param value - Value to validate
+ * @param validator - Validator to use
+ * @param name - Name for error messages
+ * @throws Error if validation fails
+ */
+export declare function assertProp<T>(value: any, validator: Validator<T>, name?: any): asserts value is T;
+/**
+ * Warn if prop doesn't match validator (non-throwing)
+ *
+ * @param value - Value to validate
+ * @param validator - Validator to use
+ * @param name - Name for warning messages
+ */
+export declare function warnProp(value: any, validator: Validator, name?: any): void;
+/**
+ * PropTypes - collection of common validators
+ */
+export declare const PropTypes: {
+  string: Validator<string>
+  number: Validator<number>
+  boolean: Validator<boolean>
+  func: Validator<(...args: any[]) => any>
+  object: Validator<object>
+  array: Validator<any[]>
+  any: Validator<any>
+  email: Validator<string>
+  url: Validator<string>
+  oneOf: <T>(validValues: T[]) => Validator<T>
+  oneOfType: (validators: Validator[]) => Validator
+  arrayOf: (validator: Validator) => Validator
+  shape: (shape: Record<string, Validator>) => Validator
+  instanceOf: <T>(expectedClass: new (...args: any[]) => T) => Validator<T>
+  custom: (validatorFn: (value: any, propName: string, componentName: string) => boolean, errorMessage: string | ((value: any, propName: string, componentName: string) => string)) => Validator
+  min: (min: number) => Validator<number>
+  max: (max: number) => Validator<number>
+  range: (min: number, max: number) => Validator<number>
+  pattern: (pattern: RegExp) => Validator<string>
+};
+/**
+ * Prop validator function type
+ */
+export declare interface PropValidator<_T = any> {
+  validate: (value: any, propName: string, componentName: string) => boolean
+  message: (value: any, propName: string, componentName: string) => string
+  isRequired?: boolean
+}
+/**
+ * Validation result
+ */
+export declare interface ValidationResult {
+  valid: boolean
+  errors: string[]
+}
+/**
+ * Prop schema definition
+ */
+export type PropSchema = Record<string, Validator>
+/**
+ * Base validator class
+ */
+declare class Validator<T = any> implements PropValidator<T> {
+  public validate: (value: any, propName: string, componentName: string) => boolean;
+  public message: (value: any, propName: string, componentName: string) => string;
+  public isRequired?: any;
+  constructor(validate: (value: any, propName: string, componentName: string) => boolean, message: (value: any, propName: string, componentName: string) => string, isRequired?: any);
+}