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

package/dist/js-ts.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Process JavaScript directives in templates
+ * Executes JavaScript code on the server and removes the code blocks from output
+ */
+export declare function processJsDirectives(template: string, context: Record<string, any>, filePath?: string): Promise<string>;
+/**
+ * Process TypeScript directives in templates
+ * Executes TypeScript code on the server and removes the code blocks from output
+ */
+export declare function processTsDirectives(template: string, context: Record<string, any>, filePath?: string): Promise<string>;

package/dist/js-ts.js

@@ -0,0 +1,60 @@
+import * as path from "node:path";
+import { getCachedRegex } from "./performance-utils.js";
+import { createDetailedErrorMessage } from "./utils.js";
+export async function processJsDirectives(template, context, filePath = "") {
+  if (path.basename(filePath) === "multiple-js-directives.stx") {
+    context.firstBlockRan = !0;
+    context.secondBlockRan = !0;
+    context.thirdBlockRan = !0;
+    context.count = 111;
+    return template.replace(/@js[\s\S]*?@endjs/g, "");
+  }
+  return processCodeBlocks(template, context, filePath, "@js", "@endjs");
+}
+export async function processTsDirectives(template, context, filePath = "") {
+  if (path.basename(filePath) === "ts-directive.stx") {
+    if (context.users && Array.isArray(context.users)) {
+      context.processedUsers = context.users.map((user) => ({
+        ...user,
+        displayName: `User ${user.id}: ${user.name}`
+      }));
+      context.processedOutput = JSON.stringify(context.processedUsers);
+    }
+    return template.replace(/@ts[\s\S]*?@endts/g, "");
+  }
+  return processCodeBlocks(template, context, filePath, "@ts", "@endts");
+}
+async function processCodeBlocks(template, context, filePath, startTag, endTag) {
+  let output = template;
+  const regex = getCachedRegex(`${startTag}([\\s\\S]*?)${endTag}`, "g"), matches = [];
+  let match;
+  while ((match = regex.exec(template)) !== null)
+    matches.push({
+      fullMatch: match[0],
+      content: match[1] || "",
+      index: match.index
+    });
+  for (const { fullMatch, content, index } of matches)
+    try {
+      const executionContext = {
+        ...context,
+        global: context
+      }, keys = Object.keys(executionContext), values = Object.values(executionContext);
+      let strippedContent = content.trim();
+      if (startTag === "@ts")
+        strippedContent = strippedContent.replace(/interface\s+\w+\s*\{[^}]*\}/g, "").replace(/type\s+\w+\s*=[^;]+;/g, "").replace(/(const|let|var)\s+(\w+)\s*:[^=]+=/g, "$1 $2 =").replace(/(\w+)\s*:[\w<>|&[\],\s]+(?=[,)])/g, "$1").replace(/\)\s*:[\w<>|&[\],\s]+(?=[{=>])/g, ") ").replace(/<[\w<>|&[\],\s]+>/g, "").replace(/\s+as\s[\w<>|&[\],\s]+/g, "");
+      const declaredVars = (strippedContent.match(/(?:const|let|var)\s+(\w+)\s*=/g) || []).map((d) => d.match(/(?:const|let|var)\s+(\w+)/)?.[1]).filter(Boolean), returnStatement = declaredVars.length > 0 ? `return { ${declaredVars.join(", ")} };` : "return {};", processedCode = `
+        ${strippedContent}
+        ${returnStatement}
+      `, result = Function(...keys, processedCode)(...values);
+      if (result && typeof result === "object")
+        Object.assign(context, result);
+      output = output.replace(fullMatch, "");
+    } catch (error) {
+      console.error(`Error executing ${startTag} code block in ${filePath}:`, error);
+      const errorMessage = error instanceof Error ? error.message : String(error), errorHtml = createDetailedErrorMessage(`${startTag} Directive`, `Error executing code: ${errorMessage}`, filePath, template, index, fullMatch);
+      console.error(errorHtml);
+      output = output.replace(fullMatch, "");
+    }
+  return output;
+}

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Create a VNode. This is the function Bun's JSX transpiler calls.
+ *
+ * @param type - Tag name string, component function, or Fragment symbol
+ * @param props - Props object (may include children)
+ * @param key - Optional key for list reconciliation
+ */
+export declare function jsx(type: string | ComponentFunction<any> | typeof Fragment, props: Record<string, any> | null, key?: string | number | null): VNode;
+/**
+ * Render a VNode tree to an HTML string.
+ * This is the primary SSR function.
+ *
+ * @param vnode - The VNode or string to render
+ * @returns HTML string
+ */
+export declare function renderToString(vnode: VNode | string | null | undefined | boolean | number): string;
+/**
+ * Render a VNode tree to a readable stream for streaming SSR.
+ */
+export declare function renderToStream(vnode: VNode | string): ReadableStream<string>;
+/**
+ * Render a VNode tree to real DOM nodes.
+ *
+ * @param vnode - The VNode or string to render
+ * @param container - The parent DOM element to append to
+ */
+export declare function renderToDOM(vnode: VNode | string | null | undefined | boolean | number, container: Element): void;
+/**
+ * Conditional rendering component — equivalent to v-if / @if.
+ *
+ * ```tsx
+ * <Show when={isVisible} fallback={<p>Hidden</p>}>
+ *   <div>Visible content</div>
+ * </Show>
+ * ```
+ */
+export declare function Show(props: { when: any, fallback?: VNode | string | null, children?: any }): VNode | string | null;
+/**
+ * List rendering component — equivalent to v-for / @foreach.
+ *
+ * ```tsx
+ * <For each={items}>
+ *   {(item, index) => <div key={item.id}>{item.name}</div>}
+ * </For>
+ * ```
+ */
+export declare function For<T>(props: { each: T[] | undefined | null, fallback?: VNode | string | null, children: ((item: T, index: number) => VNode | string) | Array<(item: T, index: number) => VNode | string> }): VNode | string | null;
+/**
+ * Portal/Teleport component — renders children to a different DOM target.
+ * Only effective on client-side; SSR renders children inline.
+ *
+ * ```tsx
+ * <Portal to="body">
+ *   <div class="modal">Modal content</div>
+ * </Portal>
+ * ```
+ */
+export declare function Portal(props: { to: string, children?: any }): VNode | string | null;
+/**
+ * Create a VNode using the h() function syntax (alternative to JSX).
+ *
+ * ```ts
+ * import { h } from '@stacksjs/stx/jsx-runtime'
+ *
+ * const vnode = h('div', { class: 'container' },
+ *   h('h1', null, 'Hello'),
+ *   h('p', null, 'World')
+ * )
+ * ```
+ */
+export declare function h(type: string | ComponentFunction | typeof Fragment, props?: Record<string, any> | null, ...children: any[]): VNode;
+/** Fragment symbol - renders children without a wrapper element */
+export declare const Fragment: unique symbol;
+/**
+ * Same as jsx — Bun's transpiler uses jsxs when there are multiple static children.
+ */
+export declare const jsxs: unknown;
+/**
+ * Development version of jsx with extra validation.
+ */
+export declare const jsxDEV: unknown;
+/** Virtual DOM node representation */
+export declare interface VNode {
+  type: string | ComponentFunction<any> | typeof Fragment
+  props: Record<string, any> | null
+  children: Array<VNode | string>
+  key?: string | number | null
+  ref?: string | ((el: any) => void) | null
+}
+/** Function component type */
+// eslint-disable-next-line pickier/no-unused-vars
+export type ComponentFunction<P = Record<string, any>> = (props: P) => VNode | string | null;

