sugarcraft/sugar-veil

PHP port of rmhubbert/bubbletea-overlay — modal/overlay compositing for terminal UIs. Composite foreground content over a background at any position (Top/Right/Bottom/Left/Center) with optional pixel offsets.

Maintainers

Package info

github.com/sugarcraft/sugar-veil

pkg:composer/sugarcraft/sugar-veil

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v0.2.0 2026-05-07 01:29 UTC

Requires

  • php: ^8.1
  • sugarcraft/candy-core: @dev

Requires (Dev)

MIT a701ca34b3d5d650fe72e4606f7a2f5f7f1cfd1a

  • Joe Huss <detain.woop@interserver.net>

terminalmodalcompositeoverlaytuisugarcraft

This package is not auto-updated.

Last update: 2026-05-07 14:50:23 UTC

README

sugar-veil

CI codecov Packagist Version License PHP

SugarVeil

PHP port of rmhubbert/bubbletea-overlay — modal/overlay compositing for terminal UIs. Composite one string (foreground) over another (background) at any position with optional pixel offsets.

Features

  • 9 position modes: Top, Right, Bottom, Left, Center, and the 4 corners (TopRight, BottomRight, BottomLeft, TopLeft)
  • Pixel-precise offsets: X/Y offsets fine-tune any position
  • Pure rendering: composites any background + foreground strings
  • Works with any TUI framework: render your models first, then composite
  • No dependencies: pure PHP, no FFI

Install

composer require sugarcraft/sugar-veil

Quick Start

use SugarCraft\Veil\Veil;

$veil = Veil::new();

// Background: a 40x10 box
$bg = "┌──────────────────────────────────────┐\n" .
      "│         Main Application             │\n" .
      "│                                      │\n" .
      "│   [content]                          │\n" .
      "└──────────────────────────────────────┘";

// Foreground: a smaller overlay
$fg = "╔════════╗\n║ MODAL  ║\n╚════════╝";

// Composite fg centered over bg
$output = $veil->composite($fg, $bg, Position::CENTER, Position::CENTER);
echo $output;

Positioning

$veil->composite(
    string  $foreground,
    string  $background,
    Position $vertical,    // TOP | CENTER | BOTTOM
    Position $horizontal,  // LEFT | CENTER | RIGHT
    int      $xOffset = 0, // shift right (+N) or left (-N) cells
    int      $yOffset = 0  // shift down  (+N) or up   (-N) lines
): string

Corner positions

// Top-right corner
$veil->composite($fg, $bg, Position::TOP, Position::RIGHT);

// Bottom-left corner with offset
$veil->composite($fg, $bg, Position::BOTTOM, Position::LEFT, xOffset: 2, yOffset: -1);

License

MIT