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.

13.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  FocusPlugin's keyboard + pointer focus, driven through a mock-wasm App
 *        (see tests/helpers/mockApp). The mock backs the builtin Interactable /
 *        UIInteraction fields in JS, so the enabled-gating and click-to-focus
 *        branches — unreachable without a connected module — are covered here
 *        alongside the pure Tab navigation. FocusSystem is playModeOnly, which
 *        the harness satisfies.
 */
import { describe, it, expect, beforeEach } from 'vitest';
import { flushPendingRegistrations } from '../src/app/app';
import type { App } from '../src/app/app';
import { Input, InputState, inputEventCallbacks } from '../src/input/input';
import { UIEvents, UIEventQueue } from '../src/ui/core/events';
import { Focusable, FocusManager } from '../src/ui/input/focusable';
import { Interactable, UIInteraction } from '../src/ui/input/interactable';
import { focusPlugin } from '../src/ui/input/focus';
import { setEditorMode } from '../src/ecs/env';
import { UIDialog } from '../src/ui/behavior/dialog';
import { UINode } from '../src/ui/core/ui-node';
import { TextInput } from '../src/ui/text/text-input';
import { bootMockApp } from './helpers/mockApp';
import type { Entity } from '../src/types';

let app: App;

beforeEach(() => {
  app = bootMockApp().app;
  app.insertResource(Input, new InputState());   // fresh, so key state can't leak between tests
  app.insertResource(UIEvents, new UIEventQueue());
  focusPlugin.build(app); // registers Focusable, inserts a fresh FocusManager, adds FocusSystem
  flushPendingRegistrations(app);
});

/** A focusable entity. `enabled` drives the (builtin) Interactable gate. */
function addFocusable(tabIndex: number, enabled = true): Entity {
  const e = app.world.spawn();
  app.world.insert(e, Focusable, { tabIndex, isFocused: false });
  app.world.insert(e, Interactable, { enabled });
  return e;
}

async function tab(opts: { shift?: boolean } = {}): Promise<void> {
  const input = app.getResource(Input) as InputState;
  input.keysPressed.add('Tab');
  if (opts.shift) input.keysDown.add('Shift');
  await app.tick(1 / 60);
  input.keysPressed.delete('Tab');
  if (opts.shift) input.keysDown.delete('Shift');
}

const focused = (): Entity | null => app.getResource(FocusManager).focusedEntity;
const isFocused = (e: Entity): boolean =>
  (app.world.get(e, Focusable) as { isFocused: boolean }).isFocused;

describe('FocusPlugin Tab navigation', () => {
  it('focuses the lowest tabIndex first, then advances in tabIndex order', async () => {
    const b = addFocusable(20); // inserted first, but higher tabIndex
    const a = addFocusable(10);
    const c = addFocusable(30);

    await tab();
    expect(focused()).toBe(a); // sorted by tabIndex, not spawn order
    expect(isFocused(a)).toBe(true);

    await tab();
    expect(focused()).toBe(b);
    expect(isFocused(a)).toBe(false); // previous entity blurred
    expect(isFocused(b)).toBe(true);

    await tab();
    expect(focused()).toBe(c);
  });

  it('wraps from the last focusable back to the first', async () => {
    const a = addFocusable(0);
    addFocusable(1);
    await tab(); // → a
    await tab(); // → second
    await tab(); // → wraps to a
    expect(focused()).toBe(a);
  });

  it('Shift+Tab walks the order in reverse, starting from the last entry', async () => {
    const a = addFocusable(0);
    const b = addFocusable(1);
    await tab({ shift: true }); // no current focus + reverse ⇒ last
    expect(focused()).toBe(b);
    await tab({ shift: true });
    expect(focused()).toBe(a);
  });

  it('re-focusing the already-focused entity is a no-op', async () => {
    const only = addFocusable(0);
    await tab();
    await tab(); // single focusable ⇒ stays on itself
    expect(focused()).toBe(only);
    expect(isFocused(only)).toBe(true);
  });

  it('skips a focusable whose Interactable is disabled', async () => {
    const a = addFocusable(0);
    addFocusable(1, /* enabled */ false); // out of the tab order
    const c = addFocusable(2);
    await tab();
    expect(focused()).toBe(a);
    await tab();
    expect(focused()).toBe(c); // jumps over the disabled one
  });
});

