@edelstone/tints-and-shades 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @edelstone/tints-and-shades
+
+Deterministic tint and shade generator for 6-character hex colors.  
+Used internally by the [Tint & Shade Generator](https://maketintsandshades.com) and published as a standalone API.
+
+## Install
+
+```bash
+npm install @edelstone/tints-and-shades
+```
+
+## API
+
+```ts
+calculateTints(colorValue: string, steps?: number[]): ScaleColor[]
+calculateShades(colorValue: string, steps?: number[]): ScaleColor[]
+```
+
+```ts
+type ScaleColor = {
+  hex: string;
+  ratio: number;
+  percent: number;
+};
+```
+
+### Parameters
+
+- **colorValue**  
+  6-character hex string without `#`, e.g. `3b82f6`  
+  Must be a valid 6-character hex value.
+
+- **steps** (optional)  
+  Array of finite numeric mix ratios.  
+  Example: `[0, 0.1, 0.2, 0.3]`
+
+If omitted, the default steps are:
+
+```js
+[0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
+```
+
+## Returns
+
+An array of `ScaleColor` objects:
+
+- `hex`: 6-character hex string (without `#`)
+- `ratio`: numeric step ratio used for the mix
+- `percent`: `ratio` expressed as a percentage (rounded to 1 decimal)
+
+## Example
+
+```js
+import { calculateTints, calculateShades } 
+  from "@edelstone/tints-and-shades";
+
+const tints = calculateTints("000000", [0, 0.5, 1]);
+const shades = calculateShades("ffffff", [0, 0.5, 1]);
+```
+
+Tints output:
+
+```json
+[
+  { "hex": "000000", "ratio": 0, "percent": 0 },
+  { "hex": "808080", "ratio": 0.5, "percent": 50 },
+  { "hex": "ffffff", "ratio": 1, "percent": 100 }
+]
+```
+
+Shades output:
+
+```json
+[
+  { "hex": "ffffff", "ratio": 0, "percent": 0 },
+  { "hex": "808080", "ratio": 0.5, "percent": 50 },
+  { "hex": "000000", "ratio": 1, "percent": 100 }
+]
+```
+
+## Validation
+
+- `colorValue` must be a 6-character hex string (no `#`).
+- Invalid values throw a `TypeError`.
+- `steps` must be an array of finite numbers.
+- Invalid `steps` input throws a `TypeError`.
+
+## Learn More
+
+- Calculation method and rationale: [Tint & Shade Generator docs](https://maketintsandshades.com/about/#calculation-method)
+
+## Development
+
+From repo root:
+
+```bash
+npm run build:api
+npm run test:api
+```
+
+From package directory:
+
+```bash
+npm run build
+npm run test
+```

package/dist/generator.d.ts

@@ -0,0 +1,7 @@
+export type ScaleColor = {
+    hex: string;
+    ratio: number;
+    percent: number;
+};
+export declare const calculateShades: (colorValue: string, steps?: number[]) => ScaleColor[];
+export declare const calculateTints: (colorValue: string, steps?: number[]) => ScaleColor[];

package/dist/generator.js

@@ -0,0 +1,59 @@
+const pad = (number, length) => {
+    let str = number.toString();
+    while (str.length < length) {
+        str = "0" + str;
+    }
+    return str;
+};
+const hexToRGB = (colorValue) => ({
+    red: parseInt(colorValue.slice(0, 2), 16),
+    green: parseInt(colorValue.slice(2, 4), 16),
+    blue: parseInt(colorValue.slice(4, 6), 16)
+});
+const intToHex = (rgbint) => pad(Math.min(Math.max(Math.round(rgbint), 0), 255).toString(16), 2);
+const rgbToHex = (rgb) => intToHex(rgb.red) + intToHex(rgb.green) + intToHex(rgb.blue);
+const DEFAULT_STEPS = [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9];
+const validateColorValue = (colorValue) => {
+    if (typeof colorValue !== "string" || colorValue.length !== 6 || !/^[0-9a-fA-F]{6}$/.test(colorValue)) {
+        throw new TypeError("colorValue must be a 6-character hex string without '#'.");
+    }
+};
+const resolveSteps = (steps) => {
+    if (typeof steps === "undefined")
+        return DEFAULT_STEPS;
+    if (!Array.isArray(steps)) {
+        throw new TypeError("steps must be an array of numbers.");
+    }
+    if (!steps.every((step) => typeof step === "number" && Number.isFinite(step))) {
+        throw new TypeError("steps must be an array of numbers.");
+    }
+    return steps;
+};
+const mixChannel = (from, to, ratio) => from + (to - from) * ratio;
+const calculateScale = (colorValue, steps, mixFn) => {
+    validateColorValue(colorValue);
+    const stepRatios = resolveSteps(steps);
+    const color = hexToRGB(colorValue);
+    const values = [];
+    for (const ratio of stepRatios) {
+        const rgb = mixFn(color, ratio);
+        values.push({
+            hex: rgbToHex(rgb),
+            ratio,
+            percent: Number((ratio * 100).toFixed(1))
+        });
+    }
+    return values;
+};
+const rgbShade = (rgb, ratio) => ({
+    red: mixChannel(rgb.red, 0, ratio),
+    green: mixChannel(rgb.green, 0, ratio),
+    blue: mixChannel(rgb.blue, 0, ratio)
+});
+const rgbTint = (rgb, ratio) => ({
+    red: mixChannel(rgb.red, 255, ratio),
+    green: mixChannel(rgb.green, 255, ratio),
+    blue: mixChannel(rgb.blue, 255, ratio)
+});
+export const calculateShades = (colorValue, steps) => calculateScale(colorValue, steps, rgbShade);
+export const calculateTints = (colorValue, steps) => calculateScale(colorValue, steps, rgbTint);

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { calculateTints, calculateShades } from "./generator.js";
+export type { ScaleColor } from "./generator.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { calculateTints, calculateShades } from "./generator.js";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@edelstone/tints-and-shades",
+  "version": "0.1.0",
+  "description": "Core tint and shade calculation API used by tints-and-shades.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}