leptos_posthoc/

lib.rs

#![cfg_attr(feature = "ssr", allow(unused_variables))]
#![cfg_attr(feature = "ssr", allow(unused_mut))]
#![cfg_attr(feature = "ssr", allow(unused_imports))]

/*! Allows for "hydrating" an existent DOM with reactive leptos components,
 * without the entire DOM having to be generated by leptos components.
 *
 * ## Why would you want that?
 * 1. **CSR:** It allows for building scripts that others can just embed in their arbitrary HTML documents, that add 
 *    `<insert your favourite fancy feature here>`. For an example, see the `examples/csr` directory: 
 *    the `index.html` has a node `<script src='csr_example.js'></script>`, which "hydrates" nodes with the 
 *    `data-replace-with-leptos`-attribute with leptos components that add a hover-popup (using 
 *    [thaw](https://docs.rs/thaw)).
 * 2. **SSR:** Occasionally, you might want to dynamically insert some HTML string into the DOM, for example one that 
 *    gets generated from some data and returned by a server function. This HTML might contain certain nodes that 
 *    we want to attach reactive functionality to. For an example, see the `examples/ssr` directory.
 *
 * ## CSR Example
 * Say we want to replace all elements with the attribute `data-replace-with-leptos` with a leptos component 
 * `MyReplacementComponent`, that simply wraps the original children in a `div` with a solid red border. This 
 * component would roughly look like this:
 * ```
 * #[component]
 * fn MyReplacementComponent(orig:OriginalNode) -> impl IntoView {
 *    view! {
 *       <div style="border: 1px solid red;">
 *         <DomChildren orig />
 *      </div>
 *   }
 * }
 * ```
 * This component takes an `orig:`[`OriginalNode`] that represents the, well, original [`Element`].
 *
 * So, where do we get `orig` from?
 * - If we already have an `e:&`[`Element`], we can simply call `e.into()`.
 * - More likely, we don't have an [`Element`] yet. Moreover, we probably want to iterate over the entire body 
 *   *once* to find all nodes we want to make reactive, and we also need to set up a global reactive system for all 
 *   our inserted components.
 *
 *   To do that, we call [`hydrate_body`] (requires the `csr` feature flag) with a function that takes the 
 *   [`OriginalNode`] of the body and returns some leptos view; e.g.:
 *
 * ```
 *  #[component]
 *  fn MainBody(orig:OriginalNode) -> impl IntoView {
 *     // set up some signals, provide context etc.
 *     view!{
 *       <DomChildren orig/>
 *     }
 *  }
 *  #[wasm_bindgen(start)]
 *   pub fn run() {
 *       console_error_panic_hook::set_once();
 *       hydrate_body(|orig| view!(<MainBody orig/>).into_any())
 *   }
 * ```
 *
 * This sets up the reactive system, but does not yet replace any elements further down in the DOM. To do that, 
 * we provide a function that takes an `&`[`Element`] and optionally returns an 
 * [`FnOnce`]`() -> impl `[`IntoView`]`+'static`, if the element should be changed. This function is then passed to 
 * [`DomChildrenCont`], which will iterate over all children of the replaced element and replace them with the 
 * provided function.
 *
 * Let's modify our `MainBody` to replace all elements with the attribute `data-replace-with-leptos` with a 
 * `MyReplacementComponent`:
 *
 * ```
 *  fn replace(e:&Element) -> Option<impl FnOnce() -> AnyView> {
 *    e.get_attribute("data-replace-with-leptos").map(|_| {
 *      let orig: OriginalNode = e.clone().into();
 *      || view!(<MyReplacementComponent orig/>).into_any()
 *    })
 *  }
 *
 *  #[component]
 *  fn MainBody(orig:OriginalNode) -> impl IntoView {
 *     // set up some signals, provide context etc.
 *     view!{
 *       <DomChildrenCont orig cont=replace/>
 *     }
 *  }
 *
 * #[component]
 * fn MyReplacementComponent(orig:OriginalNode) -> impl IntoView {
 *    view! {
 *       <div style="border: 1px solid red;">
 *         <DomChildrenCont orig cont=replace/>
 *      </div>
 *   }
 * }
 * ```
 *
 * ...now, `replace` will get called on every element of the DOM, including those that were "moved around" in 
 * earlier `MyReplacementComponent`s, respecting the proper reactive graph (regardin signal inheritance etc.).
 *
 * ### SSR Example
 *
 * In general, for SSR we can simply use the normal leptos components to generate the entire DOM. We control the 
 * server, hence we control the DOM anyway.
 *
 * However, it might occasionally be the case that we want to dynamically *extend* the DOM at some point by 
 * retrieving HTML from elsewhere, and then want to do a similar "hydration" iteration over the freshly inserted 
 * nodes. This is what [`DomStringCont`] is for, and it does not require the `csr` feature:
 *
 * ```
 *  #[component]
 *  fn MyComponentThatGetsAStringFromSomewhere() -> impl IntoView {
 *   // get some HTML string from somewhere
 *   // e.g. some API call
 *   let html = "<div data-replace-with-leptos>...</div>".to_string();
 *   view! {
 *     <DomStringCont html cont=replace/>
 *   }
 * }
 * ```
 *
 * See the `examples/ssr` directory for a full example.
*/

