@basiclines/rampa-sdk 1.6.0 → 1.7.1

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.d.ts

@@ -2,7 +2,8 @@ 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';
+import { PlaneColorSpace } from './plane-color-space';
+import type { ColorFormat, ScaleType, BlendMode, HarmonyType, RampResult, RampaResult, ColorInfo, InterpolationMode, ColorResult, ColorAccessor, RgbComponents, LinearColorSpaceFn, CubeColorSpaceResult, PlaneColorSpaceResult, ColorSpaceOptions } from './types';
 /**
  * Create a new color ramp builder from a base color.
  *
@@ -34,5 +35,5 @@ export declare namespace rampa {
  * ```
  */
 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, };
+export { RampaBuilder, ReadOnlyBuilder, LinearColorSpace, CubeColorSpace, PlaneColorSpace };
+export type { ColorFormat, ScaleType, BlendMode, HarmonyType, RampResult, RampaResult, ColorInfo, InterpolationMode, ColorResult, ColorAccessor, RgbComponents, LinearColorSpaceFn, CubeColorSpaceResult, PlaneColorSpaceResult, ColorSpaceOptions, };

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/dist/plane-color-space.d.ts

@@ -0,0 +1,36 @@
+import type { ColorFormat, InterpolationMode, PlaneColorSpaceResult } from './types';
+/**
+ * Create a 2D color plane from dark, light, and hue anchors.
+ *
+ * The plane interpolates between 4 corners:
+ *   (0,0) = dark    — origin (bottom-left)
+ *   (1,0) = dark    — saturation has no effect at lightness=0
+ *   (0,1) = light   — achromatic light (top-left)
+ *   (1,1) = hue     — full chromatic color (top-right)
+ *
+ * Create one plane per hue, reusing the same dark/light anchors:
+ *
+ * @example
+ * ```ts
+ * 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
+ * red.palette   // → string[36] (6²)
+ *
+ * // With different interpolation or output format:
+ * new PlaneColorSpace(dark, light, hue).interpolation('lab').format('rgb').size(8);
+ * ```
+ */
+export declare class PlaneColorSpace {
+    private _dark;
+    private _light;
+    private _hue;
+    private _interpolation;
+    private _format;
+    constructor(dark: string, light: string, hue: string);
+    interpolation(mode: InterpolationMode): this;
+    format(fmt: ColorFormat): this;
+    size(stepsPerAxis: number): PlaneColorSpaceResult;
+}

package/dist/types.d.ts

@@ -105,3 +105,15 @@ export interface CubeColorSpaceResult {
     /** 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);
 }
+/**
+ * The result returned by PlaneColorSpace.size().
+ * Callable with (saturation, lightness) to look up colors on the 2D plane.
+ */
+export interface PlaneColorSpaceResult {
+    /** Look up a color by 2D coordinates (both 0-based, clamped to size-1) */
+    (saturation: number, lightness: number): ColorAccessor;
+    /** Full palette array (length = size²) */
+    palette: string[];
+    /** Steps per axis */
+    size: number;
+}

package/package.json

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