describe('FocusPlugin pointer focus', () => {
  it('a justPressed UIInteraction focuses that entity', 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(isFocused(e)).toBe(true);
  });

  it('moving focus by click blurs the previously focused entity', async () => {
    const a = addFocusable(0);
    await tab();
    expect(focused()).toBe(a);

    const b = app.world.spawn();
    app.world.insert(b, Focusable, { tabIndex: 5, isFocused: false });
    app.world.insert(b, UIInteraction, { justPressed: true });
    await app.tick(1 / 60);
    expect(focused()).toBe(b);
    expect(isFocused(a)).toBe(false); // a was blurred
    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);
  });
});


describe('FocusPlugin browser default policy', () => {
  it.each(['ShiftLeft', 'ShiftRight'])('reverses using the real DOM %s code', async (code) => {
    const a = addFocusable(0);
    const b = addFocusable(1);
    const input = app.getResource(Input);
    input.keysDown.add(code);
    await tab();
    expect(focused()).toBe(b);
    await tab();
    expect(focused()).toBe(a);
  });

  it('claims Tab only with eligible controls and releases the policy on cleanup', () => {
    const callbacks = inputEventCallbacks(app.getResource(Input));
    expect(callbacks.onKeyDown('Tab')).toBe(false);
    addFocusable(0, false);
    expect(callbacks.onKeyDown('Tab')).toBe(false);
    addFocusable(1);
    expect(callbacks.onKeyDown('Tab')).toBe(true);
    expect(app.getResource(Input).keysPressed.has('Tab')).toBe(true);
    app.setPaused(true);
    expect(callbacks.onKeyDown('Tab')).toBe(false);
    app.setPaused(false);
    focusPlugin.cleanup(app);
    expect(callbacks.onKeyDown('Tab')).toBe(false);
  });

  it('claims activation only for a valid eligible focus', async () => {
    const callbacks = inputEventCallbacks(app.getResource(Input));
    const entity = addFocusable(0);
    expect(callbacks.onKeyDown('Enter')).toBe(false);
    await tab();
    expect(callbacks.onKeyDown('Enter')).toBe(true);
    expect(callbacks.onKeyDown('Space')).toBe(true);
    app.world.despawn(entity);
    expect(callbacks.onKeyDown('Enter')).toBe(false);
  });
});


it('retains Shift at the Tab edge when the whole chord ends before a frame', async () => {
  addFocusable(0);
  const last = addFocusable(1);
  const input = app.getResource(Input);
  input.noteKeyDown('ShiftLeft');
  input.noteKeyDown('Tab');
  input.noteKeyUp('Tab');
  input.noteKeyUp('ShiftLeft');
  await app.tick(1 / 60);
  expect(focused()).toBe(last);
});


it('does not claim keys in edit mode or activation for a text field', async () => {
  const entity = addFocusable(0);
  const callbacks = inputEventCallbacks(app.getResource(Input));
  setEditorMode(true);
  expect(callbacks.onKeyDown('Tab')).toBe(false);
  setEditorMode(false);
  await tab();
  app.world.insert(entity, TextInput, {});
  expect(callbacks.onKeyDown('Enter')).toBe(false);
  expect(callbacks.onKeyDown('Space')).toBe(false);
  expect(callbacks.onKeyDown('Tab')).toBe(true);
});

it('does not reuse a released Shift for the next frame Tab', async () => {
  const first = addFocusable(0);
  addFocusable(1);
  const input = app.getResource(Input);
  input.noteKeyDown('ShiftRight');
  input.noteKeyDown('Tab');
  input.noteKeyUp('Tab');
  input.noteKeyUp('ShiftRight');
  await app.tick(1 / 60);
  input.clearFrameState();
  input.noteKeyDown('Tab');
  await app.tick(1 / 60);
  expect(focused()).toBe(first);
});


