inpt 0.0.0

package/dist/types/core/BoundAction.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Counts the number of enabled flags in the given bitmask.
+ *
+ * @param bitmask - A bitmask.
+ * @return The number of enabled flags.
+ * @internal
+ */
+export {};

package/dist/types/core/Disposable.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Describes objects that can dispose internal resources.
+ *
+ * @group Core
+ */
+export interface Disposable {
+    /**
+     * Frees internal resources.
+     */
+    dispose(): void;
+}

package/dist/types/core/Input.d.ts

@@ -0,0 +1,46 @@
+import { Modifier } from "./Modifier.js";
+/**
+ * Input options.
+ *
+ * @group Core
+ */
+export interface InputOptions {
+    /**
+     * A list of required modifers.
+     */
+    modifiers?: Modifier[];
+}
+/**
+ * Input data.
+ *
+ * @group Core
+ */
+export declare class Input<T = unknown> {
+    /**
+     * @see {@link value}
+     */
+    _value: T;
+    /**
+     * @see {@link modifiers}
+     */
+    _modifiers: number;
+    /**
+     * Constructs new input data.
+     *
+     * @param value - The primary input value.
+     * @param options - Additional options.
+     */
+    constructor(value: T, { modifiers }?: InputOptions);
+    /**
+     * The primary input value.
+     */
+    get value(): T;
+    set value(value: T);
+    /**
+     * The required modifiers, stored as a bitmask.
+     *
+     * Modifiers can be set directly as a bitmask or as a list of modifier keys.
+     */
+    get modifiers(): number;
+    set modifiers(value: number | Modifier[]);
+}

package/dist/types/core/InputManager.d.ts

@@ -0,0 +1,179 @@
+import { Event, EventTarget } from "synthetic-event";
+import { InputSettings } from "../settings/InputSettings.js";
+import { Disposable } from "./Disposable.js";
+import { InputManagerEventMap } from "./InputManagerEventMap.js";
+/**
+ * InputManager options.
+ *
+ * @group Core
+ */
+export interface InputManagerOptions {
+    /**
+     * The input settings.
+     */
+    settings?: InputSettings;
+    /**
+     * The DOM element that acts as the primary event target.
+     */
+    domElement?: HTMLElement | null;
+}
+/**
+ * An input manager.
+ *
+ * @group Core
+ */
+export declare class InputManager extends EventTarget<InputManagerEventMap> implements Disposable, EventListenerObject {
+    /**
+     * @see {@link domElement}
+     */
+    private _domElement;
+    /**
+     * @see {@link enabled}
+     */
+    private _enabled;
+    /**
+     * A collection that organizes active pointer events by ID.
+     */
+    private readonly pointerEvents;
+    /**
+     * A collection of deferred mouse events that are handled when the pointer lock state changes.
+     */
+    private readonly deferredMouseEvents;
+    /**
+     * A collection of actions that are currently active.
+     */
+    private readonly activeActions;
+    private readonly movementEvent;
+    /**
+     * The settings.
+     */
+    readonly settings: InputSettings;
+    /**
+     * Constructs a new input manager.
+     *
+     * @param options - The options.
+     */
+    constructor({ settings, domElement }?: InputManagerOptions);
+    /**
+     * A DOM element that acts as the primary event target.
+     */
+    get domElement(): HTMLElement | null;
+    set domElement(value: HTMLElement | null);
+    /**
+     * Determines whether the input listeners are currently enabled.
+     */
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    /**
+     * Indicates whether the pointer is currently locked.
+     */
+    get pointerLocked(): boolean;
+    /**
+     * Registers event listeners.
+     */
+    private addEventListeners;
+    /**
+     * Unregisters event listeners.
+     */
+    private removeEventListeners;
+    /**
+     * Reset the input state.
+     */
+    private resetInputState;
+    /**
+     * Locks the pointer.
+     *
+     * @return A promise that resolves when the pointer has been locked.
+     */
+    private lockPointer;
+    /**
+     * Unlocks the pointer.
+     */
+    private unlockPointer;
+    /**
+     * Handles pointer move events.
+     *
+     * @param event - A pointer event.
+     */
+    private onPointerMove;
+    /**
+     * Handles pointer lock change events.
+     */
+    private onPointerLockChange;
+    /**
+     * Handles `mousedown` events.
+     *
+     * Mouse events are used because pointer events don't fire for other mouse buttons while a pointer is active.
+     *
+     * @param event - A mouse event.
+     */
+    private onMouseDownNative;
+    /**
+     * Handles `mouseup` events.
+     *
+     * Mouse events are used because pointer events don't fire for other mouse buttons while a pointer is active.
+     *
+     * @param event - A mouse event.
+     */
+    private onMouseUpNative;
+    /**
+     * Handles `mousedown` events.
+     *
+     * @param event - A mouse event.
+     */
+    private onMouseDown;
+    /**
+     * Handles `mouseup` events.
+     *
+     * @param event - A mouse event.
+     */
+    private onMouseUp;
+    /**
+     * Handles `pointerdown` events.
+     *
+     * @param event - A pointer event.
+     */
+    private onPointerDown;
+    /**
+     * Handles `pointerup` events.
+     *
+     * @param event - A pointer event.
+     */
+    private onPointerUp;
+    /**
+     * Handles `contextmenu` events.
+     *
+     * @param event - A pointer event.
+     */
+    private onContextMenu;
+    /**
+     * Handles `wheel` events.
+     *
+     * @param event - A wheel event.
+     */
+    private onWheel;
+    /**
+     * Handles `keydown` events.
+     *
+     * @param event - A keyboard event.
+     */
+    private onKeyDown;
+    /**
+     * Handles `keyup` events.
+     *
+     * @param event - A keyboard event.
+     */
+    private onKeyUp;
+    /**
+     * Handles `pointercancel` events.
+     *
+     * @param event - A pointer event.
+     */
+    private onPointerCancel;
+    /**
+     * Cancels active interactions on visibility loss.
+     */
+    private onVisibilityChange;
+    handleEvent(event: Event): void;
+    dispose(): void;
+}

