vertigo 0.11.2

#![doc = include_str!("../README.md")]

//!
//! # Short-links to most commonly used things
//!
//! * DOM creation
//!   * [main] - Wraps function to be vertigo entry-point
//!   * [dom!] - Builds [DomNode] using RSX/rstml (HTML-like) syntax
//!   * [css!] - Builds [Css] using CSS-like syntax
//!   * [tw!] - Wraps tailwind class names
//!   * [component] - Wraps function to be used as component in RSX
//! * Data storing
//!   * [Value] - Read-write reactive value
//!   * [Computed] - Read-only (computed) reactive value
//!   * [LazyCache] - Lazy cache for fetched resources
//!   * [store] - Wraps function to be used as a store (singleton) generator
//! * Others
//!   * [bind!] - Auto-clones variables before use
//!   * [get_driver] - Access to browser facilities
//!   * [router::Router] - Hash or history routing

#![deny(rust_2018_idioms)]
#![cfg_attr(test, allow(clippy::panic_in_result_fn))]

mod computed;
mod css;
pub mod dev;
mod dom;
mod dom_macro;
mod driver_module;
mod exports;
pub mod external_api;
mod fetch;
mod future_box;
pub mod html_entities;
mod instant;
pub mod render;
pub mod router;
#[cfg(test)]
mod tests;
mod websocket;

// Exports from vertigo

pub use computed::{
    AutoMap, Computed, Dependencies, DropResource, Reactive, ToComputed, Value, context::Context,
};
pub use css::{
    css_structs::{Css, CssGroup},
    tailwind_class::TwClass,
};
pub use dom::{
    attr_value::{AttrValue, CssAttrValue},
    dom_comment::DomComment,
    dom_element::DomElement,
    dom_element_ref::DomElementRef,
    dom_id::DomId,
    dom_node::DomNode,
    dom_text::DomText,
    events::{ClickEvent, DropFileEvent, DropFileItem, KeyDownEvent},
};
pub use dom_macro::{AttrGroup, AttrGroupValue, EmbedDom};
pub use driver_module::{
    driver::{Driver, FetchMethod, FetchResult, get_driver, transaction},
    js_value::{
        JsJson, JsJsonContext, JsJsonDeserialize, JsJsonNumber, JsJsonSerialize, from_json, to_json,
    },
};
pub use exports::start_app;
pub use fetch::{
    lazy_cache::{self, LazyCache},
    request_builder::{RequestBody, RequestBuilder, RequestResponse},
    resource::Resource,
};
pub use instant::{Instant, InstantType};
pub use render::collection::CollectionKey;
pub use websocket::{WebsocketConnection, WebsocketMessage};

// Commonly used things
pub mod prelude {
    pub use crate::{Computed, Css, DomNode, ToComputed, Value, bind, component, css, dom};
}

// Re-export log module which can be used in vertigo plugins
pub use log;

/// Spawn a future - thus allowing to fire async functions in, for example, event handler. Handy when fetching resources from internet.
pub fn spawn(future: impl Future<Output = ()> + 'static) {
    get_driver().spawn(future)
}

// Re-export self for tests and macros used in vertigo crate
extern crate self as vertigo;

// Below re-exports from vertigo_macro

/// Allows to include a static file
///
/// This will place the file along with the rest of generated files. The macro returns a public path to the file with it's hash in name.
pub use vertigo_macro::include_static;

/// Allows to trace tailwind class names.
///
/// To use tailwind class name outside of literal tw attribute value, wrap it with `tw!` macro, so it gets traced by tailwind bundler.
///
/// Note that use of tailwind automatically adds tailwind base css sheet which zeroes various default rules.
///
/// ```rust
/// use vertigo::{dom, tw};
///
/// let my_class = tw!("flex");
///
/// dom! {
///     <div tw={my_class}>
///         <p>"One"</p>
///         <p>"Two"</p>
///     </div>
/// };
/// ```
pub use vertigo_macro::tw;

/// Allows to conveniently clone values into closure.
///
/// ```rust
/// use vertigo::{bind, dom, Value};
///
/// let count = Value::new(0);
///
/// let increment = bind!(count, |_| {
///     count.change(|value| {
///         *value += 1;
///     });
/// });
///
/// dom! {
///     <div>
///         <p>"Counter: " { count }</p>
///         <button on_click={increment}>"+"</button>
///     </div>
/// };
/// ```
///
/// Binding complex names results in last part being accessible inside:
///
/// ```rust
/// use vertigo::bind;
///
/// struct Point {
///     pub x: i32,
///     pub y: i32,
/// }
///
/// let point = Point { x: 1, y: 2 };
///
/// let callback = bind!(point.x, point.y, || {
///     println!("Point: ({x}, {y})");
/// });
/// ```
pub use vertigo_macro::bind;

/// Allows to create an event handler based on provided arguments which is wrapped in Rc
pub use vertigo_macro::bind_rc;

/// Allows to create an event handler based on provided arguments which launches an asynchronous action
pub use vertigo_macro::bind_spawn;

