@tradik/xslt-processor 1.0.2 → 1.1.1

package/src/xslt/serializer/namespaces.js

@@ -0,0 +1,68 @@
+/**
+ * Namespace Declaration Tracking
+ *
+ * Computes the `xmlns` declarations an element has to carry so that every
+ * namespace is declared where it is first used and never twice.
+ */
+
+import { XMLNS_NAMESPACE, XML_NAMESPACE } from "./constants.js";
+
+/**
+ * Create the namespace scope in effect above the result tree root.
+ *
+ * @returns {Map<string, string>} Prefix (empty string for the default) to URI
+ */
+export function createNamespaceScope() {
+  return new Map([
+    ["", ""],
+    ["xml", XML_NAMESPACE],
+  ]);
+}
+
+/**
+ * Collect the namespace declarations an element must emit.
+ *
+ * @param {Element} element - Element being serialized
+ * @param {Map<string, string>} scope - Namespace scope inherited from the parent
+ * @returns {{declarations: Array<{prefix: string, uri: string}>, scope: Map<string, string>}}
+ *   The declarations to write and the scope in effect for the children
+ */
+export function collectNamespaceDeclarations(element, scope) {
+  const declarations = [];
+  let next = scope;
+
+  /**
+   * Record a declaration when the binding is not already in scope.
+   * @param {string} prefix - Namespace prefix, empty for the default namespace
+   * @param {string} uri - Namespace URI
+   * @returns {void}
+   */
+  const declare = (prefix, uri) => {
+    if (next.get(prefix) === uri) {
+      return;
+    }
+    if (next === scope) {
+      next = new Map(scope);
+    }
+    next.set(prefix, uri);
+    declarations.push({ prefix, uri });
+  };
+
+  declare(element.prefix || "", element.namespaceURI || "");
+
+  const attributes = Array.from(element.attributes || []);
+
+  for (const attribute of attributes) {
+    if (attribute.namespaceURI !== XMLNS_NAMESPACE && attribute.prefix) {
+      declare(attribute.prefix, attribute.namespaceURI || "");
+    }
+  }
+
+  for (const attribute of attributes) {
+    if (attribute.namespaceURI === XMLNS_NAMESPACE) {
+      declare(attribute.prefix ? attribute.localName : "", attribute.value);
+    }
+  }
+
+  return { declarations, scope: next };
+}

package/src/xslt/serializer/rawText.js

@@ -0,0 +1,41 @@
+/**
+ * Raw Text Registry
+ *
+ * Tracks the text nodes produced with `disable-output-escaping="yes"`
+ * (XSLT 1.0 section 16.4) so the serializers can emit them verbatim.
+ */
+
+/**
+ * Text nodes whose content must be written without escaping.
+ * @type {WeakSet<Node>}
+ */
+export const rawTextNodes = new WeakSet();
+
+/**
+ * Mark a text node as produced with `disable-output-escaping="yes"`.
+ *
+ * @param {Node|null} node - Text node to mark
+ * @returns {Node|null} The same node, for chaining
+ */
+export function markRawText(node) {
+  if (node) {
+    rawTextNodes.add(node);
+  }
+  return node;
+}
+
+/**
+ * Check whether a node must be serialized without output escaping.
+ *
+ * Both the registry and the legacy `_disableOutputEscaping` flag set by the
+ * XSLT engine are honored so that either marking mechanism works.
+ *
+ * @param {Node|null} node - Node to test
+ * @returns {boolean} True when the node content must be emitted raw
+ */
+export function isRawText(node) {
+  if (!node) {
+    return false;
+  }
+  return rawTextNodes.has(node) || node._disableOutputEscaping === true;
+}

package/src/xslt/serializer/settings.js

