@stacksjs/components 0.2.93 → 0.2.94

package/src/utils/animation/keyframes.ts

@@ -1,230 +0,0 @@
-/**
- * Keyframe animation utilities using Web Animations API
- *
- * @example
- * ```ts
- * import { animate, KeyframeAnimations } from '@stacksjs/components'
- *
- * // Use predefined animation
- * animate(element, 'fadeIn', { duration: 500 })
- *
- * // Custom keyframes
- * createKeyframeAnimation(element, [
- *   { offset: 0, opacity: 0, transform: 'scale(0.5)' },
- *   { offset: 1, opacity: 1, transform: 'scale(1)' }
- * ], { duration: 300 })
- * ```
- */
-
-/**
- * Single keyframe definition
- */
-export interface Keyframe {
-  /** Keyframe position (0 to 1) */
-  offset: number
-  /** CSS properties to animate */
-  [property: string]: any
-}
-
-/**
- * Animation configuration options
- */
-export interface AnimationOptions {
-  /** Animation duration in milliseconds */
-  duration?: number
-  /** Easing function, CSS easing string */
-  easing?: string
-  /** Delay before animation starts in milliseconds */
-  delay?: number
-  /** Number of iterations (Infinity for infinite) */
-  iterations?: number
-  /** Animation direction */
-  direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse'
-  /** Fill mode */
-  fill?: 'none' | 'forwards' | 'backwards' | 'both'
-}
-
-/**
- * Create a keyframe animation using Web Animations API
- *
- * @param element - Target HTML element
- * @param keyframes - Array of keyframe definitions
- * @param options - Animation options
- * @returns Animation instance or null if not supported
- */
-export function createKeyframeAnimation(
-  element: HTMLElement,
-  keyframes: readonly Keyframe[] | Keyframe[],
-  options: AnimationOptions = {},
-): Animation | null {
-  if (typeof element.animate !== 'function') {
-    console.warn('Web Animations API not supported')
-    return null
-  }
-
-  const {
-    duration = 1000,
-    easing = 'ease',
-    delay = 0,
-    iterations = 1,
-    direction = 'normal',
-    fill = 'both',
-  } = options
-
-  return element.animate([...keyframes], {
-    duration,
-    easing,
-    delay,
-    iterations,
-    direction,
-    fill,
-  })
-}
-
-/**
- * Predefined keyframe animation presets
- *
- * Available animations:
- * - fadeIn/fadeOut
- * - slideInUp/Down/Left/Right, slideOutUp/Down/Left/Right
- * - zoomIn/Out
- * - rotate, bounce, pulse, shake, swing
- * - flip, rubberBand, heartbeat
- */
-export const KeyframeAnimations = {
-  fadeIn: [
-    { offset: 0, opacity: 0 },
-    { offset: 1, opacity: 1 },
-  ],
-  fadeOut: [
-    { offset: 0, opacity: 1 },
-    { offset: 1, opacity: 0 },
-  ],
-  slideInUp: [
-    { offset: 0, transform: 'translateY(100%)', opacity: 0 },
-    { offset: 1, transform: 'translateY(0)', opacity: 1 },
-  ],
-  slideInDown: [
-    { offset: 0, transform: 'translateY(-100%)', opacity: 0 },
-    { offset: 1, transform: 'translateY(0)', opacity: 1 },
-  ],
-  slideInLeft: [
-    { offset: 0, transform: 'translateX(-100%)', opacity: 0 },
-    { offset: 1, transform: 'translateX(0)', opacity: 1 },
-  ],
-  slideInRight: [
-    { offset: 0, transform: 'translateX(100%)', opacity: 0 },
-    { offset: 1, transform: 'translateX(0)', opacity: 1 },
-  ],
-  slideOutUp: [
-    { offset: 0, transform: 'translateY(0)', opacity: 1 },
-    { offset: 1, transform: 'translateY(-100%)', opacity: 0 },
-  ],
-  slideOutDown: [
-    { offset: 0, transform: 'translateY(0)', opacity: 1 },
-    { offset: 1, transform: 'translateY(100%)', opacity: 0 },
-  ],
-  slideOutLeft: [
-    { offset: 0, transform: 'translateX(0)', opacity: 1 },
-    { offset: 1, transform: 'translateX(-100%)', opacity: 0 },
-  ],
-  slideOutRight: [
-    { offset: 0, transform: 'translateX(0)', opacity: 1 },
-    { offset: 1, transform: 'translateX(100%)', opacity: 0 },
-  ],
-  zoomIn: [
-    { offset: 0, transform: 'scale(0)', opacity: 0 },
-    { offset: 0.5, opacity: 1 },
-    { offset: 1, transform: 'scale(1)' },
-  ],
-  zoomOut: [
-    { offset: 0, transform: 'scale(1)', opacity: 1 },
-    { offset: 0.5, opacity: 1 },
-    { offset: 1, transform: 'scale(0)', opacity: 0 },
-  ],
-  rotate: [
-    { offset: 0, transform: 'rotate(0deg)' },
-    { offset: 1, transform: 'rotate(360deg)' },
-  ],
-  bounce: [
-    { offset: 0, transform: 'translateY(0)' },
-    { offset: 0.2, transform: 'translateY(0)' },
-    { offset: 0.4, transform: 'translateY(-30px)' },
-    { offset: 0.43, transform: 'translateY(-30px)' },
-    { offset: 0.53, transform: 'translateY(0)' },
-    { offset: 0.7, transform: 'translateY(-15px)' },
-    { offset: 0.8, transform: 'translateY(0)' },
-    { offset: 0.9, transform: 'translateY(-4px)' },
-    { offset: 1, transform: 'translateY(0)' },
-  ],
-  pulse: [
-    { offset: 0, transform: 'scale(1)' },
-    { offset: 0.5, transform: 'scale(1.05)' },
-    { offset: 1, transform: 'scale(1)' },
-  ],
-  shake: [
-    { offset: 0, transform: 'translateX(0)' },
-    { offset: 0.1, transform: 'translateX(-10px)' },
-    { offset: 0.2, transform: 'translateX(10px)' },
-    { offset: 0.3, transform: 'translateX(-10px)' },
-    { offset: 0.4, transform: 'translateX(10px)' },
-    { offset: 0.5, transform: 'translateX(-10px)' },
-    { offset: 0.6, transform: 'translateX(10px)' },
-    { offset: 0.7, transform: 'translateX(-10px)' },
-    { offset: 0.8, transform: 'translateX(10px)' },
-    { offset: 0.9, transform: 'translateX(-10px)' },
-    { offset: 1, transform: 'translateX(0)' },
-  ],
-  swing: [
-    { offset: 0, transform: 'rotate(0deg)' },
-    { offset: 0.2, transform: 'rotate(15deg)' },
-    { offset: 0.4, transform: 'rotate(-10deg)' },
-    { offset: 0.6, transform: 'rotate(5deg)' },
-    { offset: 0.8, transform: 'rotate(-5deg)' },
-    { offset: 1, transform: 'rotate(0deg)' },
-  ],
-  flip: [
-    { offset: 0, transform: 'perspective(400px) rotateY(0)', animationTimingFunction: 'ease-out' },
-    { offset: 0.4, transform: 'perspective(400px) translateZ(150px) rotateY(170deg)', animationTimingFunction: 'ease-out' },
-    { offset: 0.5, transform: 'perspective(400px) translateZ(150px) rotateY(190deg)', animationTimingFunction: 'ease-in' },
-    { offset: 0.8, transform: 'perspective(400px) rotateY(360deg)', animationTimingFunction: 'ease-in' },
-    { offset: 1, transform: 'perspective(400px)', animationTimingFunction: 'ease-in' },
-  ],
-  rubberBand: [
-    { offset: 0, transform: 'scale(1)' },
-    { offset: 0.3, transform: 'scaleX(1.25) scaleY(0.75)' },
-    { offset: 0.4, transform: 'scaleX(0.75) scaleY(1.25)' },
-    { offset: 0.5, transform: 'scaleX(1.15) scaleY(0.85)' },
-    { offset: 0.65, transform: 'scaleX(0.95) scaleY(1.05)' },
-    { offset: 0.75, transform: 'scaleX(1.05) scaleY(0.95)' },
-    { offset: 1, transform: 'scale(1)' },
-  ],
-  heartbeat: [
-    { offset: 0, transform: 'scale(1)' },
-    { offset: 0.14, transform: 'scale(1.3)' },
-    { offset: 0.28, transform: 'scale(1)' },
-    { offset: 0.42, transform: 'scale(1.3)' },
-    { offset: 0.7, transform: 'scale(1)' },
-  ],
-} as const
-
-/**
- * Type for predefined animation names
- */
-export type KeyframeAnimationName = keyof typeof KeyframeAnimations
-
-/**
- * Animate an element with a predefined animation
- *
- * @param element - Target HTML element
- * @param animationName - Name of predefined animation
- * @param options - Animation options
- * @returns Animation instance or null if not supported
- */
-export function animate(
-  element: HTMLElement,
-  animationName: KeyframeAnimationName,
-  options: AnimationOptions = {},
-): Animation | null {
-  return createKeyframeAnimation(element, KeyframeAnimations[animationName], options)
-}

