pseudo-dom 0.15.0 → 0.17.0

package/README.md

@@ -59,6 +59,18 @@ reflected properties (`ariaLabel`, `ariaExpanded`, `ariaValueNow`, ...) are real
 matching `aria-*` attribute (`ariaLabel` <-> `aria-label`; the mapping isn't camelCase-to-kebab-case, so
 `ariaColCount` <-> `aria-colcount`, not `aria-col-count`).
 
+`getAttributeNode` / `setAttributeNode` / `removeAttributeNode` give and take real `Attr` nodes (backed by
+`AttrService`) instead of plain strings - `setAttributeNode` returns whatever `Attr` previously held that name (or
+`null` when it's new), and `removeAttributeNode` throws when the element has no attribute matching the one given, like
+the DOM's. Every `*NS` method (`getAttributeNS`, `hasAttributeNS`, `setAttributeNS`, `removeAttributeNS`,
+`getAttributeNodeNS`, `setAttributeNodeNS`) behaves exactly like its non-NS counterpart, ignoring the namespace
+argument entirely - there's no real namespace parsing here, matching `getElementsByTagNameNS`.
+
+**Form controls** have a real `value` (`input`, `textarea`, `select`, `button`, `option`, `output`) and `checked`
+(`input`). Like the DOM's, they start from the `value` / `checked` attributes (a checkbox with no `value` reads
+`'on'`), and once set they stop following the attribute - setting them never changes the attribute. `value` is always
+a string, so `parseInt(input.value)` works on a number attribute. `cloneNode` keeps the current value and checkedness.
+
 **`style`** is a real, live `CSSStyleDeclaration`:
 
 - Named property access (`el.style.backgroundColor = 'red'`) alongside `getPropertyValue` / `setProperty` /
@@ -169,9 +181,6 @@ it) - useful for watching pseudo-dom-driven code run, or checking a final result
 - There are text and comment nodes (`PseudoText`, `PseudoComment`); `textContent` works like the DOM's (the text of
   everything below, and setting it replaces the children with a text node)
 
-## Not implemented yet
-
-- The `Attr`-node / namespaced attribute methods (`getAttributeNode`, `getAttributeNS`, ...)
 ## Modules
 
 <dl>
