@basiclines/rampa 1.5.2 → 1.7.0

package/README.md

@@ -183,6 +183,9 @@ The `colorspace` subcommand lets you define and query multi-dimensional color sp
 # Linear: 2-color interpolated ramp
 rampa colorspace --linear '#ffffff' '#000000' --size 24 --at 12
 
+# Plane: 2D saturation×lightness for a single hue
+rampa colorspace --plane '#1e1e2e' '#cdd6f4' '#f38ba8' --size 6 --xy 3,5
+
 # Cube: 8-corner color cube with named aliases
 rampa colorspace --cube k=#1e1e2e r=#f38ba8 g=#a6e3a1 b=#89b4fa \
                         y=#f9e2af m=#cba6f7 c=#94e2d5 w=#cdd6f4 \
@@ -211,15 +214,29 @@ Config file format:
 }
 ```
 
+Plane config:
+```json
+{
+  "type": "plane",
+  "dark": "#1e1e2e",
+  "light": "#cdd6f4",
+  "hue": "#f38ba8",
+  "size": 6,
+  "interpolation": "oklch"
+}
+```
+
 #### Colorspace Flags
 
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--linear` | Define a linear color space (2+ colors) | - |
+| `--plane` | Define a plane color space (dark light hue) | - |
 | `--cube` | Define a cube color space (8 key=color pairs) | - |
 | `--config` | Load color space from a JSON config file | - |
 | `--size` | Resolution per axis | 6 |
 | `--at` | Query a specific 1-based index (linear) | - |
+| `--xy` | Query plane with saturation,lightness (e.g., `3,5`) | - |
 | `--tint` | Query cube with alias:intensity pairs (e.g., `r:4,b:2`) | - |
 | `--interpolation` | Interpolation mode: oklch, lab, rgb, false | oklch |
 | `--format` | Output format: hex, hsl, rgb, oklch | hex |

package/dist/index.js

@@ -8950,6 +8950,21 @@ function generateCubeSpace(corners, stepsPerAxis, mode = "oklch") {
   }
   return colors2;
 }
