@lewishowles/cli-style 0.9.0 → 0.11.0

package/src/formatters/ansi.js

@@ -100,7 +100,7 @@ export function stripAnsi(value) {
  *     Coloured text, or the original text when colour is disabled.
  */
 function wrapColour(value, colour, options, createCode) {
-	const resolvedColour = resolveColourValue(colour);
+	const resolvedColour = resolveColourValue(colour, options);
 
 	if (options.colour !== true || resolvedColour === null) {
 		return value;
@@ -118,6 +118,14 @@ function wrapColour(value, colour, options, createCode) {
  *     ANSI foreground sequence.
  */
 function createForegroundCode(colour) {
+	if (colour === "default-foreground") {
+		return "\u001b[39m";
+	}
+
+	if (colour.startsWith("ansi-256:")) {
+		return `\u001b[38;5;${colour.slice("ansi-256:".length)}m`;
+	}
+
 	const { blue, green, red } = parseHexColour(colour);
 
 	return `\u001b[38;2;${red};${green};${blue}m`;
@@ -132,6 +140,14 @@ function createForegroundCode(colour) {
  *     ANSI background sequence.
  */
 function createBackgroundCode(colour) {
+	if (colour === "default-background") {
+		return "\u001b[49m";
+	}
+
+	if (colour.startsWith("ansi-256:")) {
+		return `\u001b[48;5;${colour.slice("ansi-256:".length)}m`;
+	}
+
 	const { blue, green, red } = parseHexColour(colour);
 
 	return `\u001b[48;2;${red};${green};${blue}m`;

package/src/gallery/render-gallery.js

@@ -4,9 +4,11 @@ import { commandResult } from "../patterns/command-result.js";
 import { compactDataTable } from "../patterns/compact-data-table.js";
 import { confirmationResult } from "../patterns/confirmation-result.js";
 import { diagnosticReport } from "../patterns/diagnostic-report.js";
+import { diffBlock } from "../patterns/diff-block.js";
 import { nextStepBlock } from "../patterns/next-step-block.js";
 import { taskSummary } from "../patterns/task-summary.js";
 import { stripAnsi } from "../formatters/ansi.js";
+import { renderSpinnerFrame } from "../interactive/spinner.js";
 import { barChart } from "../primitives/bar-chart.js";
 import { chip } from "../primitives/chip.js";
 import { divider } from "../primitives/divider.js";
@@ -15,6 +17,7 @@ import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
 import { rowGroup } from "../primitives/row-group.js";
+import { sparkline } from "../primitives/sparkline.js";
 import { span } from "../primitives/span.js";
 import { status } from "../primitives/status.js";
 import { step, stepProgress, stepStates } from "../primitives/step-progress.js";
@@ -115,7 +118,7 @@ export const galleryVariants = ["current", "no-colour", "no-unicode", "plain"];
 // Gallery sections available for focused output.
 export const gallerySections = ["primitives", "patterns"];
 
-// Pattern fixtures available for focused output and interactive search.
+// Fixtures available for focused output and interactive search.
 export const galleryFixtures = [
 	"diagnostic-report",
 	"reporter",
@@ -127,6 +130,9 @@ export const galleryFixtures = [
 	"compact-data-table-narrow",
 	"confirmation-result",
 	"next-step-block",
+	"diff-block",
+	"sparkline",
+	"spinner",
 ];
 
 /**
@@ -179,7 +185,7 @@ function renderVariant(variant, options, request) {
 	const sections = [];
 
 	if (request.fixture !== undefined) {
-		sections.push(renderPatterns(resolvedVariant.options, request.fixture));
+		sections.push(renderFocusedFixture(request.fixture, resolvedVariant.options));
 	} else {
 		if (request.section === undefined || request.section === "primitives") {
 			sections.push(renderPrimitives(resolvedVariant.options));
@@ -434,6 +440,36 @@ function renderPatterns(options, fixture) {
 		options,
 	);
 
+	const diff = diffBlock(
+		{
+			lines: [
+				{
+					text: "render()",
+					type: "header",
+				},
+				{
+					newLineNumber: 102,
+					text: "return nextStep;",
+					type: "added",
+				},
+				{
+					oldLineNumber: 101,
+					text: "return currentStep;",
+					type: "removed",
+				},
+				{
+					newLineNumber: 100,
+					oldLineNumber: 100,
+					text: "const currentStep = getStep();",
+					type: "context",
+				},
+			],
+			path: "src/render.js",
+			title: "Renderer change",
+		},
+		options,
+	);
+
 	const reporter = createReporter(options);
 
 	reporter.divider("Project setup", "Claude + Codex");
@@ -561,6 +597,7 @@ function renderPatterns(options, fixture) {
 		"compact-data-table-narrow": ["Compact data table (narrow)", narrowCompactTable],
 		"confirmation-result": ["Confirmation result", confirmation],
 		"diagnostic-report": ["Diagnostic report", report],
+		"diff-block": ["Diff block", diff],
 		"next-step-block": ["Next-step block", nextStep],
 		reporter: ["Reporter", reporterOutput],
 		"task-summary": ["Task summary", summary],
@@ -594,6 +631,9 @@ function renderPatterns(options, fixture) {
 		"Audit finding",
 		frameExample(audit, options),
 		"",
+		"Diff block",
+		frameExample(diff, options),
+		"",
 		"Compact data table",
 		frameExample(compactTable, options),
 		"",
@@ -622,6 +662,52 @@ function renderPatternFixture(fixture, options) {
 	return [fixture[0], frameExample(fixture[1], options)].join("\n");
 }
 
+/**
+ * Render the focused sparkline fixture.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Framed sparkline fixture output.
+ */
+function renderSparklineFixture(options) {
+	return ["Sparkline", frameExample(renderSparklineExample(options), options)].join("\n");
+}
+
+/**
+ * Render the focused spinner fixture.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Framed spinner fixture output.
+ */
+function renderSpinnerFixture(options) {
+	return ["Spinner", frameExample(renderSpinnerExample(options), options)].join("\n");
+}
+
+/**
+ * Render one fixture selected through `--fixture`.
+ *
+ * @param  {string}  fixture
+ *     Requested fixture name.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Framed fixture output.
+ */
+function renderFocusedFixture(fixture, options) {
+	if (fixture === "sparkline") {
+		return renderSparklineFixture(options);
+	}
+
+	if (fixture === "spinner") {
+		return renderSpinnerFixture(options);
+	}
+
+	return renderPatterns(options, fixture);
+}
+
 /**
  * Add gallery-only framing around one rendered example.
  *
@@ -665,9 +751,15 @@ function renderPrimitives(options) {
 		"Progress bars",
 		...renderProgressExamples(options),
 		"",
+		"Spinner",
+		renderSpinnerExample(options),
+		"",
 		"Bar charts",
 		renderBarChartExample(options),
 		"",
+		"Sparklines",
+		renderSparklineExample(options),
+		"",
 		"Tables",
 		renderTableExample(options),
 		"",
@@ -806,6 +898,75 @@ function renderBarChartExample(options) {
 	});
 }
 
+/**
+ * Render representative sparkline sequences.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Sparkline examples.
+ */
+function renderSparklineExample(options) {
+	const examples = [
+		{
+			label: "Rising",
+			tone: "success",
+			values: [1, 2, 3, 4, 5, 6],
+		},
+		{
+			label: "Falling",
+			tone: "danger",
+			values: [6, 5, 4, 3, 2, 1],
+		},
+		{
+			label: "Flat",
+			tone: "info",
+			values: [4, 4, 4, 4, 4, 4],
+		},
+		{
+			label: "Negative",
+			tone: "warning",
+			values: [-6, -4, -5, -2, -3, -1],
+		},
+		{
+			label: "Narrow mixed",
+			tone: "info",
+			values: [0, 10, -5, 5, 2, 8, -2],
+			width: 4,
+		},
+	];
+
+	return examples
+		.map((example) =>
+			sparkline({
+				...options,
+				...example,
+				width: example.width ?? 16,
+			}),
+		)
+		.join("\n");
+}
+
+/**
+ * Render static loading, success, and fail frames for the spinner primitive.
+ *
+ * The gallery shows fixed snapshots rather than a live animation, so no timer is started.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Spinner state examples.
+ */
+function renderSpinnerExample(options) {
+	const label = "Running task";
+
+	return [
+		renderSpinnerFrame(label, 0, options),
+		status(resultTypes.SUCCESS, "", { ...options, label }),
+		status(resultTypes.FAILED, "", { ...options, label }),
+	].join("\n");
+}
+
 /**
  * Render common progress values and tones.
  *

package/src/index.js

@@ -1,16 +1,25 @@
 export { createCliStyle, profiles } from "./create-cli-style.js";
 
 export { resolveProfile } from "./capability/resolve-profile.js";
-export { resolveTerminalCapabilities } from "./capability/terminal.js";
+export { resolveTerminalCapabilities, resolveTheme } from "./capability/terminal.js";
 export { isProfile } from "./profiles/profiles.js";
 
 export { renderHelp } from "./cli/help.js";
+export { parseCatalogueRequest, renderCatalogue } from "./cli/catalogue-command.js";
+export {
+	getRendererMetadata,
+	rendererCatalogue,
+	rendererNames,
+} from "./catalogue/renderer-catalogue.js";
+
 export {
 	adapterNames,
 	parseAdapterPathRequest,
 	renderAdapterPath,
 } from "./cli/adapter-path-command.js";
-export { parseRenderRequest, rendererNames, renderJsonInput } from "./cli/render-command.js";
+
+export { parseRenderRequest, renderJsonInput } from "./cli/render-command.js";
+
 export {
 	galleryFixtures,
 	gallerySections,
@@ -20,12 +29,14 @@ export {
 
 export { background, foreground, stripAnsi, style } from "./formatters/ansi.js";
 export { defaultWidth, minimumWidth, normaliseWidth } from "./formatters/width.js";
+export { renderSpinnerFrame, runSpinner, spinner } from "./interactive/spinner.js";
 export { agentTranscript } from "./patterns/agent-transcript.js";
 export { auditFinding } from "./patterns/audit-finding.js";
 export { commandResult } from "./patterns/command-result.js";
 export { compactDataTable } from "./patterns/compact-data-table.js";
 export { confirmationResult } from "./patterns/confirmation-result.js";
 export { diagnosticReport } from "./patterns/diagnostic-report.js";
+export { diffBlock } from "./patterns/diff-block.js";
 export { nextStepBlock } from "./patterns/next-step-block.js";
 export { taskSummary } from "./patterns/task-summary.js";
 export { barChart } from "./primitives/bar-chart.js";
@@ -36,10 +47,12 @@ export { panel } from "./primitives/panel.js";
 export { progressBar } from "./primitives/progress-bar.js";
 export { row } from "./primitives/row.js";
 export { rowGroup } from "./primitives/row-group.js";
+export { sparkline } from "./primitives/sparkline.js";
 export { span } from "./primitives/span.js";
 export { status } from "./primitives/status.js";
 export { step, stepProgress, stepStates } from "./primitives/step-progress.js";
 export { table } from "./primitives/table.js";
+
 export {
 	createReporter,
 	renderGroup,
@@ -47,10 +60,12 @@ export {
 	renderReporterStatus,
 	renderSection,
 } from "./reporters/create-reporter.js";
+
 export {
 	chartColours,
 	chipColours,
 	colourTokens,
+	diffColours,
 	getColourToken,
 	getToneColour,
 	panelColours,
@@ -58,8 +73,10 @@ export {
 	resolveColourValue,
 	tableColours,
 	terminalColours,
+	themes,
 	toneColours,
 } from "./theme/colours.js";
+
 export {
 	getHighestSeverityResult,
 	getResultSymbol,

package/src/interactive/spinner.js

@@ -0,0 +1,335 @@
+import { foreground } from "../formatters/ansi.js";
+import { profiles } from "../profiles/profiles.js";
+import { status } from "../primitives/status.js";
+import { resultTypes } from "../theme/results.js";
+
+// Frame glyphs cycled while a spinner is animating.
+const unicodeFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const asciiFrames = ["-", "\\", "|", "/"];
+
+// Time between animated frame redraws.
+const frameIntervalMs = 80;
+
+// Built from a character code, rather than a string escape, so the control byte stays visible in diffs.
+const escapeCharacter = String.fromCharCode(27);
+
+// ANSI cursor and line-clear sequences used only on an interactive TTY.
+const hideCursor = `${escapeCharacter}[?25l`;
+const showCursor = `${escapeCharacter}[?25h`;
+const clearLine = `\r${escapeCharacter}[2K`;
+
+// Profiles that always use the static, non-animated spinner output.
+const nonInteractiveProfiles = new Set([
+	profiles.AGENT,
+	profiles.CI,
+	profiles.JSON,
+	profiles.PLAIN,
+]);
+
+// Spinner currently writing output; only one may be active at a time.
+let runningSpinner = null;
+
+// Whether the process-exit cleanup listener has been registered.
+let cleanupRegistered = false;
+
+/**
+ * Start a spinner and return a manual handle for advanced lifecycle control.
+ *
+ * @param  {string}  text
+ *     Initial spinner text.
+ * @param  {object}  options
+ *     Rendering and capability options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {boolean}  options.isTty
+ *     Whether stdout is an interactive terminal.
+ * @param  {string}  options.profile
+ *     Resolved output profile.
+ * @param  {object}  options.stream
+ *     Writable stream the spinner writes to. Defaults to `process.stderr`.
+ * @param  {boolean}  options.unicode
+ *     Whether Unicode symbols should be used.
+ * @returns  {object}
+ *     Handle with `update`, `succeed`, `fail`, and `stop` methods.
+ */
+export function spinner(text, options = {}) {
+	if (runningSpinner !== null) {
+		throw new Error("A spinner is already active; stop it before starting another.");
+	}
+
+	const state = {
+		active: true,
+		frameIndex: 0,
+		interactive: isInteractive(options),
+		options,
+		stream: options.stream ?? process.stderr,
+		text,
+		timer: null,
+	};
+
+	runningSpinner = state;
+	registerCleanup();
+	startSpinnerState(state);
+
+	return {
+		fail: (finalText) => finishSpinnerState(state, resultTypes.FAILED, finalText),
+		stop: () => stopSpinnerState(state),
+		succeed: (finalText) => finishSpinnerState(state, resultTypes.SUCCESS, finalText),
+		update: (nextText) => updateSpinnerState(state, nextText),
+	};
+}
+
+/**
+ * Run an async task behind a spinner, resolving or rejecting it unchanged.
+ *
+ * @param  {string}  text
+ *     Spinner text shown while the task runs.
+ * @param  {Function}  fn
+ *     Async task to run.
+ * @param  {object}  options
+ *     Rendering and capability options, forwarded to `spinner()`.
+ * @returns  {Promise<*>}
+ *     Resolved value of `fn`, or its rejection rethrown after cleanup.
+ */
+export async function runSpinner(text, fn, options = {}) {
+	const handle = spinner(text, options);
+
+	try {
+		const result = await fn();
+
+		handle.succeed();
+
+		return result;
+	} catch (error) {
+		handle.fail();
+
+		throw error;
+	} finally {
+		handle.stop();
+	}
+}
+
+/**
+ * Render one animated spinner frame without starting a timer.
+ *
+ * @param  {string}  text
+ *     Spinner text to show alongside the frame glyph.
+ * @param  {number}  frameIndex
+ *     Frame position to render.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {boolean}  options.unicode
+ *     Whether Unicode symbols should be used.
+ * @returns  {string}
+ *     Rendered frame line.
+ */
+export function renderSpinnerFrame(text, frameIndex, options = {}) {
+	const frames = options.unicode === false ? asciiFrames : unicodeFrames;
+	const glyph = frames[frameIndex % frames.length];
+	const colouredGlyph = foreground(glyph, "info", options);
+
+	return `${colouredGlyph} ${text}`;
+}
+
+/**
+ * Determine whether a spinner should animate on the current output target.
+ *
+ * @param  {object}  options
+ *     Rendering and capability options.
+ * @returns  {boolean}
+ *     Whether the spinner can animate.
+ */
+function isInteractive(options) {
+	return options.isTty === true && !nonInteractiveProfiles.has(options.profile);
+}
+
+/**
+ * Write the initial spinner output for a state, starting the frame timer when interactive.
+ *
+ * @param  {object}  state
+ *     Spinner state to start.
+ * @returns  {void}
+ */
+function startSpinnerState(state) {
+	if (!state.interactive) {
+		state.stream.write(
+			`${status(resultTypes.INFO, "", { ...state.options, label: state.text })}\n`,
+		);
+
+		return;
+	}
+
+	state.stream.write(hideCursor);
+	renderFrame(state);
+
+	state.timer = setInterval(() => tickSpinnerState(state), frameIntervalMs);
+	state.timer.unref?.();
+}
+
+/**
+ * Advance and redraw the animated frame for a state.
+ *
+ * @param  {object}  state
+ *     Spinner state to advance.
+ * @returns  {void}
+ */
+function tickSpinnerState(state) {
+	state.frameIndex += 1;
+
+	renderFrame(state);
+}
+
+/**
+ * Redraw the current animated frame in place.
+ *
+ * @param  {object}  state
+ *     Spinner state to render.
+ * @returns  {void}
+ */
+function renderFrame(state) {
+	state.stream.write(
+		`${clearLine}${renderSpinnerFrame(state.text, state.frameIndex, state.options)}`,
+	);
+}
+
+/**
+ * Update the text shown by an active spinner.
+ *
+ * @param  {object}  state
+ *     Spinner state to update.
+ * @param  {string}  nextText
+ *     Replacement spinner text.
+ * @returns  {void}
+ */
+function updateSpinnerState(state, nextText) {
+	if (!state.active) {
+		return;
+	}
+
+	state.text = nextText;
+
+	if (state.interactive) {
+		renderFrame(state);
+	}
+}
+
+/**
+ * Stop a spinner without printing a result line.
+ *
+ * @param  {object}  state
+ *     Spinner state to stop.
+ * @returns  {void}
+ */
+function stopSpinnerState(state) {
+	if (!state.active) {
+		return;
+	}
+
+	state.active = false;
+	clearSpinnerTimer(state);
+
+	if (state.interactive) {
+		state.stream.write(`${clearLine}${showCursor}`);
+	}
+
+	if (runningSpinner === state) {
+		runningSpinner = null;
+	}
+}
+
+/**
+ * Stop a spinner and print a success or fail result line.
+ *
+ * @param  {object}  state
+ *     Spinner state to finish.
+ * @param  {string}  resultType
+ *     Result type to display, from `resultTypes`.
+ * @param  {string}  finalText
+ *     Optional replacement text for the result line.
+ * @returns  {void}
+ */
+function finishSpinnerState(state, resultType, finalText) {
+	if (!state.active) {
+		return;
+	}
+
+	state.active = false;
+	clearSpinnerTimer(state);
+
+	const label = finalText ?? state.text;
+	const line = status(resultType, "", { ...state.options, label });
+
+	if (state.interactive) {
+		state.stream.write(`${clearLine}${showCursor}${line}\n`);
+	} else {
+		state.stream.write(`${line}\n`);
+	}
+
+	if (runningSpinner === state) {
+		runningSpinner = null;
+	}
+}
+
+/**
+ * Clear an active state's frame timer, when one exists.
+ *
+ * @param  {object}  state
+ *     Spinner state to clear.
+ * @returns  {void}
+ */
+function clearSpinnerTimer(state) {
+	if (state.timer !== null) {
+		clearInterval(state.timer);
+		state.timer = null;
+	}
+}
+
+/**
+ * Restore the cursor for an active, interactive spinner, stop its frame timer, and clear the
+ * running reference.
+ *
+ * @returns  {void}
+ */
+function restoreRunningSpinner() {
+	if (runningSpinner !== null) {
+		clearSpinnerTimer(runningSpinner);
+
+		if (runningSpinner.interactive) {
+			runningSpinner.stream.write(`${clearLine}${showCursor}`);
+		}
+	}
+
+	runningSpinner = null;
+}
+
+/**
+ * Restore the cursor on SIGINT, then re-raise the signal so the process still terminates with
+ * Node's default SIGINT exit code. A listener that did not re-raise would silently replace that
+ * default termination, leaving the process running whenever other work still holds the event loop
+ * open.
+ *
+ * @returns  {void}
+ */
+function handleSpinnerSigint() {
+	restoreRunningSpinner();
+	process.removeListener("SIGINT", handleSpinnerSigint);
+	process.kill(process.pid, "SIGINT");
+}
+
+/**
+ * Register process-exit and SIGINT listeners, once, that restore the cursor for an interrupted spinner.
+ *
+ * @returns  {void}
+ */
+function registerCleanup() {
+	if (cleanupRegistered) {
+		return;
+	}
+
+	cleanupRegistered = true;
+
+	process.on("exit", restoreRunningSpinner);
+	process.on("SIGINT", handleSpinnerSigint);
+}