pseudo-dom 0.12.0 → 0.14.0

package/README.md

@@ -144,10 +144,12 @@ if (typeof document === 'undefined') {
 }
 ```
 
-`installGlobal(target = globalThis)` fills in `document` / `Node` / `Element` / `HTMLElement` on `target`, using
+`installGlobal(target = globalThis)` fills in `document` / `Node` / `Element` / `HTMLElement` / `HTMLDocument` /
+`window` (a self-reference, like a real browser's) on `target`, using
 [browser-or-node](https://www.npmjs.com/package/browser-or-node) to check whether a real DOM (a real browser, or a
 jsdom-based test environment) is already there first - it's always safe to call, everywhere: it does nothing when
-one is.
+one is. `Node` / `Element` / `HTMLElement` / `HTMLDocument` are the classes themselves (not instances), so
+`x instanceof Element` works, matching the real DOM's.
 
 There's no real rendering to look at, so `logElement(node, [label])` prints a readable, indented view of a node's
 markup to the console (`prettyPrint(node, [indent])`, from the same module, returns the string instead of printing
@@ -317,10 +319,14 @@ order in which an event travels down through them). A node which has no parent h
 <dd><p>Remember the element which has the focus in a tree.</p>
 </dd>
 <dt><a href="#escapeText">escapeText(text)</a> ⇒ <code>string</code></dt>
-<dd><p>Escape text so it is safe inside HTML text content.</p>
+<dd><p>Escape text so it is safe inside HTML text content. Coerces to a string first - unlike a real DOM, pseudo-dom&#39;s
+setAttribute does not itself coerce (see the same note on escapeAttributeValue), and nodeValue is not guaranteed
+to be a string either.</p>
 </dd>
 <dt><a href="#escapeAttributeValue">escapeAttributeValue(value)</a> ⇒ <code>string</code></dt>
-<dd><p>Escape a value so it is safe inside a double-quoted HTML attribute.</p>
+<dd><p>Escape a value so it is safe inside a double-quoted HTML attribute. Coerces to a string first: a real DOM&#39;s
+setAttribute always stores a string, however pseudo-dom&#39;s does not coerce what it is given, so a value set via
+setAttribute(name, 5) is stored (and read back by getAttribute) as the number 5, not the string &#39;5&#39;.</p>
 </dd>
 <dt><a href="#serializeAttributes">serializeAttributes(element)</a> ⇒ <code>string</code></dt>
 <dd><p>Every attribute of the element, serialized (class instead of className, boolean attributes bare, the never-real
@@ -5483,24 +5489,28 @@ Remember the element which has the focus in a tree.
 <a name="escapeText"></a>
 
 ## escapeText(text) ⇒ <code>string</code>
-Escape text so it is safe inside HTML text content.
+Escape text so it is safe inside HTML text content. Coerces to a string first - unlike a real DOM, pseudo-dom's
+setAttribute does not itself coerce (see the same note on escapeAttributeValue), and nodeValue is not guaranteed
+to be a string either.
 
 **Kind**: global function  
 
 | Param | Type |
 | --- | --- |
-| text | <code>string</code> | 
+| text | <code>\*</code> | 
 
 <a name="escapeAttributeValue"></a>
 
 ## escapeAttributeValue(value) ⇒ <code>string</code>
-Escape a value so it is safe inside a double-quoted HTML attribute.
+Escape a value so it is safe inside a double-quoted HTML attribute. Coerces to a string first: a real DOM's
+setAttribute always stores a string, however pseudo-dom's does not coerce what it is given, so a value set via
+setAttribute(name, 5) is stored (and read back by getAttribute) as the number 5, not the string '5'.
 
 **Kind**: global function  
 
 | Param | Type |
 | --- | --- |
-| value | <code>string</code> | 
+| value | <code>\*</code> | 
 
 <a name="serializeAttributes"></a>
 
@@ -5566,9 +5576,10 @@ context.
 
 * [generateDocument(root, context)](#generateDocument) ⇒ <code>Window</code> \| <code>PseudoEventTarget</code>
     * [~newWindow](#generateDocument..newWindow) : <code>Window</code> \| <code>PseudoEventTarget</code>
-    * [~Node](#generateDocument..Node) : <code>Node</code> \| <code>PseudoNode</code>
-    * [~Element](#generateDocument..Element) : <code>Element</code> \| <code>PseudoElement</code>
-    * [~HTMLElement](#generateDocument..HTMLElement) : <code>HTMLElement</code> \| <code>PseudoHTMLElement</code>
+    * [~Node](#generateDocument..Node) : <code>function</code>
+    * [~Element](#generateDocument..Element) : <code>function</code>
+    * [~HTMLElement](#generateDocument..HTMLElement) : <code>function</code>
+    * [~HTMLDocument](#generateDocument..HTMLDocument) : <code>function</code>
     * [~document](#generateDocument..document) : <code>Document</code> \| [<code>PseudoHTMLDocument</code>](#PseudoHTMLDocument)
 
 <a name="generateDocument..newWindow"></a>
@@ -5577,22 +5588,35 @@ context.
 **Kind**: inner constant of [<code>generateDocument</code>](#generateDocument)  
 <a name="generateDocument..Node"></a>
 
-### generateDocument~Node : <code>Node</code> \| <code>PseudoNode</code>
+### generateDocument~Node : <code>function</code>
+The Node class itself (matching the DOM's window.Node), not an instance - the right-hand side of `instanceof`
+must be a constructor, so `x instanceof Node` needs this, not `new PseudoNode()`.
+
 **Kind**: inner constant of [<code>generateDocument</code>](#generateDocument)  
 <a name="generateDocument..Element"></a>
 
-### generateDocument~Element : <code>Element</code> \| <code>PseudoElement</code>
+### generateDocument~Element : <code>function</code>
+The Element class itself, for the same reason as Node.
+
 **Kind**: inner constant of [<code>generateDocument</code>](#generateDocument)  
 <a name="generateDocument..HTMLElement"></a>
 
-### generateDocument~HTMLElement : <code>HTMLElement</code> \| <code>PseudoHTMLElement</code>
-Create an instance of HTMLElement if not available
+### generateDocument~HTMLElement : <code>function</code>
+The HTMLElement class itself, for the same reason as Node.
+
+**Kind**: inner constant of [<code>generateDocument</code>](#generateDocument)  
+<a name="generateDocument..HTMLDocument"></a>
+
+### generateDocument~HTMLDocument : <code>function</code>
+The HTMLDocument class itself, for the same reason as Node (so `document instanceof HTMLDocument`, a common
+real-DOM-detection check, works).
 
 **Kind**: inner constant of [<code>generateDocument</code>](#generateDocument)  
 <a name="generateDocument..document"></a>
 
 ### generateDocument~document : <code>Document</code> \| [<code>PseudoHTMLDocument</code>](#PseudoHTMLDocument)
-Define document when not available
+Define document when not available - a real instance, unlike the classes above (window.document IS an object,
+not a constructor).
 
 **Kind**: inner constant of [<code>generateDocument</code>](#generateDocument)  
 <a name="nearestElementSibling"></a>

package/browser/pseudo-dom.js

@@ -734,30 +734,42 @@
    */
       const newWindow = typeof root.document === 'undefined' ? root : new EventTargetService_1.default()
       /**
-   * @type {Node|PseudoNode}
+   * The Node class itself (matching the DOM's window.Node), not an instance - the right-hand side of `instanceof`
+   * must be a constructor, so `x instanceof Node` needs this, not `new PseudoNode()`.
+   * @type {Function}
    */
-      const Node = root.Node || new NodeService_1.NodeService()
+      const Node = root.Node || NodeService_1.NodeService
       if (typeof newWindow.Node === 'undefined') {
         newWindow.Node = Node
       }
       /**
-   *
-   * @type {Element|PseudoElement}
+   * The Element class itself, for the same reason as Node.
+   * @type {Function}
    */
-      const Element = root.Element || new ElementService_1.ElementService()
+      const Element = root.Element || ElementService_1.ElementService
       if (typeof newWindow.Element === 'undefined') {
         newWindow.Element = Element
       }
       /**
-   * Create an instance of HTMLElement if not available
-   * @type {HTMLElement|PseudoHTMLElement}
+   * The HTMLElement class itself, for the same reason as Node.
+   * @type {Function}
    */
-      const HTMLElement = root.HTMLElement || new HTMLElementService_1.HTMLElementService()
+      const HTMLElement = root.HTMLElement || HTMLElementService_1.HTMLElementService
       if (typeof newWindow.HTMLElement === 'undefined') {
         newWindow.HTMLElement = HTMLElement
       }
       /**
-   * Define document when not available
+   * The HTMLDocument class itself, for the same reason as Node (so `document instanceof HTMLDocument`, a common
+   * real-DOM-detection check, works).
+   * @type {Function}
+   */
+      const HTMLDocument = root.HTMLDocument || PseudoHTMLDocument_1.default
+      if (typeof newWindow.HTMLDocument === 'undefined') {
+        newWindow.HTMLDocument = HTMLDocument
+      }
+      /**
+   * Define document when not available - a real instance, unlike the classes above (window.document IS an object,
+   * not a constructor).
    * @type {Document|PseudoHTMLDocument}
    */
       const document = root.document || new PseudoHTMLDocument_1.default()
@@ -814,17 +826,21 @@
  * When there is no real DOM already available (a real browser, or a jsdom-based test environment - isBrowser is
  * true for both, since jsdom's window has a document too, and a jsdom document should never be overwritten, real
  * DOM behaviour is always closer to the real thing), populate the given global-like target with document / Node /
- * Element / HTMLElement, generated by generateDocument, so code written against a real DOM's globals works as-is.
- * Does nothing when a real DOM is already there, matching generateDocument's own only-fill-what-is-missing
- * behaviour - calling this is always safe, in any environment.
+ * Element / HTMLElement / HTMLDocument, generated by generateDocument, plus window (a self-reference, matching a
+ * real browser's global scope - some code checks for a bare `window` before falling back to `global`), so code
+ * written against a real DOM's globals works as-is. Does nothing when a real DOM is already there, matching
+ * generateDocument's own only-fill-what-is-missing behaviour - calling this is always safe, in any environment.
  * @memberOf module:factories
- * @param {*} [target] The object to add document / Node / Element / HTMLElement onto - defaults to globalThis, so
- * bare `document`, `Node`, etc. resolve from anywhere once this has run
+ * @param {*} [target] The object to add document / Node / Element / HTMLElement / window onto - defaults to
+ * globalThis, so bare `document`, `Node`, `window`, etc. resolve from anywhere once this has run
  * @returns {*} The same target, for convenience
  */
     const installGlobal = (target = typeof globalThis !== 'undefined' ? globalThis : {}) => {
       if (!browser_or_node_1.isBrowser) {
         (0, generateDocument_1.default)(target, target)
+        if (typeof target.window === 'undefined') {
+          target.window = target
+        }
       }
       return target
     }
@@ -1055,17 +1071,21 @@
     // Boolean HTML attributes: present (with no value) when true, absent entirely when false
     const BOOLEAN_ATTRIBUTES = new Set(['hidden'])
     /**
- * Escape text so it is safe inside HTML text content.
- * @param {string} text
+ * Escape text so it is safe inside HTML text content. Coerces to a string first - unlike a real DOM, pseudo-dom's
+ * setAttribute does not itself coerce (see the same note on escapeAttributeValue), and nodeValue is not guaranteed
+ * to be a string either.
+ * @param {*} text
  * @returns {string}
  */
-    const escapeText = text => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    const escapeText = text => String(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
     /**
- * Escape a value so it is safe inside a double-quoted HTML attribute.
- * @param {string} value
+ * Escape a value so it is safe inside a double-quoted HTML attribute. Coerces to a string first: a real DOM's
+ * setAttribute always stores a string, however pseudo-dom's does not coerce what it is given, so a value set via
+ * setAttribute(name, 5) is stored (and read back by getAttribute) as the number 5, not the string '5'.
+ * @param {*} value
  * @returns {string}
  */
-    const escapeAttributeValue = value => value.replace(/&/g, '&amp;').replace(/"/g, '&quot;')
+    const escapeAttributeValue = value => String(value).replace(/&/g, '&amp;').replace(/"/g, '&quot;')
     /**
  * Every attribute of the element, serialized (class instead of className, boolean attributes bare, the never-real
  * mock properties left out, style added from the live CSSStyleDeclaration when it is not empty).