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

package/dist/build-optimizer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Analyze which directives are used in a template.
+ */
+export declare function analyzeDirectiveUsage(template: string): DirectiveUsage[];
+/**
+ * Get list of unused directives for tree-shaking.
+ */
+export declare function getUnusedDirectives(template: string, preserveDirectives?: string[]): string[];
+/**
+ * Generate tree-shaken directive loader code.
+ */
+export declare function generateTreeShakenBundle(usedDirectives: string[]): string;
+/**
+ * Find dead code branches that can be eliminated.
+ */
+export declare function findDeadBranches(template: string, constants?: Record<string, unknown>): DeadBranch[];
+/**
+ * Remove dead code branches from template.
+ */
+export declare function eliminateDeadCode(template: string, constants?: Record<string, unknown>): { content: string, removed: string[] };
+/**
+ * Evaluate a constant expression at compile time.
+ */
+export declare function evaluateConstant(expression: string, constants: Record<string, unknown>): unknown;
+/**
+ * Fold constant expressions in template.
+ */
+export declare function foldConstants(template: string, constants: Record<string, unknown>): { content: string, folded: string[] };
+/**
+ * Minify HTML content while preserving template directives.
+ */
+export declare function minifyHtml(template: string): string;
+/**
+ * Pool repeated string literals in template.
+ */
+export declare function poolStrings(template: string): {
+  content: string
+  pool: Map<string, string>
+  count: number
+};
+/**
+ * Optimize a single template with all available optimizations.
+ */
+export declare function optimizeTemplate(template: string, options?: OptimizationOptions): OptimizationResult;
+/**
+ * Create optimized build for multiple templates.
+ */
+export declare function createOptimizedBuild(templates: Map<string, string>, options?: OptimizationOptions): Promise<BuildResult>;
+/** Optimization options */
+export declare interface OptimizationOptions {
+  treeShake?: boolean
+  deadCodeElimination?: boolean
+  constantFolding?: boolean
+  stringPooling?: boolean
+  minifyHtml?: boolean
+  removeDevCode?: boolean
+  constants?: Record<string, unknown>
+  preserveDirectives?: string[]
+  target?: 'production' | 'development'
+}
+/** Optimization result */
+export declare interface OptimizationResult {
+  content: string
+  originalSize: number
+  optimizedSize: number
+  reduction: number
+  appliedOptimizations: string[]
+  removedDirectives: string[]
+  foldedConstants: string[]
+  pooledStrings: number
+  warnings: string[]
+}
+/** Build result for multiple templates */
+export declare interface BuildResult {
+  templates: Map<string, OptimizationResult>
+  directiveBundle?: string
+  stringPool?: Map<string, string>
+  totalOriginalSize: number
+  totalOptimizedSize: number
+  overallReduction: number
+  warnings: string[]
+}
+/** Directive usage info */
+declare interface DirectiveUsage {
+  name: string
+  count: number
+  locations: Array<{ line: number, column: number }>
+}
+/** Dead code branch */
+declare interface DeadBranch {
+  start: number
+  end: number
+  reason: string
+}
+// =============================================================================
+// Export Analysis Functions
+// =============================================================================
+export {
+  analyzeDirectiveUsage as analyzeUsage,
+  findDeadBranches as findDeadCode,
+};

package/dist/build-optimizer.js

