@basiclines/rampa-sdk 1.6.0 → 1.7.0

package/README.md

@@ -345,7 +345,11 @@ rampa('#3b82f6').size(5).lightness(10, 90).add('complementary').toJSON();
 
 ## Color Spaces
 
-Color spaces let you create structured palettes from a set of anchor colors and query them semantically. Two primitives are available:
+Color spaces let you create structured palettes from a set of anchor colors and query them semantically. Three geometric primitives are available:
+
+- **LinearColorSpace** — 1D interpolated ramp
+- **PlaneColorSpace** — 2D saturation×lightness plane
+- **CubeColorSpace** — 3D trilinear interpolation cube
 
 ### `LinearColorSpace`
 
@@ -355,11 +359,9 @@ Interpolates between two colors to produce an evenly-spaced ramp.
 import { LinearColorSpace } from '@basiclines/rampa-sdk';
 
 const neutral = new LinearColorSpace('#ffffff', '#000000').size(24);
-neutral(1)               // → ColorResult (lightest)
-neutral(12)              // → ColorResult (mid gray)
-neutral(24)              // → ColorResult (darkest)
-neutral(12).hex          // → '#666666'
-neutral(12).format('hsl') // → 'hsl(0, 0%, 40%)'
+neutral(1)               // → '#ffffff' (lightest, returns string directly)
+neutral(12)              // → '#666666' (mid gray)
+neutral(12).hsl()        // → 'hsl(0, 0%, 40%)'
 neutral.palette          // → string[24]
 ```
 
@@ -377,6 +379,44 @@ base(1)  // → '#45475a' (exact, no interpolation)
 base(3)  // → '#a6e3a1'
 ```
 
+### `PlaneColorSpace`
+
+Creates a 2D color plane for a single hue, anchored to shared dark/light values. Create one plane per hue.
+
+```
+Y(lightness)
+1 │  light ─────────── hue
+  │    │                 │
+  │    │   interpolated  │
+  │    │                 │
+0 │  dark ─────────── dark
+  └──────────────────────── X(saturation)
+      0                  1
+```
+
+At Y=0 the entire row converges to the dark anchor.
+
+```typescript
+import { PlaneColorSpace } from '@basiclines/rampa-sdk';
+
+// One plane per hue, reuse dark/light anchors
+const red  = new PlaneColorSpace('#1e1e2e', '#cdd6f4', '#f38ba8').size(6);
+const blue = new PlaneColorSpace('#1e1e2e', '#cdd6f4', '#89b4fa').size(6);
+
+red(3, 5)          // → ColorAccessor (saturation=3, lightness=5)
+red(0, 3)          // → achromatic at lightness 3 (no hue influence)
+red(5, 5)          // → full hue color
+red(0, 0)          // → dark anchor
+red.palette        // → string[36] (6²)
+
+// Template literals and concatenation work directly
+`background: ${red(3, 5)};`  // → 'background: #ab34cd;'
+
+// Format conversion
+red(3, 5).hsl()    // → 'hsl(280, 60%, 50%)'
+red(3, 5).oklch()  // → 'oklch(52.3% 0.198 310)'
+```
+
 ### `CubeColorSpace`
 
 Creates a 3D color cube from 8 corner colors via trilinear interpolation. The constructor keys become alias names for semantic lookups.
@@ -384,7 +424,7 @@ Creates a 3D color cube from 8 corner colors via trilinear interpolation. The co
 ```typescript
 import { CubeColorSpace } from '@basiclines/rampa-sdk';
 
-const tint = new CubeColorSpace({
+const { r, b, tint } = new CubeColorSpace({
   k: '#1e1e2e',    // origin (0,0,0)
   r: '#f38ba8',    // x axis
   g: '#a6e3a1',    // y axis
@@ -395,11 +435,9 @@ const tint = new CubeColorSpace({
   w: '#cdd6f4',    // x+y+z
 }).size(6);
 
-tint({ r: 4 })           // → strong red
+r(4)                     // → strong red
 tint({ r: 4, b: 2 })     // → red-blue blend
 tint({ w: 3 })           // → mid-white (all axes at 3)
-tint({ r: 5, w: 2 })     // → pastel red (white raises base)
-tint.palette             // → string[216] (6³)
 ```
 
 #### Custom vocabulary
@@ -440,7 +478,7 @@ When you call `tint({ r: 4, b: 2 })`, each alias's mask is multiplied by its int
 
 ### Interpolation modes
 