mod dom;
mod node;

pub use node::OriginalNode;

#[cfg(any(feature = "csr", feature = "hydrate"))]
pub use dom::hydrate_node;

use leptos::{html::Span, math::Mrow, prelude::*, web_sys::Element};

/// A component that calls `cont` on `orig` and all its children,
/// potentially "hydrating" them further, and reinserts the original
/// element into the DOM.
/// 
/// If ``skip_head`` is set to true, `cont` will not be called on the head element itself.
#[allow(unused_variables)] 
#[component]
pub fn DomCont<
    V: IntoView + 'static,
    R: FnOnce() -> V,
    F: Fn(&Element) -> Option<R> + 'static + Send,
>(
    orig: OriginalNode,
    cont: F,
    #[prop(optional)] skip_head: bool,
    #[prop(optional, into)] class: MaybeProp<String>,
    #[prop(optional, into)] style: MaybeProp<String>,
) -> impl IntoView {
    #[cfg(any(feature = "csr", feature = "hydrate"))]
    {
        let orig = orig
            .add_any_attr(leptos::tachys::html::class::class(move || class.get()))
            .add_any_attr(leptos::tachys::html::style::style(move || style.get()));
        orig.as_view(move |e| {
            if skip_head {
                dom::hydrate_children(e.clone().into(), &cont);
            } else {
                dom::hydrate_node(e.clone().into(), &cont);
            }
        })
    }
}

/// A component that inserts the  children of some [`OriginalNode`]
/// and renders them into the DOM.
#[allow(unused_variables)] 
#[component]
pub fn DomChildren(orig: OriginalNode) -> impl IntoView {
    #[cfg(any(feature = "csr", feature = "hydrate"))]
    {
        orig.child_vec()
            .into_iter()
            .map(|c| match c {
                leptos::either::Either::Left(c) => leptos::either::Either::Left(c.as_view(|_| ())),
                leptos::either::Either::Right(c) => leptos::either::Either::Right(c),
            })
            .collect_view()
    }
}

/// A component that inserts the  children of some [`OriginalNode`] like [`DomChildren`],
/// and then hydrates them using `cont` like [`DomCont`].
#[allow(unused_variables)] 
#[component]
pub fn DomChildrenCont<
    V: IntoView + 'static,
    R: FnOnce() -> V,
    F: Fn(&Element) -> Option<R> + 'static + Send + Clone,
>(
    orig: OriginalNode,
    cont: F,
) -> impl IntoView {
    #[cfg(any(feature = "csr", feature = "hydrate"))]
    {
        orig.child_vec()
            .into_iter()
            .map(|c| match c {
                leptos::either::Either::Left(c) => leptos::either::Either::Left({
                    if let Some(r) = cont(&c) {
                        leptos::either::Either::Left(r())
                    } else {
                        let cont = cont.clone();
                        leptos::either::Either::Right(
                            c.as_view(move |e| dom::hydrate_children(e.clone().into(), &cont)),
                        )
                    }
                }),
                leptos::either::Either::Right(c) => leptos::either::Either::Right(c),
            })
            .collect_view()
    }
}

/// A component that renders a string of valid HTML, and then hydrates the resulting DOM nodes 
/// using `cont` like [`DomCont`].
#[allow(unused_variables)] 
#[component]
pub fn DomStringCont<
    V: IntoView + 'static,
    R: FnOnce() -> V,
    F: Fn(&Element) -> Option<R> + 'static,
