@stacksjs/stx 0.2.0 → 0.2.3

package/dist/devtools.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Enable STX DevTools.
+ */
+export declare function enableDevTools(options?: {
+  maxEvents?: number
+  maxPerformance?: number
+}): void;
+/**
+ * Disable STX DevTools.
+ */
+export declare function disableDevTools(): void;
+/**
+ * Register a component with DevTools.
+ */
+export declare function registerComponent(name: string, element: HTMLElement, props?: Record<string, unknown>, state?: Record<string, unknown>, file?: string): string;
+/**
+ * Update component state in DevTools.
+ */
+export declare function updateComponentState(id: string, state: Record<string, unknown>): void;
+/**
+ * Update component props in DevTools.
+ */
+export declare function updateComponentProps(id: string, props: Record<string, unknown>): void;
+/**
+ * Unregister a component from DevTools.
+ */
+export declare function unregisterComponent(id: string): void;
+/**
+ * Register a store with DevTools.
+ */
+export declare function registerStore(id: string, initialState: Record<string, unknown>, getters?: Record<string, unknown>, actions?: string[]): void;
+/**
+ * Record a store mutation.
+ */
+export declare function recordStoreMutation(storeId: string, name: string, oldValue: unknown, newValue: unknown, type?: 'state' | 'action'): void;
+/**
+ * Update store getters.
+ */
+export declare function updateStoreGetters(storeId: string, getters: Record<string, unknown>): void;
+/**
+ * Record an event in the timeline.
+ */
+export declare function recordEvent(event: EventRecord): void;
+/**
+ * Record a performance metric.
+ */
+export declare function recordPerformance(metric: PerformanceMetric): void;
+/**
+ * Measure execution time of a function.
+ */
+export declare function measurePerformance<T>(name: string, fn: () => T, componentId?: string): T;
+/**
+ * Measure async execution time.
+ */
+export declare function measurePerformanceAsync<T>(name: string, fn: () => Promise<T>, componentId?: string): Promise<T>;
+/**
+ * STX DevTools Integration
+ *
+ * Provides debugging and inspection tools for STX applications.
+ *
+ * @module devtools
+ *
+ * @example
+ * ```html
+ * <script>
+ * import { enableDevTools } from 'stx'
+ *
+ * // Enable DevTools in development
+ * if (process.env.NODE_ENV === 'development') {
+ *   enableDevTools()
+ * }
+ * </script>
+ * ```
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface ComponentInfo {
+  id: string
+  name: string
+  file?: string
+  parentId?: string
+  children: string[]
+  props: Record<string, unknown>
+  state: Record<string, unknown>
+  exposed: string[]
+  element?: HTMLElement
+  renderCount: number
+  lastRenderTime: number
+  createdAt: number
+}
+export declare interface StoreInfo {
+  id: string
+  state: Record<string, unknown>
+  getters: Record<string, unknown>
+  actions: string[]
+  history: MutationRecord[]
+}
+export declare interface MutationRecord {
+  timestamp: number
+  type: 'state' | 'action'
+  name: string
+  oldValue?: unknown
+  newValue?: unknown
+  stack?: string
+}
+export declare interface EventRecord {
+  timestamp: number
+  type: string
+  componentId?: string
+  payload: unknown
+  target?: string
+}
+export declare interface PerformanceMetric {
+  name: string
+  duration: number
+  timestamp: number
+  componentId?: string
+  metadata?: Record<string, unknown>
+}
+export declare interface DevToolsState {
+  enabled: boolean
+  components: Map<string, ComponentInfo>
+  stores: Map<string, StoreInfo>
+  events: EventRecord[]
+  performance: PerformanceMetric[]
+  selectedComponent: string | null
+  selectedStore: string | null
+  maxEvents: number
+  maxPerformance: number
+}
+export {
+  devToolsState,
+  selectComponent,
+  selectStore,
+  inspectElement,
+  highlightComponent,
+  clearHighlight,
+  logComponentTree,
+  logStoreState,
+  timeTravel,
+};

package/dist/directive-api.d.ts

@@ -0,0 +1,111 @@
+import type { CustomDirective } from './types';
+/**
+ * Register a directive globally.
+ */
+export declare function registerDirective<P extends DirectiveParams = DirectiveParams>(definition: FullDirectiveDefinition<P>): void;
+/**
+ * Get a registered directive.
+ */
+export declare function getDirective(name: string): FullDirectiveDefinition | undefined;
+/**
+ * Get all registered directives.
+ */
+export declare function getDirectives(): FullDirectiveDefinition[];
+/**
+ * Unregister a directive.
+ */
+export declare function unregisterDirective(name: string): boolean;
+/**
+ * Define a custom directive.
+ *
+ * @example
+ * ```typescript
+ * // Simple transform directive
+ * const uppercase = defineDirective({
+ *   name: 'uppercase',
+ *   transform: (content) => content.toUpperCase()
+ * })
+ *
+ * // Directive with parameters and validation
+ * const truncate = defineDirective({
+ *   name: 'truncate',
+ *   defaults: { length: 100, suffix: '...' },
+ *   validate: ({ length }) => length > 0 || 'Length must be positive',
+ *   transform: (content, { length, suffix }) =>
+ *     content.length > length
+ *       ? content.slice(0, length) + suffix
+ *       : content
+ * })
+ *
+ * // Client-side directive
+ * const tooltip = defineDirective({
+ *   name: 'tooltip',
+ *   transform: (content, { text }) =>
+ *     `<span data-tooltip="${text}">${content}</span>`,
+ *   client: {
+ *     mounted(el, { value }) {
+ *       el.title = value
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare function defineDirective<P extends DirectiveParams = DirectiveParams, T = unknown>(definition: FullDirectiveDefinition<P, T>): CustomDirective;
+/**
+ * Define a client-only directive.
+ */
+export declare function defineClientDirective<T = unknown>(name: string, definition: ClientDirectiveDefinition<T> | ((el: HTMLElement, binding: DirectiveBinding<T>) => void)): ClientDirectiveDefinition<T>;
+/**
+ * Create common built-in directives.
+ */
+export declare function createBuiltinDirectives(): CustomDirective[];
+/**
+ * Generate client-side directive runtime.
+ */
+export declare function generateDirectiveRuntime(): string;
+/**
+ * Process v-directive attributes in templates.
+ * Converts v-directive:arg.mod="value" to data attributes and client setup.
+ */
+export declare function processDirectiveAttributes(template: string): string;
+/** Directive binding for client-side directives */
+export declare interface DirectiveBinding<T = unknown> {
+  value: T
+  oldValue?: T
+  arg?: string
+  modifiers: Record<string, boolean>
+  instance: unknown
+  dir: ClientDirectiveDefinition<T>
+}
+/** Server-side directive definition */
+export declare interface DirectiveDefinition<P extends DirectiveParams = DirectiveParams> {
+  name: string
+  hasEndTag?: boolean
+  description?: string
+  transform?: (
+    content: string,
+    params: P,
+    context: Record<string, unknown>,
+    filePath: string,
+  ) => string | Promise<string>
+  validate?: (params: P) => boolean | string
+  defaults?: Partial<P>
+  clientScript?: (params: P) => string
+  css?: (params: P) => string
+}
+/** Client-side directive hooks */
+export declare interface ClientDirectiveDefinition<T = unknown> {
+  created?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
+  beforeMount?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
+  mounted?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
+  beforeUpdate?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
+  updated?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
+  beforeUnmount?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
+  unmounted?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
+}
+/** Combined directive (server + client) */
+export declare interface FullDirectiveDefinition<P extends DirectiveParams = DirectiveParams, T = unknown> extends DirectiveDefinition<P> {
+  client?: ClientDirectiveDefinition<T>
+}
+/** Directive parameter types */
+export type DirectiveParams = Record<string, unknown>

