@league-of-foundry-developers/foundry-vtt-types 13.340.1 → 13.345.1

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

@@ -0,0 +1,24 @@
+// 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";
+
+export { default as MouseInteractionManager } from "./mouse-handler.mjs";
+
+export { default as RenderFlags, RenderFlagsMixin } from "./render-flags.mjs";
+
+// Ping classes
+export { default as Ping } from "./ping/ping.mjs";
+export { default as PulsePing } from "./ping/pulse.mjs";
+export { default as ChevronPing } from "./ping/chevron.mjs";
+export { default as AlertPing } from "./ping/alert.mjs";
+export { default as ArrowPing } from "./ping/arrow.mjs";
+
+// Ruler classes
+export { default as BaseRuler } from "./ruler/base-ruler.mjs";
+export { default as Ruler } from "./ruler/ruler.mjs";
+
+// Type-only exports
+export { RenderFlag } from "./render-flags.mjs";

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

@@ -0,0 +1,18 @@
+/* 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 RenderFlag = foundry.canvas.interaction.RenderFlag.Any;
+
+type PingData = User.PingData;
+
+type PingOptions = foundry.canvas.interaction.Ping.ConstructorOptions;
+
+type PulsePingOptions = foundry.canvas.interaction.PulsePing.ConstructorOptions;

package/src/foundry/client/canvas/interaction/mouse-handler.d.mts

@@ -0,0 +1,362 @@
+import type { AnyArray, Brand, Identity, NullishProps } from "#utils";
+import type { ControlIcon } from "#client/canvas/containers/_module.d.mts";
+
+/**
+ * Handle mouse interaction events for a Canvas object.
+ * There are three phases of events: hover, click, and drag
+ *
+ * Hover Events:
+ * _handlePointerOver
+ *  action: hoverIn
+ * _handlePointerOut
+ *  action: hoverOut
+ *
+ * Left Click and Double-Click
+ * _handlePointerDown
+ *  action: clickLeft
+ *  action: clickLeft2
+ *  action: unclickLeft
+ *
+ * Right Click and Double-Click
+ * _handleRightDown
+ *  action: clickRight
+ *  action: clickRight2
+ *  action: unclickRight
+ *
+ * Drag and Drop
+ * _handlePointerMove
+ *  action: dragLeftStart
+ *  action: dragRightStart
+ *  action: dragLeftMove
+ *  action: dragRightMove
+ * _handlePointerUp
+ *  action: dragLeftDrop
+ *  action: dragRightDrop
+ * _handleDragCancel
+ *  action: dragLeftCancel
+ *  action: dragRightCancel
+ */
+declare class MouseInteractionManager<ObjectFor extends PIXI.Container = PIXI.Container> {
+  /**
+   * @param permissions - (default: `{}`)
+   * @param callbacks   - (default: `{}`)
+   * @param options     - (default: `{}`)
+   * @remarks Foundry does not provide type information for the constructor, everything here is inferred from usage
+   */
+  constructor(
+    object: ObjectFor,
+    layer: PIXI.Container,
+    permissions?: MouseInteractionManager.Permissions,
+    callbacks?: MouseInteractionManager.Callbacks,
+    options?: MouseInteractionManager.Options,
+  );
+
+  object: ObjectFor;
+
+  layer: PIXI.Container;
+
+  /**
+   * @defaultValue `{}`
+   */
+  permissions: MouseInteractionManager.Permissions;
+
+  /**
+   * @defaultValue `{}`
+   */
+  callbacks: MouseInteractionManager.Callbacks;
+
+  /**
+   * @defaultValue `{}`
+   */
+  options: MouseInteractionManager.Options;
+
+  /**
+   * The current interaction state
+   * @defaultValue `MouseInteractionManager.INTERACTION_STATES.NONE`
+   */
+  state: MouseInteractionManager.INTERACTION_STATES;
+
+  /**
+   * Bound handlers which can be added and removed
+   * @defaultValue `{}`
+   */
+  interactionData: MouseInteractionManager.InteractionData<ObjectFor>;
+
+  /**
+   * The drag handling time
+   * @defaultValue `0`
+   */
+  dragTime: number;
+
+  /**
+   * The time of the last left-click event
+   * @defaultValue `0`
+   */
+  lcTime: number;
+
+  /**
+   * The time of the last right-click event
+   * @defaultValue `0`
+   */
+  rcTime: number;
+
+  /**
+   * A flag for whether we are right-click dragging
+   * @defaultValue `false`
+   */
+  _dragRight: boolean;
+
+  /**
+   * An optional ControlIcon instance for the object
+   */
+  controlIcon: ControlIcon | null;
+
+  /**
+   * The view id pertaining to the PIXI Application.
+   * If not provided, default to canvas.app.view.id
+   */
+  viewId: string;
+
+  /**
+   * The client position of the last left/right-click.
+   */
+  lastClick: PIXI.Point;
+
+  /**
+   * Enumerate the states of a mouse interaction workflow.
+   * 0: NONE - the object is inactive
+   * 1: HOVER - the mouse is hovered over the object
+   * 2: CLICKED - the object is clicked
+   * 3: GRABBED - the object is grabbed
+   * 4: DRAG - the object is being dragged
+   * 5: DROP - the object is being dropped
+   */
+  static INTERACTION_STATES: MouseInteractionManager.InteractionStates;
+
+  /**
+   * The maximum number of milliseconds between two clicks to be considered a double-click.
+   * @defaultValue `250`
+   */
+  static DOUBLE_CLICK_TIME_MS: number;
+
+  /**
+   * The maximum number of pixels between two clicks to be considered a double-click.
+   * @defaultValue `5`
+   */
+  static DOUBLE_CLICK_DISTANCE_PX: number;
+
+  /**
+   * The number of milliseconds of mouse click depression to consider it a long press.
+   * @defaultValue `500`
+   */
+  static LONG_PRESS_DURATION_MS: number;
+
+  /**
+   * Global timeout for the long-press event.
+   * @defaultValue `null`
+   */
+  static longPressTimeout: number | null;
+
+  /**
+   * Emulate a pointermove event. Needs to be called when an object with the static event mode
+   * or any of its parents is transformed or its visibility is changed.
+   */
+  static emulateMoveEvent(): void;
+
+  /**
+   * Get the target.
+   */
+  get target(): PIXI.DisplayObject;
+
+  /**
+   * Is this mouse manager in a dragging state?
+   */
+  get isDragging(): boolean;
+
+  /**
+   * Activate interactivity for the handled object
+   */
+  activate(): this;
+
+  /**
+   * Test whether the current user has permission to perform a step of the workflow
+   * @param action - The action being attempted
+   * @param event  - The event being handled
+   * @returns Can the action be performed?
+   */
+  can(action: MouseInteractionManager.PermissionAction, event: MouseInteractionManager.Event): boolean;
+
+  /**
+   * Execute a callback function associated with a certain action in the workflow
+   * @param action - The action being attempted
+   * @param event  - The event being handled
+   * @param args   - Additional callback arguments.
+   * @returns A boolean which may indicate that the event was handled by the callback.
+   *          Events which do not specify a callback are assumed to have been handled as no-op.
+   * @remarks
+   */
+  callback(action: MouseInteractionManager.Action, event: MouseInteractionManager.Event, ...args: AnyArray): boolean;
+
+  /**
+   * A reference to the possible interaction states which can be observed
+   */
+  get states(): typeof MouseInteractionManager.INTERACTION_STATES;
+
+  /**
+   * A reference to the possible interaction states which can be observed
+   */
+  get handlerOutcomes(): MouseInteractionManager.HandlerOutcomes;
+
+  /**
+   * A public method to handle directly an event into this manager, according to its type.
+   * Note: drag events are not handled.
+   * @returns Has the event been processed?
+   *
+   * @remarks Note that the event has specific `interactionData` it expects. A valid `event` can be
+   * fairly involved to create from scratch.
+   */
+  handleEvent(event: MouseInteractionManager.Event): boolean;
+
+  /**
+   * A public method to cancel a current interaction workflow from this manager.
+   * @param event - The event that initiates the cancellation
+   *
+   * @remarks Note that the event has specific `interactionData` it expects. A valid `event` can be
+   * fairly involved to create from scratch.
+   */
+  cancel(event: MouseInteractionManager.Event): void;
+
+  /**
+   * Reset the mouse manager.
+   */
+  reset(options?: MouseInteractionManager.ResetOptions): void;
+}
+
+declare namespace MouseInteractionManager {
+  interface Any extends AnyMouseInteractionManager {}
+  interface AnyConstructor extends Identity<typeof AnyMouseInteractionManager> {}
+
+  /** @privateRemarks The private class property is `#HANDLER_OUTCOME` singular, but the getter is `handlerOutcomes`, so the brand uses the plural */
+  type HANDLER_OUTCOMES = Brand<number, "MouseInteractionManager.HANDLER_OUTCOMES">;
+
+  interface HandlerOutcomes {
+    /** -2: SKIPPED - the handler has been skipped by previous logic */
+    SKIPPED: -2 & MouseInteractionManager.HANDLER_OUTCOMES;
+
+    /** -1: DISALLOWED - the handler has dissallowed further process */
+    DISALLOWED: -1 & MouseInteractionManager.HANDLER_OUTCOMES;
+
+    /** 1: REFUSED - the handler callback has been processed and is refusing further process */
+    REFUSED: 1 & MouseInteractionManager.HANDLER_OUTCOMES;
+
+    /** 2: ACCEPTED - the handler callback has been processed and is accepting further process */
+    ACCEPTED: 2 & MouseInteractionManager.HANDLER_OUTCOMES;
+  }
+
+  type INTERACTION_STATES = Brand<number, "MouseInteractionManager.INTERACTION_STATES">;
+
+  interface InteractionStates {
+    NONE: 0 & MouseInteractionManager.INTERACTION_STATES;
+    HOVER: 1 & MouseInteractionManager.INTERACTION_STATES;
+    CLICKED: 2 & MouseInteractionManager.INTERACTION_STATES;
+    GRABBED: 3 & MouseInteractionManager.INTERACTION_STATES;
+    DRAG: 4 & MouseInteractionManager.INTERACTION_STATES;
+    DROP: 5 & MouseInteractionManager.INTERACTION_STATES;
+  }
+
+  /**
+   * @remarks The list of actions provided by foundry, minus `dragXCancel`, `unclickX`, and `longPress`, which do not check permissions
+   */
+  type PermissionAction =
+    | "clickLeft"
+    | "clickLeft2"
+    | "clickRight"
+    | "clickRight2"
+    | "dragLeftDrop"
+    | "dragLeftMove"
+    | "dragLeftStart"
+    | "dragRightDrop"
+    | "dragRightMove"
+    | "dragRightStart"
+    | "hoverIn"
+    | "hoverOut";
+
+  type PermissionFunction = (user: User.Implementation, event: MouseInteractionManager.Event) => boolean;
+
+  type Permissions = Partial<Record<PermissionAction, PermissionFunction | boolean>>;
+
+  /**
+   * @remarks The full list of possible callback actions.
+   *
+   * Three actions get additional, non-event arguments passed by Foundry:
+   * - `hoverIn` on all placeables takes `options: { hoverOutOthers: boolean }` to trigger hover-out behavior on sibling objects
+   *   - For Regions specifically, `hoverOut` takes an `options: { updateLegend: boolean }` object, and that key is also added to Region `hoverIn` options
+   * - `longPress` receives `origin: PIXI.Point`
+   */
+  type Action = PermissionAction | "dragLeftCancel" | "dragRightCancel" | "unclickLeft" | "unclickRight" | "longPress";
+
+  /**
+   * @remarks Only three actions get additional, non-event arguments passed by Foundry:
+   * - `hoverIn` on all placeables takes `options: { hoverOutOthers: boolean }` to trigger hover-out behavior on sibling objects
+   *   - For Regions specifically, `hoverOut` takes an `options: { updateLegend: boolean }` object, and that key is also added to Region `hoverIn` options
+   * - `longPress` receives `origin: PIXI.Point`
+   */
+  type CallbackFunction = (event: MouseInteractionManager.Event, ...args: never) => boolean | null | void;
+
+  type Callbacks = Partial<Record<Action, CallbackFunction>>;
+
+  /** @internal */
+  type _Options = NullishProps<{
+    /**
+     * @remarks If passed, will set `this.controlIcon` to `Object[target]`; in practice, this should only be `null` or `"controlIcon"`
+     * @privateRemarks Despite Foundry typing this as `PIXI.DisplayObject` its one use in practice is as `string | null`
+     */
+    target: string | null;
+
+    /**
+     * @remarks If falsey, gets replaced with `(canvas.dimensions.size / 4)`
+     */
+    dragResistance: number;
+
+    /**
+     * @remarks Undocumented. Used in the constructor as `this.viewId = (this.options.application ?? canvas.app).view.id`, never passed in practice
+     */
+    application: PIXI.Application;
+  }>;
+
+  /**
+   * Interaction options which configure handling workflows
+   */
+  interface Options extends _Options {}
+
+  /** @internal */
+  type _ResetOptions = NullishProps<{
+    /**
+     * Reset the interaction data?
+     * @defaultValue `true`
+     */
+    interactionData: boolean;
+
+    /**
+     * Reset the state?
+     * @defaultValue `true`
+     */
+    state: boolean;
+  }>;
+
+  interface ResetOptions extends _ResetOptions {}
+
+  interface InteractionData<T extends PIXI.DisplayObject> {
+    origin?: PIXI.Point | undefined;
+    destination?: PIXI.Point | undefined;
+    object?: T | undefined;
+  }
+
+  type Event = foundry.canvas.Canvas.Event._Base | globalThis.Event;
+}
+
+export default MouseInteractionManager;
+
+declare abstract class AnyMouseInteractionManager extends MouseInteractionManager {
+  constructor(...args: never);
+}

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

@@ -0,0 +1,38 @@
+import type { Identity } from "#utils";
+import type { PulsePing } from "#client/canvas/interaction/_module.d.mts";
+
+/**
+ * A type of ping that produces a pulse warning sign animation.
+ */
+declare class AlertPing extends PulsePing {
+  /**
+   * @param origin  - The canvas coordinates of the origin of the ping.
+   * @param options - Additional options to configure the ping animation.
+   */
+  constructor(origin: PIXI.Point, options: AlertPing.ConstructorOptions);
+
+  protected override _drawShape(g: PIXI.Graphics, color: number | Color, alpha: number, size: number): void;
+}
+
+declare namespace AlertPing {
+  interface Any extends AnyAlertPing {}
+  interface AnyConstructor extends Identity<typeof AnyAlertPing> {}
+
+  /** @privateRemarks Only exists to change the default value of `color` */
+  interface ConstructorOptions extends PulsePing.ConstructorOptions {
+    /**
+     * @defaultValue `"#ff0000"`
+     * @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
+     * @privateRemarks Typing this as `Ping.ConstructorOptions["color"]` breaks, because it thinks `| undefined` has snuck in for unknown reasons
+     */
+    color?: Color.Source;
+  }
+}
+
+export default AlertPing;
+
+declare abstract class AnyAlertPing extends AlertPing {
+  constructor(...args: never);
+}

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

