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

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

@@ -0,0 +1,20 @@
+export {};
+
+declare global {
+  /**
+   * A helper class to manage requesting clipboard permissions and provide common functionality for working with the
+   * clipboard.
+   */
+  class ClipboardHelper {
+    /**
+     * @throws `"You may not re-initialize the singleton ClipboardHelper. Use game.clipboard instead."`
+     */
+    constructor();
+
+    /**
+     * Copies plain text to the clipboard in a cross-browser compatible way.
+     * @param text - The text to copy.
+     */
+    copyPlainText(text: string): Promise<void>;
+  }
+}

package/src/foundry/client/core/document-index.d.mts

@@ -0,0 +1,118 @@
+import type { DOCUMENT_OWNERSHIP_LEVELS } from "../../common/constants.d.mts";
+
+export {};
+
+declare global {
+  /**
+   * This class is responsible for indexing all documents available in the world and storing them in a word tree structure
+   * that allows for fast searching.
+   */
+  class DocumentIndex {
+    constructor();
+    /**
+     * A collection of WordTree structures for each document type.
+     * @defaultValue `{}`
+     */
+    trees: Record<string, foundry.utils.WordTree>;
+
+    /**
+     * A reverse-lookup of a document's UUID to its parent node in the word tree.
+     * @defaultValue `{}`
+     */
+    uuids: Record<string, foundry.utils.StringTree.StringTreeNode>;
+
+    /**
+     * Returns a Promise that resolves when the indexing process is complete.
+     */
+    get ready(): Promise<void> | null;
+
+    /**
+     * Index all available documents in the world and store them in a word tree.
+     */
+    index(): Promise<void>;
+
+    /**
+     * Return entries that match the given string prefix.
+     * @param prefix  - The prefix.
+     * @param options - Additional options to configure behaviour.
+     * @returns A number of entries that have the given prefix, grouped by document type.
+     */
+    lookup(
+      prefix: string,
+      options?: {
+        /**
+         * The maximum number of items per document type to retrieve. It is important to set this
+         * value as very short prefixes will naturally match large numbers of entries. (default: `10`)
+         * (default: `10`)
+         */
+        limit?: number;
+        /**
+         * Optionally provide an array of document types. Only entries of that type
+         * will be searched for. (default: `[]`)
+         */
+        documentTypes?: string[];
+        /**
+         * A filter function to apply to each candidate entry.
+         */
+        filterEntries?: foundry.utils.StringTree.StringTreeEntryFilter;
+        /**
+         * Only return entries that the user meets this ownership level for.
+         */
+        ownership?: DOCUMENT_OWNERSHIP_LEVELS;
+      },
+    ): Record<string, foundry.utils.WordTree.WordTreeEntry[]>;
+
+    /**
+     * Add an entry to the index.
+     * @param doc - The document entry.
+     */
+    addDocument(doc: foundry.abstract.Document.Any): void;
+
+    /**
+     * Remove an entry from the index.
+     * @param doc - The document entry.
+     */
+    removeDocument(doc: foundry.abstract.Document.Any): void;
+
+    /**
+     * Replace an entry in the index with an updated one.
+     * @param doc - The document entry.
+     */
+    replaceDocument(doc: foundry.abstract.Document.Any): void;
+
+    /**
+     * Add a leaf node to the word tree index.
+     * @param doc     - The document or compendium index entry to add.
+     * @param options - Additional information for indexing.
+     * @internal
+     */
+    protected _addLeaf(
+      doc: foundry.abstract.Document.Any,
+      options?: {
+        /** The compendium that the index belongs to. */
+        pack?: CompendiumCollection.Any;
+      },
+    ): void;
+
+    /**
+     * Aggregate the compendium index and add it to the word tree index.
+     * @param pack - The compendium pack.
+     * @internal
+     */
+    protected _indexCompendium(pack: CompendiumCollection.Any): void;
+
+    /**
+     * Add all of a parent document's embedded documents to the index.
+     * @param parent - The parent document.
+     * @internal
+     */
+    protected _indexEmbeddedDocuments(parent: foundry.abstract.Document.Any): void;
+
+    /**
+     * Aggregate all documents and embedded documents in a world collection and add them to the index.
+     * @param documentName - The name of the documents to index.
+     * @internal
+     */
+    protected _indexWorldCollection(documentName: string): void;
+  }
+}

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

