@7h3laughingman/foundry-types 13.351.0

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

@@ -0,0 +1,189 @@
+import { KeybindingAction, KeyboardEventContext, ModifierKey } from "./../../_types.mjs";
+
+/**
+ * A set of helpers and management functions for dealing with user input from keyboard events.
+ * {@link https://keycode.info/}
+ * @see {@link foundry.Game#keyboard}
+ */
+export default class KeyboardManager {
+    constructor();
+
+    /**
+     * Begin listening to keyboard events.
+     * @internal
+     */
+    _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.
+     * @type {Record<string, string>}
+     */
+    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: "/";
+    };
+
+    /**
+     * 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;
+
+    /* -------------------------------------------- */
+    /*  Methods                                     */
+    /* -------------------------------------------- */
+
+    /**
+     * 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 options Additional options to configure behavior.
+     * @param options.altKey Emulate the ALT modifier as pressed
+     * @param options.ctrlKey Emulate the CONTROL modifier as pressed
+     * @param options.shiftKey Emulate the SHIFT modifier as pressed
+     * @param options.repeat Emulate this as a repeat event
+     * @param options.force Force the event to be handled.
+     */
+    static emulateKeypress(
+        up: boolean,
+        code: string,
+        options?: { 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
+     * @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: ModifierKey): 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;
+
+    /**
+     * 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[];
+
+    /**
+     * Processes a keyboard event context, checking it against registered keybinding actions
+     * @param context The keyboard event context
+     * @param options Additional options to configure behavior.
+     * @param options.force Force the event to be handled.
+     */
+    protected _processKeyboardContext(context: KeyboardEventContext, options?: { force?: boolean }): 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 options Options to configure behavior.
+     * @param options.force Force the keyup events to be handled.
+     */
+    releaseKeys({ force }?: { force?: boolean }): void;
+
+    /* -------------------------------------------- */
+    /*  Event Listeners and Handlers                */
+    /* -------------------------------------------- */
+
+    /**
+     * Release any down keys when focusing a form element.
+     * @param event The focus event.
+     */
+    protected _onFocusIn(event: FocusEvent): void;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Management class for Mouse events.
+ * @see {@link foundry.Game#mouse}
+ */
+export default 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
+     */
+    static MOUSE_WHEEL_RATE_LIMIT: number;
+
+    /**
+     * Begin listening to mouse events.
+     * @internal
+     */
+    _activateListeners(): void;
+}

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

@@ -0,0 +1,227 @@
+/**
+ * A singleton Tooltip Manager class responsible for rendering and positioning a dynamic tooltip element which is
+ * accessible as `game.tooltip`.
+ *
+ * @see {@link foundry.Game#tooltip}
+ *
+ * @example API Usage
+ * ```js
+ * game.tooltip.activate(htmlElement, {text: "Some tooltip text", direction: "UP"});
+ * game.tooltip.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>
+ * ```
+ */
+export default class TooltipManager {
+    constructor();
+
+    /**
+     * A cached reference to the global tooltip element
+     */
+    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.
+     */
+    static TOOLTIP_MARGIN_PX: number;
+
+    /**
+     * The number of milliseconds delay which activates a tooltip on a "long hover".
+     */
+    static TOOLTIP_ACTIVATION_MS: number;
+
+    /**
+     * The directions in which a tooltip can extend, relative to its tool-tipped element.
+     */
+    static TOOLTIP_DIRECTIONS: Readonly<{
+        UP: "UP";
+        DOWN: "DOWN";
+        LEFT: "LEFT";
+        RIGHT: "RIGHT";
+        CENTER: "CENTER";
+    }>;
+
+    /**
+     * The number of pixels buffer around a locked tooltip zone before they should be dismissed.
+     */
+    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.
+     * @param options.text 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.
+     * @param options.direction 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.
+     * @param options.cssClass 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.
+     * @param options.locked An optional boolean to lock the tooltip after creation. Defaults to false.
+     * @param options.html Explicit HTML to inject into the tooltip rather than using tooltip text. If passed as a
+     *                     string, the HTML string is cleaned with {@link foundry.utils.cleanHTML}. An explicit HTML
+     *                     string may also be set with the `data-tooltip-html` attribute on the element.
+     */
+    activate(element: HTMLElement, options?: TooltipActivationOptions): 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: PointerEvent): void;
+
+    /**
+     * Handle dismissing a locked tooltip.
+     * @param event The click event.
+     */
+    protected _onLockedTooltipDismiss(event: PointerEvent): 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 position.top Explicit top position for the tooltip
+     * @param position.right Explicit right position for the tooltip
+     * @param position.bottom Explicit bottom position for the tooltip
+     * @param position.left Explicit left position for the tooltip
+     * @param text Explicit tooltip text or HTML to display.
+     * @param options Additional options which can override tooltip behavior.
+     * @param options.cssClass An optional, space-separated list of CSS classes to apply to the activated tooltip.
+     */
+    createLockedTooltip(position: { top: string; right: string; bottom: string; left: string }, text: string, options?: { cssClass?: string }): 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(): "UP" | "DOWN";
+
+    /**
+     * 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: TooltipDirection): 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?: {
+        top?: number | null;
+        right?: number | null;
+        button?: number | null;
+        left?: number | null;
+        textAlign?: string | null;
+    }): void;
+
+    /* -------------------------------------------- */
+    /*  Factory Methods                             */
+    /* -------------------------------------------- */
+
+    /**
+     * Retrieve the configured TooltipManager implementation.
+     */
+    static get implementation(): typeof TooltipManager;
+}
+
+/**
+ * Activate the tooltip for a hovered HTML element which defines a tooltip localization key.
+ * @param {HTMLElement} element      The HTML element being hovered.
+ * @param {object} [options={}]      Additional options which can override tooltip behavior.
+ * @param {string} [options.text]
+ * @param {TooltipDirection} [options.direction]  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.
+ * @param {string} [options.cssClass]   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.
+ * @param {boolean} [options.locked=false]  An optional boolean to lock the tooltip after creation. Defaults to false.
+ * @param {HTMLElement|string} [options.html]     Explicit HTML to inject into the tooltip rather than using
+ *                                                tooltip text. If passed as a string, the HTML string is cleaned with
+ *                                                {@link foundry.utils.cleanHTML}. An explicit HTML string may also
+ *                                                be set with the `data-tooltip-html` attribute on the element.
+ */
+
+declare interface TooltipActivationOptions {
+    /**
+     * 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?: TooltipDirection;
+    /**
+     * 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. */
+    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 {@link foundry.utils.cleanHTML}. An explicit HTML string may also be set with the
+     * `data-tooltip-html` attribute on the element.
+     */
+    html?: HTMLElement | string;
+}
+
+export type TooltipDirection = keyof typeof TooltipManager.TOOLTIP_DIRECTIONS;
+
+export {};

