@league-of-foundry-developers/foundry-vtt-types 0.8.9-8 → 9.242.0

package/src/foundry/foundry.js/hooks.d.ts

@@ -1,5 +1,6 @@
 import {
   ConfiguredDocumentClass,
+  ConfiguredDocumentClassForName,
   ConfiguredObjectClassForName,
   DocumentConstructor,
   ToObjectFalseType
@@ -95,6 +96,47 @@ declare global {
       ...args: Parameters<H>
     ): ReturnType<H> | undefined;
 
+    /**
+     * Notify subscribers that an error has occurred within foundry.
+     * @param location - The method where the error was caught.
+     * @param err      - The error.
+     * @param options  - Additional options to configure behaviour.
+     */
+    static onError(
+      location: string,
+      err: Error,
+      {
+        msg,
+        notify,
+        log,
+        ...data
+      }?: {
+        /**
+         * Additional data to pass to the hook subscribers.
+         * @defaultValue `{}`
+         */
+        [key: string]: unknown;
+
+        /**
+         * A message to prefix the caught error with and/or to use in the 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;
+
     /**
      * @defaultValue `{}`
      */
@@ -129,21 +171,27 @@ declare global {
    *
    * @example Using a callback type with a static name
    * ```typescript
-   * Hooks.on('updateWorldTime', (worldTime, dt) => {
+   * Hooks.on("updateWorldTime", (worldTime, dt) => {
+   *   worldTime; // number
+   *   dt; // number
    *   // [...]
    * })
    * ```
    *
-   * @example Using a callback with a dynamic name
+   * @example Using a callback with a dynamic name and generic parameter
    * ```typescript
-   * Hooks.on<Hooks.GetCompendiumDirectoryEntryContext>('getJournalEntryContext', (jq, entryOptions) => {
+   * Hooks.on<Hooks.CloseApplication<FormApplication>>("closeFormApplication", (app, jq) => {
+   *   app; // FormApplication
+   *   jq; // JQuery
    *   // [...]
    * })
    * ```
    *
-   * @example Using a callback with a dynamic name and generic parameter
+   * @example Using the `error` callback type
    * ```typescript
-   * Hooks.on<Hooks.CloseApplication<FormApplication>>('closeFormApplication', (app, jq) => {
+   * Hooks.on("error", (...args) => {
+   *   if (args[0] === "Canvas#draw")
+   *     args[2].layer // CanvasLayer
    *   // [...]
    * })
    * ```
@@ -162,13 +210,30 @@ declare global {
         change: EffectChangeData
       ) => boolean | void;
 
+      /**
+       * A hook event that fires immediately prior to PIXI Application construction with the configuration parameters.
+       * @param canvasConfig - Canvas configuration parameters that will be used
+       * @remarks This is called by {@link Hooks.callAll}.
+       */
+      canvasConfig: (canvasConfig: {
+        view: HTMLCanvasElement;
+        width: number;
+        height: number;
+        transparent: boolean;
+        resolution: number;
+        autoDensity: boolean;
+        backgroundColor: string | null;
+        antialias: boolean;
+        powerPreference: string;
+      }) => void;
+
       /**
        * A hook event that fires when the Canvas is initialized.
        * @param canvas - the Canvas
        * @remarks This is called by {@link Hooks.callAll}.
        * @see {@link Canvas#draw}
        */
-      canvasInit: (canvas: Canvas) => unknown;
+      canvasInit: (canvas: Canvas) => void;
 
       /**
        * A hook event that fires when the Canvas is panned.
@@ -179,7 +244,7 @@ declare global {
        * @see {@link Canvas#pan}
        * @see {@link Canvas#animatePan}
        */
-      canvasPan: (canvas: Canvas, view: Canvas.View) => unknown;
+      canvasPan: (canvas: Canvas, view: Canvas.View) => void;
 
       /**
        * A hook event that fires when the Canvas is ready.
@@ -195,7 +260,7 @@ declare global {
        * @remarks This is called by {@link Hooks.callAll}.
        * @see {@link Sidebar#_onChangeTab}
        */
-      changeSidebarTab: (app: SidebarTab) => unknown;
+      changeSidebarTab: (app: SidebarTab) => void;
 
       /**
        * A hook event that fires when a chat bubble is rendered.
@@ -247,7 +312,7 @@ declare global {
        * @see {@link SceneNavigation#expand}
        * @see {@link SceneNavigation#collapse}
        */
-      collapseSceneNavigation: (nav: SceneNavigation, collapsed: boolean) => unknown;
+      collapseSceneNavigation: (nav: SceneNavigation, collapsed: boolean) => void;
 
       /**
        * A hook event that fires when the Sidebar is collapsed or expanded.
@@ -257,7 +322,21 @@ declare global {
        * @see {@link Sidebar#expand}
        * @see {@link Sidebar#collapse}
        */
-      collapseSidebar: (sidebar: Sidebar, collapsed: boolean) => unknown;
+      collapseSidebar: (sidebar: Sidebar, collapsed: boolean) => void;
+
+      /**
+       * A hook event that fires when Cards are dealt from a deck to other hands
+       * @param origin             - The origin Cards document
+       * @param destinations       - An array of destination Cards documents
+       * @param context            - Additional context which describes the operation
+       * @remarks This is called by {@link Hooks.call}.
+       * @remarks An explicit return value of `false` prevents the operation.
+       */
+      dealCards: (
+        origin: InstanceType<ConfiguredDocumentClassForName<'Cards'>>,
+        destinations: InstanceType<ConfiguredDocumentClassForName<'Cards'>>[],
+        context: Cards.DealContext
+      ) => boolean | void;
 
       /**
        * A hook event that fires when some useful data is dropped onto an ActorSheet.
@@ -302,13 +381,25 @@ declare global {
         data: object
       ) => boolean | void;
 
+      /**
+       * A hook event that fires whenever foundry experiences an error.
+       *
+       * @param location - The method where the error was caught.
+       * @param err      - The error.
+       * @param data     - Additional data that might be provided, based on the nature of the error.
+       *                   (default: `{}`)
+       * @remarks This is called by {@link Hooks.callAll}.
+       * @see {@link Hooks.onError}
+       */
+      error: (...args: ValueOf<ErrorCallbackParameters>) => void;
+
       /**
        * A hook event that fires when the Scene controls are initialized.
        * @param controls - The SceneControl configurations
        * @remarks This is called by {@link Hooks.callAll}.
        * @see {@link SceneControls#_getControlButtons}
        */
-      getSceneControlButtons: (controls: SceneControl[]) => unknown;
+      getSceneControlButtons: (controls: SceneControl[]) => void;
 
       /**
        * A hook event that fires when the context menu for a SceneNavigation entry is constructed.
@@ -345,21 +436,27 @@ declare global {
         slot: number
       ) => boolean | void;
 
+      /**
+       * A hook event that fires once Localization translations have been loaded and are ready for use.
+       * @remarks This is called by {@link Hooks.callAll}.
+       * @see {@link Localization#initialize}
+       */
+      i18nInit: () => void;
+
       /**
        * A hook event that fires as Foundry is initializing, right before any initialization tasks have begun.
        * @remarks This is called by {@link Hooks.callAll}.
        * @see {@link Game#initialize}
        */
-      init: () => unknown;
+      init: () => void;
 
       /**
-       * A hook event that fires after PointSource shaders have initialized.
-       * @param source        - The PointSource
-       * @param animationType - The animation type
+       * A hook event that fires after LightSource shaders have initialized.
+       * @param source - The LightSource being initialized
        * @remarks This is called by {@link Hooks.callAll}.
-       * @see {@link PointSource#_initializeShaders}
+       * @see {@link LightSource#_initializeShaders}
        */
-      initializePointSourceShaders: (source: PointSource, animationType: string | null) => unknown;
+      initializeLightSourceShaders: (source: LightSource) => void;
 
       /**
        * A hook event that fires when the LightingLayer is refreshed.
@@ -367,7 +464,7 @@ declare global {
        * @remarks This is called by {@link Hooks.callAll}.
        * @see {@link LightingLayer#refresh}
        */
-      lightingRefresh: (layer: LightingLayer) => unknown;
+      lightingRefresh: (layer: LightingLayer) => void;
 
       /**
        * A hook event that fires when a token's resource bar attribute has been modified.
@@ -395,20 +492,34 @@ declare global {
         updates: Record<string, number>
       ) => boolean;
 
+      /**
+       * A hook event that fires when Cards are passed from one stack to another
+       * @param origin      - The origin Cards document
+       * @param destination - The destination Cards document
+       * @param context     - Additional context which describes the operation
+       * @remarks This is called by {@link Hooks.call}.
+       * @remarks An explicit return value of `false` prevents the operation.
+       */
+      passCards: (
+        origin: InstanceType<ConfiguredDocumentClassForName<'Cards'>>,
+        destination: InstanceType<ConfiguredDocumentClassForName<'Cards'>>,
+        context: Cards.DealContext
+      ) => boolean | void;
+
       /**
        * A hook event that fires when the game is paused or un-paused.
        * @param paused - Is the game now paused (true) or un-paused (false)
        * @remarks This is called by {@link Hooks.callAll}.
        * @see {@link Game#togglePause}
        */
-      pauseGame: (paused: boolean) => unknown;
+      pauseGame: (paused: boolean) => void;
 
       /**
        * A hook event that fires when the game is fully ready.
        * @remarks This is called by {@link Hooks.callAll}.
        * @see {@link Game#setupGame}
        */
-      ready: () => unknown;
+      ready: () => void;
 
       /**
        * A hook event that fires for each ChatMessage which is rendered for addition to the ChatLog.
@@ -434,6 +545,18 @@ declare global {
         }
       ) => boolean | void;
 
+      /**
+       * A hook event that fires when a stack of Cards are returned to the decks they originally came from.
+       * @param origin   - The origin Cards document.
+       * @param returned - The cards being returned.
+       * @param context  - Additional context which describes the operation.
+       */
+      returnCards: (
+        origin: InstanceType<ConfiguredDocumentClassForName<'Cards'>>,
+        returned: InstanceType<ConfiguredDocumentClassForName<'Card'>>[],
+        context: Cards.ReturnContext
+      ) => boolean | void;
+
       /**
        * A hook event that fires when the AV settings are changed.
        * @param settings - The AVSettings manager
@@ -441,7 +564,7 @@ declare global {
        * @remarks This is called by {@link Hooks.callAll}.
        * @see {@link AVSettings#_onSettingsChanged}
        */
-      rtcSettingsChanged: (settings: AVSettings, changed: DeepPartial<AVSettings.Settings>) => unknown;
+      rtcSettingsChanged: (settings: AVSettings, changed: DeepPartial<AVSettings.Settings>) => void;
 
       /**
        * A hook event that fires when Foundry has finished initializing but
@@ -450,7 +573,7 @@ declare global {
        * @remarks This is called by {@link Hooks.callAll}.
        * @see {@link Game#setupGame}
        */
-      setup: () => unknown;
+      setup: () => void;
 
       /**
        * A hook event that fires when the SightLayer has been refreshed.
@@ -458,7 +581,7 @@ declare global {
        * @remarks This is called by {@link Hooks.callAll}.
        * @see {@link SightLayer#restrictVisibility}
        */
-      sightRefresh: (layer: SightLayer) => unknown;
+      sightRefresh: (layer: SightLayer) => void;
 
       /**
        * A hook event that fires when a token is targeted or un-targeted.
@@ -472,7 +595,7 @@ declare global {
         user: InstanceType<ConfiguredDocumentClass<typeof User>>,
         token: ConfiguredObjectClassForName<'Token'>,
         targeted: boolean
-      ) => unknown;
+      ) => void;
 
       /**
        * A hook event that fires whenever the contents of a Compendium pack were modified.
@@ -490,7 +613,7 @@ declare global {
         documents: foundry.abstract.Document<any, any>[],
         options: DocumentModificationOptions,
         userId: string
-      ) => unknown;
+      ) => void;
 
       /**
        * A hook event that fires when the World time has been updated.
@@ -499,7 +622,7 @@ declare global {
        * @remarks This is called by {@link Hooks.callAll}.
        * @see {@link GameTime#onUpdateWorldTime}
        */
-      updateWorldTime: (worldTime: number, delta: number) => unknown;
+      updateWorldTime: (worldTime: number, delta: number) => void;
     }
 
     /**
@@ -526,10 +649,7 @@ declare global {
      * @see {@link PlaceableObject#control}
      * @see {@link PlaceableObject#release}
      */
-    type ControlPlaceableObject<P extends PlaceableObject = PlaceableObject> = (
-      object: P,
-      controlled: boolean
-    ) => unknown;
+    type ControlPlaceableObject<P extends PlaceableObject = PlaceableObject> = (object: P, controlled: boolean) => void;
 
     /**
      * A hook event that fires for every embedded Document type after conclusion of a creation workflow.
@@ -549,7 +669,7 @@ declare global {
       document: InstanceType<ConfiguredDocumentClass<D>>,
       options: DocumentModificationOptions,
       userId: string
-    ) => unknown;
+    ) => void;
 
     /**
      * A hook event that fires for every Document type after conclusion of an deletion workflow.
@@ -569,7 +689,7 @@ declare global {
       document: InstanceType<ConfiguredDocumentClass<D>>,
       options: DocumentModificationOptions,
       userId: string
-    ) => unknown;
+    ) => void;
 
     /**
      * A hook event that fires whenever this Application is first rendered to add buttons to its header.
@@ -587,40 +707,15 @@ declare global {
     ) => boolean | void;
 
     /**
-     * @remarks This is called after getting the {@link ContextMenu} options for a {@link ChatLog}, but before creating
-     * the ContextMenu.
-     * @param jq           - the JQuery of the ContextMenu parent element
-     * @param entryOptions - the already created ContextMenuOptions
-     * @remarks The name for this hook is dynamically created by joining 'get' with the type name of the ChatLog and
-     * 'EntryContext'.
-     * @remarks This is called by {@link Hooks.call}.
-     * @see {@link ChatLog#_contextMenu}
-     */
-    type GetChatLogEntryContext = (jq: JQuery, entryOptions: ContextMenuEntry[]) => boolean | void;
-
-    /**
-     * @remarks This is called after getting the {@link ContextMenu} options for a {@link CombatTracker} entry, but before
-     * creating the ContextMenu.
-     * @param jq           - the JQuery of the ContextMenu parent element
-     * @param entryOptions - the already created ContextMenuOptions
-     * @remarks The name for this hook is dynamically created by joining 'get' with the type name of the CombatTracker and
-     * 'EntryContext'.
-     * @remarks This is called by {@link Hooks.call}.
-     * @see {@link CombatTracker#_contextMenu}
-     */
-    type GetCombatTrackerEntryContext = (jq: JQuery, entryOptions: ContextMenuEntry[]) => boolean | void;
-
-    /**
-     * @remarks This is called after getting the {@link ContextMenu} options for a {@link CompendiumDirectory} entry, but
-     * before creating the ContextMenu.
-     * @param jq           - the JQuery of the ContextMenu parent element
-     * @param entryOptions - the already created ContextMenuOptions
-     * @remarks The name for this hook is dynamically created by joining 'get' with the type name of the
-     * CompendiumDirectory and 'EntryContext'.
+     * A hook event that fires when the context menu for entries in an Application is constructed. Substitute the
+     * Application name in the hook event to target a specific Application, for example
+     * "getActorDirectoryEntryContext".
+     * @param html         - The HTML element to which the context options are attached
+     * @param entryOptions - The context menu entries
      * @remarks This is called by {@link Hooks.call}.
-     * @see {@link CompendiumDirectory#_contextMenu}
+     * @see {@link ContextMenu.create}
      */
-    type GetCompendiumDirectoryEntryContext = (jq: JQuery, entryOptions: ContextMenuEntry[]) => boolean | void;
+    type GetEntryContext = (html: JQuery, entryOptions: ContextMenuEntry[]) => boolean | void;
 
     /**
      * A hook event that fires when the context menu for a Sound in the PlaylistDirectory is constructed.
@@ -633,19 +728,6 @@ declare global {
      */
     type GetPlaylistDirectorySoundContext = (html: JQuery, entryOptions: ContextMenuEntry[]) => boolean | void;
 
-    /**
-     * A hook event that fires when the context menu for entries in a SidebarTab
-     * is constructed. Substitute the SidebarTab name in the hook event to target
-     * a specific SidebarTab, for example "getActorDirectoryEntryContext".
-     * @param html         - The HTML element to which the context options are attached
-     * @param entryOptions - The context menu entries
-     * @remarks The name for this hook is dynamically created by joining 'get' with the type name of the SidebarDirectory
-     * and 'EntryContext'.
-     * @remarks This is called by {@link Hooks.call}.
-     * @see {@link SidebarDirectory#_contextMenu}
-     */
-    type GetSidebarDirectoryEntryContext = (html: JQuery, entryOptions: ContextMenuEntry[]) => boolean | void;
-
     /**
      * A hook event that fires when the context menu for folders in a SidebarTab
      * is constructed. Substitute the SidebarTab name in the hook event to target
@@ -668,7 +750,7 @@ declare global {
      * @remarks This is called by {@link Hooks.callAll}.
      * @see {@link AudioHelper#_onChangeGlobalVolume}
      */
-    type GlobalVolumeChanged = (volume: number) => unknown;
+    type GlobalVolumeChanged = (volume: number) => void;
 
     /**
      * A hook event that fires when any PlaceableObject is hovered over or out.
@@ -682,7 +764,7 @@ declare global {
      * @see {@link PlaceableObject#_onHoverIn}
      * @see {@link PlaceableObject#_onHoverOut}
      */
-    type HoverPlaceableObject<P extends PlaceableObject = PlaceableObject> = (object: P, hover: boolean) => unknown;
+    type HoverPlaceableObject<P extends PlaceableObject = PlaceableObject> = (object: P, hover: boolean) => void;
 
     /**
      * A hook event that fires when any PlaceableObject is pasted onto the
@@ -816,7 +898,7 @@ declare global {
       change: DeepPartial<ConstructorParameters<D>[0]>,
       options: DocumentModificationOptions,
       userId: string
-    ) => unknown;
+    ) => void;
 
     type DynamicCallbacks =
       | CloseApplication
@@ -824,11 +906,8 @@ declare global {
       | CreateDocument
       | DeleteDocument
       | GetApplicationHeaderButtons
-      | GetChatLogEntryContext
-      | GetCombatTrackerEntryContext
-      | GetCompendiumDirectoryEntryContext
+      | GetEntryContext
       | GetPlaylistDirectorySoundContext
-      | GetSidebarDirectoryEntryContext
       | GetSidebarDirectoryFolderContext
       | HoverPlaceableObject
       | PastePlaceableObject
@@ -837,5 +916,52 @@ declare global {
       | PreUpdateDocument
       | RenderApplication
       | UpdateDocument;
+
+    interface ErrorCallbackParameters {
+      'Canvas#draw': [location: 'Canvas#draw', err: Error, data: { layer: CanvasLayer }];
+      'Application#render': [location: 'Application#render', err: Error, data: Application.RenderOptions];
+      'Localization#_loadTranslationFile': [
+        location: 'Localization#_loadTranslationFile',
+        err: Error,
+        data: { src: string }
+      ];
+      'ClientDatabaseBackend#_preCreateDocumentArray': [
+        location: 'ClientDatabaseBackend#_preCreateDocumentArray',
+        err: Error,
+        data: { id: string }
+      ];
+      'ClientDatabaseBackend#_preUpdateDocumentArray': [
+        location: 'ClientDatabaseBackend#_preUpdateDocumentArray',
+        err: Error,
+        data: { id: string }
+      ];
+      'WorldCollection#_initialize': [location: 'WorldCollection#_initialize', err: Error, data: { id: string }];
+      'ClientDocumentMixin#_initialize': [
+        location: 'ClientDocumentMixin#_initialize',
+        err: Error,
+        data: { id: string }
+      ];
+      'Actor#getTokenImages': [location: 'Actor#getTokenImages', err: Error, data: Record<string, never>];
+      'Macro#executeChat': [location: 'Macro#executeChat', err: Error, data: { command: string }];
+      'ChatMessage#roll': [location: 'ChatMessage#roll', err: Error, data: { command: string }];
+      'DefaultTokenConfig#_updateObject': [
+        location: 'DefaultTokenConfig#_updateObject',
+        err: Error,
+        data: Record<string, never>
+      ];
+      'SceneConfig#_updateObject': [location: 'SceneConfig#_updateObject', err: Error, data: { scene: string }];
+      'SidebarDirectory.setupFolders': [
+        location: 'SidebarDirectory.setupFolders',
+        err: Error,
+        data: Record<string, never>
+      ];
+      'Sidebar#_render': [location: 'Sidebar#_render', err: Error, data: { name: string }];
+      'Game#initializeCanvas': [location: 'Game#initializeCanvas', err: Error, data: Record<string, never>];
+      'EmbeddedCollection#_initialize': [
+        location: 'EmbeddedCollection#_initialize',
+        err: Error,
+        data: { id: string; documentName: string }
+      ];
+    }
   }
 }

package/src/foundry/foundry.js/imageHelper.d.ts

@@ -12,7 +12,7 @@ declare class ImageHelper {
    */
   static createThumbnail(
     src: string | PIXI.DisplayObject,
-    options?: ImageHelper.CompositeOptions
+    options?: ImageHelper.CompositeOptions & ImageHelper.TextureToImageOptions
   ): Promise<ImageHelper.ThumbnailReturn>;
 
   /* -------------------------------------------- */
@@ -31,9 +31,19 @@ declare class ImageHelper {
   /**
    * 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): string;
+  static textureToImage(texture: PIXI.Texture, { format, quality }?: ImageHelper.TextureToImageOptions): 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>;
 }
 
 declare namespace ImageHelper {
@@ -73,6 +83,20 @@ declare namespace ImageHelper {
     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.
    */