@league-of-foundry-developers/foundry-vtt-types 9.280.0 → 12.331.1-beta

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

@@ -0,0 +1,264 @@
+import type { ValueOf } from "../../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * Handle mouse interaction events for a Canvas object.
+   * There are three phases of events: hover, click, and drag
+   *
+   * Hover Events:
+   * _handleMouseOver
+   *  action: hoverIn
+   * _handleMouseOut
+   *  action: hoverOut
+   *
+   * Left Click and Double-Click
+   * _handleMouseDown
+   *  action: clickLeft
+   *  action: clickLeft2
+   *
+   * Right Click and Double-Click
+   * _handleRightDown
+   *  action: clickRight
+   *  action: clickRight2
+   *
+   * Drag and Drop
+   * _handleMouseMove
+   *  action: dragLeftStart
+   *  action: dragRightStart
+   *  action: dragLeftMove
+   *  action: dragRightMove
+   * _handleMouseUp
+   *  action: dragLeftDrop
+   *  action: dragRightDrop
+   * _handleDragCancel
+   *  action: dragLeftCancel
+   *  action: dragRightCancel
+   *
+   * @typeParam Object - The concrete {@link PIXI.Container} object that for which mouse interactions are being managed
+   */
+  class MouseInteractionManager<Object extends PIXI.Container = PIXI.Container> {
+    /**
+     * @param permissions - (default: `{}`)
+     * @param callbacks   - (default: `{}`)
+     * @param options     - (default: `{}`)
+     */
+    constructor(
+      object: PIXI.Container,
+      layer: MouseInteractionManager["layer"],
+      permissions?: MouseInteractionManager["permissions"],
+      callbacks?: MouseInteractionManager["callbacks"],
+      options?: MouseInteractionManager["options"],
+    );
+
+    object: Object;
+
+    layer: PIXI.Container;
+
+    /**
+     * @defaultValue `{}`
+     */
+    permissions: Partial<
+      Record<
+        MouseInteractionManager.PermissionAction,
+        ((user: Game["user"], event: PIXI.FederatedEvent) => boolean) | boolean
+      >
+    >;
+
+    /**
+     * @defaultValue `{}`
+     */
+    callbacks: Partial<Record<MouseInteractionManager.Action, ((event: Event | PIXI.FederatedEvent) => void) | null>>;
+
+    /**
+     * @defaultValue `{}`
+     */
+    options: MouseInteractionManager.Options;
+
+    /**
+     * The current interaction state
+     * @defaultValue `MouseInteractionManager.INTERACTION_STATES.NONE`
+     */
+    state: ValueOf<(typeof MouseInteractionManager)["INTERACTION_STATES"]>;
+
+    /**
+     * Bound handlers which can be added and removed
+     * @defaultValue `{}`
+     */
+    interactionData: {
+      origin?: PIXI.Point;
+      destination?: PIXI.Point;
+      object?: Record<string, unknown>;
+    } & Partial<Record<string, unknown>>;
+
+    /**
+     * 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`
+     */
+    protected _dragRight: boolean;
+
+    /**
+     * An optional ControlIcon instance for the object
+     */
+    controlIcon: ControlIcon | undefined;
+
+    /**
+     * The view id pertaining to the PIXI Application.
+     * If not provided, default to canvas.app.view.id
+     */
+    viewId: ControlIcon;
+
+    /**
+     * 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: DRAG - the object is being dragged
+     * 4: DROP - the object is being dropped
+     */
+    static INTERACTION_STATES: {
+      NONE: 0;
+      HOVER: 1;
+      CLICKED: 2;
+      DRAG: 3;
+      DROP: 4;
+    };
+
+    /**
+     * 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;
+
+    /**
+     * 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: Event | PIXI.FederatedEvent): 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.
+     */
+    callback(action: MouseInteractionManager.Action, event: Event | PIXI.FederatedEvent, ...args: any[]): 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(): ValueOf<MouseInteractionManager.HANDLER_OUTCOME>;
+
+    /**
+     * 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?
+     */
+    handleEvent(event: PIXI.FederatedEvent): boolean;
+
+    /**
+     * A public method to cancel a current interaction workflow from this manager.
+     * @param event - The event that initiates the cancellation
+     */
+    cancel(event: PIXI.FederatedEvent): void;
+
+    /**
+     * Reset the mouse manager.
+     */
+    reset(options?: {
+      /** Reset the interaction data? */
+      interactionData: boolean;
+
+      /** Reset the state? */
+      state: boolean;
+    }): void;
+  }
+
+  namespace MouseInteractionManager {
+    /**
+     * Enumerate the states of handle outcome.
+     */
+    interface HANDLER_OUTCOME {
+      /** -2: SKIPPED - the handler has been skipped by previous logic */
+      SKIPPED: -2;
+
+      /** -1: DISALLOWED - the handler has dissallowed further process */
+      DISALLOWED: -1;
+
+      /** 1: REFUSED - the handler callback has been processed and is refusing further process */
+      REFUSED: 1;
+
+      /** 2: ACCEPTED - the handler callback has been processed and is accepting further process */
+      ACCEPTED: 2;
+    }
+
+    type PermissionAction =
+      | "clickLeft"
+      | "clickLeft2"
+      | "clickRight"
+      | "clickRight2"
+      | "dragLeftDrop"
+      | "dragLeftMove"
+      | "dragLeftStart"
+      | "dragRightDrop"
+      | "dragRightMove"
+      | "dragRightStart"
+      | "hoverIn"
+      | "hoverOut";
+
+    type Action = PermissionAction | "dragLeftCancel" | "dragRightCancel";
+
+    interface Options {
+      target?: PIXI.DisplayObject;
+
+      dragResistance?: number;
+    }
+  }
+}