@@ -0,0 +1,103 @@
+/**
+ * Output Settings Resolution
+ *
+ * Normalizes the `xsl:output` settings collected by the XSLT engine into the
+ * shape the serializers consume (XSLT 1.0 section 16).
+ */
+
+import { NODE_TYPE } from "./constants.js";
+
+/**
+ * Test whether an `xsl:output` yes/no attribute is enabled.
+ *
+ * @param {string|boolean|undefined} value - Raw attribute value
+ * @returns {boolean} True when the value means "yes"
+ */
+function isYes(value) {
+  return value === true || String(value).toLowerCase() === "yes";
+}
+
+/**
+ * Convert a `cdata-section-elements` value into a lookup set.
+ *
+ * @param {string|string[]|undefined} value - Whitespace separated names or array
+ * @returns {Set<string>} Element names requiring CDATA sections
+ */
+function toNameSet(value) {
+  if (Array.isArray(value)) {
+    return new Set(value);
+  }
+  if (typeof value === "string") {
+    return new Set(value.split(/\s+/).filter(Boolean));
+  }
+  return new Set();
+}
+
+/**
+ * Find the first element node of a result tree.
+ *
+ * @param {Node|null} node - Document, fragment or element
+ * @returns {Element|null} The result document element, when there is one
+ */
+export function findRootElement(node) {
+  if (!node) {
+    return null;
+  }
+  if (node.nodeType === NODE_TYPE.ELEMENT) {
+    return node;
+  }
+  for (const child of node.childNodes || []) {
+    if (child.nodeType === NODE_TYPE.ELEMENT) {
+      return child;
+    }
+  }
+  return null;
+}
+
+/**
+ * Derive the default output method from the result tree.
+ *
+ * XSLT 1.0 section 16 defaults to `html` when the document element is `html`
+ * in no namespace, and to `xml` otherwise.
+ *
+ * @param {Node|null} node - Result tree root
+ * @returns {string} Either "html" or "xml"
+ */
+export function detectOutputMethod(node) {
+  const root = findRootElement(node);
+  const isHtmlRoot =
+    root && !root.namespaceURI && root.localName.toLowerCase() === "html";
+  return isHtmlRoot ? "html" : "xml";
+}
+
+/**
+ * Normalize an `xsl:output` settings object.
+ *
+ * An absent, empty or "auto" method triggers the XSLT 1.0 default method
+ * detection based on the result tree.
+ *
+ * @param {object|null} outputSettings - Raw settings from the XSLT engine
+ * @param {Node|null} node - Result tree used for default method detection
+ * @returns {object} Normalized settings consumed by the serializers
+ */
+export function resolveOutputSettings(outputSettings, node) {
+  const raw = outputSettings || {};
+  const declared = typeof raw.method === "string" ? raw.method.trim() : "";
+  const method =
+    declared && declared !== "auto"
+      ? declared.toLowerCase()
+      : detectOutputMethod(node);
+
+  return {
+    method,
+    version: raw.version || "1.0",
+    encoding: raw.encoding || "UTF-8",
+    standalone: raw.standalone || null,
+    indent: isYes(raw.indent),
+    omitXmlDeclaration: isYes(raw.omitXmlDeclaration),
+    doctypePublic: raw.doctypePublic || null,
+    doctypeSystem: raw.doctypeSystem || null,
+    mediaType: raw.mediaType || null,
+    cdataSectionElements: toNameSet(raw.cdataSectionElements),
+  };
+}

package/src/xslt/serializer/textSerializer.js

@@ -0,0 +1,29 @@
+/**
+ * Text Output Serializer
+ *
+ * Implements the `text` output method of XSLT 1.0 section 16.3: the result is
+ * the concatenation of every descendant character data node, unescaped.
+ */
+
+import { NODE_TYPE } from "./constants.js";
+
+/**
+ * Serialize a result tree with the text output method.
+ *
+ * @param {Node} node - Document, fragment, element or character data node
+ * @returns {string} Concatenated character data
+ */
+export function serializeText(node) {
+  if (
+    node.nodeType === NODE_TYPE.TEXT ||
+    node.nodeType === NODE_TYPE.CDATA_SECTION
+  ) {
+    return node.nodeValue || "";
+  }
+
+  let text = "";
+  for (const child of node.childNodes || []) {
+    text += serializeText(child);
+  }
+  return text;
+}

package/src/xslt/serializer/xmlSerializer.js

