SugarStyle
Declarative styling + layout
Style, Border, Table\Table, Listing\ItemList, Tree\Tree, Layout::joinHorizontal/joinVertical, Layout::place, multi-layer Canvas, and Theme — the canonical color palette for all SugarCraft libs. The rendering core is pure — no I/O (an optional Output facade wraps print/printf/fprint) — so you can render frames inside a unit test.
Install
composer require sugarcraft/sugar-style
Quickstart
use SugarCraft\Style\{Style, Border, Layout, Position};
use SugarCraft\Style\Table\Table;
use SugarCraft\Core\Util\Color;
$banner = Style::new()
->bold()
->foreground(Color::hex('#ff5f87'))
->padding(0, 2)
->render('hello, styled world');
$table = Table::new()
->headers('Name', 'Age')
->row('Alice', '30')
->row('Bob', '25')
->border(Border::rounded())
->render();
echo Layout::joinVertical(Position::LEFT, $banner, $table);
What's in the box
StyleForeground / background, bold / italic / underline, overline, padding, margin, width, alignment. Immutable value object; setters keep lipgloss's bare names (
fg(), bold(), width()) and each returns a new Style.BorderEight built-in styles + custom.
Border::rounded(), thick(), double(), block(), hidden(), normal(), ascii(), markdownBorder().TableHeaders, rows, per-cell styleFunc. ANSI-aware width calc with grapheme cluster support. Optional
wrap() callback: every line it returns renders, so a wrapped row spans several physical lines.List + TreeBulleted lists and ASCII trees with custom enumerators.
Layout
joinHorizontal, joinVertical, place, plus the ratatui-style constraint solver (Layout\Layout::vertical([...])->split()) and RegionBridge for handing rectangles between sugar-constraints and sugar-cellbuffer.CanvasMulti-layer compositor. Z-ordered overlays merged by a cell-aware row splice (no alpha blending — upper cells replace lower ones), ideal for modals + tooltips.
ThemeSingle source of truth (SSOT) color palette. 10 named factories (dark/light/dracula/tokyoNight/oneDark/githubDark/solarized*/ansi/adaptive). 13 color slots (foreground/background/primary/secondary/accent/muted/error/warning/success/info/border/separator/cursor). All
with*() setters return a new Theme. adaptive() reads $COLORFGBG: any numeric slot (0-255) in the last field decides light vs dark by luminance (e.g. 7/15 light, 0/8 dark); unset, non-numeric or out-of-range falls back to dark.Embedded titles + seamsbtop-style box titles:
Border::withEmbeddedTitle() brackets text in junctions (╭─┐cpu┌────┐12:00┌───────╮) on any of six anchors; Border::seam() picks the ┬ ┴ ├ ┤ ┼ rune where an internal divider meets the frame, preserving the border family.Color degradationA Style carries a
ColorProfile and render() downsamples to it, as charmbracelet/colorprofile's Writer does: TrueColor → 38;2, Ansi256 → 38;5, Ansi → 30..37/90..97, Ascii (what NO_COLOR selects) drops color but keeps bold/italic/underline and OSC 8 links, and NoTty strips every escape — including ones carried in by pre-styled content, a transform() or a border title — while padding, borders and alignment stay. Tier rewrites apply to RGB colors; palette-slot colors (Color::ansi(n)) always emit their 30..37/90..97 form at every tier.Underline truthSub-style shapes ride the numeric SGR
4:N form emitted only alongside underline() — terminals that ignore 4:N typically draw no underline at all (no plain SGR 4 companion is sent). SGR 58 has no 4-bit spelling, so at the Ansi tier the underline color is applied through the foreground attribute instead — it recolours the glyphs rather than tinting the rule.Embedded border titles
use SugarCraft\Style\Border;
use SugarCraft\Style\Border\TitleAnchor;
use SugarCraft\Style\Style;
$border = Border::rounded()
->withEmbeddedTitle('cpu')
->withEmbeddedTitle('12:00', TitleAnchor::TopCenter)
->withEmbeddedTitle('mem', TitleAnchor::BottomLeft)
->withEmbeddedTitle('disk', TitleAnchor::BottomLeft);
echo Style::new()->border($border)->width(24)->render('load 0.42');
// ╭─┐cpu┌────┐12:00┌───────╮
// │load 0.42 │
// ╰─┘mem└─┘disk└───────────╯
echo Border::normal()->seam(left: true, right: true, up: false, down: true); // ┬
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by lipgloss (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| Theme | dark() / light() / dracula() / tokyoNight() / oneDark() / githubDark() / solarizedDark() / solarizedLight() / ansi() / adaptive() | Named theme factories |
| Theme | withPrimary($c) / withForeground($c) / withBackground($c) / withError($c) / … | 13 color slot setters — all return a new Theme |
| Style | new() | Create a new style |
| Style | foreground(color) | Set foreground color |
| Style | background(color) | Set background color |
| Style | bold(), italic(), underline(), blink(), rapidBlink() | Text effects (blink = SGR 5, rapidBlink = SGR 6) |
| Style | patch($other) | Incremental merge — only props set in $other are applied; a null color/width/border in $other is skipped, not a clear |
| Style | colorProfile(ColorProfile $p) | Force the color tier render() downsamples to (TrueColor / Ansi256 / Ansi / Ascii / NoTty) |
| BorderGradientBlend | fromColors(Color ...$colors) | 1-5 colors → 4 interpolated border-side colors |
| Style | padding(...$sides) | Add padding (1, 2, or 4 values — CSS-style shorthand) |
| Style | render(content) | Render styled content |
| Border | normal(), rounded(), thick(), double(), block(), ascii(), hidden(), markdownBorder() | All eight border style presets |
| Border | withEmbeddedTitle(text, ?anchor, ?open, ?close) | btop-style title cut into the edge (╭─┐cpu┌──╮); left/right inset one rune, center uses btop's clock formula, overflow shrinks with … |
| Border | embedJunctions(bool $bottom = false) | Default [open, close] junction pair from the border's own corners (rounded arcs squared off) |
| Border | seam(left, right, up, down) | Junction rune where a divider meets the frame (┬ ┴ ├ ┤ ┼), in the border's own family |
| Border | titles(): array | Configured border titles (getTitles() remains as a deprecated alias); over-long titles are truncated to the edge |
| Table | new() | Create a table |
| Table | headers(...), row(...) | Add table content |
| Table | wrap(?\Closure(string $cell, int $colWidth): list<string> $fn) | Per-cell wrapping; a wrapped row spans several physical lines |
| Layout | joinVertical(), joinHorizontal() | Join layouts |
| Canvas | new() | Create multi-layer canvas |
| Bar | StatusBar::new()->left()/center()/right(Segment|string ...)->width()/style()->render(); HelpBar::fromMap() | One-line chrome: positioned segment groups + key→label help rows |
Demos.
VHS-recorded GIF demos of the library's headline examples. Regenerated automatically on every push that touches the source. One example ships without a GIF: examples/styled-text.php.
Style
Foreground / background, bold, italic — chained Style builders.
Border
All eight built-in border styles.
Table
Per-cell styleFunc with header highlighting.
List
Bulleted list with custom enumerator.
Tree
Indented tree with branch glyphs.
Dashboard
Multi-panel layout joined horizontally + vertically.
Constraints
Constraint-based layout driving a 3-pane dashboard.