@oclif/table 0.3.9 → 0.4.2

package/lib/table.js

@@ -8,38 +8,15 @@ import React from 'react';
 import stripAnsi from 'strip-ansi';
 import wrapAnsi from 'wrap-ansi';
 import { BORDER_SKELETONS } from './skeletons.js';
-import { allKeysInCollection, determineWidthOfWrappedText, getColumns, getHeadings, intersperse, maybeStripAnsi, shouldUsePlainTable, sortData, } from './utils.js';
-/**
- * Determines the configured width based on the provided width value.
- * If no width is provided, it returns the width of the current terminal.
- * If the provided width is a percentage, it calculates the width based on the percentage of the terminal width.
- * If the provided width is a number, it returns the provided width.
- * If the calculated width is greater than the terminal width, it returns the terminal width.
- *
- * @param providedWidth - The width value provided.
- * @returns The determined configured width.
- */
-function determineConfiguredWidth(providedWidth, columns = process.stdout.columns) {
-    if (!providedWidth)
-        return columns;
-    const num = typeof providedWidth === 'string' && providedWidth.endsWith('%')
-        ? Math.floor((Number.parseInt(providedWidth, 10) / 100) * columns)
-        : typeof providedWidth === 'string'
-            ? Number.parseInt(providedWidth, 10)
-            : providedWidth;
-    if (num > columns) {
-        return columns;
-    }
-    return num;
-}
+import { allKeysInCollection, determineConfiguredWidth, determineWidthOfWrappedText, getColumns, getHeadings, intersperse, maybeStripAnsi, shouldUsePlainTable, sortData, } from './utils.js';
 /**
  * Determine the width to use for the table.
  *
  * This allows us to use the minimum width required to display the table if the configured width is too small.
  */
