@league-of-foundry-developers/foundry-vtt-types 13.346.0-beta.20250801022737 → 13.346.0-beta.20250803184428

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

@@ -4,8 +4,10 @@ import type { CanvasAnimation } from "#client/canvas/animation/_module.d.mts";
 
 /**
  * A class to manage a user ping on the canvas.
+ * @privateRemarks Foundry doesn't mark this abstract, but because of {@linkcode animate} always passing a bound {@linkcode _animateFrame},
+ * and the implementation here just throws, it is effectively abstract.
  */
-declare class Ping extends PIXI.Container {
+declare abstract class Ping extends PIXI.Container {
   /**
    * @param origin  - The canvas coordinates of the origin of the ping.
    * @param options - Additional options to configure the ping animation.
@@ -14,15 +16,19 @@ declare class Ping extends PIXI.Container {
 
   options: Ping.ConstructorOptions;
 
-  _color: Color;
+  /**
+   * The color of the ping
+   * @defaultValue {@linkcode Color.from | Color.from("#ff6400")}
+   */
+  protected _color: Color;
 
-  /** @remarks `Ping#destroy`'s parameter must be an object if passed, as the body does `options.children = true` */
+  /** @remarks Passing `options: boolean` is disallowed, as the body does `options.children = true` */
   override destroy(options?: PIXI.IDestroyOptions): void;
 
   /**
    * Start the ping animation.
    * @returns Returns true if the animation ran to completion, false otherwise.
-   * @privateRemarks This calls `CanvasAnimation.animate` with an empty attribute array for the first argument,
+   * @privateRemarks This calls {@linkcode CanvasAnimation.animate} with an empty attribute array for the first argument,
    * meaning no chance of early return, so no `| void` in the return type
    */
   animate(): Promise<boolean>;
@@ -31,8 +37,9 @@ declare class Ping extends PIXI.Container {
    * On each tick, advance the animation.
    * @param dt        - The number of ms that elapsed since the previous frame.
    * @param animation - The animation state.
+   * @remarks Simply throws in {@linkcode Ping}; subclasses must implement a valid {@linkcode CanvasAnimation.OnTickFunction}
    */
-  protected _animateFrame(dt: number, animation: CanvasAnimation.AnimationData): void;
+  protected abstract _animateFrame(dt: number, animation: CanvasAnimation.AnimationData<this>): void;
 }
 
 declare namespace Ping {
@@ -46,34 +53,32 @@ declare namespace Ping {
     /**
      * The duration of the animation in milliseconds.
      * @defaultValue `900`
-     * @remarks Can't be `null` because `options` is `mergeObject`ed with an object with this key,
-     * and the result is passed on to `CanvasAnimation.animate` in its options, which only has a
-     * parameter default for this property
+     * @remarks Can't be `undefined` because the default is provided via `mergeObject`
+     *
+     * See {@linkcode CanvasAnimation.AnimateOptions.duration}
      */
-    duration: number | undefined;
+    duration: number;
 
     /**
      * The size of the ping graphic.
      * @defaultValue `128`
-     * @remarks Can't be `null` or `undefined` because `options` is `mergeObject`ed with an object with this key.
-     * This value is not used in the base `Ping` class, but is used by subclasses to define radius and padding in
-     * ways where `undefined` produces `NaN` and values of `0` (ie, cast `null`) are nonsensical
+     * @remarks Can't be `undefined` because the default is provided via `mergeObject`
      */
     size: number;
 
     /**
      * The color of the ping graphic.
-     * @defaultValue `#ff6400`
-     * @remarks Can't be `null` or `undefined` because `options` is `mergeObject`ed with an object with this key,
-     * and passing either to `Color.from` produces a `Color(NaN)`, which may cause breakage in subclasses or when
-     * passed to PIXI methods
+     * @defaultValue `"#ff6400"`
+     * @remarks Can't be `undefined` because the default is provided via `mergeObject`
      */
     color: Color.Source;
 
     /**
      * The name for the ping animation to pass to {@linkcode CanvasAnimation.animate}.
+     *
+     * See {@linkcode CanvasAnimation.AnimateOptions.name}
      */
-    name: PropertyKey | undefined | null;
+    name: PropertyKey | undefined;
   }>;
 
   interface ConstructorOptions extends Ping._ConstructorOptions {}

package/src/foundry/client/canvas/interaction/ping/pulse.d.mts

@@ -11,57 +11,28 @@ declare class PulsePing extends Ping {
    * @param origin - The canvas coordinates of the origin of the ping.
    * @param options - Additional options to configure the ping animation.
    */
-  constructor(
-    origin: Canvas.Point,
-
-    /** @privateRemarks Can't be `null` as it's directly assigned to  `Ping#options` which has properties accessed null-unsafely */
-    options?: PulsePing.ConstructorOptions,
-  );
+  constructor(origin: Canvas.Point, options?: PulsePing.ConstructorOptions);
 
   override options: PulsePing.ConstructorOptions;
 
-  _color2: Color;
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  _color2: never;
 
-  /**
-   * The radius is half the diameter.
-   * @defaultValue `this.options.size / 2`
-   */
-  _r: number;
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  _r: never;
 
-  /**
-   * This is the radius that the rings initially begin at. It's set to 1/5th of the maximum radius.
-   * @defaultValue `this._r / 5`
-   */
-  _r0: number;
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  _r0: never;
 
-  /**
-   * Initialize some time slice variables that will be used to control the animation.
-   *
-   * The animation for each ring can be separated into two consecutive stages.
-   * Stage 1: Fade in a white ring with radius r0.
-   * Stage 2: Expand radius outward. While the radius is expanding outward, we have two additional, consecutive
-   * animations:
-   *  Stage 2.1: Transition color from white to the configured color.
-   *  Stage 2.2: Fade out.
-   * 1/5th of the animation time is allocated to Stage 1. 4/5ths are allocated to Stage 2. Of those 4/5ths, 2/5ths
-   * are allocated to Stage 2.1, and 2/5ths are allocated to Stage 2.2.
-   */
-  protected _computeTimeSlices(): void;
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected _computeTimeSlices(): never;
 
   override animate(): Promise<boolean>;
 
-  override _animateFrame(dt: number, animation: CanvasAnimation.AnimationData): void;
+  protected override _animateFrame(dt: number, animation: CanvasAnimation.AnimationData<this>): void;
 
-  /**
-   * Transition linearly from one color to another.
-   * @param from     - The color to transition from.
-   * @param to       - The color to transition to.
-   * @param duration - The length of the transition in milliseconds.
-   * @param t        - The current time along the duration.
-   * @returns The incremental color between from and to.
-   * @privateRemarks Foundry marked `@private`, and only types the return as `number`, instead of the more accurate `Color`
-   */
-  protected _colorTransition(from: Color, to: Color, duration: number, t: number): Color;
+  /** @deprecated Made hard private in v13 (this warning will be removed in v14) */
+  protected _colorTransition(from: never, to: never, duration: never, t: never): never;
 
   /**
    * Draw the shape for this ping.
@@ -70,7 +41,9 @@ declare class PulsePing extends Ping {
    * @param alpha - The alpha of the shape.
    * @param size  - The size of the shape to draw.
    */
-  protected _drawShape(g: PIXI.Graphics, color: number | Color, alpha: number, size: number): void;
+  protected _drawShape(g: PIXI.Graphics, color: number, alpha: number, size: number): void;
+
+  #PulsePing: true;
 }
 
 declare namespace PulsePing {
@@ -82,14 +55,12 @@ declare namespace PulsePing {
     /**
      * The number of rings used in the animation.
      * @defaultValue `3`
-     * @remarks Can't be `null` as it only has a parameter default and a coerced `0` ring count is nonsensical
      */
     rings: number;
 
     /**
      * The alternate color that the rings begin at. Use white for a 'flashing' effect.
      * @defaultValue `#ffffff`
-     * @remarks Can't be `null` as it only has a parameter default and `Color(NaN)`s are to be avoided
      */
     color2: Color.Source;
   }>;

package/src/foundry/client/canvas/interaction/render-flags.d.mts

@@ -9,6 +9,7 @@ import type {
   PhantomConstructor,
 } from "#utils";
 import type { LogCompatibilityWarningOptions } from "#common/utils/logging.d.mts";
+import type { Canvas } from "#client/canvas/_module.d.mts";
 
 declare class RenderFlagObject {
   /** @privateRemarks All mixin classes should accept anything for its constructor. */
@@ -24,8 +25,9 @@ declare class RenderFlagObject {
    * The ticker priority when RenderFlags of this class are handled.
    * Valid values are OBJECTS or PERCEPTION.
    * @defaultValue `"OBJECTS"`
+   * @remarks Must match a key of {@linkcode Canvas.pendingRenderFlags}
    */
-  static RENDER_FLAG_PRIORITY: "OBJECTS" | "PERCEPTION";
+  static RENDER_FLAG_PRIORITY: RenderFlags.Priority;
 
   /**
    * Status flags which are applied at render-time to update the PlaceableObject.
@@ -57,19 +59,14 @@ type _RenderFlag<Keys extends string> = InexactPartial<{
   reset: Keys[];
 
   /**
-   * Is this flag deprecated? The deprecation options are passed to
-   * logCompatibilityWarning. The deprectation message is auto-generated
-   * unless message is passed with the options.
+   * Is this flag deprecated? The deprecation options are passed to {@linkcode foundry.utils.logCompatibilityWarning}.
+   * The deprecation message is auto-generated unless message is passed with the options.
    * By default the message is logged only once.
    */
   deprecated: {
     message: string;
   } & LogCompatibilityWarningOptions;
 
-  /**
-   * @remarks Possibly meant to be a sub-property of deprecated,
-   * the runtime check in `RenderFlags##set` looks for this as a top level property
-   */
   alias: boolean;
 }>;
 
@@ -94,11 +91,19 @@ declare class RenderFlags<Flags extends RenderFlags.ValidateFlags<Flags>> extend
    */
   constructor(flags: Flags, config?: RenderFlags.Config);
 
-  readonly flags: Flags;
+  /** @remarks `defineProperty`'d at construction with `enumerable: false, writable: false` and the value frozen. */
+  readonly flags: Readonly<Flags>;
 
+  /** @remarks `defineProperty`'d at construction with `enumerable: false, writable: false` */
   readonly object: RenderFlagObject;
 
-  readonly priority: "OBJECT" | "PERCEPTION";
+  /**
+   * The update priority when these render flags are applied.
+   * Valid options are `"OBJECTS"` or `"PERCEPTION"`.
+   *
+   * @remarks `defineProperty`'d at construction with `enumerable: false, writable: false`
+   */
+  readonly priority: RenderFlags.Priority;
 
   /**
    * @returns The flags which were previously set that have been cleared.
@@ -128,12 +133,21 @@ declare namespace RenderFlags {
     object?: RenderFlagObject;
 
     /**
-     * The update priority when these render flags are applied.
-     * Valid options are OBJECTS or PERCEPTION.
-     * @defaultValue `PIXI.UPDATE_PRIORITY.OBJECTS`
+     * The ticker priority at which these render flags are handled
+     * @defaultValue {@linkcode PIXI.UPDATE_PRIORITY.OBJECTS}
+     * @remarks The default value does *not* match the type as of 13.346, this is a core bug: {@link https://github.com/foundryvtt/foundryvtt/issues/13171}.
+     * Due to this the property has been marked required here, it can go back to optional if the default is fixed.
+     *
+     * See {@linkcode RenderFlags.priority | RenderFlags#priority}
      */
-    priority?: typeof PIXI.UPDATE_PRIORITY.OBJECTS | typeof PIXI.UPDATE_PRIORITY.PERCEPTION;
+    priority: Priority;
   }
+
+  /**
+   * @remarks {@linkcode RenderFlags.set | RenderFlags#set} and {@linkcode RenderFlags.clear | RenderFlags#clear}
+   * both access {@linkcode Canvas.pendingRenderFlags | canvas.pendingRenderFlags[priority]}
+   */
+  type Priority = keyof Canvas.PendingRenderFlags;
 }
 
 /**
@@ -175,7 +189,7 @@ declare namespace RenderFlagsMixin {
   type _KeyOf<T> = keyof T;
 
   type ToBooleanFlags<RenderFlags extends object> = {
-    [K in _KeyOf<RenderFlags>]?: boolean | null | undefined;
+    [K in _KeyOf<RenderFlags>]?: boolean | undefined;
   };
 }
 

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

@@ -1,13 +1,240 @@
-import type { Identity } from "#utils";
-import type { RenderFlagsMixin } from "../render-flags.d.mts";
+import type { Identity, InexactPartial, IntentionalPartial, MaybePromise } from "#utils";
+import type { RenderFlagsMixin, RenderFlag } from "../render-flags.d.mts";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { PIXI } from "#configuration";
+
+/**
+ * The ruler that is used to measure distances on the Canvas.
+ */
+declare abstract class BaseRuler extends RenderFlagsMixin() {
+  /**
+   * @param user - The User for whom to construct the Ruler instance
+   */
+  constructor(user: User.Implementation);
+
+  static override RENDER_FLAGS: BaseRuler.RENDER_FLAGS;
+
+  /**
+   * Is the Ruler ready to measure?
+   */
+  static get canMeasure(): boolean;
+
+  /**
+   * Snaps the given point to the grid.
+   * @param point - The point that is to be snapped
+   * @returns The snapped point
+   * @remarks Despite forwarding to {@linkcode foundry.grid.BaseGrid.getSnappedPoint | canvas.grid.getSnappedPoint},
+   * since this only takes `{x, y}` in, it will only return `{x, y}`, never with `elevation`
+   */
+  static getSnappedPoint(point: Canvas.Point): Canvas.Point;
+
+  /**
+   * The User who this Ruler belongs to.
+   */
+  get user(): User.Implementation;
+
+  /**
+   * Is this Ruler active? True, if the path of the Ruler is nonempty.
+   */
+  get active(): boolean;
+
+  /**
+   * The Ruler is visible if it is active and either not hidden or its User is the current User.
+   */
+  get visible(): boolean;
+
+  /**
+   * The sequence of points that the Ruler measures.
+   * @defaultValue `[]`
+   * @remarks The `path` setter freezes both the outer array and each element
+   */
+  get path(): BaseRuler.Path;
+
+  set path(value);
+
+  /**
+   * The first point of the path, or undefined if the path is empty.
+   */
+  get origin(): Canvas.ElevatedPoint | undefined;
+
+  /**
+   * The last point of the path, or undefined if the path is empty.
+   * @remarks Returns `this.#path.at(-1)`, so could be the same as {@linkcode origin | #origin} if the path is
+   * only one point long for whatever reason
+   */
+  get destination(): Canvas.ElevatedPoint | undefined;
+
+  /**
+   * Is this Ruler hidden? If true, only the User of the Ruler can see it.
+   * @defaultValue `false`
+   */
+  get hidden(): boolean;
+
+  set hidden(value);
+
+  /**
+   * Called when the Ruler's path has changed.
+   */
+  protected _onPathChange(): void;
+
+  /**
+   * Called when the Ruler becomes hidden or unhidden.
+   */
+  protected _onHiddenChange(): void;
+
+  /**
+   * Reset the path and the hidden state of the Ruler.
+   */
+  reset(): void;
+
+  /**
+   * Draw the Ruler.
+   */
+  abstract draw(): MaybePromise<void>;
+
+  /**
+   * Destroy the Ruler.
+   */
+  abstract destroy(): void;
+
+  /**
+   * Refresh the Ruler.
+   */
+  refresh(): void;
+
+  /**
+   * Refresh the Ruler.
+   */
+  protected abstract _refresh(): void;
+
+  override applyRenderFlags(): void;
+
+  /**
+   * Add a waypoint.
+   * @param point   - The (unsnapped) waypoint
+   * @param options - Additional options
+   */
+  protected _addDragWaypoint(point: Canvas.Point, options?: BaseRuler.AddDragWaypointOptions): void;
+
+  /**
+   * Remove the second to last waypoint.
+   */
+  protected _removeDragWaypoint(): void;
+
+  /**
+   * Change the elevation of the destination.
+   * @param delta   - The number vertical steps
+   * @param options - Additional options
+   */
+  protected _changeDragElevation(delta: number, options?: BaseRuler.ChangeDragElevationOptions): void;
+
+  /**
+   * Handle the beginning of a new Ruler measurement workflow.
+   * @param event - The drag start event
+   */
+  protected _onDragStart(event: PIXI.FederatedEvent): void;
+
+  /**
+   * Handle the end of the Ruler measurement workflow
+   * @param event - The drag cancel event
+   * @returns If false, the cancellation of the drag workflow is prevented
+   */
+  protected _onDragCancel(event: PIXI.FederatedEvent): boolean | void;
+
+  /**
+   * Handle left-click events on the Canvas during Ruler measurement.
+   * @param event - The pointer-down event
+   */
+  protected _onClickLeft(event: PIXI.FederatedEvent): void;
+
+  /**
+   * Handle right-click events on the Canvas during Ruler measurement.
+   * @param event - The pointer-down event
+   */
+  protected _onClickRight(event: PIXI.FederatedEvent): void;
+
+  /**
+   * Continue a Ruler measurement workflow for left-mouse movements on the Canvas.
+   * @param event - The mouse move event
+   */
+  protected _onMouseMove(event: PIXI.FederatedEvent): void;
+
+  /**
+   * Conclude a Ruler measurement workflow by releasing the left-mouse button.
+   * @param event - The pointer-up event
+   */
+  protected _onMouseUp(event: PIXI.FederatedEvent): void;
+
+  /**
+   * Adjust the elevation of Ruler waypoints by scrolling up/down.
+   * @param event - The mousewheel event
+   */
+  protected _onMouseWheel(event: WheelEvent): void;
+
+  /**
+   * @deprecated "`BaseRuler#clear` is deprecated in favor of {@linkcode BaseRuler.reset | BaseRuler#reset}." (since v13, until v15)
+   */
+  clear(): void;
+
+  /**
+   * @deprecated "`BaseRuler#update` is deprecated. Set {@linkcode BaseRuler.path | BaseRuler#path}
+   * and {@linkcode BaseRuler.hidden | BaseRuler#hidden} instead." (since v13, until v15)
+   */
+  update(data?: BaseRuler.UpdateData): void;
 
-declare class BaseRuler extends RenderFlagsMixin() {
   #BaseRuler: true;
 }
 
 declare namespace BaseRuler {
   interface Any extends AnyBaseRuler {}
   interface AnyConstructor extends Identity<typeof AnyBaseRuler> {}
+
+  interface RENDER_FLAGS extends RenderFlagsMixin.RENDER_FLAGS {
+    /** @defaultValue `{}` */
+    refresh: RenderFlag<this, "refresh">;
+  }
+
+  type Path = ReadonlyArray<Readonly<Canvas.ElevatedPoint>>;
+
+  /** @internal */
+  type _AddDragWaypointOptions = InexactPartial<{
+    /**
+     * Snap the added waypoint?
+     * @defaultValue `false`
+     */
+    snap: boolean;
+  }>;
+
+  interface AddDragWaypointOptions extends _AddDragWaypointOptions {}
+
+  /** @internal */
+  type _ChangeDragElevationOptions = InexactPartial<{
+    /**
+     * Round elevations to multiples of the grid distance divided by {@linkcode CONFIG.Canvas.elevationSnappingPrecision}?
+     * If false, rounds to multiples of the grid distance.
+     * @defaultValue `false`
+     */
+    precise: boolean;
+  }>;
+
+  interface ChangeDragElevationOptions extends _ChangeDragElevationOptions {}
+
+  /** @internal */
+  type _UpdateData = IntentionalPartial<{
+    /**
+     * @defaultValue `[]`
+     * @remarks Can't be `undefined` because of an `in` check.
+     */
+    path: Canvas.ElevatedPoint[];
+
+    /**
+     * @defaultValue `false`
+     * @remarks Can't be `undefined` because of an `in` check.
+     */
+    hidden: boolean;
+  }>;
+
+  interface UpdateData extends _UpdateData {}
 }
 
 export default BaseRuler;