[REF] web: Hoot - rename 'exact' to 'count'

This commit renames the 'exact' option given to queryX helpers to
'count', as to better reflect what it specifies, i.e. returning nodes
if their count matches the given one.

This commit also adds the ":count()" pseudo-class to be used in
selectors, for consistency with other options which are also pseudo-
classes.

closes odoo#231355

X-original-commit: 8fcdcf0
Related: odoo/enterprise#97073
Signed-off-by: Michaël Mattiello (mcm) <mcm@odoo.com>
Signed-off-by: Julien Mougenot (jum) <jum@odoo.com>

Author: jum-odoo

addons/web/static/lib/hoot-dom/helpers/dom.js

@@ -59,10 +59,10 @@ import { waitUntil } from "./time";
  *
  * @typedef {{
  *  contains?: string;
+ *  count?: number;
  *  displayed?: boolean;
  *  empty?: boolean;
  *  eq?: number;
- *  exact?: number;
  *  first?: boolean;
  *  focusable?: boolean;
  *  has?: boolean;
@@ -374,6 +374,17 @@ function getWaitForNoneMessage() {
     return message;
 }
 
+/**
+ *
+ * @param {number} count
+ * @param {Parameters<NodeFilter>[0]} _node
+ * @param {Parameters<NodeFilter>[1]} _i
+ * @param {Parameters<NodeFilter>[2]} nodes
+ */
+function hasNodeCount(count, _node, _i, nodes) {
+    return count === nodes.length;
+}
+
 /**
  * @param {string} [char]
  */
@@ -906,7 +917,10 @@ function _guardedQueryAll(target, options) {
 function _queryAll(target, options) {
     queryAllLevel++;
 
-    const { exact, root, ...modifiers } = options || {};
+    const { count, root, ...modifiers } = options || {};
+    if (count !== null && count !== undefined && (!$isInteger(count) || count <= 0)) {
+        throw new HootDomError(`invalid 'count' option: should be a positive integer`);
+    }
 
     /** @type {Node[]} */
     let nodes = [];
@@ -954,7 +968,7 @@ function _queryAll(target, options) {
     const filteredNodes = applyFilters(modifierFilters, nodes);
 
     // Register query message (if needed), and/or throw an error accordingly
-    const message = registerQueryMessage(filteredNodes, exact);
+    const message = registerQueryMessage(filteredNodes, count);
     if (message) {
         throw new HootDomError(message);
     }
@@ -969,7 +983,7 @@ function _queryAll(target, options) {
  * @param {QueryOptions} options
  */
 function _queryOne(target, options) {
-    return _guardedQueryAll(target, { ...options, exact: 1 })[0];
+    return _guardedQueryAll(target, { ...options, count: 1 })[0];
 }
 
 /**
@@ -1082,6 +1096,16 @@ const customPseudoClasses = new Map();
 
 customPseudoClasses
     .set("contains", makePatternBasedPseudoClass("contains", getNodeText))
+    .set("count", (strCount) => {
+        const count = $parseInt(strCount);
+        if (!$isInteger(count) || count <= 0) {
+            throw selectorError(
+                "count",
+                `expected count to be a positive integer (got ${strCount})`
+            );
+        }
+        return hasNodeCount.bind(null, count);
+    })
     .set("displayed", () => isNodeDisplayed)
     .set("empty", () => isEmpty)
     .set("eq", (strIndex) => {
@@ -1865,6 +1889,8 @@ export function observe(target, callback) {
  *      * given *text* will be matched against:
  *          - an `<input>`, `<textarea>` or `<select>` element's **value**;
  *          - or any other element's **inner text**.
+ * - `:count`: return nodes if their count match the given *count*.
+ *      If not matching, an error is thrown;
  * - `:displayed`: matches nodes that are "displayed" (see {@link isDisplayed});
  * - `:empty`: matches nodes that have an empty *content* (**value** or **inner text**);
  * - `:eq(n)`: matches the *nth* node (0-based index);
@@ -1885,17 +1911,17 @@ export function observe(target, callback) {
  * - `:visible`: matches nodes that are "visible" (see {@link isVisible});
  *
  * An `options` object can be specified to filter[1] the results:
- * - `displayed`: whether the nodes must be "displayed" (see {@link isDisplayed});
- * - `exact`: the exact number of nodes to match (throws an error if the number of
+ * - `count`: the exact number of nodes to match (throws an error if the number of
  *  nodes doesn't match);
+ * - `displayed`: whether the nodes must be "displayed" (see {@link isDisplayed});
  * - `focusable`: whether the nodes must be "focusable" (see {@link isFocusable});
  * - `root`: the root node to query the selector in (defaults to the current fixture);
  * - `viewPort`: whether the nodes must be partially visible in the current viewport
  *  (see {@link isInViewPort});
  * - `visible`: whether the nodes must be "visible" (see {@link isVisible}).
  *      * This option implies `displayed`
  *
- * [1] these filters (except for `exact` and `root`) achieve the same result as
+ * [1] these filters (except for `count` and `root`) achieve the same result as
  *  using their homonym pseudo-classes on the final group of the given selector
  *  string (e.g. ```queryAll`ul > li:visible`;``` = ```queryAll("ul > li", { visible: true })```).
  *
@@ -1917,7 +1943,7 @@ export function observe(target, callback) {
  *  queryAll`#editor:shadow div`; // -> [div, div, ...] (inside shadow DOM)
  * @example
  *  // with options
- *  queryAll(`div:first`, { exact: 1 }); // -> [div]
+ *  queryAll(`div:first`, { count: 1 }); // -> [div]
  *  queryAll(`div`, { root: queryOne`iframe` }); // -> [div, div, ...]
  *  // redundant, but possible
  *  queryAll(`button:visible`, { visible: true }); // -> [button, button, ...]
@@ -2039,20 +2065,20 @@ export function queryFirst(target, options) {
 }
 
 /**
- * Performs a {@link queryAll} with the given arguments, along with a forced `exact: 1`
+ * Performs a {@link queryAll} with the given arguments, along with a forced `count: 1`
  * option to ensure only one node matches the given {@link Target}.
  *
  * The returned value is a single node instead of a list of nodes.
  *
  * @param {Target} target
- * @param {Omit<QueryOptions, "exact">} [options]
+ * @param {Omit<QueryOptions, "count">} [options]
  * @returns {Element}
  */
 export function queryOne(target, options) {
     [target, options] = parseRawArgs(arguments);
-    if ($isInteger(options?.exact)) {
+    if ($isInteger(options?.count)) {
         throw new HootDomError(
-            `cannot call \`queryOne\` with 'exact'=${options.exact}: did you mean to use \`queryAll\`?`
+            `cannot call \`queryOne\` with 'count'=${options.count}: did you mean to use \`queryAll\`?`
         );
     }
     return _queryOne(target, options);

addons/web/static/lib/hoot/tests/hoot-dom/dom.test.js

@@ -496,6 +496,17 @@ describe(parseUrl(import.meta.url), () => {
             });
         });
 
+        test("query options", async () => {
+            await mountForTest(FULL_HTML_TEMPLATE);
+
+            expect($$("input", { count: 2 })).toHaveLength(2);
+            expect(() => $$("input", { count: 1 })).toThrow();
+
+            expect($$("option", { count: 6 })).toHaveLength(6);
+            expect($$("option", { count: 3, root: "[name=title]" })).toHaveLength(3);
+            expect(() => $$("option", { count: 6, root: "[name=title]" })).toThrow();
+        });
+
         test("advanced use cases", async () => {
             await mountForTest(FULL_HTML_TEMPLATE);
 
@@ -864,7 +875,7 @@ describe(parseUrl(import.meta.url), () => {
             expect($1(".title:first")).toBe(getFixture().querySelector("header .title"));
 
             expect(() => $1(".title")).toThrow();
-            expect(() => $1(".title", { exact: 2 })).toThrow();
+            expect(() => $1(".title", { count: 2 })).toThrow();
         });
 
         test("queryRect", async () => {
@@ -902,10 +913,10 @@ describe(parseUrl(import.meta.url), () => {
 
             // queryOne error messages
             expect(() => $1()).toThrow(`found 0 elements instead of 1`);
-            expect(() => $$([], { exact: 18 })).toThrow(`found 0 elements instead of 18`);
+            expect(() => $$([], { count: 18 })).toThrow(`found 0 elements instead of 18`);
             expect(() => $1("")).toThrow(`found 0 elements instead of 1: 0 matching ""`);
-            expect(() => $$(".tralalero", { exact: -20 })).toThrow(
-                `found 1 element instead of -20: 1 matching ".tralalero"`
+            expect(() => $$(".tralalero", { count: -20 })).toThrow(
+                `invalid 'count' option: should be a positive integer`
             );
             expect(() => $1`.tralalero:contains(Tralala):visible:scrollable:first`).toThrow(
                 `found 0 elements instead of 1: 0 matching ".tralalero:contains(Tralala):visible:scrollable:first" (1 element with text "Tralala" > 1 visible element > 0 scrollable elements)`