-Both `LinearColorSpace` and `CubeColorSpace` support configurable interpolation:
+`LinearColorSpace`, `PlaneColorSpace`, and `CubeColorSpace` all support configurable interpolation:
 
 | Mode | Description |
 |------|-------------|
@@ -453,24 +491,37 @@ Both `LinearColorSpace` and `CubeColorSpace` support configurable interpolation:
 // LinearColorSpace
 new LinearColorSpace('#ff0000', '#0000ff').interpolation('oklch').size(10)
 new LinearColorSpace('#ff0000', '#0000ff').interpolation('lab').size(10)
-new LinearColorSpace('#ff0000', '#0000ff').interpolation('rgb').size(10)
 new LinearColorSpace('#f00', '#0f0', '#00f').interpolation(false).size(3)
 
+// PlaneColorSpace
+new PlaneColorSpace('#000', '#fff', '#f00').interpolation('oklch').size(6)
+new PlaneColorSpace('#000', '#fff', '#f00').interpolation('lab').size(6)
+
 // CubeColorSpace
-new CubeColorSpace({ ... }, { interpolation: 'lab' }).size(6)
+new CubeColorSpace({ ... }).interpolation('lab').size(6)
 ```
 
-### Color result chaining
+### Color accessor
+
+All color space lookups return a `ColorAccessor` — a string that works directly in template literals and concatenation, with conversion methods:
+
+```typescript
+const c = red(3, 5);
+`${c}`             // → '#ab34cd' (string coercion)
+'bg: ' + c         // → 'bg: #ab34cd' (concatenation)
+c.hex()            // → '#ab34cd'
+c.hsl()            // → 'hsl(280, 60%, 50%)'
+c.rgb()            // → 'rgb(171, 52, 205)'
+c.oklch()          // → 'oklch(52.3% 0.198 310)'
+c.luminance        // → 0.52 (perceptual, 0–1)
+```
 
-All color space lookups return a `ColorResult` that acts as a hex string but supports format conversion:
+Use `.format()` on the color space to change the default output format:
 
 ```typescript
