@siteimprove/alfa-dom 0.89.2

package/dist/jsx.d.ts

@@ -0,0 +1,44 @@
+import type { Element, Node } from "./index.js";
+import type * as dom from "./index.js";
+/**
+ * @public
+ */
+export declare function jsx<N extends string = string>(name: N, properties?: jsx.Properties | null, ...children: jsx.Children): Element<N>;
+/**
+ * @public
+ */
+export declare namespace jsx {
+    type Child = Node | string;
+    /**
+     * @remarks
+     * This type is declared using the short array syntax (`[]`) to avoid issues
+     * with circular generic references.
+     */
+    type Children = (Child | Children)[];
+    interface Properties {
+        [name: string]: unknown;
+        /**
+         * An optional record of CSS property names and their associated values.
+         * This works similarly to the `style` property in React.
+         *
+         * {@link https://reactjs.org/docs/dom-elements.html#style}
+         */
+        style?: Record<string, string>;
+    }
+    /**
+     * {@link https://www.typescriptlang.org/docs/handbook/jsx.html}
+     *
+     * @remarks
+     * This namespace is currently needed to let the TypeScript compiler know the
+     * shape of elements returned by `jsx()` and the properties that tags allow.
+     * We should keep an eye on https://github.com/microsoft/TypeScript/issues/14729
+     * as it might provide an opportunity to get rid of this namespace entirely.
+     */
+    namespace JSX {
+        type Element<N extends string = string> = dom.Element<N>;
+        interface IntrinsicElements {
+            [tag: string]: Properties;
+        }
+    }
+}
+//# sourceMappingURL=jsx.d.ts.map

package/dist/jsx.js

@@ -0,0 +1,45 @@
+import { h } from "./h.js";
+import { Rectangle } from "@siteimprove/alfa-rectangle";
+const { entries } = Object;
+/**
+ * @public
+ */
+export function jsx(name, properties = null, ...children) {
+    const attributes = {};
+    const style = {};
+    let box = undefined;
+    let device = undefined;
+    let externalId = undefined;
+    let serializationId = undefined;
+    for (const [name, value] of entries(properties ?? {})) {
+        if (value === null || value === undefined) {
+            continue;
+        }
+        switch (name) {
+            case "style":
+                for (const [propName, propValue] of entries(value)) {
+                    style[propName] = propValue;
+                }
+                continue;
+            case "box":
+                const deviceAndBox = value;
+                box = Rectangle.from(deviceAndBox);
+                device = deviceAndBox.device;
+                continue;
+            case "externalId":
+                if (typeof value === "string") {
+                    externalId = value;
+                }
+                continue;
+            case "serializationId":
+                if (typeof value === "string") {
+                    serializationId = value;
+                }
+                continue;
+            default:
+                attributes[name] = value === true ? value : `${value}`;
+        }
+    }
+    return h(name, attributes, children.flat(Infinity), style, box, device, externalId, serializationId);
+}
+//# sourceMappingURL=jsx.js.map

package/dist/namespace.d.ts

@@ -0,0 +1,43 @@
+/**
+ * {@link https://infra.spec.whatwg.org/#namespaces}
+ *
+ * @public
+ */
+export declare enum Namespace {
+    /**
+     * {@link https://infra.spec.whatwg.org/#html-namespace}
+     */
+    HTML = "http://www.w3.org/1999/xhtml",
+    /**
+     * {@link https://infra.spec.whatwg.org/#mathml-namespace}
+     */
+    MathML = "http://www.w3.org/1998/Math/MathML",
+    /**
+     * {@link https://infra.spec.whatwg.org/#svg-namespace}
+     */
+    SVG = "http://www.w3.org/2000/svg",
+    /**
+     * {@link https://infra.spec.whatwg.org/#xlink-namespace}
+     */
+    XLink = "http://www.w3.org/1999/xlink",
+    /**
+     * {@link https://infra.spec.whatwg.org/#xml-namespace}
+     */
+    XML = "http://www.w3.org/XML/1998/namespace",
+    /**
+     * @remarks
+     * The trailing slash is not a typo! For some reason it snuck its way into the
+     * specification and whether or not it is strictly required is an awfully good
+     * question.
+     *
+     * {@link https://infra.spec.whatwg.org/#xmlns-namespace}
+     */
+    XMLNS = "http://www.w3.org/2000/xmlns/"
+}
+/**
+ * @public
+ */
+export declare namespace Namespace {
+    function isNamespace(value: string): value is Namespace;
+}
+//# sourceMappingURL=namespace.d.ts.map

