@siteimprove/alfa-dom 0.89.2

package/dist/node.js

@@ -0,0 +1,325 @@
+import { Comparable, Comparison, } from "@siteimprove/alfa-comparable";
+import { Flags } from "@siteimprove/alfa-flags";
+import { Lazy } from "@siteimprove/alfa-lazy";
+import { Option } from "@siteimprove/alfa-option";
+import { Selective } from "@siteimprove/alfa-selective";
+import { Sequence } from "@siteimprove/alfa-sequence";
+import { String } from "@siteimprove/alfa-string";
+import * as tree from "@siteimprove/alfa-tree";
+import { Attribute, Comment, Document, Element, Fragment, Shadow, Slot, Slotable, Text, Type, } from "./index.js";
+import * as predicate from "./node/predicate.js";
+import * as traversal from "./node/traversal.js";
+/**
+ * @public
+ */
+export class Node extends tree.Node {
+    constructor(children, type, externalId, serializationId, extraData) {
+        super(children, type, externalId, serializationId, extraData);
+    }
+    /**
+     * {@link https://dom.spec.whatwg.org/#concept-descendant-text-content}
+     */
+    textContent(options = Node.Traversal.empty) {
+        return String.flatten(this.descendants(options).filter(Text.isText).join(""));
+    }
+    /**
+     * 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() {
+        /**
+         * Gather candidates for sequential focus navigation.
+         *
+         * @remarks
+         * These are all elements that are keyboard focusable (non-negative
+         * tabIndex), plus the shadow hosts and content elements that may contain
+         * focusable descendants.
+         *
+         * It is important that the traversal is done here on the DOM tree only.
+         * The shadow trees and content documents will be expanded later. Doing it
+         * too early potentially would mix their elements during sorting of the
+         * tabIndexes.
+         */
+        function candidates(node) {
+            if (Element.isElement(node)) {
+                const element = node;
+                const tabIndex = element.tabIndex();
+                // If the element is a shadow host that doesn't block keyboard navigation
+                // we record it to later expand its shadow tree.
+                if (element.shadow.isSome()) {
+                    // If the element has a negative tab index and is a shadow host then
+                    // none of its descendants will be part of the tab order.
+                    if (tabIndex.some((i) => i < 0)) {
+                        return Sequence.empty();
+                    }
+                    else {
+                        return Sequence.of([element, tabIndex]);
+                    }
+                }
+                // If the element contains a content document, we record it to later
+                // expand its content.
+                if (element.content.isSome()) {
+                    return Sequence.of([element, tabIndex]);
+                }
+                // If the element is a slot, we replace it by its assigned nodes.
+                if (Slot.isSlot(element)) {
+                    return Sequence.from(element.assignedNodes())
+                        .filter(Element.isElement)
+                        .map((element) => [element, tabIndex]);
+                }
+                // If the element is keyboard focusable, record it and recurse.
+                if (tabIndex.some((i) => i >= 0)) {
+                    return Sequence.of([element, tabIndex], Lazy.of(() => element.children().flatMap(candidates)));
+                }
+            }
+            // Otherwise (not an element, or not keyboard focusable), recurse into the children.
+            return node.children().flatMap(candidates);
+        }
+        /**
+         * Compare two elements, with non-negative tabindexes, by tabindex.
+         *
+         * @remarks
+         * Due to non-focusable shadow hosts being candidates (for shadow DOM
+         * expansion), we may have some indexes being None. These must be treated
+         * as 0 (insert in DOM order), rather than smaller than actual indexes
+         * (insert at start). Therefore, we cannot use Option.compareWith.
+         */
+        const comparer = ([, a], [, b]) => {
+            const aValue = a.getOr(0);
+            const bValue = b.getOr(0);
+            return aValue === 0
+                ? // "normal order" must come after any "specific order",
+                    // i.e., 0 is greater than any positive number.
+                    bValue === 0
+                        ? Comparison.Equal
+                        : Comparison.Greater
+                : bValue === 0
+                    ? // aValue cannot be 0 anymore.
+                        Comparison.Less
+                    : // If none are 0, simply compare the values.
+                        Comparable.compare(aValue, bValue);
+        };
+        /**
+         * Expand an element into the sequentially focusable elements in its
+         * shadow tree or content document.
+         *
+         * @remarks
+         * It is important that this expansion happens **after** sorting by tabindex
+         * since shadow DOM and content documents build their own sequential focus
+         * order that is inserted as-is in the light tree or parent browsing context.
+         * That is, a tabindex of 1 in a shadow tree or content document does
+         * **not** come before a tabindex of 2 in the main document.
+         */
+        function expand([element, tabIndex]) {
+            // In case of shadow host, we include it if its sequentially focusable,
+            // and always recurse into the shadow tree.
+            for (const shadow of element.shadow) {
+                if (tabIndex.some((i) => i >= 0)) {
+                    return Sequence.of(element, Lazy.of(() => shadow.tabOrder()));
+                }
+                else {
+                    return shadow.tabOrder();
+                }
+            }
+            // In case of content document, we always ignore the host (iframe) which
+            // usually redirects focus to the content.
+            for (const content of element.content) {
+                return content.tabOrder();
+            }
+            // If no shadow or content document, just keep the element.
+            return Sequence.of(element);
+        }
+        return candidates(this).sortWith(comparer).flatMap(expand);
+    }
+    parent(options = Node.Traversal.empty) {
+        const parent = this._parent;
+        // If we traverse the flat tree, we want to jump over shadow roots.
+        if (options.isSet(Node.Traversal.flattened)) {
+            return parent.flatMap((parent) => {
+                if (Shadow.isShadow(parent)) {
+                    return parent.host;
+                }
+                // Additionally, if this is a slottable light child of a shadow host, we want
+                // to search for where it is slotted, and return that parent instead.
+                if (Element.isElement(parent) &&
+                    parent.shadow.isSome() &&
+                    Slotable.isSlotable(this)) {
+                    return this.assignedSlot().flatMap((slot) => slot.parent(options));
+                }
+                return Option.of(parent);
+            });
+        }
+        return parent;
+    }
+    _path = [];
+    /**
+     * @internal
+     */
+    _internalPath(options) {
+        let path = this.parent(options)
+            .map((parent) => parent.path(options))
+            .getOr("/");
+        path += path === "/" ? "" : "/";
+        path += "node()";
+        path += `[${this.index(options) + 1}]`;
+        return path;
+    }
+    /**
+     * Get an XPath that uniquely identifies the node across descendants of its
+     * root.
+     */
+    // path may change if the subtree is attached to a parent, so we shouldn't
+    // cache it.
+    // However, path is a fairly "final" serialisation operation that makes
+    // little sense in the context of an incomplete tree.
+    // For the sake of simplicity, and until we encounter errors due to this,
+    // we accept the risk of caching the value assuming that it will only be
+    // computed on fully frozen trees.
+    path(options = Node.Traversal.empty) {
+        if (this._path[options.value] !== undefined) {
+            return this._path[options.value];
+        }
+        else {
+            this._path[options.value] = this._internalPath(options);
+            return this._internalPath(options);
+        }
+    }
+    equals(value) {
+        return value === this;
+    }
+    toEARL() {
+        return {
+            "@context": {
+                ptr: "http://www.w3.org/2009/pointers#",
+            },
+            "@type": [
+                "ptr:Pointer",
+                "ptr:SinglePointer",
+                "ptr:ExpressionPointer",
+                "ptr:XPathPointer",
+            ],
+            "ptr:expression": this.path(),
+        };
+    }
+    toSARIF() {
+        return {
+            logicalLocations: [
+                {
+                    fullyQualifiedName: this.path(),
+                },
+            ],
+        };
+    }
+}
+/**
+ * @public
+ */
+(function (Node) {
+    function isNode(value) {
+        return value instanceof Node;
+    }
+    Node.isNode = isNode;
+    class Traversal extends Flags {
+        static of(...flags) {
+            return new Traversal(Flags._reduce(...flags));
+        }
+    }
+    Node.Traversal = Traversal;
+    (function (Traversal) {
+        Traversal.none = 0;
+        /**
+         * When set, traverse the node in shadow-including tree order.
+         *
+         * {@link https://dom.spec.whatwg.org/#concept-shadow-including-tree-order}
+         */
+        Traversal.composed = (1 << 0);
+        /**
+         * When set, traverse the flattened element tree rooted at the node.
+         *
+         * {@link https://drafts.csswg.org/css-scoping/#flat-tree}
+         */
+        Traversal.flattened = (1 << 1);
+        /**
+         * When set, traverse all nested browsing contexts encountered.
+         *
+         * {@link https://html.spec.whatwg.org/#nested-browsing-context}
+         */
+        Traversal.nested = (1 << 2);
+        Traversal.empty = Traversal.of(Traversal.none);
+    })(Traversal = Node.Traversal || (Node.Traversal = {}));
+    /**
+     * Traversal options to traverse the flat tree.
+     *
+     * {@link https://drafts.csswg.org/css-scoping-1/#flattening}
+     */
+    Node.flatTree = Traversal.of(Traversal.flattened);
+    /**
+     * Traversal options to traverse all relevant nodes (flat tree and inside
+     * nested browsing container), a very frequent use case.
+     */
+    Node.fullTree = Traversal.of(Traversal.flattened, Traversal.nested);
+    /**
+     * Traversal options to traverse in shadow-including tree order and inside
+     * nested browsing context container, a common use case.
+     */
+    Node.composedNested = Traversal.of(Traversal.composed, Traversal.nested);
+    function from(json, device) {
+        return fromNode(json, device).run();
+    }
+    Node.from = from;
+    /**
+     * @internal
+     */
+    function fromNode(json, device) {
+        switch (json.type) {
+            case "element":
+                return Element.fromElement(json, device);
+            case "attribute":
+                return Attribute.fromAttribute(json);
+            case "text":
+                return Text.fromText(json);
+            case "comment":
+                return Comment.fromComment(json);
+            case "document":
+                return Document.fromDocument(json, device);
+            case "type":
+                return Type.fromType(json);
+            case "fragment":
+                return Fragment.fromFragment(json, device);
+            default:
+                throw new Error(`Unexpected node of type: ${json.type}`);
+        }
+    }
+    Node.fromNode = fromNode;
+    function clone(node, options, device) {
+        return cloneNode(node, options, device).run();
+    }
+    Node.clone = clone;
+    /**
+     * @internal
+     */
+    function cloneNode(node, options = {
+        predicate: () => false,
+        newElements: [],
+    }, device) {
+        return Selective.of(node)
+            .if(Element.isElement, Element.cloneElement(options, device))
+            .if(Attribute.isAttribute, Attribute.cloneAttribute)
+            .if(Text.isText, Text.cloneText)
+            .if(Comment.isComment, Comment.cloneComment)
+            .if(Document.isDocument, Document.cloneDocument(options, device))
+            .if(Type.isType, Type.cloneType)
+            .if(Fragment.isFragment, Fragment.cloneFragment(options, device))
+            .if(Shadow.isShadow, Shadow.cloneShadow(options, device))
+            .else(() => {
+            throw new Error(`Unexpected node of type: ${node.type}`);
+        })
+            .get();
+    }
+    Node.cloneNode = cloneNode;
+    Node.getNodesBetween = traversal.getNodesBetween;
+    Node.hasChild = predicate.hasChild, Node.hasDescendant = predicate.hasDescendant, Node.hasInclusiveDescendant = predicate.hasInclusiveDescendant, Node.hasTextContent = predicate.hasTextContent, Node.isRoot = predicate.isRoot;
+})(Node || (Node = {}));
+//# sourceMappingURL=node.js.map

