@santana-org/ui

📦 Install

npm install @santana-org/ui
pnpm add @santana-org/ui

🚀 Quickstart

import { createSpinner, table, box, badge, createProgressBar } from "@santana-org/ui"

const spinner = createSpinner("Fetching data…")
spinner.start()
await fetchData()
spinner.succeed("Done!")

📖 API

Spinner

const spinner = createSpinner(message, options?)
spinner.start(message?)   // begin animating
spinner.update(message)   // update the label while running
spinner.succeed(message?) // ✓ green checkmark
spinner.fail(message?)    // ✗ red cross
spinner.stop()            // · neutral stop

| Option | Type | Default | Description | |---|---|---|---| | colorsEnabled | boolean | true | Force or disable ANSI colors | | stream | WriteStream | process.stderr | Output destination |

Table

table(rows, options?)

rows is string[][]. The first row is treated as a header by default.

| Option | Type | Default | Description | |---|---|---|---| | header | boolean | true | Style first row as a header | | colorsEnabled | boolean | true | Force or disable ANSI colors |

console.log(table([
  ["Name", "Version", "Size"],
  ["colors", "0.2.1", "18 kB"],
  ["logger", "0.2.2", "4 kB"],
]))
// ╭────────┬─────────┬───────╮
// │ Name   │ Version │ Size  │
// ├────────┼─────────┼───────┤
// │ colors │ 0.2.1   │ 18 kB │
// │ logger │ 0.2.2   │ 4 kB  │
// ╰────────┴─────────┴───────╯

Box

box(content, options?)

| Option | Type | Default | Description | |---|---|---|---| | title | string | — | Optional title in the top border | | width | number | 60 | Total box width | | padding | number | 1 | Horizontal inner padding | | colorsEnabled | boolean | true | Force or disable ANSI colors |

console.log(box(["Line one", "Line two"], { title: "Summary" }))
// ╭─ Summary ──────────────────────────────────────────────╮
// │                                                        │
// │ Line one                                               │
// │ Line two                                               │
// │                                                        │
// ╰────────────────────────────────────────────────────────╯

Badge

badge(text, options?)

| Option | Type | Default | Description | |---|---|---|---| | variant | BadgeVariant | "default" | Color scheme | | colorsEnabled | boolean | true | Force or disable ANSI colors |

Available variants: "default" "success" "warn" "error" "info" "muted" "accent"

badge("v1.2.3")              // [v1.2.3]  (cyan)
badge("DONE", { variant: "success" })  // [DONE]    (green)
badge("WARN", { variant: "warn" })     // [WARN]    (yellow)

Progress bar

const bar = createProgressBar(options?)
bar.update(value, total, label?)  // rewrite current line
bar.complete(label?)              // ✓ done line

| Option | Type | Default | Description | |---|---|---|---| | width | number | 30 | Bar fill width in characters | | filled | string | "█" | Filled segment character | | empty | string | "░" | Empty segment character | | colorsEnabled | boolean | true | Force or disable ANSI colors | | stream | WriteStream | process.stderr | Output destination |

const bar = createProgressBar()
for (let i = 0; i <= 100; i++) {
  bar.update(i, 100, "Uploading…")
  await sleep(20)
}
bar.complete("Upload done")

Status lines

statusSuccess("Built in 1.2s")               // ✓ Built in 1.2s
statusError("Build failed", { label: "tsc" }) // ✗ [tsc] Build failed
statusWarn("Peer dep missing")               // ⚠ Peer dep missing
statusInfo("Listening on :3000")             // ◆ Listening on :3000
statusMuted("Skipping unchanged files")      // · Skipping unchanged files
statusStep(2, 5, "Installing deps")          // [2/5] Installing deps

All accept { colorsEnabled?, label? } options.

Divider / section header

divider()                          // ────────────────────────────────────────────────────────────
divider("Results", { width: 40 }) // ────────── Results ──────────
sectionHeader("Configuration")    // ┌ Configuration

Brand banner

brandBanner({
  title: "my-cli",
  version: "1.2.3",
  tagline: "The fast build tool",
  badge: "beta",
})

╭──────────────────────────────────────────────────────────╮
│                                                          │
│  my-cli  v1.2.3                                          │
│  The fast build tool  [ beta ]                           │
│                                                          │
╰──────────────────────────────────────────────────────────╯

inlineBrand("my-cli") // ◆ my-cli

🏗️ Design decisions

• TTY-aware. All components respect colorsEnabled — pass false or detect process.stdout.isTTY to get clean plain-text output in CI or piped contexts.
• No global state. Every primitive is created fresh via a factory function — safe to use concurrently.
• Stream-injectable. Spinners and progress bars write to process.stderr by default and accept any WriteStream — making them easy to test or redirect.
• ESM-first. CJS interop included, but the package is written for modern runtimes.

📄 License

MIT © santana-org — contributions are welcome, see CONTRIBUTING.