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): modal focus trap, dropdown open-state keyboard, overlay scrollbars, rich-text word-wrap
esengine66497e2dbb34
diff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/guides/ui-components.mdxindex 34b9c3c14..bc80283cb 100644--- a/docs/astro/src/content/docs/guides/ui-components.mdx+++ b/docs/astro/src/content/docs/guides/ui-components.mdx@@ -219,7 +219,8 @@ createDropdown({<Aside type="note">Labels + selection live in a **`UIDropdown` component**; the behavior system ownsthe popup (click toggles it, **a click anywhere else closes it**), row selection,- and **arrow-key stepping** while the closed control is focused — so a+ and the keyboard: arrows step the selection open or closed (the open popup+ highlights the selected row), **Enter** confirms and **Escape** dismisses — so aprefab-placed dropdown is fully functional without code. The popup is rebuilt oneach open with fresh theme roles.</Aside>@@ -254,6 +255,9 @@ dialog.close();| `closeOnEscape` / `closeOnBackdrop` | The standard dismissals — Escape, and a click on the scrim (not the panel). Both default `true`. || `onOpenChange(open)` | Fires on every open/close, whoever initiated it. |+While a dialog is open it also **traps the Tab ring**: only focusables inside the+open dialog's subtree participate (the scrim already blocks pointer focus outside).+**Handle:** `open()`, `close()`, `isOpen()`, `dispose()`, plus `entity` (thebackdrop root) / `panelEntity`.@@ -313,9 +317,11 @@ list.data.setItems(freshList); // replace all`scroll` and `view` as escape hatches to the underlying `ScrollContainer` / `ListView`.<Aside type="note">- Scrolling works out of the box: mouse wheel over the viewport, and pointer **drag with+ Scrolling works out of the box: mouse wheel over the viewport, pointer **drag witha kinetic fling** — the platform layer funnels the primary touch into the pointer- stream, so touch scrolling rides the same path. Tune it with `dragScroll: false` or+ stream, so touch scrolling rides the same path — and an **auto-fading overlay+ scrollbar** per scrollable axis (opt out with `showScrollbar: false` on the+ ScrollContainer). Tune it with `dragScroll: false` or`decelerationRate` (fling velocity left after 1s; default `0.135`, the ScrollRectstandard). For heterogeneous rows, pass a map of item type → template instead of one`item`, and give the data source a `getItemType(i)`.diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdxindex 32beb6ded..9d0a0d13b 100644--- a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx@@ -207,7 +207,8 @@ createDropdown({<Aside type="note">标签与选择存在 **`UIDropdown` 组件**里;行为系统拥有弹出层(点击开合,**点击其他任意位置- 自动关闭**)、行选择、以及闭合聚焦时的**方向键换选**——摆出来的 prefab 无需代码即完整可用。+ 自动关闭**)、行选择、以及键盘:开合两态方向键都能换选(打开的弹出层高亮选中行),+ **Enter** 确认、**Escape** 取消——摆出来的 prefab 无需代码即完整可用。弹出层每次打开都用新鲜的主题角色重建。</Aside>@@ -240,6 +241,9 @@ dialog.close();| `closeOnEscape` / `closeOnBackdrop` | 两个标准关闭方式——Escape,以及点击遮罩(不含面板)。都默认 `true`。 || `onOpenChange(open)` | 每次开/关都会触发,无论由谁发起。 |+对话框打开期间还会**捕获 Tab 环**:只有打开对话框子树内的可聚焦控件参与轮换+(遮罩本来就挡住了外部的指针聚焦)。+**句柄:** `open()`、`close()`、`isOpen()`、`dispose()`,以及 `entity`(背景根)/ `panelEntity`。<Aside type="note">@@ -295,8 +299,9 @@ list.data.setItems(freshList); // 全替换`ScrollContainer` / `ListView` 的逃生舱。<Aside type="note">- 滚动开箱即用:视口上的鼠标滚轮,以及指针**拖拽 + 惯性甩动**——平台层把主触点并入指针流,- 触摸滚动走同一条路径。可用 `dragScroll: false` 关闭,或用 `decelerationRate` 调惯性+ 滚动开箱即用:视口上的鼠标滚轮、指针**拖拽 + 惯性甩动**(平台层把主触点并入指针流,+ 触摸滚动走同一条路径),以及每个可滚动轴的**自动淡出悬浮滚动条**(ScrollContainer 传+ `showScrollbar: false` 关闭)。可用 `dragScroll: false` 关闭,或用 `decelerationRate` 调惯性(甩动 1 秒后剩余的速度比例;默认 `0.135`,ScrollRect 标准值)。异构行:用「item 类型 → 模板」的映射代替单个 `item`,并给数据源一个 `getItemType(i)`。</Aside>diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 505efa36b..e09f51482 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5485,6 +5485,7 @@ getDecelerationRate: () => numbergetDragScroll: () => booleangetMaxOffset: () => Vec2getOffset: () => Vec2+getShowScrollbar: () => booleangetViewportSize: () => Vec2getWheelSpeed: () => numberonScroll: (listener: ScrollListener) => () => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex c0898bc62..0182c7ee3 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -5480,6 +5480,7 @@ getDecelerationRate: () => numbergetDragScroll: () => booleangetMaxOffset: () => Vec2getOffset: () => Vec2+getShowScrollbar: () => booleangetViewportSize: () => Vec2getWheelSpeed: () => numberonScroll: (listener: ScrollListener) => () => voiddiff --git a/sdk/src/ui/ARCHITECTURE.md b/sdk/src/ui/ARCHITECTURE.mdindex 2a5a15771..f5b37a925 100644--- a/sdk/src/ui/ARCHITECTURE.md+++ b/sdk/src/ui/ARCHITECTURE.md@@ -43,7 +43,7 @@ collection, or widgets.| `layout/` | Flexbox layout + safe area + layout bookkeeping | `anchor`, `flex`, `layout` (Yoga driver plugin), `safe-area`, `ui-layout-generation` || `input/` | Pointer/keyboard interaction primitives + their plugins | `interactable`, `draggable`, `focusable`, `drag`, `focus`, `interaction` || `controller/` | The one widget-state mechanism: named pages + per-component property gears, tween-applied | `ui-controller`, `ui-gear`, `gear-apply`, `interaction-gears`, `bind-page`, `ai-builtins`, `plugin` |-| `behavior/` | Runtime systems: scroll/collection ticking, data-driven widget behavior, theme re-resolution | `plugin` (UIBehaviorPlugin), `dialog`, `slider`, `toggle`, `dropdown`, `theme-apply` |+| `behavior/` | Runtime systems: scroll/collection ticking, data-driven widget behavior, scrollbars, theme re-resolution | `plugin` (UIBehaviorPlugin), `dialog`, `slider`, `toggle`, `dropdown`, `scrollbar`, `theme-apply` || `render/` | UI-specific render concerns | `mask`, `render-order` || `collection/` | Data-driven collections + view recycling | `list-view`, `scroll-container`, `view-pool`, `data-source`, `layout-provider` || `text/` | SDF glyph atlas, text layout, rich text, editable text | `glyph-atlas`, `text-renderer`, `layout`, `rich-text-*`, `text-input`, `image-resolver` |diff --git a/sdk/src/ui/behavior/dropdown.ts b/sdk/src/ui/behavior/dropdown.tsindex 3b028cb76..8496c005c 100644--- a/sdk/src/ui/behavior/dropdown.ts+++ b/sdk/src/ui/behavior/dropdown.ts@@ -26,7 +26,7 @@ import { Text, type TextData } from '../core/text';import { UIEventType, type UIEventQueue } from '../core/events';import { Interactable, makeWidgetInteractable, type InteractableData } from '../input/interactable';import { Focusable, type FocusableData } from '../input/focusable';-import { UIController, interactionController } from '../controller/ui-controller';+import { UIController, interactionController, type UIControllerData, INTERACTION_CONTROLLER } from '../controller/ui-controller';import { UIGear } from '../controller/ui-gear';import { interactionGears } from '../controller/interaction-gears';import { themeColors } from '../theme/tokens';@@ -52,6 +52,7 @@ export const UIDropdown = defineComponent<UIDropdownData>('UIDropdown', {interface PopupState {panel: Entity;+ rows: Entity[];unsubs: Array<() => void>;}@@ -104,6 +105,7 @@ export function openDropdown(world: World, events: UIEventQueue, e: Entity): voimarkThemed(world, panel, { visual: 'surfaceElevated' });const unsubs: Array<() => void> = [];+ const rows: Entity[] = [];for (let i = 0; i < d.options.length; i++) {const row = spawnUIEntity({world,@@ -118,20 +120,25 @@ export function openDropdown(world: World, events: UIEventQueue, e: Entity): voivisual: { color: t.control },});// Rows are pointer-only: the popup is transient, so they stay out of- // the Tab ring.+ // the Tab ring. 'selected' is NOT driver-owned — the keyboard highlight+ // holds it, and the pointer driver leaves such pages alone.makeWidgetInteractable(world, row, { focusable: false });world.insert(row, UIController, {- controllers: [interactionController(['normal', 'hover', 'pressed'])],+ controllers: [interactionController(['normal', 'hover', 'pressed', 'selected'])],});world.insert(row, UIGear, {bindings: interactionGears({normal: { color: t.control },hover: { color: t.primaryHover },pressed: { color: t.primaryActive },+ selected: { color: t.primaryActive },}),});markThemed(world, row, {- states: { normal: 'control', hover: 'primaryHover', pressed: 'primaryActive' },+ states: {+ normal: 'control', hover: 'primaryHover',+ pressed: 'primaryActive', selected: 'primaryActive',+ },});const rowLabel = spawnUIEntity({@@ -151,8 +158,28 @@ export function openDropdown(world: World, events: UIEventQueue, e: Entity): voiworld.insert(e, UIDropdown, cur);}}));+ rows.push(row);+ }+ popups.set(e, { panel, rows, unsubs });+ highlightRow(world, rows, d.selectedIndex);+}++/** Keyboard highlight: the selected row holds the non-driver-owned 'selected'+ * page; every other row returns to 'normal', handing pointer hover back to+ * the driver. */+function highlightRow(world: World, rows: Entity[], selected: number): void {+ for (let i = 0; i < rows.length; i++) {+ const row = rows[i]!;+ if (!world.valid(row) || !world.has(row, UIController)) continue;+ const data = world.get(row, UIController) as UIControllerData;+ const ctrl = data.controllers.find((c) => c.name === INTERACTION_CONTROLLER);+ if (!ctrl) continue;+ const want = i === selected ? 'selected' : (ctrl.current === 'selected' ? 'normal' : ctrl.current);+ if (ctrl.current !== want) {+ ctrl.current = want;+ world.insert(row, UIController, data);+ }}- popups.set(e, { panel, unsubs });}/** True when `entity` is inside the popup subtree of any open dropdown. */@@ -205,13 +232,15 @@ export function createDropdownSystem(world: World, events: UIEventQueue): Systemfor (const e of world.getEntitiesWithComponents([UIDropdown])) {const d = world.get(e, UIDropdown) as UIDropdownData;- // Keyboard: step the selection while focused and closed (the- // native <select> convention).+ // Keyboard: arrows step the selection whether the popup is open+ // (moving the row highlight) or closed (the native <select>+ // convention); Enter confirms and Escape dismisses an open popup.const focused = world.has(e, Focusable)&& (world.get(e, Focusable) as FocusableData).isFocused;const enabled = !world.has(e, Interactable)|| (world.get(e, Interactable) as InteractableData).enabled;- if (focused && enabled && !isDropdownOpen(world, e) && d.options.length > 0) {+ const open = isDropdownOpen(world, e);+ if (focused && enabled && d.options.length > 0) {let next = d.selectedIndex;if (input.isKeyPressed('ArrowDown')) next = Math.min(next + 1, d.options.length - 1);if (input.isKeyPressed('ArrowUp')) next = Math.max(next - 1, 0);@@ -219,9 +248,13 @@ export function createDropdownSystem(world: World, events: UIEventQueue): Systemd.selectedIndex = next;world.insert(e, UIDropdown, d);}+ if (open && (input.isKeyPressed('Enter') || input.isKeyPressed('Escape'))) {+ closeDropdown(world, e);+ }}- // Selection → label + change event, whoever wrote the index.+ // Selection → label + row highlight + change event, whoever wrote+ // the index.if (shown.get(e) !== d.selectedIndex) {const emitChange = shown.has(e); // first sync is initial paintshown.set(e, d.selectedIndex);@@ -233,6 +266,8 @@ export function createDropdownSystem(world: World, events: UIEventQueue): Systemworld.insert(d.label, Text, txt);}}+ const popup = popupsOf(world).get(e);+ if (popup) highlightRow(world, popup.rows, d.selectedIndex);if (emitChange) events.emit(e, UIEventType.Change, { index: d.selectedIndex });}}diff --git a/sdk/src/ui/behavior/plugin.ts b/sdk/src/ui/behavior/plugin.tsindex 5c2084eca..93688500c 100644--- a/sdk/src/ui/behavior/plugin.ts+++ b/sdk/src/ui/behavior/plugin.ts@@ -20,6 +20,7 @@ import { UIDialog, createDialogSystem } from './dialog';import { UISlider, createSliderSystem } from './slider';import { UIToggle, createToggleSystem } from './toggle';import { UIDropdown, createDropdownSystem } from './dropdown';+import { createScrollbarSystem } from './scrollbar';import { registerComponent } from '../../component';/** Screen-px slop before a press becomes a scroll drag (matches Draggable). */@@ -123,6 +124,12 @@ export class UIBehaviorPlugin implements Plugin {{ runIf: playModeOnly },);+ app.addSystemToSchedule(+ Schedule.Update,+ createScrollbarSystem(world, scrollContainers),+ { runIf: playModeOnly },+ );+app.addSystemToSchedule(Schedule.Update,defineSystem([], () => listViews.tick(), { name: 'ListViewSystem' }),diff --git a/sdk/src/ui/behavior/scrollbar.ts b/sdk/src/ui/behavior/scrollbar.tsnew file mode 100644index 000000000..23f4a4121--- /dev/null+++ b/sdk/src/ui/behavior/scrollbar.ts@@ -0,0 +1,148 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file ui/behavior/scrollbar.ts+ * @brief Auto-fading overlay scrollbar thumbs for scroll containers.+ *+ * Every attached ScrollContainer (list views, scroll views) gets lazy thumb+ * entities per scrollable axis: they appear while the offset moves, then fade+ * out after a short idle — the modern overlay convention, no layout impact+ * (Absolute, out of flow) and no input surface (not interactable). Thumbs are+ * theme-tagged (`text` role, alpha preserved) so they re-skin live.+ */+import { defineSystem, type SystemDef } from '../../system';+import { Res, Time, type TimeData } from '../../resource';+import type { World } from '../../world';+import type { Entity, Vec2 } from '../../types';+import { px } from '../core/dimension';+import { spawnUIEntity } from '../core/compose';+import { UINode, UIPositionType, type UINodeData } from '../core/ui-node';+import { UIVisual, type UIVisualData } from '../core/ui-visual';+import { themeColors } from '../theme/tokens';+import { markThemed } from '../theme/theme-style';+import { EntityStateMap } from '../util/helpers';+import type { ScrollContainer, ScrollContainerRegistry } from '../collection/scroll-container';++const THUMB_THICKNESS = 4;+const THUMB_MARGIN = 2;+const THUMB_MIN_LENGTH = 20;+const THUMB_ALPHA = 0.35;+/** Seconds of stillness before the fade starts, and the fade's duration. */+const IDLE_DELAY = 0.8;+const FADE_TIME = 0.3;++interface BarState {+ v: Entity | null;+ h: Entity | null;+ last: Vec2;+ /** Seconds since the offset last moved. */+ idle: number;+}++function spawnThumb(world: World, viewport: Entity, axis: 'v' | 'h'): Entity {+ const thumb = spawnUIEntity({+ world,+ parent: viewport,+ node: axis === 'v'+ ? {+ position: UIPositionType.Absolute,+ insetRight: px(THUMB_MARGIN),+ insetTop: px(0),+ width: px(THUMB_THICKNESS),+ height: px(THUMB_MIN_LENGTH),+ }+ : {+ position: UIPositionType.Absolute,+ insetBottom: px(THUMB_MARGIN),+ insetLeft: px(0),+ height: px(THUMB_THICKNESS),+ width: px(THUMB_MIN_LENGTH),+ },+ visual: { color: { ...themeColors().text, a: 0 } },+ });+ markThemed(world, thumb, { visual: 'text' });+ return thumb;+}++function layoutThumb(+ world: World, thumb: Entity, axis: 'v' | 'h',+ offset: number, maxOffset: number, viewportLen: number, contentLen: number,+ alpha: number,+): void {+ if (!world.valid(thumb)) return;+ const len = Math.max(THUMB_MIN_LENGTH, (viewportLen / contentLen) * viewportLen);+ const range = Math.max(0, viewportLen - len);+ const along = maxOffset > 0 ? (offset / maxOffset) * range : 0;++ const n = world.get(thumb, UINode) as UINodeData;+ if (axis === 'v') {+ n.insetTop = px(along);+ n.height = px(len);+ } else {+ n.insetLeft = px(along);+ n.width = px(len);+ }+ world.insert(thumb, UINode, n);++ const vis = world.get(thumb, UIVisual) as UIVisualData;+ const a = THUMB_ALPHA * alpha;+ if (Math.abs(vis.color.a - a) > 0.001) {+ vis.color = { ...vis.color, a };+ world.insert(thumb, UIVisual, vis);+ }+}++/** Sync thumbs for every attached scroll container; fade after idle. */+export function createScrollbarSystem(+ world: World,+ containers: ScrollContainerRegistry,+): SystemDef {+ const bars = new EntityStateMap<BarState>();++ return defineSystem([Res(Time)], (time: TimeData) => {+ const seen = new Set<Entity>();+ for (const [entityNum, container] of containers.entries()) {+ const entity = entityNum as Entity;+ if (!world.valid(entity) || !(container as ScrollContainer).getShowScrollbar()) continue;+ seen.add(entity);++ const offset = container.getOffset();+ const viewport = container.getViewportSize();+ const content = container.getContentSize();+ const max = container.getMaxOffset();++ let bar = bars.get(entity);+ if (!bar) {+ bar = { v: null, h: null, last: offset, idle: IDLE_DELAY + FADE_TIME };+ bars.set(entity, bar);+ }++ if (offset.x !== bar.last.x || offset.y !== bar.last.y) {+ bar.last = offset;+ bar.idle = 0;+ } else {+ bar.idle += time.delta;+ }+ const alpha = bar.idle <= IDLE_DELAY+ ? 1+ : Math.max(0, 1 - (bar.idle - IDLE_DELAY) / FADE_TIME);++ if (max.y > 0 && bar.v === null && alpha > 0) bar.v = spawnThumb(world, entity, 'v');+ if (max.x > 0 && bar.h === null && alpha > 0) bar.h = spawnThumb(world, entity, 'h');+ if (bar.v !== null) {+ layoutThumb(world, bar.v, 'v', offset.y, max.y, viewport.y, content.y, max.y > 0 ? alpha : 0);+ }+ if (bar.h !== null) {+ layoutThumb(world, bar.h, 'h', offset.x, max.x, viewport.x, content.x, max.x > 0 ? alpha : 0);+ }+ }++ // Detached / despawned containers: drop the thumbs with them.+ for (const [entity, bar] of bars) {+ if (seen.has(entity)) continue;+ if (bar.v !== null && world.valid(bar.v)) world.despawn(bar.v);+ if (bar.h !== null && world.valid(bar.h)) world.despawn(bar.h);+ bars.delete(entity);+ }+ }, { name: 'UIScrollbarSystem' });+}diff --git a/sdk/src/ui/collection/scroll-container.ts b/sdk/src/ui/collection/scroll-container.tsindex bae3db447..764fb4402 100644--- a/sdk/src/ui/collection/scroll-container.ts+++ b/sdk/src/ui/collection/scroll-container.ts@@ -15,6 +15,8 @@ export interface ScrollContainerOptions {dragScroll?: boolean;/** Fling velocity left after 1s of coasting. Default 0.135. */decelerationRate?: number;+ /** Auto-fading overlay scrollbar thumbs. Default true. */+ showScrollbar?: boolean;}export type ScrollListener = (offset: Vec2) => void;@@ -35,6 +37,7 @@ export class ScrollContainer {private readonly wheelSpeed_: number;private readonly dragScroll_: boolean;private readonly decelerationRate_: number;+ private readonly showScrollbar_: boolean;private readonly listeners_ = new Set<ScrollListener>();constructor(opts: ScrollContainerOptions) {@@ -44,6 +47,7 @@ export class ScrollContainer {this.wheelSpeed_ = opts.wheelSpeed ?? 1;this.dragScroll_ = opts.dragScroll ?? true;this.decelerationRate_ = opts.decelerationRate ?? 0.135;+ this.showScrollbar_ = opts.showScrollbar ?? true;this.setOffset(opts.initialOffset ?? { x: 0, y: 0 });}@@ -66,6 +70,10 @@ export class ScrollContainer {};}+ getShowScrollbar(): boolean {+ return this.showScrollbar_;+ }+getWheelSpeed(): number {return this.wheelSpeed_;}diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex ebafb05b5..8ee194855 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -143,6 +143,8 @@ export {type UIDropdownData,} from './behavior/dropdown';+export { createScrollbarSystem } from './behavior/scrollbar';+// ─── Controllers + Gears (shared UI state) ──────────────────────────────────export {@@ -478,6 +480,8 @@ export { EngineAtlasPageStore } from './text/atlas-page-store';export {layoutLine,layoutRichLine,+ layoutRichRuns,+ wrapRichRuns,layoutText,wrapLine,measureWidth,diff --git a/sdk/src/ui/input/focus.ts b/sdk/src/ui/input/focus.tsindex 2f8da254c..2f0110c0b 100644--- a/sdk/src/ui/input/focus.ts+++ b/sdk/src/ui/input/focus.ts@@ -14,9 +14,12 @@ import type { InteractableData } from './interactable';import { UIInteraction } from './interactable';import type { UIInteractionData } from './interactable';import { TextInput } from '../text/text-input';+import { UIDialog, isDialogOpen } from '../behavior/dialog';+import { walkParentChain } from '../util/helpers';import { playModeOnly } from '../../env';import { UIEvents, UIEventQueue, UIEventType } from '../core/events';import { PluginName } from '../../systemLabels';+import type { ESEngineModule, CppRegistry } from '../../wasm';export class FocusPlugin implements Plugin {name = PluginName.Focus;@@ -26,9 +29,37 @@ export class FocusPlugin implements Plugin {registerComponent('Focusable', Focusable);const world = app.world;+ const module = app.wasmModule as ESEngineModule | undefined;+ const registry = module ? (world.getCppRegistry() as CppRegistry) : undefined;const focusManager = new FocusManagerState();app.insertResource(FocusManager, focusManager);+ // display:none removes an entity from rendering + hit-testing; the Tab+ // ring must skip it too or focus lands on invisible controls.+ const hiddenInTree = (e: Entity): boolean =>+ !!(module?.getUINodeHiddenInTree && registry+ && module.getUINodeHiddenInTree(registry, e));++ // An open modal traps the Tab ring: only focusables inside an open+ // UIDialog subtree participate while one is up (the scrim already+ // blocks pointer focus outside).+ const openDialogRoots = (): Entity[] =>+ world.getEntitiesWithComponents([UIDialog]).filter((e) => isDialogOpen(world, e));+ const insideAny = (entity: Entity, roots: Entity[]): boolean => {+ if (roots.length === 0) return true;+ const set = new Set(roots.map((r) => r as number));+ if (set.has(entity as number)) return true;+ let inside = false;+ walkParentChain(world, entity, (ancestor) => {+ if (set.has(ancestor as number)) {+ inside = true;+ return true;+ }+ return false;+ });+ return inside;+ };+app.addSystemToSchedule(Schedule.Update, defineSystem([Res(Input), Res(UIEvents)],(input: InputState, events: UIEventQueue) => {@@ -87,6 +118,7 @@ export class FocusPlugin implements Plugin {}function getSortedFocusables(): Entity[] {+ const trapRoots = openDialogRoots();const entries: { entity: Entity; tabIndex: number }[] = [];for (const entity of focusableEntities) {if (!world.valid(entity)) continue;@@ -94,6 +126,8 @@ export class FocusPlugin implements Plugin {const interactable = world.get(entity, Interactable) as InteractableData;if (!interactable.enabled) continue;}+ if (hiddenInTree(entity)) continue;+ if (!insideAny(entity, trapRoots)) continue;const f = world.get(entity, Focusable) as FocusableData;entries.push({ entity, tabIndex: f.tabIndex });}diff --git a/sdk/src/ui/text/layout.ts b/sdk/src/ui/text/layout.tsindex 938673d0b..974dfa5bd 100644--- a/sdk/src/ui/text/layout.ts+++ b/sdk/src/ui/text/layout.ts@@ -15,7 +15,7 @@*/import type { GlyphAtlas } from './glyph-atlas';import { TEXT_VERTEX_FLOATS } from './submit';-import { parseRichText } from './rich-text-parser';+import { parseRichText, type TextSegment } from './rich-text-parser';import { UI_TEXT_BOLD, UI_TEXT_ITALIC } from './text-transform';export interface TextLayoutOptions {@@ -152,7 +152,7 @@ export interface MultilineTextOptions extends TextLayoutOptions {rich?: boolean;/** Base color (used by rich runs without their own color). */color?: RGBA;- /** Word-wrap width in display px (plain text only). 0/undefined = no wrap. */+ /** Word-wrap width in display px (plain and rich text). 0/undefined = no wrap. */maxWidth?: number;/*** Width (display px) each line is horizontally aligned within — the layout box.@@ -233,14 +233,23 @@ export function layoutText(const align = opts.align ?? TEXT_ALIGN_LEFT;const baseColor = opts.color ?? ([1, 1, 1, 1] as const);const rawLines = text.split('\n');- // Word-wrap (plain text only) before stacking; explicit \n still hard-breaks.- const lines = (opts.maxWidth && opts.maxWidth > 0 && !opts.rich)- ? rawLines.flatMap(l => wrapLine(l, atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0))- : rawLines;+ const wrap = !!(opts.maxWidth && opts.maxWidth > 0);+ const richOpts = { fontSizePx: opts.fontSizePx, letterSpacing: opts.letterSpacing, color: baseColor };- const lineLayouts = lines.map(line => (opts.rich- ? layoutRichLine(line, atlas, fontFamily, { fontSizePx: opts.fontSizePx, letterSpacing: opts.letterSpacing, color: baseColor }, style)- : layoutLine(line, atlas, fontFamily, opts, style)));+ // Word-wrap before stacking; explicit \n still hard-breaks. Rich lines wrap+ // at the styled-run level so a token measures with its own size/style.+ const lineLayouts = opts.rich+ ? rawLines+ .map(l => parseRichText(l).filter((r): r is TextSegment => r.type === 'text'))+ .flatMap(runs => (wrap+ ? wrapRichRuns(runs, atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0)+ : [runs]))+ .map(runs => layoutRichRuns(runs, atlas, fontFamily, richOpts, style))+ : (wrap+ ? rawLines.flatMap(l => wrapLine(l, atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0))+ : rawLines+ ).map(line => layoutLine(line, atlas, fontFamily, opts, style));+ const lines = lineLayouts; // line count only belowconst contentWidth = lineLayouts.reduce((m, l) => Math.max(m, l.width), 0);// Align within the layout box when one is given (independent of word-wrap), then@@ -277,14 +286,120 @@ export function layoutRichLine(fontFamily: string,opts: RichTextLayoutOptions,baseStyle = 0,+): TextLayout {+ return layoutRichRuns(+ parseRichText(content).filter((r): r is TextSegment => r.type === 'text'),+ atlas, fontFamily, opts, baseStyle);+}++/** Measure a styled run's advance width (mirrors layoutRichRuns' pen math). */+function measureRun(+ text: string, run: TextSegment, atlas: GlyphAtlas, fontFamily: string,+ baseSizePx: number, baseStyle: number, spacing: number,+): number {+ const runSize = run.fontSize ?? baseSizePx;+ const pixelSize = atlas.pixelSizeFor(runSize);+ const scale = runSize / pixelSize;+ const style = baseStyle | (run.bold ? UI_TEXT_BOLD : 0) | (run.italic ? UI_TEXT_ITALIC : 0);+ let w = 0;+ for (const ch of text) {+ const cp = ch.codePointAt(0);+ if (cp === undefined) continue;+ const gph = atlas.getGlyph(cp, fontFamily, style, pixelSize);+ if (gph) w += gph.advance * scale + spacing;+ }+ return w;+}++/**+ * Greedy word-wrap over styled runs: tokens measure with their own run's+ * size/style, breaks land at spaces (a single oversized token breaks+ * character-by-character), and each output line is a run list ready for+ * {@link layoutRichRuns}. The plain-text twin is {@link wrapLine}.+ */+export function wrapRichRuns(+ runs: TextSegment[], atlas: GlyphAtlas, fontFamily: string,+ baseSizePx: number, baseStyle: number, maxWidth: number, spacing = 0,+): TextSegment[][] {+ interface Token { run: TextSegment; text: string; space: boolean }+ const tokens: Token[] = [];+ for (const run of runs) {+ for (const part of run.text.split(/(\s+)/)) {+ if (part === '') continue;+ tokens.push({ run, text: part, space: /^\s+$/.test(part) });+ }+ }++ const lines: TextSegment[][] = [];+ let cur: Token[] = [];+ let curWidth = 0;+ const measure = (t: Token) =>+ measureRun(t.text, t.run, atlas, fontFamily, baseSizePx, baseStyle, spacing);+ const flush = () => {+ while (cur.length > 0 && cur[cur.length - 1]!.space) cur.pop();+ // Merge adjacent tokens of the same run back into segments.+ const segs: TextSegment[] = [];+ for (const t of cur) {+ const last = segs[segs.length - 1];+ if (last && last.bold === t.run.bold && last.italic === t.run.italic+ && last.color === t.run.color && last.fontSize === t.run.fontSize) {+ last.text += t.text;+ } else {+ segs.push({ ...t.run, text: t.text });+ }+ }+ if (segs.length > 0) lines.push(segs);+ cur = [];+ curWidth = 0;+ };+ const push = (t: Token) => { cur.push(t); curWidth += measure(t); };+ const charBreak = (t: Token) => {+ for (const ch of t.text) {+ const w = measureRun(ch, t.run, atlas, fontFamily, baseSizePx, baseStyle, spacing);+ if (cur.length > 0 && curWidth + w > maxWidth) flush();+ push({ run: t.run, text: ch, space: false });+ }+ };++ for (const t of tokens) {+ if (t.space) {+ if (cur.length > 0) push(t); // keep inter-word spaces, drop leading+ continue;+ }+ const w = measure(t);+ if (cur.length === 0) {+ if (w <= maxWidth) push(t);+ else charBreak(t);+ } else if (curWidth + w <= maxWidth) {+ push(t);+ } else {+ flush();+ if (w <= maxWidth) push(t);+ else charBreak(t);+ }+ }+ flush();+ return lines.length ? lines : [[]];+}++/**+ * Lay out a single rich line from its styled runs: each run carries per-run+ * color + size + bold/italic; all runs share the baseline (y = 0). Image runs+ * never reach here (callers filter to TextSegments). Pure → unit-testable.+ */+export function layoutRichRuns(+ runs: TextSegment[],+ atlas: GlyphAtlas,+ fontFamily: string,+ opts: RichTextLayoutOptions,+ baseStyle = 0,): TextLayout {const spacing = opts.letterSpacing ?? 0;const glyphs: LaidGlyph[] = [];let penX = 0;let lineHeight = opts.fontSizePx;- for (const run of parseRichText(content)) {- if (run.type !== 'text') continue; // embedded images: deferred+ for (const run of runs) {const runSize = run.fontSize ?? opts.fontSizePx;const pixelSize = atlas.pixelSizeFor(runSize);const scale = runSize / pixelSize;diff --git a/sdk/tests/ui-scrollbar.test.ts b/sdk/tests/ui-scrollbar.test.tsnew file mode 100644index 000000000..83b824a23--- /dev/null+++ b/sdk/tests/ui-scrollbar.test.ts@@ -0,0 +1,140 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file UIScrollbarSystem — overlay thumbs appear on scroll, track the offset,+ * and fade out after idle.+ */+import { describe, it, expect, beforeEach } from 'vitest';+import { createScrollbarSystem } from '../src/ui/behavior/scrollbar';+import { ScrollContainer, ScrollContainerRegistry } from '../src/ui/collection/scroll-container';+import { UINode } from '../src/ui/core/ui-node';+import { UIVisual } from '../src/ui/core/ui-visual';+import type { Entity } from '../src/types';+import type { World } from '../src/world';++interface MockWorld {+ _entities: Set<number>;+ _components: Map<number, Map<object, unknown>>;+ spawn(): Entity;+ despawn(e: Entity): void;+ valid(e: Entity): boolean;+ setParent(c: Entity, p: Entity): void;+ has(e: Entity, c: object): boolean;+ get(e: Entity, c: object): unknown;+ insert(e: Entity, c: object, data: unknown): void;+ getEntitiesWithComponents(cs: object[]): Entity[];+ onDespawn(cb: (e: Entity) => void): () => void;+}++function createMockWorld(): MockWorld {+ let nextId = 1;+ const w: MockWorld = {+ _entities: new Set(),+ _components: new Map(),+ spawn() {+ const id = nextId++;+ w._entities.add(id);+ w._components.set(id, new Map());+ return id as Entity;+ },+ despawn(e) {+ w._entities.delete(e as number);+ w._components.delete(e as number);+ },+ valid(e) { return w._entities.has(e as number); },+ setParent() { /* not needed */ },+ has(e, c) { return w._components.get(e as number)?.has(c) ?? false; },+ get(e, c) { return w._components.get(e as number)?.get(c); },+ insert(e, c, d) { w._components.get(e as number)?.set(c, d); },+ getEntitiesWithComponents(cs) {+ return [...w._entities].filter((e) =>+ cs.every((c) => w._components.get(e)?.has(c))) as Entity[];+ },+ onDespawn() { return () => {}; },+ };+ return w;+}++describe('UIScrollbarSystem', () => {+ let world: MockWorld;+ let registry: ScrollContainerRegistry;+ let viewport: Entity;+ let scroll: ScrollContainer;+ let tick: (dt?: number) => void;++ const thumbs = (): Entity[] =>+ [...world._entities].filter((e) =>+ e !== (viewport as number)+ && world.has(e as Entity, UINode) && world.has(e as Entity, UIVisual)) as Entity[];++ beforeEach(() => {+ world = createMockWorld();+ registry = new ScrollContainerRegistry();+ viewport = world.spawn();+ scroll = new ScrollContainer({+ viewportSize: { x: 100, y: 100 },+ contentSize: { x: 100, y: 300 },+ });+ registry.attach(viewport as number, scroll);+ const sys = createScrollbarSystem(world as unknown as World, registry);+ // eslint-disable-next-line @typescript-eslint/no-explicit-any+ tick = (dt = 1 / 60) => (sys as any)._fn({ delta: dt });+ });++ it('spawns a vertical thumb once the offset moves, sized to the visible fraction', () => {+ tick();+ expect(thumbs()).toHaveLength(0); // still — nothing shown++ scroll.scrollBy({ x: 0, y: 100 });+ tick();+ const [thumb] = thumbs();+ expect(thumb).toBeDefined();+ const n = world.get(thumb!, UINode) as { height: { value: number }; insetTop: { value: number } };+ // viewport/content = 1/3 of the 100px track ≈ 33.3px…+ expect(n.height.value).toBeCloseTo(100 * 100 / 300, 1);+ // …placed at offset 100 of max 200 → half the remaining track.+ expect(n.insetTop.value).toBeCloseTo((100 / 200) * (100 - 100 * 100 / 300), 1);+ const vis = world.get(thumb!, UIVisual) as { color: { a: number } };+ expect(vis.color.a).toBeGreaterThan(0.3);+ });++ it('fades the thumb out after the idle delay', () => {+ tick(); // baseline frame before the scroll+ scroll.scrollBy({ x: 0, y: 50 });+ tick();+ const [thumb] = thumbs();+ expect(thumb).toBeDefined();++ for (let i = 0; i < 90; i++) tick(); // 1.5s of stillness > delay + fade+ const vis = world.get(thumb!, UIVisual) as { color: { a: number } };+ expect(vis.color.a).toBe(0);+ });++ it('drops the thumbs when the container detaches', () => {+ tick();+ scroll.scrollBy({ x: 0, y: 50 });+ tick();+ expect(thumbs()).toHaveLength(1);++ registry.detach(viewport as number);+ tick();+ expect(thumbs()).toHaveLength(0);+ });++ it('a horizontal-only container never grows a vertical thumb', () => {+ registry.detach(viewport as number);+ const h = new ScrollContainer({+ viewportSize: { x: 100, y: 100 },+ contentSize: { x: 300, y: 100 },+ direction: 'horizontal',+ });+ registry.attach(viewport as number, h);+ tick();+ h.scrollBy({ x: 60, y: 0 });+ tick();+ const all = thumbs();+ expect(all).toHaveLength(1);+ const n = world.get(all[0]!, UINode) as { width: { value: number } };+ expect(n.width.value).toBeCloseTo(100 * 100 / 300, 1); // horizontal thumb length+ });+});diff --git a/sdk/tests/ui-slider-dropdown.test.ts b/sdk/tests/ui-slider-dropdown.test.tsindex cd22e9d34..fa5725c61 100644--- a/sdk/tests/ui-slider-dropdown.test.ts+++ b/sdk/tests/ui-slider-dropdown.test.ts@@ -276,6 +276,35 @@ describe('createDropdown', () => {expect(dd.isOpen()).toBe(false);});+ it('open state: Enter closes the popup; the selected row holds the selected page', () => {+ const dd = createDropdown({+ world: world as unknown as World, events,+ options: ['a', 'b', 'c'], selectedIndex: 1,+ });+ tick();+ dd.open();+ expect(dd.isOpen()).toBe(true);++ // Exactly one popup row sits on the non-driver-owned 'selected' page.+ const selectedRows = (world as unknown as { _components: Map<number, Map<object, unknown>> })+ ._components;+ let count = 0;+ for (const comps of selectedRows.values()) {+ for (const data of comps.values()) {+ const d = data as { controllers?: Array<{ name: string; current: string }> };+ if (d?.controllers?.some((c) => c.current === 'selected')) count++;+ }+ }+ expect(count).toBe(1);++ const f = world.get(dd.entity, Focusable) as { isFocused: boolean };+ f.isFocused = true;+ world.insert(dd.entity, Focusable, f);+ keys.add('Enter');+ tick();+ expect(dd.isOpen()).toBe(false);+ });+it('arrow keys step the selection while focused and closed', () => {const dd = createDropdown({world: world as unknown as World, events,diff --git a/sdk/tests/ui-text-wrap.test.ts b/sdk/tests/ui-text-wrap.test.tsindex cd7ddc31e..4c29245e4 100644--- a/sdk/tests/ui-text-wrap.test.ts+++ b/sdk/tests/ui-text-wrap.test.ts@@ -9,7 +9,8 @@ import { describe, it, expect } from 'vitest';import {GlyphAtlas, type GlyphRasterizer, type AtlasPageStore, type RasterGlyph,} from '../src/ui/text/glyph-atlas';-import { wrapLine, measureWidth, layoutText } from '../src/ui/text/layout';+import { wrapLine, wrapRichRuns, measureWidth, layoutText } from '../src/ui/text/layout';+import type { TextSegment } from '../src/ui/text/rich-text-parser';function makeAtlas(): GlyphAtlas {const rasterizer: GlyphRasterizer = {@@ -53,4 +54,39 @@ describe('REARCH_GUI P1.4c: word-wrap', () => {// glyphs of line 3 sit below line 1expect(layout.glyphs[5].y0).toBeLessThan(layout.glyphs[0].y0);});++ const seg = (text: string, over: Partial<TextSegment> = {}): TextSegment => ({+ type: 'text', text, bold: false, italic: false, color: null, fontSize: null, ...over,+ });++ it('wrapRichRuns breaks styled runs at spaces, preserving each token\'s run style', () => {+ // "AA <b>AA AA</b>" at width 12 → three lines, the bold style survives the break.+ const lines = wrapRichRuns(+ [seg('AA '), seg('AA AA', { bold: true })],+ makeAtlas(), 'Arial', F, 0, 12);+ expect(lines.map((l) => l.map((r) => `${r.bold ? 'b' : 'n'}:${r.text}`))).toEqual([+ ['n:AA'], ['b:AA'], ['b:AA'],+ ]);+ });++ it('wrapRichRuns keeps a fitting styled line intact and merges same-style tokens', () => {+ const lines = wrapRichRuns([seg('AA AA')], makeAtlas(), 'Arial', F, 0, 30);+ expect(lines).toHaveLength(1);+ expect(lines[0]).toHaveLength(1); // tokens merged back into one segment+ expect(lines[0]![0]!.text).toBe('AA AA');+ });++ it('wrapRichRuns measures a token with its own fontSize', () => {+ // A double-size run: each glyph advances 11 (scale 1) instead of 5.5,+ // so "AA" (22) overflows width 12 and char-breaks.+ const lines = wrapRichRuns([seg('AA', { fontSize: 48 })], makeAtlas(), 'Arial', F, 0, 12);+ expect(lines.map((l) => l.map((r) => r.text))).toEqual([['A'], ['A']]);+ });++ it('layoutText wraps rich markup end-to-end', () => {+ const layout = layoutText('AA <b>AA</b> AA', makeAtlas(), 'Arial',+ { fontSizePx: F, maxWidth: 12, rich: true });+ expect(layout.glyphs.length).toBe(6); // 3 lines × "AA"+ expect(layout.glyphs[5].y0).toBeLessThan(layout.glyphs[0].y0);+ });});