package/dist/dynamic-components.d.ts

@@ -0,0 +1,14 @@
+import type { StxOptions } from './types';
+/**
+ * Process `<component :is="expr">` tags in the template.
+ * Evaluates the :is expression against the context to determine which
+ * component to render, then resolves and renders that component inline.
+ *
+ * @param template - The template string
+ * @param context - Current template context
+ * @param filePath - Current file path
+ * @param options - stx options
+ * @param dependencies - Dependency tracking set
+ * @returns Processed template with dynamic components resolved
+ */
+export declare function processDynamicComponents(template: string, context: Record<string, any>, filePath: string, options: StxOptions, dependencies?: Set<string>): Promise<string>;

package/dist/edge-runtime.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Detect the current edge runtime platform.
+ */
+export declare function detectRuntime(): RuntimeInfo;
+/**
+ * Check if running in an edge environment.
+ */
+export declare function isEdgeEnvironment(): boolean;
+/**
+ * Check if running in a server environment (including edge).
+ */
+export declare function isServerEnvironment(): boolean;
+/**
+ * Create a platform-agnostic environment accessor.
+ */
+export declare function createEnvAccessor(platformEnv?: Record<string, unknown>): EnvAccessor;
+/**
+ * Create a platform-agnostic KV namespace.
+ */
+export declare function createKVNamespace(platformKV?: unknown): KVNamespace | undefined;
+/**
+ * Create a platform-agnostic cache.
+ */
+export declare function createEdgeCache(): EdgeCache | undefined;
+/**
+ * Create an edge handler.
+ */
+export declare function createEdgeHandler(config: EdgeHandlerConfig): void;
+/**
+ * Create a streaming response for edge platforms.
+ */
+export declare function createStreamingResponse(stream: ReadableStream<Uint8Array>, options?: ResponseInit): Response;
+/**
+ * Create a text encoder stream.
+ */
+export declare function createTextEncoderStream(): TransformStream<string, Uint8Array>;
+/**
+ * Pipe strings to a streaming response.
+ */
+export declare function stringToStream(strings: AsyncIterable<string>): ReadableStream<Uint8Array>;
+/**
+ * Create a Cloudflare Workers handler.
+ */
+export declare function createCloudflareHandler(config: EdgeHandlerConfig): {
+  fetch: (request: Request, env: Record<string, unknown>, ctx: { waitUntil: (p: Promise<unknown>) => void }) => Promise<Response>
+};
+/**
+ * Create a Deno Deploy handler.
+ */
+export declare function createDenoHandler(config: EdgeHandlerConfig): (request: Request) => Promise<Response>;
+/**
+ * Create a Vercel Edge handler.
+ */
+export declare function createVercelHandler(config: EdgeHandlerConfig): (request: Request) => Promise<Response>;
+/**
+ * Create a Netlify Edge handler.
+ */
+export declare function createNetlifyHandler(config: EdgeHandlerConfig): (request: Request, context: { geo?: GeoInfo }) => Promise<Response>;
+/**
+ * Parse cookies from request.
+ */
+export declare function parseCookies(request: Request): Record<string, string>;
+/**
+ * Create a Set-Cookie header value.
+ */
+export declare function createCookie(name: string, value: string, options?: {
+    maxAge?: number
+    expires?: Date
+    path?: string
+    domain?: string
+    secure?: boolean
+    httpOnly?: boolean
+    sameSite?: 'Strict' | 'Lax' | 'None'
+  }): string;
+/**
+ * JSON response helper.
+ */
+export declare function jsonResponse(data: unknown, init?: ResponseInit): Response;
+/**
+ * Redirect response helper.
+ */
+export declare function redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+/**
+ * Not found response helper.
+ */
+export declare function notFound(message?: any): Response;
+/** Edge runtime detection result */
+export declare interface RuntimeInfo {
+  platform: EdgePlatform
+  version?: string
+  supportsStreaming: boolean
+  supportsCrypto: boolean
+  supportsKV: boolean
+  supportsCache: boolean
+  capabilities: string[]
+}
+/** Edge handler configuration */
+export declare interface EdgeHandlerConfig {
+  render: (request: Request, context: EdgeContext) => Promise<Response | string>
+  onError?: (error: Error, request: Request) => Response
+  middleware?: EdgeMiddleware[]
+  cache?: EdgeCacheConfig
+  cors?: CorsConfig
+}
+/** Edge context passed to handlers */
+export declare interface EdgeContext {
+  runtime: RuntimeInfo
+  platform: Record<string, unknown>
+  requestId: string
+  geo?: GeoInfo
+  timing: {
+    start: number
+    getElapsed: () => number
+  }
+  kv?: KVNamespace
+  cache?: EdgeCache
+  env: EnvAccessor
+}
+/** Geographic information */
+export declare interface GeoInfo {
+  city?: string
+  country?: string
+  countryCode?: string
+  region?: string
+  latitude?: number
+  longitude?: number
+  timezone?: string
+}
+/** Cache configuration */
+export declare interface EdgeCacheConfig {
+  enabled: boolean
+  ttl?: number
+  keyGenerator?: (request: Request) => string
+  includePaths?: RegExp[]
+  excludePaths?: RegExp[]
+  staleWhileRevalidate?: number
+}
+/** CORS configuration */
+export declare interface CorsConfig {
+  origins?: string[] | '*'
+  methods?: string[]
+  headers?: string[]
+  exposeHeaders?: string[]
+  credentials?: boolean
+  maxAge?: number
+}
+/** KV namespace interface (platform-agnostic) */
+export declare interface KVNamespace {
+  get: (key: string) => Promise<string | null>
+  getWithMetadata: <T>(key: string) => Promise<{ value: string | null, metadata: T | null }>
+  put: (key: string, value: string, options?: KVPutOptions) => Promise<void>
+  delete: (key: string) => Promise<void>
+  list: (options?: KVListOptions) => Promise<KVListResult>
+}
+/** KV put options */
+export declare interface KVPutOptions {
+  expiration?: number
+  expirationTtl?: number
+  metadata?: Record<string, unknown>
+}
+/** KV list options */
+export declare interface KVListOptions {
+  prefix?: string
+  limit?: number
+  cursor?: string
+}
+/** KV list result */
+export declare interface KVListResult {
+  keys: { name: string, expiration?: number, metadata?: Record<string, unknown> }[]
+  cursor?: string
+  list_complete: boolean
+}
+/** Edge cache interface */
+export declare interface EdgeCache {
+  match: (request: Request) => Promise<Response | undefined>
+  put: (request: Request, response: Response) => Promise<void>
+  delete: (request: Request) => Promise<boolean>
+}
+/** Environment variable accessor */
+export declare interface EnvAccessor {
+  get: (key: string) => string | undefined
+  getOrThrow: (key: string) => string
+  has: (key: string) => boolean
+  all: () => Record<string, string>
+}
+/** Supported edge runtime platforms */
+export type EdgePlatform = | 'cloudflare'
+  | 'deno'
+  | 'vercel'
+  | 'netlify'
+  | 'fastly'
+  | 'node'
+  | 'bun'
+  | 'unknown'
+/** Middleware function */
+export type EdgeMiddleware = (
+  request: Request,
+  context: EdgeContext,
+  next: () => Promise<Response>
+) => Promise<Response>