package/dist/types/core/InputManagerEventMap.d.ts

@@ -0,0 +1,26 @@
+import { Event } from "synthetic-event";
+import { ActionEvent } from "../events/ActionEvent.js";
+import { MovementEvent } from "../events/MovementEvent.js";
+/**
+ * Events emitted by the input manager.
+ *
+ * @group Core
+ */
+export interface InputManagerEventMap {
+    /**
+     * Indicates that a specific action was activated.
+     */
+    activate: ActionEvent<"activate">;
+    /**
+     * Indicates that a specific action was deactivated.
+     */
+    deactivate: ActionEvent<"deactivate">;
+    /**
+     * A pointer movement change.
+     */
+    move: MovementEvent;
+    /**
+     * Signals that the input state has been reset.
+     */
+    reset: Event<"reset">;
+}

package/dist/types/core/KeyCode.d.ts

@@ -0,0 +1,7 @@
+/**
+ * An enumeration of input keys.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code
+ * @group Core
+ */
+export type KeyCode = ("Backspace" | "Tab" | "Enter" | "ShiftLeft" | "ShiftRight" | "ControlLeft" | "ControlRight" | "AltLeft" | "AltRight" | "Pause" | "CapsLock" | "Escape" | "Space" | "PageUp" | "PageDown" | "End" | "Home" | "ArrowLeft" | "ArrowUp" | "ArrowRight" | "ArrowDown" | "Insert" | "Delete" | "Digit0" | "Digit1" | "Digit2" | "Digit3" | "Digit4" | "Digit5" | "Digit6" | "Digit7" | "Digit8" | "Digit9" | "KeyA" | "KeyB" | "KeyC" | "KeyD" | "KeyE" | "KeyF" | "KeyG" | "KeyH" | "KeyI" | "KeyJ" | "KeyK" | "KeyL" | "KeyM" | "KeyN" | "KeyO" | "KeyP" | "KeyQ" | "KeyR" | "KeyS" | "KeyT" | "KeyU" | "KeyV" | "KeyW" | "KeyX" | "KeyY" | "KeyZ" | "OSLeft" | "OSRight" | "MetaLeft" | "MetaRight" | "MediaSelect" | "Numpad0" | "Numpad1" | "Numpad2" | "Numpad3" | "Numpad4" | "Numpad5" | "Numpad6" | "Numpad7" | "Numpad8" | "Numpad9" | "NumpadMultiply" | "NumpadAdd" | "NumpadSubtract" | "NumpadDecimal" | "NumpadDivide" | "F1" | "F2" | "F3" | "F4" | "F5" | "F6" | "F7" | "F8" | "F9" | "F10" | "F11" | "F12" | "NumLock" | "ScrollLock" | "Semicolon" | "Equal" | "Comma" | "Minus" | "Period" | "Slash" | "Backquote" | "BracketLeft" | "BracketRight" | "Backslash");

