@basiclines/rampa-sdk 1.7.0 → 1.7.1

package/dist/builder.d.ts

@@ -0,0 +1,38 @@
+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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,48 @@
+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

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

package/dist/formatters/json.d.ts

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

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { RampaBuilder } from './builder';
+import { ReadOnlyBuilder } from './read-only';
+import { LinearColorSpace } from './linear-color-space';
+import { CubeColorSpace } from './cube-color-space';
+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.
+ *
+ * @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, PlaneColorSpace };
+export type { ColorFormat, ScaleType, BlendMode, HarmonyType, RampResult, RampaResult, ColorInfo, InterpolationMode, ColorResult, ColorAccessor, RgbComponents, LinearColorSpaceFn, CubeColorSpaceResult, PlaneColorSpaceResult, ColorSpaceOptions, };

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

@@ -0,0 +1,43 @@
+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/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/read-only.d.ts

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,119 @@
+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);
+}
+/**
+ * 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.7.0",
+  "version": "1.7.1",
   "description": "Programmatic JavaScript SDK for generating color palettes with rampa",
   "type": "module",
   "main": "./dist/index.js",