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
// SPDX-License-Identifier: Apache-2.0
// 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, 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).
*/
import type { LocalizationAPI } from '../../i18n/Localization';
export interface TextFieldDisplay {
/** The glyph string to render: the value, the placeholder when empty, or a
* run of bullets when the field is a password. */
text: string;
/** True when {@link text} is the placeholder (drives placeholder color). */
isPlaceholder: boolean;
}
/** The shown glyphs for a field with `value`. Empty ⇒ the placeholder; password
* ⇒ one bullet per character. Pure. */
export function textFieldDisplay(
value: string,
password: boolean,
placeholder: string,
bullet: string,
placeholderI18nKey?: string,
localization?: Pick<LocalizationAPI, 't'>,
): TextFieldDisplay {
if (value.length === 0) return {
text: placeholderI18nKey && localization ? localization.t(placeholderI18nKey) : 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 };
}
/**
* Choose the closest measured UTF-16 prefix to text-space offset `x`.
* Supplying the original value excludes surrogate-pair interiors, including
* when the measured prefixes belong to password bullets. Empty fields return 0.
*/
export function nearestCaretIndex(prefixWidths: readonly number[], x: number, value?: string): number {
let best = 0;
let bestDist = Infinity;
for (let i = 0; i < prefixWidths.length; i++) {
if (value && i > 0 && (value.codePointAt(i - 1) ?? 0) > 0xffff) continue;
const d = Math.abs(prefixWidths[i] - x);
if (d < bestDist) {
bestDist = d;
best = i;
}
}
return best;
}
/** Convert an on-screen point — device px, GL bottom-up, the space the UI
* hit-test / camera use — into CSS pixels (top-down) for positioning the hidden
* IME `<textarea>` so the OS candidate window anchors at the caret instead of
* the screen corner. Inverse of the hit-test's `mouseX*dpr`, `screenH −
* mouseY*dpr`. Pure. */
export function imeAnchorCss(screenX: number, screenY: number, screenH: number, dpr: number): { left: number; top: number } {
const d = dpr > 0 ? dpr : 1;
return { left: screenX / d, top: (screenH - screenY) / d };
}
/** A visual line of a multiline value: its text (no trailing `\n`) and the
* index in the full value where it starts. */
export interface VisualLine {
text: string;
start: number;
}
/** Split a value into its hard-broken (`\n`) visual lines with their start
* indices. Always at least one line. Pure. (Soft word-wrap is not modeled —
* the multiline field breaks on explicit newlines.) */
export function splitLines(value: string): VisualLine[] {
const lines: VisualLine[] = [];
let start = 0;
for (;;) {
const nl = value.indexOf('\n', start);
if (nl < 0) { lines.push({ text: value.slice(start), start }); break; }
lines.push({ text: value.slice(start, nl), start });
start = nl + 1;
}
return lines;
}
/** Locate a caret index as a (line, column) in the `\n`-broken value. `column`
* is the offset within the line's text; `lineStart` is the line's start index
* so `value.slice(lineStart, caret)` is the prefix whose width places the
* caret on that line. Pure. */
export function caretLineCol(value: string, caret: number): { line: number; col: number; lineStart: number } {
const c = Math.max(0, Math.min(caret, value.length));
const lines = splitLines(value);
for (let i = 0; i < lines.length; i++) {
const end = lines[i].start + lines[i].text.length;
if (c <= end) return { line: i, col: c - lines[i].start, lineStart: lines[i].start };
}
const last = lines[lines.length - 1];
return { line: lines.length - 1, col: last.text.length, lineStart: last.start };
}
/** Per-line column span of a selection `[lo, hi]` over the `\n`-broken value:
* one entry per visual line that has selected text, giving the column range to
* highlight on that line. Used to draw one highlight rect per line. Pure. */
export function lineSelections(value: string, lo: number, hi: number): Array<{ line: number; from: number; to: number }> {
const a = Math.max(0, Math.min(Math.min(lo, hi), value.length));
const b = Math.max(0, Math.min(Math.max(lo, hi), value.length));
const out: Array<{ line: number; from: number; to: number }> = [];
const lines = splitLines(value);
for (let i = 0; i < lines.length; i++) {
const ls = lines[i].start;
const le = ls + lines[i].text.length;
const from = Math.max(a, ls);
const to = Math.min(b, le);
if (to > from) out.push({ line: i, from: from - ls, to: to - ls });
}
return out;
}
/**
* How far into the inner box a line of `textW` starts, for `align` in `innerW`.
*
* A single-line field realizes its alignment through this offset rather than
* through its child Text's own `align`, because the text layout aligns WITHOUT a
* clamp: a value wider than the box would be centred and overflow both edges,
* fighting the horizontal scroll that exists to keep the caret in view. Clamped
* at zero, a field holds its alignment while the value is short and behaves
* exactly as a left-aligned one once the value fills the box.
*
* It lives here because three things have to agree about it — where the glyphs
* are drawn, where the caret and selection rect go, and which character a click
* lands on. Align is 0 left / 1 center / 2 right, matching TextAlign.
*/
export function alignOffset(align: number, innerW: number, textW: number): number {
const slack = Math.max(0, innerW - textW);
return align === 1 ? slack / 2 : align === 2 ? slack : 0;
}