package/dist/env.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns true when running in production mode
+ */
+export declare function isProduction(): boolean;
+/**
+ * Returns true when NOT in production mode, or when debug is enabled.
+ * This covers development, test, and unset environments.
+ */
+export declare function isDevelopment(): boolean;

package/dist/error-boundaries.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Process @errorBoundary directives in templates.
+ *
+ * Syntax:
+ *   @errorBoundary
+ *     <content that might error>
+ *   @fallback
+ *     <fallback content shown on error>
+ *   @enderrorBoundary
+ *
+ * Or with options:
+ *   @errorBoundary(id: 'my-boundary', logErrors: false)
+ */
+export declare function processErrorBoundaryDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Wrap content in a try/catch for SSR error handling.
+ * Returns the fallback if an error occurs during rendering.
+ */
+export declare function withErrorBoundary<T>(render: () => T | Promise<T>, fallback: T, onError?: (error: Error) => void): Promise<T>;
+/**
+ * Create an error boundary wrapper function.
+ */
+export declare function createErrorBoundary<T>(fallback: T, options?: ErrorBoundaryOptions): (render: () => T | Promise<T>) => Promise<T>;
+/**
+ * Generate CSS for error boundary styling.
+ */
+export declare function generateErrorBoundaryCSS(): string;
+/**
+ * Generate client-side runtime for error boundaries.
+ */
+export declare function generateErrorBoundaryRuntime(): string;
+/**
+ * STX Error Boundaries
+ *
+ * Provides graceful error handling for component trees.
+ * When an error occurs within an error boundary, the fallback content is shown
+ * instead of crashing the entire application.
+ *
+ * @module error-boundaries
+ *
+ * @example
+ * ```html
+ * @errorBoundary
+ *   <RiskyComponent />
+ * @fallback
+ *   <div class="error-state">
+ *     <p>Something went wrong</p>
+ *     <button @click="$retry()">Retry</button>
+ *   </div>
+ * @enderrorBoundary
+ * ```
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface ErrorBoundaryOptions {
+  onError?: (error: Error, info: ErrorInfo) => void
+  logErrors?: boolean
+  id?: string
+}
+export declare interface ErrorInfo {
+  componentName?: string
+  stack?: string
+  timestamp: number
+  boundaryId: string
+}
+export declare interface ErrorBoundaryState {
+  hasError: boolean
+  error: Error | null
+  info: ErrorInfo | null
+}

package/dist/error-handling.d.ts

@@ -1,101 +1 @@
-/**
- * Enhanced error reporting with better context
- */
-export declare function createEnhancedError(type: string, message: string, context: ErrorContext): string;
-/**
- * Safe wrapper for potentially dangerous operations
- */
-export declare function safeExecute<T>(operation: () => T, fallback: T, errorHandler?: (error: Error) => void): T;
-/**
- * Async version of safe wrapper
- */
-export declare function safeExecuteAsync<T>(operation: () => Promise<T>, fallback: T, errorHandler?: (error: Error) => void): Promise<T>;
-/**
- * Validation utilities
- */
-export declare const validators: {
-  /**
-   * Validate file path is safe
-   */
-  isValidFilePath(filePath: string): unknown
-};
-/**
- * Error recovery strategies
- */
-export declare const errorRecovery: {
-  /**
-   * Attempt to fix common template syntax errors
-   */
-  fixCommonSyntaxErrors(template: string): unknown;
-  /**
-   * Create fallback content for failed template sections
-   */
-  createFallbackContent(sectionType: string, error: Error): unknown
-};
-// Global error logger instance
-export declare const errorLogger: ErrorLogger;
-/**
- * Development mode helpers
- */
-export declare const devHelpers: {
-  /**
-   * Check if we're in development mode
-   */
-  isDevelopment(): boolean {
-    return process.env.NODE_ENV === 'development' || process.env.stx_DEBUG === 'true'
-  },
-
-  /**
-   * Log detailed error information in development
-   */
-  logDetailedError(error: Error, context?: any): void {
-    if (!this.isDevelopment())
-      return
-
-    console.error('=== stx Detailed Error ===')
-    console.error('Error: unknown
-};
-/**
- * Error context information
- */
-export declare interface ErrorContext {
-  filePath: string
-  template: string
-  offset: number
-  match: string
-}
-/**
- * Custom error types for better error classification
- */
-export declare class StxError extends Error {
-  public code: string;
-  public filePath?: string;
-  public line?: number;
-  public column?: number;
-  public context?: string;
-  constructor(message: string, code: string, filePath?: string, line?: number, column?: number, context?: string);
-}
-export declare class StxSyntaxError extends StxError {
-  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string);
-}
-export declare class StxRuntimeError extends StxError {
-  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string);
-}
-export declare class StxSecurityError extends StxError {
-  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string);
-}
-export declare class StxFileError extends StxError {
-  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string);
-}
-/**
- * Error logging and monitoring
- */
-export declare class ErrorLogger {
-  private errors: Array<{ timestamp: Date, error: Error, context?: any }>;
-  private maxErrors: any;
-  log(error: Error, context?: any): void;
-  getRecentErrors(limit?: any): Array<{ timestamp: Date, error: Error, context?: any }>;
-  getErrorsByType(errorType: string): Array<{ timestamp: Date, error: Error, context?: any }>;
-  clear(): void;
-  getStats(): { total: number, byType: Record<string, number> };
-}
+export * from './errors';