package/dist/style/block.d.ts

@@ -0,0 +1,30 @@
+import type { Equatable } from "@siteimprove/alfa-equatable";
+import { Iterable } from "@siteimprove/alfa-iterable";
+import type { Serializable } from "@siteimprove/alfa-json";
+import { Option } from "@siteimprove/alfa-option";
+import type { Predicate } from "@siteimprove/alfa-predicate";
+import { Declaration } from "./declaration.js";
+/**
+ * @public
+ */
+export declare class Block implements Iterable<Declaration>, Equatable, Serializable {
+    static of(declarations: Iterable<Declaration>): Block;
+    private _declarations;
+    private constructor();
+    get declarations(): Iterable<Declaration>;
+    get size(): number;
+    isEmpty(): boolean;
+    declaration(predicate: string | Predicate<Declaration>): Option<Declaration>;
+    equals(value: unknown): value is this;
+    [Symbol.iterator](): Iterator<Declaration>;
+    toJSON(): Block.JSON;
+    toString(): string;
+}
+/**
+ * @public
+ */
+export declare namespace Block {
+    type JSON = Array<Declaration.JSON>;
+    function from(jsonOrText: JSON | string): Block;
+}
+//# sourceMappingURL=block.d.ts.map

package/dist/style/block.js

@@ -0,0 +1,63 @@
+import { Declaration as CSSDeclaration, Lexer } from "@siteimprove/alfa-css";
+import { Iterable } from "@siteimprove/alfa-iterable";
+import { Option } from "@siteimprove/alfa-option";
+import { Declaration } from "./declaration.js";
+/**
+ * @public
+ */
+export class Block {
+    static of(declarations) {
+        return new Block(Array.from(declarations));
+    }
+    _declarations;
+    constructor(declarations) {
+        this._declarations = declarations;
+    }
+    get declarations() {
+        return this._declarations;
+    }
+    get size() {
+        return this._declarations.length;
+    }
+    isEmpty() {
+        return this._declarations.length === 0;
+    }
+    declaration(predicate) {
+        return Option.from(this._declarations.find(typeof predicate === "string"
+            ? (declaration) => declaration.name === predicate
+            : predicate));
+    }
+    equals(value) {
+        return (value instanceof Block &&
+            value._declarations.length === this._declarations.length &&
+            value._declarations.every((declaration, i) => declaration.equals(this._declarations[i])));
+    }
+    *[Symbol.iterator]() {
+        yield* this._declarations;
+    }
+    toJSON() {
+        return this._declarations.map((declaration) => declaration.toJSON());
+    }
+    toString() {
+        return this._declarations.join(";\n");
+    }
+}
+/**
+ * @public
+ */
+(function (Block) {
+    function from(jsonOrText) {
+        if (typeof jsonOrText === "string") {
+            return Block.of(Iterable.map(CSSDeclaration.parseList(Lexer.lex(jsonOrText)).getUnsafe(`Could not parse CSS declarations "${jsonOrText}"`)[1], (declaration) => Declaration.from({
+                name: declaration.name,
+                value: declaration.value.join(""),
+                important: declaration.important,
+            })));
+        }
+        else {
+            return Block.of(jsonOrText.map(Declaration.from));
+        }
+    }
+    Block.from = from;
+})(Block || (Block = {}));
+//# sourceMappingURL=block.js.map

