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

package/src/foundry/client/pixi/layers/placeables/notes.d.mts

@@ -1,4 +1,4 @@
-import type { HandleEmptyObject, InexactPartial } from "fvtt-types/utils";
+import type { HandleEmptyObject, Identity, InexactPartial, NullishProps } from "fvtt-types/utils";
 
 declare global {
   /**
@@ -33,13 +33,14 @@ declare global {
      */
     static TOGGLE_SETTING: "notesDisplayToggle";
 
-    override get hookName(): string;
+    override get hookName(): "NotesLayer";
 
+    /** @defaultValue `game.settings.get("core", "notesDisplayToggle")` */
     override interactiveChildren: boolean;
 
-    override _deactivate(): void;
+    protected override _deactivate(): void;
 
-    override _draw(options: HandleEmptyObject<NotesLayer.DrawOptions>): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<NotesLayer.DrawOptions>): Promise<void>;
 
     /**
      * Register game settings used by the NotesLayer
@@ -58,51 +59,69 @@ declare global {
      * @returns A Promise which resolves once the pan animation has concluded.
      */
     panToNote(
-      note: Note,
-      /** @remarks Can't be NullishProps because `duration` is passed to `canvas.animatePan` which only provides a default for `undefined` with `{ duration=250 }`, and must be numeric */
-      options?: InexactPartial<{
-        /**
-         * The resulting zoom level.
-         * @defaultValue `1.5`
-         */
-        scale: number;
-
-        /**
-         * The speed of the pan animation in milliseconds.
-         * @defaultValue `250`
-         */
-        duration: number;
-      }>,
+      note: Note.Implementation,
+      options?: NotesLayer.PanToNoteOptions, // not:null (destructured)
     ): Promise<void>;
 
     // eslint-disable-next-line @typescript-eslint/no-misused-promises
-    protected override _onClickLeft(event: PIXI.FederatedEvent): Promise<Note | void>;
+    protected override _onClickLeft(event: PIXI.FederatedEvent): Promise<Note.Implementation | void>;
 
     /**
      * Handle JournalEntry document drop data
      */
