Continued from the Lorum Ipsum discord working group. This is a proposal for a new text API using required components and replacing Vec<TextSection> with a hierarchy of text entities.

See cart's comment for the current proposed design. Most of the discussion below remains relevant.

Objectives

• Improve the ergonomics of spawning basic one-line text.
• Break Text into separate components to take advantage of the new required components API. Deprecate existing text bundles.
• Facilitate text picking, including picking for regions of text that contain multiple sub-spans (e.g. a hyperlink that is partially bolded).
• Open a path to building text blocks that contain non-text elements (e.g. images, UI sub-trees, etc.) that are controlled by the text layout algorithm.
• Increase flexibility of constructing and managing complex text blocks. For example, bevy_mod_bbcode uses a custom multi-entity solution for text.

Background

Right now we use cosmic-text to control text layout. We feed cosmic-text an iterator over text sections, and it constructs a Buffer that knows how to organize the text contents. The buffer is then used to construct a TextLayoutInfo which has all the glyphs and their positions for rendering text in Bevy (both UI and 2d text).

When doing UI layout with taffy, a node with text on it is treated as having an opaque 'content block' (see the ContentSize component). Whenever a node has a content block, taffy asks the block for its computed size using different x/y bounds as part of the taffy layout algorithm (CSS grid/flexbox). For a text node, you compute that size by using the text's Buffer to recompute text layout.

Summary

Currently we store text sections as Vec<TextSection> in a single Text component that has all text layout and style information.

In this proposal, we break Text into a tree of text nodes. At the root of the tree are the following components:

• TextLayout: controls wrapping/line breaking
• TextBlock: contains the cosmic text buffer and caches the list of text section entities
• TextSpan: indicates the node should be tracked as part of text tree collection

Any node of the tree underneath a TextBlock (including the entity with TextBlock) can include the following components (if a child doesn't have TextSpan then we don't traverse into that child - only contiguous TextSpan nodes are considered):

• Text: contains a string
• TextStyle: font, font size, color
• TextSpan: indicates the node should be tracked as part of text tree collection

To delineate between UI and 2d we have:

• TextNode: marker component for UI text, requires components for setting up a UI node
• Text2d: marker component for 2d text, requires components for setting up a 2d node

The final bit of magic to make this ergonomic is using TextNode::new() and Text2d::new() to produce bundles instead of making just the components. This introduces a small learning curve but makes everything fit together nicely.

API

#[derive(Component)]
pub struct TextSpan;

#[derive(Component)]
pub struct TextLayout
{
    pub justify: JustifyText,
    pub break: BreakLineOn,
}

#[derive(Component)]
#[requires(TextStyle, TextSpan)]
pub struct Text(String);

impl Text
{
    pub fn new(text: impl Into<String>) -> Self
    {
        Self(text.into())
    }
}

#[derive(Component)]
pub struct TextStyle
{
    pub font: Handle<Font>,
    pub size: f32,
    pub color: Color,
}

pub struct TextEntity
{
    entity: Entity,
    /// Records the hierarchy depth of the entity within a `TextBlock`.
    depth: usize,
}

#[derive(Component)]
#[requires(TextLayoutInfo, TextLayout, TextSpan)]
pub struct TextBlock
{
    /// Buffer is private because buffer contents are always refreshed from ecs state when writing glyphs to
    /// `TextLayoutInfo`. If you want to control the buffer contents manually or use the `cosmic-text`
    /// editor, then you should manually implement the conversion to `TextLayoutInfo`.
    pub(crate) buffer: CosmicBuffer,
    pub(crate) entities: SmallVec<[TextEntity; 1]>,
    pub(crate) needs_recompute: bool,
}

impl TextBlock
{
    pub fn entities(&self) -> &[TextEntity]
    {
        &self.entities
    }
}

/// Renamed from `TextFlags`.
#[derive(Component)]
pub struct TextNodeFlags
{
    needs_measure_fn: bool
}

#[derive(Component)]
#[requires(TextBlock, TextNodeFlags, ContentSize, Node)]
pub struct TextNode;

impl TextNode
{
    // Returns a bundle for setting up UI text.
    pub fn new(text: impl Into<String>) -> (Self, Text)
    {
        (Self, Text::new(text))
    }
}

#[derive(Component)]
#[requires(TextBlock, TextBounds, Spatial2d)]
pub struct Text2d;

impl Text2d
{
  // Returns a bundle for setting up 2d text.
  pub fn new(text: impl Into<String>) -> (Self, Text)
  {
    (Self, Text::new(text))
  }
}

