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

package/src/foundry/client/canvas/interaction/ruler/ruler.d.mts

@@ -0,0 +1,498 @@
+import type { Brand, FixedInstanceType, Identity, IntentionalPartial, NullishProps } from "#utils";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { GridHighlight, PreciseText } 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 Ruler - used to measure distances and trigger movements
+ */
+declare class Ruler extends PIXI.Container {
+  /**
+   * @param user    - The User for whom to construct the Ruler instance
+   *                  (default: `game.user`)
+   * @param options - Additional options
+   */
+  constructor(user?: User.Implementation, options?: Ruler.ConstructorOptions);
+
+  /**
+   * Record the User which this Ruler references
+   * @defaultValue `game.user`
+   */
+  user: User.Implementation;
+
+  /**
+   * The ruler name - used to differentiate between players
+   * @defaultValue `"Ruler." + user.id`
+   */
+  name: string;
+
+  /**
+   * The ruler color - by default the color of the active user
+   * @defaultValue `this.user.color`
+   */
+  color: Color;
+
+  /**
+   * The Ruler element is a Graphics instance which draws the line and points of the measured path
+   */
+  ruler: PIXI.Graphics;
+
+  /**
+   * The Labels element is a Container of Text elements which label the measured path
+   */
+  labels: PIXI.Container;
+
+  /**
+   * The possible Ruler measurement states.
+   */
+  static get STATES(): Ruler.States;
+
+  /**
+   * Is the ruler ready for measure?
+   */
+  static get canMeasure(): boolean;
+
+  /**
+   * The current destination point at the end of the measurement
+   * @defaultValue `null`
+   */
+  destination: Canvas.Point | null;
+
+  /**
+   * The origin point of the measurement, which is the first waypoint.
+   * @defaultValue `null`
+   */
+  get origin(): Canvas.Point | null;
+
+  /**
+   * This Array tracks individual waypoints along the ruler's measured path.
+   * The first waypoint is always the origin of the route.
+   * @defaultValue `[]`
+   */
+  waypoints: Canvas.Point[];
+
+  /**
+   * The array of most recently computed ruler measurement segments
+   * @defaultValue `[]`
+   */
+  segments: Ruler.MeasurementSegment[];
+
+  /**
+   * The measurement history.
+   */
+  get history(): Ruler.MeasurementHistory;
+
+  /**
+   * The computed total distance of the Ruler.
+   * @defaultValue `0`
+   */
+  totalDistance: number;
+
+  /**
+   * The computed total cost of the Ruler.
+   * @defaultValue `0`
+   */
+  totalCost: number;
+
+  /**
+   * The current state of the Ruler (one of {@linkcode Ruler.States}).
+   */
+  get state(): Ruler.STATES;
+
+  /**
+   * The current state of the Ruler (one of {@linkcode Ruler.States}).
+   * @defaultValue `Ruler.STATES.INACTIVE`
+   */
+  protected _state: Ruler.STATES;
+
+  /**
+   * Is the Ruler being actively used to measure distance?
+   */
+  get active(): boolean;
+
+  /**
+   * Get a GridHighlight layer for this Ruler
+   */
+  get highlightLayer(): GridHighlight;
+
+  /**
+   * The Token that is moved by the Ruler.
+   */
+  get token(): Token.Implementation | null;
+
+  /**
+   * Clear display of the current Ruler
+   */
+  clear(): void;
+
+  /**
+   * Measure the distance between two points and render the ruler UI to illustrate it
+   * @param destination - The destination point to which to measure
+   * @param options     - Additional options
+   * @returns The array of measured segments if measured
+   */
+  measure(
+    destination: Canvas.Point,
+    options?: Ruler.MeasureOptions, // not:null (destructured)
+  ): Ruler.MeasurementSegment[] | void;
+
+  /**
+   * Get the measurement origin.
+   * @param point   - The waypoint
+   * @param options - Additional options
+   */
+  protected _getMeasurementOrigin(
+    point: Canvas.Point,
+    options?: Ruler.GetMeasurementOriginOptions, // not:null (destructured)
+  ): Canvas.Point;
+
+  /**
+   * While measurement is in progress, update the destination to be the central point of the target grid space.
+   * @param point   - The point coordinates
+   * @param options - Additional options
+   * @returns The snapped destination point
+   */
+  protected _getMeasurementDestination(
+    point: Canvas.Point,
+    options?: Ruler.GetMeasurementDestinationOptions, // not:null (destructured)
+  ): Canvas.Point;
+
+  /**
+   * Translate the waypoints and destination point of the Ruler into an array of Ray segments.
+   * @returns The segments of the measured path
+   */
+  protected _getMeasurementSegments(): Ruler.MeasurementSegment[];
+
+  /**
+   * Handle the start of a Ruler measurement workflow
+   * @param origin  - The origin
+   * @param options - Additional options
+   */
+  protected _startMeasurement(
+    origin: Canvas.Point,
+    options?: Ruler.StartMeasurementOptions, // not:null (destructured)
+  ): void;
+
+  /**
+   * Handle the conclusion of a Ruler measurement workflow
+   */
+  protected _endMeasurement(): void;
+
+  /**
+   * Handle the addition of a new waypoint in the Ruler measurement path
+   * @param point   - The waypoint
+   * @param options - Additional options
+   */
+  protected _addWaypoint(
+    point: Canvas.Point,
+    options?: Ruler.AddWaypointOptions, // not:null (destructured)
+  ): void;
+
+  /**
+   * Handle the removal of a waypoint in the Ruler measurement path
+   */
+  protected _removeWaypoint(): void;
+
+  /**
+   * Get the cost function to be used for Ruler measurements.
+   * @remarks Just a stub in v12.331
+   */
+  protected _getCostFunction(): foundry.grid.BaseGrid.MeasurePathCostFunction2D | void;
+
+  /**
+   * Compute the distance of each segment and the total distance of the measured path.
+   */
+  protected _computeDistance(): void;
+
+  /**
+   * Get the text label for a segment of the measured path
+   */
+  protected _getSegmentLabel(segment: Ruler.PartialSegmentForLabelling): string;
+
+  /**
+   * Draw each segment of the measured path.
+   */
+  protected _drawMeasuredPath(): void;
+
+  /**
+   * Highlight the measurement required to complete the move in the minimum number of discrete spaces
+   */
+  protected _highlightMeasurementSegment(segment: Ruler.PartialSegmentForHighlighting): void;
+
+  /**
+   * Determine whether a SPACE keypress event entails a legal token movement along a measured ruler
+   *
+   * @returns An indicator for whether a token was successfully moved or not. If True the event should be
+   *          prevented from propagating further, if False it should move on to other handlers.
+   */
+  moveToken(): Promise<boolean>;
+
+  /**
+   * Acquire a Token, if any, which is eligible to perform a movement based on the starting point of the Ruler
+   * @param origin - The origin of the Ruler
+   * @returns The Token that is to be moved, if any
+   *
+   */
+  protected _getMovementToken(origin: Canvas.Point): Token.Implementation | null;
+
+  /**
+   * Get the current measurement history.
+   * @returns The current measurement history, if any
+   * @remarks Just a stub in v12.331
+   */
+  protected _getMeasurementHistory(): Ruler.MeasurementHistory | void;
+
+  /**
+   * Create the next measurement history from the current history and current Ruler state.
+   * @returns The next measurement history
+   */
+  protected _createMeasurementHistory(): Ruler.MeasurementHistory;
+
+  /**
+   * Test whether a Token is allowed to execute a measured movement path.
+   * @param token - The Token being tested
+   * @returns Whether the movement is allowed
+   * @throws  A specific Error message used instead of returning false
+   */
+  protected _canMove(token: Token.Implementation): boolean;
+
+  /**
+   * Animate piecewise Token movement along the measured segment path.
+   * @param token - The Token being animated
+   * @returns A Promise which resolves once all animation is completed
+   */
+  protected _animateMovement(token: Token.Implementation): Promise<void>;
+
+  /**
+   * Update Token position and configure its animation properties for the next leg of its animation.
+   * @param token         - The Token being updated
+   * @param segment       - The measured segment being moved
+   * @param destination   - The adjusted destination coordinate
+   * @param updateOptions - Additional options to configure the `TokenDocument` update
+   * @returns A Promise that resolves once the animation for this segment is done
+   */
+  protected _animateSegment(
+    token: Token.Implementation,
+    segment: Ruler.PartialSegmentForAnimating,
+    destination: Canvas.Point,
+    updateOptions?: Ruler.PartialTokenUpdateOptions, // not:null (used as first param in mergeObject)
+  ): Promise<void>;
+
+  /**
+   * An method which can be extended by a subclass of Ruler to define custom behaviors before a confirmed movement.
+   * @param token - The Token that will be moving
+   */
+  protected _preMove(token: Token.Implementation): Promise<void>;
+
+  /**
+   * An event which can be extended by a subclass of Ruler to define custom behaviors before a confirmed movement.
+   * @param token - The Token that finished moving
+   */
+  protected _postMove(token: Token.Implementation): Promise<void>;
+
+  /**
+   * Broadcast Ruler measurement if its User is the connected client.
+   * The broadcast is throttled to 100ms.
+   */
+  protected _broadcastMeasurement(): void;
+
+  /**
+   * Package Ruler data to an object which can be serialized to a string.
+   */
+  protected _getMeasurementData(): Ruler.MeasurementData;
+
+  /**
+   * Update a Ruler instance using data provided through the cursor activity socket
+   * @param data - Ruler data with which to update the display
+   */
+  update(data?: Ruler.MeasurementData | null): void;
+
+  /**
+   * Handle the beginning of a new Ruler measurement workflow
+   * @param event - The drag start event
+   * @see {@linkcode Canvas.#onDragLeftStart}
+   */
+  protected _onDragStart(event: Canvas.Event.Pointer): void;
+
+  /**
+   * Handle left-click events on the Canvas during Ruler measurement.
+   * @param event - The pointer-down event
+   * @see {@linkcode Canvas._onClickLeft}
+   */
+  protected _onClickLeft(event: Canvas.Event.Pointer): void;
+
+  /**
+   * Handle right-click events on the Canvas during Ruler measurement.
+   * @param event - The pointer-down event
+   * @see {@linkcode Canvas._onClickRight}
+   */
+  protected _onClickRight(event: Canvas.Event.Pointer): void;
+
+  /**
+   * Continue a Ruler measurement workflow for left-mouse movements on the Canvas.
+   * @param event - The mouse move event
+   * @see {@linkcode Canvas.#onDragLeftMove}
+   */
+  protected _onMouseMove(event: Canvas.Event.Pointer): void;
+
+  /**
+   * Conclude a Ruler measurement workflow by releasing the left-mouse button.
+   * @param event - The pointer-up event
+   * @see {@linkcode Canvas.#onDragLeftDrop}
+   */
+  protected _onMouseUp(event: Canvas.Event.Pointer): void;
+}
+
+declare namespace Ruler {
+  interface Any extends AnyRuler {}
+  interface AnyConstructor extends Identity<typeof AnyRuler> {}
+
+  type ConfiguredClass = CONFIG["Canvas"]["rulerClass"];
+  type ConfiguredInstance = FixedInstanceType<ConfiguredClass>;
+
+  /** @internal */
+  type _ConstructorOptions = NullishProps<{
+    /**
+     * The color of the ruler (defaults to the color of the User)
+     * @defaultValue `this.user.color`
+     */
+    color?: number;
+  }>;
+
+  interface ConstructorOptions extends _ConstructorOptions {}
+
+  type STATES = Brand<number, "Ruler.STATES">;
+
+  interface States {
+    readonly INACTIVE: 0 & STATES;
+    readonly STARTING: 1 & STATES;
+    readonly MEASURING: 2 & STATES;
+    readonly MOVING: 3 & STATES;
+  }
+
+  interface MeasurementSegment {
+    /** The Ray which represents the point-to-point line segment */
+    ray: Ray;
+
+    teleport: boolean;
+
+    /** The text object used to display a label for this segment */
+    label: PreciseText;
+
+    /** The measured distance of the segment */
+    distance: number;
+
+    /** The measured cost of the segment */
+    cost: number;
+
+    /** The cumulative measured distance of this segment and the segments before it */
+    cumulativeDistance: number;
+
+    /** The cumulative measured cost of this segment and the segments before it */
+    cumulativeCost: number;
+
+    /** Is this segment part of the measurement history? */
+    history: boolean;
+
+    /** Is this segment the first one after the measurement history? */
+    first: boolean;
+
+    /** Is this segment the last one? */
+    last: boolean;
+
+    /** Animation options passed to {@link TokenDocument.update | `TokenDocument#update`} */
+    animation: TokenDocument.Database.Update["animation"];
+  }
+
+  interface MeasurementHistoryWaypoint {
+    /** The x-coordinate of the waypoint */
+    x: number;
+
+    /** The y-coordinate of the waypoint */
+    y: number;
+
+    /** Teleported to from the previous waypoint this waypoint? */
+    teleport: boolean;
+
+    /** The cost of having moved from the previous waypoint to this waypoint */
+    cost: number;
+  }
+
+  type MeasurementHistory = MeasurementHistoryWaypoint[];
+
+  interface MeasurementData {
+    /** The state ({@link Ruler.state | `Ruler#state`}) */
+    state: Ruler.STATES;
+
+    /** The token ID ({@link Ruler.token | `Ruler#token`}) */
+    token: string | null;
+
+    /** The measurement history ({@link Ruler.history | `Ruler#history`}) */
+    history: MeasurementHistory;
+
+    /** The waypoints ({@link Ruler.waypoints | `Ruler#waypoints`}) */
+    waypoints: Canvas.Point[];
+
+    /** The destination ({@link Ruler.destination | `Ruler#destination`}) */
+    destination: Canvas.Point | null;
+  }
+
+  /** @internal */
+  type _Snap = NullishProps<{
+    /**
+     * Snap the destination?
+     * @defaultValue `true`
+     */
+    snap: boolean;
+  }>;
+
+  /** @internal */
+  type _MeasureOptions = NullishProps<{
+    /**
+     * If not forced and the destination matches the current destination of this ruler, no measuring is done and nothing is returned
+     * @defaultValue `false`
+     */
+    force: boolean;
+  }>;
+
+  interface MeasureOptions extends _Snap, _MeasureOptions {}
+
+  interface GetMeasurementOriginOptions extends _Snap {}
+
+  interface GetMeasurementDestinationOptions extends _Snap {}
+
+  /** @internal */
+  type _StartMeasurementOptions = NullishProps<{
+    /**
+     * The token that is moved (defaults to {@link Ruler#_getMovementToken})
+     */
+    token: Token.Implementation | null;
+  }>;
+
+  interface StartMeasurementOptions extends _StartMeasurementOptions, _Snap {}
+
+  interface AddWaypointOptions extends _Snap {}
+
+  // TODO: revisit after docs v2
+  type PartialTokenUpdateOptions = IntentionalPartial<TokenDocument.Database.Update>;
+
+  // TODO: also revisit after docs v2 merges with new and improved IntentionalPartial
+  interface PartialSegmentForLabelling
+    extends Pick<MeasurementSegment, "teleport" | "last" | "distance">,
+      IntentionalPartial<Omit<MeasurementSegment, "teleport" | "last" | "distance">> {}
+
+  interface PartialSegmentForHighlighting
+    extends Pick<MeasurementSegment, "teleport" | "ray">,
+      IntentionalPartial<Omit<MeasurementSegment, "teleport" | "ray">> {}
+
+  interface PartialSegmentForAnimating
+    extends Pick<MeasurementSegment, "teleport" | "animation">,
+      IntentionalPartial<Omit<MeasurementSegment, "teleport" | "animation">> {}
+}
+
+export default Ruler;
+
+declare abstract class AnyRuler extends Ruler {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/layers/_module.d.mts

@@ -0,0 +1,36 @@
+// In Foundry itself this file contains re-exports of these other modules.
+// Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
+// While `.mts` could work, to avoid `import-x/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import-x/extensions */
+
+export * as types from "./_types.mjs";
+
+// Base Layers
+export { default as CanvasLayer } from "./base/canvas-layer.mjs";
+export { default as InteractionLayer } from "./base/interaction-layer.mjs";
+export { default as PlaceablesLayer } from "./base/placeables-layer.mjs";
+
+// Effects
+export { default as CanvasBackgroundAlterationEffects } from "./effects/background-effects.mjs";
+export { default as CanvasColorationEffects } from "./effects/coloration-effects.mjs";
+export { default as CanvasDarknessEffects } from "./effects/darkness-effects.mjs";
+export { default as CanvasIlluminationEffects, DarknessLevelContainer } from "./effects/illumination-effects.mjs";
+export { default as WeatherEffects } from "./effects/weather-effects.mjs";
+
+// Masks
+export { default as CanvasDepthMask } from "./masks/depth.mjs";
+export { default as CanvasOcclusionMask } from "./masks/occlusion.mjs";
+export { default as CanvasVisionMask } from "./masks/vision.mjs";
+
+// Other layers
+export { default as DrawingsLayer } from "./drawings.mjs";
+export { default as LightingLayer } from "./lighting.mjs";
+export { default as NotesLayer } from "./notes.mjs";
+export { default as WallsLayer } from "./walls.mjs";
+export { default as TokenLayer } from "./tokens.mjs";
+export { default as RegionLayer } from "./regions.mjs";
+export { default as SoundsLayer } from "./sounds.mjs";
+export { default as TemplateLayer } from "./templates.mjs";
+export { default as ControlsLayer } from "./controls.mjs";
+export { default as GridLayer } from "./grid.mjs";
+export { default as TilesLayer } from "./tiles.mjs";

package/src/foundry/client/canvas/layers/_types.d.mts

@@ -0,0 +1,26 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+// After seeing that none of these types add anything or are even exported a
+// very reasonable question may be: Why on earth does this file exist?
+//
+// Well this is the file in which Foundry defines these types. We don't house
+// them here because it has poor discoverability. It's also just nice to
+// have as reference to keep us synced with the latest version of Foundry.
+
+export {};
+
+type AmbientSoundPlaybackConfig = foundry.canvas.layers.SoundsLayer.AmbientSoundPlaybackConfig;
+
+type CanvasHistoryEvent<DocumentName extends foundry.abstract.Document.PlaceableType> =
+  foundry.canvas.layers.PlaceablesLayer.HistoryEntry<DocumentName>;
+
+type PlaceablesLayerOptions<Placeable extends foundry.canvas.placeables.PlaceableObject.AnyConstructor> =
+  foundry.canvas.layers.PlaceablesLayer.LayerOptions<Placeable>;
+
+type CanvasVisionContainerSight = foundry.canvas.layers.CanvasVisionMask.CanvasVisionContainerSight;
+
+type CanvasVisionContainerLight = foundry.canvas.layers.CanvasVisionMask.CanvasVisionContainerLight;
+
+type CanvasVisionContainerDarkness = foundry.canvas.layers.CanvasVisionMask.CanvasVisionContainerDarkness;
+
+type CanvasVisionContainer = foundry.canvas.layers.CanvasVisionMask.CanvasVisionContainer;

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

@@ -0,0 +1,91 @@
+import type { HandleEmptyObject, Identity } from "#utils";
+
+/**
+ * An abstract pattern for primary layers of the game canvas to implement
+ */
+declare abstract class CanvasLayer extends PIXI.Container {
+  /**
+   * Options for this layer instance.
+   * @defaultValue `this.constructor.layerOptions`
+   */
+  options: CanvasLayer.LayerOptions;
+
+  /**
+   * @defaultValue `false`
+   */
+  override interactiveChildren: boolean;
+
+  /**
+   * Customize behaviors of this CanvasLayer by modifying some behaviors at a class level.
+   */
+  static get layerOptions(): CanvasLayer.LayerOptions;
+
+  /**
+   * Return a reference to the active instance of this canvas layer
+   */
+  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.
+   * @remarks Foundry defines this as a getter, but since CanvasLayer extends PIXI.Container, it has to be a property.
+   */
+  readonly name: string;
+
+  /**
+   * The name used by hooks to construct their hook string.
+   * Note: You should override this getter if hookName should not return the class constructor name.
+   */
+  get hookName(): string;
+
+  /**
+   * Draw the canvas layer, rendering its internal components and returning a Promise
+   * 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?: 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: 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?: 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: HandleEmptyObject<CanvasLayer.TearDownOptions>): Promise<void>;
+}
+
+declare namespace CanvasLayer {
+  interface Any extends AnyCanvasLayer {}
+  interface AnyConstructor extends Identity<typeof AnyCanvasLayer> {}
+
+  interface LayerOptions {
+    /**
+     * The layer name by which the instance is referenced within the Canvas
+     */
+    name: string;
+
+    baseClass: typeof CanvasLayer;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface DrawOptions {}
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface TearDownOptions {}
+}
+
+export default CanvasLayer;
+
+declare abstract class AnyCanvasLayer extends CanvasLayer {
+  constructor(...args: never);
+}