@@ -0,0 +1,62 @@
+export {};
+
+declare global {
+  /** Management class for Gamepad events */
+  class GamepadManager {
+    constructor();
+
+    /**
+     * @defaultValue `null`
+     * @internal
+     */
+    protected _gamepadPoller: number | null;
+
+    /**
+     * The connected Gamepads
+     * @internal
+     */
+    protected _connectedGamepads: Map<string, ConnectedGamepad>;
+
+    /**
+     * How often Gamepad polling should check for button presses
+     * @defaultValue `100`
+     */
+    static GAMEPAD_POLLER_INTERVAL_MS: number;
+
+    /**
+     * Begin listening to gamepad events.
+     */
+    protected _activateListeners(): void;
+
+    /**
+     * Handles a Gamepad Connection event, adding its info to the poll list
+     * @param event - The originating Event
+     * @internal
+     */
+    protected _onGamepadConnect(event: GamepadEvent): void;
+
+    /**
+     * Handles a Gamepad Disconnect event, removing it from consideration for polling
+     * @param event - The originating Event
+     * @internal
+     */
+    protected _onGamepadDisconnect(event: GamepadEvent): void;
+
+    /**
+     * Polls all Connected Gamepads for updates. If they have been updated, checks status of Axis and Buttons,
+     * firing off Keybinding Contexts as appropriate
+     * @internal
+     */
+    protected _pollGamepads(): void;
+
+    /**
+     * Converts a Gamepad Input event into a KeyboardEvent, then fires it
+     * @param gamepadId - The string representation of the Gamepad Input
+     * @param up        - True if the Input is pressed or active
+     * @param repeat    - True if the Input is being held
+     *                    (default: `false`)
+     * @internal
+     */
+    protected _handleGamepadInput(gamepadId: string, up: boolean, repeat?: boolean): void;
+  }
+}

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

