It looks like your PR has been selected for a highlight in the next release blog post, but you didn't provide a release note.

Please review the instructions for writing release notes, then expand or revise the content in the release notes directory to showcase your changes.

Seconding @viridia here: I really like this work and the broad direction, but want to try and chunk this down as best as we can.

Seeing the central vision here was really compelling and useful, and gives me the confidence to start merging little chunks of this in.

If TextSpan is removed, issues arise when displaying long texts that require line breaks or when performing per-span text styling in languages where words are not separated by spaces, such as Japanese or Chinese. In these languages, the text moves to the next line when the character boundary reaches the right edge of the screen, rather than at word boundaries.

Please take a look at the screenshot below. It compares the results when splitting long text into multiple Text or TextSpan elements to apply different colors to each part. The UiDebugOption is enabled, showing the boundaries of GUI elements. The rendering with TextSpans is properly line-broken. On the other hand, with Texts, line breaks are applied to each part, making it difficult to read the text as a whole.

This screenshot is from v0.17.1. I also tested the code from this pull request, but I couldn't find any functionality that performs rendering equivalent to TextSpan.

// Bevy 0.17

use bevy::{color::palettes::tailwind, input::common_conditions::input_just_pressed, prelude::*};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, startup)
        // Press Escape to exit.
        .add_systems(
            Update,
            (|mut exit: MessageWriter<AppExit>| _ = exit.write_default())
                .run_if(input_just_pressed(KeyCode::Escape)),
        )
        .insert_resource(UiDebugOptions {
            enabled: true,
            ..default()
        })
        .run();
}

fn startup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2d);

    let line_breaks = [
        LineBreak::WordBoundary,
        LineBreak::AnyCharacter,
        LineBreak::WordOrCharacter,
        LineBreak::NoWrap,
    ];

    let root_container = commands
        .spawn(Node {
            width: percent(100),
            height: percent(100),
            flex_direction: FlexDirection::Column,
            justify_content: JustifyContent::SpaceEvenly,
            ..default()
        })
        .id();

    let font = asset_server.load("NotoSansJP-Subset-Regular.otf");

    for line_break in &line_breaks {
        commands.spawn((
            Node {
                width: percent(100),
                ..default()
            },
            ChildOf(root_container),
            children![
                Text::new(format!("(Text & LineBreak::{line_break:?}) ")),
                (
                    Text::new("あああああああああああああああ"),
                    TextFont::from(font.clone()),
                    TextLayout::new_with_linebreak(*line_break),
                    TextColor::from(tailwind::CYAN_500),
                ),
                (
                    Text::new("いいいいいいいいいいいいいいい"),
                    TextFont::from(font.clone()),
                    TextLayout::new_with_linebreak(*line_break),
                    TextColor::from(tailwind::BLUE_500),
                ),
                (
                    Text::new("ううううううううううううううう"),
                    TextFont::from(font.clone()),
                    TextLayout::new_with_linebreak(*line_break),
                    TextColor::from(tailwind::INDIGO_500),
                ),
                (
                    Text::new("えええええええええええええええ"),
                    TextFont::from(font.clone()),
                    TextLayout::new_with_linebreak(*line_break),
                    TextColor::from(tailwind::PURPLE_500),
                ),
                (
                    Text::new("おおおおおおおおおおおおおおお"),
                    TextFont::from(font.clone()),
                    TextLayout::new_with_linebreak(*line_break),
                    TextColor::from(tailwind::PINK_500),
                ),
            ],
        ));
    }

    for line_break in &line_breaks {
        commands.spawn((
            Node {
                width: percent(100),
                ..default()
            },
            ChildOf(root_container),
            Text::default(),
            TextLayout::new_with_linebreak(*line_break),
            children![
                TextSpan::new(format!("(TextSpan & LineBreak::{line_break:?}) ")),
                (
                    TextSpan::new("あああああああああああああああ"),
                    TextFont::from(font.clone()),
                    TextColor::from(tailwind::CYAN_500),
                ),
                (
                    TextSpan::new("いいいいいいいいいいいいいいい"),
                    TextFont::from(font.clone()),
                    TextColor::from(tailwind::BLUE_500),
                ),
                (
                    TextSpan::new("ううううううううううううううう"),
                    TextFont::from(font.clone()),
                    TextColor::from(tailwind::INDIGO_500),
                ),
                (
                    TextSpan::new("えええええええええええええええ"),
                    TextFont::from(font.clone()),
                    TextColor::from(tailwind::PURPLE_500),
                ),
                (
                    TextSpan::new("おおおおおおおおおおおおおおお"),
                    TextFont::from(font.clone()),
                    TextColor::from(tailwind::PINK_500),
                ),
            ],
        ));
    }
}

Seconding @viridia here: I really like this work and the broad direction, but want to try and chunk this down as best as we can.

Seeing the central vision here was really compelling and useful, and gives me the confidence to start merging little chunks of this in.