package/dist/types/core/Modifier.d.ts

@@ -0,0 +1,6 @@
+/**
+ * An enumeration of modifier keys.
+ *
+ * @group Core
+ */
+export type Modifier = "Alt" | "Ctrl" | "Meta" | "Shift";

package/dist/types/core/PointerButton.d.ts

@@ -0,0 +1,19 @@
+/**
+ * An enumeration of pointer buttons.
+ *
+ * @group Core
+ */
+export declare enum PointerButton {
+    /**
+     * The main button such as the left button on a mouse.
+     */
+    MAIN = 0,
+    /**
+     * An auxiliary button such as the middle button on a mouse.
+     */
+    AUXILIARY = 1,
+    /**
+     * A secondary button such as the right button on a mouse.
+     */
+    SECONDARY = 2
+}

package/dist/types/core/PointerLockBehavior.d.ts

@@ -0,0 +1,6 @@
+/**
+ * An enumeration of pointer lock behaviors.
+ *
+ * @group Core
+ */
+export type PointerLockBehavior = "none" | "lock" | "lock-hold";

package/dist/types/core/WheelRotation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * An enumeration of wheel rotations.
+ *
+ * @group Core
+ */
+export declare enum WheelRotation {
+    /**
+     * A negative horizontal wheel rotation, i.e. scrolling left.
+     */
+    NEGATIVE_X = "-x",
+    /**
+     * A positive horizontal wheel rotation, i.e. scrolling right.
+     */
+    POSITIVE_X = "+x",
+    /**
+     * A negative vertical wheel rotation, i.e. scrolling up.
+     */
+    NEGATIVE_Y = "-y",
+    /**
+     * A positive vertical wheel rotation, i.e. scrolling down.
+     */
+    POSITIVE_Y = "+y"
+}
+/**
+ * Retrieves the wheel rotation from a given wheel event.
+ *
+ * @param event - The event.
+ * @return The rotation, or undefined if there is no delta information.
+ */
+export declare function getWheelRotation(event: WheelEvent): WheelRotation | undefined;

package/dist/types/core/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./BoundAction.js";
+export * from "./Disposable.js";
+export * from "./Input.js";
+export * from "./InputManager.js";
+export * from "./InputManagerEventMap.js";
+export * from "./KeyCode.js";
+export * from "./Modifier.js";
+export * from "./PointerButton.js";
+export * from "./PointerLockBehavior.js";
+export * from "./WheelRotation.js";

package/dist/types/events/ActionEvent.d.ts

@@ -0,0 +1,12 @@
+import { Event } from "synthetic-event";
+/**
+ * An action event.
+ *
+ * @group Events
+ */
+export interface ActionEvent<TEventType extends string = string> extends Event<TEventType> {
+    /**
+     * The action.
+     */
+    action: string;
+}

package/dist/types/events/MovementEvent.d.ts

@@ -0,0 +1,28 @@
+import { Event } from "synthetic-event";
+/**
+ * A movement event.
+ *
+ * @group Events
+ */
+export interface MovementEvent extends Event<"move"> {
+    /**
+     * The number of active pointers.
+     */
+    pointerCount: number;
+    /**
+     * The position change along the X-axis.
+     */
+    deltaX: number;
+    /**
+     * The position change along the Y-axis.
+     */
+    deltaY: number;
+    /**
+     * The position on the X-axis.
+     */
+    x: number;
+    /**
+     * The position on the Y-axis.
+     */
+    y: number;
+}