>(
    html: String,
    cont: F,
    #[prop(optional)] on_load: Option<RwSignal<bool>>,
    #[prop(optional, into)] class: MaybeProp<String>,
    #[prop(optional, into)] style: MaybeProp<String>,
) -> impl IntoView {
    let rf = NodeRef::<Span>::new();
    rf.on_load(move |e| {
        #[cfg(any(feature = "csr", feature = "hydrate"))]
        {
            dom::hydrate_children(e.into(), &cont);
        }
        if let Some(on_load) = on_load {
            on_load.set(true);
        }
    });
    view!(<span node_ref=rf inner_html=html
      class=move || class.get() style=move || style.get()
    />)
}

/// Like [`DomStringCont`], but using `<mrow>` instead of `<span>` initially, in case we are
/// in MathML (otherwise, there's a danger the browser will move the resulting nodes outside of the
/// `<math>` node!).
#[allow(unused_variables)] 
#[component]
pub fn DomStringContMath<
    V: IntoView + 'static,
    R: FnOnce() -> V + 'static,
    F: Fn(&Element) -> Option<R> + 'static + Send + Clone,
>(
    html: String,
    cont: F,
    #[prop(optional)] on_load: Option<RwSignal<bool>>,
    #[prop(optional, into)] class: MaybeProp<String>,
    #[prop(optional, into)] style: MaybeProp<String>,
) -> impl IntoView {
    let rf = NodeRef::<Mrow>::new();
    let cnt = cont.clone();
    rf.on_load(move |e| {
        #[cfg(any(feature = "csr", feature = "hydrate"))]
        {
            dom::hydrate_children(e.into(), &cnt);
        }
        if let Some(on_load) = on_load {
            on_load.set(true);
        }
    });
    view!(<mrow node_ref=rf inner_html=html class=move || class.get() style=move || style.get()/>)
}

// need some check to not iterate over the entire body multiple times for some reason.
// I'm not sure why this is necessary, but it seems to be.
#[cfg(feature = "csr")]
static DONE: std::sync::OnceLock<()> = std::sync::OnceLock::new();

/// Hydrates the entire DOM with leptos components, starting at the body.
///
/// `v` is a function that takes the [`OriginalChildren`] of the `<body>` (likely reinserting them somewhere) and returns some 
/// leptos view replacing the original children(!) of the body.
#[cfg(feature = "csr")]
pub fn hydrate_body<N: IntoView>(v: impl FnOnce(OriginalNode) -> N + 'static) {
    // make sure this only ever happens once.
    if DONE.get().is_some() {
        return;
    }
    DONE.get_or_init(|| ());
    let document = leptos::tachys::dom::document();
    // We check that the DOM has been fully loaded
    let state = document.ready_state();
    let go = move || {
        let body = leptos::tachys::dom::body();
        let nd = leptos::tachys::dom::document()
            .create_element("div")
            .expect("Error creating div");
        while let Some(c) = body.child_nodes().get(0) {
            nd.append_child(&c).expect("Error appending child");
        }
        mount_to_body(move || v(nd.into()));
    };
    if state == "complete" || state == "interactive" {
        go();
    } else {
        use leptos::wasm_bindgen::JsCast;
        let fun = std::rc::Rc::new(std::cell::Cell::new(Some(go)));
        let closure = leptos::wasm_bindgen::closure::Closure::wrap(Box::new(
            move |_: leptos::web_sys::Event| {
                if let Some(f) = fun.take() {
                    f()
                }
            },
        ) as Box<dyn FnMut(_)>);
        document
            .add_event_listener_with_callback("DOMContentLoaded", closure.as_ref().unchecked_ref())
            .unwrap();
        closure.forget();
    }
}

// ------------------------------------------------------------

#[cfg(any(feature = "csr", feature = "hydrate"))]
fn cleanup(node: leptos::web_sys::Node) {
    let c = send_wrapper::SendWrapper::new(node);
    Owner::on_cleanup(move || {
        if let Some(p) = c.parent_element() {
            let _ = p.remove_child(&c);
        }
    });
}

/*
#[cfg(any(feature="csr",feature="hydrate"))]
fn prettyprint(node:&web_sys::Node) -> String {
  use leptos::wasm_bindgen::JsCast;
  if let Some(e) = node.dyn_ref::<Element>() {
    e.outer_html()
  } else if let Some(t) = node.dyn_ref::<web_sys::Text>() {
    t.data()
  } else if let Some(c) = node.dyn_ref::<web_sys::Comment>() {
    c.data()
  } else {
    node.to_string().as_string().expect("wut")
  }
}
   */