@stacksjs/components 0.2.3

package/dist/utils/animation/keyframes.d.ts

@@ -0,0 +1,334 @@
+/**
+ * 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 declare function createKeyframeAnimation(element: HTMLElement, keyframes: readonly Keyframe[] | Keyframe[], options?: AnimationOptions): Animation | null;
+/**
+ * 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 declare function animate(element: HTMLElement, animationName: KeyframeAnimationName, options?: AnimationOptions): Animation | null;
+/**
+ * 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 declare const KeyframeAnimations: {
+  fadeIn: readonly [{
+  offset: 0;
+  opacity: 0
+}, {
+  offset: 1;
+  opacity: 1
+}];
+  fadeOut: readonly [{
+  offset: 0;
+  opacity: 1
+}, {
+  offset: 1;
+  opacity: 0
+}];
+  slideInUp: readonly [{
+  offset: 0;
+  transform: 'translateY(100%)';
+  opacity: 0
+}, {
+  offset: 1;
+  transform: 'translateY(0)';
+  opacity: 1
+}];
+  slideInDown: readonly [{
+  offset: 0;
+  transform: 'translateY(-100%)';
+  opacity: 0
+}, {
+  offset: 1;
+  transform: 'translateY(0)';
+  opacity: 1
+}];
+  slideInLeft: readonly [{
+  offset: 0;
+  transform: 'translateX(-100%)';
+  opacity: 0
+}, {
+  offset: 1;
+  transform: 'translateX(0)';
+  opacity: 1
+}];
+  slideInRight: readonly [{
+  offset: 0;
+  transform: 'translateX(100%)';
+  opacity: 0
+}, {
+  offset: 1;
+  transform: 'translateX(0)';
+  opacity: 1
+}];
+  slideOutUp: readonly [{
+  offset: 0;
+  transform: 'translateY(0)';
+  opacity: 1
+}, {
+  offset: 1;
+  transform: 'translateY(-100%)';
+  opacity: 0
+}];
+  slideOutDown: readonly [{
+  offset: 0;
+  transform: 'translateY(0)';
+  opacity: 1
+}, {
+  offset: 1;
+  transform: 'translateY(100%)';
+  opacity: 0
+}];
+  slideOutLeft: readonly [{
+  offset: 0;
+  transform: 'translateX(0)';
+  opacity: 1
+}, {
+  offset: 1;
+  transform: 'translateX(-100%)';
+  opacity: 0
+}];
+  slideOutRight: readonly [{
+  offset: 0;
+  transform: 'translateX(0)';
+  opacity: 1
+}, {
+  offset: 1;
+  transform: 'translateX(100%)';
+  opacity: 0
+}];
+  zoomIn: readonly [{
+  offset: 0;
+  transform: 'scale(0)';
+  opacity: 0
+}, {
+  offset: 0.5;
+  opacity: 1
+}, {
+  offset: 1;
+  transform: 'scale(1)'
+}];
+  zoomOut: readonly [{
+  offset: 0;
+  transform: 'scale(1)';
+  opacity: 1
+}, {
+  offset: 0.5;
+  opacity: 1
+}, {
+  offset: 1;
+  transform: 'scale(0)';
+  opacity: 0
+}];
+  rotate: readonly [{
+  offset: 0;
+  transform: 'rotate(0deg)'
+}, {
+  offset: 1;
+  transform: 'rotate(360deg)'
+}];
+  bounce: readonly [{
+  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: readonly [{
+  offset: 0;
+  transform: 'scale(1)'
+}, {
+  offset: 0.5;
+  transform: 'scale(1.05)'
+}, {
+  offset: 1;
+  transform: 'scale(1)'
+}];
+  shake: readonly [{
+  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: readonly [{
+  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: readonly [{
+  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: readonly [{
+  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: readonly [{
+  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)'
+}]
+};
+/**
+ * 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 declare interface Keyframe {
+  offset: number
+}
+/**
+ * Animation configuration options
+ */
+export declare interface AnimationOptions {
+  duration?: number
+  easing?: string
+  delay?: number
+  iterations?: number
+  direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse'
+  fill?: 'none' | 'forwards' | 'backwards' | 'both'
+}
+/**
+ * Type for predefined animation names
+ */
+export type KeyframeAnimationName = keyof typeof KeyframeAnimations