package/src/foundry/client/pixi/core/interaction/ping.d.mts

@@ -0,0 +1,58 @@
+import type { IDestroyOptions } from "pixi.js";
+
+declare global {
+  interface PingOptions {
+    /**
+     * The duration of the animation in milliseconds.
+     * @defaultValue `900`
+     */
+    duration?: number;
+
+    /**
+     * The size of the ping graphic.
+     * @defaultValue `128`
+     */
+    size?: number;
+
+    /**
+     * The color of the ping graphic.
+     * @defaultValue `#ff6400`
+     */
+    color?: string;
+
+    /**
+     * The name for the ping animation to pass to {@link CanvasAnimation.animate}.
+     */
+    name?: string;
+  }
+
+  /**
+   * A class to manage a user ping on the canvas.
+   */
+  class Ping extends PIXI.Container {
+    /**
+     * @param origin  - The canvas co-ordinates of the origin of the ping.
+     * @param options - Additional options to configure the ping animation.
+     */
+    constructor(origin: PIXI.Point, options?: PingOptions);
+
+    options: PingOptions;
+
+    _color: Color | number;
+
+    destroy(options?: IDestroyOptions | boolean): void;
+
+    /**
+     * Start the ping animation.
+     * @returns Returns true if the animation ran to completion, false otherwise.
+     */
+    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: CanvasAnimationData): void;
+  }
+}

package/src/foundry/client/pixi/core/interaction/pings/chevron.d.mts

@@ -0,0 +1,73 @@
+export {};
+
+declare global {
+  /**
+   * A type of ping that points to a specific location.
+   */
+  class ChevronPing extends Ping {
+    /**
+     * @param origin  - The canvas co-ordinates of the origin of the ping.
+     * @param options - Additional options to configure the ping animation.
+     *                  (default: `{duration: 900, size: 128, color: "#ff6400"}`)
+     */
+    constructor(origin: PIXI.Point, options?: PingOptions);
+
+    /** @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;
+
+    /**
+     * The path to the chevron texture.
+     * @internal
+     */
+    protected static _CHEVRON_PATH: "icons/pings/chevron.webp";
+
+    override animate(): Promise<boolean>;
+
+    override _animateFrame(dt: number, animation: CanvasAnimationData): void;
+
+    /**
+     * Draw the outer and inner rings.
+     * @param a - The alpha.
+     * @internal
+     */
+    protected _drawRings(a: number): void;
+
+    /**
+     * Load the chevron texture.
+     * @internal
+     */
+    protected _loadChevron(): Promise<PIXI.Sprite>;
+
+    /**
+     * Draw the two rings that are used as part of the ping animation.
+     * @internal
+     */
+    protected _createRings(): PIXI.Graphics[];
+  }
+}