package/dist/namespace.js

@@ -0,0 +1,57 @@
+/**
+ * {@link https://infra.spec.whatwg.org/#namespaces}
+ *
+ * @public
+ */
+export var Namespace;
+(function (Namespace) {
+    /**
+     * {@link https://infra.spec.whatwg.org/#html-namespace}
+     */
+    Namespace["HTML"] = "http://www.w3.org/1999/xhtml";
+    /**
+     * {@link https://infra.spec.whatwg.org/#mathml-namespace}
+     */
+    Namespace["MathML"] = "http://www.w3.org/1998/Math/MathML";
+    /**
+     * {@link https://infra.spec.whatwg.org/#svg-namespace}
+     */
+    Namespace["SVG"] = "http://www.w3.org/2000/svg";
+    /**
+     * {@link https://infra.spec.whatwg.org/#xlink-namespace}
+     */
+    Namespace["XLink"] = "http://www.w3.org/1999/xlink";
+    /**
+     * {@link https://infra.spec.whatwg.org/#xml-namespace}
+     */
+    Namespace["XML"] = "http://www.w3.org/XML/1998/namespace";
+    /**
+     * @remarks
+     * The trailing slash is not a typo! For some reason it snuck its way into the
+     * specification and whether or not it is strictly required is an awfully good
+     * question.
+     *
+     * {@link https://infra.spec.whatwg.org/#xmlns-namespace}
+     */
+    Namespace["XMLNS"] = "http://www.w3.org/2000/xmlns/";
+})(Namespace || (Namespace = {}));
+/**
+ * @public
+ */
+(function (Namespace) {
+    function isNamespace(value) {
+        switch (value) {
+            case Namespace.HTML:
+            case Namespace.MathML:
+            case Namespace.SVG:
+            case Namespace.XLink:
+            case Namespace.XML:
+            case Namespace.XMLNS:
+                return true;
+            default:
+                return false;
+        }
+    }
+    Namespace.isNamespace = isNamespace;
+})(Namespace || (Namespace = {}));
+//# sourceMappingURL=namespace.js.map

package/dist/native.d.ts

@@ -0,0 +1,18 @@
+import type { Attribute, Comment, Document, Element, Node, Text, Type } from "./index.js";
+/**
+ * @internal
+ */
+export declare namespace Native {
+    function fromNode(node: globalThis.Element, options?: Options): Promise<Element.JSON>;
+    function fromNode(node: globalThis.Attr, options?: Options): Promise<Attribute.JSON>;
+    function fromNode(node: globalThis.Text, options?: Options): Promise<Text.JSON>;
+    function fromNode(node: globalThis.Comment, options?: Options): Promise<Comment.JSON>;
+    function fromNode(node: globalThis.Document, options?: Options): Promise<Document.JSON>;
+    function fromNode(node: globalThis.DocumentType, options?: Options): Promise<Type.JSON>;
+    function fromNode(node: globalThis.Node, options?: Options): Promise<Node.JSON>;
+    interface Options {
+        /** Whether to enforce anonymous CORS on <link> missing one */
+        withCrossOrigin?: boolean;
+    }
+}
+//# sourceMappingURL=native.d.ts.map

package/dist/native.js

