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

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

@@ -0,0 +1,71 @@
+import type { GetKey } from "../../../types/helperTypes.d.mts";
+
+declare global {
+  /**
+   * Export data content to be saved to a local file
+   * @param data     - Data content converted to a string
+   * @param type     - The type of
+   * @param filename - The filename of the resulting download
+   */
+  function saveDataToFile(data: string, type: string, filename: string): void;
+
+  /**
+   * Read text data from a user provided File object
+   * @param file - A File object
+   * @returns A Promise which resolves to the loaded text data
+   */
+  function readTextFromFile(file: File): Promise<string>;
+
+  /**
+   * Retrieve an Entity or Embedded Entity by its Universally Unique Identifier (uuid).
+   * @param uuid    - The uuid of the Entity or Embedded Entity to retrieve
+   * @param options - Options to configure how a UUID is resolved.
+   */
+  function fromUuid(
+    uuid: string,
+    options?: {
+      /** A Document to resolve relative UUIDs against. */
+      relative?: ClientDocument;
+      /** Allow retrieving an invalid Document. (default: `false`) */
+      invalid?: boolean;
+    },
+  ): Promise<foundry.abstract.Document.Any | null>;
+
+  /**
+   * Retrieve a Document by its Universally Unique Identifier (uuid) synchronously. If the uuid resolves to a compendium
+   * document, that document's index entry will be returned instead.
+   * @param uuid     - The uuid of the Document to retrieve.
+   * @param relative - A document to resolve relative UUIDs against.
+   * @returns The Document or its index entry if it resides in a Compendium, otherwise null.
+   * @throws If the uuid resolves to a Document that cannot be retrieved synchronously.
+   */
+  function fromUuidSync(
+    uuid: string,
+    options?: {
+      /** A Document to resolve relative UUIDs against. */
+      relative?: ClientDocument;
+      /** Allow retrieving an invalid Document. (default: `false`) */
+      invalid?: boolean;
+      /** Throw an error if the UUID cannot be resolved synchronously. (default: `true`) */
+      strict?: boolean;
+    },
+  ): foundry.abstract.Document.Any | Record<string, unknown> | null;
+
+  /**
+   * Resolve a series of embedded document UUID parts against a parent Document.
+   * @param parent - The parent Document.
+   * @param parts  - A series of Embedded Document UUID parts.
+   * @returns The resolved Embedded Document.
+   * @internal
+   */
+  function _resolveEmbedded(parent: foundry.abstract.Document.Any, parts: string[]): foundry.abstract.Document.Any;
+
+  /**
+   * Return a reference to the Document class implementation which is configured for use.
+   * @param documentName - The canonical Document name, for example "Actor"
+   * @returns configured Document class implementation
+   */
+  function getDocumentClass<DocumentName extends string>(
+    documentName: DocumentName,
+  ): GetKey<GetKey<CONFIG, DocumentName, never>, "documentClass", undefined>;
+}

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

