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

package/dist/async-components.d.ts

@@ -0,0 +1,123 @@
+/**
+ * STX Async Components
+ *
+ * Provides lazy loading capabilities for components with loading and error states.
+ *
+ * @module async-components
+ *
+ * @example
+ * ```html
+ * @async(component: 'HeavyChart', timeout: 5000)
+ *   <div class="loading">Loading chart...</div>
+ * @error
+ *   <div class="error">Failed to load chart</div>
+ * @endasync
+ * ```
+ *
+ * Or inline:
+ * ```html
+ * <AsyncComponent
+ *   :component="() => import('./HeavyChart.stx')"
+ *   :timeout="5000"
+ * >
+ *   <template #loading>Loading...</template>
+ *   <template #error="{ error }">Error: {{ error.message }}</template>
+ * </AsyncComponent>
+ * ```
+ */
+export interface AsyncComponentOptions {
+    /** Component path or name to load */
+    component: string;
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Delay before showing loading state in ms (default: 200) */
+    delay?: number;
+    /** Whether to suspend parent Suspense boundary */
+    suspensible?: boolean;
+    /** Custom loading component */
+    loadingComponent?: string;
+    /** Custom error component */
+    errorComponent?: string;
+    /** Retry attempts on failure (default: 0) */
+    retries?: number;
+    /** Props to pass to the loaded component */
+    props?: Record<string, unknown>;
+}
+export interface AsyncComponentState {
+    /** Current loading state */
+    status: 'pending' | 'loading' | 'resolved' | 'rejected';
+    /** The loaded component content */
+    component: string | null;
+    /** Error if loading failed */
+    error: Error | null;
+    /** Number of retry attempts made */
+    attempts: number;
+}
+/**
+ * Process @async directives in templates.
+ *
+ * Syntax:
+ *   @async(component: 'ComponentName', timeout: 5000)
+ *     <loading content>
+ *   @error
+ *     <error content>
+ *   @endasync
+ */
+export declare function processAsyncDirectives(template: string, _context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Define an async component for programmatic use.
+ *
+ * @example
+ * ```typescript
+ * const AsyncChart = defineAsyncComponent({
+ *   loader: () => import('./Chart.stx'),
+ *   loadingComponent: LoadingSpinner,
+ *   errorComponent: ErrorDisplay,
+ *   delay: 200,
+ *   timeout: 3000
+ * })
+ * ```
+ */
+export interface DefineAsyncComponentOptions {
+    /** Function that returns a Promise resolving to the component */
+    loader: () => Promise<{
+        default: string;
+    } | string>;
+    /** Component to show while loading */
+    loadingComponent?: string;
+    /** Component to show on error */
+    errorComponent?: string;
+    /** Delay before showing loading component (ms) */
+    delay?: number;
+    /** Timeout before showing error (ms) */
+    timeout?: number;
+    /** Whether to suspend parent Suspense */
+    suspensible?: boolean;
+    /** Called when loading starts */
+    onLoadStart?: () => void;
+    /** Called when component is loaded */
+    onLoadEnd?: () => void;
+    /** Called on error */
+    onError?: (error: Error, retry: () => void, fail: () => void, attempts: number) => void;
+}
+/**
+ * Define an async component.
+ */
+export declare function defineAsyncComponent(options: DefineAsyncComponentOptions | (() => Promise<{
+    default: string;
+} | string>)): AsyncComponentDefinition;
+export interface AsyncComponentDefinition extends DefineAsyncComponentOptions {
+    __asyncComponent: true;
+}
+/**
+ * Check if a value is an async component definition.
+ */
+export declare function isAsyncComponent(value: unknown): value is AsyncComponentDefinition;
+/**
+ * Generate CSS for async component styling.
+ */
+export declare function generateAsyncComponentCSS(): string;
+/**
+ * Generate client-side runtime for async components.
+ */
+export declare function generateAsyncComponentRuntime(): string;

package/dist/async-components.js

@@ -0,0 +1,428 @@
+let asyncIdCounter = 0;
+function generateAsyncId() {
+  return `async-${++asyncIdCounter}-${Date.now().toString(36)}`;
+}
+export function processAsyncDirectives(template, _context = {}, _filePath) {
+  const asyncWithErrorRegex = /@async\s*\(([^)]*)\)\s*([\s\S]*?)@error\s*([\s\S]*?)@endasync/gi, asyncWithoutErrorRegex = /@async\s*\(([^)]*)\)\s*([\s\S]*?)@endasync/gi;
+  let result = template;
+  result = result.replace(asyncWithErrorRegex, (_match, optionsStr, loadingContent, errorContent) => {
+    const asyncId = generateAsyncId(), options = parseAsyncOptions(optionsStr);
+    return generateAsyncComponentHtml(asyncId, options, loadingContent.trim(), errorContent.trim());
+  });
+  result = result.replace(asyncWithoutErrorRegex, (_match, optionsStr, loadingContent) => {
+    const asyncId = generateAsyncId(), options = parseAsyncOptions(optionsStr);
+    return generateAsyncComponentHtml(asyncId, options, loadingContent.trim(), '<div class="stx-async-error">Failed to load component</div>');
+  });
+  return result;
+}
+function parseAsyncOptions(optionsStr) {
+  const options = {
+    component: "",
+    timeout: 30000,
+    delay: 200,
+    suspensible: !0,
+    retries: 0
+  }, keyValueRegex = /(\w+)\s*:\s*(?:'([^']*)'|"([^"]*)"|(\d+)|(\w+))/g;
+  let match;
+  while ((match = keyValueRegex.exec(optionsStr)) !== null) {
+    const key = match[1], strValue = match[2] || match[3], numValue = match[4], boolOrId = match[5];
+    switch (key) {
+      case "component":
+        options.component = strValue || boolOrId || "";
+        break;
+      case "timeout":
+        options.timeout = numValue ? parseInt(numValue, 10) : 30000;
+        break;
+      case "delay":
+        options.delay = numValue ? parseInt(numValue, 10) : 200;
+        break;
+      case "suspensible":
+        options.suspensible = boolOrId === "true";
+        break;
+      case "retries":
+        options.retries = numValue ? parseInt(numValue, 10) : 0;
+        break;
+      case "loadingComponent":
+        options.loadingComponent = strValue || boolOrId;
+        break;
+      case "errorComponent":
+        options.errorComponent = strValue || boolOrId;
+        break;
+    }
+  }
+  return options;
+}
+function generateAsyncComponentHtml(asyncId, options, loadingContent, errorContent) {
+  const { component, timeout, delay, suspensible, retries } = options;
+  return `
+<div class="stx-async-component" data-async-id="${asyncId}" data-component="${component}" data-status="pending">
+  <div class="stx-async-loading" data-async-loading="${asyncId}">
+    ${loadingContent}
+  </div>
+  <div class="stx-async-content" data-async-content="${asyncId}" style="display: none;">
+  </div>
+  <div class="stx-async-error" data-async-error="${asyncId}" style="display: none;">
+    ${errorContent}
+  </div>
+</div>
+<script>
+(function() {
+  const asyncId = '${asyncId}';
+  const componentPath = '${component}';
+  const timeout = ${timeout};
+  const delay = ${delay};
+  const suspensible = ${suspensible};
+  const maxRetries = ${retries};
+
+  const container = document.querySelector('[data-async-id="' + asyncId + '"]');
+  const loadingEl = document.querySelector('[data-async-loading="' + asyncId + '"]');
+  const contentEl = document.querySelector('[data-async-content="' + asyncId + '"]');
+  const errorEl = document.querySelector('[data-async-error="' + asyncId + '"]');
+
+  if (!container || !loadingEl || !contentEl || !errorEl) return;
+
+  let attempts = 0;
+  let delayTimer = null;
+  let timeoutTimer = null;
+  let resolved = false;
+  let aborted = false;
+
+  // AbortController + container detachment guards (stacksjs/stx#1720). Without
+  // these, an in-flight fetch from a previous page would write innerHTML on
+  // a detached container after the user SPA-navigated away, or \u2014 for
+  // components removed via :if/parent toggle \u2014 would log a "rejected" state
+  // on a node that no longer exists. The router dispatches stx:navigate
+  // when a navigation starts; we treat that as a teardown signal. The
+  // isConnected check covers non-router unmounts (:if false, parent remove).
+  const controller = new AbortController();
+  function teardown() {
+    if (aborted) return;
+    aborted = true;
+    controller.abort();
+    clearTimeout(delayTimer);
+    clearTimeout(timeoutTimer);
+    window.removeEventListener('stx:navigate', teardown);
+  }
+  window.addEventListener('stx:navigate', teardown);
+
+  // Update state
+  function setState(status) {
+    container.setAttribute('data-status', status);
+    loadingEl.style.display = status === 'loading' ? '' : 'none';
+    contentEl.style.display = status === 'resolved' ? '' : 'none';
+    errorEl.style.display = status === 'rejected' ? '' : 'none';
+  }
+
+  // Show loading after delay
+  function showLoading() {
+    if (!resolved) {
+      setState('loading');
+    }
+  }
+
+  // Load component
+  async function loadComponent() {
+    attempts++;
+
+    // Start delay timer for loading state
+    delayTimer = setTimeout(showLoading, delay);
+
+    // Start timeout timer
+    timeoutTimer = setTimeout(function() {
+      if (!resolved) {
+        handleError(new Error('Component load timeout after ' + timeout + 'ms'));
+      }
+    }, timeout);
+
+    try {
+      // Notify Suspense boundary if suspensible
+      if (suspensible && window.STX && window.STX.suspense) {
+        window.STX.suspense.register(asyncId);
+      }
+
+      // Fetch the component with the AbortController signal so a teardown
+      // (SPA navigation, component unmount) cancels the in-flight request.
+      const response = await fetch('/_stx/component/' + encodeURIComponent(componentPath), {
+        signal: controller.signal
+      });
+
+      if (!response.ok) {
+        throw new Error('Failed to load component: ' + response.statusText);
+      }
+
+      const html = await response.text();
+
+      // Clear timers
+      clearTimeout(delayTimer);
+      clearTimeout(timeoutTimer);
+
+      // Belt-and-suspenders: if the container was removed between the fetch
+      // starting and now (e.g. :if flipped to false, or a non-router parent
+      // mutation), bail before writing innerHTML on a detached node.
+      if (aborted || !container.isConnected) return;
+
+      resolved = true;
+      contentEl.innerHTML = html;
+      setState('resolved');
+
+      // Execute any scripts in the loaded component
+      contentEl.querySelectorAll('script').forEach(function(script) {
+        const newScript = document.createElement('script');
+        if (script.src) {
+          newScript.src = script.src;
+        }
+else {
+          newScript.textContent = script.textContent;
+        }
+        script.parentNode.replaceChild(newScript, script);
+      });
+
+      // Process signals/bindings on the loaded content ({{ }}, :attr, @event, etc.)
+      if (window.stx && window.stx._latestSetup) {
+        window.dispatchEvent(new Event('stx:load'));
+      }
+
+      // Notify Suspense boundary
+      if (suspensible && window.STX && window.STX.suspense) {
+        window.STX.suspense.resolve(asyncId);
+      }
+
+      // Dispatch loaded event
+      container.dispatchEvent(new CustomEvent('stx:async:loaded', {
+        detail: { asyncId: asyncId, component: componentPath },
+        bubbles: true
+      }));
+
+      // Load succeeded \u2014 drop the navigate-teardown listener so it doesn't
+      // accumulate per async component across an app's lifetime.
+      window.removeEventListener('stx:navigate', teardown);
+    }
+catch (error) {
+      // AbortError fires when teardown() runs during an in-flight fetch.
+      // That's not a load failure \u2014 the component is being unmounted, so
+      // don't render the rejected state, don't retry, don't dispatch error.
+      if (aborted || (error && error.name === 'AbortError')) return;
+      handleError(error);
+    }
+  }
+
+  // Handle errors
+  function handleError(error) {
+    clearTimeout(delayTimer);
+    clearTimeout(timeoutTimer);
+
+    // The container may have been removed (e.g., a non-router :if toggle)
+    // between the failure and now. No DOM left to write the error state to.
+    if (aborted || !container.isConnected) return;
+
+    if (attempts < maxRetries) {
+      // Retry
+      console.warn('[stx:async:' + asyncId + '] Retrying... (' + attempts + '/' + maxRetries + ')');
+      setTimeout(loadComponent, 1000 * attempts); // Exponential backoff
+      return;
+    }
+
+    resolved = true;
+    setState('rejected');
+
+    // Update error content with error message
+    const errorMsgEl = errorEl.querySelector('[data-error-message]');
+    if (errorMsgEl) {
+      errorMsgEl.textContent = error.message;
+    }
+
+    // Notify Suspense boundary
+    if (suspensible && window.STX && window.STX.suspense) {
+      window.STX.suspense.reject(asyncId, error);
+    }
+
+    // Dispatch error event
+    container.dispatchEvent(new CustomEvent('stx:async:error', {
+      detail: { asyncId: asyncId, component: componentPath, error: error },
+      bubbles: true
+    }));
+
+    console.error('[stx:async:' + asyncId + ']', error);
+
+    // Final error state \u2014 no more retries. Drop the navigate listener so it
+    // doesn't outlive the (failed) component.
+    window.removeEventListener('stx:navigate', teardown);
+  }
+
+  // Retry function
+  function retry() {
+    resolved = false;
+    attempts = 0;
+    setState('pending');
+    loadComponent();
+  }
+
+  // Expose retry function
+  window['$stxAsyncRetry_' + asyncId.replace(/-/g, '_')] = retry;
+
+  // Make $retry available within the error content
+  errorEl.querySelectorAll('[onclick*="$retry"]').forEach(function(el) {
+    const onclick = el.getAttribute('onclick');
+    if (onclick) {
+      el.setAttribute('onclick', onclick.replace(/\\$retry\\(\\)/g, "window['$stxAsyncRetry_" + asyncId.replace(/-/g, '_') + "']()"));
+    }
+  });
+
+  // Expose API
+  window.STX = window.STX || {};
+  window.STX.asyncComponents = window.STX.asyncComponents || {};
+  window.STX.asyncComponents[asyncId] = {
+    getStatus: function() { return container.getAttribute('data-status'); },
+    retry: retry,
+    getAttempts: function() { return attempts; }
+  };
+
+  // Start loading
+  loadComponent();
+})();
+</script>
+`;
+}
+export function defineAsyncComponent(options) {
+  return {
+    __asyncComponent: !0,
+    ...typeof options === "function" ? { loader: options } : options
+  };
+}
+export function isAsyncComponent(value) {
+  return typeof value === "object" && value !== null && "__asyncComponent" in value && value.__asyncComponent === !0;
+}
+export function generateAsyncComponentCSS() {
+  return `
+/* STX Async Component Styles */
+.stx-async-component {
+  position: relative;
+}
+
+.stx-async-loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100px;
+}
+
+.stx-async-error {
+  padding: 1rem;
+  border: 1px solid #ef4444;
+  border-radius: 0.5rem;
+  background-color: #fef2f2;
+  color: #991b1b;
+}
+
+.stx-async-error 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-async-error button:hover {
+  background-color: #dc2626;
+}
+
+/* Loading spinner animation */
+@keyframes stx-async-spin {
+  to { transform: rotate(360deg); }
+}
+
+.stx-async-spinner {
+  width: 24px;
+  height: 24px;
+  border: 2px solid #e5e7eb;
+  border-top-color: #3b82f6;
+  border-radius: 50%;
+  animation: stx-async-spin 0.8s linear infinite;
+}
+
+/* Skeleton loading */
+.stx-async-skeleton {
+  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+  background-size: 200% 100%;
+  animation: stx-async-shimmer 1.5s infinite;
+  border-radius: 0.25rem;
+}
+
+@keyframes stx-async-shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+
+/* Dark mode */
+@media (prefers-color-scheme: dark) {
+  .stx-async-error {
+    background-color: #450a0a;
+    color: #fecaca;
+  }
+
+  .stx-async-skeleton {
+    background: linear-gradient(90deg, #374151 25%, #4b5563 50%, #374151 75%);
+    background-size: 200% 100%;
+  }
+}
+`;
+}
+export function generateAsyncComponentRuntime() {
+  return `
+// STX Async Component Runtime
+(function() {
+  if (typeof window === 'undefined') return;
+
+  window.STX = window.STX || {};
+  window.STX.asyncComponents = window.STX.asyncComponents || {};
+
+  // Load a component dynamically
+  window.STX.loadComponent = async function(componentPath, targetSelector, options) {
+    options = options || {};
+    const target = document.querySelector(targetSelector);
+    if (!target) {
+      throw new Error('Target element not found: ' + targetSelector);
+    }
+
+    const loadingHtml = options.loading || '<div class="stx-async-spinner"></div>';
+    target.innerHTML = loadingHtml;
+
+    try {
+      const response = await fetch('/_stx/component/' + encodeURIComponent(componentPath));
+      if (!response.ok) {
+        throw new Error('Failed to load: ' + response.statusText);
+      }
+
+      const html = await response.text();
+      target.innerHTML = html;
+
+      // Execute scripts
+      target.querySelectorAll('script').forEach(function(script) {
+        const newScript = document.createElement('script');
+        if (script.src) {
+          newScript.src = script.src;
+        }
+else {
+          newScript.textContent = script.textContent;
+        }
+        script.parentNode.replaceChild(newScript, script);
+      });
+
+      if (options.onLoad) options.onLoad();
+      return true;
+    }
+catch (error) {
+      if (options.error) {
+        target.innerHTML = options.error;
+      }
+      if (options.onError) options.onError(error);
+      throw error;
+    }
+  };
+
+  console.log('[stx] Async component runtime initialized');
+})();
+`;
+}