@@ -0,0 +1,132 @@
+import type { AnyFunction } from "../../../types/utils.d.mts";
+
+export {};
+
+declare global {
+  /**
+   * A simple event framework used throughout Foundry Virtual Tabletop.
+   * When key actions or events occur, a "hook" is defined where user-defined callback functions can execute.
+   * This class manages the registration and execution of hooked callback functions.
+   */
+  class Hooks {
+    /**
+     * A mapping of hook events which have functions registered to them.
+     */
+    static get events(): Hooks.HookedFunction[];
+
+    /**
+     * Register a callback handler which should be triggered when a hook is triggered.
+     *
+     * @param hook    - The unique name of the hooked event
+     * @param fn      - The callback function which should be triggered when the hook event occurs
+     * @param options - Options which customize hook registration
+     * @returns An ID number of the hooked function which can be used to turn off the hook later
+     */
+    static on<K extends keyof Hooks.StaticCallbacks>(
+      hook: K,
+      fn: Hooks.StaticCallbacks[K],
+      options?: Hooks.OnOptions,
+    ): number;
+    static on<H extends Hooks.DynamicCallbacks>(hook: string, fn: H, options?: Hooks.OnOptions): number;
+    static on<H extends (...args: any) => any>(hook: string, fn: H, options?: Hooks.OnOptions): number;
+
+    /**
+     * Register a callback handler for an event which is only triggered once the first time the event occurs.
+     * An alias for Hooks.on with `{once: true}`
+     * @param hook - The unique name of the hooked event
+     * @param fn   - The callback function which should be triggered when the hook event occurs
+     * @returns An ID number of the hooked function which can be used to turn off the hook later
+     */
+    static once<K extends keyof Hooks.StaticCallbacks>(
+      hook: K,
+      fn: Hooks.StaticCallbacks[K],
+    ): ReturnType<(typeof Hooks)["on"]>;
+    static once<H extends Hooks.DynamicCallbacks>(hook: string, fn: H): ReturnType<(typeof Hooks)["on"]>;
+    static once<H extends (...args: any) => any>(hook: string, fn: H): ReturnType<(typeof Hooks)["on"]>;
+
+    /**
+     * Unregister a callback handler for a particular hook event
+     *
+     * @param hook - The unique name of the hooked event
+     * @param fn   - The function, or ID number for the function, that should be turned off
+     */
+    static off<K extends keyof Hooks.StaticCallbacks>(hook: K, fn: number | Hooks.StaticCallbacks[K]): void;
+    static off<H extends Hooks.DynamicCallbacks>(hook: string, fn: number | H): void;
+    static off<H extends (...args: any) => any>(hook: string, fn: number | H): void;
+
+    /**
+     * Call all hook listeners in the order in which they were registered
+     * Hooks called this way can not be handled by returning false and will always trigger every hook callback.
+     *
+     * @param hook - The hook being triggered
+     * @param args - Arguments passed to the hook callback functions
+     */
+    static callAll<K extends keyof Hooks.StaticCallbacks>(hook: K, ...args: Parameters<Hooks.StaticCallbacks[K]>): true;
+    static callAll<H extends Hooks.DynamicCallbacks>(hook: string, ...args: Parameters<H>): true;
+    static callAll<H extends (...args: any) => any>(hook: string, ...args: Parameters<H>): true;
+
+    /**
+     * Call hook listeners in the order in which they were registered.
+     * Continue calling hooks until either all have been called or one returns false.
+     *
+     * Hook listeners which return false denote that the original event has been adequately handled and no further
+     * hooks should be called.
+     *
+     * @param hook - The hook being triggered
+     * @param args - Arguments passed to the hook callback functions
+     */
+    static call<K extends keyof Hooks.StaticCallbacks>(hook: K, ...args: Parameters<Hooks.StaticCallbacks[K]>): boolean;
+    static call<H extends Hooks.DynamicCallbacks>(hook: string, ...args: Parameters<H>): boolean;
+    static call<H extends (...args: any) => any>(hook: string, ...args: Parameters<H>): boolean;
+
+    /**
+     * Notify subscribers that an error has occurred within foundry.
+     * @param location - The method where the error was caught.
+     * @param error    - The error.
+     * @param options  - Additional options to configure behaviour.
+     */
+    static onError(
+      location: string,
+      error: Error,
+      {
+        msg,
+        notify,
+        log,
+        ...data
+      }?: {
+        /**
+         * Additional data to pass to the hook subscribers.
+         * @defaultValue `{}`
+         */
+        [key: string]: unknown;
+
+        /**
+         * A message which should prefix the resulting error or notification.
+         * @defaultValue `""`
+         */
+        msg?: string | undefined;
+
+        /**
+         * The level at which to log the error to console (if at all).
+         * @defaultValue `null`
+         */
+        notify?: keyof NonNullable<(typeof ui)["notifications"]> | null | undefined;
+
+        /**
+         * The level at which to spawn a notification in the UI (if at all).
+         * @defaultValue `null`
+         */
+        log?: keyof typeof console | null | undefined;
+      },
+    ): void;
+  }
+
+  namespace Hooks {
+    interface HookedFunction {
+      hook: string;
+      id: number;
+      fn: AnyFunction;
+      once: boolean;
+    }
+  }
+}

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

