Change feathers bsn APIs to make captions an explicit parameter. (#23787)

# Objective

As discussed in [this discord
thread](https://discord.com/channels/691052431525675048/1492688648360165406),
using the `Children` relation to append caption elements to feathers
widgets is dodgy.

## Solution

Make `caption` an explicit parameter for button, radio, and checkbox
widgets.

Also fixed some erroneous docs.

## Testing

Manual testing of feathers and bevy_city examples.

Note that there's no migration guide because this only affects the bsn
functions, which are new.

Author: viridia

crates/bevy_feathers/src/controls/button.rs

@@ -43,14 +43,26 @@ pub enum ButtonVariant {
 }
 
 /// Parameters for the button template, passed to [`button`] function.
-#[derive(Default)]
 pub struct ButtonProps {
+    /// Label for this button. This can contain multiple entities, which will be contained
+    /// in a horizontal flexbox.
+    pub caption: Box<dyn SceneList>,
     /// Color variant for the button.
     pub variant: ButtonVariant,
     /// Rounded corners options
     pub corners: RoundedCorners,
 }
 
+impl Default for ButtonProps {
+    fn default() -> Self {
+        Self {
+            caption: Box::new(bsn_list!()),
+            variant: ButtonVariant::default(),
+            corners: Default::default(),
+        }
+    }
+}
+
 /// Scene function to spawn a button.
 ///
 /// # Arguments
@@ -85,15 +97,25 @@ pub fn button(props: ButtonProps) -> impl Scene {
             font_size: FontSize::Px(14.0),
             weight: FontWeight::NORMAL,
         }
+        Children [
+            {props.caption}
+        ]
     }
 }
 
+/// Parameters for the [`button_bundle`] template.
+#[derive(Default)]
+pub struct ButtonBundleProps {
+    /// Color variant for the button.
+    pub variant: ButtonVariant,
+    /// Rounded corners options
+    pub corners: RoundedCorners,
+}
+
 /// Template function to spawn a button.
 ///
 /// # Arguments
 /// * `props` - construction properties for the button.
-/// * `overrides` - a bundle of components that are merged in with the normal button components.
-/// * `children` - a [`SpawnableList`] of child elements, such as a label or icon for the button.
 ///
 /// # Emitted events
 /// * [`bevy_ui_widgets::Activate`] when any of the following happens:
@@ -103,7 +125,7 @@ pub fn button(props: ButtonProps) -> impl Scene {
 ///  These events can be disabled by adding an [`bevy_ui::InteractionDisabled`] component to the entity
 #[deprecated(since = "0.19.0", note = "Use the button() BSN function")]
 pub fn button_bundle<C: SpawnableList<ChildOf> + Send + Sync + 'static, B: Bundle>(
-    props: ButtonProps,
+    props: ButtonBundleProps,
     overrides: B,
     children: C,
 ) -> impl Bundle {

crates/bevy_feathers/src/controls/checkbox.rs

@@ -34,6 +34,21 @@ use crate::{
     tokens,
 };
 
+/// Parameters for the checkbox template, passed to [`checkbox`] function.
+pub struct CheckboxProps {
+    /// Label for this checkbox. This can contain multiple entities, which will be contained
+    /// in a flexbox.
+    pub caption: Box<dyn SceneList>,
+}
+
+impl Default for CheckboxProps {
+    fn default() -> Self {
+        Self {
+            caption: Box::new(bsn_list!()),
+        }
+    }
+}
+
 /// Marker for the checkbox frame (contains both checkbox and label)
 #[derive(Component, Default, Clone, Reflect)]
 #[reflect(Component, Clone, Default)]
@@ -55,7 +70,7 @@ struct CheckboxMark;
 /// * [`bevy_ui_widgets::ValueChange<bool>`] with the new value when the checkbox changes state.
 ///
 ///  These events can be disabled by adding an [`bevy_ui::InteractionDisabled`] component to the entity
-pub fn checkbox() -> impl Scene {
+pub fn checkbox(props: CheckboxProps) -> impl Scene {
     bsn! {
         Node {
             display: Display::Flex,
@@ -102,22 +117,20 @@ pub fn checkbox() -> impl Scene {
                 UiTransform::from_rotation(Rot2::FRAC_PI_4)
                 CheckboxMark
                 ThemeBorderColor(tokens::CHECKBOX_MARK)
-            )]
-        )]
+            )]),
+            {props.caption}
+        ]
     }
 }
 
 /// Template function to spawn a checkbox.
 ///
