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

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[]);
+}

package/src/foundry/client/pixi/core/interaction/mouse-handler.d.mts

@@ -1,4 +1,4 @@
-import type { ValueOf } from "../../../../../types/utils.d.mts";
+import type { Brand, NullishProps } from "fvtt-types/utils";
 
 declare global {
   /**
@@ -36,38 +36,34 @@ declare global {
    *  action: dragLeftCancel
    *  action: dragRightCancel
    */
-  class MouseInteractionManager<Object extends PIXI.Container = PIXI.Container> {
+  class MouseInteractionManager<ObjectFor extends PIXI.Container = PIXI.Container> {
     /**
      * @param permissions - (default: `{}`)
      * @param callbacks   - (default: `{}`)
      * @param options     - (default: `{}`)
+     * @remarks Foundry does not provide type information for the constructor, everything here is inferred from usage
      */
     constructor(
-      object: PIXI.Container,
-      layer: MouseInteractionManager["layer"],
-      permissions?: MouseInteractionManager["permissions"],
-      callbacks?: MouseInteractionManager["callbacks"],
-      options?: MouseInteractionManager["options"],
+      object: ObjectFor,
+      layer: PIXI.Container,
+      permissions?: MouseInteractionManager.Permissions,
+      callbacks?: MouseInteractionManager.Callbacks,
+      options?: MouseInteractionManager.Options,
     );
 
-    object: Object;
+    object: ObjectFor;
 
     layer: PIXI.Container;
 
     /**
      * @defaultValue `{}`
      */
-    permissions: Partial<
-      Record<
-        MouseInteractionManager.PermissionAction,
-        ((user: Game["user"], event: PIXI.FederatedEvent) => boolean) | boolean
-      >
-    >;
+    permissions: MouseInteractionManager.Permissions;
 
     /**
      * @defaultValue `{}`
      */
-    callbacks: Partial<Record<MouseInteractionManager.Action, ((event: Event | PIXI.FederatedEvent) => void) | null>>;
+    callbacks: MouseInteractionManager.Callbacks;
 
     /**
      * @defaultValue `{}`
@@ -78,17 +74,13 @@ declare global {
      * The current interaction state
      * @defaultValue `MouseInteractionManager.INTERACTION_STATES.NONE`
      */
-    state: ValueOf<(typeof MouseInteractionManager)["INTERACTION_STATES"]>;
+    state: MouseInteractionManager.INTERACTION_STATES;
 
     /**
      * Bound handlers which can be added and removed
      * @defaultValue `{}`
      */
-    interactionData: {
-      origin?: PIXI.Point;
-      destination?: PIXI.Point;
-      object?: Record<string, unknown>;
-    } & Partial<Record<string, unknown>>;
+    interactionData: MouseInteractionManager.InteractionData<ObjectFor>;
 
     /**
      * The drag handling time
@@ -112,7 +104,7 @@ declare global {
      * A flag for whether we are right-click dragging
      * @defaultValue `false`
      */
-    protected _dragRight: boolean;
+    _dragRight: boolean;
 
     /**
      * An optional ControlIcon instance for the object
@@ -139,7 +131,7 @@ declare global {
      * 4: DRAG - the object is being dragged
      * 5: DROP - the object is being dropped
      */
-    static INTERACTION_STATES: MouseInteractionManager.INTERACTION_STATES;
+    static INTERACTION_STATES: MouseInteractionManager.InteractionStates;
 
     /**
      * The maximum number of milliseconds between two clicks to be considered a double-click.
@@ -201,19 +193,19 @@ declare global {
      * @param args   - Additional callback arguments.
      * @returns A boolean which may indicate that the event was handled by the callback.
      *          Events which do not specify a callback are assumed to have been handled as no-op.
+     * @remarks
      */
     callback(action: MouseInteractionManager.Action, event: Event | PIXI.FederatedEvent, ...args: any[]): boolean;
 
     /**
      * A reference to the possible interaction states which can be observed
      */
-    get states(): MouseInteractionManager.INTERACTION_STATES;
+    get states(): typeof MouseInteractionManager.INTERACTION_STATES;
 
     /**
      * A reference to the possible interaction states which can be observed
      */
-    get handlerOutcomes(): MouseInteractionManager.HANDLER_OUTCOME;
-
+    get handlerOutcomes(): MouseInteractionManager.HandlerOutcomes;
     /**
      * A public method to handle directly an event into this manager, according to its type.
      * Note: drag events are not handled.
@@ -230,42 +222,44 @@ declare global {
     /**
      * Reset the mouse manager.
      */
-    reset(options?: {
-      /** Reset the interaction data? */
-      interactionData: boolean;
-
-      /** Reset the state? */
-      state: boolean;
-    }): void;
+    reset(options?: MouseInteractionManager.ResetOptions): void;
   }
 
   namespace MouseInteractionManager {
-    /**
-     * Enumerate the states of handle outcome.
-     */
-    interface HANDLER_OUTCOME {
+    interface Any extends AnyMouseInteractionManager {}
+    type AnyConstructor = typeof AnyMouseInteractionManager;
+
+    /** @privateRemarks The private class property is `#HANDLER_OUTCOME` singular, but the getter is `handlerOutcomes`, so the brand uses the plural*/
+    type HANDLER_OUTCOMES = Brand<number, "MouseInteractionManager.HANDLER_OUTCOMES">;
+
+    interface HandlerOutcomes {
       /** -2: SKIPPED - the handler has been skipped by previous logic */
-      SKIPPED: -2;
+      SKIPPED: -2 & MouseInteractionManager.HANDLER_OUTCOMES;
 
       /** -1: DISALLOWED - the handler has dissallowed further process */
-      DISALLOWED: -1;
+      DISALLOWED: -1 & MouseInteractionManager.HANDLER_OUTCOMES;
 
       /** 1: REFUSED - the handler callback has been processed and is refusing further process */
-      REFUSED: 1;
+      REFUSED: 1 & MouseInteractionManager.HANDLER_OUTCOMES;
 
       /** 2: ACCEPTED - the handler callback has been processed and is accepting further process */
-      ACCEPTED: 2;
+      ACCEPTED: 2 & MouseInteractionManager.HANDLER_OUTCOMES;
     }
 
-    interface INTERACTION_STATES {
-      NONE: 0;
-      HOVER: 1;
-      CLICKED: 2;
-      GRABBED: 3;
-      DRAG: 4;
-      DROP: 5;
+    type INTERACTION_STATES = Brand<number, "MouseInteractionManager.INTERACTION_STATES">;
+
+    interface InteractionStates {
+      NONE: 0 & MouseInteractionManager.INTERACTION_STATES;
+      HOVER: 1 & MouseInteractionManager.INTERACTION_STATES;
+      CLICKED: 2 & MouseInteractionManager.INTERACTION_STATES;
+      GRABBED: 3 & MouseInteractionManager.INTERACTION_STATES;
+      DRAG: 4 & MouseInteractionManager.INTERACTION_STATES;
+      DROP: 5 & MouseInteractionManager.INTERACTION_STATES;
     }
 
+    /**
+     * @remarks The list of actions provided by foundry, minus `dragXCancel`, `unclickX`, and `longPress`, which do not check permissions
+     */
     type PermissionAction =
       | "clickLeft"
       | "clickLeft2"
@@ -280,12 +274,85 @@ declare global {
       | "hoverIn"
       | "hoverOut";
 
-    type Action = PermissionAction | "dragLeftCancel" | "dragRightCancel";
+    type PermissionFunction = (user: User.ConfiguredInstance, event: Event | PIXI.FederatedEvent) => boolean;
+
+    type Permissions = Partial<Record<PermissionAction, PermissionFunction | boolean>>;
+
+    /**
+     * @remarks The full list of possible callback actions.
+     *
+     * Three actions get additional, non-event arguments passed by Foundry:
+     * - `hoverIn` on all placeables takes `options: { hoverOutOthers: boolean }` to trigger hover-out behavior on sibling objects
+     *   - For Regions specifically, `hoverOut` takes an `options: { updateLegend: boolean }` object, and that key is also added to Region `hoverIn` options
+     * - `longPress` receives `origin: PIXI.Point`
+     */
+    type Action =
+      | PermissionAction
+      | "dragLeftCancel"
+      | "dragRightCancel"
+      | "unclickLeft"
+      | "unclickRight"
+      | "longPress";
+
+    /**
+     * @remarks Only three actions get additional, non-event arguments passed by Foundry:
+     * - `hoverIn` on all placeables takes `options: { hoverOutOthers: boolean }` to trigger hover-out behavior on sibling objects
+     *   - For Regions specifically, `hoverOut` takes an `options: { updateLegend: boolean }` object, and that key is also added to Region `hoverIn` options
+     * - `longPress` receives `origin: PIXI.Point`
+     */
+    type CallbackFunction = (event: Event | PIXI.FederatedEvent, ...args: any[]) => boolean | null | void;
+
+    type Callbacks = Partial<Record<Action, CallbackFunction>>;
+
+    /** @internal */
+    type _Options = NullishProps<{
+      /**
+       * @remarks If passed, will set `this.controlIcon` to `Object[target]`; in practice, this should only be `null` or `"controlIcon"`
+       * @privateRemarks Despite Foundry typing this as `PIXI.DisplayObject` its one use in practice is as `string | null`
+       */
+      target: string | null;
 
-    interface Options {
-      target?: PIXI.DisplayObject;
+      /**
+       * @remarks If falsey, gets replaced with `(canvas.dimensions.size / 4)`
+       */
+      dragResistance: number;
 
-      dragResistance?: number;
+      /**
+       * @remarks Undocumented. Used in the constructor as `this.viewId = (this.options.application ?? canvas.app).view.id`, never passed in practice
+       */
+      application: PIXI.Application;
+    }>;
+
+    /**
+     * Interaction options which configure handling workflows
+     */
+    interface Options extends _Options {}
+
+    /** @internal */
+    type _ResetOptions = NullishProps<{
+      /**
+       * Reset the interaction data?
+       * @defaultValue `true`
+       */
+      interactionData: boolean;
+
+      /**
+       * Reset the state?
+       * @defaultValue `true`
+       */
+      state: boolean;
+    }>;
+
+    interface ResetOptions extends _ResetOptions {}
+
+    interface InteractionData<T> {
+      origin?: PIXI.Point;
+      destination?: PIXI.Point;
+      object?: T;
     }
   }
 }
+
+declare abstract class AnyMouseInteractionManager extends MouseInteractionManager {
+  constructor(arg0: never, ...args: never[]);
+}