intuituive/

lib.rs

//! intuiTUIve: a reactive, retained terminal UI framework built on rs-rich.
//!
//! You describe the screen once, as a tree of nodes, and keep your state in
//! [signals](signal). When a signal changes, the nodes that read it draw
//! again, and only the cells that changed are sent to the terminal. There
//! is no draw loop to write, no layout pass to call, and no "what changed"
//! to track.
//!
//! ```no_run
//! use intuituive::prelude::*;
//!
//! fn main() -> std::io::Result<()> {
//!     App::new(|| {
//!         let count = signal(0);
//!         column([
//!             text!("[b]Count:[/] {count}").panel("Counter"),
//!             label("[dim]+ adds one · q quits"),
//!         ])
//!         .on_key("+", move |_| count.update(|c| *c += 1))
//!         .on_key("q", |cx| cx.quit())
//!     })
//!     .run()
//! }
//! ```
//!
//! - **Nodes** ([`text`](fn@text), [`label`], [`renderable`], [`column`](fn@column), [`row`],
//!   [`grid`], [`each`], [`switch`], [`Node::panel`]) are built once and
//!   kept. Any rich renderable is a node: a `Table`, `Markdown`, `Syntax`, a
//!   chart.
//! - **Layout** sizes children by [`Size`] (fixed, percentage, flexible or
//!   their content), within minimums and maximums, with gaps and padding.
//! - **State** is [`signal`]s and [`memo`]s. Reading one while drawing
//!   subscribes the node; writing one redraws exactly its readers.
//! - **Input**: [`Node::on_key`] bindings bubble from the focused node up;
//!   Tab moves the focus; [`Node::on_click`] gets clicks, routed by the
//!   layout the last frame kept.
//! - **Screens**: [`Ctx::push`], [`Ctx::modal`] and [`Ctx::pop`] keep a
//!   stack of screens, each with its own state and focus.
//! - **Background work**: [`spawn`], [`spawn_future`] and [`resource`] run
//!   slow work off the app's thread and write signals with the result; a
//!   [`Proxy`] lets any thread do the same.
//! - **Themes**: [`Theme`] styles the framework's parts and names styles
//!   for markup; [`Ctx::set_theme`] switches at run time.
//! - **Inline**: [`App::inline`] runs in a few rows below the prompt
//!   instead of the alternate screen.
//! - **Responsive**: [`Node::hide_below`] and a stylesheet's `@media`
//!   rules follow the terminal's size; [`viewport`] reads it.
//! - **The outside world**, behind off-by-default features (plugins: the
//!   core stays generic): `audio::pcm` reads raw PCM a buffer at a time,
//!   `audio::play` plays it at its rate and `audio::Capture::simulated`
//!   stands in for a sound card in tests (`pcm`), `audio::input` captures
//!   a sound card into a signal
//!   (`audio`, with PulseAudio sources under `pulse`),
//!   `audio::wav` reads and records WAV files (`wav`), `watch_path` wakes
//!   the app when files change (`watch`), `image` draws an image file
//!   in half blocks (`art`), `meter`, `sparkline`, `spectrogram` and
//!   `bar_spectrum` show levels and spectra (`viz`), and `files` has a
//!   file manager's components: Miller columns, file lists, previews,
//!   background file jobs and a streaming finder (`files`).
//! - **Generic building blocks**: [`miller_of`] (Miller columns over any
//!   [`MillerSource`] tree), [`jobs`](fn@jobs) and [`jobs_panel`]
//!   (cancellable work with progress), [`fuzzy_list`] and [`finder_of`]
//!   (a fuzzy list over any stream of items), [`preview_of`] (a value
//!   loaded off the app's thread for the current key), [`multi_select`]
//!   (a selection by key with a visual range), [`list_search`] (find next
//!   and previous over a list), [`tab_set`](fn@tab_set) (tabs' states with one
//!   active), [`facts`] (a description list), [`digits`] (big digits
//!   in any build), and [`state`]'s files and [`FrecencyStore`] (an
//!   app's state between sessions). The core is generic only; the domain
//!   plugins above build on these.
//! - **Sprites and pixels**: [`sprite::stage`] draws [`sprite::Sprite`]s
//!   (cell art with transparent cells, animated on the app's clock) over a
//!   backdrop, with clicks, hovers and collisions by their cells;
//!   [`pixels::pixels`] is an RGBA framebuffer drawn in half blocks,
//!   quadrants or Braille, with blits, rectangles and lines. Plugins cut
//!   an image into sprites (`sprite_sheet`, behind `art`) and make
//!   rs-rich-micro's micro assets sprites (`micro_sprite`, behind `micro`).
//! - **Tests**: [`App::render_with`] and [`App::run_on`] with
//!   `rich-interact`'s headless driver run an app without a terminal;
//!   [`App::driver`] steps one, and [`assert_screen!`] compares its screen
//!   with a snapshot (see [`testing`]).
//!
//! The design, and how it compares with ratatui, is in
//! `docs/design/intuituive.md`.

