@theme-registry/refract 0.1.3 → 0.1.5

package/dist/cli.js

@@ -8004,7 +8004,7 @@ const RATIO_VALUES = {
  * overlap, so a scaffolded literal and an authored `harmony:` key agree. `pentadic` is local — the
  * subsystem has no five-way scheme, and the scaffolder needs one to reach five brand colours.
  */
-const SCHEME_ROTATIONS = {
+const SCHEME_ROTATIONS$1 = {
     complement: [180],
     analogous: [-30, 30],
     "split-complement": [150, 210],
@@ -8106,7 +8106,7 @@ const defaultSchemeFor = (brandCount) => {
     return "pentadic";
 };
 /** Schemes that produce exactly `brandCount − 1` members — the valid choices at that count. */
-const schemesFor = (brandCount) => Object.keys(SCHEME_ROTATIONS).filter((s) => SCHEME_ROTATIONS[s].length === brandCount - 1);
+const schemesFor = (brandCount) => Object.keys(SCHEME_ROTATIONS$1).filter((s) => SCHEME_ROTATIONS$1[s].length === brandCount - 1);
 /**
  * The contrast gate. Builds the palette set, audits every text-on-base pairing, and walks the
  * lightness of each failing colour down one OKLCH point at a time until it clears the bar.
@@ -8202,7 +8202,7 @@ function scaffoldTheme(answers) {
     }
     else if (brandCount > 1) {
         const scheme = (_g = answers.scheme) !== null && _g !== void 0 ? _g : defaultSchemeFor(brandCount);
-        const rotations = SCHEME_ROTATIONS[scheme];
+        const rotations = SCHEME_ROTATIONS$1[scheme];
         if (!rotations)
             throw new Error(`Unknown harmony scheme "${scheme}".`);
         rotations.slice(0, brandCount - 1).forEach((deg, i) => {
@@ -8430,16 +8430,22 @@ function runCreate(options) {
 }
 
 /**
- * Minimal interactive prompts over `node:readline` (Node-only).
+ * Interactive prompts over `node:readline` and raw stdin (Node-only).
  *
  * The package ships zero runtime dependencies and this is the build layer, so rather than pull in a
- * prompt library for one command these are the four shapes the CLI actually needs. They are
- * line-based, not raw-mode: you type a number or a value and press Enter. That loses arrow-key
- * navigation, and buys a prompt that behaves predictably over SSH, in CI logs, in a Docker build,
- * and under any terminal that doesn't grant raw mode — where a fancier prompt would hang or garble.
+ * prompt library these are the shapes the CLIs actually need, implemented directly.
+ *
+ * Three tiers, chosen per call:
+ *
+ *  1. **Raw mode** (a TTY that grants `setRawMode`) — arrow keys move, space toggles, Enter confirms.
+ *     What people expect from `npm create`.
+ *  2. **Line mode** (a TTY that refuses raw mode — some CI shells, some remote terminals) — the same
+ *     questions answered by typing a number. Plainer, but never wedged.
+ *  3. **Non-interactive** (no TTY at all: a pipe, CI, `--yes`) — every prompt takes its default
+ *     without blocking, so a scripted run can't deadlock on stdin that will never arrive.
  *
- * Every prompt is **non-interactive-safe**: with no TTY (a pipe, CI, `--yes`) it takes the default
- * without blocking, so a scripted run never deadlocks waiting on stdin that will never arrive.
+ * Key handling is a **pure reducer** (`applyKey`), so navigation is unit-testable without a terminal;
+ * the raw loop is only plumbing around it.
  */
 /** ANSI helpers — no-ops when the stream isn't a TTY, so piped output stays clean. */
 const useColor = () => Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
@@ -8449,10 +8455,131 @@ const dim = (s) => paint("2", s);
 const cyan = (s) => paint("36", s);
 const green = (s) => paint("32", s);
 const yellow = (s) => paint("33", s);
+/** Terminal control, named so the rendering below reads as intent rather than escape soup. */
+const cursorUp = (n) => (n > 0 ? `\u001b[${n}A` : "");
+const CLEAR_DOWN = "\u001b[0J";
+const HIDE_CURSOR = "\u001b[?25l";
+const SHOW_CURSOR = "\u001b[?25h";
+/**
+ * Does this terminal do 24-bit colour? `COLORTERM` is the only real signal, and plenty of capable
+ * terminals (Apple Terminal among them) never set it — so a missing value means "approximate", not
+ * "give up". Gating swatches on truecolor alone would silently delete them for those users.
+ */
+const truecolor = () => { var _a; return /truecolor|24bit/i.test((_a = process.env.COLORTERM) !== null && _a !== void 0 ? _a : ""); };
+/** Nearest xterm-256 colour-cube index for an RGB triple — the fallback when 24-bit isn't offered. */
+const to256 = (r, g, b) => {
+    const axis = (v) => (v < 48 ? 0 : v < 114 ? 1 : Math.min(5, Math.round((v - 35) / 40)));
+    return 16 + 36 * axis(r) + 6 * axis(g) + axis(b);
+};
+/**
+ * `#rrggbb` → a coloured block: exact in 24-bit terminals, approximated in 256-colour ones, and
+ * empty when there's no colour at all (a pipe, `NO_COLOR`) so redirected output stays clean.
+ *
+ * Approximating is right here — the swatch is a preview, and the exact value is written to the theme
+ * file regardless. An approximately-right hue beats a blank space.
+ */
+function swatch(hex, width = 2) {
+    if (!useColor())
+        return "";
+    const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        return "";
+    const n = parseInt(m[1], 16);
+    const [r, g, b] = [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+    const bg = truecolor() ? `48;2;${r};${g};${b}` : `48;5;${to256(r, g, b)}`;
+    return `\u001b[${bg}m${" ".repeat(width)}\u001b[0m`;
+}
+/** Decode a raw stdin chunk into a {@link ListKey}. Arrows arrive as escape sequences; j/k mirror vim. */
+function decodeKey(chunk) {
+    switch (chunk) {
+        case "\u001b[A":
+        case "k":
+            return "up";
+        case "\u001b[B":
+        case "j":
+            return "down";
+        case " ":
+            return "space";
+        case "\r":
+        case "\n":
+            return "submit";
+        case "a":
+            return "all";
+        case "\u0003": // Ctrl-C
+        case "\u001b": // bare Escape
+            return "cancel";
+        default:
+            return "none";
+    }
+}
 /**
- * A prompt session. Holds one readline interface for the whole interview so stdin is opened and
- * closed exactly once; `interactive` is false when there's no TTY, and every ask short-circuits to
- * its default.
+ * Split one stdin chunk into the keys it contains.
+ *
+ * A held-down arrow key, or fast typing, delivers several sequences in a single `data` event — so
+ * decoding the chunk as one key would swallow all but the first and make the list feel like it drops
+ * input. Escape sequences (`ESC [ <letter>`) are taken as a unit; everything else is one key each.
+ */
+function decodeKeys(chunk) {
+    const keys = [];
+    for (let i = 0; i < chunk.length;) {
+        if (chunk[i] === "\u001b" && chunk[i + 1] === "[" && i + 2 < chunk.length) {
+            keys.push(decodeKey(chunk.slice(i, i + 3)));
+            i += 3;
+        }
+        else {
+            keys.push(decodeKey(chunk[i]));
+            i += 1;
+        }
+    }
+    return keys;
+}
+/**
+ * Advance a list prompt by one key. Pure — no I/O — so navigation is testable without a terminal.
+ *
+ * The cursor **wraps** at both ends: with six options, up from the first should land on the last
+ * rather than stick. `space` and `a` toggle only in multi mode; in single mode Enter is the commit,
+ * so space would be ambiguous.
+ */
+function applyKey(state, key, count, multi) {
+    if (state.done || state.cancelled || count === 0)
+        return state;
+    switch (key) {
+        case "up":
+            return { ...state, cursor: (state.cursor - 1 + count) % count };
+        case "down":
+            return { ...state, cursor: (state.cursor + 1) % count };
+        case "space": {
+            if (!multi)
+                return state;
+            const next = new Set(state.selected);
+            if (next.has(state.cursor))
+                next.delete(state.cursor);
+            else
+                next.add(state.cursor);
+            return { ...state, selected: next };
+        }
+        case "all": {
+            if (!multi)
+                return state;
+            const everything = state.selected.size === count;
+            return {
+                ...state,
+                selected: everything ? new Set() : new Set(Array.from({ length: count }, (_, i) => i)),
+            };
+        }
+        case "submit":
+            return { ...state, done: true };
+        case "cancel":
+            return { ...state, cancelled: true };
+        default:
+            return state;
+    }
+}
+/** Can we drive the terminal directly? Some TTYs (and most CI) don't grant raw mode. */
+const rawCapable = () => Boolean(process.stdin.isTTY) && typeof process.stdin.setRawMode === "function";
+/**
+ * A prompt session. Holds at most one readline interface, so stdin is opened and closed once;
+ * `interactive` is false when there's no TTY, and every ask short-circuits to its default.
  */
 class Prompter {
     constructor(interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY)) {
@@ -8471,7 +8598,11 @@ class Prompter {
     question(text) {
         return new Promise(resolve => this.io.question(text, answer => resolve(answer)));
     }
-    /** Print a line to stdout. Kept on the prompter so command code never touches `process.stdout`. */
+    /** Raw write, no newline — for cursor control during a live render. */
+    out(s) {
+        process.stdout.write(s);
+    }
+    /** Print a line. Kept on the prompter so command code never touches `process.stdout`. */
     write(line = "") {
         process.stdout.write(`${line}\n`);
     }
@@ -8498,11 +8629,140 @@ class Prompter {
         });
         return Number(answer);
     }
-    /** Pick one. Answers are 1-based indices; blank takes the default (the first choice unless given). */
+    /** Pick one — arrows to move, Enter to choose. */
     async select(label, choices, defaultIndex = 0) {
-        var _a, _b;
+        var _a, _b, _c;
         if (!this.interactive || choices.length === 1)
             return (_b = (_a = choices[defaultIndex]) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : choices[0].value;
+        if (rawCapable()) {
+            const picked = await this.runList(label, choices, {
+                multi: false,
+                cursor: defaultIndex,
+                selected: new Set(),
+            });
+            return choices[(_c = picked[0]) !== null && _c !== void 0 ? _c : defaultIndex].value;
+        }
+        return this.selectByNumber(label, choices, defaultIndex);
+    }
+    /** Pick any — arrows to move, space to toggle, `a` for all/none, Enter to confirm. */
+    async multiselect(label, choices, preselected) {
+        var _a;
+        if (!this.interactive)
+            return preselected.map(i => choices[i].value);
+        if (rawCapable()) {
+            const picked = await this.runList(label, choices, {
+                multi: true,
+                cursor: (_a = preselected[0]) !== null && _a !== void 0 ? _a : 0,
+                selected: new Set(preselected),
+            });
+            return picked.map(i => choices[i].value);
+        }
+        return this.multiselectByNumber(label, choices, preselected);
+    }
+    /**
+     * The raw-mode list loop. Renders in place: each keypress rewinds over the block just drawn and
+     * repaints it, so the list stays put instead of scrolling the terminal away.
+     *
+     * Any readline interface is closed first — it would otherwise swallow the keystrokes we need.
+     * `cleanup` always restores the terminal (raw mode off, cursor shown), including on cancel, so a
+     * Ctrl-C can't leave the shell in a state where typing is invisible.
+     */
+    runList(label, choices, init) {
+        this.close(); // readline and raw mode can't both own stdin
+        const stdin = process.stdin;
+        const { multi } = init;
+        let state = {
+            cursor: Math.max(0, Math.min(init.cursor, choices.length - 1)),
+            selected: init.selected,
+            done: false,
+            cancelled: false,
+        };
+        let painted = 0;
+        const help = multi ? "↑↓ move · space toggle · a all · enter confirm" : "↑↓ move · enter select";
+        // Pad labels so the hints line up into a column — a ragged right edge is most of why a long
+        // option list reads as noise.
+        const widest = choices.reduce((w, c) => Math.max(w, c.label.length), 0);
+        const frame = () => {
+            const rows = choices.map((c, i) => {
+                var _a;
+                const here = i === state.cursor;
+                // Focus and selection are SEPARATE signals and both need to be visible: the caret says
+                // where you are, the box says what's chosen. Showing only one (as this did) leaves a
+                // multi-select where you can't tell what the keys will act on.
+                const caret = here ? green("❯") : " ";
+                const box = multi ? (state.selected.has(i) ? green("[✓]") : dim("[ ]")) : "";
+                const name = here ? bold(c.label) : c.label;
+                const pad = " ".repeat(Math.max(0, widest - c.label.length));
+                const blocks = ((_a = c.swatches) !== null && _a !== void 0 ? _a : []).map(s => swatch(s)).filter(Boolean).join(" ");
+                const art = blocks ? `  ${blocks}` : "";
+                const hint = c.hint ? `  ${dim(c.hint)}` : "";
+                return `  ${caret} ${box ? `${box} ` : ""}${name}${pad}${art}${hint}`;
+            });
+            return [`${cyan("?")} ${bold(label)} ${dim(help)}`, ...rows].join("\n");
+        };
+        const paintFrame = () => {
+            if (painted)
+                this.out(cursorUp(painted) + CLEAR_DOWN);
+            const text = frame();
+            this.out(`${text}\n`);
+            painted = text.split("\n").length;
+        };
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                stdin.removeListener("data", onData);
+                stdin.removeListener("end", onEnd);
+                if (stdin.isTTY)
+                    stdin.setRawMode(false);
+                stdin.pause();
+                this.out(SHOW_CURSOR);
+            };
+            /**
+             * stdin closed while we were waiting — a piped run, a closed terminal, a killed parent. There
+             * is no further input coming, so commit what's on screen instead of blocking forever.
+             */
+            const onEnd = () => {
+                const chosen = multi ? [...state.selected].sort((a, b) => a - b) : [state.cursor];
+                this.out(cursorUp(painted) + CLEAR_DOWN);
+                cleanup();
+                resolve(chosen);
+            };
+            const onData = (chunk) => {
+                // One event can carry several keys (a held-down arrow); apply them all, then paint once.
+                for (const key of decodeKeys(chunk)) {
+                    state = applyKey(state, key, choices.length, multi);
+                    if (state.done || state.cancelled)
+                        break;
+                }
+                if (state.cancelled) {
+                    this.out(cursorUp(painted) + CLEAR_DOWN);
+                    cleanup();
+                    reject(new Error("Cancelled."));
+                    return;
+                }
+                if (state.done) {
+                    const chosen = multi ? [...state.selected].sort((a, b) => a - b) : [state.cursor];
+                    // Replace the live block with a one-line record of the answer, so a finished interview
+                    // reads back as a transcript rather than a wall of spent menus.
+                    this.out(cursorUp(painted) + CLEAR_DOWN);
+                    const summary = chosen.length ? chosen.map(i => choices[i].label).join(", ") : "none";
+                    this.write(`${cyan("?")} ${bold(label)} ${dim("›")} ${green(summary)}`);
+                    cleanup();
+                    resolve(chosen);
+                    return;
+                }
+                paintFrame();
+            };
+            stdin.setRawMode(true);
+            stdin.resume();
+            stdin.setEncoding("utf8");
+            this.out(HIDE_CURSOR);
+            stdin.on("data", onData);
+            stdin.on("end", onEnd);
+            paintFrame();
+        });
+    }
+    /** Line-mode fallback: pick one by number. */
+    async selectByNumber(label, choices, defaultIndex) {
         this.write(`${cyan("?")} ${bold(label)}`);
         choices.forEach((c, i) => {
             const marker = i === defaultIndex ? green("❯") : " ";
@@ -8519,14 +8779,9 @@ class Prompter {
             this.write(`  ${yellow("!")} Enter a number between 1 and ${choices.length}.`);
         }
     }
-    /**
-     * Pick any. Answers are comma-separated indices; blank keeps the pre-selected set, and an explicit
-     * `none` clears it — otherwise there'd be no way to deselect everything with a line-based prompt.
-     */
-    async multiselect(label, choices, preselected) {
-        if (!this.interactive)
-            return preselected.map(i => choices[i].value);
-        this.write(`${cyan("?")} ${bold(label)} ${dim("(comma-separated, blank = keep, \"none\" = clear)")}`);
+    /** Line-mode fallback: pick any by comma-separated numbers. */
+    async multiselectByNumber(label, choices, preselected) {
+        this.write(`${cyan("?")} ${bold(label)} ${dim('(comma-separated, blank = keep, "none" = clear)')}`);
         choices.forEach((c, i) => {
             const on = preselected.includes(i);
             const hint = c.hint ? ` ${dim(`— ${c.hint}`)}` : "";
@@ -8547,6 +8802,19 @@ class Prompter {
     }
 }
 
+/**
+ * The hues a scheme derives from a seed — the same rotations the generator will bake, so the
+ * preview beside each option is the palette you'd actually get, not an illustration.
+ */
+const SCHEME_ROTATIONS = {
+    complement: [180],
+    analogous: [-30, 30],
+    "split-complement": [150, 210],
+    triadic: [120, 240],
+    tetradic: [90, 180, 270],
+    pentadic: [72, 144, 216, 288],
+};
+const schemeHues = (seedHex, scheme) => { var _a; return ((_a = SCHEME_ROTATIONS[scheme]) !== null && _a !== void 0 ? _a : []).map(deg => convertRgbToHex(parseColor(rotateHue(seedHex, deg)).rgb)); };
 /** What each harmony scheme is for, in one line — the names mean nothing to most people. */
 const SCHEME_HINTS = {
     complement: "one companion, 180° opposite — maximum separation",
@@ -8589,7 +8857,9 @@ async function promptCreateAnswers(p, given = {}) {
     var _a, _b, _c, _d, _e, _f, _g, _h;
     const seed = (_a = given.seed) !== null && _a !== void 0 ? _a : (await p.text("Primary colour", "#4c6ef5", isColor));
     const lightness = Math.round(rgbToOklch(parseColor(seed).rgb).L * 10) / 10;
-    p.write(`  ${dim(`parsed · lightness ${lightness}% — lands at ≈${nearestLadderStep(lightness)} on the ladder`)}`);
+    const seedHex = convertRgbToHex(parseColor(seed).rgb);
+    const chip = swatch(seedHex, 3);
+    p.write(`  ${chip ? `${chip} ` : ""}${dim(`${seedHex} · lightness ${lightness}% — lands at ≈${nearestLadderStep(lightness)} on the ladder`)}`);
     p.write();
     const manual = Boolean(given.manual);
     let brandCount = 2;
@@ -8612,7 +8882,14 @@ async function promptCreateAnswers(p, given = {}) {
         const options = schemesFor(brandCount);
         scheme = (_c = given.scheme) !== null && _c !== void 0 ? _c : defaultSchemeFor(brandCount);
         if (!given.scheme && options.length > 1) {
-            scheme = await p.select("Harmony scheme", options.map(s => ({ value: s, label: s, hint: SCHEME_HINTS[s] })), Math.max(0, options.indexOf(scheme)));
+            // Show the hues each scheme actually produces. "split-complement" is a word; two blocks of
+            // real colour beside the seed is the thing you're choosing between.
+            scheme = await p.select("Harmony scheme", options.map(s => ({
+                value: s,
+                label: s,
+                hint: SCHEME_HINTS[s],
+                swatches: [seedHex, ...schemeHues(seedHex, s)],
+            })), Math.max(0, options.indexOf(scheme)));
         }
         if (scheme && brandCount > 1) {
             p.write(`  ${dim(`→ ${scheme} · each member becomes its own palette with a full ladder`)}`);