@antha/input 0.0.1

package/dist/bindings/antha-menu-nav.mod.js

@@ -0,0 +1,332 @@
+import { defineAnthaMod } from '@antha/engine';
+import { check } from '@augment-vir/assert';
+import { getObjectTypedEntries, getObjectTypedValues } from '@augment-vir/common';
+import { convertDuration } from 'date-vir';
+import { NavController, NavDirection, NavValue } from 'device-navigation';
+import { PredefinedGamepadBrand } from 'gamepad-type';
+import { InputDirection } from '../raw-inputs/raw-input.js';
+import { AnyGamepad, } from './player-bindings.js';
+export { nav, navAttribute, NavController } from 'device-navigation';
+/**
+ * All supported menu navigation bindings. To ignore any, simply don't allow players to bind to
+ * them. Any menus that don't have sufficient nestings to support any specific binding simply won't
+ * do anything if they're active.
+ *
+ * @category Menu
+ */
+export var MenuNavBinding;
+(function (MenuNavBinding) {
+    MenuNavBinding["MenuUp"] = "menu-up";
+    MenuNavBinding["MenuDown"] = "menu-down";
+    MenuNavBinding["MenuLeft"] = "menu-left";
+    MenuNavBinding["MenuRight"] = "menu-right";
+    /**
+     * Enter into a sub-menu.
+     *
+     * For example, this is usually a click, the enter button, "A" on Xbox or Nintendo controllers,
+     * or "X" on Playstation controllers.
+     */
+    MenuNavBinding["MenuEnter"] = "menu-enter";
+    /**
+     * Exit out of a sub-menu.
+     *
+     * For example, this is usually the Escape key, "B" on Xbox or Nintendo controllers, or "△" on
+     * Playstation controllers.
+     */
+    MenuNavBinding["MenuExit"] = "menu-exit";
+    /** Navigate to the next section in a menu. */
+    MenuNavBinding["MenuSectionNext"] = "menu-section-next";
+    /** Navigate to the previous section in a menu. */
+    MenuNavBinding["MenuSectionPrevious"] = "menu-section-previous";
+})(MenuNavBinding || (MenuNavBinding = {}));
+/**
+ * Default menu nav bindings for {@link AnthaMenuNavMod}.
+ *
+ * @category Internal
+ */
+export const defaultMenuNavBindings = {
+    [MenuNavBinding.MenuLeft]: [
+        {
+            deviceKey: AnyGamepad,
+            direction: InputDirection.Positive,
+            inputName: 'd-pad-left',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyA',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyJ',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-ArrowLeft',
+        },
+    ],
+    [MenuNavBinding.MenuRight]: [
+        {
+            deviceKey: AnyGamepad,
+            direction: InputDirection.Positive,
+            inputName: 'd-pad-right',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyD',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyL',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-ArrowRight',
+        },
+    ],
+    [MenuNavBinding.MenuUp]: [
+        {
+            deviceKey: AnyGamepad,
+            direction: InputDirection.Positive,
+            inputName: 'd-pad-up',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyW',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyI',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-ArrowUp',
+        },
+    ],
+    [MenuNavBinding.MenuDown]: [
+        {
+            deviceKey: AnyGamepad,
+            direction: InputDirection.Positive,
+            inputName: 'd-pad-down',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyS',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyK',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-ArrowDown',
+        },
+    ],
+    [MenuNavBinding.MenuEnter]: [
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-Space',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-Enter',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-NumpadEnter',
+        },
+        {
+            deviceKey: AnyGamepad,
+            direction: InputDirection.Positive,
+            gamepadBrand: PredefinedGamepadBrand.Sony,
+            inputName: 'X',
+        },
+        {
+            deviceKey: AnyGamepad,
+            direction: InputDirection.Positive,
+            inputName: 'A',
+        },
+    ],
+    [MenuNavBinding.MenuExit]: [
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-Escape',
+        },
+        {
+            deviceKey: AnyGamepad,
+            direction: InputDirection.Positive,
+            gamepadBrand: PredefinedGamepadBrand.Sony,
+            inputName: 'O',
+        },
+        {
+            deviceKey: AnyGamepad,
+            direction: InputDirection.Positive,
+            inputName: 'B',
+        },
+    ],
+    [MenuNavBinding.MenuSectionNext]: [
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyE',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyO',
+        },
+        {
+            deviceKey: AnyGamepad,
+            direction: InputDirection.Positive,
+            inputName: 'R1',
+        },
+    ],
+    [MenuNavBinding.MenuSectionPrevious]: [
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyQ',
+        },
+        {
+            deviceKey: 'keyboard',
+            direction: InputDirection.Positive,
+            inputName: 'button-KeyU',
+        },
+        {
+            deviceKey: AnyGamepad,
+            direction: InputDirection.Positive,
+            inputName: 'L1',
+        },
+    ],
+};
+/** @category Internal */
+export const defaultMenuNavOptions = {
+    repeatThreshold: {
+        milliseconds: 500,
+    },
+    repeatInterval: {
+        milliseconds: 60,
+    },
+    allowWrapping: true,
+};
+/**
+ * A pre-built mod that enables menu navigation. Set `isInMenu` on your game state to true to
+ * activate it.
+ *
+ * @category Pre-Built Mods
+ */
+export function createAnthaMenuNavMod(options = {}) {
+    return defineAnthaMod({
+        modName: 'menu-nav',
+        initState: {
+            menuNavOptions: {
+                ...defaultMenuNavOptions,
+                ...options,
+            },
+        },
+        execute({ state, hostElement }) {
+            if (!state.navController) {
+                state.navController = new NavController(hostElement, {
+                    alwaysRequireFocused: true,
+                    activateOnMouseUp: false,
+                    ...options,
+                });
+            }
+            if (!state.isInMenu || !state.menuNavOptions || !state.activeBindings) {
+                return;
+            }
+            const repeatThreshold = convertDuration(state.menuNavOptions.repeatThreshold, {
+                milliseconds: true,
+            }).milliseconds;
+            const repeatInterval = convertDuration(state.menuNavOptions.repeatInterval, {
+                milliseconds: true,
+            }).milliseconds;
+            const bindingsToAct = {};
+            const activeMenuBindings = {};
+            getObjectTypedValues(state.activeBindings).forEach((playerActiveBindings) => {
+                getObjectTypedEntries(playerActiveBindings).forEach(([bindingName, activeBinding,]) => {
+                    if (!check.isEnumValue(bindingName, MenuNavBinding)) {
+                        return;
+                    }
+                    activeMenuBindings[bindingName] = true;
+                    if (!activeBinding.actCount ||
+                        (activeBinding.holdDuration.milliseconds >= repeatThreshold &&
+                            activeBinding.holdDuration.milliseconds -
+                                activeBinding.lastActDuration.milliseconds >
+                                repeatInterval)) {
+                        bindingsToAct[bindingName] = true;
+                        activeBinding.actCount++;
+                        activeBinding.lastActDuration = activeBinding.holdDuration;
+                    }
+                });
+            });
+            if (bindingsToAct[MenuNavBinding.MenuEnter]) {
+                state.navController.enterInto({
+                    fallbackToActivate: true,
+                });
+                return;
+            }
+            else if (bindingsToAct[MenuNavBinding.MenuExit]) {
+                state.navController.exitOutOf();
+                return;
+            }
+            if (!activeMenuBindings[MenuNavBinding.MenuEnter] &&
+                state.navController.currentNavEntry?.entry.navValue === NavValue.Active) {
+                state.navController.deactivate();
+            }
+            const sectionDirection = bindingsToAct[MenuNavBinding.MenuSectionNext] &&
+                !bindingsToAct[MenuNavBinding.MenuSectionPrevious]
+                ? NavDirection.Right
+                : !bindingsToAct[MenuNavBinding.MenuSectionNext] &&
+                    bindingsToAct[MenuNavBinding.MenuSectionPrevious]
+                    ? NavDirection.Left
+                    : undefined;
+            if (sectionDirection) {
+                state.navController.navigatePibling({
+                    allowWrapping: state.menuNavOptions.allowWrapping,
+                    direction: sectionDirection,
+                });
+                return;
+            }
+            const vertical = bindingsToAct[MenuNavBinding.MenuUp] && !bindingsToAct[MenuNavBinding.MenuDown]
+                ? NavDirection.Up
+                : !bindingsToAct[MenuNavBinding.MenuUp] &&
+                    bindingsToAct[MenuNavBinding.MenuDown]
+                    ? NavDirection.Down
+                    : undefined;
+            const horizontal = bindingsToAct[MenuNavBinding.MenuRight] && !bindingsToAct[MenuNavBinding.MenuLeft]
+                ? NavDirection.Right
+                : !bindingsToAct[MenuNavBinding.MenuRight] &&
+                    bindingsToAct[MenuNavBinding.MenuLeft]
+                    ? NavDirection.Left
+                    : undefined;
+            if (vertical) {
+                state.navController.navigate({
+                    allowWrapping: state.menuNavOptions.allowWrapping,
+                    direction: vertical,
+                });
+            }
+            if (horizontal) {
+                state.navController.navigate({
+                    allowWrapping: state.menuNavOptions.allowWrapping,
+                    direction: horizontal,
+                });
+            }
+        },
+    });
+}

