experimental: parse linear-gradient and extract stops, angle, side-or-corner and hints from the gradient. (#4131)

## Description
This PR is to kick off the #3448 track. First of everything we need to
build the gradient selector/indicator

![image](https://github.com/user-attachments/assets/6901327d-0ba0-4b7d-a3ff-41dbcf806912)

Which should be able to parse the gradient and pick the `stops` and
`colors` and `hints` from it.


## Steps for reproduction

1. click button
2. expect xyz

## Code Review

- [ ] hi @kof, I need you to do
  - conceptual review (architecture, feature-correctness)
  - detailed review (read every line)
  - test it on preview

## Before requesting a review

- [ ] made a self-review
- [ ] added inline comments where things may be not obvious (the "why",
not "what")

## Before merging

- [ ] tested locally and on preview environment (preview dev login:
5de6)
- [ ] updated [test
cases](https://github.com/webstudio-is/webstudio/blob/main/apps/builder/docs/test-cases.md)
document
- [ ] added tests
- [ ] if any new env variables are added, added them to `.env` file

Author: JayaKrishnaNamburu

packages/css-data/src/property-parsers/linear-gradient.test.ts

@@ -0,0 +1,137 @@
+import { test, describe, expect } from "@jest/globals";
+import {
+  parseLinearGradient,
+  reconstructLinearGradient,
+} from "./linear-gradient";
+
+describe("parses linear-gradient", () => {
+  test("parses gradient without angle, sides and color-stops", () => {
+    expect(parseLinearGradient("linear-gradient(red, blue, yellow)")).toEqual({
+      angle: undefined,
+      sideOrCorner: undefined,
+      stops: [
+        {
+          color: { alpha: 1, b: 0, g: 0, r: 255, type: "rgb" },
+          hint: undefined,
+          position: undefined,
+        },
+        {
+          color: { alpha: 1, b: 255, g: 0, r: 0, type: "rgb" },
+          hint: undefined,
+          position: undefined,
+        },
+        {
+          color: { alpha: 1, b: 0, g: 255, r: 255, type: "rgb" },
+          hint: undefined,
+          position: undefined,
+        },
+      ],
+    });
+  });
+
+  test("parses linear-gradient with angle and color-stops", () => {
+    expect(
+      parseLinearGradient("linear-gradient(135deg, orange 60% 20%, 40%, cyan)")
+    ).toEqual({
+      angle: { type: "unit", unit: "deg", value: 135 },
+      sideOrCorner: undefined,
+      stops: [
+        {
+          color: { alpha: 1, b: 0, g: 165, r: 255, type: "rgb" },
+          hint: { type: "unit", unit: "%", value: 20 },
+          position: { type: "unit", unit: "%", value: 60 },
+        },
+        { hint: { type: "unit", unit: "%", value: 40 } },
+        {
+          color: { alpha: 1, b: 255, g: 255, r: 0, type: "rgb" },
+          hint: undefined,
+          position: undefined,
+        },
+      ],
+    });
+  });
+
+  test("parses linear-gradient with side-or-corer and multiple colors without stops", () => {
+    expect(
+      parseLinearGradient(
+        "linear-gradient(to top right, orange, yellow, blue, green)"
+      )
+    ).toEqual({
+      angle: undefined,
+      sideOrCorner: { type: "keyword", value: "to top right" },
+      stops: [
+        {
+          color: { alpha: 1, b: 0, g: 165, r: 255, type: "rgb" },
+          hint: undefined,
+          position: undefined,
+        },
+        {
+          color: { alpha: 1, b: 0, g: 255, r: 255, type: "rgb" },
+          hint: undefined,
+          position: undefined,
+        },
+        {
+          color: { alpha: 1, b: 255, g: 0, r: 0, type: "rgb" },
+          hint: undefined,
+          position: undefined,
+        },
+        {
+          color: { alpha: 1, b: 0, g: 128, r: 0, type: "rgb" },
+          hint: undefined,
+          position: undefined,
+        },
+      ],
+    });
+  });
+
+  test("parses linear-gradient with multiple angles and color-stops", () => {
+    expect(
+      parseLinearGradient(
+        "linear-gradient(to right, red 20%, orange 20% 40%, yellow 40% 60%, green 60% 80%, blue 80% )"
+      )
+    ).toEqual({
+      angle: undefined,
+      sideOrCorner: { type: "keyword", value: "to right" },
+      stops: [
+        {
+          color: { alpha: 1, b: 0, g: 0, r: 255, type: "rgb" },
+          hint: undefined,
+          position: { type: "unit", unit: "%", value: 20 },
+        },
+        {
+          color: { alpha: 1, b: 0, g: 165, r: 255, type: "rgb" },
+          hint: { type: "unit", unit: "%", value: 40 },
+          position: { type: "unit", unit: "%", value: 20 },
+        },
+        {
+          color: { alpha: 1, b: 0, g: 255, r: 255, type: "rgb" },
+          hint: { type: "unit", unit: "%", value: 60 },
+          position: { type: "unit", unit: "%", value: 40 },
+        },
+        {
+          color: { alpha: 1, b: 0, g: 128, r: 0, type: "rgb" },
+          hint: { type: "unit", unit: "%", value: 80 },
+          position: { type: "unit", unit: "%", value: 60 },
+        },
+        {
+          color: { alpha: 1, b: 255, g: 0, r: 0, type: "rgb" },
+          hint: undefined,
+          position: { type: "unit", unit: "%", value: 80 },
+        },
+      ],
+    });
+  });
+
+  test("parses linear-gradient with rgb values", () => {
+    const parsed = parseLinearGradient(
+      "linear-gradient(rgb(255, 0, 0), rgb(0, 255, 0), rgb(0, 0, 255))"
+    );
+    if (parsed === undefined) {
+      throw new Error("parsed is undefined");
+    }
+
+    expect(reconstructLinearGradient(parsed)).toEqual(
+      "linear-gradient(rgba(255, 0, 0, 1), rgba(0, 255, 0, 1), rgba(0, 0, 255, 1))"
+    );
+  });
+});

packages/css-data/src/property-parsers/linear-gradient.ts

@@ -0,0 +1,200 @@
+import * as csstree from "css-tree";
+import { cssTryParseValue } from "../parse-css-value";
+import { colord, extend } from "colord";
+import {
+  type UnitValue,
+  type Unit,
+  toValue,
+  KeywordValue,
+  type RgbValue,
+} from "@webstudio-is/css-engine";
+import namesPlugin from "colord/plugins/names";
+
+extend([namesPlugin]);
+
+interface GradientStop {
+  color?: RgbValue;
+  position?: UnitValue;
+  hint?: UnitValue;
+}
+
+interface ParsedGradient {
+  angle?: UnitValue;
+  sideOrCorner?: KeywordValue;
+  stops: GradientStop[];
+}
+
+const sideOrCorderIdentifiers = ["to", "top", "bottom", "left", "right"];
+
+// We are currently not supporting color-interpolation-method from the linear-gradient syntax.
+// There are multiple reasons to not support it:
+// - mdn-data does not have any information about it. There is a PR that is opened about it.
+//   https://github.com/mdn/data/pull/766 which needs to be released first.
+// - we can't use css-tree parser directly and by-pass using css-tree lexer.match.But there are again multiple issues
+//   css-tree package don't have information about <color-interpolation-method> for [email protected].
+//   They only added it after [email protected] which has breaking changes for us to upgrade directly.
+// - patching the css-tree package is a solution. But the issue was, we need to import esm build of the package.
+//   But in esm build the patch.json file is merged in build file. So, even if patch the json file for syntaxes it will not help.
+
+export const parseLinearGradient = (
+  gradient: string
+): ParsedGradient | undefined => {
+  const ast = cssTryParseValue(gradient);
+  if (ast === undefined) {
+    return;
+  }
+
+  const match = csstree.lexer.match(
+    "linear-gradient( [ <angle> | to <side-or-corner> ]? , <color-stop-list> )",
+    ast
+  );
+  if (match.matched === null) {
+    return;
+  }
+
+  let angle: UnitValue | undefined;
+  let sideOrCorner: KeywordValue | undefined;
+  const stops: GradientStop[] = [];
+  let gradientParts: csstree.CssNode[] = [];
+
+  csstree.walk(ast, (node) => {
+    if (node.type === "Function" && node.name === "linear-gradient") {
+      for (const item of node.children) {
+        if (item.type !== "Operator") {
+          gradientParts.push(item);
+        }
+
+        if (
+          (item.type === "Operator" && item.value === ",") ||
+          node.children.last === item
+        ) {
+          // If the gradientParts lenght is 1, then we need to check if it is angle or not.
+          // If it's angle, then the value is related to <angle> or else it is a <color-hint>.
+          if (gradientParts.length === 1) {
+            if (isAngle(gradientParts[0]) === true) {
+              angle = mapPercenTageOrDimentionToUnit(gradientParts[0]);
+            }
+
+            if (
+              gradientParts[0].type === "Percentage" ||
+              (gradientParts[0].type === "Dimension" &&
+                ["deg", "grad", "rad", "turn"].includes(
+                  gradientParts[0].unit
+                ) === false)
+            ) {
+              stops.push({
+                hint: mapPercenTageOrDimentionToUnit(gradientParts[0]),
+              });
+            }
+          }
+
+          if (gradientParts.length && isSideOrCorner(gradientParts[0])) {
+            const value = gradientParts
+              .map((item) => csstree.generate(item))
+              .join(" ");
+            sideOrCorner = { type: "keyword", value };
+          }
+
+          // if there is a color-stop in the gradientParts, then we need to parse it for position and hint.
+          const colorStop = gradientParts.find(isColorStop);
+          if (colorStop !== undefined) {
+            const [_colorStop, position, hint] = gradientParts;
+
+            const stop: GradientStop = {
+              color: getColor(colorStop),
+              position: mapPercenTageOrDimentionToUnit(position),
+              hint: mapPercenTageOrDimentionToUnit(hint),
+            };
+
+            stops.push(stop);
+          }
+
+          gradientParts = [];
+        }
+      }
+    }
+  });
+
+  return { angle, sideOrCorner, stops };
+};
+
+const mapPercenTageOrDimentionToUnit = (
+  node?: csstree.CssNode
+): UnitValue | undefined => {
+  if (node === undefined) {
+    return;
+  }
+
+  if (node.type !== "Percentage" && node.type !== "Dimension") {
+    return;
+  }
+
+  return {
+    type: "unit",
+    value: parseFloat(node.value),
+    unit: node.type === "Percentage" ? "%" : (node.unit as Unit),
+  };
+};
+
+const isAngle = (node: csstree.CssNode): node is csstree.Dimension =>
+  node.type === "Dimension" &&
+  ["deg", "grad", "rad", "turn"].includes(node.unit);
+
+const isSideOrCorner = (node: csstree.CssNode): node is csstree.Identifier =>
+  node.type === "Identifier" && sideOrCorderIdentifiers.includes(node.name);
+
+const isColorStop = (
+  node: csstree.CssNode
+): node is csstree.Identifier | csstree.FunctionNode | csstree.Hash => {
+  return (
+    (node.type === "Function" ||
+      (node.type === "Identifier" &&
+        sideOrCorderIdentifiers.includes(node.name)) === false ||
+      node.type === "Hash") &&
+    colord(csstree.generate(node)).isValid() === true
+  );
+};
+
+const getColor = (
+  node: csstree.FunctionNode | csstree.Identifier | csstree.Hash
+): RgbValue | undefined => {
+  let color: string;
+  if (node.type === "Function") {
+    color = csstree.generate(node);
+  } else if (node.type === "Identifier") {
+    color = node.name;
+  } else {
+    color = csstree.generate(node);
+  }
+
+  const result = colord(color);
+  if (result.isValid()) {
+    const value = result.toRgb();
+
+    return {
+      type: "rgb",
+      r: value.r,
+      g: value.g,
+      b: value.b,
+      alpha: value.a,
+    };
+  }
+};
+
+export const reconstructLinearGradient = (parsed: ParsedGradient): string => {
+  const direction = parsed.angle || parsed.sideOrCorner;
+  const stops = parsed.stops
+    .map((stop: GradientStop) => {
+      let result = toValue(stop.color);
+      if (stop.position) {
+        result += ` ${toValue(stop.position)}`;
+      }
+      if (stop.hint) {
+        result += ` ${toValue(stop.hint)}`;
+      }
+      return result;
+    })
+    .join(", ");
+
+  return `linear-gradient(${direction ? toValue(direction) + ", " : ""}${stops})`;
+};