package/dist/types/events/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./ActionEvent.js";
+export * from "./MovementEvent.js";

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./core/index.js";
+export * from "./events/index.js";
+export * from "./settings/index.js";

package/dist/types/settings/Bindings.d.ts

@@ -0,0 +1,125 @@
+import { Input } from "../core/Input.js";
+/**
+ * Input bindings.
+ *
+ * @group Settings
+ * @param TKey - The type of the input values.
+ */
+export declare class Bindings<TInput> {
+    /**
+     * The default bindings.
+     */
+    private defaultActions;
+    /**
+     * A collection that maps inputs to actions.
+     */
+    private actions;
+    /**
+     * Constructs new input bindings.
+     */
+    constructor();
+    /**
+     * Resets the current bindings to match the default bindings.
+     *
+     * @return This instance.
+     */
+    reset(): this;
+    /**
+     * Resets the current bindings and establishes default bindings.
+     *
+     * @param actions - A collection that maps inputs to actions.
+     * @return This instance.
+     */
+    setDefault(actions: Map<TInput | Input<TInput>, string>): this;
+    /**
+     * Clears the default bindings.
+     *
+     * @return This instance.
+     */
+    clearDefault(): this;
+    /**
+     * Clears the current bindings.
+     *
+     * @return This instance.
+     */
+    clear(): this;
+    /**
+     * Copies the given bindings, including the default bindings.
+     *
+     * @param bindings - Bindings.
+     * @return This instance.
+     */
+    copy(bindings: Bindings<TInput>): this;
+    /**
+     * Clones these bindings.
+     *
+     * @return The cloned bindings.
+     */
+    clone(): Bindings<TInput>;
+    /**
+     * Checks if any actions are bound to the given input.
+     *
+     * @param input - An input.
+     * @return Whether the given input is bound to an action.
+     */
+    has(input: TInput | Input<TInput>): boolean;
+    /**
+     * Returns the action that exactly matches the given input.
+     *
+     * @param input - An input.
+     * @return The action, or undefined if the input is not bound to any action.
+     */
+    get(input: TInput | Input<TInput>): string | undefined;
+    /**
+     * Binds an action to an input.
+     *
+     * @param input - An input.
+     * @param action - An action.
+     * @return This instance.
+     */
+    set(input: TInput | Input<TInput>, action: string): this;
+    /**
+     * Unbinds an action.
+     *
+     * @param input - The input.
+     * @return Whether the binding existed.
+     */
+    delete(input: TInput | Input<TInput>): boolean;
+    /**
+     * Returns all actions that match the given mouse event.
+     *
+     * @param event - A mouse event
+     * @return The matching actions sorted by specificity, DESC, or undefined if there is no bound action.
+     */
+    matchMouseEvent(event: MouseEvent): string[] | undefined;
+    /**
+     * Returns all actions that match the given wheel event.
+     *
+     * @param event - A wheel event
+     * @return The matching actions sorted by specificity, DESC, or undefined if there is no bound action.
+     */
+    matchWheelEvent(event: WheelEvent): string[] | undefined;
+    /**
+     * Returns all actions that match the given keyboard event.
+     *
+     * @param event - A keyboard event
+     * @return The matching actions sorted by specificity, DESC, or undefined if there is no bound action.
+     */
+    matchKeyboardEvent(event: KeyboardEvent): string[] | undefined;
+    /**
+     * Returns all actions that match the given input.
+     *
+     * @param input - An input.
+     * @param modifiers - A modifier bitmask. Default is `~0 >>> 0` which allows all modifiers.
+     * @return The matching actions sorted by specificity, DESC, or undefined if there is no bound action.
+     */
+    match(input: TInput, modifiers?: number): string[] | undefined;
+    /**
+     * Copies the given JSON data.
+     *
+     * @param json - The JSON data.
+     * @return This instance.
+     */
+    fromJSON(json: string | Bindings<TInput>): this;
+    toJSON(): Record<string, unknown>;
+}

package/dist/types/settings/InputSettings.d.ts

