mirror of
https://github.com/ratatui/ratatui.git
synced 2025-09-26 20:40:44 +00:00
docs: add crate organization sections to workspace (#1946)
Adds summary-level crate organization documentation to all crates explaining the modular workspace structure and when to use each crate. Links to ARCHITECTURE.md for detailed information.
This commit is contained in:
Josh McKinney
GitHub
parent
cfb65e64ba
commit
5620e06b1a
203
ARCHITECTURE.md
Normal file
203
ARCHITECTURE.md
Normal file
@ -0,0 +1,203 @@
|
||||
# Ratatui Architecture
|
||||
|
||||
This document provides a comprehensive overview of Ratatui's architecture and crate
|
||||
organization, introduced in version 0.30.0.
|
||||
|
||||
## Overview
|
||||
|
||||
Starting with Ratatui 0.30.0, the project was reorganized from a single monolithic crate into
|
||||
a modular workspace consisting of multiple specialized crates. This architectural decision was
|
||||
made to improve modularity, reduce compilation times, enable more flexible dependency
|
||||
management, and provide better API stability for third-party widget libraries.
|
||||
|
||||
## Crate Organization
|
||||
|
||||
The Ratatui project is now organized as a Cargo workspace containing the following crates:
|
||||
|
||||
### Core Crates
|
||||
|
||||
#### `ratatui` (Main Crate)
|
||||
|
||||
- **Purpose**: The main entry point that most applications should use
|
||||
- **Contents**: Re-exports everything from other crates for convenience, plus experimental features
|
||||
- **Target Users**: Application developers building terminal UIs
|
||||
- **Key Features**:
|
||||
- Complete widget ecosystem
|
||||
- Backend implementations
|
||||
- Layout system
|
||||
- Terminal management
|
||||
- Experimental `WidgetRef` and `StatefulWidgetRef` traits
|
||||
|
||||
#### `ratatui-core`
|
||||
|
||||
- **Purpose**: Foundational types and traits for the Ratatui ecosystem
|
||||
- **Contents**: Core widget traits, text types, buffer, layout, style, and symbols
|
||||
- **Target Users**: Widget library authors, minimalist projects
|
||||
- **Key Features**:
|
||||
- `Widget` and `StatefulWidget` traits
|
||||
- Text rendering (`Text`, `Line`, `Span`)
|
||||
- Buffer management
|
||||
- Layout system
|
||||
- Style and color definitions
|
||||
- Symbol collections
|
||||
|
||||
#### `ratatui-widgets`
|
||||
|
||||
- **Purpose**: Built-in widget implementations
|
||||
- **Contents**: All standard widgets like `Block`, `Paragraph`, `List`, `Chart`, etc.
|
||||
- **Target Users**: Applications needing standard widgets, widget library authors
|
||||
- **Key Features**:
|
||||
- Complete set of built-in widgets
|
||||
- Optimized implementations
|
||||
- Comprehensive documentation and examples
|
||||
|
||||
### Backend Crates
|
||||
|
||||
#### `ratatui-crossterm`
|
||||
|
||||
- **Purpose**: Crossterm backend implementation
|
||||
- **Contents**: Cross-platform terminal backend using the `crossterm` crate
|
||||
- **Target Users**: Applications targeting multiple platforms
|
||||
|
||||
#### `ratatui-termion`
|
||||
|
||||
- **Purpose**: Termion backend implementation
|
||||
- **Contents**: Unix-specific terminal backend using the `termion` crate
|
||||
- **Target Users**: Unix-specific applications requiring low-level control
|
||||
|
||||
#### `ratatui-termwiz`
|
||||
|
||||
- **Purpose**: Termwiz backend implementation
|
||||
- **Contents**: Terminal backend using the `termwiz` crate
|
||||
- **Target Users**: Applications needing advanced terminal features
|
||||
|
||||
### Utility Crates
|
||||
|
||||
#### `ratatui-macros`
|
||||
|
||||
- **Purpose**: Declarative macros for common patterns and boilerplate reduction
|
||||
- **Contents**: Macros for common patterns and boilerplate reduction
|
||||
- **Target Users**: Applications and libraries wanting macro support
|
||||
|
||||
## Dependency Relationships
|
||||
|
||||
```text
|
||||
ratatui
|
||||
├── ratatui-core
|
||||
├── ratatui-widgets → ratatui-core
|
||||
├── ratatui-crossterm → ratatui-core
|
||||
├── ratatui-termion → ratatui-core
|
||||
├── ratatui-termwiz → ratatui-core
|
||||
└── ratatui-macros
|
||||
```
|
||||
|
||||
### Key Dependencies
|
||||
|
||||
- **ratatui-core**: Foundation for all other crates
|
||||
- **ratatui-widgets**: Depends on `ratatui-core` for widget traits and types
|
||||
- **Backend crates**: Each depends on `ratatui-core` for backend traits and types
|
||||
- **ratatui**: Depends on all other crates and re-exports their public APIs
|
||||
|
||||
## Design Principles
|
||||
|
||||
### Stability and Compatibility
|
||||
|
||||
The modular architecture provides different levels of API stability:
|
||||
|
||||
- **ratatui-core**: Designed for maximum stability to minimize breaking changes for widget
|
||||
libraries
|
||||
- **ratatui-widgets**: Focused on widget implementations with moderate stability requirements
|
||||
- **Backend crates**: Isolated from core changes, allowing backend-specific updates
|
||||
- **ratatui**: Main crate that can evolve more freely while maintaining backward compatibility
|
||||
through re-exports
|
||||
|
||||
### Compilation Performance
|
||||
|
||||
The split architecture enables:
|
||||
|
||||
- **Reduced compilation times**: Widget libraries only need to compile core types
|
||||
- **Parallel compilation**: Different crates can be compiled in parallel
|
||||
- **Selective compilation**: Applications can exclude unused backends or widgets
|
||||
|
||||
### Ecosystem Benefits
|
||||
|
||||
- **Widget Library Authors**: Can depend on stable `ratatui-core` without frequent updates
|
||||
- **Application Developers**: Can use the convenient `ratatui` crate with everything included
|
||||
- **Minimalist Projects**: Can use only `ratatui-core` for lightweight applications
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### For Application Developers
|
||||
|
||||
Most applications should continue using the main `ratatui` crate with minimal changes:
|
||||
|
||||
```rust
|
||||
// No changes needed - everything is re-exported
|
||||
use ratatui::{
|
||||
widgets::{Block, Paragraph},
|
||||
layout::{Layout, Constraint},
|
||||
Terminal,
|
||||
};
|
||||
```
|
||||
|
||||
### For Widget Library Authors
|
||||
|
||||
Consider migrating to `ratatui-core` for better stability:
|
||||
|
||||
```rust
|
||||
// Before (0.29.x and earlier)
|
||||
use ratatui::{
|
||||
widgets::{Widget, StatefulWidget},
|
||||
buffer::Buffer,
|
||||
layout::Rect,
|
||||
};
|
||||
|
||||
// After (0.30.0+)
|
||||
use ratatui_core::{
|
||||
widgets::{Widget, StatefulWidget},
|
||||
buffer::Buffer,
|
||||
layout::Rect,
|
||||
};
|
||||
```
|
||||
|
||||
### Backwards Compatibility
|
||||
|
||||
All existing code using the `ratatui` crate will continue to work unchanged, as the main crate
|
||||
re-exports all public APIs from the specialized crates.
|
||||
|
||||
## Future Considerations
|
||||
|
||||
### Potential Enhancements
|
||||
|
||||
- **Widget-specific crates**: Further split widgets into individual crates for even more
|
||||
granular dependencies
|
||||
- **Plugin system**: Enable dynamic widget loading and third-party widget ecosystems
|
||||
- **Feature flags**: More granular feature flags for compile-time customization
|
||||
|
||||
### Version Synchronization
|
||||
|
||||
Currently, all crates are versioned together for simplicity. Future versions may adopt
|
||||
independent versioning once the API stabilizes further.
|
||||
|
||||
## Related Issues and PRs
|
||||
|
||||
This architecture was developed through extensive discussion and implementation across multiple
|
||||
PRs:
|
||||
|
||||
- [Issue #1388](https://github.com/ratatui/ratatui/issues/1388): Original RFC for modularization
|
||||
- [PR #1459](https://github.com/ratatui/ratatui/pull/1459): Move ratatui crate into workspace
|
||||
folder
|
||||
- [PR #1460](https://github.com/ratatui/ratatui/pull/1460): Move core types to ratatui-core
|
||||
- [PR #1474](https://github.com/ratatui/ratatui/pull/1474): Move widgets into ratatui-widgets
|
||||
crate
|
||||
|
||||
## Contributing
|
||||
|
||||
When contributing to the Ratatui project, please consider:
|
||||
|
||||
- **Core changes**: Submit PRs against `ratatui-core` for fundamental improvements
|
||||
- **Widget changes**: Submit PRs against `ratatui-widgets` for widget-specific improvements
|
||||
- **Backend changes**: Submit PRs against the appropriate backend crate
|
||||
- **Integration changes**: Submit PRs against the main `ratatui` crate
|
||||
|
||||
See the [CONTRIBUTING.md](CONTRIBUTING.md) guide for more details on the contribution process.
|
||||
@ -91,6 +91,14 @@ cd ratatui
|
||||
cargo xtask build
|
||||
```
|
||||
|
||||
### Architecture
|
||||
|
||||
For an understanding of the crate organization and design decisions, see [ARCHITECTURE.md]. This
|
||||
document explains the modular workspace structure introduced in version 0.30.0 and provides
|
||||
guidance on which crate to use for different use cases.
|
||||
|
||||
[ARCHITECTURE.md]: ./ARCHITECTURE.md
|
||||
|
||||
### Tests
|
||||
|
||||
The [test coverage](https://app.codecov.io/gh/ratatui/ratatui) of the crate is reasonably
|
||||
|
||||
@ -73,6 +73,7 @@ fn render(frame: &mut Frame) {
|
||||
- [Ratatui Forum] - a place to ask questions and discuss the library.
|
||||
- [Widget Examples] - a collection of examples that demonstrate how to use the library.
|
||||
- [App Examples] - a collection of more complex examples that demonstrate how to build apps.
|
||||
- [ARCHITECTURE.md] - explains the crate organization and modular workspace structure.
|
||||
- [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
|
||||
- [Breaking Changes] - a list of breaking changes in the library.
|
||||
|
||||
@ -141,6 +142,7 @@ This project is licensed under the [MIT License][License].
|
||||
[Docs]: https://docs.rs/ratatui
|
||||
[Widget Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui-widgets/examples
|
||||
[App Examples]: https://github.com/ratatui/ratatui/tree/main/examples
|
||||
[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
[Changelog]: https://github.com/ratatui/ratatui/blob/main/CHANGELOG.md
|
||||
[git-cliff]: https://git-cliff.org
|
||||
[Conventional Commits]: https://www.conventionalcommits.org
|
||||
|
||||
@ -29,6 +29,32 @@ Add `ratatui-core` to your `Cargo.toml`:
|
||||
cargo add ratatui-core
|
||||
```
|
||||
|
||||
## Crate Organization
|
||||
|
||||
`ratatui-core` is part of the Ratatui workspace that was modularized in version 0.30.0 to
|
||||
improve compilation times, API stability, and dependency management. This crate provides the
|
||||
foundational types and traits that other crates in the workspace depend on.
|
||||
|
||||
**When to use `ratatui-core`:**
|
||||
|
||||
- Building widget libraries that implement [`Widget`] or [`StatefulWidget`]
|
||||
- Creating lightweight applications that don't need built-in widgets
|
||||
- You want minimal dependencies and faster compilation times
|
||||
- You need maximum API stability (core types change less frequently)
|
||||
|
||||
**When to use the main [`ratatui`] crate:**
|
||||
|
||||
- Building applications that use built-in widgets
|
||||
- You want convenience and don't mind slightly longer compilation times
|
||||
- You need backend implementations and terminal management utilities
|
||||
|
||||
For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
|
||||
[`ratatui`]: https://crates.io/crates/ratatui
|
||||
[`Widget`]: widgets::Widget
|
||||
[`StatefulWidget`]: widgets::StatefulWidget
|
||||
[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions from the community! Please see our [CONTRIBUTING](../CONTRIBUTING.md)
|
||||
|
||||
@ -27,6 +27,32 @@
|
||||
//! ```shell
|
||||
//! cargo add ratatui-core
|
||||
//! ```
|
||||
//!
|
||||
//! # Crate Organization
|
||||
//!
|
||||
//! `ratatui-core` is part of the Ratatui workspace that was modularized in version 0.30.0 to
|
||||
//! improve compilation times, API stability, and dependency management. This crate provides the
|
||||
//! foundational types and traits that other crates in the workspace depend on.
|
||||
//!
|
||||
//! **When to use `ratatui-core`:**
|
||||
//!
|
||||
//! - Building widget libraries that implement [`Widget`] or [`StatefulWidget`]
|
||||
//! - Creating lightweight applications that don't need built-in widgets
|
||||
//! - You want minimal dependencies and faster compilation times
|
||||
//! - You need maximum API stability (core types change less frequently)
|
||||
//!
|
||||
//! **When to use the main [`ratatui`] crate:**
|
||||
//!
|
||||
//! - Building applications that use built-in widgets
|
||||
//! - You want convenience and don't mind slightly longer compilation times
|
||||
//! - You need backend implementations and terminal management utilities
|
||||
//!
|
||||
//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
//!
|
||||
//! [`ratatui`]: https://crates.io/crates/ratatui
|
||||
//! [`Widget`]: widgets::Widget
|
||||
//! [`StatefulWidget`]: widgets::StatefulWidget
|
||||
//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
#![cfg_attr(feature = "document-features", doc = "\n## Features")]
|
||||
#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
|
||||
//!
|
||||
|
||||
@ -7,4 +7,25 @@ the [Crossterm] crate to interact with the terminal.
|
||||
|
||||
[Crossterm]: https://crates.io/crates/crossterm
|
||||
|
||||
## Crate Organization
|
||||
|
||||
`ratatui-crossterm` is part of the Ratatui workspace that was modularized in version 0.30.0.
|
||||
This crate provides the [Crossterm] backend implementation for Ratatui.
|
||||
|
||||
**When to use `ratatui-crossterm`:**
|
||||
|
||||
- You need fine-grained control over dependencies
|
||||
- Building a widget library that needs backend functionality
|
||||
- You want to use only the Crossterm backend without other backends
|
||||
|
||||
**When to use the main [`ratatui`] crate:**
|
||||
|
||||
- Building applications (recommended - includes crossterm backend by default)
|
||||
- You want the convenience of having everything available
|
||||
|
||||
For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
|
||||
[`ratatui`]: https://crates.io/crates/ratatui
|
||||
[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
|
||||
<!-- cargo-rdme end -->
|
||||
|
||||
@ -10,6 +10,27 @@
|
||||
//! the [Crossterm] crate to interact with the terminal.
|
||||
//!
|
||||
//! [Crossterm]: https://crates.io/crates/crossterm
|
||||
//!
|
||||
//! # Crate Organization
|
||||
//!
|
||||
//! `ratatui-crossterm` is part of the Ratatui workspace that was modularized in version 0.30.0.
|
||||
//! This crate provides the [Crossterm] backend implementation for Ratatui.
|
||||
//!
|
||||
//! **When to use `ratatui-crossterm`:**
|
||||
//!
|
||||
//! - You need fine-grained control over dependencies
|
||||
//! - Building a widget library that needs backend functionality
|
||||
//! - You want to use only the Crossterm backend without other backends
|
||||
//!
|
||||
//! **When to use the main [`ratatui`] crate:**
|
||||
//!
|
||||
//! - Building applications (recommended - includes crossterm backend by default)
|
||||
//! - You want the convenience of having everything available
|
||||
//!
|
||||
//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
//!
|
||||
//! [`ratatui`]: https://crates.io/crates/ratatui
|
||||
//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
#![cfg_attr(feature = "document-features", doc = "\n## Features")]
|
||||
#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
|
||||
|
||||
|
||||
@ -115,6 +115,28 @@ let table = Table::new(rows, constraints![==20, *=1]);
|
||||
Contributions to `ratatui-macros` are welcome! Whether it's submitting a bug report, a feature
|
||||
request, or a pull request, all forms of contributions are valued and appreciated.
|
||||
|
||||
## Crate Organization
|
||||
|
||||
`ratatui-macros` is part of the Ratatui workspace that was modularized in version 0.30.0.
|
||||
This crate provides declarative macros to reduce boilerplate when working with
|
||||
Ratatui.
|
||||
|
||||
**When to use `ratatui-macros`:**
|
||||
|
||||
- You want to reduce boilerplate when creating styled text, layouts, or tables
|
||||
- You prefer macro-based syntax for creating UI elements
|
||||
- You need compile-time generation of repetitive UI code
|
||||
|
||||
**When to use the main [`ratatui`] crate:**
|
||||
|
||||
- Building applications (recommended - includes macros when the `macros` feature is enabled)
|
||||
- You want the convenience of having everything available
|
||||
|
||||
For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
|
||||
[`ratatui`]: https://crates.io/crates/ratatui
|
||||
[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
|
||||
[Crates.io badge]: https://img.shields.io/crates/v/ratatui-macros?logo=rust&style=flat-square
|
||||
[License badge]: https://img.shields.io/crates/l/ratatui-macros
|
||||
[CI Badge]:
|
||||
|
||||
@ -121,6 +121,28 @@
|
||||
//! Contributions to `ratatui-macros` are welcome! Whether it's submitting a bug report, a feature
|
||||
//! request, or a pull request, all forms of contributions are valued and appreciated.
|
||||
//!
|
||||
//! # Crate Organization
|
||||
//!
|
||||
//! `ratatui-macros` is part of the Ratatui workspace that was modularized in version 0.30.0.
|
||||
//! This crate provides declarative macros to reduce boilerplate when working with
|
||||
//! Ratatui.
|
||||
//!
|
||||
//! **When to use `ratatui-macros`:**
|
||||
//!
|
||||
//! - You want to reduce boilerplate when creating styled text, layouts, or tables
|
||||
//! - You prefer macro-based syntax for creating UI elements
|
||||
//! - You need compile-time generation of repetitive UI code
|
||||
//!
|
||||
//! **When to use the main [`ratatui`] crate:**
|
||||
//!
|
||||
//! - Building applications (recommended - includes macros when the `macros` feature is enabled)
|
||||
//! - You want the convenience of having everything available
|
||||
//!
|
||||
//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
//!
|
||||
//! [`ratatui`]: https://crates.io/crates/ratatui
|
||||
//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
//!
|
||||
//! [Crates.io badge]: https://img.shields.io/crates/v/ratatui-macros?logo=rust&style=flat-square
|
||||
//! [License badge]: https://img.shields.io/crates/l/ratatui-macros
|
||||
//! [CI Badge]:
|
||||
|
||||
@ -8,4 +8,26 @@ the [Termion] crate to interact with the terminal.
|
||||
[`Backend`]: ratatui_core::backend::Backend
|
||||
[Termion]: https://docs.rs/termion
|
||||
|
||||
## Crate Organization
|
||||
|
||||
`ratatui-termion` is part of the Ratatui workspace that was modularized in version 0.30.0.
|
||||
This crate provides the [Termion] backend implementation for Ratatui.
|
||||
|
||||
**When to use `ratatui-termion`:**
|
||||
|
||||
- You need fine-grained control over dependencies
|
||||
- Building a widget library that needs backend functionality
|
||||
- You want to use only the Termion backend without other backends
|
||||
- You prefer Termion's Unix-focused approach
|
||||
|
||||
**When to use the main [`ratatui`] crate:**
|
||||
|
||||
- Building applications (recommended - includes termion backend when enabled)
|
||||
- You want the convenience of having everything available
|
||||
|
||||
For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
|
||||
[`ratatui`]: https://crates.io/crates/ratatui
|
||||
[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
|
||||
<!-- cargo-rdme end -->
|
||||
|
||||
@ -11,6 +11,28 @@
|
||||
//!
|
||||
//! [`Backend`]: ratatui_core::backend::Backend
|
||||
//! [Termion]: https://docs.rs/termion
|
||||
//!
|
||||
//! # Crate Organization
|
||||
//!
|
||||
//! `ratatui-termion` is part of the Ratatui workspace that was modularized in version 0.30.0.
|
||||
//! This crate provides the [Termion] backend implementation for Ratatui.
|
||||
//!
|
||||
//! **When to use `ratatui-termion`:**
|
||||
//!
|
||||
//! - You need fine-grained control over dependencies
|
||||
//! - Building a widget library that needs backend functionality
|
||||
//! - You want to use only the Termion backend without other backends
|
||||
//! - You prefer Termion's Unix-focused approach
|
||||
//!
|
||||
//! **When to use the main [`ratatui`] crate:**
|
||||
//!
|
||||
//! - Building applications (recommended - includes termion backend when enabled)
|
||||
//! - You want the convenience of having everything available
|
||||
//!
|
||||
//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
//!
|
||||
//! [`ratatui`]: https://crates.io/crates/ratatui
|
||||
//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
#![cfg_attr(feature = "document-features", doc = "\n## Features")]
|
||||
#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
|
||||
|
||||
|
||||
@ -8,4 +8,26 @@ the [Termwiz] crate to interact with the terminal.
|
||||
[`Backend`]: trait.Backend.html
|
||||
[Termwiz]: https://crates.io/crates/termwiz
|
||||
|
||||
## Crate Organization
|
||||
|
||||
`ratatui-termwiz` is part of the Ratatui workspace that was modularized in version 0.30.0.
|
||||
This crate provides the [Termwiz] backend implementation for Ratatui.
|
||||
|
||||
**When to use `ratatui-termwiz`:**
|
||||
|
||||
- You need fine-grained control over dependencies
|
||||
- Building a widget library that needs backend functionality
|
||||
- You want to use only the Termwiz backend without other backends
|
||||
- You need Termwiz's advanced terminal capabilities
|
||||
|
||||
**When to use the main [`ratatui`] crate:**
|
||||
|
||||
- Building applications (recommended - includes termwiz backend when enabled)
|
||||
- You want the convenience of having everything available
|
||||
|
||||
For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
|
||||
[`ratatui`]: https://crates.io/crates/ratatui
|
||||
[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
|
||||
<!-- cargo-rdme end -->
|
||||
|
||||
@ -11,6 +11,28 @@
|
||||
//!
|
||||
//! [`Backend`]: trait.Backend.html
|
||||
//! [Termwiz]: https://crates.io/crates/termwiz
|
||||
//!
|
||||
//! # Crate Organization
|
||||
//!
|
||||
//! `ratatui-termwiz` is part of the Ratatui workspace that was modularized in version 0.30.0.
|
||||
//! This crate provides the [Termwiz] backend implementation for Ratatui.
|
||||
//!
|
||||
//! **When to use `ratatui-termwiz`:**
|
||||
//!
|
||||
//! - You need fine-grained control over dependencies
|
||||
//! - Building a widget library that needs backend functionality
|
||||
//! - You want to use only the Termwiz backend without other backends
|
||||
//! - You need Termwiz's advanced terminal capabilities
|
||||
//!
|
||||
//! **When to use the main [`ratatui`] crate:**
|
||||
//!
|
||||
//! - Building applications (recommended - includes termwiz backend when enabled)
|
||||
//! - You want the convenience of having everything available
|
||||
//!
|
||||
//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
//!
|
||||
//! [`ratatui`]: https://crates.io/crates/ratatui
|
||||
//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
#![cfg_attr(feature = "document-features", doc = "\n## Features")]
|
||||
#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
|
||||
|
||||
|
||||
@ -70,6 +70,28 @@ cargo add ratatui-widgets
|
||||
|
||||
All these widgets are re-exported directly under `ratatui::widgets` in the `ratatui` crate.
|
||||
|
||||
## Crate Organization
|
||||
|
||||
`ratatui-widgets` is part of the Ratatui workspace that was modularized in version 0.30.0.
|
||||
This crate contains all the built-in widget implementations that were previously part of the
|
||||
main `ratatui` crate.
|
||||
|
||||
**When to use `ratatui-widgets`:**
|
||||
|
||||
- Building widget libraries that need to compose with built-in widgets
|
||||
- You want finer-grained dependencies and only need specific widgets
|
||||
- Creating custom widgets that extend or wrap the built-in ones
|
||||
|
||||
**When to use the main [`ratatui`] crate:**
|
||||
|
||||
- Building applications (recommended - includes everything you need)
|
||||
- You want the convenience of having all widgets available
|
||||
|
||||
For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
|
||||
[`ratatui`]: https://crates.io/crates/ratatui
|
||||
[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please open an issue or submit a pull request on GitHub. For more
|
||||
|
||||
@ -69,6 +69,28 @@
|
||||
//! [`Tabs`]: crate::tabs::Tabs
|
||||
//!
|
||||
//! All these widgets are re-exported directly under `ratatui::widgets` in the `ratatui` crate.
|
||||
//!
|
||||
//! # Crate Organization
|
||||
//!
|
||||
//! `ratatui-widgets` is part of the Ratatui workspace that was modularized in version 0.30.0.
|
||||
//! This crate contains all the built-in widget implementations that were previously part of the
|
||||
//! main `ratatui` crate.
|
||||
//!
|
||||
//! **When to use `ratatui-widgets`:**
|
||||
//!
|
||||
//! - Building widget libraries that need to compose with built-in widgets
|
||||
//! - You want finer-grained dependencies and only need specific widgets
|
||||
//! - Creating custom widgets that extend or wrap the built-in ones
|
||||
//!
|
||||
//! **When to use the main [`ratatui`] crate:**
|
||||
//!
|
||||
//! - Building applications (recommended - includes everything you need)
|
||||
//! - You want the convenience of having all widgets available
|
||||
//!
|
||||
//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
|
||||
//!
|
||||
//! [`ratatui`]: https://crates.io/crates/ratatui
|
||||
//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
#![cfg_attr(feature = "document-features", doc = "\n## Features")]
|
||||
#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
|
||||
//!
|
||||
|
||||
@ -21,8 +21,6 @@
|
||||
//!
|
||||
//! </div>
|
||||
//!
|
||||
//! # Ratatui
|
||||
//!
|
||||
//! [Ratatui][Ratatui Website] is a crate for cooking up terminal user interfaces in Rust. It is a
|
||||
//! lightweight library that provides a set of [widgets](`widgets`) and utilities to build complex
|
||||
//! Rust TUIs. Ratatui was forked from the [tui-rs] crate in 2023 in order to continue its
|
||||
@ -66,7 +64,7 @@
|
||||
//! various [Examples]. There are also several starter templates available in the [templates]
|
||||
//! repository.
|
||||
//!
|
||||
//! ## Other documentation
|
||||
//! # Other documentation
|
||||
//!
|
||||
//! - [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials
|
||||
//! - [Ratatui Forum][Forum] - a place to ask questions and discuss the library
|
||||
@ -79,7 +77,27 @@
|
||||
//! You can also watch the [FOSDEM 2024 talk] about Ratatui which gives a brief introduction to
|
||||
//! terminal user interfaces and showcases the features of Ratatui, along with a hello world demo.
|
||||
//!
|
||||
//! ## Introduction
|
||||
//! # Crate Organization
|
||||
//!
|
||||
//! Starting with Ratatui 0.30.0, the project was reorganized into a modular workspace to improve
|
||||
//! compilation times, API stability, and dependency management. Most applications should continue
|
||||
//! using this main `ratatui` crate, which re-exports everything for convenience:
|
||||
//!
|
||||
//! - **[`ratatui`](crate)**: Main crate with complete functionality (recommended for apps)
|
||||
//! - **[`ratatui-core`]**: Core traits and types for widget libraries
|
||||
//! - **[`ratatui-widgets`]**: Built-in widget implementations
|
||||
//! - **Backend crates**: [`ratatui-crossterm`], [`ratatui-termion`], [`ratatui-termwiz`]
|
||||
//! - **[`ratatui-macros`]**: Macros for simplifying the boilerplate
|
||||
//!
|
||||
//! **For application developers**: No changes needed - continue using `ratatui` as before.
|
||||
//!
|
||||
//! **For widget library authors**: Consider depending on [`ratatui-core`] instead of the full
|
||||
//! `ratatui` crate for better API stability and reduced dependencies.
|
||||
//!
|
||||
//! See [ARCHITECTURE.md] for detailed information about the crate organization and design
|
||||
//! decisions.
|
||||
//!
|
||||
//! # Introduction
|
||||
//!
|
||||
//! Ratatui is based on the principle of immediate rendering with intermediate buffers. This means
|
||||
//! that for each frame, your app must render all [`widgets`] that are supposed to be part of the
|
||||
@ -99,7 +117,7 @@
|
||||
//! - Handles input events
|
||||
//! - Restore the terminal state
|
||||
//!
|
||||
//! ### Initialize and restore the terminal
|
||||
//! ## Initialize and restore the terminal
|
||||
//!
|
||||
//! The [`Terminal`] type is the main entry point for any Ratatui application. It is generic over a
|
||||
//! a choice of [`Backend`] implementations that each provide functionality to draw frames, clear
|
||||
@ -126,7 +144,7 @@
|
||||
//! See the [`backend` module] and the [Backends] section of the [Ratatui Website] for more info on
|
||||
//! the alternate screen and raw mode.
|
||||
//!
|
||||
//! ### Drawing the UI
|
||||
//! ## Drawing the UI
|
||||
//!
|
||||
//! Drawing the UI is done by calling the [`Terminal::draw`] method on the terminal instance. This
|
||||
//! method takes a closure that is called with a [`Frame`] instance. The [`Frame`] provides the size
|
||||
@ -156,7 +174,7 @@
|
||||
//! # fn handle_events() -> std::io::Result<bool> { Ok(false) }
|
||||
//! ```
|
||||
//!
|
||||
//! ### Handling events
|
||||
//! ## Handling events
|
||||
//!
|
||||
//! Ratatui does not include any input handling. Instead event handling can be implemented by
|
||||
//! calling backend library methods directly. See the [Handling Events] section of the [Ratatui
|
||||
@ -180,7 +198,7 @@
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! ## Layout
|
||||
//! # Layout
|
||||
//!
|
||||
//! The library comes with a basic yet useful layout management object called [`Layout`] which
|
||||
//! allows you to split the available space into multiple areas and then render widgets in each
|
||||
@ -217,7 +235,7 @@
|
||||
//! Status Bar──────────────────────────────────
|
||||
//! ```
|
||||
//!
|
||||
//! ## Text and styling
|
||||
//! # Text and styling
|
||||
//!
|
||||
//! The [`Text`], [`Line`] and [`Span`] types are the building blocks of the library and are used in
|
||||
//! many places. [`Text`] is a list of [`Line`]s and a [`Line`] is a list of [`Span`]s. A [`Span`]
|
||||
@ -307,6 +325,13 @@
|
||||
//! [Termion]: https://crates.io/crates/termion
|
||||
//! [Termwiz]: https://crates.io/crates/termwiz
|
||||
//! [tui-rs]: https://crates.io/crates/tui
|
||||
//! [`ratatui-core`]: https://crates.io/crates/ratatui-core
|
||||
//! [`ratatui-widgets`]: https://crates.io/crates/ratatui-widgets
|
||||
//! [`ratatui-crossterm`]: https://crates.io/crates/ratatui-crossterm
|
||||
//! [`ratatui-termion`]: https://crates.io/crates/ratatui-termion
|
||||
//! [`ratatui-termwiz`]: https://crates.io/crates/ratatui-termwiz
|
||||
//! [`ratatui-macros`]: https://crates.io/crates/ratatui-macros
|
||||
//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
//! [GitHub Sponsors]: https://github.com/sponsors/ratatui
|
||||
//! [Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square&logoColor=E05D44&color=E05D44
|
||||
//! [License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square&color=1370D3
|
||||
@ -324,6 +349,13 @@
|
||||
//! [Forum Badge]: https://img.shields.io/discourse/likes?server=https%3A%2F%2Fforum.ratatui.rs&style=flat-square&logo=discourse&label=forum&color=C43AC3
|
||||
//! [Forum]: https://forum.ratatui.rs
|
||||
//! [Sponsors Badge]: https://img.shields.io/github/sponsors/ratatui?logo=github&style=flat-square&color=1370D3
|
||||
//! [`ratatui-core`]: https://crates.io/crates/ratatui-core
|
||||
//! [`ratatui-widgets`]: https://crates.io/crates/ratatui-widgets
|
||||
//! [`ratatui-crossterm`]: https://crates.io/crates/ratatui-crossterm
|
||||
//! [`ratatui-termion`]: https://crates.io/crates/ratatui-termion
|
||||
//! [`ratatui-termwiz`]: https://crates.io/crates/ratatui-termwiz
|
||||
//! [`ratatui-macros`]: https://crates.io/crates/ratatui-macros
|
||||
//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
|
||||
|
||||
#![warn(clippy::std_instead_of_core)]
|
||||
#![warn(clippy::std_instead_of_alloc)]
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user