@basiclines/rampa-sdk 1.5.2 → 1.6.0

package/dist/color-result.d.ts

@@ -1,4 +1,19 @@
-import type { ColorResult } from './types';
+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.

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

@@ -1,9 +1,10 @@
-import type { InterpolationMode, CubeColorSpaceResult } from './types';
+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
@@ -12,13 +13,14 @@ import type { InterpolationMode, CubeColorSpaceResult } from './types';
  *   y: '#f9e2af', m: '#cba6f7', c: '#94e2d5', w: '#cdd6f4',
  * }).size(6);
  *
- * // With different interpolation:
- * const space2 = new CubeColorSpace({ ... }).interpolation('lab').size(6);
+ * // With different interpolation or output format:
+ * const space2 = new CubeColorSpace({ ... }).interpolation('lab').format('rgb').size(6);
  *
- * space.r(4)              // → ColorResult (single-axis shortcut)
- * space.tint({ r: 3, b: 2 }) // → ColorResult (multi-axis)
- * space.cube(3, 0, 2)     // → ColorResult (raw coordinates)
- * space.palette            // → string[216]
+ * 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;
@@ -27,6 +29,7 @@ import type { InterpolationMode, CubeColorSpaceResult } from './types';
 export declare class CubeColorSpace {
     private _corners;
     private _interpolation;
+    private _format;
     constructor(corners: Record<string, string>, options?: {
         interpolation?: InterpolationMode;
     });
@@ -34,6 +37,10 @@ export declare class CubeColorSpace {
      * 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.
      */

package/dist/index.d.ts

@@ -2,7 +2,7 @@ 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, RgbComponents, LinearColorSpaceFn, CubeColorSpaceResult, ColorSpaceOptions } from './types';
+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.
  *
@@ -35,4 +35,4 @@ 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, RgbComponents, LinearColorSpaceFn, CubeColorSpaceResult, ColorSpaceOptions, };
+export type { ColorFormat, ScaleType, BlendMode, HarmonyType, RampResult, RampaResult, ColorInfo, InterpolationMode, ColorResult, ColorAccessor, RgbComponents, LinearColorSpaceFn, CubeColorSpaceResult, ColorSpaceOptions, };

package/dist/index.js

@@ -7941,6 +7941,60 @@ function generateCubeSpace(corners, stepsPerAxis, mode = "oklch") {
 }
 
 // src/color-result.ts
