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

package/src/foundry/client/helpers/interaction/keyboard-manager.d.mts

@@ -0,0 +1,331 @@
+import type { Brand, Identity, InexactPartial } from "#utils";
+import type ClientKeybindings from "./client-keybindings.mjs";
+
+/**
+ * A set of helpers and management functions for dealing with user input from keyboard events.
+ * {@link https://keycode.info/}
+ * @see {@linkcode foundry.Game.keyboard | Game#keyboard}
+ */
+declare class KeyboardManager {
+  /**
+   * @remarks
+   * @throws If `game.keyboard` is already initialized
+   */
+  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>;
+
+  /**
+   * Is logical keybindings active?
+   */
+  static get isUniversalMode(): boolean;
+
+  /**
+   * Allowed modifier keys
+   */
+  static MODIFIER_KEYS: KeyboardManager.ModifierKeys;
+
+  /**
+   * Track which KeyboardEvent#code presses associate with each modifier
+   * @defaultValue
+   * ```js
+   * {
+   *   Alt: ["AltLeft", "AltRight"];
+   *   Control: ["ControlLeft", "ControlRight", "MetaLeft", "MetaRight", "Meta", "OsLeft", "OsRight"];
+   *   Shift: ["ShiftLeft", "ShiftRight"];
+   * }
+   * ```
+   */
+  static MODIFIER_CODES: KeyboardManager.ModifierCodes;
+
+  /**
+   * Key codes which are "protected" and should not be used because they are reserved for browser-level actions.
+   * @defaultValue `["F5", "F11", "F12", "PrintScreen", "ScrollLock", "NumLock", "CapsLock"]`
+   */
+  static PROTECTED_KEYS: string[];
+
+  /**
+   * The OS-specific string display for what their Command key is
+   * @defaultValue `navigator.appVersion.includes("Mac") ? "⌘" : "Control"`
+   */
+  static CONTROL_KEY_STRING: string;
+
+  /**
+   * 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.
+   * @defaultValue
+   * ```js
+   * {
+   *   ArrowLeft: "⬅",
+   *   ArrowRight: "➡",
+   *   ArrowUp: "⬆",
+   *   ArrowDown: "⬇",
+   *   Backquote: "`",
+   *   Backslash: "\\",
+   *   BracketLeft: "[",
+   *   BracketRight: "]",
+   *   Comma: ",",
+   *   Control: this.CONTROL_KEY_STRING,
+   *   Equal: "=",
+   *   Meta: isMac ? "⌘" : "⊞",
+   *   MetaLeft: isMac ? "⌘" : "⊞",
+   *   MetaRight: isMac ? "⌘" : "⊞",
+   *   OsLeft: isMac ? "⌘" : "⊞",
+   *   OsRight: isMac ? "⌘" : "⊞",
+   *   Minus: "-",
+   *   NumpadAdd: "Numpad+",
+   *   NumpadSubtract: "Numpad-",
+   *   Period: ".",
+   *   Quote: "'",
+   *   Semicolon: ";",
+   *   Slash: "/"
+   * }
+   * ```
+   */
+  static KEYCODE_DISPLAY_MAPPING: Record<string, string>;
+
+  /**
+   * Matches any single graphic Unicode code-point (letters, digits, punctuation, symbols, including emoji).
+   * Non-printable identifiers like *ArrowLeft*, *ShiftLeft*, *Dead* never match.
+   */
+  static PRINTABLE_CHAR_REGEX: RegExp;
+
+  /**
+   * Canonical identifier for a key press.
+   */
+  static translateKey(event: KeyboardEvent): string;
+
+  /**
+   * Determines whether an `HTMLElement` currently has focus, which may influence keybinding actions.
+   *
+   * An element is considered to have focus if:
+   * 1. It has a `dataset.keyboardFocus` attribute explicitly set to `"true"` or an empty string (`""`).
+   * 2. It is an `<input>`, `<select>`, or `<textarea>` element, all of which inherently accept keyboard input.
+   * 3. It has the `isContentEditable` property set to `true`, meaning it is an editable element.
+   * 4. It is a `<button>` element inside a `<form>`, which suggests interactive use.
+   *
+   * An element is considered **not** focused if:
+   * 1. There is no currently active element (`document.activeElement` is not an `HTMLElement`).
+   * 2. It has a `dataset.keyboardFocus` attribute explicitly set to `"false"`.
+   *
+   * If none of these conditions are met, the element is assumed to be unfocused.
+   */
+  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 {@linkcode KeyboardEvent.code | KeyboardEvent#code} which is being pressed
+   */
+  static emulateKeypress(
+    up: boolean,
+    key: string,
+    options?: KeyboardManager.EmulateKeypressOptions,
+  ): 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: keyof KeyboardManager.ModifierKeys): 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;
+
+  /** @deprecated Removed in v13 (this warning will be removed in v14) */
+  protected static _getContextDisplayString(context: never, includeModifiers: never): never;
+
+  /**
+   * Given a keyboard-event context, return every registered keybinding that matches it (may be empty).
+   * @internal
+   */
+  protected static _getMatchingActions(
+    context: KeyboardManager.KeyboardEventContext,
+  ): ClientKeybindings.KeybindingAction[];
+
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected static _testContext(action: never, context: never): never;
+
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected static _executeKeybind(keybind: never, context: never): never;
+
+  /**
+   * Processes a keyboard event context, checking it against registered keybinding actions
+   * @param context - The keyboard event context
+   * @internal
+   */
+  protected _processKeyboardContext(
+    context: KeyboardManager.KeyboardEventContext,
+    options?: KeyboardManager.ProcessKeyboardContextOptions,
+  ): void;
+
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected _reset(): never;
+
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected _handleKeyboardEvent(event: never, up: never): never;
+
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected _onCompositionEnd(event: never): never;
+
+  /**
+   * 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(options?: KeyboardManager.ReleaseKeysOptions): void;
+
+  /**
+   * Release any down keys when focusing a form element.
+   * @param event - The focus event.
+   */
+  protected _onFocusIn(event: FocusEvent): void;
+
+  #KeyboardManager: true;
+}
+
+declare namespace KeyboardManager {
+  interface Any extends AnyKeyboardManager {}
+  interface AnyConstructor extends Identity<typeof AnyKeyboardManager> {}
+
+  type MODIFIER_KEYS = Brand<string, "KeyboardManager.MODIFIER_KEYS">;
+
+  interface ModifierKeys {
+    CONTROL: "Control" & MODIFIER_KEYS;
+    SHIFT: "Shift" & MODIFIER_KEYS;
+    ALT: "Alt" & MODIFIER_KEYS;
+  }
+
+  interface ModifierCodes {
+    Alt: string[];
+    Control: string[];
+    Shift: string[];
+  }
+
+  /** @internal */
+  type _EmulateKeypressOptions = InexactPartial<{
+    /**
+     * Emulate the ALT modifier as pressed
+     * @defaultValue `false`
+     */
+    altKey: boolean;
+
+    /**
+     * Emulate the CONTROL modifier as pressed
+     * @defaultValue `false`
+     */
+    ctrlKey: boolean;
+
+    /**
+     * Emulate the SHIFT modifier as pressed
+     * @defaultValue `false`
+     */
+    shiftKey: boolean;
+
+    /**
+     * Emulate this as a repeat event
+     * @defaultValue `false`
+     */
+    repeat: boolean;
+
+    /**
+     * Force the event to be handled.
+     * @defaultValue `false`
+     */
+    force: boolean;
+  }>;
+
+  interface EmulateKeypressOptions extends _EmulateKeypressOptions {}
+
+  /**
+   * Keyboard event context
+   */
+  interface KeyboardEventContext {
+    /** The normalized string key, such as "KeyA" */
+    key: string;
+
+    /** The logical string key, such as "a" */
+    logicalKey: 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;
+  }
+
+  interface ProcessKeyboardContextOptions extends Pick<EmulateKeypressOptions, "force"> {}
+
+  type _ReleaseKeysOptions = InexactPartial<{
+    /**
+     * Force the keyup events to be handled.
+     * @defaultValue `true`
+     */
+    force: boolean;
+  }>;
+
+  interface ReleaseKeysOptions extends _ReleaseKeysOptions {}
+}
+
+export default KeyboardManager;
+
+declare abstract class AnyKeyboardManager extends KeyboardManager {
+  constructor(...args: never);
+}

