yggdrasil/bridges/

navigation.rs

//! 浏览器导航协调器桥接；历史记录中的页面状态只保存在当前文档内存中。
//!
//! 协调器是 `window.__routeTransitions`（`libs/yggdrasil-core/src/route-transitions.ts`），
//! 它拥有 history 与视图过渡；这里是它的 Rust 封装。`push/replace/back/forward/external`
//! 返回协调器是否存在（`false` 时调用方自行回退到浏览器原生导航），服务端恒为 `false`。

use serde::{de::DeserializeOwned, Serialize};

/// 请求站内跳转（视图过渡后写入 history）。协调器缺失返回 `false`。
pub fn push(route: &str) -> bool {
    #[cfg(target_arch = "wasm32")]
    if let Some(module) = wasm::get_module() {
        module.push(route);
        return true;
    }
    let _ = route;
    false
}

/// 请求站内替换跳转。协调器缺失返回 `false`。
pub fn replace(route: &str) -> bool {
    #[cfg(target_arch = "wasm32")]
    if let Some(module) = wasm::get_module() {
        module.replace(route);
        return true;
    }
    let _ = route;
    false
}

/// 历史记录后退。协调器缺失返回 `false`。
pub fn back() -> bool {
    #[cfg(target_arch = "wasm32")]
    if let Some(module) = wasm::get_module() {
        module.back();
        return true;
    }
    false
}

/// 历史记录前进。协调器缺失返回 `false`。
pub fn forward() -> bool {
    #[cfg(target_arch = "wasm32")]
    if let Some(module) = wasm::get_module() {
        module.forward();
        return true;
    }
    false
}

/// 整页跳转到站外或非 SPA 地址。协调器缺失或跳转失败返回 `false`。
pub fn external(url: &str) -> bool {
    #[cfg(target_arch = "wasm32")]
    if let Some(module) = wasm::get_module() {
        return module.external(url);
    }
    let _ = url;
    false
}

/// 连接协调器：之后它每次发布新路由都会调用 `notify`；悬停、聚焦、触屏按下站内链接时
/// 调用 `prefetch(route, with_data)`。协调器缺失或连接失败返回 `false`。
///
/// JS 同时持有两个闭包的函数引用；调用方必须保持两个 `Closure` 存活到 [`disconnect`] 之后。
#[cfg(target_arch = "wasm32")]
pub fn connect(
    notify: &wasm_bindgen::prelude::Closure<dyn FnMut()>,
    prefetch: &wasm_bindgen::prelude::Closure<dyn FnMut(String, bool)>,
) -> bool {
    let Some(module) = wasm::get_module() else {
        return false;
    };
    if module.connect(notify, None, prefetch).is_err() {
        let _ = module.disconnect();
        return false;
    }
    true
}

/// 断开协调器，释放它持有的事件监听与历史记录状态。
#[cfg(target_arch = "wasm32")]
pub fn disconnect() {
    if let Some(module) = wasm::get_module() {
        let _ = module.disconnect();
    }
}

/// 读取当前历史记录保存的页面状态。SSR 和资源加载失败时没有客户端状态。
pub fn read_state<T: DeserializeOwned>(key: &str) -> Option<T> {
    #[cfg(target_arch = "wasm32")]
    {
        let value = wasm::get_module()?.read_state(key)?;
        serde_json::from_slice(value.as_bytes()).ok()
    }
    #[cfg(not(target_arch = "wasm32"))]
    {
        let _ = key;
        None
    }
}

/// 写入挂载时捕获的历史记录，避免卸载后的异步回调覆盖新页面状态。
pub fn write_state<T: Serialize>(entry_id: &str, key: &str, value: &T) {
    #[cfg(target_arch = "wasm32")]
    if let (Some(module), Ok(value)) = (wasm::get_module(), serde_json::to_string(value)) {
        module.write_state(entry_id, key, &value);
    }
    #[cfg(not(target_arch = "wasm32"))]
    let _ = (entry_id, key, value);
}

/// 页面挂载时捕获的历史记录标识。服务端返回空字符串。
pub fn entry_id() -> String {
    #[cfg(target_arch = "wasm32")]
    if let Some(module) = wasm::get_module() {
        return module.entry_id();
    }
    String::new()
}

/// 退出登录时清理后台历史记录中的页面状态。
pub fn clear_admin_state() {
    #[cfg(target_arch = "wasm32")]
    if let Some(module) = wasm::get_module() {
        module.clear_admin_state();
    }
}

