@edelstone/tints-and-shades 0.1.6 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @edelstone/tints-and-shades
 
-Deterministic tint and shade generator for 6-character hex colors.  
+Deterministic color toolkit for tints, shades, color-wheel relationships, hex normalization, and hex/RGB/HSL conversion.  
 Used internally by the [Tint & Shade Generator](https://maketintsandshades.com) and published here as a standalone API.
 
 ## Install
@@ -9,14 +9,48 @@ Used internally by the [Tint & Shade Generator](https://maketintsandshades.com)
 npm install @edelstone/tints-and-shades
 ```
 
+## Quick example
+
+```js
+import {
+  normalizeHex,
+  calculateTints,
+  calculateShades,
+  getComplementaryHex
+} from "@edelstone/tints-and-shades";
+
+const baseHex = normalizeHex("#3bf"); // "33bbff"
+if (!baseHex) throw new Error("Invalid color");
+
+const tints = calculateTints(baseHex, [0, 0.5, 1]);
+const shades = calculateShades(baseHex, [0, 0.5, 1]);
+const complementary = getComplementaryHex(baseHex);
+```
+
+```json
+{
+  "complementary": "ff7733",
+  "tints": [
+    { "hex": "33bbff", "ratio": 0, "percent": 0 },
+    { "hex": "99ddff", "ratio": 0.5, "percent": 50 },
+    { "hex": "ffffff", "ratio": 1, "percent": 100 }
+  ],
+  "shades": [
+    { "hex": "33bbff", "ratio": 0, "percent": 0 },
+    { "hex": "1a5e80", "ratio": 0.5, "percent": 50 },
+    { "hex": "000000", "ratio": 1, "percent": 100 }
+  ]
+}
+```
+
 ## API
 
+### Generation
+
 ```ts
 calculateTints(colorValue: string, steps?: number[]): ScaleColor[]
 calculateShades(colorValue: string, steps?: number[]): ScaleColor[]
-```
 
-```ts
 type ScaleColor = {
   hex: string;
   ratio: number;
@@ -24,83 +58,53 @@ type ScaleColor = {
 };
 ```
 
-### 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]`
+Default steps: `[0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]`
 
-If omitted, the default steps are:
+### Normalization
 
-```js
-[0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
+```ts
+normalizeHex(value: string): string | null
 ```
 
-## Returns
+Returns canonical 6-character lowercase hex without `#` (3-character hex is expanded), or `null` if invalid.
 
-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";
+### Relationships
 
-const tints = calculateTints("000000", [0, 0.5, 1]);
-const shades = calculateShades("ffffff", [0, 0.5, 1]);
+```ts
+getComplementaryHex(colorValue: string): string
+getSplitComplementaryHexes(colorValue: string): [string, string]
+getAnalogousHexes(colorValue: string): [string, string]
+getTriadicHexes(colorValue: string): [string, string]
 ```
 
-Tints output:
+Hue is rotated by standard offsets while preserving saturation and lightness.
 
-```json
-[
-  { "hex": "000000", "ratio": 0, "percent": 0 },
-  { "hex": "808080", "ratio": 0.5, "percent": 50 },
-  { "hex": "ffffff", "ratio": 1, "percent": 100 }
-]
-```
+### Conversions
 
-Shades output:
+```ts
+hexToRgb(colorValue: string): RGB
+rgbToHex(rgb: RGB): string
+rgbToHsl(rgb: RGB): HSL
+hslToRgb(hsl: HSL): RGB
+
+type RGB = {
+  red: number;
+  green: number;
+  blue: number;
+};
 
-```json
-[
-  { "hex": "ffffff", "ratio": 0, "percent": 0 },
-  { "hex": "808080", "ratio": 0.5, "percent": 50 },
-  { "hex": "000000", "ratio": 1, "percent": 100 }
-]
+type HSL = {
+  hue: number;
+  saturation: number;
+  lightness: number;
+};
 ```
 
-## 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
+Converts between hex, RGB, and HSL using deterministic channel clamping and standard HSL conversion math.
 
-- Calculation method and rationale available on the [Tint & Shade Generator docs](https://maketintsandshades.com/about/#calculation-method).
+## Validation rules
 
-## Development
-
-From repo root:
-
-```bash
-npm run build:api
-npm run test:api
-```
-
-From package directory:
-
-```bash
-npm run build
-npm run test
-```
+- Generation requires a 6-character hex string (no `#`) and finite numeric steps.
+- Relationship and conversion helpers accept valid 3- or 6-character hex (optional `#`).
+- `normalizeHex` returns `null` for invalid input.
+- Other helpers throw `TypeError` for invalid input.

package/dist/color.d.ts

@@ -0,0 +1,19 @@
+export type RGB = {
+    red: number;
+    green: number;
+    blue: number;
+};
+export type HSL = {
+    hue: number;
+    saturation: number;
+    lightness: number;
+};
+export declare const normalizeHex: (value: string) => string | null;
+export declare const hexToRgb: (colorValue: string) => RGB;
+export declare const rgbToHex: (rgb: RGB) => string;
+export declare const rgbToHsl: (rgb: RGB) => HSL;
+export declare const hslToRgb: ({ hue, saturation, lightness }: HSL) => RGB;
+export declare const getComplementaryHex: (colorValue: string) => string;
+export declare const getSplitComplementaryHexes: (colorValue: string) => [string, string];
+export declare const getAnalogousHexes: (colorValue: string) => [string, string];
+export declare const getTriadicHexes: (colorValue: string) => [string, string];

package/dist/color.js

@@ -0,0 +1,108 @@
+const HEX_3_RE = /^[0-9a-fA-F]{3}$/;
+const HEX_6_RE = /^[0-9a-fA-F]{6}$/;
+const clampChannel = (value) => Math.min(Math.max(Math.round(value), 0), 255);
+const toChannelHex = (value) => clampChannel(value).toString(16).padStart(2, "0");
+const normalizeHue = (value) => ((value % 360) + 360) % 360;
+const assertNormalizedHex = (value) => {
+    const normalized = normalizeHex(value);
+    if (!normalized) {
+        throw new TypeError("colorValue must be a valid 3- or 6-character hex string with optional '#'.");
+    }
+    return normalized;
+};
+export const normalizeHex = (value) => {
+    if (typeof value !== "string")
+        return null;
+    const stripped = value.trim().replace(/^#/, "").toLowerCase();
+    if (HEX_6_RE.test(stripped))
+        return stripped;
+    if (HEX_3_RE.test(stripped)) {
+        return stripped.split("").map((char) => char + char).join("");
+    }
+    return null;
+};
+export const hexToRgb = (colorValue) => {
+    const normalized = assertNormalizedHex(colorValue);
+    return {
+        red: parseInt(normalized.slice(0, 2), 16),
+        green: parseInt(normalized.slice(2, 4), 16),
+        blue: parseInt(normalized.slice(4, 6), 16)
+    };
+};
+export const rgbToHex = (rgb) => toChannelHex(rgb.red) + toChannelHex(rgb.green) + toChannelHex(rgb.blue);
+export const rgbToHsl = (rgb) => {
+    const r = clampChannel(rgb.red) / 255;
+    const g = clampChannel(rgb.green) / 255;
+    const b = clampChannel(rgb.blue) / 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    let hue = 0;
+    let saturation = 0;
+    const lightness = (max + min) / 2;
+    if (max !== min) {
+        const delta = max - min;
+        saturation = lightness > 0.5 ? delta / (2 - max - min) : delta / (max + min);
+        switch (max) {
+            case r:
+                hue = ((g - b) / delta + (g < b ? 6 : 0)) * 60;
+                break;
+            case g:
+                hue = ((b - r) / delta + 2) * 60;
+                break;
+            default:
+                hue = ((r - g) / delta + 4) * 60;
+                break;
+        }
+    }
+    return {
+        hue: normalizeHue(hue),
+        saturation,
+        lightness
+    };
+};
+const hueToRgb = (p, q, t) => {
+    let channel = t;
+    if (channel < 0)
+        channel += 1;
+    if (channel > 1)
+        channel -= 1;
+    if (channel < 1 / 6)
+        return p + (q - p) * 6 * channel;
+    if (channel < 1 / 2)
+        return q;
+    if (channel < 2 / 3)
+        return p + (q - p) * (2 / 3 - channel) * 6;
+    return p;
+};
+export const hslToRgb = ({ hue, saturation, lightness }) => {
+    const h = normalizeHue(hue) / 360;
+    const s = Math.min(Math.max(saturation, 0), 1);
+    const l = Math.min(Math.max(lightness, 0), 1);
+    if (s === 0) {
+        const value = clampChannel(l * 255);
+        return { red: value, green: value, blue: value };
+    }
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    return {
+        red: clampChannel(hueToRgb(p, q, h + 1 / 3) * 255),
+        green: clampChannel(hueToRgb(p, q, h) * 255),
+        blue: clampChannel(hueToRgb(p, q, h - 1 / 3) * 255)
+    };
+};
+const rotateHueHexes = (colorValue, offsets) => {
+    const normalized = assertNormalizedHex(colorValue);
+    const baseHsl = rgbToHsl(hexToRgb(normalized));
+    return offsets.map((offset) => {
+        const rgb = hslToRgb({
+            hue: normalizeHue(baseHsl.hue + offset),
+            saturation: baseHsl.saturation,
+            lightness: baseHsl.lightness
+        });
+        return rgbToHex(rgb);
+    });
+};
+export const getComplementaryHex = (colorValue) => rotateHueHexes(colorValue, [180])[0];
+export const getSplitComplementaryHexes = (colorValue) => rotateHueHexes(colorValue, [150, 210]);
+export const getAnalogousHexes = (colorValue) => rotateHueHexes(colorValue, [-30, 30]);
+export const getTriadicHexes = (colorValue) => rotateHueHexes(colorValue, [120, 240]);

package/dist/generator.js

@@ -1,17 +1,4 @@
-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);
+import { hexToRgb, rgbToHex } from "./color.js";
 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)) {
@@ -33,7 +20,7 @@ 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 color = hexToRgb(colorValue);
     const values = [];
     for (const ratio of stepRatios) {
         const rgb = mixFn(color, ratio);

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export { calculateTints, calculateShades } from "./generator.js";
 export type { ScaleColor } from "./generator.js";
+export { normalizeHex, hexToRgb, rgbToHex, rgbToHsl, hslToRgb, getComplementaryHex, getSplitComplementaryHexes, getAnalogousHexes, getTriadicHexes } from "./color.js";
+export type { RGB, HSL } from "./color.js";

package/dist/index.js

@@ -1 +1,2 @@
 export { calculateTints, calculateShades } from "./generator.js";
+export { normalizeHex, hexToRgb, rgbToHex, rgbToHsl, hslToRgb, getComplementaryHex, getSplitComplementaryHexes, getAnalogousHexes, getTriadicHexes } from "./color.js";

package/package.json

@@ -12,8 +12,8 @@
   "engines": {
     "node": ">=18"
   },
-  "version": "0.1.6",
-  "description": "Deterministic tint and shade generator for 6-character hex colors.",
+  "version": "0.2.0",
+  "description": "Deterministic color toolkit for tints, shades, color-wheel relationships, hex normalization, and hex/RGB/HSL conversion.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {