@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.345.1-beta.20250704.94554

package/src/foundry/common/grid/base.d.mts

@@ -1,4 +1,8 @@
-import type { AnyObject, InexactPartial } from "fvtt-types/utils";
+import type { AnyObject, EmptyObject, InexactPartial, Identity } from "#utils";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { GridHighlight } from "#client/canvas/containers/_module.mjs";
+import type { Ray } from "#client/canvas/geometry/_module.d.mts";
+import type { Token } from "#client/canvas/placeables/_module.d.mts";
 
 /**
  * The base grid class.
@@ -26,7 +30,7 @@ declare abstract class BaseGrid {
   alpha: number;
 
   /**
-   * The grid type (see {@link CONST.GRID_TYPES}).
+   * The grid type (see {@linkcode CONST.GRID_TYPES}).
    */
   type: CONST.GRID_TYPES;
 
@@ -93,7 +97,7 @@ declare abstract class BaseGrid {
    * In square grids with illegal diagonals the offset of the given coordinates is returned
    * if the direction is diagonal.
    * @param coords    - The coordinates
-   * @param direction - The direction (see {@link CONST.MOVEMENT_DIRECTIONS})
+   * @param direction - The direction (see {@linkcode CONST.MOVEMENT_DIRECTIONS})
    * @returns The offset
    */
   abstract getShiftedOffset(coords: BaseGrid.Coordinates, direction: number): BaseGrid.Offset;
@@ -104,7 +108,7 @@ declare abstract class BaseGrid {
    * In square grids with illegal diagonals the point is not shifted if the direction is diagonal.
    * In gridless grids the point coordinates are shifted by the grid size.
    * @param point     - The point that is to be shifted
-   * @param direction - The direction (see {@link CONST.MOVEMENT_DIRECTIONS})
+   * @param direction - The direction (see {@linkcode CONST.MOVEMENT_DIRECTIONS})
    * @returns The shifted point
    */
   abstract getShiftedPoint(point: Canvas.Point, direction: number): Canvas.Point;
@@ -129,7 +133,7 @@ declare abstract class BaseGrid {
 
   /**
    * Returns the points of the grid space shape relative to the center point.
-   * The points are returned in the same order as in {@link BaseGrid#getVertices}.
+   * The points are returned in the same order as in {@link BaseGrid.getVertices | `BaseGrid#getVertices`}.
    * In gridless grids an empty array is returned.
    * @returns The points of the polygon
    */
@@ -167,13 +171,13 @@ declare abstract class BaseGrid {
        * The function that returns the cost for a given move between
        * grid spaces (default is the distance traveled along the direct path)
        */
-      cost: BaseGrid.MeasurePathCostFunction;
+      cost: BaseGrid.MeasurePathCostFunction2D | BaseGrid.MeasurePathCostFunction3D;
     }>,
   ): BaseGrid.MeasurePathResult;
 
   /**
    * Measures the path and writes the measurements into `result`.
-   * Called by {@link BaseGrid#measurePath}.
+   * Called by {@link BaseGrid.measurePath | `BaseGrid#getDirectPath`}.
    * @param waypoints - The waypoints the path must pass through
    * @param options   - Additional measurement options
    * @param result    - The measurement result that the measurements need to be written to
@@ -185,7 +189,7 @@ declare abstract class BaseGrid {
        * The function that returns the cost for a given move between
        * grid spaces (default is the distance traveled along the direct path)
        */
-      cost: BaseGrid.MeasurePathCostFunction;
+      cost: BaseGrid.MeasurePathCostFunction2D | BaseGrid.MeasurePathCostFunction3D;
     }>,
     result: BaseGrid.MeasurePathResult,
   ): void;
