1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
//! # iocraft
//!
//! `iocraft` is a library for crafting beautiful text output and interfaces for the terminal or
//! logs. It allows you to easily build complex layouts and interactive elements using a
//! declarative API.
//!
//! ## Features
//!
//! - Define your UI using a clean, highly readable syntax.
//! - Organize your UI using flexbox layouts powered by [`taffy`](https://docs.rs/taffy/).
//! - Output colored and styled UIs to the terminal or ASCII output anywhere else.
//! - Create animated or interactive elements with event handling and hooks.
//! - Build fullscreen terminal applications with ease.
//! - Pass [props](crate::Props) and [context](crate::components::ContextProvider) by reference to avoid unnecessary cloning.
//!
//! ## Optional Features
//!
//! - `unstable-output-streams`: enables configuring the render stream and stdout/stderr handles for
//! render loops. Some crossterm operations bypass the provided writer and write directly to
//! stdout ([#652](https://github.com/crossterm-rs/crossterm/issues/652),
//! [#957](https://github.com/crossterm-rs/crossterm/pull/957),
//! [#1026](https://github.com/crossterm-rs/crossterm/pull/1026)).
//!
//! ## Getting Started
//!
//! If you're familiar with React, you'll feel right at home with `iocraft`. It uses all the same
//! concepts, but is text-focused and made for Rust.
//!
//! Here's your first `iocraft` program:
//!
//! ```
//! use iocraft::prelude::*;
//!
//! fn main() {
//! element! {
//! View(
//! border_style: BorderStyle::Round,
//! border_color: Color::Blue,
//! ) {
//! Text(content: "Hello, world!")
//! }
//! }
//! .print();
//! }
//! ```
//!
//! Your UI is composed primarily via the [`element!`] macro, which allows you to declare your UI
//! elements in a React/SwiftUI-like syntax.
//!
//! `iocraft` provides a few built-in components in the [`components`] module, such as
//! [`View`](crate::components::View), [`Text`](crate::components::Text), and
//! [`TextInput`](crate::components::TextInput), but you can also create your own using the
//! [`macro@component`] macro.
//!
//! For example, here's a custom component that uses a [hook](crate::hooks) to display a counter
//! which increments every 100ms:
//!
//! ```no_run
//! # use iocraft::prelude::*;
//! # use std::time::Duration;
//! #[component]
//! fn Counter(mut hooks: Hooks) -> impl Into<AnyElement<'static>> {
//! let mut count = hooks.use_state(|| 0);
//!
//! hooks.use_future(async move {
//! loop {
//! smol::Timer::after(Duration::from_millis(100)).await;
//! count += 1;
//! }
//! });
//!
//! element! {
//! Text(color: Color::Blue, content: format!("counter: {}", count))
//! }
//! }
//! ```
//!
//! ## More Examples
//!
//! There are many [examples on GitHub](https://github.com/ccbrown/iocraft/tree/main/examples)
//! which demonstrate various concepts such as tables, progress bars, full screen apps, forms, and
//! more!.
//!
//! ## Shoutouts
//!
//! `iocraft` was inspired by [Dioxus](https://github.com/DioxusLabs/dioxus) and
//! [Ink](https://github.com/vadimdemedes/ink), which you should also check out, especially if
//! you're building graphical interfaces or interested in using JavaScript/TypeScript.
//!
//! You may also want to check out [Ratatui](https://github.com/ratatui/ratatui), which serves a
//! similar purpose with a less declarative API.
// # Organization
//
// Code is organized into modules primarily for the benefit of the maintainers. Types will be
// re-exported in the root so that users of the library have a flat namespace to work with.
//
// The exception is the modules that represent collections of types, namely hooks and components.
// Those types will remain in their modules for the public API.
pub
pub
pub use *;
/// Re-exported [`taffy`] crate, which powers flexbox layout in `iocraft`.
///
/// This allows you to reference `taffy` types (e.g. [`taffy::Size`],
/// [`taffy::AvailableSpace`]) in your own code without adding a separate
/// `taffy` dependency to your `Cargo.toml`.
pub use taffy;
/// Components for crafting your UI.
/// By importing this module, you'll bring all of the crate's commonly used types into scope.
// So we can use our own macros.
extern crate self as iocraft;