pixl-cli 1.1.1 → 1.1.3

package/README.md

@@ -20,6 +20,8 @@
 	* [Displaying Info Boxes](#displaying-info-boxes)
 		+ [Centering Text](#centering-text)
 		+ [Word-Wrapping Text](#word-wrapping-text)
+	* [Displaying Definition Lists](#displaying-definition-lists)
+	* [Displaying Dashboard Grids](#displaying-dashboard-grids)
 	* [Displaying Tables](#displaying-tables)
 	* [Graphical Progress Bars](#graphical-progress-bars)
 		+ [Configuration](#configuration)
@@ -398,6 +400,105 @@ culpa qui officia deserunt mollit anim
 id est laborum.
 ```
 
+## Displaying Definition Lists
+
+Call `cli.defList()` to render a two-column list of labels and values inside a box.  Labels are bold by default, values are plain, and no vertical border is drawn between the columns.  Colons are added to labels automatically when needed.  Lines will automatically truncate with ellipsis as needed.
+
+```js
+const cli = require('pixl-cli');
+
+let event = {
+	id: "emm2wtlsxrtjz8v4",
+	title: "Simple Shell Test",
+	category: "general",
+	username: "admin"
+};
+
+cli.println( cli.defList([
+	[ "Event ID", event.id ],
+	[ "Title", event.title ],
+	[ "Category", event.category ],
+	[ "Author", event.username ]
+], {
+	labelStyles: ["yellow", "bold"],
+	textStyles: ["green"],
+	indent: 1
+}) );
+```
+
+This produces a definition list like this, with colors when the terminal supports them:
+
+```
+ ┌─────────────────────────────┐
+ │ Event ID: emm2wtlsxrtjz8v4  │
+ │ Title:    Simple Shell Test │
+ │ Category: general           │
+ │ Author:   admin             │
+ └─────────────────────────────┘
+```
+
+The label and value columns are left-aligned.  When the box would exceed the attached terminal width, long values are shortened with an ellipsis.  The complete label column is preserved whenever possible.  The `indent` is treated as a horizontal margin on both sides when calculating the available width.
+
+You can customize the definition list with these options:
+
+| Property Name | Description |
+|---------------|-------------|
+| `labelStyles` | An array of [chalk](https://www.npmjs.com/package/chalk) styles or functions for labels.  Defaults to `["bold"]`. |
+| `textStyles` | An array of styles or functions for values.  Defaults to `[]`. |
+| `borderStyles` | An array of styles or functions for the box border.  Defaults to `["gray"]`. |
+| `indent` | Horizontal margin in characters on both sides of the box.  Defaults to `0`. |
+| `gap` | Spaces between the label and value columns.  Defaults to `1`. |
+| `hspace` | Spaces between the content and each side of the box.  Defaults to `1`. |
+| `vspace` | Empty lines above and below the list inside the box.  Defaults to `0`. |
+
+## Displaying Dashboard Grids
+
+Call `cli.dashGrid()` to render a responsive grid of dashboard units.  Each unit contains a centered value and label, and all units have the same dimensions regardless of their content.  Pass an array of `[label, value]` pairs:
+
+```js
+const cli = require('pixl-cli');
+
+cli.println( cli.dashGrid([
+	[ "Conductors", 1 ],
+	[ "Servers", 2 ],
+	[ "Current Alerts", 0 ],
+	[ "Active Jobs", 0 ],
+	[ "Job Success Rate", "100%" ],
+	[ "Avg. Job Elapsed", "31 sec" ]
+], {
+	minCols: 3,
+	maxCols: 5,
+	gap: 1,
+	valueStyles: ["bold", "green"]
+}) );
+```
+
+At a width of 62 columns, the first row looks like this:
+
+```
+┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
+│        1         │ │        2         │ │        0         │
+│                  │ │                  │ │                  │
+│    Conductors    │ │     Servers      │ │  Current Alerts  │
+└──────────────────┘ └──────────────────┘ └──────────────────┘
+```
+
+The grid uses the current terminal width and flows additional units onto new rows.  An incomplete final row ends after its last unit.  Labels and values are limited to one line and automatically shortened with an ellipsis when necessary.  ANSI styles and emoji are measured by their terminal display width.
+
+You can customize the dashboard grid with these options:
+
+| Property Name | Description |
+|---------------|-------------|
+| `width` | Overall layout width, including horizontal margins.  Defaults to `cli.width()`, or `80` when no terminal width is available. |
+| `unitWidth` | Target outer width used to select the responsive column count.  Defaults to `20`. |
+| `minCols` | Preferred minimum number of columns.  Defaults to `3`.  Extremely narrow terminals may use fewer to avoid overflow. |
+| `maxCols` | Maximum number of columns.  Defaults to `5`. |
+| `gap` | Horizontal spaces between units.  Grid rows use `gap - 1` blank lines.  Defaults to `1`, producing no vertical blank line. |
+| `indent` | Horizontal margin in characters on both sides of the grid.  Defaults to `0`. |
+| `valueStyles` | An array of [chalk](https://www.npmjs.com/package/chalk) styles or functions for values.  Defaults to `["bold"]`. |
+| `labelStyles` | An array of styles or functions for labels.  Defaults to `["gray"]`. |
+| `borderStyles` | An array of styles or functions for unit borders.  Defaults to `["gray"]`. |
+
 ## Displaying Tables
 
 ![Table Example](https://pixlcore.com/software/pixl-cli/table.png)
@@ -687,6 +788,8 @@ The full list of methods and objects that are imported are:
 - `yesno()`
 - `table()`
 - `box()`
+- `defList()`
+- `dashGrid()`
 - `wrap()`
 - `center()`
 - `commify()`

package/cli.js

@@ -176,7 +176,11 @@ var cli = module.exports = {
 		output.push( indent + this.applyStyles("┌" + this.repeat("─", width) + "┐", styles) );
 		
 		// left, content, right
-		var lines = text.split(/\n/);
+		// Styled text normally carries its SGR modes across newlines, but the styled
+		// right border resets those modes before the next content line.  Make each
+		// line self-contained before inserting borders between them.
+		var safeText = (styles && styles.length) ? Util.preserveAnsiLineStyles(text) : text;
+		var lines = safeText.split(/\n/);
 		while (vspace-- > 0) {
 			lines.unshift( "" );
 			lines.push( "" );
@@ -197,6 +201,227 @@ var cli = module.exports = {
 		return output.join("\n");
 	},
 	
+	defList: function(rows, args) {
+		// Render a two-column definition list inside a box.  The labels share a
+		// common width, but there is deliberately no border between the columns.
+		var self = this;
+		if (!args) args = {};
+		
+		// Empty arrays are valid style overrides, so test for the property rather
+		// than using || here.  Labels are bold by default and values are plain.
+		var labelStyles = ('labelStyles' in args) ? args.labelStyles : ["bold"];
+		var textStyles = ('textStyles' in args) ? args.textStyles : [];
+		var borderStyles = ('borderStyles' in args) ? args.borderStyles :
+			(('styles' in args) ? args.styles : ["gray"]);
+		var hspace = ('hspace' in args) ? args.hspace : 1;
+		var vspace = args.vspace || 0;
+		
+		// Gaps are whole terminal cells.  Invalid and negative values become zero.
+		var gap = ('gap' in args) ? Math.floor(Number(args.gap)) : 1;
+		if (!isFinite(gap) || (gap < 0)) gap = 0;
+		var indent = args.indent || "";
+		if (typeof(indent) == 'number') indent = this.space(indent);
+		
+		// Normalize and style all cells before measuring them.  This allows ANSI
+		// color, custom style functions and the cli.emoji() cursor hack to coexist
+		// with the display-width calculations below.
+		var items = (rows || []).map( function(row) {
+			var label = '' + row[0];
+			var value = '' + row[1];
+			
+			// Definition lists are one item per line.  Flatten accidental newlines so
+			// a cell cannot escape its row and disturb the surrounding box.
+			label = label.replace(/\r?\n/g, ' ').replace(/\s+$/, '');
+			value = value.replace(/\r?\n/g, ' ');
+			if (!label.replace(ansiPattern, '').match(/:$/)) label += ':';
+			
+			return {
+				label: self.applyStyles(label, labelStyles),
+				value: self.applyStyles(value, textStyles)
+			};
+		} );
+		
+		var labelWidth = 0;
+		var valueWidth = 0;
+		
+		items.forEach( function(item) {
+			labelWidth = Math.max( labelWidth, stringWidth(item.label) );
+			valueWidth = Math.max( valueWidth, stringWidth(item.value) );
+		} );
+		
+		// The indent acts as a horizontal margin, so reserve it on both sides.
+		// Also reserve both box borders, both padding areas, and the requested gap
+		// separating the label and value columns.
+		var terminalWidth = this.width();
+		var contentWidth = labelWidth + gap + valueWidth;
+		
+		if (terminalWidth) {
+			var availableWidth = terminalWidth - (stringWidth(indent) * 2);
+			var availableContentWidth = Math.max(0, availableWidth - 2 - (hspace * 2));
+			contentWidth = Math.min(contentWidth, availableContentWidth);
+		}
+		
+		// Keep the complete label column whenever possible, and give all remaining
+		// room to values.  On extremely narrow terminals labels are shortened too,
+		// while still reserving one cell for a value when any room remains.
+		if (labelWidth + gap + 1 > contentWidth) {
+			labelWidth = Math.max(0, contentWidth - gap - 1);
+		}
+		valueWidth = Math.max(0, contentWidth - labelWidth - (labelWidth ? gap : 0));
+		
+		var truncate = function(text, width) {
+			// Width.truncate() preserves ANSI resets and complete emoji graphemes.
+			if (width < 1) return '';
+			return (stringWidth(text) > width) ? Width.truncate(text, width, '…') : text;
+		};
+		
+		var lines = items.map( function(item) {
+			var label = truncate(item.label, labelWidth);
+			var value = truncate(item.value, valueWidth);
+			if (!labelWidth) return value;
+			return self.pad(label, labelWidth) + self.space(gap) + value;
+		} );
+		
+		// Let box() handle the border, padding, vertical spacing and final row
+		// padding.  Passing the normalized indent keeps numeric margins consistent.
+		return this.box( lines.join("\n"), {
+			styles: borderStyles,
+			hspace: hspace,
+			vspace: vspace,
+			indent: indent
+		} );
+	},
+	
+	dashGrid: function(rows, args) {
+		// Render a responsive grid of equal-sized dashboard units.  Each unit has a
+		// centered value, a centered label, a blank spacer row and its own border.
+		var self = this;
+		if (!rows || !rows.length) return '';
+		if (!args) args = {};
+		
+		// Normalize numeric layout options to non-negative whole terminal cells.
+		// Invalid values fall back to their documented defaults.
+		var wholeNumber = function(value, defaultValue, minimum) {
+			value = Math.floor(Number(value));
+			if (!isFinite(value)) value = defaultValue;
+			return Math.max(minimum, value);
+		};
+		
+		var targetUnitWidth = wholeNumber(args.unitWidth, 20, 5);
+		var minCols = wholeNumber(args.minCols, 3, 1);
+		var maxCols = wholeNumber(args.maxCols, 5, 1);
+		var gap = wholeNumber(args.gap, 1, 0);
+		var indent = args.indent || '';
+		if (typeof(indent) == 'number') indent = this.space(indent);
+		
+		// A maximum is a hard cap.  If conflicting limits are supplied, lower the
+		// minimum to match rather than silently exceeding the requested maximum.
+		if (minCols > maxCols) minCols = maxCols;
+		
+		// Empty style arrays are intentional overrides, so property checks are used
+		// instead of ||.  Values are bold, labels and borders are gray by default.
+		var valueStyles = ('valueStyles' in args) ? args.valueStyles : ["bold"];
+		var labelStyles = ('labelStyles' in args) ? args.labelStyles : ["gray"];
+		var borderStyles = ('borderStyles' in args) ? args.borderStyles : ["gray"];
+		
+		// An explicit width makes redirected output and tests deterministic.  When
+		// attached to a terminal, cli.width() returns process.stdout.columns.
+		var layoutWidth = ('width' in args) ?
+			wholeNumber(args.width, 80, 0) : (this.width() || 80);
+		var availableWidth = Math.max(0, layoutWidth - (stringWidth(indent) * 2));
+		if (availableWidth < 2) return '';
+		
+		// Start with the preferred responsive column count, bounded by the caller's
+		// limits and the number of units.  unitWidth is a planning target; the actual
+		// width is calculated below after horizontal gaps have been reserved.
+		var numCols = Math.floor(availableWidth / targetUnitWidth);
+		numCols = Math.max(minCols, Math.min(maxCols, numCols));
+		numCols = Math.min(numCols, rows.length);
+		
+		// Each useful unit needs five cells: two borders, two padding cells and one
+		// content cell.  On a very narrow terminal, safety takes priority over the
+		// requested minimum column count so the grid never overflows.
+		var maxFittingCols = Math.floor((availableWidth + gap) / (5 + gap));
+		maxFittingCols = Math.max(1, maxFittingCols);
+		numCols = Math.max(1, Math.min(numCols, maxFittingCols));
+		
+		// All units use the same exact outer width.  Any indivisible remainder stays
+		// unused at the right edge, including on incomplete final rows.
+		var unitWidth = Math.floor(
+			(availableWidth - ((numCols - 1) * gap)) / numCols
+		);
+		if (unitWidth < 2) return '';
+		
+		var innerWidth = unitWidth - 2;
+		var contentWidth = Math.max(0, innerWidth - 2);
+		
+		var truncate = function(text) {
+			// Preserve ANSI styles, complete graphemes and cli.emoji() sequences.
+			if (contentWidth < 1) return '';
+			return (stringWidth(text) > contentWidth) ?
+				Width.truncate(text, contentWidth, '…') : text;
+		};
+		
+		var centerCell = function(text) {
+			// Center by terminal display width rather than JavaScript string length.
+			var remain = Math.max(0, innerWidth - stringWidth(text));
+			var left = Math.floor(remain / 2);
+			return self.space(left) + text + self.space(remain - left);
+		};
+		
+		var units = rows.map( function(row) {
+			var label = ('' + row[0]).replace(/\r?\n/g, ' ');
+			var value = ('' + row[1]).replace(/\r?\n/g, ' ');
+			return {
+				label: self.applyStyles(label, labelStyles),
+				value: self.applyStyles(value, valueStyles)
+			};
+		} );
+		
+		var renderUnit = function(unit) {
+			// The interior layout is: value, blank, label.
+			var top = self.applyStyles(
+				'┌' + self.repeat('─', innerWidth) + '┐', borderStyles
+			);
+			var bottom = self.applyStyles(
+				'└' + self.repeat('─', innerWidth) + '┘', borderStyles
+			);
+			var leftBorder = self.applyStyles('│', borderStyles);
+			var rightBorder = self.applyStyles('│', borderStyles);
+			var blank = leftBorder + self.space(innerWidth) + rightBorder;
+			
+			return [
+				top,
+				leftBorder + centerCell(truncate(unit.value)) + rightBorder,
+				blank,
+				leftBorder + centerCell(truncate(unit.label)) + rightBorder,
+				bottom
+			];
+		};
+		
+		var output = [];
+		for (var rowIdx = 0; rowIdx < units.length; rowIdx += numCols) {
+			var gridRow = units.slice(rowIdx, rowIdx + numCols).map(renderUnit);
+			
+			// Join corresponding lines from each unit to form one complete grid row.
+			for (var lineIdx = 0; lineIdx < gridRow[0].length; lineIdx++) {
+				output.push(
+					indent + gridRow.map( function(unit) {
+						return unit[lineIdx];
+					} ).join(self.space(gap))
+				);
+			}
+			
+			// Adjacent text lines already provide one row of vertical separation, so
+			// subtract one when translating the horizontal gap into blank lines.
+			if (rowIdx + numCols < units.length) {
+				for (var gapIdx = 0; gapIdx < Math.max(0, gap - 1); gapIdx++) output.push('');
+			}
+		}
+		
+		return output.join("\n");
+	},
+	
 	applyStyles: function(text, styles) {
 		// apply one or more chalk styles or functions to text string
 		if (!styles) return text;
@@ -487,7 +712,7 @@ var cli = module.exports = {
 		global.Tools = Tools;
 		
 		// bind wrap functions
-		["prompt", "yesno", "table", "box", "wrap", "center", "print", "println", "verbose", "verboseln", "warn", "warnln", "die", "dieln", "loadFile", "saveFile", "appendFile"].forEach( function(func) {
+		["prompt", "yesno", "table", "box", "defList", "dashGrid", "wrap", "center", "print", "println", "verbose", "verboseln", "warn", "warnln", "die", "dieln", "loadFile", "saveFile", "appendFile"].forEach( function(func) {
 			global[func] = self[func].bind(self);
 		} );
 		

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pixl-cli",
-	"version": "1.1.1",
+	"version": "1.1.3",
 	"description": "Tools for building command-line apps for Node.js.",
 	"author": "Joseph Huckaby <jhuckaby@gmail.com>",
 	"homepage": "https://github.com/jhuckaby/pixl-cli",

package/util.js

@@ -32,8 +32,36 @@ function splitAnsiGraphemes(text) {
 	return units;
 }
 
+function preserveAnsiLineStyles(text) {
+	// A styled multi-line string normally relies on terminal modes carrying across
+	// newline characters.  Callers such as cli.box() insert independently styled
+	// borders between those lines, whose reset codes can cancel the content styles.
+	// Close all modes at each line ending, then restore the exact SGR state after the
+	// next border by replaying the original SGR history at the next line's start.
+	var lines = text.split('\n');
+	if (lines.length < 2) return text;
+	
+	var sgrHistory = '';
+	var sgrPattern = /^(?:\u001B\[|\u009B)[0-9:;]*m$/;
+	var reset = '\u001b[0m';
+	
+	return lines.map( function(line, idx) {
+		var reopen = sgrHistory;
+		
+		// Only sequences from the original text enter the history.  Synthetic reset
+		// and replay sequences added here must not accumulate on subsequent lines.
+		splitAnsiGraphemes(line).forEach( function(unit) {
+			if (unit.ansi && unit.text.match(sgrPattern)) sgrHistory += unit.text;
+		} );
+		
+		if ((idx < lines.length - 1) && sgrHistory) line += reset;
+		return reopen + line;
+	} ).join('\n');
+}
+
 module.exports = {
 	ansiPattern: ansiPattern,
 	graphemeSegmenter: graphemeSegmenter,
-	splitAnsiGraphemes: splitAnsiGraphemes
+	splitAnsiGraphemes: splitAnsiGraphemes,
+	preserveAnsiLineStyles: preserveAnsiLineStyles
 };

package/width.js

@@ -79,6 +79,26 @@ function truncate(text, width, suffix) {
 	var units = Util.splitAnsiGraphemes(text);
 	var trailingAnsi = [];
 	
+	// cli.emoji() surrounds one grapheme with cursor save, restore and movement
+	// sequences.  Treat this entire construct as one display unit so truncation
+	// can never keep the save sequence while discarding its matching restore.
+	for (var idx = 0; idx <= units.length - 4; idx++) {
+		if (
+			units[idx].ansi && (units[idx].text === '\u001b7') &&
+			!units[idx + 1].ansi &&
+			units[idx + 2].ansi && (units[idx + 2].text === '\u001b8') &&
+			units[idx + 3].ansi && (units[idx + 3].text === '\u001b[2C')
+		) {
+			var emojiUnit = units.slice(idx, idx + 4).map( function(unit) {
+				return unit.text;
+			} ).join('');
+			units.splice(idx, 4, {
+				text: emojiUnit,
+				ansi: false
+			});
+		}
+	}
+	
 	for (var idx = units.length - 1; idx >= 0; idx--) {
 		if (!units[idx].ansi) break;
 		if (units[idx].text.match(/^(?:\u001B\[|\u009B)[^m]*m$/)) {