@lewishowles/cli-style 0.1.0

package/src/primitives/feedback.js

@@ -0,0 +1,83 @@
+import { foreground, style } from "../formatters/ansi.js";
+import { getResultSymbol, resultTypes } from "../theme/results.js";
+import { panel } from "./panel.js";
+
+/**
+ * Render an informational hint.
+ *
+ * @param  {string}  message
+ *     Hint text.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @returns  {string}
+ *     Rendered hint.
+ */
+export function hint(message = "", options = {}) {
+	const prefix = "i Hint:";
+
+	if (options.colour !== true) {
+		return `${prefix} ${message}`;
+	}
+
+	const renderedPrefix = style(foreground(prefix, "info", options), "bold", options);
+
+	return `${renderedPrefix} ${message}`;
+}
+
+/**
+ * Render an empty-state message.
+ *
+ * @param  {string}  title
+ *     Empty-state title.
+ * @param  {string}  detail
+ *     Optional supporting detail.
+ * @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 empty state.
+ */
+export function emptyState(title = "No results", detail = "", options = {}) {
+	const symbol = getResultSymbol(resultTypes.SKIPPED, options);
+	const prefix = `${symbol} ${title}`;
+	const detailText = detail === "" ? "" : ` ${detail}`;
+
+	if (options.colour !== true) {
+		return `${prefix}${detailText}`;
+	}
+
+	const renderedPrefix = style(foreground(prefix, "muted", options), "bold", options);
+
+	return `${renderedPrefix}${detailText}`;
+}
+
+/**
+ * Render a structured error block.
+ *
+ * @param  {string}  title
+ *     Error title.
+ * @param  {string[]}  lines
+ *     Supporting error details.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.unicode
+ *     Whether Unicode symbols should be used.
+ * @returns  {string}
+ *     Rendered error block.
+ */
+export function errorBlock(title = "Failed", lines = [], options = {}) {
+	const symbol = getResultSymbol(resultTypes.FAILED, options);
+	const detailLines = Array.isArray(lines) ? lines : [];
+
+	return panel({
+		...options,
+		lines: detailLines,
+		title: `${symbol} Error: ${title}`,
+		tone: "danger",
+	});
+}

package/src/primitives/panel.js

@@ -0,0 +1,100 @@
+import { background, foreground, style } from "../formatters/ansi.js";
+import { profiles } from "../profiles/profiles.js";
+import { panelColours } from "../theme/colours.js";
+
+// Panels use a stable width so grouped output aligns across a report.
+const defaultWidth = 40;
+
+// Info is the neutral semantic accent for grouped explanatory content.
+const defaultTone = "info";
+
+/**
+ * Render a grouped block with a semantic left accent.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {string[]}  options.lines
+ *     Content lines to render.
+ * @param  {number}  options.panelWidth
+ *     Total panel width.
+ * @param  {string}  options.profile
+ *     Active output profile.
+ * @param  {string}  options.title
+ *     Optional panel title.
+ * @param  {string}  options.tone
+ *     Semantic accent tone.
+ * @param  {boolean}  options.unicode
+ *     Whether Unicode symbols should be used.
+ * @returns  {string}
+ *     Rendered panel.
+ */
+export function panel(options = {}) {
+	const lines = options.lines ?? [];
+
+	if (options.profile === profiles.CI) {
+		return [
+			...(options.title === undefined ? [] : [options.title]),
+			...lines,
+		].join("\n");
+	}
+
+	const width = Math.max(options.panelWidth ?? defaultWidth, 4);
+	const panelLines = [
+		"",
+		...(options.title === undefined ? [] : [options.title]),
+		...lines,
+		"",
+	];
+
+	return panelLines
+		.map((line, index) => renderLine(line, width, index === 1 && options.title !== undefined, options))
+		.join("\n");
+}
+
+/**
+ * Render one fixed-width panel line.
+ *
+ * @param  {string}  line
+ *     Content line.
+ * @param  {number}  width
+ *     Total panel width.
+ * @param  {boolean}  isTitle
+ *     Whether the line is the panel title.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered content line.
+ */
+function renderLine(line, width, isTitle, options) {
+	const accent = options.unicode === false ? "|" : "▌";
+	const contentWidth = width - 5;
+	const visibleLine = line.slice(0, contentWidth);
+	const content = `  ${visibleLine.padEnd(contentWidth, " ")}  `;
+
+	if (options.colour !== true) {
+		return `${accent}${content}`;
+	}
+
+	const renderedAccent = renderPanelColour(accent, options);
+	const renderedContent = background(content, panelColours.background, options);
+
+	return `${renderedAccent}${isTitle ? style(renderedContent, "bold", options) : renderedContent}`;
+}
+
+/**
+ * Apply the panel's semantic colour.
+ *
+ * @param  {string}  value
+ *     Panel text to colour.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Coloured panel text.
+ */
+function renderPanelColour(value, options) {
+	const tone = panelColours[options.tone ?? defaultTone] ?? panelColours[defaultTone];
+
+	return foreground(value, tone, options);
+}

