Crate waterui_core

Expand description

§`WaterUI` Core

waterui_core provides the essential building blocks for developing cross-platform reactive UIs. This foundation layer establishes a unified architecture that works consistently across desktop, mobile, web, and embedded environments.

§Architecture Overview

The system is structured around these key concepts:

§Declarative View System

The View trait forms the foundation of the UI component model:

pub trait View: 'static {
    fn body(self, env: &Environment) -> impl View;
}

This recursive definition enables composition of complex interfaces from simple building blocks. Each view receives contextual information and transforms into its visual representation.

§Context Propagation

The Environment provides a type-based dependency injection system:

use waterui_core::Environment;

let env = Environment::new();
// .with() and .install() methods would be used with actual theme and plugin types

This propagates configuration and resources through the view hierarchy without explicit parameter passing.

§Type Erasure

AnyView enables heterogeneous collections by preserving behavior while erasing concrete types, facilitating dynamic composition patterns.

§Component Architecture

The framework provides several component categories:

Platform Components: Native UI elements with platform-optimized rendering
Reactive Components: Views that automatically update when data changes
Metadata Components: Elements that carry additional rendering instructions
Composite Components: Higher-order components built from primitive elements

§Reactive Data Flow

State management integrates seamlessly with the view system:

use waterui_core::{Binding, Signal, SignalExt};

// Create a reactive state container
let counter = Binding::container(0);

// Derive the exact value consumed by a signal-aware component.
let label = counter.map(|count| format!("Current value: {count}"));
assert_eq!(label.get(), "Current value: 0");

Signal-aware component inputs subscribe to derived values and update only the affected native property. Structural subtree replacement is reserved for cases where the view identity itself changes.

§Extensibility

The plugin interface enables framework extensions without modifying core code:

use waterui_core::{plugin::Plugin, Environment};

struct MyPlugin;
impl Plugin for MyPlugin {}

let mut env = Environment::new();
MyPlugin.install(&mut env);

This enables modular functionality like theming, localization, and platform-specific features.

Re-exports§

pub use nami as reactive;

Modules§

accessibility: Helpers for customizing accessibility metadata when the built-in WaterUI defaults are not enough.
animation: WaterUI Animation System
anyview: This module provides type-erased view implementations to enable heterogeneous collections of views and dynamic dispatch.
binding: Reactive Bindings
constant: Constant Values for Reactive Computation
dynamic: Dynamic views that can be updated at runtime.
easing: Unified easing system for WaterUI animations.
env: Environment management module for sharing data across views.
event: Event handling components and utilities.
extract: This module provides mechanisms for extracting values from the Environment.
gesture: Declarative gesture descriptors used by WaterUI components.
handler: Handler type aliases for action callbacks.
id: Identity, tagging, and mapping functionality for UI components.
interaction: Interaction state shared by controls and rendering backends.
layout: Layout primitives and geometry types for the WaterUI layout system.
main_thread: MainThreadBound: a main-thread-confinement wrapper.
metadata: Metadata components for attaching arbitrary data to views.
native: This module provides platform-specific native views that can wrap platform-native UI components.
plugin: Provides the Plugin trait for extending application functionality.
resolve: The Resolve Pattern
vector_arithmetic: VectorArithmetic trait for types that can be linearly interpolated.
view: View Module
view_renderer: View renderer for capturing views to pixel data.
views: Collection of view-related utilities for managing and transforming UI components.

Macros§

configurable: Creates a configurable view with builder pattern methods.
impl_constant: Macro to implement the Signal trait for constant types.
impl_debug: Implements a basic Debug trait for types using their type name.
impl_deref: Implements the Deref trait for transparent access to an inner type.
impl_extractor: Implements the Extractor trait for a type.
raw_view: Implements a native view that is handled by the platform backend.

Structs§

AnimationTrack: Shared animation timeline state for values implementing Animatable.
AnyView: A type-erased wrapper for a View.
Binding: A Binding<T> represents a mutable value of type T that can be observed.
Computed: A wrapper around a boxed implementation of the ComputedImpl trait.
Dynamic: A dynamic view that can be updated.
Environment: An Environment stores a map of types to values.
Error: The Error type, a wrapper around a dynamic error type.
IgnorableMetadata: A metadata wrapper that can be safely ignored by renderers if not handled explicitly.
MainThreadBound: Wraps a !Send/!Sync value so it satisfies Send + Sync, while enforcing at runtime that it is only accessed on the thread that constructed it.
Metadata: Represents a view that carries additional metadata of type T.
Native: A wrapper for platform-specific native UI components.
RenderResult: Result of rendering a view to RGBA pixels.
RenderSize: Size for view rendering.
Retain: A metadata key that retains a value for its lifetime.
State: Wrapper for cloneable state values injected into the environment.
Str: A string type that can be either a static reference or a ref-counted owned string.
ViewRenderer: Type-erased view renderer stored in Environment.

Enums§

EasingCurve: Declarative easing curve with only two variants.

Traits§

Animatable: SwiftUI-style animation protocol.
AnimationExt: Extension trait providing animation methods for reactive values.
CustomViewRenderer: Trait for custom view renderers.
Interpolatable: Trait for types that can be linearly interpolated.
IntoSignal: A trait for converting a value into a computation.
IntoSignalF32: Converts constants or reactive signals into an f32 signal.
NativeView: A trait for all views handled by the native backend.
Signal: The core trait for reactive system.
SignalExt: Extension trait providing convenient methods for all Signal types.
View: View represents a part of the user interface.

Functions§

binding: Creates a new binding from a value with automatic type conversion.
constant: Creates a new constant reactive value.
flatten_signal: Flattens a signal whose current value is another computed signal.