@pixel-forge/sass-utils 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Itay "Cipher" Leybovich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @pixel-forge/sass-utils
+
+Sass shorthands, mixins, and functions. No runtime JavaScript — this package
+ships source partials that you `@use` from your own stylesheets.
+
+Function docs live on the SCSS as SassDoc (`///` comments), the Sass equivalent
+of JSDoc. A later docs site can generate pages from those comments. `/* */` is
+not used — Sass would copy those into the consumer's CSS.
+
+## Install
+
+```bash
+npm i @pixel-forge/sass-utils
+```
+
+Requires a Dart Sass compiler (`sass` or `sass-embedded`, 1.71+ for the `pkg:`
+importer).
+
+## Import surface
+
+There is no compiled CSS and no `dist/`. npm publishes `src/`. The public
+surface is the `exports` map in `package.json` — one subpath per domain, each
+pointing at that domain's `_index.scss`. Extra files in the folder (for example
+`_number.scss`) are for `@forward` from `_index.scss`; they are not importable as
+their own subpaths.
+
+```scss
+@use 'pkg:@pixel-forge/sass-utils/assertion' as Assert;
+@use 'pkg:@pixel-forge/sass-utils/color' as Color;
+@use 'pkg:@pixel-forge/sass-utils/palette' as Palette;
+```
+
+| Subpath     | Exposes                                        |
+| ----------- | ---------------------------------------------- |
+| `assertion` | `assertColor`, `assertNumber`, `assertInteger` |
+| `color`     | `colorWithAlpha`                               |
+| `palette`   | `paletteBuilder`                               |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@pixel-forge/sass-utils",
+  "version": "0.1.0",
+  "description": "Sass shorthands, mixins, and functions for Pixel Forge.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pixel-forge/Pixel-Forge.git",
+    "directory": "packages/sass-utils"
+  },
+  "homepage": "https://github.com/pixel-forge/Pixel-Forge/tree/main/packages/sass-utils#readme",
+  "bugs": "https://github.com/pixel-forge/Pixel-Forge/issues",
+  "keywords": [
+    "sass",
+    "scss",
+    "mixins",
+    "functions",
+    "shorthands"
+  ],
+  "files": [
+    "src"
+  ],
+  "exports": {
+    "./assertion": {
+      "sass": "./src/assertion/_index.scss",
+      "default": "./src/assertion/_index.scss"
+    },
+    "./color": {
+      "sass": "./src/color/_index.scss",
+      "default": "./src/color/_index.scss"
+    },
+    "./palette": {
+      "sass": "./src/palette/_index.scss",
+      "default": "./src/palette/_index.scss"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "devDependencies": {
+    "sass": "^1.103.1"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/assertion/_index.scss

@@ -0,0 +1,73 @@
+@use 'sass:meta';
+@use 'sass:math';
+
+/// Returns `$value` if it is a color.
+///
+/// CSS named colors like `red` are colors. A quoted string or a number is not.
+///
+/// @param {*} $value - Candidate to check
+/// @return {Color} `$value` unchanged
+/// @throw if `meta.type-of($value)` is not `color`
+@function assertColor($value) {
+  @if meta.type-of($value) != 'color' {
+    @error 'Expected a color, got #{meta.type-of($value)}: #{$value}';
+  }
+  @return $value;
+}
+
+/// Returns `$value` if it is a number. `$min` and `$max` are inclusive bounds;
+/// omit a bound (or pass `null`) to leave that side open.
+///
+/// @param {*} $value - Candidate to check
+/// @param {Number | null} $min [null] - Inclusive lower bound
+/// @param {Number | null} $max [null] - Inclusive upper bound
+/// @return {Number} `$value` unchanged
+/// @throw if `$value` is not a number
+/// @throw if a provided bound is not a number
+/// @throw if `$value < $min` or `$value > $max`
+///
+/// @example scss
+///   assertNumber($n, $min: 0);
+///   assertNumber($n, $max: 100);
+///   assertNumber($alpha, 0, 1);
+@function assertNumber($value, $min: null, $max: null) {
+  @if meta.type-of($value) != 'number' {
+    @error 'Expected a number, got #{meta.type-of($value)}: #{$value}';
+  }
+
+  @if $min != null {
+    @if meta.type-of($min) != 'number' {
+      @error 'Expected minimum to be a number, got #{meta.type-of($min)}: #{$min}';
+    }
+
+    @if $value < $min {
+      @error 'Expected at least #{$min}, got #{$value}';
+    }
+  }
+
+  @if $max != null {
+    @if meta.type-of($max) != 'number' {
+      @error 'Expected maximum to be a number, got #{meta.type-of($max)}: #{$max}';
+    }
+
+    @if $value > $max {
+      @error 'Expected at most #{$max}, got #{$value}';
+    }
+  }
+
+  @return $value;
+}
+
+/// Returns `$value` if it is an integer. Non-numbers fail through `assertNumber`.
+///
+/// @param {*} $value - Candidate to check
+/// @return {Number} `$value` unchanged
+/// @throw if `$value` is not a number
+/// @throw if `$value` is not an integer
+@function assertInteger($value) {
+  $value: assertNumber($value);
+  @if $value != math.round($value) {
+    @error 'Expected an integer, got #{$value}';
+  }
+  @return $value;
+}

package/src/color/_index.scss

@@ -0,0 +1,22 @@
+@use 'sass:color';
+@use '../assertion' as Assert;
+
+/// Returns `$color` with its alpha set to `$alpha`. Channels are read in `rgb`
+/// space, so HSL (and other) inputs still produce an RGB result.
+///
+/// @param {Color} $color - Any Sass color
+/// @param {Number} $alpha [1] - Opacity in the inclusive `0–1` range
+/// @return {Color}
+/// @throw if `$color` is not a color
+/// @throw if `$alpha` is not a number in `0–1`
+///
+/// @example scss
+///   .overlay { color: colorWithAlpha(#000, 0.5); }
+@function colorWithAlpha($color, $alpha: 1) {
+  $color: Assert.assertColor($color);
+  $alpha: Assert.assertNumber($alpha, 0, 1);
+  $r: color.channel($color, 'red', $space: rgb);
+  $g: color.channel($color, 'green', $space: rgb);
+  $b: color.channel($color, 'blue', $space: rgb);
+  @return rgba($r, $g, $b, $alpha);
+}

package/src/palette/_index.scss

@@ -0,0 +1,32 @@
+@use 'sass:math';
+@use 'sass:color';
+@use 'sass:list';
+@use '../assertion' as Assert;
+
+/// Builds a list of successively lighter tints of `$baseColor`.
+///
+/// Index `0` is `$baseColor` unchanged. Each later index scales lightness by
+/// `i / $steps` toward white. The loop is `0` to `$steps` exclusive, so the
+/// list never includes a fully white step.
+///
+/// @param {Color} $baseColor - Color to tint
+/// @param {Number} $steps - Length of the list; integer `>= 1`
+/// @return {List} `$steps` colors
+/// @throw if `$baseColor` is not a color
+/// @throw if `$steps` is not an integer `>= 1`
+///
+/// @example scss
+///   $tints: paletteBuilder(#f00, 4);
+///   // red, rgb(100%, 25%, 25%), rgb(100%, 50%, 50%), rgb(100%, 75%, 75%)
+@function paletteBuilder($baseColor, $steps) {
+  $baseColor: Assert.assertColor($baseColor);
+  $steps: Assert.assertInteger($steps);
+  $steps: Assert.assertNumber($steps, $min: 1);
+  $colorList: ();
+  @for $i from 0 to $steps {
+    $lightness: math.percentage(math.div($i, $steps));
+    $newColor: color.scale($baseColor, $lightness: $lightness);
+    $colorList: list.append($colorList, $newColor);
+  }
+  @return $colorList;
+}