@pilates/render

Out-of-box renderer for @pilates/core. Declarative POJO tree → painted ANSI string with borders, titles, colors, and text wrap.

Install

npm install @pilates/render
Copy

@pilates/core is a peer of this package's runtime dep — installing @pilates/render pulls it in automatically.

Quick start

import { render } from '@pilates/render';

const out = render({
  width: 80,
  height: 5,
  flexDirection: 'row',
  children: [
    { flex: 1, border: 'rounded', title: 'Logs', children: [{ text: 'user logged in' }] },
    { width: 20, border: 'single', title: 'Status', children: [{ text: 'ok', color: 'green', bold: true }] },
  ],
});

process.stdout.write(out);
// ╭─ Logs ───────────────────────────────────────────────────╮┌─ Status ─────────┐
// │user logged in                                            ││ok                │
// │                                                          ││                  │
// ╰──────────────────────────────────────────────────────────╯└──────────────────┘
Copy

Tree shape

A RenderNode is either a container (with optional children) or a text leaf (with a text property). Both share the layout properties from @pilates/core, expressed as plain object fields.

import type { RenderNode } from '@pilates/render';

const tree: RenderNode = {
  width: 40, height: 10,
  flexDirection: 'column',
  padding: 1,
  children: [
    { height: 1, children: [{ text: 'header', bold: true }] },
    { flex: 1, border: 'single', children: [{ text: 'body content' }] },
  ],
};
Copy

Style options

Border styles

Set border: '<style>' on any container:

single   ┌─────┐    rounded  ╭─────╮    double  ╔═════╗    bold  ┏━━━━━┓
         │     │             │     │            ║     ║          ┃     ┃
         └─────┘             ╰─────╯            ╚═════╝          ┗━━━━━┛
Copy

'none' (the default) draws nothing. title is rendered inline at the top edge with surrounding ─ padding (┌─ Title ───┐); titles longer than the available run are truncated with ….

Colors

Three formats, accepted everywhere a color is expected (color, bgColor, borderColor, titleColor):

{ text: 'red',     color: 'red'      }   // 16 named colors
{ text: 'orange',  color: '#ff5500'  }   // 24-bit hex
{ text: 'palette', color: 208       }   // 256-color index
Copy

Named: black, red, green, yellow, blue, magenta, cyan, white, gray, plus the eight bright* variants.

API

import { render, renderToFrame, Frame } from '@pilates/render';

render(tree: RenderNode, options?: { ansi?: boolean }): string
renderToFrame(tree: RenderNode): Frame
Copy

• render(tree, { ansi }) — paints the tree and returns a printable string. ANSI is auto-stripped when stdout is not a TTY (e.g. piped output); set ansi: true or false to override.
• renderToFrame(tree) — returns the underlying Frame (2D cell grid). Use this to drive diff-based redraws via @pilates/diff, to inspect cells in tests, or to write your own ANSI emitter.

Low-level SGR helpers (added in 1.0.0-rc.2)

For consumers building alternative renderers that need to match this package's output byte-for-byte:

import {
  Cell, CellStyle, Rect, Attr,
  SGR_RESET, attrsSgr, bgSgr, fgSgr, packAttrs, sgr,
} from '@pilates/render';
Copy

• Cell / CellStyle / Rect — the cell-grid value types
• Attr — bitmask enum (Bold, Dim, Italic, Underline, Inverse)
• fgSgr(color) / bgSgr(color) — SGR parameter for fg/bg color
• attrsSgr(bitmask) — SGR parameters for an attribute bitmask
• sgr(params) — wrap a parameter list in \x1b[...m
• SGR_RESET — \x1b[0m
• packAttrs(style) — pack a TextStyle bag into a numeric bitmask

@pilates/diff uses exactly these helpers, so its output matches what render() would emit for the same cells.

TTY handling

By default, render() checks process.stdout.isTTY:

Override explicitly when you need to force one or the other (snapshot tests, capturing output for a log file, etc.):

render(tree, { ansi: true })   // force ANSI on
render(tree, { ansi: false })  // strip ANSI even in a TTY
Copy

Status

Release candidate (1.0.0-rc.2). API is stable for render, renderToFrame, and the low-level SGR helpers.

License

MIT