@@ -0,0 +1,161 @@
+export {};
+
+declare global {
+  /**
+   * A helper class to provide common functionality for working with HTML5 video objects
+   * A singleton instance of this class is available as `game.video`
+   */
+  class VideoHelper {
+    /** @throws `"You may not re-initialize the singleton VideoHelper. Use game.video instead."` */
+    constructor();
+
+    /**
+     * A user gesture must be registered before video playback can begin.
+     * This Set records the video elements which await such a gesture.
+     */
+    pending: Set<HTMLVideoElement>;
+
+    /**
+     * A mapping of base64 video thumbnail images
+     * @defaultValue an empty Map
+     */
+    thumbs: Map<string, string>;
+
+    /**
+     * A flag for whether video playback is currently locked by awaiting a user gesture
+     * @defaultValue `true`
+     */
+    locked: boolean;
+
+    /**
+     * Store a Promise while the YouTube API is initializing.
+     */
+    #youTubeReady: Promise<void>;
+
+    /**
+     * The YouTube URL regex.
+     */
+    #youTubeRegex: RegExp;
+
+    /**
+     * Return the HTML element which provides the source for a loaded texture.
+     * @param mesh - The rendered mesh
+     * @returns The source HTML element
+     */
+    getSourceElement(mesh: PIXI.Sprite | SpriteMesh): HTMLImageElement | HTMLVideoElement | null;
+
+    /**
+     * Get the video element source corresponding to a Sprite or SpriteMesh.
+     * @param object - The PIXI source
+     * @returns The source video element or null
+     */
+    getVideoSource(object: PIXI.Sprite | PIXI.Texture | SpriteMesh): HTMLVideoElement | null;
+
+    /**
+     * Clone a video texture so that it can be played independently of the original base texture.
+     * @param source - The video element source
+     * @returns An unlinked PIXI.Texture which can be played independently
+     */
+    cloneTexture(source: HTMLVideoElement): Promise<PIXI.Texture>;
+
+    /**
+     * Check if a source has a video extension.
+     * @param src - The source.
+     * @returns If the source has a video extension or not.
+     */
+    static hasVideoExtension(src: string): boolean;
+
+    /**
+     * Play a single video source
+     * If playback is not yet enabled, add the video to the pending queue
+     * @param video   - The VIDEO element to play
+     * @param options - Additional options for modifying video playback (default: `{}`)
+     */
+    play(
+      video: HTMLVideoElement,
+      options?: {
+        /**
+         * Should the video be playing? Otherwise, it will be paused
+         * @defaultValue `true`
+         */
+        playing?: boolean;
+
+        /**
+         * Should the video loop?
+         * @defaultValue `true`
+         */
+        loop?: boolean;
+
+        /** A specific timestamp between 0 and the video duration to begin playback */
+        offset?: number;
+
+        /** Desired volume level of the video's audio channel (if any) */
+        volume?: number;
+      },
+    ): void;
+
+    /**
+     * Stop a single video source
+     * @param video - The VIDEO element to stop
+     */
+    stop(video: HTMLVideoElement): void;
+
+    /**
+     * Register an event listener to await the first mousemove gesture and begin playback once observed
+     * A user interaction must involve a mouse click or keypress.
+     * Listen for any of these events, and handle the first observed gesture.
+     */
+    awaitFirstGesture(): void;
+
+    /**
+     * Handle the first observed user gesture
+     * We need a slight delay because unfortunately Chrome is stupid and doesn't always acknowledge the gesture fast enough.
+     * @param event - The mouse-move event which enables playback
+     * @internal
+     */
+    protected _onFirstGesture(event: Event): void;
+
+    /**
+     * Create and cache a static thumbnail to use for the video.
+     * The thumbnail is cached using the video file path or URL.
+     * @param src     - The source video URL
+     * @param options - Thumbnail creation options, including width and height
+     * @returns The created and cached base64 thumbnail image, or a placeholder image if the canvas is
+     *          disabled and no thumbnail can be generated.
+     */
+    createThumbnail(src: string, options: ImageHelper.CompositeOptions): Promise<string>;
+
+    /**
+     * Lazily-load the YouTube API and retrieve a Player instance for a given iframe.
+     * @param id     - The iframe ID.
+     * @param config - A player config object. See {@link https://developers.google.com/youtube/iframe_api_reference} for reference.
+     */
+    getYouTubePlayer(id: string, config?: YT.PlayerOptions): Promise<YT.Player>;
+
+    /**
+     * Retrieve a YouTube video ID from a URL.
+     * @param url - The URL.
+     */
+    getYouTubeId(url: string): string;
+
+    /**
+     * Take a URL to a YouTube video and convert it into a URL suitable for embedding in a YouTube iframe.
+     * @param url  - The URL to convert.
+     * @param vars - YouTube player parameters. (default: `{}`)
+     * @returns The YouTube embed URL.
+     */
+    getYouTubeEmbedURL(url: string, vars?: YT.PlayerVars): string;
+
+    /**
+     * Test a URL to see if it points to a YouTube video.
+     * @param url - The URL to test. (default: `""`)
+     */
+    isYouTubeURL(url?: string): boolean;
+
+    /**
+     * Inject the YouTube API into the page.
+     * @returns A Promise that resolves when the API has initialized.
+     */
+    #injectYouTubeAPI(): Promise<void>;
+  }
+}

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

