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

package/src/foundry/client-esm/canvas/sources/base-effect-source.d.mts

@@ -1,4 +1,4 @@
-import type { InexactPartial } from "../../../../types/utils.d.mts";
+import type { NullishProps, IntentionalPartial, AnyObject, Identity } from "#utils";
 
 /**
  * TODO - Re-document after ESM refactor.
@@ -14,50 +14,56 @@ import type { InexactPartial } from "../../../../types/utils.d.mts";
  * ```
  * @privateRemarks The TODO is foundry's
  */
-declare class BaseEffectSource<
-  SourceData extends BaseEffectSource.BaseEffectSourceData,
+declare abstract class BaseEffectSource<
+  SourceData extends BaseEffectSource.SourceData,
   SourceShape extends PIXI.Polygon,
 > {
   /**
    * An effect source is constructed by providing configuration options.
    * @param options - Options which modify the base effect source instance
+   * @remarks Passing a PlaceableObject is deprecated, and will be removed in v13
    */
-  constructor(options?: BaseEffectSource.BaseEffectSourceOptions);
+  // not null (property access)
+  constructor(options?: BaseEffectSource.ConstructorOptions | PlaceableObject);
 
   /**
    * The type of source represented by this data structure.
    * Each subclass must implement this attribute.
+   * @remarks Effectively abstract, must be defined by subclasses; `undefined` in `BaseEffectSource`
    */
-  static sourceType: string;
+  static sourceType: string | undefined;
 
   /**
    * The target collection into the effects canvas group.
+   * @remarks Foundry marked `@abstract`; Is `undefined` in `BaseEffectSource`
    */
-  static effectsCollection: string;
+  static effectsCollection: string | undefined;
 
   /**
    * Effect source default data.
    * @defaultValue
    * ```js
    * {
-   * x: 0,
-   * y: 0,
-   * elevation: 0,
-   * disabled: false
+   *   x: 0,
+   *   y: 0,
+   *   elevation: 0,
+   *   disabled: false
    * }
    * ```
    */
-  static defaultData: BaseEffectSource.BaseEffectSourceData;
+  static defaultData: BaseEffectSource.SourceData;
 
   /**
    * Some other object which is responsible for this source.
+   * @privateRemarks In Foundry practice this appears to only ever be `null`, `Token.Object`, or `EffectsCanvasGroup` in v12
    */
-  object: PlaceableObject | null;
+  object: PlaceableObject.Any | CanvasGroupMixin.AnyMixed | null;
 
   /**
    * The source id linked to this effect source.
+   * @remarks Foundry types this as Readonly<string>, but does nothing to that effect at runtime
    */
-  readonly sourceId: string;
+  sourceId: string | undefined;
 
   /**
    * The data of this source.
@@ -66,13 +72,15 @@ declare class BaseEffectSource<
 
   /**
    * The geometric shape of the effect source which is generated later.
+   * @remarks This only isn't `undefined` in subclasses implementing `_createShapes()`, usually via {@link foundry.canvas.sources.PointEffectSourceMixin | `PointEffectSourceMixin`}
    */
-  shape: SourceShape;
+  shape: SourceShape | undefined;
 
   /**
    * A collection of boolean flags which control rendering and refresh behavior for the source.
+   * @defaultValue `{}`
    */
-  protected _flags: Record<string, boolean | number>;
+  protected _flags: BaseEffectSource.Flags;
 
   /**
    * The x-coordinate of the point source origin.
@@ -119,6 +127,7 @@ declare class BaseEffectSource<
   /**
    * Records of suppression strings with a boolean value.
    * If any of this record is true, the source is suppressed.
+   * @defaultValue `{}`
    */
   suppression: Record<string, boolean>;
 
@@ -128,35 +137,34 @@ declare class BaseEffectSource<
    * @param options - Additional options which modify source initialization
    * @returns The initialized source
    */
-  initialize(
-    data?: InexactPartial<SourceData>,
-    options?: InexactPartial<{
-      // The type def references a behaviors object that is not even passed into the function
-      /**
-       * Should source data be reset to default values before applying changes?
-       * @defaultValue `false`
-       */
-      reset?: boolean;
-    }>,
-  ): this;
+  // options: not null (destructured)
+  initialize(data?: NullishProps<SourceData> | null, options?: BaseEffectSource.InitializeOptions): this;
 
   /**
    * Subclass specific data initialization steps.
    * @param data - Provided data for configuration
+   * @remarks Not actually `abstract`, but a is a no-op in `BaseEffectSource`
    */
-  _initialize(data: Partial<SourceData>): void;
+  protected _initialize(
+    /** @privateRemarks `IntentionalPartial` because `#initialize` has filtered invalid keys and replaced any nullish values before calling this */
+    data: IntentionalPartial<SourceData>,
+  ): void;
 
-  /**
-   * Create the polygon shape (or shapes) for this source using configured data.
-   */
-  protected _createShapes(): void;
+  /** Create the polygon shape (or shapes) for this source using configured data. */
+  protected abstract _createShapes(): void;
 
   /**
    * Subclass specific configuration steps. Occurs after data initialization and shape computation.
    * Only called if the source is attached and not disabled.
    * @param changes - Changes to the source data which were applied
+   * @remarks Not actually abstract, but is a no-op in `BaseEffectSource`
+   * @privateRemarks This is actually passed *flattened* partial data, and while we were very close to having
+   * that be a non-issue, `RenderedEffectSource`'s data's `animation` and `GlobalLightSource`'s `darkness`
+   * properties are objects, so this can't just be `IntentionalPartial<SourceData>` until we have a `Flatten<>`
+   * type.
    */
-  protected _configure(changes: Partial<SourceData>): void;
+  // TODO: Flatten<IntentionalPartial<SourceData>>
+  protected _configure(changes: AnyObject): void;
 
   /**
    * Refresh the state and uniforms of the source.
@@ -199,7 +207,7 @@ declare class BaseEffectSource<
    * @deprecated since v12, will be removed in v14
    * @remarks `"BaseEffectSource#_createShape is deprecated in favor of BaseEffectSource#_createShapes."`
    */
-  _createShape(): void;
+  protected _createShape(): void;
 
   /**
    * @deprecated since v12, will be removed in v14
@@ -209,42 +217,78 @@ declare class BaseEffectSource<
 }
 
 declare namespace BaseEffectSource {
-  type AnyConstructor = typeof AnyBaseEffectSource;
+  interface Any extends AnyBaseEffectSource {}
+  interface AnyConstructor extends Identity<typeof AnyBaseEffectSource> {}
 
-  interface BaseEffectSourceOptions {
+  /** @internal */
+  type _ConstructorOptions = NullishProps<{
     /**
      * An optional PlaceableObject which is responsible for this source
+     * @remarks Only the global light source is passed the ECG
      */
-    object?: PlaceableObject | undefined;
+    object: PlaceableObject.Any | EffectsCanvasGroup.Any;
+  }>;
+
+  interface ConstructorOptions extends _ConstructorOptions {
     /**
      * A unique ID for this source. This will be set automatically if an
      * object is provided, otherwise is required.
+     * @remarks The above is misleading; sourceId will only be inferred if you pass a `PlaceableObject`
+     * _instead_ of an options object to the constructor (which is a deprecated path removed in v13),
+     * _not_ if you pass in `{ object: PlaceableObject }`, where you're expected to also pass `sourceId`
+     * yourself.
      */
-    sourceId?: string | undefined;
+    sourceId?: string;
   }
 
-  interface BaseEffectSourceData {
+  interface SourceData {
     /**
      * The x-coordinate of the source location
+     * @defaultValue `0`
      */
     x: number;
+
     /**
      * The y-coordinate of the source location
+     * @defaultValue `0`
      */
     y: number;
+
     /**
      * The elevation of the point source
+     * @defaultValue `0`
      */
     elevation: number;
+
     /**
      * Whether or not the source is disabled
+     * @defaultValue `false`
      */
     disabled: boolean;
   }
+
+  /** @internal */
+  type _InitializeOptions = NullishProps<{
+    /**
+     * Should source data be reset to default values before applying changes?
+     * @defaultValue `false`
+     */
+    reset: boolean;
+  }>;
+
+  /** @privateRemarks Foundry describes an `options.behaviors` key, but it is neither checked for nor used at runtime */
+  interface InitializeOptions extends _InitializeOptions {}
+
+  /** @privateRemarks The `| number` is from Foundry's typing, but core only uses boolean flags in v12.331 */
+  interface Flags extends Record<string, boolean | number | undefined> {
+    renderSoftEdges?: boolean;
+    initializedMeshes?: boolean;
+    hasColor?: boolean;
+  }
 }
 
-declare abstract class AnyBaseEffectSource extends BaseEffectSource<any, any> {
-  constructor(arg0: never, ...args: never[]);
+declare abstract class AnyBaseEffectSource extends BaseEffectSource<BaseEffectSource.SourceData, PIXI.Polygon> {
+  constructor(...args: never);
 }
 
 export default BaseEffectSource;

package/src/foundry/client-esm/canvas/sources/base-light-source.d.mts

@@ -1,13 +1,13 @@
-import type { InexactPartial } from "../../../../types/utils.d.mts";
+import type { Identity, IntentionalPartial, NullishProps } from "#utils";
 import type RenderedEffectSource from "./rendered-effect-source.d.mts";
 
 /**
  * A specialized subclass of BaseEffectSource which deals with the rendering of light or darkness.
  */
-declare class BaseLightSource<
-  SourceData extends BaseLightSource.LightSourceData = BaseLightSource.LightSourceData,
+declare abstract class BaseLightSource<
+  SourceData extends BaseLightSource.SourceData = BaseLightSource.SourceData,
   SourceShape extends PIXI.Polygon = PIXI.Polygon,
-  RenderingLayers extends Record<string, RenderedEffectSource.RenderedEffectSourceLayer> = RenderedEffectSource.Layers,
+  RenderingLayers extends Record<string, RenderedEffectSource.SourceLayer> = RenderedEffectSource.Layers,
 > extends RenderedEffectSource<SourceData, SourceShape, RenderingLayers> {
   /** @defaultValue `"light"` */
   static override sourceType: string;
@@ -20,140 +20,204 @@ declare class BaseLightSource<
 
   /**
    * The corresponding lighting levels for dim light.
+   * @defaultValue `foundry.CONST.LIGHTING_LEVELS.DIM`
    */
   protected static _dimLightingLevel: foundry.CONST.LIGHTING_LEVELS;
 
   /**
    * The corresponding lighting levels for bright light.
+   * @defaultValue `foundry.CONST.LIGHTING_LEVELS.BRIGHT`
    */
   protected static _brightLightingLevel: foundry.CONST.LIGHTING_LEVELS;
 
   /**
    * The corresponding animation config.
+   * @privateRemarks Only uses {@link CONFIG.Canvas.lightAnimations | `CONFIG.Canvas.lightAnimations`} in
+   * {@link foundry.canvas.sources.BaseLightSource | `foundry.canvas.sources.BaseLightSource`}, but
+   * {@link foundry.canvas.sources.PointDarknessSource | `foundry.canvas.sources.PointDarknessSource`}
+   * overrides to use `.darknessAnimations`, so the union type is necessary
    */
-  protected static get ANIMATIONS(): CONFIG.Canvas.LightSourceAnimationConfig;
+  protected static get ANIMATIONS(): typeof CONFIG.Canvas.lightAnimations | typeof CONFIG.Canvas.darknessAnimations;
 
   /**
    * @defaultValue
    * ```js
    * {
-   * ...super.defaultData,
-   * priority: 0,
-   * alpha: 0.5,
-   * bright: 0,
-   * coloration: 1,
-   * contrast: 0,
-   * dim: 0,
-   * attenuation: 0.5,
-   * luminosity: 0.5,
-   * saturation: 0,
-   * shadows: 0,
-   * vision: false
+   *   ...super.defaultData,
+   *   priority: 0,
+   *   alpha: 0.5,
+   *   bright: 0,
+   *   coloration: 1,
+   *   contrast: 0,
+   *   dim: 0,
+   *   attenuation: 0.5,
+   *   luminosity: 0.5,
+   *   saturation: 0,
+   *   shadows: 0,
+   *   vision: false
    * }
    * ```
    */
-  static override defaultData: RenderedEffectSource.RenderedEffectSourceData;
+  static override defaultData: BaseLightSource.SourceData;
 
   /**
    * A ratio of dim:bright as part of the source radius
    */
   ratio: number;
 
-  override _initialize(data: Partial<SourceData>): void;
+  protected override _initialize(data: IntentionalPartial<SourceData>): void;
 
-  override _updateColorationUniforms(): void;
+  protected override _updateColorationUniforms(): void;
 
-  override _updateIlluminationUniforms(): void;
+  protected override _updateIlluminationUniforms(): void;
 
-  override _updateBackgroundUniforms(): void;
+  protected override _updateBackgroundUniforms(): void;
 
-  override _updateCommonUniforms(shader: AbstractBaseShader): void;
+  protected override _updateCommonUniforms(shader: AbstractBaseShader): void;
+
+  /** @remarks Doesn't exist prior to initialization. Ultimately set in `_updateCommonUniforms` */
+  cachedAttenuation?: number;
+
+  /** @remarks Doesn't exist prior to initialization. Ultimately set in `_updateCommonUniforms` */
+  computedAttenuation?: number;
 
   /**
    * An animation with flickering ratio and light intensity.
    * @param dt      - Delta time
    * @param options - Additional options which modify the torch animation
    */
-  animateTorch(dt: number, options?: InexactPartial<RenderedEffectSource.AnimationOptions>): void;
+  // not null (destructured)
+  animateTorch(dt: number, options?: RenderedEffectSource.AnimationFunctionOptions): void;
 
   /**
    * An animation with flickering ratio and light intensity
    * @param dt      - Delta time
    * @param options - Additional options which modify the flame animation
    */
-  animateFlickering(
-    dt: number,
-    options?: InexactPartial<
-      RenderedEffectSource.AnimationOptions & {
-        /**
-         * Noise amplification (\>1) or dampening (\<1)
-         * @defaultValue `1`
-         */
-        amplification: number;
-      }
-    >,
-  ): void;
+  // not null (destructured)
+  animateFlickering(dt: number, options?: BaseLightSource.AnimateFlickeringOptions): void;
+
+  /**
+   * @remarks This property will be generated on any class that is `#animateFlickering`'s `this` when it is called.
+   * In Foundry practice this will always be a `BaseLightSource` subclass, so it's defined here. Foundry does not
+   * document it.
+   */
+  _noise?: SmoothNoise;
 
   /**
    * A basic "pulse" animation which expands and contracts.
    * @param dt      - Delta time
    * @param options - Additional options which modify the pulse animation
    */
-  animatePulse(dt: number, options?: InexactPartial<RenderedEffectSource.AnimationOptions>): void;
+  // not null (destructured)
+  animatePulse(dt: number, options?: RenderedEffectSource.AnimationFunctionOptions): void;
 
   /**
-   * @deprecated since v12
+   * @deprecated since v12, until v14
+   * @remarks "BaseLightSource#isDarkness is now obsolete. Use DarknessSource instead."
+   *
+   * Always returns `false`
    */
   get isDarkness(): boolean;
 }
 
 declare namespace BaseLightSource {
-  interface LightSourceData extends RenderedEffectSource.RenderedEffectSourceData {
+  interface Any extends AnyBaseLightSource {}
+  interface AnyConstructor extends Identity<typeof AnyBaseLightSource> {}
+
+  type LightAnimationFunction = (
+    this: BaseLightSource,
+    dt: number,
+    options?: RenderedEffectSource.AnimationFunctionOptions,
+  ) => void;
+
+  interface SourceData extends RenderedEffectSource.SourceData {
     /**
      * An opacity for the emitted light, if any
+     * @defaultValue `0.5`
      */
     alpha: number;
+
     /**
      * The allowed radius of bright vision or illumination
+     * @defaultValue `0`
      */
     bright: number;
+
     /**
      * The coloration technique applied in the shader
+     * @defaultValue `1`
      */
     coloration: number;
+
     /**
      * The amount of contrast this light applies to the background texture
+     * @defaultValue `0`
      */
     contrast: number;
+
     /**
      * The allowed radius of dim vision or illumination
+     * @defaultValue `0`
      */
     dim: number;
+
     /**
      * Strength of the attenuation between bright, dim, and dark
+     * @defaultValue `0.5`
      */
     attenuation: number;
+
     /**
      * The luminosity applied in the shader
+     * @defaultValue `0.5`
      */
     luminosity: number;
+
     /**
      * The amount of color saturation this light applies to the background texture
+     * @defaultValue `0`
      */
     saturation: number;
+
     /**
      * The depth of shadows this light applies to the background texture
+     * @defaultValue `0`
      */
     shadows: number;
+
     /**
      * Whether or not this source provides a source of vision
+     * @defaultValue `false`
      */
     vision: boolean;
+
     /**
      * Strength of this source to beat or not negative/positive sources
+     * @defaultValue `0`
      */
     priority: number;
   }
+
+  /** @internal */
+  type _AnimateFlickeringOptions = NullishProps<{
+    /**
+     * Noise amplification (\>1) or dampening (\<1)
+     * @defaultValue `1`
+     * @remarks Parameter default only, `null` is only cast to `0`
+     */
+    amplification: number;
+  }>;
+
+  interface AnimateFlickeringOptions extends RenderedEffectSource.AnimationFunctionOptions, _AnimateFlickeringOptions {}
+}
+
+declare abstract class AnyBaseLightSource extends BaseLightSource<
+  BaseLightSource.SourceData,
+  PIXI.Polygon,
+  RenderedEffectSource.Layers
+> {
+  constructor(...args: never);
 }
 
 export default BaseLightSource;

package/src/foundry/client-esm/canvas/sources/global-light-source.d.mts

@@ -1,9 +1,15 @@
+import type { FixedInstanceType, Identity } from "#utils";
 import type BaseLightSource from "./base-light-source.d.mts";
+import type RenderedEffectSource from "./rendered-effect-source.d.mts";
 
 /**
  * A specialized subclass of the BaseLightSource which is used to render global light source linked to the scene.
  */
-export default class GlobalLightSource extends BaseLightSource {
+declare class GlobalLightSource<
+  SourceData extends GlobalLightSource.SourceData = GlobalLightSource.SourceData,
+  SourceShape extends PIXI.Polygon = PIXI.Polygon,
+  RenderingLayers extends Record<string, RenderedEffectSource.SourceLayer> = RenderedEffectSource.Layers,
+> extends BaseLightSource<SourceData, SourceShape, RenderingLayers> {
   /** @defaultValue `"GlobalLight"` */
   static override sourceType: string;
 
@@ -14,34 +20,102 @@ export default class GlobalLightSource extends BaseLightSource {
    * @defaultValue
    * ```js
    * {
-   * ...super.defaultData,
-   * rotation: 0,
-   * angle: 360,
-   * attenuation: 0,
-   * priority: -Infinity,
-   * vision: false,
-   * walls: false,
-   * elevation: Infinity,
-   * darkness: {min: 0, max: 0}
+   *   ...super.defaultData,
+   *   rotation: 0,
+   *   angle: 360,
+   *   attenuation: 0,
+   *   priority: -Infinity,
+   *   vision: false,
+   *   walls: false,
+   *   elevation: Infinity,
+   *   darkness: {min: 0, max: 0}
    * }
    * ```
    */
-  static override defaultData: BaseLightSource.LightSourceData;
+  static override defaultData: GlobalLightSource.SourceData;
+
+  /** @privateRemarks This class implements `#_createShapes`, so it's shape property will 'never' be undefined (after initialization) */
+  shape: SourceShape;
 
   /**
    * Name of this global light source.
-   * @defaultValue GlobalLightSource.sourceType
+   * @defaultValue `this.constructor.sourceType` (`"GlobalLight"`)
    */
   name: string;
 
   /**
    * A custom polygon placeholder.
+   * @defaultValue `null`
+   * @remarks This is not set anywhere in Foundry code, so will always be null barring system/module/user action
    */
   customPolygon: PIXI.Polygon | number[] | null;
 
-  override _createShapes(): void;
+  protected override _createShapes(): void;
+
+  protected override _initializeSoftEdges(): void;
+
+  protected override _updateGeometry(): void;
+
+  protected override _updateCommonUniforms(shader: AbstractBaseShader): void;
+}
+
+declare namespace GlobalLightSource {
+  interface Any extends AnyGlobalLightSource {}
+  interface AnyConstructor extends Identity<typeof AnyGlobalLightSource> {}
+
+  /**
+   * @privateRemarks `attenuation`, `priority`, and `elevation` exist in the parent interface,
+   * but are here for defaultValue overrides
+   */
+  interface SourceData extends BaseLightSource.SourceData {
+    /** @privateRemarks Type override only, the global light is not going to use a `darknessShader` */
+    animation: RenderedEffectSource.StoredLightAnimationConfig;
+
+    /**
+     * @defaultValue `0`
+     * @remarks Seemingly unused here, since `GlobalLightSource` does not inherit from `PointEffectSourceMixin`
+     */
+    rotation: number;
 
-  override _initializeSoftEdges(): void;
+    /**
+     * @defaultValue `360`
+     * @remarks Seemingly unused here, since `GlobalLightSource` does not inherit from `PointEffectSourceMixin`
+     */
+    angle: number;
 
-  override _updateGeometry(): void;
+    /** @defaultValue `0` */
+    attenuation: number;
+
+    /** @defaultValue `-Infinity` */
+    priority: number;
+
+    // `vision` override omitted as it doesn't change the default
+
+    /**
+     * @defaultValue `false`
+     * @remarks Seemingly unused here, since `GlobalLightSource` does not inherit from `PointEffectSourceMixin`
+     */
+    walls: boolean;
+
+    /** @defaultValue `Infinity` */
+    elevation: number;
+
+    /** @remarks Threshold values for what darkness level the global light should be enabled for */
+    darkness: {
+      /** @defaultValue `0` */
+      min: number;
+
+      /** @defaultValue `0` */
+      max: number;
+    };
+  }
+
+  type ConfiguredClass = CONFIG["Canvas"]["globalLightSourceClass"];
+  type ConfiguredInstance = FixedInstanceType<ConfiguredClass>;
 }
+
+declare abstract class AnyGlobalLightSource extends GlobalLightSource {
+  constructor(...args: never);
+}
+
+export default GlobalLightSource;