// 1.a Simple UI text node.
//
// Node, Buffer ["Hello"]
commands.spawn(TextNode::new("Hello"));

// 1.b Simple 2d text node.
//
// Buffer ["Hello"]
commands.spawn(Text2d::new("Hello"));

// 2.a UI multi-span text.
//
// Node, Buffer ["What a ", "wonderful ", "world"]
commands
  .spawn(TextNode::new("What a "))
  .with_children(|parent| {
    parent.spawn(Text::new("wonderful "));
    parent.spawn(Text::new("world"));
  });

// 2.b 2d multi-span text.
//
// Buffer ["What a ", "wonderful ", "world"]
commands
  .spawn(Text2d::new("What a "))
  .with_children(|parent| {
    parent.spawn(Text::new("wonderful "));
    parent.spawn(Text::new("world"));
  });

// 2.c UI multi-span text expanded from markup "[b]Hello, [i]World[\i][\b]"
//
// Node, Buffer ["Hello, ", "World"]
commands
  .spawn(TextNode)
  .with_children(|parent| {
    parent.spawn((
        Text::new("Hello, "),
        TextStyle::from_font(fonts.get(FontFamily::new("Fira Sans").bold()))
    ));
    parent
        .spawn(TextSpan)
        .with_children(|parent| {
          parent.spawn((
              Text::new("World"),
              TextStyle::from_font(fonts.get(FontFamily::new("Fira Sans").bold().italic()))
          ));
  });

// 3. Multi-node UI
//
// Node
// - Node, Buffer ["Hello"]
// - Node, Buffer ["World"]
commands
  .spawn(Node)
  .with_children(|parent| {
    parent.spawn(TextNode::new("Hello"));
    parent.spawn(TextNode::new("World"));
  });

// 4. (Invalid, no TextBlock. Warning emitted.)
commands
  .spawn(Text::new("Hello"))
  .with_child(|parent| {
    parent.spawn(Text::new("World"));
  });

Implementation details

• When Text or TextStyle changes on entity, iterate upwards to find TextBlock then set its needs_update flag. This flag is used by text2d and UI text to decide if the buffer should be rebuilt.
• In TextPipeline::update_buffer, instead of taking in a &[TextSection], take in impl Iterator<Item = (&Text, &TextStyle)>. This iterator should internally traverse the entity hierarchy and rebuild the TextBlock::entities vector in-line. This is an effective way to keep the entities vector accurate without any extra hierarchy traversal/management code.
• For text picking, use the text section already stored in TextLayoutInfo. The section index can be used with TextBlock::entities to look up the correct entity for picking events.
• Add an OnRemove observer for Text that sets the TextBlock::needs_update flag on the nearest TextBlock ancestor.
• In this proposal CosmicBuffer is embedded in TextBlock and should not be edited by users since any edits will be overwritten by the internal systems that filter for TextBlock. However, buffer construction, ContentSize measurements, and TextLayoutInfo assembly will be opt-in via the TextBlock, TextNode, and Text2d components. A user can instead manually construct and update ContentSize and TextLayoutInfo by adding a custom component/code for managing cosmic-text buffers, and simply not including those opt-in components. The TextPipeline should be refactored a bit to facilitate this (split up TextPipeline::queue_text so you can construct TextLayoutInfo without needing bevy-specific text sections/blocks).
  • UI: you'd need Node, ContentSize, TextLayoutInfo, CustomCosmicBuffer + code to manage these
  • 2d: you'd need Spatial2d, TextLayoutInfo, CustomCosmicBuffer + code to manage these

Open questions

• On taffy, Visibility, and Transform traversal, we want to ignore the child Text entities. One solution would be a SkipChildren marker component required by TextBlock. Or perhaps SkipChildren<T> and then require SkipChildren<Node>, SkipChildren<Visibility>, SkipChildren<Transform>.

Alternatives

• @viridia has proposed adding a Display::Flow setting to the UI Style which would have behavior similar to TextBlock.
• @cart has proposed only having a Text component, and auto-detecting the root node of text blocks (possibly with Display::Flow playing a part).

Problems with the alternatives:

• Auto-detection of block roots means all uses of Text need to be aware of each other for proper auto-setup (e.g. 2d and UI).
• The behavior of Display::Flow is also desirable for 2d.
• The behavior we need is satisfied by required components so it would be weird to add special magic to get that for text.
• We don't always want Text on all the nodes of a text block. This isn't a hard blocker to the alternatives since they could use TextSpan like I do in this proposal.
• Display::Flow would increase the complexity of Style, which is already quite overly-complected.