@@ -0,0 +1,449 @@
+/// <reference lib="dom" />
+/**
+ * @internal
+ */
+export var Native;
+(function (Native) {
+    async function fromNode(node, options) {
+        const { withCrossOrigin = false } = options ?? {};
+        return toNode(node);
+        async function toNode(node) {
+            switch (node.nodeType) {
+                case node.ELEMENT_NODE:
+                    return toElement(node);
+                case node.ATTRIBUTE_NODE:
+                    return toAttribute(node);
+                case node.TEXT_NODE:
+                    return toText(node);
+                case node.COMMENT_NODE:
+                    return toComment(node);
+                case node.DOCUMENT_NODE:
+                    return toDocument(node);
+                case node.DOCUMENT_TYPE_NODE:
+                    return toType(node);
+            }
+            throw new Error(`Unsupported node of type: ${node.nodeType}`);
+        }
+        async function toElement(element) {
+            return {
+                type: "element",
+                namespace: element.namespaceURI,
+                prefix: element.prefix,
+                name: element.localName,
+                attributes: map(element.attributes, toAttribute),
+                style: "style" in element ? toBlock(element.style) : null,
+                children: await mapAsync(element.childNodes, toNode),
+                shadow: element.shadowRoot !== null
+                    ? await toShadow(element.shadowRoot)
+                    : null,
+                content: "contentDocument" in element && element.contentDocument !== null
+                    ? await toDocument(element.contentDocument)
+                    : null,
+                box: toRectangle(element.getBoundingClientRect()),
+            };
+        }
+        function toAttribute(attribute) {
+            return {
+                type: "attribute",
+                namespace: attribute.namespaceURI,
+                prefix: attribute.prefix,
+                name: attribute.localName,
+                value: attribute.value,
+            };
+        }
+        function toText(text) {
+            return {
+                type: "text",
+                data: text.data,
+            };
+        }
+        function toComment(comment) {
+            return {
+                type: "comment",
+                data: comment.data,
+            };
+        }
+        async function toDocument(document) {
+            if (withCrossOrigin) {
+                await ensureCrossOrigin(document);
+            }
+            return {
+                type: "document",
+                children: await mapAsync(document.childNodes, toNode),
+                style: getStyleSheets(document),
+            };
+        }
+        function toType(type) {
+            return {
+                type: "type",
+                name: type.name,
+                publicId: type.publicId === "" ? null : type.publicId,
+                systemId: type.systemId === "" ? null : type.systemId,
+            };
+        }
+        async function toShadow(shadow) {
+            if (withCrossOrigin) {
+                await ensureCrossOrigin(document);
+            }
+            return {
+                type: "shadow",
+                mode: shadow.mode,
+                children: await mapAsync(shadow.childNodes, toNode),
+                style: getStyleSheets(shadow),
+            };
+        }
+        /**
+         * @privateRemarks
+         * Adopted stylesheets are assumed to be ordered after document stylesheets.
+         *
+         * {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets}
+         */
+        function getStyleSheets(docOrShadow) {
+            return [
+                ...map(docOrShadow.styleSheets, toSheet),
+                // `adoptedStyleSheets` generated by JSDOM can be undefined despite it violating the type.
+                // It seems this part of the specification is still not fully implemented in JSDOM as of July 2024.
+                // https://github.com/jsdom/jsdom/issues/3444
+                ...map(docOrShadow.adoptedStyleSheets ?? [], toSheet),
+            ];
+        }
+        function toSheet(sheet) {
+            let rules;
+            try {
+                rules = map(sheet.cssRules, toRule);
+            }
+            catch {
+                rules = [];
+            }
+            return {
+                rules,
+                disabled: sheet.disabled,
+                condition: 
+                // Sheets generated by pre-renderers like JSDOM do not contain media
+                // at all.
+                // OTOH, the MediaList.mediaText interface treat null as the empty
+                // string, so we must do the same here (in the other direction).
+                (sheet?.media?.mediaText ?? "") === "" ? null : sheet.media.mediaText,
+            };
+        }
+        function toRule(rule) {
+            // In the best case, rule.constructor.name works and everything is fine.
+            switch (rule.constructor.name) {
+                case "CSSFontFaceRule":
+                    return toFontFaceRule(rule);
+                case "CSSImportRule":
+                    return toImportRule(rule);
+                case "CSSKeyframeRule":
+                    return toKeyframeRule(rule);
+                case "CSSKeyframesRule":
+                    return toKeyframesRule(rule);
+                case "CSSLayerBlockRule":
+                    return toLayerBlockRule(rule);
+                case "CSSLayerStatementRule":
+                    return toLayerStatementRule(rule);
+                case "CSSMediaRule":
+                    return toMediaRule(rule);
+                case "CSSNamespaceRule":
+                    return toNamespaceRule(rule);
+                case "CSSPageRule":
+                    return toPageRule(rule);
+                case "CSSStyleRule":
+                    return toStyleRule(rule);
+                case "CSSSupportsRule":
+                    return toSupportsRule(rule);
+            }
+            // In some case (June 2024: in Firefox), rule.constructor.name returns
+            // undefined when used from an extension's content script. This is likely
+            // due to the fact that the rule has been created in the "page" world,
+            // but this code is evaluated in a content script world which does not
+            // have access to the actual constructor.
+            // However, in that case, .toString() seems to work… Since it may have been
+            // redefined along the prototype chain, we make sure to use the basic one.
+            // see https://stackoverflow.com/questions/43616128/undefined-javascript-object-constructor
+            switch (Object.prototype.toString.apply(rule)) {
+                case "[object CSSFontFaceRule]":
+                    return toFontFaceRule(rule);
+                case "[object CSSImportRule]":
+                    return toImportRule(rule);
+                case "[object CSSKeyframeRule]":
+                    return toKeyframeRule(rule);
+                case "[object CSSKeyframesRule]":
+                    return toKeyframesRule(rule);
+                case "[object CSSLayerBlockRule]":
+                    return toLayerBlockRule(rule);
+                case "[object CSSLayerStatementRule]":
+                    return toLayerStatementRule(rule);
+                case "[object CSSMediaRule]":
+                    return toMediaRule(rule);
+                case "[object CSSNamespaceRule]":
+                    return toNamespaceRule(rule);
+                case "[object CSSPageRule]":
+                    return toPageRule(rule);
+                case "[object CSSStyleRule]":
+                    return toStyleRule(rule);
+                case "[object CSSSupportsRule]":
+                    return toSupportsRule(rule);
+            }
+            // If everything else failed, we default to the deprecated `type`.
+            // This is clearly bad, notably because @layer rules where introduced
+            // after the deprecation and thus do not have a `type` property.
+            // But it might still save the show in some corner cases.
+            switch (rule.type) {
+                case CSSRule.FONT_FACE_RULE:
+                    return toFontFaceRule(rule);
+                case CSSRule.IMPORT_RULE:
+                    return toImportRule(rule);
+                case CSSRule.KEYFRAME_RULE:
+                    return toKeyframeRule(rule);
+                case CSSRule.KEYFRAMES_RULE:
+                    return toKeyframesRule(rule);
+                // case "CSSLayerBlockRule":
+                //   return toLayerBlockRule(rule);
+                // case "CSSLayerStatementRule":
+                //   return toLayerStatementRule(rule);
+                case CSSRule.MEDIA_RULE:
+                    return toMediaRule(rule);
+                case CSSRule.NAMESPACE_RULE:
+                    return toNamespaceRule(rule);
+                case CSSRule.PAGE_RULE:
+                    return toPageRule(rule);
+                case CSSRule.STYLE_RULE:
+                    return toStyleRule(rule);
+                case CSSRule.SUPPORTS_RULE:
+                    return toSupportsRule(rule);
+            }
+            // If nothing worked, just crash.
+            throw new Error(`Unsupported rule of type: ${rule.constructor.name} / ${Object.prototype.toString.apply(rule)} / ${rule.type}`);
+        }
+        function toFontFaceRule(rule) {
+            return {
+                type: "font-face",
+                style: toBlock(rule.style),
+            };
+        }
+        function toImportRule(rule) {
+            return {
+                type: "import",
+                rules: rule.styleSheet === null ? [] : toSheet(rule.styleSheet).rules,
+                condition: rule.media.mediaText === "" ? "all" : rule.media.mediaText,
+                href: rule.href,
+                supportText: rule.supportsText,
+                layer: rule.layerName,
+            };
+        }
+        function toKeyframeRule(rule) {
+            return {
+                type: "keyframe",
+                key: rule.keyText,
+                style: toBlock(rule.style),
+            };
+        }
+        function toKeyframesRule(rule) {
+            let rules;
+            try {
+                rules = map(rule.cssRules, toRule);
+            }
+            catch {
+                rules = [];
+            }
+            return {
+                type: "keyframes",
+                rules,
+                name: rule.name,
+            };
+        }
+        function toLayerBlockRule(rule) {
+            return {
+                type: "layer-block",
+                layer: rule.name,
+                rules: map(rule.cssRules, toRule),
+            };
+        }
+        function toLayerStatementRule(rule) {
+            return {
+                type: "layer-statement",
+                layers: [...rule.nameList],
+            };
+        }
+        function toMediaRule(rule) {
+            let rules;
+            try {
+                rules = map(rule.cssRules, toRule);
+            }
+            catch {
+                rules = [];
+            }
+            return {
+                type: "media",
+                condition: rule.conditionText,
+                rules,
+            };
+        }
+        function toNamespaceRule(rule) {
+            return {
+                type: "namespace",
+                namespace: rule.namespaceURI,
+                prefix: rule.prefix,
+            };
+        }
+        function toPageRule(rule) {
+            return {
+                type: "page",
+                selector: rule.selectorText,
+                style: toBlock(rule.style),
+            };
+        }
+        function toStyleRule(styleRule) {
+            return {
+                type: "style",
+                selector: styleRule.selectorText,
+                style: toBlock(styleRule.style),
+            };
+        }
+        function toSupportsRule(rule) {
+            let rules;
+            try {
+                rules = map(rule.cssRules, toRule);
+            }
+            catch {
+                rules = [];
+            }
+            return {
+                type: "supports",
+                condition: rule.conditionText,
+                rules,
+            };
+        }
+        /**
+         * @privateRemarks
+         * User Agents normally expose the pre-parsed declarations.
+         * However, there is a corner case of shorthands whose value is a `var()`
+         * where several UAs (as of April 2024: at least Chrome and Firefox) list
+         * the **longhands** in their CSSStyleDeclaration object (in the enumerable
+         * part), but associate no values to them, only to the corresponding
+         * shorthand (as expected and declared). This causes attempts to access
+         * the apparently declared properties through the `getPropertyValue()`
+         * method to return an empty string.
+         *
+         * {@link https://github.com/Siteimprove/alfa/issues/1563}
+         *
+         * To circumvent that, we simply return the raw CSS text; and delegate parsing
+         * to consumers, aka Block.from.
+         *
+         * Note that somehow JSDOM behaves differently and correctly associate the
+         * value with the shorthand. This means that the local tests using JSDOM
+         * are brittle and cannot detect a regression on this issue.
+         */
+        function toBlock(block) {
+            return block.cssText;
+        }
+        function toRectangle(domRect) {
+            return {
+                type: "rectangle",
+                x: domRect.x,
+                y: domRect.y,
+                width: domRect.width,
+                height: domRect.height,
+            };
+        }
+        function map(arrayLike, mapper) {
+            const result = new Array(arrayLike.length);
+            for (let i = 0, n = arrayLike.length; i < n; i++) {
+                result[i] = mapper(arrayLike[i]);
+            }
+            return result;
+        }
+        async function mapAsync(arrayLike, mapper) {
+            const result = new Array(arrayLike.length);
+            for (let i = 0, n = arrayLike.length; i < n; i++) {
+                result[i] = await mapper(arrayLike[i]);
+            }
+            return result;
+        }
+        /**
+         * Ensure that the needed resources for the document or shadow root, such as
+         * style sheets, adhere to CORS policy.
+         */
+        async function ensureCrossOrigin(documentOrShadowRoot) {
+            /**
+             * Ensure that all `<link>` elements specify the `crossorigin` attribute.
+             * Even `<link>` elements that reference same-origin resources will need
+             * this attribute as they may contain nested resource imports that risk
+             * violating CORS policy.
+             *
+             * Do keep in mind that this will only work for resources that also set
+             * appropriate CORS request headers.
+             */
+            const links = documentOrShadowRoot.querySelectorAll("link");
+            for (let i = 0; i < links.length; i++) {
+                const link = links[i];
+                /**
+                 * Skip `<link>` elements for which the `crossorigin` attribute is already
+                 * set to a valid value.
+                 */
+                if (link.crossOrigin !== null) {
+                    continue;
+                }
+                /**
+                 * Simply setting the `crossorigin` attribute for the `<link>` element
+                 * will not work as it must be reevaluated. We therefore create a clone,
+                 * set the `crossorigin` attribute, and replace the original `<link>`
+                 * element.
+                 */
+                const clone = link.cloneNode();
+                /**
+                 * Set the `crossorigin` attribute to `anonymous`, ensuring that
+                 * credentials are not sent as part of the cross-origin request. This is
+                 * incredibly important as we don't want to risk leaking credentials!
+                 */
+                clone.crossOrigin = "anonymous";
+                /**
+                 * Replace the original `<link>` element with its clone. For style sheets,
+                 * this will unfortunately cause a FOUC while the browser recomputes
+                 * styles.
+                 *
+                 * {@link https://en.wikipedia.org/wiki/Flash_of_unstyled_content}
+                 */
+                link.parentNode.replaceChild(clone, link);
+                /**
+                 * While certain resources will load synchronously from cache, others will
+                 * not and we therefore need to await these.
+                 */
+                if (shouldAwait(link)) {
+                    /**
+                     * Construct a promise that resolves once the `<link>` element either
+                     * loads successfully or fails to load. If the `<link>` element fails to
+                     * load, a request error will be logged to the console which should be
+                     * enough indication that something didn't go quite as expected. Either
+                     * way, we will deliver audit results even in the event of a missing
+                     * resource.
+                     */
+                    await new Promise((resolve) => ["load", "error"].forEach((event) => clone.addEventListener(event, () => resolve())));
+                }
+            }
+            /**
+             * Check if the given `<link>` element should be awaited.
+             */
+            function shouldAwait(link) {
+                /**
+                 * A `<link>` element with an empty `href` will cause the fetch process to
+                 * abort with no events to await.
+                 */
+                if (link.getAttribute("href")?.trim() === "") {
+                    return false;
+                }
+                /**
+                 * Style sheets should be awaited as these are loaded and applied
+                 * asynchronously, often times causing additional resources to be loaded
+                 * via `url()` references and `@import` rules.
+                 */
+                if (link.rel === "stylesheet") {
+                    return true;
+                }
+                return false;
+            }
+        }
+    }
+    Native.fromNode = fromNode;
+})(Native || (Native = {}));
+//# sourceMappingURL=native.js.map

