Skip to main content

wabot_feature_ui_controller/
lib.rs

1//! # wabot-feature-ui-controller
2//!
3//! Server-rendered pages with islands — port of
4//! `wabot-ts/src/feature/ui-controller`. Renderer-agnostic: this crate
5//! owns routing, the document shell, the island protocol, actions and
6//! boosted navigation, and knows nothing about how a view's HTML was
7//! produced. `wabot-addon-ui-maud` is the default renderer.
8//!
9//! ```ignore
10//! #[singleton]
11//! #[derive(Default)]
12//! pub struct PanelController;
13//!
14//! #[ui_controller("/panel", app, layout)]
15//! impl PanelController {
16//!     fn layout(&self, outlet: ViewBody) -> ViewBody {
17//!         html! { nav { a href="/panel" { "Home" } } (outlet) }.into_view()
18//!     }
19//!
20//!     #[view("/")]
21//!     async fn index(&self) -> UiResult<ViewBody> {
22//!         Ok(html! { h1 { "Panel" } (island("counter", &Props { start: 0 }, html! { … })) }
23//!             .into_view())
24//!     }
25//!
26//!     #[action("save")]
27//!     async fn save(&self, req: SaveRequest) -> UiResult<Saved> { … }
28//! }
29//!
30//! let router = PanelController::register_ui_routes(&c, ui_router());
31//! run_ui_controllers(router, RestServerConfig::from_env()).await?;
32//! ```
33//!
34//! ## Shape of a request
35//!
36//! * `GET <controller><view>` — middleware, handler, render, document.
37//!   With `X-Wabot-Nav: 1` on an `app` controller it answers a JSON
38//!   fragment instead, and both forms carry an ETag so a repeat visit
39//!   gets a 304.
40//! * `POST <controller>/_action/<name>` — middleware, handler, JSON.
41//!
42//! ## Not ported
43//!
44//! The esbuild bundler, CSS modules, the dev server, and
45//! `StaticPageCache` (SSG/ISR). Islands here are plain JS the app
46//! serves; there is no build step. See `docs/ui-renderer-review.md`.
47
48pub mod assets;
49pub mod dev;
50pub mod document;
51pub mod island;
52pub mod nav;
53pub mod runtime;
54pub mod scope;
55pub mod static_cache;
56pub mod tsx;
57pub mod view;
58
59pub use assets::{content_type_for, embedded_assets, EmbeddedAsset, EmbeddedAssets};
60pub use document::{escape_attr, escape_html, render_document, AttrValue, DocumentOptions};
61pub use island::{island_host, outlet_host, serialize_props, IslandRef};
62pub use nav::{
63    app_bootstrap_script, etag_for, FragmentPayload, CLIENT_RUNTIME_JS, CLIENT_RUNTIME_PATH,
64    NAV_HEADER,
65};
66pub use runtime::{
67    action_route, client_runtime_response, join_route, page_response, redirect_response,
68    render_view_page, render_view_response, static_variant, synthetic_parts, version_precondition,
69    wants_fragment, with_version_etag, RenderedView, ViewRenderConfig,
70};
71pub use scope::{
72    add_script, add_style, in_scope, record_island, set_meta, set_title, with_scope,
73    with_scope_async, RenderScope,
74};
75pub use static_cache::{StaticPage, StaticPageCache, StaticVariant};
76pub use tsx::{TsxConfig, TsxError};
77pub use view::{Redirect, UiError, UiResult, ViewBody, ViewOutcome};
78
79// The UI layer runs on the same axum stack as the REST controllers and
80// shares their middleware and error types; re-export what generated
81// code and user code need so a UI-only app needs one dependency.
82pub use wabot_feature_rest_controller::{
83    axum, decompose_request, extract_typed, ok_json, run_middlewares, HandlerContext, Middleware,
84    MiddlewareInstance, RestError, RestServerConfig, DEFAULT_MAX_BODY,
85};
86
87use axum::routing::get;
88use axum::Router;
89
90/// A router pre-loaded with the framework's own routes — currently the
91/// client runtime at `/_wabot/client.js`. Start from this instead of
92/// `Router::new()` so islands and boosted navigation work.
93pub fn ui_router() -> Router {
94    Router::new().route(
95        CLIENT_RUNTIME_PATH,
96        get(|| async { client_runtime_response() }),
97    )
98}
99
100/// Serve the UI router. Thin alias over the REST server so a process
101/// exposing both uses one listener; call
102/// `wabot_feature_rest_controller::run_rest_controllers` directly if
103/// you merged the routers yourself.
104pub async fn run_ui_controllers(router: Router, config: RestServerConfig) -> std::io::Result<()> {
105    wabot_feature_rest_controller::run_rest_controllers(router, config).await
106}