Common Patterns

Reusable patterns and Effect.js integration techniques for building layouts with effect-boxes.

Effect.js Integration

Pipe and Data-Last Style

All box operations support data-last style for use with pipe. Functions are also callable data-first:

import * as Box from "effect-boxes/Box";
import * as Ansi from "effect-boxes/Ansi";
import { pipe } from "effect";
 
// Data-last with pipe (recommended)
const box1 = pipe(
  Box.text("Hello"),
  Box.moveRight(5),
  Box.annotate(Ansi.bold),
  Box.border("rounded")
);
 
// Data-first (also works)
const box2 = pipe(
  Box.moveRight(Box.text("Hello"), 5),
  Box.annotate(Ansi.bold),
  Box.border("rounded")
);
 
// Method chaining with .pipe()
const box3 = pipe(
  Box.text("Hello").pipe(Box.moveRight(5)),
  Box.annotate(Ansi.bold),
  Box.border("rounded")
);

╭──────────╮
│     Hello│
╰──────────╯

Structural Equality

Boxes implement Effect's Equal and Hash interfaces. Two boxes with the same content and dimensions are structurally equal:

import { Equal } from "effect";
import * as Box from "effect-boxes/Box";
 
const a = Box.text("hello");
const b = Box.text("hello");
const c = Box.text("world");
 
Equal.equals(a, b); // true
Equal.equals(a, c); // false

This means boxes can be used as keys in HashMap or deduplicated in HashSet.

UI Patterns

Status Indicators

const statusIcon = (icon: string, text: string, color: Ansi.AnsiAnnotation) =>
  Box.hcat(
    [
      pipe(Box.text(`${icon} `), Box.annotate(color)),
      pipe(Box.text(text), Box.annotate(color)),
    ],
    Box.top
  );
 
const statuses = Box.vcat(
  [
    statusIcon("✓", "Tests passed", Ansi.green),
    statusIcon("✗", "Build failed", Ansi.red),
    statusIcon("⚠", "3 warnings", Ansi.yellow),
    statusIcon("ℹ", "Running...", Ansi.blue),
  ],
  Box.left
);

✓ Tests passed
✗ Build failed
⚠ 3 warnings
ℹ Running...

Progress Bar

const progressBar = (progress: number, total: number, width: number) => {
  const ratio = Math.min(progress / total, 1);
  const filled = Math.round(ratio * width);
  const empty = width - filled;
 
  return Box.hcat(
    [
      pipe(Box.text("█".repeat(filled)), Box.annotate(Ansi.green)),
      pipe(Box.text("░".repeat(empty)), Box.annotate(Ansi.dim)),
      Box.text(` ${Math.round(ratio * 100)}%`),
    ],
    Box.top
  );
};
 
const bar = progressBar(70, 100, 50);

╭──────────────────────────────────────────────────────╮
│███████████████████████████████████░░░░░░░░░░░░░░░ 70%│
╰──────────────────────────────────────────────────────╯

Data Table

const table = (headers: string[], rows: Box.Box<Ansi.AnsiStyle>[][]) => {
  const colWidth = 16;
  const headerRow = Box.punctuateH(
    headers.map((h) =>
      pipe(
        Box.text(h),
        Box.annotate(Ansi.bold),
        Box.alignHoriz(Box.left, colWidth)
      )
    ),
    Box.top,
    Box.text("│")
  );
  const separator = Box.text(
    "─".repeat(headers.length * colWidth + headers.length - 1)
  );
  const dataRows = rows.map((row) =>
    Box.punctuateH(
      row.map((cell) => pipe(cell, Box.alignHoriz(Box.left, colWidth))),
      Box.top,
      Box.text("│")
    )
  );
  return Box.vcat([headerRow, separator, ...dataRows], Box.left);
};

╭──────────────────────────────────────────────────╮
│Name            │Role            │Status          │
│──────────────────────────────────────────────────│
│Alice           │Engineer        │Active          │
│Bob             │Designer        │Away            │
│Carol           │Manager         │Offline         │
╰──────────────────────────────────────────────────╯

Key-Value Panel

const kvPanel = (entries: [string, Box.Box<any>][], width: number) =>
  pipe(
    Container.make({ width, padding: 1 }, (ctx) =>
      Box.vcat(
        entries.map(([key, value]) =>
          Flex.row(
            [
              Flex.fixed(pipe(Box.text(`${key}:`), Box.annotate(Ansi.dim))),
              Flex.spacer(),
              Flex.fixed(value),
            ],
            ctx.innerWidth
          )
        ),
        Box.left
      )
    ),
    Box.border("rounded")
  );

╭────────────────────────────────────────╮
│                                        │
│ Host:                          prod-01 │
│ Status:                        healthy │
│ Uptime:                         14d 3h │
│ Load:                             0.42 │
│                                        │
╰────────────────────────────────────────╯

Composition Patterns

Building Reusable Components

Create helper functions that return Box values for consistent styling:

const heading = (text: string) =>
  pipe(Box.text(text), Box.annotate(Ansi.combine(Ansi.bold, Ansi.white)));
 
const label = (text: string) => pipe(Box.text(text), Box.annotate(Ansi.dim));
 
const badge = (text: string, color: Ansi.AnsiAnnotation) =>
  pipe(Box.text(` ${text} `), Box.annotate(color), Box.border("rounded"));
 
const section = (title: string, content: Box.Box<Ansi.AnsiStyle>) =>
  Box.vcat([heading(title), Box.text("─".repeat(40)), content], Box.left);

Container + Flex + Grid

The three Layout primitives compose for complex responsive layouts:

const dashboard = Container.make({ width: 65, padding: 1 }, (ctx) => {
  // Header with flex
  const header = Flex.row(
    [
      Flex.fixed(heading("Dashboard")),
      Flex.spacer(),
      Flex.fixed(label("v1.0")),
    ],
    ctx.innerWidth
  );
 
  // KPI cards in a grid
  const kpis = Grid.auto(kpiData.map(renderKpiCard), ctx.innerWidth, {
    minColWidth: 20,
  });
 
  // Vertical stack
  return Flex.col(
    [Flex.fixed(header), Flex.fixed(kpis), Flex.grow(mainContent)],
    ctx.innerHeight
  );
});

Conditional Styling

const statusColor = (status: string) => {
  switch (status) {
    case "ok":
      return Ansi.green;
    case "warn":
      return Ansi.yellow;
    case "error":
      return Ansi.red;
    default:
      return Ansi.dim;
  }
};
 
const renderStatus = (name: string, status: string) =>
  Flex.row(
    [
      Flex.fixed(Box.text(name)),
      Flex.spacer(),
      Flex.fixed(pipe(Box.text(status), Box.annotate(statusColor(status)))),
    ],
    40
  );