@@ -0,0 +1,433 @@
+const DEFAULT_OPTIONS = {
+  treeShake: !0,
+  deadCodeElimination: !0,
+  constantFolding: !0,
+  stringPooling: !1,
+  minifyHtml: !0,
+  removeDevCode: !0,
+  constants: {},
+  preserveDirectives: [],
+  target: "production"
+}, ALL_DIRECTIVES = [
+  "if",
+  "else",
+  "elseif",
+  "endif",
+  "unless",
+  "endunless",
+  "switch",
+  "case",
+  "default",
+  "endswitch",
+  "for",
+  "endfor",
+  "foreach",
+  "endforeach",
+  "forelse",
+  "endforelse",
+  "while",
+  "endwhile",
+  "break",
+  "continue",
+  "empty",
+  "extends",
+  "section",
+  "endsection",
+  "yield",
+  "parent",
+  "include",
+  "includeIf",
+  "includeWhen",
+  "includeFirst",
+  "once",
+  "endonce",
+  "push",
+  "endpush",
+  "prepend",
+  "endprepend",
+  "stack",
+  "component",
+  "endcomponent",
+  "slot",
+  "endslot",
+  "props",
+  "auth",
+  "endauth",
+  "guest",
+  "endguest",
+  "can",
+  "endcan",
+  "cannot",
+  "endcannot",
+  "role",
+  "endrole",
+  "hasRole",
+  "endhasRole",
+  "hasAnyRole",
+  "endhasAnyRole",
+  "csrf",
+  "method",
+  "error",
+  "enderror",
+  "old",
+  "input",
+  "textarea",
+  "select",
+  "checkbox",
+  "radio",
+  "file",
+  "translate",
+  "lang",
+  "choice",
+  "meta",
+  "title",
+  "seo",
+  "jsonld",
+  "canonical",
+  "robots",
+  "sitemap",
+  "ts",
+  "endts",
+  "js",
+  "endjs",
+  "css",
+  "endcss",
+  "markdown",
+  "endmarkdown",
+  "verbatim",
+  "endverbatim",
+  "env",
+  "production",
+  "debug",
+  "isset",
+  "endisset",
+  "empty",
+  "endempty"
+];
+export function analyzeDirectiveUsage(template) {
+  const usage = new Map, directiveRegex = /@(\w+)/g;
+  let match, line = 1, lastNewline = 0;
+  while ((match = directiveRegex.exec(template)) !== null) {
+    const name = match[1], beforeMatch = template.slice(lastNewline, match.index);
+    line += (beforeMatch.match(/\n/g) || []).length;
+    lastNewline = match.index;
+    const column = match.index - template.lastIndexOf(`
+`, match.index - 1);
+    if (ALL_DIRECTIVES.includes(name)) {
+      const existing = usage.get(name);
+      if (existing) {
+        existing.count++;
+        existing.locations.push({ line, column });
+      } else
+        usage.set(name, {
+          name,
+          count: 1,
+          locations: [{ line, column }]
+        });
+    }
+  }
+  return Array.from(usage.values());
+}
+export function getUnusedDirectives(template, preserveDirectives = []) {
+  const used = analyzeDirectiveUsage(template), usedNames = new Set(used.map((u) => u.name));
+  for (const dir of preserveDirectives)
+    usedNames.add(dir);
+  for (const name of Array.from(usedNames))
+    if (!name.startsWith("end"))
+      usedNames.add(`end${name}`);
+  return ALL_DIRECTIVES.filter((d) => !usedNames.has(d));
+}
+export function generateTreeShakenBundle(usedDirectives) {
+  const imports = [], modules = {
+    conditionals: ["if", "else", "elseif", "endif", "unless", "endunless", "switch", "case", "default", "endswitch", "isset", "endisset"],
+    loops: ["for", "endfor", "foreach", "endforeach", "forelse", "endforelse", "while", "endwhile", "break", "continue", "empty"],
+    includes: ["include", "includeIf", "includeWhen", "includeFirst", "once", "endonce", "extends", "section", "endsection", "yield", "parent", "push", "endpush", "prepend", "endprepend", "stack"],
+    components: ["component", "endcomponent", "slot", "endslot", "props"],
+    auth: ["auth", "endauth", "guest", "endguest", "can", "endcan", "cannot", "endcannot", "role", "endrole", "hasRole", "endhasRole", "hasAnyRole", "endhasAnyRole"],
+    forms: ["csrf", "method", "error", "enderror", "old", "input", "textarea", "select", "checkbox", "radio", "file"],
+    i18n: ["translate", "lang", "choice"],
+    seo: ["meta", "title", "seo", "jsonld", "canonical", "robots", "sitemap"]
+  }, neededModules = new Set;
+  for (const dir of usedDirectives)
+    for (const [module, directives] of Object.entries(modules))
+      if (directives.includes(dir)) {
+        neededModules.add(module);
+        break;
+      }
+  for (const module of neededModules)
+    imports.push(`import { process${capitalize(module)} } from './${module}'`);
+  const directiveMap = usedDirectives.filter((d) => !d.startsWith("end")).map((d) => `  '${d}': true`).join(`,
+`);
+  return `// Tree-shaken directive bundle
+// Only includes: ${usedDirectives.join(", ")}
+${imports.join(`
+`)}
+
+export const activeDirectives = {
+${directiveMap}
+}
+
+export function isDirectiveActive(name: string): boolean {
+  return name in activeDirectives
+}
+`;
+}
+export function findDeadBranches(template, constants = {}) {
+  const deadBranches = [], ifRegex = /@if\(([^)]+)\)[\s\S]*?@endif/g, ifMatches = template.matchAll(ifRegex);
+  for (const match of ifMatches) {
+    const condition = match[1].trim();
+    if (evaluateConstant(condition, constants) === !1)
+      deadBranches.push({
+        start: match.index,
+        end: match.index + match[0].length,
+        reason: `@if condition always false: ${condition}`
+      });
+  }
+  const unlessRegex = /@unless\(([^)]+)\)[\s\S]*?@endunless/g, unlessMatches = template.matchAll(unlessRegex);
+  for (const match of unlessMatches) {
+    const condition = match[1].trim();
+    if (evaluateConstant(condition, constants) === !0)
+      deadBranches.push({
+        start: match.index,
+        end: match.index + match[0].length,
+        reason: `@unless condition always true: ${condition}`
+      });
+  }
+  const envRegex = /@env\(['"]development['"]\)[\s\S]*?@endenv/g;
+  if (constants.__ENV__ === "production") {
+    const envMatches = template.matchAll(envRegex);
+    for (const match of envMatches)
+      deadBranches.push({
+        start: match.index,
+        end: match.index + match[0].length,
+        reason: "Development-only code in production build"
+      });
+  }
+  const debugRegex = /@debug[\s\S]*?@enddebug/g;
+  if (constants.__ENV__ === "production") {
+    const debugMatches = template.matchAll(debugRegex);
+    for (const match of debugMatches)
+      deadBranches.push({
+        start: match.index,
+        end: match.index + match[0].length,
+        reason: "Debug code in production build"
+      });
+  }
+  return deadBranches;
+}
+export function eliminateDeadCode(template, constants = {}) {
+  const deadBranches = findDeadBranches(template, constants), removed = [];
+  deadBranches.sort((a, b) => b.start - a.start);
+  let result = template;
+  for (const branch of deadBranches) {
+    result = result.slice(0, branch.start) + result.slice(branch.end);
+    removed.push(branch.reason);
+  }
+  return { content: result, removed };
+}
+export function evaluateConstant(expression, constants) {
+  if (expression === "true")
+    return !0;
+  if (expression === "false")
+    return !1;
+  if (expression === "null")
+    return null;
+  if (/^\d+$/.test(expression))
+    return Number.parseInt(expression, 10);
+  if (/^\d+\.\d+$/.test(expression))
+    return Number.parseFloat(expression);
+  if (/^['"].*['"]$/.test(expression))
+    return expression.slice(1, -1);
+  if (expression in constants)
+    return constants[expression];
+  const comparisonMatch = expression.match(/^(\w+)\s*(===|!==|==|!=|>=|<=|>|<)\s*(.+)$/);
+  if (comparisonMatch) {
+    const [, left, op, right] = comparisonMatch, leftVal = left in constants ? constants[left] : void 0, rightVal = evaluateConstant(right, constants);
+    if (leftVal !== void 0 && rightVal !== void 0)
+      switch (op) {
+        case "==":
+        case "===":
+          return leftVal === rightVal;
+        case "!=":
+        case "!==":
+          return leftVal !== rightVal;
+        case ">":
+          return leftVal > rightVal;
+        case "<":
+          return leftVal < rightVal;
+        case ">=":
+          return leftVal >= rightVal;
+        case "<=":
+          return leftVal <= rightVal;
+      }
+  }
+  return;
+}
+export function foldConstants(template, constants) {
+  const folded = [];
+  let result = template;
+  result = result.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, name) => {
+    if (name in constants) {
+      folded.push(`{{ ${name} }} -> ${constants[name]}`);
+      return String(constants[name]);
+    }
+    return match;
+  });
+  result = result.replace(/\{\{\s*(\d+)\s*([+\-*])\s*(\d+)\s*\}\}/g, (match, a, op, b) => {
+    const numA = Number.parseInt(a, 10), numB = Number.parseInt(b, 10);
+    let result;
+    switch (op) {
+      case "+":
+        result = numA + numB;
+        break;
+      case "-":
+        result = numA - numB;
+        break;
+      case "*":
+        result = numA * numB;
+        break;
+      default:
+        return match;
+    }
+    folded.push(`{{ ${a} ${op} ${b} }} -> ${result}`);
+    return String(result);
+  });
+  return { content: result, folded };
+}
+export function minifyHtml(template) {
+  let result = template;
+  const preserved = [];
+  let markerIndex = 0;
+  result = result.replace(/<(pre|code|script|style)([^>]*)>([\s\S]*?)<\/\1>/gi, (match) => {
+    const marker = `__PRESERVE_${markerIndex++}__`;
+    preserved.push({ marker, content: match });
+    return marker;
+  });
+  result = result.replace(/\{\{([\s\S]*?)\}\}/g, (match) => {
+    const marker = `__PRESERVE_${markerIndex++}__`;
+    preserved.push({ marker, content: match });
+    return marker;
+  });
+  result = result.replace(/\{\{--([\s\S]*?)--\}\}/g, "");
+  result = result.replace(/<!--[\s\S]*?-->/g, "");
+  result = result.replace(/>\s+</g, "><");
+  result = result.replace(/^\s+/gm, "");
+  result = result.replace(/\s+$/gm, "");
+  result = result.replace(/\s{2,}/g, " ");
+  for (const { marker, content } of preserved) {
+    const idx = result.indexOf(marker);
+    if (idx !== -1)
+      result = result.slice(0, idx) + content + result.slice(idx + marker.length);
+  }
+  return result.trim();
+}
+export function poolStrings(template) {
+  const pool = new Map, stringCounts = new Map, stringRegex = /(['"])([^'"]{10,})\1/g;
+  let match;
+  while ((match = stringRegex.exec(template)) !== null) {
+    const str = match[2];
+    stringCounts.set(str, (stringCounts.get(str) || 0) + 1);
+  }
+  let poolIndex = 0, result = template;
+  for (const [str, count] of stringCounts)
+    if (count > 1) {
+      const varName = `__STR_${poolIndex++}__`;
+      pool.set(varName, str);
+      const escaped = str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), regex = new RegExp(`(['"])${escaped}\\1`, "g");
+      result = result.replace(regex, varName);
+    }
+  return { content: result, pool, count: pool.size };
+}
+export function optimizeTemplate(template, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options }, originalSize = new Blob([template]).size;
+  let content = template;
+  const appliedOptimizations = [], warnings = [];
+  let removedDirectives = [], foldedConstants = [], pooledStrings = 0;
+  if (opts.target === "production")
+    opts.constants = { ...opts.constants, __ENV__: "production" };
+  if (opts.deadCodeElimination) {
+    const result = eliminateDeadCode(content, opts.constants);
+    content = result.content;
+    if (result.removed.length > 0) {
+      appliedOptimizations.push("Dead code elimination");
+      warnings.push(...result.removed.map((r) => `Removed: ${r}`));
+    }
+  }
+  if (opts.constantFolding && Object.keys(opts.constants).length > 0) {
+    const result = foldConstants(content, opts.constants);
+    content = result.content;
+    foldedConstants = result.folded;
+    if (foldedConstants.length > 0)
+      appliedOptimizations.push("Constant folding");
+  }
+  if (opts.treeShake) {
+    removedDirectives = getUnusedDirectives(content, opts.preserveDirectives);
+    if (removedDirectives.length > 0)
+      appliedOptimizations.push("Tree shaking");
+  }
+  if (opts.stringPooling) {
+    const result = poolStrings(content);
+    content = result.content;
+    pooledStrings = result.count;
+    if (pooledStrings > 0)
+      appliedOptimizations.push("String pooling");
+  }
+  if (opts.minifyHtml) {
+    const minified = minifyHtml(content);
+    if (minified.length < content.length) {
+      content = minified;
+      appliedOptimizations.push("HTML minification");
+    }
+  }
+  const optimizedSize = new Blob([content]).size, reduction = originalSize > 0 ? Math.round((1 - optimizedSize / originalSize) * 100) : 0;
+  return {
+    content,
+    originalSize,
+    optimizedSize,
+    reduction,
+    appliedOptimizations,
+    removedDirectives,
+    foldedConstants,
+    pooledStrings,
+    warnings
+  };
+}
+export async function createOptimizedBuild(templates, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options }, results = new Map, warnings = [];
+  let totalOriginalSize = 0, totalOptimizedSize = 0;
+  const allUsedDirectives = new Set;
+  for (const [path, template] of templates) {
+    const result = optimizeTemplate(template, opts);
+    results.set(path, result);
+    totalOriginalSize += result.originalSize;
+    totalOptimizedSize += result.optimizedSize;
+    warnings.push(...result.warnings.map((w) => `${path}: ${w}`));
+    const usage = analyzeDirectiveUsage(template);
+    for (const u of usage)
+      allUsedDirectives.add(u.name);
+  }
+  let directiveBundle;
+  if (opts.treeShake)
+    directiveBundle = generateTreeShakenBundle(Array.from(allUsedDirectives));
+  let stringPool;
+  if (opts.stringPooling)
+    stringPool = new Map;
+  const overallReduction = totalOriginalSize > 0 ? Math.round((1 - totalOptimizedSize / totalOriginalSize) * 100) : 0;
+  return {
+    templates: results,
+    directiveBundle,
+    stringPool,
+    totalOriginalSize,
+    totalOptimizedSize,
+    overallReduction,
+    warnings
+  };
+}
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+export {
+  analyzeDirectiveUsage as analyzeUsage,
+  findDeadBranches as findDeadCode
+};