package/dist/bindings/player-bindings.d.ts

@@ -0,0 +1,116 @@
+import { type GamepadInputDeviceKey, type InputDeviceKey } from 'input-device-handler';
+import { type InputDirection } from '../raw-inputs/raw-input.js';
+/**
+ * A mapping of gamepad keys that simply allows them to be interpreted as different keys. This is
+ * useful for mapping a controller in any port to any other port. For example, mapping the
+ * controller in port 4 to port 1.
+ *
+ * @category Internal
+ */
+export type GamepadKeyMap = Partial<Record<GamepadInputDeviceKey, GamepadInputDeviceKey>>;
+/**
+ * A binding assignment device key that maps the input to _any_ connected controller.
+ *
+ * @category Internal
+ */
+export declare const AnyGamepad: "any-gamepad";
+/**
+ * A binding assignment device key that maps the input to _any_ connected controller.
+ *
+ * @category Internal
+ */
+export type AnyGamepad = typeof AnyGamepad;
+/**
+ * All supported device keys for input binding assignments.
+ *
+ * @category Internal
+ */
+export type AnthaDeviceKey = InputDeviceKey | AnyGamepad;
+/**
+ * An individual binding assignment. Used in `createAnthaReadBindingsMod` and
+ * {@link BindingAssignments}.
+ *
+ * @category Internal
+ */
+export type BindingAssignment = {
+    deviceKey: AnthaDeviceKey;
+    /**
+     * The input key, button, or gamepad input name (like `'button-keyW'` for keyboard buttons or
+     * `'button-12'` or `'X'` for gamepads).
+     */
+    inputName: string;
+    /** Required gamepad brand. */
+    gamepadBrand?: string;
+    direction: InputDirection;
+};
+/**
+ * Starts at `'1'`.
+ *
+ * @category Internal
+ */
+export type PlayerPosition = `${number}`;
+/**
+ * A collection of bindings for a single player. Used in `createAnthaReadBindingsMod` and
+ * {@link PlayersBindingAssignments}.
+ *
+ * @category Internal
+ */
+export type BindingAssignments<BindingNames extends string = string> = Partial<Record<BindingNames, BindingAssignment[]>>;
+/**
+ * A collection of bindings for all players. Used in `createAnthaReadBindingsMod` and
+ * `AnthaInputBindingsState`.
+ *
+ * @category Internal
+ */
+export type PlayersBindingAssignments<BindingNames extends string = string> = Record<PlayerPosition, BindingAssignments<BindingNames>>;
+/**
+ * An individual active binding. Used in `createAnthaReadBindingsMod` and {@link ActiveBindings}.
+ *
+ * @category Internal
+ */
+export type ActiveBinding = {
+    /**
+     * The full duration for which the current binding has been active in its current direction.
+     * When an active is first pressed, this will be 0 milliseconds.
+     *
+     * @default {milliseconds: 0}
+     */
+    holdDuration: {
+        milliseconds: number;
+    };
+    value: number;
+    /**
+     * The hold duration at which the last time this binding was acted upon. When the binding hasn't
+     * been acted on yet, this contain 0 milliseconds.
+     *
+     * This must be set by whatever process is acting on this binding, whenever it does so.
+     *
+     * @default {milliseconds: 0}
+     */
+    lastActDuration: {
+        milliseconds: number;
+    };
+    /**
+     * The number of times which this binding has been acted upon for the current hold. When a
+     * binding is first activated, this will be `0`.
+     *
+     * This must be incremented by whatever process is acting on this binding, whenever it does so.
+     *
+     * @default 0
+     */
+    actCount: number;
+};
+/**
+ * A collection of all active bindings for an individual player. Used in
+ * `createAnthaReadBindingsMod` and {@link PlayersActiveBindings}.
+ *
+ * @category Internal
+ */
+export type ActiveBindings<BindingNames extends string = string> = Partial<Record<BindingNames, ActiveBinding>>;
+/**
+ * A collection of all active bindings for all players. Used in `createAnthaReadBindingsMod` and
+ * `AnthaInputBindingsState`.
+ *
+ * @category Internal
+ */
+export type PlayersActiveBindings<BindingNames extends string = string> = Record<PlayerPosition, ActiveBindings<BindingNames>>;