@@ -0,0 +1,41 @@
+import type { Identity, NullishProps } from "#utils";
+import type { PulsePing } from "#client/canvas/interaction/_module.d.mts";
+
+/**
+ * A type of ping that produces an arrow pointing in a given direction.
+ */
+declare class ArrowPing extends PulsePing {
+  /**
+   * @param origin - The canvas coordinates of the origin of the ping. This becomes the arrow's tip.
+   * @param options - Additional options to configure the ping animation.
+   */
+  constructor(origin: PIXI.Point, options?: ArrowPing.ConstructorOptions);
+
+  // @privateRemarks The `options` property does not get overridden here as the `rotation` key does not
+  // get passed up to super, so it's still just `PulsePing.Constructor.Options`
+
+  protected override _drawShape(g: PIXI.Graphics, color: number | Color, alpha: number, size: number): void;
+}
+
+declare namespace ArrowPing {
+  interface Any extends AnyArrowPing {}
+  interface AnyConstructor extends Identity<typeof AnyArrowPing> {}
+
+  /** @internal */
+  type _ConstructorOptions = NullishProps<{
+    /**
+     * The angle of the arrow in radians.
+     * @defaultValue `0`
+     * @privateRemarks Null coercion to `0` is fine here, as it's only added to then passed to `Math.normalizeRadians`
+     */
+    rotation: number;
+  }>;
+
+  interface ConstructorOptions extends _ConstructorOptions, PulsePing.ConstructorOptions {}
+}
+
+export default ArrowPing;
+
+declare abstract class AnyArrowPing extends ArrowPing {
+  constructor(...args: never);
+}

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

