@lewishowles/cli-style 0.9.0 → 0.10.0

package/src/primitives/sparkline.js

@@ -0,0 +1,209 @@
+import { foreground } from "../formatters/ansi.js";
+import { getToneColour } from "../theme/colours.js";
+
+// Sparklines balance useful resolution with compact terminal output.
+const defaultWidth = 20;
+
+// Success gives an unconfigured trend a familiar positive semantic tone.
+const defaultTone = "success";
+
+// Unicode levels show eight graduated values without needing colour.
+const unicodeSymbols = "▁▂▃▄▅▆▇█";
+
+// ASCII levels provide the same eight-step visual fallback.
+const asciiSymbols = "._-:=+*#";
+
+/**
+ * Render a compact trend with stable numeric context.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {string}  options.label
+ *     Optional trend label.
+ * @param  {string}  options.tone
+ *     Semantic colour tone for the trend.
+ * @param  {boolean}  options.unicode
+ *     Whether graduated Unicode characters should be used.
+ * @param  {number[]}  options.values
+ *     Finite numeric values in time order.
+ * @param  {number}  options.width
+ *     Maximum number of plotted samples.
+ * @returns  {string}
+ *     Rendered sparkline, or an empty string for unusable values.
+ */
+export function sparkline(options = {}) {
+	const values = normaliseValues(options.values);
+
+	if (values.length === 0) {
+		return "";
+	}
+
+	const range = resolveRange(values);
+	const width = normaliseWidth(options.width);
+	const sampledValues = sampleValues(values, width, range);
+	const symbols = options.unicode === false ? asciiSymbols : unicodeSymbols;
+	const trend = sampledValues.map((value) => renderValue(value, range, symbols)).join("");
+	const numericText = `latest=${values.at(-1)} min=${range.minimum} max=${range.maximum}`;
+
+	const label =
+		typeof options.label === "string" && options.label !== "" ? `${options.label}: ` : "";
+
+	const renderedTrend = renderTrend(trend, options);
+
+	return `${label}${renderedTrend} ${numericText}`;
+}
+
+/**
+ * Return finite numeric values when the input is usable.
+ *
+ * @param  {*}  values
+ *     Requested trend values.
+ * @returns  {number[]}
+ *     Finite values, or an empty array.
+ */
+function normaliseValues(values) {
+	if (
+		!Array.isArray(values) ||
+		values.length === 0 ||
+		values.some((value) => !Number.isFinite(value))
+	) {
+		return [];
+	}
+
+	return values;
+}
+
+/**
+ * Return a usable positive integer plot width.
+ *
+ * @param  {number}  width
+ *     Requested plot width.
+ * @returns  {number}
+ *     Positive integer width.
+ */
+function normaliseWidth(width) {
+	if (!Number.isFinite(width)) {
+		return defaultWidth;
+	}
+
+	return Math.max(Math.floor(width), 1);
+}
+
+/**
+ * Resolve the shared scale and extrema indexes for a trend.
+ *
+ * @param  {number[]}  values
+ *     Finite trend values.
+ * @returns  {object}
+ *     Trend range and first extrema indexes.
+ */
+function resolveRange(values) {
+	let minimum = values[0];
+	let maximum = values[0];
+	let minimumIndex = 0;
+	let maximumIndex = 0;
+
+	for (let index = 1; index < values.length; index += 1) {
+		if (values[index] < minimum) {
+			minimum = values[index];
+			minimumIndex = index;
+		}
+
+		if (values[index] > maximum) {
+			maximum = values[index];
+			maximumIndex = index;
+		}
+	}
+
+	return {
+		maximum,
+		maximumIndex,
+		minimum,
+		minimumIndex,
+	};
+}
+
+/**
+ * Reduce values to deterministic plotted samples while retaining key points.
+ *
+ * @param  {number[]}  values
+ *     Finite trend values.
+ * @param  {number}  width
+ *     Maximum number of plotted samples.
+ * @param  {object}  range
+ *     Shared trend range and extrema indexes.
+ * @returns  {number[]}
+ *     Sampled values in their original order.
+ */
+function sampleValues(values, width, range) {
+	if (values.length <= width) {
+		return values;
+	}
+
+	const latestIndex = values.length - 1;
+	const requiredIndexes = [...new Set([latestIndex, range.minimumIndex, range.maximumIndex])];
+	const selectedIndexes = new Set(requiredIndexes.slice(0, width));
+
+	const evenlySpacedIndexes = Array.from({ length: width }, (_, index) =>
+		Math.round((index * (values.length - 1)) / Math.max(width - 1, 1)),
+	);
+
+	for (const index of evenlySpacedIndexes) {
+		if (selectedIndexes.size >= width) {
+			break;
+		}
+
+		selectedIndexes.add(index);
+	}
+
+	for (let index = 0; selectedIndexes.size < width; index += 1) {
+		selectedIndexes.add(index);
+	}
+
+	return [...selectedIndexes].sort((left, right) => left - right).map((index) => values[index]);
+}
+
+/**
+ * Map one value onto the active graduated character set.
+ *
+ * @param  {number}  value
+ *     Value to render.
+ * @param  {object}  range
+ *     Full trend range used for the shared scale.
+ * @param  {string}  symbols
+ *     Graduated characters.
+ * @returns  {string}
+ *     One trend character.
+ */
+function renderValue(value, range, symbols) {
+	if (range.minimum === range.maximum) {
+		return symbols[Math.floor((symbols.length - 1) / 2)];
+	}
+
+	const ratio = (value - range.minimum) / (range.maximum - range.minimum);
+	const symbolIndex = Math.round(ratio * (symbols.length - 1));
+
+	return symbols[symbolIndex];
+}
+
+/**
+ * Apply a semantic tone only when colour output is explicitly enabled.
+ *
+ * @param  {string}  trend
+ *     Uncoloured trend text.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Trend text with optional ANSI colour.
+ */
+function renderTrend(trend, options) {
+	if (options.colour !== true) {
+		return trend;
+	}
+
+	const tone = getToneColour(options.tone, options) === null ? defaultTone : options.tone;
+
+	return foreground(trend, tone, options);
+}

