@oclif/table 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Salesforce.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+<img src="https://user-images.githubusercontent.com/449385/38243295-e0a47d58-372e-11e8-9bc0-8c02a6f4d2ac.png" width="260" height="73">
+
+[![Version](https://img.shields.io/npm/v/@oclif/table.svg)](https://npmjs.org/package/@oclif/table)
+[![Downloads/week](https://img.shields.io/npm/dw/@oclif/table.svg)](https://npmjs.org/package/@oclif/table)
+[![License](https://img.shields.io/npm/l/@oclif/table.svg)](https://github.com/oclif/table/blob/main/LICENSE)
+
+# Description
+
+Print tables to the terminal using [ink](https://www.npmjs.com/package/ink)
+
+# Examples
+
+You can see examples of how to use it in the [examples](./examples/) directory.
+
+You can run any of these with the following:
+
+```
+tsx examples/basic.ts
+```
+
+# Contributing
+
+See the [contributing guide](./CONRTIBUTING.md).

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { makeTable, makeTables } from './table.js';
+export type { TableProps } from './types.js';

package/lib/index.js

@@ -0,0 +1 @@
+export { makeTable, makeTables } from './table.js';

package/lib/skeletons.d.ts

@@ -0,0 +1,17 @@
+export declare const BORDER_STYLES: readonly ["all", "headers-only-with-outline", "headers-only-with-underline", "headers-only", "horizontal-with-outline", "horizontal", "none", "outline", "vertical-with-outline", "vertical"];
+export type BorderStyle = (typeof BORDER_STYLES)[number];
+type Skeleton = {
+    cross: string;
+    left: string;
+    line: string;
+    right: string;
+};
+export declare const BORDER_SKELETONS: Record<BorderStyle, {
+    data: Skeleton;
+    footer: Skeleton;
+    header: Skeleton;
+    heading: Skeleton;
+    separator: Skeleton;
+    headerFooter?: Skeleton;
+}>;
+export {};

package/lib/skeletons.js

@@ -0,0 +1,358 @@
+export const BORDER_STYLES = [
+    'all',
+    'headers-only-with-outline',
+    'headers-only-with-underline',
+    'headers-only',
+    'horizontal-with-outline',
+    'horizontal',
+    'none',
+    'outline',
+    'vertical-with-outline',
+    'vertical',
+];
+export const BORDER_SKELETONS = {
+    all: {
+        data: {
+            cross: '│',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        footer: {
+            cross: '┴',
+            left: '└',
+            line: '─',
+            right: '┘',
+        },
+        header: {
+            cross: '┬',
+            left: '┌',
+            line: '─',
+            right: '┐',
+        },
+        heading: {
+            cross: '│',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        separator: {
+            cross: '┼',
+            left: '├',
+            line: '─',
+            right: '┤',
+        },
+    },
+    'headers-only': {
+        data: {
+            cross: ' ',
+            left: ' ',
+            line: ' ',
+            right: ' ',
+        },
+        footer: {
+            cross: '',
+            left: '',
+            line: '',
+            right: '',
+        },
+        header: {
+            cross: '─',
+            left: '┌',
+            line: '─',
+            right: '┐',
+        },
+        headerFooter: {
+            cross: '─',
+            left: '└',
+            line: '─',
+            right: '┘',
+        },
+        heading: {
+            cross: ' ',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        separator: {
+            cross: '',
+            left: '',
+            line: '',
+            right: '',
+        },
+    },
+    'headers-only-with-outline': {
+        data: {
+            cross: ' ',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        footer: {
+            cross: '─',
+            left: '└',
+            line: '─',
+            right: '┘',
+        },
+        header: {
+            cross: '─',
+            left: '┌',
+            line: '─',
+            right: '┐',
+        },
+        headerFooter: {
+            cross: '─',
+            left: '├',
+            line: '─',
+            right: '┤',
+        },
+        heading: {
+            cross: ' ',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        separator: {
+            cross: '',
+            left: '',
+            line: '',
+            right: '',
+        },
+    },
+    'headers-only-with-underline': {
+        data: {
+            cross: ' ',
+            left: ' ',
+            line: ' ',
+            right: ' ',
+        },
+        footer: {
+            cross: '',
+            left: '',
+            line: '',
+            right: '',
+        },
+        header: {
+            cross: '',
+            left: '',
+            line: '',
+            right: '',
+        },
+        headerFooter: {
+            cross: '─',
+            left: ' ',
+            line: '─',
+            right: ' ',
+        },
+        heading: {
+            cross: ' ',
+            left: ' ',
+            line: ' ',
+            right: ' ',
+        },
+        separator: {
+            cross: '',
+            left: '',
+            line: '',
+            right: '',
+        },
+    },
+    horizontal: {
+        data: {
+            cross: ' ',
+            left: ' ',
+            line: ' ',
+            right: ' ',
+        },
+        footer: {
+            cross: '─',
+            left: '─',
+            line: '─',
+            right: '─',
+        },
+        header: {
+            cross: ' ',
+            left: ' ',
+            line: ' ',
+            right: ' ',
+        },
+        heading: {
+            cross: ' ',
+            left: ' ',
+            line: ' ',
+            right: ' ',
+        },
+        separator: {
+            cross: '─',
+            left: '─',
+            line: '─',
+            right: '─',
+        },
+    },
+    'horizontal-with-outline': {
+        data: {
+            cross: ' ',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        footer: {
+            cross: '─',
+            left: '└',
+            line: '─',
+            right: '┘',
+        },
+        header: {
+            cross: '─',
+            left: '┌',
+            line: '─',
+            right: '┐',
+        },
+        heading: {
+            cross: ' ',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        separator: {
+            cross: '─',
+            left: '├',
+            line: '─',
+            right: '┤',
+        },
+    },
+    none: {
+        data: {
+            cross: ' ',
+            left: ' ',
+            line: ' ',
+            right: ' ',
+        },
+        footer: {
+            cross: ' ',
+            left: ' ',
+            line: ' ',
+            right: ' ',
+        },
+        header: {
+            cross: ' ',
+            left: ' ',
+            line: ' ',
+            right: ' ',
+        },
+        heading: {
+            cross: ' ',
+            left: ' ',
+            line: ' ',
+            right: ' ',
+        },
+        separator: {
+            cross: '',
+            left: '',
+            line: '',
+            right: '',
+        },
+    },
+    outline: {
+        data: {
+            cross: ' ',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        footer: {
+            cross: '─',
+            left: '└',
+            line: '─',
+            right: '┘',
+        },
+        header: {
+            cross: '─',
+            left: '┌',
+            line: '─',
+            right: '┐',
+        },
+        heading: {
+            cross: ' ',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        separator: {
+            cross: '',
+            left: '',
+            line: '',
+            right: '',
+        },
+    },
+    vertical: {
+        data: {
+            cross: '│',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        footer: {
+            cross: '',
+            left: '',
+            line: '',
+            right: '',
+        },
+        header: {
+            cross: ' ',
+            left: ' ',
+            line: ' ',
+            right: ' ',
+        },
+        heading: {
+            cross: '│',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        separator: {
+            cross: '',
+            left: '',
+            line: '',
+            right: '',
+        },
+    },
+    'vertical-with-outline': {
+        data: {
+            cross: '│',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        footer: {
+            cross: '┴',
+            left: '└',
+            line: '─',
+            right: '┘',
+        },
+        header: {
+            cross: '┬',
+            left: '┌',
+            line: '─',
+            right: '┐',
+        },
+        headerFooter: {
+            cross: '┼',
+            left: '├',
+            line: '─',
+            right: '┤',
+        },
+        heading: {
+            cross: '│',
+            left: '│',
+            line: ' ',
+            right: '│',
+        },
+        separator: {
+            cross: '',
+            left: '',
+            line: '',
+            right: '',
+        },
+    },
+};

package/lib/table.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+import { CellProps, ContainerProps, ScalarDict, TableProps } from './types.js';
+export declare function Table<T extends ScalarDict>(props: TableProps<T>): React.JSX.Element;
+/**
+ * Renders the header of a table.
+ */
+export declare function Header(props: React.PropsWithChildren): React.JSX.Element;
+/**
+ * Renders a cell in the table.
+ */
+export declare function Cell(props: CellProps): React.JSX.Element;
+/**
+ * Renders the scaffold of the table.
+ */
+export declare function Skeleton(props: React.PropsWithChildren & {
+    readonly height?: number;
+}): React.JSX.Element;
+/**
+ * Renders a table with the given data.
+ * @param options see {@link TableProps}
+ */
+export declare function makeTable<T extends ScalarDict>(options: TableProps<T>): void;
+export declare function makeTables<T extends ScalarDict[]>(tables: {
+    [P in keyof T]: TableProps<T[P]>;
+}, options?: Omit<ContainerProps, 'children'>): void;

package/lib/table.js

@@ -0,0 +1,238 @@
+/* eslint-disable react/prop-types */
+import cliTruncate from 'cli-truncate';
+import { Box, Text, render } from 'ink';
+import { sha1 } from 'object-hash';
+import React from 'react';
+import stripAnsi from 'strip-ansi';
+import wrapAnsi from 'wrap-ansi';
+import { BORDER_SKELETONS } from './skeletons.js';
+import { allKeysInCollection, getColumns, getHeadings, intersperse, maybeStripAnsi, 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;
+}
+/**
+ * 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) {
+    const tableWidth = columns.map((c) => c.width).reduce((a, b) => a + b) + columns.length + 1;
+    return tableWidth < configuredWidth ? configuredWidth : tableWidth;
+}
+export function Table(props) {
+    const { data, filter, horizontalAlignment = 'left', maxWidth, noStyle = false, orientation = 'horizontal', overflow = 'truncate', padding = 1, sort, title, verticalAlignment = 'top', } = 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 config = {
+        borderStyle,
+        columns: props.columns ?? allKeysInCollection(data),
+        data: processedData,
+        headerOptions,
+        horizontalAlignment,
+        maxWidth: determineConfiguredWidth(maxWidth),
+        overflow,
+        padding,
+        verticalAlignment,
+    };
+    const headings = getHeadings(config);
+    const columns = getColumns(config, headings);
+    const dataComponent = row({
+        borderProps,
+        cell: Cell,
+        skeleton: BORDER_SKELETONS[config.borderStyle].data,
+    });
+    const footerComponent = row({
+        borderProps,
+        cell: Skeleton,
+        props: borderProps,
+        skeleton: BORDER_SKELETONS[config.borderStyle].footer,
+    });
+    const headerComponent = row({
+        borderProps,
+        cell: Skeleton,
+        props: borderProps,
+        skeleton: BORDER_SKELETONS[config.borderStyle].header,
+    });
+    const { headerFooter } = BORDER_SKELETONS[config.borderStyle];
+    const headerFooterComponent = headerFooter
+        ? row({
+            borderProps,
+            cell: Skeleton,
+            props: borderProps,
+            skeleton: headerFooter,
+        })
+        : () => false;
+    const headingComponent = row({
+        borderProps,
+        cell: Header,
+        props: config.headerOptions,
+        skeleton: BORDER_SKELETONS[config.borderStyle].heading,
+    });
+    const separatorComponent = row({
+        borderProps,
+        cell: Skeleton,
+        props: borderProps,
+        skeleton: BORDER_SKELETONS[config.borderStyle].separator,
+    });
+    if (orientation === 'vertical') {
+        return (React.createElement(Box, { flexDirection: "column", width: determineWidthToUse(columns, config.maxWidth), paddingBottom: 1 },
+            title && React.createElement(Text, { ...titleOptions }, title),
+            processedData.map((row, index) => {
+                // Calculate the hash of the row based on its value and position
+                const key = `row-${sha1(row)}-${index}`;
+                const maxKeyLength = Math.max(...Object.values(headings).map((c) => c.length));
+                // Construct a row.
+                return (React.createElement(Box, { key: key, borderTop: true, borderBottom: false, borderLeft: false, borderRight: false, flexDirection: "column", borderStyle: noStyle ? undefined : 'single', borderColor: borderColor }, columns.map((column) => {
+                    const value = (row[column.column] ?? '').toString();
+                    const keyName = (headings[column.key] ?? column.key).toString();
+                    const keyPadding = ' '.repeat(maxKeyLength - keyName.length + padding);
+                    return (React.createElement(Box, { key: `${key}-cell-${column.key}`, flexWrap: "wrap" },
+                        React.createElement(Text, { ...config.headerOptions },
+                            keyName,
+                            keyPadding),
+                        React.createElement(Text, { wrap: overflow }, value)));
+                })));
+            })));
+    }
+    return (React.createElement(Box, { flexDirection: "column", width: determineWidthToUse(columns, config.maxWidth) },
+        title && React.createElement(Text, { ...titleOptions }, title),
+        headerComponent({ columns, data: {}, key: 'header' }),
+        headingComponent({ columns, data: headings, key: 'heading' }),
+        headerFooterComponent({ columns, data: {}, key: 'footer' }),
+        processedData.map((row, index) => {
+            // Calculate the hash of the row based on its value and position
+            const key = `row-${sha1(row)}-${index}`;
+            // Construct a row.
+            return (React.createElement(Box, { key: key, flexDirection: "column" },
+                separatorComponent({ columns, data: {}, key: `separator-${key}` }),
+                dataComponent({ columns, data: row, key: `data-${key}` })));
+        }),
+        footerComponent({ columns, data: {}, key: 'footer' })));
+}
+/**
+ * Constructs a Row element from the configuration.
+ */
+function row(config) {
+    // This is a component builder. We return a function.
+    const { borderProps, skeleton } = config;
+    return (props) => {
+        const data = props.columns.map((column, colI) => {
+            const { horizontalAlignment, overflow, padding, verticalAlignment, width } = column;
+            const value = props.data[column.column];
+            if (value === undefined || value === null) {
+                const key = `${props.key}-empty-${column.key}`;
+                return (React.createElement(config.cell, { key: key, column: colI, ...config.props }, skeleton.line.repeat(width)));
+            }
+            const key = `${props.key}-cell-${column.key}`;
+            // 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
+            const valueWithNoZeroWidthChars = String(value).replaceAll('​', ' ');
+            const spaceForText = width - padding * 2;
+            const v = 
+            // if the visible length of the value is greater than the column width, truncate or wrap
+            stripAnsi(valueWithNoZeroWidthChars).length >= spaceForText
+                ? overflow === 'wrap'
+                    ? wrapAnsi(valueWithNoZeroWidthChars, spaceForText, { hard: true, trim: true, wordWrap: false }).replaceAll('\n', `${' '.repeat(padding)}\n${' '.repeat(padding)}`)
+                    : cliTruncate(valueWithNoZeroWidthChars, spaceForText)
+                : valueWithNoZeroWidthChars;
+            const spaces = overflow === 'wrap' ? width - stripAnsi(v).split('\n')[0].trim().length : width - stripAnsi(v).length;
+            let marginLeft;
+            let marginRight;
+            if (horizontalAlignment === 'left') {
+                marginLeft = padding;
+                marginRight = spaces - marginLeft;
+            }
+            else if (horizontalAlignment === 'center') {
+                marginLeft = Math.floor(spaces / 2);
+                marginRight = Math.ceil(spaces / 2);
+            }
+            else {
+                marginRight = padding;
+                marginLeft = spaces - marginRight;
+            }
+            const alignItems = verticalAlignment === 'top' ? 'flex-start' : verticalAlignment === 'center' ? 'center' : 'flex-end';
+            return (React.createElement(config.cell, { key: key, column: colI, alignItems, ...config.props }, `${skeleton.line.repeat(marginLeft)}${v}${skeleton.line.repeat(marginRight)}`));
+        });
+        const height = data.map((d) => d.props.children.split('\n').length).reduce((a, b) => Math.max(a, b), 0);
+        const elements = intersperse((i) => {
+            const key = `${props.key}-hseparator-${i}`;
+            // The horizontal separator.
+            return (React.createElement(Skeleton, { key: key, height: height, ...borderProps }, skeleton.cross));
+        }, data);
+        return (React.createElement(Box, { flexDirection: "row" },
+            React.createElement(Skeleton, { height: height, ...borderProps }, skeleton.left),
+            ...elements,
+            React.createElement(Skeleton, { height: height, ...borderProps }, skeleton.right)));
+    };
+}
+/**
+ * Renders the header of a table.
+ */
+export function Header(props) {
+    const { children, ...rest } = props;
+    return React.createElement(Text, { ...rest }, children);
+}
+/**
+ * Renders a cell in the table.
+ */
+export function Cell(props) {
+    return (React.createElement(Box, { ...props },
+        React.createElement(Text, null, props.children)));
+}
+/**
+ * Renders the scaffold of the table.
+ */
+export function Skeleton(props) {
+    const { children, ...rest } = props;
+    // repeat Text component height times
+    const texts = Array.from({ length: props.height ?? 1 }, (_, i) => (React.createElement(Text, { key: i, ...rest }, children)));
+    return React.createElement(Box, { flexDirection: "column" }, texts);
+}
+/**
+ * Renders a table with the given data.
+ * @param options see {@link TableProps}
+ */
+export function makeTable(options) {
+    const instance = render(React.createElement(Table, { ...options }));
+    instance.unmount();
+}
+function Container(props) {
+    return (React.createElement(Box, { flexWrap: "wrap", flexDirection: props.direction ?? 'row', ...props }, props.children));
+}
+export function makeTables(tables, options) {
+    const leftMargin = options?.marginLeft ?? options?.margin ?? 0;
+    const rightMargin = options?.marginRight ?? options?.margin ?? 0;
+    const columns = process.stdout.columns - (leftMargin + rightMargin);
+    const processed = tables.map((table) => ({
+        ...table,
+        // adjust maxWidth to account for margin
+        maxWidth: determineConfiguredWidth(table.maxWidth, columns),
+    }));
+    const instance = render(React.createElement(Container, { ...options }, processed.map((table) => (React.createElement(Table, { key: sha1(table), ...table })))));
+    instance.unmount();
+}

package/lib/types.d.ts

@@ -0,0 +1,237 @@
+import { BorderStyle } from './skeletons.js';
+export type Scalar = string | number | boolean | null | undefined;
+export type ScalarDict = {
+    [key: string]: Scalar;
+};
+export type CellProps = React.PropsWithChildren<{
+    readonly column: number;
+}>;
+export type HorizontalAlignment = 'left' | 'right' | 'center';
+export type VerticalAlignment = 'top' | 'center' | 'bottom';
+export type ColumnProps<T> = {
+    /**
+     * Horizontal alignment of cell content. Overrides the horizontal alignment set in the table.
+     */
+    horizontalAlignment?: HorizontalAlignment;
+    key: T;
+    /**
+     * Name of the column. If not provided, it will default to the key.
+     */
+    name?: string;
+    /**
+     * Overflow behavior for cells. Overrides the overflow set in the table.
+     */
+    overflow?: Overflow;
+    /**
+     * Padding for the column. Overrides the padding set in the table.
+     */
+    padding?: number;
+    /**
+     * Vertical alignment of cell content. Overrides the vertical alignment set in the table.
+     */
+    verticalAlignment?: VerticalAlignment;
+};
+export type AllColumnProps<T> = {
+    [K in keyof T]: ColumnProps<K>;
+}[keyof T];
+export type Percentage = `${number}%`;
+type TextOptions = {
+    color?: SupportedColor;
+    backgroundColor?: SupportedColor;
+    bold?: boolean;
+    dimColor?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    inverse?: boolean;
+};
+export type HeaderFormatter = ((header: string) => string) | 'camelCase' | 'capitalCase' | 'constantCase' | 'kebabCase' | 'pascalCase' | 'sentenceCase' | 'snakeCase';
+export type SupportedColor = 'black' | 'blackBright' | 'blue' | 'blueBright' | 'cyan' | 'cyanBright' | 'gray' | 'green' | 'greenBright' | 'grey' | 'magenta' | 'magentaBright' | 'red' | 'redBright' | 'reset' | 'white' | 'whiteBright' | 'yellow' | 'yellowBright' | `#${string}` | `rgb(${number},${number},${number})`;
+export type HeaderOptions = TextOptions & {
+    /**
+     * Column header formatter. Can either be a function or a method name on the `change-case` library.
+     *
+     * See https://www.npmjs.com/package/change-case for more information.
+     */
+    formatter?: HeaderFormatter;
+};
+type Overflow = 'wrap' | 'truncate';
+type SortOrder<T> = 'asc' | 'desc' | ((valueA: T, valueB: T) => number);
+export type Sort<T> = {
+    [K in keyof T]?: SortOrder<T[K]>;
+};
+export type TableProps<T extends ScalarDict> = {
+    /**
+     * List of values (rows).
+     */
+    data: T[];
+    /**
+     * Columns that we should display in the table.
+     */
+    columns?: (keyof T | AllColumnProps<T>)[];
+    /**
+     * Cell padding.
+     */
+    padding?: number;
+    /**
+     * 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`).
+     *
+     * 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 width of the table.
+     */
+    maxWidth?: Percentage | number;
+    /**
+     * Overflow behavior for cells. Defaults to 'truncate'.
+     */
+    overflow?: Overflow;
+    /**
+     * Styling options for the column headers
+     */
+    headerOptions?: HeaderOptions;
+    /**
+     * Border style for the table. Defaults to 'all'. Only applies to horizontal orientation.
+     */
+    borderStyle?: BorderStyle;
+    /**
+     * Color of the table border. Defaults to 'white' in dark terminals and 'black' in light terminals.
+     */
+    borderColor?: SupportedColor;
+    /**
+     * Align data in columns. Defaults to 'left'. Only applies to horizontal orientation.
+     */
+    horizontalAlignment?: HorizontalAlignment;
+    /**
+     * Apply a filter to each row in the table.
+     */
+    filter?: (row: T) => boolean;
+    /**
+     * Sort the data in the table.
+     *
+     * Each key in the object should correspond to a column in the table. The value can be 'asc', 'desc', or a custom sort function.
+     *
+     * The order of the keys determines the order of the sorting. The first key is the primary sort key, the second key is the secondary sort key, and so on.
+     *
+     * @example
+     * ```js
+     * const data = [
+     * {name: 'Alice', age: 30},
+     * {name: 'Bob', age: 25},
+     * {name: 'Charlie', age: 35},
+     * ]
+     *
+     * // sort the name column in ascending order
+     * makeTable({data, sort: {name: 'asc'}})
+     *
+     * // sort the name column in descending order
+     * makeTable({data, sort: {name: 'desc'}})
+     *
+     * // sort by name in ascending order and age in descending order
+     * makeTable({data, sort: {name: 'asc', age: 'desc'}})
+     *
+     * // sort by name in ascending order and age in descending order using a custom sort function
+     * makeTable({data, sort: {name: 'asc', age: (a, b) => b - a}})
+     * ```
+     */
+    sort?: Sort<T>;
+    /**
+     * The orientation of the table. Defaults to 'horizontal'.
+     *
+     * If 'vertical', individual records will be displayed vertically in key:value pairs.
+     *
+     * @example
+     * ```
+     * ─────────────
+     *  Name Alice
+     *  Id   36329
+     *  Age  20
+     * ─────────────
+     *  Name Bob
+     *  Id   49032
+     *  Age  21
+     * ─────────────
+     * ```
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Vertical alignment of cell content. Defaults to 'top'. Only applies to horizontal orientation.
+     */
+    verticalAlignment?: VerticalAlignment;
+    /**
+     * Title of the table. Displayed above the table.
+     */
+    title?: string;
+    /**
+     * Styling options for the title of the table.
+     */
+    titleOptions?: TextOptions;
+    /**
+     * Disable all styling for the table.
+     */
+    noStyle?: boolean;
+};
+export type Config<T> = {
+    columns: (keyof T | AllColumnProps<T>)[];
+    data: T[];
+    padding: number;
+    maxWidth: number;
+    overflow: Overflow;
+    headerOptions: HeaderOptions;
+    borderStyle: BorderStyle;
+    horizontalAlignment: HorizontalAlignment;
+    verticalAlignment: VerticalAlignment;
+};
+export type RowConfig = {
+    /**
+     * Component used to render cells.
+     */
+    cell: (props: CellProps) => React.ReactNode;
+    /**
+     * Component used to render skeleton in the row.
+     */
+    skeleton: {
+        /**
+         * Characters used in skeleton.
+         *    |             |
+         * (left)-(line)-(cross)-(line)-(right)
+         *    |             |
+         */
+        left: string;
+        right: string;
+        cross: string;
+        line: string;
+    };
+    props?: Record<string, unknown>;
+    borderProps: {
+        color: SupportedColor | undefined;
+    };
+};
+export type RowProps<T extends ScalarDict> = {
+    readonly key: string;
+    readonly data: Partial<T>;
+    readonly columns: Column<T>[];
+};
+export type Column<T> = {
+    key: string;
+    column: keyof T;
+    width: number;
+    padding: number;
+    horizontalAlignment: HorizontalAlignment;
+    verticalAlignment: VerticalAlignment;
+    overflow: Overflow;
+};
+export type ContainerProps = {
+    readonly alignItems?: 'flex-start' | 'flex-end' | 'center';
+    readonly children: React.ReactNode;
+    readonly columnGap?: number;
+    readonly direction?: 'row' | 'column';
+    readonly margin?: number;
+    readonly marginLeft?: number;
+    readonly marginRight?: number;
+    readonly marginTop?: number;
+    readonly marginBottom?: number;
+    readonly rowGap?: number;
+};
+export {};

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/lib/utils.d.ts

@@ -0,0 +1,15 @@
+import { Column, Config, ScalarDict, Sort } from './types.js';
+/**
+ * Intersperses a list of elements with another element.
+ *
+ * @example
+ * ```js
+ * intersperse(() => 'foo', [1, 2, 3]) // => [1, 'foo', 2, 'foo', 3]
+ * ```
+ */
+export declare function intersperse<T, I>(intersperser: (index: number) => I, elements: T[]): (T | I)[];
+export declare function sortData<T extends ScalarDict>(data: T[], sort?: Sort<T> | undefined): T[];
+export declare function allKeysInCollection<T extends ScalarDict>(data: T[]): (keyof T)[];
+export declare function getColumns<T extends ScalarDict>(config: Config<T>, headings: Partial<T>): Column<T>[];
+export declare function getHeadings<T extends ScalarDict>(config: Config<T>): Partial<T>;
+export declare function maybeStripAnsi<T extends ScalarDict[]>(data: T, noStyle: boolean): T;

package/lib/utils.js

@@ -0,0 +1,140 @@
+import { camelCase, capitalCase, constantCase, kebabCase, pascalCase, sentenceCase, snakeCase } from 'change-case';
+import { orderBy } from 'natural-orderby';
+import stripAnsi from 'strip-ansi';
+/**
+ * Intersperses a list of elements with another element.
+ *
+ * @example
+ * ```js
+ * intersperse(() => 'foo', [1, 2, 3]) // => [1, 'foo', 2, 'foo', 3]
+ * ```
+ */
+export function intersperse(intersperser, elements) {
+    // Intersperse by reducing from left.
+    const interspersed = elements.reduce((acc, element, index) => {
+        // Only add element if it's the first one.
+        if (acc.length === 0)
+            return [element];
+        // Add the intersperser as well otherwise.
+        return [...acc, intersperser(index), element];
+    }, []);
+    return interspersed;
+}
+export function sortData(data, sort) {
+    if (!sort)
+        return data;
+    const identifiers = Object.keys(sort);
+    const orders = Object.values(sort);
+    return orderBy(data, identifiers, orders);
+}
+export function allKeysInCollection(data) {
+    const keys = new Set();
+    for (const row of data) {
+        for (const key in row) {
+            if (key in row)
+                keys.add(key);
+        }
+    }
+    return [...keys];
+}
+export function getColumns(config, headings) {
+    const { columns, horizontalAlignment, maxWidth, overflow, verticalAlignment } = config;
+    const widths = columns.map((propsOrKey) => {
+        const props = typeof propsOrKey === 'object' ? propsOrKey : { key: propsOrKey };
+        const { key } = props;
+        const padding = props.padding ?? config.padding;
+        // Get the width of each cell in the column
+        const data = config.data.map((data) => {
+            const value = data[key];
+            if (value === undefined || value === null)
+                return 0;
+            return stripAnsi(String(value).replaceAll('​', ' ')).length;
+        });
+        const header = String(headings[key]).length;
+        const width = Math.max(...data, header) + padding * 2;
+        return {
+            column: key,
+            horizontalAlignment: props.horizontalAlignment ?? horizontalAlignment,
+            key: String(key),
+            overflow: props.overflow ?? overflow,
+            padding,
+            verticalAlignment: props.verticalAlignment ?? verticalAlignment,
+            width,
+        };
+    });
+    const numberOfBorders = widths.length + 1;
+    const calculateTableWidth = (widths) => widths.map((w) => w.width).reduce((a, b) => a + b) + numberOfBorders;
+    // If the table is too wide, reduce the width of the largest column as little as possible to fit the table.
+    // At most, it will reduce the width to the length of the column's header plus padding.
+    // If the table is still too wide, it will reduce the width of the next largest column and so on
+    let tableWidth = calculateTableWidth(widths);
+    const seen = new Set();
+    while (tableWidth > maxWidth) {
+        const largestColumn = widths.reduce((a, b) => (a.width > b.width ? a : b));
+        const header = String(headings[largestColumn.key]).length;
+        // The minimum width of a column is the width of the header plus padding on both sides
+        const minWidth = header + largestColumn.padding * 2;
+        const difference = tableWidth - maxWidth;
+        const newWidth = largestColumn.width - difference < minWidth ? minWidth : largestColumn.width - difference;
+        largestColumn.width = newWidth;
+        tableWidth = calculateTableWidth(widths);
+        if (seen.has(largestColumn.key))
+            break;
+        seen.add(largestColumn.key);
+    }
+    return widths;
+}
+export function getHeadings(config) {
+    const { columns, headerOptions: { formatter }, } = config;
+    const format = (header) => {
+        if (typeof header !== 'string')
+            return header;
+        if (!formatter)
+            return header;
+        if (typeof formatter === 'function')
+            return formatter(header);
+        switch (formatter) {
+            case 'pascalCase': {
+                return pascalCase(header);
+            }
+            case 'capitalCase': {
+                return capitalCase(header);
+            }
+            case 'camelCase': {
+                return camelCase(header);
+            }
+            case 'snakeCase': {
+                return snakeCase(header);
+            }
+            case 'kebabCase': {
+                return kebabCase(header);
+            }
+            case 'constantCase': {
+                return constantCase(header);
+            }
+            case 'sentenceCase': {
+                return sentenceCase(header);
+            }
+            default: {
+                return header;
+            }
+        }
+    };
+    return Object.fromEntries(columns.map((c) => {
+        const key = typeof c === 'object' ? c.key : c;
+        const name = typeof c === 'object' ? (c.name ?? format(key)) : format(c);
+        return [key, name];
+    }));
+}
+export function maybeStripAnsi(data, noStyle) {
+    if (!noStyle)
+        return data;
+    const newData = [];
+    for (const row in data) {
+        if (row in data) {
+            const newRow = Object.fromEntries(Object.entries(data[row]).map(([key, value]) => [key, typeof value === 'string' ? stripAnsi(value) : value]));
+            newData.push(newRow);
+        }
+    }
+    return newData;
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@oclif/table",
+  "description": "Display table in terminal",
+  "version": "0.1.0",
+  "author": "Salesforce",
+  "bugs": "https://github.com/oclif/multi-stage-output/issues",
+  "dependencies": {
+    "@oclif/core": "^4",
+    "@types/react": "^18.3.3",
+    "change-case": "^5.4.4",
+    "cli-truncate": "^4.0.0",
+    "ink": "^5.0.1",
+    "natural-orderby": "^3.0.2",
+    "object-hash": "^3.0.0",
+    "react": "^18.3.1",
+    "strip-ansi": "^7.1.0",
+    "wrap-ansi": "^9.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19",
+    "@oclif/prettier-config": "^0.2.1",
+    "@types/chai": "^4.3.16",
+    "@types/mocha": "^10.0.7",
+    "@types/node": "^18",
+    "@types/object-hash": "^3.0.6",
+    "@types/sinon": "^17.0.3",
+    "ansis": "^3.3.2",
+    "chai": "^4.5.0",
+    "commitlint": "^19",
+    "eslint": "^8.57.0",
+    "eslint-config-oclif": "^5.2.0",
+    "eslint-config-oclif-typescript": "^3.1.8",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-config-xo": "^0.45.0",
+    "eslint-config-xo-react": "^0.27.0",
+    "eslint-plugin-react": "^7.34.3",
+    "eslint-plugin-react-hooks": "^4.6.2",
+    "husky": "^9.1.3",
+    "ink-testing-library": "^4.0.0",
+    "lint-staged": "^15",
+    "mocha": "^10.7.3",
+    "prettier": "^3.3.3",
+    "shx": "^0.3.4",
+    "sinon": "^18",
+    "terminal-link": "^3.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "/lib"
+  ],
+  "homepage": "https://github.com/oclif/core",
+  "keywords": [
+    "oclif",
+    "cli",
+    "stages"
+  ],
+  "license": "MIT",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "repository": "oclif/core",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "shx rm -rf lib && tsc",
+    "compile": "tsc",
+    "format": "prettier --write \"+(src|test)/**/*.+(ts|js|json)\"",
+    "lint": "eslint . --ext .ts",
+    "posttest": "yarn lint",
+    "prepack": "yarn run build",
+    "prepare": "husky",
+    "test": "mocha --forbid-only \"test/**/*.test.+(ts|tsx)\" --parallel"
+  },
+  "types": "lib/index.d.ts",
+  "type": "module"
+}