describe('dynamic focus eligibility', () => {
  it('blurs a newly disabled focused control and cannot activate it', async () => {
    const entity = addFocusable(0);
    await tab();
    const events = app.getResource(UIEvents);
    let clicks = 0, blurs = 0;
    events.on(entity, 'click', () => clicks++);
    events.on(entity, 'blur', () => blurs++);
    app.world.insert(entity, Interactable, { enabled: false });
    app.getResource(Input).keysPressed.add('Enter');
    await app.tick(1 / 60);
    expect(focused()).toBe(null);
    expect(isFocused(entity)).toBe(false);
    expect(blurs).toBe(1);
    expect(clicks).toBe(0);
  });

  it('opening a dialog clears background focus before keyboard activation', async () => {
    const background = addFocusable(0);
    await tab();
    const dialog = app.world.spawn();
    app.world.insert(dialog, UINode, {});
    app.world.insert(dialog, UIDialog, {});
    const confirm = addFocusable(1);
    app.world.setParent(confirm, dialog);
    const events = app.getResource(UIEvents);
    let clicks = 0;
    events.on(background, 'click', () => clicks++);
    app.getResource(Input).keysPressed.add('Space');
    await app.tick(1 / 60);
    expect(focused()).toBe(null);
    expect(isFocused(background)).toBe(false);
    expect(clicks).toBe(0);
    app.getResource(Input).clearFrameState();
    await tab();
    expect(focused()).toBe(confirm);
  });

  it('cannot move pointer focus to a background entity outside a dialog', async () => {
    const background = addFocusable(0);
    const dialog = app.world.spawn();
    app.world.insert(dialog, UINode, {});
    app.world.insert(dialog, UIDialog, {});
    app.world.insert(background, UIInteraction, { justPressed: true });
    await app.tick(1 / 60);
    expect(focused()).toBe(null);
  });

  it('clears focus when the Focusable component is removed', async () => {
    const entity = addFocusable(0);
    await tab();
    app.world.remove(entity, Focusable);
    await app.tick(1 / 60);
    expect(focused()).toBe(null);
    expect(app.getResource(FocusManager).focusVisible).toBe(false);
  });
});


it('rechecks eligibility after a synchronous focus handler opens a dialog', async () => {
  const background = addFocusable(0);
  const dialog = app.world.spawn();
  app.world.insert(dialog, UINode, {});
  let clicks = 0;
  app.getResource(UIEvents).on(background, 'focus', () => app.world.insert(dialog, UIDialog, {}));
  app.getResource(UIEvents).on(background, 'click', () => clicks++);
  app.world.insert(background, UIInteraction, { justPressed: true });
  app.getResource(Input).keysPressed.add('Enter');
  await app.tick(1 / 60);
  expect(focused()).toBe(null);
  expect(clicks).toBe(0);
});

it('does not focus a target deleted by the previous control blur callback', async () => {
  const first = addFocusable(0), next = addFocusable(1);
  await tab();
  app.getResource(UIEvents).on(first, 'blur', () => app.world.despawn(next));
  await tab();
  expect(focused()).toBe(null);
});

it('rechecks modal eligibility after the previous control blur callback', async () => {
  const first = addFocusable(0), next = addFocusable(1);
  const dialog = app.world.spawn(); app.world.insert(dialog, UINode, {});
  await tab();
  app.getResource(UIEvents).on(first, 'blur', () => app.world.insert(dialog, UIDialog, {}));
  await tab();
  expect(focused()).toBe(null);
  expect(isFocused(next)).toBe(false);
});

it('clears focus immediately when the focus callback destroys its control', async () => {
  const entity = addFocusable(0);
  app.getResource(UIEvents).on(entity, 'focus', () => app.world.despawn(entity));
  await tab();
  expect(focused()).toBe(null);
});

it('reports cleared manager state to blur callbacks before focusing the next control', async () => {
  const first = addFocusable(0), next = addFocusable(1);
  await tab();
  const observed: (Entity | null)[] = [];
  app.getResource(UIEvents).on(first, 'blur', () => observed.push(focused()));
  await tab();
  expect(observed).toEqual([null]);
  expect(focused()).toBe(next);
});