Streamline and test @siteimprove/alfa-cascade

.changeset/four-parents-jog.md

@@ -0,0 +1,9 @@
+---
+"@siteimprove/alfa-cascade": minor
+---
+
+**Breaking:** `RuleTree.add` and `RuleTree.Node.add` have been made internal.
+
+These have heavy assumptions on arguments in order to build a correct rule tree and are not intended for external use. Use `Cascade.of` to build correct cascade and rule trees.
+
+In addition, `RuleTree.Node.add` has been moved to an instance method, and its arguments have been simplified.

.changeset/pink-walls-remain.md

@@ -0,0 +1,5 @@
+---
+"@siteimprove/alfa-selector": minor
+---
+
+**Added:** Selectors now contain a "key selector" which is the leftmost simple selector in a compound one, or the rightmost in a complex one.

.changeset/tiny-eyes-attack.md

@@ -0,0 +1,7 @@
+---
+"@siteimprove/alfa-cascade": minor
+---
+
+**Breaking:** `Cascade.get()` now returns a `RuleTree.Node` instead of an `Option`.
+
+`RuleTree` now have a fake root with no declarations, if no rule matches the current element, `Cascade.get(element)` will return that fake root.

docs/review/api/alfa-cascade.api.md

@@ -23,7 +23,7 @@ export class Cascade implements Serializable {
     // Warning: (ae-forgotten-export) The symbol "AncestorFilter" needs to be exported by the entry point index.d.ts
     //
     // (undocumented)
-    get(element: Element, context?: Context, filter?: Option<AncestorFilter>): Option<RuleTree.Node>;
+    get(element: Element, context?: Context, filter?: Option<AncestorFilter>): RuleTree.Node;
     // (undocumented)
     static of(node: Document | Shadow, device: Device): Cascade;
     // (undocumented)
@@ -51,12 +51,8 @@ export namespace Cascade {
 
 // @public
 export class RuleTree implements Serializable {
-    // (undocumented)
-    add(rules: Iterable_2<{
-        rule: Rule;
-        selector: Selector;
-        declarations: Iterable_2<Declaration>;
-    }>): Option<RuleTree.Node>;
+    // @internal
+    add(rules: Iterable_2<RuleTree.Item>): RuleTree.Node;
     // (undocumented)
     static empty(): RuleTree;
     // (undocumented)
@@ -65,12 +61,35 @@ export class RuleTree implements Serializable {
 
 // @public (undocumented)
 export namespace RuleTree {
+    // @internal
+    export interface Item {
+        // (undocumented)
+        declarations: Iterable_2<Declaration>;
+        // (undocumented)
+        rule: Rule;
+        // (undocumented)
+        selector: Selector;
+    }
+    // (undocumented)
+    export namespace Item {
+        // (undocumented)
+        export interface JSON {
+            // (undocumented)
+            [key: string]: json.JSON;
+            // (undocumented)
+            declarations: Array<Declaration.JSON>;
+            // (undocumented)
+            rule: Rule.JSON;
+            // (undocumented)
+            selector: Selector.JSON;
+        }
+    }
     // (undocumented)
     export type JSON = Array<Node.JSON>;
     // (undocumented)
     export class Node implements Serializable {
-        // (undocumented)
-        static add(rule: Rule, selector: Selector, declarations: Iterable_2<Declaration>, children: Array<Node>, parent: Option<Node>): Node;
+        // @internal
+        add(item: Item): Node;
         // (undocumented)
         ancestors(): Iterable_2<Node>;
         // (undocumented)
@@ -80,7 +99,7 @@ export namespace RuleTree {
         // (undocumented)
         inclusiveAncestors(): Iterable_2<Node>;
         // (undocumented)
-        static of(rule: Rule, selector: Selector, declarations: Iterable_2<Declaration>, children: Array<Node>, parent: Option<Node>): Node;
+        static of({ rule, selector, declarations }: Item, children: Array<Node>, parent: Option<Node>): Node;
         // (undocumented)
         get parent(): Option<Node>;
         // (undocumented)
@@ -99,11 +118,7 @@ export namespace RuleTree {
             // (undocumented)
             children: Array<Node.JSON>;
             // (undocumented)
-            declarations: Array<Declaration.JSON>;
-            // (undocumented)
-            rule: Rule.JSON;
-            // (undocumented)
-            selector: Selector.JSON;
+            item: Item.JSON;
         }
     }
 }

docs/review/api/alfa-selector.api.md

@@ -110,6 +110,8 @@ export class Class extends WithName<"class"> {
     // (undocumented)
     equals(value: unknown): value is this;
     // (undocumented)
+    protected readonly _key: Option<Class>;
+    // (undocumented)
     matches(element: Element): boolean;
     // (undocumented)
     static of(name: string): Class;
@@ -161,6 +163,8 @@ export class Complex extends Selector_2<"complex"> {
     // (undocumented)
     equals(value: unknown): value is this;
     // (undocumented)
+    protected readonly _key: Option<Id | Class | Type>;
+    // (undocumented)
     get left(): Simple | Compound | Complex;
     // (undocumented)
     matches(element: Element, context?: Context): boolean;
@@ -200,6 +204,8 @@ export class Compound extends Selector_2<"compound"> {
     // (undocumented)
     equals(value: unknown): value is this;
     // (undocumented)
+    protected readonly _key: Option<Id | Class | Type>;
+    // (undocumented)
     get length(): number;
     // (undocumented)
     matches(element: Element, context?: Context): boolean;
@@ -296,6 +302,8 @@ export class Id extends WithName<"id"> {
     // (undocumented)
     equals(value: unknown): value is this;
     // (undocumented)
+    protected readonly _key: Option<Id>;
+    // (undocumented)
     matches(element: Element): boolean;
     // (undocumented)
     static of(name: string): Id;
@@ -495,6 +503,8 @@ export class Type extends WithName<"type"> {
     // (undocumented)
     equals(value: unknown): value is this;
     // (undocumented)
+    protected readonly _key: Option<Type>;
+    // (undocumented)
     matches(element: Element): boolean;
     // (undocumented)
     get namespace(): Option<string>;