`box`

Box drawing and ASCII art - render content boxes, tables, dialog boxes, progress bars, and frames in the terminal using Unicode box-drawing characters, with single, double, rounded, and plain-ASCII border styles.

Load with: use box

What this module does

box renders terminal UI elements as strings using Unicode box-drawing characters. You pick a style - "single" (─│┌┐└┘), "double" (═║╔╗╚╝), "rounded" (─│╭╮╰╯), or "ascii" (-|+++++) - and the module builds the borders, wraps your content, and returns the rendered string ready to print.

Every element type (box, table, dialog, progress bar, frame) has a default instance and a parameterised constructor, plus a one-shot "quick render" convenience function.

Quick example

use box

# Simple content box
prn(bxrnd("Hello, world!", 20, 3, "rounded"))
# ╭──────────────────╮
# │ Hello, world!    │
# ╰──────────────────╯

# Table
prn(bxtca(["Name", "Score"], [["Alice", "95"], ["Bob", "87"]], "single"))
# ┌──────┬───────┐
# │ Name │ Score │
# ├──────┼───────┤
# │ Alice│  95   │
# │  Bob │  87   │
# └──────┴───────┘

# Progress bar at 60%
prn(bxpaa(0.6, 20, tru, "loading..."))
# |████████████░░░░░░░░| 60% loading...

Functions

Characters and styles

bxchr()

Returns the full Unicode box-drawing character set as an object: horizontal, vertical, all four corner types (plain, double, rounded), crosses, tees, block/shade characters (█░▒▓), half-blocks, dot, and bullet.

bxsty()

Returns the four named style sets: single, double, rounded, ascii. Each has top_left, top_right, bottom_left, bottom_right, horizontal, vertical, cross, tee_down, tee_up, tee_right, tee_left.

Content box

bxsaa(width, height, style)

Creates a box config. Defaults: width: 10, height: 3, style: "single", padding: 1.

bxsmp(box, content)

Renders a box with its content. Wraps content to fit the inner width (width - 2*padding), adds blank lines to fill height - 2*padding rows, builds the top/bottom borders and padded content lines. Returns the rendered string.

bxrnd(content, width, height, style)

One-shot: creates a box config and renders it immediately.

Table

bxtda(style, padding)

Creates a table config with empty headers and rows.

bxtbl(table, headers)

Sets the header row.

bxtaa(table, row)

Appends a data row (list of cell strings).

bxtba(table)

Renders the table. Auto-sizes columns to fit the widest cell. Draws top border, header row, separator, data rows, and bottom border. Returns the rendered string.

bxtca(headers, rows, style)

One-shot table render.

Dialog box

bxdba(title, message, width, height)

Creates a dialog config. Default style is "rounded". Defaults: width: 40, height: 10.

bxdlg(dialog, button_text)

Adds a button label to the dialog.

bxdaa(dialog)

Renders the dialog. Shows a title line with separator, wrapped message, a button separator, and centred button labels. Returns the rendered string.

bxdca(title, message, buttons, width, height)

One-shot dialog render.

Progress bar

bxpba(width, progress, style)

Creates a progress bar config. progress is a float from 0.0 to 1.0. Default: width: 20, show_percentage: tru.

bxprg(progress_bar)

Renders the bar. Fills progress * width cells with █ and the rest with ░, wrapped in vertical borders. Appends percentage and optional text label.

bxpaa(progress, width, show_percentage, text)

One-shot progress bar render.

Frame with shadow

bxfaa(width, height, style)

Creates a frame config. Includes title, content, and shadow: tru fields.

bxfrm(frame)

Renders a frame - a box with an optional title line injected at the top, and an optional shadow (each line gets a trailing space appended).

Colorised box

bxcaa(foreground, background, style)

Creates a color box config with foreground and background color names.

bxclr(color_box, text)

Renders a box around text, then applies background color via colr.bg and foreground color via colr.col to each line. Returns the colorised string.

Notes

All render functions return strings - use prn to display them in a terminal that supports Unicode.
Color functions require the colr module for ANSI escape code wrapping.
Content wrapping uses txt.wrap - long words that exceed the inner width will not be broken.
Requires trl, txt, and colr.