@sardine/colour 2.4.0 → 4.0.0

package/dist/isDarkColour.d.ts

@@ -1,10 +1,10 @@
 import type { NamedCSSColour, WCAG } from "./types";
 /**
  * Evaluates if a colour is dark by measuring the contrast ratio against black and white.
- * It accepts CSS RGB colours, named CSS or hexadecimal.
+ * It accepts CSS RGB colours (including percentage values), named CSS or hexadecimal.
  *
  * If you know in advance the type of colour you want to evaluate consider using `isCSSNamedDarkColour`, `isCSSRGBDarkColour` or `isHexDarkColour` as they are smaller functions
- * @param {string | NamedCSSColour} colour - A colour value, ie: `hotpink`, `#333222` or `rgb(12,34,45)`
+ * @param {string | NamedCSSColour} colour - A colour value, ie: `hotpink`, `#333222`, `rgb(12,34,45)`, or `rgb(50%, 25%, 100%)`
  * @param {"WCAG2.1" | "WCAG3.0"} standard - Evaluate agains "WCAG2.1" or "WCAG3.0"
  * @returns {boolean} Returns `true`, `false` or `undefined` if name is not a valid CSS named colour
  */

package/dist/pickHexColourContrast.d.ts

@@ -4,5 +4,5 @@ type ColorArgs = {
     optionOneColour: string;
     optionTwoColour: string;
 };
-export declare const pickHexColourContrast: ({ backgroundColour, optionOneColour, optionTwoColour }: ColorArgs, standard: WCAG) => string;
+export declare const pickHexColourContrast: ({ backgroundColour, optionOneColour, optionTwoColour }: ColorArgs, standard: WCAG) => string | null;
 export {};

package/dist/sortHexColours.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Helper to parse hex and get HSV + alpha
+ * @param hex Hex color string
+ * @returns Object with hue, saturation, value, and alpha
+ */
+export declare function getColorInfo(hex: string): {
+    h: number;
+    s: number;
+    v: number;
+    a: number;
+} | null;
+/**
+ * Helper to get custom order for greyscale values
+ * @param v HSV value (brightness) from 0 to 1
+ * @returns Order priority: 0 for grey/other, 1 for black, 2 for white
+ */
+export declare function getGreyscaleOrder(v: number): number;
+/**
+ * Sorts an array of hex colours by hue, then by saturation.
+ * Colours with 0% saturation (greyscale) are shifted to the end.
+ * Fully transparent colours (alpha = 0) are placed at the very end.
+ * Accepts hex colours in #RRGGBB or #RRGGBBAA format.
+ * @param hexColours Array of hex colour strings
+ * @returns Sorted array of hex colour strings
+ */
+export declare function sortHexColours(hexColours: string[]): string[];

package/dist/types.d.ts

@@ -1,3 +1,14 @@
+/**
+ * The HSV colour model represents colours by describing the Hue, Saturation, and Value channels.
+ */
+export interface HSVColour {
+    /** A number between 0 and 360 to describe the Hue channel */
+    h: number;
+    /** A number between 0 and 1 to describe the Saturation channel */
+    s: number;
+    /** A number between 0 and 1 to describe the Value channel */
+    v: number;
+}
 /**
  * The RGB colour model represents a broad array of colours by describing the Red, Green and Blue channels.
  */
@@ -48,5 +59,5 @@ export type WCAG = "WCAG2.1" | "WCAG3.0";
 /**
  * Named list from https://developer.mozilla.org/en-US/docs/Web/CSS/named-color
  */
