@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.345.1-beta.20250704.94554

package/src/foundry/client/core/keybindings.d.mts

@@ -1,413 +0,0 @@
-import type { LazyUnknown, ValueOf } from "fvtt-types/utils";
-
-declare global {
-  /**
-   * A class responsible for managing defined game keybinding.
-   * Each keybinding is a string key/value pair belonging to a certain namespace and a certain store scope.
-   *
-   * When Foundry Virtual Tabletop is initialized, a singleton instance of this class is constructed within the global
-   * Game object as as game.keybindings.
-   *
-   * @see {@link Game.keybindings}
-   * @see {@link SettingKeybindingConfig}
-   * @see {@link KeybindingsConfig}
-   */
-  class ClientKeybindings {
-    constructor();
-
-    /** Registered Keybinding actions */
-    actions: Map<string, ClientKeybindings.KeybindingActionConfig>;
-
-    /** A mapping of a string key to possible Actions that might execute off it */
-    activeKeys: Map<string, ClientKeybindings.KeybindingAction[]>;
-
-    /**
-     * A stored cache of Keybind Actions Ids to Bindings
-     * @remarks This is only undefined before the "ready" hook.
-     */
-    bindings: Map<string, ClientKeybindings.KeybindingActionBinding[]> | undefined;
-
-    /**
-     * A count of how many registered keybindings there are
-     * @internal
-     * @defaultValue `0`
-     */
-    protected _registered: number;
-
-    /**
-     * A timestamp which tracks the last time a pan operation was performed
-     * @internal
-     * @defaultValue `0`
-     */
-    protected _moveTime: number;
-
-    static MOVEMENT_DIRECTIONS: ClientKeybindings.MovementDirections;
-
-    static ZOOM_DIRECTIONS: ClientKeybindings.ZoomDirections;
-
-    /**
-     * An alias of the movement key set tracked by the keyboard
-     */
-    get moveKeys(): Set<string>;
-
-    /** Initializes the keybinding values for all registered actions */
-    initialize(): void;
-
-    /**
-     * Register a new keybinding
-     *
-     * @param namespace - The namespace the Keybinding Action belongs to
-     * @param action    - A unique machine-readable id for the Keybinding Action
-     * @param data      - Configuration for keybinding data
-     *
-     * @example Define a keybinding which shows a notification
-     * ```typescript
-     * game.keybindings.register("myModule", "showNotification", {
-     *   name: "My Settings Keybinding",
-     *   hint: "A description of what will occur when the Keybinding is executed.",
-     *   uneditable: [
-     *     {
-     *       key: "Digit1",
-     *       modifiers: ["Control"]
-     *     }
-     *   ],
-     *   editable: [
-     *     {
-     *       key: "F1"
-     *     }
-     *   ],
-     *   onDown: () => { ui.notifications.info("Pressed!") },
-     *   onUp: () => {},
-     *   restricted: true,                         // Restrict this Keybinding to gamemaster only?
-     *   reservedModifiers: ["Alt""],              // If the ALT modifier is pressed, the notification is permanent instead of temporary
-     *   precedence: CONST.KEYBINDING_PRECEDENCE.NORMAL
-     * }
-     * ```
-     * @throws if called after `this.bindings` has been initialized.
-     */
-    register(namespace: string, action: string, data: ClientKeybindings.KeybindingActionConfig): void;
-
-    /**
-     * Get the current Bindings of a given namespace's Keybinding Action
-     *
-     * @param namespace - The namespace under which the setting is registered
-     * @param action    - The keybind action to retrieve
-     *
-     * @example Retrieve the current Keybinding Action Bindings
-     * ```typescript
-     * game.keybindings.get("myModule", "showNotification");
-     * ```
-     */
-    get(namespace: string, action: string): ClientKeybindings.KeybindingActionBinding[];
-
-    /**
-     * Set the editable Bindings of a Keybinding Action for a certain namespace and Action
-     *
-     * @param namespace - The namespace under which the Keybinding is registered
-     * @param action    - The Keybinding action to set
-     * @param bindings  - The Bindings to assign to the Keybinding
-     *
-     * @example Update the current value of a keybinding
-     * ```typescript
-     * game.keybindings.set("myModule", "showNotification", [
-     *     {
-     *       key: "F2",
-     *       modifiers: [ "CONTROL" ]
-     *     }
-     * ]);
-     * ```
-     * @remarks Passing `undefined` or nothing as `bindings` resets to the default.
-     */
-    set(namespace: string, action: string, bindings?: ClientKeybindings.KeybindingActionBinding[]): Promise<void>;
-
-    /** Reset all client keybindings back to their default configuration. */
-    resetDefaults(): Promise<void>;
-
-    /**
-     * A helper method that, when given a value, ensures that the returned value is a standardized Binding array
-     * @param values - An array of keybinding assignments to be validated
-     * @returns An array of keybinding assignments confirmed as valid
-     * @internal
-     */
-    protected static _validateBindings(
-      values: Array<ClientKeybindings.KeybindingActionBinding>,
-    ): Array<Required<ClientKeybindings.KeybindingActionBinding>>;
-
-    /**
-     * Validate that assigned modifiers are allowed
-     * @param keys - An array of modifiers which may be valid
-     * @returns An array of modifiers which are confirmed as valid
-     * @internal
-     */
-    protected static _validateModifiers(keys: string[]): string[];
-
-    /**
-     * Compares two Keybinding Actions based on their Order
-     * @param a - The first Keybinding Action
-     * @param b - the second Keybinding Action
-     * @internal
-     */
-    static _compareActions(a: ClientKeybindings.KeybindingAction, b: ClientKeybindings.KeybindingAction): number;
-
-    /**
-     * Register core keybindings.
-     * @param view           - The active game view
-     */
-    protected _registerCoreKeybindings(view: Game.View): void;
-
-    /**
-     * Handle Select all action
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onSelectAllObjects(context?: KeyboardManager.KeyboardEventContext): boolean;
-
-    /**
-     * Handle Cycle View actions
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onCycleView(context: KeyboardManager.KeyboardEventContext): boolean;
-
-    /**
-     * Handle Dismiss actions
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onDismiss(context?: KeyboardManager.KeyboardEventContext): Promise<boolean>;
-
-    /**
-     * Open Character sheet for current token or controlled actor
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onToggleCharacterSheet(
-      context?: KeyboardManager.KeyboardEventContext,
-    ): ReturnType<Game["toggleCharacterSheet"]>;
-
-    /**
-     * Handle action to target the currently hovered token.
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onTarget(context: KeyboardManager.KeyboardEventContext): boolean;
-
-    /**
-     * Handle DELETE Keypress Events
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onDelete(context?: KeyboardManager.KeyboardEventContext): boolean;
-
-    /**
-     * Handle keyboard movement once a small delay has elapsed to allow for multiple simultaneous key-presses.
-     * @param context - The context data of the event
-     * @param layer   - The active InteractionLayer instance
-     * @internal
-     */
-    protected _handleMovement(context: KeyboardManager.KeyboardEventContext, layer: InteractionLayer): void;
-
-    /** Handle panning the canvas using CTRL + directional keys */
-    protected _handleCanvasPan(): ReturnType<Canvas["animatePan"]>;
-
-    /**
-     * Handle Measured Ruler Movement Action
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onMeasuredRulerMovement(context?: KeyboardManager.KeyboardEventContext): boolean | void;
-
-    /**
-     * Handle Pause Action
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onPause(context?: KeyboardManager.KeyboardEventContext): true;
-
-    /**
-     * Handle Highlight action
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onHighlight(context?: KeyboardManager.KeyboardEventContext): boolean;
-
-    /**
-     * Handle Pan action
-     * @param context            - The context data of the event
-     * @param movementDirections - The Directions being panned in
-     * @internal
-     */
-    protected _onPan(
-      context: KeyboardManager.KeyboardEventContext,
-      movementDirections: ClientKeybindings.MovementDirection[],
-    ): boolean;
-
-    /**
-     * Handle Macro executions
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onMacroExecute(
-      context: KeyboardManager.KeyboardEventContext,
-      number: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0,
-    ): boolean;
-
-    /**
-     * Handle Macro page swaps
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onMacroPageSwap(context: KeyboardManager.KeyboardEventContext, page: number): true;
-
-    /**
-     * Handle action to copy data to clipboard
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onCopy(context?: KeyboardManager.KeyboardEventContext): boolean;
-
-    /**
-     * Handle Paste action
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onPaste(context: KeyboardManager.KeyboardEventContext): boolean;
-
-    /**
-     * Handle Undo action
-     * @param context - The context data of the event
-     * @internal
-     */
-    protected static _onUndo(context?: KeyboardManager.KeyboardEventContext): boolean;
-
-    /**
-     * Handle presses to keyboard zoom keys
-     * @param context       - The context data of the event
-     * @param zoomDirection - The direction to zoom
-     * @internal
-     */
-    protected static _onZoom(
-      context: KeyboardManager.KeyboardEventContext | LazyUnknown,
-      zoomDirection: ClientKeybindings.ZoomDirection,
-    ): boolean;
-
-    /**
-     * Bring the chat window into view and focus the input
-     * @param context - The context data of the event
-     * @internal
-     */
-    static _onFocusChat(context: KeyboardManager.KeyboardEventContext): boolean;
-  }
-
-  namespace ClientKeybindings {
-    /**
-     * A Client Keybinding Action Configuration
-     * @remarks Copied from `resources/app/common/types.mjs`
-     */
-    interface KeybindingActionConfig {
-      /** The namespace within which the action was registered */
-      namespace?: string;
-
-      /** The human readable name */
-      name: string;
-
-      /** An additional human readable hint */
-      hint?: string | undefined;
-
-      /** The default bindings that can never be changed nor removed. */
-      uneditable?: KeybindingActionBinding[] | undefined;
-
-      /** The default bindings that can be changed by the user. */
-      editable?: KeybindingActionBinding[] | undefined;
-
-      /** A function to execute when a key down event occurs. If True is returned, the event is consumed and no further keybinds execute. */
-      onDown?: ((ctx: KeyboardManager.KeyboardEventContext) => boolean | void) | undefined;
-
-      /** A function to execute when a key up event occurs. If True is returned, the event is consumed and no further keybinds execute. */
-      onUp?: ((ctx: KeyboardManager.KeyboardEventContext) => boolean | void) | undefined;
-
-      /** If True, allows Repeat events to execute the Action's onDown. Defaults to false. */
-      repeat?: boolean | undefined;
-
-      /** If true, only a GM can edit and execute this Action */
-      restricted?: boolean | undefined;
-
-      /** Modifiers such as [ "CONTROL" ] that can be also pressed when executing this Action. Prevents using one of these modifiers as a Binding. */
-      reservedModifiers?: string[] | undefined;
-
-      /** The preferred precedence of running this Keybinding Action */
-      precedence?: number | undefined; // TODO: KEYBINDING_PRECEDENCE?
-
-      /** The recorded registration order of the action */
-      order?: number | undefined;
-    }
-
-    /**
-     * A Client Keybinding Action Binding
-     * @remarks Copied from `resources/app/common/types.mjs`
-     */
-    interface KeybindingActionBinding {
-      /** A numeric index which tracks this bindings position during form rendering */
-      index?: number | undefined;
-
-      /** The KeyboardEvent#code value from https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values */
-      key: string;
-
-      /** An array of modifiers keys from KeyboardManager.MODIFIER_KEYS which are required for this binding to be activated */
-      modifiers?: string[] | undefined;
-    }
-
-    /**
-     * An action that can occur when a key is pressed
-     * @remarks Copied from `resources/app/common/types.mjs`
-     */
-    interface KeybindingAction {
-      /** The namespaced machine identifier of the Action */
-      action: string;
-
-      /** The Keyboard key */
-      key: string;
-
-      /** The human readable name */
-      name: string;
-
-      /** Required modifiers */
-      requiredModifiers: string[];
-
-      /** Optional (reserved) modifiers */
-      optionalModifiers: string[];
-
-      /** The handler that executes onDown */
-      onDown?: ((ctx: KeyboardManager.KeyboardEventContext) => boolean | void) | undefined;
-
-      /** The handler that executes onUp */
-      onUp?: ((ctx: KeyboardManager.KeyboardEventContext) => boolean | void) | undefined;
-
-      /** If True, allows Repeat events to execute this Action's onDown */
-      repeat: boolean;
-
-      /** If true, only a GM can execute this Action */
-      restricted: boolean;
-
-      /** The registration precedence */
-      precedence: number;
-
-      /** The registration order */
-      order: number;
-    }
-
-    interface MovementDirections {
-      UP: "up";
-      LEFT: "left";
-      DOWN: "down";
-      RIGHT: "right";
-    }
-    type MovementDirection = ValueOf<MovementDirections>;
-
-    interface ZoomDirections {
-      IN: "in";
-      OUT: "out";
-    }
-    type ZoomDirection = ValueOf<ZoomDirections>;
-  }
-}

