@league-of-foundry-developers/foundry-vtt-types 12.331.3-beta → 12.331.4-beta

package/src/foundry/client/pixi/layers/controls/ruler.d.mts

@@ -1,4 +1,4 @@
-import type { NullishProps, ValueOf } from "../../../../../types/utils.d.mts";
+import type { Brand, FixedInstanceType, Identity, IntentionalPartial, NullishProps } from "fvtt-types/utils";
 
 declare global {
   /**
@@ -10,21 +10,13 @@ declare global {
      *                  (default: `game.user`)
      * @param options - Additional options
      */
-    constructor(
-      user?: User.ConfiguredInstance,
-      options?: NullishProps<{
-        /**
-         * The color of the ruler (defaults to the color of the User)
-         */
-        color?: number;
-      }>,
-    );
+    constructor(user?: User.Implementation, options?: Ruler.ConstructorOptions);
 
     /**
      * Record the User which this Ruler references
      * @defaultValue `game.user`
      */
-    user: User.ConfiguredInstance;
+    user: User.Implementation;
 
     /**
      * The ruler name - used to differentiate between players
@@ -34,7 +26,7 @@ declare global {
 
     /**
      * The ruler color - by default the color of the active user
-     * @defaultValue `foundry.utils.colorStringToHex(this.user.data.color) || 0x42F4E2`
+     * @defaultValue `this.user.color`
      */
     color: Color;
 
@@ -51,7 +43,7 @@ declare global {
     /**
      * The possible Ruler measurement states.
      */
-    static get STATES(): Ruler.STATES;
+    static get STATES(): Ruler.States;
 
     /**
      * Is the ruler ready for measure?
@@ -101,15 +93,15 @@ declare global {
     totalCost: number;
 
     /**
-     * The current state of the Ruler (one of {@link Ruler.STATES}).
+     * The current state of the Ruler (one of {@link Ruler.States | `Ruler.States`}).
      */
-    get state(): ValueOf<Ruler.STATES>;
+    get state(): Ruler.STATES;
 
     /**
-     * The current state of the Ruler (one of {@link Ruler.STATES}).
+     * The current state of the Ruler (one of {@link Ruler.States | `Ruler.States`}).
      * @defaultValue `Ruler.STATES.INACTIVE`
      */
-    protected _state: ValueOf<Ruler.STATES>;
+    protected _state: Ruler.STATES;
 
     /**
      * Is the Ruler being actively used to measure distance?
@@ -124,7 +116,7 @@ declare global {
     /**
      * The Token that is moved by the Ruler.
      */
-    get token(): Token.ConfiguredInstance | null;
+    get token(): Token.Object | null;
 
     /**
      * Clear display of the current Ruler
@@ -139,19 +131,7 @@ declare global {
      */
     measure(
       destination: Canvas.Point,
-      options?: NullishProps<{
-        /**
-         * Snap the destination?
-         * @defaultValue `true`
-         */
-        snap: boolean;
-
-        /**
-         * 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;
-      }>,
+      options?: Ruler.MeasureOptions, // not:null (destructured)
     ): Ruler.MeasurementSegment[] | void;
 
     /**
@@ -161,13 +141,7 @@ declare global {
      */
     protected _getMeasurementOrigin(
       point: Canvas.Point,
-      options?: NullishProps<{
-        /**
-         * Snap the waypoint?
-         * @defaultValue `true`
-         */
-        snap: boolean;
-      }>,
+      options?: Ruler.GetMeasurementOriginOptions, // not:null (destructured)
     ): Canvas.Point;
 
     /**
@@ -178,13 +152,7 @@ declare global {
      */
     protected _getMeasurementDestination(
       point: Canvas.Point,
-      options?: NullishProps<{
-        /**
-         * Snap the point?
-         * @defaultValue `true`
-         */
-        snap: boolean;
-      }>,
+      options?: Ruler.GetMeasurementDestinationOptions, // not:null (destructured)
     ): Canvas.Point;
 
     /**
@@ -200,18 +168,7 @@ declare global {
      */
     protected _startMeasurement(
       origin: Canvas.Point,
-      options?: NullishProps<{
-        /**
-         * Snap the origin?
-         * @defaultValue `true`
-         */
-        snap: boolean;
-
-        /**
-         * The token that is moved (defaults to {@link Ruler#_getMovementToken})
-         */
-        token: Token.ConfiguredInstance | null;
-      }>,
+      options?: Ruler.StartMeasurementOptions, // not:null (destructured)
     ): void;
 
     /**
@@ -226,13 +183,7 @@ declare global {
      */
     protected _addWaypoint(
       point: Canvas.Point,
-      options?: NullishProps<{
-        /**
-         * Snap the waypoint?
-         * @defaultValue `true`
-         */
-        snap: boolean;
-      }>,
+      options?: Ruler.AddWaypointOptions, // not:null (destructured)
     ): void;
 
     /**
@@ -242,6 +193,7 @@ declare global {
 
     /**
      * Get the cost function to be used for Ruler measurements.
+     * @remarks Just a stub in v12.331
      */
     protected _getCostFunction(): foundry.grid.BaseGrid.MeasurePathCostFunction | void;
 
@@ -253,7 +205,7 @@ declare global {
     /**
      * Get the text label for a segment of the measured path
      */
-    protected _getSegmentLabel(segment: Ruler.MeasurementSegment): string;
+    protected _getSegmentLabel(segment: Ruler.PartialSegmentForLabelling): string;
 
     /**
      * Draw each segment of the measured path.
@@ -263,7 +215,7 @@ declare global {
     /**
      * Highlight the measurement required to complete the move in the minimum number of discrete spaces
      */
-    protected _highlightMeasurementSegment(segment: Ruler.MeasurementSegment): void;
+    protected _highlightMeasurementSegment(segment: Ruler.PartialSegmentForHighlighting): void;
 
     /**
      * Determine whether a SPACE keypress event entails a legal token movement along a measured ruler
@@ -279,11 +231,12 @@ declare global {
      * @returns The Token that is to be moved, if any
      *
      */
-    protected _getMovementToken(origin: Canvas.Point): Token.ConfiguredInstance | null;
+    protected _getMovementToken(origin: Canvas.Point): Token.Object | 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;
 
@@ -299,14 +252,14 @@ declare global {
      * @returns Whether the movement is allowed
      * @throws  A specific Error message used instead of returning false
      */
-    protected _canMove(token: Token.ConfiguredInstance): boolean;
+    protected _canMove(token: Token.Object): 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.ConfiguredInstance): Promise<void>;
+    protected _animateMovement(token: Token.Object): Promise<void>;
 
     /**
      * Update Token position and configure its animation properties for the next leg of its animation.
@@ -317,23 +270,23 @@ declare global {
      * @returns A Promise that resolves once the animation for this segment is done
      */
     protected _animateSegment(
-      token: Token.ConfiguredInstance,
-      segment: Ruler.MeasurementSegment,
+      token: Token.Object,
+      segment: Ruler.PartialSegmentForAnimating,
       destination: Canvas.Point,
-      updateOptions: TokenDocument.DatabaseOperations["update"],
+      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): Promise<void>;
+    protected _preMove(token: Token.Object): 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): Promise<void>;
+    protected _postMove(token: Token.Object): Promise<void>;
 
     /**
      * Broadcast Ruler measurement if its User is the connected client.
@@ -350,63 +303,83 @@ declare global {
      * 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;
+    update(data?: Ruler.MeasurementData | null): void;
 
     /**
      * Handle the beginning of a new Ruler measurement workflow
      * @param event - The drag start event
-     * @see Canvas.#onDragLeftStart
+     * @see {@link Canvas.#onDragLeftStart | `Canvas.#onDragLeftStart`}
      */
     protected _onDragStart(event: PIXI.FederatedEvent): void;
 
     /**
      * Handle left-click events on the Canvas during Ruler measurement.
      * @param event - The pointer-down event
-     * @see Canvas._onClickLeft
+     * @see {@link Canvas._onClickLeft | `Canvas._onClickLeft`}
      */
     protected _onClickLeft(event: PIXI.FederatedEvent): void;
 
     /**
      * Handle right-click events on the Canvas during Ruler measurement.
      * @param event - The pointer-down event
-     * @see Canvas._onClickRight
+     * @see {@link Canvas._onClickRight | `Canvas._onClickRight`}
      */
     protected _onClickRight(event: PIXI.FederatedEvent): void;
 
     /**
      * Continue a Ruler measurement workflow for left-mouse movements on the Canvas.
      * @param event - The mouse move event
-     * @see Canvas.#onDragLeftMove
+     * @see {@link Canvas.#onDragLeftMove | `Canvas.#onDragLeftMove`}
      */
     protected _onMouseMove(event: PIXI.FederatedEvent): void;
 
     /**
      * Conclude a Ruler measurement workflow by releasing the left-mouse button.
      * @param event - The pointer-up event
-     * @see Canvas.#onDragLeftDrop
+     * @see {@link Canvas.#onDragLeftDrop | `Canvas.#onDragLeftDrop`}
      */
     protected _onMouseUp(event: PIXI.FederatedEvent): void;
 
     /**
      * Move the Token along the measured path when the move key is pressed.
+     * @remarks `context` is unused in 12.331
      */
     protected _onMoveKeyDown(context: KeyboardManager.KeyboardEventContext): void;
   }
 
   namespace Ruler {
-    type AnyConstructor = typeof AnyRuler;
-
-    interface STATES {
-      readonly INACTIVE: 0;
-      readonly STARTING: 1;
-      readonly MEASURING: 2;
-      readonly MOVING: 3;
+    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;
 
@@ -431,8 +404,8 @@ declare global {
       /** Is this segment the last one? */
       last: boolean;
 
-      /** Animation options passed to {@link TokenDocument#update} */
-      animation: object;
+      /** Animation options passed to {@link TokenDocument.update | `TokenDocument#update`} */
+      animation: TokenDocument.Database.Update["animation"];
     }
 
     interface MeasurementHistoryWaypoint {
@@ -452,24 +425,76 @@ declare global {
     type MeasurementHistory = MeasurementHistoryWaypoint[];
 
     interface MeasurementData {
-      /** The state ({@link Ruler#state}) */
-      state: ValueOf<Ruler.STATES>;
+      /** The state ({@link Ruler.state | `Ruler#state`}) */
+      state: Ruler.STATES;
 
-      /** The token ID ({@link Ruler#token}) */
+      /** The token ID ({@link Ruler.token | `Ruler#token`}) */
       token: string | null;
 
-      /** The measurement history ({@link Ruler#history}) */
+      /** The measurement history ({@link Ruler.history | `Ruler#history`}) */
       history: MeasurementHistory;
 
-      /** The waypoints ({@link Ruler#waypoints}) */
+      /** The waypoints ({@link Ruler.waypoints | `Ruler#waypoints`}) */
       waypoints: Canvas.Point[];
 
-      /** The destination ({@link Ruler#destination}) */
+      /** 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.Object | 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">> {}
   }
 }
 
 declare abstract class AnyRuler extends Ruler {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/layers/effects/background-effects.d.mts

@@ -1,23 +1,17 @@
-export {};
+import type { HandleEmptyObject, Identity } from "fvtt-types/utils";
 
 declare global {
   /**
    * A layer of background alteration effects which change the appearance of the primary group render texture.
    */
-  class CanvasBackgroundAlterationEffects<
-    DrawOptions extends CanvasBackgroundAlterationEffects.DrawOptions = CanvasBackgroundAlterationEffects.DrawOptions,
-    TearDownOptions extends
-      CanvasBackgroundAlterationEffects.TearDownOptions = CanvasBackgroundAlterationEffects.TearDownOptions,
-  > extends CanvasLayer<DrawOptions, TearDownOptions> {
+  class CanvasBackgroundAlterationEffects extends CanvasLayer {
     /**
      * A collection of effects which provide background vision alterations.
-     * @defaultValue `vision.sortableChildren = true`
      */
     vision: PIXI.Container;
 
     /**
      * A collection of effects which provide background preferred vision alterations.
-     * @defaultValue `visionPreferred.sortableChildren = true`
      */
     visionPreferred: PIXI.Container;
 
@@ -26,9 +20,11 @@ declare global {
      */
     lighting: PIXI.Container;
 
-    protected override _draw(options?: DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<CanvasBackgroundAlterationEffects.DrawOptions>): Promise<void>;
 
-    protected override _tearDown(options?: TearDownOptions): Promise<void>;
+    protected override _tearDown(
+      options: HandleEmptyObject<CanvasBackgroundAlterationEffects.TearDownOptions>,
+    ): Promise<void>;
 
     /**
      * Clear background alteration effects vision and lighting containers
@@ -37,7 +33,8 @@ declare global {
   }
 
   namespace CanvasBackgroundAlterationEffects {
-    type AnyConstructor = typeof AnyCanvasBackgroundAlterationEffects;
+    interface Any extends AnyCanvasBackgroundAlterationEffects {}
+    interface AnyConstructor extends Identity<typeof AnyCanvasBackgroundAlterationEffects> {}
 
     interface DrawOptions extends CanvasLayer.DrawOptions {}
 
@@ -46,5 +43,5 @@ declare global {
 }
 
 declare abstract class AnyCanvasBackgroundAlterationEffects extends CanvasBackgroundAlterationEffects {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/layers/effects/coloration-effects.d.mts

@@ -1,13 +1,10 @@
-export {};
+import type { HandleEmptyObject, Identity } from "fvtt-types/utils";
 
 declare global {
   /**
    * A CanvasLayer for displaying coloration visual effects
    */
-  class CanvasColorationEffects<
-    DrawOptions extends CanvasColorationEffects.DrawOptions = CanvasColorationEffects.DrawOptions,
-    TearDownOptions extends CanvasColorationEffects.TearDownOptions = CanvasColorationEffects.TearDownOptions,
-  > extends CanvasLayer<DrawOptions, TearDownOptions> {
+  class CanvasColorationEffects extends CanvasLayer {
     /**
      * @defaultValue `true`
      */
@@ -15,21 +12,23 @@ declare global {
 
     /**
      * The filter used to mask visual effects on this layer
+     * @remarks Only `undefined` prior to first draw
      */
-    filter: VisualEffectsMaskingFilter;
+    filter: VisualEffectsMaskingFilter.ConfiguredInstance | undefined;
 
     /**
      * Clear coloration effects container
      */
     clear(): void;
 
-    protected override _draw(options?: DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<CanvasColorationEffects.DrawOptions>): Promise<void>;
 
-    protected override _tearDown(options?: TearDownOptions): Promise<void>;
+    protected override _tearDown(options: HandleEmptyObject<CanvasColorationEffects.TearDownOptions>): Promise<void>;
   }
 
   namespace CanvasColorationEffects {
-    type AnyConstructor = typeof AnyCanvasColorationEffects;
+    interface Any extends AnyCanvasColorationEffects {}
+    interface AnyConstructor extends Identity<typeof AnyCanvasColorationEffects> {}
 
     interface DrawOptions extends CanvasLayer.DrawOptions {}
 
@@ -38,5 +37,5 @@ declare global {
 }
 
 declare abstract class AnyCanvasColorationEffects extends CanvasColorationEffects {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/layers/effects/darkness-effects.d.mts

@@ -1,13 +1,10 @@
-export {};
+import type { HandleEmptyObject, Identity } from "fvtt-types/utils";
 
 declare global {
   /**
    * A layer of background alteration effects which change the appearance of the primary group render texture.
    */
-  class CanvasDarknessEffects<
-    DrawOptions extends CanvasDarknessEffects.DrawOptions = CanvasDarknessEffects.DrawOptions,
-    TearDownOptions extends CanvasLayer.TearDownOptions = CanvasLayer.TearDownOptions,
-  > extends CanvasLayer<DrawOptions, TearDownOptions> {
+  class CanvasDarknessEffects extends CanvasLayer {
     /**
      * @defaultValue `true`
      */
@@ -18,16 +15,19 @@ declare global {
      */
     clear(): void;
 
-    override _draw(options: DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<CanvasDarknessEffects.DrawOptions>): Promise<void>;
   }
 
   namespace CanvasDarknessEffects {
-    type AnyConstructor = typeof AnyCanvasDarknessEffects;
+    interface Any extends AnyCanvasDarknessEffects {}
+    interface AnyConstructor extends Identity<typeof AnyCanvasDarknessEffects> {}
 
     interface DrawOptions extends CanvasLayer.DrawOptions {}
+
+    interface TearDownOptions extends CanvasLayer.TearDownOptions {}
   }
 }
 
 declare abstract class AnyCanvasDarknessEffects extends CanvasDarknessEffects {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }