From d1c51e4e770959b9d0eb0bc8ec6a855a36b8f473 Mon Sep 17 00:00:00 2001 From: Spencer Ferris <3319370+spencewenski@users.noreply.github.com> Date: Fri, 21 Jun 2024 15:57:50 -0700 Subject: [PATCH 1/2] docs: Add docs for `ToChildren` As discussed in https://github.com/leptos-rs/leptos/discussions/2640, the `ToChildren` trait is useful to consumers who want to use the builder syntax. However, because it is currently annotated with `#[docs(hidden)]`, it's not visible in docs and also not included in Jetbrains's auto-complete. Add a doc comment for the `ToChildren` trait, including doc tests that demonstrate how to use the trait and how it compares to directly creating children. --- leptos/src/children.rs | 56 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/leptos/src/children.rs b/leptos/src/children.rs index 2d369cf213..303fb012fa 100644 --- a/leptos/src/children.rs +++ b/leptos/src/children.rs @@ -16,8 +16,62 @@ pub type ChildrenFnMut = Box Fragment>; // This is to still support components that accept `Box Fragment>` as a children. type BoxedChildrenFn = Box Fragment>; -#[doc(hidden)] +/// This trait can be used when constructing a component that takes children without needing +/// to know exactly what children type the component expects. This is used internally by the +/// `view!` macro implementation, and can also be used explicitly when using the builder syntax. +/// +/// # Examples +/// +/// ## Without ToChildren +/// +/// Without [ToChildren], consumers need to explicitly provide children using the type expected +/// by the component. For example, [Provider][crate::Provider]'s children need to wrapped in +/// a [Box], while [Show][crate::Show]'s children need to be wrapped in an [Rc]. +/// +/// ``` +/// # use leptos::{ProviderProps, ShowProps}; +/// # use leptos_dom::html::p; +/// # use leptos_dom::IntoView; +/// # use leptos_macro::component; +/// # use std::rc::Rc; +/// # +/// #[component] +/// fn App() -> impl IntoView { +/// ( +/// ProviderProps::builder() +/// .children(Box::new(|| p().child("Foo").into())), +/// ShowProps::builder().children(Rc::new(|| p().child("Foo").into())), +/// ) +/// } +/// ``` +/// +/// ## With ToChildren +/// +/// With [ToChildren], consumers don't need to know exactly which type a component uses for +/// its children. This also removes the need to call `into()` on items in the children closure. +/// +/// ``` +/// # use leptos::{ProviderProps, ShowProps}; +/// # use leptos_dom::html::p; +/// # use leptos_dom::IntoView; +/// # use leptos_macro::component; +/// # use std::rc::Rc; +/// # use leptos::ToChildren; +/// # +/// #[component] +/// fn App() -> impl IntoView { +/// ( +/// ProviderProps::builder() +/// .children(ToChildren::to_children(|| p().child("Foo"))), +/// ShowProps::builder() +/// .children(ToChildren::to_children(|| p().child("Foo"))), +/// ) +/// } +/// ``` pub trait ToChildren { + /// Convert the provided type to (generally a closure) to Self (generally a "children" type, + /// e.g., [Children]). See the implementations to see exactly which input types are supported + /// and which "children" type they are converted to. fn to_children(f: F) -> Self; } From 645f627dc54201f99efe876d0506b003090892be Mon Sep 17 00:00:00 2001 From: Spencer Ferris <3319370+spencewenski@users.noreply.github.com> Date: Sat, 22 Jun 2024 11:11:47 -0700 Subject: [PATCH 2/2] docs: Fix incorrect examples in `ToChildren` docs Some examples were added to `ToChildren` that don't compile. This wasn't caught earlier because no errors were seen in the IDE when writing the examples. The issue was correctly caught by CI, however. --- leptos/src/children.rs | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/leptos/src/children.rs b/leptos/src/children.rs index 303fb012fa..404a0e59d0 100644 --- a/leptos/src/children.rs +++ b/leptos/src/children.rs @@ -39,8 +39,16 @@ type BoxedChildrenFn = Box Fragment>; /// fn App() -> impl IntoView { /// ( /// ProviderProps::builder() -/// .children(Box::new(|| p().child("Foo").into())), -/// ShowProps::builder().children(Rc::new(|| p().child("Foo").into())), +/// .children(Box::new(|| p().child("Foo").into_view().into())) +/// // ... +/// # .value("Foo") +/// # .build(), +/// ShowProps::builder() +/// .children(Rc::new(|| p().child("Foo").into_view().into())) +/// // ... +/// # .when(|| true) +/// # .fallback(|| p().child("foo")) +/// # .build(), /// ) /// } /// ``` @@ -48,7 +56,7 @@ type BoxedChildrenFn = Box Fragment>; /// ## With ToChildren /// /// With [ToChildren], consumers don't need to know exactly which type a component uses for -/// its children. This also removes the need to call `into()` on items in the children closure. +/// its children. /// /// ``` /// # use leptos::{ProviderProps, ShowProps}; @@ -62,12 +70,22 @@ type BoxedChildrenFn = Box Fragment>; /// fn App() -> impl IntoView { /// ( /// ProviderProps::builder() -/// .children(ToChildren::to_children(|| p().child("Foo"))), +/// .children(ToChildren::to_children(|| { +/// p().child("Foo").into_view().into() +/// })) +/// // ... +/// # .value("Foo") +/// # .build(), /// ShowProps::builder() -/// .children(ToChildren::to_children(|| p().child("Foo"))), +/// .children(ToChildren::to_children(|| { +/// p().child("Foo").into_view().into() +/// })) +/// // ... +/// # .when(|| true) +/// # .fallback(|| p().child("foo")) +/// # .build(), /// ) /// } -/// ``` pub trait ToChildren { /// Convert the provided type to (generally a closure) to Self (generally a "children" type, /// e.g., [Children]). See the implementations to see exactly which input types are supported