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
fix(ui): a clicked button stops looking focused, and focus gets a colour of its own
yhh37b259b5f50a
diff --git a/sdk/src/ui/controller/gear-apply.ts b/sdk/src/ui/controller/gear-apply.tsindex 6a5e39011..c628ef79f 100644--- a/sdk/src/ui/controller/gear-apply.ts+++ b/sdk/src/ui/controller/gear-apply.ts@@ -23,7 +23,7 @@ import { Res, Time, type TimeData } from '../../resource';import { applyEasing } from '../../animation/Easing';import { EntityStateMap } from '../util/helpers';import { Interactable, UIInteraction, type InteractableData, type UIInteractionData } from '../input/interactable';-import { Focusable, type FocusableData } from '../input/focusable';+import { Focusable, FocusManager, type FocusManagerState } from '../input/focusable';import type { Entity } from '../../types';import type { World } from '../../world';import {@@ -120,16 +120,21 @@ const DRIVER_OWNED_PAGES: ReadonlySet<string> = new Set([/*** Pure derivation: choose the interaction page a hit-test pass implies.* Extracted so unit tests can cover the branching without a World.+ *+ * `focusVisible` is `:focus-visible`, not "has focus": a pointer press moves focus+ * too, and a control that keeps a focus look after being clicked reads as stuck —+ * the pointer is long gone and the button is still lit until you click elsewhere.+ * See {@link FocusManagerState.focusVisible}.*/export function driverStateFor(enabled: boolean,interaction: UIInteractionData | null,- focused = false,+ focusVisible = false,): string {if (!enabled) return 'disabled';if (interaction?.pressed) return 'pressed';if (interaction?.hovered) return 'hover';- if (focused) return 'focused';+ if (focusVisible) return 'focused';return 'normal';}@@ -141,7 +146,7 @@ export function driverStateFor(* `current` holds a user-managed page outside {@link DRIVER_OWNED_PAGES}.*/export function createInteractionControllerDriverSystem(world: World): SystemDef {- return defineSystem([], () => {+ return defineSystem([Res(FocusManager)], (focus: FocusManagerState) => {for (const e of world.getEntitiesWithComponents([Interactable, UIController])) {const data = world.get(e, UIController) as UIControllerData;const ctrl = data.controllers.find(c => c.name === INTERACTION_CONTROLLER);@@ -151,9 +156,10 @@ export function createInteractionControllerDriverSystem(world: World): SystemDef? (world.get(e, UIInteraction) as UIInteractionData): null;const interactable = world.get(e, Interactable) as InteractableData;- const focused = world.has(e, Focusable)- && (world.get(e, Focusable) as FocusableData).isFocused;- const next = driverStateFor(interactable.enabled, inter, focused);+ // The manager, not Focusable.isFocused: only it knows HOW focus arrived,+ // and a pointer-focused control must not wear the focus look.+ const focusVisible = world.has(e, Focusable) && focus.isVisiblyFocused(e);+ const next = driverStateFor(interactable.enabled, inter, focusVisible);if (next !== ctrl.current && ctrl.pages.includes(next)) {ctrl.current = next;world.insert(e, UIController, data);diff --git a/sdk/src/ui/input/focus.ts b/sdk/src/ui/input/focus.tsindex 733d00dbb..f722dac5e 100644--- a/sdk/src/ui/input/focus.ts+++ b/sdk/src/ui/input/focus.ts@@ -81,7 +81,10 @@ export class FocusPlugin implements Plugin {const interaction = world.get(entity, UIInteraction) as UIInteractionData;if (interaction.justPressed) {pressedFocusable = true;- setFocus(entity);+ // Focus, but NOT visibly: a pointer press moves focus so+ // Enter/Space act on what you clicked, while the control+ // keeps looking the way the pointer left it.+ setFocus(entity, false);}}@@ -120,7 +123,9 @@ export class FocusPlugin implements Plugin {: (currentIdx + 1) % sorted.length;}- setFocus(sorted[nextIdx]);+ // Tab is the case the highlight exists for — nothing else says+ // where you are.+ setFocus(sorted[nextIdx], true);}function getSortedFocusables(): Entity[] {@@ -141,12 +146,17 @@ export class FocusPlugin implements Plugin {return entries.map(e => e.entity);}- function setFocus(entity: Entity): void {+ function setFocus(entity: Entity, visible: boolean): void {const prev = focusManager.focusedEntity;- if (prev === entity) return;+ // Re-focusing what is already focused still updates HOW: tabbing+ // to a control you had clicked must start drawing the highlight.+ if (prev === entity) {+ focusManager.focusVisible = visible;+ return;+ }blurEntity(prev);- focusManager.focus(entity);+ focusManager.focus(entity, visible);const f = world.get(entity, Focusable) as FocusableData;f.isFocused = true;world.insert(entity, Focusable, f);diff --git a/sdk/src/ui/input/focusable.ts b/sdk/src/ui/input/focusable.tsindex 531da3847..0f89fca0f 100644--- a/sdk/src/ui/input/focusable.ts+++ b/sdk/src/ui/input/focusable.ts@@ -23,17 +23,40 @@ export const Focusable = defineComponent<FocusableData>('Focusable', {export class FocusManagerState {focusedEntity: Entity | null = null;- focus(entity: Entity): Entity | null {+ /**+ * Whether the current focus should be SHOWN — the `:focus-visible` rule the web+ * arrived at, for the same reason.+ *+ * Focus follows a pointer press (so Enter/Space then act on what you clicked),+ * but a clicked control that keeps a focus highlight reads as stuck: the pointer+ * has moved on and the button is still lit, until you click something else. Only+ * keyboard-acquired focus is worth drawing, because only then is the highlight+ * the sole thing telling you where you are.+ *+ * Lives here rather than on {@link Focusable} because it is per-session input+ * state, like hover — authoring it into a scene would mean nothing.+ */+ focusVisible = false;++ /** `visible` = acquired by keyboard. Pointer presses pass false. */+ focus(entity: Entity, visible = false): Entity | null {const prev = this.focusedEntity;this.focusedEntity = entity;+ this.focusVisible = visible;return prev;}blur(): Entity | null {const prev = this.focusedEntity;this.focusedEntity = null;+ this.focusVisible = false;return prev;}++ /** Whether `entity` holds focus AND that focus should be drawn. */+ isVisiblyFocused(entity: Entity): boolean {+ return this.focusedEntity === entity && this.focusVisible;+ }}export const FocusManager = defineResource<FocusManagerState>(diff --git a/sdk/src/ui/theme/tokens.ts b/sdk/src/ui/theme/tokens.tsindex f61fff68d..2d4f73050 100644--- a/sdk/src/ui/theme/tokens.ts+++ b/sdk/src/ui/theme/tokens.ts@@ -23,6 +23,14 @@ export interface ThemeColors {control: Color;controlHover: Color;controlActive: Color;+ /**+ * Keyboard focus. A ROLE of its own rather than a reuse of `controlHover`,+ * because the two answer different questions — "the pointer is here" and "the+ * keyboard is here" — and a user tabbing through a form has nothing but this to+ * tell them where they are. Only ever shown for focus that arrived by keyboard+ * (see FocusManagerState.focusVisible).+ */+ controlFocus: Color;/** Slider / progress track. */track: Color;/** Accent — slider fill, progress fill, selected option. */@@ -40,7 +48,7 @@ export interface ThemeColors {/** Every color role, in display order — THE list a theme editor or a project* format validator iterates (keyof ThemeColors, as a runtime value). */export const THEME_COLOR_ROLES: readonly (keyof ThemeColors)[] = [- 'surface', 'surfaceElevated', 'control', 'controlHover', 'controlActive',+ 'surface', 'surfaceElevated', 'control', 'controlHover', 'controlActive', 'controlFocus','track', 'primary', 'primaryHover', 'primaryActive', 'onPrimary', 'text', 'backdrop',];@@ -70,6 +78,9 @@ export const DARK_TOKENS: ThemeTokens = {control: { r: 0.22, g: 0.22, b: 0.26, a: 1 },controlHover: { r: 0.28, g: 0.28, b: 0.32, a: 1 },controlActive: { r: 0.18, g: 0.18, b: 0.22, a: 1 },+ // Cooler than hover rather than merely lighter, so the two stay apart for a+ // reader who cannot rely on a small brightness step.+ controlFocus: { r: 0.30, g: 0.34, b: 0.44, a: 1 },track: { r: 0.15, g: 0.15, b: 0.15, a: 1 },primary: { r: 0.25, g: 0.56, b: 0.96, a: 1 },primaryHover: { r: 0.30, g: 0.50, b: 0.90, a: 1 },@@ -89,6 +100,7 @@ export const LIGHT_TOKENS: ThemeTokens = {control: { r: 0.90, g: 0.90, b: 0.92, a: 1 },controlHover: { r: 0.84, g: 0.84, b: 0.87, a: 1 },controlActive: { r: 0.78, g: 0.78, b: 0.82, a: 1 },+ controlFocus: { r: 0.80, g: 0.85, b: 0.95, a: 1 },track: { r: 0.86, g: 0.86, b: 0.88, a: 1 },primary: { r: 0.20, g: 0.52, b: 0.92, a: 1 },primaryHover: { r: 0.26, g: 0.58, b: 0.96, a: 1 },diff --git a/sdk/src/ui/widgets/button.ts b/sdk/src/ui/widgets/button.tsindex ac9476ad3..f169d9ed1 100644--- a/sdk/src/ui/widgets/button.ts+++ b/sdk/src/ui/widgets/button.ts@@ -68,7 +68,7 @@ export function themeButtonStates(): Record<string, ButtonStateVisual> {pressed: { color: c.controlActive },disabled: { color: { ...c.control, a: c.control.a * 0.5 } },// Keyboard focus reads as hover — there is no ring primitive (yet).- focused: { color: c.controlHover },+ focused: { color: c.controlFocus },};}@@ -113,7 +113,7 @@ export function createButton(opts: ButtonOptions): ButtonHandle {markThemed(world, entity, {states: {normal: 'control', hover: 'controlHover', pressed: 'controlActive',- disabled: 'control', focused: 'controlHover',+ disabled: 'control', focused: 'controlFocus',},});}diff --git a/sdk/src/ui/widgets/prefabs/Button.esprefab b/sdk/src/ui/widgets/prefabs/Button.esprefabindex b7073abd9..e43327f93 100644--- a/sdk/src/ui/widgets/prefabs/Button.esprefab+++ b/sdk/src/ui/widgets/prefabs/Button.esprefab@@ -221,9 +221,9 @@"a": 0.5},"focused": {- "r": 0.28,- "g": 0.28,- "b": 0.32,+ "r": 0.3,+ "g": 0.34,+ "b": 0.44,"a": 1}}@@ -239,7 +239,7 @@"hover": "controlHover","pressed": "controlActive","disabled": "control",- "focused": "controlHover"+ "focused": "controlFocus"}}}diff --git a/sdk/src/ui/widgets/prefabs/Toggle.esprefab b/sdk/src/ui/widgets/prefabs/Toggle.esprefabindex 2dd2f73d8..027eb29b5 100644--- a/sdk/src/ui/widgets/prefabs/Toggle.esprefab+++ b/sdk/src/ui/widgets/prefabs/Toggle.esprefab@@ -221,9 +221,9 @@"a": 0.5},"focused": {- "r": 0.28,- "g": 0.28,- "b": 0.32,+ "r": 0.3,+ "g": 0.34,+ "b": 0.44,"a": 1}}@@ -239,7 +239,7 @@"hover": "controlHover","pressed": "controlActive","disabled": "control",- "focused": "controlHover"+ "focused": "controlFocus"}}},diff --git a/sdk/src/ui/widgets/prefabs/generated.ts b/sdk/src/ui/widgets/prefabs/generated.tsindex 601377e08..2ed991f17 100644--- a/sdk/src/ui/widgets/prefabs/generated.ts+++ b/sdk/src/ui/widgets/prefabs/generated.ts@@ -225,9 +225,9 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {"a": 0.5},"focused": {- "r": 0.28,- "g": 0.28,- "b": 0.32,+ "r": 0.3,+ "g": 0.34,+ "b": 0.44,"a": 1}}@@ -243,7 +243,7 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {"hover": "controlHover","pressed": "controlActive","disabled": "control",- "focused": "controlHover"+ "focused": "controlFocus"}}}@@ -638,9 +638,9 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {"a": 0.5},"focused": {- "r": 0.28,- "g": 0.28,- "b": 0.32,+ "r": 0.3,+ "g": 0.34,+ "b": 0.44,"a": 1}}@@ -656,7 +656,7 @@ export const BUILTIN_UI_PREFABS: Record<string, PrefabData> = {"hover": "controlHover","pressed": "controlActive","disabled": "control",- "focused": "controlHover"+ "focused": "controlFocus"}}},diff --git a/sdk/tests/ui-focus-plugin.test.ts b/sdk/tests/ui-focus-plugin.test.tsindex 15bd35aa9..f30615a70 100644--- a/sdk/tests/ui-focus-plugin.test.ts+++ b/sdk/tests/ui-focus-plugin.test.ts@@ -130,3 +130,55 @@ describe('FocusPlugin pointer focus', () => {expect(isFocused(b)).toBe(true);});});++// — :focus-visible ————————————————————————————————————————————————————————————+//+// Focus follows a pointer press so Enter/Space act on what you clicked. But a+// clicked control that KEEPS a focus look reads as stuck — the pointer has moved+// on and the button is still lit until you click something else. So focus tracks+// how it arrived, and only keyboard focus is drawn.++const visible = (): boolean => app.getResource(FocusManager).focusVisible;++describe('focus visibility', () => {+ it('is off for pointer focus, on for Tab', async () => {+ const e = app.world.spawn();+ app.world.insert(e, Focusable, { tabIndex: 0, isFocused: false });+ app.world.insert(e, UIInteraction, { justPressed: true });+ await app.tick(1 / 60);+ expect(focused()).toBe(e);+ expect(visible()).toBe(false); // focused, but not drawn++ app.world.insert(e, UIInteraction, { justPressed: false });+ await tab();+ expect(visible()).toBe(true);+ });++ it('starts drawing when Tab lands on a control that was clicked', async () => {+ // The re-focus path: same entity, different acquisition. Focus does not move,+ // so an early return that skipped the update would leave it invisible forever.+ const e = addFocusable(0);+ app.world.insert(e, UIInteraction, { justPressed: true });+ await app.tick(1 / 60);+ expect(focused()).toBe(e);+ expect(visible()).toBe(false);++ app.world.insert(e, UIInteraction, { justPressed: false });+ await tab(); // only one focusable → Tab wraps back to it+ expect(focused()).toBe(e);+ expect(visible()).toBe(true);+ });++ it('stops being visible once focus is dropped', async () => {+ addFocusable(0);+ await tab();+ expect(visible()).toBe(true);++ const input = app.getResource(Input) as InputState;+ input.keysPressed.add('Escape');+ await app.tick(1 / 60);+ input.keysPressed.delete('Escape');+ expect(focused()).toBeNull();+ expect(visible()).toBe(false);+ });+});diff --git a/sdk/tests/ui-systems.test.ts b/sdk/tests/ui-systems.test.tsindex b48b62d01..3236defe9 100644--- a/sdk/tests/ui-systems.test.ts+++ b/sdk/tests/ui-systems.test.ts@@ -22,6 +22,18 @@ describe('driverStateFor', () => {expect(driverStateFor(true, inter(true, false))).toBe('hover');});+ it('shows "focused" only for VISIBLE focus, and never over pointer state', () => {+ // The third argument is `:focus-visible`, not "has focus". A pointer press+ // focuses too, and a button that keeps the focus look after a click stays+ // lit long after the pointer has gone — which is what this ranking prevents.+ expect(driverStateFor(true, inter(false, false), true)).toBe('focused');+ expect(driverStateFor(true, inter(false, false), false)).toBe('normal');+ // Pointer state still wins while the pointer is actually there.+ expect(driverStateFor(true, inter(true, false), true)).toBe('hover');+ expect(driverStateFor(true, inter(true, true), true)).toBe('pressed');+ expect(driverStateFor(false, inter(false, false), true)).toBe('disabled');+ });+it('returns "normal" when idle or no interaction data', () => {expect(driverStateFor(true, inter(false, false))).toBe('normal');expect(driverStateFor(true, null)).toBe('normal');