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): 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.mdx
index 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 owns
the 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 a
prefab-placed dropdown is fully functional without code. The popup is rebuilt on
each 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` (the
backdrop 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 with
a 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 ScrollRect
standard). 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.mdx
index 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.md
index 505efa36b..e09f51482 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5485,6 +5485,7 @@ getDecelerationRate: () => number
getDragScroll: () => boolean
getMaxOffset: () => Vec2
getOffset: () => Vec2
+getShowScrollbar: () => boolean
getViewportSize: () => Vec2
getWheelSpeed: () => number
onScroll: (listener: ScrollListener) => () => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index c0898bc62..0182c7ee3 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -5480,6 +5480,7 @@ getDecelerationRate: () => number
getDragScroll: () => boolean
getMaxOffset: () => Vec2
getOffset: () => Vec2
+getShowScrollbar: () => boolean
getViewportSize: () => Vec2
getWheelSpeed: () => number
onScroll: (listener: ScrollListener) => () => void
diff --git a/sdk/src/ui/ARCHITECTURE.md b/sdk/src/ui/ARCHITECTURE.md
index 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.ts
index 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): voi
markThemed(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): voi
visual: { 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): voi
world.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): System
for (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): System
d.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 paint
shown.set(e, d.selectedIndex);
@@ -233,6 +266,8 @@ export function createDropdownSystem(world: World, events: UIEventQueue): System
world.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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 below
const 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 1
expect(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);
+ });
});