@@ -0,0 +1,128 @@
+import type { ValueOf } from "../../../types/utils.d.mts";
+
+// TODO: smarter types for named functions
+declare global {
+  interface WorkerTask {
+    [key: string]: unknown;
+
+    /** An incrementing task ID used to reference task progress */
+    taskId?: number;
+
+    /** The task action being performed, from WorkerManager.WORKER_TASK_ACTIONS */
+    action: ValueOf<typeof WorkerManager.WORKER_TASK_ACTIONS>;
+  }
+
+  /**
+   * An asynchronous web Worker which can load user-defined functions and await execution using Promises.
+   * @param name    - The worker name to be initialized
+   * @param options - Worker initialization options (default: `{}`)
+   */
+  class AsyncWorker extends Worker {
+    constructor(name: string, options?: Partial<AsyncWorker.Options>);
+
+    name: string;
+
+    /**
+     * A path reference to the JavaScript file which provides companion worker-side functionality.
+     * @defaultValue `"scripts/worker.js"`
+     */
+    static WORKER_HARNESS_JS: string;
+
+    /**
+     * A Promise which resolves once the Worker is ready to accept tasks
+     */
+    get ready(): Promise<void>;
+
+    /**
+     * An auto-incrementing task index.
+     * @defaultValue `0`
+     * @internal
+     */
+    protected _taskIndex: number;
+
+    /**
+     * Load a function onto a given Worker.
+     * The function must be a pure function with no external dependencies or requirements on global scope.
+     * @param functionName - The name of the function to load
+     * @param functionRef  - A reference to the function that should be loaded
+     * @returns A Promise which resolves once the Worker has loaded the function.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    loadFunction(functionName: string, functionRef: Function): Promise<unknown>;
+
+    /**
+     * Execute a task on a specific Worker.
+     * @param functionName - The named function to execute on the worker. This function must first have been loaded.
+     * @param args         - An array of parameters with which to call the requested function (default: `[]`)
+     * @param transfer     - An array of transferable objects which are transferred to the worker thread.
+     *                       See https://developer.mozilla.org/en-US/docs/Glossary/Transferable_objects
+     *                       (default: `[]`)
+     * @returns A Promise which resolves with the returned result of the function once complete.
+     */
+    executeFunction(functionName: string, args?: any[], transfer?: any[]): Promise<unknown>;
+  }
+
+  /**
+   * A client-side class responsible for managing a set of web workers.
+   * This interface is accessed as a singleton instance via game.workers.
+   * @see Game#workers
+   */
+  class WorkerManager extends Map<string, AsyncWorker> {
+    constructor();
+
+    /**
+     * Supported worker task actions
+     */
+    static WORKER_TASK_ACTIONS: Readonly<{
+      INIT: "init";
+      LOAD: "load";
+      EXECUTE: "execute";
+    }>;
+
+    /**
+     * Create a new named Worker.
+     * @param name   - The named Worker to create
+     * @param config - Worker configuration parameters passed to the AsyncWorker constructor
+     * @returns The created AsyncWorker which is ready to accept tasks
+     */
+    createWorker(name: string, config?: AsyncWorker.Options): Promise<AsyncWorker>;
+
+    /**
+     * Retire a current Worker, terminating it immediately.
+     * @see {@link Worker#terminate}
+     * @param name - The named worker to terminate
+     */
+    retireWorker(name: string): void;
+
+    /**
+     * Get a currently active Worker by name.
+     * @param name - The named Worker to retrieve
+     * @returns The AsyncWorker instance
+     * @deprecated since v11, will be removed in v13
+     * @remarks `"WorkerManager#getWorker is deprecated in favor of WorkerManager#get"`
+     * @remarks Throws an error if the name is not in the internal map, while `get` does not.
+     */
+    getWorker(name: string): AsyncWorker;
+  }
+
+  namespace AsyncWorker {
+    interface Options {
+      /**
+       * Should the worker run in debug mode?
+       * @defaultValue `false`
+       */
+      debug: boolean;
+
+      /**
+       * Should the worker automatically load the primitives library?
+       * @defaultValue `false`
+       */
+      loadPrimitives: boolean;
+
+      /**
+       * Should the worker operates in script modes? Optional scripts.
+       */
+      scripts: string[];
+    }
+  }
+}

