According to the issue linked from Cargo.toml, the intention has been to
manually upgrade unicode-width every now and then, after verifying that
the new version does not disrupt Ratatui. See
https://github.com/ratatui/ratatui/issues/1271#issuecomment-2373917195.
This PR unblocks using Ratatui in a dependency graph where some other
crate requires some of the fixes that landed in unicode-width 0.2.1.
Without this PR, Cargo blocks Ratatui from being used.
```console
error: failed to select a version for `unicode-width`.
... required by package `ratatui v0.29.0`
... which satisfies dependency `ratatui = "^0.29"` of package `cargo v0.91.0`
... which satisfies path dependency `cargo` (locked to 0.91.0) of package `repro v0.0.0`
versions that meet the requirements `=0.2.0` are: 0.2.0
all possible versions conflict with previously selected packages.
previously selected package `unicode-width v0.2.1`
... which satisfies dependency `unicode-width = "^0.2.1"` of package `cargo v0.91.0`
... which satisfies path dependency `cargo` (locked to 0.91.0) of package `repro v0.0.0`
failed to select a version for `unicode-width` which could resolve this conflict
```
Resolves https://github.com/ratatui/ratatui/issues/1951
BREAKING CHANGE: Old `Flex::SpaceAround` behavior is available by using
`Flex::SpaceEvenly` and new
`Flex::SpaceAround` now distributes space evenly around each element
except the middle spacers
are twice the size of first and last elements
With this change, the following variants of `Flex` are supported:
- `Flex::Start`: Aligns items to the start; excess space appears at the
end.
- `Flex::End`: Aligns items to the end; excess space appears at the
start.
- `Flex::Center`: Centers items with equal space on both sides.
- `Flex::SpaceAround` (**new**): Distributes space _around_ items; space
between items is _twice_ the edge spacing.
- `Flex::SpaceBetween`: Distributes space _evenly between_ items except
no space at the edges.
- `Flex::SpaceEvenly` (**previously `Flex::SpaceAround`**): Distributes
space _evenly between_ items and edges.
- `Flex::Legacy`: Preserves legacy behavior, placing all excess space at
the end.
This aligns behavior of `Flex` with CSS flexbox more closely.
The following is a screenshot in action:
<img width="1090" alt="image"
src="https://github.com/user-attachments/assets/2c7cd797-27bd-4242-a824-4565d369227b"
/>
---------
Co-authored-by: Jagoda Estera Ślązak <128227338+j-g00da@users.noreply.github.com>
The title alignment is better expressed in the `Line` as this fits more
coherently with the rest of the library.
BREAKING CHANGES:
- `widgets::block` is no longer exported
- `widgets::block::Title` no longer exists
- `widgets::block::Position` is now `widgets::TitlePosition`
- `Block::title()` now accepts `Into::<Line>` instead of `Into<Title>`
- `BlockExt` is now exported at widgets::`BlockExt`
Closes: https://github.com/ratatui/ratatui/issues/738
This makes it possible to create constants using the shorthand methods.
```rust
const MY_STYLE: Style = Style::new().blue().on_black();
```
Rather than implementing Styled for Style and then adding extension
methods that implement the Stylize shorthands, this implements the
methods as const functions directly on Style.
BREAKING CHANGE: `Style` no longer implements `Styled`. Any calls to
methods implemented by the blanket implementation of Stylize are now
defined directly on Style. Remove the Stylize import if it is no longer
used by your code.
The `reset()` method does not have a direct replacement, as it clashes
with the existing `reset()` method. Use `Style::reset()` rather than
`some_style.reset()`
Fixes: #1158
Some corrections and added details to BREAKING-CHANGES.md.
I decided to remove:
- `Backend` now uses `Self::Error` for error handling instead of
`std::io::Error`
- `Terminal<B>` now uses `B::Error` for error handling instead of
`std::io::Error`
...as we are still using `std::io::Error` in built-in backends, so this
will only be breaking if a third-party backend decides to use a custom
error other than `std::io::Error`, which would be a breaking change in
downstream and not `ratatui`.
The exception to that is `TestBackend`, which uses `Infallible`, but
this already has its own breaking changes entry.
Resolves#1780
BREAKING CHANGE: Disabling `default-features` will now disable layout
cache, which can have a negative impact on performance.
`Layout::init_cache` and `Layout::DEFAULT_CACHE_SIZE` are now only
available if `layout-cache` feature is enabled.
Resolves#1775
BREAKING CHANGE: Custom backends now have to implement `Backend::Error`
and `Backend::clear_region`. Additionally some generic `Backend` usage
will have to explicitly set trait bounds for `Backend::Error`.
We don't anticipate removing or deprecating the type alias in the near
future, but it is recommended to update your imports to use the new
name.
Added a VerticalAlignment enum to make the API more consistent. We don't
have a specific use case for it yet, but it's better to add it now and
be able to use it in the future.
BREAKING-CHANGE: The `Alignment` enum has been renamed to
`HorizontalAlignment` to better reflect its purpose. A type alias has
been added to maintain backwards compatibility, however there are some
cases where type aliases are not enough to maintain backwards
compatibility. E.g. when using glob imports to import all the enum
variants. This should not affect most users, but it is recommended to
update your imports to use the new name.
```diff
- use ratatui::layout::Alignment;
+ use ratatui::layout::HorizontalAlignment;
- use Alignment::*;
+ use HorizontalAlignment::*;
```
Allow styling for `List`'s highlight symbol
This change makes it so anything that implements `Into<Line>` can be
used as a highlight symbol.
BREAKING CHANGE: `List::highlight_symbol` can no longer be used in const
context
BREAKING CHANGE: `List::highlight_symbol` accepted `&str`. Conversion
methods that rely on type inference will need to be rewritten as the
compiler cannot infer the type.
closes: https://github.com/ratatui/ratatui/issues/1443
---------
Co-authored-by: Josh McKinney <joshka@users.noreply.github.com>
Based on the last several [termwiz
commits](https://github.com/wezterm/wezterm/commits/main/termwiz), it
looks like this release has a few fixes for hyperlinks and input
handling, plus some dependency updates.
Tested with the demo app to ensure things still work.
---------
Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
- Move Terminal, TerminalOptions, ViewPort, CompletedFrame, Frame to
ratatui-core crate
- Move render_widget_ref() and render_stateful_widget_ref() to extension
trait (FrameExt) due as the Ref types are unstable and kept in the
main lib instead of -core
- Fix rustdoc errors / feature config issues
BREAKING CHANGE: to call `Frame::render_widget_ref()` or
`Frame::render_stateful_widget_ref()` you now need to import the
FrameExt trait from `ratatui::widgets` and enable the
`unstable-widget-ref` feature.
Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
These are less stable than the non-ref traits as we have not yet
committed to the exact API. This change moves them to ratatui from
ratatui-core.
To facilitate this:
- implementations of WidgetRef for all internal widgets are removed and
replaced with implementations of Widget for references to those
widgets.
- Widget is now implemented for Option<W> where W: Widget, allowing for
rendering of optional widgets.
- The blanket implementation of Widget for WidgetRef is reversed, to be
a blanket implementation of WidgetRef for all &W where W: Widget.
BREAKING CHANGE: implementations of WidgetRef no longer have a blanket
implementation of Widget, so Widgets should generally implement the
Widget trait on a reference to the widget rather than implementing
WidgetRef directly. This has the advantage of not requiring unstable
features to be enabled.
Part of: https://github.com/ratatui/ratatui/issues/1388
Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
The buffer, layout, style, symbols, text, and the top level of widgets
modules are moved to ratatui-core. This is the first step in
modularizing the library so that the core types can be used in other
projects without the need for the backend / widgets types.
This helps reduce the need for updating other crates as often due to
semver changes outside of the core types.
---------
Co-authored-by: Orhun Parmaksız <orhun@archlinux.org>
Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
Adds two traits `IntoCrossterm` and `FromCrossterm` for converting
between ratatui and crossterm types. This is necessary in order to avoid
the orphan rule when implementing `From` for crossterm types once the
crossterm types are moved to a separate crate.
Similarly Termwiz and Termwiz gain FromTermion, IntoTermion, FromTermwiz
and IntoTermwiz traits.
BREAKING CHANGE: The `From` and `Into` impls for backend types are now
replaced
with specific backend traits.
```diff
+ use ratatui::backend::{FromCrossterm, IntoCrossterm};
let crossterm_color = crossterm::style::Color::Black;
- let ratatui_color = crossterm_color.into();
- let ratatui_color = ratatui::style::Color::from(crossterm_color);
+ let ratatui_color = ratatui::style::Color::from_crossterm(crossterm_color);
- let crossterm_color = ratatui_color.into();
- let crossterm_color = crossterm::style::Color::from(ratatui_color);
+ let crossterm_color = ratatui_color.into_crossterm();
let crossterm_attribute = crossterm::style::types::Attribute::Bold;
- let ratatui_modifier = crossterm_attribute.into();
- let ratatui_modifier = ratatui::style::Modifier::from(crossterm_attribute);
+ let ratatui_modifier = ratatui::style::Modifier::from_crossterm(crossterm_attribute);
- let crossterm_attribute = ratatui_modifier.into();
- let crossterm_attribute = crossterm::style::types::Attribute::from(ratatui_modifier);
+ let crossterm_attribute = ratatui_modifier.into_crossterm();
```
Similar conversions for `ContentStyle` -> `Style` and `Attributes` ->
`Modifier` exist for Crossterm,
and all the Termion and Termwiz types.
---------
Co-authored-by: Orhun Parmaksız <orhun@archlinux.org>
- distingiush between empty bars and bars with a value of 0
- provide custom styling for empty bars
- provide custom styling for individual bars
- inverts the rendering algorithm to be item first
Closes: #1325
BREAKING CHANGE: `Sparkline::data` takes `IntoIterator<Item = SparklineBar>`
instead of `&[u64]` and is no longer const
Co-authored-by: Josh McKinney <joshka@users.noreply.github.com>
BREAKING CHANGE: The Rect Positions iterator no longer has public
fields. The `rect` and `current_position` fields have been made private
as they were not intended to be accessed directly.
BREAKING-CHANGE: Previously `Color::from_hsl` accepted components
as individual f64 parameters. It now accepts a single `palette::Hsl`
value
and is gated behind a `palette` feature flag.
```diff
- Color::from_hsl(360.0, 100.0, 100.0)
+ Color::from_hsl(Hsl::new(360.0, 100.0, 100.0))
```
Fixes: <https://github.com/ratatui/ratatui/issues/1414>
---------
Co-authored-by: Josh McKinney <joshka@users.noreply.github.com>
BREAKING-CHANGE: The `pub` modifier has been removed from fields on the
`layout::rect::Columns` and `layout::rect::Rows` iterators. These fields
were not intended to be public and should not have been accessed
directly.
Fixes: #1357
This change fixes the unexpected behavior of the Rect::new() function to
be more intuitive. The Rect::new() function now clamps the width and
height of the rectangle to keep each bound within u16::MAX. The
Rect::area() function now returns a u32 instead of a u16 to allow for
larger areas to be calculated.
Previously, the Rect::new() function would clamp the total area of the
rectangle to u16::MAX, by preserving the aspect ratio of the rectangle.
BREAKING CHANGE: Rect::area() now returns a u32 instead of a u16.
Fixes: <https://github.com/ratatui/ratatui/issues/1375>
Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
BREAKING-CHANGES: `Line` now implements `From<Cow<str>`
As this adds an extra conversion, ambiguous infered values may no longer
compile.
```rust
// given:
struct Foo { ... }
impl From<Foo> for String { ... }
impl From<Foo> for Cow<str> { ... }
let foo = Foo { ... };
let line = Line::from(foo); // now fails due to ambiguous type inference
// replace with
let line = Line::from(String::from(foo));
```
Fixes: https://github.com/ratatui/ratatui/issues/1367
---------
Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
`Tabs::select()` now accepts `Into<Option<usize>>` instead of `usize`.
This allows tabs to be deselected by passing `None`.
`Tabs::default()` is now also implemented manually instead of deriving
`Default`, and a new method `Tabs::titles()` is added to set the titles
of the tabs.
Fixes: <https://github.com/ratatui/ratatui/pull/1412>
BREAKING CHANGE: `Tabs::select()` now accepts `Into<Option<usize>>`
which breaks any code already using parameter type inference:
```diff
let selected = 1u8;
- let tabs = Tabs::new(["A", "B"]).select(selected.into())
+ let tabs = Tabs::new(["A", "B"]).select(selected as usize)
```
Fixes https://github.com/ratatui-org/ratatui/issues/1250
Adds support for selecting a column and cell in `TableState`. The
selected column, and cells style can be set by
`Table::column_highlight_style` and `Table::cell_highlight_style`
respectively.
The table example has also been updated to display the new
functionality:
https://github.com/user-attachments/assets/e5fd2858-4931-4ce1-a2f6-a5ea1eacbecc
BREAKING CHANGE: The Serialized output of the state will now include the
"selected_column" field. Software that manually parse the serialized the
output (with anything other than the `Serialize` implementation on
`TableState`) may have to be refactored if the "selected_column" field
is not accounted for. This does not affect users who rely on the
`Deserialize`, or `Serialize` implementation on the state.
BREAKING CHANGE: The `Table::highlight_style` is now deprecated in favor
of `Table::row_highlight_style`.
---------
Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
The new methods return/accept `Into<Position>` which can be either a Position or a (u16, u16) tuple.
```rust
backend.set_cursor_position(Position { x: 0, y: 20 })?;
let position = backend.get_cursor_position()?;
terminal.set_cursor_position((0, 20))?;
let position = terminal.set_cursor_position()?;
```
This is a simplification of the public API that is helpful for new users
that are not familiar with how rust re-exports work, and helps avoid
clashes with other modules in the backends that are named terminal.
BREAKING CHANGE: The `terminal` module is now private and can not be
used directly. The types under this module are exported from the root of
the crate.
```diff
- use ratatui::terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, ViewPort};
+ use ratatui::{CompletedFrame, Frame, Terminal, TerminalOptions, ViewPort};
```
Fixes: https://github.com/ratatui-org/ratatui/issues/1210
Layout::init_cache no longer returns bool and takes a NonZeroUsize instead of usize
The cache is a thread-local, so doesn't make much sense to require
synchronized initialization.
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.
Updates the requirements on termion to permit the latest version.
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
</details>
BREAKING CHANGE: Changelog:
<https://gitlab.redox-os.org/redox-os/termion/-/blob/master/CHANGELOG.md>
A change is only necessary if you were matching on all variants of the
`MouseEvent` enum without a
wildcard. In this case, you need to either handle the two new variants,
`MouseLeft` and
`MouseRight`, or add a wildcard.
Co-authored-by: Josh McKinney <joshka@users.noreply.github.com>
