@newtonedev/colors 0.0.1 → 1.0.0

package/dist/scale/key-color.d.ts

@@ -1,53 +1,57 @@
-import type { Hex, Oklch, Gamut } from "../types.js";
-import { type ResolvedColor } from "./resolve-color.js";
+import type { Hex, Oklch } from "../types.js";
 /**
  * The result of deriving scale parameters from a key color.
  *
- * Spread `hue` and `chroma` directly into ScaleOptions, then pass
- * `resolved.oklch` to findNearest to locate the color in the generated scale.
+ * Spread `hue` and `chroma` directly into ScaleOptions, then use
+ * `stepIndex` to locate the key color's position in the generated scale.
  */
 export interface KeyColorResult {
     /** Derived hue angle — use directly as ScaleOptions.hue. */
     readonly hue: number;
     /**
      * Derived chroma shape — use directly as ScaleOptions.chroma.
-     * - `value`: how saturated the scale is (0–1, relative to gamut boundary).
-     * - `offset`: where in the scale the key color's lightness falls (0 = lightest, 1 = darkest).
+     * - `amount`: how saturated the scale is (0–1, relative to gamut boundary).
+     * - `balance`: where in the scale the key color's lightness falls (0 = lightest, 1 = darkest).
      */
     readonly chroma: {
-        readonly value: number;
-        readonly offset: number;
+        readonly amount: number;
+        readonly balance: number;
     };
-    /**
-     * The resolved color — pass to findNearest to locate the key color
-     * in the scale after calling generateScale.
-     *
-     * @example
-     * const key = keyColor('#3B82F6', { gamut, lightest, darkest });
-     * const scale = generateScale({ ...key, steps, grading, gradient });
-     * const nearest = findNearest(key.resolved.oklch, scale);
-     */
-    readonly resolved: ResolvedColor;
+    /** The step index in a scale of `steps` length where this color lands. */
+    readonly stepIndex: number;
+    /** Hex representation of the resolved color (sRGB-clamped if necessary). */
+    readonly hex: Hex;
+    /** The final OKLCH color, guaranteed in-gamut for the target gamut. */
+    readonly oklch: Oklch;
+    /** Whether the input was outside the target gamut and was remapped. */
+    readonly wasRemapped: boolean;
+    /** The original OKLCH before gamut mapping (identical to oklch if in-gamut). */
+    readonly original: Oklch;
 }
 /**
- * Derive scale parameters from a key (brand) color.
+ * Derive scale parameters from a known color.
  *
  * Given a hex or OKLCH color, returns the `hue` and `chroma` values
- * ready to spread into ScaleOptions. The chroma offset is derived from
+ * ready to spread into ScaleOptions. The chroma balance is derived from
  * where the color's lightness falls within the scale's lightness range,
- * so the scale's chroma peak aligns with the key color's position.
+ * so the chroma distribution is centered around the key color's position.
  *
  * @param color    A hex string (#RGB or #RRGGBB) or an OKLCH color object.
  * @param options  Scale context — must match the ScaleOptions you will use.
+ *                 `contrast` values are slider values (0–1), same as ScaleOptions.contrast.
+ *                 `steps` is the number of steps in the scale (default: 26).
  *
  * @example
- * const key = keyColor('#3B82F6', { gamut: 'srgb', lightest: 0.96, darkest: 0.16 });
- * const scale = generateScale({ ...key, steps: 26 });
- * const { index } = findNearest(key.resolved.oklch, scale);
+ * const key = keyColor('#3B82F6');
+ * const scale = generateScale({ hue: key.hue, chroma: key.chroma });
+ * const matchedHex = oklchToHex(scale[key.stepIndex]);
  */
 export declare function keyColor(color: Hex | Oklch, options?: {
-    readonly gamut?: Gamut;
-    readonly lightest?: number;
-    readonly darkest?: number;
+    readonly isP3?: boolean;
+    readonly contrast?: {
+        readonly light?: number;
+        readonly dark?: number;
+    };
+    readonly steps?: number;
 }): KeyColorResult;
 //# sourceMappingURL=key-color.d.ts.map

