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

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

@@ -1,31 +1,6 @@
-import type { IDestroyOptions } from "pixi.js";
+import type { InexactPartial } from "fvtt-types/utils";
 
 declare global {
-  interface PingOptions {
-    /**
-     * The duration of the animation in milliseconds.
-     * @defaultValue `900`
-     */
-    duration?: number;
-
-    /**
-     * The size of the ping graphic.
-     * @defaultValue `128`
-     */
-    size?: number;
-
-    /**
-     * The color of the ping graphic.
-     * @defaultValue `#ff6400`
-     */
-    color?: string;
-
-    /**
-     * The name for the ping animation to pass to {@link CanvasAnimation.animate}.
-     */
-    name?: string;
-  }
-
   /**
    * A class to manage a user ping on the canvas.
    */
@@ -38,13 +13,16 @@ declare global {
 
     options: PingOptions;
 
-    _color: Color | number;
+    _color: Color;
 
-    destroy(options?: IDestroyOptions | boolean): void;
+    /** @remarks `Ping#destroy`'s parameter must be an object if passed, as the body does `options.children = true` */
+    override destroy(options?: PIXI.IDestroyOptions): void;
 
     /**
      * Start the ping animation.
      * @returns Returns true if the animation ran to completion, false otherwise.
+     * @privateRemarks This calls `CanvasAnimation.animate` with an empty attribute array for the first argument,
+     * meaning no chance of early return, so no `| void` in the return type
      */
     animate(): Promise<boolean>;
 
@@ -55,4 +33,49 @@ declare global {
      */
     protected _animateFrame(dt: number, animation: CanvasAnimationData): void;
   }
+
+  namespace Ping {
+    interface Any extends AnyPing {}
+    type AnyConstructor = typeof AnyPing;
+
+    /** @internal */
+    type _Options = InexactPartial<{
+      /**
+       * The duration of the animation in milliseconds.
+       * @defaultValue `900`
+       * @remarks Can't be `null` because `options` is `mergeObject`ed with an object with this key,
+       * and the result is passed on to `CanvasAnimation.animate` in its options
+       */
+      duration: number | undefined;
+
+      /**
+       * The size of the ping graphic.
+       * @defaultValue `128`
+       * @remarks Can't be `null` or `undefined` because `options` is `mergeObject`ed with an object with this key.
+       * This value is not used in the base `Ping` class, but is used by subclasses to define radius and padding in
+       * ways where `undefined` produces `NaN` and values of `0` (ie, cast `null`) are nonsensical
+       */
+      size: number;
+
+      /**
+       * The color of the ping graphic.
+       * @defaultValue `#ff6400`
+       * @remarks Can't be `null` or `undefined` because `options` is `mergeObject`ed with an object with this key,
+       * and passing either to `Color.from` produces a `Color(NaN)`, which may cause breakage in subclasses or when
+       * passed to PIXI methods
+       */
+      color: Color.Source;
+
+      /**
+       * The name for the ping animation to pass to {@link CanvasAnimation.animate}.
+       */
+      name?: PropertyKey | undefined | null;
+    }>;
+  }
+
+  interface PingOptions extends Ping._Options {}
+}
+
+declare abstract class AnyPing extends Ping {
+  constructor(arg0: never, ...args: never[]);
 }

package/src/foundry/client/pixi/core/interaction/pings/chevron.d.mts

@@ -41,11 +41,19 @@ declare global {
      */
     _t34: number;
 
+    /** @remarks Doesn't exist before the first `#_createRings()` call, usually via `#animate()` */
+    _inner?: PIXI.Graphics;
+
+    /** @remarks Doesn't exist before the first `#_createRings()` call, usually via `#animate()` */
+    _outer?: PIXI.Graphics;
+
     /**
      * The path to the chevron texture.
-     * @internal
+     * @remarks Unusually for Foundry, this is referred to by `ChevronPing.`, not `this.constructor.`, in
+     * `#_loadChevron()`, which must therefore be overridden to use a different value in a subclass
+     * @privateRemarks Foundry marked `@private`.
      */
-    protected static _CHEVRON_PATH: "icons/pings/chevron.webp";
+    static _CHEVRON_PATH: string;
 
     override animate(): Promise<boolean>;
 
@@ -54,20 +62,20 @@ declare global {
     /**
      * Draw the outer and inner rings.
      * @param a - The alpha.
-     * @internal
+     * @privateRemarks Foundry marked `@private`
      */
-    protected _drawRings(a: number): void;
+    _drawRings(a: number): void;
 
     /**
      * Load the chevron texture.
-     * @internal
+     * @privateRemarks Foundry marked `@private`
      */
-    protected _loadChevron(): Promise<PIXI.Sprite>;
+    _loadChevron(): Promise<PIXI.Sprite>;
 
     /**
      * Draw the two rings that are used as part of the ping animation.
-     * @internal
+     * @privateRemarks Foundry marked `@private`
      */
-    protected _createRings(): PIXI.Graphics[];
+    _createRings(): [PIXI.Graphics, PIXI.Graphics];
   }
 }

package/src/foundry/client/pixi/core/interaction/pings/pulse.d.mts

@@ -1,20 +1,6 @@
-export {};
+import type { InexactPartial, NullishProps } from "fvtt-types/utils";
 
 declare global {
-  interface PulsePingOptions extends PingOptions {
-    /**
-     * The number of rings used in the animation.
-     * (default: `3`)
-     */
-    rings?: number;
-
-    /**
-     * The alternate color that the rings begin at. Use white for a 'flashing' effect.
-     * (default: `#ffffff`)
-     */
-    color2?: string;
-  }
-
   /**
    * A type of ping that produces a pulsing animation.
    */
@@ -25,7 +11,9 @@ declare global {
      */
     constructor(origin: Canvas.Point, options?: PulsePingOptions);
 
-    _color2: Color | number;
+    override options: PulsePingOptions;
+
+    _color2: Color;
 
     /**
      * The radius is half the diameter.
@@ -64,9 +52,9 @@ declare global {
      * @param duration - The length of the transition in milliseconds.
      * @param t        - The current time along the duration.
      * @returns The incremental color between from and to.
-     * @internal
+     * @privateRemarks Foundry marked `@private`, and only types the return as `number`, instead of the more accurate `Color`
      */
-    protected _colorTransition(from: Color, to: Color, duration: number, t: number): number;
+    protected _colorTransition(from: Color, to: Color, duration: number, t: number): Color;
 
     /**
      * Draw the shape for this ping.
@@ -75,9 +63,33 @@ declare global {
      * @param alpha - The alpha of the shape.
      * @param size  - The size of the shape to draw.
      */
-    protected _drawShape(g: PIXI.Graphics, color: number, alph: number, size: number): void;
+    protected _drawShape(g: PIXI.Graphics, color: number | Color, alpha: number, size: number): void;
   }
 
+  namespace PulsePing {
+    interface Any extends AnyPulsePing {}
+    type AnyConstructor = typeof AnyPulsePing;
+
+    /** @internal */
+    type _Options = InexactPartial<{
+      /**
+       * The number of rings used in the animation.
+       * @defaultValue `3`
+       * @remarks Can't be `null` as it only has a parameter default and a coerced `0` ring count is nonsensical
+       */
+      rings?: number;
+
+      /**
+       * The alternate color that the rings begin at. Use white for a 'flashing' effect.
+       * @defaultValue `#ffffff`
+       * @remarks Can't be `null` as it only has a parameter default and `Color(NaN)`s are to be avoided
+       */
+      color2?: Color.Source;
+    }>;
+  }
+
+  interface PulsePingOptions extends PingOptions, PulsePing._Options {}
+
   /**
    * A type of ping that produces an arrow pointing in a given direction.
    */
@@ -86,18 +98,29 @@ declare global {
      * @param origin - The canvas coordinates of the origin of the ping. This becomes the arrow's tip.
      * @param options - Additional options to configure the ping animation.
      */
-    constructor(
-      origin: PIXI.Point,
-      options: PulsePingOptions & {
-        /**
-         * The angle of the arrow in radians.
-         * (default: `0`)
-         */
-        rotation: number;
-      },
-    );
-
-    protected override _drawShape(g: PIXI.Graphics, color: number, alph: number, size: number): void;
+    constructor(origin: PIXI.Point, options?: ArrowPing.Options);
+
+    // @privateRemarks `options` does not get overridden here as the `rotation` key does not
+    // get passed up to super, so the property is still just `PulsePingOptions`
+
+    protected override _drawShape(g: PIXI.Graphics, color: number | Color, alpha: number, size: number): void;
+  }
+
+  namespace ArrowPing {
+    interface Any extends AnyArrowPing {}
+    type AnyConstructor = typeof AnyArrowPing;
+
+    /** @internal */
+    type _Options = NullishProps<{
+      /**
+       * The angle of the arrow in radians.
+       * @defaultValue `0`
+       * @privateRemarks Null coercion to `0` is fine here, as it's only added to then passed to `Math.normalizeRadians`
+       */
+      rotation: number;
+    }>;
+
+    interface Options extends PulsePingOptions, _Options {}
   }
 
   /**
@@ -108,8 +131,36 @@ declare global {
      * @param origin  - The canvas coordinates of the origin of the ping.
      * @param options - Additional options to configure the ping animation.
      */
-    constructor(origin: PIXI.Point, options: PulsePingOptions);
+    constructor(origin: PIXI.Point, options: AlertPing.Options);
+
+    protected override _drawShape(g: PIXI.Graphics, color: number | Color, alpha: number, size: number): void;
+  }
 
-    protected override _drawShape(g: PIXI.Graphics, color: number, alph: number, size: number): void;
+  namespace AlertPing {
+    interface Any extends AnyAlertPing {}
+    type AnyConstructor = typeof AnyAlertPing;
+
+    /** @privateRemarks Only exists to change the default value of `color` */
+    interface Options extends PulsePingOptions {
+      /**
+       * @defaultValue `"#ff0000"`
+       * @remarks Can't be `null` or `undefined` because `options` is `mergeObject`ed with an object with this key,
+       * and passing either to `Color.from` produces a `Color(NaN)`, which may cause breakage in subclasses or when
+       * passed to PIXI methods
+       */
+      color?: PulsePingOptions["color"];
+    }
   }
 }
