ratatui_table/lib.rs
1#![no_std]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3#![doc(
4 html_logo_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/logo.png",
5 html_favicon_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/favicon.ico"
6)]
7#![warn(missing_docs)]
8//! An experimental evolution of Ratatui's built-in [`Table`] widget.
9//!
10//! `ratatui-table` starts with the Table implementation from Ratatui main at
11//! [`3d8639c`]. Version 0.1.0 is intended to render like that built-in Table while giving Table
12//! contributors room to explore borders, virtualization, selection, marking, borrowed data, and
13//! other changes independently.
14//!
15//! [`3d8639c`]: https://github.com/ratatui/ratatui/commit/3d8639cbb2f910200f30e680a8923ccaf99ba1bf
16//! [`Table`]: https://docs.rs/ratatui-table/latest/ratatui_table/struct.Table.html
17//!
18//! This crate is an opt-in development path for the built-in widget, not a competing Table design.
19//! If the experiment succeeds, Ratatui should be able to offer an easy upgrade or re-export path.
20//! No such re-export is implemented or promised yet.
21//!
22//! # Stability
23//!
24//! Releases before 1.0 may make breaking changes in minor versions. Each breaking release should
25//! document how to migrate. The 0.1.0 baseline deliberately avoids folding the existing Table
26//! proposals into the initial extraction so each proposal remains independently reviewable.
27//!
28//! # Installation
29//!
30//! ```shell
31//! cargo add ratatui-table
32//! ```
33//!
34//! # Example
35//!
36//! ```rust
37//! use ratatui::layout::Constraint;
38//! use ratatui_table::{Row, Table};
39//!
40//! let rows = [
41//! Row::new(["Alice", "Engineer"]),
42//! Row::new(["Bob", "Designer"]),
43//! ];
44//! let widths = [Constraint::Length(10), Constraint::Length(12)];
45//! let table = Table::new(rows, widths);
46//! ```
47//!
48//! # Ratatui compatibility
49//!
50//! [`Table::block`][block] accepts a ratatui-widgets [`Block`][block-widget] to preserve the
51//! built-in API. This means the initial crate depends on `ratatui-widgets` with default features
52//! disabled. A future Ratatui facade can re-export this crate without requiring this crate to
53//! become part of `ratatui-widgets` itself.
54//!
55//! [block]: https://docs.rs/ratatui-table/latest/ratatui_table/struct.Table.html#method.block
56//! [block-widget]: https://docs.rs/ratatui-widgets/latest/ratatui_widgets/block/struct.Block.html
57//!
58//! # Feature flags
59//!
60//! - `std` enables the standard-library features of the Ratatui dependencies. The Table itself
61//! remains usable with `no_std` plus `alloc` by default.
62//! - `serde` adds serialization and deserialization for [`TableState`], [`HighlightSpacing`][hs],
63//! and [`HighlightPlacement`][hp].
64//!
65//! [`TableState`]: https://docs.rs/ratatui-table/latest/ratatui_table/struct.TableState.html
66//! [hs]: https://docs.rs/ratatui-table/latest/ratatui_table/enum.HighlightSpacing.html
67//! [hp]: https://docs.rs/ratatui-table/latest/ratatui_table/enum.HighlightPlacement.html
68//!
69//! # Governance
70//!
71//! Contributors with repository Write access can review and merge ordinary Table work. Ratatui
72//! maintainers retain control of protected release configuration and approve every crates.io
73//! publication.
74
75extern crate alloc;
76
77mod table;
78
79#[doc(inline)]
80pub use table::{Cell, HighlightPlacement, HighlightSpacing, Row, Table, TableState};