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

package/src/foundry/client/pixi/layers/controls/cursor.d.mts

@@ -1,33 +1,42 @@
-export {};
+import type { Identity } from "fvtt-types/utils";
 
 declare global {
   /**
    * A single Mouse Cursor
    */
   class Cursor extends PIXI.Container {
-    constructor(user: User.ConfiguredInstance);
+    constructor(user: User.Implementation);
 
     /**
-     * Update visibility and animations
-     * @param user - The user
+     * @defaultValue `{x: 0, y: 0}`
      */
-    refreshVisibility(user: User.ConfiguredInstance): void;
+    target: PIXI.IPointData;
 
     /**
-     * @defaultValue `{x: 0, y: 0}`
+     * Update visibility and animations
+     * @param user - The user
      */
-    target: { x: number; y: number };
+    refreshVisibility(user: User.Implementation): void;
 
     /**
      * Draw the user's cursor as a small dot with their user name attached as text
      */
-    draw(user: User.ConfiguredInstance): void;
+    draw(user: User.Implementation): void;
 
     /**
      * Move an existing cursor to a new position smoothly along the animation loop
      */
     protected _animate(): void;
 
-    override destroy(options?: PIXI.DisplayObject.DestroyOptions): void;
+    override destroy(options?: PIXI.IDestroyOptions | boolean): void;
+  }
+
+  namespace Cursor {
+    interface Any extends AnyCursor {}
+    interface AnyConstructor extends Identity<typeof AnyCursor> {}
   }
 }
+
+declare abstract class AnyCursor extends Cursor {
+  constructor(...args: never);
+}

package/src/foundry/client/pixi/layers/controls/door.d.mts

