waterui_core/lib.rs
1//! # `WaterUI` Core
2//!
3//! `waterui_core` provides the essential building blocks for developing cross-platform reactive UIs.
4//! This foundation layer establishes a unified architecture that works consistently across desktop,
5//! mobile, web, and embedded environments.
6
7#![cfg_attr(feature = "nightly", feature(never_type))]
8//!
9//! ## Architecture Overview
10//!
11//! The system is structured around these key concepts:
12//!
13//! ### Declarative View System
14//!
15//! The [`View`] trait forms the foundation of the UI component model:
16//! ```text
17//! pub trait View: 'static {
18//! fn body(self, env: &Environment) -> impl View;
19//! }
20//! ```
21//!
22//! This recursive definition enables composition of complex interfaces from simple
23//! building blocks. Each view receives contextual information and transforms into
24//! its visual representation.
25//!
26//! ### Context Propagation
27//!
28//! The [`Environment`] provides a type-based dependency injection system:
29//!
30//! ```rust
31//! use waterui_core::Environment;
32//!
33//! let env = Environment::new();
34//! // .with() and .install() methods would be used with actual theme and plugin types
35//! ```
36//!
37//! This propagates configuration and resources through the view hierarchy without
38//! explicit parameter passing.
39//!
40//! ### Type Erasure
41//!
42//! [`AnyView`] enables heterogeneous collections by preserving behavior while
43//! erasing concrete types, facilitating dynamic composition patterns.
44//!
45//! ## Component Architecture
46//!
47//! The framework provides several component categories:
48//!
49//! - **Platform Components**: Native UI elements with platform-optimized rendering
50//! - **Reactive Components**: Views that automatically update when data changes
51//! - **Metadata Components**: Elements that carry additional rendering instructions
52//! - **Composite Components**: Higher-order components built from primitive elements
53//!
54//! ## Reactive Data Flow
55//!
56//! State management integrates seamlessly with the view system:
57//!
58//! ```rust
59//! use waterui_core::{Binding, Signal, SignalExt};
60//!
61//! // Create a reactive state container
62//! let counter = Binding::container(0);
63//!
64//! // Derive the exact value consumed by a signal-aware component.
65//! let label = counter.map(|count| format!("Current value: {count}"));
66//! assert_eq!(label.get(), "Current value: 0");
67//! ```
68//!
69//! Signal-aware component inputs subscribe to derived values and update only the
70//! affected native property. Structural subtree replacement is reserved for cases
71//! where the view identity itself changes.
72//!
73//! ## Extensibility
74//!
75//! The plugin interface enables framework extensions without modifying core code:
76//!
77//! ```rust
78//! use waterui_core::{plugin::Plugin, Environment};
79//!
80//! struct MyPlugin;
81//! impl Plugin for MyPlugin {}
82//!
83//! let mut env = Environment::new();
84//! MyPlugin.install(&mut env);
85//! ```
86//!
87//! This enables modular functionality like theming, localization, and platform-specific features.
88
89#![cfg_attr(not(feature = "std"), no_std)]
90extern crate alloc;
91
92#[macro_use]
93mod macros;
94mod animation_system;
95mod components;
96mod foundation;
97mod state;
98mod ui;
99
100pub use animation::{Animatable, AnimationExt, AnimationTrack};
101pub use animation_system::{animation, easing, vector_arithmetic};
102pub use anyhow::Error;
103pub use anyview::AnyView;
104pub use components::*;
105pub use easing::{EasingCurve, Interpolatable};
106pub use env::Environment;
107pub use extract::State;
108pub use foundation::main_thread::MainThreadBound;
109pub use foundation::signal::flatten_signal;
110pub use foundation::{env, extract, handler, id, main_thread, plugin, resolve};
111pub use nami as reactive;
112pub use nami::signal::IntoSignal;
113pub use nami::{Binding, Computed, Signal, SignalExt, binding, constant, impl_constant};
114pub use state::IntoSignalF32;
115pub use ui::{accessibility, event, gesture, interaction, layout, view, view_renderer, views};
116pub use view::View;
117pub use view_renderer::{CustomViewRenderer, RenderResult, RenderSize, ViewRenderer};
118pub use waterui_str::Str;