@stacksjs/stx 0.1.16 → 0.2.3

package/dist/errors/codes.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Set the locale for error messages
+ */
+export declare function setErrorLocale(locale: string): void;
+/**
+ * Get the current error message locale
+ */
+export declare function getErrorLocale(): string;
+/**
+ * Register custom error messages for a locale
+ * This allows overriding default messages or adding translations
+ */
+export declare function registerErrorMessages(messages: ErrorMessages): void;
+/**
+ * Clear custom error messages
+ */
+export declare function clearErrorMessages(): void;
+/**
+ * Get an error message by code, with placeholder substitution
+ */
+export declare function getErrorMessage(code: number, params?: Record<string, string>): ErrorMessageTemplate;
+/**
+ * Format an error with localized message
+ */
+export declare function formatLocalizedError(code: number, params?: Record<string, string>): string;
+/**
+ * Get error code name from numeric code
+ */
+export declare function getErrorCodeName(code: number): string | undefined;
+/**
+ * Numeric error codes for programmatic error handling
+ *
+ * Error code ranges:
+ * - 1000-1099: Syntax errors
+ * - 1100-1199: Runtime errors
+ * - 1200-1299: Security errors
+ * - 1300-1399: File errors
+ * - 1400-1499: Configuration errors
+ * - 1500-1599: Component errors
+ * - 1600-1699: Expression errors
+ */
+export declare const ErrorCodes: {
+  // Syntax errors (1000-1099)
+  UNCLOSED_DIRECTIVE: 1001;
+  UNCLOSED_EXPRESSION: 1002;
+  INVALID_DIRECTIVE_SYNTAX: 1003;
+  MALFORMED_EXPRESSION: 1004;
+  UNEXPECTED_TOKEN: 1005;
+  // Runtime errors (1100-1199)
+  UNDEFINED_VARIABLE: 1101;
+  TYPE_ERROR: 1102;
+  EVALUATION_ERROR: 1103;
+  INFINITE_LOOP: 1104;
+  CIRCULAR_REFERENCE: 1105;
+  // Security errors (1200-1299)
+  UNSAFE_EXPRESSION: 1201;
+  PATH_TRAVERSAL: 1202;
+  XSS_ATTEMPT: 1203;
+  CODE_INJECTION: 1204;
+  DOM_API_VIOLATION: 1205;
+  // File errors (1300-1399)
+  FILE_NOT_FOUND: 1301;
+  FILE_READ_ERROR: 1302;
+  INVALID_FILE_PATH: 1303;
+  PERMISSION_DENIED: 1304;
+  // Configuration errors (1400-1499)
+  INVALID_CONFIG: 1401;
+  MISSING_REQUIRED_CONFIG: 1402;
+  DEPRECATED_CONFIG: 1403;
+  // Component errors (1500-1599)
+  COMPONENT_NOT_FOUND: 1501;
+  INVALID_PROPS: 1502;
+  COMPONENT_RENDER_ERROR: 1503;
+  // Expression errors (1600-1699)
+  FILTER_NOT_FOUND: 1601;
+  INVALID_FILTER_ARGS: 1602;
+  EXPRESSION_TIMEOUT: 1603
+};
+/**
+ * Error Codes and Localized Messages
+ *
+ * Provides numeric error codes for programmatic error handling
+ * and localized error message templates.
+ *
+ * @module errors/codes
+ */
+/**
+ * Error message template with placeholder support
+ * Placeholders use {{name}} syntax
+ */
+export declare interface ErrorMessageTemplate {
+  message: string
+  help?: string
+}
+/**
+ * Localized error messages by error code
+ */
+export type ErrorMessages = Record<number, ErrorMessageTemplate>
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes]

package/dist/errors/formatter.d.ts