package/dist/scale/key-color.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"key-color.d.ts","sourceRoot":"","sources":["../../src/scale/key-color.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGtE;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,GAAG,GAAG,KAAK,EAClB,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B,GACA,cAAc,CAUhB"}
+{"version":3,"file":"key-color.d.ts","sourceRoot":"","sources":["../../src/scale/key-color.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAK9C;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,GAAG,GAAG,KAAK,EAClB,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,cAAc,CAiBhB"}

package/dist/scale/resolve-color.d.ts

@@ -1,4 +1,4 @@
-import type { Hex, Oklch, Gamut } from "../types.js";
+import type { Hex, Oklch } from "../types.js";
 /**
  * Result of resolving a color into scale-ready parameters.
  */
@@ -13,9 +13,9 @@ export interface ResolvedColor {
     readonly original: Oklch;
     /** Chroma lost during gamut mapping (0 if in-gamut). */
     readonly chromaShift: number;
-    /** Hue from the resolved color — use directly as ScaleOptions.hue. */
+    /** Hue from the resolved color. */
     readonly hue: number;
-    /** Chroma as a fraction of the gamut boundary at this L/h (0–1) — use as ScaleOptions.chroma.value. */
+    /** Chroma as a fraction of the gamut boundary at this L/h (0–1). */
     readonly chromaRatio: number;
 }
 /**
@@ -23,33 +23,13 @@ export interface ResolvedColor {
  *
  * If the color is outside the target gamut, it is perceptually mapped to the
  * nearest in-gamut color (chroma reduction at fixed L and h). The result
- * includes the derived hue and chromaRatio for direct use in ScaleOptions.
+ * includes the derived hue and chromaRatio.
  *
  * Hex input is always valid sRGB, so `wasRemapped` will be false for hex
  * with gamut="srgb". OKLCH input may be out of gamut and will be mapped.
  *
  * @param input   A hex string (#RGB, #RRGGBB) or an OKLCH color.
- * @param gamut   Target gamut (default: "srgb").
+ * @param isP3   Use Display P3 gamut instead of sRGB (default: false).
  */
-export declare function resolveColor(input: Hex | Oklch, gamut?: Gamut): ResolvedColor;
-/**
- * Result of finding the nearest color in a scale.
- */
-export interface NearestMatch {
-    /** Index of the nearest step in the scale (0-based). */
-    readonly index: number;
-    /** The nearest OKLCH color from the scale. */
-    readonly color: Oklch;
-    /** Perceptual distance (deltaEOK) between the target and nearest step. */
-    readonly distance: number;
-}
-/**
- * Find the step in a scale perceptually closest to a target color.
- *
- * Uses deltaEOK (Euclidean distance in OKLAB) for comparison.
- *
- * @param target  The color to match against.
- * @param scale   An array of OKLCH colors (e.g. from generateScale).
- */
-export declare function findNearest(target: Oklch, scale: readonly Oklch[]): NearestMatch;
+export declare function resolveColor(input: Hex | Oklch, isP3?: boolean): ResolvedColor;
 //# sourceMappingURL=resolve-color.d.ts.map

package/dist/scale/resolve-color.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-color.d.ts","sourceRoot":"","sources":["../../src/scale/resolve-color.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAYrD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,uGAAuG;IACvG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,GAAG,GAAG,KAAK,EAClB,KAAK,GAAE,KAAc,GACpB,aAAa,CAkCf;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,KAAK,EACb,KAAK,EAAE,SAAS,KAAK,EAAE,GACtB,YAAY,CAqBd"}
+{"version":3,"file":"resolve-color.d.ts","sourceRoot":"","sources":["../../src/scale/resolve-color.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAS,MAAM,aAAa,CAAC;AAWrD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,GAAG,GAAG,KAAK,EAClB,IAAI,GAAE,OAAe,GACpB,aAAa,CA+Bf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newtonedev/colors",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "Color scale engine — produces accessible color scales from declarative parameters",
   "type": "module",
   "main": "./dist/index.cjs",