Metadata-Version: 2.3
Name: tuiro
Version: 0.1.0
Summary: Tiny terminal UI utility for clean, colorful build output.
Keywords: terminal,tui,ansi,cli,colors,logging,build-tools
Author: NellowTCS
Author-email: NellowTCS <nellowtcs@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Terminals
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# tuiro

tuiro is a tiny terminal UI helper designed for clean, readable, and structured output in build scripts and command‑line tools. It provides simple utilities for sections, banners, status messages, command logging, and themed output without introducing heavy dependencies or complex abstractions.

> tuiro began as an internal utility inside the TactileBrowser project (https://github.com/NellowTCS/TactileBrowser). It is now available as a standalone library for any script or tool that wants clear and consistent terminal output.

## Features

- Lightweight and dependency‑free
- ANSI color support with optional CI mode
- Built‑in themes and user‑defined palettes
- Section and subsection headers
- Informational, warning, success, and error messages
- Command logging for build steps
- Centered banners with automatic terminal width detection
- A simple step context manager for build phases
- A minimal CLI for quick verification and theme testing

## Installation

```
pip install tuiro
```

For development:

```
uv pip install -e .
```

## Usage

Basic example:

```python
from tuiro import TUI

tui = TUI()
tui.banner("Build")
tui.section("Environment")
tui.info("Checking dependencies")
tui.success("All checks passed")
```

Example output (colors omitted):

```
╔══════════════════════════════════════════════════════════╗
║                          Build                           ║
╚══════════════════════════════════════════════════════════╝

────────────────────────────────────────────────────────────
  Environment
────────────────────────────────────────────────────────────
[*] Checking dependencies
[OK] All checks passed
```

## Themes

tuiro supports both built‑in themes and user‑defined palettes.

### Built‑in themes

- default  
- mono  
- pastel  

Use a theme by name:

```python
tui = TUI(theme="pastel")
```

### Custom palettes

Palettes live in `tuiro.palette`. Users can define their own palette by subclassing `Palette`:

```python
from tuiro.palette import Palette
from tuiro.colors import Colors

class MyPalette(Palette):
    success = Colors.BRIGHT_GREEN
    info = Colors.BRIGHT_CYAN
```

Then pass it to TUI:

```python
tui = TUI(theme=MyPalette)
```

or:

```python
tui = TUI(theme=MyPalette())
```

Note: The CLI `--theme` flag accepts only built‑in theme names from `PROFILES`. Custom palettes must be provided from Python code.

## CLI

tuiro includes a small demonstration CLI:

```
tuiro
```

Flags:

```
tuiro --ci
tuiro --no-color
tuiro --theme pastel
tuiro --help
tuiro --version
```

Behavior:

- `--ci` disables colors
- `--no-color` also disables colors
- If both are provided, colors remain disabled
- `--theme NAME` selects a built‑in theme
- `--help` lists available themes

Example:

```
tuiro --ci --theme mono
```

## API

### `TUI(ci_mode: bool = False, theme: str | Palette = "default")`

Creates a new terminal UI helper.

### `section(title: str)`

Prints a high‑visibility section header.

### `subsection(title: str)`

Prints a smaller subsection header.

### `banner(title: str)`

Prints a centered banner.

### Status messages

```
info(message: str)
success(message: str)
warning(message: str)
error(message: str)
```

### `command(cmd: str | list[str])`

Prints a command being executed. Lists are joined with spaces.

### `result(label: str, value: str)`

Prints a key‑value result line.

### `table(rows: list[tuple[str, str]])`

Prints a simple two‑column table aligned on the left column.

### `step(title: str)`

Context manager for build steps:

```python
with tui.step("Compiling"):
    run_compiler()
```

## License

MIT License. See (LICENSE)[LICENSE] for details.