package/dist/node/attribute/predicate/has-name.d.ts

@@ -0,0 +1,11 @@
+import type { Refinement } from "@siteimprove/alfa-refinement";
+import { Attribute } from "../../attribute.js";
+/**
+ * @public
+ */
+export declare function hasName<N extends string = string>(predicate: Refinement<string, N>): Refinement<Attribute, Attribute<N>>;
+/**
+ * @public
+ */
+export declare function hasName<N extends string = string>(name: N, ...rest: Array<N>): Refinement<Attribute, Attribute<N>>;
+//# sourceMappingURL=has-name.d.ts.map

package/dist/node/attribute/predicate/has-name.js

@@ -0,0 +1,13 @@
+import { Attribute } from "../../attribute.js";
+export function hasName(nameOrPredicate, ...names) {
+    let predicate;
+    if (typeof nameOrPredicate === "function") {
+        predicate = nameOrPredicate;
+    }
+    else {
+        names.unshift(nameOrPredicate);
+        predicate = (name, attribute) => names.some((candidate) => Attribute.foldCase(candidate, attribute.owner) === name);
+    }
+    return (attribute) => predicate(attribute.name, attribute);
+}
+//# sourceMappingURL=has-name.js.map

package/dist/node/attribute/predicate.d.ts

@@ -0,0 +1,2 @@
+export * from "./predicate/has-name.js";
+//# sourceMappingURL=predicate.d.ts.map