package/src/foundry/client/pixi/core/interaction/pings/index.d.mts

@@ -0,0 +1,2 @@
+import "./chevron.d.mts";
+import "./pulse.d.mts";

package/src/foundry/client/pixi/core/interaction/pings/pulse.d.mts

@@ -0,0 +1,115 @@
+export {};
+
+declare global {
+  interface PulsePingOptions extends PingOptions {
+    /**
+     * The number of rings used in the animation.
+     * (default: `3`)
+     */
+    rings?: number;
+
+    /**
+     * The alternate color that the rings begin at. Use white for a 'flashing' effect.
+     * (default: `#ffffff`)
+     */
+    color2?: string;
+  }
+
+  /**
+   * A type of ping that produces a pulsing animation.
+   */
+  class PulsePing extends Ping {
+    /**
+     * @param origin - The canvas co-ordinates of the origin of the ping.
+     * @param options - Additional options to configure the ping animation.
+     */
+    constructor(origin: PIXI.Point, options?: PulsePingOptions);
+
+    _color2: Color | number;
+
+    /**
+     * The radius is half the diameter.
+     * @defaultValue `this.options.size / 2`
+     */
+    _r: number;
+
+    /**
+     * 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;
+
+    /**
+     * 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;
+
+    override animate(): Promise<boolean>;
+
+    override _animateFrame(dt: number, animation: CanvasAnimationData): 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.
+     * @internal
+     */
+    protected _colorTransition(from: Color, to: Color, duration: number, t: number): number;
+
+    /**
+     * Draw the shape for this ping.
+     * @param g     - The graphics object to draw to.
+     * @param color - The color of the shape.
+     * @param alpha - The alpha of the shape.
+     * @param size  - The size of the shape to draw.
+     */
+    protected _drawShape(g: PIXI.Graphics, color: number, alph: number, size: number): void;
+  }
+
+  /**
+   * A type of ping that produces an arrow pointing in a given direction.
+   */
+  class ArrowPing extends PulsePing {
+    /**
+     * @param origin - The canvas co-ordinates 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: PulsePingOptions & {
+        /**
+         * The angle of the arrow in radians.
+         * (default: `0`)
+         */
+        rotation: number;
+      },
+    );
+
+    protected override _drawShape(g: PIXI.Graphics, color: number, alph: number, size: number): void;
+  }
+
+  /**
+   * A type of ping that produces a pulse warning sign animation.
+   */
+  class AlertPing extends PulsePing {
+    /**
+     * @param origin  - The canvas co-ordinates of the origin of the ping.
+     * @param options - Additional options to configure the ping animation.
+     */
+    constructor(origin: PIXI.Point, options: PulsePingOptions);
+
+    protected override _drawShape(g: PIXI.Graphics, color: number, alph: number, size: number): void;
+  }
+}

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

