From 3c9d1fbdbbbc4dbb306ee3205dc4c18e52dbbf88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Orhun=20Parmaks=C4=B1z?= Date: Mon, 24 Jun 2024 00:15:21 +0300 Subject: [PATCH 1/3] docs(highlights): add highlights for 0.27.0 --- src/content/docs/highlights/index.md | 1 + src/content/docs/highlights/v0.27.md | 293 +++++++++++++++++++++++++++ 2 files changed, 294 insertions(+) create mode 100644 src/content/docs/highlights/v0.27.md diff --git a/src/content/docs/highlights/index.md b/src/content/docs/highlights/index.md index 37336dcaf..34b1aa145 100644 --- a/src/content/docs/highlights/index.md +++ b/src/content/docs/highlights/index.md @@ -5,6 +5,7 @@ title: Highlights This section highlights the main changes in each major release of Ratatui (from v0.21.0 through the latest version). +- [v0.27](./v027/) - [v0.26.3](./v0263/) - [v0.26.2](./v0262/) - [v0.26](./v026/) diff --git a/src/content/docs/highlights/v0.27.md b/src/content/docs/highlights/v0.27.md new file mode 100644 index 000000000..cd01e7ade --- /dev/null +++ b/src/content/docs/highlights/v0.27.md @@ -0,0 +1,293 @@ +--- +title: v0.27.0 +--- + + + +⚠️ See the [breaking changes](https://github.com/ratatui-org/ratatui/blob/main/BREAKING-CHANGES.md) +for this release. + +## LineGauge: Background Styles 📊 + +`LineGauge::gauge_style` is now deprecated in favor of `filled_style` and `unfilled_style` methods +which makes it possible to set the foreground/background styles for different states. + +```rust +let gauge = LineGauge::default() + .filled_style(Style::default().fg(Color::Green)) + .unfilled_style(Style::default().fg(Color::White)) + .ratio(0.43); +``` + +We also added a +[Line Gauge example](https://github.com/ratatui-org/ratatui/blob/main/examples/line_gauge.rs): + + + +## Palette Colors 🎨 + +⚠️ This is behind the "palette" feature flag. + +You can now use colors from the [palette](https://crates.io/crates/palette) crate in Ratatui! + +```rust +use palette::{LinSrgb, Srgb}; +use ratatui::style::Color; + +let color = Color::from(Srgb::new(1.0f32, 0.0, 0.0)); +let color = Color::from(LinSrgb::new(1.0f32, 0.0, 0.0)); +``` + +--- + +## New Border Sets 🖼️ + +### `border::EMPTY` + +It uses an empty space symbol (░) + +```rust +let block = Block::bordered().title("Title").border_set(border::EMPTY); +``` + +```text +░░░░░░░░ +░░ ░░ +░░ ░░ ░░ +░░ ░░ ░░ +░░ ░░ +░░░░░░░░ +``` + +This is useful for when you need to allocate space for the border and apply the border style to a +block without actually drawing a border. This makes it possible to style the entire title area or a +block rather than just the title content. + +### `border::FULL` + +It uses a full block symbol (█) + +```rust +let block = Block::bordered().title("Title").border_set(border::FULL); +``` + +```text +████ +█xx█ +█xx█ +████ +``` + +--- + +## Re-export Backends 📤 + +`crossterm`, `termion`, and `termwiz` can now be accessed as +`ratatui::{crossterm, termion, termwiz}` respectively. + +This makes it possible to just add the Ratatui crate as a dependency and use the backend of choice +without having to add the backend crates as dependencies. + +To update existing code, replace all instances of `crossterm::` with `ratatui::crossterm::`, +`termion::` with `ratatui::termion::`, and `termwiz::` with `ratatui::termwiz::`. + +Example for `crossterm`: + +```diff +-use crossterm::event::{Event, KeyCode, KeyEvent, KeyEventKind}; ++use ratatui::crossterm::event::{Event, KeyCode, KeyEvent, KeyEventKind}; +``` + +And then you can remove `crossterm` from `Cargo.toml`! + +--- + +## Update Prelude 📜 + +Based on a [suggestion on Reddit](https://www.reddit.com/r/rust/comments/1cle18j/comment/l2uuuh7/) +we made changes to the `prelude` module. + +> Note: This module allows you to easily use `ratatui` without a huge amount of imports! e.g. +> `use ratatui::prelude::*;` + +The following items have been removed from the prelude: + +- `style::Styled` - this trait is useful for widgets that want to support the Stylize trait, but it + adds complexity as widgets have two `style` methods and a `set_style` method. +- `symbols::Marker` - this item is used by code that needs to draw to the `Canvas` widget, but it's + not a common item that would be used by most users of the library. +- `terminal::{CompletedFrame, TerminalOptions, Viewport}` - these items are rarely used by code that + needs to interact with the terminal, and they're generally only ever used once in any app. + +The following items have been added to the prelude: + +- `layout::{Position, Size}` - these items are used by code that needs to interact with the layout + system. These are newer items that were added in the last few releases, which should be used more + liberally. + +--- + +## Tracing Example 🔍 + +Wondering how to debug TUI apps? Tried `println` and it didn't work? We got you covered! + +We added an example that demonstrates how to log to a file: + +![tracing example](https://vhs.charm.sh/vhs-21jgJCedh2YnFDONw0JW7l.gif) + +- Code: +- Related discussion on Ratatui Forum: + + +--- + +## Hyperlink Example 🔗 + +We added a proof-of-concept example for using hyperlinks in the terminal. + +![Demo](https://vhs.charm.sh/vhs-2c5cvJzN7KTKR7U3Jbk71J.gif) + +> The code is available +> [here](https://github.com/ratatui-org/ratatui/blob/main/examples/hyperlink.rs). + +--- + +## Cell: New methods 🔧 + +You can now create empty `Cell`s like this: + +```rust +let mut cell = Cell::EMPTY; +assert_eq!(cell.symbol(), " "); +``` + +We also added a constant `Cell:new` method for simplify the construction as follows: + +```diff +-let mut cell = Cell::default(); +-cell.set_symbol("a"); ++let cell = Cell::new("a"); +``` + +--- + +## Make `Stylize::bg()` generic 🔄 + +Previously, `Stylize::bg()` accepted `Color` but now accepts `Into`. This allows more +flexible types from calling scopes, though it can break some type inference in the calling scope. + +--- + +## Writer Methods on Backends 🖋️ + +`crossterm` and `termion` backends now have `writer()` and `writer_mut()` methods for obtain access +to the underlying writer. + +This is useful e.g. if you want to see what has been written so far. + +```rust +let terminal = Terminal::new(CrosstermBackend::new(Vec::::new())); +let ui = |frame| { ... }; + +terminal.draw(ui); + +let crossterm_backend = terminal.backend(); +let buffer = crossterm_backend.writer(); +``` + +--- + +## Add Missing VHS Tapes 📼 + +We were missing demos for some of our examples. They are now added! + +[Constraint explorer example](https://github.com/ratatui-org/ratatui/blob/main/examples/constraint-explorer.rs): + +![constraint-explorer](https://github.com/ratatui-org/ratatui/assets/381361/9933df57-3afc-4d5b-88bd-15909f6dcdaf) + +[Minimal example](https://github.com/ratatui-org/ratatui/blob/main/examples/minimal.rs): + +![minimal](https://github.com/ratatui-org/ratatui/assets/381361/d39b518e-906b-4725-8cae-6fbad17f3a90) + +--- + +## List: Remove deprecated `start_corner()` 🚫 + +`List::start_corner` was deprecated back in v0.25. + +Use `List::direction` and `ListDirection` instead: + +```diff +- list.start_corner(Corner::TopLeft); +- list.start_corner(Corner::TopRight); +// This is not an error, BottomRight rendered top to bottom previously +- list.start_corner(Corner::BottomRight); +// all becomes ++ list.direction(ListDirection::TopToBottom); +``` + +```diff +- list.start_corner(Corner::BottomLeft); +// becomes ++ list.direction(ListDirection::BottomToTop); +``` + +`layout::Corner` is also removed entirely. + +--- + +## Padding: Deprecate `zero()` 🚫 + +It is now a constant! + +```diff +-Padding::zero() ++Padding::ZERO +``` + +--- + +## Buffer: Improve Performance ⚡️ + +`Buffer::filled` now moves the cell instead of taking a reference: + +```diff +-Buffer::filled(area, &Cell::new("X")); ++Buffer::filled(area, Cell::new("X")); +``` + +--- + +## Rect: Improve Performance ⚡️ + +`Margin` needs to be passed without reference now: + +```diff +-let area = area.inner(&Margin { ++let area = area.inner(Margin { + vertical: 0, + horizontal: 2, + }); +``` + +--- + +## Other 💼 + +- `Position` and `Size` now implements `Display` + ([#1162](https://github.com/ratatui-org/ratatui/pull/1162)) +- Remove newlines when converting strings to `Line`s + ([#1191](https://github.com/ratatui-org/ratatui/pull/1191)) + - `Line::from("a\nb")` now returns a `Line` with two `Span`s instead of one +- Ensure that zero-width characters are rendered correctly + ([#1165](https://github.com/ratatui-org/ratatui/pull/1165)) +- Respect area width while rendering &str and String + ([#1177](https://github.com/ratatui-org/ratatui/pull/1177)) +- Improve benchmark consistency ([#1126](https://github.com/ratatui-org/ratatui/pull/1126)) + +--- + +_"I can't believe it! A real gourmet kitchen, and I get to watch!" – Remy_ From bcdd61e726ca4ab3d620d610a68d15240e0a4d3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Orhun=20Parmaks=C4=B1z?= Date: Mon, 24 Jun 2024 11:24:56 +0300 Subject: [PATCH 2/3] docs(highlights): add code example for generic Stylize bg --- src/content/docs/highlights/v0.27.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/content/docs/highlights/v0.27.md b/src/content/docs/highlights/v0.27.md index cd01e7ade..0be10ed06 100644 --- a/src/content/docs/highlights/v0.27.md +++ b/src/content/docs/highlights/v0.27.md @@ -179,6 +179,11 @@ We also added a constant `Cell:new` method for simplify the construction as foll Previously, `Stylize::bg()` accepted `Color` but now accepts `Into`. This allows more flexible types from calling scopes, though it can break some type inference in the calling scope. +```rust +let srgb_color: Srgb = Srgb::new(255, 0, 0); +foo.bg(srgb_color); +``` + --- ## Writer Methods on Backends 🖋️ From e3a6c959320488ba4c6f4c2f7a72110d86dd24b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Orhun=20Parmaks=C4=B1z?= Date: Mon, 24 Jun 2024 13:41:45 +0300 Subject: [PATCH 3/3] docs(highlights): add new entries --- src/content/docs/highlights/v0.27.md | 33 ++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/src/content/docs/highlights/v0.27.md b/src/content/docs/highlights/v0.27.md index 0be10ed06..7c3e8757e 100644 --- a/src/content/docs/highlights/v0.27.md +++ b/src/content/docs/highlights/v0.27.md @@ -27,6 +27,39 @@ We also added a Your browser does not support the video tag. +--- + +## List: Navigation Methods 🧭 + +You can now navigate in the `List` widget by using the following methods! + +```rust +let mut state = ListState::default(); +state.select_first(); +state.select_next(); +state.select_previous(); +state.select_last(); +``` + +It also clamps the selected index to the bounds of the list when navigating. + +--- + +## Text: Conversion From Display 🔄 + +`Text`, `Span` and `Line` now supports conversion from any type that implements the `Display` trait! + +```rust +let text = "line1\nline2".to_text(); +let span = (6.66).to_span(); +let line = 42.to_line(); +``` + +This has been made possible with the newly added `ToText`, `ToSpan` and `ToLine` traits +respectfully. + +--- + ## Palette Colors 🎨 ⚠️ This is behind the "palette" feature flag.