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

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

@@ -1,503 +1,208 @@
-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 { FixedInstanceType, Identity, InexactPartial } from "#utils";
 import type { Ray } from "#client/canvas/geometry/_module.d.mts";
-import type { Token } from "#client/canvas/placeables/_module.d.mts";
+import type { BaseRuler } from "../_module.d.mts";
+import type { BaseGrid } from "#common/grid/_module.d.mts";
 
 /**
- * The Ruler - used to measure distances and trigger movements
+ * The default implementation of the Ruler.
  */
-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;
+declare class Ruler extends BaseRuler {
+  constructor(user: User.Implementation);
 
   /**
-   * The current state of the Ruler (one of {@linkcode Ruler.States}).
+   * A handlebars template used to render each waypoint label.
+   * @defaultValue `"templates/hud/waypoint-label.hbs"`
    */
-  get state(): Ruler.STATES;
+  static WAYPOINT_LABEL_TEMPLATE: string;
 
   /**
-   * The current state of the Ruler (one of {@linkcode Ruler.States}).
-   * @defaultValue `Ruler.STATES.INACTIVE`
+   * Configure the properties of the outline.
+   * Called in {@linkcode Ruler.draw | Ruler#draw}.
+   * @returns The thickness in pixels and the color
    */
-  protected _state: Ruler.STATES;
+  protected _configureOutline(): Ruler.ConfigureOutlineReturn;
 
-  /**
-   * 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;
+  override draw(): Promise<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;
+  override destroy(): void;
 
-  /**
-   * Compute the distance of each segment and the total distance of the measured path.
-   */
-  protected _computeDistance(): void;
+  protected override _refresh(): void;
 
   /**
-   * Get the text label for a segment of the measured path
+   * Get the context used to render a ruler waypoint label
+   * @remarks `Ruler##renderWaypointLabels` always starts by passing an empty object for `state`, but the parameter itself has no default
    */
-  protected _getSegmentLabel(segment: Ruler.PartialSegmentForLabelling): string;
+  protected _getWaypointLabelContext(
+    waypoint: Ruler.Waypoint,
+    state: Ruler.WaypointContextState,
+  ): Ruler.WaypointContext | void;
 
   /**
-   * Draw each segment of the measured path.
+   * Get the style of the waypoint at the given waypoint.
+   * @param waypoint - The waypoint
+   * @returns The radius, color, and alpha of the waypoint
+   * @remarks `waypoint` is unused in core's implementation as of 13.346
    */
-  protected _drawMeasuredPath(): void;
+  protected _getWaypointStyle(waypoint: Ruler.Waypoint): Ruler.WaypointStyle;
 
   /**
-   * Highlight the measurement required to complete the move in the minimum number of discrete spaces
+   * Get the style of the segment from the previous to the given waypoint.
+   * @param waypoint - The waypoint
+   * @returns The line width, color, and alpha of the segment
+   * @remarks `waypoint` is unused in core's implementation as of 13.346
    */
-  protected _highlightMeasurementSegment(segment: Ruler.PartialSegmentForHighlighting): void;
+  protected _getSegmentStyle(waypoint: Ruler.Waypoint): Ruler.SegmentStyle;
 
   /**
-   * 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.
+   * @deprecated "`Ruler#color` is deprecated. Use {@linkcode Ruler.user | Ruler#user#color} instead." (since v13, until v15)
+   * @remarks Pulling `color` from {@linkcode Ruler._getWaypointStyle | #_getWaypointStyle()} or
+   * {@linkcode Ruler._getSegmentStyle | #_getSegmentStyle()} as appropriate would be the more accurate replacement
    */
-  moveToken(): Promise<boolean>;
+  get color(): Color;
 
   /**
-   * 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
-   *
+   * @deprecated "`Ruler#ruler` is deprecated without replacement." (since v13, until v15)
    */
-  protected _getMovementToken(origin: Canvas.Point): Token.Implementation | null;
+  get ruler(): PIXI.Graphics;
 
-  /**
-   * 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;
+  #Ruler: true;
 }
 
 declare namespace Ruler {
   interface Any extends AnyRuler {}
   interface AnyConstructor extends Identity<typeof AnyRuler> {}
 
-  type ImplementationClass = CONFIG["Canvas"]["rulerClass"];
-  type Implementation = FixedInstanceType<ImplementationClass>;
-
-  /** @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 {}
+  interface ImplementationClass extends Identity<CONFIG["Canvas"]["rulerClass"]> {}
+  interface Implementation extends FixedInstanceType<ImplementationClass> {}
 
-  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 ConfigureOutlineReturn {
+    thickness: number;
+    color: PIXI.ColorSource;
   }
 
-  interface MeasurementHistoryWaypoint {
-    /** The x-coordinate of the waypoint */
+  interface Waypoint {
+    /** The x-coordinate in pixels */
     x: number;
 
-    /** The y-coordinate of the waypoint */
+    /** The y-coordinate in pixels */
     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[];
+    /** The elevation in grid units */
+    elevation: number;
 
-  interface MeasurementData {
-    /** The state ({@link Ruler.state | `Ruler#state`}) */
-    state: Ruler.STATES;
+    /** The index of the waypoint */
+    index: number;
 
-    /** The token ID ({@link Ruler.token | `Ruler#token`}) */
-    token: string | null;
+    /**
+     * The ray from the center point of previous to the center point of this waypoint,
+     * or null if there is no previous waypoint.
+     */
+    ray: Ray | null;
 
-    /** The measurement history ({@link Ruler.history | `Ruler#history`}) */
-    history: MeasurementHistory;
+    /** The measurements at this waypoint. */
+    measurement: BaseGrid.MeasurePathResultWaypoint;
 
-    /** The waypoints ({@link Ruler.waypoints | `Ruler#waypoints`}) */
-    waypoints: Canvas.Point[];
+    /** The previous waypoint, if any. */
+    previous: Waypoint;
 
-    /** The destination ({@link Ruler.destination | `Ruler#destination`}) */
-    destination: Canvas.Point | null;
+    /** The next waypoint, if any. */
+    next: Waypoint;
   }
 
-  /** @internal */
-  type _Snap = NullishProps<{
+  /**
+   * @remarks The type of the `state` param passed to {@linkcode Ruler._getWaypointLabelContext | Ruler#_getWaypointLabelContext}.
+   * It gets passed initially empty, and is mutated and shared between each call to that method made in `Ruler##renderWaypointLabels`.
+   */
+  interface WaypointContextState {
     /**
-     * Snap the destination?
-     * @defaultValue `true`
+     * @remarks Gets set `true` the first time a waypoint has non-`0` elevation and remains `true` from then on, within
+     * the context of a single `##renderWaypointLabels` call
      */
-    snap: boolean;
-  }>;
+    hasElevation?: boolean | undefined;
+  }
 
-  /** @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 WaypointContext {
+    action: string;
+    cssClass: string;
+    secret: boolean;
+    units: string;
+    uiScale: number;
+    position: {
+      x: number;
+      y: number;
+    };
+    distance: SegmentDistance;
+    elevation: ElevationContext;
+  }
+
+  /**
+   * {@linkcode SegmentDistance} and {@linkcode ElevationContext} (and {@linkcode foundry.canvas.placeables.tokens.TokenRuler.SegmentCost | TokenRuler.SegmentCost})
+   * all will include the {@linkcode Number.signedString | .signedString()} of the difference in the property they're describing
+   * @internal
+   */
+  type _DeltaString = InexactPartial<{
+    delta: string;
   }>;
 
-  interface MeasureOptions extends _Snap, _MeasureOptions {}
+  interface SegmentDistance extends _DeltaString {
+    total: string;
+  }
 
-  interface GetMeasurementOriginOptions extends _Snap {}
+  interface ElevationContext extends _DeltaString {
+    total: number;
+    icon: string;
+    hidden: boolean;
+  }
 
-  interface GetMeasurementDestinationOptions extends _Snap {}
+  /**
+   * {@linkcode WaypointStyle} and {@linkcode SegmentStyle} both have defaults applied to these properties when read in
+   * `Ruler##drawPath` and `TokenRuler##drawPath`, via:
+   * ```js
+   * // WaypointStyle:
+   * const {radius, color=0xFFFFFF, alpha=1} = this._getWaypointStyle(waypoint);
+   * // SegmentStyle:
+   * let {width, color=0xFFFFFF, alpha=1} = this._getSegmentStyle(waypoint)
+   * ```
+   * @internal
+   */
+  type _StylePropsWithDefaults = InexactPartial<{
+    /**
+     * @defaultValue `0xFFFFFF`
+     * @remarks The above default is the value if the implementation of {@linkcode Ruler._getWaypointStyle | Ruler#_getWaypointStyle}
+     * or {@linkcode foundry.canvas.placeables.tokens.TokenRuler._getWaypointStyle | TokenRuler#_getWaypointStyle} being used provides
+     * no value/`undefined` for this property. The effective defaults in core's implementations are {@linkcode Ruler.user | this.user.color}
+     * and `game.users.get(waypoint.userId)?.color ?? 0x000000`, respectively
+     */
+    color: PIXI.ColorSource;
 
-  /** @internal */
-  type _StartMeasurementOptions = NullishProps<{
     /**
-     * The token that is moved (defaults to {@link Ruler#_getMovementToken})
+     * @defaultValue `1`
+     * @remarks The above default is the value if the implementation of {@linkcode Ruler._getWaypointStyle | Ruler#_getWaypointStyle}
+     * or {@linkcode foundry.canvas.placeables.tokens.TokenRuler._getWaypointStyle | TokenRuler#_getWaypointStyle} being used provides
+     * no value/`undefined` for this property. It is *also* the default value core's implementations provide in both cases.
      */
-    token: Token.Implementation | null;
+    alpha: number;
   }>;
 
-  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 WaypointStyle extends _StylePropsWithDefaults {
+    radius: number;
+  }
 
-  interface PartialSegmentForHighlighting
-    extends Pick<MeasurementSegment, "teleport" | "ray">,
-      IntentionalPartial<Omit<MeasurementSegment, "teleport" | "ray">> {}
+  interface SegmentStyle extends _StylePropsWithDefaults {
+    width: number;
+  }
 
-  interface PartialSegmentForAnimating
-    extends Pick<MeasurementSegment, "teleport" | "animation">,
-      IntentionalPartial<Omit<MeasurementSegment, "teleport" | "animation">> {}
+  // BaseRuler interfaces it'd be convenient to not need a second import for
+  export import RENDER_FLAGS = foundry.canvas.interaction.BaseRuler.RENDER_FLAGS;
+  export import Path = foundry.canvas.interaction.BaseRuler.Path;
+  export import UpdateData = foundry.canvas.interaction.BaseRuler.UpdateData;
+  export import AddDragWaypointOptions = foundry.canvas.interaction.BaseRuler.AddDragWaypointOptions;
+  export import ChangeDragElevationOptions = foundry.canvas.interaction.BaseRuler.ChangeDragElevationOptions;
 
-  /**
-   * @deprecated Replaced by {@linkcode Ruler.ImplementationClass}.
-   */
+  /** @deprecated Use {@linkcode ImplementationClass} instead */
   type ConfiguredClass = ImplementationClass;
 
-  /**
-   * @deprecated Replaced by {@linkcode Ruler.Implementation}.
-   */
+  /** @deprecated Use {@linkcode Implementation} instead */
   type ConfiguredInstance = Implementation;
 }
 

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

@@ -183,7 +183,7 @@ declare class ControlsLayer extends InteractionLayer {
    * Update display of an active Ruler object for a user given provided data
    * @see {@link Ruler#update}
    */
-  updateRuler(user: User.Implementation, rulerData?: Ruler.MeasurementData | null): void;
+  updateRuler(user: User.Implementation, rulerData?: Ruler.UpdateData | null): void;
 
   /**
    * Handle a broadcast ping.