@@ -0,0 +1,98 @@
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { CanvasAnimation } from "#client/canvas/animation/_module.d.mts";
+import type { Identity } from "#utils";
+import type { Ping } from "#client/canvas/interaction/_module.d.mts";
+
+/**
+ * A type of ping that points to a specific location.
+ */
+declare class ChevronPing extends Ping {
+  /**
+   * @param origin  - The canvas coordinates of the origin of the ping.
+   * @param options - Additional options to configure the ping animation.
+   *                  (default: `{duration: 900, size: 128, color: "#ff6400"}`)
+   */
+  constructor(
+    origin: Canvas.Point,
+
+    /** @privateRemarks Can't be `null` as it's directly assigned to  `Ping#options` which has properties accessed null-unsafely */
+    options?: Ping.ConstructorOptions,
+  );
+
+  /** @defaultValue `(this.options.size / 2) * .75` */
+  _r: number;
+
+  /**
+   * The inner ring is 3/4s the size of the outer.
+   * @defaultValue `this._r * .75`
+   */
+  _rInner: number;
+
+  /**
+   * The animation is split into three stages. First, the chevron fades in and moves downwards, then the rings fade
+   * in, then everything fades out as the chevron moves back up.
+   * Store the 1/4 time slice.
+   * @defaultValue `this.options.duration * .25`
+   */
+  _t14: number;
+
+  /**
+   * Store the 1/2 time slice.
+   * @defaultValue `this.options.duration * .5`
+   */
+  _t12: number;
+
+  /**
+   * Store the 3/4s time slice.
+   * @defaultValue `this._t14 * 3`
+   */
+  _t34: number;
+
+  /** @remarks Doesn't exist before the first `#_createRings()` call, usually via `#animate()` */
+  _inner?: PIXI.Graphics;
+
+  /** @remarks Doesn't exist before the first `#_createRings()` call, usually via `#animate()` */
+  _outer?: PIXI.Graphics;
+
+  /**
+   * The path to the chevron texture.
+   * @remarks Unusually for Foundry, this is referred to by `ChevronPing.`, not `this.constructor.`, in
+   * `#_loadChevron()`, which must therefore be overridden to use a different value in a subclass
+   * @privateRemarks Foundry marked `@private`.
+   */
+  static _CHEVRON_PATH: string;
+
+  override animate(): Promise<boolean>;
+
+  override _animateFrame(dt: number, animation: CanvasAnimation.AnimationData): void;
+
+  /**
+   * Draw the outer and inner rings.
+   * @param a - The alpha.
+   * @privateRemarks Foundry marked `@private`
+   */
+  _drawRings(a: number): void;
+
+  /**
+   * Load the chevron texture.
+   * @privateRemarks Foundry marked `@private`
+   */
+  _loadChevron(): Promise<PIXI.Sprite>;
+
+  /**
+   * Draw the two rings that are used as part of the ping animation.
+   * @privateRemarks Foundry marked `@private`
+   */
+  _createRings(): [PIXI.Graphics, PIXI.Graphics];
+}
+
+declare namespace ChevronPing {
+  interface Any extends AnyChevronPing {}
+  interface AnyConstructor extends Identity<typeof AnyChevronPing> {}
+}
+
+export default ChevronPing;
+
+declare abstract class AnyChevronPing extends ChevronPing {
+  constructor(...args: never);
+}

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

