@siteimprove/alfa-dom 0.92.0 → 0.93.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @siteimprove/alfa-dom
 
+## 0.93.1
+
+## 0.93.0
+
+### Minor Changes
+
+- **Breaking:** `Element.hasDisplaySize()` now builds a `Predicate<Element<"select">>` instead of a `Predicate<Element>`. ([#1683](https://github.com/Siteimprove/alfa/pull/1683))
+
+  That is, it can only be applied to elements that have been typed as `<select>` elements, where it makes sense. If the type of element cannot be narrowed in TypeScript (e.g. because it is the result of a direct test on `Element#name`), a type assertion is needed; in general, using the `Element.hasName` refinement is recommended over testing `Element#name`.
+
+- **Added:** A method `Element<"select">#displaySize()` is now available. ([#1683](https://github.com/Siteimprove/alfa/pull/1683))
+
+- **Breaking:** The helper `Element.inputType(element)` has been replaced by a method `element.inputType()`. ([#1683](https://github.com/Siteimprove/alfa/pull/1683))
+
+  It can still only be called if `element` has been typed as `Element<"input">`, i.e. is an `<input>` HTML element.
+
+- **Added:** An `Element<"select">#optionsList()` helper is now available. ([#1683](https://github.com/Siteimprove/alfa/pull/1683))
+
 ## 0.92.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export * from "./node/attribute.js";
 export * from "./node/comment.js";
 export * from "./node/document.js";
 export * from "./node/element.js";
+import "./node/element/augment.js";
 export * from "./node/fragment.js";
 export * from "./node/shadow.js";
 export * from "./node/text.js";

package/dist/index.js

@@ -22,6 +22,7 @@ export * from "./node/attribute.js";
 export * from "./node/comment.js";
 export * from "./node/document.js";
 export * from "./node/element.js";
+import "./node/element/augment.js";
 export * from "./node/fragment.js";
 export * from "./node/shadow.js";
 export * from "./node/text.js";

package/dist/jsx-runtime.d.ts

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "./jsx.js";
 import type { Element } from "./index.js";
 export declare namespace JSX {
-    type Element = _jsx.JSX.Element;
+    type Element<N extends string = string> = _jsx.JSX.Element<N>;
     interface IntrinsicElements extends _jsx.JSX.IntrinsicElements {
     }
 }

package/dist/node/element/augment.d.ts

@@ -0,0 +1,26 @@
+import { Sequence } from "@siteimprove/alfa-sequence";
+import type { InputType } from "./input-type.js";
+declare module "../element.js" {
+    interface Element<N extends string> {
+        /**
+         * {@link https://html.spec.whatwg.org/#attr-input-type}
+         */
+        inputType(this: Element<"input">): InputType;
+        /**
+         * {@link https://html.spec.whatwg.org/multipage/form-elements.html#concept-select-size}
+         *
+         * @remarks
+         * The size IDL attribute should have a value of 0, not 1 or 4, when the
+         * size content attribute is undefined. This is for historical reasons. In
+         * our case, this is not affecting the results, and it is easier to treat it
+         * as the actual displayed size.
+         * {@link https://html.spec.whatwg.org/multipage/form-elements.html#dom-select-size}
+         */
+        displaySize(this: Element<"select">): number;
+        /**
+         * {@link https://html.spec.whatwg.org/multipage/form-elements.html#concept-select-option-list}
+         */
+        optionsList(this: Element<"select">): Sequence<Element<"option">>;
+    }
+}
+//# sourceMappingURL=augment.d.ts.map

package/dist/node/element/augment.js

@@ -0,0 +1,56 @@
+/*
+ * Augment the Element class with some methods that are specific to a given
+ * element. These are grouped here to de-clutter the main class declaration
+ * which thus only contains generic methods.
+ *
+ * {@link https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation
+ */
+import { None, Some } from "@siteimprove/alfa-option";
+import { Sequence } from "@siteimprove/alfa-sequence";
+import { Element } from "../element.js";
+Element.prototype.inputType = function () {
+    if (this._inputType === undefined) {
+        this._inputType = this.attribute("type")
+            .flatMap((attribute) => attribute.enumerate("hidden", "search", "tel", "url", "email", "password", "date", "month", "week", "time", "datetime-local", "number", "range", "color", "checkbox", "radio", "file", "submit", "image", "reset", "button", "text"))
+            .getOr("text");
+    }
+    return this._inputType;
+};
+Element.prototype.displaySize = function () {
+    if (this._displaySize === undefined) {
+        this._displaySize = this.attribute("size")
+            .flatMap((attribute) => {
+            const size = parseInt(attribute.value, 10);
+            if (size === size && size === (size | 0)) {
+                return Some.of(size);
+            }
+            return None;
+        })
+            .getOrElse(() => (this.attribute("multiple").isSome() ? 4 : 1));
+    }
+    return this._displaySize;
+};
+Element.prototype.optionsList = function () {
+    if (this._optionsList === undefined) {
+        this._optionsList = this.children()
+            .filter(Element.isElement)
+            .flatMap((child) => {
+            switch (child.name) {
+                case "option":
+                    return Sequence.from([child]);
+                case "optgroup":
+                    return child
+                        .children()
+                        .filter(Element.isElement)
+                        .filter(
+                    // We cannot really use `Element.hasName` here as it would
+                    // create a circular dependency.
+                    (grandchild) => grandchild.name === "option");
+                default:
+                    return Sequence.empty();
+            }
+        });
+    }
+    return this._optionsList;
+};
+//# sourceMappingURL=augment.js.map

package/dist/node/element/input-type.d.ts

@@ -1,12 +1,7 @@
-import type { Element } from "../element.js";
 /**
  * {@link https://html.spec.whatwg.org/#attr-input-type}
  *
  * @internal
  */
 export type InputType = "hidden" | "search" | "tel" | "url" | "email" | "password" | "date" | "month" | "week" | "time" | "datetime-local" | "number" | "range" | "color" | "checkbox" | "radio" | "file" | "submit" | "image" | "reset" | "button" | "text";
-/**
- * @public
- */
-export declare function inputType(element: Element<"input">): InputType;
 //# sourceMappingURL=input-type.d.ts.map

package/dist/node/element/input-type.js

@@ -1,10 +1,2 @@
-/**
- * @public
- */
-export function inputType(element) {
-    return element
-        .attribute("type")
-        .flatMap((attribute) => attribute.enumerate("hidden", "search", "tel", "url", "email", "password", "date", "month", "week", "time", "datetime-local", "number", "range", "color", "checkbox", "radio", "file", "submit", "image", "reset", "button", "text"))
-        .getOr("text");
-}
+export {};
 //# sourceMappingURL=input-type.js.map

package/dist/node/element/predicate/has-display-size.d.ts

@@ -3,5 +3,5 @@ import type { Element } from "../../element.js";
 /**
  * @public
  */
-export declare function hasDisplaySize(valueOrPredicate: number | Predicate<number>): Predicate<Element>;
+export declare function hasDisplaySize(valueOrPredicate: number | Predicate<number>): Predicate<Element<"select">>;
 //# sourceMappingURL=has-display-size.d.ts.map

package/dist/node/element/predicate/has-display-size.js

@@ -1,4 +1,3 @@
-import { None, Option } from "@siteimprove/alfa-option";
 /**
  * @public
  */
@@ -7,22 +6,7 @@ export function hasDisplaySize(valueOrPredicate) {
         ? valueOrPredicate
         : (size) => valueOrPredicate === size;
     return (element) => {
-        const displaySize = element
-            .attribute("size")
-            .flatMap((size) => {
-            const sizeValue = parseInt(size.value, 10);
-            if (sizeValue === sizeValue && sizeValue === (sizeValue | 0)) {
-                return Option.of(sizeValue);
-            }
-            else {
-                return None;
-            }
-        })
-            .getOrElse(() => element
-            .attribute("multiple")
-            .map(() => 4)
-            .getOr(1));
-        return predicate(displaySize);
+        return predicate(element.displaySize());
     };
 }
 //# sourceMappingURL=has-display-size.js.map

package/dist/node/element/predicate/has-input-type.js

@@ -1,6 +1,6 @@
 import { Predicate } from "@siteimprove/alfa-predicate";
 import { Refinement } from "@siteimprove/alfa-refinement";
-import { inputType } from "../input-type.js";
+import {} from "../input-type.js";
 import { hasName } from "./has-name.js";
 const { equals, test } = Predicate;
 const { and } = Refinement;
@@ -12,6 +12,6 @@ export function hasInputType(inputTypeOrPredicate, ...inputTypes) {
     else {
         predicate = equals(inputTypeOrPredicate, ...inputTypes);
     }
-    return and(hasName("input"), (element) => test(predicate, inputType(element)));
+    return and(hasName("input"), (element) => test(predicate, element.inputType()));
 }
 //# sourceMappingURL=has-input-type.js.map

package/dist/node/element.d.ts

@@ -14,7 +14,7 @@ import { Document } from "./document.js";
 import { Shadow } from "./shadow.js";
 import { Slot } from "./slot.js";
 import { Slotable } from "./slotable.js";
-import * as helpers from "./element/input-type.js";
+import type * as helpers from "./element/input-type.js";
 import * as predicate from "./element/predicate.js";
 /**
  * @public
@@ -60,6 +60,9 @@ export declare class Element<N extends string = string> extends Node<"element">
      * {@link https://html.spec.whatwg.org/#dom-tabindex}
      */
     tabIndex(): Option<number>;
+    protected _inputType: helpers.InputType | undefined;
+    protected _displaySize: number | undefined;
+    protected _optionsList: Sequence<Element<"option">> | undefined;
     /**
      * {@link https://dom.spec.whatwg.org/#dom-slotable-assignedslot}
      */
@@ -117,6 +120,6 @@ export declare namespace Element {
      */
     function cloneElement(options: Node.ElementReplacementOptions, device?: Device): (element: Element) => Trampoline<Element>;
     const hasAttribute: typeof predicate.hasAttribute, hasBox: typeof predicate.hasBox, hasDisplaySize: typeof predicate.hasDisplaySize, hasId: typeof predicate.hasId, hasInputType: typeof predicate.hasInputType, hasName: typeof predicate.hasName, hasNamespace: typeof predicate.hasNamespace, hasTabIndex: typeof predicate.hasTabIndex, hasUniqueId: Predicate<Element<string>>, isBrowsingContextContainer: typeof predicate.isBrowsingContextContainer, isContent: typeof predicate.isContent, isActuallyDisabled: typeof predicate.isActuallyDisabled, isDocumentElement: typeof predicate.isDocumentElement, isDraggable: typeof predicate.isDraggable, isEditingHost: typeof predicate.isEditingHost, isFallback: typeof predicate.isFallback, isScopedTo: typeof predicate.isScopedTo, isSuggestedFocusable: typeof predicate.isSuggestedFocusable, isReplaced: typeof predicate.isReplaced;
-    const inputType: typeof helpers.inputType;
+    type InputType = helpers.InputType;
 }
 //# sourceMappingURL=element.d.ts.map

package/dist/node/element.js

@@ -15,7 +15,6 @@ import { Document } from "./document.js";
 import { Shadow } from "./shadow.js";
 import { Slot } from "./slot.js";
 import { Slotable } from "./slotable.js";
-import * as helpers from "./element/input-type.js";
 import * as predicate from "./element/predicate.js";
 const { isEmpty } = Iterable;
 const { not } = Predicate;
@@ -172,6 +171,19 @@ export class Element extends Node {
         }
         return None;
     }
+    /*
+     * 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
+     * class. However, we need to declare the variables here as they would
+     * otherwise be public which exposes too much. And they must be `protected`
+     * to be accessible by the augments.
+     */
+    _inputType;
+    _displaySize;
+    _optionsList;
+    /*
+     * End of caches for methods specific to some kind of elements.
+     */
     /**
      * {@link https://dom.spec.whatwg.org/#dom-slotable-assignedslot}
      */
@@ -325,6 +337,5 @@ export class Element extends Node {
     }
     Element.cloneElement = cloneElement;
     Element.hasAttribute = predicate.hasAttribute, Element.hasBox = predicate.hasBox, Element.hasDisplaySize = predicate.hasDisplaySize, Element.hasId = predicate.hasId, Element.hasInputType = predicate.hasInputType, Element.hasName = predicate.hasName, Element.hasNamespace = predicate.hasNamespace, Element.hasTabIndex = predicate.hasTabIndex, Element.hasUniqueId = predicate.hasUniqueId, Element.isBrowsingContextContainer = predicate.isBrowsingContextContainer, Element.isContent = predicate.isContent, Element.isActuallyDisabled = predicate.isActuallyDisabled, Element.isDocumentElement = predicate.isDocumentElement, Element.isDraggable = predicate.isDraggable, Element.isEditingHost = predicate.isEditingHost, Element.isFallback = predicate.isFallback, Element.isScopedTo = predicate.isScopedTo, Element.isSuggestedFocusable = predicate.isSuggestedFocusable, Element.isReplaced = predicate.isReplaced;
-    Element.inputType = helpers.inputType;
 })(Element || (Element = {}));
 //# sourceMappingURL=element.js.map

package/dist/node/query/inclusive-element-descendants.d.ts

@@ -1,6 +1,6 @@
 import type { Sequence } from "@siteimprove/alfa-sequence";
 import { Node } from "../../node.js";
-import { Element } from "../element.js";
+import type { Element } from "../element.js";
 /**
  * @public
  */

package/dist/node/query/inclusive-element-descendants.js

@@ -1,5 +1,4 @@
 import { Node } from "../../node.js";
-import { Element } from "../element.js";
 import { getElementDescendants } from "./element-descendants.js";
 /**
  * @public

package/package.json

@@ -2,7 +2,7 @@
   "$schema": "http://json.schemastore.org/package",
   "name": "@siteimprove/alfa-dom",
   "homepage": "https://alfa.siteimprove.com",
-  "version": "0.92.0",
+  "version": "0.93.1",
   "license": "MIT",
   "description": "Implementations of the core DOM and CSSOM node types",
   "repository": {
@@ -33,32 +33,32 @@
     "dist/**/*.d.ts"
   ],
   "dependencies": {
-    "@siteimprove/alfa-array": "^0.92.0",
-    "@siteimprove/alfa-cache": "^0.92.0",
-    "@siteimprove/alfa-comparable": "^0.92.0",
-    "@siteimprove/alfa-css": "^0.92.0",
-    "@siteimprove/alfa-css-feature": "^0.92.0",
-    "@siteimprove/alfa-device": "^0.92.0",
-    "@siteimprove/alfa-earl": "^0.92.0",
-    "@siteimprove/alfa-equatable": "^0.92.0",
-    "@siteimprove/alfa-flags": "^0.92.0",
-    "@siteimprove/alfa-iterable": "^0.92.0",
-    "@siteimprove/alfa-json": "^0.92.0",
-    "@siteimprove/alfa-lazy": "^0.92.0",
-    "@siteimprove/alfa-map": "^0.92.0",
-    "@siteimprove/alfa-option": "^0.92.0",
-    "@siteimprove/alfa-predicate": "^0.92.0",
-    "@siteimprove/alfa-rectangle": "^0.92.0",
-    "@siteimprove/alfa-refinement": "^0.92.0",
-    "@siteimprove/alfa-sarif": "^0.92.0",
-    "@siteimprove/alfa-selective": "^0.92.0",
-    "@siteimprove/alfa-sequence": "^0.92.0",
-    "@siteimprove/alfa-string": "^0.92.0",
-    "@siteimprove/alfa-trampoline": "^0.92.0",
-    "@siteimprove/alfa-tree": "^0.92.0"
+    "@siteimprove/alfa-array": "^0.93.1",
+    "@siteimprove/alfa-cache": "^0.93.1",
+    "@siteimprove/alfa-comparable": "^0.93.1",
+    "@siteimprove/alfa-css": "^0.93.1",
+    "@siteimprove/alfa-css-feature": "^0.93.1",
+    "@siteimprove/alfa-device": "^0.93.1",
+    "@siteimprove/alfa-earl": "^0.93.1",
+    "@siteimprove/alfa-equatable": "^0.93.1",
+    "@siteimprove/alfa-flags": "^0.93.1",
+    "@siteimprove/alfa-iterable": "^0.93.1",
+    "@siteimprove/alfa-json": "^0.93.1",
+    "@siteimprove/alfa-lazy": "^0.93.1",
+    "@siteimprove/alfa-map": "^0.93.1",
+    "@siteimprove/alfa-option": "^0.93.1",
+    "@siteimprove/alfa-predicate": "^0.93.1",
+    "@siteimprove/alfa-rectangle": "^0.93.1",
+    "@siteimprove/alfa-refinement": "^0.93.1",
+    "@siteimprove/alfa-sarif": "^0.93.1",
+    "@siteimprove/alfa-selective": "^0.93.1",
+    "@siteimprove/alfa-sequence": "^0.93.1",
+    "@siteimprove/alfa-string": "^0.93.1",
+    "@siteimprove/alfa-trampoline": "^0.93.1",
+    "@siteimprove/alfa-tree": "^0.93.1"
   },
   "devDependencies": {
-    "@siteimprove/alfa-test": "^0.92.0",
+    "@siteimprove/alfa-test": "^0.93.1",
     "@types/jsdom": "^21.1.6",
     "jsdom": "^25.0.0"
   },