@siteimprove/alfa-dom 0.108.2 → 0.110.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @siteimprove/alfa-dom
 
+## 0.110.0
+
+### Patch Changes
+
+- **Added:** The `inert` attribute is now supported. ([#1964](https://github.com/Siteimprove/alfa/pull/1964))
+
+## 0.109.0
+
+### Patch Changes
+
+- **Added:** A new function `getTextDescendants` has been added to the `Query` namespace. It retrieves all text descendants of a node, with an option to group text under matching sub-trees into labeled `TextGroup` objects. ([#1972](https://github.com/Siteimprove/alfa/pull/1972))
+
+- **Changed:** The `index()` method on nodes now accepts an optional predicate parameter to filter siblings when calculating the node's index position. ([#1980](https://github.com/Siteimprove/alfa/pull/1980))
+
 ## 0.108.2
 
 ## 0.108.1

package/dist/node/comment.js

@@ -28,7 +28,7 @@ export class Comment extends Node {
             .getOr("/");
         path += path === "/" ? "" : "/";
         path += "comment()";
-        const index = this.preceding(options).count(Comment.isComment);
+        const index = this.index(options, Comment.isComment);
         path += `[${index + 1}]`;
         return path;
     }

package/dist/node/element/predicate/is-suggested-focusable.js

@@ -11,6 +11,9 @@ import { Element } from "../../element.js";
  * @public
  */
 export function isSuggestedFocusable(element) {
+    if (element.isInert()) {
+        return false;
+    }
     switch (element.name) {
         case "a":
         case "link":

package/dist/node/element.d.ts

@@ -60,9 +60,20 @@ export declare class Element<N extends string = string> extends Node<"element">
      * {@link https://html.spec.whatwg.org/#dom-tabindex}
      */
     tabIndex(): Option<number>;
+    /**
+     * Computes inertness of an element based on the `inert` attribute.
+     *
+     * {@link https://html.spec.whatwg.org/#the-inert-attribute}
+     *
+     * @privateRemarks
+     * According to {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inert}
+     * only open dialogs can escape inertness (except when they have the `inert` attribute).
+     */
+    isInert(): boolean;
     protected _inputType: helpers.InputType | undefined;
     protected _displaySize: number | undefined;
     protected _optionsList: Sequence<Element<"option">> | undefined;
+    private _isInert;
     /**
      * {@link https://dom.spec.whatwg.org/#dom-slotable-assignedslot}
      */

package/dist/node/element.js

@@ -17,7 +17,7 @@ import { Slot } from "./slot.js";
 import { Slotable } from "./slotable.js";
 import * as predicate from "./element/predicate.js";
 const { isEmpty } = Iterable;
-const { not } = Predicate;
+const { and, not, or, test } = Predicate;
 /**
  * @public
  */
@@ -171,6 +171,30 @@ export class Element extends Node {
         }
         return None;
     }
+    /**
+     * Computes inertness of an element based on the `inert` attribute.
+     *
+     * {@link https://html.spec.whatwg.org/#the-inert-attribute}
+     *
+     * @privateRemarks
+     * According to {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inert}
+     * only open dialogs can escape inertness (except when they have the `inert` attribute).
+     */
+    isInert() {
+        if (this._isInert === undefined) {
+            this._isInert = test(or(
+            // Explicitly inert;
+            Element.hasAttribute("inert"), and(
+            // or not an open dialog,
+            not(and(Element.hasName("dialog"), Element.hasAttribute("open"))), 
+            // and with an inert ancestor.
+            (element) => element
+                .parent(Node.flatTree)
+                .filter(Element.isElement)
+                .some((parent) => parent.isInert()))), this);
+        }
+        return this._isInert;
+    }
     /*
      * This collects caches for methods that are specific to some kind of elements.
      * The actual methods are declared in element/augment.ts to de-clutter this
@@ -181,6 +205,7 @@ export class Element extends Node {
     _inputType;
     _displaySize;
     _optionsList;
+    _isInert;
     /*
      * End of caches for methods specific to some kind of elements.
      */
@@ -205,9 +230,7 @@ export class Element extends Node {
             .getOr("/");
         path += path === "/" ? "" : "/";
         path += this._name;
-        const index = this.preceding(options)
-            .filter(Element.isElement)
-            .count((element) => element._name === this._name);
+        const index = this.index(options, (node) => Element.isElement(node) && node._name === this._name);
         path += `[${index + 1}]`;
         return path;
     }

package/dist/node/query/descendants.d.ts

@@ -1,8 +1,9 @@
 import type { Predicate } from "@siteimprove/alfa-predicate";
 import type { Refinement } from "@siteimprove/alfa-refinement";
-import type { Sequence } from "@siteimprove/alfa-sequence";
+import { Sequence } from "@siteimprove/alfa-sequence";
 import { Node } from "../../node.js";
 import { Element } from "../element.js";
+import { Text } from "../text.js";
 /**
  * Get all descendants of a node that satisfy a given refinement.
  *
@@ -31,4 +32,36 @@ export declare const getElementDescendants: (node: Node, options?: Node.Traversa
  * @public
  */
 export declare function getInclusiveElementDescendants(node: Element, options?: Node.Traversal): Sequence<Element>;
+/**
+ * A group of text nodes with an associated label.
+ *
+ * @public
+ */
+export interface TextGroup {
+    label: string;
+    text: Sequence<Text>;
+}
+/**
+ * Options for grouping text descendants.
+ *
+ * @public
+ */
+export interface TextGroupOptions<N extends Node = Node> {
+    startsGroup: Refinement<Node, N>;
+    getLabel: (node: N) => string;
+}
+/**
+ * Get all text descendants of a node, optionally grouping some into labeled groups.
+ *
+ * @remarks
+ * When a descendant matches `startsGroup`, all of its text descendants are collected
+ * into a {@link TextGroup} with a label from `getLabel`. Text nodes outside such
+ * sub-trees are returned as plain {@link Text} nodes.
+ *
+ * Groups are not nested: if a `startsGroup` node contains another `startsGroup` node,
+ * the inner node's text is included in the outer group, not as a separate group.
+ *
+ * @public
+ */
+export declare function getTextDescendants<N extends Node = Node>(textOptions?: TextGroupOptions<N>): (node: Node, options?: Node.Traversal) => Sequence<Text | TextGroup>;
 //# sourceMappingURL=descendants.d.ts.map

package/dist/node/query/descendants.js

@@ -1,6 +1,8 @@
 import { Cache } from "@siteimprove/alfa-cache";
+import { Sequence } from "@siteimprove/alfa-sequence";
 import { Node } from "../../node.js";
 import { Element } from "../element.js";
+import { Text } from "../text.js";
 const _descendantsCache = Cache.empty();
 export function getDescendants(predicate) {
     return (node, options = Node.Traversal.empty) => {
@@ -23,4 +25,51 @@ export const getElementDescendants = getDescendants(Element.isElement);
 export function getInclusiveElementDescendants(node, options = Node.Traversal.empty) {
     return getElementDescendants(node, options).prepend(node);
 }
+const _textCache = Cache.empty();
+const defaultTextOptions = {
+    startsGroup: (node) => false,
+    getLabel: () => "",
+};
+/**
+ * Get all text descendants of a node, optionally grouping some into labeled groups.
+ *
+ * @remarks
+ * When a descendant matches `startsGroup`, all of its text descendants are collected
+ * into a {@link TextGroup} with a label from `getLabel`. Text nodes outside such
+ * sub-trees are returned as plain {@link Text} nodes.
+ *
+ * Groups are not nested: if a `startsGroup` node contains another `startsGroup` node,
+ * the inner node's text is included in the outer group, not as a separate group.
+ *
+ * @public
+ */
+export function getTextDescendants(textOptions = defaultTextOptions) {
+    return (node, options = Node.Traversal.empty) => {
+        const optionsMap = _textCache
+            .get(textOptions, Cache.empty)
+            .get(node, () => []);
+        if (optionsMap[options.value] === undefined) {
+            optionsMap[options.value] = Sequence.from(_getTextDescendants(node, textOptions, options));
+        }
+        return optionsMap[options.value];
+    };
+}
+function* _getTextDescendants(node, textOptions, traversalOptions) {
+    const { startsGroup, getLabel } = textOptions;
+    for (const child of node.children(traversalOptions)) {
+        if (startsGroup(child)) {
+            const groupText = getDescendants(Text.isText)(child, traversalOptions);
+            yield {
+                label: getLabel(child),
+                text: groupText,
+            };
+        }
+        else if (Text.isText(child)) {
+            yield child;
+        }
+        else {
+            yield* _getTextDescendants(child, textOptions, traversalOptions);
+        }
+    }
+}
 //# sourceMappingURL=descendants.js.map

package/dist/node/query/index.d.ts

@@ -1,12 +1,16 @@
 import * as descendants from "./descendants.js";
 import * as elementIdMap from "./element-id-map.js";
+import type { Node } from "../../node.js";
 /**
  * @public
  */
 export declare namespace Query {
     const getDescendants: typeof descendants.getDescendants;
-    const getElementDescendants: (node: import("../../node.js").Node, options?: import("../../node.js").Node.Traversal) => import("@siteimprove/alfa-sequence").Sequence<import("../element.js").Element<string>>;
-    const getElementIdMap: typeof elementIdMap.getElementIdMap;
+    const getElementDescendants: (node: Node, options?: Node.Traversal) => import("@siteimprove/alfa-sequence").Sequence<import("../element.js").Element<string>>;
     const getInclusiveElementDescendants: typeof descendants.getInclusiveElementDescendants;
+    const getTextDescendants: typeof descendants.getTextDescendants;
+    const getElementIdMap: typeof elementIdMap.getElementIdMap;
+    type TextGroup = descendants.TextGroup;
+    type TextGroupOptions<N extends Node = Node> = descendants.TextGroupOptions<N>;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/node/query/index.js

@@ -7,7 +7,8 @@ export var Query;
 (function (Query) {
     Query.getDescendants = descendants.getDescendants;
     Query.getElementDescendants = descendants.getElementDescendants;
-    Query.getElementIdMap = elementIdMap.getElementIdMap;
     Query.getInclusiveElementDescendants = descendants.getInclusiveElementDescendants;
+    Query.getTextDescendants = descendants.getTextDescendants;
+    Query.getElementIdMap = elementIdMap.getElementIdMap;
 })(Query || (Query = {}));
 //# sourceMappingURL=index.js.map

package/dist/node/text.js

@@ -44,7 +44,7 @@ export class Text extends Node {
             .getOr("/");
         path += path === "/" ? "" : "/";
         path += "text()";
-        const index = this.preceding(options).count(Text.isText);
+        const index = this.index(options, Text.isText);
         path += `[${index + 1}]`;
         return path;
     }

package/dist/node.d.ts

@@ -73,7 +73,7 @@ export interface Node {
     last(options?: Node.Traversal): Option<Node>;
     previous(options?: Node.Traversal): Option<Node>;
     next(options?: Node.Traversal): Option<Node>;
-    index(options?: Node.Traversal): number;
+    index(options?: Node.Traversal, predicate?: Predicate<Node>): number;
     closest<T extends Node>(refinement: Refinement<Node, T>, options?: Node.Traversal): Option<T>;
     closest(predicate: Predicate<Node>, options?: Node.Traversal): Option<Node>;
 }

package/dist/node.js

@@ -183,13 +183,10 @@ export class Node extends tree.Node {
     // 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 {
+        if (this._path[options.value] == undefined) {
             this._path[options.value] = this._internalPath(options);
-            return this._internalPath(options);
         }
+        return this._path[options.value];
     }
     equals(value) {
         return value === this;

package/package.json

@@ -2,7 +2,7 @@
   "$schema": "http://json.schemastore.org/package",
   "name": "@siteimprove/alfa-dom",
   "homepage": "https://alfa.siteimprove.com",
-  "version": "0.108.2",
+  "version": "0.110.0",
   "license": "MIT",
   "description": "Implementations of the core DOM and CSSOM node types",
   "repository": {
@@ -35,37 +35,37 @@
     "dist/**/*.d.ts"
   ],
   "dependencies": {
-    "@siteimprove/alfa-array": "^0.108.2",
-    "@siteimprove/alfa-cache": "^0.108.2",
-    "@siteimprove/alfa-comparable": "^0.108.2",
-    "@siteimprove/alfa-css": "^0.108.2",
-    "@siteimprove/alfa-css-feature": "^0.108.2",
-    "@siteimprove/alfa-device": "^0.108.2",
-    "@siteimprove/alfa-earl": "^0.108.2",
-    "@siteimprove/alfa-equatable": "^0.108.2",
-    "@siteimprove/alfa-flags": "^0.108.2",
-    "@siteimprove/alfa-iterable": "^0.108.2",
-    "@siteimprove/alfa-json": "^0.108.2",
-    "@siteimprove/alfa-lazy": "^0.108.2",
-    "@siteimprove/alfa-map": "^0.108.2",
-    "@siteimprove/alfa-option": "^0.108.2",
-    "@siteimprove/alfa-parser": "^0.108.2",
-    "@siteimprove/alfa-predicate": "^0.108.2",
-    "@siteimprove/alfa-rectangle": "^0.108.2",
-    "@siteimprove/alfa-refinement": "^0.108.2",
-    "@siteimprove/alfa-result": "^0.108.2",
-    "@siteimprove/alfa-sarif": "^0.108.2",
-    "@siteimprove/alfa-selective": "^0.108.2",
-    "@siteimprove/alfa-sequence": "^0.108.2",
-    "@siteimprove/alfa-slice": "^0.108.2",
-    "@siteimprove/alfa-string": "^0.108.2",
-    "@siteimprove/alfa-trampoline": "^0.108.2",
-    "@siteimprove/alfa-tree": "^0.108.2"
+    "@siteimprove/alfa-array": "^0.110.0",
+    "@siteimprove/alfa-cache": "^0.110.0",
+    "@siteimprove/alfa-comparable": "^0.110.0",
+    "@siteimprove/alfa-css": "^0.110.0",
+    "@siteimprove/alfa-css-feature": "^0.110.0",
+    "@siteimprove/alfa-device": "^0.110.0",
+    "@siteimprove/alfa-earl": "^0.110.0",
+    "@siteimprove/alfa-equatable": "^0.110.0",
+    "@siteimprove/alfa-flags": "^0.110.0",
+    "@siteimprove/alfa-iterable": "^0.110.0",
+    "@siteimprove/alfa-json": "^0.110.0",
+    "@siteimprove/alfa-lazy": "^0.110.0",
+    "@siteimprove/alfa-map": "^0.110.0",
+    "@siteimprove/alfa-option": "^0.110.0",
+    "@siteimprove/alfa-parser": "^0.110.0",
+    "@siteimprove/alfa-predicate": "^0.110.0",
+    "@siteimprove/alfa-rectangle": "^0.110.0",
+    "@siteimprove/alfa-refinement": "^0.110.0",
+    "@siteimprove/alfa-result": "^0.110.0",
+    "@siteimprove/alfa-sarif": "^0.110.0",
+    "@siteimprove/alfa-selective": "^0.110.0",
+    "@siteimprove/alfa-sequence": "^0.110.0",
+    "@siteimprove/alfa-slice": "^0.110.0",
+    "@siteimprove/alfa-string": "^0.110.0",
+    "@siteimprove/alfa-trampoline": "^0.110.0",
+    "@siteimprove/alfa-tree": "^0.110.0"
   },
   "devDependencies": {
-    "@siteimprove/alfa-test": "^0.108.2",
+    "@siteimprove/alfa-test": "^0.110.0",
     "@types/jsdom": "^27.0.0",
-    "jsdom": "^27.2.0"
+    "jsdom": "^27.4.0"
   },
   "publishConfig": {
     "access": "public",