omni-color 0.1.0 → 0.1.1

package/README.md

@@ -805,22 +805,22 @@ new Color('#ff7f50').getHarmonyColors('TRIADIC').map((color) => color.toHex());
 
 #### `getColorSwatch(options?: ColorSwatchOptions): ColorSwatch`
 
-- <ins>Returns</ins> a [`ColorSwatch`](#types-color-swatch) of lighter and darker variants keyed `100`–`900`, reporting the anchored stop via `mainStop`. When `extended` is `true`, returns instead an [`ExtendedColorSwatch`](#types-extended-color-swatch) with half-steps `50`–`950` are added without moving the base color to a half-stop; otherwise, [`BaseColorSwatch`](#types-base-color-swatch).
+- <ins>Returns</ins> a [`ColorSwatch`](#types-color-swatch) of lighter and darker variants keyed `100`–`900`, reporting the base shade via `baseShade`. When `extended` is `true`, returns instead an [`ExtendedColorSwatch`](#types-extended-color-swatch) with half-shades `50`–`950` added without moving the base color to a half-shade; otherwise, [`BaseColorSwatch`](#types-base-color-swatch).
 - <ins>Inputs</ins>:
   - `options` (optional) - `ColorSwatchOptions`:
-    - `centerOn500` - force the original color onto the `500` stop instead of dynamically anchoring by lightness (default is `false`).
-    - `extended` - set to `true` to include midpoint stops `50`–`950` and return an [`ExtendedColorSwatch`](#types-extended-color-swatch). Defaults to `false` (basic stops only).
+    - `centerOn500` - force the original color onto the `500` shade instead of dynamically anchoring by lightness (default is `false`).
+    - `extended` - set to `true` to include midpoint shades `50`–`950` and return an [`ExtendedColorSwatch`](#types-extended-color-swatch). Defaults to `false` (base shades only).
 
 ```ts
 const green = new Color('green');
 const swatch = green.getColorSwatch({ centerOn500: true });
-swatch.mainStop; // 500
+swatch.baseShade; // 500
 swatch[500].equals(green); // true
 swatch[100].toHex(); // lightest
 swatch[900].toHex(); // darkest
 
 const extendedSwatch = new Color('#008000').getColorSwatch({ extended: true });
-extendedSwatch.mainStop; // 700
+extendedSwatch.baseShade; // 700
 extendedSwatch[700].equals('#008000'); // true
 extendedSwatch[50].toHex(); // lightest
 extendedSwatch[500].toHex(); // middle
@@ -829,7 +829,9 @@ extendedSwatch[950].toHex(); // darkest
 
 #### `getColorPalette(harmony = 'COMPLEMENTARY', options?: GenerateColorPaletteOptions): ColorPalette`
 
-- <ins>Returns</ins> a complete [`ColorPalette`](#types-color-palette) containing the primary swatch, secondary swatches from the chosen harmony, neutral/tinted neutrals, and semantic swatches (`info`, `positive`, `negative`, `warning`, `special`).
+- <ins>Returns</ins> a complete [`ColorPalette`](#types-color-palette) containing the primary swatch, secondary swatches from the chosen harmony, neutral/tinted neutrals, secondary tinted neutrals, and semantic swatches (`info`, `positive`, `negative`, `warning`, `special`).
+- `palette.tintedNeutrals` is tinted toward the main color.
+- `palette.secondaryTintedNeutrals` is an array of tinted neutral swatches for the secondary colors. It always matches `palette.secondaryColors` by index: `palette.secondaryTintedNeutrals[0]` is for `palette.secondaryColors[0]`, `palette.secondaryTintedNeutrals[1]` is for `palette.secondaryColors[1]`, and so on.
 - <ins>Inputs</ins>:
   - `harmony` (optional) - [`ColorHarmony`](#types-color-harmony) used to generate secondary colors (defaults to `'COMPLEMENTARY'`).
   - `options` (optional) - `GenerateColorPaletteOptions`:
@@ -843,7 +845,9 @@ const palette = new Color('#ff7f50').getColorPalette('ANALOGOUS', {
   semanticHarmonization: { huePull: 0.35 },
   swatchOptions: { centerOn500: false },
 });
-palette.info[500].toHex(); // '#9d40d4'
+palette.info[500].toHex(); // '#9d3fd3'
+palette.secondaryColors[0][500].toHex(); // '#f92354'
+palette.secondaryTintedNeutrals[0][500].toHex(); // '#8c7d7f' - for secondaryColors[0]
 ```
 
 ### Readability and Accessibility
@@ -1001,10 +1005,12 @@ bestSwatchBackground.toHex(); // '#301308'
   - <span id="types-color-oklch">`ColorOKLCH`</span> - OKLCH color space with lightness, chroma, and hue. `{ l: number; c: number; h: number }` where `l` is a number between 0 and 1 (lightness), `c` is a number representing chroma (typically 0–0.4), and `h` is a number between 0 and 360 (hue in degrees).
 - <span id="types-color-space">`ColorSpace`</span> - supported color spaces for `Color.toColorString()`: `"SRGB" | "DISPLAY-P3" | "REC2020"`.
 - <span id="types-color-temperature-label">`ColorTemperatureLabel`</span> - color temperature options: `"Candlelight" | "Incandescent lamp" | "Halogen lamp" | "Fluorescent lamp" | "Daylight" | "Cloudy sky" | "Shade" | "Blue sky"`
-- <span id="types-base-color-swatch">`BaseColorSwatch`</span> - a swatch representing shades of the same color from 100 to 900 `{ 100: number; 200 number; ... 900: number }` where `100` is the lightest shade and `900` is the darkest shade.
-- <span id="types-extended-color-swatch">`ExtendedColorSwatch`</span> - same as a [`ColorSwatch`](#types-color-swatch) but includes half-shades at 50, 100, 150, ..., 950. It is a superset of [`ColorSwatch`](#types-color-swatch).
+- <span id="types-base-color-swatch-shade">`BaseColorSwatchShade`</span> - a base swatch shade key: `100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900`.
+- <span id="types-extended-color-swatch-shade">`ExtendedColorSwatchShade`</span> - an extended swatch shade key: [`BaseColorSwatchShade`](#types-base-color-swatch-shade) plus `50 | 150 | 250 | 350 | 450 | 550 | 650 | 750 | 850 | 950`.
+- <span id="types-base-color-swatch">`BaseColorSwatch`</span> - a swatch representing shades of the same color from 100 to 900 with `baseShade` identifying the original color shade. `100` is the lightest shade and `900` is the darkest shade.
+- <span id="types-extended-color-swatch">`ExtendedColorSwatch`</span> - same as a [`BaseColorSwatch`](#types-base-color-swatch) but includes half-shades at 50, 100, 150, ..., 950.
 - <span id="types-color-swatch">`ColorSwatch`</span> - `BaseColorSwatch | ExtendedColorSwatch`.
-- <span id="types-color-palette">`ColorPalette`</span> - a collection of [`ColorSwatch`](#types-color-swatch)es representing a color palette for a specified [`ColorHarmony`](#types-color-harmony). Includes a `primary` swatch for the main (base) color, `secondaryColors` swatches depending on the color harmony, and swatches for `neutrals`, `tintedNeutrals` (neutrals slightly tinted towards the main color), and swatches for semantic colors `info`, `negative`, `positive`, `special`, and `warning`.
+- <span id="types-color-palette">`ColorPalette`</span> - a collection of [`ColorSwatch`](#types-color-swatch)es representing a color palette for a specified [`ColorHarmony`](#types-color-harmony). Includes a `primary` swatch for the main (base) color, `secondaryColors` swatches depending on the color harmony, swatches for `neutrals`, `tintedNeutrals` (neutrals slightly tinted toward the main color), `secondaryTintedNeutrals` (an array of tinted neutral swatches that matches `secondaryColors` by index), and swatches for semantic colors `info`, `negative`, `positive`, `special`, and `warning`.
 - <span id="types-color-harmony">`ColorHarmony`</span> - a type of color harmony to generate [`ColorPalette`](#types-color-palette): `"COMPLEMENTARY" | "SPLIT_COMPLEMENTARY" | "TRIADIC" | "SQUARE" | "TETRADIC" | "ANALOGOUS" | "MONOCHROMATIC"`
 - <span id="types-grayscale-handling-mode">`GrayscaleHandlingMode`</span> - how hue rotations handle grayscale inputs: `"SPIN_LIGHTNESS" | "IGNORE"`.
 

package/dist/index.d.ts

@@ -1,5 +1,70 @@
 type CaseInsensitive<T extends string> = T | Lowercase<T> | Uppercase<T> | Capitalize<Lowercase<T>>;
 
+type ColorHex = `#${string}`;
+interface ColorRGB {
+    r: number;
+    g: number;
+    b: number;
+}
+interface ColorRGBA extends ColorRGB {
+    a: number;
+}
+interface ColorHSL {
+    h: number;
+    s: number;
+    l: number;
+}
+interface ColorHSLA extends ColorHSL {
+    a: number;
+}
+interface ColorHSV {
+    h: number;
+    s: number;
+    v: number;
+}
+interface ColorHSVA extends ColorHSV {
+    a: number;
+}
+interface ColorHWB {
+    h: number;
+    w: number;
+    b: number;
+}
+interface ColorHWBA extends ColorHWB {
+    a: number;
+}
+interface ColorCMYK {
+    c: number;
+    m: number;
+    y: number;
+    k: number;
+}
+interface ColorLAB {
+    l: number;
+    a: number;
+    b: number;
+    format?: CaseInsensitive<'LAB'>;
+}
+interface ColorOKLAB {
+    l: number;
+    a: number;
+    b: number;
+    format?: CaseInsensitive<'OKLAB'>;
+}
+interface ColorLCH {
+    l: number;
+    c: number;
+    h: number;
+    format?: CaseInsensitive<'LCH'>;
+}
+interface ColorOKLCH {
+    l: number;
+    c: number;
+    h: number;
+    format?: CaseInsensitive<'OKLCH'>;
+}
+type ColorFormat = ColorHex | ColorRGB | ColorRGBA | ColorHSL | ColorHSLA | ColorHSV | ColorHSVA | ColorHWB | ColorHWBA | ColorCMYK | ColorLAB | ColorOKLAB | ColorLCH | ColorOKLCH;
+
 declare const GRAYSCALE_HANDLING_MODES: readonly ["SPIN_LIGHTNESS", "IGNORE"];
 type GrayscaleHandlingMode = (typeof GRAYSCALE_HANDLING_MODES)[number];
 declare const COLOR_HARMONIES: readonly ["COMPLEMENTARY", "SPLIT_COMPLEMENTARY", "TRIADIC", "SQUARE", "TETRADIC", "ANALOGOUS", "MONOCHROMATIC"];
@@ -7,9 +72,22 @@ type ColorHarmony = (typeof COLOR_HARMONIES)[number];
 interface ColorHarmonyOptions {
     grayscaleHandlingMode?: CaseInsensitive<GrayscaleHandlingMode>;
 }
+type TetradicHarmonyDirection = 'CLOCKWISE' | 'COUNTERCLOCKWISE';
+interface TetradicHarmonyOptions extends ColorHarmonyOptions {
+    /**
+     * Direction used for tetradic hue spins.
+     *
+     * - CLOCKWISE: +60, +180, +240
+     * - COUNTERCLOCKWISE: -60, -180, -240
+     *
+     * Defaults to CLOCKWISE.
+     */
+    direction?: CaseInsensitive<TetradicHarmonyDirection>;
+}
 
-type BasicColorSwatchStop = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
-interface BaseColorSwatchStops {
+type BaseColorSwatchShade = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+type ExtendedColorSwatchShade = BaseColorSwatchShade | 50 | 150 | 250 | 350 | 450 | 550 | 650 | 750 | 850 | 950;
+interface BaseColorSwatchShades {
     100: Color;
     200: Color;
     300: Color;
@@ -20,11 +98,11 @@ interface BaseColorSwatchStops {
     800: Color;
     900: Color;
 }
-interface BaseColorSwatch extends BaseColorSwatchStops {
-    type: 'BASIC';
-    mainStop: BasicColorSwatchStop;
+interface BaseColorSwatch extends BaseColorSwatchShades {
+    type: 'BASE';
+    baseShade: BaseColorSwatchShade;
 }
-interface ExtendedColorSwatchStops extends BaseColorSwatchStops {
+interface ExtendedColorSwatchShades extends BaseColorSwatchShades {
     50: Color;
     150: Color;
     250: Color;
@@ -36,28 +114,40 @@ interface ExtendedColorSwatchStops extends BaseColorSwatchStops {
     850: Color;
     950: Color;
 }
-interface ExtendedColorSwatch extends ExtendedColorSwatchStops {
+interface ExtendedColorSwatch extends ExtendedColorSwatchShades {
     type: 'EXTENDED';
-    mainStop: BasicColorSwatchStop;
+    baseShade: BaseColorSwatchShade;
 }
 type ColorSwatch = BaseColorSwatch | ExtendedColorSwatch;
 interface ColorSwatchOptions {
     /**
-     * Include half-stops (`50`, `150`, …, `950`) interpolated between the base swatch stops.
+     * Include half-shades (`50`, `150`, …, `950`) interpolated between the base swatch shades.
      */
     extended?: boolean;
     /**
-     * Center the provided color on the 500 swatch stop instead of positioning it dynamically.
+     * Center the provided color on the 500 swatch shade instead of positioning it dynamically.
      */
     centerOn500?: boolean;
 }
 
 interface ColorPalette {
+    /** The main color's swatch. */
     primary: ColorSwatch;
+    /** Swatches generated from the selected harmony, excluding the main color. */
     secondaryColors: ColorSwatch[];
+    /** Neutral swatch harmonized to the main color's lightness. */
     neutrals: ColorSwatch;
+    /** Neutral swatch harmonized to the main color's lightness and slightly tinted toward the main color. */
     tintedNeutrals: ColorSwatch;
-    back: Color;
+    /**
+     * Tinted neutral swatches for each secondary color.
+     *
+     * This array always matches `secondaryColors` by index: `secondaryTintedNeutrals[0]`
+     * is the tinted neutral swatch for `secondaryColors[0]`, `secondaryTintedNeutrals[1]`
+     * is the tinted neutral swatch for `secondaryColors[1]`, and so on.
+     */
+    secondaryTintedNeutrals: ColorSwatch[];
+    black: Color;
     white: Color;
     info: ColorSwatch;
     negative: ColorSwatch;
@@ -79,76 +169,6 @@ interface GenerateColorPaletteOptions {
     swatchOptions?: ColorSwatchOptions;
 }
 
-declare const COLOR_BRAND: unique symbol;
-interface ColorBrand {
-    readonly [COLOR_BRAND]: true;
-}
-
-type ColorHex = `#${string}`;
-interface ColorRGB {
-    r: number;
-    g: number;
-    b: number;
-}
-interface ColorRGBA extends ColorRGB {
-    a: number;
-}
-interface ColorHSL {
-    h: number;
-    s: number;
-    l: number;
-}
-interface ColorHSLA extends ColorHSL {
-    a: number;
-}
-interface ColorHSV {
-    h: number;
-    s: number;
-    v: number;
-}
-interface ColorHSVA extends ColorHSV {
-    a: number;
-}
-interface ColorHWB {
-    h: number;
-    w: number;
-    b: number;
-}
-interface ColorHWBA extends ColorHWB {
-    a: number;
-}
-interface ColorCMYK {
-    c: number;
-    m: number;
-    y: number;
-    k: number;
-}
-interface ColorLAB {
-    l: number;
-    a: number;
-    b: number;
-    format?: CaseInsensitive<'LAB'>;
-}
-interface ColorOKLAB {
-    l: number;
-    a: number;
-    b: number;
-    format?: CaseInsensitive<'OKLAB'>;
-}
-interface ColorLCH {
-    l: number;
-    c: number;
-    h: number;
-    format?: CaseInsensitive<'LCH'>;
-}
-interface ColorOKLCH {
-    l: number;
-    c: number;
-    h: number;
-    format?: CaseInsensitive<'OKLCH'>;
-}
-type ColorFormat = ColorHex | ColorRGB | ColorRGBA | ColorHSL | ColorHSLA | ColorHSV | ColorHSVA | ColorHWB | ColorHWBA | ColorCMYK | ColorLAB | ColorOKLAB | ColorLCH | ColorOKLCH;
-
 type ColorSpace = 'SRGB' | 'DISPLAY-P3' | 'REC2020';
 interface ColorStringOptions {
     space?: CaseInsensitive<ColorSpace>;
@@ -459,6 +479,10 @@ interface IsColorDarkYIQOptions {
 }
 type IsColorDarkOptions = IsColorDarkWCAGOptions | IsColorDarkYIQOptions;
 
+declare const COLOR_BRAND: unique symbol;
+interface ColorBrand {
+    readonly [COLOR_BRAND]: true;
+}
 type ValidColorInputFormat = Color | ColorFormat | string;
 /**
  * The base omni-color object.
@@ -907,7 +931,7 @@ declare class Color implements ColorBrand {
      * d.toHex(); // '#0000ff'
      * ```
      */
-    getTetradicHarmonyColors(options?: ColorHarmonyOptions): [Color, Color, Color, Color];
+    getTetradicHarmonyColors(options?: TetradicHarmonyOptions): [Color, Color, Color, Color];
     /**
      * Get the analogous harmony for the color. These are colors adjacent to
      * the base hue, offering subtle contrast.
@@ -958,26 +982,26 @@ declare class Color implements ColorBrand {
     /**
      * Returns a {@link ColorSwatch} of lighter and darker variants of the color. The
      * swatch has keys `100`–`900` and, by default, anchors the original color on the
-     * stop that best matches its lightness (reported via the `mainStop` property).
+     * shade that best matches its lightness (reported via the `baseShade` property).
      * Lower numbers are lighter and higher numbers are darker, with black and white
      * always centered on `500`. Passing `{ centerOn500: true }` forces the original
-     * color onto the `500` stop regardless of its brightness. Passing
-     * `{ extended: true }` adds midpoint stops (`50`, `150`, `250`, ... `950`) that
+     * color onto the `500` shade regardless of its brightness. Passing
+     * `{ extended: true }` adds midpoint shades (`50`, `150`, `250`, ... `950`) that
      * are interpolated between the base swatch colors while still anchoring the
-     * base color on a `100`–`900` stop.
+     * base color on a `100`–`900` shade.
      *
-     * @param options - Optional {@link ColorSwatchOptions} for requesting the extended swatch or customizing the anchor stop.
+     * @param options - Optional {@link ColorSwatchOptions} for requesting the extended swatch or customizing the base shade.
      * @returns A {@link ColorSwatch} containing lighter and darker {@link Color}s ranging from lightest to darkest.
      *
      * @example
      * ```ts
      * const swatch = new Color('#ff0000').getColorSwatch();
-     * swatch.mainStop; // e.g. 500
+     * swatch.baseShade; // e.g. 500
      * const light = swatch[100]; // lightest shade
      * const dark = swatch[900];  // darkest shade
      *
      * const extendedSwatch = new Color('#ff0000').getColorSwatch({ extended: true, centerOn500: true });
-     * extendedSwatch.mainStop; // 500
+     * extendedSwatch.baseShade; // 500
      * const midLight = extendedSwatch[150]; // halfway between 100 and 200
      * const darkest = extendedSwatch[950];  // darker than 900
      * ```
@@ -1230,4 +1254,4 @@ declare class Color implements ColorBrand {
     clone(): Color;
 }
 
-export { type APCAReadabilityOptions, type APCAReadabilityPolicy, type APCAReadabilityReport, type APCAThresholdPreset, type AverageColorsOptions, type BaseColorName, type BlendColorsOptions, type BlendMode, type BlendSpace, type CIE94Options, type CIEDE2000Options, Color, type ColorBrightnessOptions, type ColorBrightnessSpace, type ColorCMYK, type ColorDarknessMode, type ColorFormat, type ColorGradientEasing, type ColorGradientInterpolation, type ColorGradientOptions, type ColorGradientSpace, type ColorHSL, type ColorHSLA, type ColorHSV, type ColorHSVA, type ColorHWB, type ColorHWBA, type ColorHarmony, type ColorHarmonyOptions, type ColorHex, type ColorLAB, type ColorLCH, type ColorLightnessModifier, type ColorNameAndLightness, type ColorOKLAB, type ColorOKLCH, type ColorPalette, type ColorRGB, type ColorRGBA, type ColorSaturationOptions, type ColorSaturationSpace, type ColorSpace, type ColorStringOptions, type ColorSwatch, type ColorSwatchOptions, type ColorTemperatureAndLabel, type ColorTemperatureLabel, type ColorTemperatureStringFormatOptions, type DeltaEMethod, type DeltaEOptions, type ExtendedColorSwatch, type GenerateColorPaletteOptions, type GrayscaleHandlingMode, type HueInterpolationMode, type IsColorDarkOptions, type MixColorsOptions, type MixSpace, type MixType, type RandomColorOptions, type ReadabilityAlgorithm, type ReadabilityOptions, type WCAGReadabilityConformanceLevel, type WCAGReadabilityOptions, type WCAGReadabilityReport, type WCAGReadabilityTextSizeOptions };
+export { type APCAReadabilityOptions, type APCAReadabilityPolicy, type APCAReadabilityReport, type APCAThresholdPreset, type AverageColorsOptions, type BaseColorName, type BaseColorSwatch, type BaseColorSwatchShade, type BlendColorsOptions, type BlendMode, type BlendSpace, type CIE94Options, type CIEDE2000Options, Color, type ColorBrightnessOptions, type ColorBrightnessSpace, type ColorCMYK, type ColorDarknessMode, type ColorFormat, type ColorGradientEasing, type ColorGradientInterpolation, type ColorGradientOptions, type ColorGradientSpace, type ColorHSL, type ColorHSLA, type ColorHSV, type ColorHSVA, type ColorHWB, type ColorHWBA, type ColorHarmony, type ColorHarmonyOptions, type ColorHex, type ColorLAB, type ColorLCH, type ColorLightnessModifier, type ColorNameAndLightness, type ColorOKLAB, type ColorOKLCH, type ColorPalette, type ColorRGB, type ColorRGBA, type ColorSaturationOptions, type ColorSaturationSpace, type ColorSpace, type ColorStringOptions, type ColorSwatch, type ColorSwatchOptions, type ColorTemperatureAndLabel, type ColorTemperatureLabel, type ColorTemperatureStringFormatOptions, type DeltaEMethod, type DeltaEOptions, type ExtendedColorSwatch, type ExtendedColorSwatchShade, type GenerateColorPaletteOptions, type GrayscaleHandlingMode, type HueInterpolationMode, type IsColorDarkOptions, type MixColorsOptions, type MixSpace, type MixType, type RandomColorOptions, type ReadabilityAlgorithm, type ReadabilityOptions, type TetradicHarmonyDirection, type TetradicHarmonyOptions, type WCAGReadabilityConformanceLevel, type WCAGReadabilityOptions, type WCAGReadabilityReport, type WCAGReadabilityTextSizeOptions };