Metadata-Version: 2.4
Name: lazy-cuh
Version: 0.1.0a4
Summary: Reusable lazygit-style Textual TUI framework primitives.
Author-email: "Jan T. Müller" <mail@jantmueller.com>
License-Expression: MIT
Project-URL: homepage, https://github.com/janthmueller/lazy-cuh
Project-URL: documentation, https://janthmueller.github.io/lazy-cuh/
Project-URL: source, https://github.com/janthmueller/lazy-cuh
Project-URL: tracker, https://github.com/janthmueller/lazy-cuh/issues
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich<15,>=13
Requires-Dist: textual>=0.86
Provides-Extra: dev
Requires-Dist: pyright>=1.1; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Provides-Extra: docs
Provides-Extra: release
Requires-Dist: build>=1; extra == "release"
Requires-Dist: python-semantic-release<11,>=10; extra == "release"
Requires-Dist: twine>=5; extra == "release"
Dynamic: license-file

# lazy-cuh

`lazy-cuh` is an experimental Python framework for building lazygit-style
terminal user interfaces on top of [Textual](https://textual.textualize.io/).

It provides reusable building blocks for terminal apps that need pane-based
navigation, compact key hints, modal flows, and list/tree content that behaves
consistently.

## Status

Pre-alpha. The package is useful for experimentation and early dogfooding, but
APIs are expected to change before a stable release.

## Features

- bordered panels with numbered titles and tabs
- vim-like item navigation and optional line numbers
- reusable list, tree, text, and option-style views
- contextual keybars and expandable help hints
- confirm, input, info, and notice models
- action, command, and keybinding primitives
- clear separation between app state, rendering, navigation, viewport, and
  Textual widget adapters

## Installation

```bash
pip install lazy-cuh
```

Pre-release versions may need:

```bash
pip install --pre lazy-cuh
```

## Quick Example

```python
from rich.text import Text

import lazy_cuh as lc

items = (
    lc.core.NavigableItem(id="panels", label=Text("Composable panels and tabs")),
    lc.core.NavigableItem(id="navigation", label=Text("Vim-style item navigation")),
    lc.core.NavigableItem(id="keybars", label=Text("Context-aware keybars")),
)

view = lc.view.ListViewModel(
    items=items,
    cursor_index=1,
    spec=lc.view.ListViewSpec(
        width=60,
        line_numbers=lc.layout.LineNumberSpec(lc.layout.LineNumberMode.RELATIVE),
    ),
)

for line in view.rendered_lines():
    print(line.plain)
```

## Examples

After installing from source, run the interactive demo:

```bash
uv run lazy-cuh-demo
```

Focused examples are also available:

```bash
uv run lazy-cuh-example-app-shell
uv run lazy-cuh-example-text-wrap
uv run lazy-cuh-example-help-modal
uv run lazy-cuh-example-help-keybar
uv run lazy-cuh-example-options
```

## Documentation

The documentation lives in `docs/` and is built with Astro Starlight. Start
with the quick start for a minimal view, then use the app-structure guide for
the recommended full-app composition path. The docs also cover lists, trees,
panels, keybars, modals, and Textual adapters.

## Development

For local development:

```bash
uv sync --extra dev --extra release
uv run pytest
uv run pyright
uv run ruff check .
```

Nix users can enter the packaged development shell with:

```bash
nix develop
```