-export type NamedCSSColour = "aliceblue" | "antiquewhite" | "aqua" | "aquamarine" | "azure" | "beige" | "bisque" | "black" | "blanchedalmond" | "blue" | "blueviolet" | "brown" | "burlywood" | "cadetblue" | "chartreuse" | "chocolate" | "coral" | "cornflowerblue" | "cornsilk" | "crimson" | "cyan" | "darkblue" | "darkcyan" | "darkgoldenrod" | "darkgray" | "darkgreen" | "darkgrey" | "darkkhaki" | "darkmagenta" | "darkolivegreen" | "darkorange" | "darkorchid" | "darkred" | "darksalmon" | "darkseagreen" | "darkslateblue" | "darkslategray" | "darkslategrey" | "darkturquoise" | "darkviolet" | "deeppink" | "deepskyblue" | "dimgray" | "dimgrey" | "dodgerblue" | "firebrick" | "floralwhite" | "forestgreen" | "fuchsia" | "gainsboro" | "ghostwhite" | "gold" | "goldenrod" | "gray" | "green" | "greenyellow" | "grey" | "honeydew" | "hotpink" | "indianred" | "indigo" | "ivory" | "khaki" | "lavender" | "lavenderblush" | "lawngreen" | "lemonchiffon" | "lightblue" | "lightcoral" | "lightcyan" | "lightgoldenrodyellow" | "lightgray" | "lightgreen" | "lightgrey" | "lightpink" | "lightsalmon" | "lightseagreen" | "lightskyblue" | "lightslategray" | "lightslategrey" | "lightsteelblue" | "lightyellow" | "lime" | "limegreen" | "linen" | "magenta" | "maroon" | "mediumaquamarine" | "mediumblue" | "mediumorchid" | "mediumpurple" | "mediumseagreen" | "mediumslateblue" | "mediumspringgreen" | "mediumturquoise" | "mediumvioletred" | "midnightblue" | "mintcream" | "mistyrose" | "moccasin" | "navajowhite" | "navy" | "oldlace" | "olive" | "olivedrab" | "orangered" | "orchid" | "palegoldenrod" | "palegreen" | "paleturquoise" | "palevioletred" | "papayawhip" | "peachpuff" | "peru" | "pink" | "plum" | "powderblue" | "purple" | "red" | "rosybrown" | "royalblue" | "saddlebrown" | "salmon" | "sandybrown" | "seagreen" | "seashell" | "sienna" | "silver" | "skyblue" | "slateblue" | "slategray" | "slategrey" | "snow" | "springgreen" | "steelblue" | "tan" | "teal" | "thistle" | "tomato" | "transparent" | "turquoise" | "violet" | "wheat" | "white" | "whitesmoke" | "yellow" | "yellowgreen";
+export type NamedCSSColour = "aliceblue" | "antiquewhite" | "aqua" | "aquamarine" | "azure" | "beige" | "bisque" | "black" | "blanchedalmond" | "blue" | "blueviolet" | "brown" | "burlywood" | "cadetblue" | "chartreuse" | "chocolate" | "coral" | "cornflowerblue" | "cornsilk" | "crimson" | "cyan" | "darkblue" | "darkcyan" | "darkgoldenrod" | "darkgray" | "darkgreen" | "darkgrey" | "darkkhaki" | "darkmagenta" | "darkolivegreen" | "darkorange" | "darkorchid" | "darkred" | "darksalmon" | "darkseagreen" | "darkslateblue" | "darkslategray" | "darkslategrey" | "darkturquoise" | "darkviolet" | "deeppink" | "deepskyblue" | "dimgray" | "dimgrey" | "dodgerblue" | "firebrick" | "floralwhite" | "forestgreen" | "fuchsia" | "gainsboro" | "ghostwhite" | "gold" | "goldenrod" | "gray" | "green" | "greenyellow" | "grey" | "honeydew" | "hotpink" | "indianred" | "indigo" | "ivory" | "khaki" | "lavender" | "lavenderblush" | "lawngreen" | "lemonchiffon" | "lightblue" | "lightcoral" | "lightcyan" | "lightgoldenrodyellow" | "lightgray" | "lightgreen" | "lightgrey" | "lightpink" | "lightsalmon" | "lightseagreen" | "lightskyblue" | "lightslategray" | "lightslategrey" | "lightsteelblue" | "lightyellow" | "lime" | "limegreen" | "linen" | "magenta" | "maroon" | "mediumaquamarine" | "mediumblue" | "mediumorchid" | "mediumpurple" | "mediumseagreen" | "mediumslateblue" | "mediumspringgreen" | "mediumturquoise" | "mediumvioletred" | "midnightblue" | "mintcream" | "mistyrose" | "moccasin" | "navajowhite" | "navy" | "oldlace" | "olive" | "olivedrab" | "orange" | "orangered" | "orchid" | "palegoldenrod" | "palegreen" | "paleturquoise" | "palevioletred" | "papayawhip" | "peachpuff" | "peru" | "pink" | "plum" | "powderblue" | "purple" | "rebeccapurple" | "red" | "rosybrown" | "royalblue" | "saddlebrown" | "salmon" | "sandybrown" | "seagreen" | "seashell" | "sienna" | "silver" | "skyblue" | "slateblue" | "slategray" | "slategrey" | "snow" | "springgreen" | "steelblue" | "tan" | "teal" | "thistle" | "tomato" | "transparent" | "turquoise" | "violet" | "wheat" | "white" | "whitesmoke" | "yellow" | "yellowgreen";
 export type NamedCSSColours = Array<[NamedCSSColour, string]>;

package/dist/util/index.d.ts

@@ -15,15 +15,7 @@ export declare function deltaHue_d({ C1, C2, h1_d, h2_d }: HueHelper): number;
  * @param HueHelper param
  */
 export declare function meanHue_d({ C1, C2, h1_d, h2_d }: HueHelper): number;
-/**
- * Converts a number in degrees to radians
- * @param n Number in degrees to be converted
- */
 export declare const toRadians: (n: number) => number;
-/**
- * Calculates a recurring square root
- * @param n Input number
- */
 export declare const bigSquare: (n: number) => number;
 /**
  * Normalise black and white colorimetry as specified in IEC 61966-2-1
@@ -31,10 +23,6 @@ export declare const bigSquare: (n: number) => number;
  * @param rgbValue number to be normalised
  */
 export declare function linearRGB(rgbValue: number, WCAG21?: boolean): number;
-/**
- * The division of the f function domain into two parts was done to prevent an infinite slope at n = 0
- * @param n Number to be constrained
- */
 export declare function constrainLab(n: number): number;
 /**
  * Clamps a number between two values
@@ -44,3 +32,5 @@ export declare function constrainLab(n: number): number;
  * @returns {number} - A clamped value
  */
 export declare function clamp(value: number, min: number, max: number): number;
