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}