package/src/client/helpers/localization.d.mts

@@ -0,0 +1,143 @@
+import DataModel from "./../../common/abstract/data.mjs";
+import { DataField, SchemaField } from "./../../common/data/fields.mjs";
+
+/**
+ * A helper class which assists with localization and string translation
+ */
+export default class Localization {
+    /**
+     * The target language for localization
+     */
+    lang: string;
+
+    /**
+     * The translation dictionary for the target language
+     */
+    translations: Record<string, TranslationDictionaryValue>;
+
+    /**
+     * Fallback translations if the target keys are not found
+     */
+    _fallback: Record<string, TranslationDictionaryValue>;
+
+    /**
+     * @param serverLanguage The default language configuration setting for the server
+     */
+    constructor(serverLanguage: string);
+
+    /**
+     * Initialize the Localization module
+     * Discover available language translations and apply the current language setting
+     */
+    initialize(): Promise<void>;
+
+    /* -------------------------------------------- */
+    /*  Data Model Localization                     */
+    /* -------------------------------------------- */
+
+    /**
+     * Perform one-time localization of the fields in a DataModel schema, translating their label and hint properties.
+     * @param {typeof DataModel} model          The DataModel class to localize
+     * @param {object} options                  Options which configure how localization is performed
+     * @param {string[]} [options.prefixes]       An array of localization key prefixes to use. If not specified, prefixes
+     *                                            are learned from the DataModel.LOCALIZATION_PREFIXES static property.
+     * @param {string} [options.prefixPath]       A localization path prefix used to prefix all field names within this
+     *                                            model. This is generally not required.
+     *
+     * @example
+     * JavaScript class definition and localization call.
+     * ```js
+     * class MyDataModel extends foundry.abstract.DataModel {
+     *   static defineSchema() {
+     *     return {
+     *       foo: new foundry.data.fields.StringField(),
+     *       bar: new foundry.data.fields.NumberField()
+     *     };
+     *   }
+     *   static LOCALIZATION_PREFIXES = ["MYMODULE.MYDATAMODEL"];
+     * }
+     *
+     * Hooks.on("i18nInit", () => {
+     *   Localization.localizeDataModel(MyDataModel);
+     * });
+     * ```
+     *
+     * JSON localization file
+     * ```json
+     * {
+     *   "MYMODULE": {
+     *     "MYDATAMODEL": {
+     *       "FIELDS" : {
+     *         "foo": {
+     *           "label": "Foo",
+     *           "hint": "Instructions for foo"
+     *         },
+     *         "bar": {
+     *           "label": "Bar",
+     *           "hint": "Instructions for bar"
+     *         }
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    static localizeDataModel(model: AbstractConstructorOf<DataModel>, options?: { prefixes?: string[]; prefixPath?: string }): void;
+
+    /**
+   * Localize the "label" and "hint" properties for all fields in a data schema.
+
+   */
+    static localizeSchema(schema: SchemaField, prefixes?: string[], options?: { prefixPath?: string; seenFields?: Set<DataField> }): void;
+
+    /**
+     * Set a language as the active translation source for the session
+     * @param lang A language string in CONFIG.supportedLanguages
+     * @returns A Promise which resolves once the translations for the requested language are ready
+     */
+    setLanguage(lang: string): Promise<void>;
+
+    /* -------------------------------------------- */
+    /*  Localization API                            */
+    /* -------------------------------------------- */
+
+    /**
+     * Return whether a certain string has a known translation defined.
+     * @param stringId The string key being translated
+     * @param fallback Allow fallback translations to count?
+     */
+    has(stringId: string, fallback?: boolean): boolean;
+
+    /**
+     * Localize a string by drawing a translation from the available translations dictionary, if available
+     * If a translation is not available, the original string is returned
+     * @param stringId  The string ID to translate
+     * @return          The translated string
+     */
+    localize(stringId: string): string;
+
+    /**
+     * Localize a string including variable formatting for input arguments.
+     * Provide a string ID which defines the localized template.
+     * Variables can be included in the template enclosed in braces and will be substituted using those named keys.
+     *
+     * @param stringId The string ID to translate
+     * @param data     Provided input data
+     * @return The translated and formatted string
+     *
+     * @example
+     * const stringId = "MY_TEST_STRING"; // "Your name is {name}"
+     * game.i18n.format("MY_TEST_STRING", {name: "Andrew"}); // Produces "Your name is Andrew"
+     */
+    format(stringId: string, data?: Record<string, Maybe<string | number | boolean>>): string;
+
+    /**
+     * Retrieve list formatter configured to the world's language setting.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat}
+     * @param options.style The list formatter style, either "long", "short", or "narrow".
+     * @param options.type The list formatter type, either "conjunction", "disjunction", or "unit".
+     */
+    getListFormatter(options?: { style?: Intl.ListFormatStyle; type?: Intl.ListFormatType }): Intl.ListFormat;
+}
+
+type TranslationDictionaryValue = string | { [key: string]: TranslationDictionaryValue };