package/src/theme/colours.js

@@ -1,16 +1,107 @@
-// Semantic colour tokens for terminal output and generated previews.
+// Semantic colour roles used by renderers and public integrations.
 export const colourTokens = {
-	accent: "#c58cff",
-	background: "#070b0d",
-	border: "#2a3a42",
-	danger: "#ff7272",
-	info: "#8bbdff",
-	muted: "#7a8a92",
-	success: "#8fdf72",
-	surface: "#0f181b",
-	surfaceRaised: "#132024",
-	text: "#e8eef0",
-	warning: "#f4bd5f",
+	accent: "accent",
+	background: "background",
+	border: "border",
+	danger: "danger",
+	diffAddedBackground: "diffAddedBackground",
+	diffAddedText: "diffAddedText",
+	diffRemovedBackground: "diffRemovedBackground",
+	diffRemovedText: "diffRemovedText",
+	info: "info",
+	muted: "muted",
+	panelText: "panelText",
+	success: "success",
+	surface: "surface",
+	surfaceRaised: "surfaceRaised",
+	text: "text",
+	warning: "warning",
+};
+
+// Resolved theme names accepted by the public rendering options.
+export const themes = {
+	AUTO: "auto",
+	DARK: "dark",
+	LIGHT: "light",
+};
+
+const defaultBackground = "default-background";
+const defaultForeground = "default-foreground";
+
+// Theme palettes keep normal text on the user's terminal foreground.
+const palettes = {
+	[themes.AUTO]: {
+		accent: defaultForeground,
+		background: defaultBackground,
+		border: defaultForeground,
+		danger: defaultForeground,
+		diffAddedBackground: defaultBackground,
+		diffAddedText: defaultForeground,
+		diffRemovedBackground: defaultBackground,
+		diffRemovedText: defaultForeground,
+		info: defaultForeground,
+		muted: defaultForeground,
+		panelText: defaultForeground,
+		success: defaultForeground,
+		surface: defaultBackground,
+		surfaceRaised: defaultBackground,
+		text: defaultForeground,
+		warning: defaultForeground,
+		chipAgent: defaultBackground,
+		chipDanger: defaultBackground,
+		chipInfo: defaultBackground,
+		chipNeutral: defaultBackground,
+		chipSuccess: defaultBackground,
+		chipWarning: defaultBackground,
+	},
+	[themes.DARK]: {
+		accent: "ansi-256:183",
+		background: defaultBackground,
+		border: "ansi-256:239",
+		danger: "ansi-256:210",
+		diffAddedBackground: "ansi-256:22",
+		diffAddedText: "ansi-256:114",
+		diffRemovedBackground: "ansi-256:52",
+		diffRemovedText: "ansi-256:210",
+		info: "ansi-256:117",
+		muted: "ansi-256:246",
+		panelText: "ansi-256:252",
+		success: "ansi-256:114",
+		surface: "ansi-256:234",
+		surfaceRaised: "ansi-256:236",
+		text: defaultForeground,
+		warning: "ansi-256:215",
+		chipAgent: "ansi-256:58",
+		chipDanger: "ansi-256:52",
+		chipInfo: "ansi-256:17",
+		chipNeutral: "ansi-256:236",
+		chipSuccess: "ansi-256:22",
+		chipWarning: "ansi-256:58",
+	},
+	[themes.LIGHT]: {
+		accent: "ansi-256:25",
+		background: defaultBackground,
+		border: "ansi-256:250",
+		danger: "ansi-256:160",
+		diffAddedBackground: "ansi-256:194",
+		diffAddedText: "ansi-256:22",
+		diffRemovedBackground: "ansi-256:224",
+		diffRemovedText: "ansi-256:124",
+		info: "ansi-256:25",
+		muted: "ansi-256:242",
+		panelText: "ansi-256:238",
+		success: "ansi-256:28",
+		surface: "ansi-256:255",
+		surfaceRaised: "ansi-256:254",
+		text: defaultForeground,
+		warning: "ansi-256:94",
+		chipAgent: "ansi-256:229",
+		chipDanger: "ansi-256:224",
+		chipInfo: "ansi-256:153",
+		chipNeutral: "ansi-256:254",
+		chipSuccess: "ansi-256:194",
+		chipWarning: "ansi-256:229",
+	},
 };
 
 // Terminal frame colours for gallery-style previews.
