pixijs-input-devices 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -44,6 +44,24 @@ declare class GamepadJoystick {
 	/** A scalar -1.0 to 1.0 representing the Y-axis position on the stick */
 	get y(): number;
 }
+declare const ButtonCode: readonly [
+	"A",
+	"B",
+	"X",
+	"Y",
+	"LeftShoulder",
+	"RightShoulder",
+	"LeftTrigger",
+	"RightTrigger",
+	"Back",
+	"Start",
+	"LeftStick",
+	"RightStick",
+	"DPadUp",
+	"DPadDown",
+	"DPadLeft",
+	"DPadRight"
+];
 export declare abstract class CustomDevice {
 	readonly id: string;
 	readonly type = "custom";
@@ -65,21 +83,16 @@ export declare abstract class CustomDevice {
 export declare class GamepadDevice {
 	source: Gamepad;
 	static defaultOptions: {
-		binds: {
-			0: "trigger";
-			1: "navigateBack";
-			8: "navigateBack";
-			13: "navigateDown";
-			14: "navigateLeft";
-			15: "navigateRight";
-			12: "navigateUp";
-		};
-		joystickDeadzone: number;
+		navigationalBinds: Partial<Record<Button, NavigationIntent>>;
 		intent: {
 			joystickCommitSensitivity: number;
 			firstCooldownMs: number;
 			defaultCooldownMs: number;
 		};
+		vibration: {
+			enabled: boolean;
+			intensity: number;
+		};
 	};
 	/**
 	 * Globally unique identifier for this gamepad slot.
@@ -87,39 +100,24 @@ export declare class GamepadDevice {
 	 */
 	readonly id: string;
 	readonly type = "gamepad";
+	/**
+	 * Associate custom metadata with a device.
+	 */
+	meta: Record<string, any>;
+	lastUpdated: number;
 	/**
 	 * Platform of this gamepad, useful for configuring standard
 	 * button layouts or displaying branded icons.
 	 * @example "playstation"
 	 */
 	platform: GamepadPlatform;
-	lastUpdated: number;
-	/** Configurable metadata. */
-	assignee?: any;
-	options: {
-		binds: {
-			0: "trigger";
-			1: "navigateBack";
-			8: "navigateBack";
-			13: "navigateDown";
-			14: "navigateLeft";
-			15: "navigateRight";
-			12: "navigateUp";
-		};
-		joystickDeadzone: number;
-		intent: {
-			joystickCommitSensitivity: number;
-			firstCooldownMs: number;
-			defaultCooldownMs: number;
-		};
-	};
+	options: typeof GamepadDevice.defaultOptions;
 	private _btnPrevState;
 	private _axisIntents;
 	private readonly _throttleIdLeftStickX;
 	private readonly _throttleIdLeftStickY;
-	/** Left Joystick */
+	private readonly _emitter;
 	readonly leftJoystick: GamepadJoystick;
-	/** Right Joystick */
 	readonly rightJoystick: GamepadJoystick;
 	/** A scalar 0.0 to 1.0 representing the trigger pull */
 	get leftTrigger(): number;
@@ -129,29 +127,49 @@ export declare class GamepadDevice {
 	get leftShoulder(): number;
 	/** A scalar 0.0 to 1.0 representing the trigger pull */
 	get rightShoulder(): number;
-	/** Gamepad button accessors */
-	get button(): GamepadButtons;
-	/** Check whether a button is pressed */
-	pressing(button: Button): boolean;
-	/** Check whether all buttons in a group are pressed */
-	pressingAll(group: Button[]): boolean;
-	/** Check whether at least one button in a group is pressed */
-	pressingAny(group: Button[]): boolean;
+	/** Add an event listener */
+	on<K extends keyof GamepadDeviceEvent>(event: K, listener: (event: GamepadDeviceEvent[K]) => void): this;
+	/** Remove an event listener */
+	off<K extends keyof GamepadDeviceEvent>(event: K, listener: (event: GamepadDeviceEvent[K]) => void): this;
+	/** Accessors for buttons */
+	button: Record<ButtonCode, boolean>;
+	/**
+	 * Play a vibration effect (if supported).
+	 *
+	 * This API only works in browsers that support it.
+	 * @see https://caniuse.com/mdn-api_gamepad_vibrationactuator
+	 */
+	playVibration({ duration, weakMagnitude, strongMagnitude, vibrationType, rightTrigger, leftTrigger, startDelay, }?: GamepadVibration): void;
 	update(source: Gamepad, now: number): void;
 	clear(): void;
 	constructor(source: Gamepad);
 	private updatePresses;
 }
-export declare class InputDeviceManager {
-	static readonly shared: InputDeviceManager;
-	static readonly gamepadsApiSupported: boolean;
-	private hasFocus;
-	/** Global keyboard. These inputs are always up to date.. */
+export declare class InputDevice {
+	static readonly shared: InputDevice;
+	static keyboard: KeyboardDevice;
+	static gamepads: readonly GamepadDevice[];
+	static devices: readonly Device[];
+	static update: () => ReadonlyArray<Device>;
 	readonly keyboard: KeyboardDevice;
-	/** Connected gamepads. Keep in mind these inputs are only up-to-date from the last update(). */
+	private readonly _emitter;
+	/** Add an event listener */
+	on<K extends keyof InputDeviceEvent>(event: K, listener: (event: InputDeviceEvent[K]) => void): this;
+	/** Remove an event listener */
+	off<K extends keyof InputDeviceEvent>(event: K, listener: (event: InputDeviceEvent[K]) => void): this;
+	private hasFocus;
+	/**
+	 * Connected gamepads accessible by index.
+	 *
+	 * Keep in mind these inputs are only up-to-date from the last update().
+	 */
 	get gamepads(): readonly GamepadDevice[];
-	/** Connected devices. Keep in mind these inputs may only be up-to-date from the last update(). */
-	get devices(): readonly InputDevice[];
+	/**
+	 * Connected devices.
+	 *
+	 * Keep in mind these inputs may only be up-to-date from the last update().
+	 */
+	get devices(): readonly Device[];
 	options: {
 		clearInputInBackground: boolean;
 	};
@@ -162,11 +180,11 @@ export declare class InputDeviceManager {
 	/**
 	 * Performs a poll of latest input from all devices
 	 */
-	update(): ReadonlyArray<InputDevice>;
+	update(): ReadonlyArray<Device>;
 	/** Add a custom device. */
 	add(device: CustomDevice): void;
 	/** Remove a custom device. */
-	remove(device: InputDevice): void;
+	remove(device: Device): void;
 	/**
 	 * @returns updates connected gamepads, performing a poll of latest input
 	 */
@@ -174,41 +192,59 @@ export declare class InputDeviceManager {
 	private removeGamepad;
 }
 export declare class KeyboardDevice {
-	readonly id: "keyboard";
+	static global: KeyboardDevice;
 	readonly type: "keyboard";
-	layout: KeyboardLayout;
-	assignee?: any;
+	readonly id: "keyboard";
+	/**
+	 * Associate custom metadata with a device.
+	 */
+	meta: Record<string, any>;
 	lastUpdated: number;
-	static defaultOptions: {
-		binds: {
-			Enter: "trigger";
-			Escape: "navigateBack";
-			ArrowDown: "navigateDown";
-			ArrowLeft: "navigateLeft";
-			ArrowRight: "navigateRight";
-			ArrowUp: "navigateUp";
-		};
-	};
+	/**
+	 * Detect layout from keypresses.
+	 *
+	 * This will continuously check "keydown" events until the
+	 * layout can be determined.
+	 */
+	detectLayoutOnKeypress: boolean;
+	private _layout;
+	private _layoutSource;
+	private _emitter;
+	on<K extends keyof KeyboardDeviceEvent>(event: K, listener: (event: KeyboardDeviceEvent[K]) => void): this;
+	off<K extends keyof KeyboardDeviceEvent>(event: K, listener: (event: KeyboardDeviceEvent[K]) => void): this;
 	options: {
-		binds: {
-			0: "trigger";
-			1: "navigateBack";
-			8: "navigateBack";
-			13: "navigateDown";
-			14: "navigateLeft";
-			15: "navigateRight";
-			12: "navigateUp";
-		};
+		/**
+		 * Keys to prevent default event propagation for.
+		 */
+		preventDefaultKeys: Set<KeyCode>;
+		navigationBinds: Partial<Record<KeyCode, NavigationIntent>>;
 	};
-	configureEventListeners(): void;
+	private constructor();
+	/**
+	 * Keyboard Layout
+	 *
+	 * If not set manually, this is determined by the browser (in
+	 * browsers that support detection), otherwise layout is inferred
+	 * on keypress, or from device language.
+	 *
+	 * Supports the "big four": `"QWERTY"`, `"AZERTY"`, `"QWERTZ"`,
+	 * and `"JCUKEN"` - i.e. it does not include specialized layouts
+	 * (e.g. Dvorak, Colemak, BÉPO), or regional layouts (e.g. Hangeul,
+	 * Kana) etc.
+	 *
+	 * When not set explicitly, this is provided by the browser,
+	 * or detected by keystrokes, or finally inferred from the
+	 * browser's language.
+	 *
+	 * @example "JCUKEN"
+	 */
+	get layout(): KeyboardLayout;
+	set layout(value: KeyboardLayout);
+	/** How the keyboard layout was determined. */
+	get layoutSource(): KeyboardLayoutSource;
+	private configureEventListeners;
 	/** Accessors for keys */
 	key: Record<KeyCode, boolean>;
-	/** Check whether a key is pressed */
-	pressing(key: KeyCode): boolean;
-	/** Check whether all buttons in a group are pressed */
-	pressingAll(group: KeyCode[]): boolean;
-	/** Check whether at least one button in a group is pressed */
-	pressingAny(group: KeyCode[]): boolean;
 	/**
 	 * Get the label for the given key code in the current keyboard layout.
 	 *
@@ -237,6 +273,11 @@ export declare class Navigation {
 	 * navigation intents.
 	 */
 	stageRoot?: Container;
+	/**
+	 * When enabled, if no pointover/mouseover listeners
+	 * exist, a default effect will be used instead.
+	 */
+	fallbackEffects: boolean;
 	private _focused?;
 	private _responderStack;
 	private constructor();
@@ -252,7 +293,7 @@ export declare class Navigation {
 	 * Emit interaction intent to the first responder,
 	 * or the global responder if none.
 	 */
-	emit(intent: NavigationIntent, device: InputDevice): void;
+	commit(intent: NavigationIntent, device: Device): void;
 	/**
 	 * Remove the top-most global interaction target
 	 */
@@ -261,8 +302,11 @@ export declare class Navigation {
 	 * Set the new top-most global interaction target.
 	 */
 	pushResponder(responder: NavigationResponder): void;
-	private _propogateIntent;
+	private _propagateIntent;
 	private _handleGlobalIntent;
+	private _emitBlur;
+	private _emitFocus;
+	private _emitTrigger;
 }
 export declare const Button: {
 	/** A Button (Xbox / Nintendo: "A", PlayStation: "Cross") */
@@ -299,10 +343,73 @@ export declare const Button: {
 	readonly DPadRight: 15;
 };
 export declare const KeyCode: {
+	readonly AltLeft: "AltLeft";
+	readonly AltRight: "AltRight";
+	readonly ArrowDown: "ArrowDown";
 	readonly ArrowLeft: "ArrowLeft";
 	readonly ArrowRight: "ArrowRight";
 	readonly ArrowUp: "ArrowUp";
-	readonly ArrowDown: "ArrowDown";
+	readonly Backquote: "Backquote";
+	readonly Backslash: "Backslash";
+	readonly Backspace: "Backspace";
+	readonly BracketLeft: "BracketLeft";
+	readonly BracketRight: "BracketRight";
+	readonly CapsLock: "CapsLock";
+	readonly Comma: "Comma";
+	readonly ContextMenu: "ContextMenu";
+	readonly ControlLeft: "ControlLeft";
+	readonly ControlRight: "ControlRight";
+	readonly Delete: "Delete";
+	readonly Digit0: "Digit0";
+	readonly Digit1: "Digit1";
+	readonly Digit2: "Digit2";
+	readonly Digit3: "Digit3";
+	readonly Digit4: "Digit4";
+	readonly Digit5: "Digit5";
+	readonly Digit6: "Digit6";
+	readonly Digit7: "Digit7";
+	readonly Digit8: "Digit8";
+	readonly Digit9: "Digit9";
+	readonly End: "End";
+	readonly Enter: "Enter";
+	readonly Equal: "Equal";
+	readonly Escape: "Escape";
+	readonly F1: "F1";
+	readonly F10: "F10";
+	readonly F11: "F11";
+	readonly F12: "F12";
+	readonly F13: "F13";
+	readonly F14: "F14";
+	readonly F15: "F15";
+	readonly F16: "F16";
+	readonly F17: "F17";
+	readonly F18: "F18";
+	readonly F19: "F19";
+	readonly F2: "F2";
+	readonly F20: "F20";
+	readonly F21: "F21";
+	readonly F22: "F22";
+	readonly F23: "F23";
+	readonly F24: "F24";
+	readonly F25: "F25";
+	readonly F26: "F26";
+	readonly F27: "F27";
+	readonly F28: "F28";
+	readonly F29: "F29";
+	readonly F3: "F3";
+	readonly F30: "F30";
+	readonly F31: "F31";
+	readonly F32: "F32";
+	readonly F4: "F4";
+	readonly F5: "F5";
+	readonly F6: "F6";
+	readonly F7: "F7";
+	readonly F8: "F8";
+	readonly F9: "F9";
+	readonly Home: "Home";
+	readonly IntlBackslash: "IntlBackslash";
+	readonly IntlRo: "IntlRo";
+	readonly IntlYen: "IntlYen";
 	readonly KeyA: "KeyA";
 	readonly KeyB: "KeyB";
 	readonly KeyC: "KeyC";
@@ -329,42 +436,14 @@ export declare const KeyCode: {
 	readonly KeyX: "KeyX";
 	readonly KeyY: "KeyY";
 	readonly KeyZ: "KeyZ";
-	readonly Digit0: "Digit0";
-	readonly Digit1: "Digit1";
-	readonly Digit2: "Digit2";
-	readonly Digit3: "Digit3";
-	readonly Digit4: "Digit4";
-	readonly Digit5: "Digit5";
-	readonly Digit6: "Digit6";
-	readonly Digit7: "Digit7";
-	readonly Digit8: "Digit8";
-	readonly Digit9: "Digit9";
-	readonly Backquote: "Backquote";
-	readonly Backslash: "Backslash";
-	readonly Backspace: "Backspace";
-	readonly BracketLeft: "BracketLeft";
-	readonly BracketRight: "BracketRight";
-	readonly Comma: "Comma";
-	readonly Delete: "Delete";
-	readonly End: "End";
-	readonly Enter: "Enter";
-	readonly Equal: "Equal";
-	readonly Escape: "Escape";
-	readonly Home: "Home";
-	readonly Minus: "Minus";
-	readonly Period: "Period";
-	readonly Quote: "Quote";
-	readonly Semicolon: "Semicolon";
-	readonly Slash: "Slash";
-	readonly Space: "Space";
-	readonly ShiftRight: "ShiftRight";
-	readonly AltRight: "AltRight";
-	readonly ControlRight: "ControlRight";
-	readonly MetaRight: "MetaRight";
-	readonly ShiftLeft: "ShiftLeft";
-	readonly AltLeft: "AltLeft";
-	readonly ControlLeft: "ControlLeft";
+	readonly Lang1: "Lang1";
+	readonly Lang2: "Lang2";
+	readonly MediaTrackNext: "MediaTrackNext";
+	readonly MediaTrackPrevious: "MediaTrackPrevious";
 	readonly MetaLeft: "MetaLeft";
+	readonly MetaRight: "MetaRight";
+	readonly Minus: "Minus";
+	readonly NumLock: "NumLock";
 	readonly Numpad0: "Numpad0";
 	readonly Numpad1: "Numpad1";
 	readonly Numpad2: "Numpad2";
@@ -375,11 +454,32 @@ export declare const KeyCode: {
 	readonly Numpad7: "Numpad7";
 	readonly Numpad8: "Numpad8";
 	readonly Numpad9: "Numpad9";
+	readonly NumpadAdd: "NumpadAdd";
+	readonly NumpadComma: "NumpadComma";
+	readonly NumpadDecimal: "NumpadDecimal";
+	readonly NumpadDivide: "NumpadDivide";
+	readonly NumpadMultiply: "NumpadMultiply";
+	readonly NumpadSubtract: "NumpadSubtract";
+	readonly OSLeft: "OSLeft";
+	readonly Pause: "Pause";
+	readonly Period: "Period";
+	readonly Quote: "Quote";
+	readonly ScrollLock: "ScrollLock";
+	readonly Semicolon: "Semicolon";
+	readonly ShiftLeft: "ShiftLeft";
+	readonly ShiftRight: "ShiftRight";
+	readonly Slash: "Slash";
+	readonly Space: "Space";
+	readonly Tab: "Tab";
+	readonly VolumeDown: "VolumeDown";
+	readonly VolumeMute: "VolumeMute";
+	readonly VolumeUp: "VolumeUp";
+	readonly WakeUp: "WakeUp";
 };
 /**
  * @returns all navigatable containers in some container
  */
-export declare function getAllNavigatables(root: Container): NavigatableContainer[];
+export declare function getAllNavigatables(target: Container, navigatables?: NavigatableContainer[]): NavigatableContainer[];
 /**
  * @returns the first navigatable container in the given direction
  */
@@ -387,11 +487,36 @@ export declare function getFirstNavigatable(root: Container, currentFocus?: Cont
 	minimumDistance?: number;
 }): NavigatableContainer | undefined;
 /**
- * @returns the first navigatable container in the given direction
+ * Register the mixin for PIXI.Container.
+ *
+ * @param container A reference to `PIXI.Container`.
  */
-export declare function getFirstNavigatableInDirection(navigatables: NavigatableContainer[], currentFocus?: Container, nearestDirection?: NavigationDirection, { minimumDistance, }?: {
-	minimumDistance?: number;
-}): NavigatableContainer | undefined;
+export declare function registerPixiJSInputDeviceMixin(container: any): void;
+export interface GamepadButtonPressEvent {
+	device: GamepadDevice;
+	button: Button;
+	buttonCode: ButtonCode;
+}
+export interface InputDeviceEvent {
+	deviceadded: {
+		device: Device;
+	};
+	deviceremoved: {
+		device: Device;
+	};
+}
+export interface KeyboardDeviceKeydownEvent {
+	device: KeyboardDevice;
+	keyCode: KeyCode;
+	/** Layout-specific label for key. @example "Ц" // JCUKEN for "KeyW" */
+	label: string;
+	event: KeyboardEvent;
+}
+export interface KeyboardDeviceLayoutUpdatedEvent {
+	device: KeyboardDevice;
+	layout: KeyboardLayout;
+	source: KeyboardLayoutSource;
+}
 /**
  * A target that responds to navigation on the stack.
  */
@@ -403,7 +528,7 @@ export interface NavigationResponder {
 	 * Unhandled interaction intents will be bubbled up to the next target. You
 	 * might return `true` here to prevent any intent from being propagated.
 	 */
-	handledNavigationIntent?(intent: NavigationIntent, device: InputDevice): boolean;
+	handledNavigationIntent?(intent: NavigationIntent, device: Device): boolean;
 	/**
 	 * This method is triggered when the target became the first responder.
 	 *
@@ -419,24 +544,13 @@ export interface NavigationResponder {
 	resignedAsFirstResponder?(): void;
 }
 export type Button = (typeof Button)[keyof typeof Button];
-/** Array with strongly-typed indices (0-15) */
-export type GamepadButtons = {
-	[Button.A]: GamepadButton;
-	[Button.B]: GamepadButton;
-	[Button.X]: GamepadButton;
-	[Button.Y]: GamepadButton;
-	[Button.LeftShoulder]: GamepadButton;
-	[Button.RightShoulder]: GamepadButton;
-	[Button.LeftTrigger]: GamepadButton;
-	[Button.RightTrigger]: GamepadButton;
-	[Button.Back]: GamepadButton;
-	[Button.Start]: GamepadButton;
-	[Button.LeftStick]: GamepadButton;
-	[Button.RightStick]: GamepadButton;
-	[Button.DPadUp]: GamepadButton;
-	[Button.DPadDown]: GamepadButton;
-	[Button.DPadLeft]: GamepadButton;
-	[Button.DPadRight]: GamepadButton;
+export type ButtonCode = typeof ButtonCode[number];
+export type Device = GamepadDevice | KeyboardDevice | CustomDevice;
+export type GamepadButtonDownEvent = (gamepad: GamepadDevice, button: Button) => void;
+export type GamepadDeviceEvent = {} & {
+	[button in ButtonCode]: GamepadButtonPressEvent;
+} & {
+	[button in Button]: GamepadButtonPressEvent;
 };
 export type GamepadDeviceSource = {
 	source: Gamepad;
@@ -447,14 +561,20 @@ export type GamepadDeviceSource = {
  * Note: Non-comprehensive list, covers the most brands only.
  */
 export type GamepadPlatform = "logitech" | "nintendo" | "playstation" | "steam" | "xbox" | "other";
-export type InputDevice = GamepadDevice | KeyboardDevice | CustomDevice;
+export type GamepadVibration = GamepadEffectParameters & {
+	vibrationType?: GamepadHapticEffectType;
+};
 export type KeyCode = (typeof KeyCode)[keyof typeof KeyCode];
-/**
- * Supported keyboard layouts.
- */
+export type KeyboardDeviceEvent = {
+	layoutdetected: KeyboardDeviceLayoutUpdatedEvent;
+} & {
+	[key in KeyCode]: KeyboardDeviceKeydownEvent;
+};
 export type KeyboardLayout = "QWERTY" | "AZERTY" | "JCUKEN" | "QWERTZ";
+export type KeyboardLayoutSource = "browser" | "lang" | "keypress" | "manual";
 export type NavigatableContainer = Container;
 export type NavigationDirection = "navigateLeft" | "navigateRight" | "navigateUp" | "navigateDown";
 export type NavigationIntent = "navigateBack" | "navigateDown" | "navigateLeft" | "navigateRight" | "navigateUp" | "trigger";
+export type NavigationTargetEvent = "focus" | "blur";
 
 export {};