lignin

A lightweight but featureful virtual DOM library, primarily for web use.

no_std and no dependencies without the "callbacks" feature.

Installation

Please use cargo-edit to always add the latest version of this library:

cargo add lignin && cargo add -D lignin --features callbacks

Some type constraints are more strict with the "callbacks" feature enabled, so make sure to always check this way!

When writing a renderer that supports callbacks, instead use

cargo add lignin --features callbacks

to always enable the feature.

Features

"callbacks"

Enables DOM callback support. Off by default. Requires std.

Apps or components can be written against the callback API without enabling this feature, in which case those code paths can be erased at compile-time.

Example

use lignin::{Node, Element, ElementCreationOptions};

// Please bring your own allocator where necessary.
let _ = &Node::HtmlElement {
  element: &Element {
    name: "DIV", // Use all-caps for more efficient DOM interactions.¹
    creation_options: ElementCreationOptions::new(), // `const fn` builder and getter/setter patterns for extensible interfaces.
    attributes: &[],
    content: Node::Multi(&[
      "Hello! ".into(), // Some convenience included.
      Node::Comment {
        comment: "--> Be mindful of HTML pitfalls. <!--", // Renderers must validate.
        dom_binding: None,
      }
    ]),
    event_bindings: &[], // Strongly typed using `web-sys`.
  },
  dom_binding: None, // For JS interop.
}
.prefer_thread_safe(); // Thread-safety can be inferred from bindings!

¹ See Element.tagName (MDN). This avoids case-insensitive comparisons.

Implementation Contract

There are a few ecosystem compatibility rules that aren't covered by Rust's type system or the unsafe keyword. Please see the main module documentation for more information.

Prior Art

• Dodrio, which didn't quite satisfy my requirements but generally inspired this approach.

Thanks

To Dronaroid for finding a great name for this library, @platy for criticism and pushing me towards a better implementation, and everyone on the Rust Programming Language Community Server discord who answered my questions that came up during the rewrite.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Code of Conduct

Changelog

Versioning

lignin strictly follows Semantic Versioning 2.0.0 with the following exceptions:

• The minor version will not reset to 0 on major version changes (except for v1).
  Consider it the global feature level.
• The patch version will not reset to 0 on major or minor version changes (except for v0.1 and v1).
  Consider it the global patch level.

This includes the Rust version requirement specified above.
Earlier Rust versions may be compatible, but this can change with minor or patch releases.

Which versions are affected by features and patches can be determined from the respective headings in CHANGELOG.md.