@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/error-boundaries.js

@@ -0,0 +1,281 @@
+let boundaryIdCounter = 0;
+function generateBoundaryId() {
+  return `eb-${++boundaryIdCounter}-${Date.now().toString(36)}`;
+}
+export function processErrorBoundaryDirectives(template, context = {}, _filePath) {
+  const boundaryRegex = /@errorBoundary(?:\s*\(([^)]*)\))?\s*([\s\S]*?)@fallback\s*([\s\S]*?)@enderrorBoundary/gi;
+  return template.replace(boundaryRegex, (_match, optionsStr, content, fallback) => {
+    const boundaryId = generateBoundaryId(), options = parseErrorBoundaryOptions(optionsStr || "");
+    return generateErrorBoundaryHtml(boundaryId, content.trim(), fallback.trim(), options);
+  });
+}
+function parseErrorBoundaryOptions(optionsStr) {
+  const options = {}, keyValueRegex = /(\w+)\s*:\s*(?:'([^']*)'|"([^"]*)"|(\w+))/g;
+  let match;
+  while ((match = keyValueRegex.exec(optionsStr)) !== null) {
+    const key = match[1], value = match[2] || match[3] || match[4];
+    switch (key) {
+      case "id":
+        options.id = value;
+        break;
+      case "logErrors":
+        options.logErrors = value === "true";
+        break;
+    }
+  }
+  return options;
+}
+function generateErrorBoundaryHtml(boundaryId, content, fallback, options) {
+  const logErrors = options.logErrors !== !1;
+  return `
+<div class="stx-error-boundary" data-boundary-id="${boundaryId}" data-has-error="false">
+  <div class="stx-error-boundary-content" data-boundary-content="${boundaryId}">
+    ${content}
+  </div>
+  <div class="stx-error-boundary-fallback" data-boundary-fallback="${boundaryId}" style="display: none;">
+    ${fallback}
+  </div>
+</div>
+<script>
+(function() {
+  const boundaryId = '${boundaryId}';
+  const logErrors = ${logErrors};
+  const boundary = document.querySelector('[data-boundary-id="' + boundaryId + '"]');
+  const contentEl = document.querySelector('[data-boundary-content="' + boundaryId + '"]');
+  const fallbackEl = document.querySelector('[data-boundary-fallback="' + boundaryId + '"]');
+
+  if (!boundary || !contentEl || !fallbackEl) return;
+
+  // Error state
+  let hasError = false;
+  let lastError = null;
+
+  // Show error fallback
+  function showFallback(error) {
+    hasError = true;
+    lastError = error;
+    boundary.setAttribute('data-has-error', 'true');
+    contentEl.style.display = 'none';
+    fallbackEl.style.display = '';
+
+    if (logErrors) {
+      console.error('[stx:errorBoundary:' + boundaryId + ']', error);
+    }
+
+    // Dispatch error event
+    boundary.dispatchEvent(new CustomEvent('stx:error', {
+      detail: { error: error, boundaryId: boundaryId },
+      bubbles: true
+    }));
+  }
+
+  // Retry function (resets the boundary)
+  function retry() {
+    hasError = false;
+    lastError = null;
+    boundary.setAttribute('data-has-error', 'false');
+    contentEl.style.display = '';
+    fallbackEl.style.display = 'none';
+
+    // Dispatch retry event
+    boundary.dispatchEvent(new CustomEvent('stx:retry', {
+      detail: { boundaryId: boundaryId },
+      bubbles: true
+    }));
+  }
+
+  // Expose retry function
+  window['$stxRetry_' + boundaryId.replace(/-/g, '_')] = retry;
+
+  // Make $retry available within the fallback
+  fallbackEl.querySelectorAll('[onclick*="$retry"]').forEach(function(el) {
+    const onclick = el.getAttribute('onclick');
+    if (onclick) {
+      el.setAttribute('onclick', onclick.replace(/\\$retry\\(\\)/g, "window['$stxRetry_" + boundaryId.replace(/-/g, '_') + "']()"));
+    }
+  });
+
+  // Handle @click="$retry()" syntax
+  fallbackEl.querySelectorAll('[\\\\@click*="$retry"]').forEach(function(el) {
+    el.addEventListener('click', function(e) {
+      e.preventDefault();
+      retry();
+    });
+  });
+
+  // Also check for data-onclick
+  fallbackEl.querySelectorAll('[data-onclick*="$retry"]').forEach(function(el) {
+    el.addEventListener('click', function(e) {
+      e.preventDefault();
+      retry();
+    });
+  });
+
+  // Catch errors in content
+  contentEl.addEventListener('error', function(e) {
+    showFallback(e.error || new Error('Unknown error'));
+  }, true);
+
+  // Wrap global error handler for this boundary
+  const originalOnError = window.onerror;
+  window.onerror = function(message, source, lineno, colno, error) {
+    // Check if error originated from within this boundary
+    if (contentEl.contains(document.activeElement) || isErrorFromBoundary(error)) {
+      showFallback(error || new Error(String(message)));
+      return true; // Prevent default handling
+    }
+    if (originalOnError) {
+      return originalOnError.apply(this, arguments);
+    }
+    return false;
+  };
+
+  // Helper to check if error is from this boundary (basic heuristic)
+  function isErrorFromBoundary(error) {
+    if (!error || !error.stack) return false;
+    return error.stack.includes(boundaryId);
+  }
+
+  // Expose error info
+  window.STX = window.STX || {};
+  window.STX.errorBoundaries = window.STX.errorBoundaries || {};
+  window.STX.errorBoundaries[boundaryId] = {
+    hasError: function() { return hasError; },
+    getError: function() { return lastError; },
+    retry: retry,
+    showFallback: showFallback
+  };
+})();
+</script>
+`;
+}
+export async function withErrorBoundary(render, fallback, onError) {
+  try {
+    return await render();
+  } catch (error) {
+    if (onError)
+      onError(error instanceof Error ? error : Error(String(error)));
+    else
+      console.error("[stx:errorBoundary] SSR Error:", error);
+    return fallback;
+  }
+}
+export function createErrorBoundary(fallback, options = {}) {
+  const onError = options.onError ? (error) => options.onError(error, { timestamp: Date.now(), boundaryId: "ssr" }) : void 0;
+  return (render) => withErrorBoundary(render, fallback, onError);
+}
+export function generateErrorBoundaryCSS() {
+  return `
+/* STX Error Boundary Styles */
+.stx-error-boundary {
+  position: relative;
+}
+
+.stx-error-boundary[data-has-error="true"] .stx-error-boundary-content {
+  display: none;
+}
+
+.stx-error-boundary[data-has-error="true"] .stx-error-boundary-fallback {
+  display: block !important;
+}
+
+/* Default fallback styling (can be overridden) */
+.stx-error-boundary-fallback {
+  padding: 1rem;
+  border: 1px solid #ef4444;
+  border-radius: 0.5rem;
+  background-color: #fef2f2;
+  color: #991b1b;
+}
+
+.stx-error-boundary-fallback button {
+  margin-top: 0.5rem;
+  padding: 0.5rem 1rem;
+  border: 1px solid #ef4444;
+  border-radius: 0.25rem;
+  background-color: #ef4444;
+  color: white;
+  cursor: pointer;
+}
+
+.stx-error-boundary-fallback button:hover {
+  background-color: #dc2626;
+}
+
+/* Dark mode support */
+@media (prefers-color-scheme: dark) {
+  .stx-error-boundary-fallback {
+    background-color: #450a0a;
+    color: #fecaca;
+  }
+}
+`;
+}
+export function generateErrorBoundaryRuntime() {
+  return `
+// STX Error Boundary Runtime
+(function() {
+  if (typeof window === 'undefined') return;
+
+  window.STX = window.STX || {};
+  window.STX.errorBoundaries = window.STX.errorBoundaries || {};
+
+  // Create an error boundary programmatically
+  window.STX.createErrorBoundary = function(element, options) {
+    options = options || {};
+    const boundaryId = 'eb-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2);
+
+    let hasError = false;
+    let lastError = null;
+    let fallbackContent = options.fallback || '<p>Something went wrong</p>';
+
+    const contentWrapper = document.createElement('div');
+    contentWrapper.className = 'stx-error-boundary-content';
+
+    const fallbackWrapper = document.createElement('div');
+    fallbackWrapper.className = 'stx-error-boundary-fallback';
+    fallbackWrapper.style.display = 'none';
+    fallbackWrapper.innerHTML = fallbackContent;
+
+    // Move element's children to content wrapper
+    while (element.firstChild) {
+      contentWrapper.appendChild(element.firstChild);
+    }
+
+    element.appendChild(contentWrapper);
+    element.appendChild(fallbackWrapper);
+    element.classList.add('stx-error-boundary');
+    element.setAttribute('data-boundary-id', boundaryId);
+
+    function showFallback(error) {
+      hasError = true;
+      lastError = error;
+      element.setAttribute('data-has-error', 'true');
+      contentWrapper.style.display = 'none';
+      fallbackWrapper.style.display = '';
+      if (options.onError) options.onError(error);
+    }
+
+    function retry() {
+      hasError = false;
+      lastError = null;
+      element.setAttribute('data-has-error', 'false');
+      contentWrapper.style.display = '';
+      fallbackWrapper.style.display = 'none';
+      if (options.onRetry) options.onRetry();
+    }
+
+    window.STX.errorBoundaries[boundaryId] = {
+      hasError: function() { return hasError; },
+      getError: function() { return lastError; },
+      retry: retry,
+      showFallback: showFallback
+    };
+
+    return window.STX.errorBoundaries[boundaryId];
+  };
+
+  console.log('[stx] Error boundary runtime initialized');
+})();
+`;
+}

