@lewishowles/cli-style 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.16.0 - 2026-09-21
+
+### Breaking changes
+
+- BREAKING: Removed the `panelWidth` option from `panel()` and the `panel` renderer. Use `width` instead.
+- BREAKING: Panels now honour the requested total `width`, raise widths below 6 to the minimum usable width, and wrap long lines to fit.
+
+### Fixed
+
+- An explicit JSON `width` now takes precedence over the terminal width for width-aware renderers, so piped output stays within the caller's requested bounds.
+
 ## 0.15.0 - 2026-09-20
 
 ### Added

package/README.md

@@ -86,6 +86,10 @@ ui.print(output);
 
 Renderer methods return strings. `ui.print()`, `ui.write()`, and CLI commands handle stdout and stderr.
 
+For `render` commands, width follows this priority: JSON payload `width`, `--width`,
+`stdout.columns`, positive `COLUMNS`, then `80`, so piped output stays within the caller's requested
+size when the payload supplies a width.
+
 ### CLI render
 
 Use `cli-style render <renderer>` when a script needs rendered text from JSON input:
@@ -383,19 +387,19 @@ Pre-render a `span` when only part of the hint needs emphasis.
 
 ### Structured primitives
 
-| Renderer        | Main fields                            |
-| --------------- | -------------------------------------- |
-| `divider`       | `label`, `dividerWidth`, `character`   |
-| `chip`          | `label`, `tone`                        |
-| `panel`         | `title`, `lines`, `tone`, `panelWidth` |
-| `table`         | `columns`, `rows`, `width`             |
-| `progress-bar`  | `value`, `max`, `barWidth`, `tone`     |
-| `bar-chart`     | `rows`, `barWidth`                     |
-| `sparkline`     | `values`, `label`, `tone`, `width`     |
-| `step`          | `label`, `state`                       |
-| `step-progress` | `steps`, `current`                     |
-| `empty-state`   | `title`, `detail`                      |
-| `error-block`   | `title`, `lines`                       |
+| Renderer        | Main fields                          |
+| --------------- | ------------------------------------ |
+| `divider`       | `label`, `dividerWidth`, `character` |
+| `chip`          | `label`, `tone`                      |
+| `panel`         | `title`, `lines`, `tone`, `width`    |
+| `table`         | `columns`, `rows`, `width`           |
+| `progress-bar`  | `value`, `max`, `barWidth`, `tone`   |
+| `bar-chart`     | `rows`, `barWidth`                   |
+| `sparkline`     | `values`, `label`, `tone`, `width`   |
+| `step`          | `label`, `state`                     |
+| `step-progress` | `steps`, `current`                   |
+| `empty-state`   | `title`, `detail`                    |
+| `error-block`   | `title`, `lines`                     |
 
 For visual examples, run `cli-style gallery --section primitives`.
 

package/adapters/python/cli_style/_wrappers.py

@@ -297,7 +297,7 @@ def panel(
 	lines: list[str] | None = None,
 	title: str | None = None,
 	tone: str = "info",
-	panel_width: int | float | None = None,
+	width: int | float | None = None,
 	**kwargs: Any,
 ) -> str:
 	"""Return panel output; extra keyword arguments go to render()."""
