Refactor implementation and improve package resolution

- Compare algorithms with hsluv-javascript 1.0.2; no numerical changes needed
- Deduplicate public API functions via private _to-color() helper
- Refactor args-hsl into _normalize-hue and _normalize-percent helpers
- Mark internal conversion helpers as private with _ prefix
- Add package exports for modern Sass pkg: URL support
- Document CLI usage with --load-path and --pkg-importer options
- Refresh package-lock.json version to match package.json

Author: boronine-bot

README.md

@@ -41,6 +41,24 @@ Emitted css:
 }
 ```
 
+When compiling with the Sass CLI, make sure `node_modules` is in the load path:
+
+```sh
+sass --load-path=node_modules styles.scss styles.css
+```
+
+Or use the Node package importer with a `pkg:` URL:
+
+```scss
+@use "pkg:hsluv-sass" as hsluv;
+```
+
+```sh
+sass --pkg-importer=node styles.scss styles.css
+```
+
+Most build tools add `node_modules` to the Sass load path automatically.
+
 ### API
 
 ```scss

package-lock.json

@@ -3,8 +3,14 @@
   "version": "3.0.0-beta.1",
   "type": "module",
   "description": "HSLuv Sass - Human friendly HSL",
-  "main": "src/_hsluv.scss",
-  "sass": "src/_hsluv.scss",
+  "main": "index.scss",
+  "sass": "index.scss",
+  "exports": {
+    ".": {
+      "sass": "./index.scss",
+      "default": "./src/_hsluv.scss"
+    }
+  },
   "directories": {
     "test": "test"
   },

package.json

