jtlt 0.2.0 → 0.3.0

package/src/DOMJoiningTransformer.js

@@ -1,6 +1,12 @@
 import * as JHTML from 'jhtml';
 import AbstractJoiningTransformer from './AbstractJoiningTransformer.js';
 
+/**
+ * @callback SimpleCallback
+ * @this {DOMJoiningTransformer}
+ * @returns {void}
+ */
+
 /**
  * Joining transformer that accumulates into a DOM tree.
  *
@@ -8,17 +14,21 @@ import AbstractJoiningTransformer from './AbstractJoiningTransformer.js';
  * It expects templates to build DOM nodes explicitly (e.g., via element(),
  * attribute(), and text()), though string/number/boolean will append text
  * nodes for convenience.
+ * @extends {AbstractJoiningTransformer<"dom">}
  */
 class DOMJoiningTransformer extends AbstractJoiningTransformer {
   /**
    * @param {DocumentFragment|Element} o - Initial DOM node
-   * @param {object} cfg - Configuration object
-   * @param {object} [cfg.document] - Document object
+   * @param {import('./AbstractJoiningTransformer.js').
+   *   DOMJoiningTransformerConfig} cfg - Configuration object
    */
   constructor (o, cfg) {
-    super(cfg); // Include this in any subclass of AbstractJoiningTransformer
-    this._dom = o ||
-    /** @type {any} */ (cfg).document.createDocumentFragment();
+    super(cfg);
+    this._dom = o || cfg.document.createDocumentFragment();
+    /** @type {XMLDocument[]} */
+    this._docs = [];
+    /** @type {Array<{href: string, document: XMLDocument, format?: string}>} */
+    this._resultDocuments = [];
   }
 
   /**
@@ -38,32 +48,36 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
   }
 
   /**
-   * @returns {DocumentFragment|Element}
+   * @returns {DocumentFragment|Element|XMLDocument[]}
    */
   get () {
+    if (this._cfg.exposeDocuments) {
+      return this._docs;
+    }
     return this._dom;
   }
 
   /**
    * @param {string} prop - Property name
-   * @param {*} val - Property value
+   * @param {any} val - Property value
    * @returns {void}
    */
-  // eslint-disable-next-line class-methods-use-this -- Incomplete?
   propValue (prop, val) {
-    //
+    // @ts-expect-error Ok
+    this._dom[prop] = val;
   }
 
   /**
-   * @param {object} obj - Object to serialize
-   * @param {Function} [cb] - Callback function.
+   * @param {Record<string, unknown>} obj - Object to serialize
+   * @param {(this: DOMJoiningTransformer) => void} [cb] - Callback function.
    * @param {any[]} [usePropertySets] - Property sets to use
-   * @param {object} [propSets] - Additional property sets
+   * @param {Record<string, unknown>} [propSets] - Additional property sets
    * @returns {DOMJoiningTransformer}
    */
   object (obj, cb, usePropertySets, propSets) {
     this._requireSameChildren('dom', 'object');
-    if (this._cfg && /** @type {any} */ (this._cfg).JHTMLForJSON) {
+    if (this._cfg.JHTMLForJSON) {
+      Object.assign(obj, propSets);
       this.append(JHTML.toJHTMLDOM(/** @type {any} */ (obj)));
     } else {
       // Todo: set current position and deal with children
@@ -74,12 +88,12 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
 
   /**
    * @param {any[]|Element} arr
-   * @param {Function} [cb] - Callback function
+   * @param {(this: DOMJoiningTransformer) => void} [cb] - Callback function
    * @returns {DOMJoiningTransformer}
    */
   array (arr, cb) {
     this._requireSameChildren('dom', 'array');
-    if (this._cfg && /** @type {any} */ (this._cfg).JHTMLForJSON) {
+    if (this._cfg.JHTMLForJSON) {
       this.append(JHTML.toJHTMLDOM(/** @type {any} */ (arr)));
     } else {
       // Todo: set current position and deal with children
@@ -90,7 +104,8 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
 
   /**
    * @param {string} str - String value
-   * @param {Function} cb - Callback function (unused)
+   * @param {(this: DOMJoiningTransformer) => void} [cb] - Callback
+   *   function (unused)
    * @returns {DOMJoiningTransformer}
    */
   string (str, cb) {
@@ -129,7 +144,7 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
    * @returns {DOMJoiningTransformer}
    */
   undefined () {
-    if (this._cfg && /** @type {any} */ (this._cfg).mode !== 'JavaScript') {
+    if (this._cfg.mode !== 'JavaScript') {
       throw new Error(
         'undefined is not allowed unless added in JavaScript mode'
       );
@@ -143,7 +158,7 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
    * @returns {DOMJoiningTransformer}
    */
   nonfiniteNumber (num) {
-    if (this._cfg && /** @type {any} */ (this._cfg).mode !== 'JavaScript') {
+    if (this._cfg.mode !== 'JavaScript') {
       throw new Error(
         'Non-finite numbers are not allowed unless added in JavaScript mode'
       );
@@ -153,11 +168,11 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
   }
 
   /**
-   * @param {Function} func - Function to stringify
+   * @param {(...args: any[]) => any} func - Function to stringify
    * @returns {DOMJoiningTransformer}
    */
   function (func) {
-    if (this._cfg && /** @type {any} */ (this._cfg).mode !== 'JavaScript') {
+    if (this._cfg.mode !== 'JavaScript') {
       throw new Error(
         'function is not allowed unless added in JavaScript mode'
       );
@@ -167,9 +182,23 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
   }
 
   /**
-   * @param {string} elName - Element name
-   * @param {object} [atts] - Attributes object
-   * @param {Function} [cb] - Callback function
+   * @param {import('./StringJoiningTransformer.js').OutputConfig} cfg
+   * @returns {DOMJoiningTransformer}
+   */
+  output (cfg) {
+    // We wait until first element is set in `element()` to add
+    //   XML declaration and DOCTYPE as latter depends on root element
+    this._outputConfig = cfg;
+
+    // Use for file extension if making downloadable?
+    this.mediaType = cfg.mediaType;
+    return this;
+  }
+
+  /**
+   * @param {Element|string} elName - Element name
+   * @param {Record<string, string>} [atts] - Attributes object
+   * @param {(this: DOMJoiningTransformer) => void} [cb] - Callback function
    * @returns {DOMJoiningTransformer}
    */
   element (elName, atts, cb) {
@@ -179,13 +208,100 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
     // Todo: allow separate XML DOM one with XML String and hXML conversions
     //   (HTML to XHTML is inevitably safe?)
 
-    const el = this._cfg &&
-    /** @type {any} */ (this._cfg).document.createElement(elName);
+    if (!this.root && this._outputConfig) {
+      this.root = elName;
+
+      const elementName = typeof elName === 'string'
+        ? elName
+        : elName.localName;
+
+      const {
+        omitXmlDeclaration, doctypePublic, doctypeSystem, method
+      /* c8 ignore start -- outputConfig ?? attribution issue */
+      } = this._outputConfig ?? {};
+      /* c8 ignore stop */
+
+      /* c8 ignore start -- namespace/prefix detection branches */
+      const dtd = this._cfg.document.implementation.createDocumentType(
+        elementName,
+        doctypePublic ?? '',
+        doctypeSystem ?? ''
+      );
+
+      let xmlns;
+      if (elementName.includes(':')) {
+        const prefix = elementName.slice(0, elementName.indexOf(':'));
+        xmlns = atts?.[prefix];
+      } else {
+        ({xmlns} = atts ?? {});
+      }
+
+      const doc = /** @type {XMLDocument} */ (
+        this._cfg.document.implementation.createDocument(
+          xmlns ?? null,
+          elementName,
+          dtd
+        )
+      );
+      /* c8 ignore stop */
+
+      /* c8 ignore start -- third OR condition short-circuits */
+      if (!omitXmlDeclaration && (
+        method === 'xml' || method === 'xhtml' || omitXmlDeclaration === false)
+      ) {
+        const {version, encoding, standalone} = this._outputConfig ?? {};
+
+        const xmlDeclarationData = `${
+          version ? ` version="${version}"` : ''
+        }${
+          encoding ? ` encoding="${encoding}"` : ''
+        }${
+          standalone ? ` standalone="yes"` : ''
+        }`.slice(1);
+
+        const xmlDecl = doc.createProcessingInstruction(
+          'xml', xmlDeclarationData
+        );
+        doc.insertBefore(
+          xmlDecl,
+          doc.firstChild
+        );
+      }
+      /* c8 ignore stop */
+
+      // Push the document to _docs
+      this._docs.push(doc);
+
+      // Use the document's root element
+      const el = doc.documentElement;
+
+      for (const att in atts) {
+        if (Object.hasOwn(atts, att)) {
+          el.setAttribute(att, atts[att]);
+        }
+      }
+
+      const oldDOM = this._dom;
+      this._dom = el;
+
+      if (cb) {
+        cb.call(this);
+      }
+      this._dom = oldDOM;
+
+      return this;
+    }
+
+    // Non-root elements
+    const el = elName && typeof elName === 'object'
+      ? elName
+      : /** @type {Element} */ (
+        this._cfg.document.createElement(elName)
+      );
+
     for (const att in atts) {
       if (Object.hasOwn(atts, att)) {
-        /** @type {Record<string, any>} */
-        const attsObj = /** @type {any} */ (atts);
-        el.setAttribute(att, attsObj[att]);
+        el.setAttribute(att, atts[att]);
       }
     }
     this.append(el);
@@ -193,6 +309,7 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
     const oldDOM = this._dom;
 
     this._dom = el;
+
     if (cb) {
       cb.call(this);
     }
@@ -224,6 +341,40 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
     return this;
   }
 
+  /**
+   * @param {string} text
+   * @returns {DOMJoiningTransformer}}
+   */
+  comment (text) {
+    if (!this._dom || typeof this._dom !== 'object' ||
+        (![1, 9, 11].includes(this._dom.nodeType))) {
+      throw new Error(
+        'You may only set a comment on a document, fragment, or element'
+      );
+    }
+    this._dom.append((this._dom.ownerDocument).createComment(text));
+    return this;
+  }
+
+  /**
+   * @param {string} target
+   * @param {string} data
+   * @returns {DOMJoiningTransformer}}
+   */
+  processingInstruction (target, data) {
+    if (!this._dom || typeof this._dom !== 'object' ||
+        (![1, 9, 11].includes(this._dom.nodeType))) {
+      throw new Error(
+        'You may only set a processing instruction on a ' +
+          'document, fragment, or element'
+      );
+    }
+    this._dom.append((this._dom.ownerDocument).createProcessingInstruction(
+      target, data
+    ));
+    return this;
+  }
+
   /**
    * @param {string} str
    * @returns {DOMJoiningTransformer}
@@ -232,6 +383,102 @@ class DOMJoiningTransformer extends AbstractJoiningTransformer {
     this.text(str);
     return this;
   }
+
+  /**
+   * Creates a new XML document and executes a callback in its context.
+   * Similar to XSLT's xsl:document, this allows templates to generate
+   * multiple output documents. The created document is pushed to this._docs
+   * and will be included in the result when exposeDocuments is true.
+   *
+   * @param {(this: DOMJoiningTransformer) => void} cb
+   *   Callback that builds the document content
+   * @param {import('./StringJoiningTransformer.js').OutputConfig} [cfg]
+   *   Output configuration for the document (encoding, doctype, etc.)
+   * @returns {DOMJoiningTransformer}
+   */
+  document (cb, cfg) {
+    // Save current state
+    /** @type {any} */
+    const oldRoot = this.root;
+    /** @type {any} */
+    const oldOutputConfig = this._outputConfig;
+    const oldDOM = this._dom;
+
+    // Reset state for new document
+    this.root = undefined;
+    /** @type {any} */
+    this._outputConfig = cfg;
+
+    // Create a new document fragment as the working context
+    const fragment = this._cfg.document.createDocumentFragment();
+    this._dom = fragment;
+
+    // Execute callback to build document content
+    cb.call(this);
+
+    // Restore previous state
+    this.root = oldRoot;
+    this._outputConfig = oldOutputConfig;
+    this._dom = oldDOM;
+
+    return this;
+  }
+
+  /**
+   * Creates a new result document with metadata (href, format).
+   * Similar to XSLT's xsl:result-document, this allows templates to generate
+   * multiple output documents with associated metadata like URIs. The created
+   * document is stored in this._resultDocuments with the provided href.
+   *
+   * @param {string} href - URI/path for the result document
+   * @param {(this: DOMJoiningTransformer) => void} cb
+   *   Callback that builds the document content
+   * @param {import('./StringJoiningTransformer.js').OutputConfig} [cfg]
+   *   Output configuration for the document (encoding, doctype, format, etc.)
+   * @returns {DOMJoiningTransformer}
+   */
+  resultDocument (href, cb, cfg) {
+    // Save current state
+    /** @type {any} */
+    const oldRoot = this.root;
+    /** @type {any} */
+    const oldOutputConfig = this._outputConfig;
+    const oldDOM = this._dom;
+
+    // Reset state for new document
+    this.root = undefined;
+    /** @type {any} */
+    this._outputConfig = cfg;
+
+    // Create a new document fragment as the working context
+    const fragment = this._cfg.document.createDocumentFragment();
+    this._dom = fragment;
+
+    // Execute callback to build document content
+    cb.call(this);
+
+    // Get the created document from _docs (document() will have pushed it)
+    // or extract from the current DOM state
+    const resultDoc = this._docs.length > 0
+      ? /** @type {XMLDocument} */ (this._docs.at(-1))
+      : /** @type {XMLDocument} */ (
+        this._cfg.document.implementation.createDocument(null, 'root', null)
+      );
+
+    // Store with metadata, using the output config that was set during callback
+    this._resultDocuments.push({
+      href,
+      document: resultDoc,
+      format: this._outputConfig?.method || cfg?.method
+    });
+
+    // Restore previous state
+    this.root = oldRoot;
+    this._outputConfig = oldOutputConfig;
+    this._dom = oldDOM;
+
+    return this;
+  }
 }
 
 export default DOMJoiningTransformer;