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

package/src/foundry/client/pixi/core/shapes/ray.d.mts

@@ -71,14 +71,14 @@ declare global {
     /**
      * The cached angle, computed lazily in Ray#angle
      * @defaultValue `undefined`
-     * @internal
+     * @privateRemarks Foundry marked `@private` and doesn't type the `| undefined`
      */
     protected _angle: number | undefined;
 
     /**
      * The cached distance, computed lazily in Ray#distance
      * @defaultValue `undefined`
-     * @internal
+     * @privateRemarks Foundry marked `@private` and doesn't type the `| undefined`
      */
     protected _distance: number | undefined;
 
@@ -87,10 +87,11 @@ declare global {
      * The angle is computed lazily (only if required) and cached.
      */
     get angle(): number;
-    set angle(value: number);
+
+    set angle(value);
 
     /**
-     * A bounding rectangle that encompasses the Ray
+     * A normalized bounding rectangle that encompasses the Ray
      */
     get bounds(): PIXI.Rectangle;
 
@@ -99,7 +100,8 @@ declare global {
      * The distance is computed lazily (only if required) and cached.
      */
     get distance(): number;
-    set distance(value: number);
+
+    set distance(value);
 
     /**
      * A factory method to construct a Ray from an origin point, an angle, and a distance
@@ -117,7 +119,7 @@ declare global {
      * @param B - The destination point [x,y]
      * @returns The constructed Ray instance
      */
-    static fromArrays(A: Canvas.PointArray, B: Canvas.PointArray): Ray;
+    static fromArrays(A: Canvas.PointTuple, B: Canvas.PointTuple): Ray;
 
     /**
      * Project the Array by some proportion of it's initial distance.
@@ -125,7 +127,7 @@ declare global {
      * @param t - The distance along the Ray
      * @returns The coordinates of the projected point
      */
-    project(t: number): { x: number; y: number };
+    project(t: number): PIXI.IPointData;
 
     /**
      * Create a Ray by projecting a certain distance towards a known point.
@@ -154,12 +156,28 @@ declare global {
      * @param distance - A distance the new ray should project, otherwise uses the same distance.
      * @returns A new Ray with an offset angle
      */
-    shiftAngle(angleOffset: number, distance?: number): Ray;
+    shiftAngle(
+      offset: number,
+      /**
+       * @defaultValue `this.distance`
+       * @remarks Default provided by `||`, so `0` is effectively `this.distance`
+       */
+      distance?: number | null,
+    ): Ray;
 
     /**
      * Find the point I[x,y] and distance t* on ray R(t) which intersects another ray
      * @see foundry.utils.lineLineIntersection
      */
-    intersectSegment(coords: [x0: number, y0: number, x1: number, y1: number]): LineIntersection | null;
+    intersectSegment(coords: Canvas.PairOfPointsTuple): LineIntersection | null;
+  }
+
+  namespace Ray {
+    interface Any extends AnyRay {}
+    type AnyConstructor = typeof AnyRay;
   }
 }
+
+declare abstract class AnyRay extends Ray {
+  constructor(arg0: never, ...args: never[]);
+}

package/src/foundry/client/pixi/core/shapes/source-polygon.d.mts

@@ -1,24 +1,20 @@
-import type { ConstructorOf, InexactPartial } from "../../../../../types/utils.d.mts";
+import type { Brand, Coalesce, InexactPartial, NullishProps } from "fvtt-types/utils";
 import type PointEffectSourceMixin from "../../../../client-esm/canvas/sources/point-effect-source.d.mts";
 
 declare global {
-  interface PointSourcePolygonConfig extends PointSourcePolygon._Config {
-    /** The type of polygon being computed */
-    type: PointSourcePolygon.PolygonType;
-  }
-
   /**
    * An extension of the default PIXI.Polygon which is used to represent the line of sight for a point source.
    */
   abstract class PointSourcePolygon extends PIXI.Polygon {
+    /**
+     * @remarks This is protected because `new PointSourcePolygon` does not sufficiently initalize the class; Use the static `create` method instead.
+     */
+    protected constructor(...args: ConstructorParameters<typeof PIXI.Polygon>);
+
     /**
      * Customize how wall direction of one-way walls is applied
      */
-    static readonly WALL_DIRECTION_MODES: Readonly<{
-      NORMAL: 0;
-      REVERSED: 1;
-      BOTH: 2;
-    }>;
+    static WALL_DIRECTION_MODES: PointSourcePolygon.WallDirectionModes;
 
     /**
      * The rectangular bounds of this polygon
@@ -28,14 +24,15 @@ declare global {
 
     /**
      * The origin point of the source polygon.
+     * @remarks Not initalized to any value, but immediately set by `PointSourcePolygon#initalize`
      */
     origin: Canvas.Point;
 
     /**
      * The configuration of this polygon.
-     * @defaultValue `{}`
+     * @remarks Initialized as `{}` but immediately filled by `PointSourcePolygon#initalize`
      */
-    config: PointSourcePolygonConfig;
+    config: PointSourcePolygon.StoredConfig;
 
     /**
      * An indicator for whether this polygon is constrained by some boundary shape?
@@ -48,20 +45,18 @@ declare global {
      * @param origin     - The origin point to benchmark
      * @param config     - The polygon configuration to benchmark
      */
-    static benchmark(iterations: number, origin: Canvas.Point, config: PointSourcePolygonConfig): Promise<void>;
+    static benchmark(iterations: number, origin: Canvas.Point, config: PointSourcePolygon.Config): Promise<void>;
 
     /**
      * Compute the polygon given a point origin and radius
      * @param origin - The origin source point
      * @param config - Configuration options which customize the polygon computation
-     *                 (default: `{}`)
      * @returns The computed polygon instance
+     * @remarks Subclasses must implement a `.create` override to accurately type the return.
+     *
+     * Despite being a `={}` parameter, a `config` object with a valid `type` property must be passed
      */
-    static create<T extends ConstructorOf<PointSourcePolygon>>(
-      this: T,
-      origin: Canvas.Point,
-      config?: Parameters<InstanceType<T>["initialize"]>[1],
-    ): InstanceType<T>;
+    static create(origin: Canvas.Point, config: PointSourcePolygon.Config): unknown;
 
     /**
      * Create a clone of this polygon.
@@ -86,7 +81,7 @@ declare global {
      * @param origin - The provided polygon origin
      * @param config - The provided configuration object
      */
-    initialize(origin: Canvas.Point, config: PointSourcePolygonConfig): void;
+    initialize(origin: Canvas.Point, config: PointSourcePolygon.Config): void;
 
     /**
      * Apply a constraining boundary shape to an existing PointSourcePolygon.
@@ -96,12 +91,16 @@ declare global {
      * @param intersectionOptions - Options passed to the shape intersection method
      * @returns A new constrained polygon
      */
+    applyConstraint(constraint: PIXI.Polygon, intersectionOptions?: PIXI.Polygon.IntersectPolygonOptions): this;
+    applyConstraint(constraint: PIXI.Circle, intersectionOptions?: PIXI.Circle.WACIntersectPolygonOptions): this;
+    applyConstraint(constraint: PIXI.Circle, intersectionOptions?: PIXI.Circle.ClipperLibIntersectPolygonOptions): this;
+    applyConstraint(constraint: PIXI.Rectangle, intersectionOptions?: PIXI.Rectangle.WACIntersectPolygonOptions): this;
     applyConstraint(
-      constraint: PIXI.Circle | PIXI.Rectangle | PIXI.Polygon,
-      intersectionOptions?: Record<string, unknown>,
-    ): PointSourcePolygon;
+      constraint: PIXI.Rectangle,
+      intersectionOptions?: PIXI.Rectangle.ClipperLibIntersectPolygonOptions,
+    ): this;
 
-    contains(x: number, y: number): boolean;
+    override contains(x: number, y: number): boolean;
 
     /**
      * Constrain polygon points by applying boundary shapes.
@@ -121,23 +120,11 @@ declare global {
      *          * all: returns a sorted array of PolygonVertex instances
      *          * closest: returns a PolygonVertex instance or null
      */
-    static testCollision<Mode extends PointSourcePolygon.CollisionModes>(
+    static testCollision<Mode extends PointSourcePolygon.CollisionModes | undefined = undefined>(
       origin: Canvas.Point,
       destination: Canvas.Point,
-      {
-        mode,
-        ...config
-      }: {
-        /**
-         * The collision mode to test: "any", "all", or "closest"
-         * (default: "all")
-         */
-        mode?: Mode;
-
-        /** The configuration that defines a certain Polygon type */
-        config?: PointSourcePolygonConfig;
-      },
-    ): PointSourcePolygon.TestCollision<Mode>;
+      { mode, ...config }: PointSourcePolygon.TestCollisionConfig<Mode>,
+    ): PointSourcePolygon.TestCollision<Coalesce<Mode, "all">>;
 
     /**
      * Determine the set of collisions which occurs for a Ray.
@@ -166,8 +153,9 @@ declare global {
      * Augment a PointSourcePolygon by adding additional coverage for shapes permitted by threshold walls.
      * @param polygon - The computed polygon
      * @returns The augmented polygon
+     * @remarks Mutates and returns the same reference it's passed, not a new polygon
      */
-    static applyThresholdAttenuation(polygon: PointSourcePolygon): PointSourcePolygon;
+    static applyThresholdAttenuation<PolyType extends PointSourcePolygon>(polygon: PolyType): PolyType;
 
     /**
      * @deprecated since v11, will be removed in v13
@@ -180,22 +168,109 @@ declare global {
   }
 
   namespace PointSourcePolygon {
+    interface Any extends AnyPointSourcePolygon {}
+    type AnyConstructor = typeof AnyPointSourcePolygon;
+
+    type WALL_DIRECTION_MODES = Brand<number, "PointSourcePolygon.WALL_DIRECTION_MODES">;
+
+    interface WallDirectionModes {
+      readonly NORMAL: 0 & WALL_DIRECTION_MODES;
+      readonly REVERSED: 1 & WALL_DIRECTION_MODES;
+      readonly BOTH: 2 & WALL_DIRECTION_MODES;
+    }
+
     /** @internal */
-    type _Config = InexactPartial<{
-      /** The angle of emission, if limited */
-      angle: number;
+    type _TestCollisionConfig<Mode> = InexactPartial<{
+      /**
+       * The collision mode to test: "any", "all", or "closest"
+       * @defaultValue `"all"`
+       * @remarks Can't be `null` as it only has a parameter default
+       */
+      mode: Mode;
+    }>;
 
-      /** The desired density of padding rays, a number per PI */
-      density: number;
+    interface TestCollisionConfig<Mode> extends _TestCollisionConfig<Mode>, Config {}
+
+    /**
+     * @internal
+     * @privateRemarks Properties of the config that get set in `#initialize` or elsewhere with no respect to their passed value
+     */
+    interface _ComputedConfig {
+      /**
+       * Does this polygon have a limited radius?
+       * @remarks `true` if `(cfg.radius > 0) && (cfg.radius < canvas.dimensions.maxR)`
+       */
+      hasLimitedRadius: boolean;
+
+      /**
+       * Does this polygon have a limited angle?
+       * @remarks `true` if `cfg.angle !== 360`
+       */
+      hasLimitedAngle: boolean;
+    }
+
+    /**
+     * @internal
+     * @privateRemarks Properties of the config that might be omitted but can't be explicitly `undefined`
+     */
+    interface _OptionalOnlyConfig {
+      /**
+       * The object (if any) that spawned this polygon.
+       * @remarks Not guaranteed by `PointSourcePolygon#initalize` but will exist in all configs created by `PointEffectSourceMixin` subclasses. No default provided
+       * @privateRemarks Foundry types this as `PointSource` which is neither a typedef nor a class, not even a mixin class name. The type here matches usage and tracks with what they probably meant.
+       */
+      source?: PointEffectSourceMixin.AnyMixed;
+
+      /**
+       * The external radius of the source
+       * @remarks Can't be `undefined` or `null` or its use in math would produce `NaN`s.
+       *
+       * Not guaranteed by `PointSourcePolygon#initalize` but will exist in all configs created by `PointEffectSourceMixin` subclasses.
+       */
+      externalRadius?: number;
+    }
 
-      /** A limited radius of the resulting polygon */
+    /**
+     * @internal
+     * @privateRemarks Properties of the config that have defaults for nullish values in `#initialize`, and thus are guaranteed in the stored config
+     */
+    interface _BaseConfig {
+      /**
+       * A limited radius of the resulting polygon
+       * @defaultValue `canvas.dimensions.maxR`
+       */
       radius: number;
 
-      /** The direction of facing, required if the angle is limited */
+      /**
+       * The desired density of padding rays, a number per PI
+       * @defaultValue `PIXI.Circle.approximateVertexDensity(cfg.radius)`
+       */
+      density: number;
+
+      /**
+       * The angle of emission, if limited
+       * @defaultValue `360`
+       */
+      angle: number;
+
+      /**
+       * The direction of facing, required if the angle is limited
+       * @defaultValue `0`
+       */
       rotation: number;
 
-      /** Customize how wall direction of one-way walls is applied */
-      wallDirectionMode: number;
+      /**
+       * Does this polygon use the Scene inner or outer bounding rectangle
+       * @defaultValue `true` if `type === "sight"` and the origin point is inside `canvas.dimensions.sceneRect` else `false`
+       * @remarks Computed if not provided or passed nullish.
+       */
+      useInnerBounds: boolean;
+
+      /**
+       * Customize how wall direction of one-way walls is applied
+       * @defaultValue `PointSourcePolygon.WALL_DIRECTION_MODES.NORMAL`
+       */
+      wallDirectionMode: PointSourcePolygon.WALL_DIRECTION_MODES;
 
       /**
        * Compute the polygon with threshold wall constraints applied
@@ -209,41 +284,56 @@ declare global {
        */
       includeDarkness: boolean;
 
-      /** Priority when it comes to ignore edges from darkness sources */
-      priority: number;
-
-      /** Display debugging visualization and logging for the polygon */
-      debug: boolean;
+      /**
+       * Limiting polygon boundary shapes
+       * @defaultValue `[]`
+       * @remarks Never passed in Foundry practice
+       */
+      boundaryShapes: Array<BoundaryShapes>;
 
-      /** The object (if any) that spawned this polygon. */
-      source: PointEffectSourceMixin.AnyMixed;
+      /**
+       * Display debugging visualization and logging for the polygon
+       * @remarks Overriden `true` if `CONFIG.debug.polygons` is truthy
+       */
+      debug?: boolean;
 
-      /** Limiting polygon boundary shapes */
-      boundaryShapes: Array<PIXI.Rectangle | PIXI.Circle | PIXI.Polygon>;
+      /**
+       * Priority when it comes to ignore edges from darkness sources
+       * @remarks This is listed in the typedef, but is not in use by Foundry in 12.331
+       */
+      priority?: number;
+    }
 
-      /** Does this polygon use the Scene inner or outer bounding rectangle */
-      readonly useInnerBounds: boolean;
+    /**
+     * @internal
+     * @privateRemarks The only property required in all configs
+     */
+    interface _RequiredConfig {
+      /** The type of polygon being computed */
+      type: PolygonType;
+    }
 
-      /** Does this polygon have a limited radius? */
-      readonly hasLimitedRadius: boolean;
+    interface StoredConfig extends _RequiredConfig, _BaseConfig, _OptionalOnlyConfig, _ComputedConfig {}
 
-      /** Does this polygon have a limited angle? */
-      readonly hasLimitedAngle: boolean;
+    interface Config extends _RequiredConfig, NullishProps<_BaseConfig>, _OptionalOnlyConfig {}
 
-      /** The computed bounding box for the polygon */
-      readonly boundingBox: PIXI.Rectangle;
-    }>;
+    type BoundaryShapes = PIXI.Rectangle | PIXI.Circle | PIXI.Polygon;
 
     type PolygonType = "light" | "sight" | "sound" | "move" | "universal";
 
     type CollisionModes = "any" | "all" | "closest";
 
-    interface CollisionTypes {
+    /** @internal */
+    interface _CollisionTypesReturnMap {
       any: boolean;
-      closest: foundry.canvas.edges.PolygonVertex;
-      all: foundry.canvas.edges.PolygonVertex[] | null;
+      closest: foundry.canvas.edges.PolygonVertex | null;
+      all: foundry.canvas.edges.PolygonVertex[];
     }
 
-    type TestCollision<Mode extends CollisionModes> = CollisionTypes[Mode];
+    type TestCollision<Mode extends CollisionModes> = _CollisionTypesReturnMap[Mode];
   }
 }
+
+declare abstract class AnyPointSourcePolygon extends PointSourcePolygon {
+  constructor(arg0: never, ...args: never[]);
+}