+/** MDN reference for CSS named colours — shared to avoid duplicating the URL string in the bundle */
+export declare const NAMED_CSS_COLOUR_URL = "https://developer.mozilla.org/en-US/docs/Web/CSS/named-color";

package/dist/util/regexers.d.ts

@@ -1,13 +1,7 @@
-/** Six digit Hexadecimal colour, ie: #12FF21 */
-export declare const hexRegex: RegExp;
-/** Eight digit Hexadecimal colour, ie: #12FF21BE */
-export declare const hexAlphaRegex: RegExp;
-/** Three digit Hexadecimal colour, ie: #FFF */
-export declare const shortHexRegex: RegExp;
-/** Four digit Hexadecimal colour, ie: #FFF4 */
-export declare const shortAlphaHexRegex: RegExp;
+/** Any valid hexadecimal colour: 3, 4, 6, or 8 hex digits after `#` */
+export declare const hexAnyRegex: RegExp;
 /**
- * Captures the folowing CSS RGB formats:
+ * Captures the following CSS RGB formats:
  * - `rgb(0,0,0)`
  * - `rgba(0, 0, 0, 0.4)`
  * - `rgba(0,0,0,50%)`
@@ -15,5 +9,8 @@ export declare const shortAlphaHexRegex: RegExp;
  * - `rgba(0 0 0 / 0.4)`
  * - `rgb(0 0 0 / 0.5)`
  * - `rgb(0 0 0 / 50%)`
+ * - `rgb(50%, 25%, 100%)`
+ * - `rgba(50%, 25%, 100%, 0.8)`
+ * - `rgba(50%, 25%, 100%, 80%)`
  */
 export declare const cssRGBARegex: RegExp;

package/package.json

@@ -1,59 +1,75 @@
 {
-  "name": "@sardine/colour",
-  "version": "2.4.0",
-  "description": "It does things to colours",
-  "type": "module",
-  "module": "./dist/index.mjs",
-  "main": "./dist/index.cjs",
-  "types": "./dist/index.d.ts",
-  "unpkg": "./dist/index.min.js",
-  "sideEffects": false,
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.mjs"
-    }
-  },
-  "scripts": {
-    "build": "npx vite build",
-    "test": "npx vitest run --coverage",
-    "types:emit": "npx tsc -p tsconfig.emit.json",
-    "types:check": "npx tsc --noEmit",
-    "static": "npx biome ci src"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/sardinedev/colour.git"
-  },
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "color",
-    "colour"
-  ],
-  "author": "Hugo Nogueira",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/sardinedev/colour/issues"
-  },
-  "homepage": "https://github.com/sardinedev/colour#readme",
-  "engines": {
-    "node": ">= 16"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "1.9.4",
-    "@changesets/cli": "^2.27.1",
-    "@tsconfig/node20": "^20.1.4",
-    "@tsconfig/strictest": "^2.0.5",
-    "@vitest/coverage-v8": "^2.0.0",
-    "lefthook": "^1.8.1",
-    "typescript": "^5.4.5",
-    "vite": "^6.0.0",
-    "vitest": "^2.0.0"
-  }
+	"name": "@sardine/colour",
+	"version": "4.0.0",
+	"description": "It does things to colours",
+	"type": "module",
+	"module": "./dist/index.mjs",
+	"main": "./dist/index.cjs",
+	"types": "./dist/index.d.ts",
+	"unpkg": "./dist/index.min.js",
+	"sideEffects": false,
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"require": "./dist/index.cjs",
+			"import": "./dist/index.mjs"
+		}
+	},
+	"scripts": {
+		"build": "npx vite build",
+		"test": "npx vitest run --coverage",
+		"types:emit": "npx tsc -p tsconfig.emit.json",
+		"types:check": "npx tsc --noEmit",
+		"static": "npx biome ci src",
+		"size": "size-limit"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/sardinedev/colour.git"
+	},
+	"files": [
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"color",
+		"colour"
+	],
+	"author": "Hugo Nogueira",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/sardinedev/colour/issues"
+	},
+	"homepage": "https://github.com/sardinedev/colour#readme",
+	"engines": {
+		"node": ">= 20"
+	},
+	"size-limit": [
+		{
+			"name": "ESM build",
+			"path": "dist/index.mjs",
+			"brotli": false
+		},
+		{
+			"name": "CJS build",
+			"path": "dist/index.cjs",
+			"brotli": false
+		}
+	],
+	"devDependencies": {
+		"@biomejs/biome": "2.4.10",
+		"@changesets/cli": "^2.27.1",
+		"@size-limit/preset-small-lib": "^12.0.0",
+		"@tsconfig/node24": "^24.0.0",
+		"@tsconfig/strictest": "^2.0.5",
+		"@types/node": "^24.10.13",
+		"@vitest/coverage-v8": "^4.0.0",
+		"lefthook": "^2.0.0",
+		"size-limit": "^12.0.0",
+		"typescript": "^5.4.5",
+		"vite": "^8.0.0",
+		"vitest": "^4.0.0"
+	}
 }