+function detectColorFormat(color) {
+  const trimmed = color.trim();
+  if (/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(trimmed))
+    return "hex";
+  if (/^rgb\s*\(/.test(trimmed))
+    return "rgb";
+  if (/^hsl\s*\(/.test(trimmed))
+    return "hsl";
+  if (/^oklch\s*\(/.test(trimmed))
+    return "oklch";
+  throw new Error(`Unknown color format: ${color}`);
+}
+function validateSameFormat(colors) {
+  const formats = colors.map((c2) => detectColorFormat(c2));
+  const first = formats[0];
+  for (let i = 1;i < formats.length; i++) {
+    if (formats[i] !== first) {
+      throw new Error(`All colors must use the same format. Found '${first}' and '${formats[i]}': ${colors[0]} vs ${colors[i]}`);
+    }
+  }
+  return first;
+}
+function createColorAccessor(hex6, outputFormat) {
+  const c2 = chroma_js_default(hex6);
+  const [l] = c2.oklch();
+  const formatColor2 = (fmt) => {
+    switch (fmt) {
+      case "hsl": {
+        const [h, s, l2] = c2.hsl();
+        return `hsl(${Math.round(h || 0)}, ${Math.round(s * 100)}%, ${Math.round(l2 * 100)}%)`;
+      }
+      case "rgb": {
+        const [r2, g, b] = c2.rgb();
+        return `rgb(${r2}, ${g}, ${b})`;
+      }
+      case "oklch": {
+        const [l2, ch, h] = c2.oklch();
+        return `oklch(${(l2 * 100).toFixed(1)}% ${ch.toFixed(3)} ${Math.round(h || 0)})`;
+      }
+      default:
+        return hex6;
+    }
+  };
+  const value = formatColor2(outputFormat);
+  const accessor = new String(value);
+  Object.defineProperties(accessor, {
+    hex: { value: () => hex6, enumerable: false },
+    hsl: { value: () => formatColor2("hsl"), enumerable: false },
+    rgb: { value: () => formatColor2("rgb"), enumerable: false },
+    oklch: { value: () => formatColor2("oklch"), enumerable: false },
+    luminance: { value: l, enumerable: false }
+  });
+  return accessor;
+}
 function createColorResult(hex6) {
   const c2 = chroma_js_default(hex6);
   const [r2, g, b] = c2.rgb();
@@ -7978,30 +8032,39 @@ function createColorResult(hex6) {
 class LinearColorSpace {
   _colors;
   _interpolation = "oklch";
+  _format = "hex";
   constructor(...colors) {
     if (colors.length < 2) {
       throw new Error("LinearColorSpace requires at least 2 colors");
     }
+    validateSameFormat(colors);
     this._colors = colors;
   }
   interpolation(mode) {
     this._interpolation = mode;
     return this;
   }
+  format(fmt) {
+    this._format = fmt;
+    return this;
+  }
   size(steps) {
     let palette;
+    const outputFormat = this._format;
     if (this._interpolation === false) {
-      palette = [...this._colors];
+      palette = this._colors.map((c2) => chroma_js_default(c2).hex());
     } else {
-      palette = generateLinearSpace(this._colors[0], this._colors[this._colors.length - 1], steps, this._interpolation);
+      const firstHex = chroma_js_default(this._colors[0]).hex();
+      const lastHex = chroma_js_default(this._colors[this._colors.length - 1]).hex();
+      palette = generateLinearSpace(firstHex, lastHex, steps, this._interpolation);
     }
-    return buildFn(palette);
+    return buildFn(palette, outputFormat);
   }
 }
-function buildFn(palette) {
+function buildFn(palette, outputFormat) {
   const fn4 = (index) => {
     const i = Math.max(1, Math.min(palette.length, index)) - 1;
-    return createColorResult(palette[i]);
+    return createColorAccessor(palette[i], outputFormat);
   };
   fn4.palette = palette;
   fn4.size = palette.length;
@@ -8023,11 +8086,13 @@ var CORNER_MASKS = [
 class CubeColorSpace {
   _corners;
   _interpolation;
+  _format = "hex";
   constructor(corners, options) {
     const keys = Object.keys(corners);
     if (keys.length !== 8) {
       throw new Error(`CubeColorSpace requires exactly 8 corner colors, got ${keys.length}`);
     }
+    validateSameFormat(Object.values(corners));
     this._corners = corners;
     this._interpolation = options?.interpolation ?? "oklch";
   }
@@ -8035,9 +8100,14 @@ class CubeColorSpace {
     this._interpolation = mode;
     return this;
   }
+  format(fmt) {
+    this._format = fmt;
+    return this;
+  }
   size(stepsPerAxis) {
     const keys = Object.keys(this._corners);
-    const cornerColors = keys.map((k3) => this._corners[k3]);
+    const cornerColors = keys.map((k3) => chroma_js_default(this._corners[k3]).hex());
+    const outputFormat = this._format;
     const aliases = {};
     for (let i = 0;i < 8; i++) {
       aliases[keys[i]] = CORNER_MASKS[i];
@@ -8049,7 +8119,7 @@ class CubeColorSpace {
       cy = Math.max(0, Math.min(max11, Math.round(cy)));
       cz = Math.max(0, Math.min(max11, Math.round(cz)));
       const index = cx * stepsPerAxis * stepsPerAxis + cy * stepsPerAxis + cz;
-      return createColorResult(palette[index]);
+      return createColorAccessor(palette[index], outputFormat);
     };
     const tint = (query) => {
       let cx = 0, cy = 0, cz = 0;

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

@@ -1,16 +1,18 @@
-import type { InterpolationMode, LinearColorSpaceFn } from './types';
+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)                // → ColorResult (mid gray)
- * neutral(12).format('hsl')  // → 'hsl(...)'
+ * neutral(12)                // → "#808080" (string in output format)
+ * neutral(12).hsl()          // → "hsl(...)" (convert to another format)
  *
- * // Different interpolation
- * const ramp = new LinearColorSpace('#ff0000', '#0000ff').interpolation('lab').size(10);
+ * // 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')
@@ -23,12 +25,17 @@ import type { InterpolationMode, LinearColorSpaceFn } from './types';
 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.
      */

package/dist/types.d.ts

@@ -55,12 +55,33 @@ export interface ColorResult {
     /** 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): ColorResult;
+    (index: number): ColorAccessor;
     palette: string[];
     size: number;
 }
@@ -74,13 +95,13 @@ export interface LinearColorSpaceFn {
  */
 export interface CubeColorSpaceResult {
     /** Multi-axis lookup: tint({ r: 3, b: 2 }) */
-    tint(query: Record<string, number>): ColorResult;
+    tint(query: Record<string, number>): ColorAccessor;
     /** Raw 3D coordinate lookup: cube(x, y, z) */
-    cube(x: number, y: number, z: number): ColorResult;
+    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) => ColorResult) | string[] | number | ((query: Record<string, number>) => ColorResult) | ((x: number, y: number, z: number) => ColorResult);
+    [key: string]: ((index: number) => ColorAccessor) | string[] | number | ((query: Record<string, number>) => ColorAccessor) | ((x: number, y: number, z: number) => ColorAccessor);
 }

package/package.json

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