@league-of-foundry-developers/foundry-vtt-types 12.331.3-beta → 12.331.4-beta

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

@@ -1,15 +1,11 @@
-import type { IntentionalPartial } from "../../../../../types/helperTypes.d.mts";
-import type { InexactPartial, NullishProps } from "../../../../../types/utils.d.mts";
+import type { IntentionalPartial, InexactPartial, NullishProps, HandleEmptyObject, Identity } from "fvtt-types/utils";
 import type { AmbientSoundEffect } from "../../../../common/documents/_types.d.mts";
 
 declare global {
   /**
    * This Canvas Layer provides a container for AmbientSound objects.
    */
-  class SoundsLayer<
-    DrawOptions extends SoundsLayer.DrawOptions = SoundsLayer.DrawOptions,
-    TearDownOptions extends SoundsLayer.TearDownOptions = SoundsLayer.TearDownOptions,
-  > extends PlaceablesLayer<"AmbientSound", DrawOptions, TearDownOptions> {
+  class SoundsLayer extends PlaceablesLayer<"AmbientSound"> {
     /**
      * @privateRemarks This is not overridden in foundry but reflects the real behavior.
      */
@@ -25,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.
@@ -46,13 +42,13 @@ declare global {
 
     static override documentName: "AmbientSound";
 
-    override get hookName(): string;
+    override get hookName(): "SoundsLayer";
 
-    override _draw(options?: DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<SoundsLayer.DrawOptions>): Promise<void>;
 
-    override _tearDown(options?: 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
@@ -64,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
@@ -87,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
@@ -96,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.
@@ -160,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>;
 
     /**
@@ -191,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.Object | 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.ObjectClass> {
       name: "sounds";
       zIndex: 900;
     }
@@ -214,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`
@@ -247,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.Object;
 
       /**
-       * 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;
     }
   }
 }
@@ -316,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,14 +1,11 @@
-export {};
+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<
-    DrawOptions extends TemplateLayer.DrawOptions = TemplateLayer.DrawOptions,
-    TearDownOptions extends PlaceablesLayer.TearDownOptions = PlaceablesLayer.TearDownOptions,
-  > extends PlaceablesLayer<"MeasuredTemplate", DrawOptions, TearDownOptions> {
+  class TemplateLayer extends PlaceablesLayer<"MeasuredTemplate"> {
     /**
      * @privateRemarks This is not overridden in foundry but reflects the real behavior.
      */
@@ -33,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?: DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<TemplateLayer.DrawOptions>): Promise<void>;
 
     /**
      * Register game settings used by the TemplatesLayer
@@ -49,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.Object> | 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.ObjectClass> {
       name: "templates";
       rotatableObjects: true;
       zIndex: 400;
@@ -68,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,13 +1,10 @@
-import type BaseTile from "../../../../common/documents/tile.d.mts";
+import type { HandleEmptyObject, Identity } from "fvtt-types/utils";
 
 declare global {
   /**
    * A PlaceablesLayer designed for rendering the visual Scene for a specific vertical cross-section.
    */
-  class TilesLayer<
-    DrawOptions extends PlaceablesLayer.DrawOptions = PlaceablesLayer.DrawOptions,
-    TearDownOptions extends TilesLayer.TearDownOptions = TilesLayer.TearDownOptions,
-  > extends PlaceablesLayer<"Tile", DrawOptions, TearDownOptions> {
+  class TilesLayer extends PlaceablesLayer<"Tile"> {
     /**
      * @privateRemarks This is not overridden in foundry but reflects the real behavior.
      */
@@ -30,20 +27,24 @@ 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.Object[];
 
-    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.Object>;
 
     override getSnappedPoint(point: Canvas.Point): Canvas.Point;
 
-    protected override _tearDown(options?: TearDownOptions): Promise<void>;
+    protected override _tearDown(options: HandleEmptyObject<TilesLayer.TearDownOptions>): Promise<void>;
 
     protected override _onDragLeftStart(event: PIXI.FederatedEvent): void;
 
@@ -57,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
@@ -69,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.Object[];
 
     /**
      * @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.ObjectClass> {
       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);
 }