-const color = tint({ r: 4, b: 2 });
-color.hex              // → '#ab34cd'
-color.format('hsl')    // → 'hsl(280, 60%, 50%)'
-color.format('rgb')    // → 'rgb(171, 52, 205)'
-color.format('oklch')  // → 'oklch(52.3% 0.198 310)'
-color.toString()       // → '#ab34cd'
+const rgbSpace = new PlaneColorSpace('#000', '#fff', '#f00').format('rgb').size(6);
+`${rgbSpace(3, 5)}`  // → 'rgb(255, 128, 128)'
+rgbSpace(3, 5).hex() // → '#ff8080' (still available)
 ```
 
 ## Development

package/dist/index.js

@@ -7939,6 +7939,21 @@ function generateCubeSpace(corners, stepsPerAxis, mode = "oklch") {
   }
   return colors;
 }
+function generatePlaneSpace(dark, light, hue3, stepsPerAxis, mode = "oklch") {
+  const mix = (a, b, t) => mixWithMode(a, b, t, mode);
+  const max11 = stepsPerAxis - 1;
+  const colors = [];
+  for (let xi = 0;xi < stepsPerAxis; xi++) {
+    const tx = max11 === 0 ? 0 : xi / max11;
+    const bottom = dark;
+    const top = mix(light, hue3, tx);
+    for (let yi = 0;yi < stepsPerAxis; yi++) {
+      const ty = max11 === 0 ? 0 : yi / max11;
+      colors.push(mix(bottom, top, ty));
+    }
+  }
+  return colors;
+}
 
 // src/color-result.ts
 function detectColorFormat(color) {
@@ -8147,6 +8162,46 @@ class CubeColorSpace {
   }
 }
 
+// src/plane-color-space.ts
+class PlaneColorSpace {
+  _dark;
+  _light;
+  _hue;
+  _interpolation;
+  _format = "hex";
+  constructor(dark, light, hue3) {
+    validateSameFormat([dark, light, hue3]);
+    this._dark = chroma_js_default(dark).hex();
+    this._light = chroma_js_default(light).hex();
+    this._hue = chroma_js_default(hue3).hex();
+    this._interpolation = "oklch";
+  }
+  interpolation(mode) {
+    this._interpolation = mode;
+    return this;
+  }
+  format(fmt) {
+    this._format = fmt;
+    return this;
+  }
+  size(stepsPerAxis) {
+    const palette = generatePlaneSpace(this._dark, this._light, this._hue, stepsPerAxis, this._interpolation);
+    const fmt = this._format;
+    const lookup = (saturation, lightness) => {
+      const sx = Math.max(0, Math.min(stepsPerAxis - 1, saturation));
+      const ly = Math.max(0, Math.min(stepsPerAxis - 1, lightness));
+      const idx = sx * stepsPerAxis + ly;
+      return createColorAccessor(palette[idx], fmt);
+    };
+    const result = lookup;
+    Object.defineProperties(result, {
+      palette: { value: palette, enumerable: true },
+      size: { value: stepsPerAxis, enumerable: true }
+    });
+    return result;
+  }
+}
+
 // ../src/usecases/MixColors.ts
 function mixColors(color1, color2, t) {
   const oklch1 = convertToOklch(color1);
@@ -8200,6 +8255,7 @@ export {
   color,
   ReadOnlyBuilder,
   RampaBuilder,
+  PlaneColorSpace,
   LinearColorSpace,
   CubeColorSpace
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basiclines/rampa-sdk",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Programmatic JavaScript SDK for generating color palettes with rampa",
   "type": "module",
   "main": "./dist/index.js",

package/dist/builder.d.ts

@@ -1,38 +0,0 @@
-import type { ColorFormat, ScaleType, BlendMode, HarmonyType, RampaResult } from './types';
-export declare class RampaBuilder {
-    private _baseColor;
-    private _size;
-    private _format;
-    private _lightnessStart;
-    private _lightnessEnd;
-    private _saturationStart;
-    private _saturationEnd;
-    private _hueStart;
-    private _hueEnd;
-    private _lightnessScale;
-    private _saturationScale;
-    private _hueScale;
-    private _tintColor?;
-    private _tintOpacity;
-    private _tintBlend;
-    private _harmonies;
-    constructor(baseColor: string);
-    size(steps: number): this;
-    format(fmt: ColorFormat): this;
-    lightness(start: number, end: number): this;
-    saturation(start: number, end: number): this;
-    hue(start: number, end: number): this;
-    lightnessScale(scale: ScaleType): this;
-    saturationScale(scale: ScaleType): this;
-    hueScale(scale: ScaleType): this;
-    tint(color: string, opacity: number, blend?: BlendMode): this;
-    add(type: HarmonyType): this;
-    add(type: 'shift', degrees: number): this;
-    private buildConfig;
-    private formatColor;
-    private getHarmonyColors;
-    private buildRamps;
-    generate(): RampaResult;
-    toCSS(): string;
-    toJSON(): string;
-}

package/dist/color-result.d.ts

@@ -1,21 +0,0 @@
-import type { ColorFormat, ColorResult, ColorAccessor } from './types';
-/**
- * Detect the format of a color string.
- */
-export declare function detectColorFormat(color: string): ColorFormat;
-/**
- * Validate that all colors in an array share the same format.
- * Returns the detected format.
- */
-export declare function validateSameFormat(colors: string[]): ColorFormat;
-/**
- * Create a ColorAccessor from a hex string with a given output format.
- * Returns a String object with conversion methods so it acts as a string
- * in template literals, comparisons, and concatenation.
- */
-export declare function createColorAccessor(hex: string, outputFormat: ColorFormat): ColorAccessor;
-/**
- * Create a ColorResult from a hex string.
- * Acts as a string (hex) by default, supports .format() for conversions.
- */
-export declare function createColorResult(hex: string): ColorResult;

package/dist/cube-color-space.d.ts

@@ -1,48 +0,0 @@
-import type { ColorFormat, InterpolationMode, CubeColorSpaceResult } from './types';
-/**
- * Create a 3D color cube from 8 named corner colors.
- *
- * The constructor keys become shortcut function names and tint() aliases.
- * Key order determines cube position (see CORNER_MASKS above).
- * All input colors must use the same format.
- *
- * @example
- * ```ts
- * const space = new CubeColorSpace({
- *   k: '#1e1e2e', r: '#f38ba8', g: '#a6e3a1', b: '#89b4fa',
- *   y: '#f9e2af', m: '#cba6f7', c: '#94e2d5', w: '#cdd6f4',
- * }).size(6);
- *
- * // With different interpolation or output format:
- * const space2 = new CubeColorSpace({ ... }).interpolation('lab').format('rgb').size(6);
- *
- * space.r(4)                 // → "f38ba8" (string in output format)
- * space.r(4).hsl()           // → "hsl(...)" (convert to another format)
- * space.tint({ r: 3, b: 2 }) // → string in output format
- * space.cube(3, 0, 2)        // → string in output format
- * space.palette               // → string[216]
- *
- * // Destructure for convenience:
- * const { r, w, tint, cube } = space;
- * ```
- */
-export declare class CubeColorSpace {
-    private _corners;
-    private _interpolation;
-    private _format;
-    constructor(corners: Record<string, string>, options?: {
-        interpolation?: InterpolationMode;
-    });
-    /**
-     * Set the interpolation mode.
-     */
-    interpolation(mode: InterpolationMode): this;
-    /**
-     * Set the output color format (default: 'hex').
-     */
-    format(fmt: ColorFormat): this;
-    /**
-     * Set the steps per axis and return the color space accessor object.
-     */
-    size(stepsPerAxis: number): CubeColorSpaceResult;
-}

package/dist/formatters/css.d.ts

@@ -1,2 +0,0 @@
-import type { RampResult } from '../types';
-export declare function formatCssOutput(ramps: RampResult[]): string;

package/dist/formatters/json.d.ts

@@ -1,2 +0,0 @@
-import type { RampResult } from '../types';
-export declare function formatJsonOutput(ramps: RampResult[]): string;

package/dist/index.d.ts

@@ -1,38 +0,0 @@
-import { RampaBuilder } from './builder';
-import { ReadOnlyBuilder } from './read-only';
-import { LinearColorSpace } from './linear-color-space';
-import { CubeColorSpace } from './cube-color-space';
-import type { ColorFormat, ScaleType, BlendMode, HarmonyType, RampResult, RampaResult, ColorInfo, InterpolationMode, ColorResult, ColorAccessor, RgbComponents, LinearColorSpaceFn, CubeColorSpaceResult, ColorSpaceOptions } from './types';
-/**
- * Create a new color ramp builder from a base color.
- *
- * @example
- * ```ts
- * import { rampa } from '@basiclines/rampa-sdk';
- *
- * const result = rampa('#3b82f6').size(10).generate();
- * const css = rampa('#3b82f6').add('complementary').toCSS();
- * ```
- */
-export declare function rampa(baseColor: string): RampaBuilder;
-export declare namespace rampa {
-    var convert: (color: string, format: ColorFormat) => string;
-    var readOnly: (color: string) => ReadOnlyBuilder;
-    var mix: (color1: string, color2: string, t: number) => string;
-}
-/**
- * Create a ColorResult from any hex color string.
- * Provides .hex, .rgb, .luminance, .format() for color inspection.
- *
- * @example
- * ```ts
- * import { color } from '@basiclines/rampa-sdk';
- * const c = color('#ff0000');
- * c.rgb        // { r: 255, g: 0, b: 0 }
- * c.luminance  // 0.627 (OKLCH perceptual lightness)
- * c.format('hsl') // 'hsl(0, 100%, 50%)'
- * ```
- */
-export declare function color(hex: string): ColorResult;
-export { RampaBuilder, ReadOnlyBuilder, LinearColorSpace, CubeColorSpace };
-export type { ColorFormat, ScaleType, BlendMode, HarmonyType, RampResult, RampaResult, ColorInfo, InterpolationMode, ColorResult, ColorAccessor, RgbComponents, LinearColorSpaceFn, CubeColorSpaceResult, ColorSpaceOptions, };

package/dist/linear-color-space.d.ts

@@ -1,43 +0,0 @@
-import type { ColorFormat, InterpolationMode, LinearColorSpaceFn } from './types';
-/**
- * Create a linear color space.
- * All input colors must use the same format.
- *
- * @example
- * ```ts
- * // Interpolated (default: oklch)
- * const neutral = new LinearColorSpace('#ffffff', '#000000').size(24);
- * neutral(12)                // → "#808080" (string in output format)
- * neutral(12).hsl()          // → "hsl(...)" (convert to another format)
- *
- * // Different interpolation and output format:
- * const ramp = new LinearColorSpace('#ff0000', '#0000ff').interpolation('lab').format('rgb').size(10);
- * ramp(5)                    // → "rgb(128, 0, 128)"
- *
- * // Lookup table — no interpolation, just a plain color array
- * const base = new LinearColorSpace('#000', '#f00', '#0f0', '#ff0', '#00f', '#f0f', '#0ff', '#fff')
- *   .interpolation(false)
- *   .size(8);
- * base(1)  // → first color
- * base(3)  // → third color
- * ```
- */
-export declare class LinearColorSpace {
-    private _colors;
-    private _interpolation;
-    private _format;
-    constructor(...colors: string[]);
-    /**
-     * Set the interpolation mode.
-     * Pass false for a plain lookup table (no interpolation).
-     */
-    interpolation(mode: InterpolationMode | false): this;
-    /**
-     * Set the output color format (default: 'hex').
-     */
-    format(fmt: ColorFormat): this;
-    /**
-     * Set the number of color steps and return the color accessor function.
-     */
-    size(steps: number): LinearColorSpaceFn;
-}

package/dist/read-only.d.ts

@@ -1,8 +0,0 @@
-import type { ColorFormat, ColorInfo } from './types';
-export declare class ReadOnlyBuilder {
-    private _color;
-    private _format?;
-    constructor(color: string);
-    format(fmt: ColorFormat): this;
-    generate(): ColorInfo | string;
-}

package/dist/types.d.ts

@@ -1,107 +0,0 @@
-export type ColorFormat = 'hex' | 'hsl' | 'rgb' | 'oklch';
-export type ScaleType = 'linear' | 'geometric' | 'fibonacci' | 'golden-ratio' | 'logarithmic' | 'powers-of-2' | 'musical-ratio' | 'cielab-uniform' | 'ease-in' | 'ease-out' | 'ease-in-out';
-export type BlendMode = 'normal' | 'darken' | 'multiply' | 'plus-darker' | 'color-burn' | 'lighten' | 'screen' | 'plus-lighter' | 'color-dodge' | 'overlay' | 'soft-light' | 'hard-light' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity';
-export type HarmonyType = 'complementary' | 'triadic' | 'analogous' | 'split-complementary' | 'square' | 'compound';
-export interface RampResult {
-    name: string;
-    baseColor: string;
-    colors: string[];
-}
-export interface RampaResult {
-    ramps: RampResult[];
-}
-export interface ColorInfo {
-    hex: string;
-    rgb: {
-        r: number;
-        g: number;
-        b: number;
-    };
-    hsl: {
-        h: number;
-        s: number;
-        l: number;
-    };
-    oklch: {
-        l: number;
-        c: number;
-        h: number;
-    };
-}
-export type InterpolationMode = 'oklch' | 'lab' | 'rgb';
-export interface ColorSpaceOptions {
-    interpolation?: InterpolationMode;
-}
-/**
- * RGB components (0-255).
- */
-export interface RgbComponents {
-    r: number;
-    g: number;
-    b: number;
-}
-/**
- * A color result that acts as a hex string but supports format chaining.
- */
-export interface ColorResult {
-    /** Hex color string */
-    hex: string;
-    /** RGB components (0-255) */
-    rgb: RgbComponents;
-    /** Perceptual luminance (0-1) using OKLCH lightness */
-    luminance: number;
-    /** Format the color as hsl, rgb, oklch, or hex */
-    format(fmt: ColorFormat): string;
-    /** String coercion returns hex */
-    toString(): string;
-}
-/**
- * A color accessor returned by color space functions.
- * Acts as a string via toString()/valueOf() in the color space's output format.
- * Has .hex(), .hsl(), .rgb(), .oklch() methods for format conversion.
- */
-export interface ColorAccessor {
-    /** Convert to hex string */
-    hex(): string;
-    /** Convert to hsl string */
-    hsl(): string;
-    /** Convert to rgb string */
-    rgb(): string;
-    /** Convert to oklch string */
-    oklch(): string;
-    /** Perceptual luminance (0-1) using OKLCH lightness */
-    luminance: number;
-    /** String coercion returns color in the space's output format */
-    toString(): string;
-    /** Primitive coercion returns the formatted string */
-    valueOf(): string;
-}
-/**
- * The function signature returned by LinearColorSpace.
- * Call it with a 1-based index to get a color.
- */
-export interface LinearColorSpaceFn {
-    (index: number): ColorAccessor;
-    palette: string[];
-    size: number;
-}
-/**
- * The result object returned by CubeColorSpace.size().
- * Provides multiple ways to access colors:
- * - Per-corner shortcut functions (e.g. r(3), w(5))
- * - tint() for multi-axis lookups
- * - cube() for raw 3D coordinate access
- * - palette for the full color array
- */
-export interface CubeColorSpaceResult {
-    /** Multi-axis lookup: tint({ r: 3, b: 2 }) */
-    tint(query: Record<string, number>): ColorAccessor;
-    /** Raw 3D coordinate lookup: cube(x, y, z) */
-    cube(x: number, y: number, z: number): ColorAccessor;
-    /** Full palette array */
-    palette: string[];
-    /** Steps per axis */
-    size: number;
-    /** Per-corner shortcut functions, keyed by constructor key names */
-    [key: string]: ((index: number) => ColorAccessor) | string[] | number | ((query: Record<string, number>) => ColorAccessor) | ((x: number, y: number, z: number) => ColorAccessor);
-}