package/src/primitives/progress-bar.js

@@ -0,0 +1,121 @@
+import { foreground } from "../formatters/ansi.js";
+import { getToneColour } from "../theme/colours.js";
+
+// Progress bars balance useful resolution with compact terminal output.
+const defaultWidth = 20;
+
+// Success is the default tone for work progressing normally.
+const defaultTone = "success";
+
+// Invalid maxima fall back to a percentage-friendly range.
+const defaultMaximum = 100;
+
+/**
+ * Render a single value against a maximum.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {number}  options.barWidth
+ *     Number of characters used by the bar.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {number}  options.max
+ *     Maximum progress value.
+ * @param  {string}  options.tone
+ *     Semantic colour tone for completed progress.
+ * @param  {boolean}  options.unicode
+ *     Whether Unicode bar characters should be used.
+ * @param  {number}  options.value
+ *     Current progress value.
+ * @returns  {string}
+ *     Rendered progress bar.
+ */
+export function progressBar(options = {}) {
+	const maximum = normaliseMaximum(options.max);
+	const value = normaliseValue(options.value);
+	const width = normaliseWidth(options.barWidth);
+	const ratio = Math.min(Math.max(value / maximum, 0), 1);
+	const filledWidth = Math.round(width * ratio);
+	const emptyWidth = width - filledWidth;
+	const symbols = barSymbols(options);
+	const filled = symbols.filled.repeat(filledWidth);
+	const empty = symbols.empty.repeat(emptyWidth);
+	const percentage = Math.round(ratio * 100);
+	const numericText = `${percentage}% (${value}/${maximum})`;
+
+	if (options.colour !== true) {
+		return `[${filled}${empty}] ${numericText}`;
+	}
+
+	const tone = getToneColour(options.tone) === null ? defaultTone : options.tone;
+	const renderedFilled = filled === "" ? "" : foreground(filled, tone ?? defaultTone, options);
+	const renderedEmpty = empty === "" ? "" : foreground(empty, "muted", options);
+
+	return `[${renderedFilled}${renderedEmpty}] ${numericText}`;
+}
+
+/**
+ * Return progress characters for the active capability.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {object}
+ *     Filled and empty progress symbols.
+ */
+function barSymbols(options) {
+	if (options.unicode === false) {
+		return {
+			empty: "-",
+			filled: "#",
+		};
+	}
+
+	return {
+		empty: "░",
+		filled: "█",
+	};
+}
+
+/**
+ * Return a usable maximum.
+ *
+ * @param  {number}  maximum
+ *     Requested maximum.
+ * @returns  {number}
+ *     Positive finite maximum.
+ */
+function normaliseMaximum(maximum) {
+	if (!Number.isFinite(maximum) || maximum <= 0) {
+		return defaultMaximum;
+	}
+
+	return maximum;
+}
+
+/**
+ * Return a usable progress value.
+ *
+ * @param  {number}  value
+ *     Requested progress value.
+ * @returns  {number}
+ *     Finite progress value.
+ */
+function normaliseValue(value) {
+	return Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * Return a usable integer bar width.
+ *
+ * @param  {number}  width
+ *     Requested bar width.
+ * @returns  {number}
+ *     Positive integer width.
+ */
+function normaliseWidth(width) {
+	if (!Number.isFinite(width)) {
+		return defaultWidth;
+	}
+
+	return Math.max(Math.floor(width), 1);
+}

package/src/primitives/row.js

@@ -0,0 +1,80 @@
+import { foreground } from "../formatters/ansi.js";
+
+// Row labels use the same subdued tone as table headers by default.
+const defaultLabelColour = "muted";
+
+// Rows use a compact gap that still reads cleanly in plain terminals.
+const defaultSeparator = "  ";
+
+/**
+ * Render a labelled value row.
+ *
+ * @param  {string}  label
+ *     Label text to render.
+ * @param  {string}  value
+ *     Value text to render.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {string}  options.labelColour
+ *     Colour token for the label.
+ * @param  {number}  options.labelWidth
+ *     Minimum label width before the separator.
+ * @param  {string}  options.separator
+ *     Text between label and value.
+ * @param  {string}  options.valueColour
+ *     Optional colour token for the value.
+ * @returns  {string}
+ *     Rendered row.
+ */
+export function row(label, value = "", options = {}) {
+	const labelWidth = Math.max(label.length, options.labelWidth ?? 0);
+	const labelText = label.padEnd(labelWidth, " ");
+	const renderedLabel = renderLabel(labelText, options);
+
+	if (value === "") {
+		return renderedLabel;
+	}
+
+	const renderedValue = renderValue(value, options);
+	const separator = options.separator ?? defaultSeparator;
+
+	return `${renderedLabel}${separator}${renderedValue}`;
+}
+
+/**
+ * Render a row label.
+ *
+ * @param  {string}  label
+ *     Label text to render.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered label.
+ */
+function renderLabel(label, options) {
+	if (options.colour !== true) {
+		return label;
+	}
+
+	return foreground(label, options.labelColour ?? defaultLabelColour, options);
+}
+
+/**
+ * Render a row value.
+ *
+ * @param  {string}  value
+ *     Value text to render.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered value.
+ */
+function renderValue(value, options) {
+	if (options.colour !== true || options.valueColour === undefined) {
+		return value;
+	}
+
+	return foreground(value, options.valueColour, options);
+}

package/src/primitives/status.js

@@ -0,0 +1,39 @@
+import { foreground, style } from "../formatters/ansi.js";
+import { getResultSymbol, getResultToken, resultTypes } from "../theme/results.js";
+
+/**
+ * Render a result status line.
+ *
+ * @param  {string}  resultType
+ *     Result type to render.
+ * @param  {string}  detail
+ *     Optional detail text.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {string}  options.label
+ *     Optional text label override.
+ * @param  {boolean}  options.unicode
+ *     Whether Unicode symbols should be used.
+ * @returns  {string}
+ *     Rendered status line.
+ */
+export function status(resultType = resultTypes.UNKNOWN, detail = "", options = {}) {
+	const token = getResultToken(resultType);
+	const symbol = getResultSymbol(resultType, options);
+	const label = typeof options.label === "string" && options.label !== ""
+		? options.label
+		: token.label;
+	const prefix = `${symbol} ${label}`;
+	const detailText = detail === "" ? "" : ` ${detail}`;
+
+	if (options.colour !== true) {
+		return `${prefix}${detailText}`;
+	}
+
+	const colouredPrefix = foreground(prefix, token.tone, options);
+	const boldPrefix = style(colouredPrefix, "bold", options);
+
+	return `${boldPrefix}${detailText}`;
+}

package/src/primitives/step-progress.js

@@ -0,0 +1,184 @@
+import { foreground } from "../formatters/ansi.js";
+import { getResultSymbol, getResultToken, resultTypes } from "../theme/results.js";
+
+// Step states describe position in an ordered flow.
+export const stepStates = {
+	COMPLETE: "complete",
+	CURRENT: "current",
+	PENDING: "pending",
+};
+
+// Current steps use the running symbol defined by the package contract.
+const currentToken = {
+	symbols: {
+		ascii: "...",
+		unicode: "…",
+	},
+	tone: "info",
+};
+
+/**
+ * Render one labelled step state.
+ *
+ * @param  {string}  label
+ *     Step label.
+ * @param  {string}  state
+ *     Step state or result type.
+ * @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 step.
+ */
+export function step(label = "", state = stepStates.PENDING, options = {}) {
+	const token = stepToken(state);
+	const symbol = stepSymbol(state, token, options);
+
+	if (options.colour !== true) {
+		return `${symbol} ${label}`;
+	}
+
+	const renderedSymbol = foreground(symbol, token.tone, options);
+
+	return `${renderedSymbol} ${label}`;
+}
+
+/**
+ * Render an ordered sequence with inferred states and explicit counts.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {number}  options.current
+ *     Zero-based current step index.
+ * @param  {string[]}  options.steps
+ *     Ordered step labels.
+ * @returns  {string}
+ *     Rendered step progress.
+ */
+export function stepProgress(options = {}) {
+	const steps = normaliseSteps(options.steps);
+
+	if (steps.length === 0) {
+		return "";
+	}
+
+	const current = normaliseCurrent(options.current, steps.length);
+
+	return steps.map((label, index) => {
+		const state = stateForIndex(index, current);
+		const count = `${index + 1}/${steps.length}`;
+
+		return `${count} ${step(label, state, options)}`;
+	}).join("\n");
+}
+
+/**
+ * Return valid step labels.
+ *
+ * @param  {string[]}  steps
+ *     Requested step labels.
+ * @returns  {string[]}
+ *     Non-empty labels.
+ */
+function normaliseSteps(steps) {
+	if (!Array.isArray(steps)) {
+		return [];
+	}
+
+	return steps.filter((label) => typeof label === "string" && label !== "");
+}
+
+/**
+ * Return a current index within the step range.
+ *
+ * @param  {number}  current
+ *     Requested current index.
+ * @param  {number}  stepCount
+ *     Number of available steps.
+ * @returns  {number}
+ *     Clamped current index.
+ */
+function normaliseCurrent(current, stepCount) {
+	if (!Number.isFinite(current)) {
+		return 0;
+	}
+
+	return Math.min(Math.max(Math.floor(current), 0), stepCount - 1);
+}
+
+/**
+ * Infer a positional state for a step index.
+ *
+ * @param  {number}  index
+ *     Step index.
+ * @param  {number}  current
+ *     Current step index.
+ * @returns  {string}
+ *     Positional step state.
+ */
+function stateForIndex(index, current) {
+	if (index < current) {
+		return stepStates.COMPLETE;
+	}
+
+	if (index === current) {
+		return stepStates.CURRENT;
+	}
+
+	return stepStates.PENDING;
+}
+
+/**
+ * Return the display token for a step state.
+ *
+ * @param  {string}  state
+ *     Step state or result type.
+ * @returns  {object}
+ *     Symbol and tone token.
+ */
+function stepToken(state) {
+	if (state === stepStates.COMPLETE) {
+		return getResultToken(resultTypes.SUCCESS);
+	}
+
+	if (state === stepStates.CURRENT) {
+		return currentToken;
+	}
+
+	if (state === stepStates.PENDING) {
+		return getResultToken(resultTypes.SKIPPED);
+	}
+
+	return getResultToken(state);
+}
+
+/**
+ * Return the display symbol for a step state.
+ *
+ * @param  {string}  state
+ *     Step state or result type.
+ * @param  {object}  token
+ *     Resolved step token.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Step symbol.
+ */
+function stepSymbol(state, token, options) {
+	if (state === stepStates.CURRENT) {
+		return options.unicode === false ? token.symbols.ascii : token.symbols.unicode;
+	}
+
+	if (state === stepStates.COMPLETE) {
+		return getResultSymbol(resultTypes.SUCCESS, options);
+	}
+
+	if (state === stepStates.PENDING) {
+		return getResultSymbol(resultTypes.SKIPPED, options);
+	}
+
+	return getResultSymbol(state, options);
+}