package/src/foundry/client/data/abstract/canvas-document.d.mts

@@ -0,0 +1,70 @@
+import type { Mixin } from "../../../../types/utils.d.mts";
+import type Document from "../../../common/abstract/document.d.mts";
+import type { ClientDocument } from "./client-document.d.mts";
+
+declare class CanvasDocument<
+  // TODO(LukeAbby): Setting this to `Scene.ConfiguredInstance` causes a lot of circular errors.
+  BaseDocument extends Document<any, any, Scene | null>,
+> extends ClientDocument<BaseDocument> {
+  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+  constructor(...args: any[]);
+
+  /**
+   * A lazily constructed PlaceableObject instance which can represent this Document on the game canvas.
+   */
+  get object(): Document.ConfiguredObjectInstanceForName<BaseDocument["documentName"]> | null;
+
+  /**
+   * A reference to the PlaceableObject instance which represents this Embedded Document.
+   * @internal
+   * @defaultValue `null`
+   */
+  protected _object: Document.ConfiguredObjectInstanceForName<BaseDocument["documentName"]> | null;
+
+  /**
+   * Has this object been deliberately destroyed as part of the deletion workflow?
+   * @internal
+   * @defaultValue `false`
+   */
+  protected _destroyed: boolean;
+
+  /**
+   * A reference to the CanvasLayer which contains Document objects of this type.
+   */
+  get layer(): InstanceType<PlaceablesLayer.ConfiguredClassForName<BaseDocument["documentName"]>>;
+
+  /**
+   * An indicator for whether this document is currently rendered on the game canvas.
+   */
+  get rendered(): boolean;
+
+  /**
+   * @privateRemarks _preCreate, _onCreate, _onUpdate, and _onDelete are all overridden but with no signature changes.
+   * For type simplicity they are left off. These methods historically have been the source of a large amount of computation from tsc.
+   */
+}
+
+declare namespace CanvasDocument {
+  type Any = CanvasDocument<any>;
+}
+
+declare global {
+  /**
+   * @deprecated {@link CanvasDocument.Any | `CanvasDocument.Any`}
+   */
+  type CanvasDocument = ReturnType<typeof CanvasDocumentMixin>;
+
+  /**
+   * A specialized sub-class of the ClientDocumentMixin which is used for document types that are intended to be represented upon the game Canvas.
+   */
+  function CanvasDocumentMixin<BaseClass extends Document.Internal.Constructor>(
+    Base: BaseClass,
+  ): typeof AnyDocument & Mixin<typeof CanvasDocument<InstanceType<BaseClass>>, BaseClass>;
+}
+
+// This is yet another `AnyDocument` type.
+// It exists specifically because the `Document.AnyConstructor` type is too safe to be merged in with a mixin.
+// The `arg0: never, ...args: never[]` trick trips up the base constructor check and so this one with an actual `...args: any[]` one is used instead.
+declare class AnyDocument extends Document<any, any, any> {
+  constructor(...args: any[]);
+}