Crate ironhtml_elements

Expand description

§ironhtml-elements

Type-safe HTML5 elements following the WHATWG HTML Living Standard.

This crate provides zero-sized types for all HTML5 elements with traits for content categories, enabling compile-time validation of HTML structure.

§Example

use ironhtml_elements::{Div, Span, A, Img, HtmlElement};
use ironhtml_elements::{FlowContent, PhrasingContent, EmbeddedContent};

// Access element tag names
assert_eq!(Div::TAG, "div");
assert_eq!(A::TAG, "a");

// Check if an element is void (self-closing)
assert!(!Div::VOID);  // <div></div>
assert!(Img::VOID);   // <img />

// Use traits to constrain valid element usage
fn accepts_flow<T: FlowContent>() {}
fn accepts_phrasing<T: PhrasingContent>() {}

accepts_flow::<Div>();      // OK - div is flow content
accepts_flow::<Span>();     // OK - span is flow content
accepts_phrasing::<Span>(); // OK - span is phrasing content
// accepts_phrasing::<Div>(); // ERROR - div is not phrasing content

§Specification References

§Design Decisions

§Zero-Sized Types (ZSTs) for Elements

Each HTML element is defined as a unit struct with no fields. This design provides zero runtime overhead - ZSTs occupy no memory:

use ironhtml_elements::{Div, Span, A};
use core::mem::size_of;

// All element types are zero-sized
assert_eq!(size_of::<Div>(), 0);
assert_eq!(size_of::<Span>(), 0);
assert_eq!(size_of::<A>(), 0);

Benefits:

Zero runtime overhead: ZSTs occupy no memory at runtime. The type exists only at compile time for type checking.
Compile-time markers: Elements serve as type-level tags that carry semantic meaning without any runtime representation.
Optimal codegen: The Rust compiler can completely eliminate ZSTs during optimization, resulting in no additional instructions.

§Traits for Content Categories

Content categories from the WHATWG spec are modeled as marker traits with a hierarchy that reflects the specification:

use ironhtml_elements::{Div, Span, Article, H1};
use ironhtml_elements::{FlowContent, PhrasingContent, SectioningContent, HeadingContent};

// Generic functions can require specific content categories
fn accepts_flow<T: FlowContent>() {}
fn accepts_phrasing<T: PhrasingContent>() {}
fn accepts_sectioning<T: SectioningContent>() {}

// Div is flow content
accepts_flow::<Div>();

// Span is phrasing content (and therefore also flow content)
accepts_phrasing::<Span>();
accepts_flow::<Span>();

// Article is sectioning content
accepts_sectioning::<Article>();

This design enables:

Compile-time constraint checking: Generic functions can require elements to belong to specific content categories.
Trait hierarchy reflects spec: The supertrait relationships (e.g., PhrasingContent: FlowContent) mirror the WHATWG specification where all phrasing content is also flow content.
Extensibility: New element types can implement these traits to integrate with existing validation logic.

§The `CanContain` Pattern

Parent-child relationships use a binary trait pattern:

use ironhtml_elements::{Div, Span, Ul, Li, Table, Tr, Td, P, CanContain};

// Check valid parent-child relationships at compile time
fn can_nest<Parent: CanContain<Child>, Child>() {}

// Lists: Ul can contain Li
can_nest::<Ul, Li>();

// Tables: Table contains Tr, Tr contains Td
can_nest::<Tr, Td>();

// Div can contain any flow content
can_nest::<Div, P>();
can_nest::<Div, Span>();
can_nest::<Div, Ul>();

// Span can contain phrasing content
can_nest::<Span, Span>();

This design provides:

Compile-time validation: Invalid nesting like <ul><div> or <p><div> produces a compilation error rather than a runtime error.
Precise control: Each parent-child relationship is explicitly declared, matching the WHATWG content model specification.
Generic implementations: Using trait bounds like impl<T: FlowContent> avoids listing every valid child element individually while still providing type safety.

§Why This Approach?

Traditional HTML builders use runtime validation or stringly-typed APIs where errors are only discovered at runtime or not at all. For example, builder.element("div").child("invalid") might error at runtime, or invalid nesting like putting a <li> directly in a <div> might silently produce malformed HTML.

This crate instead leverages Rust’s type system to make invalid HTML structures impossible to represent. The compiler becomes your HTML validator, catching errors before your code even runs.

Structs§