package/src/client/helpers/media/_module.d.mts

@@ -0,0 +1,3 @@
+export { default as CompendiumArt } from "./compendium-art.mjs";
+export { default as ImageHelper } from "./image-helper.mjs";
+export { default as VideoHelper } from "./video-helper.mjs";

package/src/client/helpers/media/compendium-art.d.mts

@@ -0,0 +1,29 @@
+import { CompendiumArtDescriptor, CompendiumArtInfo } from "../_types.mjs";
+
+/**
+ * A class responsible for managing package-provided art and applying it to Documents in compendium packs.
+ */
+export default class CompendiumArt extends Map<string, CompendiumArtInfo> {
+    constructor(entries: readonly (readonly [string, CompendiumArtInfo])[] | null);
+
+    /** The key for the package manifest flag used to store the mapping information. */
+    FLAG: "compendiumArtMappings";
+
+    /** The key for the setting used to store the World's art preferences. */
+    SETTING: "compendiumArtConfiguration";
+
+    /**
+     * Whether art application is enabled. This should be switched off when performing client-side compendium migrations
+     * in order to avoid persisting injected data.
+     */
+    enabled: boolean;
+
+    /** Retrieve all active packages that provide art mappings in priority order. */
+    getPackages(): CompendiumArtDescriptor[];
+
+    /**
+     * Collate Document art mappings from active packages.
+     * @internal
+     */
+    _registerArt(): Promise<void>;
+}