comments, simplifications

Author: kof

apps/builder/app/builder/features/style-panel/sections/backgrounds/gradient-utils.ts

@@ -60,6 +60,10 @@ const gradientFunctionNames: Record<
   },
 };
 
+/**
+ * Checks if a CSS value string starts with a gradient function of the specified type.
+ * Handles both base and repeating gradient functions (e.g., "linear-gradient" and "repeating-linear-gradient").
+ */
 const startsWithGradientFunction = (value: string, type: GradientType) => {
   const normalized = value.trim().toLowerCase();
   const { base, repeating } = gradientFunctionNames[type];
@@ -87,23 +91,16 @@ export const percentUnitOptions: UnitOption[] = [
   },
 ];
 
-const createKeywordValue = (value: string): KeywordValue => ({
-  type: "keyword",
-  value,
-});
-
-const createCenterKeyword = () => createKeywordValue("center");
-
 export const gradientPositionXOptions: KeywordValue[] = [
-  createCenterKeyword(),
-  createKeywordValue("left"),
-  createKeywordValue("right"),
+  { type: "keyword", value: "center" },
+  { type: "keyword", value: "left" },
+  { type: "keyword", value: "right" },
 ];
 
 export const gradientPositionYOptions: KeywordValue[] = [
-  createCenterKeyword(),
-  createKeywordValue("top"),
-  createKeywordValue("bottom"),
+  { type: "keyword", value: "center" },
+  { type: "keyword", value: "top" },
+  { type: "keyword", value: "bottom" },
 ];
 
 const getAxisPositionValue = (
@@ -120,11 +117,15 @@ const getAxisPositionValue = (
   return parsed;
 };
 
+/**
+ * Parses a gradient position string into separate x and y StyleValues.
+ * Defaults to "center center" if position is undefined or parsing fails.
+ */
 export const parseGradientPositionValues = (position?: string) => {
   if (position === undefined) {
     return {
-      xValue: createCenterKeyword(),
-      yValue: createCenterKeyword(),
+      xValue: { type: "keyword" as const, value: "center" },
+      yValue: { type: "keyword" as const, value: "center" },
     } as const;
   }
   try {
@@ -134,27 +135,33 @@ export const parseGradientPositionValues = (position?: string) => {
       // Use the real background-position longhand when parsing so we can reuse
       // its CSS syntax rules, but assign the result to the gradient-specific
       // custom property downstream.
-      xValue:
-        getAxisPositionValue(backgroundPositionXLonghand, xLonghand?.[1]) ??
-        createCenterKeyword(),
-      yValue:
-        getAxisPositionValue(backgroundPositionYLonghand, yLonghand?.[1]) ??
-        createCenterKeyword(),
+      xValue: getAxisPositionValue(
+        backgroundPositionXLonghand,
+        xLonghand?.[1]
+      ) ?? { type: "keyword" as const, value: "center" },
+      yValue: getAxisPositionValue(
+        backgroundPositionYLonghand,
+        yLonghand?.[1]
+      ) ?? { type: "keyword" as const, value: "center" },
     } as const;
   } catch {
     return {
-      xValue: createCenterKeyword(),
-      yValue: createCenterKeyword(),
+      xValue: { type: "keyword" as const, value: "center" },
+      yValue: { type: "keyword" as const, value: "center" },
     } as const;
   }
 };
 
+/**
+ * Formats x and y position values into a CSS position string.
+ * Omits "center center" as it's the default. Returns just x if y is center.
+ */
 export const formatGradientPositionValues = (
   xValue?: StyleValue,
   yValue?: StyleValue
 ) => {
-  const x = toValue(xValue ?? createCenterKeyword());
-  const y = toValue(yValue ?? createCenterKeyword());
+  const x = toValue(xValue ?? { type: "keyword" as const, value: "center" });
+  const y = toValue(yValue ?? { type: "keyword" as const, value: "center" });
   if (x === "center" && y === "center") {
     return;
   }
@@ -190,6 +197,11 @@ const angleUnitToDegrees = (value: UnitValue): number | undefined => {
   }
 };
 
+/**
+ * Converts a UnitValue to a PercentUnitValue.
+ * For percent units, clamps to 0-100. For angle units, converts to percent (0-100 representing 0-360deg).
+ * Returns undefined for unsupported unit types.
+ */
 const toPercentUnitValue = (value: UnitValue): PercentUnitValue | undefined => {
   if (value.unit === "%") {
     return {
@@ -286,7 +298,7 @@ export const isRadialGradient = (
 ): gradient is ParsedRadialGradient => gradient.type === "radial";
 
 /**
- * Get the default angle for a gradient according to CSS spec.
+ * Returns the CSS spec default angle for each gradient type:
  * - linear-gradient: 180deg (to bottom)
  * - conic-gradient: 0deg (from top)
  * - radial-gradient: undefined (no angle)
@@ -330,6 +342,10 @@ export const getPercentUnit = (
   }
 };
 
+/**
+ * Converts repeating-*-gradient to *-gradient while preserving leading whitespace.
+ * Returns both the normalized string and whether it was originally repeating.
+ */
 export const normalizeGradientInput = (
   gradientString: string,
   gradientType: GradientType
@@ -401,6 +417,10 @@ export const sideOrCornerToAngle = (
   }
 };
 
+/**
+ * Interpolates missing stop positions proportionally between defined positions.
+ * Only works with percent units - returns original gradient for non-percent units.
+ */
 export const fillMissingStopPositions = <T extends ParsedGradient>(
   gradient: T
 ): T => {
@@ -501,11 +521,9 @@ export const fillMissingStopPositions = <T extends ParsedGradient>(
   } as T;
 };
 
-const cloneVarValue = (value: VarValue): VarValue => ({
-  ...value,
-  fallback: value.fallback && { ...value.fallback },
-});
-
+/**
+ * Clones stop values, deep cloning var fallbacks to avoid shared references.
+ */
 const cloneGradientStopValue = <
   Value extends GradientStop["position"] | GradientStop["hint"],
 >(
@@ -525,50 +543,48 @@ const cloneGradientStopValue = <
   return { ...value };
 };
 
+/**
+ * Clones colors, deep cloning var fallbacks to avoid shared references.
+ */
 const cloneGradientStopColor = (
   color: GradientStop["color"] | undefined
 ): GradientStop["color"] => {
   if (color === undefined) {
-    return { ...fallbackStopColor } satisfies GradientStop["color"];
+    return { ...fallbackStopColor };
   }
   if (color.type === "var") {
     return {
       ...color,
       fallback: color.fallback && { ...color.fallback },
-    } satisfies GradientStop["color"];
-  }
-  if (color.type === "rgb") {
-    return { ...color } satisfies GradientStop["color"];
+    };
   }
-  return { ...color } satisfies GradientStop["color"];
-};
-
-const createSolidGradientStops = (color: GradientStop["color"]) => {
-  const firstColor = cloneGradientStopColor(color);
-  const secondColor = cloneGradientStopColor(color);
-  return [
-    {
-      color: firstColor,
-      position: { type: "unit", unit: "%", value: 0 },
-    },
-    {
-      color: secondColor,
-      position: { type: "unit", unit: "%", value: 100 },
-    },
-  ] satisfies GradientStop[];
+  return { ...color };
 };
 
+/**
+ * Creates a solid color gradient (two identical stops at 0% and 100%).
+ */
 export const createSolidLinearGradient = (
   color: GradientStop["color"],
   base?: ParsedLinearGradient
 ): ParsedLinearGradient => {
-  const stops = createSolidGradientStops(color);
+  const firstColor = cloneGradientStopColor(color);
+  const secondColor = cloneGradientStopColor(color);
   return {
     type: "linear",
     angle: base?.angle,
     sideOrCorner: base?.sideOrCorner,
-    stops,
-  } satisfies ParsedLinearGradient;
+    stops: [
+      {
+        color: firstColor,
+        position: { type: "unit", unit: "%", value: 0 },
+      },
+      {
+        color: secondColor,
+        position: { type: "unit", unit: "%", value: 100 },
+      },
+    ],
+  };
 };
 
 type AngleUnitValue = UnitValue & { unit: AngleUnit };
@@ -582,14 +598,17 @@ const resolveAnglePrimitive = (
   }
 
   if (value.type === "var") {
-    return cloneVarValue(value);
+    return {
+      ...value,
+      fallback: value.fallback && { ...value.fallback },
+    };
   }
 
   if (value.type === "unit" && isAngleUnit(value.unit)) {
     return {
       ...value,
       unit: value.unit,
-    } satisfies AngleUnitValue;
+    };
   }
 
   return;
@@ -689,6 +708,9 @@ const normalizeStopsForPicker = <T extends ParsedGradient>(gradient: T): T => {
   } as T;
 };
 