/// Macro for creating `JsJson` from structures and structures from `JsJson`.
///
/// Used for fetching and sending objects over the network.
///
/// Enums representation is compatible with serde's "external tagging" which is the default.
///
/// # Options
///
/// ## Container Options
///
/// * `rename_all = "..."`: Rename all fields according to the given case convention.
///   Supported values: `PascalCase`, `camelCase`, `snake_case`, `kebab-case`, `SHOUTY_SNAKE_CASE`, `UPPERCASE`, `lowercase`.
///
/// ## Field Options
///
/// * `default`: Default value for the field if it is missing in the JSON.
///   If no value is provided, `Default::default()` is used.
/// * `rename = "..."`: Rename the field to the given string.
/// * `stringify`: Serialize the field using `Display` and deserialize using `FromStr`. Useful for foreign structs.
///
/// # Example
///
/// ```rust
/// use vertigo::AutoJsJson;
///
/// #[derive(AutoJsJson)]
/// #[js_json(rename_all = "camelCase")]
/// pub struct Post {
///     pub id: i64,
///     pub name: String,
///     #[js_json(default)]
///     pub visible: bool,
///     #[js_json(stringify)]
///     pub status: Status,
/// }
///
/// #[derive(Clone)]
/// pub enum Status {
///     Active,
///     Inactive,
/// }
///
/// impl std::fmt::Display for Status {
///     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
///         match self {
///             Status::Active => write!(f, "active"),
///             Status::Inactive => write!(f, "inactive"),
///         }
///     }
/// }
///
/// impl std::str::FromStr for Status {
///     type Err = String;
///
///     fn from_str(s: &str) -> Result<Self, Self::Err> {
///         match s {
///             "active" => Ok(Status::Active),
///             "inactive" => Ok(Status::Inactive),
///             _ => Err("Invalid status".to_string()),
///         }
///     }
/// }
///
/// let post = Post {
///     id: 1,
///     name: "Hello".to_string(),
///     visible: true,
///     status: Status::Active,
/// };
///
/// let js_json = vertigo::to_json(post);
///
/// let post2 = vertigo::from_json::<Post>(js_json);
/// ```
///
/// # Creating newtypes for foreign types
///
/// Option `stringify` can be used for newtypes to serialize them using `Display` and deserialize using `FromStr`.
///
/// ```rust
/// use vertigo::AutoJsJson;
///
/// // Let's say we have a type that implements `Display` and `FromStr`
/// // but doesn't support JsJson serialization
/// struct ForeignType(i64);
///
/// # impl std::fmt::Display for ForeignType {
/// #     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
/// #         write!(f, "{}", self.0)
/// #     }
/// # }
/// # impl std::str::FromStr for ForeignType {
/// #     type Err = String;
/// #
/// #     fn from_str(s: &str) -> Result<Self, Self::Err> {
/// #         Ok(ForeignType(s.parse().map_err(|_| "Invalid value".to_string())?))
/// #     }
/// # }
///
/// // We can use `stringify` option to serialize it
/// // using `Display` and deserialize using `FromStr`
/// #[derive(AutoJsJson)]
/// struct MyType(#[js_json(stringify)] ForeignType);
pub use vertigo_macro::AutoJsJson;

/// Macro which transforms a provided function into a component that can be used in [dom!] macro
///
/// ```rust
/// use vertigo::prelude::*;
///
/// #[component]
/// pub fn Header(name: Value<String>) {
///     dom! {
///         <div>"Hello" {name}</div>
///     }
/// }
///
/// let name = Value::new("world".to_string());
///
/// dom! {
///     <div>
///        <Header name={name} />
///     </div>
/// };
/// ```
///
/// ```rust
/// use vertigo::{bind, component, dom, AttrGroup, Value};
///
/// #[component]
/// pub fn Input<'a>(label: &'a str, value: Value<String>, input: AttrGroup) {
///     let on_input = bind!(value, |new_value: String| {
///         value.set(new_value);
///     });
///
///     dom! {
///         <div>
///             {label}
///             <input {value} {on_input} {..input} />
///         </div>
///     }
/// }
///
/// let value = Value::new("world".to_string());
///
/// dom! {
///     <div>
///        <Input label="Hello" {value} input:name="hello_value" />
///     </div>
/// };
/// ```
///
/// Note: [AttrGroup] allows to dynamically pass arguments to some child node.
pub use vertigo_macro::component;