package/dist/error-handling.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error Handling Module
+ *
+ * This module has been refactored into smaller, more focused files.
+ * All exports are re-exported from the errors/ directory.
+ *
+ * @module error-handling
+ * @see ./errors/codes.ts - Error codes and localized messages
+ * @see ./errors/types.ts - Error classes and configuration
+ * @see ./errors/formatter.ts - Error formatting utilities
+ * @see ./errors/sanitizer.ts - Parameter sanitization
+ * @see ./errors/logger.ts - Error logging and recovery
+ */
+export * from './errors';

package/dist/error-handling.js

@@ -0,0 +1 @@
+export * from "./errors/index.js";

package/dist/errors/codes.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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
+ */
+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;
+/**
+ * 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: {
+    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];
+/**
+ * Get error code name from numeric code
+ */
+export declare function getErrorCodeName(code: number): string | undefined;

package/dist/errors/codes.js

@@ -0,0 +1,97 @@
+const defaultErrorMessages = {
+  1001: { message: "Unclosed directive: {{directive}}", help: "Make sure to close the directive with the appropriate end tag" },
+  1002: { message: "Unclosed expression at position {{position}}", help: "Check for missing closing braces }}" },
+  1003: { message: "Invalid directive syntax: {{directive}}", help: "Review the directive documentation for correct syntax" },
+  1004: { message: "Malformed expression: {{expression}}", help: "Check for syntax errors in your expression" },
+  1005: { message: "Unexpected token: {{token}}", help: "Remove or fix the unexpected token" },
+  1101: { message: "Undefined variable: {{variable}}", help: "Make sure the variable is defined in the template context" },
+  1102: { message: "Type error: {{details}}", help: "Check that you are using the correct types" },
+  1103: { message: "Evaluation error: {{details}}", help: "Review the expression for errors" },
+  1104: { message: "Infinite loop detected in {{location}}", help: "Check your loop conditions" },
+  1105: { message: "Circular reference detected: {{path}}", help: "Remove the circular dependency" },
+  1201: { message: "Unsafe expression blocked: {{expression}}", help: "This expression contains potentially dangerous code" },
+  1202: { message: "Path traversal attempt blocked: {{path}}", help: "Use only relative paths within allowed directories" },
+  1203: { message: "Potential XSS attempt blocked", help: "Sanitize user input before rendering" },
+  1204: { message: "Code injection attempt blocked: {{code}}", help: "Avoid executing dynamic code" },
+  1205: { message: "Prohibited DOM API usage: {{api}}", help: "Use STX.useRefs(), STX.useRef(), STX.el() and other STX helpers instead of direct DOM manipulation" },
+  1301: { message: "File not found: {{path}}", help: "Check that the file exists and the path is correct" },
+  1302: { message: "Error reading file: {{path}}", help: "Check file permissions and encoding" },
+  1303: { message: "Invalid file path: {{path}}", help: "Use a valid file path" },
+  1304: { message: "Permission denied: {{path}}", help: "Check file permissions" },
+  1401: { message: "Invalid configuration: {{details}}", help: "Review your stx.config.ts file" },
+  1402: { message: "Missing required configuration: {{key}}", help: "Add the required configuration option" },
+  1403: { message: "Deprecated configuration: {{key}}", help: "Update to the new configuration format" },
+  1501: { message: "Component not found: {{name}}", help: "Check that the component exists in your components directory" },
+  1502: { message: "Invalid props for component {{name}}: {{details}}", help: "Check the component prop requirements" },
+  1503: { message: "Error rendering component {{name}}: {{details}}", help: "Check the component template for errors" },
+  1601: { message: "Filter not found: {{filter}}", help: "Register the filter or check the filter name" },
+  1602: { message: "Invalid arguments for filter {{filter}}: {{details}}", help: "Check the filter documentation for correct arguments" },
+  1603: { message: "Expression evaluation timed out", help: "Simplify the expression or increase the timeout" }
+};
+let customErrorMessages = {}, currentLocale = "en";
+export function setErrorLocale(locale) {
+  currentLocale = locale;
+}
+export function getErrorLocale() {
+  return currentLocale;
+}
+export function registerErrorMessages(messages) {
+  customErrorMessages = { ...customErrorMessages, ...messages };
+}
+export function clearErrorMessages() {
+  customErrorMessages = {};
+}
+export function getErrorMessage(code, params = {}) {
+  const template = customErrorMessages[code] || defaultErrorMessages[code] || {
+    message: `Unknown error (code: ${code})`
+  };
+  let { message, help } = template;
+  for (const [key, value] of Object.entries(params)) {
+    const placeholder = `{{${key}}}`;
+    message = message.replace(new RegExp(placeholder, "g"), value);
+    if (help)
+      help = help.replace(new RegExp(placeholder, "g"), value);
+  }
+  return { message, help };
+}
+export function formatLocalizedError(code, params = {}) {
+  const { message, help } = getErrorMessage(code, params);
+  return help ? `${message}
+  Help: ${help}` : message;
+}
+export 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
+};
+export function getErrorCodeName(code) {
+  for (const [name, value] of Object.entries(ErrorCodes))
+    if (value === code)
+      return name;
+  return;
+}

package/dist/errors/formatter.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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
+ */
+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>;