+/**
+ * Converts conic angle units (deg, turn, etc.) to percent units for picker UI.
+ */
 const convertConicStopsToPercent = <T extends ParsedGradient>(
   gradient: T
 ): T => {
@@ -748,6 +770,9 @@ const convertConicStopsToPercent = <T extends ParsedGradient>(
   } as T;
 };
 
+/**
+ * Prepares gradient for picker UI: converts angles to percent, resolves vars, fills positions, applies hint overrides.
+ */
 export const resolveGradientForPicker = <T extends ParsedGradient>(
   gradient: T,
   hintOverrides: ReadonlyMap<number, PercentUnitValue>
@@ -782,6 +807,9 @@ export const resolveGradientForPicker = <T extends ParsedGradient>(
   } as T;
 };
 
+/**
+ * Returns same map reference if unchanged for referential equality.
+ */
 export const removeHintOverride = (
   overrides: Map<number, PercentUnitValue>,
   stopIndex: number
@@ -794,6 +822,9 @@ export const removeHintOverride = (
   return next;
 };
 
+/**
+ * Returns same map reference if unchanged for referential equality.
+ */
 export const setHintOverride = (
   overrides: Map<number, PercentUnitValue>,
   stopIndex: number,
@@ -817,6 +848,9 @@ export const setHintOverride = (
   return next;
 };
 
+/**
+ * Returns same map reference if unchanged for referential equality.
+ */
 export const pruneHintOverrides = (
   overrides: Map<number, PercentUnitValue>,
   stopCount: number
@@ -835,13 +869,11 @@ export const pruneHintOverrides = (
   return changed ? next : overrides;
 };
 
-// Helper to get stop position as a number (0-100) for sorting and calculations
 export const getStopPosition = (stop: GradientStop): number =>
   stop.position?.type === "unit" && stop.position.unit === "%"
     ? stop.position.value
     : 0;
 
-// Reindex hint overrides after a stop is deleted
 export const reindexHintOverrides = (
   overrides: Map<number, PercentUnitValue>,
   deletedIndex: number
@@ -857,7 +889,6 @@ export const reindexHintOverrides = (
   return reindexed;
 };
 
-// Sort gradient stops by position and reindex hint overrides to match
 export const sortGradientStops = (
   gradient: ParsedGradient,
   hintOverrides: Map<number, PercentUnitValue>
@@ -905,6 +936,9 @@ export type ReverseStopsResolution<T extends ParsedGradient> =
     }
   | { type: "none" };
 
+/**
+ * Reverses stops and mirrors percent positions (0% becomes 100%, etc.).
+ */
 export const resolveReverseStops = <T extends ParsedGradient>(
   gradient: T,
   selectedStopIndex: number
@@ -1208,7 +1242,9 @@ type GradientByType<T extends GradientType> = Extract<
   { type: T }
 >;
 
-// Cache for parsed gradients - avoids re-parsing the same gradient string
+/**
+ * Cached to avoid re-parsing the same string.
+ */
 const parsedGradientCache = new Map<string, ParsedGradient | undefined>();
 
 export const parseAnyGradient = (value: string): ParsedGradient | undefined => {
@@ -1252,6 +1288,11 @@ export const convertGradientToTarget = <Target extends GradientType>(
   return converted as GradientByType<Target>;
 };
 
+/**
+ * Formats a gradient for a specific background type.
+ * Handles solid color conversion and gradient type conversions.
+ * Returns the formatted CSS gradient string.
+ */
 export const formatGradientForType = (
   styleValue: StyleValue | undefined,
   target: Exclude<BackgroundType, "image">
@@ -1273,6 +1314,11 @@ export const formatGradientForType = (
   return formatRadialGradient(parsed);
 };
 
+/**
+ * Detects the background type from a StyleValue.
+ * Returns "solid" for uniform linear gradients, specific gradient types for gradients,
+ * and "image" for non-gradient values or unparseable gradients.
+ */
 export const detectBackgroundType = (
   styleValue?: StyleValue
 ): BackgroundType => {
@@ -1323,6 +1369,11 @@ export const detectBackgroundType = (
   return "image";
 };
 
+/**
+ * Gets a specific background layer item from a ComputedStyleDecl.
+ * For index 0, returns the first layer or the cascaded value itself.
+ * For index > 0, delegates to getRepeatedStyleItem.
+ */
 export const getBackgroundStyleItem = (
   styleDecl: ComputedStyleDecl,
   index: number