@@ -19,50 +110,63 @@ export const terminalColours = {
 	border: "border",
 	title: "muted",
 	trafficLights: {
-		close: "#ff7272",
-		minimise: "#f4bd5f",
-		zoom: "#8fdf72",
+		close: "danger",
+		minimise: "warning",
+		zoom: "success",
 	},
 };
 
 // Chip and pill colour pairs for speaker labels and compact states.
 export const chipColours = {
 	agent: {
-		background: "#3a2815",
+		background: "chipAgent",
 		foreground: "warning",
 	},
 	danger: {
-		background: "#3c1d22",
+		background: "chipDanger",
 		foreground: "danger",
 	},
 	info: {
-		background: "#14273b",
+		background: "chipInfo",
 		foreground: "info",
 	},
 	neutral: {
-		background: "#172126",
+		background: "chipNeutral",
 		foreground: "muted",
 	},
 	success: {
-		background: "#18351f",
+		background: "chipSuccess",
 		foreground: "success",
 	},
 	user: {
-		background: "#1f3b1f",
+		background: "chipSuccess",
 		foreground: "success",
 	},
 	warning: {
-		background: "#3a2815",
+		background: "chipWarning",
 		foreground: "warning",
 	},
 };
 
+// Diff row colours pair forced backgrounds with explicit readable text tokens.
+export const diffColours = {
+	added: {
+		background: "diffAddedBackground",
+		foreground: "diffAddedText",
+	},
+	removed: {
+		background: "diffRemovedBackground",
+		foreground: "diffRemovedText",
+	},
+};
+
 // Panel colours for grouped reports and agent responses.
 export const panelColours = {
 	background: "surface",
 	border: "border",
 	danger: "danger",
 	info: "info",
+	body: "panelText",
 	success: "success",
 	warning: "warning",
 };
@@ -77,7 +181,7 @@ export const tableColours = {
 
 // Chart colours for simple bars and positive/negative trend segments.
 export const chartColours = {
-	barNegative: "#c48745",
+	barNegative: "warning",
 	barPositive: "success",
 	barWarning: "warning",
 	label: "muted",
@@ -101,41 +205,73 @@ export const toneColours = {
 };
 
 /**
- * Resolve a colour token by name.
+ * Resolve a colour token by name for the active theme.
  *
  * @param  {string}  colourName
  *     Colour token name.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {string}  options.theme
+ *     Resolved terminal theme.
  * @returns  {string|null}
- *     Hex colour value when supported.
+ *     ANSI-256, terminal-default, or null when unsupported.
  */
-export function getColourToken(colourName) {
-	return colourTokens[colourName] ?? null;
+export function getColourToken(colourName, options = {}) {
+	return palettes[resolveTheme(options.theme)][colourName] ?? null;
 }
 
 /**
  * Resolve a tone to a colour token value.
  *
  * @param  {string}  tone
- *     Tone name to resolve.
+ *     Semantic tone name.
+ * @param  {object}  options
+ *     Rendering options.
  * @returns  {string|null}
- *     Hex colour value when supported.
+ *     ANSI-256, terminal-default, or null when unsupported.
  */
-export function getToneColour(tone) {
-	return getColourToken(toneColours[tone]);
+export function getToneColour(tone, options = {}) {
+	return getColourToken(toneColours[tone], options);
 }
 
 /**
- * Resolve a direct hex colour or colour token reference.
+ * Resolve a colour token or direct hex value.
  *
  * @param  {string}  colour
- *     Hex colour value or colour token name.
+ *     Colour token name or hex colour.
+ * @param  {object}  options
+ *     Rendering options.
  * @returns  {string|null}
- *     Hex colour value when supported.
+ *     Resolved formatter colour value when supported.
  */
-export function resolveColourValue(colour) {
+export function resolveColourValue(colour, options = {}) {
 	if (colour?.startsWith("#")) {
 		return colour;
 	}
 
-	return getColourToken(colour);
+	return getColourToken(colour, options);
+}
+
+/**
+ * Check whether a value is a recognised theme name.
+ *
+ * @param  {string}  theme
+ *     Candidate theme name.
+ * @returns  {boolean}
+ *     Whether the theme can select a palette.
+ */
+export function isTheme(theme) {
+	return Object.values(themes).includes(theme);
+}
+
+/**
+ * Resolve an unknown theme to the safe automatic palette.
+ *
+ * @param  {string}  theme
+ *     Candidate theme name.
+ * @returns  {string}
+ *     Recognised theme name.
+ */
+function resolveTheme(theme) {
+	return isTheme(theme) ? theme : themes.DARK;
 }