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

package/src/foundry/client/pixi/groups/primary.d.mts

@@ -1,4 +1,4 @@
-import type { Renderer } from "pixi.js";
+import type { Brand, HandleEmptyObject } from "fvtt-types/utils";
 
 // Included to match Foundry's documented types
 type PrimaryCanvasObject = ReturnType<typeof PrimaryCanvasObjectMixin>;
@@ -9,7 +9,10 @@ declare global {
    * This group is a {@link CachedContainer} which is rendered to the Scene as a {@link SpriteMesh}.
    * This allows the rendered result of the Primary Canvas Group to be affected by a {@link BaseSamplerShader}.
    */
-  class PrimaryCanvasGroup extends CanvasGroupMixin(CachedContainer) {
+  class PrimaryCanvasGroup<
+    DrawOptions extends PrimaryCanvasGroup.DrawOptions = PrimaryCanvasGroup.DrawOptions,
+    TearDownOptions extends PrimaryCanvasGroup.TearDownOptions = PrimaryCanvasGroup.TearDownOptions,
+  > extends CanvasGroupMixin<typeof CachedContainer, "primary">(CachedContainer)<DrawOptions, TearDownOptions> {
     /**
      * @param sprite - (default: `new SpriteMesh(undefined, BaseSamplerShader)`)
      */
@@ -18,24 +21,19 @@ declare global {
     /**
      * Sort order to break ties on the group/layer level.
      */
-    static readonly SORT_LAYERS: {
-      SCENE: number;
-      TILES: number;
-      DRAWINGS: number;
-      TOKENS: number;
-      WEATHER: number;
-    };
+    static SORT_LAYERS: PrimaryCanvasGroup.Sort_Layers;
 
     /**
-     * @defaultValue `"primary"`
+     * @defaultValue
+     * ```js
+     * {
+     *   scaleMode: PIXI.SCALE_MODES.NEAREST,
+     *   format: PIXI.FORMATS.RGB,
+     *   multisample: PIXI.MSAA_QUALITY.NONE
+     * }
+     * ```
      */
-    static override groupName: string;
-
-    static override textureConfiguration: {
-      scaleMode: PIXI.SCALE_MODES;
-      format: PIXI.FORMATS;
-      multisample: PIXI.MSAA_QUALITY;
-    };
+    static override textureConfiguration: CachedContainer.TextureConfiguration;
 
     /**
      * @defaultValue `"none"`
@@ -45,12 +43,12 @@ declare global {
     /**
      * @defaultValue `[0, 0, 0, 0]`
      */
-    override clearColor: [r: number, g: number, b: number, a: number];
+    override clearColor: Color.RGBAColorVector;
 
     /**
      * The background color in RGB.
      */
-    _backgroundColor?: [red: number, green: number, blue: number];
+    _backgroundColor: Color.RGBColorVector | undefined;
 
     /**
      * Track the set of HTMLVideoElements which are currently playing as part of this group.
@@ -59,6 +57,7 @@ declare global {
 
     /**
      * Occludable objects above this elevation are faded on hover.
+     * @defaultValue `0`
      */
     hoverFadeElevation: number;
 
@@ -71,53 +70,52 @@ declare global {
     /**
      * The primary background image configured for the Scene, rendered as a SpriteMesh.
      */
-    background: SpriteMesh;
+    background: SpriteMesh | undefined;
 
     /**
      * The primary foreground image configured for the Scene, rendered as a SpriteMesh.
      */
-    foreground: SpriteMesh;
+    foreground: SpriteMesh | undefined;
 
     /**
      * A Quadtree which partitions and organizes primary canvas objects.
      */
-    quadtree: CanvasQuadtree;
+    quadtree: CanvasQuadtree<PrimaryCanvasObjectMixin.AnyMixed>;
 
     /**
      * The collection of PrimaryDrawingContainer objects which are rendered in the Scene.
+     * @privateRemarks Foundry types this as `Collection<PrimaryDrawingContainer>`, which doesn't exist. It's `PrimaryGraphics` in practice.
      */
     drawings: Collection<PrimaryGraphics>;
 
     /**
      * The collection of SpriteMesh objects which are rendered in the Scene.
+     * @privateRemarks Foundry types this as `Collection<TokenMesh>`, which doesn't exist. In practice it's `PrimarySpriteMesh`
      */
     tokens: Collection<PrimarySpriteMesh>;
 
     /**
      * The collection of SpriteMesh objects which are rendered in the Scene.
+     * @privateRemarks Foundry types this as `Collection<PrimarySpriteMesh | TileSprite>`, but `TileSprite` doens't exist. In practice it's all `PrimarySpriteMesh`.
      */
     tiles: Collection<PrimarySpriteMesh>;
 
     /**
      * The ambience filter which is applying post-processing effects.
      */
-    _ambienceFilter: PrimaryCanvasGroupAmbienceFilter;
-
-    /**
-     * Render all tokens in their own render texture.
-     * @param renderer - The renderer to use.
-     */
-    _renderTokens(renderer: PIXI.Renderer): void;
+    _ambienceFilter: PrimaryCanvasGroupAmbienceFilter | undefined;
 
     /**
      * Return the base HTML image or video element which provides the background texture.
+     * @privateRemarks Foundry does not indicate the possibility of a null return
      */
-    get backgroundSource(): HTMLImageElement | HTMLVideoElement;
+    get backgroundSource(): HTMLImageElement | HTMLVideoElement | null;
 
     /**
      * Return the base HTML image or video element which provides the foreground texture.
+     * @privateRemarks Foundry does not indicate the possibility of a null return
      */
-    get foregroundSource(): HTMLImageElement | HTMLVideoElement;
+    get foregroundSource(): HTMLImageElement | HTMLVideoElement | null;
 
     /**
      * Refresh the primary mesh.
@@ -129,61 +127,62 @@ declare global {
      */
     update(): void;
 
-    protected override _draw(options: CanvasGroupMixin.DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<DrawOptions>): Promise<void>;
 
-    protected override _render(_renderer: Renderer): void;
+    protected override _render(_renderer: PIXI.Renderer): void;
 
-    protected override _tearDown(options: CanvasGroupMixin.TearDownOptions): Promise<void>;
+    protected override _tearDown(options: HandleEmptyObject<TearDownOptions>): Promise<void>;
 
     /**
      * Draw the SpriteMesh for a specific Token object.
      * @param token - The Token being added
      * @returns The added PrimarySpriteMesh
      */
-    addToken(token: Token): PrimarySpriteMesh;
+    addToken(token: Token.ConfiguredInstance): PrimarySpriteMesh;
 
     /**
      * Remove a TokenMesh from the group.
      * @param token - The Token being removed
      */
-    removeToken(token: Token): void;
+    removeToken(token: Token.ConfiguredInstance): void;
 
     /**
      * Draw the SpriteMesh for a specific Token object.
      * @param tile - The Tile being added
      * @returns The added PrimarySpriteMesh
      */
-    addTile(tile: Tile): PrimarySpriteMesh;
+    addTile(tile: Tile.ConfiguredInstance): PrimarySpriteMesh;
 
     /**
      * Remove a TokenMesh from the group.
      * @param tile - The Tile being removed
      */
-    removeTile(tile: Tile): void;
+    removeTile(tile: Tile.ConfiguredInstance): void;
 
     /**
      * Add a PrimaryGraphics to the group.
      * @param drawing - The Drawing being added
      * @returns The created PrimaryGraphics instance
      */
-    addDrawing(drawing: Drawing): PrimaryGraphics;
+    addDrawing(drawing: Drawing.ConfiguredInstance): PrimaryGraphics;
 
     /**
      * Remove a PrimaryGraphics from the group.
      * @param drawing - The Drawing being removed
      */
-    removeDrawing(drawing: Drawing): void;
+    removeDrawing(drawing: Drawing.ConfiguredInstance): void;
 
     /**
      * Override the default PIXI.Container behavior for how objects in this container are sorted.
-     * @override
+     * @remarks Actually an override of `PIXI.Container#sortChildren`
      */
     sortChildren(): void;
 
     /**
      * Handle mousemove events on the primary group to update the hovered state of its children.
+     * @remarks Foundry marked `@internal`
      */
-    protected _onMouseMove(): void;
+    _onMouseMove(): void;
 
     /**
      * @deprecated since v12, will be removed in v14
@@ -197,4 +196,27 @@ declare global {
      */
     mapElevationAlpha(elevation: number): number;
   }
+
+  namespace PrimaryCanvasGroup {
+    interface Any extends AnyPrimaryCanvasGroup {}
+    type AnyConstructor = typeof AnyPrimaryCanvasGroup;
+
+    interface DrawOptions extends CanvasGroupMixin.DrawOptions {}
+
+    interface TearDownOptions extends CanvasGroupMixin.TearDownOptions {}
+
+    type SORT_LAYERS = Brand<number, "PrimaryCanvasGroup.SORT_LAYERS">;
+
+    interface Sort_Layers {
+      readonly SCENE: 0 & SORT_LAYERS;
+      readonly TILES: 500 & SORT_LAYERS;
+      readonly DRAWINGS: 600 & SORT_LAYERS;
+      readonly TOKENS: 700 & SORT_LAYERS;
+      readonly WEATHER: 1000 & SORT_LAYERS;
+    }
+  }
+}
+
+declare abstract class AnyPrimaryCanvasGroup extends PrimaryCanvasGroup {
+  constructor(arg0: never, ...args: never[]);
 }

package/src/foundry/client/pixi/groups/rendered.d.mts

@@ -4,15 +4,27 @@ declare global {
   /**
    * A container group which contains the environment canvas group and the interface canvas group.
    */
-  class RenderedCanvasGroup extends CanvasGroupMixin(PIXI.Container) {
-    /**
-     * @defaultValue `"rendered"`
-     */
-    static override groupName: string;
-
+  class RenderedCanvasGroup<
+    DrawOptions extends RenderedCanvasGroup.DrawOptions = RenderedCanvasGroup.DrawOptions,
+    TearDownOptions extends RenderedCanvasGroup.TearDownOptions = RenderedCanvasGroup.TearDownOptions,
+  > extends CanvasGroupMixin<typeof PIXI.Container, "rendered">(PIXI.Container)<DrawOptions, TearDownOptions> {
     /**
+     * Should this group tear down its non-layer children?
      * @defaultValue `false`
      */
     static override tearDownChildren: boolean;
   }
+
+  namespace RenderedCanvasGroup {
+    interface Any extends AnyRenderedCanvasGroup {}
+    type AnyConstructor = typeof AnyRenderedCanvasGroup;
+
+    interface DrawOptions extends CanvasGroupMixin.DrawOptions {}
+
+    interface TearDownOptions extends CanvasGroupMixin.TearDownOptions {}
+  }
+}
+
+declare abstract class AnyRenderedCanvasGroup extends RenderedCanvasGroup {
+  constructor(arg0: never, ...args: never[]);
 }

package/src/foundry/client/pixi/layers/base/canvas-layer.d.mts

@@ -1,15 +1,10 @@
-export {};
+import type { HandleEmptyObject } from "fvtt-types/utils";
 
 declare global {
   /**
    * An abstract pattern for primary layers of the game canvas to implement
    */
-  abstract class CanvasLayer<
-    DrawOptions extends CanvasLayer.DrawOptions = CanvasLayer.DrawOptions,
-    TearDownOptions extends CanvasLayer.TearDownOptions = CanvasLayer.TearDownOptions,
-  > extends PIXI.Container {
-    constructor();
-
+  abstract class CanvasLayer extends PIXI.Container {
     /**
      * Options for this layer instance.
      * @defaultValue `this.constructor.layerOptions`
@@ -19,7 +14,7 @@ declare global {
     /**
      * @defaultValue `false`
      */
-    interactiveChildren: boolean;
+    override interactiveChildren: boolean;
 
     /**
      * Customize behaviors of this CanvasLayer by modifying some behaviors at a class level.
@@ -29,7 +24,7 @@ declare global {
     /**
      * Return a reference to the active instance of this canvas layer
      */
-    static get instance(): CanvasLayer | PIXI.Container | undefined;
+    static get instance(): CanvasLayer.Any | PIXI.Container | undefined;
 
     /**
      * The canonical name of the CanvasLayer is the name of the constructor that is the immediate child of the defined baseClass for the layer type.
@@ -48,29 +43,30 @@ declare global {
      * The Promise resolves to the drawn layer once its contents are successfully rendered.
      * @param options - Options which configure how the layer is drawn
      */
-    draw(options?: DrawOptions): Promise<this>;
+    draw(options?: HandleEmptyObject<CanvasLayer.DrawOptions>): Promise<this>;
 
     /**
      * The inner _draw method which must be defined by each CanvasLayer subclass.
      * @param options - Options which configure how the layer is drawn
      */
-    protected abstract _draw(options?: DrawOptions): Promise<void>;
+    protected abstract _draw(options: HandleEmptyObject<CanvasLayer.DrawOptions>): Promise<void>;
 
     /**
      * Deconstruct data used in the current layer in preparation to re-draw the canvas
      * @param options - Options which configure how the layer is deconstructed
      * @remarks ControlsLayer returns void. See https://gitlab.com/foundrynet/foundryvtt/-/issues/6939
      */
-    tearDown(options?: TearDownOptions): Promise<this | void>;
+    tearDown(options?: HandleEmptyObject<CanvasLayer.TearDownOptions>): Promise<this>;
 
     /**
      * The inner _tearDown method which may be customized by each CanvasLayer subclass.
      * @param options - Options which configure how the layer is deconstructed
      */
-    protected _tearDown(options?: TearDownOptions): Promise<void>;
+    protected _tearDown(options: HandleEmptyObject<CanvasLayer.TearDownOptions>): Promise<void>;
   }
 
   namespace CanvasLayer {
+    interface Any extends AnyCanvasLayer {}
     type AnyConstructor = typeof AnyCanvasLayer;
 
     interface LayerOptions {

package/src/foundry/client/pixi/layers/base/interaction-layer.d.mts

@@ -1,13 +1,10 @@
-import type { NullishProps } from "../../../../../types/utils.d.mts";
+import type { HandleEmptyObject, NullishProps } from "fvtt-types/utils";
 
 declare global {
   /**
    * A subclass of CanvasLayer which provides support for user interaction with its contained objects.
    */
-  class InteractionLayer<
-    DrawOptions extends InteractionLayer.DrawOptions = InteractionLayer.DrawOptions,
-    TearDownOptions extends CanvasLayer.TearDownOptions = CanvasLayer.TearDownOptions,
-  > extends CanvasLayer<DrawOptions, TearDownOptions> {
+  class InteractionLayer extends CanvasLayer {
     /**
      * Is this layer currently active
      */
@@ -20,6 +17,7 @@ declare global {
 
     /**
      * @defaultValue `"passive"`
+     * @remarks Set to `"static"` when this layer is `#activate()`d, returned to `"passive"` when `#deactivate()`d
      */
     override eventMode: PIXI.EventMode;
 
@@ -40,14 +38,7 @@ declare global {
      * @param options - Options which configure layer activation
      * @returns - The layer instance, now activated
      */
-    activate(
-      options?: NullishProps<{
-        /**
-         * A specific tool in the control palette to set as active
-         */
-        tool: string;
-      }>,
-    ): this;
+    activate(options?: InteractionLayer.ActivateOptions): this;
 
     /**
      * The inner _activate method which may be defined by each InteractionLayer subclass.
@@ -65,7 +56,7 @@ declare global {
      */
     protected _deactivate(): void;
 
-    protected override _draw(options?: DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<InteractionLayer.DrawOptions>): Promise<void>;
 
     /**
      * Get the zIndex that should be used for ordering this layer vertically relative to others in the same Container.
@@ -74,7 +65,7 @@ declare global {
 
     /**
      * Handle left mouse-click events which originate from the Canvas stage.
-     * @see {@link Canvas._onClickLeft}
+     * @see {@link Canvas#_onClickLeft}
      * @param event - The PIXI InteractionEvent which wraps a PointerEvent
      */
     protected _onClickLeft(event: PIXI.FederatedEvent): void;
@@ -97,9 +88,8 @@ declare global {
      * Start a left-click drag workflow originating from the Canvas stage.
      * @see {@link Canvas.#onDragLeftStart}
      * @param event - The PIXI InteractionEvent which wraps a PointerEvent
-     * @remarks Current implementation always returns undefined
      */
-    protected _onDragLeftStart(event: PIXI.FederatedEvent): unknown;
+    protected _onDragLeftStart(event: PIXI.FederatedEvent): void;
 
     /**
      * Continue a left-click drag workflow originating from the Canvas stage.
@@ -145,6 +135,7 @@ declare global {
   }
 
   namespace InteractionLayer {
+    interface Any extends AnyInteractionLayer {}
     type AnyConstructor = typeof AnyInteractionLayer;
 
     interface LayerOptions extends CanvasLayer.LayerOptions {
@@ -153,7 +144,17 @@ declare global {
       baseClass: typeof InteractionLayer;
     }
 
+    /** @internal */
+    type _ActivateOptions = NullishProps<{
+      /** A specific tool in the control palette to set as active */
+      tool: string;
+    }>;
+
+    interface ActivateOptions extends _ActivateOptions {}
+
     interface DrawOptions extends CanvasLayer.DrawOptions {}
+
+    interface TearDownOptions extends CanvasLayer.TearDownOptions {}
   }
 }