@@ -0,0 +1,64 @@
+import type { ErrorCode } from './codes';
+import type { ErrorContext } from './types';
+/**
+ * Create a standardized error message in any format
+ */
+export declare function formatError(options: ErrorMessageOptions): StandardizedError;
+/**
+ * Quick helper for creating inline error messages (for template output)
+ */
+export declare function inlineError(type: string, message: string, code?: ErrorCode): string;
+/**
+ * Quick helper for creating console error messages
+ */
+export declare function consoleError(type: string, message: string, filePath?: string, line?: number, code?: ErrorCode): string;
+/**
+ * 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>;
+/**
+ * Standardized error message options
+ */
+export declare interface ErrorMessageOptions {
+  type: string
+  message: string
+  code?: ErrorCode
+  filePath?: string
+  line?: number
+  column?: number
+  template?: string
+  offset?: number
+  snippet?: string
+  suggestion?: string
+  format?: ErrorOutputFormat
+}
+/**
+ * Standardized error message result
+ */
+export declare interface StandardizedError {
+  formatted: string
+  data: {
+    type: string
+    code: number | undefined
+    codeName: string | undefined
+    message: string
+    filePath: string | undefined
+    line: number | undefined
+    column: number | undefined
+    snippet: string | undefined
+    suggestion: string | undefined
+    timestamp: string
+  }
+}
+/**
+ * Error output format options
+ */
+export type ErrorOutputFormat = 'html' | 'text' | 'json' | 'console'

package/dist/errors/index.d.ts

@@ -0,0 +1,56 @@
+export {
+  clearErrorMessages,
+  type ErrorCode,
+  ErrorCodes,
+  type ErrorMessages,
+  type ErrorMessageTemplate,
+  formatLocalizedError,
+  getErrorCodeName,
+  getErrorLocale,
+  getErrorMessage,
+  registerErrorMessages,
+  setErrorLocale,
+} from './codes';
+export {
+  consoleError,
+  createEnhancedError,
+  type ErrorMessageOptions,
+  type ErrorOutputFormat,
+  formatError,
+  inlineError,
+  safeExecute,
+  safeExecuteAsync,
+  type StandardizedError,
+} from './formatter';
+export {
+  devHelpers,
+  type ErrorLogEntry,
+  ErrorLogger,
+  errorLogger,
+  type ErrorLoggerOptions,
+  errorRecovery,
+} from './logger';
+export {
+  sanitizeComponentProps,
+  sanitizeDirectiveParam,
+  sanitizeDirectiveParams,
+  type SanitizedParam,
+  sanitizeExpression,
+  sanitizeFilePath,
+  type SanitizeOptions,
+  validators,
+} from './sanitizer';
+export {
+  configureErrorHandling,
+  type ErrorConfig,
+  type ErrorContext,
+  formatFilePath,
+  getErrorConfig,
+  resetErrorConfig,
+  StxError,
+  StxFileError,
+  StxRuntimeError,
+  StxSecurityError,
+  StxSyntaxError,
+  StxValidationError,
+} from './types';

package/dist/errors/logger.d.ts

@@ -0,0 +1,74 @@
+import { isDevelopment } from '../env';
+export declare const errorRecovery: ErrorRecovery;
+// Global error logger instance
+export declare const errorLogger: ErrorLogger;
+export declare const devHelpers: DevHelpers;
+/**
+ * Error recovery strategies
+ *
+ * NOTE: Auto-recovery is opt-in via configuration.
+ * Use configureErrorHandling({ enableAutoRecovery: true }) to enable.
+ */
+export declare interface ErrorRecovery {
+  isEnabled(): boolean
+  fixCommonSyntaxErrors(template: string): { fixed: string, fixes: string[] }
+  createFallbackContent(sectionType: string, error: Error): string
+}
+/**
+ * Error logger configuration options
+ */
+export declare interface ErrorLoggerOptions {
+  maxErrors?: number
+  enableFileLogging?: boolean
+  logFilePath?: string
+  logFormat?: 'json' | 'text'
+  maxFileSize?: number
+  maxLogFiles?: number
+  minLevel?: 'all' | 'error' | 'warning'
+}
+/**
+ * Error log entry structure
+ */
+export declare interface ErrorLogEntry {
+  timestamp: Date
+  error: Error
+  context?: unknown
+  level?: 'error' | 'warning' | 'info'
+}
+/**
+ * Development mode helpers
+ */
+export declare interface DevHelpers {
+  isDevelopment(): boolean
+  logDetailedError(error: Error, context?: unknown): void
+  createErrorReport(error: Error, context?: unknown): string
+}
+/**
+ * Error logging and monitoring with optional file persistence
+ */
+export declare class ErrorLogger {
+  private errors: ErrorLogEntry[];
+  private maxErrors: number;
+  private enableFileLogging: boolean;
+  private logFilePath: string;
+  private logFormat: 'json' | 'text';
+  private maxFileSize: number;
+  private maxLogFiles: number;
+  private minLevel: 'all' | 'error' | 'warning';
+  private writeQueue: Promise<void>;
+  constructor(options?: ErrorLoggerOptions);
+  configure(options: ErrorLoggerOptions): void;
+  log(error: Error, context?: unknown, level?: 'error' | 'warning' | 'info'): void;
+  private shouldLog(level: 'error' | 'warning' | 'info'): boolean;
+  private formatEntry(entry: ErrorLogEntry): string;
+  private writeToFile(entry: ErrorLogEntry): void;
+  private rotateIfNeeded(fs: typeof import('node:fs')): Promise<void>;
+  getRecentErrors(limit?: any): ErrorLogEntry[];
+  getErrorsByType(errorType: string): ErrorLogEntry[];
+  getErrorsByLevel(level: 'error' | 'warning' | 'info'): ErrorLogEntry[];
+  clear(): void;
+  clearLogFile(): Promise<void>;
+  getStats(): { total: number, byType: Record<string, number>, byLevel: Record<string, number> };
+  exportToFile(filePath: string, format?: 'json' | 'text'): Promise<void>;
+  flush(): Promise<void>;
+}

