Text input support - Tracking

[Zeophlite]

History:

@ickshonpe originally put together #20326 , which included text input, widgets, and lots of features.

From there, they split off just the bevy_text::input module - #20336

Current

I adopted that, without undo/redo, which was a blocker - #20763 - the intention was to get this over the line for 0.17. I did further work to better document, split up the module, removed clipboard, filtering, masking, etc.

Future PR:

• upstream undo/redo - Temporarily upstream undo_2 #20489
• add filtering / masking - revert f0a8596
• widgets - Comprehensive text input support (without undo) #20826 (TODO: split out clipboard from here)
• add clipboard - from above PR

Other commentary:

• Migrate any changes relative to the text input code in this PR.
• Rename the text input widgets to TextInput and TextArea to be consistent with web nomenclature.
• Move the widgets into the same crate as the other core widgets (presumably after the renaming of that crate:
  Consider renaming bevy_core_widgets to bevy_headless_widgets #20664).
• an additional follow-on PR could implement a feathers-branded text input widget
• make Cursor to be a related entity, rather than defined by components and resources. This will make it easier for someone to implement a code editor with multiple cursors for example; maybe that's out of scope but I think it wouldn't add too much complexity.
• ideal design would be to just add an Editor component to some existing top level Text entity
• Text is always joined via a "\n" but for correctness you might use the BufferLine's LineEnding (e.g. on windows it might be \r\n if coming from a file or a paste), but I'm not 100% sure on this.
• consider get_text_into(target_buffer, ..) just to allow a user to avoid allocation/reallocation of a new string, and to reuse an existing allocation, particularly if fetched for temporary reasons. e.g. this could be used for the password mask.
• PasswordMask implementation having two editors with two buffers does feel odd to me. you can basically just replace the hidden editor's Cursor and Selection with the PasswordMask's Cursor and Selection, then you don't need to worry about weird pixel-level mismatches (the recommendation about fixed width fonts won't be relevant). It may be necessary to separate text change from text selection actions to make this work.
• For text selections, get the selection and cursor of the mask editor, apply that selection and cursor directly to the hidden editor. i.e. text selections only directly affect the mask editor, and the state of the hidden editor is derived.
• For text changes, apply the TextEdits to the hidden editor, get the text from the hidden editor and replace each char with the mask char, and finally replace the text of the mask editor. i.e. text changes only directly affect the hidden editor, and the state of the mask editor is derived.
• The PasswordMask I think is very similar conceptually to a syntax-highlighted code editor, a visual representation the user can interact with, and an underlying representation the user's edits actually affect, so there may be a more general solution here. Perhaps related entities?
• Should ScrollingLayoutRunIter be upstreamed if it's a bug with cosmic-text?
• I've played a bit with this PR and how to use it, and I think it introduces too many things at once, and some that doesn't interact well together.
• I would prefer a simpler PR that would introduce a component that holds a cosmic buffer, and how to interact with it. Making it smaller would also improve the code organisation.

[alice-i-cecile]

I spent today taking a crack at this, working on a simpler PR and trying to understand the problem space. I said the following on Discord.

I spent today experimenting with text input, focusing on your review feedback from 20763:

I would prefer a simpler PR that would introduce a component that holds a cosmic buffer, and how to interact with it. Making it smaller would also improve the code organisation.

I also agreed that a more minimal implementation would be much nicer as a place to start! For the first PR, I'm aiming for:

• text that you can enter into a box
• cursor navigation
• backspace support
• placeholder text
• an example to show how it works

Absolutely nothing else: no styling, no feathers, no validation, no clipboard, no undo... Those can all be done as separate PRs, giving them the review attention they need without blocking orthogonal progress.

Draft branch here. I'm targeting a flexible multi-entity design, with distinct ⁨⁨TextEntry⁩⁩ and ⁨⁨TextEntryField⁩⁩ entities + recursive search to allow you to organize them in the hierarchy however you like.

As I explored further, I'm a bit skeptical (but not opposed to) the notion of storing a raw cosmic_text::Buffer component as the underlying primitive. Editor seems like it might offer a fair bit of additional functionality out of the box, working to handle things like cursors and various text input for us. This was the approach taken in the previous PRs.

That said, it's also very poorly documented, and wants a ⁨⁨BufferRef⁩⁩, with an associated lifetime. That is... not great for how Bevy wants to work: ideally the ⁨⁨Buffer⁩⁩ that it is referencing is the one held in our existing ComputedTextBlock, required by ⁨⁨Text⁩⁩. After more digging, it looks like we can make a ⁨⁨BufferRef::Owned⁩⁩ to avoid lifetime problems without creating memory leaks. I think the final cost there is mostly going to be in code duplication for actually updating / displaying the special text input text.

I'm also not sure if things like gamepad or mobile support are going to be viable when using the ⁨⁨Editor⁩⁩ helper: ⁨⁨cosmic_text⁩⁩ seems to be intercepting user input as well, bypassing ⁨⁨bevy_input⁩⁩ / ⁨⁨bevy_winit⁩⁩. Do not love that.

If we decide to go with the raw ⁨⁨Buffer⁩⁩ approach, I think we should reuse the existing buffer from ⁨⁨Text⁩⁩, and ensure that the values we need don't get clobbered during TextPipeline::update_buffer, then track things like cursor state in our own⁨⁨TextEntryField⁩⁩ which is used to set TextLayoutInfo and drive the displayed text buffer as needed.

[alice-i-cecile]

Consolidating into #23014.