+function generatePlaneSpace(dark, light, hue3, stepsPerAxis, mode = "oklch") {
+  const mix = (a2, b2, t2) => mixWithMode(a2, b2, t2, mode);
+  const max11 = stepsPerAxis - 1;
+  const colors2 = [];
+  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;
+      colors2.push(mix(bottom, top, ty));
+    }
+  }
+  return colors2;
+}
 var init_ColorSpaceEngine = __esm(() => {
   init_OklchEngine();
   init_chroma_js2();
@@ -8973,6 +8988,7 @@ Query colors from a color space defined by anchor colors
 USAGE
   ${cyan}rampa colorspace --cube key=color ... [options]${reset}
   ${cyan}rampa colorspace --linear color ... [options]${reset}
+  ${cyan}rampa colorspace --plane dark light hue [options]${reset}
   ${cyan}rampa colorspace --config file.json [options]${reset}
 
 COLOR SPACE DEFINITION
@@ -8982,6 +8998,9 @@ COLOR SPACE DEFINITION
   ${cyan}--linear color ...${reset}            ${dim}Define a LinearColorSpace from 2+ colors${reset}
                                   ${dim}Interpolates between first and last color${reset}
 
+  ${cyan}--plane dark light hue${reset}        ${dim}Define a PlaneColorSpace (2D saturation×lightness)${reset}
+                                  ${dim}dark=origin, light=achromatic anchor, hue=chromatic corner${reset}
+
   ${cyan}--config file.json${reset}            ${dim}Load color space from a JSON config file${reset}
 
 OPTIONS
@@ -8997,6 +9016,9 @@ QUERIES ${dim}(omit to output full palette)${reset}
   ${cyan}--at N${reset}                        ${dim}Query LinearColorSpace by 1-based index${reset}
                                   ${dim}Example: --at 12${reset}
 
+  ${cyan}--xy sat,light${reset}                ${dim}Query PlaneColorSpace by saturation,lightness${reset}
+                                  ${dim}Example: --xy 3,5${reset}
+
 OUTPUT
   ${cyan}--format type${reset}                 ${dim}Color format: hex (default), hsl, rgb, oklch${reset}
   ${cyan}--output type${reset}                 ${dim}Full palette format: text (default), json${reset}
@@ -9019,6 +9041,9 @@ EXAMPLES
   rampa colorspace --linear '#f00' '#0f0' '#00f' '#ff0' \\
                    --interpolation false --at 2
 
+  ${dim}# Plane: 2D saturation×lightness for a single hue${reset}
+  rampa colorspace --plane '#1e1e2e' '#cdd6f4' '#f38ba8' --size 6 --xy 3,5
+
   ${dim}# Query from config file${reset}
   rampa colorspace --config catppuccin.json --tint r:4,b:2
 `;
@@ -9080,6 +9105,30 @@ function parseColorspaceArgs(argv2) {
       }
       continue;
     }
+    if (arg === "--plane") {
+      args.mode = "plane";
+      i2++;
+      const planeColors = [];
+      while (i2 < argv2.length && !argv2[i2].startsWith("--")) {
+        const color = argv2[i2];
+        try {
+          chroma_js_default(color);
+        } catch {
+          console.error(`Invalid color: ${color}`);
+          process.exit(1);
+        }
+        planeColors.push(color);
+        i2++;
+      }
+      if (planeColors.length !== 3) {
+        console.error("PlaneColorSpace requires exactly 3 colors: dark light hue");
+        process.exit(1);
+      }
+      args.dark = planeColors[0];
+      args.light = planeColors[1];
+      args.hue = planeColors[2];
+      continue;
+    }
     if (arg === "--config") {
       args.mode = "config";
       args.configPath = argv2[++i2];
@@ -9112,6 +9161,12 @@ function parseColorspaceArgs(argv2) {
       i2++;
       continue;
     }
+    if (arg === "--xy") {
+      const parts = argv2[++i2].split(",");
+      args.xy = [parseInt(parts[0]), parseInt(parts[1])];
+      i2++;
+      continue;
+    }
     if (arg === "--format") {
       args.format = argv2[++i2];
       i2++;
@@ -9140,6 +9195,11 @@ function loadConfig(path) {
     if (config.type === "linear" || config.colors) {
       args.mode = "linear";
       args.colors = config.colors;
+    } else if (config.type === "plane") {
+      args.mode = "plane";
+      args.dark = config.dark;
+      args.light = config.light;
+      args.hue = config.hue;
     } else {
       args.mode = "cube";
       args.corners = config.corners;
@@ -9178,11 +9238,14 @@ function runColorspace(argv2) {
       ...Object.fromEntries(Object.entries(args).filter(([, v2]) => v2 !== undefined && v2 !== 0)),
       mode: config.mode,
       corners: config.corners,
-      colors: config.colors
+      colors: config.colors,
+      dark: config.dark,
+      light: config.light,
+      hue: config.hue
     };
   }
   if (args.size === 0) {
-    args.size = args.mode === "cube" ? 6 : 24;
+    args.size = args.mode === "linear" ? 24 : 6;
   }
   let palette;
   let aliases;
@@ -9202,6 +9265,12 @@ function runColorspace(argv2) {
     } else {
       palette = generateCubeSpace(cornerColors, args.size, args.interpolation);
     }
+  } else if (args.mode === "plane") {
+    if (!args.dark || !args.light || !args.hue) {
+      console.error("PlaneColorSpace requires 3 colors: dark light hue");
+      process.exit(1);
+    }
+    palette = generatePlaneSpace(args.dark, args.light, args.hue, args.size, args.interpolation === false ? "oklch" : args.interpolation);
   } else {
     if (!args.colors || args.colors.length < 2) {
       console.error("LinearColorSpace requires at least 2 colors");
@@ -9238,6 +9307,18 @@ function runColorspace(argv2) {
     console.log(formatColor2(palette[i2], args.format));
     return;
   }
+  if (args.xy !== undefined) {
+    if (args.mode !== "plane") {
+      console.error("--xy query is only supported with --plane mode");
+      process.exit(1);
+    }
+    const [sat, light] = args.xy;
+    const sx = Math.max(0, Math.min(args.size - 1, sat));
+    const ly = Math.max(0, Math.min(args.size - 1, light));
+    const index = sx * args.size + ly;
+    console.log(formatColor2(palette[index], args.format));
+    return;
+  }
   if (args.output === "json") {
     const formatted = palette.map((hex6) => formatColor2(hex6, args.format));
     console.log(JSON.stringify({ palette: formatted, size: palette.length }, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basiclines/rampa",
-  "version": "1.5.2",
+  "version": "1.7.0",
   "description": "Generate mathematically accurate color palettes from a base color",
   "type": "module",
   "bin": {