/// 与本轮路由 DOM 一起渲染的导航编号。
pub fn navigation_id() -> u32 {
    #[cfg(target_arch = "wasm32")]
    if let Some(module) = wasm::get_module() {
        return module.navigation_id();
    }
    0
}

/// 布局 effect 在实际 DOM 提交后通知 JS；JS 再核对编号和 DOM 标记。
pub fn rendered(id: u32, route: &str) {
    #[cfg(target_arch = "wasm32")]
    if let Some(module) = wasm::get_module() {
        module.rendered(id, route);
    }
    #[cfg(not(target_arch = "wasm32"))]
    let _ = (id, route);
}

/// 协调器是否处于分包迟到的挂起状态（`<html>` 带 `is-route-pending`）。服务端恒为 `false`。
///
/// 迟到的新页面挂载后，组件 Effect（微任务）先于 `RouteMarker` 用 `set_timeout(0)`
/// 触发的 [`rendered`] 运行，协调器在 `rendered` 里才撤类，所以 Effect 内读到的仍为 `true`。
pub fn route_pending() -> bool {
    #[cfg(target_arch = "wasm32")]
    {
        leptos::prelude::document()
            .document_element()
            .is_some_and(|root| root.class_list().contains("is-route-pending"))
    }
    #[cfg(not(target_arch = "wasm32"))]
    {
        false
    }
}

#[cfg(target_arch = "wasm32")]
pub mod wasm {
    use wasm_bindgen::{prelude::*, JsCast};

    #[wasm_bindgen]
    extern "C" {
        /// `window.__routeTransitions` 是对象字面量，通过 Reflect 读取。
        pub type NavigationModule;

        #[wasm_bindgen(method, catch)]
        pub fn connect(
            this: &NavigationModule,
            notify: &Closure<dyn FnMut()>,
            prefix: Option<&str>,
            prefetch: &Closure<dyn FnMut(String, bool)>,
        ) -> Result<(), JsValue>;

        #[wasm_bindgen(method, catch)]
        pub fn disconnect(this: &NavigationModule) -> Result<(), JsValue>;

        #[wasm_bindgen(method, js_name = currentRoute)]
        pub fn current_route(this: &NavigationModule) -> String;

        #[wasm_bindgen(method, js_name = currentPrefix)]
        pub fn current_prefix(this: &NavigationModule) -> Option<String>;

        #[wasm_bindgen(method, js_name = navigationId)]
        pub fn navigation_id(this: &NavigationModule) -> u32;

        #[wasm_bindgen(method)]
        pub fn push(this: &NavigationModule, route: &str);

        #[wasm_bindgen(method)]
        pub fn replace(this: &NavigationModule, route: &str);

        #[wasm_bindgen(method)]
        pub fn back(this: &NavigationModule);

        #[wasm_bindgen(method)]
        pub fn forward(this: &NavigationModule);

        #[wasm_bindgen(method)]
        pub fn external(this: &NavigationModule, url: &str) -> bool;

        #[wasm_bindgen(method)]
        pub fn rendered(this: &NavigationModule, id: u32, route: &str);

        #[wasm_bindgen(method, js_name = readState)]
        pub fn read_state(this: &NavigationModule, key: &str) -> Option<String>;

        #[wasm_bindgen(method, js_name = writeState)]
        pub fn write_state(this: &NavigationModule, entry_id: &str, key: &str, value: &str);

        #[wasm_bindgen(method, js_name = entryId)]
        pub fn entry_id(this: &NavigationModule) -> String;

        #[wasm_bindgen(method, js_name = clearAdminState)]
        pub fn clear_admin_state(this: &NavigationModule);

        #[wasm_bindgen(method, js_name = setLeaveGuard)]
        pub fn set_leave_guard(
            this: &NavigationModule,
            check: &Closure<dyn FnMut() -> bool>,
        ) -> u32;

        #[wasm_bindgen(method, js_name = clearLeaveGuard)]
        pub fn clear_leave_guard(this: &NavigationModule, id: u32);
    }

    pub fn get_module() -> Option<NavigationModule> {
        let window = web_sys::window()?;
        let value = js_sys::Reflect::get(&window, &"__routeTransitions".into()).ok()?;
        if value.is_null() || value.is_undefined() {
            return None;
        }
        let connect = js_sys::Reflect::get(&value, &"connect".into()).ok()?;
        connect
            .is_function()
            .then(|| value.unchecked_into::<NavigationModule>())
    }
}