Support for mask CSS shorthand property (#1711)

* Add `mask-*` longhands * Add tests for mask-mode * Add tests for mask-origin * Add tests for mask-repeat * Move types from coord-box.ts to box.ts * Extract API * Fix knip warnings * Implement mask-repeat * Extract common function * Remove empty test files * Handle layers in mask-composite * Update TODO and fix link * Handle layers in mask-mode * Handle layers in mask-origin * Add mask-size * Add mask-position * Remove unused imports * Extract API * Implement mask-position * Extract API * Implement shorthand `mask` * Extract API * Add `mask` to shorthands * Extract API * Add test of shorthand as well as clean up and minor fixes * Update few-clouds-play.md * Rename file * Update mask-layers.ts * Update packages/alfa-style/src/property/helpers/mask-layers.ts Co-authored-by: Jean-Yves Moyen <[email protected]> * Update packages/alfa-style/src/property/mask.ts Co-authored-by: Jean-Yves Moyen <[email protected]> * Add method for cutting or repeating an `alfa-css` `List` * Move layering logic * Align with existing code structure * Extract API * Make the returned layers resolver typed * Extract API * Use `Tuple` in `mask-repeat` * Use `Tuple` in `mask-size` * Add note about discrepancy with spec in position computation * Extract API --------- Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Jean-Yves Moyen <[email protected]>
Siteimprove · Dec 12, 2024 · 3a3e6e5 · 3a3e6e5
1 parent 092e524
commit 3a3e6e5
Show file tree

Hide file tree

Showing 32 changed files with 1,913 additions and 163 deletions.
diff --git a/.changeset/few-clouds-play.md b/.changeset/few-clouds-play.md
@@ -0,0 +1,5 @@
+---
+"@siteimprove/alfa-style": minor
+---
+
+**Added:** CSS shorthand property `mask` and corresponding longhand properties are now supported.
diff --git a/.changeset/rare-lies-invent.md b/.changeset/rare-lies-invent.md
@@ -0,0 +1,5 @@
+---
+"@siteimprove/alfa-css": minor
+---
+
+**Added:** `List#cutOrExtend` is now available.
diff --git a/.changeset/tame-ants-work.md b/.changeset/tame-ants-work.md
@@ -0,0 +1,5 @@
+---
+"@siteimprove/alfa-css": minor
+---
+
+**Added:** `List#size` is now available.
diff --git a/docs/review/api/alfa-css.api.md b/docs/review/api/alfa-css.api.md
@@ -201,18 +201,36 @@ export type Box = Keyword<"border-box"> | Keyword<"padding-box"> | Keyword<"cont
 // @public (undocumented)
 export namespace Box {
     // (undocumented)
-    export type Geometry = Shape | Keyword<"fill-box"> | Keyword<"stroke-box"> | Keyword<"view-box">;
+    export type CoordBox = PaintBox | Keyword<"view-box">;
     const // (undocumented)
     parse: Parser<Box>;
     // (undocumented)
+    export namespace CoordBox {
+        // (undocumented)
+        export type JSON = PaintBox.JSON | Keyword.JSON<"view-box">;
+    }
+    // (undocumented)
+    export type Geometry = Shape | Keyword<"fill-box"> | Keyword<"stroke-box"> | Keyword<"view-box">;
+    const // (undocumented)
+    parseShape: Parser<Shape>;
+    // (undocumented)
     export namespace Geometry {
         // (undocumented)
         export type JSON = Shape.JSON | Keyword.JSON<"fill-box"> | Keyword.JSON<"stroke-box"> | Keyword.JSON<"view-box">;
     }
     // (undocumented)
     export type JSON = Keyword.JSON<"border-box"> | Keyword.JSON<"padding-box"> | Keyword.JSON<"content-box">;
     const // (undocumented)
-    parseShape: Parser<Shape>;
+    parseGeometry: Parser<Geometry>;
+    // (undocumented)
+    export type PaintBox = VisualBox | Keyword<"fill-box"> | Keyword<"stroke-box">;
+    // (undocumented)
+    export namespace PaintBox {
+        // (undocumented)
+        export type JSON = VisualBox.JSON | Keyword.JSON<"fill-box"> | Keyword.JSON<"stroke-box">;
+    }
+    const // (undocumented)
+    parseVisualBox: Parser<VisualBox>;
     // (undocumented)
     export type Shape = Box | Keyword<"margin-box">;
     // (undocumented)
@@ -221,7 +239,17 @@ export namespace Box {
         export type JSON = Box.JSON | Keyword.JSON<"margin-box">;
     }
     const // (undocumented)
-    parseGeometry: Parser<Geometry>;
+    parsePaintBox: Parser<PaintBox>;
+    // (undocumented)
+    export type VisualBox = Keyword<"content-box"> | Keyword<"padding-box"> | Keyword<"border-box">;
+    // (undocumented)
+    export namespace VisualBox {
+        // (undocumented)
+        export type JSON = Keyword.JSON<"content-box"> | Keyword.JSON<"padding-box"> | Keyword.JSON<"border-box">;
+    }
+    const // (undocumented)
+    parseCoordBox: Parser<CoordBox>;
+        {};
 }
 
 // Warning: (ae-forgotten-export) The symbol "BasicShape" needs to be exported by the entry point index.d.ts
@@ -1230,6 +1258,7 @@ export namespace Lexer {
 export class List<V extends Value> extends Value<"list", Value.HasCalculation<[V]>> implements Iterable_2<V>, Resolvable<List<Resolvable.Resolved<V>>, Resolvable.Resolver<V>>, PartiallyResolvable<List<Resolvable.PartiallyResolved<V>>, Resolvable.PartialResolver<V>> {
     // (undocumented)
     [Symbol.iterator](): Iterator<V>;
+    cutOrExtend(length: number): List<V>;
     // (undocumented)
     equals<T extends Value>(value: List<T>): boolean;
     // (undocumented)
@@ -1245,6 +1274,8 @@ export class List<V extends Value> extends Value<"list", Value.HasCalculation<[V
     // (undocumented)
     resolve(resolver?: Resolvable.Resolver<V>): List<Resolvable.Resolved<V>>;
     // (undocumented)
+    get size(): number;
+    // (undocumented)
     toJSON(): List.JSON<V>;
     // (undocumented)
     toString(): string;

diff --git a/docs/review/api/alfa-style.api.md b/docs/review/api/alfa-style.api.md
diff --git a/packages/alfa-css/src/value/box.ts b/packages/alfa-css/src/value/box.ts
@@ -66,4 +66,62 @@ export namespace Box {
     parseShape,
     Keyword.parse("fill-box", "stroke-box", "view-box"),
   );
+
+  /**
+   * {@link https://www.w3.org/TR/css-box-4/#typedef-visual-box}
+   */
+  export type VisualBox =
+    | Keyword<"content-box">
+    | Keyword<"padding-box">
+    | Keyword<"border-box">;
+
+  namespace VisualBox {
+    export type JSON =
+      | Keyword.JSON<"content-box">
+      | Keyword.JSON<"padding-box">
+      | Keyword.JSON<"border-box">;
+  }
+
+  export const parseVisualBox: CSSParser<VisualBox> = Keyword.parse(
+    "content-box",
+    "padding-box",
+    "border-box",
+  );
+
+  /**
+   * {@link https://www.w3.org/TR/css-box-4/#typedef-paint-box}
+   */
+  export type PaintBox =
+    | VisualBox
+    | Keyword<"fill-box">
+    | Keyword<"stroke-box">;
+
+  namespace PaintBox {
+    export type JSON =
+      | VisualBox.JSON
+      | Keyword.JSON<"fill-box">
+      | Keyword.JSON<"stroke-box">;
+  }
+
+  export const parsePaintBox: CSSParser<PaintBox> = either(
+    parseVisualBox,
+    Keyword.parse("fill-box", "stroke-box"),
+  );
+
+  /**
+   * {@link https://www.w3.org/TR/css-box-4/#typedef-coord-box}
+   *
+   * @privateRemarks
+   * This is not the same type as `Geometry`. The only difference is that this type does not contain `margin-box`.
+   */
+  export type CoordBox = PaintBox | Keyword<"view-box">;
+
+  export namespace CoordBox {
+    export type JSON = PaintBox.JSON | Keyword.JSON<"view-box">;
+  }
+
+  export const parseCoordBox: CSSParser<CoordBox> = either(
+    parsePaintBox,
+    Keyword.parse("view-box"),
+  );
 }
diff --git a/packages/alfa-css/src/value/collection/list.ts b/packages/alfa-css/src/value/collection/list.ts
@@ -44,6 +44,10 @@ export class List<V extends Value>
     return this._values;
   }
 
+  public get size(): number {
+    return this._values.length;
+  }
+
   public resolve(
     resolver?: Resolvable.Resolver<V>,
   ): List<Resolvable.Resolved<V>> {
@@ -65,6 +69,33 @@ export class List<V extends Value>
     return new List(this._values.map(mapper), this._separator);
   }
 
+  /**
+   * Returns a copy of the current instance cut off or extended with repeated values to match the given `length`.
+   *
+   * @example
+   * List.of([1, 2, 3]).cutOrExtend(2); // returns a new List with values [1, 2]
+   *
+   * @example
+   * List.of([1, 2, 3]).cutOrExtend(5); // returns a new List with values [1, 2, 3, 1, 2]
+   */
+  public cutOrExtend(length: number): List<V> {
+    if (this.size === length) {
+      return new List(this._values, this._separator);
+    }
+
+    if (length < this.size) {
+      return new List(this._values.slice(0, length), this._separator);
+    }
+
+    const extended: Array<V> = [];
+    for (let i = 0; i < length; ++i) {
+      // Cyclically repeat the values until the result has the desired length.
+      extended.push(this._values[i % this.size]);
+    }
+
+    return new List(extended, this._separator);
+  }
+
   public equals<T extends Value>(value: List<T>): boolean;
 
   public equals(value: unknown): value is this;

diff --git a/packages/alfa-css/test/value/collection/list.spec.ts b/packages/alfa-css/test/value/collection/list.spec.ts
@@ -2,15 +2,13 @@ import type { Parser } from "@siteimprove/alfa-parser";
 import type { Slice } from "@siteimprove/alfa-slice";
 import { test } from "@siteimprove/alfa-test";
 
-import type {
-  Token,
-  Value} from "../../../dist/index.js";
+import type { Token, Value } from "../../../dist/index.js";
 import {
   Length,
   LengthPercentage,
   Lexer,
   List,
-  Number
+  Number,
 } from "../../../dist/index.js";
 
 function parse<V extends Value>(
@@ -68,3 +66,40 @@ test("resolve() resolves all values in a list", (t) => {
     separator: ", ",
   });
 });
+
+test("#cutOrExtend returns identical copy if list has the same length as the given length", (t) => {
+  t.deepEqual(parse("1, 2, 3", Number.parse).cutOrExtend(3).toJSON(), {
+    type: "list",
+    values: [
+      { type: "number", value: 1 },
+      { type: "number", value: 2 },
+      { type: "number", value: 3 },
+    ],
+    separator: ", ",
+  });
+});
+
+test("#cutOrExtend cuts a list longer than the given length", (t) => {
+  t.deepEqual(parse("1, 2, 3", Number.parse).cutOrExtend(2).toJSON(), {
+    type: "list",
+    values: [
+      { type: "number", value: 1 },
+      { type: "number", value: 2 },
+    ],
+    separator: ", ",
+  });
+});
+
+test("#cutOrExtend repeats a list shorter than the given length", (t) => {
+  t.deepEqual(parse("1, 2, 3", Number.parse).cutOrExtend(5).toJSON(), {
+    type: "list",
+    values: [
+      { type: "number", value: 1 },
+      { type: "number", value: 2 },
+      { type: "number", value: 3 },
+      { type: "number", value: 1 },
+      { type: "number", value: 2 },
+    ],
+    separator: ", ",
+  });
+});
diff --git a/packages/alfa-style/src/longhands.ts b/packages/alfa-style/src/longhands.ts
@@ -83,6 +83,14 @@ import MarginBottom from "./property/margin-bottom.js";
 import MarginLeft from "./property/margin-left.js";
 import MarginRight from "./property/margin-right.js";
 import MarginTop from "./property/margin-top.js";
+import MaskClip from "./property/mask-clip.js";
+import MaskComposite from "./property/mask-composite.js";
+import MaskImage from "./property/mask-image.js";
+import MaskMode from "./property/mask-mode.js";
+import MaskOrigin from "./property/mask-origin.js";
+import MaskPosition from "./property/mask-position.js";
+import MaskRepeat from "./property/mask-repeat.js";
+import MaskSize from "./property/mask-size.js";
 import MinHeight from "./property/min-height.js";
 import MinWidth from "./property/min-width.js";
 import MixBlendMode from "./property/mix-blend-mode.js";
@@ -268,6 +276,14 @@ export namespace Longhands {
     "margin-left": MarginLeft,
     "margin-right": MarginRight,
     "margin-top": MarginTop,
+    "mask-clip": MaskClip,
+    "mask-composite": MaskComposite,
+    "mask-image": MaskImage,
+    "mask-mode": MaskMode,
+    "mask-origin": MaskOrigin,
+    "mask-position": MaskPosition,
+    "mask-repeat": MaskRepeat,
+    "mask-size": MaskSize,
     "min-height": MinHeight,
     "min-width": MinWidth,
     "mix-blend-mode": MixBlendMode,

diff --git a/packages/alfa-style/src/property/mask-clip.ts b/packages/alfa-style/src/property/mask-clip.ts
@@ -0,0 +1,41 @@
+import { Parser } from "@siteimprove/alfa-parser";
+import { Box, Keyword, List } from "@siteimprove/alfa-css";
+
+import { Longhand } from "../longhand.js";
+import { Resolver } from "../resolver.js";
+
+const { either } = Parser;
+
+type Specified = List<Specified.Item>;
+
+/**
+ * @internal
+ */
+export namespace Specified {
+  export type Item = Box.CoordBox | Keyword<"no-clip">;
+}
+
+type Computed = Specified;
+
+/**
+ * @internal
+ */
+export const parse = either(Box.parseCoordBox, Keyword.parse("no-clip"));
+
+const parseList = List.parseCommaSeparated(parse);
+
+/**
+ * @internal
+ */
+export const initialItem = Keyword.of("border-box");
+
+/**
+ * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/mask-clip}
+ *
+ * @internal
+ */
+export default Longhand.of<Specified, Computed>(
+  List.of([initialItem]),
+  parseList,
+  (value, style) => value.map(Resolver.layers(style, "mask-image")),
+);
diff --git a/packages/alfa-style/src/property/mask-composite.ts b/packages/alfa-style/src/property/mask-composite.ts
@@ -0,0 +1,42 @@
+import { Keyword, List } from "@siteimprove/alfa-css";
+
+import { Longhand } from "../longhand.js";
+import { Resolver } from "../resolver.js";
+
+type Specified = List<Specified.Item>;
+
+/**
+ * @internal
+ */
+export namespace Specified {
+  export type Item =
+    | Keyword<"add">
+    | Keyword<"subtract">
+    | Keyword<"intersect">
+    | Keyword<"exclude">;
+}
+
+type Computed = Specified;
+
+/**
+ * @internal
+ */
+export const parse = Keyword.parse("add", "subtract", "intersect", "exclude");
+
+const parseList = List.parseCommaSeparated(parse);
+
+/**
+ * @internal
+ */
+export const initialItem = Keyword.of("add");
+
+/**
+ * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/mask-composite}
+ *
+ * @internal
+ */
+export default Longhand.of<Specified, Computed>(
+  List.of([initialItem], ", "),
+  parseList,
+  (value, style) => value.map(Resolver.layers(style, "mask-image")),
+);