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
158
159
160
161
162
163
164
165
166
167
168
169
//! Kova Native: a GPU-accelerated, Rust-first native GUI framework.
//!
//! The facade connects the existing platform, retained element tree and GPU
//! renderer. Use [`prelude`] for element builders and [`Application`] to run
//! them in a native window.
//!
//! Kova Native draws a retained UI through wgpu, solves layout with Taffy, and
//! shapes Unicode text with cosmic-text. Applications use Rust elements,
//! callbacks and signals. Windows and input are provided by the native platform
//! layer; there is no browser runtime.
//!
//! # Quick start
//!
//! Add the facade package to your application's manifest:
//!
//! ```toml
//! [dependencies]
//! kova-native = "0.3.1"
//! ```
//!
//! The package name uses hyphens; the Rust import is `kova_native`.
//! This example opens a window with a reactive counter:
//!
//! ```no_run
//! use kova_native::prelude::*;
//!
//! fn main() -> KovaResult<()> {
//! let owner = Owner::new_root();
//! let count = owner.with(|| signal(0_u32));
//! let result = Application::new()
//! .title("Kova Native counter")
//! .size(640.0, 420.0)
//! .run(move || {
//! column().center().gap(16.0)
//! .child(text(move || format!("Count: {}", count.get())))
//! .child(button("Increment")
//! .on_click(move |_| count.update(|value| *value += 1)))
//! });
//! owner.dispose();
//! result.map(|_| ())
//! }
//! ```
//!
//! Run native applications on the main thread. They need a windowing session
//! and a supported GPU backend. Window dimensions and layout lengths are logical
//! pixels; the platform's scale factor controls glyph rasterization and GPU output.
//!
//! # State and invalidation
//!
//! The reactive runtime is owned by the UI thread. [`core::Owner`] scopes signals,
//! effects and cleanup. Keep application state outside the root builder when it
//! must survive a rebuild, as in the counter above.
//!
//! Where a signal is read determines the work it invalidates:
//!
//! | Read location | Result |
//! | --- | --- |
//! | A [`text`][widgets::elements::text] closure | Update that text node |
//! | A [`bind`][widgets::Interactive::bind] style closure | Update the node's style and invalidate affected layout or paint |
//! | A [`dynamic`][widgets::elements::dynamic] builder | Rebuild that region's children |
//! | The builder passed to [`Application::run`] | Rebuild the root region |
//!
//! Reads outside a tracked callback do not subscribe a UI node. Use
//! [`core::batch`] to coalesce changes, and [`core::memo`] for derived state.
//! Region-owned state is disposed when that region is rebuilt or removed.
//!
//! # Elements, layout and events
//!
//! Start with [`widgets::elements::row`], [`widgets::elements::column`],
//! [`widgets::elements::stack`] and [`widgets::elements::div`]. The
//! [`widgets::Styled`] trait adds sizing, spacing, fills, borders and shadows.
//! [`widgets::Interactive`] adds reactive bindings, callbacks, actions and transitions. The
//! [`widgets::widgets`] module provides buttons, checkboxes, switches, sliders
//! and progress bars. [`prelude`] imports this common vocabulary.
//!
//! [`Application::key_bindings`] registers shortcuts in the existing action
//! system. Handle actions on elements with [`widgets::Interactive::on_action`].
//! Keyboard dispatch follows the focus path; pointer dispatch uses hit testing,
//! capture and bubbling through the retained element tree.
//!
//! Use [`Application::on_file_drop`] to receive paths dragged from the desktop
//! onto the window. The callback runs once for each dropped file:
//!
//! ```no_run
//! use kova_native::prelude::*;
//! use std::path::PathBuf;
//!
//! fn main() -> KovaResult<()> {
//! let owner = Owner::new_root();
//! let dropped_path = owner.with(|| signal(String::from("Drop a file here")));
//! let result = Application::new()
//! .on_file_drop({
//! let dropped_path = dropped_path.clone();
//! move |path: PathBuf| dropped_path.set(path.display().to_string())
//! })
//! .run(move || text(move || dropped_path.get()));
//! owner.dispose();
//! result.map(|_| ())
//! }
//! ```
//!
//! `widgets::elements::img_bind` updates a mounted image when its signal changes,
//! preserving the image element. Use `.on_pen(...)` on an element to receive
//! pressure-aware pointer events, and `.on_close_request(...)` on the application
//! to accept or cancel an attempt to close its window.
//!
//! # Subsystems
//!
//! The facade re-exports the existing library crates. Use these modules when
//! implementing custom elements or working directly with the frame pipeline:
//!
//! | Module | Responsibility |
//! | --- | --- |
//! | [`crate::core`] | Geometry, colors, identifiers, reactive state and dirty flags |
//! | [`crate::widgets`] | Elements, styling, themes, retained tree and event dispatch |
//! | [`crate::layout`] | Flexbox, grid, constraints and incremental layout |
//! | [`crate::text`] | Unicode shaping, font fallback, wrapping and glyph rasterization |
//! | [`crate::render`] | GPU context, scene commands, batching, atlases and effects |
//! | [`crate::assets`] | Image and SVG loading, rasterization and caching |
//! | [`crate::input`] | Events, keystrokes, actions and keymaps |
//! | [`crate::animation`] | Tweens, easing, springs and property transitions |
//! | [`crate::platform`] | Native windows, event loop, clipboard and IME hooks |
//!
//! # Examples and current scope
//!
//! The repository's [showcase](https://github.com/v3nn7/Kova-native/tree/main/examples/showcase)
//! exercises the same element tree, text system and renderer used by applications.
//! It includes native smoke runs and GPU captures. See the
//! [README](https://github.com/v3nn7/Kova-native#readme) for launch commands.
//!
//! The API is experimental. `text_input` provides single-line editing with
//! selection, clipboard, undo and IME composition; multi-line editing,
//! accessibility, arbitrary masks and custom shader registration are still
//! pending. The
//! [repository audit](https://github.com/v3nn7/Kova-native/blob/main/docs/AUDIT.md)
//! records the implemented subsystems and validation boundaries.
pub use ;
pub use kova_native_animation as animation;
pub use kova_native_assets as assets;
pub use kova_native_core as core;
pub use kova_native_input as input;
pub use kova_native_layout as layout;
pub use kova_native_platform as platform;
pub use kova_native_render as render;
pub use kova_native_text as text;
pub use kova_native_widgets as widgets;
/// Common application and element-building vocabulary.