// A builder method that returns `Self` is `#[must_use]`: dropping its
// result drops the value (CONTRIBUTING.md, "API conventions").
#![warn(clippy::return_self_not_must_use)]

pub mod a11y;
mod actions;
pub mod app;
#[cfg(feature = "pcm")]
pub mod audio;
#[cfg(feature = "art")]
pub mod banner;
mod bars;
#[cfg(feature = "art")]
mod big_text;
mod bindings;
pub mod border;
mod builtin;
mod calendar;
mod clock;
mod collapsible;
pub mod command_line;
mod commands;
pub mod complete;
mod controls;
mod datetime;
mod dialog;
mod diff_view;
mod digits;
mod editor_theme;
mod effect;
mod facts;
mod feed;
#[cfg(feature = "files")]
pub mod files;
pub mod finder;
mod float;
pub mod focus;
pub mod fx;
mod help;
mod hex;
#[cfg(feature = "art")]
mod image;
mod input;
pub mod inspect;
pub mod jobs;
pub mod layout;
mod list;
mod lockstep;
pub mod log;
#[cfg(feature = "syntax")]
mod markdown;
#[cfg(feature = "syntax")]
mod markdown_viewer;
pub mod menu;
#[cfg(feature = "micro")]
pub mod micro_sprite;
pub mod miller;
pub mod node;
mod node_list;
mod notify;
mod palette;
mod parity;
pub mod pixels;
mod place;
pub mod preview;
pub mod query;
pub mod reactive;
mod reorder;
mod rule;
pub mod screen;
mod scroll_virtual;
mod scrollbar;
pub mod select;
mod select_field;
mod sequence;
mod sheet;
mod signals;
mod solver;
pub mod source;
mod spinner;
mod split;
pub mod sprite;
#[cfg(feature = "art")]
pub mod sprite_sheet;
pub mod state;
pub mod tab_set;
mod table_scroll;
pub mod task;
pub mod testing;
mod text_area;
pub mod text_edit;
pub mod timedemo;
pub mod transport;
mod tree;
mod tree_table;
mod treemap;
#[cfg(feature = "vim")]
pub mod vim;
#[cfg(feature = "viz")]
mod viz;
#[cfg(feature = "watch")]
mod watch;
pub mod widget;
pub mod widgets;

/// rs-rich, for renderables, styles and markup helpers, so an app needs
/// only this crate as a dependency.
pub use rich;
/// rs-rich-interact, for its components (`interact::Input`,
/// `interact::Select`, …) and the headless test driver.
pub use rich_interact as interact;
/// Dates as people type them (`tomorrow`, `eow`, `3d`): rs-rich-interact's.
pub use rich_interact::dates;