@@ -0,0 +1,190 @@
+import type { InexactPartial } from "../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * A helper class to provide common functionality for working with Image objects
+   */
+  // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+  class ImageHelper {
+    /**
+     * Create thumbnail preview for a provided image path.
+     * @param src     - The string URL or DisplayObject of the texture to render to a thumbnail
+     * @param options - Additional named options passed to the {@link ImageHelper.compositeCanvasTexture} method
+     *                  (default: `{}`)
+     * @returns The parsed and converted thumbnail data
+     */
+    static createThumbnail(
+      src: string | PIXI.DisplayObject,
+      options?: InexactPartial<ImageHelper.CompositeOptions & ImageHelper.TextureToImageOptions>,
+    ): Promise<ImageHelper.ThumbnailReturn>;
+
+    /**
+     * Composite a canvas object by rendering it to a single texture
+     * @param object  - The DisplayObject to render to a texture
+     * @param options - Additional named options
+     *                  (default: `{}`)
+     * @returns The composite Texture object
+     */
+    static compositeCanvasTexture(
+      object: PIXI.DisplayObject,
+      options?: InexactPartial<ImageHelper.CompositeOptions>,
+    ): PIXI.Texture;
+
+    /**
+     * Extract a texture to a base64 PNG string
+     * @param texture - The Texture object to extract
+     * @param options - (default: `{}`)
+     * @returns A base64 png string of the texture
+     */
+    static textureToImage(
+      texture: PIXI.Texture,
+      options?: InexactPartial<ImageHelper.TextureToImageOptions>,
+    ): Promise<string>;
+
+    /**
+     * Asynchronously convert a DisplayObject container to base64 using Canvas#toBlob and FileReader
+     * @param target  - A PIXI display object to convert
+     * @param type    - The requested mime type of the output, default is image/png
+     * @param quality - A number between 0 and 1 for image quality if image/jpeg or image/webp
+     * @returns A processed base64 string
+     */
+    static pixiToBase64(target: PIXI.DisplayObject, type: string, quality: number): Promise<string>;
+
+    /**
+     * Asynchronously convert a canvas element to base64.
+     * @param type    - (default: `["image/png"]`)
+     * @returns The base64 string of the canvas.
+     */
+    static canvasToBase64(
+      canvas: HTMLCanvasElement,
+      type?: foundry.CONST.IMAGE_FILE_EXTENSIONS,
+      quality?: number,
+    ): Promise<string>;
+
+    /**
+     * Upload a base64 image string to a persisted data storage location
+     * @param base64   - The base64 string
+     * @param fileName - The file name to upload
+     * @param filePath - The file path where the file should be uploaded
+     * @param options  - Additional options which affect uploading
+     * @returns A promise which resolves to the FilePicker upload response
+     */
+    static uploadBase64(
+      base64: string,
+      fileName: string,
+      filePath: string,
+      options?: {
+        /** The data storage location to which the file should be uploaded (default: `"data"`) */
+        storage: string;
+        /** The MIME type of the file being uploaded */
+        type?: foundry.CONST.IMAGE_FILE_EXTENSIONS;
+        /** Display a UI notification when the upload is processed. (default: `true`)  */
+        notify: boolean;
+      },
+    ): Promise<ReturnType<(typeof FilePicker)["upload"]>>;
+
+    /**
+     * Create a canvas element containing the pixel data.
+     * @param pixels - Buffer used to create the image data.
+     * @param width  - Buffered image width.
+     * @param height - Buffered image height.
+     */
+    static pixelsToCanvas(
+      pixels: Uint8ClampedArray,
+      width: number,
+      height: number,
+      options: InexactPartial<ImageHelper.PixelsToCanvasOptions>,
+    ): HTMLCanvasElement;
+  }
+
+  namespace ImageHelper {
+    /**
+     * An interface for options for the {@link ImageHelper.createThumbnail} and {@link ImageHelper.compositeCanvasTexture}
+     * methods.
+     */
+    interface CompositeOptions {
+      /**
+       * Center the texture in the rendered frame?
+       * @defaultValue `true`
+       */
+      center: boolean;
+
+      /**
+       * The desired height of the output texture
+       * @defaultValue The height of the object passed to {@link ImageHelper.compositeCanvasTexture}
+       */
+      height: number;
+
+      /**
+       * A horizontal translation to apply to the object
+       * @defaultValue `0`
+       */
+      tx: number;
+
+      /**
+       * A vertical translation to apply to the object
+       * @defaultValue `0`
+       */
+      ty: number;
+
+      /**
+       * The desired width of the output texture
+       * @defaultValue The width of the object passed to {@link ImageHelper.compositeCanvasTexture}
+       */
+      width: number;
+    }
+
+    interface TextureToImageOptions {
+      /**
+       * Image format, e.g. "image/jpeg" or "image/webp".
+       * @defaultValue `"image/png"`
+       */
+      format: string;
+
+      /**
+       * JPEG or WEBP compression from 0 to 1. Default is 0.92.
+       * @defaultValue `0.92`
+       */
+      quality: number;
+    }
+
+    /**
+     * An interface for return values of the {@link ImageHelper.createThumbnail} method.
+     */
+    interface ThumbnailReturn {
+      /**
+       * The height of the {@link PIXI.Sprite}, created by {@link ImageHelper.createThumbnail}
+       */
+      height: number;
+
+      /**
+       * The originally passed `string` URL or DisplayObject
+       */
+      src: string | PIXI.DisplayObject;
+
+      /**
+       * The Texture, returned from {@link ImageHelper.compositeCanvasTexture}, with `destroy(true)` already called on it.
+       */
+      texture: PIXI.Texture;
+
+      /**
+       * The base64 encoded image data, returned from {@link ImageHelper.textureToImage}
+       */
+      thumb: string;
+
+      /**
+       * The width of the {@link PIXI.Sprite}, created by {@link ImageHelper.createThumbnail}
+       */
+      width: number;
+    }
+
+    interface PixelsToCanvasOptions {
+      /** The element to use. */
+      element: HTMLCanvasElement;
+      /** Specified width for the element (default to buffer image width). */
+      ew: number;
+      /** Specified height for the element (default to buffer image height). */
+      eh: number;
+    }
+  }
+}

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