package/dist/build-views.d.ts

@@ -0,0 +1,56 @@
+import type { StxOptions } from './types';
+/**
+ * Render a single STX template to HTML
+ */
+export declare function renderView(templatePath: string, props?: Record<string, unknown>, options?: Partial<StxOptions>): Promise<string>;
+/**
+ * Build all views in a directory
+ */
+export declare function buildViews(options: ViewBuildOptions): Promise<BuildResult>;
+/**
+ * Watch views directory and rebuild on changes
+ */
+export declare function watchViews(options: ViewBuildOptions, callback?: (result: BuildResult) => void): { close: () => void };
+/**
+ * Render a .stx email template to an email-ready HTML string
+ *
+ * Optimized for email rendering:
+ * - Disables SEO tag injection
+ * - Inlines utility classes as style attributes (via Css)
+ * - Strips <style> and <script> blocks
+ * - Returns clean HTML + plain text suitable for email
+ *
+ * @example
+ * ```typescript
+ * const { html, text } = await renderEmail('resources/emails/welcome.stx', {
+ *   userName: 'John',
+ *   unsubscribeUrl: 'https://example.com/unsubscribe?token=abc',
+ * })
+ * ```
+ */
+export declare function renderEmail(templatePath: string, props?: Record<string, unknown>, options?: Partial<StxOptions>): Promise<{ html: string, text: string }>;
+export declare interface ViewBuildOptions {
+  viewsDir: string
+  outputDir: string
+  componentsDir?: string
+  layoutsDir?: string
+  partialsDir?: string
+  globalProps?: Record<string, unknown>
+  placeholders?: Record<string, string>
+  views?: ViewConfig[]
+  debug?: boolean
+  generateManifest?: boolean
+}
+export declare interface ViewConfig {
+  input: string
+  output?: string
+  props?: Record<string, unknown>
+}
+export declare interface BuildResult {
+  success: boolean
+  views: string[]
+  errors: Array<{ file: string; error: string }>
+  duration: number
+}
+// Default export for convenience
+export default buildViews;