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

package/src/foundry/client/pixi/placeables/drawing.d.mts

@@ -1,60 +1,28 @@
-import type { ValueOf, FixedInstanceType } from "fvtt-types/utils";
+import type { ValueOf, FixedInstanceType, HandleEmptyObject, RequiredProps, NullishProps } from "fvtt-types/utils";
 import type { ConfiguredObjectClassOrDefault } from "../../config.d.mts";
 
 declare global {
-  namespace Drawing {
-    type ConfiguredClass = ConfiguredObjectClassOrDefault<typeof Drawing>;
-    type ConfiguredInstance = FixedInstanceType<ConfiguredClass>;
-
-    interface RenderFlags extends PlaceableObject.RenderFlags {
-      refreshShape: boolean;
-
-      refreshFrame: boolean;
-
-      refreshText: boolean;
-
-      refreshMesh: boolean;
-    }
-
-    interface TextEditingOptions {
-      forceTextEditing?: boolean;
-
-      isNew?: boolean;
-    }
-
-    interface AdjustableShape {
-      shape: {
-        width: number;
-        height: number;
-        points: Canvas.Point[];
-      };
-      x: number;
-      y: number;
-    }
-  }
-
   /**
    * The Drawing object is an implementation of the PlaceableObject container.
    * Each Drawing is a placeable object in the DrawingsLayer.
    */
-  class Drawing extends PlaceableObject<DrawingDocument.ConfiguredInstance> {
-    constructor(document: DrawingDocument.ConfiguredInstance);
+  class Drawing extends PlaceableObject<DrawingDocument.Implementation> {
+    // fake override; super has to type as if this could be a ControlIcon, but Drawings don't use one
+    override controlIcon: null;
 
     /**
-     * Each Drawing object belongs to the DrawingsLayer
-     * @remarks it's possible this shouldn't be here and is some data model thing
+     * The texture that is used to fill this Drawing, if any.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw. Set `null` if the Drawing's document has no `texture` set
      */
-    get layer(): DrawingsLayer;
-
-    /**
-     * Each Drawing object provides an interface for a DrawingDocument
-     */
-    document: DrawingDocument;
+    texture: PIXI.Texture | null | undefined;
 
     /**
      * The border frame and resizing handles for the drawing.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw.
      */
-    frame: PIXI.Container;
+    frame: PIXI.Container | undefined;
 
     /**
      * A text label that may be displayed as part of the interface layer for the Drawing.
@@ -63,35 +31,19 @@ declare global {
     text: PreciseText | null;
 
     /**
-     * The primary drawing shape
-     * @defaultValue `null`
+     * The drawing shape which is rendered as a PIXI.Graphics in the interface or a PrimaryGraphics in the Primary Group.
+     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw.
      */
-    shape: PrimaryGraphics | PIXI.Graphics;
+    shape: PrimaryGraphics | PIXI.Graphics | undefined;
 
     static override embeddedName: "Drawing";
 
-    static override RENDER_FLAGS: {
-      /** @defaultValue `{ propagate: ["refresh"] }` */
-      redraw: RenderFlag<Drawing.RenderFlags>;
-
-      /** @defaultValue `{ propagate: ["refreshState", "refreshShape"], alias: true }` */
-      refresh: RenderFlag<Drawing.RenderFlags>;
-
-      /** @defaultValue `{ propagate: ["refreshFrame"] }` */
-      refreshState: RenderFlag<Drawing.RenderFlags>;
+    static override RENDER_FLAGS: Drawing.RENDER_FLAGS;
 
-      /** @defaultValue `{ propagate: ["refreshFrame", "refreshText", "refreshMesh"] }` */
-      refreshShape: RenderFlag<Drawing.RenderFlags>;
-
-      /** @defaultValue `{}` */
-      refreshFrame: RenderFlag<Drawing.RenderFlags>;
-
-      /** @defaultValue `{}` */
-      refreshText: RenderFlag<Drawing.RenderFlags>;
-
-      /** @defaultValue `{}` */
-      refreshMesh: RenderFlag<Drawing.RenderFlags>;
-    };
+    // Note: This isn't a "real" override but `renderFlags` is set corresponding to the
+    // `RENDER_FLAGS` and so it has to be adjusted here.
+    renderFlags: RenderFlags<Drawing.RENDER_FLAGS>;
 
     /**
      * The rate at which points are sampled (in milliseconds) during a freehand drawing workflow
@@ -102,7 +54,17 @@ declare global {
     /**
      * A convenience reference to the possible shape types.
      */
-    static readonly SHAPE_TYPES: (typeof foundry.data.ShapeData)["TYPES"];
+    static SHAPE_TYPES: foundry.data.ShapeData.TYPES;
+
+    /**
+     * A convenient reference for whether the current User is the author of the Drawing document.
+     */
+    get isAuthor(): boolean;
+
+    /**
+     * Is this Drawing currently visible on the Canvas?
+     */
+    get isVisible(): boolean;
 
     override get bounds(): PIXI.Rectangle;
 
@@ -126,143 +88,178 @@ declare global {
     /**
      * The shape type that this Drawing represents. A value in Drawing.SHAPE_TYPES.
      */
-    get type(): ValueOf<(typeof foundry.data.ShapeData)["TYPES"]>;
+    get type(): ValueOf<foundry.data.ShapeData.TYPES>;
 
-    override clear(): this;
+    /**
+     * The pending text.
+     * @defaultValue `undefined`
+     * @remarks Foundry marked `@internal`
+     */
+    protected _pendingText: string | undefined;
 
-    protected override _destroy(options?: PIXI.IDestroyOptions | boolean): void;
+    /**
+     * The registered keydown listener.
+     * @defaultValue `null`
+     * @remarks Foundry marked `@internal`
+     */
+    protected _onkeydown: ((event: KeyboardEvent) => void) | null;
+
+    protected override _destroy(options: PIXI.IDestroyOptions | boolean | undefined): void;
+
+    protected override _draw(options: HandleEmptyObject<Drawing.DrawOptions> | undefined): Promise<void>;
 
-    protected override _draw(options?: Record<string, unknown>): Promise<void>;
+    /**
+     * Get the line style used for drawing the shape of this Drawing.
+     * @returns The line style options (`PIXI.ILineStyleOptions`).
+     * @privateRemarks Foundry types this return as just `object` and then lists the correct interface this is a partial of in the `@returns`?!
+     */
+    protected _getLineStyle(): Drawing.LineStyleData;
+
+    /**
+     * Get the fill style used for drawing the shape of this Drawing.
+     * @returns The fill style options (`PIXI.IFillStyleOptions`).
+     * @privateRemarks Foundry types this return as just `object` and then lists the correct interface this is a partial of in the `@returns`?!
+     */
+    protected _getFillStyle(): Drawing.FillStyleData;
 
     /**
      * Prepare the text style used to instantiate a PIXI.Text or PreciseText instance for this Drawing document.
      */
     protected _getTextStyle(): PIXI.TextStyle;
 
+    override clone(): this;
+
+    // fake override; super has to account for misbehaving siblings returning void
+    override clear(): this;
+
     protected override _applyRenderFlags(flags: Drawing.RenderFlags): void;
 
     /**
-     * Draw ellipsoid shapes
-     * @internal
+     * Refresh the position.
      */
-    protected _drawEllipse(): void;
+    protected _refreshPosition(): void;
+
+    /**
+     * Refresh the rotation.
+     */
+    protected _refreshRotation(): void;
+
+    /**
+     * Refresh the displayed state of the Drawing.
+     * Used to update aspects of the Drawing which change based on the user interaction state.
+     */
+    protected _refreshState(): void;
+
+    /**
+     * Clear and then draw the shape.
+     */
+    protected _refreshShape(): void;
+
+    /**
+     * Update sorting of this Drawing relative to other PrimaryCanvasGroup siblings.
+     * Called when the elevation or sort order for the Drawing changes.
+     */
+    protected _refreshElevation(): void;
+
+    /**
+     * Refresh the border frame that encloses the Drawing.
+     */
+    protected _refreshFrame(): void;
+
+    /**
+     * Refresh the content and appearance of text.
+     */
+    protected _refreshText(): void;
 
     /**
      * Add a new polygon point to the drawing, ensuring it differs from the last one
      * @param position - The drawing point to add
      * @param options  - Options which configure how the point is added
-     * @internal
+     * @remarks Foundry marked `@internal`
      */
-    protected _addPoint(
-      position: Canvas.Point,
-      options?: {
-        /**
-         * Should the point be rounded to integer coordinates?
-         * @defaultValue `false`
-         */
-        round?: boolean;
-
-        /**
-         * Should the point be snapped to grid precision?
-         * @defaultValue `false`
-         */
-        snap?: boolean;
-
-        /**
-         * Is this a temporary control point?
-         * @defaultValue `false`
-         */
-        temporary?: boolean;
-      },
-    ): void;
+    // options: not null (destructured)
+    protected _addPoint(position: Canvas.Point, options?: Drawing.AddPointOptions): void;
 
     /**
      * Remove the last fixed point from the polygon
-     * @internal
+     * @remarks Foundry marked `@internal`
      */
     protected _removePoint(): void;
 
-    protected override _onControl(options: PlaceableObject.ControlOptions & Drawing.TextEditingOptions): void;
+    protected override _onControl(options: Drawing.ControlOptions): void;
+
+    protected override _onRelease(options: HandleEmptyObject<Drawing.ReleaseOptions>): void;
 
-    protected override _onRelease(options: PlaceableObject.ReleaseOptions): void;
+    protected override _overlapsSelection(rectangle: PIXI.Rectangle): boolean;
 
     /**
-     * @privateRemarks _onDelete and _onUpdate are overridden but with no signature changes.
-     * For type simplicity they are left off. These methods historically have been the source of a large amount of computation from tsc.
+     * Enable text editing for this drawing.
      */
+    enableTextEditing(options?: Drawing.EnableTextEditingOptions): void;
+
+    // _onUpdate and _onDelete are overridden but with no signature changes.
+    // For type simplicity they are left off. These methods historically have been the source of a large amount of computation from tsc.
 
     override activateListeners(): void;
 
-    /**
-     * @param event - unused
-     */
-    protected override _canControl(user: User.ConfiguredInstance, event?: any): boolean;
+    protected override _canControl(user: User.Implementation, _event: PIXI.FederatedEvent): boolean;
 
-    /**
-     * @param user  - unused
-     * @param event - unused
-     */
-    protected override _canConfigure(user: User.ConfiguredInstance, event?: any): boolean;
+    protected override _canConfigure(_user: User.Implementation, _event: PIXI.FederatedEvent): boolean;
+
+    // fake override to narrow the type from super, which had to account for this class's misbehaving siblings
+    // options: not null (destructured)
+    protected override _onHoverIn(event: PIXI.FederatedEvent, options?: PlaceableObject.HoverInOptions): void;
 
     /**
      * Handle mouse movement which modifies the dimensions of the drawn shape
-     * @internal
+     * @remarks Foundry marked `@internal`
      */
     protected _onMouseDraw(event: PIXI.FederatedEvent): void;
 
+    protected override _onClickLeft(event: PIXI.FederatedEvent): void;
+
     protected override _onDragLeftStart(event: PIXI.FederatedEvent): void;
 
     protected override _onDragLeftMove(event: PIXI.FederatedEvent): void;
 
-    // eslint-disable-next-line @typescript-eslint/no-misused-promises
-    protected override _onDragLeftDrop(event: PIXI.FederatedEvent): Promise<unknown>;
+    protected override _onDragLeftDrop(event: PIXI.FederatedEvent): void;
 
     protected override _onDragLeftCancel(event: PIXI.FederatedEvent): void;
 
+    // fake override to narrow the type from super, which had to account for this class's misbehaving siblings
+    protected override _prepareDragLeftDropUpdates(event: PIXI.FederatedEvent): PlaceableObject.DragLeftDropUpdate[];
+
     /**
      * Handle mouse-over event on a control handle
      * @param event - The mouseover event
-     * @internal
      */
     protected _onHandleHoverIn(event: PIXI.FederatedEvent): void;
 
     /**
      * Handle mouse-out event on a control handle
      * @param event - The mouseout event
-     * @internal
      */
     protected _onHandleHoverOut(event: PIXI.FederatedEvent): void;
 
-    /**
-     * When clicking the resize handle, initialize the drag property.
-     * @param event - The mousedown event
-     * @internal
-     */
-    protected _onHandleMouseDown(event: PIXI.FederatedEvent): void;
-
     /**
      * Starting the resize handle drag event, initialize the original data.
-     * @internal
      */
     protected _onHandleDragStart(event: PIXI.FederatedEvent): void;
 
     /**
      * Handle mousemove while dragging a tile scale handler
      * @param event - The mousemove event
-     * @internal
      */
     protected _onHandleDragMove(event: PIXI.FederatedEvent): void;
 
     /**
      * Handle mouseup after dragging a tile scale handler
      * @param event - The mouseup event
-     * @internal
      */
-    protected _onHandleDragDrop(event: PIXI.FederatedEvent): ReturnType<DrawingDocument.ConfiguredInstance["update"]>;
+    protected _onHandleDragDrop(event: PIXI.FederatedEvent): void;
 
     /**
      * Handle cancellation of a drag event for one of the resizing handles
-     * @internal
      */
     protected _onHandleDragCancel(event: PIXI.FederatedEvent): void;
 
@@ -272,9 +269,8 @@ declare global {
      * @param dx       - The pixel distance dragged in the horizontal direction
      * @param dy       - The pixel distance dragged in the vertical direction
      * @returns The adjusted shape data
-     * @internal
      */
-    static rescaleDimensions(original: Drawing.AdjustableShape, dx: number, dy: number): Drawing.AdjustableShape;
+    static rescaleDimensions(original: DrawingDocument.Source, dx: number, dy: number): DrawingDocument.Source;
 
     /**
      * Adjust the location, dimensions, and points of the Drawing before committing the change
@@ -283,11 +279,141 @@ declare global {
      * @remarks This is intentionally public because it is called by the DrawingsLayer
      * @internal
      */
-    static normalizeShape(data: Drawing.AdjustableShape): Drawing.AdjustableShape;
+    static normalizeShape(data: DrawingDocument.Source): DrawingDocument.Source;
+  }
+
+  namespace Drawing {
+    /**
+     * The implementation of the `Drawing` placeable configured through `CONFIG.Drawing.objectClass`
+     * in Foundry and {@link PlaceableObjectClassConfig | `PlaceableObjectClassConfig`} in fvtt-types.
+     *
+     * Not to be confused with {@link DrawingDocument.Implementation | `DrawingDocument.Implementation`}
+     * which refers to the implementation for the drawing document.
+     */
+    type Implementation = FixedInstanceType<ImplementationClass>;
+
+    /**
+     * The implementation of the `Drawing` placeable configured through `CONFIG.Drawing.objectClass`
+     * in Foundry and {@link PlaceableObjectClassConfig | `PlaceableObjectClassConfig`} in fvtt-types.
+     *
+     * Not to be confused with {@link DrawingDocument.ImplementationClass | `DrawingDocument.ImplementationClass`}
+     * which refers to the implementation for the drawing document.
+     */
+    // eslint-disable-next-line no-restricted-syntax
+    type ImplementationClass = ConfiguredObjectClassOrDefault<typeof Drawing>;
+
+    /**
+     * @deprecated {@link ImplementationClass | `ImplementationClass`}
+     */
+    type ObjectClass = ImplementationClass;
+
+    /**
+     * @deprecated {@link Implementation | `Implementation`}
+     */
+    type Object = Implementation;
+
+    /**
+     * @deprecated {@link Drawing.ImplementationClass | `Drawing.ImplementationClass`}
+     */
+    type ConfiguredClass = ImplementationClass;
 
     /**
-     * @remarks Not used
+     * @deprecated {@link Drawing.Implementation | `Drawing.Implementation`}
      */
-    controlIcon: null;
+    type ConfiguredInstance = Implementation;
+
+    interface RENDER_FLAGS {
+      /** @defaultValue `{ propagate: ["refresh"] }` */
+      redraw: RenderFlag<this, "redraw">;
+
+      /** @defaultValue `{ propagate: ["refreshState", "refreshTransform", "refreshText", "refreshElevation"], alias: true }` */
+      refresh: RenderFlag<this, "refresh">;
+
+      /** @defaultValue `{}` */
+      refreshState: RenderFlag<this, "refreshState">;
+
+      /** @defaultValue `{ propagate: ["refreshPosition", "refreshRotation", "refreshSize"], alias: true }` */
+      refreshTransform: RenderFlag<this, "refreshTransform">;
+
+      /** @defaultValue `{}` */
+      refreshPosition: RenderFlag<this, "refreshPosition">;
+
+      /** @defaultValue `{ propagate: ["refreshFrame"] }` */
+      refreshRotation: RenderFlag<this, "refreshRotation">;
+
+      /** @defaultValue `{ propagate: ["refreshPosition", "refreshFrame", "refreshShape", "refreshText"] }` */
+      refreshSize: RenderFlag<this, "refreshSize">;
+
+      /** @defaultValue `{}` */
+      refreshShape: RenderFlag<this, "refreshShape">;
+
+      /** @defaultValue `{}` */
+      refreshText: RenderFlag<this, "refreshText">;
+
+      /** @defaultValue `{}` */
+      refreshFrame: RenderFlag<this, "refreshFrame">;
+
+      /** @defaultValue `{}` */
+      refreshElevation: RenderFlag<this, "refreshElevation">;
+
+      /**
+       * @defaultValue
+       * ```js
+       * {
+       *   propagate: ["refreshTransform", "refreshShape", "refreshElevation"],
+       *   deprecated: { since: 12, until: 14, alias: true }
+       * }
+       * ```
+       * @deprecated since v12, until v14
+       * @remarks The `alias: true` should be a sibling of `deprecated`, not a child, this is a Foundry bug in 12.331
+       */
+      refreshMesh: RenderFlag<this, "refreshMesh">;
+    }
+
+    interface RenderFlags extends RenderFlagsMixin.ToBooleanFlags<RENDER_FLAGS> {}
+
+    interface DrawOptions extends PlaceableObject.DrawOptions {}
+
+    interface RefreshOptions extends PlaceableObject.RefreshOptions {}
+
+    interface ControlOptions extends _EnableTextEditingOptions, PlaceableObject.ControlOptions {}
+
+    interface ReleaseOptions extends PlaceableObject.ReleaseOptions {}
+
+    type LineStyleData = RequiredProps<PIXI.ILineStyleOptions, "width" | "color" | "alpha">;
+
+    /** @remarks Conditionally includes `texture`, which is already optional in the interface */
+    type FillStyleData = RequiredProps<PIXI.IFillStyleOptions, "color" | "alpha">;
+
+    /** @internal */
+    type _AddPointOptions = NullishProps<{
+      /**
+       * Should the point be rounded to integer coordinates?
+       * @defaultValue `false`
+       */
+      round: boolean;
+
+      /**
+       * Should the point be snapped to grid precision?
+       * @defaultValue `false`
+       */
+      snap: boolean;
+
+      /**
+       * Is this a temporary control point?
+       * @defaultValue `false`
+       */
+      temporary: boolean;
+    }>;
+
+    interface AddPointOptions extends _AddPointOptions {}
+
+    /** @internal */
+    type _EnableTextEditingOptions = NullishProps<{
+      forceTextEditing: boolean;
+      isNew: boolean;
+    }>;
+
+    interface EnableTextEditingOptions extends _EnableTextEditingOptions {}
   }
 }