@siteimprove/alfa-dom 0.89.2

package/dist/node/traversal/lowest-common-ancestor.d.ts

@@ -0,0 +1,13 @@
+import { Option } from "@siteimprove/alfa-option";
+import { Node } from "../../index.js";
+/**
+ * Find the lowest common ancestor of two nodes:
+ * * get the ancestors chain of both
+ * * go down the chain, from root to nodes, as long as it is the same node
+ *
+ * Complexity: linear in the depth of the nodes.
+ *
+ * @internal
+ */
+export declare function lowestCommonAncestor(node1: Node, node2: Node, options?: Node.Traversal): Option<Node>;
+//# sourceMappingURL=lowest-common-ancestor.d.ts.map

package/dist/node/traversal/lowest-common-ancestor.js

@@ -0,0 +1,19 @@
+import { None, Option } from "@siteimprove/alfa-option";
+import { Node } from "../../index.js";
+/**
+ * Find the lowest common ancestor of two nodes:
+ * * get the ancestors chain of both
+ * * go down the chain, from root to nodes, as long as it is the same node
+ *
+ * Complexity: linear in the depth of the nodes.
+ *
+ * @internal
+ */
+export function lowestCommonAncestor(node1, node2, options = Node.Traversal.empty) {
+    return node1
+        .inclusiveAncestors(options)
+        .reverse()
+        .zip(node2.inclusiveAncestors(options).reverse())
+        .reduceWhile(([first1, first2]) => first1.equals(first2), (_, [node]) => Option.of(node), None);
+}
+//# sourceMappingURL=lowest-common-ancestor.js.map

package/dist/node/traversal.d.ts

@@ -0,0 +1,2 @@
+export * from "./traversal/get-nodes-between.js";
+//# sourceMappingURL=traversal.d.ts.map

package/dist/node/traversal.js

@@ -0,0 +1,2 @@
+export * from "./traversal/get-nodes-between.js";
+//# sourceMappingURL=traversal.js.map

package/dist/node/type.d.ts

@@ -0,0 +1,45 @@
+import { Option } from "@siteimprove/alfa-option";
+import { Trampoline } from "@siteimprove/alfa-trampoline";
+import * as json from "@siteimprove/alfa-json";
+import { Node } from "../node.js";
+/**
+ * @public
+ */
+export declare class Type<N extends string = string> extends Node<"type"> {
+    static of<N extends string = string>(name: N, publicId?: Option<string>, systemId?: Option<string>, externalId?: string, serializationId?: string, extraData?: any): Type<N>;
+    static empty(): Type;
+    private readonly _name;
+    private readonly _publicId;
+    private readonly _systemId;
+    private constructor();
+    get name(): N;
+    get publicId(): Option<string>;
+    get systemId(): Option<string>;
+    toJSON(options: Node.SerializationOptions & {
+        verbosity: json.Serializable.Verbosity.Minimal | json.Serializable.Verbosity.Low;
+    }): Type.MinimalJSON;
+    toJSON(options?: Node.SerializationOptions): Type.JSON<N>;
+    toString(): string;
+}
+/**
+ * @public
+ */
+export declare namespace Type {
+    interface MinimalJSON extends Node.JSON<"type"> {
+    }
+    interface JSON<N extends string = string> extends Node.JSON<"type"> {
+        name: N;
+        publicId: string | null;
+        systemId: string | null;
+    }
+    function isType(value: unknown): value is Type;
+    /**
+     * @internal
+     */
+    function fromType<N extends string = string>(json: JSON<N>): Trampoline<Type<N>>;
+    /**
+     * @internal
+     */
+    function cloneType<N extends string = string>(type: Type<N>): Trampoline<Type<N>>;
+}
+//# sourceMappingURL=type.d.ts.map

package/dist/node/type.js