package/dist/errors/sanitizer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Sanitize a directive parameter value
+ */
+export declare function sanitizeDirectiveParam(param: string, options?: SanitizeOptions): SanitizedParam;
+/**
+ * Sanitize a file path parameter
+ */
+export declare function sanitizeFilePath(filePath: string, baseDir?: string): string | null;
+/**
+ * Sanitize an expression parameter (used in @if, @foreach, etc.)
+ */
+export declare function sanitizeExpression(expr: string): SanitizedParam;
+/**
+ * Sanitize multiple directive parameters at once
+ */
+export declare function sanitizeDirectiveParams(params: string[], options?: SanitizeOptions): SanitizedParam[];
+/**
+ * Validate and sanitize component props
+ */
+export declare function sanitizeComponentProps(props: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Validation utilities
+ */
+export declare const validators: {
+  
+};
+/**
+ * Options for parameter sanitization
+ */
+export declare interface SanitizeOptions {
+  allowHtml?: boolean
+  maxLength?: number
+  allowSpecialChars?: boolean
+  customSanitizer?: (value: string) => string
+}
+/**
+ * Result of parameter sanitization
+ */
+export declare interface SanitizedParam {
+  value: string
+  modified: boolean
+  warnings: string[]
+}

package/dist/errors/types.d.ts

@@ -0,0 +1,79 @@
+import type { ErrorCode } from './codes';
+/**
+ * Configure error handling behavior
+ */
+export declare function configureErrorHandling(config: Partial<ErrorConfig>): void;
+/**
+ * Get current error configuration
+ */
+export declare function getErrorConfig(): ErrorConfig;
+/**
+ * Reset error configuration to defaults
+ */
+export declare function resetErrorConfig(): void;
+/**
+ * Format file path based on configuration
+ */
+export declare function formatFilePath(filePath: string): string;
+/**
+ * Error handling configuration
+ */
+export declare interface ErrorConfig {
+  showRelativePaths: boolean
+  baseDir?: string
+  enableAutoRecovery: boolean
+  logRecoveryWarnings: boolean
+}
+/**
+ * Error context information
+ */
+export declare interface ErrorContext {
+  filePath: string
+  template: string
+  offset: number
+  match: string
+}
+/**
+ * Base STX error class
+ */
+export declare class StxError extends Error {
+  numericCode: ErrorCode;
+  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, numericCode?: ErrorCode);
+}
+/**
+ * Syntax error in template
+ */
+export declare class StxSyntaxError extends StxError {
+  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+}
+/**
+ * Runtime error during template processing
+ */
+export declare class StxRuntimeError extends StxError {
+  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+}
+/**
+ * Security-related error
+ */
+export declare class StxSecurityError extends StxError {
+  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+}
+/**
+ * File operation error
+ */
+export declare class StxFileError extends StxError {
+  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+}
+/**
+ * Validation error - these are ALWAYS fatal and cannot be recovered from.
+ * Used for enforcing coding standards like prohibited DOM API usage.
+ */
+export declare class StxValidationError extends StxError {
+  readonly isFatal: boolean;
+  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+}

