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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdxindex 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 scrollshorizontally** 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 aChinese/Japanese/Korean composition renders **live in the field** (the preeditstring shows at the caret as you type) and only fires `change` once thediff --git a/sdk/src/ui/text/text-input-plugin.ts b/sdk/src/ui/text/text-input-plugin.tsindex 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.tsindex 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.tsindex 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 });});});