/// Macro that allows to evaluate pseudo-JavaScript expressions.
///
/// Example 1:
///
/// ```rust
/// use vertigo::js;
///
/// let referrer = js!{ document.referrer };
/// ```
///
/// Example 2:
///
/// ```rust
/// # use vertigo::js;
/// let max_y = js!{ window.scrollMaxY };
/// js! { window.scrollTo(0, max_y) };
/// ```
///
/// Can be used with [DomElementRef]:
///
/// ```rust
/// use vertigo::{js, dom_element};
///
/// let node = dom_element! { <input /> };
/// let node_ref = node.get_ref();
/// js! { #node_ref.focus() };
/// ```
///
/// Passing an object as an argument is a little more complicated, but possible:
///
/// ```rust
/// # use vertigo::js;
/// js! {
///     window.scrollTo(
///         vec![
///             ("top", 100000.into()),
///             ("behavior", "smooth".into()),
///         ]
///     )
/// };
/// ```
#[macro_export]
macro_rules! js {
    // Convert `#ref_node.anything` into `#[ref_node] anything` which can be handled by js_inner macro.
    ( #$ident:ident.$expr:expr ) => {
        $crate::js_inner! { #[$ident] $expr }
    };
    // Otherwise be transparent.
    ( $expr:expr ) => {
        $crate::js_inner! { $expr }
    };
}

/// Used internally by [js!] macro.
pub use vertigo_macro::js_inner;

/// Marco that marks an entry point of the app
///
/// Note: Html, head and body tags are required by vertigo to properly take over the DOM
///
/// Note 2: When using external tailwind, make sure the source `tailwind.css` file is in the same directory as usage of this macro.
///
/// ```rust
/// use vertigo::prelude::*;
///
/// #[vertigo::main]
/// fn app() -> DomNode {
///     dom! {
///         <html>
///             <head/>
///             <body>
///                 <div>"Hello world"</div>
///             </body>
///         </html>
///     }
/// }
/// ```
pub use vertigo_macro::main;

/// Allows to create [DomNode] using RSX/rstml (HTML-like) syntax.
///
/// Simple DOM with a param embedded:
///
/// ```rust
/// use vertigo::dom;
///
/// let value = "world";
///
/// dom! {
///     <div>
///         <h3>"Hello " {value} "!"</h3>
///         <p>"Good morning!"</p>
///     </div>
/// };
/// ```
///
/// Mapping and embedding an `Option`:
///
/// ```rust
/// use vertigo::dom;
///
/// let name = "John";
/// let occupation = Some("Lumberjack");
///
/// dom! {
///     <div>
///         <h3>"Hello " {name} "!"</h3>
///         {..occupation.map(|occupation| dom! { <p>"Occupation: " {occupation}</p> })}
///     </div>
/// };
/// ```
///
/// Note the spread operator which utilizes the fact that `Option` is iterable in Rust.
pub use vertigo_macro::dom;

/// Allows to create [DomElement] using HTML tags.
///
/// Unlike [DomNode] generated by the [dom!] macro, it can't generate multiple nodes at top level,
/// but allows to mangle with the outcome a little more, for example using [DomElement::add_child].
pub use vertigo_macro::dom_element;

/// Version of [dom!] macro that additionally emits compiler warning with generated code.
pub use vertigo_macro::dom_debug;

/// Allows to create [Css] styles for usage in [dom!] macro.
///
/// ```rust
/// use vertigo::{css, dom};
///
/// let green_on_red = css! {"
///     color: green;
///     background-color: red;
/// "};
///
/// dom! {
///    <div css={green_on_red}>"Tomato stem"</div>
/// };
/// ```
///
/// ```rust
/// use vertigo::{css, Css, dom};
///
/// fn css_menu_item(active: bool) -> Css {
///     let bg_color = if active { "lightblue" } else { "lightgreen" };
///
///     css! {"
///         cursor: pointer;
///         background-color: {bg_color};
///
///         :hover {
///             text-decoration: underline;
///         }
///     "}
/// }
///
/// dom! {
///     <a css={css_menu_item(true)}>"Active item"</a>
///     <a css={css_menu_item(false)}>"Inactive item"</a>
/// };
/// ```
///
/// See [tooltip demo](https://github.com/vertigo-web/vertigo/blob/master/demo/app/src/app/styling/tooltip.rs) for more complex example.
pub use vertigo_macro::css;

/// Constructs a CSS block that can be manually pushed into existing [Css] styles instance.
///
/// ```rust
/// use vertigo::{css, css_block};
///
/// let mut green_style = css! {"
///     color: green;
/// "};
///
/// green_style.push_str(
///     css_block! {"
///         font-style: italic;
///    "}
/// );
/// ```
pub use vertigo_macro::css_block;

/// Wraps a function generating a resource out of parameters, and creates a store.
///
/// Accessing the store from different locations uses always the same store
/// as data is kept using [LocalKey](std::thread::LocalKey).
///
/// ```rust
/// use vertigo::{AutoJsJson, LazyCache, RequestBuilder, store};
///
/// #[derive(AutoJsJson, PartialEq)]
/// struct CommentModel {
///     id: i32,
///     name: String,
/// }
///
/// #[store]
/// fn get_post(post_id: &String) -> LazyCache<Vec<CommentModel>> {
///     RequestBuilder
///         ::get(format!("https://jsonplaceholder.typicode.com/posts/{post_id}/comments"))
///         .ttl_minutes(10)
///         .lazy_cache(|status, body| {
///             if status == 200 {
///                 Some(body.into::<Vec<CommentModel>>())
///             } else {
///                 None
///             }
///         })
/// }
pub use vertigo_macro::store;