Yeah I guess I've been a bit impatient and getting ahead of myself. The main thing we need I guess is a final decision on whether this TextSpan-less cascading text styles API is the right direction.

OK I'm a bit confused; I didn't notice the removal of TextSpan when I initially read the PR description. Can you elaborate more on how text nodes are intended to be structured?

OK I'm a bit confused; I didn't notice the removal of TextSpan when I initially read the PR description. Can you elaborate more on how text nodes are intended to be structured?

It's not much different structurally, just without TextSpan. All text entities have the Text (or Text2d) component, with a new component TextRoot. TextRoot is added automatically. Whenever a Text entity's parent changes, it queries for if the new parent is another Text entity. If isn't a Text entity, you add the TextRoot component, if it is then TextRoot is removed. Internally the implementation is simpler than with TextSpan. The drawback is that non-root Text entities still require components like ComputedNode and UiTransform that aren't used. There might be ways to work around that though, and it's much nicer to use.

OK I'm a bit confused; I didn't notice the removal of TextSpan when I initially read the PR description. Can you elaborate more on how text nodes are intended to be structured?

It's not much different structurally, just without TextSpan. All text entities have the Text (or Text2d) component. Whenever a Text entity's parent changes, it queries for if the new parent is another Text entity. If isn't a Text entity, you add the TextRoot component, if it is then TextRoot is removed. Internally the implementation is simpler than with TextSpan. The drawback is that non-root Text entities still require components like ComputedNode and UiTransform that aren't used. There might be ways to work around that though, and it's much nicer to use.

This seems controversial.

It seems like Text/Text2d is taking over the job formerly done by TextSpan. Is this just a renaming, or something more? And in what way is it nicer to use?

While TextSpan, as it exists today, may not be perfect, I do think:

• People have mostly gotten used to how it behaves.
• The user friction that it causes is fairly localized, there aren't a lot of wide-ranging knock-on effects.
• It's a compromise between two conflicting needs: "I want a simple string that's a single entity" vs "I want multiple concatenated strings".
• I would place fixing it fairly low on the list of priorities, at least from a user standpoint.

It seems like Text/Text2d is taking over the job formerly done by TextSpan. Is this just a renaming, or something more? And in what way is it nicer to use?

Lets say you are displaying a score using:

commands.spawn((Text::new("Score: "), child![(TextSpan::new("0"), ScoreMarker)]));

that is updated by a system that queries for a TextSpan with ScoreMarker. If later you decide to modify it to:

commands.spawn((Text::new("0"), ScoreMarker, child![TextSpan::new(" points")]));

the updater system also needs to be changed.
With a single Text component for all text entities, the updater would still work.

I mean, I really, really didn't like the text sections as entities changes, but left my objections too late. It's imo more confusing and difficult to use, internally it's much more complicated, and performance is terrible compared to before. It only starts to make sense with cascading text styles.

It seems like Text/Text2d is taking over the job formerly done by TextSpan. Is this just a renaming, or something more? And in what way is it nicer to use?

Oh sorry, actually it wasn't because of usability issues, I completely forgot why I wanted to remove TextSpans, I do understand your objection to making so many changes at once. The reason was that TextSpan's made the relative font sizing and automatic font atlas disposal changes really awkward. bevy_ui handles render targets very differently to bevy_sprite so they need different implementations. But you can't easily and directly identify which type of text hierarchy, Text or Text2d, each TextSpan entity belongs to. Once I got rid of TextSpans so I could just directly query for each type of text entity separately, everything became really simple.

Right now, my reaction to ComputedTextStyles is that it seems like an obvious win, it's the right thing to do - although I am concerned about potential performance impacts of keeping things in sync with their ancestors.

For the changes to TextSpan the win doesn't seem so obvious to me.

As far as "text spans as entities" goes: people have lately been doing some really neat stuff that simply wasn't possible before. And although we still don't have mixed text + non-text (like embedded icons in paragraphs), the goal is to have that ability eventually, and it's hard to see a path for doing that if spans are not entities.

It seems like Text/Text2d is taking over the job formerly done by TextSpan. Is this just a renaming, or something more? And in what way is it nicer to use?

bevy_ui handles render targets very differently to bevy_sprite so they need different implementations.

Is there a way we can embed this distinction inside of ComputedTextStyle? Since it's not meant to be user-facing, it can be extra complex.

It seems like Text/Text2d is taking over the job formerly done by TextSpan. Is this just a renaming, or something more? And in what way is it nicer to use?

bevy_ui handles render targets very differently to bevy_sprite so they need different implementations.

Is there a way we can embed this distinction inside of ComputedTextStyle? Since it's not meant to be user-facing, it can be extra complex.

Initially ComputedTextStyle was more complicated, it had the inherited FontSize value, the render target's scalefactor and size, and the final resolved font size in physical pixels, but I decided it should contain the inherited properties only, I think it was so that change detection worked better and to remove redundancy because the UI already propagates the target info through ComputedUiRenderTargetInfo.