@lewishowles/cli-style 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.13.0 - 2026-09-05
+
+### Added
+
+- Added Python `table()` and `row_group()` wrapper functions to the Python adapter, matching the existing shell/JS renderers.
+- `table()` columns can now set `maxWidth` and `overflow` (`'truncate'`, the default, or `'wrap'`) to cap a column's width and control how long values render within it.
+
 ## 0.12.1 - 2026-08-20
 
 ### Fixed

package/adapters/python/cli_style.py

@@ -159,6 +159,50 @@ def row(
 	return render("row", data, **kwargs)
 
 
+# Render an aligned table from Python values.
+#
+# @param  {list[dict[str, Any]]}  columns
+#     Table column definitions, including per-column overflow settings.
+# @param  {list[dict[str, Any]]}  rows
+#     Table row values.
+# @param  {bool|None}  unicode
+#     Optional Unicode border preference.
+# @param  {int|None}  width
+#     Optional table width.
+def table(
+	columns: list[dict[str, Any]],
+	rows: list[dict[str, Any]],
+	*,
+	unicode: bool | None = None,
+	width: int | None = None,
+	**kwargs: Any,
+) -> str:
+	return render("table", {
+		"columns": columns,
+		"rows": rows,
+		"unicode": unicode,
+		"width": width,
+	}, **kwargs)
+
+
+# Render a group of labelled value rows from Python values.
+#
+# @param  {list[dict[str, Any]]}  rows
+#     Labelled values to render together.
+# @param  {int|None}  label_width
+#     Optional minimum label width.
+def row_group(
+	rows: list[dict[str, Any]],
+	*,
+	label_width: int | None = None,
+	**kwargs: Any,
+) -> str:
+	return render("row-group", {
+		"rows": rows,
+		"labelWidth": label_width,
+	}, **kwargs)
+
+
 # Render an inline span from Python values.
 #
 # @param  {str}  value

package/package.json

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

package/src/gallery/render-gallery.js

@@ -764,6 +764,12 @@ function renderPrimitives(options) {
 		"Tables",
 		renderTableExample(options),
 		"",
+		"Truncated tables",
+		renderOverflowTableExample(options, "truncate"),
+		"",
+		"Wrapped tables",
+		renderOverflowTableExample(options, "wrap"),
+		"",
 		"Narrow tables",
 		renderTableExample({
 			...options,
@@ -900,6 +906,40 @@ function renderTableExample(options) {
 	});
 }
 
+/**
+ * Render a table with a long-detail column capped by maxWidth.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {string}  overflow
+ *     Overflow mode ('truncate' or 'wrap') for the capped column.
+ * @returns  {string}
+ *     Table example.
+ */
+function renderOverflowTableExample(options, overflow) {
+	return table({
+		...options,
+		columns: [
+			{
+				key: "source",
+				label: "Source",
+			},
+			{
+				key: "detail",
+				label: "Detail",
+				maxWidth: 28,
+				overflow,
+			},
+		],
+		rows: [
+			{
+				detail: "packages/cli-style/src/primitives/table.js",
+				source: "Table",
+			},
+		],
+	});
+}
+
 /**
  * Render a chart that exposes positive, warning, and negative colours.
  *

package/src/primitives/table.js

@@ -1,9 +1,7 @@
 import { foreground } from "../formatters/ansi.js";
+import { defaultWidth, minimumWidth, normaliseWidth } from "../formatters/width.js";
 import { tableColours } from "../theme/colours.js";
 
-// Tables assume a standard terminal width when no capability is provided.
-const defaultWidth = 80;
-
 // Columns use a compact but readable gap.
 const columnSeparator = "  ";
 
@@ -15,7 +13,9 @@ const columnSeparator = "  ";
  * @param  {boolean}  options.colour
  *     Whether ANSI colour should be applied.
  * @param  {object[]}  options.columns
- *     Column keys and labels.
+ *     Column keys and labels. A column may set maxWidth to cap its width,
+ *     with overflow ('truncate', the default, or 'wrap') controlling how
+ *     values beyond that width render.
  * @param  {object[]}  options.rows
  *     Table records.
  * @param  {boolean}  options.unicode
@@ -39,7 +39,18 @@ export function table(options = {}) {
 		widths.reduce((total, width) => total + width, 0) +
 		columnSeparator.length * (columns.length - 1);
 
-	const availableWidth = Number.isFinite(options.width) ? options.width : defaultWidth;
+	const requestedWidth = Number.isFinite(options.width) ? options.width : undefined;
+
+	// Let a requested width smaller than minimumWidth pass through unclamped.
+	const minimumTableWidth =
+		requestedWidth === undefined
+			? minimumWidth
+			: Math.max(1, Math.min(requestedWidth, minimumWidth));
+
+	const availableWidth = normaliseWidth(requestedWidth, {
+		defaultWidth,
+		minWidth: minimumTableWidth,
+	});
 
 	if (naturalWidth > availableWidth) {
 		return renderBlocks(columns, rows, options);
@@ -99,9 +110,65 @@ function normaliseRows(rows) {
  *     Column widths.
  */
 function columnWidths(columns, rows) {
-	return columns.map((column) =>
-		Math.max(column.label.length, ...rows.map((row) => cellValue(row[column.key]).length)),
-	);
+	return columns.map((column) => {
+		const naturalWidth = Math.max(
+			column.label.length,
+			...rows.map((row) => cellValue(row[column.key]).length),
+		);
+
+		const maxWidth = columnMaxWidth(column);
+
+		return maxWidth === null ? naturalWidth : Math.min(naturalWidth, maxWidth);
+	});
+}
+
+/**
+ * Return a column's configured width cap, if any.
+ *
+ * @param  {object}  column
+ *     Table column.
+ * @returns  {number|null}
+ *     Normalised maxWidth, or null when the column has none.
+ */
+function columnMaxWidth(column) {
+	if (!Number.isFinite(column.maxWidth) || column.maxWidth < 1) {
+		return null;
+	}
+
+	return normaliseWidth(column.maxWidth, {
+		defaultWidth: 1,
+		minWidth: 1,
+	});
+}
+
+/**
+ * Split a cell's value into the lines it renders as within a fixed-width column.
+ *
+ * @param  {string}  value
+ *     Cell value.
+ * @param  {object}  column
+ *     Table column, read for its overflow mode.
+ * @param  {number}  width
+ *     Column width.
+ * @returns  {string[]}
+ *     Lines the cell renders as; truncated to one line with a trailing
+ *     ellipsis unless the column's overflow is 'wrap'.
+ */
+function columnLines(value, column, width) {
+	if (value.length <= width) {
+		return [value];
+	}
+
+	if (column.overflow === "wrap") {
+		return Array.from(
+			{
+				length: Math.ceil(value.length / width),
+			},
+			(_, index) => value.slice(index * width, (index + 1) * width),
+		);
+	}
+
+	return [`${value.slice(0, width - 1)}…`];
 }
 
 /**
@@ -120,9 +187,11 @@ function columnWidths(columns, rows) {
  */
 function renderTable(columns, rows, widths, options) {
 	const header = columns
-		.map((column, index) =>
-			renderHeader(padColumn(column.label, widths[index], index, columns.length), options),
-		)
+		.map((column, index) => {
+			const headerLine = columnLines(column.label, { overflow: "truncate" }, widths[index])[0];
+
+			return renderHeader(padColumn(headerLine, widths[index], index, columns.length), options);
+		})
 		.join(columnSeparator);
 
 	const ruleCharacter = options.unicode === false ? "-" : "─";
@@ -131,17 +200,29 @@ function renderTable(columns, rows, widths, options) {
 	const renderedRule =
 		options.colour === true ? foreground(rule, tableColours.border, options) : rule;
 
-	const body = rows.map((row) =>
-		columns
-			.map((column, index) =>
-				renderCell(
-					padColumn(cellValue(row[column.key]), widths[index], index, columns.length),
-					index,
-					options,
-				),
-			)
-			.join(columnSeparator),
-	);
+	const body = rows.flatMap((row) => {
+		const lines = columns.map((column, index) =>
+			columnLines(cellValue(row[column.key]), column, widths[index]),
+		);
+
+		const lineCount = Math.max(...lines.map((column) => column.length));
+
+		return Array.from(
+			{
+				length: lineCount,
+			},
+			(_, lineIndex) =>
+				columns
+					.map((column, index) =>
+						renderCell(
+							padColumn(lines[index][lineIndex] ?? "", widths[index], index, columns.length),
+							index,
+							options,
+						),
+					)
+					.join(columnSeparator),
+		);
+	});
 
 	return [header, renderedRule, ...body].join("\n");
 }