jtlt 0.1.0

package/src/DOMJoiningTransformer.js

@@ -0,0 +1,237 @@
+import * as JHTML from 'jhtml';
+import AbstractJoiningTransformer from './AbstractJoiningTransformer.js';
+
+/**
+ * Joining transformer that accumulates into a DOM tree.
+ *
+ * This transformer appends strings and nodes to a DocumentFragment/Element.
+ * 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.
+ */
+class DOMJoiningTransformer extends AbstractJoiningTransformer {
+  /**
+   * @param {DocumentFragment|Element} o - Initial DOM node
+   * @param {object} cfg - Configuration object
+   * @param {object} [cfg.document] - Document object
+   */
+  constructor (o, cfg) {
+    super(cfg); // Include this in any subclass of AbstractJoiningTransformer
+    this._dom = o ||
+    /** @type {any} */ (cfg).document.createDocumentFragment();
+  }
+
+  /**
+   * @param {Node} item
+   * @returns {void}
+   */
+  rawAppend (item) {
+    this._dom.append(item);
+  }
+
+  /**
+   * @param {string|Node} item - Item to append
+   * @returns {void}
+   */
+  append (item) {
+    this._dom.append(item);
+  }
+
+  /**
+   * @returns {DocumentFragment|Element}
+   */
+  get () {
+    return this._dom;
+  }
+
+  /**
+   * @param {string} prop - Property name
+   * @param {*} val - Property value
+   * @returns {void}
+   */
+  // eslint-disable-next-line class-methods-use-this -- Incomplete?
+  propValue (prop, val) {
+    //
+  }
+
+  /**
+   * @param {object} obj - Object to serialize
+   * @param {Function} [cb] - Callback function.
+   * @param {any[]} [usePropertySets] - Property sets to use
+   * @param {object} [propSets] - Additional property sets
+   * @returns {DOMJoiningTransformer}
+   */
+  object (obj, cb, usePropertySets, propSets) {
+    this._requireSameChildren('dom', 'object');
+    if (this._cfg && /** @type {any} */ (this._cfg).JHTMLForJSON) {
+      this.append(JHTML.toJHTMLDOM(/** @type {any} */ (obj)));
+    } else {
+      // Todo: set current position and deal with children
+      this.append('');
+    }
+    return this;
+  }
+
+  /**
+   * @param {any[]|Element} arr
+   * @param {Function} [cb] - Callback function
+   * @returns {DOMJoiningTransformer}
+   */
+  array (arr, cb) {
+    this._requireSameChildren('dom', 'array');
+    if (this._cfg && /** @type {any} */ (this._cfg).JHTMLForJSON) {
+      this.append(JHTML.toJHTMLDOM(/** @type {any} */ (arr)));
+    } else {
+      // Todo: set current position and deal with children
+      this.append('');
+    }
+    return this;
+  }
+
+  /**
+   * @param {string} str - String value
+   * @param {Function} cb - Callback function (unused)
+   * @returns {DOMJoiningTransformer}
+   */
+  string (str, cb) {
+    // Todo: Conditionally add as JHTML (and in subsequent methods as well)
+    this.append(str);
+    return this;
+  }
+
+  /**
+   * @param {number} num - Number value
+   * @returns {DOMJoiningTransformer}
+   */
+  number (num) {
+    this.append(num.toString());
+    return this;
+  }
+
+  /**
+   * @param {boolean} bool
+   * @returns {DOMJoiningTransformer}
+   */
+  boolean (bool) {
+    this.append(bool ? 'true' : 'false');
+    return this;
+  }
+
+  /**
+   * @returns {DOMJoiningTransformer}
+   */
+  null () {
+    this.append('null');
+    return this;
+  }
+
+  /**
+   * @returns {DOMJoiningTransformer}
+   */
+  undefined () {
+    if (this._cfg && /** @type {any} */ (this._cfg).mode !== 'JavaScript') {
+      throw new Error(
+        'undefined is not allowed unless added in JavaScript mode'
+      );
+    }
+    this.append('undefined');
+    return this;
+  }
+
+  /**
+   * @param {number} num - Non-finite number (NaN, Infinity, -Infinity)
+   * @returns {DOMJoiningTransformer}
+   */
+  nonfiniteNumber (num) {
+    if (this._cfg && /** @type {any} */ (this._cfg).mode !== 'JavaScript') {
+      throw new Error(
+        'Non-finite numbers are not allowed unless added in JavaScript mode'
+      );
+    }
+    this.append(num.toString());
+    return this;
+  }
+
+  /**
+   * @param {Function} func - Function to stringify
+   * @returns {DOMJoiningTransformer}
+   */
+  function (func) {
+    if (this._cfg && /** @type {any} */ (this._cfg).mode !== 'JavaScript') {
+      throw new Error(
+        'function is not allowed unless added in JavaScript mode'
+      );
+    }
+    this.append(func.toString());
+    return this;
+  }
+
+  /**
+   * @param {string} elName - Element name
+   * @param {object} [atts] - Attributes object
+   * @param {Function} [cb] - Callback function
+   * @returns {DOMJoiningTransformer}
+   */
+  element (elName, atts, cb) {
+    // Todo: allow third argument to be array following Jamilih (also let
+    //   "atts" follow Jamilih)
+    // Todo: allow for cfg to produce Jamilih DOM output or hXML
+    // 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);
+    for (const att in atts) {
+      if (Object.hasOwn(atts, att)) {
+        /** @type {Record<string, any>} */
+        const attsObj = /** @type {any} */ (atts);
+        el.setAttribute(att, attsObj[att]);
+      }
+    }
+    this.append(el);
+
+    const oldDOM = this._dom;
+
+    this._dom = el;
+    if (cb) {
+      cb.call(this);
+    }
+    this._dom = oldDOM;
+
+    return this;
+  }
+
+  /**
+   * @param {string} name
+   * @param {string} val
+   * @returns {DOMJoiningTransformer}
+   */
+  attribute (name, val) {
+    if (!this._dom || typeof this._dom !== 'object' ||
+        this._dom.nodeType !== 1) {
+      throw new Error('You may only set an attribute on an element');
+    }
+    (/** @type {Element} */ (this._dom)).setAttribute(name, val);
+    return this;
+  }
+
+  /**
+   * @param {string} txt - Text content
+   * @returns {DOMJoiningTransformer}
+   */
+  text (txt) {
+    this.append(txt);
+    return this;
+  }
+
+  /**
+   * @param {string} str
+   * @returns {DOMJoiningTransformer}
+   */
+  plainText (str) {
+    this.text(str);
+    return this;
+  }
+}
+
+export default DOMJoiningTransformer;

