@stacksjs/stx 0.2.155 → 0.2.157

package/dist/document-shell.d.ts

@@ -1,5 +1,45 @@
-import type { AppHeadConfig } from './types/config-types';
+/**
+ * Document Shell Generator
+ *
+ * Auto-generates the HTML document wrapper around page content.
+ * No .stx file needs to write <!DOCTYPE>, <html>, <head>, or <body>.
+ * The shell is configured via stx.config.ts `app.head` and enhanced
+ * at build/serve time with runtime scripts, CSS, and meta tags.
+ *
+ * @module document-shell
+ */
 import type { ColorModeBootConfig } from './color-mode-boot';
+import type { AppHeadConfig } from './types/config-types';
+/**
+ * Inline x-cloak rule shipped in the SSR <head> (stacksjs/stx#1736).
+ *
+ * Must be parsed by the browser BEFORE first paint — so it goes in the head
+ * as static markup, not injected by the runtime script (which runs after the
+ * body has already painted, the window where false `:if` branches / hidden
+ * `:show` elements flash). The `data-stx-cloak` marker makes injection
+ * idempotent. The runtime's own late injection (signals.ts) is retained as a
+ * belt-and-suspenders for SPA-nav fragments that arrive without SSR head
+ * emission.
+ */
+export declare const CLOAK_STYLE = "<style data-stx-cloak>[x-cloak]{display:none !important}</style>";
+/**
+ * Markers recording which `<html>` attributes stx itself wrote from `htmlAttrs`
+ * (stacksjs/stx#1798).
+ *
+ * The router needs them to reconcile the root element across an SPA layout
+ * change. It cannot just diff `<html>` against the incoming document: by then
+ * the color-mode boot script has added its own `dark` class / `data-theme`, and
+ * `animation.ts` has added `data-reduced-motion`, none of which exist in the
+ * server response — a blind diff would strip them on every navigation and
+ * flash the wrong theme. These say exactly what stx put there, so the router
+ * can remove precisely that much and leave runtime state alone.
+ *
+ * `class` is tracked separately because it is the one attribute that gets
+ * *merged* into at runtime, so it has to be reconciled token-by-token rather
+ * than replaced wholesale.
+ */
+export declare const HTML_ATTRS_MARKER = "data-stx-html-attrs";
+export declare const HTML_CLASS_MARKER = "data-stx-html-class";
 /** Emit `k="v"` pairs with every value attribute-escaped. */
 /**
  * The identity of a `<meta>` tag, for deduplication.
@@ -74,7 +114,10 @@ export declare function injectCloakStyle(html: string): string;
  * comments and `<script>` blocks are stepped over, never moved), so a `<style>`
  * sitting next to the markup it styles further down the page is left alone.
  */
-export declare function hoistLeadingHeadTags(content: string): { body: string, hoisted: string[] };
+export declare function hoistLeadingHeadTags(content: string): {
+    body: string;
+    hoisted: string[];
+};
 /**
  * Generate the full HTML document shell wrapping page content.
  *
@@ -85,7 +128,7 @@ export declare function hoistLeadingHeadTags(content: string): { body: string, h
  */
 export declare function generateDocumentShell(content: string, headConfig?: AppHeadConfig, options?: {
     /** Page-specific title (overrides config) */
-    title?: string
+    title?: string;
     /**
      * The title is already HTML and must NOT be escaped again.
      *
@@ -98,24 +141,24 @@ export declare function generateDocumentShell(content: string, headConfig?: AppH
      * A title from `useHead({ title })` is a plain JS string and must stay
      * escaped — that is the XSS path (#1792 item 4).
      */
-    titleIsHtml?: boolean
+    titleIsHtml?: boolean;
     /** Extra styles to inject in <head> (e.g. Crosswind CSS, scoped styles) */
-    styles?: string[]
+    styles?: string[];
     /** Extra scripts to inject before </body> (e.g. signals runtime, router) */
-    bodyScripts?: string[]
+    bodyScripts?: string[];
     /** Extra scripts/tags for <head> */
-    headScripts?: string[]
+    headScripts?: string[];
     /** Stacks to inject (from @push directives) */
-    headStack?: string
-    bodyStack?: string
+    headStack?: string;
+    bodyStack?: string;
     /**
      * Pre-paint color-mode config (stacksjs/stx#1794). When present, the boot
      * script is emitted at the very top of <head> — above the stylesheets,
      * because a stylesheet link ahead of it would block its execution and
      * delay the one thing it exists to do early.
      */
-    colorMode?: ColorModeBootConfig
-  }): string;
+    colorMode?: ColorModeBootConfig;
+}): string;
 /**
  * Check if HTML already has a document shell (<!DOCTYPE> or <html>).
  * Templates that extend layouts with document shells should not be
@@ -196,33 +239,3 @@ export declare function injectConfigHeadTags(html: string, headConfig?: AppHeadC
  * so runtime `useHead` tags aren't double-emitted).
  */
 export declare function ensureDocumentShell(html: string, headConfig?: AppHeadConfig, options?: Parameters<typeof generateDocumentShell>[2]): string;