@@ -308,8 +308,8 @@ def panel(
 
 	if title is not None:
 		data["title"] = title
-	if panel_width is not None:
-		data["panelWidth"] = panel_width
+	if width is not None:
+		data["width"] = width
 
 	return render("panel", data, **kwargs)
 

package/adapters/python/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lewishowles-cli-style"
-version = "0.15.0"
+version = "0.16.0"
 description = "Python adapter for the shared cli-style binary."
 authors = [{ name = "Lewis Howles" }]
 license = { text = "MIT" }

package/adapters/swift/Sources/CliStyle/Wrappers.swift

@@ -341,7 +341,7 @@ extension CliStyle {
 		lines: [String]? = nil,
 		title: String? = nil,
 		tone: String = "info",
-		panelWidth: Int? = nil,
+		width: Int? = nil,
 		options: CliStyleOptions = .init()
 	) throws -> String {
 		var data: [String: Any] = [
@@ -352,8 +352,8 @@ extension CliStyle {
 		if let title = title {
 			data["title"] = title
 		}
-		if let panelWidth = panelWidth {
-			data["panelWidth"] = panelWidth
+		if let width = width {
+			data["width"] = width
 		}
 
 		return try render("panel", data: data, options: options)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/cli-style",
-	"version": "0.15.0",
+	"version": "0.16.0",
 	"description": "Shared terminal output styles for Lewis Howles tools, diagnostics, and package CLIs.",
 	"license": "MIT",
 	"repository": {

package/src/capability/terminal.js

@@ -29,7 +29,7 @@ export function resolveTerminalCapabilities(options = {}) {
 	const isCi = env.CI === "true" || env.CI === "1";
 	const isDumb = env.TERM === "dumb";
 	const forceColour = env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "0";
-	const width = resolveWidth(stdout.columns);
+	const width = resolveWidth(stdout.columns, env.COLUMNS);
 	const usesPlain = argv.includes("--plain");
 
 	const colour = resolveColour({
@@ -189,16 +189,25 @@ function resolveUnicode(options) {
 }
 
 /**
- * Resolve terminal width with a stable fallback.
+ * Resolve the terminal width from the output stream, then `COLUMNS`, then a fixed fallback.
  *
- * @param  {number}  width
- *     Stream-reported column count.
+ * @param  {number}  streamWidth
+ *     The column count the output stream reports when it is a terminal.
+ * @param  {string}  columns
+ *     The `COLUMNS` environment value, used when the stream reports no width, such as when
+ *     output is piped. Anything other than a positive whole number is ignored.
  * @returns  {number}
  *     Usable terminal width.
  */
-function resolveWidth(width) {
-	if (Number.isInteger(width) && width > 0) {
-		return width;
+function resolveWidth(streamWidth, columns) {
+	if (Number.isInteger(streamWidth) && streamWidth > 0) {
+		return streamWidth;
+	}
+
+	const environmentWidth = Number(columns);
+
+	if (Number.isInteger(environmentWidth) && environmentWidth > 0) {
+		return environmentWidth;
 	}
 
 	return defaultWidth;

package/src/catalogue/renderer-catalogue.js

@@ -595,7 +595,7 @@ const rendererDefinitions = [
 				default: "info",
 			},
 			{
-				name: "panelWidth",
+				name: "width",
 				type: "number",
 				required: false,
 				default: null,

package/src/cli/render-command.js

@@ -38,6 +38,7 @@ const renderers = {
 		bulletList(input.items, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	chip: (input, options) =>
 		chip(input.label, input.tone, {
@@ -63,6 +64,7 @@ const renderers = {
 		errorBlock(input.title, input.lines, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	hint: (input, options) =>
 		hint(input.message, {
@@ -73,12 +75,14 @@ const renderers = {
 		labelledLine(input.label, input.message, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"next-step-block": (input, options) => nextStepBlock(input, options),
 	panel: (input, options) =>
 		panel({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"progress-bar": (input, options) =>
 		progressBar({
@@ -89,16 +93,19 @@ const renderers = {
 		row(input.label, input.value, {
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"row-group": (input, options) =>
 		rowGroup({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	sparkline: (input, options) =>
 		sparkline({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	span: (input, options) =>
 		span(input.value, input.tone, {
@@ -124,6 +131,7 @@ const renderers = {
 		table({
 			...input,
 			...options,
+			width: input.width ?? options.width,
 		}),
 	"task-summary": (input, options) => taskSummary(input, options),
 };

package/src/gallery/render-gallery.js

@@ -280,7 +280,6 @@ function galleryWidthOptions(width) {
 	return {
 		barWidth: Math.max(width - 18, 1),
 		dividerWidth: width,
-		panelWidth: width,
 	};
 }
 
@@ -790,7 +789,7 @@ function renderPrimitives(options) {
 		emptyState("No results", "tone: muted", options),
 		errorBlock("Failed", ["tone: danger"], {
 			...options,
-			panelWidth: 40,
+			width: 40,
 		}),
 		"",
 		"Steps",

package/src/primitives/panel.js

@@ -1,10 +1,14 @@
 import { background, foreground, style } from "../formatters/ansi.js";
+import { wrapText } from "../formatters/wrap.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.
+// The width used when no width is given, such as a direct library call outside a terminal.
 const defaultWidth = 40;
 
+// The narrowest panel that still leaves one column for content beside the accent and padding.
+const minimumWidth = 6;
+
 // Info is the neutral semantic accent for grouped explanatory content.
 const defaultTone = "info";
 
@@ -17,8 +21,9 @@ const defaultTone = "info";
  *     Whether ANSI colour should be applied.
  * @param  {string[]}  options.lines
  *     Content lines to render.
- * @param  {number}  options.panelWidth
- *     Total panel width.
+ * @param  {number}  options.width
+ *     Total panel width, including the accent and padding. Widths below 6 are raised to 6,
+ *     which leaves room for one character of content. Longer lines wrap to fit.
  * @param  {string}  options.profile
  *     Active output profile.
  * @param  {string}  options.title
@@ -37,18 +42,18 @@ export function panel(options = {}) {
 		return [...(options.title === undefined ? [] : [options.title]), ...lines].join("\n");
 	}
 
-	const width = Math.max(options.panelWidth ?? defaultWidth, 4);
+	const width = Math.max(options.width ?? defaultWidth, minimumWidth);
 	const panelLines = ["", ...(options.title === undefined ? [] : [options.title]), ...lines, ""];
 
 	return panelLines
-		.map((line, index) =>
+		.flatMap((line, index) =>
 			renderLine(line, width, index === 1 && options.title !== undefined, options),
 		)
 		.join("\n");
 }
 
 /**
- * Render one fixed-width panel line.
+ * Render one content line, wrapped across as many panel lines as it needs.
  *
  * @param  {string}  line
  *     Content line.
@@ -58,28 +63,30 @@ export function panel(options = {}) {
  *     Whether the line is the panel title.
  * @param  {object}  options
  *     Rendering options.
- * @returns  {string}
- *     Rendered content line.
+ * @returns  {string[]}
+ *     The panel lines, each exactly `width` columns wide.
  */
 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}`;
-	}
+	return wrapText(line, contentWidth).map((visibleLine) => {
+		const content = `  ${visibleLine.padEnd(contentWidth, " ")}  `;
+
+		if (options.colour !== true) {
+			return `${accent}${content}`;
+		}
 
-	const renderedAccent = renderPanelColour(accent, options);
+		const renderedAccent = renderPanelColour(accent, options);
 
-	const renderedContent = foreground(
-		background(content, panelColours.background, options),
-		panelColours.body,
-		options,
-	);
+		const renderedContent = foreground(
+			background(content, panelColours.background, options),
+			panelColours.body,
+			options,
+		);
 
-	return `${renderedAccent}${isTitle ? style(renderedContent, "bold", options) : renderedContent}`;
+		return `${renderedAccent}${isTitle ? style(renderedContent, "bold", options) : renderedContent}`;
+	});
 }
 
 /**