package/src/foundry/client/core/keyboard.d.mts

@@ -1,271 +0,0 @@
-export {};
-
-declare global {
-  /**
-   * A set of helpers and management functions for dealing with user input from keyboard events.
-   * {@link https://keycode.info/}
-   */
-  class KeyboardManager {
-    constructor();
-
-    /**
-     * Begin listening to keyboard events.
-     */
-    protected _activateListeners(): void;
-
-    /**
-     * The set of key codes which are currently depressed (down)
-     */
-    downKeys: Set<string>;
-
-    /**
-     * The set of movement keys which were recently pressed
-     */
-    moveKeys: Set<string>;
-
-    /**
-     * Allowed modifier keys
-     */
-    static MODIFIER_KEYS: {
-      CONTROL: "Control";
-      SHIFT: "Shift";
-      ALT: "Alt";
-    };
-
-    /**
-     * Track which KeyboardEvent#code presses associate with each modifier
-     */
-    static MODIFIER_CODES: {
-      Alt: ["AltLeft", "AltRight"];
-      Control: ["ControlLeft", "ControlRight", "MetaLeft", "MetaRight", "Meta", "OsLeft", "OsRight"];
-      Shift: ["ShiftLeft", "ShiftRight"];
-    };
-
-    /**
-     * Key codes which are "protected" and should not be used because they are reserved for browser-level actions.
-     */
-    static PROTECTED_KEYS: ["F5", "F11", "F12", "PrintScreen", "ScrollLock", "NumLock", "CapsLock"];
-
-    /** The OS-specific string display for what their Command key is */
-    static CONTROL_KEY_STRING: "⌘" | "Control";
-
-    /**
-     * A special mapping of how special KeyboardEvent#code values should map to displayed strings or symbols.
-     * Values in this configuration object override any other display formatting rules which may be applied.
-     */
-    static KEYCODE_DISPLAY_MAPPING: {
-      ArrowLeft: "←" | "🡸";
-      ArrowRight: "→" | "🡺";
-      ArrowUp: "↑" | "🡹";
-      ArrowDown: "↓" | "🡻";
-      Backquote: "`";
-      Backslash: "\\";
-      BracketLeft: "[";
-      BracketRight: "]";
-      Comma: ",";
-      Control: (typeof KeyboardManager)["CONTROL_KEY_STRING"];
-      Equal: "=";
-      Meta: "⌘" | "⊞";
-      MetaLeft: "⌘" | "⊞";
-      MetaRight: "⌘" | "⊞";
-      OsLeft: "⌘" | "⊞";
-      OsRight: "⌘" | "⊞";
-      Minus: "-";
-      NumpadAdd: "Numpad+";
-      NumpadSubtract: "Numpad-";
-      Period: ".";
-      Quote: "'";
-      Semicolon: ";";
-      Slash: "/";
-    };
-
-    /**
-     * Test whether an HTMLElement currently has focus.
-     * If so we normally don't want to process keybinding actions.
-     */
-    get hasFocus(): boolean;
-
-    /**
-     * Emulates a key being pressed, triggering the Keyboard event workflow.
-     * @param up       - If True, emulates the `keyup` Event. Else, the `keydown` event
-     * @param code     - The KeyboardEvent#code which is being pressed
-     * @param altKey   - Emulate the ALT modifier as pressed
-     *                   (default: `false`)
-     * @param ctrlKey  - Emulate the CONTROL modifier as pressed
-     *                   (default: `false`)
-     * @param shiftKey - Emulate the SHIFT modifier as pressed
-     *                   (default: `false`)
-     * @param repeat   - Emulate this as a repeat event
-     *                   (default: `false`)
-     * @param force    - Force the event to be handled.
-     *                   (default: `false`)
-     */
-    static emulateKeypress(
-      up: boolean,
-      key: string,
-      {
-        altKey,
-        ctrlKey,
-        shiftKey,
-        repeat,
-        force,
-      }?: { altKey?: boolean; ctrlKey?: boolean; shiftKey?: boolean; repeat?: boolean; force?: boolean },
-    ): KeyboardManager.KeyboardEventContext;
-
-    /**
-     * Format a KeyboardEvent#code into a displayed string.
-     * @param code - The input code
-     * @returns The displayed string for this code
-     */
-    static getKeycodeDisplayString(code: string): string;
-
-    /**
-     * Get a standardized keyboard context for a given event.
-     * Every individual keypress is uniquely identified using the KeyboardEvent#code property.
-     * A list of possible key codes is documented here: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values
-     *
-     * @param event - The originating keypress event
-     * @param up    - A flag for whether the key is down or up
-     *                (default: `false`)
-     * @returns The standardized context of the event
-     */
-    static getKeyboardEventContext(event: KeyboardEvent, up: boolean): KeyboardManager.KeyboardEventContext;
-
-    /**
-     * Report whether a modifier in KeyboardManager.MODIFIER_KEYS is currently actively depressed.
-     * @param modifier - A modifier in MODIFIER_KEYS
-     * @returns Is this modifier key currently down (active)?
-     */
-    isModifierActive(modifier: string): boolean;
-
-    /**
-     * Report whether a core action key is currently actively depressed.
-     * @param action       - The core action to verify (ex: "target")
-     * @returns              Is this core action key currently down (active)?
-     */
-    isCoreActionKeyActive(action: string): boolean;
-
-    /**
-     * Converts a Keyboard Context event into a string representation, such as "C" or "Control+C"
-     * @param context          - The standardized context of the event
-     * @param includeModifiers - If True, includes modifiers in the string representation
-     *                           (default: `true`)
-     * @internal
-     */
-    protected static _getContextDisplayString(
-      context: KeyboardManager.KeyboardEventContext,
-      includeModifiers?: boolean,
-    ): string;
-
-    /**
-     * Given a standardized pressed key, find all matching registered Keybind Actions.
-     * @param context - A standardized keyboard event context
-     * @returns The matched Keybind Actions. May be empty.
-     * @internal
-     */
-    static _getMatchingActions(context: KeyboardManager.KeyboardEventContext): ClientKeybindings.KeybindingAction[];
-
-    /**
-     * Test whether a keypress context matches the registration for a keybinding action
-     * @param action  - The keybinding action
-     * @param context - The keyboard event context
-     * @returns Does the context match the action requirements?
-     * @internal
-     */
-    protected static _testContext(
-      action: ClientKeybindings.KeybindingAction,
-      context: KeyboardManager.KeyboardEventContext,
-    ): boolean;
-
-    /**
-     * Given a registered Keybinding Action, executes the action with a given event and context
-     *
-     * @param keybind - The registered Keybinding action to execute
-     * @param context - The gathered context of the event
-     * @returns Returns true if the keybind was consumed
-     * @internal
-     */
-    protected static _executeKeybind(
-      keybind: ClientKeybindings.KeybindingAction,
-      context: KeyboardManager.KeyboardEventContext,
-    ): boolean;
-
-    /**
-     * Processes a keyboard event context, checking it against registered keybinding actions
-     * @param context - The keyboard event context
-     * @internal
-     */
-    protected _processKeyboardContext(context: KeyboardManager.KeyboardEventContext): void;
-
-    /**
-     * Reset tracking for which keys are in the down and released states
-     * @internal
-     */
-    protected _reset(): void;
-
-    /**
-     * Emulate a key-up event for any currently down keys. When emulating, we go backwards such that combinations such as
-     * "CONTROL + S" emulate the "S" first in order to capture modifiers.
-     * @param force - Force the keyup events to be handled.
-     */
-    releaseKeys({ force }?: { force: boolean }): void;
-
-    /**
-     * Handle a key press into the down position
-     * @param event - The originating keyboard event
-     * @param up    - A flag for whether the key is down or up
-     * @internal
-     */
-    protected _handleKeyboardEvent(event: KeyboardEvent, up: boolean): void;
-
-    /**
-     * Input events do not fire with isComposing = false at the end of a composition event in Chrome
-     * See: https://github.com/w3c/uievents/issues/202
-     */
-    protected _onCompositionEnd(event: CompositionEvent): void;
-
-    /**
-     * Release any down keys when focusing a form element.
-     * @param event - The focus event.
-     */
-    protected _onFocusIn(event: FocusEvent): void;
-  }
-
-  namespace KeyboardManager {
-    /**
-     * Keyboard event context
-     * @remarks Copied from `resources/app/common/types.mjs`
-     */
-    interface KeyboardEventContext {
-      /** The normalized string key, such as "A" */
-      key: string;
-
-      /** The originating keypress event */
-      event: KeyboardEvent;
-
-      /** Is the Shift modifier being pressed */
-      isShift: boolean;
-
-      /** Is the Control or Meta modifier being processed */
-      isControl: boolean;
-
-      /** Is the Alt modifier being pressed */
-      isAlt: boolean;
-
-      /** Are any of the modifiers being pressed */
-      hasModifier: boolean;
-
-      /** A list of string modifiers applied to this context, such as [ "CONTROL" ] */
-      modifiers: string[];
-
-      /** True if the Key is Up, else False if down */
-      up: boolean;
-
-      /** True if the given key is being held down such that it is automatically repeating. */
-      repeat: boolean;
-
-      /** The executing Keybinding Action. May be undefined until the action is known. */
-      action?: string | undefined;
-    }
-  }
-}