docs(widgets): Add simple barchart example (#1511)

Cargo.lock

@@ -2241,6 +2241,7 @@ name = "ratatui-widgets"
 version = "0.3.0"
 dependencies = [
  "bitflags 2.6.0",
+ "color-eyre",
  "document-features",
  "indoc",
  "instability",

Cargo.toml

@@ -26,6 +26,7 @@ rust-version = "1.74.0"
 
 [workspace.dependencies]
 bitflags = "2.6.0"
+color-eyre = "0.6.3"
 crossterm = "0.28.1"
 document-features = "0.2.7"
 indoc = "2.0.5"

ratatui-widgets/Cargo.toml

@@ -16,6 +16,7 @@ rust-version.workspace = true
 
 [package.metadata.docs.rs]
 all-features = true
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
 rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
@@ -58,9 +59,10 @@ document-features = { workspace = true, optional = true }
 line-clipping = "0.2.1"
 
 [dev-dependencies]
-rstest.workspace = true
+color-eyre.workspace = true
 pretty_assertions.workspace = true
 ratatui.workspace = true
+rstest.workspace = true
 
 [lints.rust]
 unsafe_code = "forbid"
@@ -103,3 +105,7 @@ string_slice = "warn"
 string_to_string = "warn"
 unnecessary_self_imports = "warn"
 use_self = "warn"
+
+[[example]]
+name = "barchart"
+doc-scrape-examples = true

ratatui-widgets/examples/barchart.rs

@@ -0,0 +1,91 @@
+//! # [Ratatui] `BarChart` example
+//!
+//! The latest version of this example is available in the [widget examples] folder in the
+//! repository.
+//!
+//! Please note that the examples are designed to be run against the `main` branch of the Github
+//! repository. This means that you may not be able to compile with the latest release version on
+//! crates.io, or the one that you have installed locally.
+//!
+//! See the [examples readme] for more information on finding examples that match the version of the
+//! library you are using.
+//!
+//! [Ratatui]: https://github.com/ratatui/ratatui
+//! [widget examples]: https://github.com/ratatui/ratatui/blob/main/ratatui-widgets/examples
+//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md
+
+use color_eyre::Result;
+use ratatui::{
+    layout::{Constraint, Layout, Rect},
+    style::Stylize,
+    text::{Line, Span},
+    widgets::{Bar, BarChart},
+    DefaultTerminal, Frame,
+};
+
+fn main() -> Result<()> {
+    color_eyre::install()?;
+    let terminal = ratatui::init();
+    let result = run(terminal);
+    ratatui::restore();
+    result
+}
+
+/// Run the application.
+fn run(mut terminal: DefaultTerminal) -> Result<()> {
+    loop {
+        terminal.draw(draw)?;
+        if quit_key_pressed()? {
+            break Ok(());
+        }
+    }
+}
+
+/// Draw the UI with a title and two barcharts.
+fn draw(frame: &mut Frame) {
+    let vertical = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)]).spacing(1);
+    let horizontal = Layout::horizontal([Constraint::Length(28), Constraint::Fill(1)]).spacing(1);
+    let [top, main] = vertical.areas(frame.area());
+    let [left, right] = horizontal.areas(main);
+
+    let title = Line::from_iter([
+        Span::from("BarChart Widget").bold(),
+        Span::from(" (Press 'q' to quit)"),
+    ]);
+    frame.render_widget(title.centered(), top);
+    render_vertical_barchart(frame, left);
+    render_horizontal_barchart(frame, right);
+}
+
+/// Render a horizontal barchart with some sample data.
+fn render_horizontal_barchart(frame: &mut Frame, area: Rect) {
+    let bars = vec![
+        Bar::with_label("Red", 30).red(),
+        Bar::with_label("Blue", 20).blue(),
+        Bar::with_label("Green", 15).green(),
+        Bar::with_label("Yellow", 10).yellow(),
+    ];
+    let chart = BarChart::horizontal(bars).bar_width(3);
+    frame.render_widget(chart, area);
+}
+
+/// Render a vertical barchart with some sample data.
+fn render_vertical_barchart(frame: &mut Frame, area: Rect) {
+    let bars = vec![
+        Bar::with_label("Red", 30).red(),
+        Bar::with_label("Blue", 20).blue(),
+        Bar::with_label("Green", 15).green(),
+        Bar::with_label("Yellow", 10).yellow(),
+    ];
+    let chart = BarChart::vertical(bars).bar_width(6);
+    frame.render_widget(chart, area);
+}
+
+/// Wait for an event and return `true` if the Esc or 'q' key is pressed.
+fn quit_key_pressed() -> Result<bool> {
+    use ratatui::crossterm::event::{self, Event, KeyCode};
+    match event::read()? {
+        Event::Key(event) if matches!(event.code, KeyCode::Esc | KeyCode::Char('q')) => Ok(true),
+        _ => Ok(false),
+    }
+}