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:

[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:

# 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.

3.3 KiB Raw Blame History Unescape Escape