Metadata-Version: 2.4
Name: neoterm
Version: 1.0.2
Summary: Rich terminal UI framework — mouse, shaders, flexbox, Unicode
License: MIT
Keywords: terminal,tui,ui,mouse,unicode,shader,animation
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: images
Requires-Dist: Pillow>=9.0; extra == "images"
Dynamic: license-file
Dynamic: requires-python

# NeoTerm 🚀

A **rich terminal UI framework** written in pure Python.  
Cross-platform: Windows, macOS, Linux.

## Features

| Feature | Details |
|---|---|
| 🎨 **GPU-style shaders** | `rainbow`, `matrix`, `fire`, `wave`, `scanline` — per-cell, real-time |
| 🖱️ **Full mouse support** | Click, hover, scroll, drag — SGR protocol |
| 🌍 **Unicode + emoji** | Full CJK, emoji, box-drawing, braille, wide chars |
| 📐 **Flexbox layout** | `row`/`column`, `flex_grow`, `gap`, `padding`, `align`, `justify` |
| 🎬 **Animation engine** | Keyframe timelines, 12 easing functions, per-property |
| 🖼️ **Image display** | Half-block Unicode rendering (requires `Pillow`) |
| 🔲 **Widget system** | Label, Button, TextInput, ProgressBar, Table, ScrollView, Spinner, Image |
| ⚡ **Diff renderer** | Only changed cells are written — very fast |

---

## Quick Start

```bash
# first install the library
neoterm-demo

```

Optional (for image display):
```bash
pip install Pillow
```

---

## Usage

```python
import neoterm as nt
from neoterm.layout import FlexStyle

app = nt.App(fps=30)

root = nt.Container(
    direction="column",
    gap=1,
    padding=(1, 2, 1, 2),
    border=True,
    title="My App"
)

root.add(nt.Label("Hello, 🌍!", bold=True, align="center"))
root.add(nt.Divider())
root.add(nt.Button("Quit", on_click=app.quit, style=FlexStyle(height=3)))

app.mount(root)
app.run()
```

---

## Widgets

### Label
```python
nt.Label("Text 🎉", bold=True, italic=False, fg=(255,200,0), align="center")
```

### Button
```python
nt.Button("Click me", on_click=lambda: print("clicked!"))
```

### TextInput
```python
inp = nt.TextInput(placeholder="Search...", on_submit=lambda v: print(v))
```

### ProgressBar
```python
bar = nt.ProgressBar(value=42, max_val=100)
bar.value = 75  # update anytime
```

### Table
```python
table = nt.Table(
    columns=["Name", "Age", "City"],
    rows=[["Alice", 30, "Istanbul"], ["Bob", 25, "Ankara"]],
    on_select=lambda i, row: print(row),
    sortable=True
)
```

### ImageWidget
```python
img = nt.ImageWidget(path="photo.jpg", width_cells=40, height_cells=20)
```

### Spinner
```python
nt.Spinner("Loading...", fg=(100, 200, 100))
```

---

## Shaders

Apply a real-time shader to any widget:

```python
container.set_shader("rainbow")  # or: wave, matrix, fire, scanline, none
```

Available shaders: `rainbow`, `wave`, `matrix`, `fire`, `scanline`, `none`

---

## Layout (Flexbox)

```python
from neoterm.layout import FlexStyle

# Fixed size
widget = nt.Label("x", style=FlexStyle(width=20, height=3))

# Flexible — fills remaining space
widget = nt.Label("x", style=FlexStyle(flex_grow=1))

# Row of equal buttons
row = nt.Container(direction="row", gap=1)
row.add(nt.Button("A", style=FlexStyle(flex_grow=1)))
row.add(nt.Button("B", style=FlexStyle(flex_grow=1)))
```

---

## Animations

```python
label = nt.Label("Fade in!")
label.animate("opacity", from_=0.0, to=1.0, duration=0.5, easing="ease_out_cubic")
```

Available easings: `linear`, `ease_in`, `ease_out`, `ease_in_out`,
`ease_in_cubic`, `ease_out_cubic`, `ease_in_out_cubic`,
`ease_in_back`, `ease_out_back`, `bounce`, `elastic_in`, `elastic_out`

---

## Keyboard Shortcuts

| Key | Action |
|---|---|
| `Tab` | Next focusable widget |
| `Shift+Tab` | Previous focusable widget |
| `Ctrl+Q` / `Ctrl+C` | Quit |
| `↑↓` (in Table) | Navigate rows |
| `Enter` (in Table) | Select row |
| `←→` | Navigate / edit |

---

## Project Structure

```
neoterm/
├── neoterm/
│   ├── __init__.py      # public API
│   ├── platform.py      # Windows/Unix terminal abstraction
│   ├── canvas.py        # double-buffered cell renderer
│   ├── events.py        # keyboard + mouse parsing
│   ├── layout.py        # flexbox layout engine
│   ├── animation.py     # keyframe timelines + cell shaders
│   ├── widgets.py       # all widgets
│   └── app.py           # event loop
└── examples/
    ├── hello.py         # minimal example
    ├── demo.py          # full feature demo
    └── shader_gallery.py
```

---

## Requirements

- Python 3.8+
- No external dependencies (pure stdlib)
- Optional: `Pillow` for image display

## Platform Notes

**Windows**: Requires Windows 10 1903+ for VT/ANSI support (automatic).  
**macOS/Linux**: Works with any modern terminal (iTerm2, Kitty, Alacritty, GNOME Terminal, etc.).
