v0.27.0

[orhun]

0.27.0 - 2024-06-24

“I can’t believe it! A real gourmet kitchen, and I get to watch!” – Remy

We are excited to announce the new version of ratatui - a Rust library that's all about cooking up TUIs 🐭

In this version, we have focused on enhancing usability and functionality with new features like background styles for LineGauge, palette colors, and various other improvements including improved performance. Also, we added brand new examples for tracing and creating hyperlinks!

✨ Release highlights: https://ratatui.rs/highlights/v027/

⚠️ List of breaking changes can be found here.

Features

• eef1afe (linegauge) Allow LineGauge background styles by @nowNick in #565

  This PR deprecates `gauge_style` in favor of `filled_style` and
  `unfilled_style` which can have it's foreground and background styled.
  
  `cargo run --example=line_gauge --features=crossterm`
  

  line_gauge_demo.mov

  Implements:LineGauge: gauge_style is confusing #424

• 1365620 (borders) Add FULL and EMPTY border sets by @joshka in #1182

  border::FULL uses a full block symbol, while border::EMPTY uses an
  empty space. 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.

use ratatui::{symbols::border, widgets::Block};
let block = Block::bordered().title("Title").border_set(border::FULL);
let block = Block::bordered().title("Title").border_set(border::EMPTY);

• 7a48c5b (cell) Add EMPTY and (const) new method by @EdJoPaTo in #1143

  This simplifies calls to `Buffer::filled` in tests.
  

• 3f2f2cd (docs) Add tracing example by @joshka in #1192

  Add an example that demonstrates logging to a file for:
  

  https://forum.ratatui.rs/t/how-do-you-println-debug-your-tui-programs/66

cargo run --example tracing
RUST_LOG=trace cargo run --example=tracing
cat tracing.log

• 1520ed9 (layout) Impl Display for Position and Size by @joshka in #1162

