@league-of-foundry-developers/foundry-vtt-types 12.331.3-beta → 12.331.4-beta

package/src/foundry/client/pixi/core/interaction/render-flags.d.mts

@@ -1,4 +1,11 @@
-import type { AnyConstructor, InexactPartial, Mixin } from "../../../../../types/utils.d.mts";
+import type {
+  AnyConstructor,
+  ConcreteKeys,
+  FixedInstanceType,
+  InexactPartial,
+  MakeConform,
+  Mixin,
+} from "fvtt-types/utils";
 import type { LogCompatibilityWarningOptions } from "../../../../common/utils/logging.d.mts";
 
 declare class RenderFlagObject {
@@ -9,12 +16,12 @@ declare class RenderFlagObject {
    * Configure the render flags used for this class.
    * @defaultValue `{}`
    */
-  static RENDER_FLAGS: Record<string, RenderFlag.Any>;
+  static RENDER_FLAGS: RenderFlagsMixin.RENDER_FLAGS;
 
   /**
    * The ticker priority when RenderFlags of this class are handled.
    * Valid values are OBJECTS or PERCEPTION.
-   * @defaultValue "OBJECTS"
+   * @defaultValue `"OBJECTS"`
    */
   static RENDER_FLAG_PRIORITY: "OBJECTS" | "PERCEPTION";
 
@@ -22,7 +29,8 @@ declare class RenderFlagObject {
    * Status flags which are applied at render-time to update the PlaceableObject.
    * If an object defines RenderFlags, it should at least include flags for "redraw" and "refresh".
    */
-  renderFlags: RenderFlags;
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  renderFlags: RenderFlags<{}>;
 
   /**
    * Apply any current render flags, clearing the renderFlags set.
@@ -35,12 +43,16 @@ declare class RenderFlagObject {
  * @privateRemarks Values are marked as optional here based on use, foundry docs incomplete
  * @internal
  */
-type _RenderFlags<Flags> = InexactPartial<{
-  /** Activating this flag also sets these flags to true */
-  propagate: Array<Partial<keyof Flags>>;
+type _RenderFlag<Keys extends string> = InexactPartial<{
+  /**
+   * Activating this flag also sets these flags to true
+   */
+  propagate: Keys[];
 
-  /** Activating this flag resets these flags to false */
-  reset: Array<Partial<keyof Flags>>;
+  /**
+   * Activating this flag resets these flags to false
+   */
+  reset: Keys[];
 
   /**
    * Is this flag deprecated? The deprecation options are passed to
@@ -60,37 +72,46 @@ type _RenderFlags<Flags> = InexactPartial<{
 }>;
 
 declare global {
-  interface RenderFlag<Flags> extends _RenderFlags<Flags> {}
+  // Note(LukeAbby): The usage of `ConcreteKeys` is a hazard; if tsc were to become smarter it might
+  // notice that `ConcreteKeys<Flags>` is actually contravariant and reject this type. However
+  // `RenderFlags` is built upon the assumption this is only used in safe ways.
+  interface RenderFlag<out Flags extends object, Key extends keyof Flags>
+    extends _RenderFlag<Exclude<Extract<ConcreteKeys<Flags>, string>, Key>> {}
 
   namespace RenderFlag {
-    type Any = RenderFlag<any>;
+    interface Any extends _RenderFlag<string> {}
+  }
+
+  namespace RenderFlags {
+    type ValidateFlags<Flags extends object> = {
+      [K in keyof Flags]: MakeConform<Flags[K], _RenderFlag<Extract<Exclude<keyof Flags, K>, string>>>;
+    };
+
+    interface Config {
+      /** The object which owns this RenderFlags instance */
+      object?: RenderFlagObject;
+
+      /**
+       * The update priority when these render flags are applied.
+       * Valid options are OBJECTS or PERCEPTION.
+       * @defaultValue `PIXI.UPDATE_PRIORITY.OBJECTS`
+       */
+      priority?: typeof PIXI.UPDATE_PRIORITY.OBJECTS | typeof PIXI.UPDATE_PRIORITY.PERCEPTION;
+    }
   }
 
   /**
    * A data structure for tracking a set of boolean status flags.
    * This is a restricted set which can only accept flag values which are pre-defined.
    */
-  class RenderFlags extends Set<string> {
+  class RenderFlags<Flags extends RenderFlags.ValidateFlags<Flags>> extends Set<string> {
     /**
      * @param flags  - An object which defines the flags which are supported for tracking
      * @param config - Optional configuration
      */
-    constructor(
-      flags: Record<string, RenderFlag<Record<string, boolean>>>,
-      config?: {
-        /** The object which owns this RenderFlags instance */
-        object?: RenderFlagObject;
-
-        /**
-         * The update priority when these render flags are applied.
-         * Valid options are OBJECTS or PERCEPTION.
-         * @defaultValue `PIXI.UPDATE_PRIORITY.OBJECTS`
-         */
-        priority?: PIXI.UPDATE_PRIORITY.OBJECTS | PIXI.UPDATE_PRIORITY.PERCEPTION;
-      },
-    );
-
-    readonly flags: Record<string, RenderFlag<Record<string, boolean>>>;
+    constructor(flags: Flags, config?: RenderFlags.Config);
+
+    readonly flags: Flags;
 
     readonly object: RenderFlagObject;
 
@@ -109,8 +130,9 @@ declare global {
 
     /**
      * Activate certain flags, also toggling propagation and reset behaviors
+     * @remarks Flags are only set if `true`, nullish values are discarded
      */
-    set(changes: Record<string, boolean>): void;
+    set(changes: Record<string, boolean | undefined | null>): void;
   }
 
   /**
@@ -119,7 +141,31 @@ declare global {
    * @param Base - The base class being mixed. Normally a PIXI.DisplayObject
    * @returns The mixed class definition
    */
-  function RenderFlagsMixin<BaseClass extends AnyConstructor>(
+  // Note(LukeAbby): In theory a similar thing to what happens in `CanvasGroupMixin` could be done.
+  // That is passing up a generic to instantiate the generic side. However `RenderFlagsMixin` is
+  // only inherited directly by `PerceptionManager` and `PlaceableObject`.
+  // Therefore it's mostly the subclasses of `PlaceableObject` that face this problem and that can't
+  // be solved here unfortunately.
+  function RenderFlagsMixin<BaseClass extends RenderFlagsMixin.BaseClass>(
     Base: BaseClass,
   ): Mixin<typeof RenderFlagObject, BaseClass>;
+
+  namespace RenderFlagsMixin {
+    interface AnyMixedConstructor extends ReturnType<typeof RenderFlagsMixin<BaseClass>> {}
+    interface AnyMixed extends FixedInstanceType<AnyMixedConstructor> {}
+
+    type BaseClass = AnyConstructor;
+
+    type RENDER_FLAGS = Record<string, RenderFlag.Any>;
+
+    /**
+     * @internal This type exists only to make sure `ToBooleanFlags` isn't a homomorphic mapped type
+     * to avoid keeping documentation.
+     */
+    type _KeyOf<T> = keyof T;
+
+    type ToBooleanFlags<RenderFlags extends object> = {
+      [K in _KeyOf<RenderFlags>]?: boolean | null | undefined;
+    };
+  }
 }

package/src/foundry/client/pixi/core/interaction/resize-handle.d.mts

@@ -1,15 +1,15 @@
-export {};
+import type { Identity, NullishProps } from "fvtt-types/utils";
 
 declare global {
   class ResizeHandle extends PIXI.Graphics {
     /**
      * @param handlers - (default: `{}`)
      */
-    constructor(offset: ResizeHandle["offset"], handlers?: ResizeHandle["handlers"]);
+    constructor(offset: ResizeHandle.Offsets, handlers?: ResizeHandle.Handlers);
 
-    offset: [widthOffset: number, heightOffset: number];
+    offset: ResizeHandle.Offsets;
 
-    handlers: { canDrag?: boolean };
+    handlers: ResizeHandle.Handlers;
 
     /**
      * Track whether the handle is being actively used for a drag workflow
@@ -26,7 +26,7 @@ declare global {
       current: Canvas.Rectangle,
       origin: Canvas.Rectangle,
       destination: Canvas.Rectangle,
-      { aspectRatio }?: { aspectRatio?: number | null },
+      options?: ResizeHandle.UpdateDimensionsOptions,
     ): Canvas.Rectangle;
 
     activateListeners(): void;
@@ -49,4 +49,34 @@ declare global {
      */
     protected _onMouseDown(event: PIXI.FederatedEvent): void;
   }
+
+  namespace ResizeHandle {
+    interface Any extends AnyResizeHandle {}
+    interface AnyConstructor extends Identity<typeof AnyResizeHandle> {}
+
+    type Offsets = [widthOffset: number, heightOffset: number];
+
+    /** @internal */
+    type _Handlers = NullishProps<{
+      canDrag: () => boolean | null | void;
+    }>;
+
+    interface Handlers extends _Handlers {}
+
+    /** @internal */
+    type _UpdateDimensionsOptions = NullishProps<{
+      /**
+       * Constrain the aspect ratio
+       * @defaultValue `null`
+       * @remarks If truthy, will enforce the passed ratio, landscape if `width >= height`, portrait otherwise
+       */
+      aspectRatio: number;
+    }>;
+
+    interface UpdateDimensionsOptions extends _UpdateDimensionsOptions {}
+  }
+}
+
+declare abstract class AnyResizeHandle extends ResizeHandle {
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/core/interaction/targets.d.mts

@@ -1,29 +1,23 @@
-export {};
+import type { Identity } from "fvtt-types/utils";
 
-interface SetReplacementMembers<T> {
-  add(value: T): void;
-  delete(value: T): void;
-  clear(): void;
+// This class exists make it as sound as possible to override these parts of the class and make them
+// completely unrelated. It's done this way specifically to avoid situations with broken inheritance.
+declare class LenientSet<T> extends globalThis.Set<T> {
+  add(value: T): any;
+  delete(value: T): any;
 }
 
-type PatchedSet<T> = Omit<Set<T>, "add" | "delete" | "clear"> & SetReplacementMembers<T>;
-
-interface PatchedSetConstructor {
-  new <T = any>(values?: readonly T[] | null): PatchedSet<T>;
-  readonly prototype: PatchedSet<any>;
-}
-
-declare const Set: PatchedSetConstructor;
+declare const Set: typeof LenientSet;
 
 declare global {
   /**
    * A subclass of Set which manages the Token ids which the User has targeted.
-   * @see User#targets
+   * @see {@link User.targets | `User#targets`}
    */
-  class UserTargets extends Set<TokenDocument.ObjectInstance> {
+  class UserTargets extends Set<Token.Object> {
     constructor(user: UserTargets["user"]);
 
-    user: User.ConfiguredInstance;
+    user: User.Implementation;
 
     /**
      * Return the Token IDs which are user targets
@@ -33,13 +27,22 @@ declare global {
     /**
      * @remarks Returns void, but Set<T>.add returns boolean
      */
-    override add(token: TokenDocument.ObjectInstance): void;
+    override add(token: Token.Object): void;
 
     override clear(): void;
 
     /**
      * @remarks Returns void, but Set<T>.delete returns boolean
      */
-    override delete(token: TokenDocument.ObjectInstance): void;
+    override delete(token: Token.Object): void;
   }
+
+  namespace UserTargets {
+    interface Any extends AnyUserTargets {}
+    interface AnyConstructor extends Identity<typeof AnyUserTargets> {}
+  }
+}
+
+declare abstract class AnyUserTargets extends UserTargets {
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/core/loader.d.mts

@@ -1,10 +1,17 @@
-import type { AnyObject } from "../../../../types/utils.d.mts";
+import type { Identity, InexactPartial, NullishProps } from "fvtt-types/utils";
+import type { TranscoderWorker } from "@pixi/basis";
 
 declare global {
   /**
    * A Loader class which helps with loading video and image textures
    */
   class TextureLoader {
+    /**
+     * A global reference to the singleton texture loader
+     * @privateRemarks This is set outside the class via `TextureLoader.loader = new TextureLoader();`
+     */
+    static loader: TextureLoader;
+
     /**
      * The duration in milliseconds for which a texture will remain cached
      * @defaultValue `1000 * 60 * 15`
@@ -14,7 +21,7 @@ declare global {
     /**
      * Initialize the basis transcoder for PIXI.Assets
      */
-    static initializeBasisTranscoder(): Promise<unknown>;
+    static initializeBasisTranscoder(): TextureLoader.TranscodeWorkerLoadTranscoderReturn | Promise<void>;
 
     /**
      * Check if a source has a text file extension.
@@ -31,7 +38,7 @@ declare global {
      *                     (default: `1`)
      * @returns The texture data if the texture is valid, else undefined.
      */
-    static getTextureAlphaData(texture: PIXI.Texture, resolution?: number): TextureLoader.TextureAlphaData | undefined;
+    static getTextureAlphaData(texture: PIXI.Texture, resolution?: number): TextureLoader.TextureAlphaData | void;
 
     /**
      * Load all the textures which are required for a particular Scene
@@ -40,9 +47,9 @@ declare global {
      *                  (default: `{}`)
      */
     static loadSceneTextures(
-      scene: Scene.ConfiguredInstance,
-      options?: Partial<TextureLoader.LoadSceneTextureOptions>,
-    ): Promise<void[]>;
+      scene: Scene.Implementation,
+      options?: TextureLoader.LoadSceneTexturesOptions,
+    ): Promise<void>;
 
     /**
      * Load an Array of provided source URL paths
@@ -51,58 +58,29 @@ declare global {
      *                  (default: `{}`)
      * @returns A Promise which resolves once all textures are loaded
      */
-    load(sources: string[], options?: Partial<TextureLoader.LoadOptions>): Promise<PIXI.BaseTexture | void[]>;
+    load(sources: string[], options?: TextureLoader.LoadOptions): Promise<void>;
 
     /**
      * Load a single texture on-demand from a given source URL path
      * @param src - The source texture path to load
      * @returns The loaded texture object
      */
-    loadTexture(src: string): Promise<PIXI.BaseTexture | PIXI.Spritesheet | null>;
-
-    /**
-     * Log texture loading progress in the console and in the Scene loading bar
-     * @internal
-     */
-    protected _onProgress(src: string, progress: TextureLoader.Progress): void;
-
-    /**
-     * Log failed texture loading
-     * @internal
-     */
-    protected _onError(src: string, progress: TextureLoader.Progress, error: Error): void;
+    loadTexture(src: string): TextureLoader.LoadTextureReturn;
 
     /**
      * Use the Fetch API to retrieve a resource and return a Blob instance for it.
+     * @param src     - The resource URL
      * @param options - Options to configure the loading behaviour.
-     *                  (default: `{}`)
-     * @internal
+     * @returns A Blob containing the loaded data
      */
-    protected _fetchResource(
-      src: string,
-      options?: {
-        /**
-         * Append a cache-busting query parameter to the request.
-         * @defaultValue `false`
-         */
-        bustCache?: boolean | undefined;
-      },
-    ): Promise<Blob>;
-
-    /**
-     * Return a URL with a cache-busting query parameter appended.
-     * @param src - The source URL being attempted
-     * @returns The new URL, or false on a failure.
-     * @internal
-     */
-    protected _getCacheBustURL(src: string): string | false;
+    static fetchResource(src: string, options?: TextureLoader.FetchResourceOptions): Promise<Blob>;
 
     /**
      * Add an image or a sprite sheet url to the assets cache.
      * @param src - The source URL
      * @param tex - The readied texture
      */
-    setCache(src: string, tex: PIXI.BaseTexture | PIXI.Spritesheet): void;
+    setCache(src: string, asset: PIXI.BaseTexture | PIXI.Spritesheet): void;
 
     /**
      * Retrieve a texture or a sprite sheet from the assets cache
@@ -113,40 +91,43 @@ declare global {
     /**
      * Expire and unload assets from the cache which have not been used for more than CACHE_TTL milliseconds.
      */
-    expireCache(): void;
+    expireCache(): Promise<void>;
+
     /**
      * Return a URL with a cache-busting query parameter appended.
      * @param src - The source URL being attempted
      * @returns The new URL, or false on a failure.
      */
-    static getCacheBustURL(src: string): string | boolean;
+    static getCacheBustURL(src: string): string | false;
 
     /**
      * @deprecated since v11, will be removed in v13
      * @remarks TextureLoader#loadImageTexture is deprecated. Use TextureLoader#loadTexture instead.
      */
-    loadImageTexture(src: string): Promise<PIXI.BaseTexture>;
+    loadImageTexture(src: string): TextureLoader.LoadTextureReturn;
 
     /**
      * @deprecated since v11, will be removed in v13
      * @remarks TextureLoader#loadVideoTexture is deprecated. Use TextureLoader#loadTexture instead.
      */
-    loadVideoTexture(src: string): Promise<PIXI.BaseTexture>;
+    loadVideoTexture(src: string): TextureLoader.LoadTextureReturn;
 
     /**
      * @deprecated since v12, will be removed in v14
      * @remarks `"TextureLoader.textureBufferDataMap is deprecated without replacement. Use TextureLoader.getTextureAlphaData`
      * `to create a texture data map and cache it automatically, or create your own caching system."`
      */
-    static get textureBufferDataMap(): Map<string, AnyObject>;
-
-    /**
-     * A global reference to the singleton texture loader
-     */
-    static loader: TextureLoader;
+    static get textureBufferDataMap(): Map<unknown, unknown>;
   }
 
   namespace TextureLoader {
+    interface Any extends AnyTextureLoader {}
+    interface AnyConstructor extends Identity<typeof AnyTextureLoader> {}
+
+    type TranscodeWorkerLoadTranscoderReturn = ReturnType<typeof TranscoderWorker.loadTranscoder>;
+
+    type LoadTextureReturn = Promise<PIXI.BaseTexture | PIXI.Spritesheet | null>;
+
     interface TextureAlphaData {
       /** The width of the (downscaled) texture. */
       width: number;
@@ -170,50 +151,70 @@ declare global {
       data: Uint8Array;
     }
 
-    interface LoadSceneTextureOptions {
+    /** @internal */
+    type _LoadSceneTexturesOptions = InexactPartial<{
       /**
        * Destroy other expired textures
        * @defaultValue `true`
        */
-      expireCache?: boolean;
+      expireCache: boolean | null;
 
       /**
        * Additional sources to load during canvas initialize
        * @defaultValue `[]`
+       * @remarks Can't be `null` because it only has a parameter default.
+       * @privateRemarks Foundry types this as `boolean`, not even as an array, as of 13.335
        */
-      additionalSource?: Array<boolean>;
+      additionalSources: string[];
 
       /**
        * The maximum number of textures that can be loaded concurrently
+       * @remarks Can't be `null` becuase it is eventually passed to the constructor of
+       * {@link foundry.utils.Semaphore | `foundry.utils.Semaphore`}, with only a parameter deafult.
        */
-      maxConcurrent?: number;
-    }
+      maxConcurrent: number;
+    }>;
 
-    interface LoadOptions {
+    /** Options for {@link TextureLoader.loadSceneTextures | `TextureLoader.loadSceneTextures`}*/
+    interface LoadSceneTexturesOptions extends _LoadSceneTexturesOptions {}
+
+    /** @internal */
+    type _LoadOptions = NullishProps<{
       /**
        * The status message to display in the load bar
+       * @remarks Allowed to be null or undefined because ultimately `HTMLElement.textContent = undefined`
+       * or `= null` (via {@link SceneNavigation.displayProgressBar | `SceneNavigation.displayProgressBar`}) does not error and simply blanks textContent.
        */
-      message?: string | undefined;
+      message: string;
 
       /**
        * Expire other cached textures?
+       * @defaultValue `false`
+       */
+      expireCache: boolean;
+
+      /**
+       * Display loading progress bar?
        * @defaultValue `true`
        */
-      expireCache?: boolean;
+      displayProgress: boolean;
+    }> &
+      /** @privateRemarks Can't Pick `expireCache`, despite it existing on `LoadSceneTexturesOptions`, as it has a different default here */
+      Pick<LoadSceneTexturesOptions, "maxConcurrent">;
 
+    /** Options for {@link TextureLoader.load | `TextureLoader#load`} */
+    interface LoadOptions extends _LoadOptions {}
+
+    /** @internal */
+    type _FetchResourceOptions = NullishProps<{
       /**
-       * The maximum number of textures that can be loaded concurrently
+       * Append a cache-busting query parameter to the request.
+       * @defaultValue `false`
        */
-      maxConcurrent?: number;
-    }
+      bustCache: boolean;
+    }>;
 
-    interface Progress {
-      message: string;
-      loaded: number;
-      failed: number;
-      total: number;
-      pct: number;
-    }
+    interface FetchResourceOptions extends _FetchResourceOptions {}
   }
 
   /**
@@ -228,7 +229,7 @@ declare global {
    * @param src - The texture path to load.
    * @returns A texture, a sprite sheet or null if not found in cache.
    */
-  function getTexture(src: string): PIXI.Texture | null;
+  function getTexture(src: string): LoadTexture.Return;
 
   /**
    * Load a single asset and return a Promise which resolves once the asset is ready to use
@@ -236,11 +237,20 @@ declare global {
    * @param options  - Additional options which modify assset loading
    * @returns The loaded Texture or sprite sheet, or null if loading failed with no fallback
    */
-  function loadTexture(
-    src: string,
-    options?: {
+  function loadTexture(src: string, options?: LoadTexture.Options): Promise<LoadTexture.Return>;
+
+  namespace LoadTexture {
+    type Return = PIXI.Texture | PIXI.Spritesheet | null;
+
+    /** @internal */
+    type _Options = NullishProps<{
       /** A fallback texture URL to use if the requested source is unavailable */
-      fallback?: string;
-    },
-  ): Promise<PIXI.Texture | PIXI.Spritesheet | null>;
+      fallback: string;
+    }>;
+    interface Options extends _Options {}
+  }
+}
+
+declare abstract class AnyTextureLoader extends TextureLoader {
+  constructor(...args: never);
 }