Crate ambient_element

Element is a React-inspired virtual tree library for the Ambient runtime.

It is backed by the Ambient ECS; the virtual tree is converted into a real tree of entities and components. When the tree is updated, it is compared to the previous tree, and only the differences are applied to the ECS. This can be used for UI, as well as any other tree-like data structure that you want to be able to update efficiently.

Idioms

By convention, most ElementComponents define an el method that returns an Element of that type. This el takes the properties to make it easy to both construct the component and instantiate it as an Element.

In addition to this, ElementComponentExt adds an el method to all ElementComponents that converts them to an Element.

This means that an ElementComponent that looks like this

#[element_component]
fn MyComponent(hooks: &mut Hooks, a: u32, b: String) -> Element {
   // ...
}

can be instantiated as an Element using either of these methods:

MyComponent { a: 42, b: "hello".to_string() }.el()

or

MyComponent::el(42, "hello".to_string())

Passing data in

To pass data into the root of an Element tree, pass the data into its properties when constructing it and/or update the root of the tree using ElementTree::migrate_root.

To receive data from an Element tree, we recommend you use messaging. This includes sending messages to the server and/or standard messaging channels in Rust (e.g. std::sync::mpsc::channel). We do not generally recommend trying to send data out of the tree directly, as this can be difficult to reason about.

Macros

• to_owned
  Shorthand for let x = x.to_owned();

Structs

• Element
  A rendered ElementComponent instance.
• ElementTree
  A tree of instantiated Elements.
• Group
  Wrap multiple Elements in a flat hierarchy.
• Hooks
  Hooks are a way to hook into the state and lifecycle of an Element.
• Memo
  Memoize the ElementComponent, such that it is only re-rendered if the component changes.
• ShareableElementTree
  A shareable element tree. This is used to share the same tree between multiple contexts.
• Wrap
  Wraps the inner Element. This is useful for introducing an intermediate component node in a tree.

Traits

• AnyCloneable
  A trait for types that can be converted to Any and can also be cloned.
• ElementComponent
  The base trait for all element components. These are similar to React components.
• ElementComponentExt
  A convenience trait for converting an ElementComponent into an Element.
• ElementComponentName
  Contains the name of the type implementing ElementComponent.

Functions

• ambient_system
  The systems required to drive ElementTrees.
• element
  Element: The identifier of the Element that controls this entity.
• element_tree
  The element tree state for an entity.
• element_unmanaged_children
  Element unmanaged children: If this is set, the user is expected to manage the children of the Element themselves.
• init_components
  Initialize the components for the module
• render_parented_with_component
  Render the given tree underneath id.

Type Definitions

• DespawnFn
  The return type of a function passed to Hooks::use_spawn. This function is called when the Element is unmounted/despawned; use it to clean up any resources.
• Setter
  Helper type for a callback that sets some value.

Attribute Macros

• element_component
  Helper macro to implement a ElementComponent with a pure free function.