Ratatui-widgets

ratatui-widgets is a Rust crate with extra widgets for Ratatui.

Installation

cargo add ratatui-widgets

Usage

// TODO: Add usage examples

Example

Status

This README sets up an initial goal for a library of widgets to supplement Ratatui. This library will release breaking changes regularly - move fast and break things. A focus on fast delivery rather than gating on perfection is key here. Expect to see releases anytime a feature is changed or added. Release-plz will keep the version updated with respect to semver and will update the CHANGELOG with information from every PR.

This is not (yet?) an official Ratatui-org project, but may be at some point in the future.

Features

• Basic event handling abstraction and keyboard / mouse handling

• Basic buttons

  let button = Button::new("Click me");
  

• Stack container that handles widgets and layouts

  let stack = StackContainer::horizontal().with_widgets(vec![
      (Box::new(Line::raw("Left")), Constraint::Fill(1)),
      (Box::new(Text::raw("Center")), Constraint::Fill(1)),
      (Box::new(Span::raw("Right")), Constraint::Fill(1)),
  ]);
  

TODO

Most of this list of widgets from https://en.wikipedia.org/wiki/Graphical_widget#List_of_common_generic_widgets

• Create an abstraction over the backend events to an event type for mouse and keyboard events
  • Crossterm
  • Termion
  • Termwiz
  • Consider how to handle non mouse / keyboard events (resize, paste, focus, etc.)
• Support keyboard shortcuts / accellerators for buttons / menus etc.
• Consider supporting keyboard customization
• Support themes that apply to all the widgets (colors and modifiers)
• Decide on how to handle state (StatefulWidget vs other options)
• Decide on how to handle events that occur on click / change etc.
• Decide how to handle internal state (focus, hover)
• Decide how to handle focus order / selection
• Decide how containers work generally
• Buttons
  • Button [Submit]
  • Radio Button (*) item ( ) item
  • Check Box [x] item
  • Toggle Switch <_ON_ / OFF >
  • Toggle Button [ON]
  • Split Button [Submit][↓]
  • Cycle Button [Red] => [Green] => [Blue]
• Slider [------------|---------------]
• List Box (low priority as there is already one in core)
• Spinner [123][+][-]
• Drop-down List [Selected Item][↓]
• Menu
  • Context Menu
  • Pie Menu (probably not worth it in the console, but perhaps there's uses for something similar)
• Menu Bar (https://crates.io/crates/tui-menu might be worth bringing in)
• Tool Bar (good for mouse UIs, bad for keyboard)
  • Ribbon (same)
• Combo Box [____________][↓]
• Icon (not sure what use we'd see out of this one)
• Tree View (https://crates.io/crates/tui-tree-widget)
• Tree map (not listed on wiki page, but https://crates.io/crates/tui-treemap)
• Grid View / DataGrid (similar to the built-in table, but we can do much more with this)
• Link <go here> (integrate with OSC 8)
• Tab (compared to the built-in Tabs, this would be a container widget)
• ScrollBar (built-in)
• Text Box (https://crates.io/crates/tui-textarea https://crates.io/crates/tui-input)
• Label (mostly the same as just a Paragraph, but links to another field)
• Tooltip (displayed underneath when field is focused - dim text etc.)
• Balloon help (similar to tooltip - perhaps this is a larger popup for help that has to be dismissed)
• Status Bar (Mostly useful for putting a background, and adding multiple elements that are auto spaced)
• Progress Bar (Gauge / Linegauge, but optimised for time / progress)
• Infobar - like a popup or flash element, but generally non modal, dismissable, top of screen
• Containers
  • Window (not sure we need this concept, but could be useful as a top-level idea)
  • Collapsible Panel - VSCode like panels
    • Drawers - related to panels - unsure where the distinction of this lies
  • Accordion - Vertically stacked list of items that can be expanded by selection
  • Modal Window - Popup that contains other elements
  • Dialog Box - Display info in a popup and wait for a response (https://crates.io/crates/tui-confirm-dialog https://crates.io/crates/tui-file-dialog)
  • Popup (not in wikipedia, https://crates.io/crates/tui-popup)
  • Palette Window / Utility Window - floating window with commands / buttons
  • Inspector Window - shows info about the selected item elsewhere (perhaps useful as a debugging tool)
  • Frame - Grouping mechanism - perhaps this is a border with a title and acts as a container
  • Canvas (built-in perhaps)
  • Cover flow - large selection usually with images / snapshots horizontal scroll
  • Bubble flow - discussion thread (example https://github.com/dustinblackman/oatmeal)
  • Carousel - Display Visual Cards - different from cover flow in that it displays multiple cards at once
  • Scrollview - not in the wikipedia article, but https://crates.io/crates/tui-scrollview
• Suggestions for other items welcome!

License

Copyright (c) 2024 Josh McKinney

This project is licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See CONTRIBUTING.md.