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

package/dist/events.js

@@ -0,0 +1,396 @@
+import { templateHasReactiveContext } from "./runtime-globals.js";
+const DOM_EVENTS = new Set([
+  "click",
+  "dblclick",
+  "mousedown",
+  "mouseup",
+  "mousemove",
+  "mouseenter",
+  "mouseleave",
+  "mouseover",
+  "mouseout",
+  "contextmenu",
+  "wheel",
+  "keydown",
+  "keyup",
+  "keypress",
+  "submit",
+  "reset",
+  "change",
+  "input",
+  "focus",
+  "blur",
+  "focusin",
+  "focusout",
+  "select",
+  "invalid",
+  "touchstart",
+  "touchend",
+  "touchmove",
+  "touchcancel",
+  "drag",
+  "dragstart",
+  "dragend",
+  "dragenter",
+  "dragleave",
+  "dragover",
+  "drop",
+  "scroll",
+  "resize",
+  "load",
+  "error",
+  "abort",
+  "animationstart",
+  "animationend",
+  "animationiteration",
+  "transitionstart",
+  "transitionend",
+  "transitionrun",
+  "transitioncancel",
+  "mounted",
+  "unmounted"
+]), KEY_ALIASES = {
+  enter: "Enter",
+  tab: "Tab",
+  delete: "Delete",
+  backspace: "Backspace",
+  esc: "Escape",
+  escape: "Escape",
+  space: " ",
+  up: "ArrowUp",
+  down: "ArrowDown",
+  left: "ArrowLeft",
+  right: "ArrowRight",
+  home: "Home",
+  end: "End",
+  pageup: "PageUp",
+  pagedown: "PageDown"
+}, SYSTEM_KEYS = new Set(["ctrl", "alt", "shift", "meta"]), MOUSE_BUTTONS = {
+  left: 0,
+  middle: 1,
+  right: 2
+};
+function parseModifiers(parts) {
+  const modifiers = {
+    prevent: !1,
+    stop: !1,
+    once: !1,
+    capture: !1,
+    self: !1,
+    passive: !1,
+    keys: [],
+    systemKeys: [],
+    mouse: null,
+    debounce: null,
+    throttle: null
+  };
+  for (const part of parts) {
+    const lowerPart = part.toLowerCase();
+    if (lowerPart === "prevent")
+      modifiers.prevent = !0;
+    else if (lowerPart === "stop")
+      modifiers.stop = !0;
+    else if (lowerPart === "once")
+      modifiers.once = !0;
+    else if (lowerPart === "capture")
+      modifiers.capture = !0;
+    else if (lowerPart === "self")
+      modifiers.self = !0;
+    else if (lowerPart === "passive")
+      modifiers.passive = !0;
+    else if (SYSTEM_KEYS.has(lowerPart))
+      modifiers.systemKeys.push(lowerPart);
+    else if (lowerPart in MOUSE_BUTTONS)
+      modifiers.mouse = lowerPart;
+    else if (lowerPart in KEY_ALIASES || /^[a-z]$/.test(lowerPart))
+      modifiers.keys.push(KEY_ALIASES[lowerPart] || lowerPart.toUpperCase());
+    else if (lowerPart.startsWith("debounce")) {
+      const match = lowerPart.match(/debounce(?:\.(\d+))?/);
+      modifiers.debounce = match?.[1] ? Number.parseInt(match[1], 10) : 300;
+    } else if (lowerPart.startsWith("throttle")) {
+      const match = lowerPart.match(/throttle(?:\.(\d+))?/);
+      modifiers.throttle = match?.[1] ? Number.parseInt(match[1], 10) : 300;
+    }
+  }
+  return modifiers;
+}
+function findElementsWithEvents(template) {
+  const elements = [];
+  let idCounter = 0;
+  const tagRegex = /<([a-z][a-z0-9-]*)\s+([^>]*@[a-z][^>]*)>/gi;
+  let match;
+  while ((match = tagRegex.exec(template)) !== null) {
+    const [fullMatch, _tagName, attributesStr] = match, startIndex = match.index, endIndex = startIndex + fullMatch.length, elementId = `__stx_evt_${idCounter++}`, events = [], doubleQuoteRegex = /@([a-z][a-z0-9.]*)\s*=\s*"([^"]*)"/gi;
+    let attrMatch;
+    while ((attrMatch = doubleQuoteRegex.exec(attributesStr)) !== null) {
+      const [, eventWithModifiers, handler] = attrMatch, parts = eventWithModifiers.split("."), eventName = parts[0];
+      if (!DOM_EVENTS.has(eventName))
+        continue;
+      events.push({
+        attribute: `@${eventWithModifiers}`,
+        event: eventName,
+        handler,
+        modifiers: parseModifiers(parts.slice(1)),
+        elementId
+      });
+    }
+    const singleQuoteRegex = /@([a-z][a-z0-9.]*)\s*=\s*'([^']*)'/gi;
+    while ((attrMatch = singleQuoteRegex.exec(attributesStr)) !== null) {
+      const [, eventWithModifiers, handler] = attrMatch, parts = eventWithModifiers.split("."), eventName = parts[0];
+      if (!DOM_EVENTS.has(eventName))
+        continue;
+      events.push({
+        attribute: `@${eventWithModifiers}`,
+        event: eventName,
+        handler,
+        modifiers: parseModifiers(parts.slice(1)),
+        elementId
+      });
+    }
+    if (events.length > 0)
+      elements.push({
+        originalTag: fullMatch,
+        elementId,
+        events,
+        startIndex,
+        endIndex
+      });
+  }
+  return elements;
+}
+function generateModifierChecks(event) {
+  const checks = [], { modifiers } = event;
+  if (modifiers.self)
+    checks.push("if ($event.target !== $el) return");
+  for (const key of modifiers.systemKeys)
+    checks.push(`if (!$event.${key}Key) return`);
+  if (modifiers.keys.length > 0) {
+    const keyChecks = modifiers.keys.map((k) => `$event.key === '${k}'`).join(" || ");
+    checks.push(`if (!(${keyChecks})) return`);
+  }
+  if (modifiers.mouse !== null) {
+    const button = MOUSE_BUTTONS[modifiers.mouse];
+    checks.push(`if ($event.button !== ${button}) return`);
+  }
+  if (modifiers.prevent)
+    checks.push("$event.preventDefault()");
+  if (modifiers.stop)
+    checks.push("$event.stopPropagation()");
+  return checks.join("; ");
+}
+function wrapHandler(handler, modifiers) {
+  let wrapped = handler;
+  if (modifiers.debounce !== null)
+    wrapped = `__stx_debounce(() => { ${wrapped} }, ${modifiers.debounce})`;
+  else if (modifiers.throttle !== null)
+    wrapped = `__stx_throttle(() => { ${wrapped} }, ${modifiers.throttle})`;
+  return wrapped;
+}
+export function asInvocableStatement(handler) {
+  const name = handler.trim();
+  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name))
+    return handler;
+  return `if (typeof ${name} === 'function' && !${name}._isSignal) ${name}($event);`;
+}
+function generateEventListener(event) {
+  const { modifiers } = event, elementId = event.elementId.replace(/\\/g, "\\\\").replace(/'/g, "\\'"), checks = generateModifierChecks(event), handler = wrapHandler(asInvocableStatement(event.handler), modifiers), options = [];
+  if (modifiers.once)
+    options.push("once: true");
+  if (modifiers.capture)
+    options.push("capture: true");
+  if (modifiers.passive)
+    options.push("passive: true");
+  const optionsStr = options.length > 0 ? `, { ${options.join(", ")} }` : "", escapedHandler = handler.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+  if (event.event === "mounted")
+    return `
+  (function() {
+    var $el = document.getElementById('${elementId}');
+    if (!$el) return;
+    // Run mounted handler immediately (DOM is ready)
+    var scope = $el.closest('[data-stx-scope]');
+    if (scope && scope.__stx_execute) {
+      scope.__stx_execute('${escapedHandler}', null, $el);
+    }
+else {
+      __stx_runHandler('${escapedHandler}', null, $el);
+    }
+  })();`;
+  if (event.event === "unmounted")
+    return `
+  (function() {
+    var $el = document.getElementById('${elementId}');
+    if (!$el) return;
+    // Set up MutationObserver to detect removal
+    var observer = new MutationObserver(function(mutations) {
+      for (var m of mutations) {
+        for (var node of m.removedNodes) {
+          if (node === $el || (node.contains && node.contains($el))) {
+            observer.disconnect();
+            var scope = $el.closest('[data-stx-scope]');
+            if (scope && scope.__stx_execute) {
+              scope.__stx_execute('${escapedHandler}', null, $el);
+            }
+else {
+              __stx_runHandler('${escapedHandler}', null, $el);
+            }
+            return;
+          }
+        }
+      }
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+    // Store observer for cleanup
+    $el.__stx_unmount_observer = observer;
+  })();`;
+  return `
+  (function() {
+    var $el = document.getElementById('${elementId}');
+    if (!$el) return;
+    // eslint-disable-next-line pickier/no-unused-vars
+    $el.addEventListener('${event.event}', function($event) {
+      ${checks ? checks + ";" : ""}
+      // Find the closest reactive scope and execute within its context
+      var scope = $el.closest('[data-stx-scope]');
+      if (scope && scope.__stx_execute) {
+        scope.__stx_execute('${escapedHandler}', $event, $el);
+      }
+else {
+        // Fallback for non-reactive context (entity-safe; decoded + run in memory)
+        __stx_runHandler('${escapedHandler}', $event, $el);
+      }
+    }${optionsStr});
+  })();`;
+}
+export function generateRuntimeScript(events) {
+  if (events.length === 0)
+    return "";
+  return `
+<script data-stx-events>
+(function() {
+  'use strict';
+
+  // Utility functions
+  function __stx_debounce(fn, delay) {
+    var timeout;
+    return function() {
+      var args = arguments;
+      var ctx = this;
+      clearTimeout(timeout);
+      timeout = setTimeout(function() { fn.apply(ctx, args); }, delay);
+    };
+  }
+
+  function __stx_throttle(fn, delay) {
+    var last = 0;
+    return function() {
+      var now = Date.now();
+      if (now - last >= delay) {
+        last = now;
+        fn.apply(this, arguments);
+      }
+    };
+  }
+
+  // Non-reactive fallback runner. The handler is embedded HTML-entity-encoded
+  // so the surrounding script element can never contain raw markup, including
+  // its own closing tag; we decode it to JS only in memory here, then run it
+  // with $event/$el in scope.
+  //
+  // This comment must not spell that closing tag out. It used to, as an
+  // example, and a browser ends the script element at the FIRST one it sees \u2014
+  // so everything below this line, __stx_runHandler included, was emitted as
+  // page text and no listener was ever bound. The comment about escaping was
+  // the thing that needed escaping.
+  function __stx_runHandler(h, $event, $el) {
+    var code = h
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .replace(/&#x27;/g, "'")
+      .replace(/&amp;/g, '&');
+    try {
+      // eslint-disable-next-line no-new-func
+      (new Function('$event', '$el', code)).call($el, $event, $el);
+    }
+    catch (e) {
+      if (typeof console !== 'undefined') console.error('[stx] event handler error:', e);
+    }
+  }
+
+  // Event listeners
+  ${events.map(generateEventListener).join(`
+`)}
+})();
+</script>`;
+}
+export function extractAndProcessEvents(template) {
+  const elements = findElementsWithEvents(template);
+  if (elements.length === 0)
+    return { template, bindings: [] };
+  let output = template;
+  const allBindings = [];
+  for (let i = elements.length - 1;i >= 0; i--) {
+    const element = elements[i];
+    let newTag = element.originalTag;
+    if (!newTag.includes(" id="))
+      newTag = newTag.replace(/^<([a-z][a-z0-9-]*)/, `<$1 id="${element.elementId}"`);
+    else {
+      const idMatch = newTag.match(/id=["']([^"']+)["']/);
+      if (idMatch)
+        for (const evt of element.events)
+          evt.elementId = idMatch[1];
+    }
+    for (const evt of element.events) {
+      const escapedAttr = evt.attribute.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), doubleQuotePattern = new RegExp(`\\s*${escapedAttr}\\s*=\\s*"[^"]*"`, "g"), singleQuotePattern = new RegExp(`\\s*${escapedAttr}\\s*=\\s*'[^']*'`, "g");
+      newTag = newTag.replace(doubleQuotePattern, "");
+      newTag = newTag.replace(singleQuotePattern, "");
+    }
+    output = output.slice(0, element.startIndex) + newTag + output.slice(element.endIndex);
+    allBindings.push(...element.events);
+  }
+  return { template: output, bindings: allBindings };
+}
+export function processEventDirectives(template, context, _filePath) {
+  if (templateHasReactiveContext(template))
+    return template;
+  if (context.__stx_sfc_mode) {
+    if (/x-data\s*=\s*["']/.test(template))
+      return template;
+    const { template: processed, bindings } = extractAndProcessEvents(template), existing = context.__stx_event_bindings || [];
+    context.__stx_event_bindings = [...existing, ...bindings];
+    return processed;
+  }
+  const elements = findElementsWithEvents(template);
+  if (elements.length === 0)
+    return template;
+  let output = template;
+  for (let i = elements.length - 1;i >= 0; i--) {
+    const element = elements[i];
+    let newTag = element.originalTag;
+    if (!newTag.includes(" id="))
+      newTag = newTag.replace(/^<([a-z][a-z0-9-]*)/, `<$1 id="${element.elementId}"`);
+    else {
+      const idMatch = newTag.match(/id=["']([^"']+)["']/);
+      if (idMatch)
+        for (const evt of element.events)
+          evt.elementId = idMatch[1];
+    }
+    for (const evt of element.events) {
+      const escapedAttr = evt.attribute.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), doubleQuotePattern = new RegExp(`\\s*${escapedAttr}\\s*=\\s*"[^"]*"`, "g"), singleQuotePattern = new RegExp(`\\s*${escapedAttr}\\s*=\\s*'[^']*'`, "g");
+      newTag = newTag.replace(doubleQuotePattern, "");
+      newTag = newTag.replace(singleQuotePattern, "");
+    }
+    output = output.slice(0, element.startIndex) + newTag + output.slice(element.endIndex);
+  }
+  const script = generateRuntimeScript(elements.flatMap((el) => el.events)), bodyIdx = output.lastIndexOf("</body>");
+  if (bodyIdx !== -1)
+    output = output.slice(0, bodyIdx) + script + `
+` + output.slice(bodyIdx);
+  else
+    output += script;
+  return output;
+}
+export function hasEventDirectives(template) {
+  return /@[a-z]+(?:\.[a-z]+)*\s*=\s*["'][^"']*["']/i.test(template);
+}

package/dist/expressions.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Module for processing template expressions and filters
+ *
+ * Expression Syntax:
+ * ==================
+ * - `{{ expression }}` - Escaped output (HTML entities escaped)
+ * - `{!! expression !!}` - Raw/unescaped output
+ * - `{{ expression | filter }}` - Apply filter to expression
+ * - `{{ expression | filter:arg1,arg2 }}` - Filter with arguments
+ * - `{{ expression | filter1 | filter2 }}` - Filter chain
+ *
+ * Filter Parsing:
+ * ===============
+ * The filter parser uses character-by-character parsing to handle:
+ * - Pipe `|` as filter separator (but not `||` logical OR)
+ * - Colon `:` as argument separator
+ * - Quoted strings with proper escape handling
+ * - Nested parentheses in expressions
+ *
+ * Key parsing rules:
+ * - `||` (double pipe) is preserved as logical OR, not filter separator
+ * - Arguments after `:` are split by `,` respecting quotes and parens
+ * - Filter names must be alphanumeric with underscores
+ *
+ * Available Built-in Filters:
+ * ===========================
+ * String: uppercase, lowercase, capitalize, truncate, replace, stripTags
+ * Number: number, currency, abs, round
+ * Array: join, first, last, length, reverse, slice
+ * Utility: escape, json, default, urlencode
+ * i18n: translate, pluralize, date
+ */
+/**
+ * Add basic filter support to expressions
+ * Filter functions receive the value to transform, optional args, and the context object
+ */
+export type FilterFunction = (value: any, context: Record<string, any>, ...args: any[]) => any;
+export declare const defaultFilters: Record<string, FilterFunction>;
+/**
+ * Register a custom filter
+ *
+ * @param name - Filter name (used in templates as {{ value | filterName }})
+ * @param fn - Filter function
+ *
+ * @example
+ * ```typescript
+ * // Register a custom filter
+ * registerFilter('reverse', (value) => {
+ *   return String(value).split('').reverse().join('')
+ * })
+ *
+ * // Use in template: {{ name | reverse }}
+ * ```
+ */
+export declare function registerFilter(name: string, fn: FilterFunction): void;
+/**
+ * Register multiple custom filters at once
+ *
+ * @param filters - Object mapping filter names to functions
+ *
+ * @example
+ * ```typescript
+ * registerFilters({
+ *   reverse: (value) => String(value).split('').reverse().join(''),
+ *   double: (value) => Number(value) * 2,
+ * })
+ * ```
+ */
+export declare function registerFilters(filters: Record<string, FilterFunction>): void;
+/**
+ * Get all available filters (built-in + custom)
+ */
+export declare function getAllFilters(): Record<string, FilterFunction>;
+/**
+ * Clear all custom filters (useful for testing)
+ */
+export declare function clearCustomFilters(): void;
+/**
+ * HTML escape function to prevent XSS
+ */
+export declare function escapeHtml(unsafe: string): string;
+/**
+ * Escape a *value* for HTML output: the markup characters, and the template's
+ * own syntax with them.
+ *
+ * **A value is data, never a template.** The pipeline runs more than one
+ * expression pass over composed output - a loop body is processed per
+ * iteration and the finished page again, a section is spliced into its layout,
+ * an include into its parent - so whatever one pass emits, the next one reads.
+ * Without neutralising the opening braces here, a value of `{{ secret }}` is
+ * evaluated against the page's own scope on the second pass, and every field a
+ * person can type into becomes server-side template injection: a repository
+ * description, an issue title, a branch name.
+ *
+ * Reproduced in a real application before this existed: a description of
+ * `probe {{ 6*7 }} here` rendered as `probe 42 here`, and one of
+ * `{{ ownerHandle }}` printed the view's own local variable.
+ *
+ * **Only a brace that opens template syntax is encoded** - a run of `{`, or a
+ * `{` before `!`. A lone brace is left exactly as it was, so a JSON value, a
+ * CSS snippet, or prose about `{` renders byte for byte as it always did; this
+ * is a security fix and it should not rewrite everybody's output as the price.
+ *
+ * Character references rather than sentinel tokens, so there is nothing to
+ * restore afterwards and no code path that can leak a placeholder into a page.
+ * The DOM is unaffected: a reader sees `{{ secret }}`, an attribute parses back
+ * to `{`, and `JSON.parse` of a data attribute still works, because the browser
+ * decodes references before anything reads them.
+ */
+export declare function escapeHtmlValue(unsafe: string): string;
+/**
+ * Check if a template uses signals (state, derived, effect) in its script blocks
+ * or has reactive attributes (@if, @for) with function call expressions
+ *
+ * `filePath` lets a script that factors its signals into an imported module be
+ * recognised too. Without it the scan is text-only, which is what every caller
+ * did before and is still correct for a script that declares its own signals.
+ */
+export declare function usesSignalsInScript(template: string, filePath?: string): boolean;
+export declare function interpolateScriptExpressions(scriptBody: string, context: Record<string, any>): string;
+/**
+ * Interpolate expressions in a `<script>` tag's ATTRIBUTES.
+ *
+ * Attributes are HTML, not JavaScript, so they get HTML rules rather than the
+ * JSON-stringifying rules {@link interpolateScriptExpressions} applies to a
+ * body: `data-id="{{ id }}"` must become `data-id="7"`, never `data-id=""7""`.
+ *
+ * This is the only channel a module island has for server data. A module
+ * script is emitted verbatim — no IIFE, no server-data bridge — so
+ * `<script type="module" data-session="{{ id }}">` was the documented way to
+ * pass a value in, and it shipped the literal text `{{ id }}` to the browser.
+ * The failure is silent: the markup looks right, and only the code reading
+ * `dataset.session` sees a mustache.
+ *
+ * Unresolvable expressions are left untouched, matching the "preserve for the
+ * client" semantics used everywhere else.
+ */
+export declare function interpolateScriptAttributes(attrs: string, context: Record<string, any>): string;
+/**
+ * Options for {@link interpolateScriptsInTemplate}.
+ */
+export interface InterpolateScriptsOptions {
+    /**
+     * Skip `<script server>` tags. Useful when the template still contains
+     * unstripped server scripts (e.g. inside `processDirectives`) whose bodies
+     * are executed rather than embedded — running `{{ }}` substitution on
+     * them would produce invalid JS. Default: `false`.
+     */
+    skipServer?: boolean;
+}
+/**
+ * Interpolate server expressions inside every `<script>` tag in a template,
+ * skipping any script that opts out via `data-raw`, `type="application/json"`,
+ * or a `src=` attribute (external scripts don't have inline content to template).
+ *
+ * Each matched script has its body passed through {@link interpolateScriptExpressions}
+ * and its attributes through {@link interpolateScriptAttributes}. Tag structure
+ * is otherwise untouched.
+ */
+export declare function interpolateScriptsInTemplate(template: string, context: Record<string, any>, options?: InterpolateScriptsOptions): string;
+/**
+ * Process template expressions including variables, filters, and operations
+ */
+export declare function processExpressions(template: string, context: Record<string, any>, filePath: string): string;
+/**
+ * Apply filters to a value
+ */
+export declare function applyFilters(value: any, filterExpression: string, context: Record<string, any>): any;
+/**
+ * Evaluate an expression within the given context
+ * @param {string} expression - The expression to evaluate
+ * @param {Record<string, any>} context - The context object containing variables
+ * @param {boolean} silent - Whether to silently handle errors (return undefined) or throw
+ * @returns The evaluated result
+ */
+export declare function evaluateExpression(expression: string, context: Record<string, any>, silent?: boolean): any;
+/**
+ * HTML unescape function to reverse escapeHtml
+ */
+export declare function unescapeHtml(html: string): string;