-    protected _onDropData(event: DragEvent, data: NotesLayer.DropData): Promise<false | Note>;
+    protected _onDropData(event: DragEvent, data: NotesLayer.DropData): Promise<false | Note.Implementation>;
   }
 
   namespace NotesLayer {
-    type AnyConstructor = typeof AnyNotesLayer;
+    interface Any extends AnyNotesLayer {}
+    interface AnyConstructor extends Identity<typeof AnyNotesLayer> {}
 
     interface DrawOptions extends PlaceablesLayer.DrawOptions {}
 
-    interface LayerOptions extends PlaceablesLayer.LayerOptions<"Note"> {
+    interface LayerOptions extends PlaceablesLayer.LayerOptions<Note.ImplementationClass> {
       name: "notes";
       zIndex: 800;
     }
 
-    interface DropData<DocType extends "JournalEntry" | "JournalEntryPage" = "JournalEntry" | "JournalEntryPage">
-      extends Canvas.DropPosition {
-      type: DocType;
+    /** @internal */
+    interface _DropDataCommon {
       uuid: string;
-      anchor: DocType extends "JournalEntryPage" ? { name: string } : undefined;
     }
+
+    interface DropDataJournalEntry extends _DropDataCommon, Canvas.DropPosition {
+      type: "JournalEntry";
+    }
+
+    interface DropDataJournalEntryPage extends _DropDataCommon, Canvas.DropPosition {
+      type: "JournalEntryPage";
+      anchor: { name: string };
+    }
+
+    type DropData = DropDataJournalEntry | DropDataJournalEntryPage;
+
+    /** @internal */
+    type _PanToNoteOptions = NullishProps<{
+      /**
+       * The resulting zoom level.
+       * @defaultValue `1.5`
+       * @remarks The above is a parameter default only; `null` will be eventually be handled by
+       * {@link Canvas#_constrainView}, where it will be replaced with `canvas.stage.scale.x`
+       */
+      scale: number;
+    }> &
+      InexactPartial<{
+        /**
+         * The speed of the pan animation in milliseconds.
+         * @defaultValue `250`
+         * @remarks Can't be `null` as it only has a parameter default
+         */
+        duration: number;
+      }>;
+
+    interface PanToNoteOptions extends _PanToNoteOptions {}
   }
 }
 
 declare abstract class AnyNotesLayer extends NotesLayer {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/layers/placeables/regions.d.mts

@@ -1,4 +1,6 @@
-import type { EmptyObject, HandleEmptyObject } from "fvtt-types/utils";
+import type { HandleEmptyObject, Identity } from "fvtt-types/utils";
+import type Document from "#common/abstract/document.d.mts";
+import type DataModel from "#common/abstract/data.d.mts";
 
 declare global {
   /**
@@ -34,7 +36,7 @@ declare global {
 
     static override documentName: "Region";
 
-    override get hookName(): string;
+    override get hookName(): "RegionLayer";
 
     /** The RegionLegend application of this RegionLayer */
     get legend(): foundry.applications.ui.RegionLegend;
@@ -42,15 +44,19 @@ declare global {
     /**
      * Draw shapes as holes?
      * @defaultValue `false`
-     * @internal
+     * @remarks Foundry marked `@internal` but gets *and* sets it via the "hole" layer control toggle.
+     * Leaving public as this seems to be the source of truth for that.
      */
-    protected _holeMode: boolean;
+    _holeMode: boolean;
 
     protected override _activate(): void;
 
     protected override _deactivate(): void;
 
-    override storeHistory(type: PlaceablesLayer.HistoryEventType, data: EmptyObject[]): void;
+    override storeHistory<Operation extends Document.Database.Operation>(
+      type: Operation,
+      data: PlaceablesLayer.HistoryDataFor<Operation, "Region">,
+    ): void;
 
     /** @remarks Core overrides this returning an empty array to prevent copy & paste behavior. */
     override copyObjects(): [];
@@ -64,15 +70,15 @@ declare global {
     /**
      * Highlight the shape or clear the highlight.
      * @param data - The shape to highlight, or null to clear the highlight
-     * @internal
+     * @remarks Foundry marked `@internal`. If `data` is falsey, clears the current highly and returns early
      */
-    protected _highlightShape(data?: foundry.data.BaseShapeData | null): void;
+    protected _highlightShape(data?: DataModel.ConstructorDataFor<foundry.data.BaseShapeData> | null): void;
 
     protected override _onClickLeft(event: PIXI.FederatedEvent): void;
 
     protected override _onClickLeft2(event: PIXI.FederatedEvent): void;
 
-    protected override _canDragLeftStart(user: User.ConfiguredInstance, event: PIXI.FederatedEvent): boolean;
+    protected override _canDragLeftStart(user: User.Implementation, event: PIXI.FederatedEvent): boolean;
 
     protected override _onDragLeftStart(event: PIXI.FederatedEvent): void;
 
@@ -86,15 +92,22 @@ declare global {
   }
 
   namespace RegionLayer {
-    type AnyConstructor = typeof AnyRegionLayer;
-    type Any = AnyRegionLayer;
+    interface Any extends AnyRegionLayer {}
+    interface AnyConstructor extends Identity<typeof AnyRegionLayer> {}
 
     interface DrawOptions extends PlaceablesLayer.DrawOptions {}
 
-    interface LayerOptions extends PlaceablesLayer.LayerOptions<"Region"> {}
+    interface LayerOptions extends PlaceablesLayer.LayerOptions<Region.ImplementationClass> {
+      name: "regions";
+      controllableObjects: true;
+      confirmDeleteKey: true;
+      quadtree: false;
+      zIndex: 100;
+      zIndexActive: 600;
+    }
   }
 }
 
 declare abstract class AnyRegionLayer extends RegionLayer {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/layers/placeables/sounds.d.mts

@@ -1,5 +1,5 @@
-import type { IntentionalPartial, InexactPartial, NullishProps, HandleEmptyObject } from "fvtt-types/utils";
-import type { AmbientSoundEffect } from "../../../../common/documents/_types.d.mts";
+import type { IntentionalPartial, InexactPartial, NullishProps, HandleEmptyObject, Identity } from "fvtt-types/utils";
+import type { AmbientSoundEffect } from "#common/documents/_types.d.mts";
 
 declare global {
   /**
@@ -21,7 +21,7 @@ declare global {
      * A mapping of ambient audio sources which are active within the rendered Scene
      * @defaultValue `new foundry.utils.Collection()`
      */
-    sources: foundry.utils.Collection<foundry.canvas.sources.PointSoundSource>;
+    sources: foundry.utils.Collection<foundry.canvas.sources.PointSoundSource.Any>;
 
     /**
      * @privateRemarks This is not overridden in foundry but reflects the real behavior.
@@ -42,13 +42,13 @@ declare global {
 
     static override documentName: "AmbientSound";
 
-    override get hookName(): string;
+    override get hookName(): "SoundsLayer";
 
-    override _draw(options: HandleEmptyObject<SoundsLayer.DrawOptions>): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<SoundsLayer.DrawOptions>): Promise<void>;
 
-    override _tearDown(options: HandleEmptyObject<SoundsLayer.TearDownOptions>): Promise<void>;
+    protected override _tearDown(options: HandleEmptyObject<SoundsLayer.TearDownOptions>): Promise<void>;
 
-    override _activate(): void;
+    protected override _activate(): void;
 
     /**
      * Initialize all AmbientSound sources which are present on this layer
@@ -60,15 +60,9 @@ declare global {
      * Sync audio for the positions of tokens which are capable of hearing.
      * @param options - Additional options forwarded to AmbientSound synchronization
      *                  (defaultValue: `{}`)
+     * @remarks Probably meant to be treated as always `void`; the `number` return is from an `Array#push` call, not anything meaningful
      */
-    refresh(
-      options?: NullishProps<{
-        /**
-         * A duration in milliseconds to fade volume transition
-         */
-        fade: number;
-      }>,
-    ): number | void;
+    refresh(options?: SoundsLayer.RefreshOptions): number | void;
 
     /**
      * Preview ambient audio for a given mouse cursor position
@@ -83,8 +77,9 @@ declare global {
 
     /**
      * Get an array of listener positions for Tokens which are able to hear environmental sound.
+     * @remarks Returns an array of `token.center`s, so actual `PIXI.Point`s for once
      */
-    getListenerPositions(): Canvas.Point[];
+    getListenerPositions(): PIXI.Point[];
 
     /**
      * Sync the playing state and volume of all AmbientSound objects based on the position of listener points
@@ -92,15 +87,7 @@ declare global {
      * @param options   - Additional options forwarded to AmbientSound synchronization
      *                    (defaultValue: `{}`)
      */
-    protected _syncPositions(
-      listeners: Canvas.Point[],
-      options?: NullishProps<{
-        /**
-         * A duration in milliseconds to fade volume transition
-         */
-        fade: number;
-      }>,
-    ): void;
+    protected _syncPositions(listeners: PIXI.Point[], options?: SoundsLayer.SyncPositionsOptions | null): void;
 
     /**
      * Configure playback by assigning the muffled state and final playback volume for the sound.
@@ -156,10 +143,10 @@ declare global {
      */
     playAtPosition(
       src: string,
+      /** @privateRemarks The examples in the docs show passing a simple `{x, y}` object here, so unlike other places in this layer `Canvas.Point` is appropriate */
       origin: Canvas.Point,
       radius: number,
-      /** @remarks Can't be NullishProps because a default for `volume` is provided only for `undefined` with `{ volume=1 }`, which must be numeric */
-      options?: InexactPartial<SoundsLayer.PlayAtPositionOptions>,
+      options?: SoundsLayer.PlayAtPositionOptions, // not:null (destructured)
     ): Promise<foundry.audio.Sound | null>;
 
     /**
@@ -187,20 +174,18 @@ declare global {
      * @param event - The drag drop event
      * @param data  - The dropped transfer data.
      */
-    protected _onDropData(
-      event: DragEvent,
-      data: SoundsLayer.DropData,
-    ): Promise<ReturnType<PlaceablesLayer<"AmbientSound">["_createPreview"]> | false>;
+    protected _onDropData(event: DragEvent, data: SoundsLayer.DropData): Promise<AmbientSound.Implementation | false>;
   }
 
   namespace SoundsLayer {
-    type AnyConstructor = typeof AnySoundsLayer;
+    interface Any extends AnySoundsLayer {}
+    interface AnyConstructor extends Identity<typeof AnySoundsLayer> {}
 
     interface DrawOptions extends PlaceablesLayer.DrawOptions {}
 
     interface TearDownOptions extends PlaceablesLayer.TearDownOptions {}
 
-    interface LayerOptions extends PlaceablesLayer.LayerOptions<"AmbientSound"> {
+    interface LayerOptions extends PlaceablesLayer.LayerOptions<AmbientSound.ImplementationClass> {
       name: "sounds";
       zIndex: 900;
     }
@@ -210,25 +195,28 @@ declare global {
       uuid: string;
     }
 
-    interface PlayAtPositionOptions {
+    /** @internal */
+    type _Fade = NullishProps<{
       /**
-       * The maximum volume at which the effect should be played
-       * @defaultValue `1.0`
+       * A duration in milliseconds to fade volume transition
+       * @defaultValue `250`
+       * @remarks The above is only a parameter default; `null` is treated as `0`
        */
-      volume: number;
+      fade: number;
+    }>;
+
+    interface RefreshOptions extends _Fade {}
 
+    interface SyncPositionsOptions extends _Fade {}
+
+    /** @internal */
+    type _PlayAtPositionOptions = NullishProps<{
       /**
        * Should volume be attenuated by distance?
        * @defaultValue `true`
        */
       easing: boolean;
 
-      /**
-       * Should the sound be constrained by walls?
-       * @defaultValue `true`
-       */
-      walls: boolean;
-
       /**
        * Should the sound always be played for GM users regardless of actively controlled tokens?
        * @defaultValue `true`
@@ -243,54 +231,84 @@ declare global {
 
       /**
        * Additional data passed to the SoundSource constructor
-       * @remarks IntentionalPartial because this is spread into an object with existing keys
+       * @remarks `IntentionalPartial` because this is spread into an object with existing `x`, `y`, `radius`, and `walls` keys
        */
       sourceData: IntentionalPartial<PointSourceData>;
 
-      /** Additional options passed to Sound#play */
+      /**
+       * Additional options passed to Sound#play
+       * @remarks The `loop` and `volume` keys will be overwritten
+       */
       playbackOptions: foundry.audio.Sound.PlaybackOptions;
-    }
+    }> &
+      InexactPartial<{
+        /**
+         * The maximum volume at which the effect should be played
+         * @defaultValue `1`
+         * @remarks Can't be `null` because it only has a parameter default
+         */
+        volume: number;
+
+        /**
+         * Should the sound be constrained by walls?
+         * @defaultValue `true`
+         * @remarks Can't be `null` as it gets passed to `PointSoundSource.ConfiguredInstance#initialize`
+         */
+        walls: boolean;
+      }>;
+
+    interface PlayAtPositionOptions extends _PlayAtPositionOptions {}
 
-    interface AmbientSoundPlaybackConfig {
+    /** @internal */
+    type _AmbientSoundPlaybackConfig = NullishProps<{
       /**
-       * The Sound node which should be controlled for playback
+       * Is playback constrained or muffled by walls?
+       * @remarks Falsey is *possibly* muffled, truthy is definitely constrained
        */
-      sound: foundry.audio.Sound;
+      walls: boolean;
 
       /**
-       * The SoundSource which defines the area of effect for the sound
+       * The coordinates of the closest listener or undefined if there is none
+       * @remarks If falsey, `volume` is set to `0`
+       *
+       * One of the rare times Foundry actually wants a `PIXI.Point`, as it calls `listener#equals(source)`
        */
-      source: foundry.canvas.sources.PointSoundSource;
+      listener: PIXI.Point;
+    }>;
 
+    /** @privateRemarks The only place this is used outside of variables entirely internal to function bodies in Foundry code is as a parameter for `#_configurePlayback` */
+    interface AmbientSoundPlaybackConfig extends _AmbientSoundPlaybackConfig {
       /**
-       * An AmbientSound object responsible for the sound, or undefined
+       * The Sound node which should be controlled for playback
        */
-      object: AmbientSound | undefined;
+      sound?: foundry.audio.Sound;
 
       /**
-       * The coordinates of the closest listener or undefined if there is none
+       * The SoundSource which defines the area of effect for the sound
        */
-      listener: Canvas.Point | undefined;
+      source: foundry.canvas.sources.PointSoundSource.ConfiguredInstance;
 
       /**
-       * The minimum distance between a listener and the AmbientSound origin
+       * An AmbientSound object responsible for the sound, or undefined
        */
-      distance: number;
+      object?: AmbientSound.Implementation;
 
       /**
-       * Is the closest listener muffled
+       * The minimum distance between a listener and the AmbientSound origin
+       * @remarks Entirely unused in 12.331
        */
-      muffled: boolean;
+      distance?: number;
 
       /**
-       * Is playback constrained or muffled by walls?
+       * Is the closest listener muffled
+       * @remarks Always overwritten in `#_configurePlayback`, never required to be passed
        */
-      walls: boolean;
+      muffled?: boolean;
 
       /**
        * The final volume at which the Sound should be played
        */
-      volume: number;
+      volume?: number;
     }
   }
 }
@@ -312,5 +330,5 @@ interface PointSourceData {
 }
 
 declare abstract class AnySoundsLayer extends SoundsLayer {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/layers/placeables/templates.d.mts

@@ -1,8 +1,8 @@
-import type { HandleEmptyObject } from "fvtt-types/utils";
+import type { HandleEmptyObject, Identity } from "fvtt-types/utils";
 
 /**
  * This Canvas Layer provides a container for MeasuredTemplate objects.
- * @see {@link MeasuredTemplate}
+ * @see {@link MeasuredTemplate | `MeasuredTemplate`}
  */
 declare global {
   class TemplateLayer extends PlaceablesLayer<"MeasuredTemplate"> {
@@ -30,11 +30,11 @@ declare global {
 
     static override documentName: "MeasuredTemplate";
 
-    override get hookName(): string;
+    override get hookName(): "TemplateLayer";
 
-    override _deactivate(): void;
+    protected override _deactivate(): void;
 
-    override _draw(options: HandleEmptyObject<TemplateLayer.DrawOptions>): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<TemplateLayer.DrawOptions>): Promise<void>;
 
     /**
      * Register game settings used by the TemplatesLayer
@@ -46,17 +46,16 @@ declare global {
     protected override _onDragLeftMove(event: PIXI.FederatedEvent): void;
 
     // @ts-expect-error Foundry is changing the return type here from Promise<PlaceableObject[]> to Promise<MeasuredTemplate>
-    protected override _onMouseWheel(
-      event: WheelEvent,
-    ): ReturnType<MeasuredTemplate.ConfiguredInstance["rotate"]> | void;
+    protected override _onMouseWheel(event: WheelEvent): Promise<MeasuredTemplate.Implementation> | void;
   }
 
   namespace TemplateLayer {
-    type AnyConstructor = typeof AnyTemplateLayer;
+    interface Any extends AnyTemplateLayer {}
+    interface AnyConstructor extends Identity<typeof AnyTemplateLayer> {}
 
     interface DrawOptions extends PlaceablesLayer.DrawOptions {}
 
-    interface LayerOptions extends PlaceablesLayer.LayerOptions<"MeasuredTemplate"> {
+    interface LayerOptions extends PlaceablesLayer.LayerOptions<MeasuredTemplate.ImplementationClass> {
       name: "templates";
       rotatableObjects: true;
       zIndex: 400;
@@ -65,5 +64,5 @@ declare global {
 }
 
 declare abstract class AnyTemplateLayer extends TemplateLayer {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/layers/placeables/tiles.d.mts

@@ -1,5 +1,4 @@
-import type { HandleEmptyObject } from "../../../../../utils/index.d.mts";
-import type BaseTile from "../../../../common/documents/tile.d.mts";
+import type { HandleEmptyObject, Identity } from "fvtt-types/utils";
 
 declare global {
   /**
@@ -28,16 +27,20 @@ declare global {
      */
     static override get layerOptions(): TilesLayer.LayerOptions;
 
-    override get hookName(): string;
+    override get hookName(): "TilesLayer";
 
-    override get hud(): TileHUD;
+    override get hud(): NonNullable<Canvas["hud"]>["tile"];
 
     /**
      * An array of Tile objects which are rendered within the objects container
      */
-    get tiles(): Tile.ConfiguredInstance[];
+    get tiles(): Tile.Implementation[];
 
-    override controllableObjects(): Generator<Tile.ConfiguredInstance>;
+    /**
+     * @remarks Only produces foreground or non-forground tiles, depending on the state
+     * of the foregound layer toggle control
+     */
+    override controllableObjects(): Generator<Tile.Implementation>;
 
     override getSnappedPoint(point: Canvas.Point): Canvas.Point;
 
@@ -55,11 +58,12 @@ declare global {
      * Handle drop events for Tile data on the Tiles Layer
      * @param event - The concluding drag event
      * @param data  - The extracted Tile data
+     * @remarks Foundry marked `@private`
      */
     protected _onDropData(
       event: DragEvent,
-      data: BaseTile.ConstructorData,
-    ): Promise<TileDocument.ConfiguredInstance | false | void>;
+      data: TilesLayer.DropData,
+    ): Promise<TileDocument.Implementation | false | void>;
 
     /**
      * Prepare the data object when a new Tile is dropped onto the canvas
@@ -67,48 +71,55 @@ declare global {
      * @param data  - The extracted Tile data
      * @returns The prepared data to create
      */
-    _getDropData(event: DragEvent, data: BaseTile.ConstructorData): Promise<BaseTile.ConstructorData>;
+    protected _getDropData(event: DragEvent, data: TilesLayer.DropData): Promise<TileDocument.CreateData>;
 
     /**
      * Get an array of overhead Tile objects which are roofs
      * @deprecated since v12 until v14
      * @remarks "TilesLayer#roofs has been deprecated without replacement."
      */
-    get roofs(): Tile.ConfiguredInstance[];
+    get roofs(): Tile.Implementation[];
 
     /**
      * @deprecated since v11, will be removed in v13
      * @remarks "TilesLayer#textureDataMap has moved to TextureLoader.textureBufferDataMap"
      */
-    get textureDataMap(): (typeof TextureLoader)["textureBufferDataMap"];
+    get textureDataMap(): Map<unknown, unknown>;
 
     /**
      * A convenience reference to the tile occlusion mask on the primary canvas group.
      * @deprecated since v11 until v13
      * @remarks "TilesLayer#depthMask is deprecated without replacement. Use canvas.masks.depth instead"
      */
-    get depthMask(): CachedContainer;
+    get depthMask(): CanvasDepthMask.Any;
   }
 
   namespace TilesLayer {
-    type AnyConstructor = typeof AnyTilesLayer;
+    interface Any extends AnyTilesLayer {}
+    interface AnyConstructor extends Identity<typeof AnyTilesLayer> {}
 
     interface TearDownOptions extends PlaceablesLayer.TearDownOptions {}
 
-    interface LayerOptions extends PlaceablesLayer.LayerOptions<"Tile"> {
+    interface LayerOptions extends PlaceablesLayer.LayerOptions<Tile.ImplementationClass> {
       name: "tiles";
       zIndex: 300;
       controllableObjects: true;
       rotatableObjects: true;
     }
 
-    interface DropData extends Canvas.DropPosition {
+    /** @internal  */
+    type _DropData = Required<Pick<TileDocument.CreateData, "elevation" | "height" | "width" | "sort">>;
+
+    interface DropData extends Canvas.DropPosition, _DropData {
       type: "Tile";
-      uuid: string;
+      fromFilePicker: boolean;
+      tileSize: number;
+      texture: { src: string };
+      occlusion: { mode: foundry.CONST.OCCLUSION_MODES };
     }
   }
 }
 
 declare abstract class AnyTilesLayer extends TilesLayer {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }