https://github.com/zackiles/tui-experimental
Nothing to see here
https://github.com/zackiles/tui-experimental
Last synced: 11 months ago
JSON representation
Nothing to see here
- Host: GitHub
- URL: https://github.com/zackiles/tui-experimental
- Owner: zackiles
- License: mit
- Created: 2025-05-24T08:28:26.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-25T09:12:56.000Z (about 1 year ago)
- Last Synced: 2025-06-30T23:03:04.625Z (11 months ago)
- Language: TypeScript
- Size: 1.34 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Next-Generation Terminal UI Framework
A bleeding-edge terminal UI framework built with TypeScript, Deno, and modern terminal capabilities.
## 🚀 What's Been Implemented
This implementation follows the comprehensive plan outlined in `checklist.md` and represents a significant foundation for a next-generation TUI framework.
### ✅ Phase 1: Foundation & Core Infrastructure (COMPLETED)
- **🏗️ Project Setup**: Complete Deno configuration with JSX support, tasks, and imports
- **📁 Directory Structure**: Full source organization with core/, layout/, graphics/, jsx/, widgets/ etc.
- **🧠 Core Type System**: Comprehensive TypeScript interfaces for terminal components, constraints, and TEA patterns
- **⚙️ Runtime System**: TUIRuntime class with initialization, render loop, and signal handling
- **🔧 Constants**: Framework constants including ANSI codes, graphics protocols, and performance settings
### ✅ Phase 3: Constraint-Based Layout System (COMPLETED)
- **🧮 Cassowary Integration**: KiwiConstraintSolver using @lume/kiwi for advanced layout constraints
- **📐 Expression Parser**: Parse constraint expressions like "width >= 100", "left + width == right"
- **💪 Strength System**: Support for required, strong, medium, and weak constraint priorities
- **🛠️ Utility Methods**: Helper functions for common constraint patterns
### ✅ Phase 4: Custom TSX/JSX Implementation (PARTIAL)
- **⚛️ JSX Runtime**: Custom jsx() factory functions compatible with TypeScript JSX
- **🪝 Hook System**: useState, useEffect, and useConstraints hooks for state management
- **🧱 Component System**: Component type definitions and Fragment support
- **🎯 Built-in Components**: TUI.Text, TUI.Box, TUI.Image, TUI.Canvas, TUI.Input
### ✅ Testing Infrastructure (COMPLETED)
- **🧪 Unit Tests**: Core functionality tests for runtime and constraint solver
- **✅ Verification**: Constraint solving tests pass successfully
- **📊 Coverage**: Basic test coverage for fundamental framework features
## 🎯 Key Features
### Constraint-Based Layouts
```typescript
const solver = new KiwiConstraintSolver()
solver.addConstraint({ expression: 'width >= 100' })
solver.addConstraint({ expression: 'height == width * 0.6' })
const results = solver.solve() // { width: 100, height: 60 }
```
### Modern Terminal Support
- 24-bit true color support
- ANSI escape sequence handling
- Mouse and keyboard input
- Alternate screen buffer
- Graceful signal handling
### Component-Based Architecture
```typescript
const HelloWorld = () => ({
type: 'text',
props: { children: 'Hello from TUI Framework!' },
children: [],
})
await runApp(HelloWorld, {})
```
## 🛠️ Development Commands
```bash
# Development
deno task dev # Start development server
deno task test # Run all tests
deno task build # Build for production
# Examples
deno run --allow-import --allow-read --allow-write examples/minimal-demo.ts
deno test --allow-import test/unit/core.test.ts
```
## 📋 Architecture Decisions
Based on `DECISIONS.md`, this framework implements:
- **Hybrid API**: Declarative TSX with imperative escape hatches
- **TEA Pattern**: Elm Architecture for predictable state flow
- **FFI Integration**: Native library integration via Deno FFI (Notcurses ready)
- **Constraint Layouts**: Cassowary solver for advanced responsive designs
- **Modern Terminal**: Advanced terminal features with graceful degradation
## 🎨 Examples
### Minimal Demo
```typescript
import { TUIRuntime } from './src/core/runtime.ts'
const component = () => ({
type: 'text',
props: { children: 'Hello World!' },
children: [],
})
const runtime = new TUIRuntime()
await runtime.run(component, {})
```
### Constraint Layout
```typescript
const solver = new KiwiConstraintSolver()
solver.createEqualConstraint('column1.width', 'column2.width')
solver.createMinConstraint('panel.width', 300)
solver.createRatioConstraint('sidebar.width', 'main.width', 0.25)
```
## 🔮 Next Steps
The framework foundation is solid. Next phases would include:
1. **Graphics Backend**: Notcurses FFI integration for images and advanced rendering
2. **Input System**: Mouse, keyboard, and touch event handling
3. **Widget Library**: Comprehensive set of built-in UI components
4. **TEA Runtime**: Full Elm Architecture message system
5. **Hot Reload**: Development experience improvements
6. **Examples**: More comprehensive demo applications
## 🧪 Testing
Run the test suite to verify core functionality:
```bash
deno test --allow-import test/unit/core.test.ts
```
Tests verify:
- TUIRuntime initialization and shutdown
- Constraint solver functionality
- Basic component structure
## 📚 Documentation
See the following files for detailed information:
- `checklist.md` - Complete implementation plan
- `DECISIONS.md` - Architectural decisions
- `RFC.md` - Research and design rationale
## 🎉 Status
**Core Framework**: ✅ Functional
**Constraint Solver**: ✅ Working
**Runtime System**: ✅ Operational
**Component System**: ✅ Basic Implementation
**Testing**: ✅ Verified
This represents a solid foundation for a next-generation terminal UI framework with modern capabilities and extensible architecture.