Mox builder API RFC

[tiffany352]

I want to propose a more explicitly defined interface that the mox macro
consumes. Some of this is based on my own local fork I'm using for
moxie-native.

Everything I'm talking about here is based on my own requirements for
moxie-native, and I'd like to know if any of these requirements are too
strict for other implementations, or if there are other ways of
improving this.

I'll start off with suggesting that as much as possible be moved into a
module named mox_impl, so that we don't pollute the namespace of
programs and require a blob import like use moxie_native::prelude::*;.

Inside of this module, there will be another namespace for host elements
(which we will distinguish from user components, as I'll detail below).
There will also be one for attribute names, and for event names.

API Sketch

None of the types used here are literal, but are just to name the return
values so you can match them up to where they get plumbed into.

mod mox_impl {
    mod elements {
        // Note that this is not a macro.
        fn element_name_here(
            with_builder: impl FnOnce(builder: Builder) -> Builder
        ) -> Node;
    }

    mod attributes {
        fn attr_name_here() -> Attribute;
    }

    mod events {
        fn on_event_name_here() -> Event;
    }
}

The builder API has these methods on it (again, the types are not actual types):

trait Builder {
    fn set_attr(self, key: Attribute, value: Attribute::Value) -> Self;
    fn on_event(self, event: Event, callback: impl FnMut(event)) -> Self;
    fn set_data(self, key: &'static str, value: DataValue) -> Self;
    fn add_child(self, child: Node) -> Self;
    fn enter_fragment(self, with_builder: impl FnOnce(builder: Self) -> Self) -> Self;
}

Changes to syntax

1. User components need to be written in a way that lets them be
   differentiated from host components. This is already true of
   components that take arguments, since you have to use the <element _=(...)> syntax. Zero argument components need to be written
   differently from <element /> though. <element _=() /> would work
   if it didn't fail to parse.
2. Instead of <element on={func} />, events actually have names, so
   <element on_foo={func} /> turns into
   .on(mox_impl::events::on_foo(), func).
3. Add a concept of data attributes (not currently present) which are
   not statically declared. <element data_foo=4 /> -> .data("foo", 4)

Implementation

Implementation here is pretty straightforward, the biggest unknown is if
this new scheme will be difficult for other users of mox.

Simple implementations can define attribute functions as just a function
that returns a string, but this might be more manual than desired for
something like moxie-dom.

Some implementation hints from moxie-native that can come in handy here:

• The builder trait can be implemented per element with a Builder<T>
  generic. The element functions can create an instance of this builder
  and pass it to the input function.
• set_attr can be implemented using a trait like this:

  trait HasAttribute<Attr> where Attr: Attribute {
      fn set_attribute(&mut self, value: Attr::Value);
  }

• on_event can be implemented the same way using a HasEvent trait.
• The element function and the enter_fragment method are both good
  places to insert topo calls.

Examples

Simple with attributes

<foo some_attr=4 />

mox_impl::elements::foo(|builder| {
    builder
    .set_attr(mox_impl::attributes::some_attr(), 4)
})

User components

<bar>
    <user_component _=(1, "foo") />
</bar>

mox_impl::elements::bar(|builder| {
    builder
    .add_child(user_component!(1, "foo"))
})

Events and data attributes

<button on_click={func} data_foo=4 />

mox_impl::elements::button(|builder| {
    builder
    .on_event(mox_impl::events::on_click(), func)
    .data("foo", 4)
})

Children

<foo>
    <bar />
    "text"
    {children}
</foo>

mox_impl::elements::foo(|builder| {
    builder
    .add_child(mox_impl::elements::bar(|builder| builder))
    .add_child("text")
    .add_child(children)
})

Fragments

<foo>
    <>
        <fragment_child />
    <>
</foo>

mox_impl::elements::foo(|builder| {
    builder
    .enter_fragment(|builder| {
        builder
        .add_child(mox_impl::elements::fragment_child(|builder| builder))
    })
})

Bare fragments

Behavior here isn't super clear, but adding a create_fragment function
to mox_impl to handle this case seems flexible enough.

<>
    <fragment_child />
</>

mox_impl::create_fragment(|builder|
    builder
    .add_child(mox_impl::elements::fragment_child(|builder| builder))
)

Iterators

This one is tricky to support, and I currently can't handle it correctly
in moxie-native without trait specialization. I haven't thought of any
workarounds that don't require modifying the syntax to be like
..{iterator} or something like that. Any ideas here would be nice.

<foo>
    {[1, 2, 3].iter().map(|index| mox!(
        <number value={index} />
    ))}
</foo>

mox_impl::elements::foo(|builder| {
    builder
    .add_child(
        [1, 2, 3].iter().map(|index| 
            mox_impl::elements::number(|builder| {
                builder
                .set_attr(mox_impl::attributes::value(), index)
            })
        )
    )
})

[anp]

This is awesome! I've been delayed a little in reading it in detail because there was an opportunity to land #[track_caller] (happening! rust-lang/rust#65881).

I definitely want to support the overall use-cases you have, and I think it's doable. I suspect it will be much easier to figure out once there's a stable syntax for topo::nested functions. One concrete way the transition will make these questions easier is by allowing inherent method impls to also be nested, not just free functions. My rough thinking:

• get topo to a point without macros on nightly
• update moxie, moxie-native
• overhaul moxie-dom's builder API, probably modify my mox to match that
• see whether you want to change the shape of this proposal based on that
• revisit, make a decision which will hopefully be obvious by this point

Since mox is so small I don't see harm in updating two versions, plus if I do the rebase for moxie-native then I'll get much more familiar with the challenges you lay out here.

What do you think?

[tiffany352]

@anp Sounds good!

[tiffany352]

Update: the moxie-native mox fork now produces output like this:

    mox_impl::elt::app()
        .add_child(mox_impl::elt::window()
            .set_attr(mox_impl::attr::title(), "Moxie-Native Demo")
            .add_child(mox_impl::elt::view()
                .add_child(mox_impl::elt::button()
                    .set_attr(mox_impl::attr::style(), { MY_STYLE })
                    .on_event(mox_impl::event::on_click(), { on_click })
                    .add_child(mox_impl::elt::span()
                        .add_child("Click me! Total clicks: ")
                        .add_child(format!("{}", click_count))
                        .build()
                    ).build()
                ).build()
            ).build()
        ).build()

(for this snippet:)

    mox! {
        <app>
            <window title="Moxie-Native Demo">
                <view>
                    <button style={MY_STYLE} on_click={on_click}>
                        <span>
                            "Click me! Total clicks: "
                            {% "{}", click_count}
                        </span>
                    </button>
                </view>
            </window>
        </app>
    }

[anp]

This is much closer to what I expected moxie-dom would look like after #[track_caller]!

[anp]

Update on my end: after playing around with DOM bindings a bunch, I'm really liking where #121 ends up. It's pretty similar to what you describe here, with the exception that attributes are "just" method calls. To reuse the snippet you gave, this is what I'd expect it to produce:

app()
    .child(window()
        .title("Moxie-Native Demo")
        .child(view()
            .child(button()
                .style(MY_STYLE)
                .on_click(on_click)
                .child(span()
                    .child(text("Click me! Total clicks: "))
                    .child(text(format!("{}", click_count)))
                    .build()
                ).build()
            ).build()
        ).build()
    ).build()
).build()

The main benefit I see of this approach is that when it's necessary to "drop out" of the mox syntax the resulting calls look like fairly natural Rust:

pub fn filter_footer(num_complete: usize, num_active: usize) -> Footer {
    let mut footer = footer().class("footer").child(items_remaining(num_active)).child(filter());

    if num_complete > 0 {
        footer = footer.child(clear_completed_button(num_complete));
    }

    footer.build()
}

(from https://github.com/anp/moxie/pull/121/files#diff-183f1f13c96fe789ab29f87f87a8c922R33)

Thoughts?

[anp]

Also worth noting that this draws from your original and updated proposal in several ways, I think that it has the same questions about conditionals and iterators that you raised, I'm hoping that having a "more natural" non-mox syntax for elements would help there.

[tiffany352]

There's two concerns I have:

1. The constructors still get dumped into the scope, so you have to use a wildcard use to use the mox macro still. This also results in less clear error messages, due to shadowing. If I have a function called window and then use <window> it will produce a weird error (something like a type mismatch between Node<Window> and Builder<Window>).
2. .style(foo) will make it impossible to create a Builder<T> that's generic, which is where I'm at in moxie-native. It will require a macro to generate builder types for each tag.

I don't really want to lose either of these in moxie-native, but it seems weird not to unify them when they're so close now.

[anp]

Could you expand on (1)? I'm using glob imports in some parts of the PR I linked but explicit imports work fine too.

If your concern is having to have the constructor in scope at all, I could see choosing a module namespace approach (IIRC ReasonReact essentially does this at the type level), although that hampers the legibility of the non-mox case, adds nesting to rustdoc, additional things to explain when teaching, possibly other costs.

I don't think I understand the restriction you describe in (2) but would be happy to read some code to understand better.

I agree that the closer the two macros are the more incentive there is to unify them, especially if they get so close as to be "in each other's uncanny valley" from a user's perspective. That said, I'm finding that the more fluent the underlying builder API can be made, the less bothersome it is to drop down to regular builder syntax, and it's changing my thinking a little bit about mox's role in the core crate -- making me think more and more that an XML syntax for Rust should be an addition to a (any??) builder API, rather than necessarily dictating the constraints itself. It's a drastic shift from its previous role which was essentially as a tool to cope with the awful syntax transformations topo imposed. I'm not entirely sure what this means for these considerations though. Maybe moxie won't re-export mox by the time I cut a 1.0, allowing for more clarity between the differences? Not sure.

Here's another thing that's coming to mind just now: I've been thinking about a proc macro like #[mox::tag] that could be applied to a function to make it into a builder, which would be a nice way to make custom components without tons of boilerplate. Still, maybe it's worth thinking harder about how much code my current approach requires one to write out to get a builder. Ooh, fully train of thought now: maybe it's worth seeing how to mirror what derive-builder produces so that could be recommended instead?

EDIT: Also thank you for the speedy and useful feedback!

[tiffany352]

In the version I have all of the builder constructors are namespaced in mox_impl::elt::* which makes it so if you use one that doesn't exist, the error is pretty clear. This makes it impossible to define custom tags though, so I'm not sure.

As for the second point, in moxie-native there is only a .attr(key, value) method on the builder. The key is the return value of a function in mox_impl::attr::* which has a trait implemented for it. This allows me to define Builder without it knowing about which attributes exist.

I'd be fine with dropping this if there was a proc macro though. Before the builder type I was using macro_rules and it was annoying to maintain.

[anp]

Yeah I like that the error message is clear as you describe but I think custom tags are pretty important, and forced to choose between the two I'd go for custom tags (truly awful error messages notwithstanding).

The generic builder is nice, that makes more sense to me. Thanks for bearing with me :D. I've opened #125 to discuss designs for a proc macro that could ease the pain of the new API. Meanwhile, no pressure from me to migrate and we can figure out a tag attribute that would work for you (and probably open up a lot of nice cases). AFAIK if I land #121 now you shouldn't be blocked from consuming new runtime versions separately from the macro, but if I'm wrong about that definitely let me know.