Password-style character masking for editable text inputs

[Cyannide]

Objective

Password fields. EditableText's own docs list "Password-style character masking" as planned-but-unimplemented and invite contribution — this implements it.

Solution

Where the value lives: the mask is presentation; EditableText::value() is the contract. The entered text sits in a shadow slot on EditableText while a mask is present, so value() always returns the entered text and reading it requires no knowledge of the mask. Removing EditableText removes the value with it. The shadow slot is a pub field of an opaque ShadowValue type, so struct-literal construction (..default()) keeps working while the contents stay managed by the mask. The example's submit handler shows the consumer shape — one query, one call, no mask in sight:

// `EditableText::value()` always returns the entered text; a
// `CharacterMask` affects display only.
text_output.0 = format!("{:}: {:}", name, text_input.value());

Alternative considered: keeping the value on CharacterMask and exposing an honest read through a QueryData wrapper (&EditableText + Option<&CharacterMask>). Rejected because the plain Query<&EditableText> + .value() path — the obvious call — would keep returning mask glyphs, leaving the honest API as opt-in knowledge.

Cow<str>: value() previously returned parley's SplitString, which has no public constructor and can't carry the shadow. Cow is borrowed in the common case, owned only during IME composition, and comparisons/.to_string() at existing call sites work unchanged (migration guide included).

Why a twin representation: caret position, selection geometry, and click-to-position all come from the editor's own parley layout — what is drawn must be what is laid out, or mask glyphs and real characters (different advances) desync every caret coordinate. One glyph per character preserves index parity in both char and byte
space, so cursor/selection operations pass through untouched and content operations mirror by char range.

• Interception at apply_pending_edits (the documented entry point); TextEdit::apply is unchanged and documented as bypassing the mask. Paste routes through poll_and_apply_paste — the one place clipboard text is visible, and the reason this lives in bevy_text.
• Reconcile invariant, enforced each frame: the editor must hold exactly the mask string for the real value; any deviation (spawn ordering, clear(), external set_text) is adopted and re-concealed. This makes the component-hook lifecycle safe in any insertion order — and the hooks give show/hide password for free: add conceals, remove reveals.
• Password-field norms: Copy no-ops, Cut is a selection-gated delete with the clipboard untouched. IME stays enabled — on mobile the soft keyboard delivers text as IME commits, which route through the masked insert — but composition preedit is suppressed (it renders in-buffer and would display the raw text), so IME entry is commit-per-key, matching platform secure-entry behavior. EditableTextFilter/max_characters apply to the real characters.
• Word ops treat the whole value as one word, explicitly (mask glyphs are punctuation under UAX #29, so driver word segmentation is unreliable over them — and word ops shouldn't reflect the real text's word structure anyway). Matches browsers.
• Default glyph is * — Bevy's embedded default font is an ASCII subset and • renders as tofu out of the box; one line opts into • with a real font.

Composes with #25110's Placeholder with no integration code:value() is the entered text, so a hint keyed to value() emptiness just works — a hinted password field is two components on one entity. (Both PRs touch the text_input example; whichever lands second takes a one-line conflict.)

Migration

EditableText::value returns Cow<'_, str> instead of SplitString (see migration guide). EditableText::apply_pending_edits takes a new final parameter mask: Option<&CharacterMask> — pass None for existing behavior. apply_text_edits' query changed accordingly.

Follow-ups (declared, not solved)

• One glyph per char, not per grapheme cluster.
• Adding U+2022 to the embedded default-font subset would allow • as the default glyph (asset regeneration).
• Accessibility: masked fields should expose a password role and never the real value.
• ImePurpose is not exposed by bevy_window; until it is, mobile masked fields receive the standard soft keyboard rather than the platform's secure/password keyboard (predictions active). Exposing it and setting ImePurpose::Password while a masked field has focus is the completing piece.

Testing

• Zero new systems — everything lives in the existing apply path and component hooks; ambiguity_detection is unaffected.
• cargo test -p bevy_text — 17 new headless tests against real parley layout: conceal-on-add, per-op mirroring, type-over-selection, selection-gated Cut, clipboard untouched under Copy/Cut, filter-on-real-chars, explicit word-op semantics, reveal-on-remove, reconcile after external set_text, the IME-commit (mobile soft keyboard) path, and the value() contract set: honest-while-masked, shadow-presence-iff-masked, multibyte conceal/reveal round-trip, and clear().
• cargo run --example text_input — right input masked; the submit handler reads EditableText::value() with no mask in the query.

Showcase