0.23.0
We are thrilled to release the new version of ratatui 🐭, the official successor* of tui-rs.
In this version, we improved the existing widgets such as Barchart and Scrollbar. We also made improvements in the testing/internal APIs to provide a smoother testing/development experience. Additionally, we have addressed various bugs and implemented enhancements.
Here is a blog post that highlights the new features and breaking changes along with a retrospective about the project: https://blog.orhun.dev/ratatui-0-23-0
Features
-
(barchart) Add direction attribute. (horizontal bars support) (#325)
(0dca6a6)* feat(barchart): Add direction attribute Enable rendering the bars horizontally. In some cases this allow us to make more efficient use of the available space. -
(cell) Add voluntary skipping capability for sixel (#215)
(e4bcf78)> Sixel is a bitmap graphics format supported by terminals. > "Sixel mode" is entered by sending the sequence ESC+Pq. > The "String Terminator" sequence ESC+\ exits the mode. The graphics are then rendered with the top left positioned at the cursor position. It is actually possible to render sixels in ratatui with just `buf.get_mut(x, y).set_symbol("^[Pq ... ^[\")`. But any buffer covering the "image area" will overwrite the graphics. This is most likely the same buffer, even though it consists of empty characters `' '`, except for the top-left character that starts the sequence. Thus, either the buffer or cells must be specialized to avoid drawing over the graphics. This patch specializes the `Cell` with a `set_skip(bool)` method, based on James' patch: https://github.com/TurtleTheSeaHobo/tui-rs/tree/sixel-support I unsuccessfully tried specializing the `Buffer`, but as far as I can tell buffers get merged all the way "up" and thus skipping must be set on the Cells. Otherwise some kind of "skipping area" state would be required, which I think is too complicated. Having access to the buffer now it is possible to skip all cells but the first one which can then `set_symbol(sixel)`. It is up to the user to deal with the graphics size and buffer area size. It is possible to get the terminal's font size in pixels with a syscall. An image widget for ratatui that uses this `skip` flag is available at https://github.com/benjajaja/ratatu-image. -
(list) Add option to always allocate the "selection" column width (#394)
(4d70169)* feat(list): add option to always allocate the "selection" column width Before this option was available, selecting a item in a list when nothing was selected previously made the row layout change (the same applies to unselecting) by adding the width of the "highlight symbol" in the front of the list, this option allows to configure this behavior. * style: change "highlight_spacing" doc comment to use inline code-block for reference -
(release) Add automated nightly releases (#359)
(aad164a)* feat(release): add automated nightly releases * refactor(release): rename the alpha workflow * refactor(release): simplify the release calculation -
(scrollbar) Add optional track symbol (#360)
(1727fa5) [breaking]The track symbol is now optional, simplifying composition with other widgets. -
(table) Add support for line alignment in the table widget (#392)
(7748720)* feat(table): enforce line alignment in table render * test(table): add table alignment render test -
(widgets::table) Add option to always allocate the "selection" constraint (#375)
(f63ac72)* feat(table): add option to configure selection layout changes Before this option was available, selecting a row in the table when no row was selected previously made the tables layout change (the same applies to unselecting) by adding the width of the "highlight symbol" in the front of the first column, this option allows to configure this behavior. * refactor(table): refactor "get_columns_widths" to return (x, width) and "render" to make use of that * refactor(table): refactor "get_columns_widths" to take in a selection_width instead of a boolean also refactor "render" to make use of this change * fix(table): rename "highlight_set_selection_space" to "highlight_spacing" * style(table): apply doc-comment suggestions from code review -
(uncategorized) Expand serde attributes for
TestBuffer(#389)
(57ea871) -
(uncategorized) Add weak constraints to make rects closer to each other in size ✨ (#395)
(6153371)Also make `Max` and `Min` constraints MEDIUM strength for higher priority over equal chunks
Bug Fixes
-
(barchart) Empty groups causes panic (#333)
(9c95673)This unlikely to happen, since nobody wants to add an empty group. Even we fix the panic, things will not render correctly. So it is better to just not add them to the BarChart. -
(block) Fixed title_style not rendered (#349) (#363)
(49a82e0) -
(cargo) Adjust minimum paste version (#348)
(8db9fb4)ratatui is using features that are currently only available in paste 1.0.2; specifying the minimum version to be 1.0 will consequently cause a compilation error if cargo is only able to use a version less than 1.0.2. -
(example) Fix typo (#337)
(daf5890)the existential feels -
(layout) Don't leave gaps between chunks (#408)
(56455e0)Previously the layout used the floor of the calculated start and width as the value to use for the split Rects. This resulted in gaps between the split rects. This change modifies the layout to round to the nearest column instead of taking the floor of the start and width. This results in the start and end of each rect being rounded the same way and being strictly adjacent without gaps. Because there is a required constraint that ensures that the last end is equal to the area end, there is no longer the need to fixup the last item width when the fill (as e.g. width = x.99 now rounds to x+1 not x). The colors example has been updated to use Ratio(1, 8) instead of Percentage(13), as this now renders without gaps for all possible sizes, whereas previously it would have left odd gaps between columns. -
(layout) Ensure left <= right (#410)
(f4ed3b7)The recent refactor missed the positive width constraint -
(release) Fix the last tag retrieval for alpha releases (#416)
(b6b2da5) -
(release) Set the correct permissions for creating alpha releases (#400)
(778c320) -
(scrollbar) Move symbols to symbols module (#330)
(7539f77) [breaking]The symbols and sets are moved from `widgets::scrollbar` to `symbols::scrollbar`. This makes it consistent with the other symbol sets and allows us to make the scrollbar module private rather than re-exporting it. -
(table) Fix unit tests broken due to rounding (#419)
(dc55211)The merge of the table unit tests after the rounding layout fix was not rebased correctly, this addresses the broken tests, makes them more concise while adding comments to help clarify that the rounding behavior is working as expected. -
(uncategorized) Correct minor typos in documentation (#331)
(13fb11a)
Refactor
-
(barchart) Reduce some calculations (#430)
(fc727df)Calculating the label_offset is unnecessary, if we just render the group label after rendering the bars. We can just reuse bar_y. -
(layout) Simplify and doc split() (#405)
(de25de0)* test(layout): add tests for split() * refactor(layout): simplify and doc split() This is mainly a reduction in density of the code with a goal of improving mainatainability so that the algorithm is clear. -
(layout) Simplify split() function (#396)
(5195099)Removes some unnecessary code and makes the function more readable. Instead of creating a temporary result and mutating it, we just create the result directly from the list of changes.
Documentation
-
(examples) Fix the instructions for generating demo GIF (#442)
(7a70602) -
(examples) Show layout constraints (#393)
(10dbd6f)Shows the way that layout constraints interact visually  -
(examples) Add color and modifiers examples (#345)
(6ad4bd4)The intent of these examples is to show the available colors and modifiers. - added impl Display for Color   -
(examples) Update block example (#351)
(554805d) -
(examples) Add examples readme with gifs (#303)
(add578a)This commit adds a readme to the examples directory with gifs of each example. This should make it easier to see what each example does without having to run it. I modified the examples to fit better in the gifs. Mostly this was just removing the margins, but for the block example I cleaned up the code a bit to make it more readable and changed it so the background bug is not triggered. For the table example, the combination of Min, Length, and Percent constraints was causing the table to panic when the terminal was too small. I changed the example to use the Max constraint instead of the Length constraint. The layout example now shows information about how the layout is constrained on each block (which is now a paragraph with a block). -
(layout::Constraint) Add doc-comments for all variants (#371)
(c8ddc16) -
(lib) Extract feature documentation from Cargo.toml (#438)
(8b36683)* docs(lib): extract feature documentation from Cargo.toml * chore(deps): make `document-features` optional dependency * docs(lib): document the serde feature from features section -
(project) Make the project description cooler (#441)
(47fe4ad)* docs(project): make the project description cooler * docs(lib): simplify description -
(readme) Fix widget docs links (#346)
(2920e04)Add scrollbar, clear. Fix Block link. Sort -
(uncategorized) Improve scrollbar doc comment (#329)
(c3f87f2)
Performance
-
(bench) Used
iter_batchedto clone widgets in setup function (#383)
(149d489)Replaced `Bencher::iter` by `Bencher::iter_batched` to clone the widget in the setup function instead of in the benchmark timing.
Styling
-
(paragraph) Add documentation for "scroll"'s "offset" (#355)
(ab5e616)* style(paragraph): add documentation for "scroll"'s "offset" * style(paragraph): add more text to the scroll doc-comment
Testing
-
(block) Add benchmarks (#368)
(e18393d)Added benchmarks to the block widget to uncover eventual performance issues -
(canvas) Add unit tests for line (#437)
(ad3413e)Also add constructor to simplify creating lines -
(list) Added benchmarks (#377)
(664fb4c)Added benchmarks for the list widget (render and render half scrolled) -
(sparkline) Added benchmark (#384)
(3293c6b)Added benchmark for the `sparkline` widget testing a basic render with different amount of data -
(styled_grapheme) Test StyledGrapheme methods (#433)
(292a11d) -
(table) Add test for consistent table-column-width (#404)
(4cd843e) -
(test_backend) Add tests for TestBackend coverage (#434)
(b35f19e)These are mostly to catch any future bugs introduced in the test backend
Miscellaneous Tasks
-
(changelog) Show full commit message (#423)
(a937500)This allows someone reading the changelog to search for information about breaking changes or implementation of new functionality. - refactored the commit template part to a macro instead of repeating it - added a link to the commit and to the release - updated the current changelog for the alpha and unreleased changes - Automatically changed the existing * lists to - lists -
(codecov) Fix yaml syntax (#407)
(ea48af1)a yaml file cannot contain tabs outside of strings -
(docs) Add doc comment bump to release documentation (#382)
(8b28672) -
(github) Rename
tui-rs-revivalreferences toratatui-org(#340)
(964190a) -
(make) Add task descriptions to Makefile.toml (#398)
(268bbed) -
(toolchain) Bump msrv to 1.67 (#361)
(8cd3205) [breaking]* chore(toolchain)!: bump msrv to 1.67 -
(traits) Add Display and FromStr traits (#425)
(98155dc)Use strum for most of these, with a couple of manual implementations, and related tests -
(uncategorized) Use vhs to create demo.gif (#390)
(8c55158)The bug that prevented braille rendering is fixed, so switch to VHS for rendering the demo gif  -
(uncategorized) Implement
Hashcommon traits (#381)
(8c4a2e0)Reorder the derive fields to be more consistent: Debug, Default, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash Hash trait won't be impl in this PR due to rust std design. If we need hash trait for f64 related structs in the future, we should consider wrap f64 into a new type. -
(uncategorized) Implement
Eq & PartialEqcommon traits (#357)
(181706c)Reorder the derive fields to be more consistent: Debug, Default, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash -
(uncategorized) Implement
Clone & Copycommon traits (#350)
(440f62f)Implement `Clone & Copy` common traits for most structs in src. Only implement `Copy` for structs that are simple and trivial to copy. Reorder the derive fields to be more consistent: Debug, Default, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash -
(uncategorized) Implement
Debug & Defaultcommon traits (#339)
(bf49446)Implement `Debug & Default` common traits for most structs in src. Reorder the derive fields to be more consistent: Debug, Default, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash
Build
-
(examples) Fix cargo make run-examples (#327)
(e2cb11c)Enables the all-widgets feature so that the calendar example runs correctly -
(uncategorized) Forbid unsafe code (#332)
(0fb1ed8)This indicates good (high level) code and is used by tools like cargo-geiger.
Continuous Integration
-
(coverage) Exclude examples directory from coverage (#373)
(de9f52f) -
(uncategorized) Don't fail fast (#364)
(9191ad6)Run all the tests rather than canceling when one test fails. This allows us to see all the failures, rather than just the first one if there are multiple. Specifically this is useful when we have an issue in one toolchain or backend.
Contributors
Thank you so much to everyone that contributed to this release!
Here is the list of contributors who have contributed to ratatui for the first time!
- @EdJoPaTo
- @mhovd
- @joshrotenberg
- @t-nil
- @ndd7xv
- @TieWay59
- @Valentin271
- @hasezoey
- @jkcdarunday
- @stappersg
- @benjajaja
Special thanks to Florian Dehau for creating this awesome library 💖 We don't see how this would be possible without him in the first place.