+
+declare abstract class AnyPulsePing extends PulsePing {
+  constructor(arg0: never, ...args: never[]);
+}
+
+declare abstract class AnyArrowPing extends ArrowPing {
+  constructor(arg0: never, ...args: never[]);
+}
+
+declare abstract class AnyAlertPing extends AlertPing {
+  constructor(arg0: never, ...args: never[]);
+}

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

@@ -1,4 +1,4 @@
-import type { AnyConstructor, InexactPartial, Mixin } from "../../../../../types/utils.d.mts";
+import type { AnyConstructor, FixedInstanceType, InexactPartial, Mixin } from "fvtt-types/utils";
 import type { LogCompatibilityWarningOptions } from "../../../../common/utils/logging.d.mts";
 
 declare class RenderFlagObject {
@@ -37,10 +37,10 @@ declare class RenderFlagObject {
  */
 type _RenderFlags<Flags> = InexactPartial<{
   /** Activating this flag also sets these flags to true */
-  propagate: Array<Partial<keyof Flags>>;
+  propagate: Array<keyof Flags>;
 
   /** Activating this flag resets these flags to false */
-  reset: Array<Partial<keyof Flags>>;
+  reset: Array<keyof Flags>;
 
   /**
    * Is this flag deprecated? The deprecation options are passed to
@@ -60,8 +60,10 @@ type _RenderFlags<Flags> = InexactPartial<{
 }>;
 
 declare global {
-
-  interface RenderFlag<Flags> extends _RenderFlags<Flags> {}
+  // @ts-expect-error - RenderFlag is built around willfully violating subclassing rules.
+  // The primary issue at hand is that each value can refer to the keys, thus making it technically
+  // unsound to apply a subclass to its superclass.
+  interface RenderFlag<out Flags> extends _RenderFlags<Flags> {}
 
   namespace RenderFlag {
     type Any = RenderFlag<any>;
@@ -87,7 +89,7 @@ declare global {
          * Valid options are OBJECTS or PERCEPTION.
          * @defaultValue `PIXI.UPDATE_PRIORITY.OBJECTS`
          */
-        priority?: PIXI.UPDATE_PRIORITY.OBJECTS | PIXI.UPDATE_PRIORITY.PERCEPTION;
+        priority?: PIXI.UPDATE_PRIORITY;
       },
     );
 
@@ -120,7 +122,14 @@ declare global {
    * @param Base - The base class being mixed. Normally a PIXI.DisplayObject
    * @returns The mixed class definition
    */
-  function RenderFlagsMixin<BaseClass extends AnyConstructor>(
+  function RenderFlagsMixin<BaseClass extends RenderFlagsMixin.BaseClass>(
     Base: BaseClass,
   ): Mixin<typeof RenderFlagObject, BaseClass>;
+
+  namespace RenderFlagsMixin {
+    type AnyMixedConstructor = ReturnType<typeof RenderFlagsMixin<BaseClass>>;
+    interface AnyMixed extends FixedInstanceType<AnyMixedConstructor> {}
+
+    type BaseClass = AnyConstructor;
+  }
 }

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

@@ -1,15 +1,15 @@
-export {};
+import type { 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 {}
+    type AnyConstructor = 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(arg0: never, ...args: never[]);
 }

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

@@ -1,27 +1,21 @@
 export {};
 
-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
    */
-  class UserTargets extends Set<TokenDocument.ObjectInstance> {
-    constructor(user: UserTargets["user"]);
+  class UserTargets extends Set<Token.ConfiguredInstance> {
+    constructor(user: User.ConfiguredInstance);
 
     user: User.ConfiguredInstance;
 
@@ -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.ConfiguredInstance): void;
 
     override clear(): void;
 
     /**
      * @remarks Returns void, but Set<T>.delete returns boolean
      */
-    override delete(token: TokenDocument.ObjectInstance): void;
+    override delete(token: Token.ConfiguredInstance): void;
   }
+
+  namespace UserTargets {
+    interface Any extends AnyUserTargets {}
+    type AnyConstructor = typeof AnyUserTargets;
+  }
+}
+
+declare abstract class AnyUserTargets extends UserTargets {
+  constructor(arg0: never, ...args: never[]);
 }