114 lines
3.3 KiB
Markdown
114 lines
3.3 KiB
Markdown
# Canvas
|
||
|
||
Canvas is a Rust library for building form‑based and textarea‑driven terminal user interfaces.
|
||
It provides the core logic for text editing, validation, suggestions, and cursor management.
|
||
|
||
The library does not enforce a specific terminal UI framework:
|
||
- Core functionality works without any rendering backend.
|
||
- Terminal rendering support is available through the `gui` feature, which enables integration with `ratatui` and `crossterm`.
|
||
- Applications may also integrate Canvas with other backends by handling input and rendering independently.
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
Canvas is designed for applications that require structured text input in a terminal environment.
|
||
It provides:
|
||
|
||
- Text editing modes (Vim‑like or normal)
|
||
- Validation (regex, masks, limits, formatting)
|
||
- Suggestions (asynchronous dropdowns)
|
||
- Computed fields (derived values)
|
||
- Textarea widget with cursor management
|
||
- Syntax highlighting (via syntect)
|
||
- Extensible architecture for custom behaviors
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
Add the dependency to your `Cargo.toml`:
|
||
|
||
```toml
|
||
[dependencies]
|
||
canvas = { version = "0.x", features = ["gui", "cursor-style", "textarea", "validation"] }
|
||
```
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
The library is feature‑gated. Enable only what you need:
|
||
|
||
- `gui` – terminal rendering support (ratatui + crossterm)
|
||
- `cursor-style` – styled cursor support
|
||
- `validation` – regex, masks, limits, formatting
|
||
- `suggestions` – asynchronous suggestions dropdowns
|
||
- `computed` – derived fields
|
||
- `textarea` – textarea widget
|
||
- `syntect` – syntax highlighting support
|
||
- `textmode-vim` – Vim‑like editing (default)
|
||
- `textmode-normal` – normal editing mode
|
||
|
||
**Note:** `textmode-vim` and `textmode-normal` are mutually exclusive. Enable exactly one.
|
||
|
||
The default feature set is `["textmode-vim"]`.
|
||
|
||
---
|
||
|
||
## Running Examples
|
||
|
||
The repository includes several examples. Each requires specific feature flags.
|
||
Use the following commands to run them:
|
||
|
||
```bash
|
||
# Textarea with Vim mode
|
||
cargo run --example textarea_vim --features "gui cursor-style textarea textmode-vim"
|
||
|
||
# Textarea with Normal mode
|
||
cargo run --example textarea_normal --features "gui cursor-style textarea textmode-normal"
|
||
|
||
# Textarea with syntax highlighting
|
||
cargo run --example textarea_syntax --features "gui cursor-style textarea syntect textmode-normal"
|
||
|
||
# Validation examples
|
||
cargo run --example validation_1 --features "gui validation cursor-style"
|
||
cargo run --example validation_2 --features "gui validation cursor-style"
|
||
cargo run --example validation_3 --features "gui validation cursor-style"
|
||
cargo run --example validation_4 --features "gui validation cursor-style"
|
||
cargo run --example validation_5 --features "gui validation cursor-style"
|
||
|
||
# Suggestions
|
||
cargo run --example suggestions --features "suggestions gui cursor-style"
|
||
cargo run --example suggestions2 --features "suggestions gui cursor-style"
|
||
|
||
# Cursor auto movement
|
||
cargo run --example canvas_cursor_auto --features "gui cursor-style"
|
||
|
||
# Computed fields
|
||
cargo run --example computed_fields --features "gui computed"
|
||
```
|
||
|
||
---
|
||
|
||
## Documentation
|
||
|
||
- API documentation: `cargo doc --open`
|
||
- Migration notes: `CANVAS_MIGRATION.md`
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
Licensed under either of:
|
||
- Apache License, Version 2.0
|
||
- MIT License
|
||
|
||
at your option.
|
||
|
||
---
|
||
|
||
## Contributing
|
||
|
||
Contributions are welcome. Please follow the existing code structure and feature‑gating conventions.
|