package/dist/auth.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Module for handling authentication and authorization in templates
+ */
+/**
+ * Safely evaluates an auth expression within the given context
+ * Similar to evaluateExpression but specialized for auth conditionals
+ * Uses the safe evaluator to prevent code injection
+ *
+ * @param {string} expression - The expression to evaluate
+ * @param {Record<string, any>} context - The context object containing variables
+ * @returns The evaluated result
+ */
+export declare function evaluateAuthExpression(expression: string, context: Record<string, any>): any;

package/dist/auth.js

@@ -0,0 +1,12 @@
+import { createSafeFunction, isExpressionSafe, safeEvaluate } from "./safe-evaluator.js";
+export function evaluateAuthExpression(expression, context) {
+  try {
+    const trimmedExpr = expression.trim();
+    if (isExpressionSafe(trimmedExpr))
+      return createSafeFunction(trimmedExpr, Object.keys(context))(...Object.values(context));
+    else
+      return safeEvaluate(trimmedExpr, context);
+  } catch {
+    return !1;
+  }
+}

package/dist/broadcasting.d.ts

@@ -0,0 +1,77 @@
+import { Broadcast, BroadcastServer, type ServerConfig } from 'ts-broadcasting';
+import type { BroadcastingConfig } from './types/config-types';
+export type {
+  ServerConfig,
+} from 'ts-broadcasting';
+/**
+ * Get the active BroadcastServer instance (or null if not started).
+ */
+export declare function getBroadcastServer(): BroadcastServer | null;
+/**
+ * Start the broadcasting WebSocket server.
+ *
+ * Called automatically by the stx dev-server when `broadcasting.enabled`
+ * is true in stx.config.ts. You normally don't need to call this yourself.
+ */
+export declare function startBroadcasting(config: BroadcastingConfig): Promise<BroadcastServer>;
+/**
+ * Stop the broadcasting server and clean up resources.
+ */
+export declare function stopBroadcasting(): Promise<void>;
+/**
+ * Load and execute a `routes/channels.ts` file, wiring up every
+ * channel definition to the running broadcasting server.
+ *
+ * Called automatically by the stx dev-server after `startBroadcasting()`.
+ */
+export declare function loadChannels(channelsPath: string): Promise<number>;
+/**
+ * Broadcast an event to a channel (or multiple channels).
+ *
+ * @example
+ * ```ts
+ * broadcast('chat', 'message.sent', { text: 'Hello!' })
+ * broadcast(['chat', 'admin'], 'alert', { level: 'warn' })
+ * ```
+ */
+export declare function broadcast<T = unknown>(channels: string | string[], event: string, data: T): void;
+/**
+ * Broadcast to a specific user's private channel.
+ *
+ * @example
+ * ```ts
+ * toUser(42, 'notification', { title: 'You have mail' })
+ * ```
+ */
+export declare function toUser<T = unknown>(userId: string | number, event: string, data: T): void;
+/**
+ * Broadcast to multiple users.
+ */
+export declare function toUsers<T = unknown>(userIds: Array<string | number>, event: string, data: T): void;
+/**
+ * Broadcast to a private channel.
+ */
+export declare function broadcastPrivate<T = unknown>(channelName: string, event: string, data: T): void;
+/**
+ * Broadcast to a presence channel.
+ */
+export declare function broadcastPresence<T = unknown>(channelName: string, event: string, data: T): void;
+// ── Types ──────────────────────────────────────────────────────
+export declare interface ChannelDefinition<T = unknown> {
+  event?: string
+  interval?: number
+  data?: () => T | Promise<T>
+  authorize?: (socket: any, params: Record<string, string>) => boolean | object | Promise<boolean | object>
+}
+export declare interface ChannelRegistrar {
+  channel: <T = unknown>(name: string, definition: ChannelDefinition<T>) => void
+}
+/**
+ * Register channel authorization (ad-hoc, outside routes/channels.ts).
+ */
+export { channel } from 'ts-broadcasting';
+// ── Re-exports for advanced usage ──────────────────────────────
+export {
+  Broadcast,
+  BroadcastServer,
+} from 'ts-broadcasting';