package/dist/bindings/player-bindings.js

@@ -0,0 +1,6 @@
+/**
+ * A binding assignment device key that maps the input to _any_ connected controller.
+ *
+ * @category Internal
+ */
+export const AnyGamepad = 'any-gamepad';

package/dist/elements/antha-keyboard.element.d.ts

@@ -0,0 +1,92 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type NavController } from 'device-navigation';
+import { type RequireExactlyOne } from 'type-fest';
+/**
+ * Keypress details emitted by the `keyPress` event from {@link AnthaKeyboard}.
+ *
+ * @category Internal
+ */
+export type AnthaKeyboardKeyPress = RequireExactlyOne<{
+    typedCharacter: string;
+    special: AnthaKeyboardSpecialKey;
+}>;
+/** @category Internal */
+export declare enum AnthaKeyboardSpecialKey {
+    Backspace = "backspace",
+    Enter = "enter",
+    Tab = "tab",
+    NavLeft = "nav-left",
+    NavRight = "nav-right",
+    Paste = "paste",
+    HideKeyboard = "hide-keyboard",
+    CapsLock = "caps-lock",
+    LeftShift = "left-shift",
+    RightShift = "right-shift",
+    ClearAll = "clear-all"
+}
+/** @category Internal */
+export declare enum ToggleKey {
+    Shift = "shift",
+    CapsLock = "caps-lock"
+}
+type KeyboardToggleState = Partial<Record<ToggleKey, boolean>>;
+/**
+ * An on-screen keyboard that works with `AnthaMenuNavMod` to allow navigation by controller.
+ *
+ * @category Pre-Build Mods
+ */
+export declare const AnthaKeyboard: import("element-vir").DeclarativeElementDefinition<"antha-keyboard", {
+    navController: NavController;
+} & PartialWithUndefined<{
+    /**
+     * If set to `true`, a "Hide" (keyboard hide) button is shown.
+     *
+     * @default false
+     */
+    showHideButton: boolean;
+    /**
+     * If `true`, a text box with the currently entered text is not rendered above the keyboard.
+     *
+     * @default false
+     */
+    hideText: boolean;
+    /**
+     * Max length of the text.
+     *
+     * @default 128
+     */
+    maxLength: number;
+}>, {
+    value: string;
+    toggled: KeyboardToggleState;
+    cursorPosition: number;
+    beamElement: undefined | HTMLElement;
+    arrowRepeatDelay: undefined | ReturnType<typeof globalThis.setTimeout>;
+    arrowRepeatInterval: undefined | ReturnType<typeof globalThis.setInterval>;
+}, {
+    keyPress: import("element-vir").DefineEvent<((Required<Pick<{
+        typedCharacter: string;
+        special: AnthaKeyboardSpecialKey;
+    }, "typedCharacter">> & Partial<Record<"special", never>>) | (Required<Pick<{
+        typedCharacter: string;
+        special: AnthaKeyboardSpecialKey;
+    }, "special">> & Partial<Record<"typedCharacter", never>>)) & Omit<{
+        typedCharacter: string;
+        special: AnthaKeyboardSpecialKey;
+    }, "typedCharacter" | "special">>;
+    valueChange: import("element-vir").DefineEvent<string>;
+}, "antha-keyboard-", "antha-keyboard-", readonly [], readonly []>;
+/**
+ * A helper for handling key press events from {@link AnthaKeyboard}. This is used internally in
+ * {@link AnthaKeyboard} but is useful if you want to hide the keyboard's built-in text pane and use
+ * your own processing.
+ *
+ * @category Internal
+ */
+export declare function handleKeyPress({ currentValue, keyPress, cursorPosition, maxLength, }: Readonly<{
+    keyPress: Readonly<AnthaKeyboardKeyPress>;
+    currentValue: string;
+    cursorPosition: number;
+    maxLength: number;
+}>): Promise<string>;
+export {};