README

A framework-agnostic, component-based TUI layout and rendering system for PHP terminal applications.

Why Parfait?

Building a terminal UI usually means hand-managing ANSI codes, cursor math, and Unicode width edge cases. Parfait gives you a declarative, component-based API instead — you describe the UI as a tree of components, and Parfait renders it to a string.

• 🧩 Components — Panel, Modal, Accordion, FileTree, SelectList, NodeCanvas, Text, and more, each with a fluent API.
• 📐 Layouts — compose Layout::columns() / Layout::rows() with ratio-based sizing.
• 🎨 256-color theming — a semantic Color enum that emits correct ANSI codes.
• 📏 Unicode-correct width — emoji, CJK, combining marks, and ANSI escapes are measured accurately.
• 🪟 Portals — dropdowns, modals, and toasts render onto higher layers instead of being clipped.
• 🧪 Effortless testing — components are pure functions: state in → render() → string out. No terminal required.
• 🪶 Zero framework dependencies — needs only PHP 8.2+ and soloterm/grapheme.

Parfait layers cleanly on top of Laravel Prompts for input/render loops, but depends on neither Laravel nor Prompts — you can drive it from any PHP terminal program.

Requirements

• PHP ^8.2
• ext-mbstring and ext-intl (for grapheme-aware width)

Installation

composer require artisan-build/parfait

Quick Start

Every component knows the space it has via a Container, and renders to a string you print yourself:

use ArtisanBuild\Parfait\Components\Panel;
use ArtisanBuild\Parfait\Components\Text;
use ArtisanBuild\Parfait\Enums\Color;
use ArtisanBuild\Parfait\Support\Container;

$panel = Panel::make('welcome')
    ->bordered()
    ->title('Parfait')
    ->body(Text::make('greeting', 'Welcome to the TUI!')->fg(Color::Cyan))
    ->setContainer(new Container(width: 40, height: 5));

echo $panel->render();

╭── Parfait ───────────────────────────╮
│Welcome to the TUI!                   │
│                                      │
│                                      │
╰──────────────────────────────────────╯

Composing a layout

Layout arranges child components and hands each one a correctly-sized Container:

use ArtisanBuild\Parfait\Components\Panel;
use ArtisanBuild\Parfait\Components\Text;
use ArtisanBuild\Parfait\Layouts\Layout;
use ArtisanBuild\Parfait\Support\Container;

$ui = Layout::columns(1, 3)            // sidebar : main = 1 : 3
    ->add(Panel::make('sidebar')->sidebar()->title('Files'))
    ->add(Panel::make('main')->bordered()->body(Text::make('body', 'Editor')))
    ->setContainer(new Container(width: 100, height: 30));

echo $ui->render();

Components

Each component lives in src/Components/ alongside a co-located *Renderer where rendering is non-trivial — see Architecture.

Architecture

Parfait uses a co-located renderer pattern:

• Component.php holds state and props (public properties, fluent setters).
• ComponentRenderer.php turns that state into a string.

This keeps rendering logic isolated and makes components trivial to test — construct one, set its container, assert on the rendered string. The base Component provides styling helpers (applyStyle, width/truncate utilities), view-state storage, and the portal hook.

┌─────────────────────────────────────────────┐
│  Your program (owns data, handles events)    │
├─────────────────────────────────────────────┤
│  Parfait (layout + components → string)      │
├─────────────────────────────────────────────┤
│  Terminal                                    │
└─────────────────────────────────────────────┘

See DESIGN.md for the full design rationale.

Documentation

The docs/ directory covers each subsystem in depth:

1. Introduction
2. Components
3. Layouts
4. Styles
5. Navigation
6. View State
7. Events
8. Testing
9. Portals

Testing

Components are pure functions, so tests need no terminal or framework:

use ArtisanBuild\Parfait\Components\Text;
use ArtisanBuild\Parfait\Enums\Color;

it('styles text', function () {
    expect(Text::make('t', 'hi')->fg(Color::Cyan)->render())
        ->toBe("\e[38;5;81mhi\e[0m");
});

Run the suite:

composer test       # pest
composer analyse    # phpstan
composer lint       # pint (use lint:test to check without fixing)

Contributing

Contributions are welcome — see CONTRIBUTING.md for the dev setup, coding standards, and quality gates.

License

Parfait is open-source software licensed under the MIT license.