Metadata-Version: 2.4
Name: casca
Version: 1.0.0
Summary: Native Python CLI UI library with CSS-like styling
Author-email: Abdallah zain <abdallahbasemzain@outlook.com>
License: MIT
Keywords: tui,cli,terminal,ui,css,python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: chatbot
Requires-Dist: groq>=0.20.0; extra == "chatbot"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: pymdown-extensions>=10.8.0; extra == "docs"
Dynamic: license-file

# Casca

Casca is a lightweight, native Python TUI library with a DOM-like widget tree and CSS-style theming.

## Features

- Zero core dependencies (standard library runtime)
- Declarative widgets (`Container`, `Label`, `Input`, `TextArea`, `Select`, `RadioGroup`, `ListView`, `ProgressBar`, `Spinner`, `DataGrid`, `Button`, `Card`, `Header`, `ScrollView`, `Tabs`)
- Data visualization widgets (`BarChart`, `Sparkline`, `Gauge`, `Heatmap`, `ScatterPlot`)
- CSS-like style parsing and cascade
- Named themes with tokenized CSS variables (`var(primary)`, `var(surface)`, ...)
- Border styles and color controls (`ascii`, `solid`, `rounded`, `double`, `thick`, `dashed`, `border-color`)
- Auto-percentage sizing and flex layouts (Row / Column)
- Keyboard and mouse event handling in raw terminal mode
- App state helpers (`invalidate()`, `request_render()`, `set_state(...)`) and debug error overlay
- Built-in feedback helpers (`show_toast`, `set_banner`, `clear_banner`)
- Developer tooling (`casca-doctor`, debug layout overlay, style warnings)
- `Casca Studio` inspect overlay (focused path, computed style, box model) via `F2`
- Plugin architecture for community widgets (`casca.widgets` entry points)
- Optional unidirectional store (`create_store`, `combine_reducers`) for larger apps
- Benchmark suite for render/layout performance tracking
- Real examples including login screen, dashboard, tabs, and Groq chatbot

## Quick Start

```python
from casca import Container, Label, run_app

CSS = """
#root {
    padding: 1;
    border: ascii;
}
"""



ui_tree = Container(
    Label("Hello from Casca"),
    id="root",
)

if __name__ == "__main__":
    run_app(ui_tree, css=CSS)
```

Or load styles from a file:

```python
from casca import Container, Label, run_app

ui_tree = Container(
    Label("Styled from file.css"),
    id="root",
)

if __name__ == "__main__":
    run_app(ui_tree, css_path="examples/styles/02_forms.css")
```

## Run Use Cases

```bash
PYTHONPATH=. python3 use_cases/login_screen.py
PYTHONPATH=. python3 use_cases/dashboard.py
PYTHONPATH=. python3 use_cases/chatbot.py
```

`use_cases.chatbot` requires `groq` and a `GROQ_API_KEY`.

## Casca Studio Mode

Enable studio mode in any app subclass to inspect focus path and layout metadata live:

```python
from casca import App

class MyApp(App):
    studio_mode = True
```

Use `F2` to toggle the studio overlay at runtime.

## Plugin Architecture

Community widgets can register through a stable API:

```python
from casca import register_widget

class JsonViewer:
    pass

register_widget("casca-jsonviewer", JsonViewer)
```

Or expose entry points under `casca.widgets` from external packages.

Plugins can declare `CASCA_API_VERSION = "1.0"`; Casca validates major-version compatibility during registration/discovery.

## State/Store Pattern

Casca includes an optional Redux-like store for predictable state updates:

```python
from casca import App, create_store

def reducer(state, action):
    state = dict(state or {})
    if action["type"] == "inc":
        state["count"] = state.get("count", 0) + 1
    return state

class CounterApp(App):
    def __init__(self):
        super().__init__()
        self.set_store(create_store(reducer, {"count": 0}))
```

## Project Layout

- `casca/`: core library
- `use_cases/`: real apps built with Casca
- `examples/`: smaller demos
- `docs/`: MkDocs content

## License

MIT
