Advanced macros for cleaner component property syntax

[XX]

The Problem

Currently, when using components, it is necessary to explicitly specify .. to fill in omitted properties with their default values:

rsx! {
    <Element ../>
    <Element id="element" ../>
}

This is because the generated code instantiates the component using struct literal syntax, where .. expands to ..Default::default():

Element {
    id: "element",
    ..Default::default()
}

This approach is simple and clear. However, for large components with many properties, it results in the almost constant use of .., which clutters the code:

rsx! {
    <CodeExample ..>
        <CodeExamplePreview resize=true ..>
            <Element ..>"Hello"</Element>
        </CodeExamplePreview>
        <CodeExampleSource ..>
            <code class="language-html">
                r#"<Element ..>"Hello"</Element>"#
            </code>
        </CodeExampleSource>
        <CodeExampleButton ..>"Code"</CodeExampleButton>
    </CodeExample>
}

Additionally, this makes it harder to use wrapper or aggregating structs, since all component attributes must match struct field names exactly. This leads to less clean syntax like the following:

#[derive(Default)]
pub struct CodeExample {
    pub open: bool,
    pub attrs: CommonAttrs,
    pub children: Lazy<fn(&mut Buffer)>,
}

rsx! {
    <CodeExample open=true attrs=(CommonAttrs::new().id("example").class("toggle").style("color: red"))>
        ...
    </CodeExample>
}

Proposed Solution

I propose extending the component instantiation code generator with an additional mode that relies on:

• The component struct implementing Default
• Builder-style setter methods for properties

For example:

Element::default()
    .id("element")
    .tabindex(2)

With this approach, separate macro variants such as maud_cb! and rsx_cb! (CB = Component Builder) could significantly simplify component property syntax:

rsx_cb! {
    <Element />
    <Element id="element" />
    <Element id="element" tabindex=2 />
}

rsx_cb! {
    <CodeExample />
    <CodeExample open=true id="example" class="toggle" style="color: red" />
}

The .attr(...) methods could be implemented either manually or automatically using a #[derive(Builder)] macro based on the struct’s fields:

#[derive(Default, Builder)]
struct Element<'a> {
    id: &'a str,
    tabindex: u32,
    children: Lazy<fn(&mut Buffer)>,

    #[builder(skip)]
    _skipped: (),
}

Implementation

I have implemented the functionality described above so it can be experimented with and potentially used as a foundation if there is interest in adding it to hypertext.

PR: #179
Working example in tests: https://github.com/vidhanio/hypertext/pull/179/changes#diff-dc0fadfd8cc5b92a1297488453c2a317f203183fd3b3a27f0c4870b7aa9cb47cR808

[XX]

My answer from the PR discussion:

Using methods instead of directly assigning values to struct fields provides significantly more flexibility. For example, here is how one of my components is structured:

#[derive(Default, AsRef, AsMut)]
pub struct CodeExample {
    pub open: bool,

    #[as_ref]
    #[as_mut]
    pub attrs: CommonAttrs,

    pub children: Lazy<fn(&mut Buffer)>,
}

The CommonAttrs type encapsulates properties shared by many components, such as id, class, and style:

#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct CommonAttrs {
    pub id: Cow<'static, str>,
    pub classes: Vec<Cow<'static, str>>,
    pub styles: Vec<Cow<'static, str>>,
}

To avoid explicitly declaring fields for these attributes in every component or manually implementing builder methods, a trait is used:

pub trait CommonAttributeSetters {
    fn id(mut self, id: impl Into<Cow<'static, str>>) -> Self
    where
        Self: Sized,
    {
        self.set_id(id);
        self
    }

    fn class(mut self, class: impl Into<Cow<'static, str>>) -> Self
    where
        Self: Sized,
    {
        self.add_class(class);
        self
    }

    fn style(mut self, style: impl Into<Cow<'static, str>>) -> Self
    where
        Self: Sized,
    {
        self.add_style(style);
        self
    }

    fn set_id(&mut self, id: impl Into<Cow<'static, str>>);

    fn set_classes(&mut self, classes: Vec<Cow<'static, str>>);

    fn set_styles(&mut self, styles: Vec<Cow<'static, str>>);

    fn add_class(&mut self, class: impl Into<Cow<'static, str>>);

    fn add_style(&mut self, style: impl Into<Cow<'static, str>>);
}

impl CommonAttributeSetters for CommonAttrs {
    fn set_id(&mut self, id: impl Into<Cow<'static, str>>) {
        self.id = id.into();
    }

    fn set_classes(&mut self, classes: Vec<Cow<'static, str>>) {
        self.classes = classes;
    }

    fn set_styles(&mut self, styles: Vec<Cow<'static, str>>) {
        self.styles = styles;
    }

    fn add_class(&mut self, class: impl Into<Cow<'static, str>>) {
        self.classes.push(class.into());
    }

    fn add_style(&mut self, style: impl Into<Cow<'static, str>>) {
        self.styles.push(style.into());
    }
}

With a blanket implementation for all types that implement AsMut<CommonAttrs>:

impl<T: AsMut<CommonAttrs>> CommonAttributeSetters for T {
    fn set_id(&mut self, id: impl Into<Cow<'static, str>>) {
        self.as_mut().set_id(id);
    }

    fn set_classes(&mut self, classes: Vec<Cow<'static, str>>) {
        self.as_mut().set_classes(classes);
    }

    fn set_styles(&mut self, styles: Vec<Cow<'static, str>>) {
        self.as_mut().set_styles(styles);
    }

    fn add_class(&mut self, class: impl Into<Cow<'static, str>>) {
        self.as_mut().add_class(class);
    }

    fn add_style(&mut self, style: impl Into<Cow<'static, str>>) {
        self.as_mut().add_style(style);
    }
}

Now, for a component to support common attributes, it is sufficient to implement AsMut<CommonAttrs>, and the builder methods become available automatically:

#[derive(Default, AsRef, AsMut, Builder)]
pub struct CodeExample {
    pub open: bool,

    #[as_ref]
    #[as_mut]
    #[builder(skip)]
    pub attrs: CommonAttrs,

    pub children: Lazy<fn(&mut Buffer)>,
}

rsx_cb! {
    <CodeExample open=true id="the-example" class="code-example" />
}

Additionally, using methods allows performing arbitrary transformations when setting values. For example, taking a class string and appending it to the classes vector — or performing more complex logic if needed.