light_fw_core/lib.rs
1//! # Light — реактивный графический интерфейс для Rust
2//!
3//! Light — библиотека со **своим окном** (winit + программная отрисовка)
4//! и реактивностью в духе Vue 3:
5//!
6//! * атрибут `#[proxy]` превращает структуру в реактивный класс: свойства
7//! читаются и записываются через геттеры/сеттеры, которые уведомляют
8//! обозревателя;
9//! * атрибут `#[template("...")]` компилирует HTML-шаблон с директивами
10//! (`{{ … }}`, `v-model`, `@click`, `v-if`, `:disabled`, `<include>`)
11//! на этапе сборки — шаблон **полностью замещает** форму компонента;
12//! * отрисовка построена на виртуальном дереве: каждое изменение свойства
13//! приводит к пересборке дерева и сравнению с предыдущим
14//! ([`vdom::diff`]), в результате чего обновляются **только реально
15//! изменившиеся элементы** — неизменённые узлы не перерисовываются;
16//! * шаблоны могут включать другие шаблоны через `<include src="...">` —
17//! так главная форма собирается из внутренних страниц и разделов.
18//!
19//! ## Пример
20//!
21//! Компонент описывается структурой с реактивными полями и атрибутом
22//! `#[template("путь.html")]`, который компилирует HTML-шаблон в реализацию
23//! [`Component`] на этапе сборки. Шаблон хранится рядом с исходниками
24//! (например, `templates/counter.html`) и может содержать директивы:
25//!
26//! * `{{ поле }}` — интерполяция значения;
27//! * `@click="метод"` — обработчик клика (в т.ч. `close()`, `minimize()`,
28//! `toggle_maximize()`, `open_modal()` для операций с окном; имена методов
29//! без скобок поддерживаются: `@click="increment"`);
30//! * `v-model="поле"` — связывание значения текстового поля с полем
31//! структуры;
32//! * `:disabled="свойство"`, `:attr="значение"` — динамические атрибуты;
33//! * `v-if="условие"` — условный рендер;
34//! * `key="идентификатор"` — ключ узла для runtime-дерева (без него ключ
35//! совпадает с именем обработчика или порядковым номером позиции);
36//! * `position-x="left|center|right"`, `position-y="top|center|bottom"` —
37//! выравнивание; незнакомые значения безопасно фоллбэктятся в выравнивание
38//! по началу (с диагностической строкой `light: runtime parse failed at …`).
39//!
40//! Пример компонента (шаблон `templates/counter.html`):
41//!
42//! ```rust
43//! # extern crate light_fw_core as light;
44//! # use light::prelude::*;
45//!
46//! #[template("templates/counter.html")]
47//! #[proxy]
48//! struct Counter {
49//! title: String,
50//! count: i64,
51//! }
52//!
53//! impl Counter {
54//! fn increment(&self) -> bool {
55//! self.set_count(self.count() + 1);
56//! true
57//! }
58//!
59//! fn reset(&self) -> bool {
60//! self.set_count(0);
61//! true
62//! }
63//!
64//! fn is_zero(&self) -> bool {
65//! self.count() == 0
66//! }
67//! }
68//! ```
69//!
70//! Запуск окна:
71//!
72//! ```rust,no_run
73//! # extern crate light_fw_core as light;
74//! # use light::prelude::*;
75//! # #[template("templates/counter.html")]
76//! # #[proxy]
77//! # struct Counter { title: String, count: i64 }
78//! # impl Counter {
79//! # fn increment(&self) -> bool { self.set_count(self.count() + 1); true }
80//! # fn reset(&self) -> bool { self.set_count(0); true }
81//! # fn is_zero(&self) -> bool { self.count() == 0 }
82//! # }
83//! # #[cfg(not(feature = "window"))]
84//! # fn main() {}
85//! # #[cfg(feature = "window")]
86//! fn main() -> light::Result<()> {
87//! light::run(Counter::new())
88//! }
89//! ```
90//!
91//! ## Инструменты разработки
92//!
93//! Фича `devtools` добавляет модуль [`devtools`] с JSON-снимком состояния
94//! приложения: виртуальное дерево, реактивные свойства компонента и (в
95//! перспективе) раскладка. Снимок строится функцией
96//! [`capture_snapshot`](devtools::capture_snapshot).
97
98#![deny(missing_docs)]
99#![forbid(unsafe_code)]
100
101// Позволяет генерируемому коду обращаться к `::light::…` изнутри самой библиотеки.
102extern crate self as light;
103
104/// Флаг runtime-templates: доступен ли парсинг HTML-шаблонов во время выполнения.
105pub const FEATURE_RUNTIME_TEMPLATES: bool = cfg!(feature = "runtime-templates");
106
107/// Публичная константа для диагностики: включён ли hot HTML reload.
108#[cfg(feature = "runtime-templates")]
109pub const RUNTIME_TEMPLATES_ENABLED: bool = true;
110/// Публичная константа для диагностики: включён ли hot HTML reload.
111#[cfg(not(feature = "runtime-templates"))]
112pub const RUNTIME_TEMPLATES_ENABLED: bool = false;
113
114// Публичные зависимости, доступные под именем `::light::…` в сгенерированном
115// коде (макрос `#[template]`). Не опциональны: `inspect_state`/`inject_state`
116// и генерируемые ими вызовы (`serde_json::to_value`, `serde::Serialize`)
117// присутствуют в любом наборе фич (0.15.1), поэтому реэкспорт без cfg.
118pub use serde;
119pub use serde_json;
120
121pub mod a11y;
122pub mod collection;
123pub mod component;
124pub mod control;
125#[cfg(feature = "devtools")]
126pub mod devtools;
127pub mod dom;
128pub mod error;
129#[cfg(feature = "file-dialog")]
130pub mod file_dialog;
131pub mod layout;
132pub mod prelude;
133pub mod reactive;
134pub mod runtime;
135mod text_wrap;
136pub mod validation;
137pub mod vdom;
138
139#[cfg(feature = "async-runtime")]
140pub mod async_runtime;
141#[cfg(feature = "window")]
142pub mod render;
143#[cfg(feature = "window")]
144pub mod window;
145
146#[cfg(feature = "async-await")]
147pub use async_runtime::spawn_async;
148#[cfg(feature = "async-runtime")]
149pub use async_runtime::{
150 TaskContext, TaskError, TaskHandle, UserEvent, apply_action, post_to_ui, post_update,
151 post_update_to, spawn,
152};
153pub use collection::Collection;
154pub use component::{Component, WindowConfig};
155pub use control::{
156 FocusCommand, WindowCommand, WindowToken, blur, current_window_token, focus, focused_key,
157 set_current_window_token,
158};
159#[cfg(feature = "devtools")]
160pub use devtools::{
161 DevToolsCommand, DevToolsInspect, DevToolsSnapshot, STATE_FILE, capture_snapshot,
162 load_state_file, save_state_file, state_file_path, update_latest_snapshot,
163};
164pub use dom::Dom;
165pub use error::{Error, Result};
166pub use light_fw_macros::{proxy, template};
167pub use reactive::{Property, Proxy, ProxyState, Watcher, watch};
168#[cfg(feature = "window")]
169pub use render::RendererBackend;
170#[cfg(feature = "wgpu-backend")]
171pub use render::WgpuBackend;
172#[cfg(feature = "image-support")]
173pub use vdom::ImageData;
174pub use vdom::{
175 Align, Edges, Event, KeyInfo, MouseButton, NodeKind, Offset, Overflow, Position, Resize,
176 SelectOption, Size, Style, VElement, VNode, VWindow, WhiteSpace,
177};
178
179/// Открывает окно с интерфейсом компонента и запускает цикл событий.
180///
181/// Возвращает только при закрытии окна или ошибке.
182#[cfg(feature = "window")]
183pub fn run(component: impl Component + 'static) -> Result<()> {
184 window::run(component)
185}
186
187/// Запускает TCP-сервер DevTools на `127.0.0.1:port`.
188///
189/// Возвращает фактический порт (полезно при `port = 0`). Сервер работает в
190/// отдельном потоке и не блокирует UI. Подключитесь через TCP и отправьте
191/// строку `SNAPSHOT\n` — в ответ придёт JSON с полями `window_token`,
192/// `vdom`, `state`, `layout`. Команда `QUIT\n` закрывает соединение.
193///
194/// Пример:
195/// ```no_run
196/// # extern crate light_fw_core as light;
197/// let port = light::enable_devtools(9229).expect("devtools server started");
198/// eprintln!("DevTools listening on 127.0.0.1:{}", port);
199/// ```
200#[cfg(feature = "devtools")]
201pub fn enable_devtools(port: u16) -> std::io::Result<u16> {
202 devtools::server::start(port)
203}