Metadata-Version: 2.4
Name: develia-tuitools
Version: 0.1.3
Summary: Console presentation layer built on rich.
Author-email: Antonio Gil Espinosa <antonio.gil.espinosa@gmail.com>
Requires-Python: >=3.8
Requires-Dist: rich<14,>=13
Description-Content-Type: text/markdown

# develia-tuitools

Reusable console presentation layer built on [rich](https://github.com/Textualize/rich).

It provides step/section headings, marked status messages (`✓`, `!`, `✗`),
key/value panels, progress bars (download, percentage, and indeterminate wait),
selection menus, and shared color themes.

## Usage

```python
from develia import tuitools as ui

ui.step(1, 3, "Finding source image")
ui.info("Latest snapshot...")
ui.detail("Searching in /var/lib/snapshots")
ui.warning("Snapshot is older than 24 hours")
ui.success("Snapshot found and ready")
ui.error("Could not read boot sector")

with ui.download_progress("Downloading /dev/sda", total=1024) as task:
    task.advance(1024)

ui.panel("DONE", [("File", "backup.img"), ("Size", "1.0 KiB")])
```

## Themes

```python
from develia import tuitools as ui

ui.use_theme("default")
ui.use_theme("basic")
ui.use_theme("cold")
ui.use_theme("hot")

ui.theme.input = "blue"
```

Built-in themes are exposed as `ui.DEFAULT`, `ui.BASIC`, `ui.COLD`, `ui.HOT`,
and `ui.THEMES`.

## UI language

Built-in UI strings are translated to English or Spanish. The language is
detected from the system locale when the package is imported, with English as
the fallback.

```python
from develia import tuitools as ui

ui.set_language("es_ES.UTF-8")  # Global override; normalized to "es".

with ui.language("en"):
    ui.press_to_continue()

# The previous language is restored here.
```

## Selection menus

```python
servers = [("web-1", 1), ("db-1", 2)]

chosen = ui.select(servers, "Choose a server", label=lambda s: s[0])
many = ui.select(range(1, 4), "Choose steps", multiple=True, defaults=[0])
```

Use arrows (or `j`/`k`) to move, `Enter` to confirm, `Space` to toggle
multi-selection, and `Esc`/`Ctrl+C` to raise `ui.Cancelled`. Without an
interactive terminal, a numbered list is read through `input()`. If stdin is
also unavailable, the default option is returned so cron scripts never block.

Use `ui.press_to_continue()` to pause an interactive flow until the user
presses a key.

## Terminal detection

- Without a terminal (cron, pipes), rich degrades by itself: no ANSI codes and
  no redraws.
- Some environments support color even when they do not report a terminal
  (PyCharm run console, CI). Rich output is forced when `FORCE_COLOR` or
  `PYCHARM_HOSTED` exists. `NO_COLOR` disables it.

## Compatibility

Python 3.8+ (`rich>=13,<14`, the latest branch that supports Python 3.8).

Menus use standard-library `termios`/`tty` on Unix. Textual is intentionally not
included because current versions require Python 3.9+ and take over the full
screen, which does not fit a line-oriented CLI flow that must also work in cron.