@@ -0,0 +1,86 @@
+import type { Identity, IntentionalPartial, RemoveIndexSignatures } from "#utils";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { CanvasAnimation } from "#client/canvas/animation/_module.d.mts";
+
+/**
+ * A class to manage a user ping on the canvas.
+ */
+declare 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.
+   */
+  constructor(origin: Canvas.Point, options?: Ping.ConstructorOptions);
+
+  options: Ping.ConstructorOptions;
+
+  _color: Color;
+
+  /** @remarks `Ping#destroy`'s parameter must be an object if passed, 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,
+   * meaning no chance of early return, so no `| void` in the return type
+   */
+  animate(): Promise<boolean>;
+
+  /**
+   * On each tick, advance the animation.
+   * @param dt        - The number of ms that elapsed since the previous frame.
+   * @param animation - The animation state.
+   */
+  protected _animateFrame(dt: number, animation: CanvasAnimation.AnimationData): void;
+}
+
+declare namespace Ping {
+  interface Any extends AnyPing {}
+  interface AnyConstructor extends Identity<typeof AnyPing> {}
+
+  type ConfiguredStyles = keyof RemoveIndexSignatures<typeof CONFIG.Canvas.pings.styles>;
+
+  /** @internal */
+  type _ConstructorOptions = IntentionalPartial<{
+    /**
+     * 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
+     */
+    duration: number | undefined;
+
+    /**
+     * 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
+     */
+    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
+     */
+    color: Color.Source;
+
+    /**
+     * The name for the ping animation to pass to {@linkcode CanvasAnimation.animate}.
+     */
+    name: PropertyKey | undefined | null;
+  }>;
+
+  interface ConstructorOptions extends Ping._ConstructorOptions {}
+}
+
+export default Ping;
+
+declare abstract class AnyPing extends Ping {
+  constructor(...args: never);
+}