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

package/dist/style-scoping.d.ts

@@ -0,0 +1,42 @@
+/**
+ * SFC Style Scoping
+ *
+ * Processes `<style scoped>` blocks in `.stx` single-file components.
+ * Scopes CSS selectors to the component using a deterministic hash attribute,
+ * preventing style leakage between components.
+ *
+ * Uses the CSS scoping utilities from `web-components/css-scoping.ts`.
+ *
+ * @module style-scoping
+ */
+export interface ScopedStyleResult {
+    /** The modified HTML with scope attributes added to root elements and scoped style tags */
+    html: string;
+    /** Whether any scoped styles were found and processed */
+    hasScoped: boolean;
+}
+/**
+ * Keep one copy of each rendered scoped stylesheet.
+ *
+ * Reusing the same component more than once produces the same deterministic
+ * scope attribute and CSS. A single stylesheet covers every instance, just as
+ * it does in a compiled Vue SFC, so repeating it only increases the document
+ * payload and CSS parse work.
+ */
+export declare function dedupeScopedStyles(html: string): string;
+/**
+ * Process all `<style scoped>` blocks in a template.
+ *
+ * For each `<style scoped>` block:
+ * 1. Generates a deterministic hash from the file path
+ * 2. Prefixes all CSS selectors with `[data-v-{hash}]`
+ * 3. Adds `data-v-{hash}` attribute to all top-level HTML elements
+ * 4. Replaces the `<style scoped>` tag with scoped CSS
+ *
+ * Non-scoped `<style>` tags pass through unchanged.
+ *
+ * @param template - The HTML template string
+ * @param filePath - Source file path (used for deterministic hash generation)
+ * @returns Processed template with scoped styles
+ */
+export declare function processScopedStyles(template: string, filePath: string): ScopedStyleResult;

package/dist/style-scoping.js

@@ -0,0 +1,82 @@
+import { maskAtElementPosition, matchScriptElement, matchStyleElement } from "./html-masking.js";
+import { generateComponentId, scopeCss } from "./web-components/css-scoping.js";
+const SCOPED_STYLE_ATTR = String.raw`(?<![\w-])scoped(?![\w-])`, STYLE_OPEN_TAG = /<style\s+([^>]*)>/gi, STYLE_TAG_WITH_ATTRS = /<style\s+([^>]*)>([\s\S]*?)<\/style>/gi, SCOPED_ATTR_IN_TAG = new RegExp(SCOPED_STYLE_ATTR, "i"), SCOPED_ATTR_EVERYWHERE = new RegExp(SCOPED_STYLE_ATTR, "gi");
+function hasScopedStyleTag(template) {
+  STYLE_OPEN_TAG.lastIndex = 0;
+  let tag = STYLE_OPEN_TAG.exec(template);
+  while (tag !== null) {
+    if (SCOPED_ATTR_IN_TAG.test(tag[1]))
+      return !0;
+    tag = STYLE_OPEN_TAG.exec(template);
+  }
+  return !1;
+}
+export function dedupeScopedStyles(html) {
+  const seen = new Set;
+  return html.replace(/<style\b[^>]*\bdata-stx-scoped(?:=(?:"[^"]*"|'[^']*'|[^\s>]+))?[^>]*>[\s\S]*?<\/style>\s*/gi, (styleBlock) => {
+    const key = styleBlock.trim();
+    if (seen.has(key))
+      return "";
+    seen.add(key);
+    return styleBlock;
+  });
+}
+export function processScopedStyles(template, filePath) {
+  if (!hasScopedStyleTag(template))
+    return { html: template, hasScoped: !1 };
+  const componentId = generateComponentId(filePath), scopeAttr = `data-v-${componentId}`;
+  let output = template, hasScoped = !1;
+  STYLE_TAG_WITH_ATTRS.lastIndex = 0;
+  output = output.replace(STYLE_TAG_WITH_ATTRS, (match, attrs, cssContent) => {
+    if (!SCOPED_ATTR_IN_TAG.test(attrs))
+      return match;
+    hasScoped = !0;
+    const scopedCss = scopeCssWithAttribute(cssContent, scopeAttr), cleanAttrs = attrs.replace(SCOPED_ATTR_EVERYWHERE, "").trim(), attrStr = cleanAttrs ? ` ${cleanAttrs}` : "";
+    return `<style data-stx-scoped="${componentId}"${attrStr}>${scopedCss}</style>`;
+  });
+  if (!hasScoped)
+    return { html: template, hasScoped: !1 };
+  output = addScopeAttribute(output, scopeAttr);
+  return { html: output, hasScoped: !0 };
+}
+function scopeCssWithAttribute(css, scopeAttr) {
+  return scopeCss(css, "__SCOPE_PLACEHOLDER__", { preserveHost: !1 }).replace(/\.(__SCOPE_PLACEHOLDER__) /g, `[${scopeAttr}] `).replace(/\.(__SCOPE_PLACEHOLDER__)/g, `[${scopeAttr}]`);
+}
+const MASK_TOKEN = (index) => `\x00stx-scope-mask-${index}\x00`, MASK_TOKEN_PATTERN = /\u0000stx-scope-mask-(\d+)\u0000/g;
+function addScopeAttribute(html, scopeAttr) {
+  const masked = maskAtElementPosition(html, (source, index) => {
+    const script = matchScriptElement(source, index);
+    return script > index ? script : matchStyleElement(source, index);
+  }, (_token, index) => MASK_TOKEN(index)), injected = injectScopeAttribute(masked.output, scopeAttr);
+  MASK_TOKEN_PATTERN.lastIndex = 0;
+  return injected.replace(MASK_TOKEN_PATTERN, (_match, index) => masked.tokens[Number(index)]);
+}
+function injectScopeAttribute(html, scopeAttr) {
+  const skipTags = new Set([
+    "script",
+    "style",
+    "template",
+    "html",
+    "head",
+    "body",
+    "meta",
+    "link",
+    "title",
+    "base",
+    "!doctype",
+    "!DOCTYPE"
+  ]);
+  return html.replace(/<([a-zA-Z][a-zA-Z0-9-]*)(\s[^>]*)?\/?>/g, (match, tagName, attrs) => {
+    if (skipTags.has(tagName.toLowerCase()))
+      return match;
+    if (match.includes(scopeAttr))
+      return match;
+    if (tagName.toLowerCase() === "style" || tagName.toLowerCase() === "script")
+      return match;
+    if (attrs)
+      return match.replace(`<${tagName}${attrs}`, `<${tagName} ${scopeAttr}${attrs}`);
+    if (match.endsWith("/>"))
+      return `<${tagName} ${scopeAttr} />`;
+    return `<${tagName} ${scopeAttr}>`;
+  });
+}