@@ -0,0 +1,127 @@
+/**
+ * XML Output Serializer
+ *
+ * Implements the `xml` output method of XSLT 1.0 section 16.1 and, with the
+ * `xhtml` option, the XHTML empty element convention. It is also the base of
+ * the html serializer, which overrides the dialect hooks defined here.
+ */
+
+import { TEXT_MODE, VOID_ELEMENTS } from "./constants.js";
+import { escapeXmlAttribute, escapeXmlText } from "./escape.js";
+import { BaseWriter } from "./baseWriter.js";
+
+export class XmlWriter extends BaseWriter {
+  /**
+   * Whether an XML declaration has to be written.
+   * @returns {boolean} True when the declaration is not omitted
+   */
+  get emitsXmlDeclaration() {
+    return !this.settings.omitXmlDeclaration;
+  }
+
+  /**
+   * Whether namespace declarations have to be written.
+   * @returns {boolean} Always true for XML output
+   */
+  get emitsNamespaces() {
+    return true;
+  }
+
+  /**
+   * Terminator of a processing instruction.
+   * @returns {string} The XML processing instruction terminator
+   */
+  get piTerminator() {
+    return "?>";
+  }
+
+  /**
+   * How a source CDATA section node has to be written.
+   * @returns {string} A {@link TEXT_MODE} value
+   */
+  get cdataNodeMode() {
+    return TEXT_MODE.CDATA;
+  }
+
+  /**
+   * Build the document type declaration for the xml output method.
+   *
+   * @param {Element|null} rootElement - Result document element
+   * @returns {string} Doctype markup, or an empty string when not applicable
+   */
+  doctypeMarkup(rootElement) {
+    const { doctypePublic, doctypeSystem } = this.settings;
+    if (!rootElement || !doctypeSystem) {
+      return "";
+    }
+
+    const name = rootElement.nodeName;
+    return doctypePublic
+      ? `<!DOCTYPE ${name} PUBLIC "${doctypePublic}" "${doctypeSystem}">`
+      : `<!DOCTYPE ${name} SYSTEM "${doctypeSystem}">`;
+  }
+
+  /**
+   * Determine how the character data children of an element are written.
+   *
+   * @param {Element} element - Parent element
+   * @returns {string} A {@link TEXT_MODE} value
+   */
+  childTextMode(element) {
+    const names = this.settings.cdataSectionElements;
+    return names.has(element.nodeName) || names.has(element.localName)
+      ? TEXT_MODE.CDATA
+      : TEXT_MODE.ESCAPE;
+  }
+
+  /**
+   * Whether the content of an element may be re-indented.
+   *
+   * @param {Element} _element - Element being inspected
+   * @returns {boolean} Always true for XML output
+   */
+  allowsIndentInside(_element) {
+    return true;
+  }
+
+  /**
+   * Build the markup closing an element that has no children.
+   *
+   * @param {Element} element - Empty element
+   * @param {string} _name - Element name as written
+   * @returns {string} Markup terminating the start tag
+   */
+  emptyElementMarkup(element, _name) {
+    return this.xhtml && this.isVoidElement(element) ? " />" : "/>";
+  }
+
+  /**
+   * Test whether an element is an HTML void element.
+   *
+   * @param {Element} element - Element to test
+   * @returns {boolean} True for void elements such as `br`
+   */
+  isVoidElement(element) {
+    return VOID_ELEMENTS.has(String(element.localName).toLowerCase());
+  }
+
+  /**
+   * Escape character data.
+   *
+   * @param {string} value - Text content
+   * @returns {string} Escaped text
+   */
+  escapeText(value) {
+    return escapeXmlText(value);
+  }
+
+  /**
+   * Escape an attribute value.
+   *
+   * @param {string} value - Attribute value
+   * @returns {string} Escaped value
+   */
+  escapeAttribute(value) {
+    return escapeXmlAttribute(value);
+  }
+}

package/src/xslt/serializer.js

@@ -0,0 +1,57 @@
+/**
+ * XSLT Output Serializer
+ *
+ * Serializes a result tree to a string honoring the `xsl:output` settings of
+ * the stylesheet (XSLT 1.0 section 16): output method, indentation, XML
+ * declaration, document type declaration, CDATA sections and
+ * `disable-output-escaping`.
+ *
+ * @example
+ * import { serializeResult } from './serializer.js';
+ *
+ * serializeResult(resultDocument, { method: 'xml', indent: 'yes' });
+ * // '<?xml version="1.0" encoding="UTF-8"?>\n<BAR>\n  <QUX/>\n</BAR>'
+ */
+
+import { resolveOutputSettings } from "./serializer/settings.js";
+import { XmlWriter } from "./serializer/xmlSerializer.js";
+import { HtmlWriter } from "./serializer/htmlSerializer.js";
+import { serializeText } from "./serializer/textSerializer.js";
+
+export { markRawText, isRawText, rawTextNodes } from "./serializer/rawText.js";
+export {
+  resolveOutputSettings,
+  detectOutputMethod,
+  findRootElement,
+} from "./serializer/settings.js";
+export { XmlWriter } from "./serializer/xmlSerializer.js";
+export { HtmlWriter } from "./serializer/htmlSerializer.js";
+export { serializeText } from "./serializer/textSerializer.js";
+
+/**
+ * Serialize a transformation result to a string.
+ *
+ * @param {Node|null} node - Result document, fragment or element
+ * @param {object} [outputSettings] - `xsl:output` settings, as collected by the
+ *   XSLT engine (`method`, `version`, `encoding`, `standalone`, `indent`,
+ *   `omitXmlDeclaration`, `doctypePublic`, `doctypeSystem`, `mediaType`,
+ *   `cdataSectionElements`)
+ * @returns {string} The serialized result, or an empty string for a null node
+ */
+export function serializeResult(node, outputSettings = {}) {
+  if (!node) {
+    return "";
+  }
+
+  const settings = resolveOutputSettings(outputSettings, node);
+
+  if (settings.method === "text") {
+    return serializeText(node);
+  }
+  if (settings.method === "html") {
+    return new HtmlWriter(settings).serialize(node);
+  }
+  return new XmlWriter(settings, {
+    xhtml: settings.method === "xhtml",
+  }).serialize(node);
+}