@@ -0,0 +1,20 @@
+import "./document-index.d.mts";
+import "./gamepad.d.mts";
+import "./hooks.d.mts";
+import "./image.d.mts";
+import "./issues.d.mts";
+import "./keybindings.d.mts";
+import "./keyboard.d.mts";
+import "./mouse.d.mts";
+import "./nue.d.mts";
+import "./packages.d.mts";
+import "./settings.d.mts";
+import "./socket.d.mts";
+import "./sorting.d.mts";
+import "./time.d.mts";
+import "./tooltip.d.mts";
+import "./tour.d.mts";
+import "./tours.d.mts";
+import "./utils.d.mts";
+import "./video.d.mts";
+import "./workers.d.mts";

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

@@ -0,0 +1,102 @@
+import type Document from "../../common/abstract/document.d.mts";
+import type { DataModelValidationError } from "../../common/data/validation-failure.d.mts";
+
+declare global {
+  /**
+   * An object structure of document types at the top level, with a count of different sub-types for that document type.
+   */
+  interface ModuleSubTypeCounts extends Record<Document.Type, Record<string, number>> {}
+
+  /**
+   * A class responsible for tracking issues in the current world.
+   */
+  class ClientIssues {
+    // placeholder private member
+    #clientIssues: true;
+
+    /**
+     * Detect and display warnings for known performance issues which may occur due to the user's hardware or browser
+     * configuration.
+     * @internal
+     */
+    _detectWebGLIssues(): void;
+
+    /**
+     * Add an invalid Document to the module-provided sub-type counts.
+     * @param cls               - The Document class.
+     * @param source            - The Document's source data.
+     * @internal
+     *
+     * @remarks official documentation says "invalid", but the document can be valid, it is simply not yet validated.
+     */
+    _countDocumentSubType(
+      cls: Document.Any,
+      source: unknown,
+      options?: {
+        /**
+         * Decrement the counter rather than incrementing it.
+         * @defaultValue `false`
+         */
+        decrement?: boolean | undefined;
+      },
+    ): void;
+
+    /**
+     * Track a validation failure that occurred in a WorldCollection.
+     * @param collection - The parent collection.
+     * @param source     - The Document's source data.
+     * @param error      - The validation error.
+     * @internal
+     */
+    _trackValidationFailures(
+      collection: WorldCollection<Document.AnyConstructor, string>,
+      source: unknown,
+      error: DataModelValidationError,
+    ): void;
+
+    /**
+     * Detect and record certain usability error messages which are likely to result in the user having a bad experience.
+     * @internal
+     */
+    _detectUsabilityIssues(): void;
+
+    /**
+     * Get the Document sub-type counts for a given module.
+     * @param module - The module or its ID.
+     */
+    getSubTypeCountsFor(module: Module | string): ModuleSubTypeCounts | undefined;
+
+    /**
+     * Retrieve all sub-type counts in the world.
+     */
+    getAllSubtypeCounts(): IterableIterator<[string, ModuleSubTypeCounts]>;
+
+    /**
+     * Retrieve the tracked validation failures.
+     */
+    get validationFailures(): Record<Document.Type, Record<string, { name: string; error: DataModelValidationError }>>;
+
+    /**
+     * Retrieve the tracked usability issues.
+     */
+    get usabilityIssues(): Record<string, ClientIssues.UsabilityIssue>;
+
+    /**
+     * Retrieve package compatibility issues.
+     */
+    get packageCompatibilityIssues(): { error: string[]; warning: string[] };
+  }
+
+  namespace ClientIssues {
+    interface UsabilityIssue {
+      /** The pre-localized message to display in relation to the usability issue. */
+      message: string;
+
+      /** The severity of the issue, either "error", "warning", or "info". */
+      severity: "error" | "warning" | "info";
+
+      /** Parameters to supply to the localization. */
+      params?: Record<string, object> | undefined;
+    }
+  }
+}