@caperjs/core 0.2.2 → 0.2.4

package/src/plugins/i18nPlugin.ts

@@ -17,6 +17,17 @@ export type LocaleKey = AppTypeOverrides extends { LocaleKeys: infer K extends s
   ? K | (string & {})
   : string;
 
+/**
+ * Base keys that have plural leaves (i.e. a `<base>.other` entry exists in the
+ * reference locale). These are the keys `tCount()` accepts.
+ *
+ * `(string & {})` preserves autocomplete for known keys while still
+ * accepting dynamic strings.
+ */
+export type PluralLocaleKey = AppTypeOverrides extends { LocaleKeys: infer K extends string }
+  ? (K extends `${infer B}.other` ? B : never) | (string & {})
+  : string;
+
 /**
  * Type definition for i18n dictionary.
  */
@@ -73,6 +84,8 @@ export interface Ii18nPlugin extends IPlugin {
 
   t(key: LocaleKey, params?: i18nTParams, locale?: string): string;
 
+  tCount(key: PluralLocaleKey, count: number, params?: i18nTParams, locale?: string): string;
+
   parse(input: string, locale?: string): string;
 }
 
@@ -152,10 +165,13 @@ export class i18nPlugin extends Plugin<i18nOptions> implements Ii18nPlugin {
 
   /**
    * Translates a key into a string.
-   * If the key is not found, it will return an empty string.
+   * If the key is not found (or no dictionary is loaded), it returns the key itself, so a typo
+   * renders visibly on screen instead of blanking the UI.
    * If the key is found, it will replace any placeholders in the string with the values from the params object.
-   * If the key contains a variant, it will select a random variant if the variant param is set to 'random'.
-   * If the key contains a number variant, it will select the variant based on the variant param.
+   * Every `[a|b|c]` group in the string is resolved, whether or not params were passed:
+   * `variant: 'random'` picks a random item per group, `variant: <number>` picks that index for every
+   * group (clamped to the group's last item), and with no variant param index 0 is used. Brackets never
+   * survive into the output.
    * @param key The key to translate.
    * @param params The parameters to replace in the string.
    * @param locale The locale to use for translation.
@@ -166,7 +182,7 @@ export class i18nPlugin extends Plugin<i18nOptions> implements Ii18nPlugin {
     const dict = this._dicts[locale];
     if (!dict) {
       Logger.error(`i18n:: No dictionary loaded for current locale: ${locale}`);
-      return '';
+      return key as string;
     }
     // Dot-path resolution: `t('obj.nested')` walks the dict tree. Flat keys
     // still work (including keys that literally contain dots, via the
@@ -176,24 +192,26 @@ export class i18nPlugin extends Plugin<i18nOptions> implements Ii18nPlugin {
 
     if (!str) {
       Logger.error(`i18n:: No result found for the key ${key} in the locale: ${this._locale}`);
-      return '';
+      return key as string;
     }
 
-    if (params) {
-      if (typeof params.variant === 'number' || params.variant === 'random') {
-        const match = /\[(.*?)\]/.exec(str);
-        if (match) {
-          // Split the string by the "|" character to get an array of variations.
-          const items = match[1].split('|');
-
-          // Get the selected variant based on the "variation" param.
-          const num = params.variant === 'random' ? Math.floor(Math.random() * items.length) : params.variant;
+    // Resolve every `[a|b|c]` group, whether or not params were passed, so brackets
+    // never leak into the rendered string.
+    const variant = params?.variant;
+    str = str.replace(/\[(.*?)\]/g, (_match, group: string) => {
+      // Split the group by the "|" character to get an array of variations.
+      const items = group.split('|');
 
-          // Replace the original string with the selected variant
-          str = str.replace(match[0], items[num]);
-        }
+      if (variant === 'random') {
+        return items[Math.floor(Math.random() * items.length)];
       }
 
+      // A number picks that index for every group, clamped to the group's last item.
+      const num = typeof variant === 'number' ? Math.min(Math.max(variant, 0), items.length - 1) : 0;
+      return items[num];
+    });
+
+    if (params) {
       // Iterate over all params to replace placeholders in the string.
       for (const f in params) {
         // Create a regular expression to match the placeholder for the current param.
@@ -221,6 +239,27 @@ export class i18nPlugin extends Plugin<i18nOptions> implements Ii18nPlugin {
     return this.t(key, params, locale);
   }
 
+  /**
+   * Translates a pluralised key using the locale's own plural rules.
+   * The CLDR plural category for `count` (`one`, `other`, `few`, ...) is resolved against
+   * `<key>.<category>`, falling back to `<key>.other` when that leaf does not exist.
+   * `count` is passed through as a param, so `{count}` interpolates and variants still apply.
+   * @param key The base key holding the plural leaves.
+   * @param count The count used to pick the plural category.
+   * @param params Additional parameters to replace in the string.
+   * @param locale The locale to use for translation.
+   * @returns The translated string.
+   */
+  tCount(key: PluralLocaleKey, count: number, params?: i18nTParams, locale: string = this._locale): string {
+    const category = new Intl.PluralRules(locale).select(count);
+    const dict = this._dicts[locale];
+    let pluralKey = `${key}.${category}`;
+    if (!dict || typeof resolveLocalePath(dict, pluralKey) !== 'string') {
+      pluralKey = `${key}.other`;
+    }
+    return this.t(pluralKey, { count, ...params }, locale);
+  }
+
   /**
    * Parses the input string and replaces anything in between {} braces, assuming it is a key in the dictionary.
    * @param {string} input
@@ -263,7 +302,7 @@ export class i18nPlugin extends Plugin<i18nOptions> implements Ii18nPlugin {
   }
 
   protected getCoreFunctions(): string[] {
-    return ['t', 'translate', 'setLocale'];
+    return ['t', 'translate', 'tCount', 'setLocale'];
   }
 
   protected getCoreSignals(): string[] {

package/src/plugins/input/keyboard/KeyboardContols.ts

@@ -1,5 +1,5 @@
 import { Application } from '../../../core/Application';
-import { WithSignals } from '../../../mixins';
+import { WithSignals } from '../../../mixins/signals';
 import { bindAllMethods } from '../../../utils';
 import type { Action } from '../../actions';
 import { normalizeKey, type KeyboardEventDetail } from '../../KeyboardPlugin';

package/src/plugins/input/touch/VirtualControls.ts

@@ -3,8 +3,8 @@ import type { ControlsActionMap, JoystickControlsScheme, TouchControlsMap, Touch
 
 import { JoystickDirection } from '..';
 import { Application } from '../../../core/Application';
-import { WithSignals } from '../../../mixins';
-import { type IButton, type IJoystick } from '../../../ui';
+import { WithSignals } from '../../../mixins/signals';
+import type { IButton, IJoystick } from '../../../ui';
 import type { Action } from '../../actions';
 import { AbstractControls } from '../AbstractControls';
 

package/src/plugins/spine/pixi-spine/require-shim.ts

@@ -28,7 +28,9 @@
  *****************************************************************************/
 
 declare global {
-  var require: any;
+  // @types/node (present via typeRoots) already declares `require: Require`;
+  // redeclaring it as `any` is a TS2403 conflict, so declare only what node
+  // doesn't, and keep the shim's loose typing at the use sites below.
   var PIXI: any;
 }
 

package/src/ui/Button.test.ts

@@ -0,0 +1,236 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// Button transitively imports Application → Pixi display graph. Stub it — these
+// tests drive the press-state machine directly and never touch the app singleton.
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => ({}) },
+}));
+
+import { Button } from './Button';
+import { Signal } from '../signals';
+
+/**
+ * Builds a Button instance without running the real constructor (which drags in
+ * Factory/Interactive/Focusable mixin construction and a real Pixi Sprite). Only
+ * the fields the handlers under test actually touch are hand-initialized.
+ */
+function makeButton() {
+  const button = Object.create(Button.prototype) as Button;
+
+  // Pixi's Container (via eventemitter3) normally initializes these in its own
+  // constructor, which this hand-rolled instance never runs; `on`/`off` throw
+  // without them.
+  (button as any)._events = Object.create(null);
+  (button as any)._eventsCount = 0;
+
+  (button as any).config = {
+    id: 'button',
+    textures: { default: '' },
+    sheet: undefined,
+    enabled: true,
+    cursor: 'default',
+    disabledCursor: 'not-allowed',
+  };
+
+  (button as any)._enabled = true;
+  button.isDown = false;
+  button.isOver = false;
+  (button as any)._pointerId = undefined;
+  (button as any).isKeyDown = false;
+  (button as any).cursor = 'default';
+  (button as any).focusEnabled = true;
+
+  (button as any).view = { texture: undefined };
+  (button as any).make = { texture: vi.fn(() => 'texture') };
+  (button as any)._isDownCallbacks = new Map();
+  (button as any)._isDownListenerAdded = false;
+
+  button.onDown = new Signal();
+  button.onUp = new Signal();
+  button.onUpOutside = new Signal();
+  button.onOut = new Signal();
+  button.onOver = new Signal();
+  button.onClick = new Signal();
+  button.onEnabled = new Signal();
+  button.onDisabled = new Signal();
+  button.onKeyboardEvent = new Signal();
+  button.onDestroy = new Signal();
+
+  return button;
+}
+
+describe('Button press-state machine', () => {
+  it('recovers from a press that is disabled mid-press', () => {
+    const button = makeButton();
+    const onDown = vi.fn();
+    button.onDown.connect(onDown);
+
+    (button as any).handlePointerDown({ pointerId: 1 });
+    expect(button.isDown).toBe(true);
+
+    button.enabled = false;
+    expect(button.isDown).toBe(false);
+    expect((button as any)._pointerId).toBeUndefined();
+
+    button.enabled = true;
+    (button as any).handlePointerDown({ pointerId: 2 });
+
+    expect(onDown).toHaveBeenCalledTimes(2);
+    expect(button.isDown).toBe(true);
+  });
+
+  it('clears press state on pointerupoutside while disabled and does not emit onUpOutside', () => {
+    const button = makeButton();
+    const onUpOutside = vi.fn();
+    button.onUpOutside.connect(onUpOutside);
+
+    // Arm a stale press, then disable without going through the enabled setter,
+    // to exercise the handler's own cleanup path directly.
+    button.isDown = true;
+    (button as any)._pointerId = 1;
+    (button as any)._enabled = false;
+
+    (button as any).handlePointerUpOutside({ pointerId: 1 });
+
+    expect(button.isDown).toBe(false);
+    expect((button as any)._pointerId).toBeUndefined();
+    expect(onUpOutside).not.toHaveBeenCalled();
+  });
+
+  it('removes the window pointerup listener on destroy', () => {
+    const button = makeButton();
+    (button as any).handlePointerDown({ pointerId: 1 });
+
+    // Stub out the real mixin chain's destroy() (Focusable → Interactive →
+    // WithSignals → Factory → real Pixi Container.destroy) so this test isolates
+    // Button.destroy()'s own added cleanup without needing a fully-constructed
+    // Container underneath.
+    const superDestroy = vi
+      .spyOn(Object.getPrototypeOf(Button.prototype), 'destroy')
+      .mockImplementation(() => {});
+    const removeSpy = vi.spyOn(window, 'removeEventListener');
+
+    button.destroy();
+
+    expect(removeSpy).toHaveBeenCalledWith('pointerup', (button as any).handlePointerUpOutside);
+    expect(superDestroy).toHaveBeenCalled();
+    expect(button.isDown).toBe(false);
+    expect((button as any)._pointerId).toBeUndefined();
+
+    removeSpy.mockRestore();
+    superDestroy.mockRestore();
+  });
+
+  it('does not click after a cancelled press (disabled then re-enabled)', () => {
+    const button = makeButton();
+    const onClick = vi.fn();
+    button.onClick.connect(onClick);
+
+    (button as any).handlePointerDown({ pointerId: 1 });
+    button.enabled = false;
+    button.enabled = true;
+
+    // A real pointer-driven click event carries the same pointerId as the press.
+    (button as any).handleClick({ pointerId: 1 });
+
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  it('clicks normally after a press', () => {
+    const button = makeButton();
+    const onClick = vi.fn();
+    button.onClick.connect(onClick);
+
+    (button as any).handlePointerDown({ pointerId: 1 });
+    (button as any).handleClick({ pointerId: 1 });
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('still clicks for a synthetic keyboard activation (no pointerId)', () => {
+    const button = makeButton();
+    const onClick = vi.fn();
+    button.onClick.connect(onClick);
+
+    // Mimics FocusManagerPlugin's synthetic pointerdown on Enter/Space keydown.
+    (button as any).handlePointerDown({ type: 'pointerdown' });
+    (button as any).handleClick();
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('fires onClick exactly once for a single accessibility activation delivered as click+tap', () => {
+    const button = makeButton();
+    const onClick = vi.fn();
+    button.onClick.connect(onClick);
+
+    // AccessibilitySystem dispatches ONE shared FederatedEvent instance as both
+    // 'click' and 'tap' — Button connects both to handleClick.
+    const a11yEvent = { type: 'click' };
+    (button as any).handleClick(a11yEvent);
+    (button as any).handleClick(a11yEvent);
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('suppresses a cancelled pointer-driven click even without a prior press in this test', () => {
+    const button = makeButton();
+    const onClick = vi.fn();
+    button.onClick.connect(onClick);
+
+    // isDown is false (no press) — a click event carrying a pointerId must be treated
+    // as a cancelled press and suppressed.
+    (button as any).handleClick({ pointerId: 5 });
+
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  it('fires onClick for each of two distinct accessibility activations', () => {
+    const button = makeButton();
+    const onClick = vi.fn();
+    button.onClick.connect(onClick);
+
+    (button as any).handleClick({ type: 'click' });
+    (button as any).handleClick({ type: 'click' });
+
+    expect(onClick).toHaveBeenCalledTimes(2);
+  });
+
+  it('toggles the ticker listener on for the first isDown callback and off when the last is removed', () => {
+    const button = makeButton();
+    const add = vi.fn();
+    const remove = vi.fn();
+    Object.defineProperty(button, 'app', { value: { ticker: { add, remove } }, configurable: true });
+
+    button.addIsDownCallback('a', () => {});
+    button.addIsDownCallback('b', () => {});
+
+    expect(add).toHaveBeenCalledTimes(1);
+    expect(remove).not.toHaveBeenCalled();
+
+    button.removeIsDownCallback('a');
+    expect(remove).not.toHaveBeenCalled();
+
+    button.removeIsDownCallback('b');
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+
+  it('removes the ticker listener on destroy when one is active', () => {
+    const button = makeButton();
+    const add = vi.fn();
+    const remove = vi.fn();
+    Object.defineProperty(button, 'app', { value: { ticker: { add, remove } }, configurable: true });
+
+    button.addIsDownCallback('a', () => {});
+
+    const superDestroy = vi
+      .spyOn(Object.getPrototypeOf(Button.prototype), 'destroy')
+      .mockImplementation(() => {});
+
+    button.destroy();
+
+    expect(remove).toHaveBeenCalledTimes(1);
+
+    superDestroy.mockRestore();
+  });
+});

package/src/ui/Button.ts

@@ -12,7 +12,11 @@ import {
 import { type LayoutOptions } from '@pixi/layout';
 import type { IApplication } from '../core';
 import { Application } from '../core/Application';
-import { Factory, Focusable, HTMLTextProps, Interactive, type TextProps, WithSignals } from '../mixins';
+import { Factory } from '../mixins/factory/Factory';
+import type { HTMLTextProps, TextProps } from '../mixins/factory/props';
+import { Focusable } from '../mixins/focus';
+import { Interactive } from '../mixins/interaction';
+import { WithSignals } from '../mixins/signals';
 import { Signal } from '../signals';
 import { AudioAsset, bindAllMethods, type SpritesheetAsset, type TextureAsset } from '../utils';
 
@@ -117,6 +121,7 @@ export class Button extends _Button implements IButton {
   private _isDownListenerAdded: boolean = false;
   private _pointerId?: number;
   private _textLabel?: Text | HTMLText | BitmapText;
+  private _lastClickEvent?: FederatedEvent;
 
   /**
    * The text label of the button.
@@ -186,6 +191,8 @@ export class Button extends _Button implements IButton {
       this.onInteraction('tap').connect(this.handleClick, -1),
       this.onInteraction('pointerdown').connect(this.handlePointerDown, -1),
     );
+
+    this.on('removed', this._resetPressState);
   }
 
   // enabled state
@@ -209,6 +216,7 @@ export class Button extends _Button implements IButton {
       });
       this.onEnabled.emit();
     } else {
+      this._resetPressState();
       this.view.texture = this.make.texture({
         asset: this.config.textures.disabled || this.config.textures.default,
         sheet: this.config.sheet ?? undefined,
@@ -217,6 +225,18 @@ export class Button extends _Button implements IButton {
     }
   }
 
+  /**
+   * Clears any in-progress press: removes the window-level release listener and
+   * resets press tracking. Called when the button is disabled, removed, or
+   * destroyed mid-press so a stale pointerId can't block future presses.
+   */
+  private _resetPressState() {
+    window.removeEventListener('pointerup', this.handlePointerUpOutside);
+    this.off('pointerupoutside', this.handlePointerUpOutside);
+    this.isDown = false;
+    this._pointerId = undefined;
+  }
+
   public addLabel<T extends Text | HTMLText | BitmapText>(
     config: (Partial<TextProps | HTMLTextProps> & { type?: 'text' | 'html' | 'bitmap' }) | T,
   ): T {
@@ -260,6 +280,11 @@ export class Button extends _Button implements IButton {
 
   destroy(options?: DestroyOptions) {
     this.onDestroy.emit();
+    this._resetPressState();
+    if (this._isDownListenerAdded) {
+      this.app.ticker.remove(this._handleIsDownCallbacks);
+      this._isDownListenerAdded = false;
+    }
     super.destroy(options);
   }
 
@@ -286,6 +311,7 @@ export class Button extends _Button implements IButton {
 
   removeIsDownCallback(callbackId: string) {
     this._isDownCallbacks.delete(callbackId);
+    this._checkIsDownCallbacks();
   }
 
   setTexture(textureId: ButtonTextureId, texture: TextureAsset) {
@@ -391,10 +417,20 @@ export class Button extends _Button implements IButton {
     this._pointerId = undefined;
   }
 
-  protected handleClick() {
+  protected handleClick(e?: FederatedEvent) {
     if (!this._enabled) {
       return;
     }
+    const pointerId = (e as FederatedPointerEvent | undefined)?.pointerId;
+    if (pointerId !== undefined && !this.isDown) {
+      // a pointer press that was cancelled (e.g. disabled mid-press) must not click
+      return;
+    }
+    if (e !== undefined && e === this._lastClickEvent) {
+      // accessibility dispatches one event instance as both 'click' and 'tap'
+      return;
+    }
+    this._lastClickEvent = e;
     this.isDown = false;
     this.onClick.emit();
     if (this.config.sounds?.click) {
@@ -409,17 +445,16 @@ export class Button extends _Button implements IButton {
    *  Handles the pointer up event.
    */
   protected handlePointerUpOutside(e: PointerEvent | FederatedPointerEvent) {
-    if (!this._enabled || e.pointerId !== this._pointerId) {
+    if (e.pointerId !== this._pointerId) {
       return;
     }
-    window.removeEventListener('pointerup', this.handlePointerUpOutside);
-    this.off('pointerupoutside', this.handlePointerUpOutside);
-    this.view.texture = this.make.texture({ asset: this.config.textures.default, sheet: this.config.sheet });
-    this.isDown = false;
+    const wasEnabled = this._enabled;
+    this._resetPressState();
     this.isOver = false;
-    this.onUpOutside.emit();
-
-    this._pointerId = undefined;
+    if (wasEnabled) {
+      this.view.texture = this.make.texture({ asset: this.config.textures.default, sheet: this.config.sheet });
+      this.onUpOutside.emit();
+    }
   }
 
   private _doAction(action: ButtonActionOrCallback) {
@@ -438,7 +473,7 @@ export class Button extends _Button implements IButton {
     if (!this._isDownListenerAdded && this._isDownCallbacks.size > 0) {
       this._isDownListenerAdded = true;
       this.app.ticker.add(this._handleIsDownCallbacks);
-    } else {
+    } else if (this._isDownListenerAdded && this._isDownCallbacks.size === 0) {
       this.app.ticker.remove(this._handleIsDownCallbacks);
       this._isDownListenerAdded = false;
     }

package/src/ui/FlexContainer.ts

@@ -1,8 +1,9 @@
 import type { LayoutOptions, NumberValue } from '@pixi/layout';
 import { BitmapText, Graphics, Container as PIXIContainer, Text } from 'pixi.js';
 import { Application } from '../core/Application';
-import { Container } from '../display';
-import { Factory, WithSignals } from '../mixins';
+import { Container } from '../display/Container';
+import { Factory } from '../mixins/factory/Factory';
+import { WithSignals } from '../mixins/signals';
 import { Signal } from '../signals';
 import {
   AppTypeOverrides,

package/src/ui/Input.ts

@@ -11,7 +11,10 @@ import {
   Texture,
 } from 'pixi.js';
 
-import { Focusable, Interactive, TextProps, WithSignals } from '../mixins';
+import type { TextProps } from '../mixins/factory/props';
+import { Focusable } from '../mixins/focus';
+import { Interactive } from '../mixins/interaction';
+import { WithSignals } from '../mixins/signals';
 
 import {
   EaseString,
@@ -27,7 +30,7 @@ import {
 } from '../utils';
 
 import { gsap } from 'gsap';
-import { Container } from '../display';
+import { Container } from '../display/Container';
 import { Signal } from '../signals';
 
 /**

package/src/ui/Joystick.ts

@@ -4,7 +4,7 @@
  * ported to TypeScript and adapted for Caper
  */
 import { DestroyOptions, FederatedPointerEvent, Graphics, Point, Sprite } from 'pixi.js';
-import { Container } from '../display';
+import { Container } from '../display/Container';
 import { JoystickDirection } from '../plugins';
 import { Signal } from '../signals';
 

package/src/ui/Toast.ts

@@ -1,7 +1,8 @@
 import { gsap } from 'gsap';
 import { Graphics, Text } from 'pixi.js';
 import { Container } from '../display/Container';
-import { type TextStyle, WithSignals } from '../mixins';
+import type { TextStyle } from '../mixins/factory/props';
+import { WithSignals } from '../mixins/signals';
 import { Signal } from '../signals';
 import { Button } from './Button';
 import { Toaster } from './Toaster';

package/src/ui/Toaster.ts

@@ -1,6 +1,6 @@
 import { gsap } from 'gsap';
 import { Container } from '../display/Container';
-import { WithSignals } from '../mixins';
+import { WithSignals } from '../mixins/signals';
 import { Signal } from '../signals';
 import { defaultToastConfig, Toast, ToastConfig } from './Toast';
 import { UICanvasEdge } from './UICanvas';

package/src/ui/UICanvas.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// UICanvas transitively imports Application → Pixi display graph. Stub it — the
+// pure padding helper needs none of it.
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => ({}) },
+}));
+
+import { computeEffectivePadding } from './UICanvas';
+
+const zero = { top: 0, right: 0, bottom: 0, left: 0 };
+
+describe('computeEffectivePadding', () => {
+  it('adds the safe area to the configured padding', () => {
+    expect(
+      computeEffectivePadding({ top: 10, right: 10, bottom: 10, left: 10 }, { ...zero, top: 44, bottom: 34 }),
+    ).toEqual({ top: 54, right: 10, bottom: 44, left: 10 });
+  });
+
+  it('returns the configured padding when there is no safe area', () => {
+    expect(computeEffectivePadding({ top: 10, right: 20, bottom: 30, left: 40 }, zero)).toEqual({
+      top: 10,
+      right: 20,
+      bottom: 30,
+      left: 40,
+    });
+  });
+
+  it('does not compound when applied repeatedly to the same base padding', () => {
+    const base = { top: 10, right: 10, bottom: 10, left: 10 };
+    const safeArea = { ...zero, top: 44 };
+    computeEffectivePadding(base, safeArea);
+    expect(computeEffectivePadding(base, safeArea).top).toBe(54);
+  });
+});