-function determineWidthToUse(columns, configuredWidth) {
+function determineWidthToUse(columns, maxWidth, width) {
     const tableWidth = columns.map((c) => c.width).reduce((a, b) => a + b, 0) + columns.length + 1;
-    return tableWidth < configuredWidth ? configuredWidth : tableWidth;
+    return width ?? (tableWidth < maxWidth ? maxWidth : tableWidth);
 }
 function determineTruncatePosition(overflow) {
     switch (overflow) {
@@ -134,20 +111,22 @@ export function formatTextWithMargins({ horizontalAlignment, overflow, padding,
     };
 }
 function setup(props) {
-    const { data, filter, horizontalAlignment = 'left', maxWidth, noStyle = false, overflow = 'truncate', padding = 1, sort, title, verticalAlignment = 'top', } = props;
+    const { data, filter, horizontalAlignment = 'left', maxWidth, noStyle = false, overflow = 'truncate', padding = 1, sort, title, verticalAlignment = 'top', width, } = props;
     const headerOptions = noStyle ? {} : { bold: true, color: 'blue', ...props.headerOptions };
     const borderStyle = noStyle ? 'none' : (props.borderStyle ?? 'all');
     const borderColor = noStyle ? undefined : props.borderColor;
     const borderProps = { color: borderColor };
     const titleOptions = noStyle ? {} : props.titleOptions;
     const processedData = maybeStripAnsi(sortData(filter ? data.filter((row) => filter(row)) : data, sort), noStyle);
+    const tableWidth = width ? determineConfiguredWidth(width) : undefined;
     const config = {
         borderStyle,
         columns: props.columns ?? allKeysInCollection(data),
         data: processedData,
         headerOptions,
         horizontalAlignment,
-        maxWidth: determineConfiguredWidth(maxWidth),
+        maxWidth: tableWidth ?? determineConfiguredWidth(maxWidth),
+        width: tableWidth,
         overflow,
         padding,
         verticalAlignment,
@@ -215,7 +194,7 @@ function setup(props) {
 }
 export function Table(props) {
     const { columns, config, dataComponent, footerComponent, headerComponent, headerFooterComponent, headingComponent, headings, processedData, separatorComponent, title, titleOptions, } = setup(props);
-    return (React.createElement(Box, { flexDirection: "column", width: determineWidthToUse(columns, config.maxWidth) },
+    return (React.createElement(Box, { flexDirection: "column", width: determineWidthToUse(columns, config.maxWidth, config.width) },
         title && React.createElement(Text, { ...titleOptions }, title),
         headerComponent({ columns, data: {}, key: 'header' }),
         headingComponent({ columns, data: headings, key: 'heading' }),

package/lib/types.d.ts

@@ -4,6 +4,7 @@ export type CellProps = React.PropsWithChildren<{
 }>;
 export type HorizontalAlignment = 'left' | 'right' | 'center';
 export type VerticalAlignment = 'top' | 'center' | 'bottom';
+export type Percentage = `${number}%`;
 export type ColumnProps<T> = {
     /**
      * Horizontal alignment of cell content. Overrides the horizontal alignment set in the table.
@@ -26,11 +27,14 @@ export type ColumnProps<T> = {
      * Vertical alignment of cell content. Overrides the vertical alignment set in the table.
      */
     verticalAlignment?: VerticalAlignment;
+    /**
+     * Set the width of the column. If not provided, it will default to the width of the content.
+     */
+    width?: Percentage | number;
 };
 export type AllColumnProps<T> = {
     [K in keyof T]: ColumnProps<K>;
 }[keyof T];
-export type Percentage = `${number}%`;
 type TextOptions = {
     color?: SupportedColor;
     backgroundColor?: SupportedColor;
@@ -70,15 +74,35 @@ export type TableOptions<T extends Record<string, unknown>> = {
      */
     padding?: number;
     /**
-     * Width of the table. Can be a number (e.g. 80) or a percentage (e.g. '80%').
+     * Maximum width of the table. Can be a number (e.g. 80) or a percentage (e.g. '80%').
      *
-     * If not provided, it will default to the width of the terminal (determined by `process.stdout.columns`).
+     * By default, the table will only take up as much space as it needs to fit the content. If it extends beyond the maximum width,
+     * it will wrap or truncate the content based on the `overflow` option. In other words, this property allows you to set the width
+     * at which wrapping or truncation occurs.
+     *
+     * If not provided, the maximum width will default to the terminal width.
      *
      * If you provide a number or percentage that is larger than the terminal width, it will default to the terminal width.
      *
      * If you provide a number or percentage that is too small to fit the table, it will default to the minimum width of the table.
      */
     maxWidth?: Percentage | number;
+    /**
+     * Exact width of the table. Can be a number (e.g. 80) or a percentage (e.g. '80%').
+     *
+     * By default, the table will only take up as much space as it needs to fit the content. If you set the `width` option, the table will
+     * always take up that amount of space, regardless of the content. If the content is too large, it will wrap or truncate based on the
+     * `overflow` option. If it's too small, it will add empty space evenly across the columns.
+     *
+     * Setting this property will override the `maxWidth` option.
+     *
+     * If not provided, it will default to the natural width of the table.
+     *
+     * If you provide a number or percentage that is larger than the terminal width, it will default to the terminal width.
+     *
+     * If you provide a number or percentage that is too small to fit the table, it will default to the minimum width of the table.
+     */
+    width?: Percentage | number;
     /**
      * Overflow behavior for cells. Defaults to 'truncate'.
      */
@@ -159,6 +183,7 @@ export type Config<T> = {
     borderStyle: BorderStyle;
     horizontalAlignment: HorizontalAlignment;
     verticalAlignment: VerticalAlignment;
+    width: number | undefined;
 };
 export type RowConfig = {
     /**

package/lib/utils.d.ts

@@ -1,4 +1,4 @@
-import { Column, Config, Sort } from './types.js';
+import { Column, Config, Percentage, Sort } from './types.js';
 /**
  * Intersperses a list of elements with another element.
  *
@@ -11,6 +11,17 @@ export declare function intersperse<T, I>(intersperser: (index: number) => I, el
 export declare function sortData<T extends Record<string, unknown>>(data: T[], sort?: Sort<T> | undefined): T[];
 export declare function allKeysInCollection<T extends Record<string, unknown>>(data: T[]): (keyof T)[];
 export declare function determineWidthOfWrappedText(text: string): number;
+/**
+ * Determines the configured width based on the provided width value.
+ * If no width is provided, it returns the width of the current terminal.
+ * If the provided width is a percentage, it calculates the width based on the percentage of the terminal width.
+ * If the provided width is a number, it returns the provided width.
+ * If the calculated width is greater than the terminal width, it returns the terminal width.
+ *
+ * @param providedWidth - The width value provided.
+ * @returns The determined configured width.
+ */
+export declare function determineConfiguredWidth(providedWidth: number | Percentage | undefined, columns?: number): number;
 export declare function getColumns<T extends Record<string, unknown>>(config: Config<T>, headings: Partial<T>): Column<T>[];
 export declare function getHeadings<T extends Record<string, unknown>>(config: Config<T>): Partial<T>;
 export declare function maybeStripAnsi<T extends Record<string, unknown>[]>(data: T, noStyle: boolean): T;

package/lib/utils.js

@@ -42,8 +42,31 @@ export function determineWidthOfWrappedText(text) {
     const lines = text.split('\n');
     return lines.reduce((max, line) => Math.max(max, line.length), 0);
 }
+/**
+ * Determines the configured width based on the provided width value.
+ * If no width is provided, it returns the width of the current terminal.
+ * If the provided width is a percentage, it calculates the width based on the percentage of the terminal width.
+ * If the provided width is a number, it returns the provided width.
+ * If the calculated width is greater than the terminal width, it returns the terminal width.
+ *
+ * @param providedWidth - The width value provided.
+ * @returns The determined configured width.
+ */
+export function determineConfiguredWidth(providedWidth, columns = process.stdout.columns) {
+    if (!providedWidth)
+        return columns;
+    const num = typeof providedWidth === 'string' && providedWidth.endsWith('%')
+        ? Math.floor((Number.parseInt(providedWidth, 10) / 100) * columns)
+        : typeof providedWidth === 'string'
+            ? Number.parseInt(providedWidth, 10)
+            : providedWidth;
+    if (num > columns) {
+        return columns;
+    }
+    return num;
+}
 export function getColumns(config, headings) {
-    const { columns, horizontalAlignment, maxWidth, overflow, verticalAlignment } = config;
+    const { columns, horizontalAlignment, maxWidth, overflow, verticalAlignment, width } = config;
     const widths = columns.map((propsOrKey) => {
         const props = typeof propsOrKey === 'object' ? propsOrKey : { key: propsOrKey };
         const { key } = props;
@@ -53,10 +76,16 @@ export function getColumns(config, headings) {
             const value = data[key];
             if (value === undefined || value === null)
                 return 0;
+            // Some terminals don't play nicely with zero-width characters, so we replace them with spaces.
+            // https://github.com/sindresorhus/terminal-link/issues/18
+            // https://github.com/Shopify/cli/pull/995
             return determineWidthOfWrappedText(stripAnsi(String(value).replaceAll('​', ' ')));
         });
         const header = String(headings[key]).length;
-        const width = Math.max(...data, header) + padding * 2;
+        // If a column width is provided, use that. Otherwise, use the width of the largest cell in the column.
+        const columnWidth = props.width
+            ? determineConfiguredWidth(props.width, width ?? maxWidth)
+            : Math.max(...data, header) + padding * 2;
         return {
             column: key,
             horizontalAlignment: props.horizontalAlignment ?? horizontalAlignment,
@@ -64,7 +93,7 @@ export function getColumns(config, headings) {
             overflow: props.overflow ?? overflow,
             padding,
             verticalAlignment: props.verticalAlignment ?? verticalAlignment,
-            width,
+            width: columnWidth,
         };
     });
     const numberOfBorders = widths.length + 1;
@@ -93,6 +122,18 @@ export function getColumns(config, headings) {
     seen.clear();
     // At most, reduce the width to the padding + 3
     reduceColumnWidths((col) => col.padding * 2 + 3);
+    // If the table width was provided AND it's greater than the calculated table width, expand the columns to fill the width
+    if (width && width > tableWidth) {
+        const extraWidth = width - tableWidth;
+        const extraWidthPerColumn = Math.floor(extraWidth / widths.length);
+        for (const w of widths) {
+            w.width += extraWidthPerColumn;
+            // if it's the last column, add all the remaining width
+            if (w === widths.at(-1)) {
+                w.width += extraWidth - extraWidthPerColumn * widths.length;
+            }
+        }
+    }
     return widths;
 }
 export function getHeadings(config) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/table",
   "description": "Display table in terminal",
-  "version": "0.3.9",
+  "version": "0.4.2",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/table/issues",
   "dependencies": {
@@ -9,7 +9,7 @@
     "@types/react": "^18.3.12",
     "change-case": "^5.4.4",
     "cli-truncate": "^4.0.0",
-    "ink": "^5.1.0",
+    "ink": "5.0.1",
     "natural-orderby": "^3.0.2",
     "object-hash": "^3.0.0",
     "react": "^18.3.1",
@@ -19,13 +19,13 @@
   "devDependencies": {
     "@commitlint/config-conventional": "^19",
     "@oclif/prettier-config": "^0.2.1",
-    "@oclif/test": "^4.1.3",
+    "@oclif/test": "^4.1.6",
     "@types/chai": "^4.3.16",
     "@types/mocha": "^10.0.10",
     "@types/node": "^18",
     "@types/object-hash": "^3.0.6",
     "@types/sinon": "^17.0.3",
-    "ansis": "^3.3.2",
+    "ansis": "^3.5.2",
     "chai": "^4.5.0",
     "commitlint": "^19",
     "eslint": "^8.57.0",
@@ -34,7 +34,7 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-config-xo": "^0.45.0",
     "eslint-config-xo-react": "^0.27.0",
-    "eslint-plugin-react": "^7.37.2",
+    "eslint-plugin-react": "^7.37.3",
     "eslint-plugin-react-hooks": "^4.6.2",
     "husky": "^9.1.7",
     "ink-testing-library": "^4.0.0",