package/src/utils/error-handling.ts

@@ -1,475 +0,0 @@
-/**
- * Error handling utilities for @stacksjs/components
- *
- * Provides clear, actionable error messages with links to documentation
- *
- * @example
- * ```ts
- * import { ComponentError, handleError } from '@stacksjs/components'
- *
- * throw new ComponentError('Button', 'Invalid variant provided', {
- *   received: 'invalid',
- *   expected: ['primary', 'secondary', 'outline']
- * })
- * ```
- */
-import process from 'node:process'
-
-/**
- * Base URL for documentation
- */
-const DOCS_BASE_URL = 'https://stacksjs.com/components'
-
-/**
- * Error context information
- */
-export interface ErrorContext {
-  /** The component name where the error occurred */
-  component?: string
-  /** The prop name that caused the error */
-  prop?: string
-  /** The value that was received */
-  received?: any
-  /** The expected value(s) */
-  expected?: any
-  /** Additional details about the error */
-  details?: string
-  /** Link to relevant documentation */
-  docsUrl?: string
-}
-
-/**
- * Custom error class for component errors
- */
-export class ComponentError extends Error {
-  component: string
-  context: ErrorContext
-
-  constructor(component: string, message: string, context: ErrorContext = {}) {
-    const fullMessage = ComponentError.formatMessage(component, message, context)
-    super(fullMessage)
-
-    this.name = 'ComponentError'
-    this.component = component
-    this.context = { component, ...context }
-
-    // Maintains proper stack trace for where error was thrown (only available on V8)
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, ComponentError)
-    }
-  }
-
-  /**
-   * Format error message with context
-   */
-  static formatMessage(component: string, message: string, context: ErrorContext): string {
-    let formatted = `[${component}] ${message}`
-
-    if (context.prop) {
-      formatted += `\n  Prop: "${context.prop}"`
-    }
-
-    if (context.received !== undefined) {
-      formatted += `\n  Received: ${JSON.stringify(context.received)}`
-    }
-
-    if (context.expected !== undefined) {
-      const expected = Array.isArray(context.expected)
-        ? context.expected.map(v => JSON.stringify(v)).join(', ')
-        : JSON.stringify(context.expected)
-      formatted += `\n  Expected: ${expected}`
-    }
-
-    if (context.details) {
-      formatted += `\n  Details: ${context.details}`
-    }
-
-    if (context.docsUrl) {
-      formatted += `\n  Documentation: ${context.docsUrl}`
-    }
-    else if (component) {
-      formatted += `\n  Documentation: ${DOCS_BASE_URL}/${component.toLowerCase()}`
-    }
-
-    return formatted
-  }
-
-  /**
-   * Get error as plain object
-   */
-  toJSON(): { name: string, message: string, component: string, context: ErrorContext | undefined, stack: string | undefined } {
-    return {
-      name: this.name,
-      message: this.message,
-      component: this.component,
-      context: this.context,
-      stack: this.stack,
-    }
-  }
-}
-
-/**
- * Error types for common scenarios
- */
-export const ErrorTypes = {
-  /**
-   * Invalid prop value error
-   */
-  invalidProp(component: string, prop: string, received: any, expected: any): ComponentError {
-    return new ComponentError(
-      component,
-      `Invalid prop value for "${prop}"`,
-      {
-        prop,
-        received,
-        expected,
-        details: Array.isArray(expected)
-          ? `The "${prop}" prop must be one of the allowed values`
-          : `The "${prop}" prop does not match the expected type`,
-      },
-    )
-  },
-
-  /**
-   * Required prop missing error
-   */
-  requiredProp(component: string, prop: string): ComponentError {
-    return new ComponentError(
-      component,
-      `Required prop "${prop}" is missing`,
-      {
-        prop,
-        details: `The "${prop}" prop is required for ${component} to function correctly`,
-      },
-    )
-  },
-
-  /**
-   * Invalid prop type error
-   */
-  invalidType(component: string, prop: string, received: any, expected: string): ComponentError {
-    return new ComponentError(
-      component,
-      `Invalid type for prop "${prop}"`,
-      {
-        prop,
-        received: typeof received,
-        expected,
-        details: `Expected "${prop}" to be of type ${expected}, but received ${typeof received}`,
-      },
-    )
-  },
-
-  /**
-   * Component not found error
-   */
-  componentNotFound(componentName: string): ComponentError {
-    return new ComponentError(
-      'ComponentLoader',
-      `Component "${componentName}" not found`,
-      {
-        component: componentName,
-        details: 'Make sure the component is properly imported and registered',
-      },
-    )
-  },
-
-  /**
-   * Invalid children error
-   */
-  invalidChildren(component: string, received: any, expected: string): ComponentError {
-    return new ComponentError(
-      component,
-      'Invalid children',
-      {
-        received: typeof received,
-        expected,
-        details: `${component} expects ${expected} as children`,
-      },
-    )
-  },
-
-  /**
-   * State update error
-   */
-  stateUpdate(component: string, stateName: string, error: Error): ComponentError {
-    return new ComponentError(
-      component,
-      `Failed to update state "${stateName}"`,
-      {
-        details: error.message,
-      },
-    )
-  },
-
-  /**
-   * Event handler error
-   */
-  eventHandler(component: string, eventName: string, error: Error): ComponentError {
-    return new ComponentError(
-      component,
-      `Error in "${eventName}" event handler`,
-      {
-        details: error.message,
-      },
-    )
-  },
-
-  /**
-   * Render error
-   */
-  render(component: string, error: Error): ComponentError {
-    return new ComponentError(
-      component,
-      'Failed to render component',
-      {
-        details: error.message,
-      },
-    )
-  },
-}
-
-/**
- * Global error handler
- */
-let errorHandler: ((_error: Error) => void) | null = null
-
-/**
- * Set global error handler
- *
- * @param handler - Error handler function
- *
- * @example
- * ```ts
- * setErrorHandler((error) => {
- *   console.error('Component error:', error)
- *   // Send to error tracking service
- * })
- * ```
- */
-export function setErrorHandler(handler: (error: Error) => void): void {
-  errorHandler = handler
-}
-
-/**
- * Clear the global error handler (useful for testing)
- */
-export function clearErrorHandler(): void {
-  errorHandler = null
-}
-
-/**
- * Handle an error
- *
- * @param error - Error to handle
- * @param options - Handling options
- * @param options.throwError - Whether to re-throw the error after handling
- * @param options.logError - Whether to log the error to console
- *
- * @example
- * ```ts
- * try {
- *   // Component code
- * }
-catch (error) {
- *   handleError(error, { throwError: false })
- * }
- * ```
- */
-export function handleError(
-  error: Error,
-  options: {
-    /** Whether to re-throw the error after handling */
-    throwError?: boolean
-    /** Whether to log the error to console */
-    logError?: boolean
-  } = {},
-): void {
-  const { throwError = true, logError = true } = options
-
-  // Log to console in development
-  if (logError && process.env.NODE_ENV !== 'production') {
-    console.error('Component Error:', error)
-
-    if (error instanceof ComponentError) {
-      console.group('Error Details')
-      // eslint-disable-next-line no-console
-      console.log('Component:', error.component)
-      // eslint-disable-next-line no-console
-      console.log('Context:', error.context)
-      console.groupEnd()
-    }
-  }
-
-  // Call global error handler if set
-  if (errorHandler) {
-    try {
-      errorHandler(error)
-    }
-    catch (handlerError) {
-      console.error('Error in error handler:', handlerError)
-    }
-  }
-
-  // Re-throw if requested
-  if (throwError) {
-    throw error
-  }
-}
-
-/**
- * Create a wrapped function that catches and handles errors
- *
- * @param fn - Function to wrap
- * @param component - Component name for error context
- * @param eventName - Event name for error context
- * @returns Wrapped function
- *
- * @example
- * ```ts
- * const safeHandler = wrapErrorHandler(
- *   () => { /* ... * / },
- *   'Button',
- *   'onClick'
- * )
- * ```
- */
-export function wrapErrorHandler<T extends (...args: any[]) => any>(
-  fn: T,
-  component: string,
-  eventName: string,
-): T {
-  return ((...args: any[]) => {
-    try {
-      const result = fn(...args)
-
-      // Handle async functions
-      if (result instanceof Promise) {
-        return result.catch((error) => {
-          const wrappedError = ErrorTypes.eventHandler(component, eventName, error)
-          handleError(wrappedError, { throwError: false })
-          throw wrappedError
-        })
-      }
-
-      return result
-    }
-    catch (error) {
-      const wrappedError = ErrorTypes.eventHandler(component, eventName, error as Error)
-      handleError(wrappedError, { throwError: false })
-      throw wrappedError
-    }
-  }) as T
-}
-
-/**
- * Assert a condition with a custom error
- *
- * @param condition - Condition to check
- * @param error - Error to throw if condition is false
- *
- * @example
- * ```ts
- * assert(
- *   props.variant !== undefined,
- *   ErrorTypes.requiredProp('Button', 'variant')
- * )
- * ```
- */
-export function assert(condition: any, error: Error): asserts condition {
-  if (!condition) {
-    throw error
-  }
-}
-
-/**
- * Warning message handler
- */
-export function warn(component: string, message: string, context: Partial<ErrorContext> = {}): void {
-  if (process.env.NODE_ENV === 'production') {
-    return
-  }
-
-  const fullMessage = ComponentError.formatMessage(component, message, context as ErrorContext)
-
-  console.warn(`⚠️  ${fullMessage}`)
-}
-
-/**
- * Development-only assertion
- */
-export function devAssert(condition: any, error: Error): asserts condition {
-  if (process.env.NODE_ENV === 'production') {
-    return
-  }
-
-  assert(condition, error)
-}
-
-/**
- * Create a debug logger for a component
- *
- * @param component - Component name
- * @returns Debug logger functions
- *
- * @example
- * ```ts
- * const debug = createDebugger('Button')
- * debug.log('Button rendered')
- * debug.error('Invalid prop')
- * ```
- */
-export function createDebugger(component: string): {
-  log: (...args: any[]) => void
-  warn: (message: string, context?: Partial<ErrorContext>) => void
-  error: (message: string, context?: ErrorContext) => void
-} {
-  const isDebug = typeof process !== 'undefined' && process.env.DEBUG === 'true'
-
-  return {
-    log(...args: any[]): void {
-      if (isDebug) {
-        console.log(`[${component}]`, ...args)
-      }
-    },
-    warn(message: string, context?: Partial<ErrorContext>): void {
-      warn(component, message, context)
-    },
-    error(message: string, context?: ErrorContext): void {
-      const error = new ComponentError(component, message, context)
-      handleError(error, { throwError: false })
-    },
-  }
-}
-
-/**
- * Error boundary helper for catching render errors
- *
- * @param component - Component name
- * @param renderFn - Render function
- * @param fallback - Fallback content on error
- * @returns Rendered content or fallback
- *
- * @example
- * ```ts
- * const content = errorBoundary(
- *   'MyComponent',
- *   () => renderComponent(),
- *   '<div>Error loading component</div>'
- * )
- * ```
- */
-export function errorBoundary<T>(
-  component: string,
-  renderFn: () => T,
-  fallback: T,
-): T {
-  try {
-    return renderFn()
-  }
-  catch (error) {
-    const wrappedError = ErrorTypes.render(component, error as Error)
-    handleError(wrappedError, { throwError: false })
-    return fallback
-  }
-}