pseudo-dom 0.17.0 → 1.0.0

package/dist/services/ElementService.d.ts

@@ -1,7 +1,5 @@
 /**
- * @file Substitute for the DOM Element Class.
- * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @version 1.0.0
+ * Substitute for the DOM Element Class.
  */
 import { PseudoNode } from '../interfaces/PseudoNode';
 import { PseudoElement } from '../interfaces/PseudoElement';
@@ -27,18 +25,6 @@ type DOMRect = {
 };
 /**
  * Simulate the behaviour of the Element Class when there is no DOM available.
- * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @class
- * @augments PseudoNode
- * @property {string} tagName
- * @property {string} className
- * @property {string} id
- * @property {string} innerHtml
- * @property {Array} attributes
- * @property {function} hasAttribute
- * @property {function} setAttribute
- * @property {function} getAttribute
- * @property {function} removeAttribute
  */
 export declare class ElementService extends NodeService implements Partial<PseudoElement> {
     id: string;
@@ -67,12 +53,11 @@ export declare class ElementService extends NodeService implements Partial<Pseud
     private shadowRootInstance;
     private defaultEventApplied;
     /**
-     * @param {Object} [settings={}]
-     * @param {string} [settings.tagName=''] The name of the tag this element represents
-     * @param {Array<{name: string, value: *}>} [settings.attributes=[]] The attributes (also assigned as properties) to start with
-     * @param {PseudoNode|null} [settings.parent=null] The node to add this element to as its last child
-     * @param {Array<PseudoNode>} [settings.children=[]] The nodes to start as children
-     * @constructor
+     * @param settings
+     * @param settings.tagName The name of the tag this element represents
+     * @param settings.attributes The attributes (also assigned as properties) to start with
+     * @param settings.parent The node to add this element to as its last child
+     * @param settings.children The nodes to start as children
      */
     constructor({ tagName, attributes, parent, children }?: {
         tagName?: string;
@@ -83,45 +68,38 @@ export declare class ElementService extends NodeService implements Partial<Pseud
     /**
      * The attributes with the values they have now: the ones which are also properties (className, id, style, ...) can
      * have been changed through the property, which does not change the stored list.
-     * @returns {Array<{name: string, value: *}>}
      */
     private currentAttributes;
     get nodeName(): string;
     /**
      * A copy of this element without its children: the same tag and attributes (the values which are objects, such as
      * style, are copied too rather than shared), but not its parent or listeners.
-     * @returns {ElementService}
      */
     protected cloneShallow(): NodeService;
     /**
      * Elements are equal when they have the same tag and the same attributes (in any order), which is what isEqualNode
      * checks before it compares the children.
-     * @param {NodeService} other The element to compare with
-     * @returns {boolean}
+     * @param other The element to compare with
      */
     protected equalsShallow(other: NodeService): boolean;
     get tagName(): string;
     /**
      * The local part of the element's qualified name. There is no real namespace parsing here, so this is always the
      * same as tagName.
-     * @returns {string}
      */
     get localName(): string;
     /**
      * The element's namespace prefix, or null when it has none. There is no real namespace parsing here, so this is
      * always null.
-     * @returns {string|null}
      */
     get prefix(): string | null;
     /**
      * The HTML markup of this element's children. Only the getter is here (the setter, which needs to build new
      * elements from parsed HTML, is on HTMLElementService - see its class comment).
-     * @returns {string}
      */
     get innerHTML(): string;
     /**
      * The HTML markup of this element itself, including its children. Only the getter is here (see innerHTML).
-     * @returns {string}
      */
     get outerHTML(): string;
     get nodeType(): number;
@@ -131,253 +109,226 @@ export declare class ElementService extends NodeService implements Partial<Pseud
     set className(className: string);
     /**
      * Some elements have default behaviour, this registers it when the element is added.
-     * @returns {Function}
      */
     /**
      * A live view of this element's element children (text, comments and the like are not included).
-     * @returns {PseudoHTMLCollection}
      */
     get children(): PseudoHTMLCollection;
     /**
      * How many element children this element has.
-     * @returns {number}
      */
     get childElementCount(): number;
     /**
      * The first child of this element which is an element, or null when there is none.
-     * @returns {PseudoElement|null}
      */
     get firstElementChild(): PseudoElement | null;
     /**
      * The last child of this element which is an element, or null when there is none.
-     * @returns {PseudoElement|null}
      */
     get lastElementChild(): PseudoElement | null;
     /**
      * The sibling after this one which is an element, or null when there is none.
-     * @returns {PseudoElement|null}
      */
     get nextElementSibling(): PseudoElement | null;
     /**
      * The sibling before this one which is an element, or null when there is none.
-     * @returns {PseudoElement|null}
      */
     get previousElementSibling(): PseudoElement | null;
     /**
      * Put an element at a position relative to this one: beforebegin (before this element, as its previous sibling),
      * afterbegin (as this element's first child), beforeend (as this element's last child) or afterend (after this
      * element, as its next sibling).
-     * @param {string} position beforebegin, afterbegin, beforeend or afterend
-     * @param {ElementService} element The element to insert
-     * @returns {ElementService|null} The inserted element, or null when the position needed a parent this element does not have
+     * @param position beforebegin, afterbegin, beforeend or afterend
+     * @param element The element to insert
+     * @returns The inserted element, or null when the position needed a parent this element does not have
      * @throws {Error} When the position is not one of the four above
      */
     insertAdjacentElement(position: string, element: PseudoElement): PseudoElement | null;
     /**
      * Put text at a position relative to this element, the same as insertAdjacentElement but the text becomes a text node.
-     * @param {string} position beforebegin, afterbegin, beforeend or afterend
-     * @param {string} text The text to insert
+     * @param position beforebegin, afterbegin, beforeend or afterend
+     * @param text The text to insert
      * @throws {Error} When the position is not one of the four above
      */
     insertAdjacentText(position: string, text: string): void;
     /**
      * Shared implementation for insertAdjacentElement / insertAdjacentText.
-     * @param {string} position beforebegin, afterbegin, beforeend or afterend
-     * @param {PseudoNode|string} node The node (or text) to insert
-     * @returns {PseudoNode|null} The inserted node, or null when the position needed a parent this element does not have
+     * @param position beforebegin, afterbegin, beforeend or afterend
+     * @param node The node (or text) to insert
+     * @returns The inserted node, or null when the position needed a parent this element does not have
      * @throws {Error} When the position is not one of the four above
      */
     private insertAdjacent;
     /**
      * Not implemented yet (HTML parsing is out of scope for now).
-     * @param {string} position beforebegin, afterbegin, beforeend or afterend
-     * @param {string} text The markup which would be parsed
+     * @param position beforebegin, afterbegin, beforeend or afterend
+     * @param text The markup which would be parsed
      * @throws {Error}
      */
     insertAdjacentHTML(position: string, text: string): void;
     /**
      * Whether this element itself (not its descendants) matches the given CSS selector.
-     * @param {string} selectors A CSS selector
-     * @returns {boolean}
+     * @param selectors A CSS selector
      */
     matches(selectors: string): boolean;
     /**
      * The nearest ancestor of this element (starting with this element itself) which matches the CSS selector, or
      * null when none of them do.
-     * @param {string} selectors A CSS selector
-     * @returns {PseudoElement|null}
+     * @param selectors A CSS selector
      */
     closest(selectors: string): PseudoElement | null;
     applyDefaultEvent(): Function;
     /**
      * An element which is added as a child gets its default events (for example a submit button submits its form).
-     * @param {NodeService} child The node which was inserted
+     * @param child The node which was inserted
      */
     protected childInserted(child: NodeService): void;
     /**
      * Check whether the element has an attribute by that name.
-     * @param {string} attributeName
-     * @returns {boolean}
+     * @param attributeName
      */
     hasAttribute(attributeName: string): boolean;
     /**
      * Set the value of an attribute, adding the attribute if it did not exist.
-     * @param {string} attributeName
-     * @param {string} attributeValue
-     * @returns {undefined}
+     * @param attributeName
+     * @param attributeValue
      */
     setAttribute(attributeName: string, attributeValue: string): void;
     /**
      * Retrieve the value of an attribute.
-     * @param {string} attributeName
-     * @returns {string|null} The value, or null when there is no such attribute
+     * @param attributeName
+     * @returns The value, or null when there is no such attribute
      */
     getAttribute(attributeName: string): string | null;
     /**
      * Remove an attribute from the element.
-     * @param {string} attributeName
-     * @returns {undefined}
+     * @param attributeName
      */
     removeAttribute(attributeName: string): void;
     /**
      * The name of every attribute on the element, in the order they were set.
-     * @returns {Array<string>}
      */
     getAttributeNames(): Array<string>;
     /**
      * Whether the element has any attributes at all.
-     * @returns {boolean}
      */
     hasAttributes(): boolean;
     /**
      * 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
+     * @param attributeName
+     * @returns An Attr for the attribute, or null when there is no such attribute
      */
     getAttributeNode(attributeName: string): AttrService | 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
+     * @param namespace Ignored
+     * @param attributeName
+     * @returns An Attr for the attribute, or null when there is no such attribute
      */
     getAttributeNodeNS(namespace: string, attributeName: string): AttrService | null;
     /**
      * 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
+     * @param namespace Ignored
+     * @param attributeName
+     * @returns The value, or null when there is no such attribute
      */
     getAttributeNS(namespace: string, attributeName: string): string | null;
     /**
      * 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}
+     * @param namespace Ignored
+     * @param attributeName
      */
     hasAttributeNS(namespace: string, attributeName: string): boolean;
     /**
      * Remove the node representation of an attribute from the element, and return it.
-     * @param {AttrService} attr
-     * @returns {AttrService} The removed Attr
+     * @param attr
+     * @returns The removed Attr
      * @throws {Error} When the element has no attribute matching attr.name
      */
     removeAttributeNode(attr: AttrService): AttrService;
     /**
      * 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}
+     * @param namespace Ignored
+     * @param attributeName
      */
     removeAttributeNS(namespace: string, attributeName: string): void;
     /**
      * 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
+     * @param attr
+     * @returns The replaced Attr, or null when the attribute was new
      */
     setAttributeNode(attr: AttrService): AttrService | null;
     /**
      * 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
+     * @param attr
+     * @returns The replaced Attr, or null when the attribute was new
      */
     setAttributeNodeNS(attr: AttrService): AttrService | null;
     /**
      * 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}
+     * @param namespace Ignored
+     * @param attributeName
+     * @param attributeValue
      */
     setAttributeNS(namespace: string, attributeName: string, attributeValue: string): void;
     /**
      * 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.
-     * @param {string} attributeName
-     * @param {boolean} [force]
-     * @returns {boolean}
+     * @param attributeName
+     * @param force
      */
     toggleAttribute(attributeName: string, force?: boolean): boolean;
     /**
      * The size of the element and its position, settable directly - there is no layout engine here to compute it.
-     * @returns {DOMRect}
      */
     getBoundingClientRect(): DOMRect;
     /**
      * The bounding rectangles for each line of text in the element, settable directly - there is no layout engine
      * here to compute it.
-     * @returns {Array<DOMRect>}
      */
     getClientRects(): Array<DOMRect>;
     /**
      * The Animation objects currently active on the element, settable directly - there is no animation engine here.
-     * @returns {Array<*>}
      */
     getAnimations(): Array<any>;
     /**
      * Whether the element is expected to be visible, settable directly - there is no rendering here to check it.
-     * @returns {boolean}
      */
     checkVisibility(): boolean;
     /**
      * A read-only view of the element's own inline style declarations (there is no CSS cascade here, so this is not a
      * real computed style - just what the element's own style object holds).
-     * @returns {{get: function(string): (string|undefined)}}
      */
     computedStyleMap(): {
         get: (property: string) => string | undefined;
     };
     /**
      * Whether this element currently has capture of the given pointer.
-     * @param {number} pointerId
-     * @returns {boolean}
+     * @param pointerId
      */
     hasPointerCapture(pointerId: number): boolean;
     /**
      * Give this element capture of the given pointer.
-     * @param {number} pointerId
-     * @returns {undefined}
+     * @param pointerId
      */
     setPointerCapture(pointerId: number): void;
     /**
      * Release this element's capture of the given pointer, if it had it.
-     * @param {number} pointerId
-     * @returns {undefined}
+     * @param pointerId
      */
     releasePointerCapture(pointerId: number): void;
     /**
      * Scroll to the given position (or, given an options object, the position(s) it has). There is no real scrollable
      * viewport here: this just sets scrollLeft / scrollTop.
-     * @param {number|{left: number, top: number}} [x=0]
-     * @param {number} [y=0]
-     * @returns {undefined}
+     * @param x
+     * @param y
      */
     scroll(x?: number | {
         left?: number;
@@ -385,9 +336,8 @@ export declare class ElementService extends NodeService implements Partial<Pseud
     }, y?: number): void;
     /**
      * Scroll to the given position. An alias for scroll.
-     * @param {number|{left: number, top: number}} [x=0]
-     * @param {number} [y=0]
-     * @returns {undefined}
+     * @param x
+     * @param y
      */
     scrollTo(x?: number | {
         left?: number;
@@ -395,9 +345,8 @@ export declare class ElementService extends NodeService implements Partial<Pseud
     }, y?: number): void;
     /**
      * Scroll by the given amount, relative to the current position.
-     * @param {number|{left: number, top: number}} [x=0]
-     * @param {number} [y=0]
-     * @returns {undefined}
+     * @param x
+     * @param y
      */
     scrollBy(x?: number | {
         left?: number;
@@ -406,25 +355,21 @@ export declare class ElementService extends NodeService implements Partial<Pseud
     /**
      * Scroll an ancestor until this element is in view. There is no real viewport here for that to mean anything, so
      * this does nothing (override it on an instance in a test which needs to observe the call).
-     * @returns {undefined}
      */
     scrollIntoView(): void;
     /**
      * Asynchronously ask for the element to be shown fullscreen. There is no real fullscreen here, so this just
      * resolves, like a browser granting the request would.
-     * @returns {Promise<void>}
      */
     requestFullscreen(): Promise<void>;
     /**
      * Asynchronously ask for the pointer to be locked to this element. There is no real pointer lock here, so this
      * just resolves, like a browser granting the request would.
-     * @returns {Promise<void>}
      */
     requestPointerLock(): Promise<void>;
     /**
      * Attach a shadow tree to this element and return its ShadowRoot. Throws when it already hosts one.
-     * @param {{mode: string}} options
-     * @returns {PseudoShadowRoot}
+     * @param options
      * @throws {Error}
      */
     attachShadow(options: {
@@ -433,20 +378,17 @@ export declare class ElementService extends NodeService implements Partial<Pseud
     /**
      * This element's shadow root, when it has one attached in 'open' mode, or null (including when the mode is
      * 'closed' - it still exists, but is not reachable this way, like the DOM's).
-     * @returns {PseudoShadowRoot|null}
      */
     get shadowRoot(): PseudoShadowRoot | null;
     /**
      * Read one of the aria-* reflected properties (see the individual aria* getters/setters below).
-     * @param {string} attributeName A real aria-* attribute name (aria-label, ...)
-     * @returns {string}
+     * @param attributeName A real aria-* attribute name (aria-label, ...)
      */
     private getAriaAttribute;
     /**
      * Write one of the aria-* reflected properties.
-     * @param {string} attributeName A real aria-* attribute name (aria-label, ...)
-     * @param {string} value
-     * @returns {undefined}
+     * @param attributeName A real aria-* attribute name (aria-label, ...)
+     * @param value
      */
     private setAriaAttribute;
     get ariaAtomic(): string;