light/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//! Ядро библиотеки — крейт [`light-fw-core`](light_fw_core). Дополнительные
22//! возможности подключаются как отдельные компоненты и фичи:
23//!
24//! * [`light-fw-element-form`](light_fw_element_form) (фича `elements-form`) —
25//! элементы `<checkbox>`, `<radio>`, `<select>`/`<option>`;
26//! * [`light-fw-behavior-validation`](light_fw_behavior_validation)
27//! (фича `validation`) — `required`, `:validator` и `@validate`.
28//!
29//! ## Пример
30//!
31//! ```no_run
32//! use light::prelude::*;
33//!
34//! #[template("templates/doc_example.html")]
35//! #[proxy]
36//! struct App {
37//! title: String,
38//! count: i64,
39//! name: String,
40//! show_greeting: bool,
41//! }
42//!
43//! impl App {
44//! fn increment(&self) {
45//! self.set_count(self.count() + 1);
46//! }
47//!
48//! fn is_zero(&self) -> bool {
49//! self.count() == 0
50//! }
51//!
52//! fn reset(&self) {
53//! self.set_count(0);
54//! }
55//!
56//! fn toggle_greeting(&self) {
57//! self.set_show_greeting(!self.show_greeting());
58//! }
59//! }
60//!
61//! # #[cfg(not(feature = "window"))]
62//! # fn main() {}
63//! # #[cfg(feature = "window")]
64//! fn main() -> light::Result<()> {
65//! light::run(App::new())
66//! }
67//! ```
68//!
69//! Шаблон `templates/doc_example.html`:
70//!
71//! ```html
72//! <div>
73//! <text>{{ title }}</text>
74//! <button @click="increment" :disabled="is_zero">+1 ({{ count }})</button>
75//! <button @click="reset">Сброс</button>
76//! </div>
77//! ```
78
79#![deny(missing_docs)]
80#![forbid(unsafe_code)]
81
82// Позволяет генерируемому коду обращаться к `::light::…` изнутри самой библиотеки.
83extern crate self as light;
84
85#[cfg(feature = "devtools")]
86use serde::Deserialize;
87
88// Основной API доступен всегда, без cfg (0.15.1). Глоб-реэкспорт ядра ниже
89// перетягивает `vdom::to_json` и всё остальное; здесь добавлены то, что glob
90// не даёт: `serde_json` — путь `::light::serde_json` для сгенерированного
91// макросом кода (доступен теперь в любом наборе фич), и `devtools` — только
92// при фиче.
93#[cfg(feature = "devtools")]
94pub use light_fw_core::devtools;
95pub use light_fw_core::*;
96pub use serde_json;
97
98#[cfg(feature = "async-await")]
99pub use light_fw_core::spawn_async;
100#[cfg(feature = "async-runtime")]
101pub use light_fw_core::{
102 TaskContext, TaskError, TaskHandle, UserEvent, post_to_ui, post_update, post_update_to, spawn,
103};
104#[cfg(feature = "async-runtime")]
105pub use std::any::Any;
106
107#[cfg(feature = "validation")]
108pub use light_fw_behavior_validation;
109#[cfg(feature = "devtools")]
110pub use light_fw_core::enable_devtools;
111#[cfg(feature = "elements-form")]
112pub use light_fw_element_form;
113
114/// Профиль из `light.config.json`: один из разделов `dev` / `prod`.
115#[cfg(feature = "devtools")]
116#[derive(Debug, Clone, Deserialize)]
117struct ConfigProfile {
118 /// Настройки DevTools (TCP-инспектор).
119 #[serde(default)]
120 devtools: Option<DevtoolsConfig>,
121}
122
123/// Настройки DevTools в `light.config.json`: `enabled` и `port`.
124#[cfg(feature = "devtools")]
125#[derive(Debug, Clone, Deserialize)]
126struct DevtoolsConfig {
127 /// Включён ли TCP-сервер инспектора.
128 #[serde(default)]
129 enabled: bool,
130 /// Порт для TCP-сервера (по умолчанию 9229).
131 #[serde(default = "default_devtools_port")]
132 port: u16,
133}
134
135/// Порт DevTools по умолчанию, если он не задан в конфиге.
136#[cfg(feature = "devtools")]
137fn default_devtools_port() -> u16 {
138 9229
139}
140
141/// Считывает `light.config.json` и возвращает профиль для текущей сборки.
142///
143/// При `cfg!(debug_assertions)` (сборка debug) берётся раздел `dev`, иначе —
144/// `prod`. Если файла нет или он не парсится, используется профиль с
145/// разумными значениями по умолчанию (`devtools` выключен, порт 9229).
146#[cfg(feature = "devtools")]
147fn load_profile(config_path: &str) -> ConfigProfile {
148 let text = match std::fs::read_to_string(config_path) {
149 Ok(text) => text,
150 Err(_) => return ConfigProfile { devtools: None },
151 };
152 let parsed: serde_json::Value = match serde_json::from_str(&text) {
153 Ok(value) => value,
154 Err(_) => return ConfigProfile { devtools: None },
155 };
156 let section = if cfg!(debug_assertions) {
157 "dev"
158 } else {
159 "prod"
160 };
161 match parsed.get(section) {
162 Some(profile) => {
163 serde_json::from_value(profile.clone()).unwrap_or(ConfigProfile { devtools: None })
164 }
165 None => ConfigProfile { devtools: None },
166 }
167}
168
169/// Запускает приложение по конфигурации из `light.config.json`.
170///
171/// Читает `config_path` (при отсутствии файла или ошибке разборки — использует
172/// значения по умолчанию). Для отладочной сборки (`cfg!(debug_assertions)`)
173/// выбирается раздел `dev`, для release — `prod`; если в выбранном профиле
174/// включён DevTools **и фича `devtools` активна** (`cargo dev`), поднимается
175/// TCP-сервер на заданном порту (по умолчанию 9229). Затем запускает
176/// приложение через [`light_fw_core::run`].
177///
178/// DevTools стартует только если фича `devtools` включена (`cargo dev`).
179/// Без неё сервер не поднимается, даже если в JSON `enabled: true`.
180///
181/// Пример:
182/// ```ignore
183/// use light::prelude::*;
184///
185/// #[template("templates/doc_example.html")]
186/// #[proxy]
187/// struct App {
188/// count: i64,
189/// }
190///
191/// impl App {
192/// fn increment(&self) {
193/// self.set_count(self.count() + 1);
194/// }
195/// }
196///
197/// fn main() -> light::Result<()> {
198/// light::run_with_config("light.config.json", App::new())
199/// }
200/// ```
201#[cfg(feature = "window")]
202pub fn run_with_config(
203 config_path: &str,
204 component: impl Component + 'static,
205) -> crate::Result<()> {
206 let _ = config_path;
207 #[cfg(feature = "devtools")]
208 {
209 if light_fw_core::RUNTIME_TEMPLATES_ENABLED {
210 eprintln!("light: runtime-templates enabled (hot HTML reload active)");
211 } else {
212 eprintln!("light: runtime-templates DISABLED (hot HTML reload will not work)");
213 }
214 }
215 #[cfg(feature = "devtools")]
216 {
217 let profile = load_profile(config_path);
218 if let Some(devtools) = &profile.devtools
219 && devtools.enabled
220 {
221 match enable_devtools(devtools.port) {
222 Ok(port) => eprintln!("DevTools listening on 127.0.0.1:{port}"),
223 Err(error) => eprintln!(
224 "Не удалось запустить сервер DevTools на порту {}: {error}",
225 devtools.port
226 ),
227 }
228 }
229 }
230 light_fw_core::run(component)
231}