@@ -249,7 +253,7 @@ declare abstract class BaseGrid {
    * @param size     - The grid size.
    * @param padding  - The percentage of padding.
    * @param options  - Options to configure the padding calculation.
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#calculateDimensions} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.calculateDimensions | `BaseGrid#calculateDimensions`} instead.
    */
   static calculatePadding(
     gridType: foundry.CONST.GRID_TYPES,
@@ -266,29 +270,29 @@ declare abstract class BaseGrid {
   ): { width: number; height: number; x: number; y: number };
 
   /**
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#sizeX} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.sizeX | `BaseGrid#sizeX`} instead.
    */
   get w(): number;
 
   /**
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#sizeX} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.sizeX | `BaseGrid#sizeX`} instead.
    */
   set w(value: number);
 
   /**
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#sizeY} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.sizeY | `BaseGrid#sizeY`} instead.
    */
   get h(): number;
 
   /**
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#sizeY} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.sizeY | `BaseGrid#sizeY`} instead.
    */
   set h(value: number);
 
   /**
    * Given a pair of coordinates (x, y) - return the top-left of the grid square which contains that point
    * @returns An Array [x, y] of the top-left coordinate of the square which contains (x, y)
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#getTopLeftPoint} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.getTopLeftPoint | `BaseGrid#getTopLeftPoint`} instead.
    */
   getTopLeft(x: number, y: number): Canvas.PointTuple;
 
@@ -297,7 +301,7 @@ declare abstract class BaseGrid {
    * @param x - The x-coordinate
    * @param y - The y-coordinate
    * @returns An array [cx, cy] of the central point of the grid space which contains (x, y)
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#getCenterPoint} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.getCenterPoint | `BaseGrid#getCenterPoint`} instead.
    */
   getCenter(x: number, y: number): Canvas.PointTuple;
 
@@ -306,7 +310,7 @@ declare abstract class BaseGrid {
    * @param row - The grid row coordinate against which to test for neighbors
    * @param col - The grid column coordinate against which to test for neighbors
    * @returns An array of grid positions which are neighbors of the row and column
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#getAdjacentOffsets} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.getAdjacentOffsets | `BaseGrid#getAdjacentOffsets`} instead.
    */
   getNeighbors(row: number, col: number): Canvas.PointTuple[];
 
@@ -316,7 +320,7 @@ declare abstract class BaseGrid {
    * @param x - The x-coordinate pixel position
    * @param y - The y-coordinate pixel position
    * @returns An array representing the position in grid units
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#getOffset} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.getOffset | `BaseGrid#getOffset`} instead.
    */
   getGridPositionFromPixels(x: number, y: number): Canvas.PointTuple;
 
@@ -328,7 +332,7 @@ declare abstract class BaseGrid {
    * @param x - The x-coordinate grid position
    * @param y - The y-coordinate grid position
    * @returns An array representing the position in pixels
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#getTopLeftPoint} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.getTopLeftPoint | `BaseGrid#getTopLeftPoint`} instead.
    */
   getPixelsFromGridPosition(x: number, y: number): Canvas.PointTuple;
 
@@ -341,7 +345,7 @@ declare abstract class BaseGrid {
    * @param dx - The number of grid positions to shift horizontally
    * @param dy - The number of grid positions to shift vertically
    * @param options - Additional options to configure shift behavior.
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#getShiftedPoint} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.getShiftedPoint | `BaseGrid#getShiftedPoint`} instead.
    */
   shiftPosition(
     x: number,
@@ -352,7 +356,7 @@ declare abstract class BaseGrid {
       /**
        * The token that is being shifted.
        */
-      token: Token;
+      token: Token.Implementation;
     }>,
   ): Canvas.PointTuple;
 
@@ -364,10 +368,18 @@ declare abstract class BaseGrid {
    * @param options  - Additional options which modify the measurement
    *                   (default: `{}`)
    * @returns An Array of distance measurements for each segment
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#measurePath} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.measurePath | `BaseGrid#measurePath`} instead.
    */
-  // eslint-disable-next-line @typescript-eslint/no-deprecated
-  measureDistances(segments: GridLayer.Segment[], options?: GridLayer.MeasureDistancesOptions): number[];
+  measureDistances(
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    segments: BaseGrid.Segment[],
+
+    /**
+     * @defaultValue `{}`
+     * @remarks Unused
+     */
+    options?: EmptyObject,
+  ): number[];
 
   /* -------------------------------------------- */
 
@@ -384,17 +396,19 @@ declare abstract class BaseGrid {
    *                   (default: `null`)
    * @param options  - Additional options to configure snapping behavior.
    * @returns An object containing the coordinates of the snapped location
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#getSnappedPoint} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.getSnappedPoint | `BaseGrid#getSnappedPoint`} instead.
    */
   getSnappedPosition(
     x: number,
     y: number,
     interval?: number | null,
-    options?: InexactPartial<{
-      /** The token that is being moved. */
-      token: Token;
-    }>,
-  ): { x: number; y: number };
+
+    /**
+     * @defaultValue `{}`
+     * @remarks Unused
+     */
+    options?: EmptyObject,
+  ): PIXI.IPointData;
 
   /* -------------------------------------------- */
 
@@ -402,35 +416,35 @@ declare abstract class BaseGrid {
    * Highlight a grid position for a certain coordinates
    * @param layer   - The highlight layer to use
    * @param options - Additional options to configure behavior.
-   * @deprecated Since v12 until v14. Use {@link GridLayer#highlightPosition} instead.
+   * @deprecated Since v12 until v14. Use {@link GridLayer.highlightPosition | `GridLayer#highlightPosition`} instead.
    */
   highlightGridPosition(layer: GridHighlight, options?: AnyObject): void;
 
   /* -------------------------------------------- */
 
   /**
-   * @deprecated Since v12 until v14. Use {@link Canvas#grid} instead.
+   * @deprecated Since v12 until v14. Use {@link Canvas.grid | `Canvas#grid`} instead.
    */
   get grid(): BaseGrid;
 
   /* -------------------------------------------- */
 
   /**
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#testAdjacency} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.testAdjacency | `BaseGrid#testAdjacency`} instead.
    */
   isNeighbor(r0: number, c0: number, r1: number, c1: number): boolean;
 
   /* -------------------------------------------- */
 
   /**
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#isHexagonal} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.isHexagonal | `BaseGrid#isHexagonal`} instead.
    */
   get isHex(): boolean;
 
   /* -------------------------------------------- */
 
   /**
-   * @deprecated Since v12 until v14. Use {@link BaseGrid#measurePath} instead.
+   * @deprecated Since v12 until v14. Use {@link BaseGrid.measurePath | `BaseGrid#measurePath`} instead.
    */
   measureDistance(origin: Canvas.Point, target: Canvas.Point, options: AnyObject): number[];
 
@@ -485,6 +499,9 @@ declare abstract class BaseGrid {
 }
 
 declare namespace BaseGrid {
+  interface Any extends AnyBaseGrid {}
+  interface AnyConstructor extends Identity<typeof AnyBaseGrid> {}
+
   interface Configuration {
     /** The size of a grid space in pixels (a positive number) */
     size: number;
@@ -526,20 +543,39 @@ declare namespace BaseGrid {
     thickness?: number | undefined;
   }
 
-  interface Offset {
-    /** The row coordinate */
+  type Offset = Offset2D | Offset3D;
+
+  /**
+   * 2D offset coordinates of a grid space.
+   */
+  interface Offset2D {
+    /** The row coordinate (an integer) */
     i: number;
 
-    /** The column coordinate */
+    /** The column coordinate (an integer) */
     j: number;
   }
 
+  /**
+   * 3D offset coordinates of a grid space.
+   */
+  interface Offset3D extends Offset2D {
+    /**
+     * The vertical coordinate (an integer)
+     */
+    k: number;
+  }
+
   type OffsetRange = [i0: number, j0: number, i1: number, j1: number];
 
-  type Coordinates = Offset | Canvas.Point;
+  type Coordinates = Coordinates2D | Coordinates3D;
+
+  type Coordinates2D = Offset2D | Canvas.Point;
+
+  type Coordinates3D = Offset3D | Canvas.ElevatedPoint;
 
   interface SnappingBehavior {
-    /** The snapping mode (a union of {@link CONST.GRID_SNAPPING_MODES}) */
+    /** The snapping mode (a union of {@linkcode CONST.GRID_SNAPPING_MODES}) */
     mode: number;
 
     /**
@@ -549,7 +585,40 @@ declare namespace BaseGrid {
     resolution?: number | undefined;
   }
 
-  type MeasurePathWaypoint = Coordinates | (Configuration & { teleport: boolean });
+  interface _MeasurePathWaypointData {
+    /**
+     * Teleport to this waypoint?
+     * @defaultValue `false`
+     */
+    teleport?: boolean;
+
+    /**
+     * Measure of the segment from the previous to this waypoint? The distance, cost, spaces,
+     * diagonals, and Euclidean length of a segment that is not measured are always 0.
+     * @defaultValue `true`
+     */
+    measure?: boolean;
+  }
+
+  interface MeasurePathWaypointData2D extends _MeasurePathWaypointData {
+    /**
+     * A predetermined cost (nonnegative) or a cost function to be used instead of `options.cost`.
+     */
+    cost?: number | MeasurePathCostFunction2D;
+  }
+
+  interface MeasurePathWaypointData3D extends _MeasurePathWaypointData {
+    /**
+     * A predetermined cost (nonnegative) or a cost function to be used instead of `options.cost`.
+     */
+    cost?: number | MeasurePathCostFunction3D;
+  }
+
+  type MeasurePathWaypoint2D = InexactPartial<Coordinates2D & MeasurePathWaypointData2D>;
+
+  type MeasurePathWaypoint3D = InexactPartial<Coordinates3D & MeasurePathWaypointData3D>;
+
+  type MeasurePathWaypoint = MeasurePathWaypoint2D | MeasurePathWaypoint3D;
 
   /** The measurements of a waypoint. */
   interface MeasurePathResultWaypoint {
@@ -565,7 +634,7 @@ declare namespace BaseGrid {
     /** The total number of spaces moved along a direct path up to this waypoint. */
     spaces: number;
 
-    /** The total cost of the direct path ({@link BaseGrid#getDirectPath}) up to this waypoint. */
+    /** The total cost of the direct path ({@link BaseGrid.getDirectPath | `BaseGrid#getDirectPath`}) up to this waypoint. */
     cost: number;
   }
 
@@ -586,11 +655,11 @@ declare namespace BaseGrid {
     /** The number of spaces moved along this segment. */
     spaces: number;
 
-    /** The cost of the direct path ({@link BaseGrid#getDirectPath}) between the two waypoints. */
+    /** The cost of the direct path ({@link BaseGrid.getDirectPath | `BaseGrid#getDirectPath`}) between the two waypoints. */
     cost: number;
   }
 
-  /** The measurements result of {@link BaseGrid#measurePath}. */
+  /** The measurements result of {@link BaseGrid.measurePath | `BaseGrid#measurePath`}. */
   interface MeasurePathResult {
     /** The measurements at each waypoint. */
     waypoints: MeasurePathResultWaypoint[];
@@ -608,20 +677,50 @@ declare namespace BaseGrid {
      */
     spaces: number;
 
-    /** The total cost of the direct path ({@link BaseGrid#getDirectPath}) through all waypoints. */
+    /** The total cost of the direct path ({@link BaseGrid.getDirectPath | `BaseGrid#getDirectPath`}) through all waypoints. */
     cost: number;
   }
 
   /**
-   * A function that returns the cost for a given move between grid spaces.
-   * In square and hexagonal grids the grid spaces are always adjacent unless teleported.
-   * The distance is 0 if and only if teleported. The function is never called with the same offsets.
-   * @param from     - The offset that is moved from.
-   * @param to       - The offset that is moved to.
-   * @param distance - The distance between the grid spaces, or 0 if teleported.
-   * @returns The cost of the move between the grid spaces.
+   * @deprecated in favor of {@linkcode MeasurePathCostFunction2D}
    */
-  type MeasurePathCostFunction = (from: Offset, to: Offset, distance: number) => number;
+  type MeasurePathCostFunction = MeasurePathCostFunction2D;
+
+  /**
+   * A function that returns the cost for a given move between grid spaces in 2D.
+   * In square and hexagonal grids the grid spaces are always adjacent unless teleported.
+   * The function is never called with the same offsets.
+   * @param from     - The offset that is moved from
+   * @param to       - The offset that is moved to
+   * @param distance - The distance between the grid spaces
+   * @param segment  - The properties of the segment
+   * @returns The cost of the move between the grid spaces (nonnegative)
+   * @remarks foundry marks `from`, `to`, and `segment` as readonly
+   */
+  type MeasurePathCostFunction2D = (
+    from: Offset2D,
+    to: Offset2D,
+    distance: number,
+    segment: foundry.grid.BaseGrid.MeasurePathWaypoint2D,
+  ) => number;
+
+  /**
+   * A function that returns the cost for a given move between grid spaces in 3D.
+   * In square and hexagonal grids the grid spaces are always adjacent unless teleported.
+   * The function is never called with the same offsets.
+   * @param from     - The offset that is moved from
+   * @param to       - The offset that is moved to
+   * @param distance - The distance between the grid spaces
+   * @param segment  - The properties of the segment
+   * @returns The cost of the move between the grid spaces (nonnegative)
+   * @remarks foundry marks `from`, `to`, and `segment` as readonly
+   */
+  type MeasurePathCostFunction3D = (
+    from: Offset3D,
+    to: Offset3D,
+    distance: number,
+    segment: foundry.grid.BaseGrid.MeasurePathWaypoint3D,
+  ) => number;
 
   interface Dimensions {
     width: number;
@@ -631,6 +730,17 @@ declare namespace BaseGrid {
     rows: number;
     columns: number;
   }
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   */
+  interface Segment {
+    ray: Ray;
+  }
+}
+
+declare abstract class AnyBaseGrid extends BaseGrid {
+  constructor(...args: never);
 }
 
 export default BaseGrid;

package/src/foundry/common/grid/grid-hex.d.mts

@@ -1,4 +1,5 @@
 import type HexagonalGrid from "./hexagonal.mjs";
+import type { Canvas } from "#client/canvas/_module.d.mts";
 
 /**
  * A helper class which represents a single hexagon as part of a HexagonalGrid.

package/src/foundry/common/grid/gridless.d.mts

@@ -1,6 +1,7 @@
 import type BaseGrid from "./base.d.mts";
+import type { Canvas } from "#client/canvas/_module.d.mts";
 
-import type { InexactPartial } from "fvtt-types/utils";
+import type { InexactPartial } from "#utils";
 
 declare class Gridless extends BaseGrid {
   override type: typeof CONST.GRID_TYPES.GRIDLESS;
@@ -47,7 +48,7 @@ declare class Gridless extends BaseGrid {
 declare namespace Gridless {
   interface Configuration extends BaseGrid.Configuration {}
 
-  interface Offset extends BaseGrid.Offset {}
+  type Offset = BaseGrid.Offset;
 
   interface OffsetRange extends BaseGrid.OffsetRange {}
 
@@ -63,7 +64,7 @@ declare namespace Gridless {
 
   interface MeasurePathResult extends BaseGrid.MeasurePathResult {}
 
-  type MeasurePathCostFunction = BaseGrid.MeasurePathCostFunction;
+  type MeasurePathCostFunction = BaseGrid.MeasurePathCostFunction2D | BaseGrid.MeasurePathCostFunction3D;
 
   interface Dimensions extends BaseGrid.Dimensions {}
 }