flagstaff 0.0.1 → 0.1.0

package/dist/boxen.js

@@ -0,0 +1,251 @@
+import chalk from 'roundel/chalk';
+import { width as stringWidth } from './width.js';
+import { wrap as wrapAnsi } from './wrap.js';
+const NEWLINE = '\n';
+const PAD = ' ';
+const NONE = 'none';
+const FALLBACK_COLUMNS = 80;
+const DECIMAL = 10;
+const BORDERED = 2;
+const SIDE_MARGIN_RATIO = 3;
+const HALF = 2;
+const BOXES = {
+    single: { topLeft: '┌', top: '─', topRight: '┐', right: '│', bottomRight: '┘', bottom: '─', bottomLeft: '└', left: '│' },
+    double: { topLeft: '╔', top: '═', topRight: '╗', right: '║', bottomRight: '╝', bottom: '═', bottomLeft: '╚', left: '║' },
+    round: { topLeft: '╭', top: '─', topRight: '╮', right: '│', bottomRight: '╯', bottom: '─', bottomLeft: '╰', left: '│' },
+    bold: { topLeft: '┏', top: '━', topRight: '┓', right: '┃', bottomRight: '┛', bottom: '━', bottomLeft: '┗', left: '┃' },
+    singleDouble: { topLeft: '╓', top: '─', topRight: '╖', right: '║', bottomRight: '╜', bottom: '─', bottomLeft: '╙', left: '║' },
+    doubleSingle: { topLeft: '╒', top: '═', topRight: '╕', right: '│', bottomRight: '╛', bottom: '═', bottomLeft: '╘', left: '│' },
+    classic: { topLeft: '+', top: '-', topRight: '+', right: '|', bottomRight: '+', bottom: '-', bottomLeft: '+', left: '|' },
+    arrow: { topLeft: '↘', top: '↓', topRight: '↙', right: '←', bottomRight: '↖', bottom: '↑', bottomLeft: '↗', left: '→' },
+};
+function terminalColumns() {
+    const { env, stdout, stderr } = process;
+    if (stdout?.columns)
+        return stdout.columns;
+    if (stderr?.columns)
+        return stderr.columns;
+    if (env['COLUMNS'] !== undefined)
+        return Number.parseInt(env['COLUMNS'], DECIMAL);
+    return FALLBACK_COLUMNS;
+}
+function getObject(detail) {
+    if (typeof detail === 'number') {
+        return { top: detail, right: detail * SIDE_MARGIN_RATIO, bottom: detail, left: detail * SIDE_MARGIN_RATIO };
+    }
+    return { top: 0, right: 0, bottom: 0, left: 0, ...detail };
+}
+const getBorderWidth = (borderStyle) => (borderStyle === NONE ? 0 : BORDERED);
+const SIDES = ['topLeft', 'topRight', 'bottomRight', 'bottomLeft', 'left', 'right', 'top', 'bottom'];
+const widestLine = (text) => Math.max(0, ...text.split(NEWLINE).map((line) => stringWidth(line)));
+function ansiAlign(text, align) {
+    if (text === '' || align === 'left')
+        return text;
+    const lines = text.split(NEWLINE).map((line) => ({ line, width: stringWidth(line) }));
+    const maxWidth = Math.max(0, ...lines.map((l) => l.width));
+    const diff = (w) => (align === 'right' ? maxWidth - w : Math.floor((maxWidth - w) / HALF));
+    return lines.map((l) => PAD.repeat(diff(l.width)) + l.line).join(NEWLINE);
+}
+function getBorderChars(borderStyle) {
+    if (borderStyle === NONE) {
+        return { topLeft: '', top: '', topRight: '', left: '', right: '', bottomLeft: '', bottom: '', bottomRight: '' };
+    }
+    if (typeof borderStyle === 'string') {
+        const characters = BOXES[borderStyle];
+        if (!characters)
+            throw new TypeError(`Invalid border style: ${borderStyle}`);
+        return characters;
+    }
+    const style = { ...borderStyle };
+    if (typeof style.vertical === 'string') {
+        style.left = style.vertical;
+        style.right = style.vertical;
+    }
+    if (typeof style.horizontal === 'string') {
+        style.top = style.horizontal;
+        style.bottom = style.horizontal;
+    }
+    for (const side of SIDES) {
+        if (typeof style[side] !== 'string')
+            throw new TypeError(`Invalid border style: ${side}`);
+    }
+    return style;
+}
+function makeTitle(text, horizontalRun, alignment) {
+    const textWidth = stringWidth(text);
+    if (alignment === 'left')
+        return text + horizontalRun.slice(textWidth);
+    if (alignment === 'right')
+        return horizontalRun.slice(textWidth) + text;
+    let horizontal = horizontalRun.slice(textWidth);
+    if (horizontal.length % HALF === 1) {
+        horizontal = horizontal.slice(Math.floor(horizontal.length / HALF));
+        return horizontal.slice(1) + text + horizontal;
+    }
+    horizontal = horizontal.slice(horizontal.length / HALF);
+    return horizontal + text + horizontal;
+}
+function rewrap(line, max, align) {
+    const alignedLines = ansiAlign(wrapAnsi(line, max, { hard: true }), align).split(NEWLINE);
+    const longest = Math.max(0, ...alignedLines.map((s) => stringWidth(s)));
+    if (align === 'center')
+        return alignedLines.map((l) => PAD.repeat((max - longest) / HALF) + l);
+    if (align === 'right')
+        return alignedLines.map((l) => PAD.repeat(max - longest) + l);
+    return alignedLines;
+}
+function padRows(lines, padding, width) {
+    const left = PAD.repeat(padding.left);
+    const right = PAD.repeat(padding.right);
+    const padded = lines.map((line) => {
+        const newLine = left + line + right;
+        return newLine + PAD.repeat(width - stringWidth(newLine));
+    });
+    return [
+        ...Array.from({ length: padding.top }, () => PAD.repeat(width)),
+        ...padded,
+        ...Array.from({ length: padding.bottom }, () => PAD.repeat(width)),
+    ];
+}
+function fitHeight(lines, height, width) {
+    if (height === undefined || height <= 0)
+        return lines;
+    if (lines.length > height)
+        return lines.slice(0, height);
+    return [...lines, ...Array.from({ length: height - lines.length }, () => PAD.repeat(width))];
+}
+function makeContentText(text, { padding, width, textAlignment, height }) {
+    const align = textAlignment ?? 'left';
+    const aligned = ansiAlign(text, align);
+    let lines = aligned.split(NEWLINE);
+    const textWidth = widestLine(aligned);
+    const max = width - padding.left - padding.right;
+    if (textWidth > max)
+        lines = lines.flatMap((line) => rewrap(line, max, align));
+    if (align === 'center' && textWidth < max)
+        lines = lines.map((line) => PAD.repeat((max - textWidth) / HALF) + line);
+    else if (align === 'right' && textWidth < max)
+        lines = lines.map((line) => PAD.repeat(max - textWidth) + line);
+    return fitHeight(padRows(lines, padding, width), height, width).join(NEWLINE);
+}
+const isHex = (color) => /^#(?:[0-f]{3}){1,2}$/i.test(color);
+function named(name) {
+    const value = Reflect.get(chalk, name);
+    return typeof value === 'function' ? value : undefined;
+}
+const bgName = (color) => `bg${color.charAt(0).toUpperCase()}${color.slice(1)}`;
+const asIs = (text) => text;
+const isColorValid = (color) => typeof color === 'string' && (named(color) !== undefined || isHex(color));
+const colorFunction = (color) => (isHex(color) ? chalk.hex(color) : (named(color) ?? asIs));
+const bgColorFunction = (color) => (isHex(color) ? chalk.bgHex(color) : (named(bgName(color)) ?? asIs));
+function boxContent(content, contentWidth, options) {
+    const colorizeBorder = (border) => {
+        const painted = options.borderColor === undefined ? border : colorFunction(options.borderColor)(border);
+        return options.dimBorder === true ? chalk.dim(painted) : painted;
+    };
+    const colorizeContent = (line) => (options.backgroundColor === undefined ? line : bgColorFunction(options.backgroundColor)(line));
+    const chars = getBorderChars(options.borderStyle);
+    const columns = terminalColumns();
+    let marginLeft = PAD.repeat(options.margin.left);
+    if (options.float === 'center') {
+        marginLeft = PAD.repeat(Math.max((columns - contentWidth - getBorderWidth(options.borderStyle)) / HALF, 0));
+    }
+    else if (options.float === 'right') {
+        marginLeft = PAD.repeat(Math.max(columns - contentWidth - options.margin.right - getBorderWidth(options.borderStyle), 0));
+    }
+    let result = '';
+    if (options.margin.top)
+        result += NEWLINE.repeat(options.margin.top);
+    if (options.borderStyle !== NONE || options.title !== undefined) {
+        const run = chars.top.repeat(contentWidth);
+        const top = options.title === undefined ? run : makeTitle(options.title, run, options.titleAlignment);
+        result += `${colorizeBorder(marginLeft + chars.topLeft + top + chars.topRight)}${NEWLINE}`;
+    }
+    result += content
+        .split(NEWLINE)
+        .map((line) => marginLeft + colorizeBorder(chars.left) + colorizeContent(line) + colorizeBorder(chars.right))
+        .join(NEWLINE);
+    if (options.borderStyle !== NONE) {
+        result += NEWLINE + colorizeBorder(marginLeft + chars.bottomLeft + chars.bottom.repeat(contentWidth) + chars.bottomRight);
+    }
+    if (options.margin.bottom)
+        result += NEWLINE.repeat(options.margin.bottom);
+    return result;
+}
+function sanitizeOptions(options) {
+    if (options.fullscreen !== undefined && options.fullscreen !== false && process.stdout) {
+        let dimensions = [process.stdout.columns, process.stdout.rows];
+        if (typeof options.fullscreen === 'function')
+            dimensions = options.fullscreen(...dimensions);
+        options.width ||= dimensions[0];
+        options.height ||= dimensions[1];
+    }
+    if (options.width)
+        options.width = Math.max(1, options.width - getBorderWidth(options.borderStyle));
+    if (options.height)
+        options.height = Math.max(1, options.height - getBorderWidth(options.borderStyle));
+    return options;
+}
+const formatTitle = (title, borderStyle) => (borderStyle === NONE ? title : ` ${title} `);
+function sizeTitle(options, { widthOverride, maxWidth, widest }) {
+    if (options.title === undefined)
+        return;
+    if (widthOverride) {
+        options.title = options.title.slice(0, Math.max(0, options.width - HALF));
+        if (options.title)
+            options.title = formatTitle(options.title, options.borderStyle);
+        return;
+    }
+    options.title = options.title.slice(0, Math.max(0, maxWidth - HALF));
+    if (!options.title)
+        return;
+    options.title = formatTitle(options.title, options.borderStyle);
+    if (stringWidth(options.title) > widest)
+        options.width = stringWidth(options.title);
+}
+function determineDimensions(text, input) {
+    const options = sanitizeOptions(input);
+    const widthOverride = options.width !== undefined && options.width !== 0;
+    const columns = terminalColumns();
+    const borderWidth = getBorderWidth(options.borderStyle);
+    const maxWidth = columns - options.margin.left - options.margin.right - borderWidth;
+    const widest = widestLine(wrapAnsi(text, columns - borderWidth, { hard: true, trim: false })) + options.padding.left + options.padding.right;
+    sizeTitle(options, { widthOverride, maxWidth, widest });
+    options.width ||= widest;
+    if (!widthOverride) {
+        if (options.margin.left && options.margin.right && options.width > maxWidth) {
+            const spaceForMargins = columns - options.width - borderWidth;
+            const multiplier = spaceForMargins / (options.margin.left + options.margin.right);
+            options.margin.left = Math.max(0, Math.floor(options.margin.left * multiplier));
+            options.margin.right = Math.max(0, Math.floor(options.margin.right * multiplier));
+        }
+        options.width = Math.min(options.width, columns - borderWidth - options.margin.left - options.margin.right);
+    }
+    if (options.width - (options.padding.left + options.padding.right) <= 0) {
+        options.padding.left = 0;
+        options.padding.right = 0;
+    }
+    if (options.height !== undefined && options.height - (options.padding.top + options.padding.bottom) <= 0) {
+        options.padding.top = 0;
+        options.padding.bottom = 0;
+    }
+    return options;
+}
+export { BOXES as _borderStyles };
+export default function boxen(text, options = {}) {
+    const merged = { borderStyle: 'single', dimBorder: false, textAlignment: 'left', float: 'left', titleAlignment: 'left', padding: 0, ...options };
+    if (merged.align !== undefined)
+        merged.textAlignment = merged.align;
+    if (merged.borderColor !== undefined && !isColorValid(merged.borderColor))
+        throw new Error(`${merged.borderColor} is not a valid borderColor`);
+    if (merged.backgroundColor !== undefined && !isColorValid(merged.backgroundColor))
+        throw new Error(`${merged.backgroundColor} is not a valid backgroundColor`);
+    const resolved = {
+        ...merged,
+        padding: getObject(merged.padding),
+        margin: getObject(merged.margin),
+        width: merged.width ?? 0,
+    };
+    const dimensions = determineDimensions(text, resolved);
+    return boxContent(makeContentText(text, dimensions), dimensions.width, dimensions);
+}

