I contain ()! My size is <B>0</B> bytes. I'm located at address 0x559f637aa500.
-I contain ()! My size is <B>0</B> bytes. I'm located at address 0x559f637aa500.
-I contain 1! My size is <B>1</B> bytes. I'm located at address 0x559f637aa508.
-I contain 2! My size is <B>8</B> bytes. I'm located at address 0x559f637aa500.
-The container instance occupies <B>16</B> bytes at 0x559f637aa500.
+I contain ()! My size is <B>0</B> bytes. I'm located at address 0x55907f620500.
+I contain ()! My size is <B>0</B> bytes. I'm located at address 0x55907f620500.
+I contain 1! My size is <B>1</B> bytes. I'm located at address 0x55907f620508.
+I contain 2! My size is <B>8</B> bytes. I'm located at address 0x55907f620500.
+The container instance occupies <B>16</B> bytes at 0x55907f620500.
The layout here is somewhat implementation-defined, but generally what you should see is that the MySize::<()> instances take up no space inside the Container instance and don't displace other children in memory.
This is because Asteracea components contain no hidden instance state, which means they are sized to content (and padding requirements), all the way down to zero. () is Rust's unit type, the most convenient zero sized type. The same applies to components without instance fields, of course.
diff --git a/searchindex.js b/searchindex.js
index 930a84c..f8b970d 100644
--- a/searchindex.js
+++ b/searchindex.js
@@ -1 +1 @@
-Object.assign(window.search, {"doc_urls":["intro.html#introduction","intro.html#this-book-is-a-work-in-progress","intro.html#this-framework-is-a-work-in-progress","intro.html#what-works","intro.html#what-isnt-finished","intro.html#whats-missing","intro.html#audience","intro.html#background","intro.html#asteraceas-design-goals","0_sneak_peek.html#chapter-0-sneak-peek","static_components/index.html#chapter-1-static-components","static_components/empty_component.html#an-empty-component","static_components/empty_component.html#the-breakdown","static_components/empty_component.html#pub-visibility","static_components/empty_component.html#empty-component-name","static_components/empty_component.html#-constructor-argument-list","static_components/empty_component.html#-render-argument-list","static_components/empty_component.html#-body--empty-multi-node","static_components/rust_comments.html#rust-comments","static_components/html_comments.html#html-comments","static_components/text.html#text","static_components/text.html#multiple-text-elements","static_components/elements.html#elements","static_components/child_components.html#child-components","static_components/child_components.html#child-component-instancing","static_components/ex_stateless_components_are_zero-sized.html#ex-stateless-components-are-zero-sized","dynamic_components/escalation.html#escalation","dynamic_components/escalation.html#handling-panics","dynamic_components/new_with.html#new-with---","dynamic_components/predefined_lifetimes.html#predefined-lifetimes","dynamic_components/conditional_attributes.html#conditional-attributes","dynamic_components/conditional_attributes.html#boolean-attributes","dynamic_components/argument_defaults.html#argument-defaults","dynamic_components/optional_arguments.html#optional-arguments","dynamic_components/conditional_child_component_parameters.html#conditional-child-component-parameters","dynamic_components/body_captures.html#persistence-2-body-captures","dynamic_components/dependency_extraction.html#dependency-extraction","dynamic_components/with.html#with---","conditional_content/spread_if.html#spread-if-","conditional_content/spread_if.html#pattern-matching-with-let","conditional_content/spread_if_else.html#spread-if--else","conditional_content/for.html#for-loops","conditional_content/spread_match.html#spread-match------","conditional_content/box.html#box-priv--struct--where-","conditional_content/box.html#component-recursion","conditional_content/box.html#memory-savings","conditional_content/defer.html#defer-storage","conditional_content/defer.html#naming-the-field","conditional_content/bind.html#bind-storage-move","misc/glossary.html#glossary","misc/glossary.html#element-expression","ex_hello_asteracea.html#chapter-1-hello-asteracea"],"index":{"documentStore":{"docInfo":{"0":{"body":4,"breadcrumbs":2,"title":1},"1":{"body":50,"breadcrumbs":4,"title":3},"10":{"body":80,"breadcrumbs":7,"title":4},"11":{"body":145,"breadcrumbs":7,"title":2},"12":{"body":9,"breadcrumbs":6,"title":1},"13":{"body":28,"breadcrumbs":7,"title":2},"14":{"body":35,"breadcrumbs":8,"title":3},"15":{"body":32,"breadcrumbs":8,"title":3},"16":{"body":87,"breadcrumbs":8,"title":3},"17":{"body":111,"breadcrumbs":9,"title":4},"18":{"body":66,"breadcrumbs":7,"title":2},"19":{"body":52,"breadcrumbs":7,"title":2},"2":{"body":17,"breadcrumbs":4,"title":3},"20":{"body":56,"breadcrumbs":5,"title":1},"21":{"body":212,"breadcrumbs":7,"title":3},"22":{"body":116,"breadcrumbs":5,"title":1},"23":{"body":148,"breadcrumbs":7,"title":2},"24":{"body":90,"breadcrumbs":8,"title":3},"25":{"body":211,"breadcrumbs":13,"title":5},"26":{"body":167,"breadcrumbs":5,"title":1},"27":{"body":64,"breadcrumbs":6,"title":2},"28":{"body":45,"breadcrumbs":5,"title":1},"29":{"body":60,"breadcrumbs":7,"title":2},"3":{"body":57,"breadcrumbs":2,"title":1},"30":{"body":62,"breadcrumbs":7,"title":2},"31":{"body":59,"breadcrumbs":7,"title":2},"32":{"body":51,"breadcrumbs":7,"title":2},"33":{"body":51,"breadcrumbs":7,"title":2},"34":{"body":136,"breadcrumbs":11,"title":4},"35":{"body":5,"breadcrumbs":11,"title":4},"36":{"body":21,"breadcrumbs":7,"title":2},"37":{"body":95,"breadcrumbs":3,"title":0},"38":{"body":74,"breadcrumbs":5,"title":1},"39":{"body":83,"breadcrumbs":6,"title":2},"4":{"body":38,"breadcrumbs":3,"title":2},"40":{"body":25,"breadcrumbs":5,"title":1},"41":{"body":194,"breadcrumbs":5,"title":1},"42":{"body":41,"breadcrumbs":7,"title":2},"43":{"body":91,"breadcrumbs":9,"title":3},"44":{"body":66,"breadcrumbs":8,"title":2},"45":{"body":115,"breadcrumbs":8,"title":2},"46":{"body":74,"breadcrumbs":7,"title":2},"47":{"body":52,"breadcrumbs":7,"title":2},"48":{"body":90,"breadcrumbs":9,"title":3},"49":{"body":0,"breadcrumbs":4,"title":1},"5":{"body":29,"breadcrumbs":3,"title":2},"50":{"body":6,"breadcrumbs":5,"title":2},"51":{"body":109,"breadcrumbs":7,"title":4},"6":{"body":63,"breadcrumbs":2,"title":1},"7":{"body":355,"breadcrumbs":2,"title":1},"8":{"body":354,"breadcrumbs":4,"title":3},"9":{"body":202,"breadcrumbs":7,"title":4}},"docs":{"0":{"body":"Welcome to the Asteracea guide book!","breadcrumbs":"Introduction » Introduction","id":"0","title":"Introduction"},"1":{"body":"Until the first minor version stabilisation, there likely will only be this develop-branch version published online as rendered version, which usually won't mach a version of the crate published to crates.io. (Respective versions are tagged and can be rendered offline using (from the repository's root directory) cd book and cargo run.) In addition to the missing chapters, URLs are subject to change, links have have not been filled in and code blocks without highlighting or rendered HTML output may show unimplemented features.","breadcrumbs":"Introduction » This book is a work in progress!","id":"1","title":"This book is a work in progress!"},"10":{"body":"Asteracea, unlike for example React , does not have multiple ways to define a component depending on whether you'd like to use instance state or not¹. Instead, due to low syntactic overhead and Rust's efficiency, struct components are generated throughout. Stateless struct components have zero runtime overhead compared to functions equivalent fragment! use. This, along with less boilerplate and for consistency, is why I generally recommend component! for all reusable GUI elements. In this chapter, I will introduce the basics of generating various virtual DOM nodes in Asteracea, which can then be translated into (e.g.!) HTML or browser DOM elements. ¹ The distinction has weakened in React recently. Asteracea's approach to stateful components is partially inspired by React's Hooks in terms of UX, but is implemented very differently below the surface.","breadcrumbs":"1: Static Components » Chapter 1: Static Components","id":"10","title":"Chapter 1: Static Components"},"11":{"body":"As mentioned in the introduction, the simplest Asteracea component is E()()[]. In context, and written more like what you'd see in the wild: asteracea::component! { Empty()() []\n} (All Asteracea component examples are followed by their output as rendered by lignin-html , but in this case it's an empty string.) This component expands to the following Rust code, with use imports extracted by hand to improve readability: //TODO As you can see, the component! macro created a struct type, with one constructor called new and one method called render, as well as a few helper types and functions that enable named arguments, and a Drop implementation. The output of component!, as far as you're supposed to touch it, always has this shape. No exceptions. Identifiers containing __Asteracea__ are considered internal and may change at any point in time. Please don't use them directly, even if technically accessible! You may find small bits of similar useless syntax like those empty {} blocks in new. Some of these pieces of code nudge Rust into giving you a better error message or block off certain edge cases (usually inner attributes) that either would be confusing to read or haven't been properly evaluated yet, while others, like the empty unsafe {} in drop are slots where code is placed when generating more complex components, and which should be effectively removed by the compiler if empty. (If you notice such an empty construct that impacts runtime performance or Wasm assembly size, please file a bug report.)","breadcrumbs":"1: Static Components » An Empty Component » An Empty Component","id":"11","title":"An Empty Component"},"12":{"body":"There are five distinct pieces of syntax that are translated into the output here: pub, Empty, (), () and [].","breadcrumbs":"1: Static Components » An Empty Component » The breakdown","id":"12","title":"The breakdown"},"13":{"body":"This is a plain Rust visibility and inserted just before the struct keyword in the macro output above, controlling where the component can be used directly. Leave it out to for current-module-only visibility. new and render are always declared pub; They inherit their visibility from the component structure.","breadcrumbs":"1: Static Components » An Empty Component » pub (visibility)","id":"13","title":"pub (visibility)"},"14":{"body":"This identifier is inserted verbatim into the output as shown. There aren't any requirements regarding which identifier to use, but I encourage you to avoid generic suffixes like \"…Component\". Consider e.g. \"…ListItem\", \"…Button\" or, if nothing more specific applies, \"…Panel\" as more descriptive alternatives, or leave the suffix off entirefly if there's no confusion regarding which types are components and which are not.","breadcrumbs":"1: Static Components » An Empty Component » Empty (component name)","id":"14","title":"Empty (component name)"},"15":{"body":"This is the first pair of parenthese in the input and also appears before the other in the output. As you can see, it is inserted verbatim after new here. You can use any normal argument declaration here, with the exception of self parameters. The constructor argument list also supports a shorthand to declare and assign fields on the component instance, but more on that [later].","breadcrumbs":"1: Static Components » An Empty Component » () (constructor argument list)","id":"15","title":"() (constructor argument list)"},"16":{"body":"The second pair of parentheses is used to declare additional render arguments. This one is never pasted verbatim into the resulting component, despite supporting only plain Rust argument declarations (with the exception of self parameters and, usually, bump). Instead, its items are inserted at the end of render's argument list above, after the implicit arguments &self and bump: &'bump Bump. You can access instance fields through self in the component body (more on that later) and bump is a Bump from bumpalo , a bump allocation arena that makes the VDOM more efficient. Do not place anything into bump that needs to be dropped! Bump allocators are speedy, but this speed is bought by not running any logic before the memory is reused. Some workarounds for common use cases exist, but for the most part Asteracea handles this for you. See bumpalo 's documentation for more information.","breadcrumbs":"1: Static Components » An Empty Component » () (render argument list)","id":"16","title":"() (render argument list)"},"17":{"body":"The location of [] in this example component is called the body of the component. [] itself is an empty Multi Node , which expands to Node::Multi(&*bump.alloc_with(|| [])). The contents of this node are placed in the bump allocation arena which, in this case, is effectively no operation. Location and length of this list are stored in the containing [Node], which here is returned directly from render. It's legal to reuse [Node] instances in multiple places in the VDOM tree. You can also cache long-lived [Node]s and then refer to them across multiple render cycles, to avoid re-rendering part of the VDOM. Multi Nodes are a VDOM concept that doesn't translate into DOM: Their contents are replicated without nesting in the surrounding DOM structure. You can use them, for example, to return multiple elements at the top level of a component. Another use is to represent a variable number of elements, including none. The diffing algorithm in lignin-dom advances by a single VDOM sibling when processing a multi node. This means that you can avoid shifting any following sibling nodes, which can avoid expensively recreating their DOM representation or confusing the user by moving their selection to an unexpected place.","breadcrumbs":"1: Static Components » An Empty Component » [] (body / empty Multi Node)","id":"17","title":"[] (body / empty Multi Node)"},"18":{"body":"You can use three distinct types of comments in Asteracea macros, all serving different purposes: First, standard Rust comments can be placed anywhere in Asteracea components (or any other place in a Rust program), and are not included in the compiled binary: asteracea::component! { Commented()() [ // This is a one-line comment. /* /* These are *nested* multiline comments. */ */ ]\n} Additionally, Rust documentation is supported in many places: asteracea::component! { /// This is a documented component. /// Running `cargo doc` will pick up on its documentation. pub Documented()() -> Sync []\n} These /// (or //!) annotations are not included in the compiled binary either¹, but can be picked up by standard Rust tooling like rust-analyzer . ¹ Rare exceptions in combination with other macros apply.","breadcrumbs":"1: Static Components » Rust Comments » Rust Comments","id":"18","title":"Rust Comments"},"19":{"body":"The third kind of comment is specific to Asteracea and does affect program output: asteracea::component! { HtmlCommented()() \n} The double quotes are a Rust limitation: Since Rust tokenises macro input, a string literal is required to extract raw text. You can use a multiline string to easily write a multiline HTML comment: asteracea::component! { HtmlCommented()() \n} ","breadcrumbs":"1: Static Components » HTML Comments » HTML comments","id":"19","title":"HTML comments"},"2":{"body":"It works alright for very simple examples right now, but certain parts of the grammar related to efficiently defining dynamic content haven't landed yet.","breadcrumbs":"Introduction » This framework is a work in progress!","id":"2","title":"This framework is a work in progress!"},"20":{"body":"To output a static plain Text element in Asteracea, simply use a text literal in your component's body: asteracea::component! { Text()() \"This is text.\"\n} This is text. The macro output is largely the same as for the Empty component, but the render method has changed: use lignin::Node; # pub struct Text {}\n# impl Text {\n# pub fn new() -> Self {\n# Self {}\n# }\n// …\n// TODO\n// …\n# } (Click the eye icon to view the rest of the macro output. Note that this also displays a hidden main method inserted by mdBook which isn't part of component!'s output.)","breadcrumbs":"1: Static Components » Text » Text","id":"20","title":"Text"},"21":{"body":"Text nodes can be used as children of other nodes, for example a Multi Node: asteracea::component! { TextMulti()() [ \"This is text.\" \"This is also text.\" ]\n} This is text.This is also text. use asteracea::bumpalo::Bump;\nuse lignin::{Node, ThreadBound}; # pub struct TextMulti {}\n# impl TextMulti {\n# pub fn new() -> Self {\n# Self {}\n# }\n// …\npub fn render<'a, 'bump>( self: ::std::pin::Pin<&'a Self>, bump: &'bump asteracea::bumpalo::Bump, TextMultiRenderArgs { __Asteracea__phantom: _, }: TextMultiRenderArgs<'_, 'a, 'bump>,\n) -> ::std::result::Result< impl TextMulti__Asteracea__AutoSafe< ::asteracea::lignin::Node<'bump, ::asteracea::lignin::ThreadBound>, >, ::asteracea::error::Escalation,\n> { let this = self; ::std::result::Result::Ok( ::asteracea::lignin::Node::Multi::<'bump, _>(&*bump.alloc_try_with( || -> ::std::result::Result<_, ::asteracea::error::Escalation> { ::std::result::Result::Ok([ ::asteracea::lignin::auto_safety::Align::align( ::asteracea::lignin::Node::Text::<'bump, _> { text: \"This is text.\", dom_binding: None, } .prefer_thread_safe(), ), ::asteracea::lignin::auto_safety::Align::align( ::asteracea::lignin::Node::Text::<'bump, _> { text: \"This is also text.\", dom_binding: None, } .prefer_thread_safe(), ), ]) }, )?) .prefer_thread_safe(), )\n}\n// …\n# }\n#\n# #[allow(non_camel_case_types)]\n# lignin::auto_safety::AutoSafe_alias!(pub TextMulti__Asteracea__AutoSafe);\n#\n# pub struct TextMultiRenderArgs<'render, 'a, 'bump> {\n# __Asteracea__phantom: ::core::marker::PhantomData<(&'render (), &'a (), &'bump ())>,\n# } Note that there is no space between the sentences in the generated HTML. Asteracea gives you fairly precise control over the output, but that also means it won't make changes to the document's whitespace for you. If there's no whitespace in the literal in the input, then there won't be whitespace in the content of the output (when rendering with lignin-html or lignin-dom ). There is one important difference between the HTML and DOM output of adjacent sibling Text nodes: In HTML, it is impossible to distinguish them and browsers will parse them as single DOM node. When manipulating the DOM directly, the distinct text nodes will be preserved. This is one of the reasons that a client-side renderer must once parse the existing DOM into a VDOM when hydrating an app. Another good reason is that user-supplied browser extensions may have made changes to the DOM tree. ( Please don't render into directly! Many browser extensions insert their own scripts or overlays as child elements here. While it's not too likely that these additions will make your app crash, the GUI may glitch and appear for example duplicated. Rendering into, for example, a instead is more reliable.) Multi Nodes generated by Asteracea macros always place their contents in the bump allocation arena, even if those contents are theoretically immutable.","breadcrumbs":"1: Static Components » Text » Multiple Text elements","id":"21","title":"Multiple Text elements"},"22":{"body":"To define elements and their contents, Asteracea provides a syntax similar to HTML: asteracea::component! { Div()() \n} is enough to close one. However, you can alternatively close elements with /name> too, which the compiler will validate: asteracea::component! { Div()() \n} Elements can contain any number of valid Asteracea component bodies, which are rendered as the element's children, as long as the specific element supports it: asteracea::component! { Span()() .\" >\n} This is text within a <span>. This includes other elements: asteracea::component! { DivSpan()() .\"> >\n} This is text within a <span>. Elements are statically validated against lignin-schema . Empty elements like
are written like any other element, but don't accept children and won't render a closing tag to HTML when using lignin-html : asteracea::component! { Br()()
\n}
To use custom element names without validation, quote them like this: asteracea::component! { Custom()() <\"custom-element\">\n} ( //TODO: Hide this initially and show an ellipsis comment. // Generic parameters must be used in an instance field. // We can pretend this is the case using a constructor parameter capture. // `PhantomData` is a type that provides fake storage semantics. priv _phantom: PhantomData = PhantomData::default(), )() \"Generic body.\"\n} asteracea::component! { Outer()() [ <*Inner> \"\\n\" <*module::Module> \"\\n\" <*Generic::<()>> // Mind the turbofish! ::<> 🐟💨 ]\n} Inner body.\nModule body.\nGeneric body. Explicit closing is supported: //TODO: Hide repetition.\nuse std::marker::PhantomData; asteracea::component! { Inner()() \"Inner body.\"\n} mod module { asteracea::component! { pub(crate) Module()() \"Module body.\" }\n} asteracea::component! { Generic( // Generic parameters must be used in an instance field. // We can pretend this is the case using a constructor parameter capture. // `PhantomData` is a type that provides fake storage semantics. priv _phantom: PhantomData = PhantomData::default(), )() \"Generic body.\"\n} asteracea::component! { Outer()() [ <*Inner /Inner> \"\\n\" <*module::Module /Module> \"\\n\" <*Generic::<()> /Generic> // 🪣 ]\n} Inner body.\nModule body.\nGeneric body. Using a component multiple times results in distinct instances: asteracea::component! { Inner()() \"Inner body.\"\n} asteracea::component! { Outer()() [ <*Inner> <*Inner> ]\n} Inner body.Inner body.","breadcrumbs":"1: Static Components » Child Components » Child Components","id":"23","title":"Child Components"},"24":{"body":"Note: Rust is good at erasing empty instances! If your reused component is stateless, please restate the component's type name instead of using instancing. This will keep your code clearer and less interdependent. For more information, see The Rustonomicon on Zero Sized Types (ZSTs) . Instead of instantiating and storing a child component multiple times, you can instance it by giving it a name and referencing it elsewhere through a Rust block: //TODO: Hide this initially.\nasteracea::component! { Inner()() \"Inner body.\"\n} asteracea::component! { Outer()() [ <*Inner priv inner> // Alternatively: `pub` or `pub(…)` <*{self.inner_pinned()}> ]\n} Inner body.Inner body. The component's .render(…) method is called for each of these appearances, but ::new(…) is called only once. Component instancing is especially useful when rendering alternates, since the child instance is available everywhere in the parent component's body (regardless which .render(…) path is taken).","breadcrumbs":"1: Static Components » Child Components » Child Component Instancing","id":"24","title":"Child Component Instancing"},"25":{"body":"This is an optional chapter. EX-chapters don't contain necessary information on how to use Asteracea. However, they may contain interesting information about performance characteristics or tricks you can use to make your app more maintainable. Consider the following (grasping at constructor parameter captures and value formatting a bit ahead of time): use std::{fmt::Debug, mem::size_of}; asteracea::component! { MySize( priv value: T, )() [ !\"I contain {:?}!\"(self.value) \" My size is \" ())> \" bytes.\" !\" I'm located at address {:p}.\"(self) ]\n} asteracea::component! { Container()() [ <*MySize::<()> *value = {()}> \"\\n\" <*MySize::<()> *value = {()}> \"\\n\" <*MySize:: *value = {1}> \"\\n\" <*MySize:: *value = {2}> \"\\n\" \"The container instance occupies \" ())> !\" bytes at {:p}.\"(self) ]\n} I contain ()! My size is 0 bytes. I'm located at address 0x559f637aa500.\nI contain ()! My size is 0 bytes. I'm located at address 0x559f637aa500.\nI contain 1! My size is 1 bytes. I'm located at address 0x559f637aa508.\nI contain 2! My size is 8 bytes. I'm located at address 0x559f637aa500.\nThe container instance occupies 16 bytes at 0x559f637aa500. The layout here is somewhat implementation-defined, but generally what you should see is that the MySize::<()> instances take up no space inside the Container instance and don't displace other children in memory. This is because Asteracea components contain no hidden instance state, which means they are sized to content (and padding requirements), all the way down to zero. () is Rust's unit type, the most convenient zero sized type . The same applies to components without instance fields, of course. Zero-sizing is transitive and has many interesting implications, but for our purposes the most notable one is that stateless components are almost ¹ function-like at runtime. It's for this reason that Asteracea doesn't provide a special \"slim\" component syntax. ¹ There is likely a small amount of overhead during instantiation due to the dependency extraction system. The compiler is in theory allowed to optimise it away, but this isn't guaranteed. If you have an idea how to make this process meaningfully conditional without changing Asteracea's macro syntax, I'd like to hear about it!","breadcrumbs":"1: Static Components » EX: Stateless Components are Zero-Sized » EX: Stateless Components are Zero-Sized","id":"25","title":"EX: Stateless Components are Zero-Sized"},"26":{"body":"The ::new(…) and .render(…) functions of Asteracea-components are fallible, returning a Result<_, Escalation>. Escalation s are panic-like: They are not expected during normal execution of a web frontend, are strictly deprioritised compared to the Ok path and components that catch them are encouraged to implement a \"fail once and stop\" approach where child components are disposed of on first failure. You can escalate any error along the GUI tree as long as it is Any , Error and Send . use asteracea::error::EscalateResult;\nuse std::error::Error;\nuse std::fmt::{Display, Formatter, Result}; #[derive(Debug)]\nstruct AnError;\nimpl Display for AnError { fn fmt(&self, f: &mut Formatter) -> Result { write!(f, \"A test error was raised\") }\n}\nimpl Error for AnError {} asteracea::component! { Failing() #[allow(unreachable_code)] () -> Sync { // Raising an `Escalation` means crashing at least part of the app, // so there is a speed bump for this conversion. // Think of `.escalate()?` as a Wasm-unrolling version of `.unwrap()` // and use it sparingly. return Err(AnError).escalate(); }\n} asteracea::component! { Containing()() <*Failing>\n} asteracea::component! { pub Outer()() -> Sync <*Containing>\n} A test error was raised Showing line and column information is planned, but the necessary API is currently not available on stable Rust . Hooking into tracing should be comparatively straightforward, though. If the \"force-unwind\" feature is enabled, Escalation instances are erased and the type itself uses the panic infrastructure for propagation instead of being passed up via Err variant. This may reduce code size in some cases. However, note that panics cannot be caught on platforms without unwinding, including Wasm (as of Rust 1.49.0). In the future, panic conversion will be activated automatically on compatible platforms, as long as this can be done without compromising backtraces.","breadcrumbs":"2: Dynamic Components » Escalation » Escalation","id":"26","title":"Escalation"},"27":{"body":"Asteracea's error handling will automatically try to pick up on plain Rust panics, and can prevent them from crashing your app as long you use an [Escalation::catch…] function to handle errors. However, this only works with unwinding enabled (i.e. not under Wasm!) . The currently active panic hook is invoked regardless, too. The following example should display a backtrace rather than failing the book build: asteracea::component! { Panicking() #[allow(unreachable_code)] () -> Sync { //TODO: Make this conditional on unwinding. panic!(\"Avoid doing this!\"); }\n} asteracea::component! { pub Outer()() -> Sync <*Panicking>\n} Avoid doing this! In general, prefer explicit escalation over plain panics whenever possible!","breadcrumbs":"2: Dynamic Components » Escalation » Handling panics","id":"27","title":"Handling panics"},"28":{"body":"Arbitrary Rust code can be inserted into a component's constructor using a new with-block: asteracea::component! { Constructed()() new with { // TODO } []\n} Code inside the new with-block has access to constructor parameters, and let-bindings from this block are in scope for capture initialisers: asteracea::component! { QuoteHolder( text: &str, )() new with { let quoted = format!(\"‘{}’\", text); } let self.quote: String = quoted; !(self.quote)\n} asteracea::component! { Quoter()() <*QuoteHolder *text = { \"This text is quoted.\" }>\n} ‘This text is quoted.’","breadcrumbs":"2: Dynamic Components » new with { …; } » new with { …; }","id":"28","title":"new with { …; }"},"29":{"body":"Asteracea implicitly defines certain user-accessible lifetimes: 'a is available in the ::new(…) and .render(…) contexts and represents a lower bound of the component's lifetime. 'bump is the bump allocator lifetime, used when rendering the virtual DOM representation from Asteracea components and only available in the .render(…) context. This is mostly implicit, but you have to specify it in render arguments where references flow into the VDOM. Overall, the following are true, if types and values represent their lifetimes: Self ≥ self self == 'a 'a ≥ 'bump TODO: More details, especially regarding event handlers. Remove Self: 'static constraint.","breadcrumbs":"2: Dynamic Components » Predefined Lifetimes » Predefined Lifetimes","id":"29","title":"Predefined Lifetimes"},"3":{"body":"Pretty much any static templating. Lazy initialisation, via defer and bind expressions. Events and bindings, mostly . Deferred callback continuations aren't present yet, which prevents direct component instantiation or destruction from event handlers. Hover documentation! You get tooltips for elements, attributes and events, as far as written. Some branching. Dependency injection, should be mostly working. Though I'm not entirely happy with it yet. There's per-instantiation overhead without using it. Code-sharing between client and server, as Asteracea targets the modular lignin .","breadcrumbs":"Introduction » What works","id":"3","title":"What works"},"30":{"body":"Asteracea supports conditionally setting optional attributes with the following syntax: asteracea::component! { Classic()( // This will be improved on in the next chapters. class: Option<&'bump str>, ) \n} asteracea::component! { Classical()() [ <*Classic .class = {None}> \"\\n\" <*Classic .class = {Some(\"classicist\")}> ]\n} \n Instead of &'bump str , the attribute value type here is Option<&'bump str> . If None is provided, the attribute is omitted entirely from the rendered VDOM. This can be used to conditionally render a boolean attribute like checked, providing Some(\"\") to enable the attribute. However, it is usually more convenient to use a bool directly:","breadcrumbs":"2: Dynamic Components » Conditional Attributes » Conditional Attributes","id":"30","title":"Conditional Attributes"},"31":{"body":"To make dynamic boolean attributes like hidden more convenient to use, conditional attributes also accept bool values directly: asteracea::component! { Vis()( visible: bool, ) \n} asteracea::component! { Outer()() [ <*Vis .visible = {true}> \"\\n\" <*Vis .visible = {false}> ]\n} #\n# true is converted to Some(\"\") and false to None in this case, as per specification . Which types are compatible with conditional attributes is controlled by the ConditionalAttributeValue trait. It is by default implemented for bool and Option<&'bump str>, and I recommend not extending this list unless the conversion is very fast.","breadcrumbs":"2: Dynamic Components » Conditional Attributes » Boolean Attributes","id":"31","title":"Boolean Attributes"},"32":{"body":"Asteracea provides multiple ways to make working with optional arguments easier. Like in for example TypeScript, you can specify default parameters for constructor and render arguments: asteracea::component! { Classic()( // This will be improved on in the next chapter. class: Option<&'bump str> = None, ) \n} asteracea::component! { Classical()() [ <*Classic> \"\\n\" // Parameter omitted. <*Classic .class = {Some(\"classicist\")}> ]\n} \n Default parameter expressions are normal Rust expressions, and are evaluated as needed if the parameter was not specified.","breadcrumbs":"2: Dynamic Components » Argument Defaults » Argument Defaults","id":"32","title":"Argument Defaults"},"33":{"body":"When working with values that may or may not be provided, where the default is outside the range of possible provided values, you can improve your component's interface towards consumers by using optional arguments: asteracea::component! { Classic()( class?: &'bump str, ) `-typed! >\n} asteracea::component! { Classical()() [ <*Classic> \"\\n\" <*Classic .class = {\"classicist\"}> // Not `Option<_>`-typed! ]\n} \n class is an Option<&'bump str> within Classics .render(…) method, but the parameter is provided from outside as &'bump str.","breadcrumbs":"2: Dynamic Components » Optional Arguments » Optional Arguments","id":"33","title":"Optional Arguments"},"34":{"body":"Note that providing optional argument values without Some means that None can only be specfied by not setting the parameter at all! Fortunately, it's easy to do this conditionally in the same way as for optional attributes on HTML elements: asteracea::component! { Inner()( class?: &'bump str, ) \n} asteracea::component! { Middle()( class?: &'bump str, ) <*Inner .class? = {class}>\n} asteracea::component! { Outer()() [ <*Middle> \"\\n\" <*Middle .class = {\"bourgeoisie\"}> ]\n} \n This also applies to any other kind of optional parameter, i.e. arguments with explicit default value. A note for low-level component implementers Asteracea, when using child components in templates, constructs parameter bundles using a builder pattern. It assumes that the order of distinctly named parameter assignments does not matter and, in order to reduce code size, moves some assignments of arguments that are assigned to conditionally after those of ones that are not. This is a tradeoff incurred by statically validating parameter list completeness. Parameter value evaluation order , assignment order among any unconditionally set parameters, assignment order among conditional parameters and the order of assignments to the same name are preserved regardless . As long as your program compiles, this optimisation is unobservable when handling child component types created using asteracea::component! { … }. You may still want to keep it in mind for components with custom argument builders.","breadcrumbs":"2: Dynamic Components » Conditional Child Component Parameters » Conditional Child Component Parameters","id":"34","title":"Conditional Child Component Parameters"},"35":{"body":"TODO: Renamed this to ⟦pin⟧ |etc.| TODO","breadcrumbs":"2: Dynamic Components » Persistence 2: Body Captures » Persistence 2: Body Captures","id":"35","title":"Persistence 2: Body Captures"},"36":{"body":"Asteracea natively supports inversion of control via dependency extraction, which is functionally identical to dependency injection but implemented a bit differently. To define an extractable trait, you can for example write: TODO","breadcrumbs":"2: Dynamic Components » Dependency Extraction » Dependency Extraction","id":"36","title":"Dependency Extraction"},"37":{"body":"While you can in theory place nearly any Rust code inside {}-braces as part of Asteracea's grammar, this can be disorderly for more complex calculations or cumbersome where you want to reuse parts of a calculation. Instead, you can use a with { …; } <…>-expression to run a number of Rust statements procedurally: asteracea::component! { pub WithExample()() -> Sync with { let tree_type = \"oak\"; let leaves_state = \"fallen\"; } \n} The tree in the garden is an oak.\nThe oak's leaves are fallen. with-expressions can be used anywhere an element expression is expected. Bindings declared in the with-expression's are only in scope for the embedded element expression , but with a multi node, you can use them for multiple elements: asteracea::component! { pub WithExample()() -> Sync \n} The tree in the garden is an oak.\nThe oak's leaves are fallen.","breadcrumbs":"2: Dynamic Components » with { …; } <…> » with { …; } <…>","id":"37","title":"with { …; } <…>"},"38":{"body":"To conditionally render a node, you can use spread if-expressions whenever a Node<'bump> is expected: asteracea::component! { Conditional()( present: bool, ) spread if {present} \"I am here.\"\n} asteracea::component! { Conditioned()() [ <*Conditional .present = {false}> <*Conditional .present = {true}> ]\n} I am here. Note the required curly braces ({}) around the condition and their absence on the body! This is reversed from plain Rust to show that the condition is a Rust expression while the body is not. To render multiple elements conditionally, use a multi node: asteracea::component! { Conditional()( present: bool, ) [ spread if {present} [ // <-- I recommend formatting this `[]` as you would format `{}` in Rust. \"I am here\" ] \"I like this place.\" ]\n} asteracea::component! { Conditioned()() [ <*Conditional .present = {false}> \"\\n\" <*Conditional .present = {true}> ]\n} I like this place.\nI am here and I like this place.","breadcrumbs":"3: Conditional Content » spread if {…} <…> » spread if {…} <…>","id":"38","title":"spread if {…} <…>"},"39":{"body":"is also available, though this means that Asteracea's if-{condition} is not automatically a Rust block. Use {{ statements }} if you really need one, though wrapping the spread if in a with { … } <…>-expression is likely a better idea in terms of code organisation. asteracea::component! { Conditional()( content?: &'bump str, ) [ \"[\" spread if {let Some(content) = content} \"]\" ]\n} asteracea::component! { Conditioned()() [ <*Conditional> \"\\n\" <*Conditional .content = {\"Content!\"}> ]\n} []\n[Content!] Implicit else If a spread if-expression's condition is not met, an empty Node::Multi(…) ([]) is rendered by default. A note for React users Unlike React Hooks, Asteracea's captures (including <*ChildComponent>s) are generally fine to use in conditional spread if-branches, even if which branch is taken changes during the component's lifetime. The tradeoff for this is that their initialisers always run during component instantiation and that fields are created for any declared captures.","breadcrumbs":"3: Conditional Content » spread if {…} <…> » Pattern-matching with let","id":"39","title":"Pattern-matching with let"},"4":{"body":"Thread safety inference is sometimes wonky. Write ComponentName()() -> Sync or ComponentName()() -> !Sync to determine it manually. It's sound either way, but the former may not compile. Repeat arguments for child components. This will lead towards content transclusion. I think. Attached properties, to configure transclusion. The grammar. I'll most likely change something in a breaking way before v0.1.","breadcrumbs":"Introduction » What isn't finished","id":"4","title":"What isn't finished"},"40":{"body":"You can explicitly specify alternative content with an else branch: asteracea::component! { Alternates()( show_alternative: bool = false, ) spread if {show_alternative} \"Default\" else \"Alternative\"\n} asteracea::component! { pub Alternated()() -> Sync [ <*Alternates> \"\\n\" <*Alternates .show_alternative = {true}> ]\n} Alternative\nDefault","breadcrumbs":"3: Conditional Content » spread if …… else <…> » spread if …… else <…>","id":"40","title":"spread if …… else <…>"},"41":{"body":"for loops in Asteracea components resemble those in plain Rust, but do produce output on each iteration: asteracea::component! { pub Looping()() -> Sync for word in \"This is a test.\".split(' ') {[ \"\\n\" ]}\n} \"This\" \n\"is\" \n\"a\" \n\"test.\" You can declare bindings and use child components within the loop's body as normal. Their state is: initialised anew for each new element, \"stuck\" to the respective element in the input sequence when it is reordered and dropped if an element has disappeared. Repeated elements each have their own state, but are considered interchangeable. Each such group's state \"list\" is auto-edited only at the end. DOM elements are also reordered for sequence updates, but this isn't entirely reliable if you use keys longer than 32 bits. This is guaranteed to never cause an inconsistent GUI state (since any output and bindings will still be updated to be in the correct order when diffing), but in very rare cases could result in a selection or focus \"jumping elsewhere\". Such glitches are guaranteed to never happen while the sequence is stable, however. The full explicit syntax for for-loops is as follows: asteracea::component! { pub Looping()() -> Sync for i: u8 keyed &*i => u8 in 0..255 { \".\" }\n} ............................................................................................................................................................................................................................................................... where i is the item pattern, used both for the loop body (by value) and the selector, : ⦃T⦄ determines the type of items in the sequence, keyed ⦃selector⦄ projects &mut T to &Q where Q: Eq + ToOwned, => ⦃K⦄ where K: ReprojectionKey determines the type of state keys cached internally and 0..255 is an IntoIterator to use as item source. Each of these parts is optional, but currently it may be occasionally necessary to specify a type. Specifying neither T nor K also means a loop will use somewhat less efficient dynamically typed stored keys that always incur a heap allocation when an item is added to the list. Both most annotation requirements and relative inefficiency of unannotated loops is expected to disappear with future Rust language improvements .","breadcrumbs":"3: Conditional Content » for-loops » for-loops","id":"41","title":"for-loops"},"42":{"body":"Rust's match statements are available in Asteracea contexts, with slightly changed syntax: enum Enum<'a> { Text(&'a str), Other,\n} asteracea::component! { MatchEnum()( enum_value: Enum<'_>, ) spread match {enum_value} [ Enum::Text(text) => Enum::Other => ]\n} asteracea::component! { pub Matched()() -> Sync [ <*MatchEnum .enum_value = { Enum::Text(\"Hello!\") }> \"\\n\" <*MatchEnum .enum_value = { Enum::Other }> ]\n} Hello!\n","breadcrumbs":"3: Conditional Content » spread match { … } [ … ] » spread match { … } [ … ]","id":"42","title":"spread match { … } [ … ]"},"43":{"body":"A box <…> expression moves its parameter's backing storage into a new heap object, bound to a field of the current storage context . The field can be named using box priv … syntax. If the field is named, its type can be specified using : …. If you don't name the type or specify its name using : struct …, it is generated automatically. The field can be made public by writing box pub …. Any other standard Rust visibility can be used in place of pub, too, to similar effects. In practical terms: Any captures are first placed in a Box<…> before being assigned to a ⟦named⟧ field inside the current component instance. This means that, for example, if you write box as boxed <*Component as child>, you'll need to access it as self.boxed.child. This introduces some level of runtime indirection , also when rendering components. Uninitialised boxed expressions take up very little space. Recursion becomes possible.","breadcrumbs":"3: Conditional Content » box ⟦priv …⟦: ⟦struct⟧ … ⟦where …;⟧⟧⟧ <…> » box ⟦priv …⟦: ⟦struct⟧ … ⟦where …;⟧⟧⟧ <…>","id":"43","title":"box ⟦priv …⟦: ⟦struct⟧ … ⟦where …;⟧⟧⟧ <…>"},"44":{"body":"Infinite recursive (storage) inlining isn't possible (except theoretically for zero-sized-types, but Rust makes no distinction here). This means the following requires boxing: asteracea::component! { Countdown()( i: usize, ) [ !(i) dyn if {i > 0} [ \"\\n\" box <*Countdown .i = {i - 1}> ] ]\n} Note: It's decidedly better to implement the above with a loop! If you have a better example to demonstrate recursion with, please let me know ! Note the use of dyn if to prevent infinite eager initialisation. You can alternatively combine spread if with lazy ⟦move⟧ to avoid throwing away heap allocations once they exist. This is better in cases where the recursion depth changes quickly or","breadcrumbs":"3: Conditional Content » box ⟦priv …⟦: ⟦struct⟧ … ⟦where …;⟧⟧⟧ <…> » Component recursion","id":"44","title":"Component recursion"},"45":{"body":"The container component size reduction isn't very useful in most cases, since Asteracea initialises child components eagerly, but can be used to great effect with dyn branching if certain arms require especially large storage . Consider the following: use std::mem::size_of; asteracea::component! { Heavy()() let self.large: [u8; 1_000] = #![allow(dead_code)] [0; 1_000]; // 1 KB \"Hello!\"\n} asteracea::component! { Holder()( show: bool = false, ) [ \"Holder size: \" !(size_of::()) \" bytes\" spread if {show} //TODO: Replace `spread` with `dyn`! <*Heavy> ]\n} Holder size: 1000 bytes As you can see, Holder requires 1KB of space even though Heavy is never used. You can avoid this as follows: use std::mem::size_of; asteracea::component! { Heavy()() let self.large: [u8; 1_000] = #![allow(dead_code)] [0; 1_000]; // 1 KB \"Hello!\"\n} asteracea::component! { Holder()( show: bool = false, ) [ \"Holder size: \" !(size_of::()) \" bytes\" spread if {show} //TODO: Replace `spread` with `dyn`! box <*Heavy> ]\n} Holder size: 8 bytes As dyn if won't initialise its branches unless necessary, no heap allocation happens in this case either.","breadcrumbs":"3: Conditional Content » box ⟦priv …⟦: ⟦struct⟧ … ⟦where …;⟧⟧⟧ <…> » Memory savings","id":"45","title":"Memory savings"},"46":{"body":"An alternative method of breaking up recursive component initialisation is to defer it for the recursive part of the template until it is rendered. As such, the recursive example from the box ⟦priv …⟦: ⟦struct⟧ … ⟦where …;⟧⟧⟧ <…> chapter can be written as: asteracea::component! { Countdown()( i: usize, ) -> Sync // Syncness hint required due to recursion. [ !(i) spread if {i > 0} [ \"\\n\" defer box <*Countdown .i = {i - 1}> ] ]\n} asteracea::component! { pub HalfADozen()() -> Sync? <*Countdown .i = {6}>\n} 6\n5\n4\n3\n2\n1\n0 This has different runtime characteristics: spread if doesn't drop branches that aren't active, and defer only ever runs initialisers once. This means that state persists and heap allocations are cached . Useful for (very) frequently updated content!","breadcrumbs":"3: Conditional Content » defer ⦃storage⦄ <…> » defer ⦃storage⦄ <…>","id":"46","title":"defer ⦃storage⦄ <…>"},"47":{"body":"As usual, the backing field can be named and then referred to: asteracea::component! { Introspective()() [ \"Was I rendered before? \" !(self.deferred_pinned().get().is_some()) defer priv deferred: struct Deferred [] ]\n} asteracea::component! { pub Ruminating()() -> Sync? [ <*Introspective priv introspective> \"\\n\" <*{self.introspective_pinned()}> ]\n} Was I rendered before? false\nWas I rendered before? true The subexpression backing storage is wrapped in a Deferred instance, which provides a .get() method returning an Option> depending on whether the subexpression was constructed yet. You can also call .get_or_poison() , to evaluate the constructor if pending, which returns a Result, Escalation>.","breadcrumbs":"3: Conditional Content » defer ⦃storage⦄ <…> » Naming the field","id":"47","title":"Naming the field"},"48":{"body":"Much like defer expressions, bind expressions evaluate a sub-expression constructor once when first rendered. However, they also shift the constructor scope of a sub-expression into its parent's render scope . This lets you use render parameters as constructor parameters: asteracea::component! { Early( priv early: &'static str, )() [\"Constructor parameter: \" !\"{:?}\"(self.early)]\n} asteracea::component! { Late()( late: &'static str, ) bind <*Early *early = {late}>\n} asteracea::component! { pub Test()() -> Sync? [ <*Late priv tested .late = {\"first\"}> \"\\n\" <*{self.tested_pinned()} .late = {\"second\"}> ]\n} Constructor parameter: \"first\"\nConstructor parameter: \"first\" As you can see, early is only assigned once. late is discarded during the second call. By default, the sub-expression constructor acts like (read: is) a plain Rust closure without additional keywords, but you can apply the move keyword after the optional storage configuration.","breadcrumbs":"3: Conditional Content » bind ⦃storage⦄ ⟦move⟧ <…> » bind ⦃storage⦄ ⟦move⟧ <…>","id":"48","title":"bind ⦃storage⦄ ⟦move⟧ <…>"},"49":{"body":"","breadcrumbs":"5: Miscellaneous » Glossary » Glossary","id":"49","title":"Glossary"},"5":{"body":"\"Loops\" A standard library, including a mockable HTTP client (for client and server). A router, hopefully nicely possible outside the core library. A turnkey app base. This needs to come with SSR and then optionally hydrate. Anything I haven't thought of! Suggestions are welcome.","breadcrumbs":"Introduction » What's missing","id":"5","title":"What's missing"},"50":{"body":"Asteracea's most generic template building block. Placeholder: <…>","breadcrumbs":"5: Miscellaneous » Glossary » element expression","id":"50","title":"element expression"},"51":{"body":"asteracea::component! { HelloAsteracea()() \n} Hello Asteracea! use asteracea::component;\nuse std::cell::Cell; fn schedule_render() { /* ... */ } component! { pub Counter( initial: i32, priv step: i32, )( /// This component's class attribute value. class?: &'bump str, ) -> !Sync // visible across crate-boundaries, so use explicit `Sync`ness let self.value = Cell::::new(initial); // shorthand capture