package/src/foundry/client/helpers/interaction/mouse-manager.d.mts

@@ -0,0 +1,42 @@
+import type { Identity } from "#utils";
+
+/**
+ * Management class for Mouse events
+ * @see {@linkcode foundry.Game.mouse | Game#mouse}
+ */
+declare class MouseManager {
+  /**
+   * @remarks
+   * @throws If `game.mouse` is already initialized
+   */
+  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;
+
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected _onWheel(event: never): never;
+
+  #MouseManager: true;
+}
+
+declare namespace MouseManager {
+  interface Any extends AnyMouseManager {}
+  interface AnyConstructor extends Identity<typeof AnyMouseManager> {}
+}
+
+export default MouseManager;
+
+declare abstract class AnyMouseManager extends MouseManager {
+  constructor(...args: never);
+}

package/src/foundry/client/helpers/interaction/tooltip-manager.d.mts

@@ -0,0 +1,268 @@
+import type { Brand, Identity, InexactPartial, IntentionalPartial } from "#utils";
+
+/**
+ * A singleton Tooltip Manager class responsible for rendering and positioning a dynamic tooltip element which is
+ * accessible as `game.tooltip`.
+ *
+ * @see {@linkcode foundry.Game.tooltip | Game#tooltip}
+ *
+ * @example API Usage
+ * ```typescript
+ * game.tooltips.activate(htmlElement, {text: "Some tooltip text", direction: "UP"});
+ * game.tooltips.deactivate();
+ * ```
+ *
+ * @example HTML Usage
+ * ```html
+ * <span data-tooltip="Some Tooltip" data-tooltip-direction="LEFT">I have a tooltip</span>
+ * <ol data-tooltip-direction="RIGHT">
+ *   <li data-tooltip="The First One">One</li>
+ *   <li data-tooltip="The Second One">Two</li>
+ *   <li data-tooltip="The Third One">Three</li>
+ * </ol>
+ * ```
+ */
+declare class TooltipManager {
+  /**
+   * @remarks
+   * @throws If `game.tooltip` is already initialized
+   */
+  constructor();
+
+  /**
+   * A cached reference to the global tooltip element
+   * @defaultValue `document.getElementById("tooltip")`
+   */
+  tooltip: HTMLElement;
+
+  /**
+   * A reference to the HTML element which is currently tool-tipped, if any.
+   */
+  element: HTMLElement | null;
+
+  /**
+   * An amount of margin which is used to offset tooltips from their anchored element.
+   * @defaultValue `5`
+   */
+  static TOOLTIP_MARGIN_PX: number;
+
+  /**
+   * The number of milliseconds delay which activates a tooltip on a "long hover".
+   * @defaultValue `500`
+   */
+  static TOOLTIP_ACTIVATION_MS: number;
+
+  /**
+   * The directions in which a tooltip can extend, relative to its tool-tipped element.
+   */
+  static TOOLTIP_DIRECTIONS: TooltipManager.TooltipDirections;
+
+  /**
+   * The number of pixels buffer around a locked tooltip zone before they should be dismissed.
+   * @defaultValue `50`
+   */
+  static LOCKED_TOOLTIP_BUFFER_PX: number;
+
+  /**
+   * Activate interactivity by listening for hover events on HTML elements which have a data-tooltip defined.
+   */
+  activateEventListeners(): void;
+
+  /**
+   * Activate the tooltip for a hovered HTML element which defines a tooltip localization key.
+   * @param element - The HTML element being hovered.
+   * @param options - Additional options which can override tooltip behavior. (default: `{}`)
+   * @remarks
+   * @throws If both `text` and `html` (or `text` and `content`) are passed
+   */
+  activate(element: HTMLElement, options?: TooltipManager.ActivateOptions): void;
+
+  /**
+   * Deactivate the tooltip from a previously hovered HTML element.
+   */
+  deactivate(): void;
+
+  /**
+   * Clear any pending activation workflow.
+   * @internal
+   */
+  clearPending(): void;
+
+  /**
+   * Lock the current tooltip.
+   */
+  lockTooltip(): HTMLElement;
+
+  /**
+   * Handle a request to lock the current tooltip.
+   * @param event - The click event.
+   */
+  protected _onLockTooltip(event: MouseEvent): void;
+
+  /**
+   * Handle dismissing a locked tooltip.
+   * @param event - The click event.
+   */
+  protected _onLockedTooltipDismiss(event: MouseEvent): void;
+
+  /**
+   * Dismiss a given locked tooltip.
+   * @param element - The locked tooltip to dismiss.
+   */
+  dismissLockedTooltip(element: HTMLElement): void;
+
+  /**
+   * Dismiss the set of active locked tooltips.
+   */
+  dismissLockedTooltips(): void;
+
+  /**
+   * Create a locked tooltip at the given position.
+   * @param position - A position object with coordinates for where the tooltip should be placed
+   * @param text     - Explicit tooltip text or HTML to display.
+   * @param options  - Additional options which can override tooltip behavior.
+   * @remarks Presumably passing at least one of `top` or `bottom` and one of `left` or `right` for
+   * `position` is necessary for proper operation, but this is not enforced
+   */
+  createLockedTooltip(
+    position: TooltipManager.Position,
+    text: string,
+    options?: TooltipManager.CreateLockedTooltipOptions,
+  ): HTMLElement;
+
+  /**
+   * If an explicit tooltip expansion direction was not specified, figure out a valid direction based on the bounds
+   * of the target element and the screen.
+   */
+  protected _determineDirection(): TooltipManager.TOOLTIP_DIRECTIONS;
+
+  /**
+   * Set tooltip position relative to an HTML element using an explicitly provided data-tooltip-direction.
+   * @param direction - The tooltip expansion direction specified by the element or a parent element.
+   */
+  protected _setAnchor(direction: TooltipManager.TOOLTIP_DIRECTIONS): void;
+
+  /**
+   * Apply inline styling rules to the tooltip for positioning and text alignment.
+   * @param position - An object of positioning data, supporting top, right, bottom, left, and textAlign
+   */
+  protected _setStyle(position?: TooltipManager.SetStylePosition): void;
+
+  /**
+   * Retrieve the configured TooltipManager implementation
+   */
+  // TODO: Config.ux handling
+  static get implementation(): typeof TooltipManager;
+
+  #TooltipManager: true;
+}
+
+declare namespace TooltipManager {
+  interface Any extends AnyTooltipManager {}
+  interface AnyConstructor extends Identity<typeof AnyTooltipManager> {}
+
+  /**
+   * The directions in which a tooltip can extend, relative to its tool-tipped element.
+   */
+  type TOOLTIP_DIRECTIONS = Brand<string, "TooltipManager.TOOLTIP_DIRECTIONS">;
+
+  interface TooltipDirections {
+    UP: "UP" & TOOLTIP_DIRECTIONS;
+    DOWN: "DOWN" & TOOLTIP_DIRECTIONS;
+    LEFT: "LEFT" & TOOLTIP_DIRECTIONS;
+    RIGHT: "RIGHT" & TOOLTIP_DIRECTIONS;
+    CENTER: "CENTER" & TOOLTIP_DIRECTIONS;
+  }
+
+  /** @internal */
+  type _ActivateOptions = InexactPartial<{
+    /**
+     * Explicit tooltip text to display. If this is not provided the tooltip text is acquired from
+     * the element's `data-tooltip-text` attribute if present and otherwise from its `data-tooltip`
+     * attribute. The `data-tooltip` text will be automatically localized. If `data-tooltip` is not
+     * a localization string, the text is rendered as HTML (cleaned). Both `options.text` and
+     * `data-tooltip-text` do not support HTML. It is not recommended to use `data-tooltip` for
+     * plain text and HTML as it could cause an unintentional localization. Instead use
+     * `data-tooltip-text` and `data-tooltip-html`, respectively.
+     */
+    text: string;
+
+    /**
+     * An explicit tooltip expansion direction. If this is not provided, the direction is acquired
+     * from the `data-tooltip-direction` attribute of the element or one of its parents.
+     */
+    direction: TOOLTIP_DIRECTIONS;
+
+    /**
+     * An optional, space-separated list of CSS classes to apply to the activated tooltip. If this
+     * is not provided, the CSS classes are acquired from the `data-tooltip-class` attribute of the
+     * element or one of its parents.
+     */
+    cssClass: string;
+
+    /**
+     * An optional boolean to lock the tooltip after creation. Defaults to false.
+     * @defaultValue `false`
+     */
+    locked: boolean;
+
+    /**
+     * Explicit HTML to inject into the tooltip rather than using tooltip text. If passed as a string,
+     * the HTML string is cleaned with {@linkcode foundry.utils.cleanHTML}. An explicit HTML string may
+     * also be set with the `data-tooltip-html` attribute on the element.
+     */
+    html: HTMLElement | string;
+
+    /**
+     * Explicit HTML content to inject into the tooltip rather than using tooltip text.
+     * @deprecated "The `content` option has been deprecated in favor of the `html` option" (since v13, until v15)
+     * @remarks Ignored if `html` is passed
+     */
+    content: HTMLElement;
+  }>;
+
+  interface ActivateOptions extends _ActivateOptions {}
+
+  /** @internal */
+  interface _BasePosition {
+    /** Explicit top position for the tooltip */
+    top: string;
+
+    /** Explicit right position for the tooltip */
+    right: string;
+
+    /** Explicit bottom position for the tooltip */
+    bottom: string;
+
+    /** Explicit left position for the tooltip */
+    left: string;
+  }
+
+  interface Position extends InexactPartial<_BasePosition> {}
+
+  /** @internal */
+  type _CreateLockedTooltipOptions = InexactPartial<{
+    /**
+     * An optional, space-separated list of CSS classes to apply to the activated tooltip.
+     */
+    cssClass: string;
+  }>;
+
+  interface CreateLockedTooltipOptions extends _CreateLockedTooltipOptions {}
+
+  /**
+   * @privateRemarks This is spread into an object with existing defaults (all `null`s for the `_BasePosition` properties).
+   * Distinguishing that and the `""` defaults in {@link TooltipManager.createLockedTooltip | `TooltipManager#createLockedTooltip`}
+   * is not worth repeating the properties; falsey is falsey in this case.
+   */
+  interface SetStylePosition extends IntentionalPartial<_BasePosition> {
+    /** @defaultValue `left` */
+    textAlign?: string;
+  }
+}
+
+export default TooltipManager;
+
+declare abstract class AnyTooltipManager extends TooltipManager {
+  constructor(...args: never);
+}