@@ -0,0 +1,103 @@
+import type { AnyConstructor, Mixin } from "../../../../../types/utils.d.mts";
+
+declare class RenderFlagObject {
+  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+  constructor(...args: any[]);
+
+  /**
+   * Configure the render flags used for this class.
+   * @defaultValue `{}`
+   */
+  static RENDER_FLAGS: Record<string, RenderFlag.Any>;
+
+  /**
+   * The ticker priority when RenderFlags of this class are handled.
+   * Valid values are OBJECTS or PERCEPTION.
+   * @defaultValue "OBJECTS"
+   */
+  static RENDER_FLAG_PRIORITY: "OBJECTS" | "PERCEPTION";
+
+  /**
+   * Status flags which are applied at render-time to update the PlaceableObject.
+   * If an object defines RenderFlags, it should at least include flags for "redraw" and "refresh".
+   */
+  renderFlags: RenderFlags;
+
+  /**
+   * Apply any current render flags, clearing the renderFlags set.
+   * Subclasses should override this method to define behavior.
+   */
+  applyRenderFlags(): void;
+}
+
+declare global {
+  /** @privateRemarks Values are marked as optional here based on use, foundry docs incomplete */
+  interface RenderFlag<Flags> {
+    /** Activating this flag also sets these flags to true */
+    propagate?: Array<Partial<keyof Flags>> | undefined;
+
+    /** Activating this flag resets these flags to false */
+    reset?: Array<Partial<keyof Flags>> | undefined;
+  }
+
+  namespace RenderFlag {
+    type Any = RenderFlag<any>;
+  }
+
+  /**
+   * A data structure for tracking a set of boolean status flags.
+   * This is a restricted set which can only accept flag values which are pre-defined.
+   */
+  class RenderFlags extends Set<string> {
+    /**
+     * @param flags  - An object which defines the flags which are supported for tracking
+     * @param config - Optional configuration
+     */
+    constructor(
+      flags: Record<string, RenderFlag<Record<string, boolean>>>,
+      config?: {
+        /** The object which owns this RenderFlags instance */
+        object?: RenderFlagObject;
+
+        /**
+         * The update priority when these render flags are applied.
+         * Valid options are OBJECTS or PERCEPTION.
+         * @defaultValue `PIXI.UPDATE_PRIORITY.OBJECTS`
+         */
+        priority?: PIXI.UPDATE_PRIORITY.OBJECTS | PIXI.UPDATE_PRIORITY.PERCEPTION;
+      },
+    );
+
+    readonly flags: Record<string, RenderFlag<Record<string, boolean>>>;
+
+    readonly object: RenderFlagObject;
+
+    readonly priority: "OBJECT" | "PERCEPTION";
+
+    /**
+     * @returns The flags which were previously set that have been cleared.
+     */
+    clear(): Record<string, boolean>;
+
+    /**
+     * Allow for handling one single flag at a time.
+     * This function returns whether the flag needs to be handled and removes it from the pending set.
+     */
+    handle(flag: string): boolean;
+
+    /**
+     * Activate certain flags, also toggling propagation and reset behaviors
+     */
+    set(changes: Record<string, boolean>): void;
+  }
+
+  /**
+   * Add RenderFlags functionality to some other object.
+   * This mixin standardizes the interface for such functionality.
+   * @param Base - The base class being mixed
+   * @returns The mixed class definition
+   */
+  function RenderFlagsMixin<BaseClass extends AnyConstructor>(
+    Base: BaseClass,
+  ): Mixin<typeof RenderFlagObject, BaseClass>;
+}

package/src/foundry/client/pixi/core/interaction/resize-handle.d.mts

@@ -0,0 +1,52 @@
+export {};
+
+declare global {
+  class ResizeHandle extends PIXI.Graphics {
+    /**
+     * @param handlers - (default: `{}`)
+     */
+    constructor(offset: ResizeHandle["offset"], handlers?: ResizeHandle["handlers"]);
+
+    offset: [widthOffset: number, heightOffset: number];
+
+    handlers: { canDrag?: boolean };
+
+    /**
+     * Track whether the handle is being actively used for a drag workflow
+     * @defaultValue `false`
+     */
+    active: boolean;
+
+    refresh(bounds: Rectangle): void;
+
+    /**
+     * @param aspectRatio - (default: `null`)
+     */
+    updateDimensions(
+      current: Rectangle,
+      origin: Rectangle,
+      destination: Rectangle,
+      { aspectRatio }?: { aspectRatio?: number | null },
+    ): Rectangle;
+
+    activateListeners(): void;
+
+    /**
+     * Handle mouse-over event on a control handle
+     * @param event - The mouseover event
+     */
+    protected _onHoverIn(event: PIXI.FederatedEvent): void;
+
+    /**
+     * Handle mouse-out event on a control handle
+     * @param event - The mouseout event
+     */
+    protected _onHoverOut(event: PIXI.FederatedEvent): void;
+
+    /**
+     * When we start a drag event - create a preview copy of the Tile for re-positioning
+     * @param event - The mousedown event
+     */
+    protected _onMouseDown(event: PIXI.FederatedEvent): void;
+  }
+}