Coming from boxen
A boxen alternative with a drop-in path: import boxen from flagstaff/boxen, graded 213 / 213 by boxen's own test suite — then a box component whose static projection gives a pipe, an agent and a screen reader the text and title, not the border.
flagstaff is a boxen alternative you adopt by changing one import. flagstaff/boxen
is boxen 9's API, and boxen 9.0.0's own test suite is the grade. boxen 8 is no longer graded:
9 changed two of 8's answers — a hex colour must be real hex, and vertical / horizontal
are a fallback for the sides rather than an override — and the façade follows 9.
Migrate from boxen in one import
- import boxen from 'boxen';
+ import boxen from 'flagstaff/boxen';Everything else stays: boxen(text, options) with borderStyle (all eight of cli-boxes'
styles, a style object of your own, or none), borderColor, backgroundColor,
borderBackgroundColor, dimBorder, title, titleColor, titleAlignment, footer,
footerAlignment, textAlignment, padding, margin, width, maxWidth, height,
float and fullscreen, plus _borderStyles and the Options, CustomBorderStyle,
Spacing and Color types. An invalid colour throws, as boxen's does.
Is flagstaff compatible with boxen?
Graded, not claimed. boxen's own suite, vendored at 9.0.0 and unmodified apart from the
import specifier, runs against flagstaff/boxen beside a control that runs it against real
boxen. Its cases assert the exact characters the box comes out as. The suite's colour cases
set chalk.level on the program's own chalk, so the grade runs the suite the way
burgee migrate leaves a program that imports both: chalk is roundel/chalk, the one
flagstaff/boxen draws with.
| passing | rate | |
|---|---|---|
flagstaff/boxen | 213 / 213 | 100.0% |
| boxen itself (control) | 213 / 213 | 100.0% |
From Compatibility, which npm run compat:page generates from the
oracle's last run; that page is the authority. The same page grades flagstaff's ora,
log-update and cli-table3 paths.
What you gain over boxen
For a box the drawing is the contract, so flagstaff/boxen matches it byte for byte and
the façade alone changes the dependency tree, not the output. boxen 9.0.0 resolves to
fourteen packages; its seven direct dependencies — string-width, wrap-ansi, slice-ansi,
widest-line, cli-boxes, chalk and type-fest — are folded in here, and the subpath
reaches only linegauge and roundel/chalk, both from the burgee family.
The gain beyond that is flagstaff/box, a separate API you adopt a file at a time:
box(text, { border, padding, title, width, href }) for the string, and boxComponent() to
put the box on the frame loop:
| mode | what hoist(boxComponent(), …) writes |
|---|---|
tty | the border, padding and title |
pipe, ci, accessible | title: text — no border characters |
json | one NDJSON event per transition, on stderr |
A border is noise to a screen reader and to a log an agent parses; the title and the text
are not. That static projection is required of every flagstaff component, and which mode
runs is decided once by roundel's output policy, never by the component. A box with an
href draws its text as a terminal hyperlink where the terminal is believed to support
OSC 8, and as text (url) everywhere else. Named borders come from the plugin registry, and
fromCliBoxes() brings the cli-boxes set with you.
When to switch from boxen
- Your boxes end up in CI logs, in an agent's context or in front of a screen reader.
- You want boxen's exact drawing without its fourteen-package tree — the import swap alone does that.
The loop, the built-ins and the other drop-in paths are on flagstaff.
Coming from log-update
A log-update alternative with a drop-in path: import logUpdate from flagstaff/log-update, graded 99 / 99 by log-update's own test suite — then a frame loop whose static projection gives pipes one line per state and --json one event per transition.
Coming from cli-table3
A cli-table3 alternative with a drop-in path: import Table from flagstaff/cli-table3, graded 29 / 29 by cli-table3's own test suite — then a table component whose static projection gives a pipe and an agent one line of header: value pairs per row.