package/dist/suspense.d.ts

@@ -0,0 +1,98 @@
+/**
+ * STX Suspense
+ *
+ * Coordinates async loading across component trees, showing a fallback
+ * until all async children are resolved.
+ *
+ * @module suspense
+ *
+ * @example
+ * ```html
+ * @suspense
+ *   <UserProfile :id="userId" />
+ *   <UserActivity :id="userId" />
+ *   <UserStats :id="userId" />
+ * @fallback
+ *   <PageSkeleton />
+ * @endsuspense
+ * ```
+ */
+export interface SuspenseOptions {
+    /** Custom ID for tracking */
+    id?: string;
+    /** Timeout before showing error (ms) */
+    timeout?: number;
+    /** Callback when all children resolve */
+    onResolve?: () => void;
+    /** Callback when any child rejects */
+    onError?: (error: Error) => void;
+    /** Callback when loading starts */
+    onPending?: () => void;
+}
+export interface SuspenseState {
+    /** Current state */
+    status: 'pending' | 'resolved' | 'rejected';
+    /** Pending async children */
+    pending: Set<string>;
+    /** Resolved async children */
+    resolved: Set<string>;
+    /** First error encountered */
+    error: Error | null;
+}
+export interface SuspenseBoundary {
+    /** Unique boundary ID */
+    id: string;
+    /** Current state */
+    state: SuspenseState;
+    /** Register an async child */
+    register: (childId: string) => void;
+    /** Mark a child as resolved */
+    resolve: (childId: string) => void;
+    /** Mark a child as rejected */
+    reject: (childId: string, error: Error) => void;
+    /** Reset the boundary */
+    reset: () => void;
+}
+/**
+ * Process @suspense directives in templates.
+ *
+ * Syntax:
+ *   @suspense
+ *     <async content>
+ *   @fallback
+ *     <loading fallback>
+ *   @endsuspense
+ *
+ * With options:
+ *   @suspense(timeout: 10000)
+ */
+export declare function processSuspenseDirectives(template: string, _context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Server-side suspense boundary for SSR streaming.
+ */
+export interface SSRSuspenseBoundary {
+    id: string;
+    fallback: string;
+    content: Promise<string>;
+}
+/**
+ * Create an SSR suspense boundary.
+ * Returns the fallback immediately, then streams the content when ready.
+ */
+export declare function createSSRSuspense(id: string, contentPromise: Promise<string>, fallback: string): SSRSuspenseBoundary;
+/**
+ * Render SSR suspense boundaries for streaming.
+ * Returns initial HTML with fallbacks, plus a script to replace them when content loads.
+ */
+export declare function renderSSRSuspense(boundaries: SSRSuspenseBoundary[]): Promise<{
+    initial: string;
+    streaming: AsyncGenerator<string>;
+}>;
+/**
+ * Generate CSS for suspense styling.
+ */
+export declare function generateSuspenseCSS(): string;
+/**
+ * Generate client-side runtime for suspense.
+ */
+export declare function generateSuspenseRuntime(): string;

package/dist/suspense.js

@@ -0,0 +1,398 @@
+let suspenseIdCounter = 0;
+function generateSuspenseId() {
+  return `suspense-${++suspenseIdCounter}-${Date.now().toString(36)}`;
+}
+export function processSuspenseDirectives(template, _context = {}, _filePath) {
+  const suspenseRegex = /@suspense(?:\s*\(([^)]*)\))?\s*([\s\S]*?)@fallback\s*([\s\S]*?)@endsuspense/gi;
+  return template.replace(suspenseRegex, (_match, optionsStr, content, fallback) => {
+    const suspenseId = generateSuspenseId(), options = parseSuspenseOptions(optionsStr || "");
+    return generateSuspenseHtml(suspenseId, content.trim(), fallback.trim(), options);
+  });
+}
+function parseSuspenseOptions(optionsStr) {
+  const options = {}, 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];
+    switch (key) {
+      case "id":
+        options.id = strValue;
+        break;
+      case "timeout":
+        options.timeout = numValue ? parseInt(numValue, 10) : void 0;
+        break;
+    }
+  }
+  return options;
+}
+function generateSuspenseHtml(suspenseId, content, fallback, options) {
+  const timeout = options.timeout || 30000, customId = options.id || suspenseId;
+  return `
+<div class="stx-suspense" data-suspense-id="${suspenseId}" data-custom-id="${customId}" data-status="pending">
+  <div class="stx-suspense-fallback" data-suspense-fallback="${suspenseId}">
+    ${fallback}
+  </div>
+  <div class="stx-suspense-content" data-suspense-content="${suspenseId}" style="display: none;">
+    ${content}
+  </div>
+</div>
+<script>
+(function() {
+  const suspenseId = '${suspenseId}';
+  const customId = '${customId}';
+  const timeout = ${timeout};
+
+  const container = document.querySelector('[data-suspense-id="' + suspenseId + '"]');
+  const fallbackEl = document.querySelector('[data-suspense-fallback="' + suspenseId + '"]');
+  const contentEl = document.querySelector('[data-suspense-content="' + suspenseId + '"]');
+
+  if (!container || !fallbackEl || !contentEl) return;
+
+  // State
+  const pending = new Set();
+  const resolved = new Set();
+  let status = 'pending';
+  let error = null;
+  let timeoutTimer = null;
+
+  // Update UI based on state
+  function updateUI() {
+    container.setAttribute('data-status', status);
+
+    if (status === 'resolved') {
+      fallbackEl.style.display = 'none';
+      contentEl.style.display = '';
+    }
+else if (status === 'rejected') {
+      fallbackEl.style.display = 'none';
+      contentEl.style.display = '';
+      // Show error in content area if needed
+    }
+else {
+      fallbackEl.style.display = '';
+      contentEl.style.display = 'none';
+    }
+  }
+
+  // Check if all children are resolved
+  function checkResolved() {
+    if (pending.size === 0 && resolved.size > 0) {
+      clearTimeout(timeoutTimer);
+      status = 'resolved';
+      updateUI();
+
+      container.dispatchEvent(new CustomEvent('stx:suspense:resolved', {
+        detail: { suspenseId: suspenseId, customId: customId },
+        bubbles: true
+      }));
+    }
+  }
+
+  // Register an async child
+  function register(childId) {
+    if (status === 'resolved') {
+      // Reset if we get a new child after resolution
+      status = 'pending';
+      updateUI();
+    }
+    pending.add(childId);
+
+    // Start timeout on first registration
+    if (pending.size === 1 && !timeoutTimer) {
+      timeoutTimer = setTimeout(function() {
+        if (status === 'pending') {
+          error = new Error('Suspense timeout after ' + timeout + 'ms');
+          status = 'rejected';
+          updateUI();
+
+          container.dispatchEvent(new CustomEvent('stx:suspense:timeout', {
+            detail: { suspenseId: suspenseId, customId: customId, pending: Array.from(pending) },
+            bubbles: true
+          }));
+        }
+      }, timeout);
+    }
+  }
+
+  // Resolve a child
+  function resolve(childId) {
+    pending.delete(childId);
+    resolved.add(childId);
+    checkResolved();
+  }
+
+  // Reject a child
+  function reject(childId, err) {
+    pending.delete(childId);
+    error = err;
+    status = 'rejected';
+    clearTimeout(timeoutTimer);
+    updateUI();
+
+    container.dispatchEvent(new CustomEvent('stx:suspense:error', {
+      detail: { suspenseId: suspenseId, customId: customId, error: err, childId: childId },
+      bubbles: true
+    }));
+  }
+
+  // Reset the boundary
+  function reset() {
+    pending.clear();
+    resolved.clear();
+    status = 'pending';
+    error = null;
+    clearTimeout(timeoutTimer);
+    timeoutTimer = null;
+    updateUI();
+  }
+
+  // Expose API globally for async components to use
+  window.STX = window.STX || {};
+  window.STX.suspense = window.STX.suspense || {
+    boundaries: {},
+    // Find the nearest suspense boundary for a child
+    findBoundary: function(element) {
+      const boundary = element.closest('[data-suspense-id]');
+      if (boundary) {
+        return boundary.getAttribute('data-suspense-id');
+      }
+      return null;
+    },
+    register: function(childId, boundaryId) {
+      if (!boundaryId) {
+        // Find nearest boundary
+        const asyncEl = document.querySelector('[data-async-id="' + childId + '"]');
+        if (asyncEl) {
+          boundaryId = this.findBoundary(asyncEl);
+        }
+      }
+      if (boundaryId && this.boundaries[boundaryId]) {
+        this.boundaries[boundaryId].register(childId);
+      }
+    },
+    resolve: function(childId, boundaryId) {
+      if (!boundaryId) {
+        const asyncEl = document.querySelector('[data-async-id="' + childId + '"]');
+        if (asyncEl) {
+          boundaryId = this.findBoundary(asyncEl);
+        }
+      }
+      if (boundaryId && this.boundaries[boundaryId]) {
+        this.boundaries[boundaryId].resolve(childId);
+      }
+    },
+    reject: function(childId, error, boundaryId) {
+      if (!boundaryId) {
+        const asyncEl = document.querySelector('[data-async-id="' + childId + '"]');
+        if (asyncEl) {
+          boundaryId = this.findBoundary(asyncEl);
+        }
+      }
+      if (boundaryId && this.boundaries[boundaryId]) {
+        this.boundaries[boundaryId].reject(childId, error);
+      }
+    }
+  };
+
+  // Register this boundary
+  window.STX.suspense.boundaries[suspenseId] = {
+    id: suspenseId,
+    customId: customId,
+    getStatus: function() { return status; },
+    getPending: function() { return Array.from(pending); },
+    getResolved: function() { return Array.from(resolved); },
+    getError: function() { return error; },
+    register: register,
+    resolve: resolve,
+    reject: reject,
+    reset: reset
+  };
+
+  // Initial state - if no async children register within a tick, show content
+  setTimeout(function() {
+    if (pending.size === 0 && resolved.size === 0) {
+      status = 'resolved';
+      updateUI();
+    }
+  }, 0);
+})();
+</script>
+`;
+}
+export function createSSRSuspense(id, contentPromise, fallback) {
+  return {
+    id,
+    fallback,
+    content: contentPromise
+  };
+}
+export async function renderSSRSuspense(boundaries) {
+  const initial = boundaries.map((b) => `
+<div id="stx-ssr-suspense-${b.id}" class="stx-ssr-suspense">
+  ${b.fallback}
+</div>
+`).join(`
+`);
+  async function* streamContent() {
+    for (const boundary of boundaries)
+      try {
+        const content = await boundary.content;
+        yield `
+<script>
+(function() {
+  const el = document.getElementById('stx-ssr-suspense-${boundary.id}');
+  if (el) {
+    el.innerHTML = ${JSON.stringify(content)};
+    el.classList.add('stx-ssr-suspense-resolved');
+  }
+})();
+</script>
+`;
+      } catch (error) {
+        yield `
+<script>
+(function() {
+  const el = document.getElementById('stx-ssr-suspense-${boundary.id}');
+  if (el) {
+    el.classList.add('stx-ssr-suspense-error');
+    console.error('SSR Suspense error for ${boundary.id}:', ${JSON.stringify(String(error))});
+  }
+})();
+</script>
+`;
+      }
+  }
+  return {
+    initial,
+    streaming: streamContent()
+  };
+}
+export function generateSuspenseCSS() {
+  return `
+/* STX Suspense Styles */
+.stx-suspense {
+  position: relative;
+}
+
+.stx-suspense[data-status="pending"] .stx-suspense-fallback {
+  display: block;
+}
+
+.stx-suspense[data-status="pending"] .stx-suspense-content {
+  display: none;
+}
+
+.stx-suspense[data-status="resolved"] .stx-suspense-fallback {
+  display: none;
+}
+
+.stx-suspense[data-status="resolved"] .stx-suspense-content {
+  display: block;
+}
+
+/* SSR Suspense */
+.stx-ssr-suspense {
+  transition: opacity 0.3s ease;
+}
+
+.stx-ssr-suspense-resolved {
+  animation: stx-suspense-fade-in 0.3s ease;
+}
+
+@keyframes stx-suspense-fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+/* Skeleton fallback helper */
+.stx-suspense-skeleton {
+  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+  background-size: 200% 100%;
+  animation: stx-suspense-shimmer 1.5s infinite;
+  border-radius: 0.25rem;
+}
+
+@keyframes stx-suspense-shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+
+/* Dark mode */
+@media (prefers-color-scheme: dark) {
+  .stx-suspense-skeleton {
+    background: linear-gradient(90deg, #374151 25%, #4b5563 50%, #374151 75%);
+    background-size: 200% 100%;
+  }
+}
+`;
+}
+export function generateSuspenseRuntime() {
+  return `
+// STX Suspense Runtime
+(function() {
+  if (typeof window === 'undefined') return;
+
+  window.STX = window.STX || {};
+
+  // Suspense boundary management is set up per-boundary in the HTML
+  // This just provides additional utilities
+
+  window.STX.suspense = window.STX.suspense || {
+    boundaries: {},
+    findBoundary: function(element) {
+      const boundary = element.closest('[data-suspense-id]');
+      return boundary ? boundary.getAttribute('data-suspense-id') : null;
+    },
+    register: function(childId, boundaryId) {},
+    resolve: function(childId, boundaryId) {},
+    reject: function(childId, error, boundaryId) {}
+  };
+
+  // Wait for all suspense boundaries to resolve
+  window.STX.suspense.waitForAll = function() {
+    return new Promise(function(resolve, reject) {
+      const boundaries = Object.values(window.STX.suspense.boundaries);
+      if (boundaries.length === 0) {
+        resolve();
+        return;
+      }
+
+      let resolved = 0;
+      let rejected = false;
+
+      boundaries.forEach(function(boundary) {
+        if (boundary.getStatus() === 'resolved') {
+          resolved++;
+          if (resolved === boundaries.length) resolve();
+        }
+else if (boundary.getStatus() === 'rejected') {
+          if (!rejected) {
+            rejected = true;
+            reject(boundary.getError());
+          }
+        }
+else {
+          // Listen for resolution
+          const container = document.querySelector('[data-suspense-id="' + boundary.id + '"]');
+          if (container) {
+            container.addEventListener('stx:suspense:resolved', function() {
+              resolved++;
+              if (resolved === boundaries.length && !rejected) resolve();
+            }, { once: true });
+
+            container.addEventListener('stx:suspense:error', function(e) {
+              if (!rejected) {
+                rejected = true;
+                reject(e.detail.error);
+              }
+            }, { once: true });
+          }
+        }
+      });
+    });
+  };
+
+  console.log('[stx] Suspense runtime initialized');
+})();
+`;
+}

package/dist/teleport.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Teleport Directive
+ *
+ * Moves content to a different location in the DOM.
+ * Useful for modals, tooltips, notifications that need to escape
+ * their parent's stacking context.
+ *
+ * Usage:
+ * @teleport('#modals')
+ *   <div class="modal">Modal content</div>
+ * @endteleport
+ *
+ * With disabled state:
+ * @teleport('#modals', disabled: isInline)
+ *   <div class="modal">Modal content</div>
+ * @endteleport
+ *
+ * Multiple targets:
+ * @teleport('body')  - Appends to body
+ * @teleport('#app')  - Appends to #app element
+ * @teleport('.modals-container')  - Appends to first matching element
+ */
+/**
+ * Process @teleport directives in template
+ */
+export declare function processTeleportDirectives(template: string, context: Record<string, unknown>, _filePath: string): string;
+/**
+ * Ensure teleport targets exist in the document
+ * Call this to create common teleport targets if they don't exist
+ */
+export declare function ensureTeleportTargets(): string;