-/**
- * Inline x-cloak rule shipped in the SSR <head> (stacksjs/stx#1736).
- *
- * Must be parsed by the browser BEFORE first paint — so it goes in the head
- * as static markup, not injected by the runtime script (which runs after the
- * body has already painted, the window where false `:if` branches / hidden
- * `:show` elements flash). The `data-stx-cloak` marker makes injection
- * idempotent. The runtime's own late injection (signals.ts) is retained as a
- * belt-and-suspenders for SPA-nav fragments that arrive without SSR head
- * emission.
- */
-export declare const CLOAK_STYLE: '<style data-stx-cloak>[x-cloak]{display:none !important}</style>';
-/**
- * Markers recording which `<html>` attributes stx itself wrote from `htmlAttrs`
- * (stacksjs/stx#1798).
- *
- * The router needs them to reconcile the root element across an SPA layout
- * change. It cannot just diff `<html>` against the incoming document: by then
- * the color-mode boot script has added its own `dark` class / `data-theme`, and
- * `animation.ts` has added `data-reduced-motion`, none of which exist in the
- * server response — a blind diff would strip them on every navigation and
- * flash the wrong theme. These say exactly what stx put there, so the router
- * can remove precisely that much and leave runtime state alone.
- *
- * `class` is tracked separately because it is the one attribute that gets
- * *merged* into at runtime, so it has to be reconciled token-by-token rather
- * than replaced wholesale.
- */
-export declare const HTML_ATTRS_MARKER: 'data-stx-html-attrs';
-export declare const HTML_CLASS_MARKER: 'data-stx-html-class';

package/dist/dynamic-components.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Dynamic Component Support
+ *
+ * Handles `<component :is="expr">` syntax for runtime component switching.
+ * Server-side: evaluates the expression and resolves the component.
+ * Client-side: signals runtime watches :is binding and swaps content.
+ *
+ * @module dynamic-components
+ */
 import type { StxOptions } from './types';
 /**
  * Process `<component :is="expr">` tags in the template.

package/dist/error-boundaries.d.ts

@@ -1,3 +1,50 @@
+/**
+ * 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
+ * ```
+ */
+export interface ErrorBoundaryOptions {
+    /** Custom error handler */
+    onError?: (error: Error, info: ErrorInfo) => void;
+    /** Whether to log errors to console (default: true) */
+    logErrors?: boolean;
+    /** Custom error ID for tracking */
+    id?: string;
+}
+export interface ErrorInfo {
+    /** Component name where error occurred */
+    componentName?: string;
+    /** Stack trace */
+    stack?: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Boundary ID */
+    boundaryId: string;
+}
+export interface ErrorBoundaryState {
+    /** Whether an error has occurred */
+    hasError: boolean;
+    /** The captured error */
+    error: Error | null;
+    /** Error info */
+    info: ErrorInfo | null;
+}
 /**
  * Process @errorBoundary directives in templates.
  *
@@ -11,7 +58,6 @@
  * Or with options:
  *   @errorBoundary(id: 'my-boundary', logErrors: false)
  */