package/dist/events.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Extract and process event attributes from a template without generating
+ * a standalone script. Returns the modified template (with @event attributes
+ * removed and IDs added) and the collected event bindings as data.
+ *
+ * Used by SFC processing to inject event bindings into the component's
+ * <script client> scope instead of a separate script block.
+ *
+ * @param template - The HTML template string
+ * @returns Object with processed template and collected bindings
+ */
+export declare function extractAndProcessEvents(template: string): {
+  template: string
+  bindings: ParsedEvent[]
+};
+/**
+ * Process event directives in a template.
+ *
+ * Transforms `@click`, `@keydown.enter`, etc. attributes into
+ * client-side event listeners.
+ *
+ * In SFC mode (context.__stx_sfc_mode), event bindings are collected
+ * on context.__stx_event_bindings instead of generating a standalone script.
+ * This allows them to be injected into the component's <script client> scope.
+ *
+ * @param template - The HTML template string
+ * @param context - Template context
+ * @param filePath - Source file path for error messages
+ * @returns Processed template with event binding script (or just template in SFC mode)
+ */
+export declare function processEventDirectives(template: string, context: Record<string, unknown>, _filePath: string): string;
+/**
+ * Check if a template contains event directives
+ */
+export declare function hasEventDirectives(template: string): boolean;
+/**
+ * Event Directives Module
+ *
+ * Provides Alpine.js-style event handling for STX templates.
+ * Transforms `@click`, `@keydown.enter`, etc. into client-side event listeners.
+ *
+ * ## Supported Syntax
+ *
+ * ### Basic Events
+ * ```html
+ * <button @click="count++">Increment</button>
+ * <button @click="handleClick()">Click me</button>
+ * <form @submit="handleSubmit()">...</form>
+ * ```
+ *
+ * ### Event Modifiers
+ * ```html
+ * <form @submit.prevent="handleSubmit()">...</form>
+ * <a @click.prevent.stop="navigate()">Link</a>
+ * <button @click.once="initialize()">Init</button>
+ * <div @click.self="onlyThis()">...</div>
+ * <input @keydown.capture="log()">
+ * ```
+ *
+ * ### Key Modifiers
+ * ```html
+ * <input @keydown.enter="submit()">
+ * <input @keyup.escape="cancel()">
+ * <input @keydown.space="toggle()">
+ * <input @keydown.ctrl.s="save()">
+ * <input @keydown.meta.enter="send()">
+ * ```
+ *
+ * ### Mouse Modifiers
+ * ```html
+ * <div @click.left="handleLeft()">
+ * <div @click.right="handleRight()">
+ * <div @click.middle="handleMiddle()">
+ * ```
+ *
+ * ### Special Variables
+ * ```html
+ * <input @input="value = $event.target.value">
+ * <button @click="handleClick($el)">Uses element</button>
+ * ```
+ *
+ * @module events
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface ParsedEvent {
+  attribute: string
+  event: string
+  handler: string
+  modifiers: EventModifiers
+  elementId: string
+}
+export declare interface EventModifiers {
+  prevent: boolean
+  stop: boolean
+  once: boolean
+  capture: boolean
+  self: boolean
+  passive: boolean
+  keys: string[]
+  systemKeys: string[]
+  mouse: string | null
+  debounce: number | null
+  throttle: number | null
+}

package/dist/expressions.d.ts

@@ -1,7 +1,42 @@
 /**
- * Set global context for filters
+ * Register a custom filter
+ *
+ * @param name - Filter name (used in templates as {{ value | filterName }})
+ * @param fn - Filter function
+ *
+ * @example
+ * ```typescript
+ * // Register a custom filter
+ * registerFilter('reverse', (value) => {
+ *   return String(value).split('').reverse().join('')
+ * })
+ *
+ * // Use in template: {{ name | reverse }}
+ * ```
  */
-export declare function setGlobalContext(context: Record<string, any>): void;
+export declare function registerFilter(name: string, fn: FilterFunction): void;
+/**
+ * Register multiple custom filters at once
+ *
+ * @param filters - Object mapping filter names to functions
+ *
+ * @example
+ * ```typescript
+ * registerFilters({
+ *   reverse: (value) => String(value).split('').reverse().join(''),
+ *   double: (value) => Number(value) * 2,
+ * })
+ * ```
+ */
+export declare function registerFilters(filters: Record<string, FilterFunction>): void;
+/**
+ * Get all available filters (built-in + custom)
+ */
+export declare function getAllFilters(): Record<string, FilterFunction>;
+/**
+ * Clear all custom filters (useful for testing)
+ */
+export declare function clearCustomFilters(): void;
 /**
  * HTML escape function to prevent XSS
  */