• 46977d8 (list) Add list navigation methods (first, last, previous, next) by @joshka in #1159 [breaking]

  Also cleans up the list example significantly (see also
  <https://github.com/ratatui-org/ratatui/issues/1157>)
  

  Fixes:feat(list)!: add list navigation methods (first, last, previous, next) #1159

  BREAKING CHANGE:The List widget now clamps the selected index to the
  bounds of the list when navigating with first, last, previous, and
  next, as well as when setting the index directly with select.

• 10d7788 (style) Add conversions from the palette crate colors by @joshka in #1172

  This is behind the "palette" feature flag.
  
  ```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));
  ```
  

• 7ef2dae (text) support conversion from Display to Span, Line and Text by @orhun in #1167

  Now you can create `Line` and `Text` from numbers like so:
  
  ```rust
  let line = 42.to_line();
  let text = 666.to_text();
  ```
  

• 74a32af (uncategorized) Re-export backends from the ratatui crate by @joshka in #1151

  `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::`.
  

• 3594180 (uncategorized) Make Stylize's .bg(color) generic by @kdheepak in #1103 [breaking]

• 0b5fd6b (uncategorized) Add writer() and writer_mut() to termion and crossterm backends by @enricozb in #991

  It is sometimes useful to obtain access to the writer if we want to see
  what has been written so far. For example, when using &mut [u8] as a
  writer.
  

Bug Fixes

• efa965e (line) Remove newlines when converting strings to Lines by @joshka in #1191

  Line::from("a\nb") now returns a line with two Spans instead of 1

  Fixes:Inconsistent behavior between Line::from and Line::raw  #1111

• d370aa7 (span) Ensure that zero-width characters are rendered correctly by @joshka in #1165

• 127d706 (table) Ensure render offset without selection properly by @joshka in #1187

  Fixes:TableState resets offset to 0 #1179

• 4bfdc15 (uncategorized) Render of &str and String doesn't respect area.width by @thscharler in #1177

• e6871b9 (uncategorized) Avoid unicode-width breaking change in tests by @joshka in #1171

  unicode-width 0.1.13 changed the width of \u{1} from 0 to 1.
  Our tests assumed that \u{1} had a width of 0, so this change replaces
  the \u{1} character with \u{200B} (zero width space) in the tests.
  
  Upstream issue (closed as won't fix):
  https://github.com/unicode-rs/unicode-width/issues/55
  

• 7f3efb0 (uncategorized) Pin unicode-width crate to 0.1.13 by @joshka in #1170

  semver breaking change in 0.1.13
  <https://github.com/unicode-rs/unicode-width/issues/55>
  
  <!-- Please read CONTRIBUTING.md before submitting any pull request. -->
  

• 42cda6d (uncategorized) Prevent panic from string_slice by @EdJoPaTo in #1140

  https://rust-lang.github.io/rust-clippy/master/index.html#string_slice

Refactor

• 73fd367 (block) Group builder pattern methods by @EdJoPaTo in #1134

• 257db62 (cell) Must_use and simplify style() by @EdJoPaTo in #1124

  <!-- Please read CONTRIBUTING.md before submitting any pull request. -->
  

• bf20369 (cell) Reset instead of applying default by @EdJoPaTo in #1127

  Using reset is clearer to me what actually happens. On the other case a
  struct is created to override the old one completely which basically
  does the same in a less clear way.
  

• 7d175f8 (lint) Fix new lint warnings by @EdJoPaTo in #1178

• cf67ed9 (lint) Use clippy::or_fun_call by @EdJoPaTo in #1138

  https://rust-lang.github.io/rust-clippy/master/index.html#or_fun_call

• 4770e71 (list) Remove deprecated start_corner and Corner by @Valentin271 in #759 [breaking]

  List::start_corner was deprecated in v0.25. Use List::direction and
  ListDirection instead.

- 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);

- list.start_corner(Corner::BottomLeft);
// becomes
+ list.direction(ListDirection::BottomToTop);

layout::Corner is removed entirely.

• 4f77910 (padding) Add Padding::ZERO as a constant by @EdJoPaTo in #1133

  Deprecate Padding::zero()
  

• 8061813 (uncategorized) Expand glob imports by @joshka in #1152

  Consensus is that explicit imports make it easier to understand the
  example code. This commit removes the prelude import from all examples
  and replaces it with the necessary imports, and expands other glob
  imports (widget::*, Constraint::*, KeyCode::*, etc.) everywhere else.
  Prelude glob imports not in examples are not covered by this PR.
  
  See https://github.com/ratatui-org/ratatui/issues/1150 for more details.
  

• d929971 (uncategorized) Dont manually impl Default for defaults by @EdJoPaTo in #1142

  Replace `impl Default` by `#[derive(Default)]` when its implementation
  equals.
  

• 8a60a56 (uncategorized) Needless_pass_by_ref_mut by @EdJoPaTo in #1137

  https://rust-lang.github.io/rust-clippy/master/index.html#needless_pass_by_ref_mut

• 1de9a82 (uncategorized) Simplify if let by @EdJoPaTo in #1135

  While looking through lints
  [`clippy::option_if_let_else`](https://rust-lang.github.io/rust-clippy/master/index.html#option_if_let_else)
  found these. Other findings are more complex so I skipped them.
  

Documentation

• 1908b06 (borders) Add missing closing code blocks by @orhun in #1195

• 38bb196 (breaking-changes) Mention LineGauge::gauge_style by @orhun in #1194

  see feat(LineGauge): allow LineGauge background styles #565

• 07efde5 (examples) Add hyperlink example by @joshka in #1063

• 7fdccaf (examples) Add vhs tapes for constraint-explorer and minimal examples by @joshka in #1164

• 4f307e6 (examples) Simplify paragraph example by @joshka in #1169

  Related:Consistent examples in ratatui #1157

• f429f68 (examples) Remove lifetimes from the List example by @matta in #1132

  Simplify the List example by removing lifetimes not strictly necessary
  to demonstrate how Ratatui lists work. Instead, the sample strings are
  copied into each `TodoItem`. To further simplify, I changed the code to
  use a new TodoItem::new function, rather than an implementation of the
  `From` trait.
  

• 308c1df (readme) Add links to forum by @joshka in #1188

• 2f8a936 (uncategorized) Fix links on docs.rs by @EdJoPaTo in #1144

  This also results in a more readable Cargo.toml as the locations of the
  things are more obvious now.
  
  Includes rewording of the underline-color feature.
  
  Logs of the errors: https://docs.rs/crate/ratatui/0.26.3/builds/1224962
  Also see #989
  

Performance

• 4ce67fc (buffer) Filled moves the cell to be filled by @EdJoPaTo in #1148 [breaking]

• 8b447ec (rect) Rect::inner takes Margin directly instead of reference by @EdJoPaTo in #1008 [breaking]

  BREAKING CHANGE:Margin needs to be passed without reference now.

-let area = area.inner(&Margin {
+let area = area.inner(Margin {
     vertical: 0,
     horizontal: 2,
 });

Styling

• df4b706 (uncategorized) Enable more rustfmt settings by @EdJoPaTo in #1125

Testing

• d6587bc (style) Use rstest by @EdJoPaTo in #1136

  <!-- Please read CONTRIBUTING.md before submitting any pull request. -->
  

Miscellaneous Tasks

• 7b45f74 (prelude) Add / remove items by @joshka in #1149 [breaking]

  his PR removes the items from the prelude that don't form a coherent
  common vocabulary and adds the missing items that do.
  
  Based on a comment at
  <https://www.reddit.com/r/rust/comments/1cle18j/comment/l2uuuh7/>
  

  BREAKING CHANGE: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.

• cd64367 (symbols) Add tests for line symbols by @joshka in #1186

• 8cfc316 (uncategorized) Alphabetize examples in Cargo.toml by @joshka in #1145

Build

• 70df102 (bench) Improve benchmark consistency by @EdJoPaTo in #1126

  Codegen units are optimized on their own. Per default bench / release
  have 16 codegen units. What ends up in a codeget unit is rather random
  and can influence a benchmark result as a code change can move stuff
  into a different codegen unit → prevent / allow LLVM optimizations
  unrelated to the actual change.
  
  More details: https://doc.rust-lang.org/cargo/reference/profiles.html
  

New Contributors

• @thscharler made their first contribution in #1177
• @matta made their first contribution in #1132
• @nowNick made their first contribution in #565
• @enricozb made their first contribution in #991

Full Changelog: v0.26.3...v0.27.0

---

This discussion was created from the release v0.27.0.