-// eslint-disable-next-line pickier/no-unused-vars
 export declare function processErrorBoundaryDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
 /**
  * Wrap content in a try/catch for SSR error handling.
@@ -30,43 +76,3 @@ 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

@@ -11,4 +11,4 @@
  * @see ./errors/sanitizer.ts - Parameter sanitization
  * @see ./errors/logger.ts - Error logging and recovery
  */
-export * from './errors/index';
+export * from './errors';

package/dist/errors/codes.d.ts

@@ -1,3 +1,23 @@
+/**
+ * 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 interface ErrorMessageTemplate {
+    message: string;
+    help?: string;
+}
+/**
+ * Localized error messages by error code
+ */
+export type ErrorMessages = Record<number, ErrorMessageTemplate>;
 /**
  * Set the locale for error messages
  */
@@ -23,10 +43,6 @@ export declare function getErrorMessage(code: number, params?: Record<string, st
  * 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
  *
@@ -40,45 +56,37 @@ export declare function getErrorCodeName(code: number): string | undefined;
  * - 1600-1699: Expression errors
  */
 export declare const ErrorCodes: {
-  UNCLOSED_DIRECTIVE: 1001;
-  UNCLOSED_EXPRESSION: 1002;
-  INVALID_DIRECTIVE_SYNTAX: 1003;
-  MALFORMED_EXPRESSION: 1004;
-  UNEXPECTED_TOKEN: 1005;
-  UNDEFINED_VARIABLE: 1101;
-  TYPE_ERROR: 1102;
-  EVALUATION_ERROR: 1103;
-  INFINITE_LOOP: 1104;
-  CIRCULAR_REFERENCE: 1105;
-  UNSAFE_EXPRESSION: 1201;
-  PATH_TRAVERSAL: 1202;
-  XSS_ATTEMPT: 1203;
-  CODE_INJECTION: 1204;
-  DOM_API_VIOLATION: 1205;
-  FILE_NOT_FOUND: 1301;
-  FILE_READ_ERROR: 1302;
-  INVALID_FILE_PATH: 1303;
-  PERMISSION_DENIED: 1304;
-  INVALID_CONFIG: 1401;
-  MISSING_REQUIRED_CONFIG: 1402;
-  DEPRECATED_CONFIG: 1403;
-  COMPONENT_NOT_FOUND: 1501;
-  INVALID_PROPS: 1502;
-  COMPONENT_RENDER_ERROR: 1503;
-  FILTER_NOT_FOUND: 1601;
-  INVALID_FILTER_ARGS: 1602;
-  EXPRESSION_TIMEOUT: 1603
+    readonly UNCLOSED_DIRECTIVE: 1001;
+    readonly UNCLOSED_EXPRESSION: 1002;
+    readonly INVALID_DIRECTIVE_SYNTAX: 1003;
+    readonly MALFORMED_EXPRESSION: 1004;
+    readonly UNEXPECTED_TOKEN: 1005;
+    readonly UNDEFINED_VARIABLE: 1101;
+    readonly TYPE_ERROR: 1102;
+    readonly EVALUATION_ERROR: 1103;
+    readonly INFINITE_LOOP: 1104;
+    readonly CIRCULAR_REFERENCE: 1105;
+    readonly UNSAFE_EXPRESSION: 1201;
+    readonly PATH_TRAVERSAL: 1202;
+    readonly XSS_ATTEMPT: 1203;
+    readonly CODE_INJECTION: 1204;
+    readonly DOM_API_VIOLATION: 1205;
+    readonly FILE_NOT_FOUND: 1301;
+    readonly FILE_READ_ERROR: 1302;
+    readonly INVALID_FILE_PATH: 1303;
+    readonly PERMISSION_DENIED: 1304;
+    readonly INVALID_CONFIG: 1401;
+    readonly MISSING_REQUIRED_CONFIG: 1402;
+    readonly DEPRECATED_CONFIG: 1403;
+    readonly COMPONENT_NOT_FOUND: 1501;
+    readonly INVALID_PROPS: 1502;
+    readonly COMPONENT_RENDER_ERROR: 1503;
+    readonly FILTER_NOT_FOUND: 1601;
+    readonly INVALID_FILTER_ARGS: 1602;
+    readonly EXPRESSION_TIMEOUT: 1603;
 };
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
 /**
- * Error message template with placeholder support
- * Placeholders use {{name}} syntax
- */
-export declare interface ErrorMessageTemplate {
-  message: string
-  help?: string
-}
-/**
- * Localized error messages by error code
+ * Get error code name from numeric code
  */
-export type ErrorMessages = Record<number, ErrorMessageTemplate>;
-export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+export declare function getErrorCodeName(code: number): string | undefined;

package/dist/errors/formatter.d.ts

@@ -1,5 +1,63 @@
+/**
+ * Error Formatting Utilities
+ *
+ * Provides standardized error message formatting for different output formats.
+ *
+ * @module errors/formatter
+ */
 import type { ErrorCode } from './codes';
 import type { ErrorContext } from './types';
+/**
+ * Error output format options
+ */
+export type ErrorOutputFormat = 'html' | 'text' | 'json' | 'console';
+/**
+ * Standardized error message options
+ */
+export interface ErrorMessageOptions {
+    /** Error type/category (e.g., 'Directive', 'Expression', 'Syntax') */
+    type: string;
+    /** The error message */
+    message: string;
+    /** Numeric error code */
+    code?: ErrorCode;
+    /** File path where error occurred */
+    filePath?: string;
+    /** Line number */
+    line?: number;
+    /** Column number */
+    column?: number;
+    /** Template content for context */
+    template?: string;
+    /** Position offset in template */
+    offset?: number;
+    /** The problematic code snippet */
+    snippet?: string;
+    /** Suggestion for fixing the error */
+    suggestion?: string;
+    /** Output format */
+    format?: ErrorOutputFormat;
+}
+/**
+ * Standardized error message result
+ */
+export interface StandardizedError {
+    /** Formatted error message for display */
+    formatted: string;
+    /** Raw error data */
+    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;
+    };
+}
 /**
  * Create a standardized error message in any format
  */
