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

package/src/foundry/client/pixi/layers/base/placeables-layer.d.mts

@@ -0,0 +1,598 @@
+import type { ConstructorOf, InexactPartial, ValueOf } from "../../../../../types/utils.d.mts";
+import type Document from "../../../../common/abstract/document.d.mts";
+import type EmbeddedCollection from "../../../../common/abstract/embedded-collection.d.mts";
+
+type ConcretePlaceableOrPlaceableObject<T> = T extends PlaceableObject ? T : PlaceableObject;
+
+declare global {
+  /**
+   * A subclass of Canvas Layer which is specifically designed to contain multiple PlaceableObject instances,
+   * each corresponding to an embedded Document.
+   * @typeParam DocumentName - The key of the configuration which defines the object and document class.
+   * @typeParam Options      - The type of the options in this layer.
+   */
+  class PlaceablesLayer<DocumentName extends PlaceablesLayer.Type> extends InteractionLayer {
+    constructor();
+
+    /**
+     * Sort order for placeables belonging to this layer
+     * @defaultValue `0`
+     */
+    static SORT_ORDER: number;
+
+    /**
+     * Placeable Layer Objects
+     * @defaultValue `null`
+     */
+    objects: PIXI.Container | null;
+
+    /**
+     * Preview Object Placement
+     * @defaultValue `null`
+     */
+    preview: PIXI.Container | null;
+
+    /**
+     * Keep track of history so that CTRL+Z can undo changes
+     */
+    history: Array<CanvasHistory<DocumentName>>;
+
+    /**
+     * Keep track of an object copied with CTRL+C which can be pasted later
+     * @defaultValue `[]`
+     */
+    protected _copy: ConcretePlaceableOrPlaceableObject<
+      InstanceType<Document.ConfiguredObjectClassForName<DocumentName>>
+    >[];
+
+    /**
+     * A Quadtree which partitions and organizes Walls into quadrants for efficient target identification.
+     */
+    quadtree: Quadtree<
+      ConcretePlaceableOrPlaceableObject<InstanceType<Document.ConfiguredObjectClassForName<DocumentName>>>
+    > | null;
+
+    /**
+     * @remarks Override not in foundry docs but implicit from layerOptions
+     */
+    override options: PlaceablesLayer.LayerOptions.Any;
+
+    static override get layerOptions(): PlaceablesLayer.LayerOptions.Any;
+
+    /**
+     * A reference to the named Document type which is contained within this Canvas Layer.
+     * @remarks This getter is abstract in {@link PlaceablesLayer}.
+     */
+    static documentName: PlaceablesLayer.Type;
+
+    /**
+     * Creation states affected to placeables during their construction.
+     */
+    static CREATION_STATES: Readonly<{
+      NONE: 0;
+      POTENTIAL: 1;
+      CONFIRMED: 2;
+      COMPLETED: 3;
+    }>;
+
+    /**
+     * Obtain a reference to the Collection of embedded Document instances within the currently viewed Scene
+     */
+    get documentCollection(): EmbeddedCollection<
+      InstanceType<Document.ConfiguredClassForName<DocumentName>>,
+      Scene.ConfiguredInstance
+    > | null;
+
+    /**
+     * Define a Container implementation used to render placeable objects contained in this layer
+     */
+    static get placeableClass(): ConstructorOf<PlaceableObject>;
+
+    /**
+     * If objects on this PlaceablesLayer have a HUD UI, provide a reference to its instance
+     * @remarks Returns `null` unless overridden
+     */
+    get hud(): BasePlaceableHUD<InstanceType<Document.ConfiguredObjectClassForName<DocumentName>>> | null;
+
+    /**
+     * A convenience method for accessing the placeable object instances contained in this layer
+     */
+    get placeables(): InstanceType<Document.ConfiguredObjectClassForName<DocumentName>>[];
+
+    /**
+     * An Array of placeable objects in this layer which have the _controlled attribute
+     */
+    get controlled(): InstanceType<Document.ConfiguredObjectClassForName<DocumentName>>[];
+
+    /**
+     * Iterates over placeable objects that are eligible for control/select.
+     * @remarks yields A placeable object
+     */
+    // TODO: Update remark with proper @yields tag https://github.com/microsoft/tsdoc/issues/234
+    controllableObjects(): Generator<PlaceableObject>;
+
+    /**
+     * Track the set of PlaceableObjects on this layer which are currently controlled.
+     */
+    get controlledObjects(): Map<string, PlaceableObject>;
+
+    /**
+     * Track the PlaceableObject on this layer which is currently hovered upon.
+     */
+    get hover(): PlaceableObject | null;
+
+    set hover(object);
+
+    /**
+     * Track whether "highlight all objects" is currently active
+     * @defaultValue `false`
+     */
+    highlightObjects: boolean;
+
+    /**
+     * Get the maximum sort value of all placeables.
+     * @returns The maximum sort value (-Infinity if there are no objects)
+     */
+    getMaxSort(): number;
+
+    /**
+     * Send the controlled objects of this layer to the back or bring them to the front.
+     * @param front - Bring to front instead of send to back?
+     * @returns Returns true if the layer has sortable object, and false otherwise
+     */
+    protected _sentToBackOrBringToFront(front: boolean): boolean;
+
+
+    /**
+     * Snaps the given point to grid. The layer defines the snapping behavior.
+     * @param point - The point that is to be snapped
+     * @returns The snapped point
+     */
+    getSnappedPoint(point: Point): Point;
+
+    /**
+     * Obtain an iterable of objects which should be added to this PlaceableLayer
+     */
+    getDocuments():
+      | Exclude<this["documentCollection"], null>
+      | InstanceType<Document.ConfiguredClassForName<DocumentName>>[];
+
+    override _draw(options?: Record<string, unknown>): Promise<void>;
+
+    /**
+     * Draw a single placeable object
+     * @param document - The Document instance used to create the placeable object
+     */
+    createObject(
+      document: InstanceType<Document.ConfiguredClassForName<DocumentName>>,
+    ): InstanceType<Document.ConfiguredObjectClassForName<DocumentName>> | null;
+
+    override _tearDown(options?: Record<string, unknown>): Promise<void>;
+
+    /**
+     * Override the default PIXI.Container behavior for how objects in this container are sorted.
+     * @internal
+     */
+    protected _sortObjectsByElevation(): void;
+
+    override _activate(): void;
+
+    override _deactivate(): void;
+
+    /**
+     * Clear the contents of the preview container, restoring visibility of original (non-preview) objects.
+     */
+    clearPreviewContainer(): void;
+
+    /**
+     * Get a PlaceableObject contained in this layer by its ID.
+     * Returns undefined if the object doesn't exist or if the canvas is not rendering a Scene.
+     * @param objectId - The ID of the contained object to retrieve
+     * @returns The object instance, or undefined
+     */
+    get(objectId: string): InstanceType<Document.ConfiguredObjectClassForName<DocumentName>> | undefined;
+
+    /**
+     * Acquire control over all PlaceableObject instances which are visible and controllable within the layer.
+     *
+     * @param options - Options passed to the control method of each object
+     *                  (default: `{}`)
+     * @returns An array of objects that were controlled
+     */
+    controlAll(
+      options?: PlaceableObject.ControlOptions,
+    ): InstanceType<Document.ConfiguredObjectClassForName<DocumentName>>[];
+
+    /**
+     * Release all controlled PlaceableObject instance from this layer.
+     *
+     * @param options - Options passed to the release method of each object
+     *                  (default: `{}`)
+     * @returns The number of PlaceableObject instances which were released
+     */
+    releaseAll(options?: PlaceableObject.ReleaseOptions): number;
+
+    /**
+     * Simultaneously rotate multiple PlaceableObjects using a provided angle or incremental.
+     * This executes a single database operation using Scene#updateEmbeddedDocuments.
+     * If rotating only a single object, it is better to use the PlaceableObject.rotate instance method.
+     *
+     * @param options - Options which configure how multiple objects are rotated
+     *                  (default: `{}`)
+     * @returns An array of objects which were rotated
+     * @throws An error if explicitly provided id is not valid
+     */
+    rotateMany(options?: InexactPartial<RotationOptions>): Promise<InstanceType<Document.ConfiguredObjectClassForName<DocumentName>>[]>;
+
+    /**
+     * Simultaneously move multiple PlaceableObjects via keyboard movement offsets.
+     * This executes a single database operation using Scene#updateEmbeddedDocuments.
+     *
+     * @param options - Options which configure how multiple objects are moved
+     *                  (default: `{}`)
+     * @returns An array of objects which were moved during the operation
+     * @throws An error if explicitly provided id is not valid
+     */
+    moveMany(
+      options?: InexactPartial<MovementOptions>,
+    ): Promise<InstanceType<Document.ConfiguredObjectClassForName<DocumentName>>[]> | undefined;
+
+    /**
+     * An internal helper method to identify the array of PlaceableObjects which can be moved or rotated.
+     * @param ids           - An explicit array of IDs requested.
+     * @param includeLocked - Include locked objects which would otherwise be ignored?
+     * @returns An array of objects which can be moved or rotated
+     * @throws An error if any explicitly requested ID is not valid
+     * @remarks Any non-array input for `ids` will default to using currently controlled objects,
+     * allowing you to provide `true` to the includeLocked
+     */
+    protected _getMovableObjects(ids?: string[] | null, includeLocked?: boolean): Document.ConfiguredObjectInstanceForName<DocumentName>;
+
+    /**
+     * Undo a change to the objects in this layer
+     * This method is typically activated using CTRL+Z while the layer is active
+     */
+    undoHistory(): Promise<InstanceType<Document.ConfiguredClassForName<DocumentName>>[]>;
+
+    /**
+     * A helper method to prompt for deletion of all PlaceableObject instances within the Scene
+     * Renders a confirmation dialogue to confirm with the requester that all objects will be deleted
+     * @returns An array of Document objects which were deleted by the operation
+     */
+    deleteAll(): Promise<InstanceType<Document.ConfiguredClassForName<DocumentName>>[] | false | null>;
+
+    /**
+     * Record a new CRUD event in the history log so that it can be undone later
+     * @param type - The event type (create, update, delete)
+     * @param data - The object data
+     */
+    storeHistory(
+      type: PlaceablesLayer.HistoryEventType,
+      data: InstanceType<Document.ConfiguredClassForName<DocumentName>>["_source"],
+    ): void;
+
+    /**
+     * Copy currently controlled PlaceableObjects to a temporary Array, ready to paste back into the scene later
+     * @returns The Array of copied PlaceableObject instances
+     */
+    copyObjects(): InstanceType<Document.ConfiguredObjectClassForName<DocumentName>>[];
+
+    /**
+     * Paste currently copied PlaceableObjects back to the layer by creating new copies
+     * @param position - The destination position for the copied data.
+     * @param options  - Options which modify the paste operation
+     * @returns An Array of created PlaceableObject instances
+     */
+    pasteObjects(
+      position: Point,
+      options?: InexactPartial<{
+        /**
+         * Paste data in a hidden state, if applicable. Default is false.
+         * @defaultValue `false`
+         */
+        hidden: boolean;
+
+        /**
+         * Snap the resulting objects to the grid. Default is true.
+         * @defaultValue `true`
+         */
+        snap: boolean;
+      }>,
+    ): Promise<InstanceType<Document.ConfiguredClassForName<DocumentName>>[]>;
+
+    /**
+     * Get the data of the copied object pasted at the position given by the offset.
+     * Called by {@link PlaceablesLayer#pasteObjects} for each copied object.
+     * @param copy    - The copied object that is pasted
+     * @param offset  - The offset relative from the current position to the destination
+     * @param options - Options of {@link PlaceablesLayer#pasteObjects}
+     * @returns The update data
+     */
+    _pasteObject(copy: Document.ConfiguredObjectInstanceForName<DocumentName>, offset: Point, options?: InexactPartial<{
+
+      /**
+       * Paste in a hidden state, if applicable.
+       * @defaultValue `false`
+       */
+      hidden: boolean;
+
+      /**
+       * Snap to the grid.
+       * @defaultValue `true`
+       */
+      snap: boolean;
+    }>): Document.ConfiguredSourceForName<DocumentName>
+
+    /**
+     * Select all PlaceableObject instances which fall within a coordinate rectangle.
+     * @param options        - (default: `{}`)
+     * @returns A boolean for whether the controlled set was changed in the operation
+     */
+    selectObjects(
+      options?: InexactPartial<{
+        /**
+         * The top-left x-coordinate of the selection rectangle
+         */
+        x: number;
+
+        /**
+         * The top-left y-coordinate of the selection rectangle
+         */
+        y: number;
+
+        /**
+         * The width of the selection rectangle
+         */
+        width: number;
+
+        /**
+         * The height of the selection rectangle
+         */
+        height: number;
+
+        /**
+         * Optional arguments provided to any called release() method
+         * @defaultValue `{}`
+         */
+        releaseOptions: PlaceableObject.ReleaseOptions;
+
+        /**
+         * Optional arguments provided to any called control() method
+         * @defaultValue `{ releaseOthers: false }`
+         */
+        controlOptions: PlaceableObject.ControlOptions;
+      }>,
+    ): boolean;
+
+    /**
+     * Update all objects in this layer with a provided transformation.
+     * Conditionally filter to only apply to objects which match a certain condition.
+     * @param transformation - An object of data or function to apply to all matched objects
+     * @param condition      - A function which tests whether to target each object
+     *                         (default: `null`)
+     * @param options        - Additional options passed to Document.update
+     *                         (default: `{}`)
+     * @returns An array of updated data once the operation is complete
+     */
+    updateAll(
+      transformation:
+        | ((
+            placeable: InstanceType<Document.ConfiguredObjectClassForName<DocumentName>>,
+          ) => Partial<InstanceType<Document.ConfiguredClassForName<DocumentName>>["_source"]>)
+        | Partial<InstanceType<Document.ConfiguredClassForName<DocumentName>>["_source"]>,
+      condition?: ((placeable: InstanceType<Document.ConfiguredObjectClassForName<DocumentName>>) => boolean) | null,
+      options?: Document.OnUpdateOptions<DocumentName>,
+    ): Promise<Array<InstanceType<Document.ConfiguredClassForName<DocumentName>>>>;
+
+    /**
+     * Get the world-transformed drop position.
+     * @returns Returns the transformed x, y co-ordinates, or false if the drag event was outside the canvas.
+     */
+    protected _canvasCoordinatesFromDrop(
+      event: DragEvent,
+      options?: InexactPartial<{
+        /**
+         * Return the co-ordinates of the center of the nearest grid element.
+         * @defaultValue `true`
+         */
+        center: boolean;
+      }>,
+    ): [tx: number, ty: number] | false;
+
+    /**
+     * Create a preview of this layer's object type from a world document and show its sheet to be finalized.
+     * @param createData - The data to create the object with.
+     * @param options    - Options which configure preview creation
+     * @returns The created preview object
+     */
+    protected _createPreview(
+      createData: InstanceType<Document.ConfiguredClassForName<DocumentName>>["_source"],
+      options: {
+        /**
+         * Render the preview object config sheet?
+         * @defaultValue `true`
+         */
+        renderSheet: boolean;
+
+        /**
+         * The offset-top position where the sheet should be rendered
+         * @defaultValue `0`
+         */
+        top: number;
+
+        /**
+         * The offset-left position where the sheet should be rendered
+         * @defaultValue `0`
+         */
+        left: number;
+      },
+    ): Promise<DocumentName>;
+
+    protected override _onClickLeft(event: PIXI.FederatedEvent): void;
+
+    protected override _canDragLeftStart(user: User.ConfiguredInstance, event: PIXI.FederatedEvent): boolean;
+
+    protected override _onDragLeftStart(event: PIXI.FederatedEvent): unknown;
+
+    protected override _onDragLeftMove(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftDrop(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftCancel(event: PointerEvent): void;
+
+    protected override _onClickRight(event: PIXI.FederatedEvent): void;
+
+    protected override _onMouseWheel(event: WheelEvent): void;
+
+    protected override _onDeleteKey(event: KeyboardEvent): Promise<void>;
+
+    /**
+     * @deprecated since v12, will be removed in v14
+     * @remarks `"PlaceablesLayer#gridPrecision is deprecated. Use PlaceablesLayer#getSnappedPoint instead of GridLayer#getSnappedPosition and PlaceablesLayer#gridPrecision."`
+     */
+    get gridPrecision(): number;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks `"PlaceableLayer#_highlight is deprecated. Use PlaceableLayer#highlightObjects instead."`
+     */
+    get _highlight(): this["highlightObjects"];
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks `"PlaceableLayer#_highlight is deprecated. Use PlaceableLayer#highlightObjects instead."`
+     */
+    set _highlight(state);
+  }
+
+  interface CanvasHistory<DocumentName extends PlaceablesLayer.Type> {
+    /**
+     * The type of operation stored as history (create, update, delete)
+     */
+    type: PlaceablesLayer.HistoryEventType;
+
+    /**
+     * The data corresponding to the action which may later be un-done
+     */
+    data: InstanceType<Document.ConfiguredClassForName<DocumentName>>["_source"][];
+  }
+
+  type PlaceablesLayerOptions<DocumentName extends Document.PlaceableType> = PlaceablesLayer.LayerOptions<DocumentName>
+
+  namespace PlaceablesLayer {
+    type Any = PlaceablesLayer<any>;
+
+    type AnyConstructor = typeof AnyPlaceablesLayer;
+
+    type Type = Document.PlaceableType;
+
+    type HistoryEventType = "create" | "update" | "delete";
+
+    type CreationState = ValueOf<(typeof PlaceablesLayer)["CREATION_STATES"]>;
+
+    type ConfiguredClassForName<Name extends Document.PlaceableType> = CONFIG[Name]["layerClass"];
+
+    /**
+     * @typeParam DocumentName - The key of the configuration which defines the object and document class.
+     */
+    interface LayerOptions<DocumentName extends Type> extends InteractionLayer.LayerOptions {
+      baseClass: typeof PlaceablesLayer;
+      /**
+       * Can placeable objects in this layer be controlled?
+       * @defaultValue `false`
+       */
+      controllableObjects: boolean;
+
+      /**
+       * Can placeable objects in this layer be rotated?
+       * @defaultValue `false`
+       */
+      rotatableObjects: boolean;
+
+      /**
+       * Confirm placeable object deletion with a dialog?
+       */
+      confirmDeleteKey: boolean;
+
+      /**
+       * The class used to represent an object on this layer.
+       * @defaultValue `getDocumentClass(this.documentName)`
+       */
+      objectClass: Document.ConfiguredObjectClassForName<DocumentName>;
+
+      /**
+       * Does this layer use a quadtree to track object positions?
+       * @defaultValue `true`
+       */
+      quadtree: boolean;
+    }
+
+    namespace LayerOptions {
+      type Any = LayerOptions<any>;
+    }
+  }
+}
+
+declare abstract class AnyPlaceablesLayer extends PlaceablesLayer<any> {
+  constructor(arg0: never, ...args: never[]);
+}
+
+interface RotationOptions {
+  /**
+   * A target angle of rotation (in degrees) where zero faces "south"
+   */
+  angle: number;
+
+  /**
+   * An incremental angle of rotation (in degrees)
+   */
+  delta: number;
+
+  /**
+   * Snap the resulting angle to a multiple of some increment (in degrees)
+   */
+  snap: number;
+
+  /**
+   * An Array of object IDs to target for rotation
+   */
+  ids: string[];
+
+  /**
+   * Rotate objects whose documents are locked?
+   * @defaultValue `false`
+   */
+  includeLocked: boolean;
+}
+
+interface MovementOptions {
+  /**
+   * Horizontal movement direction
+   * @defaultValue `0`
+   */
+  dx: -1 | 0 | 1;
+
+  /**
+   * Vertical movement direction
+   * @defaultValue `0`
+   */
+  dy: -1 | 0 | 1;
+
+  /**
+   * Rotate the placeable to the keyboard direction instead of moving
+   * @defaultValue
+   */
+  rotate: boolean;
+
+  /**
+   * An Array of object IDs to target for movement. The default is the IDs of controlled objects.
+   * @defaultValue `this.controlled.filter(o => !o.data.locked).map(o => o.id)`
+   */
+  ids: string[];
+
+  /**
+   * Move objects whose documents are locked?
+   * @defaultValue `false`
+   */
+  includeLocked: boolean;
+}

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

@@ -0,0 +1,27 @@
+export {};
+
+declare global {
+  /**
+   * A single Mouse Cursor
+   */
+  class Cursor extends PIXI.Container {
+    constructor(user: User.ConfiguredInstance);
+
+    /**
+     * @defaultValue `{x: 0, y: 0}`
+     */
+    target: { x: number; y: number };
+
+    /**
+     * Draw the user's cursor as a small dot with their user name attached as text
+     */
+    draw(user: User.ConfiguredInstance): void;
+
+    /**
+     * Move an existing cursor to a new position smoothly along the animation loop
+     */
+    protected _animate(): void;
+
+    override destroy(options?: Parameters<PIXI.Container["destroy"]>[0]): void;
+  }
+}

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

@@ -0,0 +1,70 @@
+export {};
+
+declare global {
+  /**
+   * An icon representing a Door Control
+   */
+  class DoorControl extends PIXI.Container {
+    constructor(wall: Wall.ConfiguredInstance);
+
+    wall: Wall.ConfiguredInstance;
+
+    /**
+     * The center of the wall which contains the door.
+     */
+    get center(): PIXI.Point;
+
+    /**
+     * Draw the DoorControl icon, displaying its icon texture and border
+     */
+    draw(): Promise<this>;
+
+    icon?: PIXI.Sprite;
+
+    bg?: PIXI.Graphics;
+
+    border?: PIXI.Graphics;
+
+    /**
+     * Get the icon texture to use for the Door Control icon based on the door state
+     */
+    protected _getTexture(): ReturnType<typeof getTexture>;
+
+    reposition(): void;
+
+    /**
+     * Determine whether the DoorControl is visible to the calling user's perspective.
+     * The control is always visible if the user is a GM and no Tokens are controlled.
+     * @see {@link CanvasVisibility#testVisibility}
+     */
+    get isVisible(): boolean;
+
+    /**
+     * Handle mouse over events on a door control icon.
+     * @param event - The originating interaction event
+     */
+    protected _onMouseOver(event: PIXI.FederatedEvent): false | void;
+
+    /**
+     * Handle mouse out events on a door control icon.
+     * @param event - The originating interaction event
+     */
+    protected _onMouseOut(event: PIXI.FederatedEvent): false | void;
+
+    /**
+     * Handle left mouse down events on a door control icon.
+     * This should only toggle between the OPEN and CLOSED states.
+     * @param event - The originating interaction event
+     */
+    protected _onMouseDown(
+      event: PIXI.FederatedEvent,
+    ): false | void | Promise<WallDocument.ConfiguredInstance | undefined>;
+
+    /**
+     * Handle right mouse down events on the door control icon
+     * This should toggle whether the door is LOCKED or CLOSED
+     * @param event - The originating interaction event
+     */
+    protected _onRightDown(event: PIXI.FederatedEvent): void | Promise<WallDocument.ConfiguredInstance | undefined>;
+  }
+}