Mark bevy_ui_widgets as experimental for now (#20972)

# Objective

- These are still going to undergo *extensive* change: users should be
aware of what they're getting into.
- Fixes #20957.

## Solution

- [x] rename the feature
- [x] remove from our default features
- [x] add warning to crate docs
- [x] add warning to release notes
- [x] add warnings to examples

## Testing

I've run both the `standard_widgets` and `standard_widgets_observers`
examples succesfully.

Author: alice-i-cecile

Cargo.toml

@@ -136,7 +136,6 @@ default = [
   "bevy_color",
   "bevy_core_pipeline",
   "bevy_post_process",
-  "bevy_ui_widgets",
   "bevy_anti_alias",
   "bevy_gilrs",
   "bevy_gizmos",
@@ -295,11 +294,14 @@ bevy_log = ["bevy_internal/bevy_log"]
 # Enable input focus subsystem
 bevy_input_focus = ["bevy_internal/bevy_input_focus"]
 
-# Headless widget collection for Bevy UI.
-bevy_ui_widgets = ["bevy_internal/bevy_ui_widgets"]
+# Experimental headless widget collection for Bevy UI.
+experimental_bevy_ui_widgets = ["bevy_internal/bevy_ui_widgets"]
 
 # Feathers widget collection.
-experimental_bevy_feathers = ["bevy_internal/bevy_feathers"]
+experimental_bevy_feathers = [
+  "bevy_internal/bevy_feathers",
+  "experimental_bevy_ui_widgets",
+]
 
 # Enable passthrough loading for SPIR-V shaders (Only supported on Vulkan, shader capabilities and extensions must agree with the platform implementation)
 spirv_shader_passthrough = ["bevy_internal/spirv_shader_passthrough"]
@@ -4526,6 +4528,7 @@ hidden = true
 name = "testbed_full_ui"
 path = "examples/testbed/full_ui.rs"
 doc-scrape-examples = true
+required-features = ["experimental_bevy_ui_widgets"]
 
 [package.metadata.example.testbed_full_ui]
 hidden = true
@@ -4661,6 +4664,7 @@ wasm = false
 name = "standard_widgets"
 path = "examples/ui/standard_widgets.rs"
 doc-scrape-examples = true
+required-features = ["experimental_bevy_ui_widgets"]
 
 [package.metadata.example.standard_widgets]
 name = "Standard Widgets"
@@ -4672,6 +4676,7 @@ wasm = true
 name = "standard_widgets_observers"
 path = "examples/ui/standard_widgets_observers.rs"
 doc-scrape-examples = true
+required-features = ["experimental_bevy_ui_widgets"]
 
 [package.metadata.example.standard_widgets_observers]
 name = "Standard Widgets (w/Observers)"
@@ -4683,6 +4688,7 @@ wasm = true
 name = "scrollbars"
 path = "examples/ui/scrollbars.rs"
 doc-scrape-examples = true
+required-features = ["experimental_bevy_ui_widgets"]
 
 [package.metadata.example.scrollbars]
 name = "Scrollbars"

crates/bevy_ui_widgets/src/lib.rs

@@ -2,7 +2,15 @@
 //! These widgets have no inherent styling, it's the responsibility of the user to add styling
 //! appropriate for their game or application.
 //!
-//! # State Management
+//! ## Warning: Experimental
+//!
+//! This crate is currently experimental and under active development.
+//! The API is likely to change substantially: be prepared to migrate your code.
+//!
+//! We are actively seeking feedback on the design and implementation of this crate, so please
+//! file issues or create PRs if you have any comments or suggestions.
+//!
+//! ## State Management
 //!
 //! Most of the widgets use external state management: this means that the widgets do not
 //! automatically update their own internal state, but instead rely on the app to update the widget

docs/cargo_features.md

@@ -45,7 +45,6 @@ The default feature set enables most of the expected features of a game engine,
 |bevy_ui|A custom ECS-driven UI framework|
 |bevy_ui_picking_backend|Provides an implementation for picking UI|
 |bevy_ui_render|Provides rendering functionality for bevy_ui|
-|bevy_ui_widgets|Headless widget collection for Bevy UI.|
 |bevy_window|Windowing layer|
 |bevy_winit|winit window and input backend|
 |custom_cursor|Enable winit custom cursor support|
@@ -93,6 +92,7 @@ The default feature set enables most of the expected features of a game engine,
 |dynamic_linking|Force dynamic linking, which improves iterative compile times|
 |embedded_watcher|Enables watching in memory asset providers for Bevy Asset hot-reloading|
 |experimental_bevy_feathers|Feathers widget collection.|
+|experimental_bevy_ui_widgets|Experimental headless widget collection for Bevy UI.|
 |experimental_pbr_pcss|Enable support for PCSS, at the risk of blowing past the global, per-shader sampler limit on older/lower-end GPUs|
 |exr|EXR image format support|
 |ff|Farbfeld image format support|

examples/ui/standard_widgets.rs

@@ -1,4 +1,9 @@
-//! This example illustrates how to create widgets using the `bevy_ui_widgets` widget set.
+//! This experimental example illustrates how to create widgets using the `bevy_ui_widgets` widget set.
+//!
+//! These widgets have no inherent styling, so this example also shows how to implement custom styles.
+//!
+//! The patterns shown here are likely to change substantially as the `bevy_ui_widgets` crate
+//! matures, so please exercise caution if you are using this as a reference for your own code.
 
 use bevy::{
     color::palettes::basic::*,

examples/ui/standard_widgets_observers.rs

@@ -1,4 +1,7 @@
-//! This example illustrates how to create widgets using the `bevy_ui_widgets` widget set.
+//! This experimental example illustrates how to create widgets using the `bevy_ui_widgets` widget set.
+//!
+//! The patterns shown here are likely to change substantially as the `bevy_ui_widgets` crate
+//! matures, so please exercise caution if you are using this as a reference for your own code.
 
 use bevy::{
     color::palettes::basic::*,

release-content/release-notes/headless-widgets.md

@@ -27,6 +27,16 @@ which can be added to any UI Node to get widget-like behavior. The standard widg
 sliders, scrollbars, checkboxes, radio buttons, and more. This set will likely be expanded in
 future releases.
 
+While these widgets are usable today, and are a solid choice for creating your own widgets for your
+own game or application, they are still **experimental**.
+Expect breaking changes as we continue to iterate and improve on them!
+
+We're as excited as you are for first-party widgets,
+and we've decided to ship these now precisely so people can try them out:
+real-world user feedback is vital for building and improving products.
+
+If you've read this and are still excited to try them out, enable the `experimental_bevy_ui_widgets` feature.
+
 ## Standard Widgets
 
 The `bevy_ui_widgets` crate provides implementations of unstyled widgets, such as buttons,