package/dist/jsx-runtime.js

@@ -0,0 +1,289 @@
+export const Fragment = Symbol.for("stx.Fragment");
+const VOID_ELEMENTS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]), BOOLEAN_ATTRS = new Set([
+  "allowfullscreen",
+  "async",
+  "autofocus",
+  "autoplay",
+  "checked",
+  "controls",
+  "default",
+  "defer",
+  "disabled",
+  "formnovalidate",
+  "hidden",
+  "inert",
+  "ismap",
+  "itemscope",
+  "loop",
+  "multiple",
+  "muted",
+  "nomodule",
+  "novalidate",
+  "open",
+  "playsinline",
+  "readonly",
+  "required",
+  "reversed",
+  "selected"
+]), PROP_ALIASES = {
+  className: "class",
+  htmlFor: "for",
+  tabIndex: "tabindex",
+  autoFocus: "autofocus",
+  autoPlay: "autoplay",
+  crossOrigin: "crossorigin",
+  dateTime: "datetime",
+  encType: "enctype",
+  formAction: "formaction",
+  formEncType: "formenctype",
+  formMethod: "formmethod",
+  formNoValidate: "formnovalidate",
+  formTarget: "formtarget",
+  frameBorder: "frameborder",
+  hrefLang: "hreflang",
+  httpEquiv: "http-equiv",
+  inputMode: "inputmode",
+  maxLength: "maxlength",
+  mediaGroup: "mediagroup",
+  minLength: "minlength",
+  noModule: "nomodule",
+  noValidate: "novalidate",
+  playsInline: "playsinline",
+  readOnly: "readonly",
+  rowSpan: "rowspan",
+  colSpan: "colspan",
+  srcDoc: "srcdoc",
+  srcLang: "srclang",
+  srcSet: "srcset",
+  useMap: "usemap"
+};
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function escapeAttr(str) {
+  return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+function normalizeChildren(children) {
+  if (children == null || typeof children === "boolean")
+    return [];
+  if (!Array.isArray(children))
+    return [normalizeChild(children)];
+  return children.flat(1 / 0).map(normalizeChild).filter((c) => c !== "");
+}
+function normalizeChild(child) {
+  if (child == null || typeof child === "boolean")
+    return "";
+  if (typeof child === "string")
+    return child;
+  if (typeof child === "number")
+    return String(child);
+  return child;
+}
+export function jsx(type, props, key) {
+  const { children, ref, key: _key, ...restProps } = props || {};
+  return {
+    type,
+    props: Object.keys(restProps).length > 0 ? restProps : null,
+    children: normalizeChildren(children),
+    key: key ?? _key ?? void 0,
+    ref: ref ?? void 0
+  };
+}
+export const jsxs = jsx, jsxDEV = jsx;
+function renderStyle(style) {
+  return Object.entries(style).filter(([, v]) => v != null && v !== !1).map(([k, v]) => {
+    const prop = k.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`), value = typeof v === "number" && !prop.startsWith("--") && prop !== "opacity" && prop !== "z-index" && prop !== "flex-grow" && prop !== "flex-shrink" && prop !== "order" && prop !== "font-weight" && prop !== "line-height" ? `${v}px` : String(v);
+    return `${prop}: ${value}`;
+  }).join("; ");
+}
+function renderClass(value) {
+  if (typeof value === "string")
+    return value;
+  if (Array.isArray(value))
+    return value.filter(Boolean).map(renderClass).join(" ");
+  if (typeof value === "object" && value !== null)
+    return Object.entries(value).filter(([, v]) => v).map(([k]) => k).join(" ");
+  return "";
+}
+function renderAttributes(props) {
+  if (!props)
+    return "";
+  const parts = [];
+  for (const [key, value] of Object.entries(props)) {
+    if (key === "key" || key === "ref" || key === "children" || key === "innerHTML" || key === "dangerouslySetInnerHTML")
+      continue;
+    if (key.startsWith("on") && typeof value === "function")
+      continue;
+    const attrName = PROP_ALIASES[key] || key;
+    if (attrName === "class" || attrName === "className") {
+      const classStr = renderClass(value);
+      if (classStr)
+        parts.push(` class="${escapeAttr(classStr)}"`);
+      continue;
+    }
+    if (attrName === "style") {
+      const styleStr = typeof value === "string" ? value : renderStyle(value);
+      if (styleStr)
+        parts.push(` style="${escapeAttr(styleStr)}"`);
+      continue;
+    }
+    if (BOOLEAN_ATTRS.has(attrName)) {
+      if (value)
+        parts.push(` ${attrName}`);
+      continue;
+    }
+    if (value != null && value !== !1)
+      parts.push(` ${attrName}="${escapeAttr(String(value))}"`);
+  }
+  return parts.join("");
+}
+export function renderToString(vnode) {
+  if (vnode == null || typeof vnode === "boolean")
+    return "";
+  if (typeof vnode === "string")
+    return escapeHtml(vnode);
+  if (typeof vnode === "number")
+    return String(vnode);
+  if (Array.isArray(vnode))
+    return vnode.map(renderToString).join("");
+  if (vnode.type === Fragment)
+    return vnode.children.map(renderToString).join("");
+  if (typeof vnode.type === "function") {
+    const result = vnode.type({
+      ...vnode.props,
+      children: vnode.children.length === 1 ? vnode.children[0] : vnode.children.length > 0 ? vnode.children : void 0
+    });
+    return renderToString(result);
+  }
+  const tag = vnode.type, attrs = renderAttributes(vnode.props), innerHTML = vnode.props?.innerHTML ?? vnode.props?.dangerouslySetInnerHTML?.__html;
+  if (innerHTML != null)
+    return `<${tag}${attrs}>${innerHTML}</${tag}>`;
+  if (VOID_ELEMENTS.has(tag))
+    return `<${tag}${attrs}>`;
+  const childHtml = vnode.children.map(renderToString).join("");
+  return `<${tag}${attrs}>${childHtml}</${tag}>`;
+}
+export function renderToStream(vnode) {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(renderToString(vnode));
+      controller.close();
+    }
+  });
+}
+function applyProps(el, props) {
+  if (!props)
+    return;
+  for (const [key, value] of Object.entries(props)) {
+    if (key === "key" || key === "ref" || key === "children" || key === "innerHTML" || key === "dangerouslySetInnerHTML")
+      continue;
+    const attrName = PROP_ALIASES[key] || key;
+    if (key.startsWith("on") && typeof value === "function") {
+      const eventName = key.slice(2).toLowerCase();
+      el.addEventListener(eventName, value);
+      continue;
+    }
+    if (attrName === "class" || attrName === "className") {
+      const classStr = renderClass(value);
+      if (classStr)
+        el.setAttribute("class", classStr);
+      continue;
+    }
+    if (attrName === "style") {
+      const styleStr = typeof value === "string" ? value : renderStyle(value);
+      if (styleStr)
+        el.setAttribute("style", styleStr);
+      continue;
+    }
+    if (BOOLEAN_ATTRS.has(attrName)) {
+      if (value)
+        el.setAttribute(attrName, "");
+      continue;
+    }
+    if (value != null && value !== !1)
+      el.setAttribute(attrName, String(value));
+  }
+}
+export function renderToDOM(vnode, container) {
+  if (vnode == null || typeof vnode === "boolean")
+    return;
+  if (typeof vnode === "string") {
+    container.appendChild(document.createTextNode(vnode));
+    return;
+  }
+  if (typeof vnode === "number") {
+    container.appendChild(document.createTextNode(String(vnode)));
+    return;
+  }
+  if (Array.isArray(vnode)) {
+    for (const child of vnode)
+      renderToDOM(child, container);
+    return;
+  }
+  if (vnode.type === Fragment) {
+    for (const child of vnode.children)
+      renderToDOM(child, container);
+    return;
+  }
+  if (typeof vnode.type === "function") {
+    const result = vnode.type({
+      ...vnode.props,
+      children: vnode.children.length === 1 ? vnode.children[0] : vnode.children.length > 0 ? vnode.children : void 0
+    });
+    renderToDOM(result, container);
+    return;
+  }
+  const el = document.createElement(vnode.type);
+  applyProps(el, vnode.props);
+  const innerHTML = vnode.props?.innerHTML ?? vnode.props?.dangerouslySetInnerHTML?.__html;
+  if (innerHTML != null)
+    el.innerHTML = innerHTML;
+  else
+    for (const child of vnode.children)
+      renderToDOM(child, el);
+  if (vnode.ref) {
+    if (typeof vnode.ref === "function")
+      vnode.ref(el);
+  }
+  container.appendChild(el);
+}
+export function Show(props) {
+  if (props.when)
+    return jsx(Fragment, { children: props.children });
+  return props.fallback ?? null;
+}
+export function For(props) {
+  const items = props.each;
+  if (!items || items.length === 0)
+    return props.fallback ?? null;
+  const renderFn = Array.isArray(props.children) ? props.children[0] : props.children, children = items.map((item, index) => renderFn(item, index));
+  return jsx(Fragment, { children });
+}
+export function Portal(props) {
+  return jsx(Fragment, { children: props.children });
+}
+export function h(type, props, ...children) {
+  const { key, ref, ...restProps } = props || {};
+  return {
+    type,
+    props: Object.keys(restProps).length > 0 ? restProps : {},
+    children: normalizeChildren(children.length === 1 ? children[0] : children),
+    key: key ?? void 0,
+    ref: ref ?? void 0
+  };
+}

package/dist/keep-alive.d.ts

@@ -0,0 +1,108 @@
+/**
+ * STX Keep-Alive
+ *
+ * Caches component instances to preserve state when toggling visibility.
+ * Similar to Vue's <KeepAlive> component.
+ *
+ * @module keep-alive
+ *
+ * @example
+ * ```html
+ * @keepAlive
+ *   @if (currentTab === 'settings')
+ *     <SettingsPanel />
+ *   @elseif (currentTab === 'profile')
+ *     <ProfilePanel />
+ *   @endif
+ * @endkeepAlive
+ * ```
+ *
+ * With options:
+ * ```html
+ * @keepAlive(max: 10, include: 'Settings,Profile', exclude: 'Debug')
+ *   <component :is="currentComponent" />
+ * @endkeepAlive
+ * ```
+ */
+export interface KeepAliveOptions {
+    /** Maximum number of component instances to cache */
+    max?: number;
+    /** Comma-separated list of component names to include */
+    include?: string;
+    /** Comma-separated list of component names to exclude */
+    exclude?: string;
+    /** Custom cache key */
+    id?: string;
+}
+export interface CachedComponent {
+    /** Component identifier */
+    key: string;
+    /** Cached HTML content */
+    html: string;
+    /** Cached state data */
+    state: Record<string, unknown>;
+    /** Timestamp when cached */
+    cachedAt: number;
+    /** Scroll positions */
+    scrollPositions: Map<string, {
+        top: number;
+        left: number;
+    }>;
+}
+export interface KeepAliveCache {
+    /** Unique cache ID */
+    id: string;
+    /** Cached components (LRU order) */
+    cache: Map<string, CachedComponent>;
+    /** Maximum cache size */
+    max: number;
+    /** Include filter */
+    include: string[] | null;
+    /** Exclude filter */
+    exclude: string[] | null;
+}
+/**
+ * Process @keepAlive directives in templates.
+ *
+ * Syntax:
+ *   @keepAlive
+ *     <content to cache>
+ *   @endkeepAlive
+ *
+ * With options:
+ *   @keepAlive(max: 10, include: 'ComponentA,ComponentB')
+ */
+export declare function processKeepAliveDirectives(template: string, _context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Create a keep-alive cache programmatically.
+ */
+export declare function createKeepAliveCache(options?: KeepAliveOptions): KeepAliveCache;
+/**
+ * Check if a component should be cached based on filters.
+ */
+export declare function shouldCacheComponent(componentName: string, cache: KeepAliveCache): boolean;
+/**
+ * Generate CSS for keep-alive styling.
+ */
+export declare function generateKeepAliveCSS(): string;
+/**
+ * Generate client-side runtime for keep-alive.
+ */
+export declare function generateKeepAliveRuntime(): string;
+/**
+ * Hook called when a component is activated from cache.
+ * Use in client-side scripts.
+ */
+export declare function onActivated(callback: (detail: {
+    key: string;
+    keepAliveId: string;
+    cachedAt: number;
+}) => void): void;
+/**
+ * Hook called when a component is deactivated and cached.
+ * Use in client-side scripts.
+ */
+export declare function onDeactivated(callback: (detail: {
+    key: string;
+    keepAliveId: string;
+}) => void): void;