pub use actions::{Action, action_overlay};
pub use app::DEFAULT_MODE;
pub use app::{
    Anchor, App, Ctx, Driver, Easing, FrameStats, Handoff, Holds, ModalOptions, Placement,
    StatsHandle, Theme, Timer, after, every, fixed_step, held_keys, plain_key, rate,
};
#[cfg(feature = "art")]
pub use big_text::big_text;
pub use bindings::{ModePage, Scaled, Stepped};
pub use border::{Border, BorderSet, Edge, Shadow, Sides};
pub use collapsible::{Status, collapsible, collapsible_with};
pub use command_line::{CommandLine, CommandLineOptions, command_line, command_line_with};
pub use commands::{Hit, HitSink, Provider, SystemCommands, Themes};
pub use complete::{
    CompleteOptions, Completion, InputHistory, complete_words, history_file, history_in,
    history_session,
};
pub use controls::{
    ButtonVariant, CheckState, button, button_of, checkbox, checkbox_of, checkbox_tri, radio,
    radio_keyed, slider, switch_of, switch_toggle,
};
pub use dialog::{ConfirmOptions, PickOptions, PromptOptions};
pub use digits::digits;
pub use editor_theme::EditorTheme;
pub use effect::{effect, fill};
pub use facts::{facts, facts_of};
pub use feed::{
    Feed, FeedEnd, FeedState, FeedTeller, Pace, Play, latest_feed, latest_iter, latest_with_state,
};
pub use finder::{FuzzyOptions, FuzzySource, finder_of, fuzzy_list, fuzzy_list_with};
pub use focus::Direction;
pub use fx::Fx;
pub use help::{HelpOptions, KeyFormat, KeyHintsOptions};
#[cfg(feature = "art")]
pub use image::{
    ImageAnchor, ImageFit, ImageMode, ImageView, Picture, Pixels, image, image_bytes,
    image_bytes_of, image_graphics, image_of, image_with, picture_bytes, picture_of, tiles_of,
};
pub use input::{input, number_input};
pub use jobs::{
    Job, JobOutcome, JobProgress, JobState, Jobs, JobsPanelOptions, ProcessOutcome, ProcessOutput,
    jobs, jobs_panel, jobs_panel_with,
};
pub use layout::{Align, AlignContent, Justify, Size, StackLayout, TextAlign};
pub use list::list_optional;
pub use lockstep::{Lockstep, Steps, stepped_worker, stepped_worker_with};
pub use log::Log;
#[cfg(feature = "syntax")]
pub use markdown::{MarkdownStream, markdown};
#[cfg(feature = "syntax")]
pub use markdown_viewer::{MarkdownHeading, MarkdownViewer, markdown_viewer};
pub use miller::{MillerSource, miller_in, miller_of};
pub use node::{
    Node, column, component, each, fit_text, grid, keyed, label, layers, leaf, list, renderable,
    repeating, row, scroll, scroll_both, scroll_both_with, scroll_with, scroll_x, switch, text,
};
pub use node::{described, drawn, drawn_described};
pub use node_list::{list_of, list_of_virtual};
pub use notify::{Corner, Level};
pub use palette::Palette;
pub use parity::{
    PlaceholderVariant, header, key_panel, link, masked_input, placeholder, progress_bar,
};
pub use place::{Offset, Origin, RectHandle};
pub use preview::{PreviewOfOptions, preview_of, preview_of_with};
pub use reactive::{Memo, Proxy, Signal, memo, on_write, on_write_ref, signal, viewport, watch};
/// What a text does with what does not fit a line: rich's.
pub use rich::Overflow;
pub use rule::rule;
pub use screen::{PaintStats, PaintStrategy};
pub use scroll_virtual::{scroll_virtual, scroll_virtual_with};
pub use select::{ListSearch, Mark, MultiSelect, list_search, multi_select};
pub use select_field::{SelectOption, select_field, select_field_keyed};
pub use sheet::{SheetError, Stylesheet};
pub use signals::{Count, History, falling, history, recent, recent_of, recent_timed, smoothed};
pub use solver::Solver;
pub use spinner::spinner;
pub use state::{
    FrecencyStore, frecency_in, frecency_session, frecency_store, read_state, state_dir,
    state_file, update_file, update_state, write_atomic, write_state,
};
pub use tab_set::{Scoped, TabSet, tab_set, tabs_for, tabs_for_indexed};
pub use task::{
    Latest, Load, Notifier, Resource, Stream, Task, latest, latest_every, resource, resource_for,
    spawn, spawn_future, spawn_stream, spawn_then,
};
pub use text_area::Caret;
pub use text_edit::{TextSearch, search_bar};
pub use transport::{Transport, transport};
pub use treemap::{TreemapOptions, treemap, treemap_with};
#[cfg(feature = "viz")]
pub use viz::{
    bar_spectrum, bar_spectrum_with, meter, meter_with, persistence, persistence_with, sparkline,
    sparkline_with, spectrogram, spectrogram_with, tuner,
};
#[cfg(feature = "watch")]
pub use watch::{
    ChangeKind, PathChange, PathEvent, PathWatch, WatchOptions, watch_path, watch_path_with,
};
pub use widget::{Widget, widget};
pub use widgets::text_area;

/// Everything an app usually needs.
pub mod prelude {
    // `text` is both the function and the `text!` macro.
    pub use crate::{
        Align, App, Border, Ctx, Edge, Justify, Load, Log, Memo, Node, Overflow, Proxy, Resource,
        Shadow, Sides, Signal, Size, Task, TextAlign, Theme, Timer, Widget, after, column,
        component, each, effect, every, fill, fixed_step, grid, input, keyed, label, latest,
        latest_every, layers, leaf, list, list_optional, memo, number_input, on_write,
        on_write_ref, rate, renderable, repeating, resource, resource_for, row, scroll,
        scroll_both, scroll_virtual, scroll_with, scroll_x, signal, spawn, switch, text, text_area,
        viewport, watch, widget,
    };
    pub use crate::{described, drawn, drawn_described};
}

/// Console markup with `format!` arguments, read again whenever a signal it
/// names changes: `text!("{count} items")`. Signals format as their value.
#[macro_export]
macro_rules! text {
    ($($arg:tt)*) => {
        $crate::node::text(move || format!($($arg)*))
    };
}

impl<T: std::fmt::Display + 'static> std::fmt::Display for Signal<T> {
    /// The value, subscribing the node that is drawing.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.with(|value| value.fmt(f))
    }
}

impl<T: std::fmt::Display + 'static> std::fmt::Display for Memo<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.with(|value| value.fmt(f))
    }
}