@flyingrobots/bijou

The pure, zero-dependency core of Bijou.

@flyingrobots/bijou provides the foundational primitives for CLIs, prompts, and portable terminal output. It manages components, themes, environment detection, and the core Surface and LayoutNode types.

Role

• Degradation-First: Automatic mode detection for interactive, static, pipe, and accessible output.
• Mixed-Mode: High-performance Surface primitives for rich TUI apps, with string-first helpers for standalone CLI scripts.
• Surface primitives without abandoning strings: Runtime apps can stay on the surface path while CLI-first flows still use the string-first helpers.
• Hexagonal Core: Pure TypeScript logic isolated from platform IO via Runtime, IO, and Style ports.

Install

npm install @flyingrobots/bijou @flyingrobots/bijou-node

Quick Start

import { initDefaultContext } from '@flyingrobots/bijou-node';
import { badge, boxSurface, tableSurface } from '@flyingrobots/bijou';

const ctx = initDefaultContext();

const panel = boxSurface(
  tableSurface({
    columns: [{ header: 'Service' }, { header: 'Status' }],
    rows: [['api', badge('LIVE', { variant: 'success', ctx })]],
    ctx,
  }),
  {
    title: 'Runtime',
    padding: { top: 1, bottom: 1, left: 1, right: 1 },
    ctx,
  },
);

Strategy: Choosing Component Families

Select the family based on the interaction semantic, not just the visual shape.

Render-path naming follows one house rule: the base family name is the public component, and a *Surface() companion means “the same family on the composable surface path.” If there is no *Surface() companion, the family is either already surface-native, intentionally string-first, or both paths would be fake duplication rather than a real second API.

Status and Feedback

• badge(): Compact, inline status.
• note(): Non-urgent explanation.
• alert(): Persistent, in-flow message.
• guidedFlow(): Calm multi-step assistance with one explicit next action.
• explainability(): AI- or machine-mediated recommendation with visible provenance and evidence.
• Use @flyingrobots/bijou-tui notifications for stacking, history, or active routing.

Selection and Prompts

• select(): Single choice from a stable set.
• filter(): Search-led choice from a large or dynamic set.
• multiselect(): Choosing multiple values to build a set.
• confirm(): Strictly binary decisions.

Hierarchy and Chronology

• tree(): Parent/child nesting.
• timeline(): Sequential, time-ordered events.
• dag(): Causal or dependency-based graphs.

Progress and Wayfinding

• progressBar(): Determinate completion.
• spinner(): Indeterminate activity.
• breadcrumb(): Path context.
• stepper(): Ordered stages in a linear process.

Documentation

• GUIDE.md: Productive-fast path.
• ADVANCED_GUIDE.md: Rendering doctrine, themes, and testing.
• Design System: Foundations, token vocabulary, and component families.

Built with 💎 by FLYING ROBOTS