README

Pre-built, customizable UI widgets for the xocdr/tui terminal UI framework.

Installation

composer require xocdr/tui-widgets

Requirements

PHP 8.4+
xocdr/tui ^0.2
ext-tui C extension

Quick Start

<?php

use Xocdr\Tui\Tui;
use Xocdr\Tui\Components\Box;
use Xocdr\Tui\Widgets\Input\Input;
use Xocdr\Tui\Widgets\Display\TodoList;

$app = function() {
    return Box::column([
        Input::create()
            ->placeholder('Enter your name')
            ->onSubmit(fn($value) => print("Hello, $value!")),

        TodoList::create([
            ['content' => 'Search codebase', 'status' => 'completed'],
            ['content' => 'Implement feature', 'status' => 'in_progress'],
            ['content' => 'Write tests', 'status' => 'pending'],
        ]),
    ]);
};

Tui::render($app)->waitUntilExit();

Widget Categories

Category	Widgets	Description
Support	Icon, FuzzyMatcher	Reusable utilities
Input	Input, SelectList, MultiSelect, Autocomplete, ConfirmInput, QuickSearch, Form	User input widgets
Layout	Divider, Section, Scrollable, Collapsible	Structure/containers
Display	TodoList, StatusBar, Tabs, Checklist, Tree, ItemList, Breadcrumb	Lists, navigation, status
Streaming	StreamingText, ThinkingBlock, ConversationThread	Real-time/AI output
Visual	BigText, Image, Shape	Graphics/visual elements
Content	Paragraph, ContentBlock, OutputBlock, Markdown, Diff, Link	Rich content
Feedback	Badge, Alert, KeyHint, Toast, LoadingState, Interruptible, Meter, ErrorBoundary	User feedback
Modal	PermissionDialog	Dialogs

Project Structure

src/
├── Contracts/      # Widget interfaces (InteractiveWidget, FocusableWidget, etc.)
├── Support/
│   ├── Enums/      # Type-safe enums (AlertVariant, BadgeVariant, etc.)
│   ├── Traits/     # Reusable traits (ScrollableTrait)
│   ├── Icon.php, FuzzyMatcher.php, Constants.php
├── Input/          # Input, SelectList, MultiSelect, Autocomplete, ConfirmInput, QuickSearch, Form
├── Layout/         # Divider, Section, Scrollable, Collapsible
├── Display/        # TodoList, StatusBar, Tabs, Checklist, Tree, ItemList, Breadcrumb
├── Streaming/      # StreamingText, ThinkingBlock, ConversationThread
├── Visual/         # BigText, Image, Shape
├── Content/        # Paragraph, ContentBlock, OutputBlock, Markdown, Diff, Link
├── Feedback/       # Badge, Alert, KeyHint, Toast, LoadingState, Interruptible, Meter, ErrorBoundary
└── Modal/          # PermissionDialog

Enums

Type-safe enums replace magic strings for variants, positions, and styles:

Enum	Values	Used By
`AlertVariant`	error, warning, success, info	Alert
`BadgeVariant`	default, success, error, warning, info, loading, primary, secondary	Badge
`ToastVariant`	success, error, warning, info	Toast
`ToastPosition`	top, bottom, top-left, top-right, bottom-left, bottom-right	Toast
`LoadingStateType`	loading, success, error, idle, pending	LoadingState
`BulletStyle`	disc, circle, square, dash, arrow, star, check, number	ItemList
`CursorStyle`	block, underline, bar, none	Input

Each enum provides color() and icon() methods for consistent theming.

Contracts

Widget capability interfaces for type-safe composition:

Interface	Methods	Purpose
`InteractiveWidget`	`interactive(bool)`	Enable/disable user interaction
`FocusableWidget`	`isFocused(bool)`	Track focus state
`SelectableWidget`	`onSelect(callable)`	Handle selection events
`DismissibleWidget`	`dismissible(bool)`, `onDismiss(callable)`	Allow widget dismissal

Development

# Install dependencies
composer install

# Run tests
./vendor/bin/phpunit

# Run single test
./vendor/bin/phpunit --filter TestClassName::testMethodName

# Check code style
./vendor/bin/phpcs

# Fix code style
./vendor/bin/phpcbf

# Static analysis
./vendor/bin/phpstan analyse

Working Directory

The .working/ directory is used for temporary files and is git-ignored:

File	Purpose
`CODE_REVIEW.md`	Code review results
`*.tmp`	Temporary files
`summaries/`	Analysis summaries
`todo.md`	Current task tracking

This directory is for development artifacts that shouldn't be committed - things like code review outputs, temporary analysis files, work-in-progress notes, and other transient content.

Documentation

Analysis Summary - Widget overview and implementation order
Task Files - Complete specifications for each widget (42 files)
Core Specs - xocdr/tui core library reference

Related Packages

ext-tui - C extension providing terminal rendering, Yoga layout, and input handling
xocdr/tui - Core PHP library with components, hooks, and event system

License

MIT

xocdr / tui-widgets

Maintainers

Details