Text Rework cleanup (#15887)

# Objective

Cleanup naming and docs, add missing migration guide after #15591 

All text root nodes now use `Text` (UI) / `Text2d`.
All text readers/writers use `Text<Type>Reader`/`Text<Type>Writer`
convention.

---

## Migration Guide

Doubles as #15591 migration guide.

Text bundles (`TextBundle` and `Text2dBundle`) were removed in favor of
`Text` and `Text2d`.
Shared configuration fields were replaced with `TextLayout`, `TextFont`
and `TextColor` components.
Just `TextBundle`'s additional field turned into `TextNodeFlags`
component,
while `Text2dBundle`'s additional fields turned into `TextBounds` and
`Anchor` components.

Text sections were removed in favor of hierarchy-based approach.
For root text entities with `Text` or `Text2d` components, child
entities with `TextSpan` will act as additional text sections.
To still access text spans by index, use the new `TextUiReader`,
`Text2dReader` and `TextUiWriter`, `Text2dWriter` system parameters.

crates/bevy_dev_tools/src/fps_overlay.rs

@@ -17,7 +17,7 @@ use bevy_render::view::Visibility;
 use bevy_text::{Font, TextColor, TextFont, TextSpan};
 use bevy_ui::{
     node_bundles::NodeBundle,
-    widget::{Text, UiTextWriter},
+    widget::{Text, TextUiWriter},
     GlobalZIndex, PositionType, Style,
 };
 use bevy_utils::default;
@@ -114,7 +114,7 @@ fn setup(mut commands: Commands, overlay_config: Res<FpsOverlayConfig>) {
 fn update_text(
     diagnostic: Res<DiagnosticsStore>,
     query: Query<Entity, With<FpsText>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     for entity in &query {
         if let Some(fps) = diagnostic.get(&FrameTimeDiagnosticsPlugin::FPS) {
@@ -128,7 +128,7 @@ fn update_text(
 fn customize_text(
     overlay_config: Res<FpsOverlayConfig>,
     query: Query<Entity, With<FpsText>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     for entity in &query {
         writer.for_each_font(entity, |mut font| {

crates/bevy_text/src/lib.rs

@@ -63,10 +63,13 @@ pub use text_access::*;
 ///
 /// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
+    #[doc(hidden)]
+    #[allow(deprecated)]
+    pub use crate::Text2dBundle;
     #[doc(hidden)]
     pub use crate::{
-        Font, JustifyText, LineBreak, Text2d, TextColor, TextError, TextFont, TextLayout,
-        TextReader2d, TextSpan, TextWriter2d,
+        Font, JustifyText, LineBreak, Text2d, Text2dReader, Text2dWriter, TextColor, TextError,
+        TextFont, TextLayout, TextSpan,
     };
 }
 

crates/bevy_text/src/text2d.rs

@@ -32,6 +32,18 @@ use bevy_transform::prelude::GlobalTransform;
 use bevy_utils::HashSet;
 use bevy_window::{PrimaryWindow, Window, WindowScaleFactorChanged};
 
+/// [`Text2dBundle`] was removed in favor of required components.
+/// The core component is now [`Text2d`] which can contain a single text segment.
+/// Indexed access to segments can be done with the new [`Text2dReader`] and [`Text2dWriter`] system params.
+/// Additional segments can be added through children with [`TextSpan`](crate::text::TextSpan).
+/// Text configuration can be done with [`TextLayout`], [`TextFont`] and [`TextColor`],
+/// while sprite-related configuration uses [`TextBounds`] and [`Anchor`] components.
+#[deprecated(
+    since = "0.15.0",
+    note = "Text2dBundle has been migrated to required components. Follow the documentation for more information."
+)]
+pub struct Text2dBundle {}
+
 /// The top-level 2D text component.
 ///
 /// Adding `Text2d` to an entity will pull in required components for setting up 2d text.
@@ -120,10 +132,10 @@ impl From<String> for Text2d {
 }
 
 /// 2d alias for [`TextReader`].
-pub type TextReader2d<'w, 's> = TextReader<'w, 's, Text2d>;
+pub type Text2dReader<'w, 's> = TextReader<'w, 's, Text2d>;
 
 /// 2d alias for [`TextWriter`].
-pub type TextWriter2d<'w, 's> = TextWriter<'w, 's, Text2d>;
+pub type Text2dWriter<'w, 's> = TextWriter<'w, 's, Text2d>;
 
 /// This system extracts the sprites from the 2D text components and adds them to the
 /// "render world".
@@ -239,7 +251,7 @@ pub fn update_text2d_layout(
         &mut TextLayoutInfo,
         &mut ComputedTextBlock,
     )>,
-    mut text_reader: TextReader2d,
+    mut text_reader: Text2dReader,
     mut font_system: ResMut<CosmicFontSystem>,
     mut swash_cache: ResMut<SwashCache>,
 ) {

crates/bevy_text/src/text_access.rs

@@ -45,7 +45,7 @@ impl TextIterScratch {
 
 /// System parameter for reading text spans in a text block.
 ///
-/// `R` is the root text component, and `S` is the text span component on children.
+/// `R` is the root text component.
 #[derive(SystemParam)]
 pub struct TextReader<'w, 's, R: TextRoot> {
     // This is a local to avoid system ambiguities when TextReaders run in parallel.

crates/bevy_ui/src/accessibility.rs

@@ -1,6 +1,6 @@
 use crate::{
     prelude::{Button, Label},
-    widget::UiTextReader,
+    widget::TextUiReader,
     Node, UiChildren, UiImage,
 };
 use bevy_a11y::{
@@ -19,7 +19,7 @@ use bevy_render::{camera::CameraUpdateSystem, prelude::Camera};
 use bevy_transform::prelude::GlobalTransform;
 
 fn calc_name(
-    text_reader: &mut UiTextReader,
+    text_reader: &mut TextUiReader,
     children: impl Iterator<Item = Entity>,
 ) -> Option<Box<str>> {
     let mut name = None;
@@ -62,7 +62,7 @@ fn button_changed(
     mut commands: Commands,
     mut query: Query<(Entity, Option<&mut AccessibilityNode>), Changed<Button>>,
     ui_children: UiChildren,
-    mut text_reader: UiTextReader,
+    mut text_reader: TextUiReader,
 ) {
     for (entity, accessible) in &mut query {
         let name = calc_name(&mut text_reader, ui_children.iter_ui_children(entity));
@@ -89,7 +89,7 @@ fn image_changed(
     mut commands: Commands,
     mut query: Query<(Entity, Option<&mut AccessibilityNode>), (Changed<UiImage>, Without<Button>)>,
     ui_children: UiChildren,
-    mut text_reader: UiTextReader,
+    mut text_reader: TextUiReader,
 ) {
     for (entity, accessible) in &mut query {
         let name = calc_name(&mut text_reader, ui_children.iter_ui_children(entity));
@@ -115,7 +115,7 @@ fn image_changed(
 fn label_changed(
     mut commands: Commands,
     mut query: Query<(Entity, Option<&mut AccessibilityNode>), Changed<Label>>,
-    mut text_reader: UiTextReader,
+    mut text_reader: TextUiReader,
 ) {
     for (entity, accessible) in &mut query {
         let values = text_reader

crates/bevy_ui/src/lib.rs

@@ -46,14 +46,20 @@ use widget::UiImageSize;
 ///
 /// This includes the most common types in this crate, re-exported for your convenience.
 pub mod prelude {
+    #[allow(deprecated)]
+    #[doc(hidden)]
+    pub use crate::widget::TextBundle;
+    #[cfg(feature = "bevy_text")]
+    #[doc(hidden)]
+    pub use crate::widget::{Text, TextUiReader, TextUiWriter};
     #[doc(hidden)]
     pub use {
         crate::{
             geometry::*,
             node_bundles::*,
             ui_material::*,
             ui_node::*,
-            widget::{Button, Label, Text, UiTextReader, UiTextWriter},
+            widget::{Button, Label},
             Interaction, UiMaterialHandle, UiMaterialPlugin, UiScale,
         },
         // `bevy_sprite` re-exports for texture slicing

crates/bevy_ui/src/widget/text.rs

@@ -48,6 +48,18 @@ impl Default for TextNodeFlags {
     }
 }
 
+/// [`TextBundle`] was removed in favor of required components.
+/// The core component is now [`Text`] which can contain a single text segment.
+/// Indexed access to segments can be done with the new [`TextUiReader`] and [`TextUiWriter`] system params.
+/// Additional segments can be added through children with [`TextSpan`](bevy_text::TextSpan).
+/// Text configuration can be done with [`TextLayout`], [`TextFont`] and [`TextColor`],
+/// while node-related configuration uses [`TextNodeFlags`] component.
+#[deprecated(
+    since = "0.15.0",
+    note = "TextBundle has been migrated to required components. Follow the documentation for more information."
+)]
+pub struct TextBundle {}
+
 /// The top-level UI text component.
 ///
 /// Adding [`Text`] to an entity will pull in required components for setting up a UI text node.
@@ -137,10 +149,10 @@ impl From<String> for Text {
 }
 
 /// UI alias for [`TextReader`].
-pub type UiTextReader<'w, 's> = TextReader<'w, 's, Text>;
+pub type TextUiReader<'w, 's> = TextReader<'w, 's, Text>;
 
 /// UI alias for [`TextWriter`].
-pub type UiTextWriter<'w, 's> = TextWriter<'w, 's, Text>;
+pub type TextUiWriter<'w, 's> = TextWriter<'w, 's, Text>;
 
 /// Text measurement for UI layout. See [`NodeMeasure`].
 pub struct TextMeasure {
@@ -273,7 +285,7 @@ pub fn measure_text_system(
         ),
         With<Node>,
     >,
-    mut text_reader: UiTextReader,
+    mut text_reader: TextUiReader,
     mut text_pipeline: ResMut<TextPipeline>,
     mut font_system: ResMut<CosmicFontSystem>,
 ) {
@@ -336,7 +348,7 @@ fn queue_text(
     mut text_flags: Mut<TextNodeFlags>,
     text_layout_info: Mut<TextLayoutInfo>,
     computed: &mut ComputedTextBlock,
-    text_reader: &mut UiTextReader,
+    text_reader: &mut TextUiReader,
     font_system: &mut CosmicFontSystem,
     swash_cache: &mut SwashCache,
 ) {
@@ -416,7 +428,7 @@ pub fn text_system(
         &mut ComputedTextBlock,
         Option<&TargetCamera>,
     )>,
-    mut text_reader: UiTextReader,
+    mut text_reader: TextUiReader,
     mut font_system: ResMut<CosmicFontSystem>,
     mut swash_cache: ResMut<SwashCache>,
 ) {

examples/3d/color_grading.rs

@@ -561,7 +561,7 @@ fn update_ui_state(
     )>,
     button_text: Query<(Entity, &ColorGradingOptionWidget), (With<Text>, Without<HelpText>)>,
     help_text: Single<Entity, With<HelpText>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
     cameras: Single<Ref<ColorGrading>>,
     currently_selected_option: Res<SelectedColorGradingOption>,
 ) {

examples/3d/lighting.rs

@@ -255,7 +255,7 @@ fn update_exposure(
     mut parameters: ResMut<Parameters>,
     mut exposure: Single<&mut Exposure>,
     text: Single<Entity, With<Text>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     // TODO: Clamp values to a reasonable range
     let entity = *text;

examples/3d/motion_blur.rs

@@ -254,7 +254,7 @@ fn keyboard_inputs(
     mut motion_blur: Single<&mut MotionBlur>,
     presses: Res<ButtonInput<KeyCode>>,
     text: Single<Entity, With<Text>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
     mut camera: ResMut<CameraMode>,
 ) {
     if presses.just_pressed(KeyCode::Digit1) {

examples/3d/order_independent_transparency.rs

@@ -67,7 +67,7 @@ fn toggle_oit(
     text: Single<Entity, With<Text>>,
     keyboard_input: Res<ButtonInput<KeyCode>>,
     q: Single<(Entity, Has<OrderIndependentTransparencySettings>), With<Camera3d>>,
-    mut text_writer: UiTextWriter,
+    mut text_writer: TextUiWriter,
 ) {
     if keyboard_input.just_pressed(KeyCode::KeyT) {
         let (e, has_oit) = *q;

examples/3d/parallax_mapping.rs

@@ -80,7 +80,7 @@ fn update_parallax_depth_scale(
     mut materials: ResMut<Assets<StandardMaterial>>,
     mut target_depth: Local<TargetDepth>,
     mut depth_update: Local<bool>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
     text: Single<Entity, With<Text>>,
 ) {
     if input.just_pressed(KeyCode::Digit1) {
@@ -110,7 +110,7 @@ fn switch_method(
     input: Res<ButtonInput<KeyCode>>,
     mut materials: ResMut<Assets<StandardMaterial>>,
     text: Single<Entity, With<Text>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
     mut current: Local<CurrentMethod>,
 ) {
     if input.just_pressed(KeyCode::Space) {
@@ -131,7 +131,7 @@ fn update_parallax_layers(
     mut materials: ResMut<Assets<StandardMaterial>>,
     mut target_layers: Local<TargetLayers>,
     text: Single<Entity, With<Text>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     if input.just_pressed(KeyCode::Digit3) {
         target_layers.0 -= 1.0;

examples/3d/pcss.rs

@@ -258,7 +258,7 @@ fn update_radio_buttons(
         Or<(With<RadioButton>, With<RadioButtonText>)>,
     >,
     app_status: Res<AppStatus>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     for (entity, image, has_text, sender) in widgets.iter_mut() {
         let selected = match **sender {

examples/3d/shadow_biases.rs

@@ -153,7 +153,7 @@ fn toggle_light(
     mut point_lights: Query<&mut PointLight>,
     mut directional_lights: Query<&mut DirectionalLight>,
     example_text: Single<Entity, With<Text>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     if input.just_pressed(KeyCode::KeyL) {
         for mut light in &mut point_lights {
@@ -179,7 +179,7 @@ fn adjust_light_position(
     input: Res<ButtonInput<KeyCode>>,
     mut lights: Query<&mut Transform, With<Lights>>,
     example_text: Single<Entity, With<Text>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     let mut offset = Vec3::ZERO;
     if input.just_pressed(KeyCode::ArrowLeft) {
@@ -216,7 +216,7 @@ fn cycle_filter_methods(
     input: Res<ButtonInput<KeyCode>>,
     mut filter_methods: Query<&mut ShadowFilteringMethod>,
     example_text: Single<Entity, With<Text>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     if input.just_pressed(KeyCode::KeyF) {
         for mut filter_method in &mut filter_methods {
@@ -244,7 +244,7 @@ fn adjust_point_light_biases(
     input: Res<ButtonInput<KeyCode>>,
     mut query: Query<&mut PointLight>,
     example_text: Single<Entity, With<Text>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     let depth_bias_step_size = 0.01;
     let normal_bias_step_size = 0.1;
@@ -279,7 +279,7 @@ fn adjust_directional_light_biases(
     input: Res<ButtonInput<KeyCode>>,
     mut query: Query<&mut DirectionalLight>,
     example_text: Single<Entity, With<Text>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     let depth_bias_step_size = 0.01;
     let normal_bias_step_size = 0.1;

examples/animation/animation_masks.rs

@@ -474,7 +474,7 @@ fn handle_button_toggles(
 fn update_ui(
     mut animation_controls: Query<(&AnimationControl, &mut BackgroundColor, &Children)>,
     texts: Query<Entity, With<Text>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
     app_state: Res<AppState>,
 ) {
     for (animation_control, mut background_color, kids) in animation_controls.iter_mut() {

examples/ecs/one_shot_systems.rs

@@ -79,12 +79,12 @@ fn evaluate_callbacks(query: Query<(Entity, &Callback), With<Triggered>>, mut co
     }
 }
 
-fn system_a(entity_a: Single<Entity, With<Text>>, mut writer: UiTextWriter) {
+fn system_a(entity_a: Single<Entity, With<Text>>, mut writer: TextUiWriter) {
     *writer.text(*entity_a, 3) = String::from("A");
     info!("A: One shot system registered with Commands was triggered");
 }
 
-fn system_b(entity_b: Single<Entity, With<Text>>, mut writer: UiTextWriter) {
+fn system_b(entity_b: Single<Entity, With<Text>>, mut writer: TextUiWriter) {
     *writer.text(*entity_b, 3) = String::from("B");
     info!("B: One shot system registered with World was triggered");
 }

examples/games/breakout.rs

@@ -336,7 +336,7 @@ fn apply_velocity(mut query: Query<(&mut Transform, &Velocity)>, time: Res<Time>
 fn update_scoreboard(
     score: Res<Score>,
     score_root: Single<Entity, (With<ScoreboardUi>, With<Text>)>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     *writer.text(*score_root, 1) = score.to_string();
 }

examples/games/contributors.rs

@@ -161,7 +161,7 @@ fn selection(
     mut contributor_selection: ResMut<ContributorSelection>,
     contributor_root: Single<Entity, (With<ContributorDisplay>, With<Text>)>,
     mut query: Query<(&Contributor, &mut Sprite, &mut Transform)>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
     time: Res<Time>,
 ) {
     if !timer.0.tick(time.delta()).just_finished() {
@@ -204,7 +204,7 @@ fn select(
     contributor: &Contributor,
     transform: &mut Transform,
     entity: Entity,
-    writer: &mut UiTextWriter,
+    writer: &mut TextUiWriter,
 ) {
     sprite.color = SELECTED.with_hue(contributor.hue).into();
 

examples/games/stepping.rs

@@ -240,7 +240,7 @@ fn update_ui(
     state: Res<State>,
     stepping: Res<Stepping>,
     ui: Single<(Entity, &Visibility), With<SteppingUi>>,
-    mut writer: UiTextWriter,
+    mut writer: TextUiWriter,
 ) {
     // ensure the UI is only visible when stepping is enabled
     let (ui, vis) = *ui;