hypen_server/lib.rs
1//! # Hypen Rust Server SDK
2//!
3//! Server-side SDK for building [Hypen](https://hypen.space) applications in Rust.
4//!
5//! Hypen is a declarative UI language and reactive runtime. This SDK provides
6//! a type-safe, idiomatic Rust API for defining stateful modules, handling
7//! actions, managing routing, and discovering components.
8//!
9//! ## Quick Start
10//!
11//! ```rust,ignore
12//! use hypen_server::prelude::*;
13//! use serde::{Deserialize, Serialize};
14//!
15//! #[derive(Clone, Default, Serialize, Deserialize)]
16//! struct CounterState {
17//! count: i32,
18//! }
19//!
20//! fn main() {
21//! let counter = HypenApp::module::<CounterState>("Counter")
22//! .state(CounterState { count: 0 })
23//! .ui(r#"
24//! Column {
25//! Text("Count: ${state.count}")
26//! Button("@actions.increment") { Text("+") }
27//! Button("@actions.decrement") { Text("-") }
28//! }
29//! "#)
30//! .on_created(|state, _ctx| {
31//! println!("Counter created at {}", state.count);
32//! })
33//! .on_action::<()>("increment", |state, _, _ctx| {
34//! state.count += 1;
35//! })
36//! .on_action::<()>("decrement", |state, _, _ctx| {
37//! state.count -= 1;
38//! })
39//! .on_destroyed(|state, _ctx| {
40//! println!("Counter destroyed at {}", state.count);
41//! })
42//! .build();
43//!
44//! // Create an app with routing
45//! let app = HypenApp::builder()
46//! .route("/", counter)
47//! .build();
48//!
49//! // Instantiate and run
50//! let instance = app.instantiate(
51//! std::sync::Arc::new(
52//! HypenApp::module::<CounterState>("Counter")
53//! .state(CounterState { count: 0 })
54//! .on_action::<()>("increment", |s, _, _| s.count += 1)
55//! .build()
56//! )
57//! ).unwrap();
58//! instance.mount();
59//! instance.dispatch_action("increment", None).unwrap();
60//! assert_eq!(instance.get_state().count, 1);
61//! }
62//! ```
63//!
64//! ## Architecture
65//!
66//! The SDK wraps the `hypen-engine` core and provides a high-level API:
67//!
68//! - **[`ModuleBuilder`](module::ModuleBuilder)** — Fluent builder for defining modules
69//! with typed state, action handlers, and lifecycle hooks.
70//! - **[`HypenApp`](app::HypenApp)** — Application registry with routing, component
71//! discovery, and a global context.
72//! - **[`GlobalContext`](context::GlobalContext)** — Cross-module communication hub
73//! for sharing state and events.
74//! - **[`HypenRouter`](router::HypenRouter)** — URL pattern-based router with
75//! parameter extraction and navigation history.
76//! - **[`ComponentRegistry`](discovery::ComponentRegistry)** — Auto-discovery of
77//! `.hypen` component files from the filesystem.
78//! - **[`EventEmitter`](events::EventEmitter)** — Pub/sub event system for
79//! decoupled communication.
80//!
81//! ## Action Handling
82//!
83//! Actions always take a name and a type parameter for the payload.
84//! Use `()` for actions with no payload.
85//!
86//! ### No payload
87//!
88//! ```rust,ignore
89//! .on_action::<()>("increment", |state, _, _ctx| {
90//! state.count += 1;
91//! })
92//! ```
93//!
94//! ### Typed payload
95//!
96//! ```rust,ignore
97//! #[derive(Deserialize)]
98//! struct SetValue { value: i32 }
99//!
100//! .on_action::<SetValue>("set_value", |state, payload, _ctx| {
101//! state.count = payload.value;
102//! })
103//! ```
104//!
105//! ### Raw JSON payload
106//!
107//! ```rust,ignore
108//! .on_action::<serde_json::Value>("raw", |state, raw, _ctx| {
109//! if let Some(n) = raw.as_i64() { state.count = n as i32; }
110//! })
111//! ```
112
113pub mod action;
114pub mod app;
115pub mod context;
116pub mod discovery;
117pub mod error;
118pub mod events;
119pub mod module;
120pub mod prelude;
121pub mod router;
122pub(crate) mod state;