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.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.esprefab
index 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.esprefab
index 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.ts
index 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.ts
index 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.ts
index 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');