Metadata-Version: 2.3
Name: interactui
Version: 0.1.0rc3
Summary: Interactive TUIs built on curses
Author: Matteo Bouvier
Author-email: Matteo Bouvier <matteo.bouvier@lyon.unicancer.fr>
Requires-Python: >=3.12.3
Description-Content-Type: text/markdown

# InteracTUI

Build interactive TUI applications based on the curses library.

InteracTUI provides a base `App` class that encapsulates a single-column layout made of `View`s.

## Example

A basic TUI might look like :
```python (examples/example.py)
from interactui import App, View
from interactui.view import Select, TextArea
from interactui.view.select import SelectOption


def quit_function(app: App, _view: View) -> None:
    app.print("Bye !")

    app.exit(0)


App().run(
    [
        TextArea("👋 Hi form InteracTUI", style={"border": "rounded", "margin": 5, "padding": (2, 10)}),
        Select("What do you want to do ?", ["Not much", SelectOption("Quit", callback=quit_function)]),
    ]
)
```

## Views

An app's layout is a collection of `View` objects. You can define your own views by inheriting from the `View` class or you can use one of the predefined views :
- `Select` - select an option from multiple options
- `MultiSelect` - select one or more options from a checkbox-style list of options
- `TextArea` - display text
- `TextAreaWithButton` - display text with a dismissal button
- `FloatingView` - base for floating views

### Key-bindings

`App`s and `View`s can define attached key-bindings with associated callback functions executed on the key press.
Key-bindings are defined in the `_key_bindings` class variable.

```python
class App:  # or View
    _key_bindings: ClassVar[list[KeyBinding]] = [...]

    ...
```

A key-bindings is made of :
- a `Key`
- a description
- a callback function `(App | View, Key, App) -> None`

An `App` comes with the following base key-bindings:
- `<Ctrl-d>` - Exit the app
- `<Ctrl-k>` - show key bindings


Predefined `View`s come with their key-bindings but you can also define your own. When inheriting form the `View` class, add your key-bindings in the `_key_bindings` class variable.

## Style

The appearance of `View`s can be customized with the `style` parameter, taking a `Style` dictionary with the following format:
```python
class Style(TypedDict, total=False):
    # all sides | (top & bottom, left & right) | (top, right, bottom, left)
    margin: SidesAmount

    # all sides | (top & bottom, left & right) | (top, right, bottom, left)
    padding: SidesAmount

    # border:
    # - "none": no border
    # - "rounded": rounded corners
    # - "squared": squared corners
    border: Corner

    # foreground font color
    color: Color

    # one or more font modifiers:
    # - "bold"
    # - "italic"
    # - "dim"
    # - "blink"
    # - "reverse"
    font_modifier: Modifier | tuple[Modifier, ...]

    # background font color
    background: Color

    # number lines | "x%" where x is in (0, 1), percentage of total height
    height: int | str

    # number columns | "x%" where x is in (0, 1), percentage of total width
    width: int | str
```

# Installation

`pip install interactui` or `uv add interactui`