@@ -0,0 +1,74 @@
+import { None, Option } from "@siteimprove/alfa-option";
+import { Trampoline } from "@siteimprove/alfa-trampoline";
+import * as json from "@siteimprove/alfa-json";
+import { Node } from "../node.js";
+/**
+ * @public
+ */
+export class Type extends Node {
+    static of(name, publicId = None, systemId = None, externalId, serializationId, extraData) {
+        return new Type(name, publicId, systemId, externalId, serializationId, extraData);
+    }
+    static empty() {
+        return new Type("html", None, None);
+    }
+    _name;
+    _publicId;
+    _systemId;
+    constructor(name, publicId, systemId, externalId, serializationId, extraData) {
+        super([], "type", externalId, serializationId, extraData);
+        this._name = name;
+        this._publicId = publicId;
+        this._systemId = systemId;
+    }
+    get name() {
+        return this._name;
+    }
+    get publicId() {
+        return this._publicId;
+    }
+    get systemId() {
+        return this._systemId;
+    }
+    toJSON(options) {
+        const result = {
+            ...super.toJSON(options),
+        };
+        delete result.children;
+        const verbosity = options?.verbosity ?? json.Serializable.Verbosity.Medium;
+        if (verbosity < json.Serializable.Verbosity.Medium) {
+            return result;
+        }
+        result.name = this.name;
+        result.publicId = this._publicId.getOr(null);
+        result.systemId = this._systemId.getOr(null);
+        return result;
+    }
+    toString() {
+        return `<!doctype ${this._name}>`;
+    }
+}
+/**
+ * @public
+ */
+(function (Type) {
+    function isType(value) {
+        return value instanceof Type;
+    }
+    Type.isType = isType;
+    /**
+     * @internal
+     */
+    function fromType(json) {
+        return Trampoline.done(Type.of(json.name, Option.from(json.publicId), Option.from(json.systemId), json.externalId, json.serializationId));
+    }
+    Type.fromType = fromType;
+    /**
+     * @internal
+     */
+    function cloneType(type) {
+        return Trampoline.done(Type.of(type.name, type.publicId, type.systemId, type.externalId, type.serializationId));
+    }
+    Type.cloneType = cloneType;
+})(Type || (Type = {}));
+//# sourceMappingURL=type.js.map

package/dist/node.d.ts