A: The <a> element - hyperlink (anchor).
Abbr: The <abbr> element - abbreviation or acronym.
Address: The <address> element - contact information.
Area: The <area> element - defines a clickable area within an image map.
Article: The <article> element - self-contained composition.
Aside: The <aside> element - tangentially related content.
Audio: The <audio> element - embeds sound content into documents.
B: The <b> element - bring attention to.
Base: The <base> element - document base URL.
Bdi: The <bdi> element - bidirectional isolate.
Bdo: The <bdo> element - bidirectional text override.
Blockquote: The <blockquote> element - block quotation.
Body: The <body> element - document body.
Br: The <br> element - line break.
Button: The <button> element - represents a clickable button.
Canvas: The <canvas> element - provides a bitmap drawing surface for graphics via JavaScript.
Caption: The <caption> element - represents the title of a table.
Cite: The <cite> element - citation or reference to a creative work.
Code: The <code> element - code fragment.
Col: The <col> element - defines a column within a table.
Colgroup: The <colgroup> element - defines a group of columns in a table.
Data: The <data> element - machine-readable data.
Datalist: The <datalist> element - contains a set of predefined options for other controls.
Dd: The <dd> element - description details.
Del: The <del> element - deleted text.
Details: The <details> element - represents a disclosure widget from which the user can obtain additional information.
Dfn: The <dfn> element - defining instance of a term.
Dialog: The <dialog> element - represents a dialog box or other interactive component.
Div: The <div> element - generic container.
Dl: The <dl> element - description list.
Dt: The <dt> element - description term.
Em: The <em> element - emphasis.
Embed: The <embed> element - embeds external content at the specified point.
Fieldset: The <fieldset> element - groups related form controls and labels.
Figcaption: The <figcaption> element - figure caption.
Figure: The <figure> element - self-contained content.
Footer: The <footer> element - footer content.
Form: The <form> element - represents a document section containing interactive controls for submitting information.
H1: The <h1> element - level 1 heading.
H2: The <h2> element - level 2 heading.
H3: The <h3> element - level 3 heading.
H4: The <h4> element - level 4 heading.
H5: The <h5> element - level 5 heading.
H6: The <h6> element - level 6 heading.
Head: The <head> element - container for document metadata.
Header: The <header> element - introductory content.
Hgroup: The <hgroup> element - heading group.
Hr: The <hr> element - thematic break.
Html: The <html> element - the root element of an HTML document.
I: The <i> element - idiomatic text.
Iframe: The <iframe> element - embeds another HTML page within the current page.
Img: The <img> element - embeds an image into the document.
Input: The <input> element - represents a typed data field for user input.
Ins: The <ins> element - inserted text.
Kbd: The <kbd> element - keyboard input.
Label: The <label> element - represents a caption for a form control.
Legend: The <legend> element - represents a caption for a <fieldset>.
Li: The <li> element - list item.
Link: The <link> element - external resource link.
Main: The <main> element - main content.
Map: The <map> element - defines an image map with clickable areas.
Mark: The <mark> element - highlighted or marked text.
Math: The <math> element - embeds MathML (Mathematical Markup Language) content.
Menu: The <menu> element - menu of commands.
Meta: The <meta> element - document metadata.
Meter: The <meter> element - represents a scalar measurement within a known range.
Nav: The <nav> element - navigation links.
Noscript: The <noscript> element - defines fallback content for when scripts are disabled.
Object: The <object> element - embeds external resource as an object.
Ol: The <ol> element - ordered list.
Optgroup: The <optgroup> element - groups related options within a <select> element.
Option_: The <option> element - defines an option in a <select>, <optgroup>, or <datalist>.
Output: The <output> element - represents the result of a calculation or user action.
P: The <p> element - paragraph.
Param: The <param> element - defines parameters for an <object> element.
Picture: The <picture> element - contains multiple image sources for responsive images.
Pre: The <pre> element - preformatted text.
Progress: The <progress> element - represents the completion progress of a task.
Q: The <q> element - inline quotation.
Rp: The <rp> element - ruby fallback parenthesis.
Rt: The <rt> element - ruby text component.
Ruby: The <ruby> element - ruby annotation.
S: The <s> element - strikethrough (no longer accurate).
Samp: The <samp> element - sample output.
Script: The <script> element - embeds or references executable code.
Search: The <search> element - search functionality.
Section: The <section> element - thematic grouping of content.
Select: The <select> element - represents a control for selecting among a set of options.
Slot: The <slot> element - defines a placeholder in a web component’s shadow DOM.
Small: The <small> element - side comments and small print.
Source: The <source> element - specifies media resources for <picture>, <audio>, and <video>.
Span: The <span> element - generic inline container.
Strong: The <strong> element - strong importance.
Style: The <style> element - embedded CSS styles.
Sub: The <sub> element - subscript.
Summary: The <summary> element - represents a summary, caption, or legend for a <details> element.
Sup: The <sup> element - superscript.
Svg: The <svg> element - embeds SVG (Scalable Vector Graphics) content.
Table: The <table> element - represents tabular data in rows and columns.
Tbody: The <tbody> element - groups body content rows in a table.
Td: The <td> element - defines a data cell in a table.
Template: The <template> element - holds HTML content that is not rendered immediately.
Text: Represents a text node in the DOM.
Textarea: The <textarea> element - represents a multi-line plain text editing control.
Tfoot: The <tfoot> element - groups footer rows in a table.
Th: The <th> element - defines a header cell in a table.
Thead: The <thead> element - groups header rows in a table.
Time: The <time> element - date and/or time.
Title: The <title> element - document title.
Tr: The <tr> element - defines a row of cells in a table.
Track: The <track> element - specifies timed text tracks for media elements.
U: The <u> element - unarticulated annotation.
Ul: The <ul> element - unordered list.
Var: The <var> element - variable or placeholder.
Video: The <video> element - embeds video content into documents.
Wbr: The <wbr> element - word break opportunity.

Traits§

CanContain: Trait indicating that an element can contain another element as a child.
EmbeddedContent: Embedded content: elements that import another resource into the document.
FlowContent: Flow content: most elements used in the body of documents and applications.
HeadingContent: Heading content: elements that define the header of a section.
HtmlElement: Trait implemented by all HTML elements.
InteractiveContent: Interactive content: elements specifically intended for user interaction.
MetadataContent: Metadata content: elements that set up the presentation or behavior of the rest of the content, or set up relationships with other documents.
PalpableContent: Palpable content: content that is not empty or hidden.
PhrasingContent: Phrasing content: the text of the document and elements that mark up that text.
ScriptSupporting: Script-supporting elements: elements that don’t represent anything themselves.
SectioningContent: Sectioning content: elements that define the scope of headings and footers.