@@ -0,0 +1,57 @@
+import { EventTarget } from "synthetic-event";
+import { KeyCode } from "../core/KeyCode.js";
+import { PointerButton } from "../core/PointerButton.js";
+import { WheelRotation } from "../core/WheelRotation.js";
+import { Bindings } from "./Bindings.js";
+import { PointerSettings } from "./PointerSettings.js";
+import { SettingsEventMap } from "./SettingsEventMap.js";
+/**
+ * Input settings.
+ *
+ * @group Settings
+ */
+export declare class InputSettings extends EventTarget<SettingsEventMap> {
+    /**
+     * Key bindings.
+     */
+    readonly keyBindings: Bindings<KeyCode>;
+    /**
+     * Pointer bindings.
+     */
+    readonly pointerBindings: Bindings<PointerButton | WheelRotation>;
+    /**
+     * Pointer settings.
+     */
+    readonly pointer: PointerSettings;
+    /**
+     * Constructs new pointer settings.
+     */
+    constructor();
+    /**
+     * Copies the given pointer settings.
+     *
+     * @param settings - Pointer settings.
+     * @return This instance.
+     */
+    copy(settings: InputSettings): this;
+    /**
+     * Clones this pointer settings instance.
+     *
+     * @return The cloned pointer settings.
+     */
+    clone(): InputSettings;
+    /**
+     * Copies the given JSON data.
+     *
+     * @param json - The JSON data.
+     * @return This instance.
+     */
+    fromJSON(json: string | InputSettings): InputSettings;
+    toJSON(): Record<string, unknown>;
+    /**
+     * Exports these settings as a data blob.
+     *
+     * @return The settings blob.
+     */
+    toBlob(): Blob;
+}

package/dist/types/settings/PointerSettings.d.ts

@@ -0,0 +1,89 @@
+import { EventTarget } from "synthetic-event";
+import { PointerButton } from "../core/PointerButton.js";
+import { PointerLockBehavior } from "../core/PointerLockBehavior.js";
+import { SettingsEventMap } from "./SettingsEventMap.js";
+/**
+ * Pointer settings.
+ *
+ * @group Settings
+ */
+export declare class PointerSettings extends EventTarget<SettingsEventMap> {
+    /**
+     * @see {@link sensitivityX}
+     */
+    private _sensitivityX;
+    /**
+     * @see {@link sensitivityY}
+     */
+    private _sensitivityY;
+    /**
+     * @see {@link lockBehavior}
+     */
+    private _lockBehavior;
+    /**
+     * Constructs new pointer settings.
+     */
+    constructor();
+    /**
+     * The horizontal sensitivity.
+     *
+     * This sensitivity acts as a baseline scale for pointer movement deltas.
+     *
+     * @defaultValue 1e-3
+     */
+    get sensitivityX(): number;
+    set sensitivityX(value: number);
+    /**
+     * The vertical sensitivity.
+     *
+     * This sensitivity acts as a baseline scale for pointer movement deltas.
+     *
+     * @defaultValue 1e-3
+     */
+    get sensitivityY(): number;
+    set sensitivityY(value: number);
+    /**
+     * Sets the horizontal and vertical rotation sensitivity.
+     *
+     * This sensitivity acts as a baseline scale for pointer movement deltas.
+     *
+     * @defaultValue 1e-3
+     */
+    set sensitivity(value: number);
+    private set lockBehavior(value);
+    /**
+     * Returns the pointer behavior for a specific button.
+     *
+     * @param button - A pointer button.
+     * @return The behavior.
+     */
+    getLockBehavior(button: PointerButton): PointerLockBehavior;
+    /**
+     * Sets the pointer behavior for a specific button.
+     *
+     * @param button - The button.
+     * @param behavior - The behavior.
+     */
+    setLockBehavior(button: PointerButton, behavior: PointerLockBehavior): void;
+    /**
+     * Copies the given pointer settings.
+     *
+     * @param settings - Pointer settings.
+     * @return This instance.
+     */
+    copy(settings: PointerSettings): PointerSettings;
+    /**
+     * Clones this pointer settings instance.
+     *
+     * @return The cloned pointer settings.
+     */
+    clone(): PointerSettings;
+    /**
+     * Copies the given JSON data.
+     *
+     * @param json - The JSON data.
+     * @return This instance.
+     */
+    fromJSON(json: string | PointerSettings): PointerSettings;
+    toJSON(): Record<string, unknown>;
+}