Preferred way to build custom components with builder syntax

[spencewenski]

Hi, I am interested in using Leptos and am currently leaning toward preferring the builder syntax because so far it seems to have better auto-complete support in RustRover/JetBrains. However, I haven't been able to find many examples of how to build a component (other than the built-in HTML methods (p(), div(), etc) using the builder syntax. Hence I have a couple questions:

1. What is the preferred method to build a custom component, e.g. the SimpleCounter from the counter example, using builder syntax?

Here's what I've tried:

1. Inspecting the expanded macro results in something like this:

component_view(
    SimpleCounter,
    component_props_builder(&SimpleCounter)
        .initial_value(0)
        .step(1)
        .build(),
)

However, I noticed that component_view and component_props_builder are annotated with #[doc(hidden)], which indicates to me that these are not meant to be used directly. Is that accurate?

2. Constructing the SimpleCounter as a normal method call (similar to the "no macros" example):

// 1. Directly creating the props
SimpleCounter(SimpleCounterProps {
    initial_value: 0,
    step: 1,
})

// 2. Creating props using the builder
SimpleCounter(
    SimpleCounterProps::builder()
        .initial_value(0)
        .step(1)
        .build(),
)

// 3. Creating the component from the props directly
SimpleCounterProps::builder()
    .initial_value(0)
    .step(1)
    .build()

Option 3 seems like the most direct equivalent to the built-in HTML methods. It is a little odd to use the *Props instead of just the component name, but this is probably my preferred approach at the moment because it removes a level of nesting from the SimpleCounter method call, which is extra useful when providing children to a custom component. Is this approach recommended? Is there another approach that would be better?

2. What is the preferred way to provide children to custom components using the builder syntax?

For this section, assume we updated the SimpleCounter to take children:

#[component]
pub fn SimpleCounter(
    // ... other props here
    #[prop(optional)]
    children: Option<Children>,
) -> impl IntoView {
  // ...
}

We can then provide a child with the view! macro as follows:

view! {
    <SimpleCounter
        initial_value=0
        step=1
    >
        <p>Foo</p>
    </SimpleCounter>
}

If we expand the macro we get something like this:

// ...
.children(ToChildren::to_children(|| {
    Fragment::lazy(|| {
        <[_]>::into_vec(Box::new([IntoView::into_view(
            p().child("Foo"),
        )]))
    })
}))

Which can be cleaned up slightly:

// ...
.children(Box::new(|| {
    Fragment::lazy(|| vec![p().child("Foo").into_view()])
}))

However, this is still pretty verbose. Is there another method of providing children I'm missing? It would be great if there's a way to provide children without needing to manually wrap them in a Box and a Fragment.

[gbj]

I guess I'm not sure whether you are mostly talking about using your own components, or using the built-in control flow components (Show, Suspense, etc.)

For your own components, you can of course just write a function instead of using the component macro. The macro is mostly useful so we can have named arguments in the XML-like syntax.

For example here's a perfectly reasonable way to have a component with children with no macros:

#[component]
pub fn App() -> impl IntoView {
    WithChildren(|| p().child("foo bar").into_view())
}

pub fn WithChildren(children: impl FnOnce() -> View) -> impl IntoView {
    div().child(children())
}

If you're talking about the built-in components that take the Children type then note that Fragment implements From<View> and FromIterator<View>, so you can do things like

#[component]
pub fn App() -> impl IntoView {
    (
        WithChildren(Box::new(|| p().child("Foo").into_view().into())),
        WithChildren(Box::new(|| {
            [p().child("Bar").into_view(), p().child("Baz").into_view()]
                .into_iter()
                .collect()
        })),
    )
}

pub fn WithChildren(children: Children) -> impl IntoView {
    div().child(children())
}

[spencewenski]

Interesting, I hadn't considered just using impl FnOnce() -> View for my own components. That's helpful, though more verbose than just writing Children as the type. (BTW, I would probably continue to use the #[component] macro because it's nice that it auto-generates a builder for the props and allows documenting the method parameters/props.)

However, for components that take Children, it's IMO a little less than ideal that the children need to be manually wrapped with Box, particularly when that's not required for the built-in HTML functions.

Perhaps my more high-level/meta feedback is I wish the builder syntax had a more consistent API. So far I've observed that some things don't require manual wrapping in Box (e.g., div().child(...)), while others do (e.g. Provider), and still others need to be wrapped in Rc (e.g. Show, which takes a ChildrenFn). Examples:

ProviderProps::builder()
    .children(Box::new(|| p().child("Foo").into_view().into()))
    // ...

ShowProps::builder()
    .children(Rc::new(|| {
        p().child("children").into_view().into()
    }))
    // ...

From my outside/new-comer's perspective, it's not immediately obvious to me why different components use different types for their children. Though I probably wouldn't consider these inconsistencies a blocker for using Leptos with the builder syntax, and I understand consistency in the builder API may not (at least historically) be a high priority as most users use the JSX-like syntax, it would be a nice DX improvement to have a more consistent API.

Maybe I'm missing some context? Is there any documentation around why components use different children types? Are there any plans to provide a more consistent builder API?

[gbj]

The ToChildren trait is designed for you not to need to know what type of children they take:

#[component]
pub fn App() -> impl IntoView {
    (
        Provider(
            ProviderProps::builder()
                .value(42)
                .children(ToChildren::to_children(|| {
                    p().child("Foo").into_view().into()
                }))
                .build(),
        ),
        Show(
            ShowProps::builder()
                .when(|| true)
                .children(ToChildren::to_children(|| {
                    p().child("children").into_view().into()
                }))
                .build(),
        ),
    )
}

So the API isn't really inconsistent -- it might be annoying because it's mostly a target for the macro, but the macro doesn't know anything about the types of the components etc.

[spencewenski]

I see... ToChildren is hidden from documentation, though (which also seems to hide it from Jetbrains' auto-complete). I assumed this meant it wasn't intended to be used externally. Is that not correct?

[gbj]

You're just giving me too much credit for thoughtfulness, here. It's designed to be used with the macros, or with no macros; you're the first person to raise the fact that, if you want to use the component macro but not the view macro, then the most useful trait is hidden from docs. That's all.

[spencewenski]

Cool, in that case I think ToChildren is a reasonable approach. I opened a PR to add docs for it: #2643