@rickosborne/hue 2025.2.16

package/README.md

@@ -0,0 +1,774 @@
+# @rickosborne/hue
+
+Basic color manipulation utilities built on  [@rickosborne/typical](https://www.npmjs.com/package/@rickosborne/typical) for types and [@rickosborne/guard](https://www.npmjs.com/package/@rickosborne/guard) for guards.
+## Usage
+
+Install via your favorite package manager.
+
+Each package supports CommonJS `require`, ESM `import`, and TypeScript usage.
+
+You also have a choice: barrel imports or direct imports.
+
+Barrel imports mean you're going to require/import everything from the same package-level namespace:
+
+```typescript
+// CommonJS
+const { isPlainObject, isListOf } = require("@rickosborne/guard");
+// ESM / TypeScript
+import { isPlainObject, isListOf } from "@rickosborne/guard";
+```
+
+Implications:
+
+- Nice and simple.
+- Your build system needs to do tree-shaking well ... or you'll end up adding the entire package even if you only import two functions.
+
+The other option is to use direct imports:
+
+```typescript
+// CommonJS
+const { isPlainObject } = require("@rickosborne/guard/is-object");
+const { isListOf } = require("@rickosborne/guard/is-list-of");
+// ESM / TypeScript
+import { isPlainObject } from "@rickosborne/guard/is-object.js";
+import { isListOf } from "@rickosborne/guard/is-list-of.js";
+```
+
+Implications:
+
+- You (probably) don't have to worry about tree-shaking as your build (likely) ends up with only the functions you need.
+
+If you're using a modern build system, there aren't any strong reasons to prefer one way over the other.
+It's really just down to your personal preference.
+
+### A quick note about file extensions
+
+Do you need to use file extensions?
+And if so, which extensions?
+
+Honestly ... this is a dumpster fire question.
+It really comes down to your own setup and configuration.
+
+Within each package itself:
+
+- The CommonJS files all have `.cjs` extensions.
+- The ESM files all have `.mjs` extensions.
+- Node subpath exports have been set up to send `.js` imports to the `.cjs` (via `require`) or `.mjs` (via `import`) files, depending on your setup.
+
+So, in theory, the only extension which _won't_ work would be `.ts` because the source isn't included.
+
+If you run into a problem with a particular configuration, file a GitHub issue with:
+
+- Your `tsconfig.json`'s `module`, `moduleResolution`, and `target` settings.
+- Your `package.json`'s `type` and `imports` settings.
+- An example of another package which imports correctly for you.
+
+## License
+
+This package is licensed as [CC-BY-NC-SA-4.0] unless otherwise noted.
+That is, Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.
+
+[CC-BY-NC-SA-4.0]: https://creativecommons.org/licenses/by-nc-sa/4.0/
+
+
+***
+
+## API
+
+### Classes
+
+#### Color
+
+<a id="api-color"></a>
+
+```typescript
+ class Color implements ColorParts 
+```
+
+#### ColorConversionError
+
+<a id="api-colorconversionerror"></a>
+
+```typescript
+ class ColorConversionError extends Error 
+```
+
+### Functions
+
+#### chroma01FromHSL
+
+<a id="api-chroma01fromhsl"></a>
+
+```typescript
+ function chroma01FromHSL(hsl: HSL | {
+    s: Real01;
+    l: Real01;
+}): Real01;
+```
+
+#### chroma01FromHSL
+
+<a id="api-chroma01fromhsl"></a>
+
+```typescript
+ function chroma01FromHSL(hsl: HSL | {
+    s: Real01;
+    l: Real01;
+} | undefined): Real01 | undefined;
+```
+
+#### chroma01FromHSV
+
+<a id="api-chroma01fromhsv"></a>
+
+```typescript
+ function chroma01FromHSV(hsv: HSV | {
+    s: Real01;
+    v: Real01;
+}): Real01;
+```
+
+#### chroma01FromHSV
+
+<a id="api-chroma01fromhsv"></a>
+
+```typescript
+ function chroma01FromHSV(hsv: HSV | {
+    s: Real01;
+    v: Real01;
+} | undefined): Real01 | undefined;
+```
+
+#### chroma01FromRGB
+
+<a id="api-chroma01fromrgb"></a>
+
+```typescript
+ function chroma01FromRGB(rgb: RGB255): Real01;
+```
+
+#### chroma01FromRGB
+
+<a id="api-chroma01fromrgb"></a>
+
+```typescript
+ function chroma01FromRGB(rgb: RGB255 | undefined): Real01 | undefined;
+```
+
+#### chroma01FromRGB01
+
+<a id="api-chroma01fromrgb01"></a>
+
+```typescript
+ function chroma01FromRGB01(rgb: RGB01): Real01;
+```
+
+Calculate the chroma value for the given RGB, producing a real number in the range [0,1].
+
+
+#### chroma01FromRGB01
+
+<a id="api-chroma01fromrgb01"></a>
+
+```typescript
+ function chroma01FromRGB01(rgb: RGB01 | undefined): Real01 | undefined;
+```
+
+#### colorComparatorBuilder
+
+<a id="api-colorcomparatorbuilder"></a>
+
+```typescript
+colorComparatorBuilder: <C extends object>(fnName: string, ...keys: (keyof UnbrandedNumbers<C>)[]) => Comparator<C | undefined>
+```
+
+Generator for color comparators, since they all follow the same pattern of working through number values. This sorts null values after defined ones.
+
+
+#### colorEqBuilder
+
+<a id="api-coloreqbuilder"></a>
+
+```typescript
+colorEqBuilder: <C extends object>(fnName: string, keys: (keyof UnbrandedNumbers<C>)[], defaultEpsilons: Record<keyof C, number>) => ColorCloseTo<C>
+```
+
+Generator for color equality functions, since they all follow the same pattern of iterating over keys and doing delta checks.
+
+
+#### colorFromCSS
+
+<a id="api-colorfromcss"></a>
+
+```typescript
+colorFromCSS: (text: string) => Color | undefined
+```
+
+Try to parse a CSS color expression. Does not support anything clever. Intended more for "I have colors in a config file" use-cases, and not "accept CSS typed in by Web users".
+
+
+#### cssFormatHSL
+
+<a id="api-cssformathsl"></a>
+
+```typescript
+cssFormatHSL: (hsl: HSL) => string
+```
+
+#### cssFormatHSV
+
+<a id="api-cssformathsv"></a>
+
+```typescript
+cssFormatHSV: (hsv: HSV) => string
+```
+
+#### cssFormatRGB
+
+<a id="api-cssformatrgb"></a>
+
+```typescript
+cssFormatRGB: (rgb: RGB255) => string
+```
+
+#### hexFromRGB
+
+<a id="api-hexfromrgb"></a>
+
+```typescript
+hexFromRGB: (rgb: RGB255, format?: "short" | "long") => string
+```
+
+#### hslFromHSV
+
+<a id="api-hslfromhsv"></a>
+
+```typescript
+ function hslFromHSV(hsv: HSV): HSL;
+```
+
+#### hslFromHSV
+
+<a id="api-hslfromhsv"></a>
+
+```typescript
+ function hslFromHSV(hsv: HSV | undefined): HSL | undefined;
+```
+
+#### hslFromRGB
+
+<a id="api-hslfromrgb"></a>
+
+```typescript
+ function hslFromRGB(rgb: RGB255): HSL;
+```
+
+#### hslFromRGB
+
+<a id="api-hslfromrgb"></a>
+
+```typescript
+ function hslFromRGB(rgb: RGB255 | undefined): HSL | undefined;
+```
+
+#### hslFromRGB01
+
+<a id="api-hslfromrgb01"></a>
+
+```typescript
+ function hslFromRGB01(rgba01: RGBA01): HSLA;
+```
+
+#### hslFromRGB01
+
+<a id="api-hslfromrgb01"></a>
+
+```typescript
+ function hslFromRGB01(rgb01: RGB01): HSL;
+```
+
+#### hslFromRGB01
+
+<a id="api-hslfromrgb01"></a>
+
+```typescript
+ function hslFromRGB01(rgb01: RGB01 | undefined): HSL | undefined;
+```
+
+#### hsvFromHSL
+
+<a id="api-hsvfromhsl"></a>
+
+```typescript
+ function hsvFromHSL(hsl: HSL): HSV;
+```
+
+#### hsvFromHSL
+
+<a id="api-hsvfromhsl"></a>
+
+```typescript
+ function hsvFromHSL(hsl: HSL | undefined): HSV | undefined;
+```
+
+#### hsvFromRGB
+
+<a id="api-hsvfromrgb"></a>
+
+```typescript
+ function hsvFromRGB(rgb: RGB255): HSV;
+```
+
+#### hsvFromRGB
+
+<a id="api-hsvfromrgb"></a>
+
+```typescript
+ function hsvFromRGB(rgb: RGB255 | undefined): HSV | undefined;
+```
+
+#### hue360FromRGB
+
+<a id="api-hue360fromrgb"></a>
+
+```typescript
+ function hue360FromRGB(rgb: RGB255, chroma01?: Real01 | undefined, max255?: Int255 | Real255 | undefined): Int360;
+```
+
+#### hue360FromRGB
+
+<a id="api-hue360fromrgb"></a>
+
+```typescript
+ function hue360FromRGB(rgb: RGB255 | undefined, chroma01?: Real01 | undefined, max255?: Int255 | Real255 | undefined): Int360 | undefined;
+```
+
+#### hue360FromRGB01
+
+<a id="api-hue360fromrgb01"></a>
+
+```typescript
+ function hue360FromRGB01(rgb01: RGB01, chroma01?: Real01 | undefined, max01?: Real01 | undefined): Int360;
+```
+
+#### hue360FromRGB01
+
+<a id="api-hue360fromrgb01"></a>
+
+```typescript
+ function hue360FromRGB01(rgb01: RGB01 | undefined, chroma01?: Real01 | undefined, max01?: Real01 | undefined): Int360 | undefined;
+```
+
+#### rgb01From255
+
+<a id="api-rgb01from255"></a>
+
+```typescript
+ function rgb01From255(rgb: RGB255): RGB01;
+```
+
+#### rgb01From255
+
+<a id="api-rgb01from255"></a>
+
+```typescript
+ function rgb01From255(rgb: RGB255 | undefined): RGB01 | undefined;
+```
+
+#### rgb01FromHueChromaMin
+
+<a id="api-rgb01fromhuechromamin"></a>
+
+```typescript
+rgb01FromHueChromaMin: (hue360: Int360, chroma01: Real01, min: Real01, alpha01: Real01 | undefined) => RGB01
+```
+
+#### rgb255From01
+
+<a id="api-rgb255from01"></a>
+
+```typescript
+ function rgb255From01(rgb: RGB01): RealRGB;
+```
+
+#### rgb255From01
+
+<a id="api-rgb255from01"></a>
+
+```typescript
+ function rgb255From01(rgb: RGB01 | undefined): RealRGB | undefined;
+```
+
+#### rgbFromHex
+
+<a id="api-rgbfromhex"></a>
+
+```typescript
+ function rgbFromHex(text: string, options?: ThrowOnError | undefined): IntRGB;
+```
+
+#### rgbFromHex
+
+<a id="api-rgbfromhex"></a>
+
+```typescript
+ function rgbFromHex(text: string | undefined, options: typeof NO_THROW): IntRGB | undefined;
+```
+
+#### rgbFromHSL
+
+<a id="api-rgbfromhsl"></a>
+
+```typescript
+ function rgbFromHSL(hsl: HSL): RGB01;
+```
+
+#### rgbFromHSL
+
+<a id="api-rgbfromhsl"></a>
+
+```typescript
+ function rgbFromHSL(hsl: HSL | undefined): RGB01 | undefined;
+```
+
+#### rgbFromHSV
+
+<a id="api-rgbfromhsv"></a>
+
+```typescript
+ function rgbFromHSV(hsv: HSV): RGB01;
+```
+
+#### rgbFromHSV
+
+<a id="api-rgbfromhsv"></a>
+
+```typescript
+ function rgbFromHSV(hsv: HSV | undefined): RGB01 | undefined;
+```
+
+#### rgbFromReal
+
+<a id="api-rgbfromreal"></a>
+
+```typescript
+ function rgbFromReal(real: RealRGBA): IntRGBA;
+```
+
+#### rgbFromReal
+
+<a id="api-rgbfromreal"></a>
+
+```typescript
+ function rgbFromReal(real: RealRGB): IntRGB;
+```
+
+#### rgbFromReal
+
+<a id="api-rgbfromreal"></a>
+
+```typescript
+ function rgbFromReal(real: RealRGB | undefined): IntRGB | undefined;
+```
+
+#### rgbIntFrom01
+
+<a id="api-rgbintfrom01"></a>
+
+```typescript
+ function rgbIntFrom01(rgba01: RGBA01): IntRGBA;
+```
+
+#### rgbIntFrom01
+
+<a id="api-rgbintfrom01"></a>
+
+```typescript
+ function rgbIntFrom01(rgb01: RGB01): IntRGB;
+```
+
+#### rgbIntFrom01
+
+<a id="api-rgbintfrom01"></a>
+
+```typescript
+ function rgbIntFrom01(rgb01: RGB01 | undefined): IntRGB | undefined;
+```
+
+#### toHSL
+
+<a id="api-tohsl"></a>
+
+```typescript
+ function toHSL(h360: number, s01: number, l01: number, a01: number): HSLA;
+```
+
+#### toHSL
+
+<a id="api-tohsl"></a>
+
+```typescript
+ function toHSL(h360: number, s01: number, l01: number, a01?: number | undefined): HSL;
+```
+
+#### toHSV
+
+<a id="api-tohsv"></a>
+
+```typescript
+ function toHSV(h360: number, s01: number, v01: number, a01: number): HSVA;
+```
+
+#### toHSV
+
+<a id="api-tohsv"></a>
+
+```typescript
+ function toHSV(h360: number, s01: number, v01: number, a01?: number | undefined): HSV;
+```
+
+#### toRGB
+
+<a id="api-torgb"></a>
+
+```typescript
+ function toRGB(r255: number, g255: number, b255: number, a255: number): RGBA255;
+```
+
+#### toRGB
+
+<a id="api-torgb"></a>
+
+```typescript
+ function toRGB(r255: number, g255: number, b255: number, a255?: number | undefined): RGB255;
+```
+
+### Interfaces
+
+#### ColorConversionErrorOptions
+
+<a id="api-colorconversionerroroptions"></a>
+
+```typescript
+export interface ColorConversionErrorOptions extends ErrorOptions 
+```
+
+#### ColorParts
+
+<a id="api-colorparts"></a>
+
+```typescript
+export interface ColorParts 
+```
+
+#### HSL
+
+<a id="api-hsl"></a>
+
+```typescript
+export interface HSL 
+```
+
+#### HSLA
+
+<a id="api-hsla"></a>
+
+```typescript
+export interface HSLA extends HSL 
+```
+
+#### HSV
+
+<a id="api-hsv"></a>
+
+```typescript
+export interface HSV 
+```
+
+#### HSVA
+
+<a id="api-hsva"></a>
+
+```typescript
+export interface HSVA extends HSV 
+```
+
+#### IntRGB
+
+<a id="api-intrgb"></a>
+
+```typescript
+export interface IntRGB 
+```
+
+A color with RGB values, and possibly an alpha. All values are integers in the range [0..255].
+
+
+#### IntRGBA
+
+<a id="api-intrgba"></a>
+
+```typescript
+export interface IntRGBA extends IntRGB 
+```
+
+A color with RGBA values. All values are integers in the range [0,255].
+
+
+#### RealRGB
+
+<a id="api-realrgb"></a>
+
+```typescript
+export interface RealRGB 
+```
+
+A color with RGB values, and possibly an alpha. All values are real numbers in the range [0,255].
+
+
+#### RealRGBA
+
+<a id="api-realrgba"></a>
+
+```typescript
+export interface RealRGBA extends RealRGB 
+```
+
+A color with RGBA values. All values are real numbers in the range [0,255].
+
+
+#### RGB01
+
+<a id="api-rgb01"></a>
+
+```typescript
+export interface RGB01 
+```
+
+A color with RGB values, and possibly an alpha. All values are real numbers in the range [0,1].
+
+
+#### RGBA01
+
+<a id="api-rgba01"></a>
+
+```typescript
+export interface RGBA01 extends RGB01 
+```
+
+### TypeAliases
+
+#### ColorCloseTo
+
+<a id="api-colorcloseto"></a>
+
+```typescript
+type ColorCloseTo<C extends object> = (a: C | undefined, b: C | undefined, epsilons?: Partial<Record<keyof C, number>> | undefined) => boolean;
+```
+
+A function which checks two colors for equivalence, within some tolerable margin of error.
+
+
+#### RGB255
+
+<a id="api-rgb255"></a>
+
+```typescript
+type RGB255 = IntRGB | RealRGB;
+```
+
+A color with RGB values, and possibly an alpha. All values are numbers in the range [0,255].
+
+
+#### RGBA255
+
+<a id="api-rgba255"></a>
+
+```typescript
+type RGBA255 = IntRGBA | RealRGBA;
+```
+
+#### UnbrandedNumbers
+
+<a id="api-unbrandednumbers"></a>
+
+```typescript
+type UnbrandedNumbers<C extends object> = {
+    [K in keyof C]: C[K] extends number ? Unbound<C[K]> : C[K];
+};
+```
+
+Remove the branding from number values, to make type operations less onerous for generics.
+
+
+#### UncheckedColorParts
+
+<a id="api-uncheckedcolorparts"></a>
+
+```typescript
+type UncheckedColorParts = {
+    [K in keyof ColorParts]?: number | undefined;
+};
+```
+
+Color parts which do not use branded numbers. Useful for tests or when you've already verified the values.
+
+
+### Variables
+
+#### COLOR_EPSILON
+
+<a id="api-color-epsilon"></a>
+
+```typescript
+COLOR_EPSILON = 0.0001
+```
+
+#### hslComparator
+
+<a id="api-hslcomparator"></a>
+
+```typescript
+hslComparator: import("../typical/comparator.js").Comparator<HSL | undefined>
+```
+
+#### hslEq
+
+<a id="api-hsleq"></a>
+
+```typescript
+hslEq: import("./color-comparator.js").ColorCloseTo<HSL>
+```
+
+#### hsvComparator
+
+<a id="api-hsvcomparator"></a>
+
+```typescript
+hsvComparator: import("../typical/comparator.js").Comparator<HSV | undefined>
+```
+
+#### hsvEq
+
+<a id="api-hsveq"></a>
+
+```typescript
+hsvEq: import("./color-comparator.js").ColorCloseTo<HSV>
+```
+
+#### rgbComparator
+
+<a id="api-rgbcomparator"></a>
+
+```typescript
+rgbComparator: import("../typical/comparator.js").Comparator<IntRGB | undefined>
+```
+
+#### rgbEq
+
+<a id="api-rgbeq"></a>
+
+```typescript
+rgbEq: import("./color-comparator.js").ColorCloseTo<RGB255 | RGB01>
+```
+