@@ -0,0 +1,263 @@
+import type { Device } from "@siteimprove/alfa-device";
+import { Flags } from "@siteimprove/alfa-flags";
+import { Option } from "@siteimprove/alfa-option";
+import type { Predicate } from "@siteimprove/alfa-predicate";
+import type { Refinement } from "@siteimprove/alfa-refinement";
+import { Sequence } from "@siteimprove/alfa-sequence";
+import type { Trampoline } from "@siteimprove/alfa-trampoline";
+import type * as earl from "@siteimprove/alfa-earl";
+import type * as json from "@siteimprove/alfa-json";
+import type * as sarif from "@siteimprove/alfa-sarif";
+import * as tree from "@siteimprove/alfa-tree";
+import { Attribute, Comment, Document, Element, Fragment, Shadow, Text, Type } from "./index.js";
+import * as predicate from "./node/predicate.js";
+import * as traversal from "./node/traversal.js";
+/**
+ * @public
+ */
+export declare abstract class Node<T extends string = string> extends tree.Node<Node.Traversal.Flag, T> implements earl.Serializable<Node.EARL>, json.Serializable<tree.Node.JSON<T>>, sarif.Serializable<sarif.Location> {
+    protected constructor(children: Array<Node>, type: T, externalId?: string, serializationId?: string, extraData?: any);
+    /**
+     * {@link https://dom.spec.whatwg.org/#concept-descendant-text-content}
+     */
+    textContent(options?: Node.Traversal): string;
+    /**
+     * Construct a sequence of descendants of this node sorted by tab index. Only
+     * nodes with a non-negative tab index are included in the sequence.
+     *
+     * {@link https://html.spec.whatwg.org/multipage/#tabindex-value}
+     */
+    tabOrder(): Sequence<Element>;
+    private _path;
+    /**
+     * @internal
+     */
+    protected _internalPath(options?: Node.Traversal): string;
+    /**
+     * Get an XPath that uniquely identifies the node across descendants of its
+     * root.
+     */
+    path(options?: Node.Traversal): string;
+    equals(value: Node): boolean;
+    equals(value: unknown): value is this;
+    toEARL(): Node.EARL;
+    toSARIF(): sarif.Location;
+}
+/**
+ * @public
+ */
+export interface Node {
+    parent(options?: Node.Traversal): Option<Node>;
+    isParentOf(node: Node, options?: Node.Traversal): boolean;
+    root(options?: Node.Traversal): Node;
+    isRootOf(node: Node, options?: Node.Traversal): boolean;
+    children(options?: Node.Traversal): Sequence<Node>;
+    isChildOf(node: Node, options?: Node.Traversal): boolean;
+    descendants(options?: Node.Traversal): Sequence<Node>;
+    isDescendantOf(node: Node, options?: Node.Traversal): boolean;
+    inclusiveDescendants(options?: Node.Traversal): Sequence<Node>;
+    isInclusiveDescendantsOf(node: Node, options?: Node.Traversal): boolean;
+    ancestors(options?: Node.Traversal): Sequence<Node>;
+    isAncestorOf(node: Node, options?: Node.Traversal): boolean;
+    inclusiveAncestors(options?: Node.Traversal): Sequence<Node>;
+    isInclusiveAncestorOf(node: Node, options?: Node.Traversal): boolean;
+    siblings(options?: Node.Traversal): Sequence<Node>;
+    isSiblingOf(node: Node, options?: Node.Traversal): boolean;
+    inclusiveSiblings(options?: Node.Traversal): Sequence<Node>;
+    isInclusiveSiblingOf(node: Node, options?: Node.Traversal): boolean;
+    preceding(options?: Node.Traversal): Sequence<Node>;
+    following(options?: Node.Traversal): Sequence<Node>;
+    first(options?: Node.Traversal): Option<Node>;
+    last(options?: Node.Traversal): Option<Node>;
+    previous(options?: Node.Traversal): Option<Node>;
+    next(options?: Node.Traversal): Option<Node>;
+    index(options?: Node.Traversal): number;
+    closest<T extends Node>(refinement: Refinement<Node, T>, options?: Node.Traversal): Option<T>;
+    closest(predicate: Predicate<Node>, options?: Node.Traversal): Option<Node>;
+}
+/**
+ * @public
+ */
+export declare namespace Node {
+    interface JSON<T extends string = string> extends tree.Node.JSON<T> {
+    }
+    interface SerializationOptions extends json.Serializable.Options {
+        device?: Device;
+    }
+    interface EARL extends earl.EARL {
+        "@context": {
+            ptr: "http://www.w3.org/2009/pointers#";
+        };
+        "@type": [
+            "ptr:Pointer",
+            "ptr:SinglePointer",
+            "ptr:ExpressionPointer",
+            "ptr:XPathPointer"
+        ];
+        "ptr:expression": string;
+        "ptr:reference"?: {
+            "@id": string;
+        };
+    }
+    function isNode(value: unknown): value is Node;
+    class Traversal extends Flags<Traversal.Flag> {
+        static of(...flags: Array<Traversal.Flag>): Traversal;
+    }
+    namespace Traversal {
+        type Flag = 0 | 1 | 2 | 4;
+        const none: Flag;
+        /**
+         * When set, traverse the node in shadow-including tree order.
+         *
+         * {@link https://dom.spec.whatwg.org/#concept-shadow-including-tree-order}
+         */
+        const composed: Flag;
+        /**
+         * When set, traverse the flattened element tree rooted at the node.
+         *
+         * {@link https://drafts.csswg.org/css-scoping/#flat-tree}
+         */
+        const flattened: Flag;
+        /**
+         * When set, traverse all nested browsing contexts encountered.
+         *
+         * {@link https://html.spec.whatwg.org/#nested-browsing-context}
+         */
+        const nested: Flag;
+        const empty: Traversal;
+    }
+    /**
+     * Traversal options to traverse the flat tree.
+     *
+     * {@link https://drafts.csswg.org/css-scoping-1/#flattening}
+     */
+    const flatTree: Traversal;
+    /**
+     * Traversal options to traverse all relevant nodes (flat tree and inside
+     * nested browsing container), a very frequent use case.
+     */
+    const fullTree: Traversal;
+    /**
+     * Traversal options to traverse in shadow-including tree order and inside
+     * nested browsing context container, a common use case.
+     */
+    const composedNested: Traversal;
+    function from(json: Element.JSON, device?: Device): Element;
+    function from(json: Attribute.JSON, device?: Device): Attribute;
+    function from(json: Text.JSON, device?: Device): Text;
+    function from(json: Comment.JSON, device?: Device): Comment;
+    function from(json: Document.JSON, device?: Device): Document;
+    function from(json: Type.JSON, device?: Device): Document;
+    function from(json: Fragment.JSON, device?: Device): Fragment;
+    function from(json: JSON, device?: Device): Node;
+    /**
+     * @internal
+     */
+    function fromNode(json: JSON, device?: Device): Trampoline<Node>;
+    interface ElementReplacementOptions {
+        predicate: Predicate<Element>;
+        newElements: Iterable<Element>;
+    }
+    /**
+     * Creates a new `Element` instance with the same value as the original and
+     * deeply referentially non-equal. Optionally replaces child elements based
+     * on a predicate.
+     *
+     * @remarks
+     * The clone will have the same `externalId` as the original.
+     * The clone will *not* get `extraData` from the original, instead it will be
+     * `undefined`.
+     */
+    function clone(node: Element, options?: ElementReplacementOptions, device?: Device): Element;
+    /**
+     * Creates a new `Attribute` instance with the same value as the original and
+     * referentially non-equal.
+     *
+     * @remarks
+     * The clone will have the same `externalId` as the original.
+     * The clone will *not* get `extraData` from the original, instead it will be
+     * `undefined`.
+     */
+    function clone(node: Attribute, options?: ElementReplacementOptions, device?: Device): Attribute;
+    /**
+     * Creates a new `Text` instance with the same value as the original and
+     * referentially non-equal.
+     *
+     * @remarks
+     * The clone will have the same `externalId` as the original.
+     * The clone will *not* get `extraData` from the original, instead it will be
+     * `undefined`.
+     */
+    function clone(node: Text, options?: ElementReplacementOptions, device?: Device): Text;
+    /**
+     * Creates a new `Comment` instance with the same value as the original and
+     * referentially non-equal.
+     *
+     * @remarks
+     * The clone will have the same `externalId` as the original.
+     * The clone will *not* get `extraData` from the original, instead it will be
+     * `undefined`.
+     */
+    function clone(node: Comment, options?: ElementReplacementOptions, device?: Device): Comment;
+    /**
+     * Creates a new `Document` instance with the same value as the original and
+     * deeply referentially non-equal. Optionally replaces child elements based
+     * on a predicate.
+     *
+     * @remarks
+     * The clone will have the same `externalId` as the original.
+     * The clone will *not* get `extraData` from the original, instead it will be
+     * `undefined`.
+     */
+    function clone(node: Document, options?: ElementReplacementOptions, device?: Device): Document;
+    /**
+     * Creates a new `Type` instance with the same value as the original and
+     * referentially non-equal.
+     *
+     * @remarks
+     * The clone will have the same `externalId` as the original.
+     * The clone will *not* get `extraData` from the original, instead it will be
+     * `undefined`.
+     */
+    function clone(node: Type, options?: ElementReplacementOptions, device?: Device): Document;
+    /**
+     * Creates a new `Fragment` instance with the same value as the original and
+     * deeply referentially non-equal. Optionally replaces child elements based
+     * on a predicate.
+     *
+     * @remarks
+     * The clone will have the same `externalId` as the original.
+     * The clone will *not* get `extraData` from the original, instead it will be
+     * `undefined`.
+     */
+    function clone(node: Fragment, options?: ElementReplacementOptions, device?: Device): Fragment;
+    /**
+     * Creates a new `Shadow` instance with the same value as the original and
+     * deeply referentially non-equal. Optionally replaces child elements based
+     * on a predicate.
+     *
+     * @remarks
+     * The clone will have the same `externalId` as the original.
+     * The clone will *not* get `extraData` from the original, instead it will be
+     * `undefined`.
+     */
+    function clone(node: Shadow, options?: ElementReplacementOptions, device?: Device): Shadow;
+    /**
+     * Creates a new `Node` instance with the same value as the original and
+     * deeply referentially non-equal. Optionally replaces child elements based
+     * on a predicate.
+     *
+     * @remarks
+     * The clone will have the same `externalId` as the original.
+     * The clone will *not* get `extraData` from the original, instead it will be
+     *   `undefined`.
+     */
+    function clone(node: Node, options?: ElementReplacementOptions, device?: Device): Node;
+    /**
+     * @internal
+     */
+    function cloneNode(node: Node, options?: ElementReplacementOptions, device?: Device): Trampoline<Node>;
+    const getNodesBetween: typeof traversal.getNodesBetween;
+    const hasChild: typeof predicate.hasChild, hasDescendant: typeof predicate.hasDescendant, hasInclusiveDescendant: typeof predicate.hasInclusiveDescendant, hasTextContent: typeof predicate.hasTextContent, isRoot: typeof predicate.isRoot;
+}
+//# sourceMappingURL=node.d.ts.map