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

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, Identity } 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, CanvasAnimation.AnimationData>;
 
     /**
      * 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?: CanvasAnimation.AnimateOptions,
+    ): 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): CanvasAnimation.AnimationData | 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,156 @@ declare global {
      */
     static easeInCircle(pt: number): number;
   }
+
+  namespace CanvasAnimation {
+    interface Any extends AnyCanvasAnimation {}
+    interface AnyConstructor extends Identity<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: CanvasAnimation.AnimationData) => void;
+
+    /** @internal */
+    type _AnimateOptions = 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 AnimateOptions extends CanvasAnimation._AnimateOptions {
+      /**
+       * 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 is 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 AnimationData extends CanvasAnimation.AnimateOptions {
+      /** 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;
+    }
+  }
+
+  /** @deprecated {@link CanvasAnimation.AnimateOptions | `CanvasAnimation.AnimateOptions`} */
+  type CanvasAnimationOptions = CanvasAnimation.AnimateOptions;
+
+  /** @deprecated {@link CanvasAnimation.AnimationData | `CanvasAnimation.AnimationData`} */
+  type CanvasAnimationData = CanvasAnimation.AnimationData;
+}
+
+declare abstract class AnyCanvasAnimation extends CanvasAnimation {
+  constructor(...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 { Identity, 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 {}
+    interface AnyConstructor extends Identity<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(...args: never);
+}