boxen

boxen: (text: string, options?: Options) => string;

type Boxes = {
    readonly none: BoxStyle;
} & CLIBoxes;

type Color = LiteralUnion<
    | 'black'
    | 'red'
    | 'green'
    | 'yellow'
    | 'blue'
    | 'magenta'
    | 'cyan'
    | 'white'
    | 'gray'
    | 'grey'
    | 'blackBright'
    | 'redBright'
    | 'greenBright'
    | 'yellowBright'
    | 'blueBright'
    | 'magentaBright'
    | 'cyanBright'
    | 'whiteBright',
    string
>;

type CustomBorderStyle = {
    /**
	@deprecated Use `top` and `bottom` instead.
	*/
    horizontal?: string;

    /**
	@deprecated Use `left` and `right` instead.
	*/
    vertical?: string;
} & BoxStyle;

type Options = {
    /**
	Color of the box border.
	*/
    readonly borderColor?: Color;

    /**
	Style of the box border.

	@default 'single'
	*/
    readonly borderStyle?: keyof Boxes | CustomBorderStyle;

    /**
	Reduce opacity of the border.

	@default false
	*/
    readonly dimBorder?: boolean;

    /**
	Space between the text and box border.

	@default 0
	*/
    readonly padding?: number | Spacing;

    /**
	Space around the box.

	@default 0
	*/
    readonly margin?: number | Spacing;

    /**
	Float the box on the available terminal screen space.

	@default 'left'
	*/
    readonly float?: 'left' | 'right' | 'center';

    /**
	Color of the background.
	*/
    readonly backgroundColor?: Color;

    /**
	Color of the background of the border.

	Defaults to `backgroundColor`. Set to `undefined` to disable.
	*/
    readonly borderBackgroundColor?: Color | 'inherit' | undefined;

    /**
	Align the text in the box based on the widest line.

	@default 'left'
	@deprecated Use `textAlignment` instead.
	*/
    readonly align?: 'left' | 'right' | 'center';

    /**
	Align the text in the box based on the widest line.

	@default 'left'
	*/
    readonly textAlignment?: 'left' | 'right' | 'center';

    /**
	Display a title at the top of the box.
	If needed, the box will horizontally expand to fit the title.

	@example
	```
	console.log(boxen('foo bar', {title: 'example'}));
	// ┌ example ┐
	// │foo bar  │
	// └─────────┘
	```
	*/
    readonly title?: string;

    /**
	Color of the title.

	Defaults to `borderColor` if set, otherwise the terminal's text color.

	Styling already applied to the `title` takes precedence.
	*/
    readonly titleColor?: LiteralUnion<
        | 'black'
        | 'red'
        | 'green'
        | 'yellow'
        | 'blue'
        | 'magenta'
        | 'cyan'
        | 'white'
        | 'gray'
        | 'grey'
        | 'blackBright'
        | 'redBright'
        | 'greenBright'
        | 'yellowBright'
        | 'blueBright'
        | 'magentaBright'
        | 'cyanBright'
        | 'whiteBright',
        string
    >;

    /**
	Align the title in the top bar.

	@default 'left'

	@example
	```
	console.log(boxen('foo bar foo bar', {title: 'example', titleAlignment: 'center'}));
	// ┌─── example ───┐
	// │foo bar foo bar│
	// └───────────────┘

	console.log(boxen('foo bar foo bar', {title: 'example', titleAlignment: 'right'}));
	// ┌────── example ┐
	// │foo bar foo bar│
	// └───────────────┘
	```
	*/
    readonly titleAlignment?: 'left' | 'right' | 'center';

    /**
	Display a footer at the bottom of the box.
	If needed, the box will horizontally expand to fit the footer.

	The footer uses the border color.

	@example
	```
	console.log(boxen('foo bar', {footer: 'example'}));
	// ┌─────────┐
	// │foo bar  │
	// └ example ┘
	```
	*/
    readonly footer?: string;

    /**
	Align the footer in the bottom bar.

	@default 'left'

	@example
	```
	console.log(boxen('foo bar foo bar', {footer: 'example', footerAlignment: 'center'}));
	// ┌───────────────┐
	// │foo bar foo bar│
	// └─── example ───┘

	console.log(boxen('foo bar foo bar', {footer: 'example', footerAlignment: 'right'}));
	// ┌───────────────┐
	// │foo bar foo bar│
	// └────── example ┘
	```
	*/
    readonly footerAlignment?: 'left' | 'right' | 'center';

    /**
	Set a fixed width for the box.

	A numeric string is also accepted.

	__Note__: This disables terminal overflow handling and may cause the box to look broken if the user's terminal is not wide enough.

	@example
	```
	import boxen from 'boxen';

	console.log(boxen('foo bar', {width: 15}));
	// ┌─────────────┐
	// │foo bar      │
	// └─────────────┘
	```
	*/
    readonly width?: number | `${number}`;

    /**
	Set a maximum width for the box.

	A numeric string is also accepted.

	The box grows with the content and does not become wider than this value.

	A character that is wider than the space left for it can still widen the box, because a character is never split.

	__Note__: This option has no effect when `width` is set.

	@example
	```
	import boxen from 'boxen';

	console.log(boxen('foo bar', {maxWidth: 20}));
	// ┌───────┐
	// │foo bar│
	// └───────┘

	console.log(boxen('Lorem ipsum dolor sit amet, consectetur.', {maxWidth: 20}));
	// ┌─────────────────┐
	// │Lorem ipsum dolor│
	// │sit amet,        │
	// │consectetur.     │
	// └─────────────────┘
	```
	*/
    readonly maxWidth?: number | `${number}`;

    /**
	Set a fixed height for the box.

	A numeric string is also accepted.

	__Note__: This option will crop overflowing content.

	@example
	```
	import boxen from 'boxen';

	console.log(boxen('foo bar', {height: 5}));
	// ┌───────┐
	// │foo bar│
	// │       │
	// │       │
	// └───────┘
	```
	*/
    readonly height?: number | `${number}`;

    /**
	__boolean__: Whether or not to fit all available space within the terminal.

	__function__: Pass a callback function to control box dimensions.

	@example
	```
	import boxen from 'boxen';

	console.log(boxen('foo bar', {
		fullscreen: (width, height) => [width, height - 1],
	}));
	```
	*/
    readonly fullscreen?:
        | boolean
        | ((width: number, height: number) => [width: number, height: number]);
};

type Spacing = {
    readonly top?: number;
    readonly right?: number;
    readonly bottom?: number;
    readonly left?: number;
};