@@ -1,13 +1,19 @@
-export {};
+import type { FixedInstanceType, Identity } from "fvtt-types/utils";
 
 declare global {
   /**
    * An icon representing a Door Control
    */
   class DoorControl extends PIXI.Container {
-    constructor(wall: Wall.ConfiguredInstance);
+    constructor(wall: Wall.Object);
 
-    wall: Wall.ConfiguredInstance;
+    wall: Wall.Object;
+
+    /**
+     * @defaultValue `false`
+     * @remarks "Door controls are not visible by default"
+     */
+    override visible: boolean;
 
     /**
      * The center of the wall which contains the door.
@@ -19,23 +25,26 @@ declare global {
      */
     draw(): Promise<this>;
 
-    icon?: PIXI.Sprite;
-
+    /** @remarks Not initialized or even defined until set in {@link DoorControl#draw} */
     bg?: PIXI.Graphics;
 
+    /** @remarks Not initialized or even defined until set in {@link DoorControl#draw} */
+    icon?: PIXI.Sprite;
+
+    /** @remarks Not initialized or even defined until set in {@link DoorControl#draw} */
     border?: PIXI.Graphics;
 
     /**
      * Get the icon texture to use for the Door Control icon based on the door state
      */
-    protected _getTexture(): ReturnType<typeof getTexture>;
+    protected _getTexture(): LoadTexture.Return;
 
     reposition(): void;
 
     /**
      * Determine whether the DoorControl is visible to the calling user's perspective.
      * The control is always visible if the user is a GM and no Tokens are controlled.
-     * @see {@link CanvasVisibility#testVisibility}
+     * @see {@link CanvasVisibility.testVisibility | `CanvasVisibility#testVisibility`}
      */
     get isVisible(): boolean;
 
@@ -43,26 +52,38 @@ declare global {
      * Handle mouse over events on a door control icon.
      * @param event - The originating interaction event
      */
-    protected _onMouseOver(event: PIXI.FederatedEvent): false | undefined;
+    protected _onMouseOver(event: PIXI.FederatedEvent): false | void;
 
     /**
      * Handle mouse out events on a door control icon.
      * @param event - The originating interaction event
      */
-    protected _onMouseOut(event: PIXI.FederatedEvent): false | undefined;
+    protected _onMouseOut(event: PIXI.FederatedEvent): false | void;
 
     /**
      * Handle left mouse down events on a door control icon.
      * This should only toggle between the OPEN and CLOSED states.
      * @param event - The originating interaction event
      */
-    protected _onMouseDown(event: PIXI.FederatedEvent): false | undefined | Promise<WallDocument.ConfiguredInstance>;
+    protected _onMouseDown(event: PIXI.FederatedEvent): false | void | Promise<WallDocument.Implementation>;
 
     /**
      * Handle right mouse down events on the door control icon
      * This should toggle whether the door is LOCKED or CLOSED
      * @param event - The originating interaction event
      */
-    protected _onRightDown(event: PIXI.FederatedEvent): undefined | Promise<WallDocument.ConfiguredInstance>;
+    protected _onRightDown(event: PIXI.FederatedEvent): void | Promise<WallDocument.Implementation>;
+  }
+
+  namespace DoorControl {
+    interface Any extends AnyDoorControl {}
+    interface AnyConstructor extends Identity<typeof AnyDoorControl> {}
+
+    type ConfiguredClass = CONFIG["Canvas"]["doorControlClass"];
+    type ConfiguredInstance = FixedInstanceType<ConfiguredClass>;
   }
 }
+
+declare abstract class AnyDoorControl extends DoorControl {
+  constructor(...args: never);
+}

package/src/foundry/client/pixi/layers/controls/layer.d.mts

@@ -1,5 +1,4 @@
-import type { IntentionalPartial } from "../../../../../types/helperTypes.d.mts";
-import type { InexactPartial, NullishProps, RemoveIndexSignatures } from "../../../../../types/utils.d.mts";
+import type { FixedInstanceType, HandleEmptyObject, Identity, NullishProps } from "fvtt-types/utils";
 import type { LineIntersection } from "../../../../common/utils/geometry.d.mts";
 
 declare global {
@@ -11,10 +10,7 @@ declare global {
    * 2) Ruler measurement
    * 3) Map pings
    */
-  class ControlsLayer<
-    DrawOptions extends ControlsLayer.DrawOptions = ControlsLayer.DrawOptions,
-    TearDownOptions extends ControlsLayer.TearDownOptions = ControlsLayer.TearDownOptions,
-  > extends InteractionLayer<DrawOptions, TearDownOptions> {
+  class ControlsLayer extends InteractionLayer {
     constructor();
 
     /**
@@ -22,62 +18,74 @@ declare global {
      */
     static get instance(): Canvas["controls"];
 
-    /**
-     * A container of DoorControl instances
-     * @defaultValue `this.addChild(new PIXI.Container())`
-     */
-    doors: PIXI.Container;
-
     /**
      * Always interactive even if disabled for doors controls
      * @defaultValue `true`
      */
     override interactiveChildren: boolean;
 
+    /**
+     * A container of DoorControl instances
+     * @defaultValue `new PIXI.Container()`
+     */
+    doors: PIXI.Container;
+
     /**
      * A container of cursor interaction elements.
      * Contains cursors, rulers, interaction rectangles, and pings
-     * @defaultValue `this.addChild(new PIXI.Container())`
+     * @defaultValue `new PIXI.Container()`
+     * @remarks This Container's `eventMode` is set to `"none"` and its `mask` is set to `canvas.masks.canvas`
      */
     cursors: PIXI.Container;
 
     /**
      * Ruler tools, one per connected user
-     * @defaultValue `this.addChild(new PIXI.Container())`
+     * @defaultValue `new PIXI.Container()`
+     * @remarks This Container's `eventMode` is set to `"none"`
      */
     rulers: PIXI.Container;
 
     /**
      * A graphics instance used for drawing debugging visualization
-     * @defaultValue `this.addChild(new PIXI.Graphics())`
+     * @defaultValue `new PIXI.Graphics()`
+     * @remarks This Graphics's `eventMode` is set to `"none"`
      */
     debug: PIXI.Graphics;
 
     /**
      * Canvas selection rectangle
-     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw
      */
     select: PIXI.Graphics | undefined;
 
     /**
      * A mapping of user IDs to Cursor instances for quick access
      * @defaultValue `{}`
+     * @remarks Cursor class is non-configurable
      */
-    protected _cursors: Record<string, Cursor>;
+    _cursors: Record<string, Cursor>;
 
     /**
      * A convenience mapping of user IDs to Ruler instances for quick access
-     * @internal
      * @defaultValue `{}`
+     * @remarks Keys are User IDs
+     *
+     * Foundry marked `@private`
      */
-    protected _rulers: Record<string, Ruler>;
+    protected _rulers: Record<string, Ruler.ConfiguredInstance>;
 
     /**
      * The positions of any offscreen pings we are tracking.
-     * @internal
+     * @remarks Keys in the format `Ping.${foundry.utils.randomID()}`
+     *
+     * Foundry marked `@private`
      */
     protected _offscreenPings: Record<string, Canvas.Point>;
 
+    /**
+     * @privateRemarks This override does not exist in Foundry but reflects reality. Not automateable because of
+     * lack of access to the constructor from the instance side
+     */
     override options: ControlsLayer.LayerOptions;
 
     /**
@@ -94,16 +102,16 @@ declare global {
     /**
      * A convenience accessor to the Ruler for the active game user
      */
-    get ruler(): ReturnType<this["getRulerForUser"]>;
+    get ruler(): Ruler.ConfiguredInstance | null;
 
     /**
      * Get the Ruler display for a specific User ID
      */
-    getRulerForUser(userId: string): Ruler | null;
+    getRulerForUser(userId: string): Ruler.ConfiguredInstance | null;
 
-    override _draw(options?: DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<ControlsLayer.DrawOptions>): Promise<void>;
 
-    override _tearDown(options?: TearDownOptions): Promise<void>;
+    protected override _tearDown(options: HandleEmptyObject<ControlsLayer.TearDownOptions>): Promise<void>;
 
     /**
      * Draw the cursors container
@@ -126,7 +134,7 @@ declare global {
      */
     drawSelect(coords: Canvas.Rectangle): void;
 
-    override _deactivate(): void;
+    protected override _deactivate(): void;
 
     /**
      * Handle mousemove events on the game canvas to broadcast activity of the user's cursor position
@@ -138,10 +146,11 @@ declare global {
      * @param event   - The triggering canvas interaction event.
      * @param origin  - The local canvas coordinates of the mousepress.
      */
-    protected _onLongPress(event: PIXI.FederatedEvent, origin: PIXI.Point): ReturnType<Canvas["ping"]>;
+    protected _onLongPress(event: PIXI.FederatedEvent, origin: PIXI.Point): Promise<boolean>;
 
     /**
      * Handle the canvas panning to a new view.
+     * @remarks Called externally in {@link Canvas#pan}
      */
     protected _onCanvasPan(): void;
 
@@ -149,102 +158,75 @@ declare global {
      * Create and draw the Cursor object for a given User
      * @param user - The User document for whom to draw the cursor Container
      */
-    drawCursor(user: User.ConfiguredInstance): Cursor;
+    drawCursor(user: User.Implementation): Cursor;
 
     /**
      * Update the cursor when the user moves to a new position
      * @param user     - The User for whom to update the cursor
      * @param position - The new cursor position
      */
-    updateCursor(user: User.ConfiguredInstance, position: Canvas.Point | null): void;
+    updateCursor(user: User.Implementation, position: Canvas.Point | null): void;
 
     /**
      * Update display of an active Ruler object for a user given provided data
+     * @see {@link Ruler#update}
      */
-    updateRuler(user: User.ConfiguredInstance, rulerData: Ruler.MeasurementData | null): void;
+    updateRuler(user: User.Implementation, rulerData?: Ruler.MeasurementData | null): void;
 
     /**
      * Handle a broadcast ping.
-     * @see {@link Ping#drawPing}
+     * @see {@link Ping.drawPing | `Ping#drawPing`}
      * @param user     - The user who pinged.
      * @param position - The position on the canvas that was pinged.
      * @param data     - The broadcast ping data.
      * @returns A promise which resolves once the Ping has been drawn and animated
      */
     handlePing(
-      user: User.ConfiguredInstance,
+      user: User.Implementation,
       position: Canvas.Point,
-      /**
-       * @privateRemarks User.PingData is InexactPartial because `zoom` is assumed to be number
-       * PingOptions is IntentionalPartial because it gets `mergeObject`ed with some defaults */
-      data?: InexactPartial<User.PingData> & IntentionalPartial<PingOptions>,
-    ): ReturnType<this["drawPing"]>;
+      /** @remarks Despite being a `={}` parameter, an object containing a valid `scene` property (a scene ID) must be passed */
+      data: ControlsLayer.HandlePingOptions,
+    ): Promise<boolean>;
 
     /**
      * Draw a ping at the edge of the viewport, pointing to the location of an off-screen ping.
-     * @see {@link Ping#drawPing}
+     * @see {@link Ping.drawPing | `Ping#drawPing`}
      * @param position - The coordinates of the off-screen ping.
      * @param options  - Additional options to configure how the ping is drawn.
      * @returns A promise which resolves once the Ping has been drawn and animated
      */
     drawOffscreenPing(
       position: Canvas.Point,
-      options?: /** @remarks Can't be NullishProps or InexactPartial because PingOptions gets spread into an object with existing values for some keys */
-      IntentionalPartial<PingOptions> &
-        NullishProps<{
-          /**
-           * The style of ping to draw, from CONFIG.Canvas.pings.
-           * @defaultValue `"arrow"`
-           */
-          style: keyof RemoveIndexSignatures<typeof CONFIG.Canvas.pings.styles>;
-
-          /**
-           * The user who pinged.
-           */
-          user: User.ConfiguredInstance;
-        }>,
-    ): ReturnType<this["drawPing"]>;
+      options?: ControlsLayer.DrawOffscreenPingOptions, // not:null (destructured)
+    ): Promise<boolean>;
 
     /**
      * Draw a ping on the canvas
-     * @see {@link Ping#animate}
+     * @see {@link Ping.animate | `Ping#animate`}
      * @param position - The position on the canvas that was pinged.
      * @param options  - Additional options to configure how the ping is drawn.
      * @returns A promise which resolves once the Ping has been drawn and animated
      */
     drawPing(
-      position: PIXI.Point,
-      options?: /** @remarks Can't be NullishProps or InexactPartial because PingOptions gets `mergeObject`ed */
-      IntentionalPartial<PingOptions> &
-        NullishProps<{
-          /**
-           * The style of ping to draw, from CONFIG.Canvas.pings.
-           * @defaultValue `"pulse"`
-           */
-          style: keyof RemoveIndexSignatures<typeof CONFIG.Canvas.pings.styles>;
-
-          /**
-           * The user who pinged.
-           */
-          user: User.ConfiguredInstance;
-        }>,
-    ): ReturnType<Ping["animate"]>;
+      position: Canvas.Point,
+      options?: ControlsLayer.DrawPingOptions, // not:null (destructured)
+    ): Promise<boolean>;
 
     /**
      * Given off-screen coordinates, determine the closest point at the edge of the viewport to these coordinates.
      * @param position - The off-screen co-ordinate.
      * @returns The closest point at the edge of the viewport to these coordinates and a ray cast from the centre of the screen towards it.
-     * @internal
+     * @remarks Foundry marked `@private`
      */
-    protected _findViewportIntersection(position: Canvas.Point): {
-      ray: Ray;
-
-      intersection: LineIntersection | null;
-    };
+    protected _findViewportIntersection(position: Canvas.Point): ControlsLayer.ViewportIntersectionData;
   }
 
   namespace ControlsLayer {
-    type AnyConstructor = typeof AnyControlsLayer;
+    interface Any extends AnyControlsLayer {}
+    interface AnyConstructor extends Identity<typeof AnyControlsLayer> {}
+
+    type ImplementationClass = CONFIG["Canvas"]["layers"]["controls"]["layerClass"];
+    type Implementation = FixedInstanceType<ImplementationClass>;
 
     interface DrawOptions extends InteractionLayer.DrawOptions {}
 
@@ -254,9 +236,39 @@ declare global {
       name: "controls";
       zIndex: 1000;
     }
+
+    interface HandlePingOptions extends User.PingData, Ping.ConstructorOptions {}
+
+    /** @internal */
+    type _DrawPingOptions = NullishProps<{
+      /**
+       * The user who pinged.
+       * @remarks Only used to set the color of the ping. If `user?.color` ends up `undefined`, the relevant Ping class will provide a default color.
+       * If a `color` property is passed along with this, `color` will take precedence
+       */
+      user: User.Implementation;
+    }>;
+
+    interface DrawPingOptions extends _DrawPingOptions, Pick<User.PingData, "style">, Ping.ConstructorOptions {}
+
+    interface DrawOffscreenPingOptions extends DrawPingOptions {
+      /**
+       * @defaultValue `"arrow"`
+       * @remarks Can't be `null` as it only has a parameter default
+       */
+      style?: User.PingData["style"] | undefined;
+    }
+
+    interface ViewportIntersectionData {
+      /** A Ray from the center of the [viewport minus right sidebar] area to the point on the edge of that area in line with an offscreen ping */
+      ray: Ray;
+
+      /** The intersection with the viewport edge, or undefined if its on-screen */
+      intersection: LineIntersection | undefined;
+    }
   }
 }
 
 declare abstract class AnyControlsLayer extends ControlsLayer {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }