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

package/src/foundry/client/pixi/core/containers/sprite-mesh.d.mts

@@ -11,22 +11,15 @@ declare global {
      * @param shaderCls - Shader class used by this sprite mesh.
      *                    (default: `BaseSamplerShader`)
      */
-    constructor(texture?: PIXI.Texture, shaderCls?: typeof BaseSamplerShader);
+    constructor(texture?: PIXI.Texture | null, shaderClass?: BaseSamplerShader.AnyConstructor);
 
+    /** @defaultValue `true` */
     override isSprite: boolean;
 
     /**
      * Snapshot of some parameters of this display object to render in batched mode.
      */
-    protected _batchData: {
-      _tintRGB: number;
-      _texture: PIXI.Texture;
-      indices: number[];
-      uvs: number[];
-      blendMode: PIXI.BLEND_MODES;
-      vertexData: number[];
-      worldAlpha: number;
-    };
+    protected _batchData: SpriteMesh.BatchData;
 
     /**
      * The indices of the geometry.
@@ -48,7 +41,7 @@ declare global {
     /**
      * The texture that the sprite is using.
      */
-    protected _texture: PIXI.Texture;
+    protected _texture: PIXI.Texture | null;
 
     /**
      * The texture ID
@@ -58,14 +51,15 @@ declare global {
 
     /**
      * Cached tint value so we can tell when the tint is changed.
+     * @defaultValue `[1, 1, 1, 1]`
      */
-    protected _cachedTint: [red: number, green: number, blue: number, alpha: number];
+    protected _cachedTint: Color.RGBAColorVector;
 
     /**
      * The texture trimmed ID.
      * @defaultValue `-1`
      */
-    _textureTrimmedID: number;
+    protected _textureTrimmedID: number;
 
     /**
      * This is used to store the uvs data of the sprite, assigned at the same time
@@ -102,6 +96,7 @@ declare global {
 
     /**
      * The transform ID.
+     * @defaultValue `-1`
      */
     private _transformID: number;
 
@@ -165,6 +160,7 @@ declare global {
      */
     get padding(): number;
 
+    /** @throws If `value < 0` */
     set padding(value);
 
     /**
@@ -208,6 +204,7 @@ declare global {
     /**
      * Returns the SpriteMesh associated batch plugin. By default the returned plugin is that of the associated shader.
      * If a plugin is forced, it will returns the forced plugin.
+     * @defaultValue `this._shader.pluginName`
      */
     get pluginName(): string;
 
@@ -220,7 +217,7 @@ declare global {
     /**
      * The texture that the sprite is using
      */
-    get texture(): PIXI.Texture;
+    get texture(): PIXI.Texture | null;
 
     set texture(texture);
 
@@ -235,8 +232,9 @@ declare global {
      * Setting the anchor to `(1,1)` would mean the sprite's origin point will be the bottom right corner.
      *
      * If you pass only single parameter, it will set both x and y to the same value as shown in the example below.
+     * @privateRemarks Technically should be `ObservablePoint<this>` but this breaks `PrimarySpriteMesh`
      */
-    get anchor(): PIXI.ObservablePoint;
+    get anchor(): PIXI.ObservablePoint<SpriteMesh.Any>;
 
     set anchor(anchor);
 
@@ -246,12 +244,13 @@ declare global {
      * A value of 0xFFFFFF will remove any tint effect.
      * @defaultValue `0xFFFFFF`
      */
-    get tint(): PIXI.ColorSource;
+    get tint(): number;
 
     set tint(tint);
 
     /**
      * The HTML source element for this SpriteMesh texture.
+     * @privateRemarks This could possibly be `PIXI.ImageSource | null`, but the below is Foundry's typing, which I think is accurate in practice
      */
     get sourceElement(): HTMLImageElement | HTMLVideoElement | null;
 
@@ -263,12 +262,12 @@ declare global {
     /**
      * When the texture is updated, this event will fire to update the scale and frame.
      */
-    _onTextureUpdate(): void;
+    protected _onTextureUpdate(): void;
 
     /**
      * Called when the anchor position updates.
      */
-    _onAnchorUpdate(): void;
+    protected _onAnchorUpdate(): void;
 
     /**
      * Update uvs and push vertices and uv buffers on GPU if necessary.
@@ -277,9 +276,9 @@ declare global {
 
     /**
      * Initialize shader based on the shader class type.
-     * @param shaderClass - Shader class used. Must inherit from AbstractBaseShader.
+     * @param shaderClass - The shader class
      */
-    setShaderClass(shaderClass: typeof AbstractBaseShader): void;
+    setShaderClass(shaderClass: BaseSamplerShader.AnyConstructor): void;
 
     override updateTransform(): void;
 
@@ -306,9 +305,10 @@ declare global {
 
     override getLocalBounds(rect: PIXI.Rectangle): PIXI.Rectangle;
 
+    /** @privateRemarks Foundry still marks this `@override` from when this class used to extend `PIXI.Mesh` */
     containsPoint(point: PIXI.IPointData): boolean;
 
-    override destroy(options: PIXI.IDestroyOptions | boolean): void;
+    override destroy(options?: PIXI.IDestroyOptions | boolean): void;
 
     /**
      * Create a SpriteMesh from another source.
@@ -318,9 +318,52 @@ declare global {
      * @param shaderClass    - The shader class to use. BaseSamplerShader by default.
      */
     static from(
-      source: string | PIXI.Texture | HTMLCanvasElement | HTMLVideoElement,
+      source: PIXI.Texture | HTMLImageElement | HTMLVideoElement | string,
       textureOptions?: PIXI.IBaseTextureOptions,
-      shaderClass?: typeof AbstractBaseShader,
+      shaderClass?: BaseSamplerShader.AnyConstructor,
     ): SpriteMesh;
   }
+
+  namespace SpriteMesh {
+    interface Any extends AnySpriteMesh {}
+    type AnyConstructor = typeof AnySpriteMesh;
+
+    /** Snapshot of some parameters of this display object to render in batched mode. */
+    interface BatchData {
+      _tintRGB: number | undefined;
+      _texture: PIXI.Texture | undefined | null;
+
+      /**
+       * @defaultValue `this.#geometry.indexBuffer.data`
+       * @remarks Set during construction
+       */
+      indices: number[];
+
+      /**
+       * @defaultValue `this.#geometry.buffers[1].data`
+       * @remarks Set during construction
+       */
+      uvs: number[];
+
+      blendMode: PIXI.BLEND_MODES | undefined;
+
+      /**
+       * @defaultValue `this.#geometry.buffers[0].data`
+       * @remarks Set during construction
+       */
+      vertexData: number[];
+
+      worldAlpha: number | undefined;
+
+      /**
+       * @defaultValue `this`
+       * @remarks Set during construction
+       */
+      object: SpriteMesh;
+    }
+  }
+}
+
+declare abstract class AnySpriteMesh extends SpriteMesh {
+  constructor(arg0: never, ...args: never[]);
 }

package/src/foundry/client/pixi/core/containers/unbound-container.d.mts

@@ -1,4 +1,4 @@
-import type { Transform } from "pixi.js";
+export {};
 
 declare global {
   /**
@@ -9,6 +9,11 @@ declare global {
     transform: UnboundTransform;
   }
 
+  namespace UnboundContainer {
+    interface Any extends AnyUnboundContainer {}
+    type AnyConstructor = typeof AnyUnboundContainer;
+  }
+
   /**
    * A custom Transform class which is not bound to the parent worldTransform.
    * localTransform are working as usual.
@@ -16,6 +21,19 @@ declare global {
   class UnboundTransform extends PIXI.Transform {
     static override IDENTITY: UnboundTransform;
 
-    override updateTransform(parentTransform: Transform): void;
+    override updateTransform(parentTransform: PIXI.Transform): void;
+  }
+
+  namespace UnboundTransform {
+    interface Any extends AnyUnboundTransform {}
+    type AnyConstructor = typeof AnyUnboundTransform;
   }
 }
+
+declare abstract class AnyUnboundContainer extends UnboundContainer {
+  constructor(arg0: never, ...args: never[]);
+}
+
+declare abstract class AnyUnboundTransform extends UnboundTransform {
+  constructor(arg0: never, ...args: never[]);
+}

package/src/foundry/client/pixi/core/interaction/canvas-animation.d.mts

@@ -1,104 +1,12 @@
-import type { ValueOf } from "../../../../../types/utils.d.mts";
-import type { PropertiesOfType } from "../../../../../types/helperTypes.d.mts";
+import type { PropertiesOfType, Brand, NullishProps, AnyObject } from "fvtt-types/utils";
 
 declare global {
-  namespace CanvasAnimation {
-    type EasingFunction = CoreEasingFunctions | ((percent: number) => number);
-    type CoreEasingFunctions = PropertiesOfType<typeof CanvasAnimation, (percent: number) => number>;
-  }
-
-  interface CanvasAnimationAttribute {
-    /** The attribute name being animated */
-    attribute: string;
-
-    /** The object within which the attribute is stored */
-    parent: object;
-
-    /** The destination value of the attribute */
-    to: number;
-
-    /** An initial value of the attribute, otherwise parent[attribute] is used */
-    from?: number;
-
-    /** The computed delta between to and from */
-    delta?: number;
-
-    /** The amount of the total delta which has been animated */
-    done?: number;
-
-    /** Is this a color animation that applies to RGB channels */
-    color?: boolean;
-  }
-
-  interface CanvasAnimationOptions {
-    /** A DisplayObject which defines context to the PIXI.Ticker function */
-    context?: PIXI.DisplayObject;
-
-    /** A unique name which can be used to reference the in-progress animation */
-    name?: string | symbol;
-
-    /** A duration in milliseconds over which the animation should occur */
-    duration?: number;
-
-    /**
-     * A priority in PIXI.UPDATE_PRIORITY which defines when the animation
-     * should be evaluated related to others
-     */
-    priority?: number;
-
-    /**
-     * An easing function used to translate animation time or the string name
-     * of a static member of the CanvasAnimation class
-     */
-    easing?: CanvasAnimation.EasingFunction;
-
-    /** A callback function which fires after every frame */
-    ontick?: (dt: number, animation: CanvasAnimationData) => void;
-  }
-
-  interface CanvasAnimationData extends CanvasAnimationOptions {
-    /** The animation function being executed each frame */
-    fn: (dt: number) => void;
-
-    /** The current time of the animation, in milliseconds */
-    time: number;
-
-    /** The attributes being animated */
-    attributes: CanvasAnimationAttribute[];
-
-    /** The current state of the animation */
-    state: ValueOf<typeof CanvasAnimation.STATES>;
-
-    /** A Promise which resolves once the animation is complete */
-    promise: Promise<boolean>;
-
-    /** The resolution function, allowing animation to be ended early */
-    resolve: (value: boolean) => void;
-
-    /** The rejection function, allowing animation to be ended early */
-    reject: (err: Error) => void;
-  }
-
   /**
    * A helper class providing utility methods for PIXI Canvas animation
    */
   class CanvasAnimation {
-    static get STATES(): {
-      /** An error occurred during waiting or running the animation. */
-      FAILED: -2;
-
-      /** The animation was terminated before it could complete. */
-      TERMINATED: -1;
-
-      /** Waiting for the wait promise before the animation is started. */
-      WAITING: 0;
-
-      /** The animation has been started and is running. */
-      RUNNING: 1;
-
-      /** The animation was completed without errors and without being terminated. */
-      COMPLETED: 2;
-    };
+    /** @privateRemarks Returns a private class property that is a frozen object, so keys are readonly */
+    static get STATES(): CanvasAnimation.States;
 
     /**
      * The ticker used for animations.
@@ -108,8 +16,10 @@ declare global {
     /**
      * Track an object of active animations by name, context, and function
      * This allows a currently playing animation to be referenced and terminated
+     * @privateRemarks Foundry does not account for the possibility of Symbol animation names and types the keys as simply `string`,
+     * despite typing `CanvasAnimationOptions.name` as `string | symbol`
      */
-    static animations: Record<string, CanvasAnimationData>;
+    static animations: Record<PropertyKey, CanvasAnimationData>;
 
     /**
      * Apply an animation from the current value of some attribute to a new value
@@ -138,20 +48,23 @@ declare global {
      * CanvasAnimation.animate(attributes, {duration:500});
      * ```
      */
-    static animate(attributes: CanvasAnimationAttribute[], options?: CanvasAnimationOptions): Promise<boolean>;
+    static animate(
+      attributes: CanvasAnimation.Attribute[],
+      options?: CanvasAnimationOptions,
+    ): CanvasAnimation.AnimateReturn;
 
     /**
      * Retrieve an animation currently in progress by its name
      * @param name - The animation name to retrieve
      * @returns The animation data, or undefined
      */
-    static getAnimation(name: string): CanvasAnimationData | undefined;
+    static getAnimation(name: PropertyKey): CanvasAnimationData | undefined;
 
     /**
      * If an animation using a certain name already exists, terminate it
      * @param name - The animation name to terminate
      */
-    static terminateAnimation(name: string): void;
+    static terminateAnimation(name: PropertyKey): void;
 
     /**
      * Cosine based easing with smooth in-out.
@@ -174,4 +87,150 @@ declare global {
      */
     static easeInCircle(pt: number): number;
   }
+
+  namespace CanvasAnimation {
+    interface Any extends AnyCanvasAnimation {}
+    type AnyConstructor = typeof AnyCanvasAnimation;
+
+    /** @remarks Helper type as many things `return CanvasAnimation.animate(...)` */
+    type AnimateReturn = Promise<boolean | void>;
+
+    type EasingFunction = CoreEasingFunctions | ((percent: number) => number);
+    type CoreEasingFunctions = PropertiesOfType<typeof CanvasAnimation, (percent: number) => number>;
+
+    type STATES = Brand<number, "CanvasAnimation.STATES">;
+
+    interface States {
+      /** An error occurred during waiting or running the animation. */
+      readonly FAILED: -2 & CanvasAnimation.STATES;
+
+      /** The animation was terminated before it could complete. */
+      readonly TERMINATED: -1 & CanvasAnimation.STATES;
+
+      /** Waiting for the wait promise before the animation is started. */
+      readonly WAITING: 0 & CanvasAnimation.STATES;
+
+      /** The animation has been started and is running. */
+      readonly RUNNING: 1 & CanvasAnimation.STATES;
+
+      /** The animation was completed without errors and without being terminated. */
+      readonly COMPLETED: 2 & CanvasAnimation.STATES;
+    }
+
+    type OnTickFunction = (dt: number, animation: CanvasAnimationData) => void;
+
+    /** @internal */
+    type _AnimationOptions = NullishProps<{
+      /**
+       * A DisplayObject which defines context to the PIXI.Ticker function
+       * @defaultValue `canvas.stage`
+       * @remarks `null` is allowed here because despite only having a parameter default,
+       * the (afaict, unexported) PIXI class `TickerListener`'s constructor (where this prop
+       * ends up) accepts `null` for context. This is likely never actually desireable, however.
+       */
+      context: PIXI.DisplayObject;
+
+      /** A unique name which can be used to reference the in-progress animation */
+      name: PropertyKey;
+
+      /**
+       * A priority in PIXI.UPDATE_PRIORITY which defines when the animation
+       * should be evaluated related to others
+       * @defaultValue `PIXI.UPDATE_PRIORITY.LOW + 1`
+       * @remarks Default provided by `??=` in function body. Numerical values between `UPDATE_PRIORITY`
+       * levels are valid but must be cast `as PIXI.UPDATE_PRIORITY` due to the Branded enum
+       */
+      priority: PIXI.UPDATE_PRIORITY;
+
+      /**
+       * An easing function used to translate animation time or the string name
+       * of a static member of the CanvasAnimation class
+       */
+      easing: CanvasAnimation.EasingFunction;
+
+      /** A callback function which fires after every frame */
+      ontick: OnTickFunction;
+
+      /** The animation isn't started until this promise resolves */
+      wait: Promise<unknown>;
+    }>;
+
+    /** @internal */
+    type _AnimationAttribute = NullishProps<{
+      /**
+       * An initial value of the attribute, otherwise parent[attribute] is used
+       * @remarks Will be replaced inside `.animate` with `Color.from(from)` if `to` is a `Color`
+       */
+      from: number | Color;
+    }>;
+
+    interface Attribute {
+      /** The attribute name being animated */
+      attribute: string;
+
+      /** The object within which the attribute is stored */
+      parent: AnyObject;
+
+      /** The destination value of the attribute */
+      to: number | Color;
+    }
+  }
+
+  interface CanvasAnimationOptions extends CanvasAnimation._AnimationOptions {
+    /**
+     * A duration in milliseconds over which the animation should occur
+     * @defaultValue `1000`
+     * @remarks Can't be `null` because it only has a parameter default, and used as a divisor in `CanvasAnimation.#animateFrame`
+     */
+    duration?: number | undefined;
+  }
+
+  interface CanvasAnimationAttribute extends CanvasAnimation.Attribute {
+    /**
+     * The computed delta between to and from
+     * @remarks This key is always overwritten inside `.animate`, its passed value is irrelevant
+     */
+    delta: number;
+
+    /**
+     * The amount of the total delta which has been animated
+     * @remarks This key is always overwritten inside `.animate`, its passed value is irrelevant
+     */
+    done: number;
+
+    /**
+     * Is this a color animation that applies to RGB channels
+     * @remarks When true, `CanvasAnimation.#animateFrame` assumes `to` *and* `from` are
+     * both `Color`s. It's automatically set `true` if `to` is passed as a `Color`, so it
+     * should be unnecessary to set manually.
+     */
+    color?: boolean;
+  }
+
+  interface CanvasAnimationData extends CanvasAnimationOptions {
+    /** The animation function being executed each frame */
+    fn: (dt: number) => void;
+
+    /** The current time of the animation, in milliseconds */
+    time: number;
+
+    /** The attributes being animated */
+    attributes: CanvasAnimationAttribute[];
+
+    /** The current state of the animation */
+    state: CanvasAnimation.STATES;
+
+    /** A Promise which resolves once the animation is complete */
+    promise: Promise<boolean>;
+
+    /** The resolution function, allowing animation to be ended early */
+    resolve: (value: boolean) => void;
+
+    /** The rejection function, allowing animation to be ended early */
+    reject: (err: Error) => void;
+  }
+}
+
+declare abstract class AnyCanvasAnimation extends CanvasAnimation {
+  constructor(arg0: never, ...args: never[]);
 }

package/src/foundry/client/pixi/core/interaction/control-icon.d.mts

@@ -1,25 +1,16 @@
-import type { InexactPartial } from "../../../../../types/utils.d.mts";
+import type { InexactPartial } from "fvtt-types/utils";
 
 declare global {
   /**
    * A generic helper for drawing a standard Control Icon
    */
   class ControlIcon extends PIXI.Container {
-    constructor(args: {
-      texture: string;
-
-      /** @defaultValue `40` */
-      size?: number;
-
-      /** @defaultValue `0xFF5500` */
-      borderColor?: number;
-
-      /** @defaultValue `null` */
-      tint?: number | null;
-
-      /** @defaultValue `number` */
-      elevation: number;
-    });
+    /**
+     * @remarks
+     * - Despite being an `={}` param, `options` is required (specifically its `texture` property)
+     * - Foundry adds a `...args` rest param after `options` and calls `super(...args)`, but `new PIXI.Container()` takes no arguments
+     */
+    constructor(options: ControlIcon.Options);
 
     iconSrc: string;
 
@@ -42,24 +33,23 @@ declare global {
     /**
      * @defaultValue `false`
      */
-    interactiveChildren: boolean;
+    override interactiveChildren: boolean;
+
+    override hitArea: PIXI.Rectangle;
 
-    hitArea: PIXI.Rectangle;
+    override cursor: string;
 
     bg: PIXI.Graphics;
 
     icon: PIXI.Sprite;
 
-    /**
-     * @defaultValue
-     * The `visible` property is true.
-     */
     border: PIXI.Graphics;
 
     tooltip: PreciseText;
 
     /**
      * The elevation of the ControlIcon, which is displayed in its tooltip text.
+     * @throws If a set is attempted with anything but a finite number
      */
     get elevation(): number;
 
@@ -77,13 +67,62 @@ declare global {
   }
 
   namespace ControlIcon {
+    interface Any extends AnyControlIcon {}
+    type AnyConstructor = typeof AnyControlIcon;
+
+    /** @internal */
+    type _Options = InexactPartial<{
+      /**
+       * @defaultValue `40`
+       * @remarks Can't be `null` as it only has a parameter default, and `null` coerced to `0` is a nonsensical size value
+       */
+      size: number;
+
+      /**
+       * @defaultValue `0xFF5500`
+       * @remarks Can't be `null` as that's not a valid value for the `PIXI.Color` constructor,
+       * and it only has a parameter default
+       */
+      borderColor: number;
+
+      /**
+       * @defaultValue `null`
+       * @remarks The default value of `null` is equivalent to `0xFFFFFF`, or effectively no tint
+       */
+      tint: number | null;
+
+      /**
+       * @defaultValue `number`
+       * @remarks Can't be null as the `ControlIcon#elevation` setter throws if passed anything but a finite number,
+       * and it only has a parameter default
+       */
+      elevation: number;
+    }>;
+
+    interface Options extends _Options {
+      /** A source string for the icon's texture */
+      texture: string;
+    }
+
+    /** @internal */
     type _RefreshOptions = InexactPartial<{
+      /** @remarks Can't be `null` because of an explicit `!== undefined` check */
       visible: boolean;
+
+      /** @remarks Can't be `null` because of an explicit `!== undefined` check */
       iconColor: number;
+
+      /** @remarks Can't be `null` because of an explicit `!== undefined` check */
       borderColor: number;
+
+      /** @remarks Can't be `null` because of an explicit `!== undefined` check */
       borderVisible: boolean;
     }>;
 
     interface RefreshOptions extends _RefreshOptions {}
   }
 }
+
+declare abstract class AnyControlIcon extends ControlIcon {
+  constructor(arg0: never, ...args: never[]);
+}