package/dist/style/declaration.d.ts

@@ -0,0 +1,65 @@
+import type { Equatable } from "@siteimprove/alfa-equatable";
+import type { Serializable } from "@siteimprove/alfa-json";
+import { Option } from "@siteimprove/alfa-option";
+import type * as json from "@siteimprove/alfa-json";
+import type { Element } from "../node/element.js";
+import type { Rule } from "./rule.js";
+/**
+ * @public
+ */
+export declare class Declaration implements Equatable, Serializable {
+    static of(name: string, value: string, important?: boolean): Declaration;
+    private readonly _name;
+    private readonly _value;
+    private readonly _important;
+    /**
+     * @remarks
+     * If the declaration is in a style rule, point to it
+     */
+    private _parent;
+    /**
+     * @remarks
+     * If the declaration is in a style attribute on an element, point to it
+     *
+     * @remarks
+     * "owner" use the same vocabulary as attribute's owner
+     *
+     * @remarks
+     * Only one of _parent and _owner should be Some.
+     */
+    private _owner;
+    private constructor();
+    get name(): string;
+    get value(): string;
+    get important(): boolean;
+    get parent(): Option<Rule>;
+    get owner(): Option<Element>;
+    ancestors(): Iterable<Rule>;
+    /**
+     * Parent rule or owner element are ignored for declaration equality.
+     */
+    equals(value: unknown): value is this;
+    toJSON(): Declaration.JSON;
+    toString(): string;
+    /**
+     * @internal
+     */
+    _attachParent(parent: Rule): boolean;
+    /**
+     * @internal
+     */
+    _attachOwner(owner: Element): boolean;
+}
+/**
+ * @public
+ */
+export declare namespace Declaration {
+    interface JSON {
+        [key: string]: json.JSON;
+        name: string;
+        value: string;
+        important: boolean;
+    }
+    function from(json: JSON): Declaration;
+}
+//# sourceMappingURL=declaration.d.ts.map

