console-toolkit 1.2.14 → 1.3.0

package/src/panel.d.ts

@@ -1,6 +1,10 @@
 import {SgrState} from './ansi/sgr-state.js';
 import Box from './box.js';
 import {StringsInput} from './strings.js';
+import {SplitOptions} from './strings/split.js';
+
+/** Sentinel character ('\x07' BELL) used to mark empty cells when placing text via `Panel.put()`. */
+export const EMPTY_CELL_SENTINEL: string;
 
 /** A single cell in a Panel. */
 export interface PanelCell {
@@ -22,7 +26,7 @@ export interface PanelToStringsOptions {
 
 /** Options for `Panel.put()`. */
 export interface PanelPutOptions {
-  /** Character treated as an empty cell (default: '\x07' BELL). */
+  /** Character treated as an empty cell (default: `EMPTY_CELL_SENTINEL`, '\x07' BELL). */
   emptySymbol?: string;
   /** If true, ignore control symbols when calculating width. */
   ignoreControlSymbols?: boolean;
@@ -132,7 +136,7 @@ export class Panel {
    * @returns This Panel (mutated).
    */
   copyFrom(x: number, y: number, width: number, height: number, panel: Panel, x1?: number, y1?: number): Panel;
-  /** Places text onto this panel at the given position. Characters matching `emptySymbol` (default: '\x07' BELL) are treated as empty cells.
+  /** Places text onto this panel at the given position. Characters matching `emptySymbol` (default: `EMPTY_CELL_SENTINEL`, '\x07' BELL) are treated as empty cells.
    * @param x - Left column.
    * @param y - Top row.
    * @param text - Content to place (Panel, Box, string, or string array).
@@ -152,15 +156,14 @@ export class Panel {
    * @param width - Region width.
    * @param height - Region height.
    * @param fn - Cell transformation function.
-   * @param options - Reserved for future use.
+   * @param options - Grapheme split options forwarded to width detection (for wide-character support).
    * @returns This Panel (mutated).
    */
-  applyFn(x: number, y: number, width: number, height: number, fn: ApplyFn): Panel;
+  applyFn(x: number, y: number, width: number, height: number, fn: ApplyFn, options?: SplitOptions): Panel;
 
   /** Fills the entire panel with a symbol and optional state.
    * @param symbol - Fill character.
    * @param state - SGR state.
-   * @param options - Reserved.
    * @returns This Panel (mutated).
    */
   fill(symbol: string, state?: SgrState | string | string[]): Panel;
@@ -171,7 +174,7 @@ export class Panel {
    * @param height - Region height.
    * @param symbol - Fill character.
    * @param state - SGR state.
-   * @param options - Reserved.
+   * @param options - Grapheme split options forwarded to width detection.
    * @returns This Panel (mutated).
    */
   fill(
@@ -180,7 +183,8 @@ export class Panel {
     width: number,
     height: number,
     symbol: string,
-    state?: SgrState | string | string[]
+    state?: SgrState | string | string[],
+    options?: SplitOptions
   ): Panel;
 
   /** Fills all cells with the given state, using `emptySymbol` for empty cells' symbol.
@@ -259,10 +263,10 @@ export class Panel {
    * @param y - Top row.
    * @param width - Region width.
    * @param height - Region height.
-   * @param options - Options passed to `applyFn()`.
+   * @param options - Grapheme split options forwarded to width detection.
    * @returns This Panel (mutated).
    */
-  clear(x: number, y?: number, width?: number, height?: number): Panel;
+  clear(x: number, y?: number, width?: number, height?: number, options?: SplitOptions): Panel;
 
   /** Pads the left side.
    * @param n - Columns.
@@ -296,7 +300,9 @@ export class Panel {
    * @returns This Panel (mutated).
    */
   padTopBottom(n: number, m: number): Panel;
-  /** Pads using CSS-style shorthand.
+  /** Pads using CSS-style shorthand. Padding adds null cells (rendered later via the
+   * `emptySymbol`/`emptyState` options of `toStrings()`); unlike `Box.pad`, this method
+   * intentionally has no `symbol` parameter — set the rendering character at draw time.
    * @param t - Top.
    * @param r - Right.
    * @param b - Bottom.

package/src/panel.js

@@ -15,15 +15,18 @@ import split, {size} from './strings/split.js';
 import Box from './box.js';
 import {addAliases} from './meta.js';
 
-/** A 2D array of cells, where each cell has a character symbol and an SGR state.
- * Provides methods for manipulation, styling, geometric transforms, and conversion to Box/strings.
- * @see {@link https://github.com/uhop/console-toolkit/wiki/Module:-panel}
- */
+export const EMPTY_CELL_SENTINEL = '\x07';
+
+const normalizeState = state => {
+  if (typeof state == 'string') return commandsToState(state.split(';'));
+  if (Array.isArray(state)) return commandsToState(state);
+  return toState(state);
+};
+
+const normalizeRegionArgs = (panel, x, y, width, height, options) =>
+  typeof x === 'object' ? [0, 0, panel.width, panel.height, x] : [x, y, width, height, options];
+
 export class Panel {
-  /** Creates an empty Panel of the given dimensions.
-   * @param {number} width - Width in columns.
-   * @param {number} height - Height in rows.
-   */
   constructor(width, height) {
     this.box = new Array(height);
     for (let i = 0; i < height; ++i) {
@@ -31,21 +34,14 @@ export class Panel {
     }
   }
 
-  /** The width of the panel in columns. */
   get width() {
     return this.box.length && this.box[0].length;
   }
 
-  /** The height of the panel in rows. */
   get height() {
     return this.box.length;
   }
 
-  /** Creates a Panel from various input types (Panel, Box, string, string[], function).
-   * @param {import('./strings.js').StringsInput} s - Input data.
-   * @param {object} [options] - Options passed to Box.make() or put().
-   * @returns {Panel}
-   */
   static make(s, options) {
     main: for (;;) {
       switch (typeof s) {
@@ -67,12 +63,6 @@ export class Panel {
     return panel;
   }
 
-  /** Converts the panel to an array of strings with embedded ANSI escape sequences.
-   * @param {object} [options] - Options.
-   * @param {string} [options.emptySymbol=' '] - Character for empty cells.
-   * @param {object} [options.emptyState] - SGR state for empty cells.
-   * @returns {string[]}
-   */
   toStrings(options = {}) {
     if (!this.height || !this.width) return Box.makeBlank(this.width, this.height).box;
 
@@ -102,21 +92,10 @@ export class Panel {
     return s;
   }
 
-  /** Converts the panel to a Box.
-   * @param {object} [options] - Options passed to toStrings().
-   * @returns {import('./box.js').Box}
-   */
   toBox(options) {
     return new Box(this.toStrings(options), true);
   }
 
-  /** Extracts a rectangular region as a new Panel.
-   * @param {number} [x=0] - Left column.
-   * @param {number} [y=0] - Top row.
-   * @param {number} [width] - Width (defaults to panel width).
-   * @param {number} [height] - Height (defaults to panel height).
-   * @returns {Panel}
-   */
   extract(x, y, width, height) {
     // normalize arguments
 
@@ -163,23 +142,10 @@ export class Panel {
     return panel;
   }
 
-  /** Creates a deep copy of this panel.
-   * @returns {Panel}
-   */
   clone() {
     return this.extract();
   }
 
-  /** Copies cells from another panel into this panel.
-   * @param {number} x - Destination x.
-   * @param {number} y - Destination y.
-   * @param {number} width - Width to copy.
-   * @param {number} height - Height to copy.
-   * @param {Panel} panel - Source panel.
-   * @param {number} [x1=0] - Source x.
-   * @param {number} [y1=0] - Source y.
-   * @returns {this}
-   */
   copyFrom(x, y, width, height, panel, x1 = 0, y1 = 0) {
     // normalize arguments
 
@@ -214,14 +180,6 @@ export class Panel {
     return this;
   }
 
-  /** Places text onto this panel at the given position. Characters matching `emptySymbol` (default: '\x07' BELL) are treated as empty cells.
-   * @param {number} x - Left column.
-   * @param {number} y - Top row.
-   * @param {import('./strings.js').StringsInput} text - Content to place.
-   * @param {object} [options] - Put options.
-   * @param {string} [options.emptySymbol='\x07'] - Character treated as an empty cell.
-   * @returns {this}
-   */
   put(x, y, text, options = {}) {
     if (text instanceof Panel) return this.copyFrom(x, y, text.width, text.height, text);
 
@@ -238,7 +196,7 @@ export class Panel {
     if (y >= this.height) return this;
     if (y + height > this.height) height = this.height - y;
 
-    const {emptySymbol = '\x07'} = options;
+    const {emptySymbol = EMPTY_CELL_SENTINEL} = options;
 
     // copy characters
     let state = {};
@@ -281,15 +239,6 @@ export class Panel {
     return this;
   }
 
-  /** Applies a function to each cell in a rectangular region.
-   * @param {number|Function} x - Left column, or the function if called with a single argument.
-   * @param {number} [y] - Top row.
-   * @param {number} [width] - Width.
-   * @param {number} [height] - Height.
-   * @param {Function} [fn] - Function `(x, y, cell) => newCell`.
-   * @param {object} [options] - Options.
-   * @returns {this}
-   */
   applyFn(x, y, width, height, fn, options) {
     // normalize arguments
 
@@ -336,16 +285,6 @@ export class Panel {
     return this;
   }
 
-  /** Fills a rectangular region with a symbol and state.
-   * @param {number|string} x - Left column, or symbol if filling the entire panel.
-   * @param {number} [y] - Top row.
-   * @param {number} [width] - Width.
-   * @param {number} [height] - Height.
-   * @param {string} [symbol] - Fill character.
-   * @param {object|string|string[]} [state={}] - SGR state.
-   * @param {object} [options] - Options.
-   * @returns {this}
-   */
   fill(x, y, width, height, symbol, state = {}, options) {
     if (typeof x === 'string') {
       symbol = x;
@@ -355,40 +294,14 @@ export class Panel {
       width = this.width;
       height = this.height;
     }
-    if (typeof state == 'string') {
-      state = commandsToState(state.split(';'));
-    } else if (Array.isArray(state)) {
-      state = commandsToState(state);
-    } else {
-      state = toState(state);
-    }
+    state = normalizeState(state);
     return this.applyFn(x, y, width, height, () => ({symbol, state}), options);
   }
 
-  /** Fills all cells with the given state, using `emptySymbol` for empty cells' symbol.
-   * @param {number|object} x - Left column, or options if filling the entire panel.
-   * @param {number} [y] - Top row.
-   * @param {number} [width] - Width.
-   * @param {number} [height] - Height.
-   * @param {object} [options] - Options with `state` and `emptySymbol`.
-   * @returns {this}
-   */
   fillState(x, y, width, height, options) {
-    if (typeof x === 'object') {
-      options = x;
-      x = 0;
-      y = 0;
-      width = this.width;
-      height = this.height;
-    }
+    [x, y, width, height, options] = normalizeRegionArgs(this, x, y, width, height, options);
     let {state = {}, emptySymbol = ' '} = options || {};
-    if (typeof state == 'string') {
-      state = commandsToState(state.split(';'));
-    } else if (Array.isArray(state)) {
-      state = commandsToState(state);
-    } else {
-      state = toState(state);
-    }
+    state = normalizeState(state);
     return this.applyFn(
       x,
       y,
@@ -399,57 +312,17 @@ export class Panel {
     );
   }
 
-  /** Fills state only for non-empty cells in a region.
-   * @param {number|object} x - Left column, or options if filling the entire panel.
-   * @param {number} [y] - Top row.
-   * @param {number} [width] - Width.
-   * @param {number} [height] - Height.
-   * @param {object} [options] - Options with `state`.
-   * @returns {this}
-   */
   fillNonEmptyState(x, y, width, height, options) {
-    if (typeof x === 'object') {
-      options = x;
-      x = 0;
-      y = 0;
-      width = this.width;
-      height = this.height;
-    }
+    [x, y, width, height, options] = normalizeRegionArgs(this, x, y, width, height, options);
     let {state = {}} = options || {};
-    if (typeof state == 'string') {
-      state = commandsToState(state.split(';'));
-    } else if (Array.isArray(state)) {
-      state = commandsToState(state);
-    } else {
-      state = toState(state);
-    }
+    state = normalizeState(state);
     return this.applyFn(x, y, width, height, (x, y, cell) => cell && {symbol: cell.symbol, state}, options);
   }
 
-  /** Combines a state before existing cell states (applied state acts as a base that cells override).
-   * @param {number|object} x - Left column, or options if filling the entire panel.
-   * @param {number} [y] - Top row.
-   * @param {number} [width] - Width.
-   * @param {number} [height] - Height.
-   * @param {object} [options] - Options with `state`, `emptySymbol`, `emptyState`.
-   * @returns {this}
-   */
   combineStateBefore(x, y, width, height, options) {
-    if (typeof x === 'object') {
-      options = x;
-      x = 0;
-      y = 0;
-      width = this.width;
-      height = this.height;
-    }
+    [x, y, width, height, options] = normalizeRegionArgs(this, x, y, width, height, options);
     let {state = {}, emptySymbol = ' ', emptyState = RESET_STATE} = options || {};
-    if (typeof state == 'string') {
-      state = commandsToState(state.split(';'));
-    } else if (Array.isArray(state)) {
-      state = commandsToState(state);
-    } else {
-      state = toState(state);
-    }
+    state = normalizeState(state);
     return this.applyFn(
       x,
       y,
@@ -463,30 +336,10 @@ export class Panel {
     );
   }
 
-  /** Combines a state after existing cell states (applied state overrides cell properties).
-   * @param {number|object} x - Left column, or options if filling the entire panel.
-   * @param {number} [y] - Top row.
-   * @param {number} [width] - Width.
-   * @param {number} [height] - Height.
-   * @param {object} [options] - Options with `state`, `emptySymbol`, `emptyState`.
-   * @returns {this}
-   */
   combineStateAfter(x, y, width, height, options) {
-    if (typeof x === 'object') {
-      options = x;
-      x = 0;
-      y = 0;
-      width = this.width;
-      height = this.height;
-    }
+    [x, y, width, height, options] = normalizeRegionArgs(this, x, y, width, height, options);
     let {state = {}, emptySymbol = ' ', emptyState = RESET_STATE} = options || {};
-    if (typeof state == 'string') {
-      state = commandsToState(state.split(';'));
-    } else if (Array.isArray(state)) {
-      state = commandsToState(state);
-    } else {
-      state = toState(state);
-    }
+    state = normalizeState(state);
     return this.applyFn(
       x,
       y,
@@ -500,14 +353,6 @@ export class Panel {
     );
   }
 
-  /** Clears (nullifies) cells in a rectangular region.
-   * @param {number} [x=0] - Left column.
-   * @param {number} [y=0] - Top row.
-   * @param {number} [width] - Width.
-   * @param {number} [height] - Height.
-   * @param {object} [options] - Options.
-   * @returns {this}
-   */
   clear(x, y, width, height, options) {
     // normalize arguments
     if (typeof x != 'number') {
@@ -528,10 +373,6 @@ export class Panel {
     return this.applyFn(x, y, width, height, () => null, options);
   }
 
-  /** Pads the left side with `n` empty columns.
-   * @param {number} n
-   * @returns {this}
-   */
   padLeft(n) {
     if (n <= 0) return this;
 
@@ -543,10 +384,6 @@ export class Panel {
     return this;
   }
 
-  /** Pads the right side with `n` empty columns.
-   * @param {number} n
-   * @returns {this}
-   */
   padRight(n) {
     if (n <= 0) return this;
 
@@ -558,11 +395,6 @@ export class Panel {
     return this;
   }
 
-  /** Pads left and right sides with empty cells.
-   * @param {number} n - Left columns.
-   * @param {number} m - Right columns.
-   * @returns {this}
-   */
   padLeftRight(n, m) {
     if (n <= 0) return this.padRight(m);
     if (m <= 0) return this.padLeft(n);
@@ -574,10 +406,6 @@ export class Panel {
     return this;
   }
 
-  /** Pads the top with `n` empty rows.
-   * @param {number} n
-   * @returns {this}
-   */
   padTop(n) {
     if (n <= 0) return this;
 
@@ -588,10 +416,6 @@ export class Panel {
     return this;
   }
 
-  /** Pads the bottom with `n` empty rows.
-   * @param {number} n
-   * @returns {this}
-   */
   padBottom(n) {
     if (n <= 0) return this;
 
@@ -602,11 +426,6 @@ export class Panel {
     return this;
   }
 
-  /** Pads top and bottom with empty rows.
-   * @param {number} n - Top rows.
-   * @param {number} m - Bottom rows.
-   * @returns {this}
-   */
   padTopBottom(n, m) {
     if (n <= 0) return this.padBottom(m);
     if (m <= 0) return this.padTop(n);
@@ -622,13 +441,6 @@ export class Panel {
     return this;
   }
 
-  /** Pads the panel using CSS-style shorthand (top, right, bottom, left).
-   * @param {number} t - Top (or all sides if only argument).
-   * @param {number} [r] - Right.
-   * @param {number} [b] - Bottom.
-   * @param {number} [l] - Left.
-   * @returns {this}
-   */
   pad(t, r, b, l) {
     // use values according to CSS rules
     if (typeof r != 'number') {
@@ -643,11 +455,6 @@ export class Panel {
     return this.padLeftRight(l, r).padTopBottom(t, b);
   }
 
-  /** Removes `n` columns starting at column `x`.
-   * @param {number} x - Start column.
-   * @param {number} n - Number of columns to remove.
-   * @returns {this}
-   */
   removeColumns(x, n) {
     // normalize arguments
     if (x < 0) {
@@ -661,11 +468,6 @@ export class Panel {
     return this;
   }
 
-  /** Removes `n` rows starting at row `y`.
-   * @param {number} y - Start row.
-   * @param {number} n - Number of rows to remove.
-   * @returns {this}
-   */
   removeRows(y, n) {
     // normalize arguments
     if (y < 0) {
@@ -679,11 +481,6 @@ export class Panel {
     return this;
   }
 
-  /** Resizes the panel horizontally.
-   * @param {number} newWidth - New width.
-   * @param {'left'|'center'|'right'} [align='right'] - Alignment when adding/removing columns.
-   * @returns {this}
-   */
   resizeH(newWidth, align = 'right') {
     if (!this.width) return this.padRight(newWidth);
 
@@ -704,11 +501,6 @@ export class Panel {
     return diff < 0 ? this.removeColumns(newWidth, -diff) : this.padRight(diff);
   }
 
-  /** Resizes the panel vertically.
-   * @param {number} newHeight - New height.
-   * @param {'top'|'center'|'bottom'} [align='bottom'] - Alignment when adding/removing rows.
-   * @returns {this}
-   */
   resizeV(newHeight, align = 'bottom') {
     if (!this.height) return this.padBottom(newHeight);
 
@@ -729,13 +521,6 @@ export class Panel {
     return diff < 0 ? this.removeRows(newHeight, -diff) : this.padBottom(diff);
   }
 
-  /** Resizes the panel in both dimensions.
-   * @param {number} newWidth - New width.
-   * @param {number} newHeight - New height.
-   * @param {'left'|'center'|'right'} [horizontal='right'] - Horizontal alignment.
-   * @param {'top'|'center'|'bottom'} [vertical='bottom'] - Vertical alignment.
-   * @returns {this}
-   */
   resize(newWidth, newHeight, horizontal = 'right', vertical = 'bottom') {
     if (!this.height) return this.padBottom(newHeight).padRight(newWidth);
 
@@ -744,11 +529,6 @@ export class Panel {
       : this.resizeH(newWidth, horizontal).resizeV(newHeight, vertical);
   }
 
-  /** Inserts `n` empty columns at position `x`.
-   * @param {number} x - Insert position.
-   * @param {number} n - Number of columns.
-   * @returns {this}
-   */
   insertColumns(x, n) {
     // normalize arguments
     if (n <= 0) return this;
@@ -760,11 +540,6 @@ export class Panel {
     return this;
   }
 
-  /** Inserts `n` empty rows at position `y`.
-   * @param {number} y - Insert position.
-   * @param {number} n - Number of rows.
-   * @returns {this}
-   */
   insertRows(y, n) {
     // normalize arguments
     if (n <= 0) return this;
@@ -777,12 +552,6 @@ export class Panel {
     return this;
   }
 
-  /** Appends another panel below this one.
-   * @param {Panel} panel - Panel to append.
-   * @param {object} [options] - Options.
-   * @param {'left'|'center'|'right'} [options.align='left'] - Horizontal alignment.
-   * @returns {this}
-   */
   addBottom(panel, {align = 'left'} = {}) {
     panel = panel.clone();
 
@@ -825,12 +594,6 @@ export class Panel {
     return this;
   }
 
-  /** Appends another panel to the right of this one.
-   * @param {Panel} panel - Panel to append.
-   * @param {object} [options] - Options.
-   * @param {'top'|'center'|'bottom'} [options.align='top'] - Vertical alignment.
-   * @returns {this}
-   */
   addRight(panel, {align = 'top'} = {}) {
     panel = panel.clone();
 
@@ -909,9 +672,6 @@ export class Panel {
     return this;
   }
 
-  /** Returns a new Panel that is the transpose of this one (rows become columns).
-   * @returns {Panel}
-   */
   transpose() {
     const panel = new Panel(this.height, this.width);
     for (let i = 0; i < this.height; ++i) {
@@ -924,9 +684,6 @@ export class Panel {
     return panel;
   }
 
-  /** Returns a new Panel rotated 90° clockwise.
-   * @returns {Panel}
-   */
   rotateRight() {
     const panel = new Panel(this.height, this.width);
     for (let i = 0; i < this.height; ++i) {
@@ -939,9 +696,6 @@ export class Panel {
     return panel;
   }
 
-  /** Returns a new Panel rotated 90° counter-clockwise.
-   * @returns {Panel}
-   */
   rotateLeft() {
     const panel = new Panel(this.height, this.width);
     for (let i = 0; i < this.height; ++i) {
@@ -954,17 +708,11 @@ export class Panel {
     return panel;
   }
 
-  /** Flips the panel horizontally (mirrors left-right) in place.
-   * @returns {this}
-   */
   flipH() {
     for (const row of this.box) row.reverse();
     return this;
   }
 
-  /** Flips the panel vertically (mirrors top-bottom) in place.
-   * @returns {this}
-   */
   flipV() {
     this.box.reverse();
     return this;
@@ -973,9 +721,6 @@ export class Panel {
 
 addAliases(Panel, {combineState: 'combineStateAfter', toPanel: 'clone'});
 
-/** Alias for `Panel.make()`. Creates a Panel from various input types.
- * @type {typeof Panel.make}
- */
 export const toPanel = Panel.make;
 
 export default Panel;