package/dist/builtins.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The first-party plugin (R4). Data only — the same shape a third party writes — and it
+ * reaches the registry through the public `register()` like any other, so the built-ins
+ * cannot grow an API a plugin cannot reach (U4). Type-only import: this file runs nothing.
+ *
+ * What lives here is what a plugin may *replace*: the glyphs every component draws its
+ * statuses with, and the spinner styles. The five components themselves (`spinner`,
+ * `progress`, `tasks`, `box`, `table`) are factories on their own subpaths, because a
+ * component is code and this file is data — and because a program that wants a progress
+ * bar should not pay for a table.
+ */
+import { type Plugin } from './plugin.js';
+export declare const builtins: Plugin;

package/dist/builtins.js

@@ -0,0 +1,19 @@
+const DOTS_INTERVAL = 80;
+const LINE_INTERVAL = 130;
+export const builtins = {
+    name: 'flagstaff',
+    contract: 1,
+    glyphs: { running: '…', ok: '✔', fail: '✖', warn: '⚠', info: 'ℹ' },
+    spinners: {
+        dots: { frames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'], interval: DOTS_INTERVAL, static: '…' },
+        line: { frames: ['-', '\\', '|', '/'], interval: LINE_INTERVAL, static: '…' },
+    },
+    borders: {
+        round: { topLeft: '╭', top: '─', topRight: '╮', left: '│', right: '│', bottomLeft: '╰', bottom: '─', bottomRight: '╯' },
+        single: { topLeft: '┌', top: '─', topRight: '┐', left: '│', right: '│', bottomLeft: '└', bottom: '─', bottomRight: '┘' },
+        double: { topLeft: '╔', top: '═', topRight: '╗', left: '║', right: '║', bottomLeft: '╚', bottom: '═', bottomRight: '╝' },
+        bold: { topLeft: '┏', top: '━', topRight: '┓', left: '┃', right: '┃', bottomLeft: '┗', bottom: '━', bottomRight: '┛' },
+        classic: { topLeft: '+', top: '-', topRight: '+', left: '|', right: '|', bottomLeft: '+', bottom: '-', bottomRight: '+' },
+        none: { topLeft: '', top: '', topRight: '', left: '', right: '', bottomLeft: '', bottom: '', bottomRight: '' },
+    },
+};

package/dist/cli-table3.d.ts

@@ -0,0 +1,138 @@
+/** Widest line, measured with SGR removed. Upstream's `strlen`. */
+export declare function strlen(str: unknown): number;
+/** Pad to `len` columns. `right` pads on the left, which is upstream's naming, not a typo. */
+export declare function pad(str: string, len: number, padChar: string, dir?: string): string;
+export declare function truncate(str: string, desiredLength: number, truncateChar?: string): string;
+export declare function wordWrap(maxLength: number, input: string, wrapOnWordBoundary?: boolean): string[];
+/** OSC 8 — the terminal hyperlink escape. */
+export declare function hyperlink(url: string, text: string): string;
+export interface TableChars {
+    [name: string]: string;
+}
+export interface TableStyle {
+    'padding-left'?: number;
+    'padding-right'?: number;
+    head?: string[];
+    border?: string[];
+    compact?: boolean;
+}
+export interface TableOptions {
+    chars?: Partial<TableChars>;
+    truncate?: string;
+    colWidths?: (number | null)[];
+    rowHeights?: (number | null)[];
+    colAligns?: (string | undefined)[];
+    rowAligns?: (string | undefined)[];
+    style?: TableStyle;
+    head?: unknown[];
+    wordWrap?: boolean;
+    /** cli-table3's older name for `wordWrap`, still honoured. */
+    textWrap?: boolean;
+    wrapOnWordBoundary?: boolean;
+}
+export declare function mergeOptions(options?: TableOptions, defaults?: TableOptions): TableOptions;
+interface Drawable {
+    x: number;
+    y: number;
+    colSpan: number;
+    rowSpan: number;
+    desiredWidth?: number;
+    desiredHeight?: number;
+    draw(lineNum: number | string, spanningCell?: number): string;
+    init(tableOptions: ResolvedOptions): void;
+    mergeTableOptions(tableOptions: ResolvedOptions, cells: Drawable[][]): void;
+}
+interface ResolvedOptions extends TableOptions {
+    colWidths: number[];
+    rowHeights: number[];
+    chars: TableChars;
+    style: TableStyle;
+}
+export declare class Cell implements Drawable {
+    x: number;
+    y: number;
+    colSpan: number;
+    rowSpan: number;
+    content: string;
+    options: Record<string, unknown>;
+    chars: TableChars;
+    truncate: string;
+    paddingLeft: number;
+    paddingRight: number;
+    head?: string[] | undefined;
+    border?: string[] | undefined;
+    fixedWidth?: number | null | undefined;
+    lines: string[];
+    desiredWidth: number;
+    desiredHeight: number;
+    widths: number[];
+    heights: number[];
+    width: number;
+    height: number;
+    hAlign?: string | undefined;
+    vAlign?: string | undefined;
+    drawRight: boolean;
+    cells?: Drawable[][] | undefined;
+    href?: string | undefined;
+    constructor(options?: unknown);
+    mergeTableOptions(tableOptions: ResolvedOptions, cells: Drawable[][]): void;
+    computeLines(tableOptions: ResolvedOptions): string[];
+    /**
+     * The href is deliberately *not* applied here. `drawLine` truncates the line it is given,
+     * and a hyperlink wrapped around the content before that point is cut through the middle
+     * of its own URL — upstream's issue #338, which emits `\x1b]8;;http://e…` and a terminal
+     * escape that never closes. The link goes on after truncation instead, around whatever
+     * text actually survived.
+     */
+    wrapLines(computedLines: string[]): string[];
+    init(tableOptions: ResolvedOptions): void;
+    draw(lineNum: number | string, spanningCell?: number): string;
+    drawTop(drawRight: boolean): string;
+    private topLeftChar;
+    /** The left edge, which a row-spanning neighbour turns into a `rightMid`. */
+    private leftEdge;
+    drawLine(lineNum: number, drawRight: boolean, forceTruncationSymbol: boolean, spanningCell?: number): string;
+    private stylizeLine;
+    drawBottom(drawRight: boolean): string;
+    drawEmpty(drawRight: boolean, spanningCell?: number): string;
+}
+/** A placeholder that draws nothing, holding the place of a column-spanned cell. */
+export declare class ColSpanCell implements Drawable {
+    x: number;
+    y: number;
+    colSpan: number;
+    rowSpan: number;
+    draw(lineNum?: number | string): string;
+    init(): void;
+    mergeTableOptions(): void;
+}
+/** A placeholder that defers to the cell above it, offset by the rows in between. */
+export declare class RowSpanCell implements Drawable {
+    readonly originalCell: Cell;
+    x: number;
+    y: number;
+    colSpan: number;
+    rowSpan: number;
+    private cellOffset;
+    private offset;
+    constructor(originalCell: Cell);
+    init(tableOptions: ResolvedOptions): void;
+    draw(lineNum: number | string): string;
+    mergeTableOptions(): void;
+}
+export declare function makeTableLayout(rows: unknown[]): Drawable[][];
+export declare const computeWidths: (vals: number[], table: Drawable[][]) => void;
+export declare const computeHeights: (vals: number[], table: Drawable[][]) => void;
+/**
+ * A table. Extends `Array`, because cli-table3 does and its callers `push` rows onto it.
+ */
+export declare class Table extends Array<unknown> {
+    readonly options: ResolvedOptions;
+    readonly messages?: string[];
+    constructor(opts?: TableOptions);
+    /** Clears the module-level message log. The suite calls it after every case. */
+    static reset(): void;
+    toString(): string;
+    get width(): number;
+}
+export default Table;