package/src/JSONJoiningTransformer.js

@@ -0,0 +1,472 @@
+import AbstractJoiningTransformer from './AbstractJoiningTransformer.js';
+
+// Regex and helper for converting dataset camelCase to dash-lower
+const camelCase = /[a-z][A-Z]/gv;
+/**
+ * @param {string} n0
+ * @returns {string}
+ */
+function _makeDatasetAttribute (n0) {
+  return n0.charAt(0) + '-' + n0.charAt(1).toLowerCase();
+}
+
+/**
+ * JSON-based joining transformer for building JSON/JavaScript objects.
+ *
+ * This joiner accumulates into an in-memory JSON value (object or array).
+ * append() will push to arrays or shallow-merge into objects; string/number/
+ * boolean/null add primitives accordingly. It does not perform HTML escaping
+ * or string serialization; it builds real JS values.
+ */
+class JSONJoiningTransformer extends AbstractJoiningTransformer {
+  /**
+   * @param {any[]|object} [o] - Initial object or array
+   * @param {object} [cfg] - Configuration object
+   */
+  constructor (o, cfg) {
+    super(cfg);
+    /** @type {any[]|object} */
+    this._obj = o || [];
+    /** @type {boolean | undefined} */
+    this._objPropState = undefined;
+    /** @type {boolean | undefined} */
+    this._arrItemState = undefined;
+    /** @type {{attsObj: Record<string, any>, jmlChildren: any[]}[]} */
+    this._elementStack = [];
+  }
+
+  /**
+   * Directly appends an item to the internal array without checks.
+   * @param {*} item - Item to append
+   * @returns {void}
+   */
+  rawAppend (item) {
+    /** @type {any[]} */ (this._obj).push(item);
+  }
+
+  /**
+   * Appends an item to the current object or array.
+   * @param {*} item - Item to append
+   * @returns {JSONJoiningTransformer}
+   */
+  append (item) {
+    // Todo: allow for first time
+    if (!this._obj || typeof this._obj !== 'object') {
+      throw new Error('You cannot append to a scalar or empty value.');
+    }
+    if (Array.isArray(this._obj)) {
+      this._obj.push(item);
+    } else {
+      Object.assign(this._obj, item);
+    }
+    return this;
+  }
+
+  /**
+   * Gets the current object or array. If unwrapSingleResult config option is
+   * enabled and the root array contains exactly one element, returns that
+   * element directly (unwrapped).
+   * @returns {any[]|object|any}
+   */
+  get () {
+    // Unwrap single-element arrays at the root level if configured
+    if (this._cfg && /** @type {any} */ (this._cfg).unwrapSingleResult &&
+        Array.isArray(this._obj) && this._obj.length === 1) {
+      return this._obj[0];
+    }
+    return this._obj;
+  }
+
+  /**
+   * Sets a property value on the current object.
+   * @param {string} prop - Property name
+   * @param {*} val - Property value
+   * @returns {void}
+   */
+  propValue (prop, val) {
+    if (!this._objPropState) {
+      throw new Error(
+        'propValue() can only be called after an object state has been set up.'
+      );
+    }
+    (/** @type {Record<string, any>} */ (this._obj))[prop] = val;
+  }
+
+  /* c8 ignore next 13 -- JSDoc block incorrectly counted as coverable by c8 */
+  /**
+   * @param {object|Function} [objOrCb] - Seed object to start with, or
+   *   callback if no seed provided
+   * @param {Function|any[]} [cbOrUsePropertySets] - Callback to be executed
+   *   on this transformer but with a context nested within the newly created
+   *   object, or array of property set names if first arg was an object
+   * @param {any[]|object} [usePropertySetsOrPropSets] - Array of string
+   *   property set names to copy onto the new object, or propSets if second
+   *   arg was a callback
+   * @param {object} [propSets] - An object of key-value pairs to copy onto
+   *   the new object
+   * @returns {JSONJoiningTransformer}
+   */
+  object (objOrCb, cbOrUsePropertySets, usePropertySetsOrPropSets, propSets) {
+    // eslint-disable-next-line unicorn/no-this-assignment -- Temporary
+    const that = this;
+    // Todo: Conditionally add as JHTML-based jml (and in subsequent methods
+    //   as well)
+    const tempObj = this._obj;
+
+    // Determine if first arg is a seed object or callback
+    let obj;
+    let cb;
+    let usePropertySets;
+    let propSetsToUse;
+
+    if (typeof objOrCb === 'function') {
+      // No seed object: object(cb, usePropertySets, propSets)
+      obj = {};
+      cb = objOrCb;
+      usePropertySets = /** @type {any[]} */ (cbOrUsePropertySets);
+      propSetsToUse = /** @type {object} */ (usePropertySetsOrPropSets);
+    } else {
+      // Seed object provided: object(obj, cb, usePropertySets, propSets)
+      // Clone seed object to avoid mutating the original
+      obj = objOrCb ? {...objOrCb} : {};
+      cb = /** @type {Function} */ (cbOrUsePropertySets);
+      usePropertySets = /** @type {any[]} */ (usePropertySetsOrPropSets);
+      propSetsToUse = propSets;
+    }
+
+    if (usePropertySets !== undefined) {
+      const merged = usePropertySets.reduce((o, psName) => {
+        return that._usePropertySets(o, psName); // Todo: Put in right scope
+      }, {});
+      Object.assign(obj, merged);
+    }
+    if (propSetsToUse !== undefined) {
+      Object.assign(obj, propSetsToUse);
+    }
+
+    /** @type {any} */
+    const oldObjPropState = this._objPropState;
+    this._objPropState = true;
+    this._obj = obj; // Set current object so propValue() works
+    // We pass the object, but user should usually use other methods
+    if (cb) {
+      cb.call(this, obj);
+    }
+    // Append after callback so object has all properties, but before
+    // restoring tempObj
+    this._obj = tempObj;
+    this.append(obj);
+    this._objPropState = oldObjPropState;
+    return this;
+  }
+
+  /**
+   * Creates a new array and executes a callback in its context.
+   * @param {any[]|Function} [arrOrCb] - Seed array to start with, or callback
+   *   if no seed provided
+   * @param {Function} [cb] - Callback function (if first arg was a seed array)
+   * @returns {JSONJoiningTransformer}
+   */
+  array (arrOrCb, cb) {
+    const tempObj = this._obj;
+
+    // Determine if first arg is a seed array or callback
+    /** @type {any[]} */
+    let arr;
+    let callback;
+
+    if (typeof arrOrCb === 'function') {
+      // No seed array: array(cb)
+      arr = [];
+      callback = arrOrCb;
+    } else {
+      // Seed array provided: array(arr, cb)
+      // Clone seed array to avoid mutating the original
+      arr = arrOrCb ? [...arrOrCb] : [];
+      callback = cb;
+    }
+
+    this._obj = arr; // Set current array so append() works
+    // We pass the array, but user should usually use other methods
+    if (callback) {
+      callback.call(this, arr);
+    }
+    // Append after callback so array has all items, but before
+    // restoring tempObj
+    this._obj = tempObj;
+    this.append(arr); // Todo: set current position and deal with children
+    return this;
+  }
+
+  /**
+   * Appends a string value.
+   * @param {string} str - String value
+  * @param {Function} [cb] - Callback function (unused)
+   * @returns {JSONJoiningTransformer}
+   */
+  string (str, cb) {
+    this._requireSameChildren('json', 'string');
+    this.append(str);
+    return this;
+  }
+
+  /**
+   * Appends a number value.
+   * @param {number} num - Number value
+   * @returns {JSONJoiningTransformer}
+   */
+  number (num) {
+    this.append(num);
+    return this;
+  }
+
+  /**
+   * Appends a boolean value.
+   * @param {boolean} bool - Boolean value
+   * @returns {JSONJoiningTransformer}
+   */
+  boolean (bool) {
+    this.append(bool);
+    return this;
+  }
+
+  /**
+   * Appends a null value.
+   * @returns {JSONJoiningTransformer}
+   */
+  null () {
+    this.append(null);
+    return this;
+  }
+
+  /**
+   * Appends an undefined value (JavaScript mode only).
+   * @returns {JSONJoiningTransformer}
+   */
+  undefined () {
+    if (this._cfg && /** @type {any} */ (this._cfg).mode !== 'JavaScript') {
+      throw new Error(
+        'undefined is not allowed unless added in JavaScript mode'
+      );
+    }
+    this.append(undefined);
+    return this;
+  }
+
+  /**
+   * Appends a non-finite number (JavaScript mode only).
+   * @param {number} num - Non-finite number (NaN, Infinity, -Infinity)
+   * @returns {JSONJoiningTransformer}
+   */
+  nonfiniteNumber (num) {
+    if (this._cfg && /** @type {any} */ (this._cfg).mode !== 'JavaScript') {
+      throw new Error(
+        'Non-finite numbers are not allowed unless added in JavaScript mode'
+      );
+    }
+    this.append(num);
+    return this;
+  }
+
+  /**
+   * Appends a function value (JavaScript mode only).
+   * @param {Function} func - Function to append
+   * @returns {JSONJoiningTransformer}
+   */
+  function (func) {
+    if (this._cfg && /** @type {any} */ (this._cfg).mode !== 'JavaScript') {
+      throw new Error(
+        'function is not allowed unless added in JavaScript mode'
+      );
+    }
+    this.append(func);
+    return this;
+  }
+
+  /**
+  * Build a Jamilih-style element JSON array and append to current container.
+  * Result form: ['tag', {attr: 'val'}, child1, child2, ...]
+  * Helpers: dataset -> data-*; $a -> ordered attributes.
+  * Supported signatures mirror StringJoiningTransformer.element.
+   * @param {string|Element|object} elName - Element name or Element-like
+   * @param {object|any[]|Function} [atts] - Attributes object or children or cb
+   * @param {any[]|Function} [childNodes] - Child nodes array or callback
+   * @param {Function} [cb] - Callback for building children/attributes
+   * @returns {JSONJoiningTransformer}
+   */
+  element (elName, atts, childNodes, cb) {
+    this._requireSameChildren('json', 'element');
+    // Normalize arguments similarly to StringJoiningTransformer.element
+    if (Array.isArray(atts)) {
+      cb = /** @type {Function} */ (childNodes);
+      childNodes = atts;
+      atts = {};
+    } else if (typeof atts === 'function') {
+      cb = /** @type {Function} */ (atts);
+      childNodes = [];
+      atts = {};
+    }
+    if (typeof childNodes === 'function') {
+      cb = /** @type {Function} */ (childNodes);
+      childNodes = [];
+    }
+
+    // Element-like object (DOM Element) -> extract attributes
+    if (typeof elName === 'object' && elName && 'attributes' in elName) {
+      /** @type {Record<string, any>} */
+      const objAtts = {};
+      // @ts-ignore - treat elName as Element-like
+      [...elName.attributes].forEach((att) => {
+        objAtts[att.name] = att.value;
+      });
+      atts = Object.assign(objAtts, atts);
+      // @ts-ignore
+      elName = /** @type {any} */ (elName).nodeName;
+    }
+
+    /** @type {Record<string, any>} */
+    let attsObj = /** @type {any} */ (atts) || {};
+    /** @type {any[]} */
+    const jmlChildren = [];
+
+    // Preprocess special attribute helpers present directly on attsObj
+    if (attsObj.dataset && typeof attsObj.dataset === 'object' &&
+      !Array.isArray(attsObj.dataset)
+    ) {
+      const ds = attsObj.dataset;
+      for (const k in ds) {
+        if (Object.hasOwn(ds, k)) {
+          const dashed = k.replaceAll(camelCase, _makeDatasetAttribute);
+          attsObj['data-' + dashed] = ds[k];
+        }
+      }
+      delete attsObj.dataset;
+    }
+    if (Array.isArray(attsObj.$a)) {
+      attsObj.$a.forEach((pair) => {
+        if (Array.isArray(pair) && pair.length > 1) {
+          attsObj[pair[0]] = pair[1];
+        }
+      });
+      delete attsObj.$a;
+    }
+
+    // If children provided as array, copy (may be primitives or nested JML)
+    if (Array.isArray(childNodes) && childNodes.length) {
+      jmlChildren.push(...childNodes);
+    }
+
+    // Callback-driven building (attribute/text/nested element mutate stack)
+    if (cb) {
+      // Push current state onto a stack
+      this._elementStack.push({attsObj, jmlChildren});
+      cb.call(this);
+      const state = /** @type {any} */ (this._elementStack.pop());
+      ({attsObj} = state);
+      // Children may have been mutated by nested element()/text();
+      // already in jmlChildren
+    }
+
+    // Build Jamilih array
+    /** @type {any[]} */
+    const jmlEl = [elName];
+    if (Object.keys(attsObj).length) {
+      jmlEl.push(attsObj);
+    }
+    jmlEl.push(...jmlChildren);
+
+    // If inside a parent element, append as its child; otherwise append to root
+    if (this._elementStack.length) {
+      const top = /** @type {any} */ (this._elementStack.at(-1));
+      top.jmlChildren.push(jmlEl);
+    } else {
+      this.append(jmlEl);
+    }
+    return this;
+  }
+
+  /**
+   * Adds/updates an attribute for the most recently open element built via
+   * a callback-driven element(). When not in an element callback context,
+   * throws. Supports the same dataset/$a helpers as string joiner.
+   * @param {string} name - Attribute name (or helper: dataset, $a)
+   * @param {string|object|any[]} val - Attribute value or helper object
+   * @returns {JSONJoiningTransformer}
+   */
+  attribute (name, val) {
+    if (!this._elementStack.length) {
+      // No-op outside an element() callback (JSON joiner semantics)
+      return this;
+    }
+    const top = /** @type {any} */ (this._elementStack.at(-1));
+    const {attsObj} = top;
+    if (name === 'dataset' && val && typeof val === 'object' &&
+      !Array.isArray(val)
+    ) {
+      for (const k in val) {
+        if (Object.hasOwn(val, k)) {
+          const dashed = k.replaceAll(camelCase, _makeDatasetAttribute);
+          attsObj['data-' + dashed] = (/** @type {any} */ (val))[k];
+        }
+      }
+      return this;
+    }
+    if (name === '$a' && Array.isArray(val)) {
+      val.forEach((pair) => {
+        if (Array.isArray(pair) && pair.length > 1) {
+          attsObj[pair[0]] = pair[1];
+        }
+      });
+      return this;
+    }
+    attsObj[name] = val;
+    return this;
+  }
+
+  /**
+   * Adds a text node (string) as a child within the current element() callback
+   * context. Outside of an element callback, simply appends the text to the
+   * current array/object like string().
+   * @param {string} txt - Text content
+   * @returns {JSONJoiningTransformer}
+   */
+  text (txt) {
+    if (this._elementStack.length) {
+      const top = /** @type {any} */ (this._elementStack.at(-1));
+      const {jmlChildren} = top;
+      jmlChildren.push(txt);
+      return this;
+    }
+    // No-op outside element context in JSON joiner
+    return this;
+  }
+
+  /**
+   * Appends plain text as a string.
+   * @param {string} str - Plain text string
+   * @returns {JSONJoiningTransformer}
+   */
+  plainText (str) {
+    this.string(str);
+    return this;
+  }
+
+  /**
+   * Helper method to use property sets (to be implemented).
+   * @param {object} obj - Object to apply property set to
+   * @param {string} psName - Property set name
+   * @returns {object}
+   */
+  _usePropertySets (obj, psName) {
+    // Merge the named property set (if present) into the provided object
+    if (this && /** @type {any} */ (this).propertySets &&
+    /** @type {any} */ (this).propertySets[psName]
+    ) {
+      return Object.assign(obj, /** @type {any} */ (this).propertySets[psName]);
+    }
+    return obj;
+  }
+}
+
+export default JSONJoiningTransformer;
+