next_rust_view/lib.rs
1//! The Next Rust view layer.
2//!
3//! ```
4//! use next_rust_view::*;
5//!
6//! fn card(title: &str) -> impl View {
7//! div![class("card"), h2![title], p!["Escaped by default: <b>"]]
8//! }
9//!
10//! let html = render_static(card("Hello"));
11//! assert_eq!(html, r#"<div class="card"><h2>Hello</h2><p>Escaped by default: <b></p></div>"#);
12//! ```
13//!
14//! Design:
15//!
16//! * Element macros (`div!`, `p!`, ...) build an [`Element`] from a list of
17//! *parts*. A part is either an attribute ([`Attr`]) or a child view.
18//! * Everything that can be rendered implements [`View`], which converts it
19//! into a [`Node`] tree. Components are plain functions returning `impl View`.
20//! * All text and attribute values are escaped. Raw HTML requires
21//! [`raw_html`], which is intentionally conspicuous.
22//! * Async content is expressed with [`suspense`] and can be streamed.
23
24#![forbid(unsafe_code)]
25
26pub mod attrs;
27pub mod class_names;
28pub mod components;
29mod css_split;
30mod escape;
31pub mod metadata;
32mod node;
33mod render;
34pub mod style;
35mod tags;
36
37pub use attrs::*;
38pub use components::{Children, ImageProps, LinkProps, Slots, each, fragment_of, island, raw_html, suspense, when};
39pub use css_split::restyle_document;
40pub use escape::{escape_attr, escape_text, is_safe_url};
41pub use metadata::Metadata;
42pub use node::{Attr, AttrValue, Element, IntoViewResult, Node, Part, Suspense, View};
43pub use render::{
44 DocumentParts, RenderFlags, STREAMING_RUNTIME, render_static, render_to_string, resolve, script_key,
45 stream_document,
46};
47pub use style::{CssClass, Stylesheet};
48pub use tags::{TAGS, VOID_TAGS};
49
50/// Group children without a wrapper element: `fragment![a, b, c]`.
51#[macro_export]
52macro_rules! fragment {
53 ($($child:expr),* $(,)?) => {
54 $crate::Node::Fragment(vec![$($crate::View::into_node($child)),*])
55 };
56}
57
58/// Client-side-navigation aware link.
59///
60/// ```
61/// use next_rust_view::*;
62/// let html = render_static(Link!(href = "/about", class = "nav", "About"));
63/// assert_eq!(html, r#"<a href="/about" class="nav" data-nr-link="">About</a>"#);
64/// ```
65#[macro_export]
66macro_rules! Link {
67 ($($body:tt)*) => { $crate::__link_munch!([$crate::Element::new("a")] $($body)*) };
68}
69
70#[doc(hidden)]
71#[macro_export]
72macro_rules! __link_munch {
73 ([$($acc:tt)*]) => { $($acc)*.with($crate::attrs::data("nr-link", "")) };
74 ([$($acc:tt)*] $key:ident = $val:expr $(, $($rest:tt)*)?) => {
75 $crate::__link_munch!([$($acc)*.with($crate::attrs::$key($val))] $($($rest)*)?)
76 };
77 ([$($acc:tt)*] $child:expr $(, $($rest:tt)*)?) => {
78 $crate::__link_munch!([$($acc)*.with($child)] $($($rest)*)?)
79 };
80}
81
82/// Responsive, lazily loaded image.
83///
84/// ```
85/// use next_rust_view::*;
86/// let html = render_static(Image!(src = "/cat.jpg", width = 640, height = 480, alt = "A cat"));
87/// assert!(html.starts_with(r#"<img src="/_next-rust/image?url=%2Fcat.jpg&w=640&q=75""#));
88/// assert!(html.contains(r#"loading="lazy""#));
89/// ```
90#[macro_export]
91macro_rules! Image {
92 ($($key:ident = $val:expr),* $(,)?) => {
93 $crate::ImageProps::default()$(.$key($val))*
94 };
95}