-/// # Arguments
-/// * `props` - construction properties for the checkbox.
-/// * `overrides` - a bundle of components that are merged in with the normal checkbox components.
-/// * `label` - the label of the checkbox.
+/// This version does not take any props. A caption can be set by appending a child entity.
 ///
 /// # Emitted events
 /// * [`bevy_ui_widgets::ValueChange<bool>`] with the new value when the checkbox changes state.
 ///
-///  These events can be disabled by adding an [`bevy_ui::InteractionDisabled`] component to the entity
+/// These events can be disabled by adding an [`bevy_ui::InteractionDisabled`] component to the entity
 #[deprecated(since = "0.19.0", note = "Use the checkbox() BSN function")]
 pub fn checkbox_bundle<C: SpawnableList<ChildOf> + Send + Sync + 'static, B: Bundle>(
     overrides: B,

crates/bevy_feathers/src/controls/menu.rs

@@ -166,14 +166,15 @@ fn on_menu_event(
 pub fn menu_button(props: MenuButtonProps) -> impl Scene {
     bsn! {
         :button(ButtonProps {
+            caption: props.caption,
             variant: ButtonVariant::Normal,
             corners: props.corners,
         })
         ActivateOnPress
         MenuButton
         FeathersMenuButton
+        // Additional children for menu chevron
         Children [
-            {props.caption},
             {
                 if props.arrow {
                     Box::new(bsn_list!(

crates/bevy_feathers/src/controls/radio.rs

@@ -43,14 +43,29 @@ struct RadioOutline;
 #[reflect(Component, Clone, Default)]
 struct RadioMark;
 
+/// Parameters for the radio button template, passed to [`radio`] function.
+pub struct RadioProps {
+    /// Label for this radio button. This can contain multiple entities, which will be contained
+    /// in a flexbox.
+    pub caption: Box<dyn SceneList>,
+}
+
+impl Default for RadioProps {
+    fn default() -> Self {
+        Self {
+            caption: Box::new(bsn_list!()),
+        }
+    }
+}
+
 /// Scene function to spawn a radio.
 ///
 /// # Emitted events
 /// * [`bevy_ui_widgets::ValueChange<bool>`] with the value true when it becomes checked.
 /// * [`bevy_ui_widgets::ValueChange<Entity>`] with the selected entity's id when a new radio button is selected.
 ///
 ///  These events can be disabled by adding an [`bevy_ui::InteractionDisabled`] component to the entity
-pub fn radio() -> impl Scene {
+pub fn radio(props: RadioProps) -> impl Scene {
     bsn! {
         Node {
             display: Display::Flex,
@@ -91,17 +106,15 @@ pub fn radio() -> impl Scene {
                 }
                 RadioMark
                 ThemeBackgroundColor(tokens::RADIO_MARK)
-            )]
-        )]
+            )]),
+            {props.caption}
+        ]
     }
 }
 
 /// Template function to spawn a radio.
 ///
-/// # Arguments
-/// * `props` - construction properties for the radio.
-/// * `overrides` - a bundle of components that are merged in with the normal radio components.
-/// * `label` - the label of the radio.
+/// This version does not take any props. A caption can be set by appending a child entity.
 ///
 /// # Emitted events
 /// * [`bevy_ui_widgets::ValueChange<bool>`] with the value true when it becomes checked.

crates/bevy_feathers/src/controls/virtual_keyboard.rs

@@ -6,7 +6,7 @@ use bevy_ui::Val;
 use bevy_ui::{widget::Text, FlexDirection};
 use bevy_ui_widgets::{observe, Activate};
 
-use crate::controls::button::{button, ButtonProps};
+use crate::controls::button::{button, ButtonBundleProps, ButtonProps};
 use crate::controls::button_bundle;
 
 /// Fired whenever a virtual key is pressed.
@@ -104,7 +104,11 @@ where
                 },
                 Children::spawn(SpawnIter(row.into_iter().map(move |key| {
                     (
-                        button_bundle(ButtonProps::default(), (), Spawn(Text::new(key.as_ref()))),
+                        button_bundle(
+                            ButtonBundleProps::default(),
+                            (),
+                            Spawn(Text::new(key.as_ref())),
+                        ),
                         observe(
                             move |activate: On<Activate>,
                                   mut commands: Commands,

examples/large_scenes/bevy_city/src/settings.rs

@@ -3,7 +3,7 @@ use bevy::{
     camera_controller::free_camera::FreeCameraState,
     feathers::{
         self,
-        controls::{button, checkbox, ButtonProps},
+        controls::{button, checkbox, ButtonProps, CheckboxProps},
         theme::{ThemeBackgroundColor, ThemedText},
     },
     pbr::wireframe::WireframeConfig,
@@ -67,16 +67,23 @@ pub fn settings_ui() -> impl Scene {
             Children [
                 Text("Settings"),
                 (
-                    checkbox()
+                    checkbox(CheckboxProps {
+                        caption: Box::new(bsn_list!(
+                            (Text("Simulate Cars") ThemedText),
+                        )),
+                    })
                     Checked
                     on(checkbox_self_update)
                     on(|change: On<ValueChange<bool>>, mut settings: ResMut<Settings>| {
                         settings.simulate_cars = change.value;
                     })
-                    Children [ (Text("Simulate Cars") ThemedText) ]
                 ),
                 (
-                    checkbox()
+                    checkbox(CheckboxProps {
+                        caption: Box::new(bsn_list!(
+                            (Text("Shadow maps enabled") ThemedText),
+                        )),
+                    })
                     Checked
                     on(checkbox_self_update)
                     on(
@@ -90,10 +97,13 @@ pub fn settings_ui() -> impl Scene {
                             }
                         }
                     )
-                    Children [ (Text("Shadow maps enabled") ThemedText) ]
                 ),
                 (
-                    checkbox()
+                    checkbox(CheckboxProps {
+                        caption: Box::new(bsn_list!(
+                            (Text("Contact shadows enabled") ThemedText),
+                        )),
+                    })
                     Checked
                     on(checkbox_self_update)
                     on(
@@ -107,10 +117,13 @@ pub fn settings_ui() -> impl Scene {
                             }
                         }
                     )
-                    Children [ (Text("Contact shadows enabled") ThemedText) ]
                 ),
                 (
-                    checkbox()
+                    checkbox(CheckboxProps {
+                        caption: Box::new(bsn_list!(
+                            (Text("Wireframe Enabled") ThemedText),
+                        )),
+                    })
                     on(checkbox_self_update)
                     on(
                         |change: On<ValueChange<bool>>,
@@ -120,10 +133,13 @@ pub fn settings_ui() -> impl Scene {
                             wireframe_config.global = change.value;
                         }
                     )
-                    Children [ (Text("Wireframe Enabled") ThemedText) ]
                 ),
                 (
-                    checkbox()
+                    checkbox(CheckboxProps {
+                        caption: Box::new(bsn_list!(
+                            (Text("CPU culling") ThemedText),
+                        )),
+                    })
                     Checked
                     on(checkbox_self_update)
                     on(
@@ -142,10 +158,14 @@ pub fn settings_ui() -> impl Scene {
                             }
                         }
                     )
-                    Children [ (Text("CPU culling") ThemedText) ]
                 ),
                 (
-                    button(ButtonProps::default())
+                    button(ButtonProps {
+                        caption: Box::new(bsn_list!(
+                            (Text("Regenerate City") ThemedText),
+                        )),
+                        ..Default::default()
+                    })
                     on(
                         |_activate: On<Activate>,
                          mut commands: Commands,
@@ -159,7 +179,6 @@ pub fn settings_ui() -> impl Scene {
                             spawn_city(&mut commands, &assets, seed, 32);
                         }
                     )
-                    Children [ (Text("Regenerate City") ThemedText) ]
                 ),
             ]
         )]