Metadata-Version: 2.4
Name: casca
Version: 1.0.1
Summary: Native Python CLI UI library with CSS-like styling
Author-email: Abdallah zain <abdallahbasemzain@outlook.com>
License: MIT
Project-URL: Homepage, https://abdallah4z.github.io/Casca/
Project-URL: Documentation, https://abdallah4z.github.io/Casca/docs.html
Project-URL: Repository, https://github.com/abdallah4z/Casca
Project-URL: Issues, https://github.com/abdallah4z/Casca/issues
Project-URL: Changelog, https://github.com/abdallah4z/Casca/releases
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: hotreload
Requires-Dist: watchdog>=4.0.0; extra == "hotreload"
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"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: watchdog>=4.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: casca[chatbot,docs,hotreload]; extra == "all"
Dynamic: license-file

# Casca

**Casca** is a lightweight, native Python TUI (Terminal User Interface) framework with a DOM-like widget tree, CSS-style theming, and modern features.

![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Test Coverage](https://img.shields.io/badge/coverage-75%25-yellowgreen.svg)

---

## ✨ Features

### Core Features
- **Zero core dependencies** (standard library runtime only)
- **DOM-like widget tree** with declarative syntax
- **CSS-style theming** with cascade and specificity
- **Flexbox layouts** (row/column) with percentage sizing
- **Named themes** with CSS variables (`var(--primary)`, `var(--surface)`, ...)
- **Full type hints** with strict mypy configuration
- **Comprehensive logging** with configurable levels

### Widgets (20+)
**Basic:** `Container`, `Label`, `Button`, `Card`, `Header`, `ScrollView`
**Forms:** `Input`, `TextArea`, `Select`, `RadioGroup`, `Checkbox`
**Data:** `ListView`, `DataGrid`, `Table`, `TreeView`
**Visual:** `ProgressBar`, `Spinner`, `Tabs`, `Slider`, `Menu`
**Layout:** `Grid`, `VirtualScrollView` (for 10,000+ items)

### Data Visualization
- `BarChart`, `Sparkline`, `Gauge`, `Heatmap`, `ScatterPlot`

### Advanced Features
- **Virtual Scrolling** - Render 10,000+ items with O(1) performance
- **Grid Layout** - CSS Grid-like 2D layout system
- **Accessibility** - Focus management, keyboard navigation, screen reader support
- **Hot Reload** - Automatic UI refresh on CSS changes (optional watchdog)
- **Image Widget** - Terminal images with multiple render modes
- **Screenshot Capture** - Export `.ansi`, `.txt`, `.svg` screenshots
- **Studio Mode** - Live inspection (focus path, computed style, box model)
- **Plugin Architecture** - Community widgets via entry points
- **Redux-like Store** - Unidirectional state management

### Developer Experience
- **casca-doctor** - Diagnostic CLI tool
- **Debug overlay** - Layout visualization, style warnings
- **Type hints** - 100% type coverage on core modules
- **Tested** - 450+ tests with comprehensive coverage
- **CI/CD** - GitHub Actions with test matrix
- **Documentation** - API reference, troubleshooting, contributing guides

---

## 🚀 Quick Start

### Installation

```bash
# Basic installation
pip install casca

# With hot reload support
pip install casca[hotreload]

# All features
pip install casca[all]
```

### Hello World

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

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

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

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

### With Logging

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

# Enable debug logging
setup_logging(level=logging.DEBUG)

ui_tree = Container(Label("Hello with logging"), id="root")
run_app(ui_tree)
```

### Load Styles from 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="styles.css")
```

---

## 📚 Examples

### Run Use Cases

```bash
# Nomeda CLI - Modern AI Chatbot
PYTHONPATH=. python3 use_cases/nomeda_cli.py

# Login screen demo
PYTHONPATH=. python3 use_cases/login_screen.py

# Dashboard with widgets
PYTHONPATH=. python3 use_cases/dashboard.py

# File selector
PYTHONPATH=. python3 use_cases/file_selector.py

# Terminal browser
PYTHONPATH=. python3 use_cases/cli_browser.py
```

### Widget Examples

```bash
# Menu widget
PYTHONPATH=. python3 examples/30_menu_example.py

# Slider widget
PYTHONPATH=. python3 examples/31_slider_example.py

# Virtual scrolling (10,000 items)
PYTHONPATH=. python3 examples/32_virtual_scroll_example.py

# Image rendering
PYTHONPATH=. python3 examples/25_image.py
```

---

## 🎨 Styling

### CSS Variables

```css
:root {
    --primary: #007bff;
    --surface: #1a1a1a;
    --border: #333;
}

#root {
    background: var(--surface);
    border-color: var(--primary);
}
```

### Border Styles

```css
#widget {
    border: solid;        /* or: ascii, rounded, double, thick, dashed */
    border-color: cyan;
}
```

### Flexbox Layouts

```css
#container {
    flex-direction: row;   /* or: column */
    gap: 1;
}
```

### Grid Layout

```python
from casca.components.widgets.grid import Grid

grid = Grid(
    columns="1fr 1fr 1fr",
    rows="auto auto",
    gap=1
)
grid.add(Label("Header"), grid_column="1 / span 3", grid_row="1")
grid.add(Label("Sidebar"), grid_column="1", grid_row="2")
grid.add(Label("Content"), grid_column="2 / span 2", grid_row="2")
```

---

## 🔍 Debugging

### Enable Debug Mode

```python
from casca import App

class MyApp(App):
    debug = True          # Detailed error messages
    debug_layout = True   # Layout visualization
    studio_mode = True    # Live inspection
```

### Enable Logging

```python
from casca import setup_logging
import logging

# Debug to stderr
setup_logging(level=logging.DEBUG)

# Or log to file
setup_logging(level=logging.INFO, log_file="casca.log")
```

### Studio Mode

Press **F2** in any running Casca app to toggle the studio overlay:
- Focused widget path
- Computed style display
- Box model visualization
- Layout debugging

### Run Diagnostic Tool

```bash
casca-doctor
casca-doctor --json
```

---

## 🏪 State Management

Casca includes an optional Redux-like store:

```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}))

    def build_ui(self):
        state = self.get_state() or {}
        count = state.get("count", 0)
        return Container(
            Label(f"Count: {count}"),
            id="root"
        )
```

### Combine Reducers

```python
from casca import combine_reducers

root_reducer = combine_reducers({
    "counter": counter_reducer,
    "user": user_reducer,
    "posts": posts_reducer
})
```

---

## 🔥 Hot Reload (Development)

Enable automatic UI refresh on CSS changes:

```python
from casca import App, run_app
from casca.core.hot_reload import enable_hot_reload

class MyApp(App):
    css_path = "styles.css"

app = MyApp()

# Enable hot reload (watch CSS files)
# Watchdog optional - falls back to polling
reloader = enable_hot_reload(app, ["styles/"])

run_app(app)
```

---

## ♿ Accessibility

### Focus Management

```python
from casca.core.accessibility import get_accessibility

accessibility = get_accessibility()

# Set tab order
accessibility.focus_manager.set_focus_order(["input1", "input2", "submit"])

# Enable focus trap for modals
accessibility.focus_manager.enable_focus_trap(modal_dialog)

# Screen reader announcements
accessibility.announce("Form submitted successfully")
```

### Keyboard Shortcuts

```python
accessibility.register_keybinding("Ctrl+S", save_handler)
accessibility.register_keybinding("F1", help_handler)
```

---

## 📊 Testing

### Run Tests

```bash
# All tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=casca --cov-report=term-missing

# Specific test file
pytest tests/test_app_comprehensive.py -v

# Fast tests only
pytest tests/ -v -m "not slow"
```

### Write Tests

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

def test_container_layout():
    container = Container(Label("Test"), id="root")
    container.resolve_styles({})
    w, h = container.calculate_layout(80, 24)

    assert w > 0
    assert h > 0
```

---

## 📁 Project Layout

```
casca/
├── casca/                     # Core library
│   ├── core/                  # App, events, terminal, store, logging
│   ├── dom/                   # Widget base class (DOM node)
│   ├── components/            # Widgets (organized by category)
│   ├── style/                 # CSS parsing and validation
│   └── plugins/               # Plugin registration
├── tests/                     # Test suite (450+ tests)
├── examples/                  # Small demos
├── use_cases/                 # Real applications
├── docs/                      # Documentation
│   ├── API_REFERENCE.md       # Complete API docs
│   ├── TROUBLESHOOTING.md     # Common issues
│   └── CONTRIBUTING.md        # Contribution guide
└── benchmarks/                # Performance benchmarks
```

---

## 🛠️ Development

### Install Development Dependencies

```bash
pip install -e ".[dev]"
```

### Run Linting

```bash
ruff check casca/ tests/
ruff format casca/ tests/ --check
```

### Run Type Checking

```bash
mypy casca/ --ignore-missing-imports
```

### Run All Tests

```bash
pytest tests/ -v --tb=short
```

### Makefile Commands

```bash
# Serve website locally
make serve

# Deploy website to GitHub Pages
make deploy-website

# Run all checks
make all
```

### Website Deployment

The Casca website is deployed to GitHub Pages at **https://abdallah4z.github.io/Casca/**

**Automatic Deployment:**
- Push to `main` branch → Auto-deploys via GitHub Actions
- Visit the site to see latest documentation

**Manual Deployment:**
```bash
# Using the deployment script
./scripts/deploy-website.sh

# Or using Make
make deploy-website
```

**Serve Locally:**
```bash
# Using Make
make serve

# Or manually
cd retro_website
python3 -m http.server 8000
```

See `retro_website/README.md` for detailed deployment instructions.

### Build Documentation

```bash
pip install -e ".[docs]"
mkdocs serve
```

---

## 📖 Documentation

- **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
- **[Contributing](docs/CONTRIBUTING.md)** - How to contribute
- **[Architecture](docs/ARCHITECTURE.md)** - System design and internals
- **[Getting Started](docs/getting-started.md)** - Installation and basics
- **[Components](docs/components.md)** - Widget reference
- **[Style Reference](docs/style-reference.md)** - CSS properties

---

## 🔧 Configuration

### mypy

Strict type checking enabled:

```ini
# mypy.ini
[mypy]
python_version = 3.10
disallow_untyped_defs = True
check_untyped_defs = True
```

### Ruff

Code formatting and linting:

```toml
# pyproject.toml
[tool.ruff]
target-version = "py310"
line-length = 100
```

### Coverage

```toml
# pyproject.toml
[tool.coverage.report]
fail_under = 60
show_missing = true
```

---

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Guidelines

- Add tests for new features
- Maintain type hints (100% on core modules)
- Follow existing code style (ruff format)
- Update documentation
- Read [CONTRIBUTING.md](docs/CONTRIBUTING.md)

---

## 📄 License

MIT License - See [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

Inspired by:
- [Textual](https://textual.textualize.io/) - Python TUI framework
- [Blessed](https://blessed.readthedocs.io/) - Terminal library
- CSS Flexbox and Grid specifications

---

## 📈 Roadmap

### v1.1.0 (Next)
- [ ] Improved CSS pseudo-selector support
- [ ] Better Windows terminal support
- [ ] Performance optimizations
- [ ] More widget themes

### Future
- [ ] Async/await support
- [ ] Plugin marketplace
- [ ] Visual designer tool
- [ ] Mobile terminal support

---

**Built with ❤️ in Python**

Need help? Check out:
- [API Reference](docs/API_REFERENCE.md)
- [Troubleshooting Guide](docs/TROUBLESHOOTING.md)
- [GitHub Issues](https://github.com/yourusername/casca/issues)