@@ -8,65 +8,71 @@
 @use "./conversions/rgb" as rgb;
 
 @function args-hsl($hue, $saturation, $lightness) {
-  $hsl: $hue;
-
-  @if ($saturation and $lightness) {
-    @if math.is-unitless($hue) {
-      $hue: $hue * 1deg;
-    }
-    @if math.unit($saturation) == "%" {
-      $saturation: math.div($saturation, 1%);
-    }
-    @if math.unit($lightness) == "%" {
-      $lightness: math.div($lightness, 1%);
-    }
-
-    $hsl: (
-      h: $hue,
-      s: $saturation,
-      l: $lightness,
+  @if $saturation and $lightness {
+    @return (
+      "h": _normalize-hue($hue),
+      "s": _normalize-percent($saturation),
+      "l": _normalize-percent($lightness)
     );
-  } @else if (meta.type-of($value: $hsl) != map) {
+  }
+
+  @if meta.type-of($hue) != map {
     @error "hsluv function with a single parameter must be called with a map of the form (h: $hue, s: $saturation, l: $lightness)";
-  } @else if not (map.get($hsl, h) and map.get($hsl, s) and map.get($hsl, l)) {
+  }
+
+  @if not
+    map.has-key($hue, "h") or not
+    map.has-key($hue, "s") or not
+    map.has-key($hue, "l")
+  {
     @error "hsluv function with a single parameter must be called with a map of the form (h: $hue, s: $saturation, l: $lightness)";
   }
 
-  @return $hsl;
+  @return $hue;
+}
+
+@function _normalize-hue($hue) {
+  @if math.is-unitless($hue) {
+    @return $hue * 1deg;
+  }
+  @return $hue;
+}
+
+@function _normalize-percent($value) {
+  @if math.unit($value) == "%" {
+    @return math.div($value, 1%);
+  }
+  @return $value;
 }
 
 @function hsluv-rgb($hsluv) {
   $lch: lch.from-hsluv($hsluv);
   $luv: luv.from-lch($lch);
   $xyz: xyz.from-luv($luv);
-  $rgb: rgb.from-xyz($xyz);
 
-  @return $rgb;
+  @return rgb.from-xyz($xyz);
 }
 
 @function hpluv-rgb($hpluv) {
   $lch: lch.from-hpluv($hpluv);
   $luv: luv.from-lch($lch);
   $xyz: xyz.from-luv($luv);
-  $rgb: rgb.from-xyz($xyz);
 
-  @return $rgb;
+  @return rgb.from-xyz($xyz);
 }
 
 @function rgb-hsluv($rgb) {
   $xyz: rgb.to-xyz($rgb);
   $luv: xyz.to-luv($xyz);
   $lch: luv.to-lch($luv);
-  $hsluv: lch.to-hsluv($lch);
 
-  @return $hsluv;
+  @return lch.to-hsluv($lch);
 }
 
 @function rgb-hpluv($rgb) {
   $xyz: rgb.to-xyz($rgb);
   $luv: xyz.to-luv($xyz);
   $lch: luv.to-lch($luv);
-  $hpluv: lch.to-hpluv($lch);
 
-  @return $hpluv;
+  @return lch.to-hpluv($lch);
 }

src/_conversions.scss

@@ -1,42 +1,42 @@
 @use "sass:map";
 
 @use "./conversions" as conv;
-@use "./conversions/xyz" as xyz;
 
-@function hsluv($hue, $saturation: null, $lightness: null) {
-  $hsluv: conv.args-hsl($hue, $saturation, $lightness);
-  $rgb: conv.hsluv-rgb($hsluv);
+// Convert an RGB map to a Sass color, optionally with alpha.
+@function _to-color($rgb, $alpha: 1) {
+  $r: map.get($rgb, "r");
+  $g: map.get($rgb, "g");
+  $b: map.get($rgb, "b");
+
+  @if $alpha == 1 {
+    @return rgb($r, $g, $b);
+  }
 
-  @return rgb(map.get($rgb, "r"), map.get($rgb, "g"), map.get($rgb, "b"));
+  @return rgba($r, $g, $b, $alpha);
 }
 
-@function hpluv($hue, $saturation: null, $lightness: null) {
-  $hpluv: conv.args-hsl($hue, $saturation, $lightness);
-  $rgb: conv.hpluv-rgb($hpluv);
+@function hsluv($hue, $saturation: null, $lightness: null) {
+  @return _to-color(
+    conv.hsluv-rgb(conv.args-hsl($hue, $saturation, $lightness))
+  );
+}
 
-  @return rgb(map.get($rgb, "r"), map.get($rgb, "g"), map.get($rgb, "b"));
+@function hpluv($hue, $saturation: null, $lightness: null) {
+  @return _to-color(
+    conv.hpluv-rgb(conv.args-hsl($hue, $saturation, $lightness))
+  );
 }
 
 @function hsluva($hue, $saturation: null, $lightness: null, $alpha: 1) {
-  $hsluv: conv.args-hsl($hue, $saturation, $lightness);
-  $rgb: conv.hsluv-rgb($hsluv);
-
-  @return rgba(
-    map.get($rgb, "r"),
-    map.get($rgb, "g"),
-    map.get($rgb, "b"),
+  @return _to-color(
+    conv.hsluv-rgb(conv.args-hsl($hue, $saturation, $lightness)),
     $alpha
   );
 }
 
 @function hpluva($hue, $saturation: null, $lightness: null, $alpha: 1) {
-  $hpluv: conv.args-hsl($hue, $saturation, $lightness);
-  $rgb: conv.hpluv-rgb($hpluv);
-
-  @return rgba(
-    map.get($rgb, "r"),
-    map.get($rgb, "g"),
-    map.get($rgb, "b"),
+  @return _to-color(
+    conv.hpluv-rgb(conv.args-hsl($hue, $saturation, $lightness)),
     $alpha
   );
 }

src/_hsluv.scss

@@ -12,7 +12,7 @@
   $c: 0;
   // white and black: disambiguate chroma
   @if not($l > 99.9999999 or $l < 0.00000001) {
-    $max: max-chroma-for-l-h($l, $h);
+    $max: _max-chroma-for-l-h($l, $h);
     $c: math.div($max, 100) * $s;
   }
 
@@ -27,7 +27,7 @@
   $c: 0;
   // white and black: disambiguate chroma
   @if not($l > 99.9999999 or $l < 0.00000001) {
-    $max: max-safe-chroma-for-l($l);
+    $max: _max-safe-chroma-for-l($l);
     $c: math.div($max, 100) * $s;
   }
   @return ("l": $l, "c": $c, "h": $h);
@@ -41,7 +41,7 @@
   $s: 0;
   // white and black: disambiguate saturation
   @if not($l > 99.9999999 or $l < 0.00000001) {
-    $max: max-chroma-for-l-h($l, $h);
+    $max: _max-chroma-for-l-h($l, $h);
     $s: math.div($c, $max) * 100;
   }
   @return ("h": $h, "s": $s, "l": $l);
@@ -55,24 +55,24 @@
   $s: 0;
   // white and black: disambiguate saturation
   @if not($l > 99.9999999 or $l < 0.00000001) {
-    $max: max-safe-chroma-for-l($l);
+    $max: _max-safe-chroma-for-l($l);
     $s: math.div($c, $max) * 100;
   }
   @return ("h": $h, "s": $s, "l": $l);
 }
 
 // For a given lightness and hue, return the maximum chroma that fits in
 // the RGB gamut.
-// @param {number[][2]} $l
+// @param {number} $l
 // @param {number} $h
 // @return {number}
-@function max-chroma-for-l-h($l, $h) {
+@function _max-chroma-for-l-h($l, $h) {
   $lengths: ();
 
-  @each $line in get-bounds($l) {
-    $l: length-of-ray-until-intersect($h, $line);
-    @if $l != null {
-      $lengths: list.append($lengths, $l);
+  @each $line in _get-bounds($l) {
+    $length: _length-of-ray-until-intersect($h, $line);
+    @if $length != null {
+      $lengths: list.append($lengths, $length);
     }
   }
 
@@ -82,17 +82,17 @@
 // For given lightness, returns the maximum chroma. Keeping the chroma value
 // below this number will ensure that for any hue, the color is within the RGB
 // gamut.
-// @param {number[][2]} $l
+// @param {number} $l
 // @return {number}
-@function max-safe-chroma-for-l($l) {
+@function _max-safe-chroma-for-l($l) {
   $lengths: ();
 
-  @each $point in get-bounds($l) {
+  @each $point in _get-bounds($l) {
     $m1: list.nth($point, 1);
     $b1: list.nth($point, 2);
-    // x where line intersects with perpendicular running though (0, 0)
-    $x: intersect-line-line(($m1, $b1), (math.div(-1, $m1), 0));
-    $lengths: list.append($lengths, distance-from-pole(($x, $b1 + $x * $m1)));
+    // x where line intersects with perpendicular running through (0, 0)
+    $x: _intersect-line-line(($m1, $b1), (math.div(-1, $m1), 0));
+    $lengths: list.append($lengths, _distance-from-pole(($x, $b1 + $x * $m1)));
   }
 
   @return math.min($lengths...);
@@ -103,18 +103,20 @@
 // push a value out of the RGB gamut
 // @param {number} $l
 // @return {number[][2]}
-@function get-bounds($l) {
+@function _get-bounds($l) {
   $sub1: math.div(math.pow($l + 16, 3), 1560896);
   $sub2: $sub1;
   @if $sub1 <= const.$epsilon {
     $sub2: math.div($l, const.$kappa);
   }
+
   $ret: ();
   @each $channel in (r, g, b) {
     $m_: map.get(const.$m, $channel);
     $m1: list.nth($m_, 1);
     $m2: list.nth($m_, 2);
     $m3: list.nth($m_, 3);
+
     @for $t from 0 through 1 {
       $top1: (284517 * $m1 - 94839 * $m3) * $sub2;
       $top2: (838422 * $m3 + 769860 * $m2 + 731718 * $m1) *
@@ -138,7 +140,7 @@
 // @param {number} $theta
 // @param {number[2]} $line
 // @return {number?}
-@function length-of-ray-until-intersect($theta, $line) {
+@function _length-of-ray-until-intersect($theta, $line) {
   // theta  -- angle of ray starting at (0, 0)
   // m, b   -- slope and intercept of line
   // x1, y1 -- coordinates of intersection
@@ -149,7 +151,6 @@
   // len * cos(theta)  = x1
   // len * sin(theta)  = y1
   //
-  //
   // b + m * (len * cos(theta)) = len * sin(theta)
   // b = len * sin(hrad) - m * len * cos(theta)
   // b = len * (sin(hrad) - m * cos(hrad))
@@ -167,7 +168,7 @@
 
 // @param {number[2]} $point
 // @return {number}
-@function distance-from-pole($point) {
+@function _distance-from-pole($point) {
   @return math.sqrt(
     math.pow(list.nth($point, 1), 2) + math.pow(list.nth($point, 2), 2)
   );
@@ -176,7 +177,7 @@
 // @param {number[2]} $line1
 // @param {number[2]} $line2
 // @return {number}
-@function intersect-line-line($line1, $line2) {
+@function _intersect-line-line($line1, $line2) {
   @return math.div(
     list.nth($line1, 2) - list.nth($line2, 2),
     list.nth($line2, 1) - list.nth($line1, 1)