@league-of-foundry-developers/foundry-vtt-types 9.255.1 → 9.268.0

package/src/foundry/foundry.js/handlebarsHelpers.d.ts

@@ -7,6 +7,23 @@ declare class HandlebarsHelpers {
    */
   static checked(value: unknown): string;
 
+  /**
+   * For use in form inputs. If the supplied value is truthy, add the "disabled" property, otherwise add nothing.
+   */
+  static disabled(value: unknown): string;
+
+  /**
+   * Concatenate a number of string terms into a single string.
+   * This is useful for passing arguments with variable names.
+   * @param values - The values to concatenate
+   *
+   * @example <caption>Concatenate several string parts to create a dynamic variable</caption>
+   * ```handlebars
+   * {{filePicker target=(concat "faces." i ".img") type="image"}}
+   * ```
+   */
+  static concat(...values: string[]): Handlebars.SafeString;
+
   /**
    * Render a pair of inputs for selecting a color.
    * @param options - Helper options
@@ -31,12 +48,15 @@ declare class HandlebarsHelpers {
    * @example <caption>Translate a provided localization string, optionally including formatting parameters</caption>
    * ```handlebars
    * <label>{{localize "ACTOR.Create"}}</label> <!-- "Create Actor" -->
-   * <label>{{localize "CHAT.InvalidCommand", command=foo}}</label> <!-- "foo is not a valid chat message command." -->
+   * <label>{{localize "CHAT.InvalidCommand" command=foo}}</label> <!-- "foo is not a valid chat message command." -->
    * ```
    */
   static localize(value: string, options: HandlebarsHelpers.LocalizeOptions): string;
 
   /**
+   * @param value   - A numeric value to format
+   * @param options - Additional options which customize the resulting format
+   * @returns The formatted string to be included in a template
    * A string formatting helper to display a number with a certain fixed number of decimals and an explicit sign.
    */
   static numberFormat(value: string, options: HandlebarsHelpers.NumberFormatOptions): string;
@@ -78,7 +98,7 @@ declare class HandlebarsHelpers {
   ): Handlebars.SafeString;
 
   /**
-   * Render a pair of inputs for selecting a color.
+   * Render a pair of inputs for selecting a value in a range.
    * @param options - Helper options
    */
   static rangePicker(options: HandlebarsHelpers.RangePickerOptions): Handlebars.SafeString;
@@ -206,10 +226,10 @@ declare namespace HandlebarsHelpers {
       editable?: boolean;
 
       /**
-       * Replace dynamic entity links?
+       * Replace dynamic document links?
        * @defaultValue `true`
        */
-      entities?: boolean;
+      documents?: boolean;
 
       /**
        * The data object providing context for inline rolls
@@ -245,11 +265,13 @@ declare namespace HandlebarsHelpers {
   interface NumberFormatOptions extends Handlebars.HelperOptions {
     hash: {
       /**
+       * The number of decimal places to include in the resulting string
        * @defaultValue `0`
        */
       decimals?: number;
 
       /**
+       * Whether to include an explicit "+" sign for positive numbers
        * @defaultValue `false`
        */
       sign?: boolean;

package/src/foundry/foundry.js/mouseInteractionManager.d.ts

@@ -96,7 +96,7 @@ declare class MouseInteractionManager<Object extends PIXI.Container = PIXI.Conta
 
   /**
    * The throttling time below which a mouse move event will not be handled
-   * @defaultValue `Math.ceil(1000 / canvas.app.ticker.maxFPS)`
+   * @defaultValue `Math.ceil(1000 / (canvas.app.ticker.maxFPS || 60));`
    * @internal
    */
   protected _dragThrottleMS: number;

package/src/foundry/foundry.js/perceptionManager.d.ts

@@ -92,7 +92,7 @@ declare namespace PerceptionManager {
     sight: {
       initialize: boolean;
       refresh: boolean;
-      noUpdateFog: boolean;
+      skipUpdateFog: boolean;
       forceUpdateFog: boolean;
     };
     sounds: {

package/src/foundry/foundry.js/pixi/containers/canvasLayer.d.ts

@@ -53,8 +53,9 @@ declare abstract class CanvasLayer<Options extends CanvasLayerOptions = CanvasLa
 
   /**
    * Deconstruct data used in the current layer in preparation to re-draw the canvas
+   * @remarks ControlsLayer returns void. See https://gitlab.com/foundrynet/foundryvtt/-/issues/6939
    */
-  tearDown(): Promise<this>;
+  tearDown(): Promise<this | void>;
 
   /**
    * Activate the CanvasLayer, deactivating other layers and marking this layer's children as interactive.

package/src/foundry/foundry.js/pixi/containers/canvasLayers/controlsLayer.d.ts

@@ -1,69 +1,76 @@
-/**
- * A CanvasLayer for displaying UI controls which are overlayed on top of other layers.
- *
- * We track three types of events:
- * 1) Cursor movement
- * 2) Ruler measurement
- * 3) Map pings
- */
-import { ConfiguredDocumentClass, ConfiguredObjectClassForName } from '../../../../../types/helperTypes';
+import { ConfiguredDocumentClass } from '../../../../../types/helperTypes';
 
 declare global {
+  /**
+   * A CanvasLayer for displaying UI controls which are overlayed on top of other layers.
+   *
+   * We track three types of events:
+   * 1) Cursor movement
+   * 2) Ruler measurement
+   * 3) Map pings
+   */
   class ControlsLayer extends CanvasLayer<ControlsLayer.LayerOptions> {
     constructor();
 
     /**
-     * Cursor position indicators
-     * @defaultValue `null`
+     * A container of DoorControl instances
+     * @defaultValue `this.addChild(new PIXI.Container())`
      */
-    cursors: PIXI.Container | null;
+    doors: PIXI.Container;
 
     /**
-     * A mapping of user IDs to Cursor instances for quick access
-     * @defaultValue `{}`
-     */
-    protected _cursors: Partial<Record<string, Cursor>>;
-
-    /**
-     * Door control icons
-     * @defaultValue `null`
+     * A container of HUD interface elements
+     * @defaultValue `this.addChild(new PIXI.Container())`
      */
-    doors: PIXI.Container | null;
+    hud: PIXI.Container;
 
     /**
-     * Status effect icons
-     * @remarks Always `null`
+     * A container of cursor interaction elements.
+     * Contains cursors, rulers, interaction rectangles, and pings
+     * @defaultValue `this.addChild(new PIXI.Container())`
      */
-    effects: null;
+    cursors: PIXI.Container;
 
     /**
      * Ruler tools, one per connected user
-     * @defaultValue `null`
+     * @defaultValue `this.addChild(new PIXI.Container())`
      */
-    rulers: PIXI.Container | null;
+    rulers: PIXI.Container;
 
     /**
-     * A convenience mapping of user IDs to Ruler instances for quick access
+     * A graphics instance used for drawing debugging visualization
+     * @defaultValue `this.addChild(new PIXI.Graphics())`
      */
-    protected _rulers: Partial<Record<string, Ruler>>;
+    debug: PIXI.Graphics;
 
     /**
      * Canvas selection rectangle
-     * @defaultValue `null`
+     * @defaultValue `undefined`
      */
-    select: PIXI.Graphics | null;
+    select: PIXI.Graphics | undefined;
 
-    // The controls layer is always interactive
-    interactiveChildren: true;
+    /**
+     * A mapping of user IDs to Cursor instances for quick access
+     * @defaultValue `{}`
+     */
+    protected _cursors: Record<string, Cursor>;
 
     /**
-     * @remarks This is not overridden in foundry but reflects the real behavior.
+     * A convenience mapping of user IDs to Ruler instances for quick access
+     * @internal
+     * @defaultValue `{}`
      */
-    static get instance(): undefined;
+    protected _rulers: Record<string, Ruler>;
 
     /**
      * @override
-     * @defaultValue `mergeObject(super.layerOptions, { name: "controls", zIndex: 1000 })`
+     * @defaultValue
+     * ```typescript
+     * foundry.utils.mergeObject(super.layerOptions, {
+     *   name: "controls",
+     *   zIndex: 1000
+     * })
+     * ```
      */
     static get layerOptions(): ControlsLayer.LayerOptions;
 
@@ -78,24 +85,18 @@ declare global {
     getRulerForUser(userId: string): Ruler | null;
 
     /** @override */
-    draw(): this;
-
-    /**
-     * Draw the cursors container
-     */
-    drawCursors(): void;
+    draw(): Promise<this>;
 
     /**
-     * Draw the Door controls container
+     * @override
+     * @remarks This breaks polymorphism. See https://gitlab.com/foundrynet/foundryvtt/-/issues/6939
      */
-    drawDoors(): void;
+    tearDown(): Promise<void>;
 
     /**
-     * Create a Door Control icon for a given Wall object
-     * @param wall - The Wall for which to create a DoorControl
-     * @returns The created DoorControl
+     * Draw the cursors container
      */
-    createDoorControl(wall: InstanceType<ConfiguredObjectClassForName<'Wall'>>): ReturnType<DoorControl['draw']> | null;
+    drawCursors(): void;
 
     /**
      * Draw Ruler tools
@@ -118,7 +119,7 @@ declare global {
 
     /**
      * Create and draw the Cursor object for a given User
-     * @param user - The User entity for whom to draw the cursor Container
+     * @param user - The User document for whom to draw the cursor Container
      */
     drawCursor(user: InstanceType<ConfiguredDocumentClass<typeof User>>): Cursor;
 

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayer.d.ts

@@ -1,9 +1,9 @@
 import {
   DataSourceForPlaceable,
-  ConfiguredDocumentClass,
   ConfiguredObjectClassForName,
   ConfiguredDocumentClassForName,
-  PlaceableDocumentType
+  PlaceableDocumentType,
+  ConstructorDataType
 } from '../../../../../types/helperTypes';
 import EmbeddedCollection from '../../../../common/abstract/embedded-collection.mjs';
 
@@ -78,6 +78,16 @@ declare global {
      */
     static documentName: PlaceableDocumentType;
 
+    /**
+     * 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
      */
@@ -130,7 +140,7 @@ declare global {
      */
     createObject(
       data: InstanceType<ConfiguredDocumentClassForName<DocumentName>>
-    ): InstanceType<ConfiguredObjectClassForName<DocumentName>>;
+    ): InstanceType<ConfiguredObjectClassForName<DocumentName>> | null;
 
     /** @override */
     tearDown(): Promise<this>;
@@ -141,6 +151,11 @@ declare global {
     /** @override */
     deactivate(): this;
 
+    /**
+     * Clear the contents of the preview container, restoring visibility of original (non-preview) objects.
+     */
+    clearPreviewContainer(): void;
+
     /**
      * Get a PlaceableObject contained in this layer by it's ID
      *
@@ -246,7 +261,7 @@ declare global {
      * @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 Entity.update
+     * @param options        - Additional options passed to Document.update
      *                         (default: `{}`)
      * @returns An array of updated data once the operation is complete
      */
@@ -268,6 +283,35 @@ declare global {
       options?: DocumentModificationContext
     ): Promise<Array<InstanceType<ConfiguredDocumentClassForName<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,
+      {
+        center
+      }?:
+        | {
+            /**
+             * Return the co-ordinates of the center of the nearest grid element.
+             * @defaultValue `true`
+             */
+            center?: boolean | undefined;
+          }
+        | undefined
+    ): [tx: number, ty: number] | false;
+
+    /**
+     * Create a preview of this layer's object type from a world document and show its sheet so it can be finalized.
+     * @param createData - The data to create the object with.
+     * @param position   - The position to render the sheet at.
+     */
+    protected _createPreview(
+      createData: ConstructorDataType<InstanceType<ConfiguredDocumentClassForName<DocumentName>>['data']>,
+      { top, left }: { top: number; left: number }
+    ): Promise<void>;
+
     /**
      * Handle left mouse-click events which originate from the Canvas stage and are dispatched to this Layer.
      * @param event - (unused)
@@ -327,35 +371,6 @@ declare global {
      *                (unused)
      */
     protected _onDeleteKey(event?: any): void;
-
-    /**
-     * @deprecated since 0.8.0
-     */
-    static get dataArray(): string;
-
-    /**
-     * @deprecated since 0.8.0
-     */
-    createMany(
-      data: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['createEmbeddedDocuments']>[1],
-      options: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['createEmbeddedDocuments']>[2]
-    ): ReturnType<InstanceType<ConfiguredDocumentClass<typeof Scene>>['createEmbeddedDocuments']>;
-
-    /**
-     * @deprecated since 0.8.0
-     */
-    updateMany(
-      data: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['updateEmbeddedDocuments']>[1],
-      options: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['updateEmbeddedDocuments']>[2]
-    ): ReturnType<InstanceType<ConfiguredDocumentClass<typeof Scene>>['updateEmbeddedDocuments']>;
-
-    /**
-     * @deprecated since 0.8.0
-     */
-    deleteMany(
-      data: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['deleteEmbeddedDocuments']>[1],
-      options: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['deleteEmbeddedDocuments']>[2]
-    ): ReturnType<InstanceType<ConfiguredDocumentClass<typeof Scene>>['deleteEmbeddedDocuments']>;
   }
 
   interface CanvasHistory<Placeable extends PlaceableObject> {
@@ -373,6 +388,8 @@ declare global {
   namespace PlaceablesLayer {
     type HistoryEventType = 'create' | 'update' | 'delete';
 
+    type CreationState = ValueOf<typeof PlaceablesLayer['CREATION_STATES']>;
+
     /**
      * @typeParam DocumentName - The key of the configuration which defines the object and document class.
      */
@@ -409,15 +426,9 @@ declare global {
 
       /**
        * Does this layer use a quadtree to track object positions?
-       * @defaultValue `false`
+       * @defaultValue `true`
        */
       quadtree: boolean;
-
-      /**
-       * The FormApplication class used to configure objects on this layer.
-       * @defaultValue `CONFIG[this.documentName].sheetClass`
-       */
-      sheetClass: ConstructorOf<FormApplication>;
     }
   }
 }

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayers/lightingLayer.d.ts

@@ -20,7 +20,7 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
   /**
    * A mapping of light sources which are active within the rendered Scene
    */
-  sources: foundry.utils.Collection<PointSource>;
+  sources: foundry.utils.Collection<LightSource>;
 
   /**
    * Increment this whenever lighting channels are re-configured.
@@ -33,7 +33,7 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
    * The currently displayed darkness level, which may override the saved Scene value
    * @defaultValue `0`
    */
-  protected darknessLevel: number;
+  darknessLevel: number;
 
   /**
    * The current client setting for whether global illumination is used or not
@@ -54,21 +54,22 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
   illumination: PIXI.Container | null;
 
   /**
-   * A flag for whether the darkness level is currently animating
-   * @defaultValue `false`
+   * The background container which visualizes the background
+   * @defaultValue `null`
    */
-  protected _animating: boolean;
+  background: PIXI.Container | null;
 
   /**
    * An array of light sources which are currently animated
+   * @internal
    */
-  protected _animatedSources: PointSource[];
+  protected _animatedSources: LightSource[];
 
   /**
    * A mapping of different light level channels
    * @defaultValue `undefined`
    */
-  channels: Record<'background' | 'black' | 'bright' | 'canvas' | 'dark' | 'dim', LightChannel> | undefined;
+  channels: ChannelConfig | undefined;
 
   /** @override */
   static documentName: 'AmbientLight';
@@ -85,7 +86,6 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
    * foundry.utils.mergeObject(super.layerOptions, {
    *  name: "lighting",
    *  rotatableObjects: true,
-   *  quadtree: true,
    *  zIndex: 300
    * })
    * ```
@@ -93,28 +93,47 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
   static get layerOptions(): LightingLayer.LayerOptions;
 
   /**
+   * TODO: Significant portions of this method may no longer be needed
    * Configure the lighting channels which are inputs to the ShadowMap
+   * @internal
    */
-  protected _configureChannels(
-    darkness?: number | null
-  ): Record<'background' | 'black' | 'bright' | 'canvas' | 'dark' | 'dim', LightChannel>;
+  protected _configureChannels({
+    darkness,
+    backgroundColor
+  }?: {
+    /** Darkness level override. */
+    darkness?: number;
+
+    /** Canvas background color override. */
+    backgroundColor?: number;
+  }): ChannelConfig;
 
   /**
    * @override
    */
   draw(): Promise<this>;
 
+  masks?: PIXI.Container;
+
   /**
    * Draw the coloration container which is responsible for rendering the visible hue of a light source.
    * Apply an additive blend to the entire container after each individual light source is blended via screen.
+   * @internal
    */
   protected _drawColorationContainer(): PIXI.Container;
 
   /**
    * Draw the illumination container which is responsible for displaying darkness and light.
+   * @internal
    */
   protected _drawIlluminationContainer(): PIXI.Container;
 
+  /**
+   * Draw the background container which is responsible for displaying altered background.
+   * @internal
+   */
+  protected _drawBackgroundContainer(): PIXI.Container;
+
   /**
    * Does this scene currently benefit from global illumination?
    */
@@ -129,7 +148,19 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
    * Refresh the active display of the LightingLayer.
    * Update the scene background color, light sources, and darkness sources
    */
-  refresh(darkness?: number | undefined): void;
+  refresh({
+    darkness,
+    backgroundColor
+  }?: {
+    /**
+     * An override darkness level to which the layer should be temporarily
+     * rendered.
+     */
+    darkness?: number;
+
+    /** An override canvas background color. */
+    backgroundColor?: number;
+  }): void;
 
   /** @override */
   tearDown(): Promise<this>;
@@ -147,6 +178,7 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
   /**
    * The ticker handler which manages animation delegation
    * @param dt - Delta time
+   * @internal
    */
   protected _animateSource(dt: number): void;
 
@@ -155,16 +187,26 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
    * Only begin animating if another animation is not already in progress.
    * @param target   - The target darkness level between 0 and 1
    *                   (default: `1.0`)
-   * @param duration - The desired animation time in milliseconds. Default is 10 seconds
-   *                   (default: `10000`)
    * @returns A Promise which resolves once the animation is complete
    */
-  animateDarkness(target?: number, { duration }?: { duration?: number }): Promise<void>;
+  animateDarkness(
+    target?: number,
+    {
+      duration
+    }?: {
+      /**
+       * The desired animation time in milliseconds. Default is 10 seconds
+       * @defaultValue `10000`
+       */
+      duration?: number;
+    }
+  ): Promise<void>;
 
   /**
    * Actions to take when the darkness level of the Scene is changed
    * @param darkness - The new darkness level
    * @param prior    - The prior darkness level
+   * @internal
    */
   protected _onDarknessChange(darkness: number, prior: number): void;
 
@@ -184,13 +226,14 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
 declare namespace LightingLayer {
   interface LayerOptions extends PlaceablesLayer.LayerOptions<'AmbientLight'> {
     name: 'lighting';
-    rotatableObjects: true;
-    quadtree: true;
-    zIndex: 300;
   }
 }
 
-declare interface LightChannel {
+type ChannelConfig = Record<'canvas' | 'background' | 'black' | 'bright' | 'dark' | 'dim', LightChannel> & {
+  darkness: { level: number; rgb: [r: number, g: number, b: number] };
+};
+
+interface LightChannel {
   hex: number;
-  rgb: [number, number, number];
+  rgb: [r: number, g: number, b: number];
 }

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayers/mapLayer.d.ts

@@ -119,9 +119,6 @@ declare global {
     interface LayerOptions<Name extends 'background' | 'foreground' = 'background' | 'foreground'>
       extends PlaceablesLayer.LayerOptions<'Tile'> {
       name: Name;
-      zIndex: 0;
-      controllableObjects: true;
-      rotatableObjects: true;
     }
 
     type DropData =

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayers/mapLayers/backgroundLayer.d.ts

@@ -20,16 +20,16 @@ declare global {
     static get layerOptions(): MapLayer.LayerOptions<'background'>;
 
     /**
-     * The outline of the scene
+     * The outline of the scene.
+     * Not rendered within the BackgroundLayer, but rather beneath it so it does not impact the PrimaryMesh texture.
      */
     outline: PIXI.Graphics | undefined;
 
-    draw(): Promise<this>;
-
     /**
      * Draw a background outline which emphasizes what portion of the canvas is playable space and what is buffer.
+     * @param outline - The outline graphics to use
      */
-    protected _drawOutline(): PIXI.Graphics | undefined;
+    drawOutline(outline: PIXI.Graphics): void;
 
     getDocuments(): Exclude<this['documentCollection'], null> | InstanceType<ConfiguredDocumentClassForName<'Tile'>>[];
 

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayers/mapLayers/foregroundLayer.d.ts

@@ -37,6 +37,15 @@ declare global {
      */
     protected _drawOcclusionMask(): CachedContainer;
 
+    /**
+     * Perform one-time initialization actions which affect the foreground layer.
+     * These actions presume and require that the layer has already been drawn.
+     */
+    initialize(): void;
+
+    /** @override */
+    activate(): this;
+
     deactivate(): this;
 
     tearDown(): Promise<this>;
@@ -50,6 +59,18 @@ declare global {
      */
     refresh(): void;
 
+    /**
+     * Add a roof sprite to the occlusion roof mask container
+     * @param tile - The roof tile being added
+     */
+    addRoofSprite(tile: InstanceType<ConfiguredObjectClassForName<'Tile'>>): void;
+
+    /**
+     * Remove a roof sprite from occlusion roof mask container
+     * @param tile - The roof tile being removed
+     */
+    removeRoofSprite(tile: InstanceType<ConfiguredObjectClassForName<'Tile'>>): void;
+
     /**
      * Update occlusion for all tiles on the foreground layer
      */

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayers/notesLayer.d.ts

@@ -47,7 +47,7 @@ declare global {
     protected _onMouseDown(event: PIXI.InteractionEvent): void;
 
     /**
-     * Handle JournalEntry entity drop data
+     * Handle JournalEntry document drop data
      */
     protected _onDropData(event: DragEvent, data: DropData<JournalEntry>): Promise<false | void>;
   }