@@ -24,41 +82,3 @@ export declare function safeExecute<T>(operation: () => T, fallback: T, errorHan
  * 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

@@ -5,64 +5,8 @@
  *
  * @module errors
  */
-// Error codes and localization
-export {
-  clearErrorMessages,
-  type ErrorCode,
-  ErrorCodes,
-  type ErrorMessages,
-  type ErrorMessageTemplate,
-  formatLocalizedError,
-  getErrorCodeName,
-  getErrorLocale,
-  getErrorMessage,
-  registerErrorMessages,
-  setErrorLocale,
-} from './codes';
-// Error formatting
-export {
-  consoleError,
-  createEnhancedError,
-  type ErrorMessageOptions,
-  type ErrorOutputFormat,
-  formatError,
-  inlineError,
-  safeExecute,
-  safeExecuteAsync,
-  type StandardizedError,
-} from './formatter';
-// Logger and recovery
-export {
-  devHelpers,
-  type ErrorLogEntry,
-  ErrorLogger,
-  errorLogger,
-  type ErrorLoggerOptions,
-  errorRecovery,
-} from './logger';
-// Sanitization
-export {
-  sanitizeComponentProps,
-  sanitizeDirectiveParam,
-  sanitizeDirectiveParams,
-  type SanitizedParam,
-  sanitizeExpression,
-  sanitizeFilePath,
-  type SanitizeOptions,
-  validators,
-} from './sanitizer';
-// Error types and classes
-export {
-  configureErrorHandling,
-  type ErrorConfig,
-  type ErrorContext,
-  formatFilePath,
-  getErrorConfig,
-  resetErrorConfig,
-  StxError,
-  StxFileError,
-  StxRuntimeError,
-  StxSecurityError,
-  StxSyntaxError,
-  StxValidationError,
-} from './types';
+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';