@@ -2433,9 +2442,14 @@ Simulate the behaviour of the HTMLElement Class when there is no DOM available.
     * [new HTMLElementService([elementOptions])](#new_HTMLElementService_new)
     * [.style](#HTMLElementService+style) ⇒ [<code>CSSStyleDeclarationService</code>](#CSSStyleDeclarationService)
     * [.dataset](#HTMLElementService+dataset) ⇒ <code>Object.&lt;string, string&gt;</code>
+    * [.value](#HTMLElementService+value) ⇒ <code>string</code> \| <code>undefined</code>
+    * [.checked](#HTMLElementService+checked) ⇒ <code>boolean</code> \| <code>undefined</code>
     * [.innerHTML](#HTMLElementService+innerHTML) ⇒ <code>undefined</code>
     * [.outerHTML](#HTMLElementService+outerHTML) ⇒ <code>undefined</code>
     * [.canFocus](#HTMLElementService+canFocus) ⇒ <code>boolean</code>
+    * [.hasValueProperty()](#HTMLElementService+hasValueProperty) ⇒ <code>boolean</code>
+    * [.hasCheckedProperty()](#HTMLElementService+hasCheckedProperty) ⇒ <code>boolean</code>
+    * [.setExpando(name, value)](#HTMLElementService+setExpando) ⇒ <code>undefined</code>
     * [.cloneShallow()](#HTMLElementService+cloneShallow) ⇒ [<code>NodeService</code>](#NodeService)
     * [.equalsShallow(other)](#HTMLElementService+equalsShallow) ⇒ <code>boolean</code>
     * [.parse(html)](#HTMLElementService+parse) ⇒ <code>Array.&lt;\*&gt;</code>
@@ -2470,6 +2484,21 @@ and style.color = 'red' work.
 The element's data-* attributes, live, under their camelCase names (data-foo-bar <-> dataset.fooBar). Backed
 directly by getAttribute / setAttribute, so it is never out of sync with the attributes themselves.
 
+**Kind**: instance property of [<code>HTMLElementService</code>](#HTMLElementService)  
+<a name="HTMLElementService+value"></a>
+
+### htmlElementService.value ⇒ <code>string</code> \| <code>undefined</code>
+The current value of a form control. Until it is set (or edited), it is the value attribute (the default value),
+or '' when there is none ('on' for a checkbox or radio); setting it never changes the attribute, like the DOM's.
+Only form controls (input, textarea, select, button, option, output) have one.
+
+**Kind**: instance property of [<code>HTMLElementService</code>](#HTMLElementService)  
+<a name="HTMLElementService+checked"></a>
+
+### htmlElementService.checked ⇒ <code>boolean</code> \| <code>undefined</code>
+Whether a checkbox or radio input is checked. Until it is set, it follows the checked attribute (which sets the
+default); setting it never changes the attribute, like the DOM's. Only input has one.
+
 **Kind**: instance property of [<code>HTMLElementService</code>](#HTMLElementService)  
 <a name="HTMLElementService+innerHTML"></a>
 
@@ -2501,10 +2530,35 @@ replaceWith. outerHTML's setter is here rather than on ElementService for the sa
 Whether this element can have the focus: form controls and links which are not disabled, and anything with a tabindex.
 
 **Kind**: instance property of [<code>HTMLElementService</code>](#HTMLElementService)  
+<a name="HTMLElementService+hasValueProperty"></a>
+
+### htmlElementService.hasValueProperty() ⇒ <code>boolean</code>
+Whether this tag has a `value` (the form controls which do).
+
+**Kind**: instance method of [<code>HTMLElementService</code>](#HTMLElementService)  
+<a name="HTMLElementService+hasCheckedProperty"></a>
+
+### htmlElementService.hasCheckedProperty() ⇒ <code>boolean</code>
+Whether this tag has a `checked` (only input does).
+
+**Kind**: instance method of [<code>HTMLElementService</code>](#HTMLElementService)  
+<a name="HTMLElementService+setExpando"></a>
+
+### htmlElementService.setExpando(name, value) ⇒ <code>undefined</code>
+Put a plain own property on the element, as assigning a property this element does not have does in the DOM.
+
+**Kind**: instance method of [<code>HTMLElementService</code>](#HTMLElementService)  
+
+| Param | Type |
+| --- | --- |
+| name | <code>string</code> | 
+| value | <code>\*</code> | 
+
 <a name="HTMLElementService+cloneShallow"></a>
 
 ### htmlElementService.cloneShallow() ⇒ [<code>NodeService</code>](#NodeService)
-Style is not attribute-backed like most properties (see the constructor), so cloneNode needs its own copy of it.
+Style is not attribute-backed like most properties (see the constructor), so cloneNode needs its own copy of it,
+and a form control keeps its current value and checkedness (as the DOM's cloneNode does).
 
 **Kind**: instance method of [<code>HTMLElementService</code>](#HTMLElementService)  
 <a name="HTMLElementService+equalsShallow"></a>
@@ -2961,6 +3015,15 @@ Simulate the behaviour of the Element Class when there is no DOM available.
     * [.removeAttribute(attributeName)](#ElementService+removeAttribute) ⇒ <code>undefined</code>
     * [.getAttributeNames()](#ElementService+getAttributeNames) ⇒ <code>Array.&lt;string&gt;</code>
     * [.hasAttributes()](#ElementService+hasAttributes) ⇒ <code>boolean</code>
+    * [.getAttributeNode(attributeName)](#ElementService+getAttributeNode) ⇒ [<code>AttrService</code>](#AttrService) \| <code>null</code>
+    * [.getAttributeNodeNS(namespace, attributeName)](#ElementService+getAttributeNodeNS) ⇒ [<code>AttrService</code>](#AttrService) \| <code>null</code>
+    * [.getAttributeNS(namespace, attributeName)](#ElementService+getAttributeNS) ⇒ <code>string</code> \| <code>null</code>
+    * [.hasAttributeNS(namespace, attributeName)](#ElementService+hasAttributeNS) ⇒ <code>boolean</code>
+    * [.removeAttributeNode(attr)](#ElementService+removeAttributeNode) ⇒ [<code>AttrService</code>](#AttrService)
+    * [.removeAttributeNS(namespace, attributeName)](#ElementService+removeAttributeNS) ⇒ <code>undefined</code>
+    * [.setAttributeNode(attr)](#ElementService+setAttributeNode) ⇒ [<code>AttrService</code>](#AttrService) \| <code>null</code>
+    * [.setAttributeNodeNS(attr)](#ElementService+setAttributeNodeNS) ⇒ [<code>AttrService</code>](#AttrService) \| <code>null</code>
+    * [.setAttributeNS(namespace, attributeName, attributeValue)](#ElementService+setAttributeNS) ⇒ <code>undefined</code>
     * [.toggleAttribute(attributeName, [force])](#ElementService+toggleAttribute) ⇒ <code>boolean</code>
     * [.getBoundingClientRect()](#ElementService+getBoundingClientRect) ⇒ <code>DOMRect</code>
     * [.getClientRects()](#ElementService+getClientRects) ⇒ <code>Array.&lt;DOMRect&gt;</code>
@@ -3272,6 +3335,128 @@ The name of every attribute on the element, in the order they were set.
 Whether the element has any attributes at all.
 
 **Kind**: instance method of [<code>ElementService</code>](#ElementService)  
+<a name="ElementService+getAttributeNode"></a>
+
+### elementService.getAttributeNode(attributeName) ⇒ [<code>AttrService</code>](#AttrService) \| <code>null</code>
+Retrieve the node representation of an attribute.
+
+**Kind**: instance method of [<code>ElementService</code>](#ElementService)  
+**Returns**: [<code>AttrService</code>](#AttrService) \| <code>null</code> - An Attr for the attribute, or null when there is no such attribute  
+
+| Param | Type |
+| --- | --- |
+| attributeName | <code>string</code> | 
+
+<a name="ElementService+getAttributeNodeNS"></a>
+
+### elementService.getAttributeNodeNS(namespace, attributeName) ⇒ [<code>AttrService</code>](#AttrService) \| <code>null</code>
+Retrieve the node representation of an attribute. There is no real namespace parsing here, so this ignores
+the namespace and behaves exactly like getAttributeNode.
+
+**Kind**: instance method of [<code>ElementService</code>](#ElementService)  
+**Returns**: [<code>AttrService</code>](#AttrService) \| <code>null</code> - An Attr for the attribute, or null when there is no such attribute  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| namespace | <code>string</code> | Ignored |
+| attributeName | <code>string</code> |  |
+
+<a name="ElementService+getAttributeNS"></a>
+
+### elementService.getAttributeNS(namespace, attributeName) ⇒ <code>string</code> \| <code>null</code>
+Retrieve the value of an attribute. There is no real namespace parsing here, so this ignores the namespace
+and behaves exactly like getAttribute.
+
+**Kind**: instance method of [<code>ElementService</code>](#ElementService)  
+**Returns**: <code>string</code> \| <code>null</code> - The value, or null when there is no such attribute  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| namespace | <code>string</code> | Ignored |
+| attributeName | <code>string</code> |  |
+
+<a name="ElementService+hasAttributeNS"></a>
+
+### elementService.hasAttributeNS(namespace, attributeName) ⇒ <code>boolean</code>
+Check whether the element has an attribute by that name. There is no real namespace parsing here, so this
+ignores the namespace and behaves exactly like hasAttribute.
+
+**Kind**: instance method of [<code>ElementService</code>](#ElementService)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| namespace | <code>string</code> | Ignored |
+| attributeName | <code>string</code> |  |
+
+<a name="ElementService+removeAttributeNode"></a>
+
+### elementService.removeAttributeNode(attr) ⇒ [<code>AttrService</code>](#AttrService)
+Remove the node representation of an attribute from the element, and return it.
+
+**Kind**: instance method of [<code>ElementService</code>](#ElementService)  
+**Returns**: [<code>AttrService</code>](#AttrService) - The removed Attr  
+**Throws**:
+
+- <code>Error</code> When the element has no attribute matching attr.name
+
+
+| Param | Type |
+| --- | --- |
+| attr | [<code>AttrService</code>](#AttrService) | 
+
+<a name="ElementService+removeAttributeNS"></a>
+
+### elementService.removeAttributeNS(namespace, attributeName) ⇒ <code>undefined</code>
+Remove an attribute from the element. There is no real namespace parsing here, so this ignores the namespace
+and behaves exactly like removeAttribute.
+
+**Kind**: instance method of [<code>ElementService</code>](#ElementService)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| namespace | <code>string</code> | Ignored |
+| attributeName | <code>string</code> |  |
+
+<a name="ElementService+setAttributeNode"></a>
+
+### elementService.setAttributeNode(attr) ⇒ [<code>AttrService</code>](#AttrService) \| <code>null</code>
+Set the node representation of an attribute, adding the attribute if it did not exist. Returns any previous
+Attr that had the same name, or null when there was none.
+
+**Kind**: instance method of [<code>ElementService</code>](#ElementService)  
+**Returns**: [<code>AttrService</code>](#AttrService) \| <code>null</code> - The replaced Attr, or null when the attribute was new  
+
+| Param | Type |
+| --- | --- |
+| attr | [<code>AttrService</code>](#AttrService) | 
+
+<a name="ElementService+setAttributeNodeNS"></a>
+
+### elementService.setAttributeNodeNS(attr) ⇒ [<code>AttrService</code>](#AttrService) \| <code>null</code>
+Set the node representation of an attribute. There is no real namespace parsing here, so this behaves
+exactly like setAttributeNode (Attr.name already carries any prefix).
+
+**Kind**: instance method of [<code>ElementService</code>](#ElementService)  
+**Returns**: [<code>AttrService</code>](#AttrService) \| <code>null</code> - The replaced Attr, or null when the attribute was new  
+
+| Param | Type |
+| --- | --- |
+| attr | [<code>AttrService</code>](#AttrService) | 
+
+<a name="ElementService+setAttributeNS"></a>
+
+### elementService.setAttributeNS(namespace, attributeName, attributeValue) ⇒ <code>undefined</code>
+Set the value of an attribute, adding the attribute if it did not exist. There is no real namespace parsing
+here, so this ignores the namespace and behaves exactly like setAttribute.
+
+**Kind**: instance method of [<code>ElementService</code>](#ElementService)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| namespace | <code>string</code> | Ignored |
+| attributeName | <code>string</code> |  |
+| attributeValue | <code>string</code> |  |
+
 <a name="ElementService+toggleAttribute"></a>
 
 ### elementService.toggleAttribute(attributeName, [force]) ⇒ <code>boolean</code>

package/browser/pseudo-dom.js

@@ -2605,6 +2605,108 @@
         return this.attributeList.length > 0
       }
 
+      /**
+   * Retrieve the node representation of an attribute.
+   * @param {string} attributeName
+   * @returns {AttrService|null} An Attr for the attribute, or null when there is no such attribute
+   */
+      getAttributeNode (attributeName) {
+        return this.hasAttribute(attributeName) ? new AttrService_1.AttrService(attributeName, this.getAttribute(attributeName) || '', this) : null
+      }
+
+      /**
+   * Retrieve the node representation of an attribute. There is no real namespace parsing here, so this ignores
+   * the namespace and behaves exactly like getAttributeNode.
+   * @param {string} namespace Ignored
+   * @param {string} attributeName
+   * @returns {AttrService|null} An Attr for the attribute, or null when there is no such attribute
+   */
+      getAttributeNodeNS (namespace, attributeName) {
+        return this.getAttributeNode(attributeName)
+      }
+
+      /**
+   * Retrieve the value of an attribute. There is no real namespace parsing here, so this ignores the namespace
+   * and behaves exactly like getAttribute.
+   * @param {string} namespace Ignored
+   * @param {string} attributeName
+   * @returns {string|null} The value, or null when there is no such attribute
+   */
+      getAttributeNS (namespace, attributeName) {
+        return this.getAttribute(attributeName)
+      }
+
+      /**
+   * Check whether the element has an attribute by that name. There is no real namespace parsing here, so this
+   * ignores the namespace and behaves exactly like hasAttribute.
+   * @param {string} namespace Ignored
+   * @param {string} attributeName
+   * @returns {boolean}
+   */
+      hasAttributeNS (namespace, attributeName) {
+        return this.hasAttribute(attributeName)
+      }
+
+      /**
+   * Remove the node representation of an attribute from the element, and return it.
+   * @param {AttrService} attr
+   * @returns {AttrService} The removed Attr
+   * @throws {Error} When the element has no attribute matching attr.name
+   */
+      removeAttributeNode (attr) {
+        if (!this.hasAttribute(attr.name)) {
+          throw new Error(`Failed to execute 'removeAttributeNode': The node provided is owned by another element (no attribute named '${attr.name}')`)
+        }
+        const removed = this.getAttributeNode(attr.name)
+        this.removeAttribute(attr.name)
+        return removed
+      }
+
+      /**
+   * Remove an attribute from the element. There is no real namespace parsing here, so this ignores the namespace
+   * and behaves exactly like removeAttribute.
+   * @param {string} namespace Ignored
+   * @param {string} attributeName
+   * @returns {undefined}
+   */
+      removeAttributeNS (namespace, attributeName) {
+        this.removeAttribute(attributeName)
+      }
+
+      /**
+   * Set the node representation of an attribute, adding the attribute if it did not exist. Returns any previous
+   * Attr that had the same name, or null when there was none.
+   * @param {AttrService} attr
+   * @returns {AttrService|null} The replaced Attr, or null when the attribute was new
+   */
+      setAttributeNode (attr) {
+        const existing = this.getAttributeNode(attr.name)
+        this.setAttribute(attr.name, attr.value)
+        return existing
+      }
+
+      /**
+   * Set the node representation of an attribute. There is no real namespace parsing here, so this behaves
+   * exactly like setAttributeNode (Attr.name already carries any prefix).
+   * @param {AttrService} attr
+   * @returns {AttrService|null} The replaced Attr, or null when the attribute was new
+   */
+      setAttributeNodeNS (attr) {
+        return this.setAttributeNode(attr)
+      }
+
+      /**
+   * Set the value of an attribute, adding the attribute if it did not exist. There is no real namespace parsing
+   * here, so this ignores the namespace and behaves exactly like setAttribute.
+   * @param {string} namespace Ignored
+   * @param {string} attributeName
+   * @param {string} attributeValue
+   * @returns {undefined}
+   */
+      setAttributeNS (namespace, attributeName, attributeValue) {
+        this.setAttribute(attributeName, attributeValue)
+      }
+
       /**
    * Add the attribute (with an empty value) when it is not present, or remove it when it is - unless force says
    * which of those to do instead. Returns whether the attribute is present after the call.
@@ -3806,6 +3908,8 @@
           parent,
           children
         })
+        this.dirtyValue = null
+        this.dirtyChecked = null
         this.styleDeclaration = (0, createStyleDeclaration_1.default)()
         this.datasetProxy = (0, createDataset_1.default)(this)
       }
@@ -3829,12 +3933,94 @@
       }
 
       /**
-   * Style is not attribute-backed like most properties (see the constructor), so cloneNode needs its own copy of it.
+   * Whether this tag has a `value` (the form controls which do).
+   * @returns {boolean}
+   */
+      hasValueProperty () {
+        return ['input', 'textarea', 'select', 'button', 'option', 'output'].indexOf(this.tagName.toLowerCase()) >= 0
+      }
+
+      /**
+   * Whether this tag has a `checked` (only input does).
+   * @returns {boolean}
+   */
+      hasCheckedProperty () {
+        return this.tagName.toLowerCase() === 'input'
+      }
+
+      /**
+   * Put a plain own property on the element, as assigning a property this element does not have does in the DOM.
+   * @param {string} name
+   * @param {*} value
+   * @returns {undefined}
+   */
+      setExpando (name, value) {
+        Object.defineProperty(this, name, {
+          value,
+          writable: true,
+          configurable: true,
+          enumerable: true
+        })
+      }
+
+      /**
+   * The current value of a form control. Until it is set (or edited), it is the value attribute (the default value),
+   * or '' when there is none ('on' for a checkbox or radio); setting it never changes the attribute, like the DOM's.
+   * Only form controls (input, textarea, select, button, option, output) have one.
+   * @returns {string|undefined}
+   */
+      get value () {
+        if (!this.hasValueProperty()) {
+          return undefined
+        }
+        if (this.dirtyValue !== null) {
+          return this.dirtyValue
+        }
+        const attribute = this.getAttribute('value')
+        if (attribute !== null) {
+          return String(attribute)
+        }
+        return this.tagName.toLowerCase() === 'input' && /^(checkbox|radio)$/i.test(String(this.getAttribute('type'))) ? 'on' : ''
+      }
+
+      set value (value) {
+        if (this.hasValueProperty()) {
+          this.dirtyValue = String(value)
+        } else {
+          this.setExpando('value', value)
+        }
+      }
+
+      /**
+   * Whether a checkbox or radio input is checked. Until it is set, it follows the checked attribute (which sets the
+   * default); setting it never changes the attribute, like the DOM's. Only input has one.
+   * @returns {boolean|undefined}
+   */
+      get checked () {
+        if (!this.hasCheckedProperty()) {
+          return undefined
+        }
+        return this.dirtyChecked !== null ? this.dirtyChecked : this.hasAttribute('checked')
+      }
+
+      set checked (checked) {
+        if (this.hasCheckedProperty()) {
+          this.dirtyChecked = Boolean(checked)
+        } else {
+          this.setExpando('checked', checked)
+        }
+      }
+
+      /**
+   * Style is not attribute-backed like most properties (see the constructor), so cloneNode needs its own copy of it,
+   * and a form control keeps its current value and checkedness (as the DOM's cloneNode does).
    * @returns {NodeService}
    */
       cloneShallow () {
         const copy = super.cloneShallow()
         copy.style.cssText = this.style.cssText
+        copy.dirtyValue = this.dirtyValue
+        copy.dirtyChecked = this.dirtyChecked
         return copy
       }