package/dist/utils/error-handling.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Set global error handler
+ *
+ * @param handler - Error handler function
+ *
+ * @example
+ * ```ts
+ * setErrorHandler((error) => {
+ *   console.error('Component error:', error)
+ *   // Send to error tracking service
+ * })
+ * ```
+ */
+export declare function setErrorHandler(handler: (error: Error) => void): void;
+/**
+ * Clear the global error handler (useful for testing)
+ */
+export declare function clearErrorHandler(): void;
+/**
+ * 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 declare 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;
+/**
+ * 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'
+ * )
+ * ```
+ */
+/* ... * / },
+ *   'Button',
+ *   'onClick'
+ * )
+ * ```
+ */
+export declare function wrapErrorHandler<T extends (...args: any[]) => any>(fn: T, component: string, eventName: string): 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 declare function assert(condition: any, error: Error): asserts condition;
+/**
+ * Warning message handler
+ */
+export declare function warn(component: string, message: string, context?: Partial<ErrorContext>): void;
+/**
+ * Development-only assertion
+ */
+export declare function devAssert(condition: any, error: Error): asserts condition;
+/**
+ * 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 declare function createDebugger(component: string): {
+  log: (...args: any[]) => void
+  warn: (message: string, context?: Partial<ErrorContext>) => void
+  error: (message: string, context?: ErrorContext) => void
+};
+/**
+ * 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 declare function errorBoundary<T>(component: string, renderFn: () => T, fallback: T): T;
+/**
+ * Error types for common scenarios
+ */
+export declare const ErrorTypes: {
+  /**
+   * Invalid prop value error
+   */
+  invalidProp(component: string, prop: string, received: any, expected: any): unknown;
+  /**
+   * Required prop missing error
+   */
+  requiredProp(component: string, prop: string): unknown;
+  /**
+   * Invalid prop type error
+   */
+  invalidType(component: string, prop: string, received: any, expected: string): unknown;
+  /**
+   * Component not found error
+   */
+  componentNotFound(componentName: string): unknown;
+  /**
+   * Invalid children error
+   */
+  invalidChildren(component: string, received: any, expected: string): unknown;
+  /**
+   * State update error
+   */
+  stateUpdate(component: string, stateName: string, error: Error): unknown;
+  /**
+   * Event handler error
+   */
+  eventHandler(component: string, eventName: string, error: Error): unknown;
+  /**
+   * Render error
+   */
+  render(component: string, error: Error): unknown
+};
+/**
+ * Error context information
+ */
+export declare interface ErrorContext {
+  component?: string
+  prop?: string
+  received?: any
+  expected?: any
+  details?: string
+  docsUrl?: string
+}
+/**
+ * Custom error class for component errors
+ */
+export declare class ComponentError extends Error {
+  component: string;
+  context: ErrorContext;
+  constructor(component: string, message: string, context?: ErrorContext);
+  static formatMessage(component: string, message: string, context: ErrorContext): string;
+  toJSON(): { name: string, message: string, component: string, context: ErrorContext | undefined, stack: string | undefined };
+}

package/dist/utils/highlighter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Initialize or get the syntax highlighter instance
+ */
+export declare function getHighlighter(): Promise<TSHighlighter>;
+/**
+ * Highlight code with syntax highlighting
+ */
+export declare function highlight(code: string, options?: HighlighterOptions): Promise<HighlightResult>;
+/**
+ * Detect language from code content
+ */
+export declare function detectLanguage(code: string): string;
+/**
+ * Apply headwind utility classes to highlighted code
+ */
+export declare function applyHeadwindClasses(html: string, additionalClasses?: string): string;
+export declare interface HighlighterOptions {
+  theme?: 'light' | 'dark' | 'auto'
+  language?: string
+  lineNumbers?: boolean
+  wrapLines?: boolean
+}
+export declare interface HighlightResult {
+  html: string
+  language: string
+  theme: string
+}

package/dist/utils/highlighter.js

@@ -0,0 +1,2 @@
+// @bun
+import{createHighlighter as E}from"ts-syntax-highlighter";var A=null;async function F(){if(!A)A=await E({theme:"github-light"});return A}async function N(b,j={}){let{theme:k="auto",language:q="typescript",lineNumbers:G=!1,wrapLines:J=!0}=j,B=await F(),D=k==="auto"?globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches?"github-dark":"github-light":k==="dark"?"github-dark":"github-light",z=await B.highlight(b,q);return{html:typeof z==="string"?z:String(z),language:q,theme:D}}function O(b){if(b.includes("<!DOCTYPE")||b.includes("<html"))return"html";if(b.includes("<?php"))return"php";if(b.includes("import")&&b.includes("from"))return"typescript";if(b.includes("function")||b.includes("const"))return"javascript";if(b.includes("{")&&b.includes("}"))return"json";if(b.includes("$")&&b.includes("|"))return"bash";if(b.includes("#")&&b.includes("##"))return"markdown";return"typescript"}function P(b,j){return`<div class="${j?`rounded-md overflow-auto text-sm leading-relaxed font-mono ${j}`:"rounded-md overflow-auto text-sm leading-relaxed font-mono"}">${b}</div>`}export{N as highlight,F as getHighlighter,O as detectLanguage,P as applyHeadwindClasses};