@league-of-foundry-developers/foundry-vtt-types 9.280.1 → 12.331.1-beta

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

@@ -0,0 +1,312 @@
+import type { ValueOf } from "../../../types/utils.d.mts";
+
+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, KeybindingActionConfig>;
+
+    /** A mapping of a string key to possible Actions that might execute off it */
+    activeKeys: Map<string, KeybindingAction[]>;
+
+    /**
+     * A stored cache of Keybind Actions Ids to Bindings
+     * @remarks This is only undefined before the "ready" hook.
+     */
+    bindings: Map<string, 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: 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): 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?: 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<KeybindingActionBinding>,
+    ): Array<Required<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: KeybindingAction, b: 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?: KeyboardEventContext): boolean;
+
+    /**
+     * Handle Cycle View actions
+     * @param context - The context data of the event
+     * @internal
+     */
+    protected static _onCycleView(context: KeyboardEventContext): boolean;
+
+    /**
+     * Handle Dismiss actions
+     * @param context - The context data of the event
+     * @internal
+     */
+    protected static _onDismiss(context?: 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?: 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: KeyboardEventContext): boolean;
+
+    /**
+     * Handle DELETE Keypress Events
+     * @param context - The context data of the event
+     * @internal
+     */
+    protected static _onDelete(context?: 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: 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?: KeyboardEventContext): boolean | void;
+
+    /**
+     * Handle Pause Action
+     * @param context - The context data of the event
+     * @internal
+     */
+    protected static _onPause(context?: KeyboardEventContext): true;
+
+    /**
+     * Handle Highlight action
+     * @param context - The context data of the event
+     * @internal
+     */
+    protected static _onHighlight(context?: KeyboardEventContext): boolean;
+
+    /**
+     * Handle Pan action
+     * @param context            - The context data of the event
+     * @param movementDirections - The Directions being panned in
+     * @internal
+     */
+    protected _onPan(context: KeyboardEventContext, movementDirections: ClientKeybindings.MovementDirection[]): boolean;
+
+    /**
+     * Handle Macro executions
+     * @param context - The context data of the event
+     * @internal
+     */
+    protected static _onMacroExecute(
+      context: 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: KeyboardEventContext, page: number): true;
+
+    /**
+     * Handle action to copy data to clipboard
+     * @param context - The context data of the event
+     * @internal
+     */
+    protected static _onCopy(context?: KeyboardEventContext): boolean;
+
+    /**
+     * Handle Paste action
+     * @param context - The context data of the event
+     * @internal
+     */
+    protected static _onPaste(context: KeyboardEventContext): boolean;
+
+    /**
+     * Handle Undo action
+     * @param context - The context data of the event
+     * @internal
+     */
+    protected static _onUndo(context?: 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: KeyboardEventContext | unknown,
+      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: KeyboardEventContext): boolean;
+  }
+
+  namespace ClientKeybindings {
+    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

@@ -0,0 +1,224 @@
+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 },
+    ): 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): 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: 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: KeyboardEventContext): 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: KeybindingAction, context: 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: KeybindingAction, context: KeyboardEventContext): boolean;
+
+    /**
+     * Processes a keyboard event context, checking it against registered keybinding actions
+     * @param context - The keyboard event context
+     * @internal
+     */
+    protected _processKeyboardContext(context: 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;
+  }
+}

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

@@ -0,0 +1,28 @@
+export {};
+
+declare global {
+  /** Management class for Mouse events */
+  class MouseManager {
+    constructor();
+
+    /**
+     * Specify a rate limit for mouse wheel to gate repeated scrolling.
+     * This is especially important for continuous scrolling mice which emit hundreds of events per second.
+     * This designates a minimum number of milliseconds which must pass before another wheel event is handled
+     * @defaultValue `50`
+     */
+    static MOUSE_WHEEL_RATE_LIMIT: number;
+
+    /**
+     * Begin listening to mouse events.
+     */
+    protected _activateListeners(): void;
+
+    /**
+     * Master mouse-wheel event handler
+     * @param event - The mouse wheel event
+     * @internal
+     */
+    protected _onWheel(event: MouseEvent): void;
+  }
+}

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

@@ -0,0 +1,38 @@
+export {};
+
+declare global {
+  /**
+   * Responsible for managing the New User Experience workflows.
+   */
+  class NewUserExperience {
+    constructor();
+
+    /**
+     * Initialize the new user experience.
+     * Currently, this generates some chat messages with hints for getting started if we detect this is a new world.
+     */
+    initialize(): void;
+
+    /**
+     * Add event listeners to the chat card links.
+     * @param msg  - The ChatMessage being rendered.
+     * @param html - The HTML content of the message.
+     * @internal
+     */
+    protected _activateListeners(msg: ChatMessage, html: JQuery): void;
+
+    /**
+     * Perform some special action triggered by clicking on a link in a NUE chat card.
+     * @param event - The click event.
+     * @internal
+     */
+    protected _onActionLink(event: Event): void;
+
+    /**
+     * Switch to the appropriate tab when a user clicks on a link in the chat message.
+     * @param event - The click event.
+     * @internal
+     */
+    protected _onTabLink(event: Event): void;
+  }
+}