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

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

@@ -1,19 +1,31 @@
-import type { ValueOf } from "../../../../types/utils.d.mts";
+import type { HandleEmptyObject, Identity, NullishProps } from "#utils";
 
 declare global {
   /**
    * A container group which contains visual effects rendered above the primary group.
+   *
+   * TODO:
+   *  The effects canvas group is now only performing shape initialization, logic that needs to happen at
+   *  the placeable or object level is now their burden.
+   *  - [DONE] Adding or removing a source from the EffectsCanvasGroup collection.
+   *  - [TODO] A change in a darkness source should re-initialize all overlaping light and vision source.
+   *
+   * ### Hook Events
+   * - {@link hookEvents.lightingRefresh | `hookEvents.lightingRefresh`}
    */
-  class EffectsCanvasGroup extends CanvasGroupMixin(PIXI.Container) {
-    constructor();
-
+  class EffectsCanvasGroup<
+    DrawOptions extends EffectsCanvasGroup.DrawOptions = EffectsCanvasGroup.DrawOptions,
+    TearDownOptions extends EffectsCanvasGroup.TearDownOptions = EffectsCanvasGroup.TearDownOptions,
+  > extends CanvasGroupMixin(PIXI.Container)<DrawOptions, TearDownOptions> {
     /**
      * Whether to currently animate light sources.
+     * @defaultValue `true`
      */
     animateLightSources: boolean;
 
     /**
      * Whether to currently animate vision sources.
+     * @defaultValue `true`
      */
     animateVisionSources: boolean;
 
@@ -73,7 +85,7 @@ declare global {
      */
     clearEffects(): void;
 
-    protected override _draw(options: CanvasGroupMixin.DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<DrawOptions>): Promise<void>;
 
     /**
      * Initialize positive light sources which exist within the active Scene.
@@ -92,17 +104,17 @@ declare global {
     /**
      * Refresh the state and uniforms of all light sources and darkness sources objects.
      */
-    refreshLightSources(): boolean;
+    refreshLightSources(): void;
 
     /**
      * Refresh the state and uniforms of all VisionSource objects.
      */
-    refreshVisionSources(): boolean;
+    refreshVisionSources(): void;
 
     /**
      * Refresh the active display of lighting.
      */
-    refreshLighting(): boolean;
+    refreshLighting(): void;
 
     /**
      * Test whether the point is inside light.
@@ -117,8 +129,9 @@ declare global {
      * @param point     - The point.
      * @param elevation - The elevation of the point.
      * @returns Is inside darkness?
+     * @remarks Foundry does not use the `elevation` parameter
      */
-    testInsideDarkness(point: Canvas.Point, elevation: number): boolean;
+    testInsideDarkness(point: Canvas.Point, _elevation?: number): boolean;
 
     /**
      * Get the darkness level at the given point.
@@ -128,14 +141,14 @@ declare global {
      */
     getDarknessLevel(point: Canvas.Point, elevation: number): number;
 
-    override _tearDown(options: CanvasGroupMixin.TearDownOptions): Promise<void>;
+    override _tearDown(options: HandleEmptyObject<TearDownOptions>): Promise<void>;
 
     /**
      * Activate vision masking for visual effects
      * @param enabled - Whether to enable or disable vision masking
      *                  (default: `true`)
      */
-    toggleMaskingFilters(enabled: boolean): void;
+    toggleMaskingFilters(enabled?: boolean): void;
 
     /**
      * Activate post-processing effects for a certain effects channel.
@@ -144,9 +157,9 @@ declare global {
      * @param uniforms            - The uniforms to update.
      */
     activatePostProcessingFilters(
-      filterMode: ValueOf<VisualEffectsMaskingFilter.FILTER_MODES>,
-      postProcessingModes: VisualEffectsMaskingFilter.PostProcessModes,
-      uniforms: AbstractBaseShader.Uniforms,
+      filterMode: VisualEffectsMaskingFilter.FILTER_MODES,
+      postProcessingModes?: VisualEffectsMaskingFilter.PostProcessModes,
+      uniforms?: AbstractBaseShader.Uniforms,
     ): void;
 
     /**
@@ -172,15 +185,53 @@ declare global {
      */
     animateDarkness(
       target?: number,
-      {
-        duration,
-      }?: {
-        /**
-         * The desired animation time in milliseconds. Default is 10 seconds
-         * @defaultValue 10000
-         */
-        duration?: number;
-      },
-    ): ReturnType<(typeof CanvasAnimation)["animate"]>;
+      options?: EffectsCanvasGroup.AnimateDarknessOptions,
+    ): CanvasAnimation.AnimateReturn;
+
+    /**
+     * @deprecated since v12, until v14
+     * @remarks "EffectsCanvasGroup#visibility has been deprecated and moved to Canvas#visibility."
+     */
+    get visibility(): Canvas["visibility"];
+
+    /**
+     * @deprecated since v12, until v14
+     * @remarks "EffectsCanvasGroup#globalLightSource has been deprecated and moved to EnvironmentCanvasGroup#globalLightSource."
+     */
+    get globalLightSource(): Canvas["environment"]["globalLightSource"];
+
+    /**
+     * @deprecated since v12
+     * @remarks "EffectsCanvasGroup#updateGlobalLightSource has been deprecated and is part of EnvironmentCanvasGroup#initialize workflow."
+     */
+    updateGlobalLightSource(): void;
   }
+
+  namespace EffectsCanvasGroup {
+    interface Any extends AnyEffectsCanvasGroup {}
+    interface AnyConstructor extends Identity<typeof AnyEffectsCanvasGroup> {}
+
+    /** @internal */
+    type _AnimateDarknessOptions = NullishProps<{
+      /**
+       * The desired animation time in milliseconds. Default is 10 seconds
+       * @defaultValue `10000`
+       * @remarks Only has a parameter default; `null` is effectively `0`, resulting in no animation, just instant darkness
+       */
+      duration: number;
+    }>;
+
+    interface AnimateDarknessOptions extends _AnimateDarknessOptions {}
+
+    interface DrawOptions extends CanvasGroupMixin.DrawOptions {}
+
+    interface TearDownOptions extends CanvasGroupMixin.TearDownOptions {}
+  }
+}
+
+declare abstract class AnyEffectsCanvasGroup extends EffectsCanvasGroup<
+  EffectsCanvasGroup.DrawOptions,
+  EffectsCanvasGroup.TearDownOptions
+> {
+  constructor(...args: never);
 }

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

@@ -1,50 +1,50 @@
-import type { InexactPartial } from "../../../../types/utils.d.mts";
-
-// TODO: Remove when this is typed as part of #2674
-type SceneEnvironmentData = unknown;
+import type { HandleEmptyObject, Identity, InexactPartial, NullishProps } from "#utils";
+import type { SceneEnvironmentData } from "../../../common/documents/_types.d.mts";
 
 declare global {
   /**
    * A container group which contains the primary canvas group and the effects canvas group.
    */
-  class EnvironmentCanvasGroup extends CanvasGroupMixin(PIXI.Container) {
+  class EnvironmentCanvasGroup<
+    DrawOptions extends EnvironmentCanvasGroup.DrawOptions = EnvironmentCanvasGroup.DrawOptions,
+    TearDownOptions extends EnvironmentCanvasGroup.TearDownOptions = EnvironmentCanvasGroup.TearDownOptions,
+  > extends CanvasGroupMixin<typeof PIXI.Container, "environment">(PIXI.Container)<DrawOptions, TearDownOptions> {
     /**
      * The global light source attached to the environment
+     * @remarks This is `defineProperty`'d as non-writable and non-configurable at construction
      */
-    globalLightSource(): foundry.canvas.sources.GlobalLightSource;
-
-    /**
-     * @defaultValue `"environment"`
-     */
-    static override groupName: string;
+    readonly globalLightSource: foundry.canvas.sources.GlobalLightSource.ConfiguredInstance;
 
     /**
+     * Should this group tear down its non-layer children?
      * @defaultValue `false`
      */
     static override tearDownChildren: boolean;
 
     /**
      * Colors exposed by the manager.
+     * @remarks Properties here are only `undefined` prior to `#initialize`ation
      */
-    colors: Record<string, Color | undefined>;
+    colors: EnvironmentCanvasGroup.Colors;
 
     /**
      * Weights used by the manager to compute colors.
+     * @remarks Properties here are only `undefined` prior to `#initialize`ation
      */
-    weights: Record<string, number | undefined>;
+    weights: EnvironmentCanvasGroup.Weights;
 
     /**
      * Get the darkness level of this scene.
      */
     get darknessLevel(): number;
 
-    protected override _draw(options: CanvasGroupMixin.DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<DrawOptions>): Promise<void>;
 
     /**
      * Initialize the scene environment options.
      * @remarks `@fires PIXI.FederatedEvent type: "darknessChange" - event: {environmentData: {darknessLevel, priorDarknessLevel}}`
      */
-    initialize(config: InexactPartial<EnvironmentCanvasGroup.InitializeConfig>): void;
+    initialize(config?: EnvironmentCanvasGroup.InitializeOptions): void;
 
     /**
      * @deprecated since v12, will be removed in v14
@@ -54,7 +54,34 @@ declare global {
   }
 
   namespace EnvironmentCanvasGroup {
-    interface InitializeConfig {
+    interface Any extends AnyEnvironmentCanvasGroup {}
+    interface AnyConstructor extends Identity<typeof AnyEnvironmentCanvasGroup> {}
+
+    interface DrawOptions extends CanvasGroupMixin.DrawOptions {}
+
+    interface TearDownOptions extends CanvasGroupMixin.TearDownOptions {}
+
+    type ColorKeys =
+      | "darkness"
+      | "halfdark"
+      | "background"
+      | "dim"
+      | "bright"
+      | "ambientBrightest"
+      | "ambientDaylight"
+      | "ambientDarkness"
+      | "sceneBackground"
+      | "fogExplored"
+      | "fogUnexplored";
+
+    interface Colors extends Record<EnvironmentCanvasGroup.ColorKeys, Color | undefined> {}
+
+    type WeightKeys = "dark" | "halfdark" | "dim" | "bright";
+
+    interface Weights extends Record<EnvironmentCanvasGroup.WeightKeys, number | undefined> {}
+
+    /** @internal */
+    type _InitializeOptions = NullishProps<{
       /** The background canvas color */
       backgroundColor: Color.Source;
 
@@ -73,8 +100,30 @@ declare global {
       /** The color applied to unexplored areas */
       fogUnexploredColor: Color.Source;
 
-      /** The scene environment data */
-      environment: SceneEnvironmentData;
-    }
+      /**
+       * @deprecated since v12 until v14
+       * @remarks "config.darknessLevel parameter into EnvironmentCanvasGroup#initialize is deprecated.
+       * You should pass the darkness level into config.environment.darknessLevel"
+       * @privateRemarks [sic]
+       */
+      darknessLevel: number;
+    }> &
+      InexactPartial<{
+        /**
+         * The scene environment data
+         * @defaultValue `{}`
+         * @remarks Can't be `null` as it only has a parameter default and has properties accessed
+         */
+        environment: NullishProps<SceneEnvironmentData>;
+      }>;
+
+    interface InitializeOptions extends _InitializeOptions {}
   }
 }
+
+declare abstract class AnyEnvironmentCanvasGroup extends EnvironmentCanvasGroup<
+  EnvironmentCanvasGroup.DrawOptions,
+  EnvironmentCanvasGroup.TearDownOptions
+> {
+  constructor(...args: never);
+}

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

@@ -1,40 +1,56 @@
-import type { EventMode } from "pixi.js";
+import type { HandleEmptyObject, Identity } from "#utils";
 
 declare global {
   /**
    * A specialized canvas group for rendering hidden containers before all others (like masks).
    */
-  class HiddenCanvasGroup extends CanvasGroupMixin(PIXI.Container) {
+  class HiddenCanvasGroup<
+    DrawOptions extends HiddenCanvasGroup.DrawOptions = HiddenCanvasGroup.DrawOptions,
+    TearDownOptions extends HiddenCanvasGroup.TearDownOptions = HiddenCanvasGroup.TearDownOptions,
+  > extends CanvasGroupMixin<typeof PIXI.Container, "hidden">(PIXI.Container)<DrawOptions, TearDownOptions> {
     /**
      * @defaultValue `"none"`
      */
-    override eventMode: EventMode;
+    override eventMode: PIXI.EventMode;
 
     /**
      * The container which hold masks.
      */
     masks: PIXI.Container;
 
-    /**
-     * @defaultValue `"hidden"`
-     */
-    static override groupName: string;
-
     /**
      * Add a mask to this group.
      * @param name          - Name of the mask.
      * @param displayObject - Display object to add.
      * @param position      - Position of the mask.
+     * @throws If `displayObject` doesn't implement a `clear` method, or if `name` is an empty string
+     * @remarks `position` is not used if fasley
      */
-    addMask(name: string, displayObject: PIXI.DisplayObject, position?: number): void;
+    addMask(name: string, displayObject: PIXI.DisplayObject, position?: number | null): void;
 
     /**
      * Invalidate the masks: flag them for rerendering.
      */
     invalidateMasks(): void;
 
-    protected override _draw(options: CanvasGroupMixin.DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<DrawOptions>): Promise<void>;
 
-    protected override _tearDown(options: CanvasGroupMixin.TearDownOptions): Promise<void>;
+    protected override _tearDown(options: HandleEmptyObject<TearDownOptions>): Promise<void>;
   }
+
+  namespace HiddenCanvasGroup {
+    interface Any extends AnyHiddenCanvasGroup {}
+    interface AnyConstructor extends Identity<typeof AnyHiddenCanvasGroup> {}
+
+    interface DrawOptions extends CanvasGroupMixin.DrawOptions {}
+
+    interface TearDownOptions extends CanvasGroupMixin.TearDownOptions {}
+  }
+}
+
+declare abstract class AnyHiddenCanvasGroup extends HiddenCanvasGroup<
+  HiddenCanvasGroup.DrawOptions,
+  HiddenCanvasGroup.TearDownOptions
+> {
+  constructor(...args: never);
 }

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

@@ -1,29 +1,28 @@
-import type { InexactPartial } from "../../../../types/utils.d.mts";
+import type { HandleEmptyObject, Identity, InexactPartial, NullishProps } from "#utils";
 
 declare global {
   /**
    * A container group which displays interface elements rendered above other canvas groups.
    */
-  class InterfaceCanvasGroup extends CanvasGroupMixin(PIXI.Container) {
-    /**
-     * @defaultValue `"interface"`
-     */
-    static override groupName: string;
-
+  class InterfaceCanvasGroup<
+    DrawOptions extends InterfaceCanvasGroup.DrawOptions = InterfaceCanvasGroup.DrawOptions,
+    TearDownOptions extends InterfaceCanvasGroup.TearDownOptions = InterfaceCanvasGroup.TearDownOptions,
+  > extends CanvasGroupMixin<typeof PIXI.Container, "interface">(PIXI.Container)<DrawOptions, TearDownOptions> {
     /**
      * Add a PrimaryGraphics to the group.
      * @param drawing - The Drawing being added
      * @returns The created Graphics instance
+     * @remarks
      */
-    addDrawing(drawing: Drawing): PIXI.Graphics;
+    addDrawing(drawing: Drawing.Object): PIXI.Graphics;
 
     /**
      * Remove a PrimaryGraphics from the group.
      * @param drawing - The Drawing being removed
      */
-    removeDrawing(drawing: Drawing): void;
+    removeDrawing(drawing: Drawing.Object): void;
 
-    protected override _draw(options: CanvasGroupMixin.DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<DrawOptions>): Promise<void>;
 
     /**
      * Display scrolling status text originating from this ObjectHUD container.
@@ -31,44 +30,69 @@ declare global {
      * @param content - The text content to display
      * @param options - Options which customize the text animation
      * @returns - The created PreciseText object which is scrolling
+     * @remarks Only returns `null` if the core `scrollingStatusText` setting is falsey
      */
     createScrollingText(
       origin: Canvas.Point,
       content: string,
-      options?: {
-        /**
-         * The duration of the scrolling effect in milliseconds
-         * @defaultValue `2000`
-         */
-        duration?: number;
+      options?: InterfaceCanvasGroup.CreateScrollingTextOptions,
+    ): Promise<PreciseText | null>;
+  }
 
-        /**
-         * The distance in pixels that the scrolling text should travel
-         * @defaultValue (2 * text.width)
-         */
-        distance?: number;
+  namespace InterfaceCanvasGroup {
+    interface Any extends AnyInterfaceCanvasGroup {}
+    interface AnyConstructor extends Identity<typeof AnyInterfaceCanvasGroup> {}
 
-        /**
-         * The original anchor point where the text appears
-         */
-        anchor: foundry.CONST.TEXT_ANCHOR_POINTS;
+    /** @internal */
+    type _CreateScrollingTextOptions = NullishProps<{
+      /**
+       * The distance in pixels that the scrolling text should travel
+       * @defaultValue Double the width or height of the text, depending on direction
+       * @remarks Default provided by `??`
+       */
+      distance: number;
 
-        /**
-         * The direction in which the text scrolls
-         */
-        direction: foundry.CONST.TEXT_ANCHOR_POINTS;
+      /**
+       * The original anchor point where the text appears
+       * @defaultValue `CONST.TEXT_ANCHOR_POINTS.CENTER`
+       */
+      anchor: foundry.CONST.TEXT_ANCHOR_POINTS;
 
-        /**
-         * An amount of randomization between [0, 1] applied to the initial position
-         * @defaultValue `0`
-         */
-        jitter: number;
+      /**
+       * The direction in which the text scrolls
+       * @defaultValue `CONST.TEXT_ANCHOR_POINTS.TOP`
+       */
+      direction: foundry.CONST.TEXT_ANCHOR_POINTS;
 
+      /**
+       * An amount of randomization between [0, 1] applied to the initial position
+       * @defaultValue `0`
+       * @remarks Only used if truthy
+       */
+      jitter: number;
+    }> &
+      InexactPartial<{
         /**
-         * Additional parameters of PIXI.TextStyle which are applied to the text
+         * The duration of the scrolling effect in milliseconds
+         * @defaultValue `2000`
+         * @remarks Can't be `null` as it only has a parameter default and a duration of `0` is not appropriate
          */
-        textStyle: InexactPartial<PIXI.ITextStyle>;
-      },
-    ): Promise<PreciseText | null>;
+        duration: number;
+      }> &
+      /**
+       * Additional parameters of PIXI.TextStyle which are applied to the text
+       * @remarks Excess keys are collected as `{...textStyle}` and passed to {@link PreciseText.getTextStyle | `PreciseText.getTextStyle`} which checks for `!== undefined`, so this can't be NullishProps
+       */
+      InexactPartial<PIXI.ITextStyle>;
+
+    interface CreateScrollingTextOptions extends _CreateScrollingTextOptions {}
+
+    interface DrawOptions extends CanvasGroupMixin.DrawOptions {}
+
+    interface TearDownOptions extends CanvasGroupMixin.TearDownOptions {}
   }
 }
+
+declare abstract class AnyInterfaceCanvasGroup extends InterfaceCanvasGroup {
+  constructor(...args: never);
+}

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

@@ -1,18 +1,30 @@
-export {};
+import type { Identity } from "#utils";
 
 declare global {
   /**
    * A container group which is not bound to the stage world transform.
    */
-  class OverlayCanvasGroup extends CanvasGroupMixin(UnboundContainer) {
-    /**
-     * @defaultValue `"overlay"`
-     */
-    static override groupName: string;
-
+  class OverlayCanvasGroup<
+    DrawOptions extends OverlayCanvasGroup.DrawOptions = OverlayCanvasGroup.DrawOptions,
+    TearDownOptions extends OverlayCanvasGroup.TearDownOptions = OverlayCanvasGroup.TearDownOptions,
+  > extends CanvasGroupMixin<typeof UnboundContainer, "overlay">(UnboundContainer)<DrawOptions, TearDownOptions> {
     /**
+     * Should this group tear down its non-layer children?
      * @defaultValue `false`
      */
     static override tearDownChildren: boolean;
   }
+
+  namespace OverlayCanvasGroup {
+    interface Any extends AnyOverlayCanvasGroup {}
+    interface AnyConstructor extends Identity<typeof AnyOverlayCanvasGroup> {}
+
+    interface DrawOptions extends CanvasGroupMixin.DrawOptions {}
+
+    interface TearDownOptions extends CanvasGroupMixin.TearDownOptions {}
+  }
+}
+
+declare abstract class AnyOverlayCanvasGroup extends OverlayCanvasGroup {
+  constructor(...args: never);
 }