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

package/src/foundry/client/data/documents/token.d.mts

@@ -1,7 +1,8 @@
-import type { AnyObject, DeepPartial, InexactPartial, InterfaceToObject, Merge } from "fvtt-types/utils";
+import type DataModel from "#common/abstract/data.mjs";
+import type { AnyArray, AnyObject, InexactPartial, InterfaceToObject, Merge, NullishProps } from "#utils";
 import type { documents } from "../../../client-esm/client.d.mts";
 import type Document from "../../../common/abstract/document.d.mts";
-import type { DataSchema } from "../../../common/data/fields.d.mts";
+import type { DataSchema, SchemaField } from "../../../common/data/fields.d.mts";
 import type { fields, LightData, TextureData } from "../../../common/data/module.d.mts";
 import type { ActorDeltaField } from "../../../common/documents/token.d.mts";
 import type BaseToken from "../../../common/documents/token.d.mts";
@@ -181,7 +182,7 @@ declare global {
     type Collection = never;
 
     /**
-     * An instance of `TokenDocument` that comes from the database but failed validation meaining that
+     * An instance of `TokenDocument` that comes from the database but failed validation meaning that
      * its `system` and `_source` could theoretically be anything.
      */
     interface Invalid extends Document.Invalid<TokenDocument.Implementation> {}
@@ -242,7 +243,7 @@ declare global {
 
       /**
        * The display mode of the Token nameplate, from CONST.TOKEN_DISPLAY_MODES
-       * @defaultValue `CONST.TOKEN_DISPLAY_MODES.NONE` (`0`)
+       * @defaultValue `CONST.TOKEN_DISPLAY_MODES.NONE`
        */
       displayName: fields.NumberField<
         {
@@ -294,7 +295,7 @@ declare global {
       }>;
 
       /**
-       * @defaultValue `CONST.TOKEN_HEXAGONAL_SHAPES.ELLIPSE_1` (`0`)
+       * @defaultValue `CONST.TOKEN_HEXAGONAL_SHAPES.ELLIPSE_1`
        */
       hexagonalShape: fields.NumberField<
         {
@@ -344,7 +345,7 @@ declare global {
 
       /**
        * The display mode of Token resource bars, from CONST.TOKEN_DISPLAY_MODES
-       * @defaultValue `CONST.TOKEN_DISPLAY_MODES.NONE` (`0`)
+       * @defaultValue `CONST.TOKEN_DISPLAY_MODES.NONE`
        */
       displayBars: fields.NumberField<
         {
@@ -861,28 +862,49 @@ declare global {
         >
       | ActorDelta.OnDeleteDescendantDocumentsArgs;
 
-    /**
-     * @deprecated {@link TokenDocument.Database | `TokenDocument.DatabaseOperation`}
-     */
-    // eslint-disable-next-line @typescript-eslint/no-deprecated
-    interface DatabaseOperations extends Document.Database.Operations<TokenDocument.Implementation> {}
+    // The getBarAttribute monkeypatch is simply inside the data model definition at `src/foundry/common/data/data.d.mts`
 
-    /**
-     * @deprecated {@link TokenDocument.CreateData | `TokenDocument.CreateData`}
-     */
-    interface ConstructorData extends TokenDocument.CreateData {}
+    interface PseudoActorCollection extends foundry.utils.Collection<Actor.Implementation> {
+      documentClass: Actor.ImplementationClass;
+    }
 
-    /**
-     * @deprecated {@link TokenDocument.implementation | `TokenDocument.ImplementationClass`}
-     */
-    type ConfiguredClass = ImplementationClass;
+    /** @internal */
+    type _GetBarAttributeOptions = NullishProps<{
+      /**
+       * An alternative attribute path to get instead of the default one
+       * @defaultValue `this[barName]?.attribute`
+       * @remarks If the above default returns falsey, the {@link TokenDocument.getBarAttribute | `TokenDocument#getBarAttribute`}
+       * call returns `null`
+       */
+      alternative: string;
+    }>;
 
-    /**
-     * @deprecated {@link TokenDocument.Implementation | `TokenDocument.Implementation`}
-     */
-    type ConfiguredInstance = Implementation;
+    interface GetBarAttributeOptions extends _GetBarAttributeOptions {}
+
+    type GetBarAttributeReturn = SingleAttributeBar | ObjectAttributeBar | null;
 
-    // The getBarAttribute monkeypatch is simply inside the data model definition at `src\foundry\common\data\data.d.mts`
+    /** @internal */
+    type _CreateCombatantsOptions = NullishProps<{
+      /**
+       * A specific Combat instance which should be modified. If undefined,
+       * the current active combat will be modified if one exists. Otherwise, a new
+       * Combat encounter will be created if the requesting user is a Gamemaster.
+       * @defaultValue `game.combats.viewed`
+       */
+      combat: Combat.Implementation;
+    }>;
+
+    interface CreateCombatantsOptions extends _CreateCombatantsOptions {}
+
+    interface DeleteCombatantsOptions extends _CreateCombatantsOptions {}
+
+    type TrackedAttributesSubject =
+      | DataModel.Any
+      | DataModel.AnyConstructor
+      | SchemaField.Any
+      | Actor.SubType
+      | AnyObject
+      | AnyArray;
 
     interface TrackedAttributesDescription {
       /** A list of property path arrays to attributes with both a value and a max property. */
@@ -891,16 +913,13 @@ declare global {
       value: string[][];
     }
 
-    interface CreateCombatantOptions {
-      /**
-       * A specific Combat instance which should be modified. If undefined,
-       * the current active combat will be modified if one exists. Otherwise, a new
-       * Combat encounter will be created if the requesting user is a Gamemaster.
-       */
-      combat?: Combat.Implementation | undefined;
+    interface TrackedAttributesChoice {
+      group: string;
+      value: string;
+      label: string;
     }
 
-    interface ToggleCombatantOptions extends InexactPartial<TokenDocument.CreateCombatantOptions> {
+    interface ToggleCombatantOptions extends InexactPartial<TokenDocument.CreateCombatantsOptions> {
       /**
        * Require this token to be an active Combatant or to be removed.
        * Otherwise, the current combat state of the Token is toggled.
@@ -908,8 +927,6 @@ declare global {
       active: boolean;
     }
 
-    type GetBarAttributeReturn = SingleAttributeBar | ObjectAttributeBar | null;
-
     type GetEmbeddedCollectionName = Embedded.CollectionName | "Actor" | "Item" | "ActiveEffect";
 
     // TODO(LukeAbby): Simplified for now to prevent circularities. The correct implementation would
@@ -919,6 +936,27 @@ declare global {
     // | (Name extends "ActiveEffect" ? globalThis.Collection<ActiveEffect.Implementation> : never)
     // | (Name extends Embedded.CollectionName ? Embedded.CollectionFor<Name> : never);
     type GetEmbeddedCollectionResult<_Name extends GetEmbeddedCollectionName> = Collection.Any;
+
+    /**
+     * @deprecated {@link TokenDocument.Database | `TokenDocument.DatabaseOperation`}
+     */
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    interface DatabaseOperations extends Document.Database.Operations<TokenDocument.Implementation> {}
+
+    /**
+     * @deprecated {@link TokenDocument.CreateData | `TokenDocument.CreateData`}
+     */
+    interface ConstructorData extends TokenDocument.CreateData {}
+
+    /**
+     * @deprecated {@link TokenDocument.implementation | `TokenDocument.ImplementationClass`}
+     */
+    type ConfiguredClass = ImplementationClass;
+
+    /**
+     * @deprecated {@link TokenDocument.Implementation | `TokenDocument.Implementation`}
+     */
+    type ConfiguredInstance = Implementation;
   }
 
   /**
@@ -936,8 +974,9 @@ declare global {
 
     /**
      * A singleton collection which holds a reference to the synthetic token actor by its base actor's ID.
+     * @remarks Initialized by an IIFE that makes a base-model {@linkcode Collection} and adds a `documentClass` property to it
      */
-    actors(): Collection<Actor.Implementation>;
+    actors: TokenDocument.PseudoActorCollection;
 
     /**
      * A lazily evaluated reference to the Actor this Token modifies.
@@ -982,8 +1021,8 @@ declare global {
      */
     regions: Set<RegionDocument.Implementation> | null;
 
-    // TODO: Same as `DataModel._initialize`
-    protected override _initialize(options?: any): void;
+    // options: not null (parameter default only)
+    protected override _initialize(options?: Document.InitializeOptions): void;
 
     override prepareBaseData(): void;
 
@@ -1007,14 +1046,10 @@ declare global {
      * @param barName     - The named bar to retrieve the attribute for
      * @returns The attribute displayed on the Token bar, if any
      */
+    // options: not null (destructured)
     getBarAttribute(
       barName: string,
-      options?: InexactPartial<{
-        /**
-         * An alternative attribute path to get instead of the default one
-         */
-        alternative: string;
-      }>,
+      options?: TokenDocument.GetBarAttributeOptions,
     ): TokenDocument.GetBarAttributeReturn;
 
     /**
@@ -1026,47 +1061,45 @@ declare global {
 
     /**
      * Add or remove this Token from a Combat encounter.
-     * @param options - Additional options passed to TokenDocument.createCombatants or
-     *                  TokenDocument.deleteCombatants
-     *                  Default: `{}`
-     *  @returns Is this Token now an active Combatant?
+     * @param options - Additional options passed to TokenDocument.createCombatants or TokenDocument.deleteCombatants (default: `{}`)
+     * @returns Is this Token now an active Combatant?
      */
-    toggleCombatant({ active, ...options }?: TokenDocument.ToggleCombatantOptions): Promise<boolean>;
+    // options: not null (destructured)
+    toggleCombatant(options?: TokenDocument.ToggleCombatantOptions): Promise<boolean>;
 
     /**
      * Create or remove Combatants for an array of provided Token objects.
      * @param tokens  - The tokens which should be added to the Combat
-     * @param options - Options which modify the toggle operation
-     *                  Default: `{}`
+     * @param options - Options which modify the toggle operation (default: `{}`)
      * @returns An array of created Combatant documents
      */
+    // options: not null (destructured)
     static createCombatants(
       tokens: TokenDocument.Implementation[],
-      options?: TokenDocument.CreateCombatantOptions,
+      options?: TokenDocument.CreateCombatantsOptions,
     ): Promise<Combatant.Implementation[]>;
 
     /**
      * Remove Combatants for the array of provided Tokens.
      * @param tokens  - The tokens which should removed from the Combat
-     * @param options - Options which modify the operation
-     *                  Default: `{}`
+     * @param options - Options which modify the operation (default: `{}`)
      * @returns An array of deleted Combatant documents
      */
+    // options: not null (destructured)
     static deleteCombatants(
       tokens: TokenDocument.Implementation[],
-      options?: TokenDocument.CreateCombatantOptions,
+      options?: TokenDocument.DeleteCombatantsOptions,
     ): Promise<Combatant.Implementation[]>;
 
     /**
      * Convenience method to change a token vision mode.
      * @param visionMode - The vision mode to apply to this token.
-     * @param defaults   - If the vision mode should be updated with its defaults.
-     *                     Default = `true`
+     * @param defaults   - If the vision mode should be updated with its defaults. (default: `true`)
      */
     updateVisionMode(
-      visionMode: typeof CONFIG.Canvas.visionModes,
-      defaults?: boolean,
-    ): Promise<ReturnType<this["update"]>>;
+      visionMode: VisionMode.ConfiguredModes,
+      defaults?: boolean | null,
+    ): Promise<TokenDocument.Implementation | undefined>;
 
     /**
      * @remarks Foundry specifically overrides this method such that unlinked `TokenDocument` instances
@@ -1079,14 +1112,20 @@ declare global {
       embeddedName: EmbeddedName,
     ): TokenDocument.GetEmbeddedCollectionResult<EmbeddedName>;
 
+    // _onCreate, _preUpdate, _onUpdate, _onDelete, preCreateOperation, _preUpdateOperation, _onCreateOperation,
+    // _onUpdateOperation, _onDeleteOperation are all overridden but with no signature changes from their definition in BaseToken.
+
     /**
-     * @privateRemarks _onCreate, _preUpdate, _onUpdate, _onDelete, preCreateOperation, _preUpdateOperation, _onCreateOperation,
-     * _onUpdateOperation, _onDeleteOperation are all overridden but with no signature changes from their definition in BaseToken.
+     * Is to Token document updated such that the Regions the Token is contained in may change?
+     * Called as part of the preUpdate workflow.
+     * @param changes - The changes.
+     * @returns Could this Token update change Region containment?
      */
+    protected _couldRegionsChange(changes: TokenDocument.UpdateData): boolean;
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class SwadeActorDelta extends ActorDelta {
      *   protected override _preCreateDescendantDocuments(...args: ActorDelta.PreCreateDescendantDocumentsArgs) {
@@ -1104,7 +1143,7 @@ declare global {
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class GurpsActorDelta extends ActorDelta {
      *   protected override _onCreateDescendantDocuments(...args: ActorDelta.OnCreateDescendantDocumentsArgs) {
@@ -1122,7 +1161,7 @@ declare global {
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class LancerActorDelta extends ActorDelta {
      *   protected override _preUpdateDescendantDocuments(...args: ActorDelta.OnUpdateDescendantDocuments) {
@@ -1140,7 +1179,7 @@ declare global {
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class Ptr2eTokenDocument extends TokenDocument {
      *   protected override _onUpdateDescendantDocuments(...args: TokenDocument.OnUpdateDescendantDocumentsArgs) {
@@ -1158,7 +1197,7 @@ declare global {
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class KultTokenDocument extends TokenDocument {
      *   protected override _preDeleteDescendantDocuments(...args: TokenDocument.PreDeleteDescendantDocumentsArgs) {
@@ -1176,7 +1215,7 @@ declare global {
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class BladesTokenDocument extends TokenDocument {
      *   protected override _onDeleteDescendantDocuments(...args: TokenDocument.OnUpdateDescendantDocuments) {
@@ -1192,21 +1231,12 @@ declare global {
      */
     protected override _onDeleteDescendantDocuments(...args: TokenDocument.OnDeleteDescendantDocumentsArgs): void;
 
-    /**
-     * Is to Token document updated such that the Regions the Token is contained in may change?
-     * Called as part of the preUpdate workflow.
-     * @param changes - The changes.
-     * @returns Could this Token update change Region containment?
-     */
-    protected _couldRegionsChange(changes: Token.UpdateData): boolean;
-
     /**
      * When the base Actor for a TokenDocument changes, we may need to update its Actor instance
+     * @remarks After updating the synthetic actor, forwards to {@link TokenDocument._onRelatedUpdate | `TokenDocument#_onRelatedUpdate`}
      */
-    protected _onUpdateBaseActor(
-      update?: DeepPartial<Actor.Implementation["_source"]>,
-      options?: Actor.Database.OnUpdateOperation,
-    ): void;
+    // update, options: not null (parameter defaults only)
+    protected _onUpdateBaseActor(update?: Actor.UpdateData, options?: Actor.Database.OnUpdateOperation): void;
 
     /**
      * Whenever the token's actor delta changes, or the base actor changes, perform associated refreshes.
@@ -1214,7 +1244,7 @@ declare global {
      * @param options - The options provided to the update.
      */
     protected _onRelatedUpdate(
-      update?: DeepPartial<Actor.Implementation["_source"]>,
+      update?: Actor.UpdateData | ActorDelta.UpdateData,
       /**
        * @privateRemarks foundry calls this field operation
        * but it's being passed options (and then ignores them)
@@ -1224,11 +1254,13 @@ declare global {
 
     /**
      * Get an Array of attribute choices which could be tracked for Actors in the Combat Tracker
+     * @param data  - The object to explore for attributes, or an Actor type.
      * @param _path - (default: `[]`)
      */
     // TODO: There's some very complex handling for non-datamodel Actor system implementations if we want
+    // _path: not null (parameter default only)
     static getTrackedAttributes(
-      data?: Actor.Implementation["system"],
+      data?: TokenDocument.TrackedAttributesSubject | null,
       _path?: string[],
     ): TokenDocument.TrackedAttributesDescription;
 
@@ -1236,8 +1268,9 @@ declare global {
      * Retrieve an Array of attribute choices from a plain object.
      * @param schema - The schema to explore for attributes.
      */
+    // _path: not null (parameter default only)
     protected static _getTrackedAttributesFromObject(
-      data: object,
+      data: AnyObject | AnyArray,
       _path?: string[],
     ): TokenDocument.TrackedAttributesDescription;
 
@@ -1246,27 +1279,31 @@ declare global {
      * @param schema - The schema to explore for attributes.
      */
     protected static _getTrackedAttributesFromSchema(
-      schema: foundry.data.fields.SchemaField.Any,
+      schema: SchemaField.Any,
       _path?: string[],
     ): TokenDocument.TrackedAttributesDescription;
 
     /**
      * Retrieve any configured attributes for a given Actor type.
      * @param type - The Actor type.
+     * @remarks If `type` is invalid, or doesn't have an entry in {@linkcode CONFIG.Actor.trackableAttributes}, returns the merged
+     * tracked attributes of all types. If no types have any configured, returns `void`
      */
-    static _getConfiguredTrackedAttributes(type: string): TokenDocument.TrackedAttributesDescription | void;
+    static _getConfiguredTrackedAttributes(
+      type?: Actor.SubType | null,
+    ): TokenDocument.TrackedAttributesDescription | void;
 
     /**
      * Inspect the Actor data model and identify the set of attributes which could be used for a Token Bar
-     * @param attributes - The tracked attributes which can be chosen from
+     * @param attributes - The tracked attributes which can be chosen from (default: `this.getTrackedAttributes()`)
      * @returns A nested object of attribute choices to display
      */
     static getTrackedAttributeChoices(
-      attributes?: TokenDocument.TrackedAttributesDescription,
-    ): Record<string, string[]>;
+      attributes?: TokenDocument.TrackedAttributesDescription | null,
+    ): TokenDocument.TrackedAttributesChoice[];
 
     /**
-     * @deprecated since v11
+     * @deprecated since v11, no specified end
      * @remarks `"TokenDocument#getActor has been deprecated. Please use the`
      * `TokenDocument#actor getter to retrieve the Actor instance that the TokenDocument represents, or use`
      * `TokenDocument#delta#apply to generate a new synthetic Actor instance."`
@@ -1274,14 +1311,14 @@ declare global {
     getActor(): Actor.Implementation;
 
     /**
-     * @deprecated since v11
+     * @deprecated since v11, until v13
+     * @remarks "You are accessing `TokenDocument#actorData` which is deprecated. Source data may be retrieved via
+     * {@link TokenDocument.delta | `TokenDocument#delta`} but all modifications/access should be done via the
+     * synthetic Actor at {@link TokenDocument.actor | `TokenDocument#actor`} if possible."
      */
-    get actorData(): this["delta"]["_source"];
+    get actorData(): ActorDelta.Source;
 
-    /**
-     * @deprecated since v11
-     */
-    set actorData(actorData: this["delta"]["_source"]);
+    set actorData(actorData: ActorDelta.CreateData);
 
     /**
      * A helper function to toggle a status effect which includes an Active Effect template
@@ -1290,12 +1327,10 @@ declare global {
      *                     (default: `{}`)
      * @returns Whether the Active Effect is now on or off
      * @deprecated since v12
-     * @remarks `TokenDocument#toggleActiveEffect is deprecated in favor of Actor#toggleStatusEffect"`
+     * @remarks "`TokenDocument#toggleActiveEffect` is deprecated in favor of {@link Actor.toggleStatusEffect | `Actor#toggleStatusEffect`}"
      */
-    toggleActiveEffect(
-      effectData: CONFIG.StatusEffect,
-      options?: InexactPartial<ToggleActiveEffectOptions>,
-    ): Promise<boolean>;
+    // options: not null (destructured)
+    toggleActiveEffect(effectData: CONFIG.StatusEffect, options?: Actor.ToggleStatusEffectOptions): Promise<boolean>;
 
     /*
      * After this point these are not really overridden methods.
@@ -1309,26 +1344,33 @@ declare global {
 
     // ClientDocument overrides
 
+    // context: not null (destructured)
     static override defaultName(
-      context: Document.DefaultNameContext<"base", NonNullable<TokenDocument.Parent>>,
+      context?: Document.DefaultNameContext<"Token", NonNullable<TokenDocument.Parent>>,
     ): string;
 
+    /** @remarks `context.parent` is required as creation requires one */
     static override createDialog(
-      data: Document.CreateDialogData<TokenDocument.CreateData>,
-      context: Document.CreateDialogContext<string, NonNullable<TokenDocument.Parent>>,
+      data: Document.CreateDialogData<TokenDocument.CreateData> | undefined,
+      context: Document.CreateDialogContext<"Token", NonNullable<TokenDocument.Parent>>,
     ): Promise<TokenDocument.Stored | null | undefined>;
 
+    // options: not null (parameter default only)
     static override fromDropData(
       data: Document.DropData<TokenDocument.Implementation>,
-      options?: Document.FromDropDataOptions,
+      options?: AnyObject,
     ): Promise<TokenDocument.Implementation | undefined>;
 
     static override fromImport(
       source: TokenDocument.Source,
-      context?: Document.FromImportContext<TokenDocument.Parent>,
+      context?: Document.FromImportContext<TokenDocument.Parent> | null,
     ): Promise<TokenDocument.Implementation>;
 
+    override _onClickDocumentLink(event: MouseEvent): ClientDocument.OnClickDocumentLinkReturn;
+
     // TODO: The deprecated Embedded Document Operations
+
+    #TokenDocument: true;
   }
 
   /**
@@ -1337,9 +1379,9 @@ declare global {
   type TrackedAttributesDescription = TokenDocument.TrackedAttributesDescription;
 
   /**
-   * @deprecated {@link TokenDocument.CreateCombatantOptions | `TokenDocument.CreateCombatantOptions`}
+   * @deprecated {@link TokenDocument.CreateCombatantsOptions | `TokenDocument.CreateCombatantOptions`}
    */
-  type CreateCombatantOptions = TokenDocument.CreateCombatantOptions;
+  type CreateCombatantOptions = TokenDocument.CreateCombatantsOptions;
 }
 
 interface SingleAttributeBar {
@@ -1356,14 +1398,3 @@ interface ObjectAttributeBar {
   max: number;
   editable: boolean;
 }
-
-interface ToggleActiveEffectOptions {
-  /**
-   * Should the Active Effect icon be displayed as an overlay on the token?
-   * @defaultValue `false`
-   */
-  overlay: boolean;
-
-  /** Force a certain active state for the effect. */
-  active: boolean;
-}