@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/serialize/markup/content.js

@@ -0,0 +1,74 @@
+/**
+ * Helpers of the markup writer about content: the children of an element
+ * as written, whitespace, namespace URIs in declarations, and the check
+ * that a document type or standalone declaration has a document to go
+ * with.
+ *
+ * @module @tradik/xslt3/serialize/markup/content
+ */
+
+import { XPathError } from "../../errors.js";
+import { isContentTypeMeta } from "./prolog.js";
+
+/**
+ * @param {string} text
+ * @returns {boolean} whether the text is XML whitespace only
+ */
+export const isWhitespace = (text) => /^[ \t\r\n]*$/.test(text);
+
+const URI_ESCAPES = { "&": "&amp;", "<": "&lt;", '"': "&quot;" };
+
+/**
+ * @param {string} uri - A namespace URI
+ * @returns {string} the URI escaped for an attribute value
+ */
+export const escapeNamespaceUri = (uri) =>
+  uri.replace(/[&<"]/g, (c) => URI_ESCAPES[c]);
+
+/**
+ * The children of an element as written: adjacent character data merged
+ * into strings, other nodes kept.
+ * @param {Element} element
+ * @param {boolean} dropMeta - Leave out content type meta elements
+ * @returns {Array<string|Node>}
+ */
+export function childList(element, dropMeta) {
+  const list = [];
+  for (let child = element.firstChild; child; child = child.nextSibling) {
+    const type = child.nodeType;
+    if (type === 3 || type === 4) {
+      const last = list.length - 1;
+      if (typeof list[last] === "string") list[last] += child.nodeValue;
+      else if (child.nodeValue) list.push(child.nodeValue);
+    } else if (type === 1 || type === 7 || type === 8) {
+      if (!(dropMeta && isContentTypeMeta(child))) list.push(child);
+    }
+  }
+  return list;
+}
+
+/**
+ * A document type declaration or a standalone declaration needs a
+ * well-formed document: one element and no text at the top level.
+ * @param {Array<string|Node>} entries
+ * @param {import("../params/settings.js").Settings} settings
+ * @throws {XPathError} SEPM0004 when the content is not a document
+ */
+export function checkDocument(entries, settings) {
+  const { method, doctypeSystem, standalone } = settings;
+  if (
+    method === "html" ||
+    (doctypeSystem === undefined && standalone === "omit")
+  ) {
+    return;
+  }
+  const elements = entries.filter(
+    (e) => typeof e !== "string" && e.nodeType === 1,
+  );
+  if (elements.length > 1 || entries.some((e) => typeof e === "string")) {
+    throw new XPathError(
+      "SEPM0004",
+      "doctype-system and standalone need a single element and no text at the top level",
+    );
+  }
+}

package/src/serialize/markup/dialect.js

@@ -0,0 +1,178 @@
+/**
+ * The differences between the xml, xhtml and html output methods
+ * (Serialization 3.1 sections 5, 6 and 7) for the markup writer: which
+ * elements are HTML elements, how empty elements, attributes and
+ * processing instructions are written, where CDATA sections, raw text and
+ * indentation are allowed.
+ *
+ * HTML elements are, for the html method, those in no namespace (and with
+ * HTML5 those in the XHTML namespace); for the xhtml method, those in the
+ * XHTML namespace (and with HTML5 those in no namespace). HTML5 output
+ * writes XHTML, SVG and MathML elements without a prefix.
+ *
+ * @module @tradik/xslt3/serialize/markup/dialect
+ */
+
+import { XPathError } from "../../errors.js";
+import { percentEncode } from "../../functions/uri.js";
+import { clarkName } from "../params/values.js";
+import {
+  BOOLEAN_ATTRIBUTES,
+  HTML5_UNPREFIXED,
+  INLINE_ELEMENTS,
+  isUriAttribute,
+  PRESERVING_ELEMENTS,
+  RAW_TEXT_ELEMENTS,
+  VOID_ELEMENTS,
+  XHTML_NAMESPACE,
+} from "./htmlData.js";
+
+/** escape-html-uri: %-escapes all but printable ASCII. */
+const escapeUri = (value) =>
+  percentEncode(value.normalize("NFC"), (cp) => cp >= 32 && cp < 127);
+
+/**
+ * Lower-cases the local names of a set of Clark names.
+ * @param {Set<string>} names
+ * @returns {Set<string>}
+ */
+const lowerCased = (names) =>
+  new Set([...names].map((n) => n.replace(/\}.*$/, (s) => s.toLowerCase())));
+
+/** Output method rules for the markup writer. */
+export class Dialect {
+  /**
+   * @param {import("../params/settings.js").Settings} settings
+   */
+  constructor(settings) {
+    this.settings = settings;
+    this.method = settings.method;
+    this.html = this.method === "html";
+    this.htmlLike = this.html || this.method === "xhtml";
+    this.html5 = this.htmlLike && settings.htmlVersion === 5;
+    this.unprefixed = this.html5 ? HTML5_UNPREFIXED : new Set();
+    this.voids = VOID_ELEMENTS[settings.htmlVersion];
+    const names = (set) => (this.html ? lowerCased(set) : set);
+    this.cdataElements = names(settings.cdataSectionElements);
+    this.suppressed = names(settings.suppressIndentation);
+  }
+
+  /**
+   * Describes an element for the other hooks.
+   * @param {Element} element
+   * @param {import("./namespaces.js").FixedElement} fixed
+   * @returns {{fixed: object, isHtml: boolean, lower: string, key: string}}
+   */
+  describe(element, fixed) {
+    const ns = fixed.namespaceURI;
+    const local = element.localName ?? element.nodeName;
+    const lower = local.toLowerCase();
+    const primary = this.html ? "" : XHTML_NAMESPACE;
+    const secondary = this.html ? XHTML_NAMESPACE : "";
+    const isHtml =
+      this.htmlLike && (ns === primary || (this.html5 && ns === secondary));
+    const key = clarkName(ns, this.html ? lower : local);
+    return { fixed, isHtml, lower, key };
+  }
+
+  /**
+   * @param {object} info - From {@link Dialect#describe}
+   * @returns {string} the markup closing an empty element's start tag
+   */
+  emptyElement(info) {
+    if (!this.htmlLike) return "/>";
+    const isVoid = info.isHtml && this.voids.has(info.lower);
+    if (this.html) {
+      if (isVoid) return ">";
+      return info.isHtml ? `></${info.fixed.name}>` : "/>";
+    }
+    return isVoid ? " />" : `></${info.fixed.name}>`;
+  }
+
+  /**
+   * @param {object} info - The element
+   * @param {{name: string, localName: string, namespaceURI: string, value: string}} attribute
+   * @param {import("../output/expander.js").Expander} expander
+   * @returns {string} the attribute markup, with its leading space
+   */
+  attribute(info, attribute, expander) {
+    let { value } = attribute;
+    if (info.isHtml && attribute.namespaceURI === "") {
+      const lower = attribute.localName.toLowerCase();
+      if (
+        this.html &&
+        BOOLEAN_ATTRIBUTES.has(lower) &&
+        value.toLowerCase() === lower
+      ) {
+        return ` ${attribute.name}`;
+      }
+      if (
+        this.settings.escapeUriAttributes &&
+        isUriAttribute(info.lower, lower)
+      ) {
+        value = escapeUri(value);
+      }
+    }
+    return ` ${attribute.name}="${expander.attribute(value)}"`;
+  }
+
+  /**
+   * How the text children of an element are written.
+   * @param {object} info
+   * @returns {"escape"|"cdata"|"raw"}
+   */
+  textMode(info) {
+    if (this.html && info.isHtml) {
+      return RAW_TEXT_ELEMENTS.has(info.lower) ? "raw" : "escape";
+    }
+    return this.cdataElements.has(info.key) ? "cdata" : "escape";
+  }
+
+  /**
+   * Whether indentation is suppressed inside an element and its
+   * descendants.
+   * @param {object} info
+   * @returns {boolean}
+   */
+  suppressesIndent(info) {
+    return (
+      this.suppressed.has(info.key) ||
+      (info.isHtml && PRESERVING_ELEMENTS.has(info.lower))
+    );
+  }
+
+  /**
+   * Whether the children (elements, comments, processing instructions)
+   * of an element may be indented: not when one is an inline element.
+   * @param {Array<string|Node>} children
+   * @returns {boolean}
+   */
+  allowsIndent(children) {
+    if (!this.htmlLike) return true;
+    return !children.some(
+      (child) =>
+        child.nodeType === 1 &&
+        INLINE_ELEMENTS.has((child.localName ?? child.nodeName).toLowerCase()),
+    );
+  }
+
+  /**
+   * @param {ProcessingInstruction} node
+   * @param {import("../output/expander.js").Expander} expander
+   * @returns {string} the processing instruction markup
+   * @throws {XPathError} SERE0015 for ">" in HTML processing instructions
+   */
+  processingInstruction(node, expander) {
+    const data = expander.unescaped(node.nodeValue ?? "");
+    const target = node.target ?? node.nodeName;
+    const space = data ? " " : "";
+    if (!this.html) return `<?${target}${space}${data}?>`;
+    if (data.includes(">")) {
+      throw new XPathError(
+        "SERE0015",
+        "A processing instruction in HTML output cannot contain >",
+      );
+    }
+    return `<?${target}${space}${data}>`;
+  }
+}

package/src/serialize/markup/htmlData.js

@@ -0,0 +1,70 @@
+/**
+ * What the html and xhtml output methods know about HTML elements and
+ * attributes (Serialization 3.1 sections 6 and 7, HTML 4.01 and the HTML
+ * Living Standard). Names are compared in lower case.
+ *
+ * @module @tradik/xslt3/serialize/markup/htmlData
+ */
+
+/** The XHTML namespace. */
+export const XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+/** Namespaces whose elements HTML5 output writes without a prefix. */
+export const HTML5_UNPREFIXED = new Set([
+  XHTML_NAMESPACE,
+  "http://www.w3.org/2000/svg",
+  "http://www.w3.org/1998/Math/MathML",
+]);
+
+const words = (text) => new Set(text.split(" "));
+
+/** Elements with no content (void elements), by HTML version. */
+export const VOID_ELEMENTS = {
+  4: words(
+    "area base basefont br col embed frame hr img input isindex link meta param",
+  ),
+  5: words(
+    "area base br col embed hr img input keygen link meta param source track wbr",
+  ),
+};
+
+/** Elements whose content is written without escaping (html method). */
+export const RAW_TEXT_ELEMENTS = words("script style");
+
+/** Elements inside which no whitespace is added. */
+export const PRESERVING_ELEMENTS = words("pre script style textarea title");
+
+/**
+ * Phrasing (inline) elements: whitespace added around them would show, so
+ * their parents are not indented.
+ */
+export const INLINE_ELEMENTS = words(
+  "a abbr acronym audio b bdi bdo big br button canvas cite code data " +
+    "datalist del dfn em embed font i iframe img input ins kbd label map " +
+    "mark math meter noscript object output picture progress q ruby s samp " +
+    "select slot small span strike strong sub sup svg template textarea " +
+    "time tt u var video wbr",
+);
+
+/** Attributes written minimized when their value is their name. */
+export const BOOLEAN_ATTRIBUTES = words(
+  "allowfullscreen async autofocus autoplay checked compact controls " +
+    "declare default defer disabled formnovalidate hidden inert ismap " +
+    "itemscope loop multiple muted nohref noresize noshade novalidate " +
+    "nowrap open playsinline readonly required reversed scoped seamless " +
+    "selected typemustmatch",
+);
+
+/** Attributes holding URIs, %-escaped with escape-uri-attributes. */
+export const URI_ATTRIBUTES = words(
+  "action archive background cite classid codebase data datasrc " +
+    "formaction href icon longdesc manifest poster profile src usemap",
+);
+
+/**
+ * Whether an attribute holds a URI (`name` only on `a`).
+ * @param {string} element - Element local name, lower case
+ * @param {string} attribute - Attribute local name, lower case
+ * @returns {boolean}
+ */
+export const isUriAttribute = (element, attribute) =>
+  URI_ATTRIBUTES.has(attribute) || (attribute === "name" && element === "a");

package/src/serialize/markup/namespaces.js

@@ -0,0 +1,145 @@
+/**
+ * Namespace fixup: the namespace declarations written on an element so
+ * that its name, its attributes' names and its in-scope namespaces are
+ * declared, whether or not the DOM holds `xmlns` attributes for them
+ * (createElementNS and setAttributeNS add none). A namespaced attribute
+ * without a usable prefix gets one (an existing one for its namespace, or
+ * ns0, ns1, ...).
+ *
+ * A scope is a Map from prefix ("" for the default namespace) to URI,
+ * shared by the elements that declare nothing and copied on change.
+ *
+ * @module @tradik/xslt3/serialize/markup/namespaces
+ */
+
+import {
+  isNamespaceDeclaration,
+  XMLNS_NAMESPACE,
+} from "../../xpath/eval/domNodes.js";
+import {
+  inScopeNamespaces,
+  XML_NAMESPACE,
+} from "../../xpath/eval/namespaceNodes.js";
+
+export { XML_NAMESPACE };
+
+/**
+ * @typedef {object} FixedElement
+ * @property {string} name - Output name of the element
+ * @property {string} namespaceURI - Its namespace, "" for none
+ * @property {Array<[string, string]>} declarations - [prefix, URI] to declare
+ * @property {Array<{name: string, localName: string, namespaceURI: string, value: string}>} attributes
+ * @property {Map<string, string>} scope - Scope of the children
+ */
+
+/**
+ * @typedef {object} FixupOptions
+ * @property {boolean} top - The element is the first one written of its
+ *   tree: its inherited namespaces are declared too
+ * @property {Set<string>} unprefixed - Namespaces whose elements are
+ *   written without a prefix (HTML5 prefix normalization)
+ * @property {boolean} undeclare - Write `xmlns:p=""` undeclarations (XML
+ *   1.1 with undeclare-prefixes)
+ */
+
+/**
+ * Bindings an element asks for, in order: inherited ones (top element),
+ * its own declarations, its name.
+ * @param {Element} element
+ * @param {string} prefix - Output prefix of the element
+ * @param {FixupOptions} options
+ * @returns {Map<string, string>}
+ */
+function wantedBindings(element, prefix, options) {
+  const wanted = new Map();
+  const add = (p, uri) => {
+    if (p === "xml") return;
+    if (p !== "" && options.unprefixed.has(uri)) return;
+    wanted.set(p, uri);
+  };
+  if (options.top) {
+    for (const [p, uri] of inScopeNamespaces(element)) {
+      if (uri !== "" || p === "") add(p, uri);
+    }
+  }
+  for (const attribute of element.attributes) {
+    if (isNamespaceDeclaration(attribute)) {
+      const name = attribute.name;
+      add(name === "xmlns" ? "" : name.slice(6), attribute.value);
+    }
+  }
+  wanted.set(prefix, element.namespaceURI ?? "");
+  return wanted;
+}
+
+/**
+ * Chooses the prefix of a namespaced attribute.
+ * @param {Attr} attribute
+ * @param {string} uri - Its namespace
+ * @param {(prefix: string) => string|undefined} bound - Current binding
+ * @param {Map<string, string>} wanted
+ * @param {Map<string, string>} scope - Scope of the parent
+ * @returns {string} the prefix
+ */
+function attributePrefix(attribute, uri, bound, wanted, scope) {
+  const own = attribute.prefix ?? "";
+  if (own !== "" && (bound(own) === undefined || bound(own) === uri)) {
+    return own;
+  }
+  for (const map of [wanted, scope]) {
+    for (const [p, u] of map) {
+      if (p !== "" && u === uri && bound(p) === uri) return p;
+    }
+  }
+  let n = 0;
+  while (bound(`ns${n}`) !== undefined) n++;
+  return `ns${n}`;
+}
+
+/**
+ * Computes the names and the namespace declarations of an element.
+ * @param {Element} element
+ * @param {Map<string, string>} scope - Scope of the parent
+ * @param {FixupOptions} options
+ * @returns {FixedElement}
+ */
+export function fixupElement(element, scope, options) {
+  const namespaceURI = element.namespaceURI ?? "";
+  const localName = element.localName ?? element.nodeName;
+  const prefix = options.unprefixed.has(namespaceURI)
+    ? ""
+    : (element.prefix ?? "");
+  const wanted = wantedBindings(element, prefix, options);
+  const bound = (p) =>
+    wanted.has(p) ? wanted.get(p) : (scope.get(p) ?? (p ? undefined : ""));
+  const attributes = [];
+  for (const attribute of element.attributes) {
+    if (isNamespaceDeclaration(attribute)) continue;
+    const uri = attribute.namespaceURI ?? "";
+    const local = attribute.localName ?? attribute.name;
+    let name = local;
+    if (uri === XML_NAMESPACE) {
+      name = `xml:${local}`;
+    } else if (uri !== "" && uri !== XMLNS_NAMESPACE) {
+      const p = attributePrefix(attribute, uri, bound, wanted, scope);
+      if (bound(p) !== uri) wanted.set(p, uri);
+      name = `${p}:${local}`;
+    }
+    const value = attribute.value;
+    attributes.push({ name, localName: local, namespaceURI: uri, value });
+  }
+  const declarations = [];
+  let childScope = scope;
+  for (const [p, uri] of wanted) {
+    const current = scope.get(p) ?? (p ? undefined : "");
+    if (current === uri) continue;
+    if (uri === "" && p !== "") {
+      if (!options.undeclare || current === undefined) continue;
+    }
+    declarations.push([p, uri]);
+    if (childScope === scope) childScope = new Map(scope);
+    childScope.set(p, uri);
+  }
+  const name = prefix ? `${prefix}:${localName}` : localName;
+  return { name, namespaceURI, declarations, attributes, scope: childScope };
+}

package/src/serialize/markup/prolog.js

@@ -0,0 +1,91 @@
+/**
+ * Markup the serializer adds on its own: the XML declaration, the
+ * document type declaration and the content type `meta` element of
+ * include-content-type (Serialization 3.1 sections 5.1, 6, 7.1 and 7.4).
+ *
+ * @module @tradik/xslt3/serialize/markup/prolog
+ */
+
+/**
+ * @param {import("../params/settings.js").Settings} settings
+ * @returns {string} the XML declaration, "" when omitted or not XML
+ */
+export function xmlDeclaration(settings) {
+  const { method, omitXmlDeclaration, version, encoding, standalone } =
+    settings;
+  if (omitXmlDeclaration || (method !== "xml" && method !== "xhtml")) {
+    return "";
+  }
+  const standalonePart =
+    standalone === "omit" ? "" : ` standalone="${standalone}"`;
+  return `<?xml version="${version}" encoding="${encoding.name}"${standalonePart}?>`;
+}
+
+/**
+ * A system literal: in double quotes, or single quotes when it holds one.
+ * @param {string} value
+ * @returns {string}
+ */
+const quoted = (value) => (value.includes('"') ? `'${value}'` : `"${value}"`);
+
+/**
+ * The document type declaration written before the first element.
+ * @param {import("../params/settings.js").Settings} settings
+ * @param {string} name - Output name of the first element
+ * @returns {string} the declaration, "" for none
+ */
+export function doctype(settings, name) {
+  const { method, htmlVersion } = settings;
+  // a zero-length doctype-system or doctype-public is absent (erratum E31)
+  const doctypePublic = settings.doctypePublic || undefined;
+  const doctypeSystem =
+    settings.doctypeSystem === undefined || settings.doctypeSystem === ""
+      ? undefined
+      : quoted(settings.doctypeSystem);
+  const html5Default =
+    htmlVersion === 5 && name.replace(/^.*:/, "").toLowerCase() === "html";
+  if (method === "html") {
+    if (doctypePublic !== undefined) {
+      const system = doctypeSystem === undefined ? "" : ` ${doctypeSystem}`;
+      return `<!DOCTYPE html PUBLIC "${doctypePublic}"${system}>`;
+    }
+    if (doctypeSystem !== undefined) {
+      return `<!DOCTYPE html SYSTEM ${doctypeSystem}>`;
+    }
+    return html5Default ? "<!DOCTYPE html>" : "";
+  }
+  if (doctypeSystem !== undefined) {
+    const external =
+      doctypePublic === undefined
+        ? `SYSTEM ${doctypeSystem}`
+        : `PUBLIC "${doctypePublic}" ${doctypeSystem}`;
+    return `<!DOCTYPE ${name} ${external}>`;
+  }
+  // xhtml with HTML5: the element name as written
+  return method === "xhtml" && html5Default
+    ? `<!DOCTYPE ${name.replace(/^.*:/, "")}>`
+    : "";
+}
+
+/**
+ * @param {import("../params/settings.js").Settings} settings
+ * @returns {string} the meta element declaring the content type
+ */
+export function contentTypeMeta(settings) {
+  const end = settings.method === "html" ? ">" : " />";
+  const content = `${settings.mediaType}; charset=${settings.encoding.name}`;
+  return `<meta http-equiv="Content-Type" content="${content}"${end}`;
+}
+
+/**
+ * Whether a node is a meta element declaring the content type (replaced
+ * by the serializer's own with include-content-type).
+ * @param {Node} node
+ * @returns {boolean}
+ */
+export function isContentTypeMeta(node) {
+  if (node.nodeType !== 1) return false;
+  if ((node.localName ?? node.nodeName).toLowerCase() !== "meta") return false;
+  const value = node.getAttribute("http-equiv");
+  return typeof value === "string" && value.toLowerCase() === "content-type";
+}