package/dist/style/declaration.js

@@ -0,0 +1,103 @@
+import { None, Option } from "@siteimprove/alfa-option";
+/**
+ * @public
+ */
+export class Declaration {
+    static of(name, value, important = false) {
+        return new Declaration(name, value, important);
+    }
+    _name;
+    _value;
+    _important;
+    /**
+     * @remarks
+     * If the declaration is in a style rule, point to it
+     */
+    _parent = None;
+    /**
+     * @remarks
+     * If the declaration is in a style attribute on an element, point to it
+     *
+     * @remarks
+     * "owner" use the same vocabulary as attribute's owner
+     *
+     * @remarks
+     * Only one of _parent and _owner should be Some.
+     */
+    _owner = None;
+    constructor(name, value, important) {
+        this._name = name;
+        this._value = value;
+        this._important = important;
+    }
+    get name() {
+        return this._name;
+    }
+    get value() {
+        return this._value;
+    }
+    get important() {
+        return this._important;
+    }
+    get parent() {
+        return this._parent;
+    }
+    get owner() {
+        return this._owner;
+    }
+    *ancestors() {
+        for (const parent of this._parent) {
+            yield parent;
+            yield* parent.ancestors();
+        }
+    }
+    /**
+     * Parent rule or owner element are ignored for declaration equality.
+     */
+    equals(value) {
+        return (value instanceof Declaration &&
+            value._name === this._name &&
+            value._value === this._value &&
+            value._important === this._important);
+    }
+    toJSON() {
+        return {
+            name: this._name,
+            value: this._value,
+            important: this._important,
+        };
+    }
+    toString() {
+        return `${this._name}: ${this._value}${this._important ? " !important" : ""}`;
+    }
+    /**
+     * @internal
+     */
+    _attachParent(parent) {
+        if (this._parent.isSome() || this._owner.isSome()) {
+            return false;
+        }
+        this._parent = Option.of(parent);
+        return true;
+    }
+    /**
+     * @internal
+     */
+    _attachOwner(owner) {
+        if (this._parent.isSome() || this._owner.isSome()) {
+            return false;
+        }
+        this._owner = Option.of(owner);
+        return true;
+    }
+}
+/**
+ * @public
+ */
+(function (Declaration) {
+    function from(json) {
+        return Declaration.of(json.name, json.value, json.important);
+    }
+    Declaration.from = from;
+})(Declaration || (Declaration = {}));
+//# sourceMappingURL=declaration.js.map