@@ -26,23 +61,63 @@ export declare function evaluateExpression(expression: string, context: Record<s
  * HTML unescape function to reverse escapeHtml
  */
 export declare function unescapeHtml(html: string): string;
+// =============================================================================
+// Built-in Filters
+// =============================================================================
 export declare const defaultFilters: {
   // String transformation filters
-  uppercase: (value: any) => unknown;
-  lowercase: (value: any) => unknown;
-  capitalize: (value: any) => unknown;
+  uppercase: (value: any, _context: Record<string, any>) => unknown;
+  lowercase: (value: any, _context: Record<string, any>) => unknown;
+  capitalize: (value: any, _context: Record<string, any>) => unknown;
   // Number filters
-  number: (value: any, decimals: number?) => unknown;
+  number: (value: any, _context: Record<string, any>, decimals: number?) => unknown;
   // Array filters
   join: () => unknown;
   // Safety filters
-  escape: (value: any) => unknown;
-  // Translation filter
-  translate: (value: any, params: Record<string, any> = {}) => unknown;
+  escape: (value: any, _context: Record<string, any>) => unknown;
+  // Translation filter - uses context parameter instead of global state
+  translate: (value: any, context: Record<string, any>, params: Record<string, any> = {}) => unknown;
   // Short alias for translate
-  t: (value: any, params: Record<string, any> = {}) => unknown
+  t: (value: any, context: Record<string, any>, params: Record<string, any> = {}) => unknown;
+  // =========================================================================
+  // Additional Utility Filters
+  // =========================================================================
+
+  // Truncate string to specified length with ellipsis
+  truncate: (value: any, _context: Record<string, any>, length: number?, suffix: string?) => unknown;
+  // Format date using Intl.DateTimeFormat
+  date: (value: any, _context: Record<string, any>, format: string?, locale: string?) => unknown;
+  // Format number as currency
+  currency: (value: any, _context: Record<string, any>, currencyCode: string?, locale: string?) => unknown;
+  // Pluralize word based on count
+  pluralize: (value: any, _context: Record<string, any>, singular: string, plural?: string) => unknown;
+  // Get first item from array or first character from string
+  first: (value: any, _context: Record<string, any>) => unknown;
+  // Get last item from array or last character from string
+  last: (value: any, _context: Record<string, any>) => unknown;
+  // Get length of array or string
+  length: (value: any, _context: Record<string, any>) => unknown;
+  // Convert to JSON string
+  json: (value: any, _context: Record<string, any>, pretty: boolean?) => unknown;
+  // Default value if null/undefined
+  default: (value: any, _context: Record<string, any>, defaultValue: any?) => unknown;
+  // Reverse string or array
+  reverse: (value: any, _context: Record<string, any>) => unknown;
+  // Slice array or string
+  slice: (value: any, _context: Record<string, any>, start: number?, end?: number) => unknown;
+  // Replace text
+  replace: (value: any, _context: Record<string, any>, search: string, replacement: string?) => unknown;
+  // Strip HTML tags
+  stripTags: (value: any, _context: Record<string, any>) => unknown;
+  // URL encode
+  urlencode: (value: any, _context: Record<string, any>) => unknown;
+  // Absolute value
+  abs: (value: any, _context: Record<string, any>) => unknown;
+  // Round number
+  round: (value: any, _context: Record<string, any>, decimals: number?) => unknown
 };
 /**
  * Add basic filter support to expressions
+ * Filter functions receive the value to transform, optional args, and the context object
  */
-export type FilterFunction = (value: any, ...args: any[]) => any
+export type FilterFunction = (value: any, context: Record<string, any>, ...args: any[]) => any

package/dist/formatter.d.ts

@@ -2,6 +2,10 @@
  * Format stx file content
  */
 export declare function formatStxContent(content: string, options?: FormatterOptions): string;
+/**
+ * Format markdown file content, processing stx code blocks
+ */
+export declare function formatMarkdownContent(content: string, options?: FormatterOptions): string;
 /**
  * stx file formatter for automatically formatting .stx files
  */