Support improvements to the new JS API

Author: nex3

lib/src/value/color.ts

@@ -20,6 +20,13 @@ interface HslColor {
   alpha: number;
 }
 
+interface HwbColor {
+  hue: number;
+  whiteness: number;
+  blackness: number;
+  alpha: number;
+}
+
 /** A SassScript color. */
 export class SassColor extends Value {
   private redInternal?: number;
@@ -30,102 +37,62 @@ export class SassColor extends Value {
   private lightnessInternal?: number;
   private readonly alphaInternal: number;
 
-  private constructor(color: RgbColor | HslColor) {
+  constructor(color: RgbColor | HslColor | HwbColor) {
     super();
 
     if ('red' in color) {
-      this.redInternal = color.red;
-      this.greenInternal = color.green;
-      this.blueInternal = color.blue;
+      this.redInternal = fuzzyAssertInRange(color.red, 0, 255, 'red');
+      this.greenInternal = fuzzyAssertInRange(color.green, 0, 255, 'green');
+      this.blueInternal = fuzzyAssertInRange(color.blue, 0, 255, 'blue');
+    } else if ('saturation' in color) {
+      this.hueInternal = color.hue % 360;
+      this.saturationInternal = fuzzyAssertInRange(
+        color.saturation,
+        0,
+        100,
+        'saturation'
+      );
+      this.lightnessInternal = fuzzyAssertInRange(
+        color.lightness,
+        0,
+        100,
+        'lightness'
+      );
     } else {
-      this.hueInternal = color.hue;
-      this.saturationInternal = color.saturation;
-      this.lightnessInternal = color.lightness;
+      // From https://www.w3.org/TR/css-color-4/#hwb-to-rgb
+      const scaledHue = (color.hue % 360) / 360;
+      let scaledWhiteness =
+        fuzzyAssertInRange(color.whiteness, 0, 100, 'whiteness') / 100;
+      let scaledBlackness =
+        fuzzyAssertInRange(color.blackness, 0, 100, 'blackness') / 100;
+
+      const sum = scaledWhiteness + scaledBlackness;
+      if (sum > 1) {
+        scaledWhiteness /= sum;
+        scaledBlackness /= sum;
+      }
+
+      // Because HWB is (currently) used much less frequently than HSL or RGB, we
+      // don't cache its values because we expect the memory overhead of doing so
+      // to outweigh the cost of recalculating it on access. Instead, we eagerly
+      // convert it to RGB and then convert back if necessary.
+      this.redInternal = toRgb(
+        scaledHue + 1 / 3,
+        scaledWhiteness,
+        scaledBlackness
+      );
+      this.greenInternal = toRgb(scaledHue, scaledWhiteness, scaledBlackness);
+      this.blueInternal = toRgb(
+        scaledHue - 1 / 3,
+        scaledWhiteness,
+        scaledBlackness
+      );
     }
-    this.alphaInternal = color.alpha;
-  }
 
-  /**
-   * Creates an RGB color.
-   *
-   * Throws an error if `red`, `green`, and `blue` aren't between `0` and `255`,
-   * or if `alpha` isn't between `0` and `1`.
-   */
-  static rgb(
-    red: number,
-    green: number,
-    blue: number,
-    alpha?: number
-  ): SassColor {
-    return new SassColor({
-      red: fuzzyAssertInRange(red, 0, 255, 'red'),
-      green: fuzzyAssertInRange(green, 0, 255, 'green'),
-      blue: fuzzyAssertInRange(blue, 0, 255, 'blue'),
-      alpha: alpha === undefined ? 1 : fuzzyAssertInRange(alpha, 0, 1, 'alpha'),
-    });
-  }
-
-  /**
-   * Creates an HSL color.
-   *
-   * Throws an error if `saturation` or `lightness` aren't between `0` and
-   * `100`, or if `alpha` isn't between `0` and `1`.
-   */
-  static hsl(
-    hue: number,
-    saturation: number,
-    lightness: number,
-    alpha?: number
-  ) {
-    return new SassColor({
-      hue: hue % 360,
-      saturation: fuzzyAssertInRange(saturation, 0, 100, 'saturation'),
-      lightness: fuzzyAssertInRange(lightness, 0, 100, 'lightness'),
-      alpha: alpha === undefined ? 1 : fuzzyAssertInRange(alpha, 0, 1, 'alpha'),
-    });
-  }
-
-  /**
-   * Creates an HWB color.
-   *
-   * Throws an error if `whiteness` or `blackness` aren't between `0` and `100`,
-   * or if `alpha` isn't between `0` and `1`.
-   */
-  static hwb(
-    hue: number,
-    whiteness: number,
-    blackness: number,
-    alpha?: number
-  ) {
-    // From https://www.w3.org/TR/css-color-4/#hwb-to-rgb
-    const scaledHue = (hue % 360) / 360;
-    let scaledWhiteness =
-      fuzzyAssertInRange(whiteness, 0, 100, 'whiteness') / 100;
-    let scaledBlackness =
-      fuzzyAssertInRange(blackness, 0, 100, 'blackness') / 100;
-
-    const sum = scaledWhiteness + scaledBlackness;
-    if (sum > 1) {
-      scaledWhiteness /= sum;
-      scaledBlackness /= sum;
-    }
-
-    const factor = 1 - scaledWhiteness - scaledBlackness;
-    function toRgb(hue: number) {
-      const channel = hueToRgb(0, 1, hue) * factor + scaledWhiteness;
-      return fuzzyRound(channel * 255);
-    }
-
-    // Because HWB is (currently) used much less frequently than HSL or RGB, we
-    // don't cache its values because we expect the memory overhead of doing so
-    // to outweigh the cost of recalculating it on access. Instead, we eagerly
-    // convert it to RGB and then convert back if necessary.
-    return SassColor.rgb(
-      toRgb(scaledHue + 1 / 3),
-      toRgb(scaledHue),
-      toRgb(scaledHue - 1 / 3),
-      alpha
-    );
+    this.alphaInternal =
+      color.alpha === undefined
+        ? 1
+        : fuzzyAssertInRange(color.alpha, 0, 1, 'alpha');
   }
 
   /** `this`'s red channel. */
@@ -202,67 +169,51 @@ export class SassColor extends Value {
   }
 
   /**
-   * Returns a copy of `this` with its RGB channels changed to `red`, `green`,
-   * `blue`, and/or `alpha`.
-   */
-  changeRgb(options: {
-    red?: number;
-    green?: number;
-    blue?: number;
-    alpha?: number;
-  }): SassColor {
-    return SassColor.rgb(
-      options.red ?? this.red,
-      options.green ?? this.green,
-      options.blue ?? this.blue,
-      options.alpha ?? this.alpha
-    );
-  }
-
-  /**
-   * Returns a copy of `this` with its HSL values changed to `hue`,
-   * `saturation`, `lightness`, and/or `alpha`.
-   */
-  changeHsl(options: {
-    hue?: number;
-    saturation?: number;
-    lightness?: number;
-    alpha?: number;
-  }): SassColor {
-    return SassColor.hsl(
-      options.hue ?? this.hue,
-      options.saturation ?? this.saturation,
-      options.lightness ?? this.lightness,
-      options.alpha ?? this.alpha
-    );
-  }
-
-  /**
-   * Returns a copy of `this` with its HWB values changed to `hue`, `whiteness`,
-   * `blackness`, and/or `alpha`.
+   * Returns a copy of `this` with its channels changed to match `color`.
    */
-  changeHwb(options: {
-    hue?: number;
-    whiteness?: number;
-    blackness?: number;
-    alpha?: number;
-  }): SassColor {
-    return SassColor.hwb(
-      options.hue ?? this.hue,
-      options.whiteness ?? this.whiteness,
-      options.blackness ?? this.blackness,
-      options.alpha ?? this.alpha
-    );
-  }
-
-  /** Returns a copy of `this` with its alpha channel changed to `alpha`. */
-  changeAlpha(alpha: number): SassColor {
-    return new SassColor({
-      red: this.red,
-      green: this.green,
-      blue: this.blue,
-      alpha: fuzzyAssertInRange(alpha, 0, 1, 'alpha'),
-    });
+  change(
+    color: Partial<RgbColor> | Partial<HslColor> | Partial<HwbColor>
+  ): SassColor {
+    if ('whiteness' in color || 'blackness' in color) {
+      return new SassColor({
+        hue: color.hue ?? this.hue,
+        whiteness: color.whiteness ?? this.whiteness,
+        blackness: color.blackness ?? this.blackness,
+        alpha: color.alpha ?? this.alpha,
+      });
+    } else if (
+      'hue' in color ||
+      'saturation' in color ||
+      'lightness' in color
+    ) {
+      // Tell TypeScript this isn't a Partial<HwbColor>.
+      const hsl = color as Partial<HslColor>;
+      return new SassColor({
+        hue: hsl.hue ?? this.hue,
+        saturation: hsl.saturation ?? this.saturation,
+        lightness: hsl.lightness ?? this.lightness,
+        alpha: hsl.alpha ?? this.alpha,
+      });
+    } else if (
+      'red' in color ||
+      'green' in color ||
+      'blue' in color ||
+      this.redInternal
+    ) {
+      return new SassColor({
+        red: color.red ?? this.red,
+        green: color.green ?? this.green,
+        blue: color.blue ?? this.blue,
+        alpha: color.alpha ?? this.alpha,
+      });
+    } else {
+      return new SassColor({
+        hue: this.hue,
+        saturation: this.saturation,
+        lightness: this.lightness,
+        alpha: color.alpha ?? this.alpha,
+      });
+    }
   }
 
   equals(other: Value): boolean {
@@ -344,6 +295,13 @@ export class SassColor extends Value {
   }
 }
 
+// A helper for converting HWB colors to RGB.
+function toRgb(hue: number, scaledWhiteness: number, scaledBlackness: number) {
+  const factor = 1 - scaledWhiteness - scaledBlackness;
+  const channel = hueToRgb(0, 1, hue) * factor + scaledWhiteness;
+  return fuzzyRound(channel * 255);
+}
+
 // An algorithm from the CSS3 spec: http://www.w3.org/TR/css3-color/#hsl-color.
 function hueToRgb(m1: number, m2: number, hue: number): number {
   if (hue < 0) hue += 1;

lib/src/value/list.ts

@@ -2,7 +2,7 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
-import {hash, List, OrderedMap} from 'immutable';
+import {hash, isList, List} from 'immutable';
 
 import {Value} from './value';
 import {SassMap} from './map';
@@ -15,6 +15,12 @@ export type ListSeparator = ',' | '/' | ' ' | null;
 // the value.
 const emptyListHashCode = hash([]);
 
+/** The options that are passed to the constructor. */
+interface ConstructorOptions {
+  separator?: ListSeparator;
+  brackets?: boolean;
+}
+
 /** A SassScript list. */
 export class SassList extends Value {
   private readonly contentsInternal: List<Value>;
@@ -26,14 +32,18 @@ export class SassList extends Value {
    * `brackets`.
    */
   constructor(
-    contents: Value[] | List<Value>,
-    options?: {
-      /** @default ',' */ separator?: ListSeparator;
-      /** @default false */ brackets?: boolean;
-    }
+    contentsOrOptions?: Value[] | List<Value> | ConstructorOptions,
+    options?: ConstructorOptions
   ) {
     super();
-    this.contentsInternal = asImmutableList(contents);
+
+    if (isList(contentsOrOptions) || Array.isArray(contentsOrOptions)) {
+      this.contentsInternal = asImmutableList(contentsOrOptions);
+    } else {
+      this.contentsInternal = List();
+      options = contentsOrOptions;
+    }
+
     if (this.contentsInternal.size > 1 && options?.separator === null) {
       throw Error(
         'Non-null separator required for SassList with more than one element.'
@@ -44,17 +54,6 @@ export class SassList extends Value {
     this.hasBracketsInternal = options?.brackets ?? false;
   }
 
-  /** Returns an empty list with the given `separator` and `brackets`. */
-  static empty(options?: {
-    /** @default null */ separator?: ListSeparator;
-    /** @default false */ brackets?: boolean;
-  }) {
-    return new SassList([], {
-      separator: options?.separator ?? null,
-      brackets: options?.brackets,
-    });
-  }
-
   get asList(): List<Value> {
     return this.contentsInternal;
   }
@@ -73,12 +72,16 @@ export class SassList extends Value {
     return this.contentsInternal.size;
   }
 
+  get(index: number): Value | undefined {
+    return this.contentsInternal.get(index);
+  }
+
   assertList(): SassList {
     return this;
   }
 
   assertMap(name?: string): SassMap {
-    if (this.contentsInternal.isEmpty()) return SassMap.empty();
+    if (this.contentsInternal.isEmpty()) return new SassMap();
     throw valueError(`${this} is not a map`, name);
   }
 
@@ -87,8 +90,8 @@ export class SassList extends Value {
    *
    * Otherwise, returns null.
    */
-  tryMap(): OrderedMap<Value, Value> | null {
-    return this.contentsInternal.isEmpty() ? OrderedMap<Value, Value>() : null;
+  tryMap(): SassMap | null {
+    return this.contentsInternal.isEmpty() ? new SassMap() : null;
   }
 
   equals(other: Value): boolean {