package/dist/style/rule/condition.d.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../rule.js";
+import { GroupingRule } from "./grouping.js";
+/**
+ * @public
+ */
+export declare abstract class ConditionRule<T extends string = string> extends GroupingRule<T> {
+    protected readonly _condition: string;
+    protected constructor(type: T, condition: string, rules: Array<Rule>);
+    get condition(): string;
+    toJSON(): ConditionRule.JSON<T>;
+}
+/**
+ * @public
+ */
+export declare namespace ConditionRule {
+    interface JSON<T extends string = string> extends GroupingRule.JSON<T> {
+        condition: string;
+    }
+    function isConditionRule(value: unknown): value is ConditionRule;
+}
+//# sourceMappingURL=condition.d.ts.map

package/dist/style/rule/condition.js

@@ -0,0 +1,30 @@
+import { GroupingRule } from "./grouping.js";
+/**
+ * @public
+ */
+export class ConditionRule extends GroupingRule {
+    _condition;
+    constructor(type, condition, rules) {
+        super(type, rules);
+        this._condition = condition;
+    }
+    get condition() {
+        return this._condition;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            condition: this._condition,
+        };
+    }
+}
+/**
+ * @public
+ */
+(function (ConditionRule) {
+    function isConditionRule(value) {
+        return value instanceof ConditionRule;
+    }
+    ConditionRule.isConditionRule = isConditionRule;
+})(ConditionRule || (ConditionRule = {}));
+//# sourceMappingURL=condition.js.map

package/dist/style/rule/font-face.d.ts

@@ -0,0 +1,29 @@
+import { Trampoline } from "@siteimprove/alfa-trampoline";
+import { Block } from "../block.js";
+import type { Declaration } from "../declaration.js";
+import { Rule } from "../rule.js";
+/**
+ * @public
+ */
+export declare class FontFaceRule extends Rule<"font-face"> {
+    static of(declarations: Iterable<Declaration>): FontFaceRule;
+    private readonly _style;
+    private constructor();
+    get style(): Block;
+    toJSON(): FontFaceRule.JSON;
+    toString(): string;
+}
+/**
+ * @public
+ */
+export declare namespace FontFaceRule {
+    interface JSON extends Rule.JSON<"font-face"> {
+        style: Block.JSON | string;
+    }
+    function isFontFaceRule(value: unknown): value is FontFaceRule;
+    /**
+     * @internal
+     */
+    function fromFontFaceRule(json: JSON): Trampoline<FontFaceRule>;
+}
+//# sourceMappingURL=font-face.d.ts.map