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

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 { AnyArray, Brand, Identity, 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;
+    callback(action: MouseInteractionManager.Action, event: Event | PIXI.FederatedEvent, ...args: AnyArray): 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 {}
+    interface AnyConstructor extends Identity<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.Implementation, 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: AnyArray) => 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(...args: never);
+}

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

@@ -1,31 +1,6 @@
-import type { IDestroyOptions } from "pixi.js";
+import type { Identity, IntentionalPartial, RemoveIndexSignatures } 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.
    */
@@ -34,17 +9,20 @@ declare global {
      * @param origin  - The canvas coordinates of the origin of the ping.
      * @param options - Additional options to configure the ping animation.
      */
-    constructor(origin: Canvas.Point, options?: PingOptions);
+    constructor(origin: Canvas.Point, options?: Ping.ConstructorOptions);
 
-    options: PingOptions;
+    options: Ping.ConstructorOptions;
 
-    _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>;
 
@@ -53,6 +31,59 @@ declare global {
      * @param dt        - The number of ms that elapsed since the previous frame.
      * @param animation - The animation state.
      */
-    protected _animateFrame(dt: number, animation: CanvasAnimationData): void;
+    protected _animateFrame(dt: number, animation: CanvasAnimation.AnimationData): void;
   }
+
+  namespace Ping {
+    interface Any extends AnyPing {}
+    interface AnyConstructor extends Identity<typeof AnyPing> {}
+
+    type ConfiguredStyles = keyof RemoveIndexSignatures<typeof CONFIG.Canvas.pings.styles>;
+
+    /** @internal */
+    type _ConstructorOptions = IntentionalPartial<{
+      /**
+       * 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, which only has a
+       * parameter default for this property
+       */
+      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 | `CanvasAnimation.animate`}.
+       */
+      name: PropertyKey | undefined | null;
+    }>;
+
+    interface ConstructorOptions extends Ping._ConstructorOptions {}
+  }
+
+  /**
+   * @deprecated {@link Ping.ConstructorOptions | `Ping.ConstructorOptions`}
+   */
+  type PingOptions = Ping.ConstructorOptions;
+}
+
+declare abstract class AnyPing extends Ping {
+  constructor(...args: never);
 }

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

@@ -10,7 +10,12 @@ declare global {
      * @param options - Additional options to configure the ping animation.
      *                  (default: `{duration: 900, size: 128, color: "#ff6400"}`)
      */
-    constructor(origin: Canvas.Point, options?: PingOptions);
+    constructor(
+      origin: Canvas.Point,
+
+      /** @privateRemarks Can't be `null` as it's directly assigned to  `Ping#options` which has properties accessed null-unsafely */
+      options?: Ping.ConstructorOptions,
+    );
 
     /** @defaultValue `(this.options.size / 2) * .75` */
     _r: number;
@@ -41,33 +46,41 @@ 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>;
 
-    override _animateFrame(dt: number, animation: CanvasAnimationData): void;
+    override _animateFrame(dt: number, animation: CanvasAnimation.AnimationData): void;
 
     /**
      * 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 { Identity, 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.
    */
@@ -23,9 +9,16 @@ declare global {
      * @param origin - The canvas coordinates of the origin of the ping.
      * @param options - Additional options to configure the ping animation.
      */
-    constructor(origin: Canvas.Point, options?: PulsePingOptions);
+    constructor(
+      origin: Canvas.Point,
 
-    _color2: Color | number;
+      /** @privateRemarks Can't be `null` as it's directly assigned to  `Ping#options` which has properties accessed null-unsafely */
+      options?: PulsePing.ConstructorOptions,
+    );
+
+    override options: PulsePing.ConstructorOptions;
+
+    _color2: Color;
 
     /**
      * The radius is half the diameter.
@@ -55,7 +48,7 @@ declare global {
 
     override animate(): Promise<boolean>;
 
-    override _animateFrame(dt: number, animation: CanvasAnimationData): void;
+    override _animateFrame(dt: number, animation: CanvasAnimation.AnimationData): void;
 
     /**
      * Transition linearly from one color to another.
@@ -64,9 +57,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,7 +68,31 @@ 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 {}
+    interface AnyConstructor extends Identity<typeof AnyPulsePing> {}
+
+    /** @internal */
+    type _ConstructorOptions = 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 ConstructorOptions extends _ConstructorOptions, Ping.ConstructorOptions {}
   }
 
   /**
@@ -86,18 +103,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;
-      },
-    );
+    constructor(origin: PIXI.Point, options?: ArrowPing.ConstructorOptions);
+
+    // @privateRemarks The `options` property does not get overridden here as the `rotation` key does not
+    // get passed up to super, so it's still just `PulsePing.Constructor.Options`
+
+    protected override _drawShape(g: PIXI.Graphics, color: number | Color, alpha: number, size: number): void;
+  }
+
+  namespace ArrowPing {
+    interface Any extends AnyArrowPing {}
+    interface AnyConstructor extends Identity<typeof AnyArrowPing> {}
 
-    protected override _drawShape(g: PIXI.Graphics, color: number, alph: number, size: number): void;
+    /** @internal */
+    type _ConstructorOptions = 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 ConstructorOptions extends _ConstructorOptions, PulsePing.ConstructorOptions {}
   }
 
   /**
@@ -108,8 +136,37 @@ 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.ConstructorOptions);
+
+    protected override _drawShape(g: PIXI.Graphics, color: number | Color, alpha: number, size: number): void;
+  }
+
+  namespace AlertPing {
+    interface Any extends AnyAlertPing {}
+    interface AnyConstructor extends Identity<typeof AnyAlertPing> {}
 
-    protected override _drawShape(g: PIXI.Graphics, color: number, alph: number, size: number): void;
+    /** @privateRemarks Only exists to change the default value of `color` */
+    interface ConstructorOptions extends PulsePing.ConstructorOptions {
+      /**
+       * @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
+       * @privateRemarks Typing this as `Ping.ConstructorOptions["color"]` breaks, because it thinks `| undefined` has snuck in for unknown reasons
+       */
+      color?: Color.Source;
+    }
   }
 }
+
+declare abstract class AnyPulsePing extends PulsePing {
+  constructor(...args: never);
+}
+
+declare abstract class AnyArrowPing extends ArrowPing {
+  constructor(...args: never);
+}
+
+declare abstract class AnyAlertPing extends AlertPing {
+  constructor(...args: never);
+}