kova_native/lib.rs
1//! Kova Native: a GPU-accelerated, Rust-first native GUI framework.
2//!
3//! The facade connects the existing platform, retained element tree and GPU
4//! renderer. Use [`prelude`] for element builders and [`Application`] to run
5//! them in a native window.
6//!
7//! Kova Native draws a retained UI through wgpu, solves layout with Taffy, and
8//! shapes Unicode text with cosmic-text. Applications use Rust elements,
9//! callbacks and signals. Windows and input are provided by the native platform
10//! layer; there is no browser runtime.
11//!
12//! # Quick start
13//!
14//! Add the facade package to your application's manifest:
15//!
16//! ```toml
17//! [dependencies]
18//! kova-native = "0.3.1"
19//! ```
20//!
21//! The package name uses hyphens; the Rust import is `kova_native`.
22//! This example opens a window with a reactive counter:
23//!
24//! ```no_run
25//! use kova_native::prelude::*;
26//!
27//! fn main() -> KovaResult<()> {
28//! let owner = Owner::new_root();
29//! let count = owner.with(|| signal(0_u32));
30//! let result = Application::new()
31//! .title("Kova Native counter")
32//! .size(640.0, 420.0)
33//! .run(move || {
34//! column().center().gap(16.0)
35//! .child(text(move || format!("Count: {}", count.get())))
36//! .child(button("Increment")
37//! .on_click(move |_| count.update(|value| *value += 1)))
38//! });
39//! owner.dispose();
40//! result.map(|_| ())
41//! }
42//! ```
43//!
44//! Run native applications on the main thread. They need a windowing session
45//! and a supported GPU backend. Window dimensions and layout lengths are logical
46//! pixels; the platform's scale factor controls glyph rasterization and GPU output.
47//!
48//! # State and invalidation
49//!
50//! The reactive runtime is owned by the UI thread. [`core::Owner`] scopes signals,
51//! effects and cleanup. Keep application state outside the root builder when it
52//! must survive a rebuild, as in the counter above.
53//!
54//! Where a signal is read determines the work it invalidates:
55//!
56//! | Read location | Result |
57//! | --- | --- |
58//! | A [`text`][widgets::elements::text] closure | Update that text node |
59//! | A [`bind`][widgets::Interactive::bind] style closure | Update the node's style and invalidate affected layout or paint |
60//! | A [`dynamic`][widgets::elements::dynamic] builder | Rebuild that region's children |
61//! | The builder passed to [`Application::run`] | Rebuild the root region |
62//!
63//! Reads outside a tracked callback do not subscribe a UI node. Use
64//! [`core::batch`] to coalesce changes, and [`core::memo`] for derived state.
65//! Region-owned state is disposed when that region is rebuilt or removed.
66//!
67//! # Elements, layout and events
68//!
69//! Start with [`widgets::elements::row`], [`widgets::elements::column`],
70//! [`widgets::elements::stack`] and [`widgets::elements::div`]. The
71//! [`widgets::Styled`] trait adds sizing, spacing, fills, borders and shadows.
72//! [`widgets::Interactive`] adds reactive bindings, callbacks, actions and transitions. The
73//! [`widgets::widgets`] module provides buttons, checkboxes, switches, sliders
74//! and progress bars. [`prelude`] imports this common vocabulary.
75//!
76//! [`Application::key_bindings`] registers shortcuts in the existing action
77//! system. Handle actions on elements with [`widgets::Interactive::on_action`].
78//! Keyboard dispatch follows the focus path; pointer dispatch uses hit testing,
79//! capture and bubbling through the retained element tree.
80//!
81//! Use [`Application::on_file_drop`] to receive paths dragged from the desktop
82//! onto the window. The callback runs once for each dropped file:
83//!
84//! ```no_run
85//! use kova_native::prelude::*;
86//! use std::path::PathBuf;
87//!
88//! fn main() -> KovaResult<()> {
89//! let owner = Owner::new_root();
90//! let dropped_path = owner.with(|| signal(String::from("Drop a file here")));
91//! let result = Application::new()
92//! .on_file_drop({
93//! let dropped_path = dropped_path.clone();
94//! move |path: PathBuf| dropped_path.set(path.display().to_string())
95//! })
96//! .run(move || text(move || dropped_path.get()));
97//! owner.dispose();
98//! result.map(|_| ())
99//! }
100//! ```
101//!
102//! `widgets::elements::img_bind` updates a mounted image when its signal changes,
103//! preserving the image element. Use `.on_pen(...)` on an element to receive
104//! pressure-aware pointer events, and `.on_close_request(...)` on the application
105//! to accept or cancel an attempt to close its window.
106//!
107//! # Subsystems
108//!
109//! The facade re-exports the existing library crates. Use these modules when
110//! implementing custom elements or working directly with the frame pipeline:
111//!
112//! | Module | Responsibility |
113//! | --- | --- |
114//! | [`crate::core`] | Geometry, colors, identifiers, reactive state and dirty flags |
115//! | [`crate::widgets`] | Elements, styling, themes, retained tree and event dispatch |
116//! | [`crate::layout`] | Flexbox, grid, constraints and incremental layout |
117//! | [`crate::text`] | Unicode shaping, font fallback, wrapping and glyph rasterization |
118//! | [`crate::render`] | GPU context, scene commands, batching, atlases and effects |
119//! | [`crate::assets`] | Image and SVG loading, rasterization and caching |
120//! | [`crate::input`] | Events, keystrokes, actions and keymaps |
121//! | [`crate::animation`] | Tweens, easing, springs and property transitions |
122//! | [`crate::platform`] | Native windows, event loop, clipboard and IME hooks |
123//!
124//! # Examples and current scope
125//!
126//! The repository's [showcase](https://github.com/v3nn7/Kova-native/tree/main/examples/showcase)
127//! exercises the same element tree, text system and renderer used by applications.
128//! It includes native smoke runs and GPU captures. See the
129//! [README](https://github.com/v3nn7/Kova-native#readme) for launch commands.
130//!
131//! The API is experimental. `text_input` provides single-line editing with
132//! selection, clipboard, undo and IME composition; multi-line editing,
133//! accessibility, arbitrary masks and custom shader registration are still
134//! pending. The
135//! [repository audit](https://github.com/v3nn7/Kova-native/blob/main/docs/AUDIT.md)
136//! records the implemented subsystems and validation boundaries.
137
138mod application;
139#[cfg(feature = "record")]
140pub mod record;
141
142pub use application::{Application, RunReport, WindowOptions};
143pub use kova_native_animation as animation;
144pub use kova_native_assets as assets;
145pub use kova_native_core as core;
146pub use kova_native_input as input;
147pub use kova_native_layout as layout;
148pub use kova_native_platform as platform;
149pub use kova_native_render as render;
150pub use kova_native_text as text;
151pub use kova_native_widgets as widgets;
152
153/// Common application and element-building vocabulary.
154pub mod prelude {
155 pub use crate::{Application, RunReport, WindowOptions};
156 pub use kova_native_animation::{
157 Animated, Animation, Easing, Lerp, Repeat, Spring, Transition,
158 };
159 pub use kova_native_assets::{ImageData, SvgData};
160 pub use kova_native_core::*;
161 pub use kova_native_input::{
162 Action, Key, KeyBinding, Keystroke, Modifiers, NamedKey, PenEvent, PenPhase, actions,
163 };
164 pub use kova_native_layout::{Length, Track, auto, pct, px, relative};
165 pub use kova_native_text::{FontStyle, FontWeight, LineHeight, TextAlign, TextStyle, TextWrap};
166 pub use kova_native_widgets::headless::Headless;
167 pub use kova_native_widgets::icons;
168 pub use kova_native_widgets::prelude::*;
169}