Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(ui): text selection + textarea as the single editing source of truth

yhhe133c004d976
diff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/guides/ui-components.mdx
index 2a05c920a..19cf56848 100644
--- a/docs/astro/src/content/docs/guides/ui-components.mdx
+++ b/docs/astro/src/content/docs/guides/ui-components.mdx
@@ -340,6 +340,13 @@ Click (or Tab to) the field to focus it; **Escape** blurs, **Enter** fires
`submit` on single-line fields. A value longer than the box **clips to it and scrolls
horizontally** so the caret stays in view as you type.
+Editing is backed by a hidden native `<textarea>`, so caret movement and
+**selection come for free**: arrows / Home / End move the caret, **Shift +
+arrows** (or **Ctrl/⌘ + A**) select a range — drawn as a highlight behind the
+text — and the platform clipboard (cut / copy / paste) works. The field mirrors
+that native selection each frame, so it always matches what a native input would
+do.
+
**IME / CJK input** works: the field drives a hidden native `<textarea>`, so a
Chinese/Japanese/Korean composition renders **live in the field** (the preedit
string shows at the caret as you type) and only fires `change` once the
diff --git a/sdk/src/ui/text/text-input-plugin.ts b/sdk/src/ui/text/text-input-plugin.ts
index 6d16a0f26..677b352c8 100644
--- a/sdk/src/ui/text/text-input-plugin.ts
+++ b/sdk/src/ui/text/text-input-plugin.ts
@@ -20,7 +20,7 @@ import { spawnUIEntity } from '../core/compose';
import { px } from '../core/dimension';
import { SdfTextRenderer } from './text-renderer';
import { measureWidth } from './layout';
-import { textFieldDisplay, type TextFieldDisplay } from './text-input-view';
+import { textFieldDisplay, maskedPrefix, fieldSelection, type TextFieldDisplay } from './text-input-view';
import { CURSOR_BLINK_INTERVAL } from '../util/constants';
import { SystemLabel, PluginName } from '../../systemLabels';
import { log } from '../../logger';
@@ -28,6 +28,9 @@ import { log } from '../../logger';
/** Masking bullet for password fields. */
const PASSWORD_CHAR = '●';
+/** Selection-highlight fill (a translucent accent drawn behind the text). */
+const SELECTION_COLOR = { r: 0.30, g: 0.55, b: 1.0, a: 0.35 };
+
export class TextInputPlugin implements Plugin {
name = PluginName.TextInput;
dependencies = [PluginName.Focus];
@@ -61,7 +64,7 @@ export class TextInputPlugin implements Plugin {
// per-entity Canvas2D rasterization / texture upload. `measureRenderer`
// owns an atlas used only to position the caret (measureWidth); its glyph
// advances match the child Text's atlas (same font config).
- const childrenOf = new Map<Entity, { text: Entity; caret: Entity }>();
+ const childrenOf = new Map<Entity, { sel: Entity; text: Entity; caret: Entity }>();
let measureRenderer: SdfTextRenderer | null = null;
const ensureMeasure = (): SdfTextRenderer => {
if (!measureRenderer) measureRenderer = new SdfTextRenderer(module);
@@ -132,24 +135,11 @@ export class TextInputPlugin implements Plugin {
return;
}
- let newPos = ti.cursorPos;
- if (e.key === 'ArrowLeft') {
- newPos = Math.max(0, ti.cursorPos - 1);
- } else if (e.key === 'ArrowRight') {
- newPos = Math.min(ti.value.length, ti.cursorPos + 1);
- } else if (e.key === 'Home') {
- newPos = 0;
- } else if (e.key === 'End') {
- newPos = ti.value.length;
- }
-
- if (newPos !== ti.cursorPos) {
- ti.cursorPos = newPos;
- textarea.selectionStart = newPos;
- textarea.selectionEnd = newPos;
- ti.dirty = true;
- resetCursorBlink();
- }
+ // Caret movement + selection (arrows, Home/End, Shift-select, Ctrl-A)
+ // are handled natively by the focused textarea — the render loop
+ // mirrors its selection each frame — so nothing to intercept here.
+ // A keystroke that moves the caret should re-show it solid.
+ resetCursorBlink();
};
const onBlur = () => {
@@ -179,6 +169,7 @@ export class TextInputPlugin implements Plugin {
textarea.removeEventListener('blur', onBlur);
textarea.remove();
for (const ch of childrenOf.values()) {
+ if (world.valid(ch.sel)) world.despawn(ch.sel);
if (world.valid(ch.text)) world.despawn(ch.text);
if (world.valid(ch.caret)) world.despawn(ch.caret);
}
@@ -293,6 +284,7 @@ export class TextInputPlugin implements Plugin {
// Reap the child entities of removed inputs.
for (const [e, ch] of childrenOf) {
if (!world.valid(e) || !world.has(e, TextInput)) {
+ if (world.valid(ch.sel)) world.despawn(ch.sel);
if (world.valid(ch.text)) world.despawn(ch.text);
if (world.valid(ch.caret)) world.despawn(ch.caret);
childrenOf.delete(e);
@@ -307,23 +299,47 @@ export class TextInputPlugin implements Plugin {
ensureBackground(entity, ti);
const ch = ensureChildren(entity, ti);
- // Fold an active IME composition into the shown text: while
- // composing, the hidden textarea holds the preedit at the caret,
- // so a focused field renders that live instead of the (not-yet-
- // committed) component value — otherwise the composed string is
- // invisible until it commits.
- const editing = composing && focused === entity;
+ // While focused, the hidden textarea is the single source of
+ // truth for editing — caret moves, native Shift/Ctrl-A
+ // selection, and the live IME preedit all land there — so a
+ // focused field renders the textarea's value + selection; a
+ // blurred field renders its committed component value.
+ const editing = focused === entity;
const val = editing ? textarea.value : ti.value;
- const caret = editing ? (textarea.selectionStart ?? val.length) : ti.cursorPos;
- const disp = textFieldDisplay(val, caret, ti.password, ti.placeholder, PASSWORD_CHAR);
+ const len = val.length;
+ const sel = editing
+ ? fieldSelection(
+ textarea.selectionStart ?? len,
+ textarea.selectionEnd ?? len,
+ textarea.selectionDirection === 'backward',
+ len)
+ : { lo: 0, hi: 0, caret: Math.max(0, Math.min(ti.cursorPos, len)), hasRange: false };
+ // Keep the component caret in step so a blur/refocus restores it.
+ if (editing && ti.cursorPos !== sel.caret) ti.cursorPos = sel.caret;
+
+ const disp = textFieldDisplay(val, ti.password, ti.placeholder, PASSWORD_CHAR);
+ const atlas = ensureMeasure().atlas;
+ const measure = (i: number): number =>
+ measureWidth(maskedPrefix(val, i, ti.password, PASSWORD_CHAR), atlas, ti.fontFamily, ti.fontSize, 0);
+ const caretRaw = measure(sel.caret);
// Single-line fields scroll horizontally to keep the caret in view;
// multiline wraps within the box and clips (no h-scroll).
const innerW = Math.max(0, w - 2 * ti.padding);
- const caretRaw = measureWidth(disp.beforeCaret, ensureMeasure().atlas, ti.fontFamily, ti.fontSize, 0);
const scrollX = ti.multiline ? 0 : Math.max(0, caretRaw - innerW);
+ // Selection highlight (single-line only): a quad spanning the
+ // masked range, drawn behind the text. A multiline selection
+ // spans lines and is left to a later pass.
+ const showSel = sel.hasRange && !ti.multiline;
+ const selLo = showSel ? measure(sel.lo) : 0;
+ const selHi = showSel ? measure(sel.hi) : 0;
+ syncSelChild(ch.sel, ti, h, showSel, ti.padding + selLo - scrollX, selHi - selLo);
+
syncTextChild(ch.text, ti, disp, innerW, scrollX);
- syncCaretChild(ch.caret, ti, h, ti.padding + caretRaw - scrollX);
+ // The blinking caret hides while a range is selected (the
+ // highlight stands in), matching a native field.
+ syncCaretChild(ch.caret, ti, h, ti.padding + caretRaw - scrollX,
+ ti.focused && cursorVisible && !sel.hasRange);
}
},
{ name: 'TextInputRenderSystem' }
@@ -356,10 +372,16 @@ export class TextInputPlugin implements Plugin {
}
}
- function ensureChildren(entity: Entity, ti: TextInputData): { text: Entity; caret: Entity } {
+ function ensureChildren(entity: Entity, ti: TextInputData): { sel: Entity; text: Entity; caret: Entity } {
const existing = childrenOf.get(entity);
- if (existing && world.valid(existing.text) && world.valid(existing.caret)) return existing;
+ if (existing && world.valid(existing.sel) && world.valid(existing.text) && world.valid(existing.caret)) return existing;
const pad = px(ti.padding);
+ // Spawn order is the tree-DFS render order: highlight (behind) < text < caret.
+ const sel = spawnUIEntity({
+ world, parent: entity,
+ node: { position: UIPositionType.Absolute, width: px(0), height: px(ti.fontSize), insetLeft: pad, insetTop: px(0) },
+ visual: { visualType: UIVisualType.SolidColor, color: { ...SELECTION_COLOR }, enabled: false },
+ });
const text = spawnUIEntity({
world, parent: entity,
// Left-anchored by insetLeft (scrolled by the render loop) with an
@@ -377,11 +399,30 @@ export class TextInputPlugin implements Plugin {
node: { position: UIPositionType.Absolute, width: px(2), height: px(ti.fontSize), insetLeft: px(ti.padding), insetTop: px(0) },
visual: { visualType: UIVisualType.SolidColor, color: ti.color, enabled: false },
});
- const ch = { text, caret };
+ const ch = { sel, text, caret };
childrenOf.set(entity, ch);
return ch;
}
+ function syncSelChild(selEntity: Entity, ti: TextInputData, boxH: number, show: boolean, x: number, width: number): void {
+ const w = Math.max(0, width);
+ const top = Math.max(0, (boxH - ti.fontSize) / 2);
+ const node = world.get(selEntity, UINode) as UINodeData;
+ if (node.insetLeft.value !== x || node.insetTop.value !== top || node.width.value !== w || node.height.value !== ti.fontSize) {
+ node.insetLeft = px(x);
+ node.insetTop = px(top);
+ node.width = px(w);
+ node.height = px(ti.fontSize);
+ world.insert(selEntity, UINode, node);
+ }
+ const v = world.get(selEntity, UIVisual) as UIVisualData;
+ const on = show && w > 0;
+ if (v.enabled !== on) {
+ v.enabled = on;
+ world.insert(selEntity, UIVisual, v);
+ }
+ }
+
function syncTextChild(textEntity: Entity, ti: TextInputData, disp: TextFieldDisplay, innerW: number, scrollX: number): void {
const t = world.get(textEntity, Text) as TextData;
const show = disp.text;
@@ -408,7 +449,7 @@ export class TextInputPlugin implements Plugin {
}
}
- function syncCaretChild(caretEntity: Entity, ti: TextInputData, boxH: number, caretX: number): void {
+ function syncCaretChild(caretEntity: Entity, ti: TextInputData, boxH: number, caretX: number, show: boolean): void {
const caretTop = Math.max(0, (boxH - ti.fontSize) / 2);
const node = world.get(caretEntity, UINode) as UINodeData;
if (node.insetLeft.value !== caretX || node.insetTop.value !== caretTop || node.height.value !== ti.fontSize) {
@@ -418,7 +459,6 @@ export class TextInputPlugin implements Plugin {
world.insert(caretEntity, UINode, node);
}
const v = world.get(caretEntity, UIVisual) as UIVisualData;
- const show = ti.focused && cursorVisible;
if (v.enabled !== show || v.color.r !== ti.color.r || v.color.g !== ti.color.g || v.color.b !== ti.color.b) {
v.enabled = show;
v.color = { ...ti.color };
diff --git a/sdk/src/ui/text/text-input-view.ts b/sdk/src/ui/text/text-input-view.ts
index 235e38750..0036d97b8 100644
--- a/sdk/src/ui/text/text-input-view.ts
+++ b/sdk/src/ui/text/text-input-view.ts
@@ -2,13 +2,14 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file ui/text/text-input-view.ts
- * @brief Pure derivation of *what a text field shows* — the glyph string,
- * whether it is the placeholder, and the (already-masked) substring
- * before the caret whose width positions the caret. Kept pure (no ECS,
- * DOM or engine) so the placeholder / password / caret-offset rules are
- * unit-testable; the input plugin feeds it the effective value + caret
- * (which, while an IME composition is active, come straight from the
- * hidden textarea so the preedit renders live).
+ * @brief Pure derivation of *what a text field shows* — the glyph string, the
+ * masked substring before an index (whose width places the caret /
+ * selection edges), and the normalized selection range. Kept pure (no
+ * ECS, DOM or engine) so the placeholder / password / selection rules
+ * are unit-testable; the input plugin feeds it the effective value +
+ * selection, which — while a field is focused — come straight from the
+ * hidden textarea (the single source of truth for editing: caret moves,
+ * IME preedit, and native shift/Ctrl-A selection all land there).
*/
export interface TextFieldDisplay {
@@ -17,31 +18,53 @@ export interface TextFieldDisplay {
text: string;
/** True when {@link text} is the placeholder (drives placeholder color). */
isPlaceholder: boolean;
- /** The substring up to the caret — already password-masked — whose measured
- * width places the caret and drives horizontal scroll. Empty for the
- * placeholder (an empty field parks the caret at the left edge). */
- beforeCaret: string;
}
-/**
- * Resolve the shown text + caret prefix for a field with `value` and caret index
- * `caret`. Empty ⇒ the placeholder (caret at the origin); password ⇒ every glyph
- * is `bullet`, including the caret prefix, so the caret still lands between
- * masked characters. Pure.
- */
+/** The shown glyphs for a field with `value`. Empty ⇒ the placeholder; password
+ * ⇒ one bullet per character. Pure. */
export function textFieldDisplay(
value: string,
- caret: number,
password: boolean,
placeholder: string,
bullet: string,
): TextFieldDisplay {
- if (value.length === 0) {
- return { text: placeholder, isPlaceholder: true, beforeCaret: '' };
- }
- const clamped = Math.max(0, Math.min(caret, value.length));
- if (password) {
- return { text: bullet.repeat(value.length), isPlaceholder: false, beforeCaret: bullet.repeat(clamped) };
- }
- return { text: value, isPlaceholder: false, beforeCaret: value.slice(0, clamped) };
+ if (value.length === 0) return { text: placeholder, isPlaceholder: true };
+ return { text: password ? bullet.repeat(value.length) : value, isPlaceholder: false };
+}
+
+/**
+ * The (already password-masked) substring of `value` up to char `index`, whose
+ * measured width positions the caret / a selection edge. `index` is clamped to
+ * `[0, value.length]`; a password masks the prefix bullet-for-bullet so an edge
+ * still lands between masked characters. Pure.
+ */
+export function maskedPrefix(value: string, index: number, password: boolean, bullet: string): string {
+ const i = Math.max(0, Math.min(index, value.length));
+ return password ? bullet.repeat(i) : value.slice(0, i);
+}
+
+export interface FieldSelection {
+ /** Selection start (the lower index). */
+ lo: number;
+ /** Selection end (the higher index). */
+ hi: number;
+ /** The caret — the moving/focus end (`lo` for a backward selection, else `hi`). */
+ caret: number;
+ /** True when `lo < hi`, i.e. there is a range to highlight. */
+ hasRange: boolean;
+}
+
+/**
+ * Normalize a textarea selection (`selectionStart`, `selectionEnd`, direction)
+ * into an ordered range + caret index, all clamped to `[0, len]`. The caret sits
+ * at the focus end: the start for a backward (shift-left / shift-up) selection,
+ * the end otherwise — matching where a native input parks the blinking caret.
+ * Pure.
+ */
+export function fieldSelection(selStart: number, selEnd: number, backward: boolean, len: number): FieldSelection {
+ const a = Math.max(0, Math.min(selStart, len));
+ const b = Math.max(0, Math.min(selEnd, len));
+ const lo = Math.min(a, b);
+ const hi = Math.max(a, b);
+ return { lo, hi, caret: backward ? lo : hi, hasRange: hi > lo };
}
diff --git a/sdk/tests/ui-text-input-view.test.ts b/sdk/tests/ui-text-input-view.test.ts
index 6cb09fb6b..e558c2ebc 100644
--- a/sdk/tests/ui-text-input-view.test.ts
+++ b/sdk/tests/ui-text-input-view.test.ts
@@ -1,55 +1,80 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file Pure display derivation for the TextInput plugin: placeholder / password
- * masking and the caret-prefix that positions the caret. The plugin feeds
- * this the *effective* value + caret — which, mid-IME-composition, are the
- * hidden textarea's live preedit — so covering the branches here covers
- * the preedit render path too.
+ * @file Pure display + selection derivation for the TextInput plugin: placeholder
+ * / password masking, the masked prefix that positions the caret and
+ * selection edges, and the normalized selection range. The plugin feeds
+ * these the *effective* value + selection — which, while a field is
+ * focused, are the hidden textarea's live state (caret, IME preedit,
+ * native shift/Ctrl-A selection) — so covering the branches here covers
+ * the caret / preedit / selection render paths.
*/
import { describe, it, expect } from 'vitest';
-import { textFieldDisplay } from '../src/ui/text/text-input-view';
+import { textFieldDisplay, maskedPrefix, fieldSelection } from '../src/ui/text/text-input-view';
const BULLET = '●';
describe('textFieldDisplay', () => {
- it('shows the placeholder for an empty value (caret parks at the origin)', () => {
- expect(textFieldDisplay('', 0, false, 'Your name', BULLET)).toEqual({
- text: 'Your name', isPlaceholder: true, beforeCaret: '',
- });
+ it('shows the placeholder for an empty value', () => {
+ expect(textFieldDisplay('', false, 'Your name', BULLET)).toEqual({ text: 'Your name', isPlaceholder: true });
});
it('an empty password field still shows the placeholder (empty wins over masking)', () => {
- expect(textFieldDisplay('', 0, true, 'Password', BULLET)).toEqual({
- text: 'Password', isPlaceholder: true, beforeCaret: '',
- });
+ expect(textFieldDisplay('', true, 'Password', BULLET)).toEqual({ text: 'Password', isPlaceholder: true });
});
- it('renders the value verbatim with the caret prefix up to the caret index', () => {
- expect(textFieldDisplay('hello', 3, false, 'ph', BULLET)).toEqual({
- text: 'hello', isPlaceholder: false, beforeCaret: 'hel',
- });
+ it('renders the value verbatim when not a password', () => {
+ expect(textFieldDisplay('hello 你好', false, 'ph', BULLET)).toEqual({ text: 'hello 你好', isPlaceholder: false });
});
- it('clamps a caret past the end so the prefix is the whole value', () => {
- expect(textFieldDisplay('hi', 99, false, 'ph', BULLET).beforeCaret).toBe('hi');
+ it('masks the whole value bullet-for-bullet for a password', () => {
+ expect(textFieldDisplay('secret', true, 'ph', BULLET)).toEqual({ text: BULLET.repeat(6), isPlaceholder: false });
+ });
+});
+
+describe('maskedPrefix', () => {
+ it('is the value sliced to the index', () => {
+ expect(maskedPrefix('hello', 3, false, BULLET)).toBe('hel');
+ });
+
+ it('clamps past the end and below zero', () => {
+ expect(maskedPrefix('hi', 99, false, BULLET)).toBe('hi');
+ expect(maskedPrefix('hi', -5, false, BULLET)).toBe('');
+ });
+
+ it('masks the prefix bullet-for-bullet for a password', () => {
+ expect(maskedPrefix('secret', 4, true, BULLET)).toBe(BULLET.repeat(4));
+ });
+
+ it('treats a live IME preedit as ordinary text (plugin passes textarea value)', () => {
+ expect(maskedPrefix('ab你好', 4, false, BULLET)).toBe('ab你好');
+ });
+});
+
+describe('fieldSelection', () => {
+ it('a collapsed selection has no range; caret at the index', () => {
+ expect(fieldSelection(3, 3, false, 10)).toEqual({ lo: 3, hi: 3, caret: 3, hasRange: false });
+ });
+
+ it('a forward selection parks the caret at the end', () => {
+ expect(fieldSelection(2, 6, false, 10)).toEqual({ lo: 2, hi: 6, caret: 6, hasRange: true });
+ });
+
+ it('a backward selection parks the caret at the start', () => {
+ expect(fieldSelection(6, 2, true, 10)).toEqual({ lo: 2, hi: 6, caret: 2, hasRange: true });
});
- it('clamps a negative caret to the origin', () => {
- expect(textFieldDisplay('hi', -5, false, 'ph', BULLET).beforeCaret).toBe('');
+ it('orders lo/hi regardless of argument order', () => {
+ const a = fieldSelection(6, 2, false, 10);
+ expect(a.lo).toBe(2);
+ expect(a.hi).toBe(6);
});
- it('masks a password value AND its caret prefix bullet-for-bullet', () => {
- const d = textFieldDisplay('secret', 4, true, 'ph', BULLET);
- expect(d.text).toBe(BULLET.repeat(6));
- expect(d.beforeCaret).toBe(BULLET.repeat(4));
- expect(d.isPlaceholder).toBe(false);
+ it('clamps both ends into [0, len]', () => {
+ expect(fieldSelection(-3, 99, false, 5)).toEqual({ lo: 0, hi: 5, caret: 5, hasRange: true });
});
- it('treats a live IME preedit as ordinary text (the plugin passes the composed value + caret)', () => {
- // Mid-composition the plugin passes textarea.value ("ab你好") + selectionStart (4).
- expect(textFieldDisplay('ab你好', 4, false, 'ph', BULLET)).toEqual({
- text: 'ab你好', isPlaceholder: false, beforeCaret: 'ab你好',
- });
+ it('a full select-all spans the whole value (Ctrl-A)', () => {
+ expect(fieldSelection(0, 8, false, 8)).toEqual({ lo: 0, hi: 8, caret: 8, hasRange: true });
});
});