Skip to main content

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}