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

package/dist/teleport.js

@@ -0,0 +1,109 @@
+let teleportCounter = 0;
+function generateTeleportId() {
+  return `stx-teleport-${++teleportCounter}`;
+}
+function parseTeleportArgs(args) {
+  const parts = args.split(",").map((p) => p.trim()), target = parts[0].replace(/['"]/g, "");
+  let disabled;
+  for (let i = 1;i < parts.length; i++) {
+    const disabledMatch = parts[i].match(/disabled:\s*(.+)/);
+    if (disabledMatch)
+      disabled = disabledMatch[1].trim();
+  }
+  return { target, disabled };
+}
+function generateTeleportScript(id, target) {
+  return `
+    <script>
+    (function() {
+      const source = document.getElementById('${id}');
+      if (!source) return;
+
+      // Get the content template up-front so we can hold a reference for the
+      // retry path. (template.content is moved out by cloneNode below.)
+      const template = source.querySelector('template');
+      if (!template) return;
+
+      function mount(targetEl) {
+        // Clone the template content and wrap it for tracking.
+        const content = template.content.cloneNode(true);
+        const wrapper = document.createElement('div');
+        wrapper.setAttribute('data-teleport-from', '${id}');
+        wrapper.appendChild(content);
+
+        targetEl.appendChild(wrapper);
+
+        // Remove the source placeholder
+        source.remove();
+
+        wrapper.dispatchEvent(new CustomEvent('teleport:mounted', {
+          bubbles: true,
+          detail: { sourceId: '${id}', target: '${target}' }
+        }));
+      }
+
+      // The teleport script runs inline at the position it's emitted. If the
+      // target is declared later in the same render pass (e.g. by a layout
+      // shell whose onMount creates the portal root), the first lookup
+      // misses. Pre-fix (stacksjs/stx#1728) the script bailed with a warning
+      // and never tried again. Now retry once via requestAnimationFrame so
+      // targets that land in the same paint cycle still work. A second
+      // miss is still a warning \u2014 we don't loop forever.
+      const firstEl = document.querySelector('${target}');
+      if (firstEl) { mount(firstEl); return; }
+
+      requestAnimationFrame(function() {
+        const retryEl = document.querySelector('${target}');
+        if (retryEl) { mount(retryEl); return; }
+        console.warn('[stx] Teleport target not found: ${target}');
+      });
+    })();
+    </script>
+  `;
+}
+export function processTeleportDirectives(template, context, _filePath) {
+  teleportCounter = 0;
+  const teleportRegex = /@teleport\s*\(([^)]+)\)\s*([\s\S]*?)@endteleport/g;
+  return template.replace(teleportRegex, (fullMatch, args, body) => {
+    const id = generateTeleportId(), { target, disabled } = parseTeleportArgs(args), content = body.trim();
+    if (disabled)
+      try {
+        let isDisabled = !1;
+        if (disabled === "true")
+          isDisabled = !0;
+        else if (disabled === "false")
+          isDisabled = !1;
+        else if (disabled in context)
+          isDisabled = Boolean(context[disabled]);
+        if (isDisabled)
+          return `<div class="stx-teleport-inline" data-teleport-disabled>${content}</div>`;
+      } catch {}
+    const script = generateTeleportScript(id, target);
+    return `
+      <div id="${id}" class="stx-teleport-source" style="display: none;">
+        <template>${content}</template>
+      </div>
+      ${script}
+    `;
+  });
+}
+export function ensureTeleportTargets() {
+  return `
+    <script>
+    (function() {
+      // Common teleport targets
+      const targets = ['#stx-modals', '#stx-tooltips', '#stx-notifications'];
+
+      targets.forEach(selector => {
+        const id = selector.slice(1); // Remove #
+        if (!document.getElementById(id)) {
+          const el = document.createElement('div');
+          el.id = id;
+          el.setAttribute('data-teleport-container', '');
+          document.body.appendChild(el);
+        }
+      });
+    })();
+    </script>
+  `;
+}

package/dist/template-compiler.d.ts

@@ -0,0 +1,33 @@
+import { type PlaceholderMap } from './placeholder';
+/**
+ * Compile a single .stx template file.
+ *
+ * Runs the full processDirectives pipeline in build mode ('compile'),
+ * producing pre-rendered HTML with placeholder tokens for dynamic content.
+ *
+ * @param filePath - Absolute path to the .stx file
+ * @param route - The URL route this page serves (e.g. '/jobs')
+ * @param options - Additional compilation options
+ */
+export declare function compileTemplate(filePath: string, route: string, options?: {
+    componentsDir?: string
+    partialsDir?: string
+    layoutsDir?: string
+    debug?: boolean
+  }): Promise<CompiledTemplate>;
+/**
+ * A pre-compiled template ready for serve-time hydration.
+ */
+export declare interface CompiledTemplate {
+  route: string
+  sourceFile: string
+  html: string
+  fragment: string
+  placeholders: PlaceholderMap
+  hasServerScripts: boolean
+  serverScriptContent: string[]
+  dependencies: string[]
+  contentHash: string
+  status?: number
+  streamTemplates?: Record<string, string>
+}

package/dist/template-compiler.js

@@ -0,0 +1,68 @@
+import path from "node:path";
+import { processDirectives } from "./process.js";
+import { defaultConfig, loadStxConfig } from "./config.js";
+import { extractVariables } from "./variable-extractor.js";
+import { createPlaceholder, resetPlaceholders, getPlaceholderRegistry } from "./placeholder.js";
+import { stripDocumentWrapper } from "./app-shell.js";
+import { createHash } from "node:crypto";
+import { Bun } from "./bun-shim.js";
+import { collectBlockDeclarations } from "./stx-virtual-ts.js";
+import { extractPageResponseStatus } from "./page-response.js";
+function createRecordingContext(baseContext = {}) {
+  const accessedKeys = new Set;
+  return { context: new Proxy(baseContext, {
+    get(target, prop) {
+      if (prop in target)
+        return target[prop];
+      if (typeof prop === "string" && !prop.startsWith("__"))
+        accessedKeys.add(prop);
+      return;
+    },
+    has(target, prop) {
+      if (prop in target)
+        return !0;
+      if (typeof prop === "string" && !prop.startsWith("__"))
+        accessedKeys.add(prop);
+      return !1;
+    }
+  }), accessedKeys };
+}
+export async function compileTemplate(filePath, route, options = {}) {
+  const absolutePath = path.resolve(filePath), content = await Bun.file(absolutePath).text(), contentHash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+  resetPlaceholders();
+  let projectConfig = {};
+  try {
+    projectConfig = await loadStxConfig();
+  } catch {}
+  const serverScriptContent = [], scriptRegex = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+  let scriptMatch;
+  while ((scriptMatch = scriptRegex.exec(content)) !== null) {
+    const attrs = scriptMatch[1];
+    if (/\bserver\b/.test(attrs))
+      serverScriptContent.push(scriptMatch[2]);
+  }
+  const serverDeclared = new Set(serverScriptContent.flatMap((code) => collectBlockDeclarations(code))), { context } = createRecordingContext({
+    __filename: absolutePath,
+    __dirname: path.dirname(absolutePath),
+    __stx_serverDeclared: serverDeclared
+  }), dependencies = new Set, opts = {
+    ...defaultConfig,
+    ...projectConfig,
+    ...options,
+    buildMode: "compile",
+    strict: !1
+  }, html = await processDirectives(content, context, absolutePath, opts, dependencies), fragment = stripDocumentWrapper(html), placeholders = getPlaceholderRegistry();
+  return {
+    route,
+    sourceFile: filePath,
+    html,
+    fragment,
+    placeholders,
+    hasServerScripts: serverScriptContent.length > 0,
+    serverScriptContent,
+    dependencies: Array.from(dependencies),
+    contentHash,
+    status: extractPageResponseStatus(content),
+    streamTemplates: context.__streamTemplates
+  };
+}

package/dist/template-hydrator.d.ts

@@ -0,0 +1,28 @@
+import type { CompiledTemplate } from './template-compiler';
+/**
+ * Hydrate a pre-compiled template with request-time data.
+ *
+ * This is the serve-time counterpart to compileTemplate(). It takes a
+ * compiled template (with placeholder tokens) and a request context,
+ * executes server scripts, evaluates expressions, and returns final HTML.
+ *
+ * @param compiled - The pre-compiled template from build time
+ * @param requestContext - Request-time context (route params, session, etc.)
+ * @returns Final HTML ready to send to the browser
+ */
+export declare function hydrateTemplate(compiled: CompiledTemplate, requestContext?: Record<string, any>): Promise<string>;
+/**
+ * Like `hydrateTemplate`, but also returns any streaming-SSR boundaries the
+ * page's `<script server>` exported (`streamBoundaries`) — re-run per request,
+ * so they're fresh. The production server uses this to stream a page's shell
+ * first, then its boundaries (#1746). `boundaries` is `undefined` for a normal
+ * page. (The low-level `streamBoundaries` form; the `@stream` sugar's captured
+ * templates aren't serialized into the compiled template, so use the function
+ * form in production.)
+ */
+export declare function hydrateTemplateStream(compiled: CompiledTemplate, requestContext?: Record<string, any>): Promise<{ html: string, boundaries?: { id: string, render: () => Promise<string> }[], redirect?: string, cookies?: string[], status?: number, headers?: Record<string, string> }>;
+/**
+ * Hydrate a fragment (for SPA navigation).
+ * Same as hydrateTemplate but returns the fragment portion.
+ */
+export declare function hydrateFragment(compiled: CompiledTemplate, requestContext?: Record<string, any>): Promise<string>;

package/dist/template-hydrator.js

@@ -0,0 +1,95 @@
+import { extractVariables } from "./variable-extractor.js";
+import { evaluateExpression, escapeHtmlValue } from "./expressions.js";
+import { replacePlaceholders, hasPlaceholders } from "./placeholder.js";
+import { runPageAction } from "./page-action.js";
+import { readResponseHeaders, readResponseStatus } from "./page-response.js";
+export async function hydrateTemplate(compiled, requestContext = {}) {
+  return (await runHydration(compiled, requestContext)).html;
+}
+export async function hydrateTemplateStream(compiled, requestContext = {}) {
+  const { html, context, redirect, cookies } = await runHydration(compiled, requestContext), status = readResponseStatus(context), headers = readResponseHeaders(context);
+  if (redirect)
+    return { html, redirect, cookies, status, headers };
+  const { extractStreamBoundaries } = await import("./streaming.js");
+  let boundaries = extractStreamBoundaries(context);
+  const templates = compiled.streamTemplates;
+  if (templates && Object.keys(templates).length > 0) {
+    const { processDirectives } = await import("./process.js"), { defaultConfig } = await import("./config.js"), dataFns = context.streamBoundaries || {}, fragmentConfig = { ...defaultConfig, autoShell: !1 }, tplBoundaries = Object.keys(templates).map((id) => ({
+      id,
+      render: async () => {
+        const data = typeof dataFns[id] === "function" ? await dataFns[id]() : void 0;
+        return processDirectives(templates[id], { ...context, $boundary: data }, compiled.sourceFile, fragmentConfig, new Set);
+      }
+    })), tplIds = new Set(tplBoundaries.map((b) => b.id));
+    boundaries = [...(boundaries || []).filter((b) => !tplIds.has(b.id)), ...tplBoundaries];
+  }
+  return { html, boundaries: boundaries && boundaries.length > 0 ? boundaries : void 0, cookies, status, headers };
+}
+async function runHydration(compiled, requestContext) {
+  const context = {
+    __filename: compiled.sourceFile,
+    __dirname: compiled.sourceFile.replace(/[/\\][^/\\]+$/, ""),
+    ...requestContext
+  };
+  if (!compiled.hasServerScripts && !hasPlaceholders(compiled.html))
+    return { html: compiled.html, context };
+  for (const scriptContent of compiled.serverScriptContent)
+    try {
+      await extractVariables(scriptContent, context, compiled.sourceFile);
+    } catch (error) {
+      console.warn(`[stx] Server script error in ${compiled.sourceFile}:`, error);
+    }
+  const action = await runPageAction(context, {
+    request: requestContext.request,
+    method: requestContext.method,
+    params: requestContext.params ?? {},
+    cookies: requestContext.cookies ?? {}
+  });
+  if (action.redirect)
+    return { html: compiled.html, context, redirect: action.redirect, cookies: action.cookies };
+  if (!hasPlaceholders(compiled.html))
+    return { html: compiled.html, context, cookies: action.cookies };
+  const values = new Map;
+  for (const [token, info] of Object.entries(compiled.placeholders))
+    if (info.expression)
+      try {
+        const value = evaluateExpression(info.expression, context);
+        if (info.type === "raw")
+          values.set(token, value !== void 0 && value !== null ? String(value) : "");
+        else
+          values.set(token, value !== void 0 && value !== null ? escapeHtmlValue(String(value)) : "");
+      } catch {
+        values.set(token, "");
+      }
+  return { html: replacePlaceholders(compiled.html, values), context, cookies: action.cookies };
+}
+export async function hydrateFragment(compiled, requestContext = {}) {
+  if (!compiled.hasServerScripts && !hasPlaceholders(compiled.fragment))
+    return compiled.fragment;
+  const context = {
+    __filename: compiled.sourceFile,
+    __dirname: compiled.sourceFile.replace(/[/\\][^/\\]+$/, ""),
+    ...requestContext
+  };
+  for (const scriptContent of compiled.serverScriptContent)
+    try {
+      await extractVariables(scriptContent, context, compiled.sourceFile);
+    } catch (error) {
+      console.warn(`[stx] Server script error in ${compiled.sourceFile}:`, error);
+    }
+  if (!hasPlaceholders(compiled.fragment))
+    return compiled.fragment;
+  const values = new Map;
+  for (const [token, info] of Object.entries(compiled.placeholders))
+    if (info.expression)
+      try {
+        const value = evaluateExpression(info.expression, context);
+        if (info.type === "raw")
+          values.set(token, value !== void 0 && value !== null ? String(value) : "");
+        else
+          values.set(token, value !== void 0 && value !== null ? escapeHtmlValue(String(value)) : "");
+      } catch {
+        values.set(token, "");
+      }
+  return replacePlaceholders(compiled.fragment, values);
+}

package/dist/template-tag-balance.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Dev-mode template tag-balance check (stacksjs/stx#1769).
+ *
+ * A single dropped closing tag (e.g. a missing `</div>`) is silently
+ * auto-closed by the HTML parser at EOF, re-parenting every following sibling
+ * INSIDE the unclosed element. Those siblings then inherit the element's
+ * `x-show`/`display:none` state and render blank — with zero diagnostics at any
+ * layer (the server 200s, hydration succeeds, no console output). The failure
+ * is purely structural and only visible by eye.
+ *
+ * This does a coarse, void- and optional-close-aware open/close COUNT per tag
+ * name and reports any mismatch. It intentionally does not attempt a full HTML
+ * parse: the goal is a cheap, high-signal dev heads-up, not a validator.
+ */
+export interface TagBalanceIssue {
+    /** Tag name as written (case preserved, so `<Icon>`/`</Icon>` match). */
+    tag: string;
+    opened: number;
+    closed: number;
+    /** 1-based line of the first opening tag of this name (best-effort). */
+    firstOpenLine: number;
+}
+/**
+ * Return the set of tag names whose opening/closing counts don't balance.
+ * Pure and side-effect free.
+ */
+export declare function findUnbalancedTags(template: string): TagBalanceIssue[];
+/**
+ * Dev-mode warning: log any tag-balance issues for a template. Best-effort — a
+ * diagnostic must never throw and break the build.
+ */
+export declare function warnUnbalancedTags(template: string, filePath: string): void;

package/dist/template-tag-balance.js

@@ -0,0 +1,93 @@
+const VOID_TAGS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]), OPTIONAL_CLOSE_TAGS = new Set([
+  "html",
+  "head",
+  "body",
+  "p",
+  "li",
+  "dt",
+  "dd",
+  "rt",
+  "rp",
+  "option",
+  "optgroup",
+  "thead",
+  "tbody",
+  "tfoot",
+  "tr",
+  "td",
+  "th",
+  "colgroup",
+  "caption"
+]);
+function blankKeepingLines(s) {
+  return s.replace(/[^\n]/g, " ");
+}
+export function findUnbalancedTags(template) {
+  const stripped = template.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, blankKeepingLines).replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, blankKeepingLines).replace(/<!--[\s\S]*?-->/g, blankKeepingLines).replace(/\{\{\{[\s\S]*?\}\}\}/g, blankKeepingLines).replace(/\{\{[\s\S]*?\}\}/g, blankKeepingLines).replace(/\{!![\s\S]*?!!\}/g, blankKeepingLines), opens = new Map, closes = new Map, tagRe = /<(\/?)([A-Za-z][\w-]*)\b(?:[^>"']|"[^"]*"|'[^']*')*?(\/?)>/g;
+  let m;
+  while ((m = tagRe.exec(stripped)) !== null) {
+    const isClose = m[1] === "/", name = m[2], selfClose = m[3] === "/";
+    if (VOID_TAGS.has(name.toLowerCase()))
+      continue;
+    if (selfClose)
+      continue;
+    if (isClose)
+      closes.set(name, (closes.get(name) ?? 0) + 1);
+    else {
+      const existing = opens.get(name);
+      if (existing)
+        existing.count++;
+      else {
+        const line = stripped.slice(0, m.index).split(`
+`).length;
+        opens.set(name, { count: 1, firstLine: line });
+      }
+    }
+  }
+  const issues = [];
+  for (const name of new Set([...opens.keys(), ...closes.keys()])) {
+    if (OPTIONAL_CLOSE_TAGS.has(name.toLowerCase()))
+      continue;
+    const opened = opens.get(name)?.count ?? 0, closed = closes.get(name) ?? 0;
+    if (opened !== closed)
+      issues.push({ tag: name, opened, closed, firstOpenLine: opens.get(name)?.firstLine ?? 0 });
+  }
+  return issues;
+}
+const warnedKeys = new Set;
+export function warnUnbalancedTags(template, filePath) {
+  let issues;
+  try {
+    issues = findUnbalancedTags(template);
+  } catch {
+    return;
+  }
+  if (issues.length === 0)
+    return;
+  const dedupeKey = `${filePath}:${template.length}`;
+  if (warnedKeys.has(dedupeKey))
+    return;
+  warnedKeys.add(dedupeKey);
+  const label = filePath ? filePath.split(/[/\\]/).pop() || filePath : "template";
+  for (const { tag, opened, closed, firstOpenLine } of issues)
+    if (opened > closed) {
+      const where = firstOpenLine ? ` (first opened at line ${firstOpenLine})` : "";
+      console.warn(`[stx] ${label}: <${tag}> ${opened} opened, ${closed} closed \u2014 an unclosed <${tag}>${where} may swallow the content that follows it.`);
+    } else
+      console.warn(`[stx] ${label}: <${tag}> ${opened} opened, ${closed} closed \u2014 ${closed - opened} stray </${tag}>.`);
+}