orbital-ui 0.1.1

Leptos component library and design system for focused, accessible product UIs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

#![recursion_limit = "256"]
//! # Orbital
//!
//! Orbital is a Leptos UI component library and preview catalog facade.
//! It combines:
//!
//! - themed UI primitives and shell/layout helpers,
//! - authentication context wiring for UI and server functions,
//! - component preview registration for the `:3010` doc catalog,
//! - SSR-safe shell utilities for [`leptos`].
//!
//! ## Feature layout
//!
//! - Client-safe modules (`auth`, `components`, `nav`, `paths`, `routes`)
//!   are available in all builds.
//! - Preview registration uses [`inventory`] when the `preview` feature is enabled.
//!
//! ## Current capabilities
//!
//! - Shell/layout primitives ([`orbital_shell`], [`OrbitalTemplate`]) for
//!   consistent app composition.
//! - Auth context providers/hooks ([`provide_auth_context`], [`use_auth_context`]).
//! - Auth redirect helpers and route guards ([`routes`]).
//! - Preview catalog registration ([`PreviewRegistration`], [`collect_preview_registrations`]).
//!
//! ## Preview workflow
//!
//! 1. Author a component and annotate it with `#[component_doc]`.
//! 2. Enable the crate's `preview` feature so the macro emits catalog metadata.
//! 3. Run `cargo leptos watch -p orbital-preview` and browse `/orbital/{slug}`.
//! 4. Cover interactive behavior with Playwright specs in `end2end/`.
//!
//! ## API reference map
//!
//! - Auth redirect helpers and route guards: [`routes`]
//! - Auth/context providers and hooks: [`context`] and [`auth`]
//! - Shell/layout and composition primitives: [`components`] and [`nav`]
//! - Preview catalog registration: [`preview`]
//! ## Minimal shell usage
//!
//! ```rust,ignore
//! use leptos::prelude::*;
//! use orbital::orbital_shell;
//!
//! fn main() {
//!     let options = leptos::config::LeptosOptions::default();
//!     let _view = orbital_shell(options, || view! { <div>"Hello Orbital"</div> });
//! }
//! ```
use leptos::prelude::*;
use leptos_meta::*;
use orbital_style::StyleRegistry;
use orbital_theme::OrbitalThemeProvider;

/// Authentication-related UI and helpers.
pub mod auth;
/// Shared UI components and composition primitives.
pub mod components;
/// Public primitives re-exported for app and shell UI.
pub mod primitives {
    pub use orbital_primitives::*;
}
/// Context providers/hooks for auth and app state.
pub mod context;
/// Common Orbital-facing data models.
pub mod models;
/// Navigation component model and helpers.
pub mod nav;
/// Route path constants and path utilities.
pub use orbital_shell::paths;
/// Component preview registration for the preview catalog.
#[cfg(any(feature = "hydrate", feature = "ssr", feature = "preview"))]
pub mod preview;
/// Auth redirect helpers and route guards.
pub mod routes;
/// High-level service helpers used by Orbital apps.
pub mod services;
/// Document shell helpers ([`OrbitalFirstPaintHeadAssets`], base path utilities).
pub mod shell;

// Re-export auth context helpers for downstream crates.
pub use context::{
    provide_auth_context, use_auth_context, use_auth_state, use_authenticated_user, AuthContext,
};
pub use models::auth::{AnonymousUser, AuthSession, AuthenticatedUser};
pub use orbital_theme::ThemeMode;
#[cfg(any(feature = "hydrate", feature = "ssr", feature = "preview"))]
pub use preview::{collect_preview_registrations, PreviewRegistration};
pub use services::auth_service::init_auth_resource;
pub use shell::OrbitalFirstPaintHeadAssets;
pub use shell::{hide_boot_loader, OrbitalBootLoaderHeadAssets, OrbitalBootOverlay};

/// Design tokens for marketing surfaces (`CornerRadius`, `BrandTone`, …).
pub use orbital_shell::tokens;

// Note: The `server` macro cannot be re-exported through regular modules.
// Use `#[orbital_macros::server]` or `use orbital_macros::server; #[server]` instead.

/// Orbital shell with HTML wrapper
///
/// Wraps the entire app with HTML structure, meta tags, and styling.
///
/// This is the canonical SSR document wrapper for Orbital apps. It injects:
///
/// - first-paint theme baseline CSS ([`OrbitalFirstPaintHeadAssets`]) with design tokens and fonts,
/// - a bootstrap loading overlay ([`OrbitalBootOverlay`]) visible until hydration completes,
/// - Leptos hydration/autoreload scripts,
/// - app-owned `/main.css` overrides.
///
/// ## Boot loader
///
/// The shell renders [`OrbitalBootLoaderHeadAssets`] and [`OrbitalBootOverlay`] automatically.
/// Your WASM `hydrate()` entrypoint **must** call [`hide_boot_loader`] immediately after
/// `leptos::mount::hydrate_body(...)`.
///
/// ## Static assets
///
/// Build the `orbital` crate before `cargo leptos watch` so `build.rs` generates
/// `public/orbital-theme-baseline.css`. Point cargo-leptos `assets-dir` at `public/`
/// (or copy the file into your app static root). Font files must live under `public/fonts/`.
/// Regenerate when `LEPTOS_BASE_PATH` changes.
pub fn orbital_shell<F, IV>(options: LeptosOptions, app_fn: F) -> impl IntoView
where
    F: Fn() -> IV + Send + 'static,
    IV: IntoView + 'static,
{
    provide_meta_context();

    view! {
         <StyleRegistry>
            <!DOCTYPE html>
            <html lang="en">
                <head>
                    <meta charset="utf-8"/>
                    <meta name="viewport" content="width=device-width, initial-scale=1"/>
                    <OrbitalFirstPaintHeadAssets />
                    <OrbitalBootLoaderHeadAssets />
                    <meta name="orbital-style"/>
                    <Title text="Welcome to Leptos" />
                    <AutoReload options=options.clone() />
                    <HydrationScripts options/>
                    <link rel="shortcut icon" type="image/ico" href="/favicon.ico" />
                    <link rel="stylesheet" href="/main.css" />
                    <MetaTags/>
                </head>
                <body style="margin: 0;">
                    {app_fn()}
                    <OrbitalBootOverlay />
                </body>
            </html>
        </StyleRegistry>
    }
}

/// Orbital template component that wraps app content
///
/// Provides OrbitalThemeProvider and other shell features. The app should pass its router as children.
#[component]
pub fn OrbitalTemplate(children: Children) -> impl IntoView {
    view! {
        <OrbitalThemeProvider>
            {children()}
        </OrbitalThemeProvider>
    }
}