package/src/xslt/templatePriority.js

@@ -0,0 +1,45 @@
+/**
+ * Default template priorities (XSLT 1.0 section 5.5).
+ *
+ * A template rule without an explicit `priority` attribute gets a default
+ * priority derived from the shape of its match pattern. A union pattern is
+ * treated as a set of template rules, one per alternative, so each
+ * alternative must be assigned its own priority by the caller.
+ *
+ * @module xslt/templatePriority
+ */
+
+const NAME = String.raw`[A-Za-z_][\w.-]*`;
+const QNAME = `(?:${NAME}:)?${NAME}`;
+
+/** Patterns of the form `name`, `prefix:name`, `@name`, `@prefix:name`. */
+const QNAME_PATTERN = new RegExp(`^(?:child::|attribute::|@)?${QNAME}$`);
+
+/** Patterns of the form `prefix:*` or `@prefix:*`. */
+const PREFIX_WILDCARD_PATTERN = new RegExp(
+  String.raw`^(?:child::|attribute::|@)?${NAME}:\*$`,
+);
+
+/** Patterns of the form `*`, `@*`, `node()`, `text()`, `comment()`, `processing-instruction()`. */
+const NODE_TEST_PATTERN =
+  /^(?:child::|attribute::|@)?(?:\*|node\(\)|text\(\)|comment\(\)|processing-instruction\(\))$/;
+
+/** `processing-instruction('literal')` patterns. */
+const PI_LITERAL_PATTERN =
+  /^(?:child::)?processing-instruction\(\s*(?:"[^"]*"|'[^']*')\s*\)$/;
+
+/**
+ * Compute the default priority of a single (non-union) match pattern.
+ *
+ * @param {string|null|undefined} pattern - The match pattern, already trimmed
+ * @returns {number} -0.5, -0.25, 0 or 0.5 as defined by the specification
+ */
+export function calculatePriority(pattern) {
+  if (!pattern) return 0.5;
+
+  if (NODE_TEST_PATTERN.test(pattern)) return -0.5;
+  if (PREFIX_WILDCARD_PATTERN.test(pattern)) return -0.25;
+  if (QNAME_PATTERN.test(pattern) || PI_LITERAL_PATTERN.test(pattern)) return 0;
+
+  return 0.5;
+}

package/src/xslt/uri.js

@@ -0,0 +1,68 @@
+/**
+ * URI helpers for XSLT stylesheet and document resolution.
+ *
+ * Kept deliberately small and dependency free: the engine only needs enough
+ * URI arithmetic to turn a relative `href` into something a host supplied
+ * loader can resolve, plus fragment removal for the `document()` function.
+ */
+
+"use strict";
+
+/** Matches an absolute URI such as `http://`, `https://` or `file://`. */
+const ABSOLUTE_URI_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+
+/**
+ * Resolve a possibly relative URI against a base URI.
+ *
+ * Absolute URIs (with a scheme) and root relative URIs (starting with `/`)
+ * are returned untouched, as is any URI when no base is available.
+ *
+ * @param {string} href - The URI to resolve
+ * @param {string} [baseUri] - The base URI, typically the stylesheet location
+ * @returns {string} The resolved URI
+ *
+ * @example
+ * resolveUri('common.xsl', '/styles/main.xsl'); // '/styles/common.xsl'
+ */
+export function resolveUri(href, baseUri) {
+  if (!href) return href;
+  if (!baseUri || isAbsoluteUri(href) || href.startsWith("/")) {
+    return href;
+  }
+
+  const lastSlash = baseUri.lastIndexOf("/");
+  const baseDir = lastSlash >= 0 ? baseUri.substring(0, lastSlash + 1) : "";
+
+  return baseDir + href;
+}
+
+/**
+ * Check whether a URI is absolute (has a scheme).
+ *
+ * @param {string} uri - The URI to inspect
+ * @returns {boolean} True when the URI carries a scheme
+ *
+ * @example
+ * isAbsoluteUri('https://example.com/a.xml'); // true
+ */
+export function isAbsoluteUri(uri) {
+  return ABSOLUTE_URI_PATTERN.test(uri);
+}
+
+/**
+ * Remove a fragment identifier from a URI.
+ *
+ * XSLT 1.0 leaves the meaning of fragment identifiers passed to `document()`
+ * implementation defined; this processor ignores them.
+ *
+ * @param {string} uri - The URI, possibly carrying a `#fragment`
+ * @returns {string} The URI without its fragment
+ *
+ * @example
+ * stripFragment('data.xml#section'); // 'data.xml'
+ */
+export function stripFragment(uri) {
+  if (typeof uri !== "string") return "";
+  const hash = uri.indexOf("#");
+  return hash === -1 ? uri : uri.substring(0, hash);
+}