@league-of-foundry-developers/foundry-vtt-types 9.280.0 → 12.331.1-beta

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

@@ -0,0 +1,310 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+import type Document from "../../../common/abstract/document.d.mts";
+import type { DocumentDatabaseOperations } from "../../../common/abstract/document.d.mts";
+
+declare global {
+  namespace RollTable {
+    type ConfiguredClass = Document.ConfiguredClassForName<"RollTable">;
+    type ConfiguredInstance = Document.ConfiguredInstanceForName<"RollTable">;
+
+    interface DatabaseOperations extends DocumentDatabaseOperations<RollTable> {}
+
+    /**
+     * Optional arguments which customize the draw
+     */
+    interface DrawOptions {
+      /**
+       * An existing Roll instance to use for drawing from the table
+       */
+      roll: Roll;
+
+      /**
+       * Allow drawing recursively from inner RollTable results
+       * @defaultValue `true`
+       */
+      recursive: boolean;
+
+      /**
+       * One or more table results which have been drawn
+       * @defaultValue `[]`
+       */
+      results: TableResult[];
+
+      /**
+       * Whether to automatically display the results in chat
+       * @defaultValue `true`
+       */
+      displayChat: boolean;
+
+      /**
+       * The chat roll mode to use when displaying the result
+       */
+      rollMode: keyof CONFIG.Dice.RollModes | "roll";
+    }
+
+    /**
+     * Additional options which modify message creation
+     */
+    interface ToMessageOptions {
+      /**
+       * An optional Roll instance which produced the drawn results
+       */
+      roll: Roll | null;
+
+      /**
+       * Additional data which customizes the created messages
+       * @defaultValue `{}`
+       */
+      messageData: ConstructorParameters<typeof foundry.documents.BaseChatMessage>[0];
+
+      /**
+       * Additional options which customize the created messages
+       * @defaultValue `{}`
+       */
+      messageOptions: Document.OnCreateOptions<"ChatMessage">;
+    }
+
+    interface RollOptions {
+      /**
+       * An alternative dice Roll to use instead of the default table formula
+       */
+      roll?: Roll;
+
+      /**
+       * If a RollTable document is drawn as a result, recursively roll it
+       * @defaultValue `true`
+       */
+      recursive?: boolean;
+
+      /**
+       * An internal flag used to track recursion depth
+       * @defaultValue `0`
+       */
+      _depth?: number;
+    }
+
+    interface RollTableHTMLEmbedConfig extends TextEditor.DocumentHTMLEmbedConfig {
+      /**
+       * Adds a button allowing the table to be rolled directly from its embedded context.
+       * Default: `false`
+       */
+      rollable?: boolean | undefined;
+    }
+  }
+
+  /**
+   * The client-side RollTable document which extends the common BaseRollTable model.
+   *
+   * @see {@link RollTables}         The world-level collection of RollTable documents
+   * @see {@link TableResult}        The embedded TableResult document
+   * @see {@link RollTableConfig}    The RollTable configuration application
+   */
+  class RollTable extends ClientDocumentMixin(foundry.documents.BaseRollTable) {
+    /**
+     * Provide a thumbnail image path used to represent this document.
+     */
+    get thumbnail(): this["img"];
+
+    /**
+     * Display a result drawn from a RollTable in the Chat Log along.
+     * Optionally also display the Roll which produced the result and configure aspects of the displayed messages.
+     *
+     * @param results - An Array of one or more TableResult Documents which were drawn and should be displayed
+     * @param options - Additional options which modify message creation
+     */
+    toMessage(
+      results: TableResult.ConfiguredInstance[],
+      options?: InexactPartial<RollTable.ToMessageOptions>,
+    ): Promise<ChatMessage.ConfiguredInstance | undefined>;
+
+    /**
+     * Draw a result from the RollTable based on the table formula or a provided Roll instance
+     * @param options - Optional arguments which customize the draw behavior
+     * @returns A Promise which resolves to an object containing the executed roll and the produced results
+     */
+    draw(options?: RollTable.DrawOptions): Promise<RollTableDraw>;
+
+    /**
+     * Draw multiple results from a RollTable, constructing a final synthetic Roll as a dice pool of inner rolls.
+     * @param number  - The number of results to draw
+     * @param options - Optional arguments which customize the draw
+     * @returns The drawn results
+     */
+    drawMany(number: number, options?: InexactPartial<RollTable.DrawOptions>): Promise<RollTableDraw>;
+
+    /**
+     * Normalize the probabilities of rolling each item in the RollTable based on their assigned weights
+     */
+    normalize(): Promise<this | undefined>;
+
+    /**
+     * Reset the state of the RollTable to return any drawn items to the table
+     * @remarks Actually, returns list of TableEntries updated, not the RollTable.
+     * As written, it force updates all records, not just the ones already drawn.
+     */
+    resetResults(): Promise<TableResult.ConfiguredInstance[]>;
+
+    /**
+     * Evaluate a RollTable by rolling its formula and retrieving a drawn result.
+     *
+     * Note that this function only performs the roll and identifies the result, the RollTable#draw function should be
+     * called to formalize the draw from the table.
+     *
+     * @param options - Options which modify rolling behavior
+     *                  (default: `{}`)
+     * @returns The Roll and results drawn by that Roll
+     *
+     * @example
+     * ```typescript
+     * // Draw results using the default table formula
+     * const defaultResults = await table.roll();
+     *
+     * // Draw results using a custom roll formula
+     * const roll = new Roll("1d20 + @abilities.wis.mod", actor.getRollData());
+     * const customResults = await table.roll({roll});
+     * ```
+     */
+    roll(options?: RollTable.RollOptions): Promise<RollTableDraw>;
+
+    /**
+     * Handle a roll from within embedded content.
+     * @param event - The originating event.
+     */
+    protected _rollFromEmbeddedHTML(event: PointerEvent): Promise<void>;
+
+    /**
+     * Get an Array of valid results for a given rolled total
+     * @param value - The rolled value
+     * @returns An Array of results
+     */
+    getResultsForRoll(value: number): TableResult.ConfiguredInstance[];
+
+    /**
+     * Create embedded roll table markup.
+     * @param config  - Configuration for embedding behavior.
+     * @param options - The original enrichment options for cases where the Document embed content
+     *                  also contains text that must be enriched.
+     *
+     * @example Embed the content of a Roll Table as a figure.
+     * ```
+     * @Embed[RollTable.kRfycm1iY3XCvP8c]
+     * ```
+     * becomes
+     * ```html
+     * <figure class="content-embed" data-content-embed data-uuid="RollTable.kRfycm1iY3XCvP8c" data-id="kRfycm1iY3XCvP8c">
+     *   <table class="roll-table-embed">
+     *     <thead>
+     *       <tr>
+     *         <th>Roll</th>
+     *         <th>Result</th>
+     *       </tr>
+     *     </thead>
+     *     <tbody>
+     *       <tr>
+     *         <td>1&mdash;10</td>
+     *         <td>
+     *           <a class="inline-roll roll" data-mode="roll" data-formula="1d6">
+     *             <i class="fas fa-dice-d20"></i>
+     *             1d6
+     *           </a>
+     *           Orcs attack!
+     *         </td>
+     *       </tr>
+     *       <tr>
+     *         <td>11&mdash;20</td>
+     *         <td>No encounter</td>
+     *       </tr>
+     *     </tbody>
+     *   </table>
+     *   <figcaption>
+     *     <div class="embed-caption">
+     *       <p>This is the Roll Table description.</p>
+     *     </div>
+     *     <cite>
+     *       <a class="content-link" data-link data-uuid="RollTable.kRfycm1iY3XCvP8c" data-id="kRfycm1iY3XCvP8c"
+     *          data-type="RollTable" data-tooltip="Rollable Table">
+     *         <i class="fas fa-th-list"></i>
+     *         Rollable Table
+     *     </cite>
+     *   </figcaption>
+     * </figure>
+     * ```
+     */
+    protected _buildEmbedHTML(
+      config: TextEditor.DocumentHTMLEmbedConfig & { rollable: boolean },
+      options?: TextEditor.EnrichmentOptions,
+    ): Promise<HTMLElement | null>;
+
+    protected override _createFigureEmbed(
+      content: HTMLElement | HTMLCollection,
+      config: TextEditor.DocumentHTMLEmbedConfig,
+      options?: TextEditor.EnrichmentOptions,
+    ): Promise<HTMLElement | null>;
+
+    protected override _onCreateDescendantDocuments(
+      parent: ClientDocument,
+      collection: string,
+      documents: ClientDocument[],
+      data: unknown[],
+      options: Document.OnCreateOptions<"TableResult">,
+      userId: string,
+    ): void;
+
+    protected override _onDeleteDescendantDocuments(
+      parent: ClientDocument,
+      collection: string,
+      documents: ClientDocument[],
+      ids: string,
+      options: Document.OnDeleteOptions<"TableResult">,
+      userId: string,
+    ): void;
+
+    override toCompendium<
+      FlagsOpt extends boolean = false,
+      SourceOpt extends boolean = true,
+      SortOpt extends boolean = true,
+      FolderOpt extends boolean = false,
+      OwnershipOpt extends boolean = false,
+      StateOpt extends boolean = true,
+      IdOpt extends boolean = false,
+    >(
+      pack?: CompendiumCollection<CompendiumCollection.Metadata> | null,
+      options?: InexactPartial<
+        ClientDocument.CompendiumExportOptions<FlagsOpt, SourceOpt, SortOpt, FolderOpt, OwnershipOpt, StateOpt, IdOpt>
+      >,
+    ): Omit<
+      this["_source"],
+      | (IdOpt extends false ? "_id" : never)
+      | ClientDocument.OmitProperty<SortOpt, "sort" | "navigation" | "navOrder">
+      | ClientDocument.OmitProperty<FolderOpt, "folder">
+      | ClientDocument.OmitProperty<FlagsOpt, "flags">
+      | ClientDocument.OmitProperty<OwnershipOpt, "ownership">
+      | ClientDocument.OmitProperty<StateOpt, "active" | "fogReset" | "playing"> // does not model the results.drawn = false
+    >;
+
+    /**
+     * Create a new RollTable document using all of the Documents from a specific Folder as new results.
+     * @param folder  - The Folder document from which to create a roll table
+     * @param options - Additional options passed to the RollTable.create method
+     */
+    static fromFolder(
+      folder: Folder,
+      options?: Document.OnCreateOptions<"Folder">,
+    ): Promise<RollTable.ConfiguredInstance | undefined>;
+  }
+
+  /**
+   * An object containing the executed Roll and the produced results
+   */
+  interface RollTableDraw {
+    /**
+     * The Dice roll which generated the draw
+     */
+    roll: Roll;
+
+    /**
+     * An array of drawn TableResult documents
+     */
+    results: Document.ToConfiguredInstance<typeof foundry.documents.BaseTableResult>[];
+  }
+}

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

@@ -0,0 +1,21 @@
+import type Document from "../../../common/abstract/document.d.mts";
+import type { DocumentDatabaseOperations } from "../../../common/abstract/document.d.mts";
+
+declare global {
+  namespace TileDocument {
+    type ConfiguredClass = Document.ConfiguredClassForName<"Tile">;
+    type ConfiguredInstance = Document.ConfiguredInstanceForName<"Tile">;
+
+    interface DatabaseOperations extends DocumentDatabaseOperations<TileDocument> {}
+  }
+
+  /**
+   * The client-side Tile document which extends the common BaseTile model.
+   *
+   * @see {@link Scene}            The Scene document type which contains Tile embedded documents
+   * @see {@link TileConfig}       The Tile configuration application
+   */
+  class TileDocument extends CanvasDocumentMixin(foundry.documents.BaseTile) {
+    override prepareDerivedData(): void;
+  }
+}

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

@@ -0,0 +1,342 @@
+import type { DeepPartial, InexactPartial } from "../../../../types/utils.d.mts";
+import type Document from "../../../common/abstract/document.d.mts";
+import type { DocumentDatabaseOperations } from "../../../common/abstract/document.d.mts";
+import type { SchemaField } from "../../../common/data/fields.d.mts";
+
+declare global {
+  namespace TokenDocument {
+    type ConfiguredClass = Document.ConfiguredClassForName<"Token">;
+    type ConfiguredInstance = InstanceType<ConfiguredClass>;
+
+    // TODO(LukeAbby): This causes a circularity that's likely latent.
+    // Look into this.
+    // type ConfiguredInstance = ConfiguredDocumentInstanceForName<"Token">;
+
+    type ObjectClass = Document.ConfiguredObjectClassForName<"Token">;
+    type ObjectInstance = Document.ConfiguredObjectInstanceForName<"Token">;
+
+    /* eslint-disable @typescript-eslint/no-empty-object-type */
+    interface DatabaseOperations
+      extends DocumentDatabaseOperations<
+        TokenDocument,
+        {},
+        {
+          previousActorId: string | null;
+          animate: boolean;
+          _priorRegions: Record<string, string[]>;
+          _priorPosition: Record<string, { x: number; y: number; elevation: number }>;
+          teleport: boolean;
+          forced: boolean;
+        },
+        {}
+      > {}
+    /* eslint-enable @typescript-eslint/no-empty-object-type */
+  }
+
+  /**
+   * The client-side Token document which extends the common BaseToken model.
+   *
+   * @see {@link Scene}               The Scene document type which contains Token embedded documents
+   * @see {@link TokenConfig}      The Token configuration application
+   */
+  class TokenDocument extends CanvasDocumentMixin(foundry.documents.BaseToken) {
+    /**
+     * A singleton collection which holds a reference to the synthetic token actor by its base actor's ID.
+     */
+    actors(): Collection<Actor.ConfiguredInstance>;
+
+    /**
+     * A lazily evaluated reference to the Actor this Token modifies.
+     * If actorLink is true, then the document is the primary Actor document.
+     * Otherwise the Actor document is a synthetic (ephemeral) document constructed using the Token's ActorDelta.
+     */
+    get actor(): Actor.ConfiguredInstance | null;
+
+    /**
+     * A reference to the base, World-level Actor this token represents.
+     */
+    get baseActor(): Actor | undefined;
+
+    /**
+     * An indicator for whether or not the current User has full control over this Token document.
+     */
+    get isOwner(): boolean;
+
+    /**
+     * A convenient reference for whether this TokenDocument is linked to the Actor it represents, or is a synthetic copy
+     */
+    get isLinked(): boolean;
+
+    /**
+     * Does this TokenDocument have the SECRET disposition and is the current user lacking the necessary permissions
+     * that would reveal this secret?
+     */
+    get isSecret(): boolean;
+
+    /**
+     * Return a reference to a Combatant that represents this Token, if one is present in the current encounter.
+     */
+    get combatant(): Combatant.ConfiguredInstance | null;
+
+    /**
+     * An indicator for whether or not this Token is currently involved in the active combat encounter.
+     */
+    get inCombat(): boolean;
+
+    /**
+     * The Regions this Token is currently in.
+     * @privateRemarks TODO: Change Set<any> to Set<RegionDocuments> when RegionDocuments are implemented
+     */
+    regions: Set<any> | null;
+
+    // TODO: Same as `DataModel._initialize`
+    protected override _initialize(options?: any): void;
+
+    override prepareBaseData(): void;
+
+    override prepareEmbeddedDocuments(): void;
+
+    override prepareDerivedData(): void;
+
+    /**
+     * Infer the subject texture path to use for a token ring.
+     */
+    protected _inferRingSubjectTexture(): string;
+
+    /**
+     * Prepare detection modes which are available to the Token.
+     * Ensure that every Token has the basic sight detection mode configured.
+     */
+    protected _prepareDetectionModes(): void;
+
+    /**
+     * A helper method to retrieve the underlying data behind one of the Token's attribute bars
+     * @param barName     - The named bar to retrieve the attribute for
+     * @returns The attribute displayed on the Token bar, if any
+     */
+    getBarAttribute(
+      barName: string,
+      options?: InexactPartial<{
+        /**
+         * An alternative attribute path to get instead of the default one
+         */
+        alternative: string;
+      }>,
+    ): SingleAttributeBar | ObjectAttributeBar | null;
+
+    /**
+     * Test whether a Token has a specific status effect.
+     * @param statusId - The status effect ID as defined in CONFIG.statusEffects
+     * @returns Does the Actor of the Token have this status effect?
+     */
+    hasStatusEffect(statusId: string): boolean;
+
+    /**
+     * 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?
+     */
+    toggleCombatant({
+      active,
+      ...options
+    }?: InexactPartial<
+      CreateCombatantOptions & {
+        /**
+         * Require this token to be an active Combatant or to be removed.
+         * Otherwise, the current combat state of the Token is toggled.
+         */
+        active: boolean;
+      }
+    >): 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: `{}`
+     * @returns An array of created Combatant documents
+     */
+    static createCombatants(tokens: TokenDocument[], options?: CreateCombatantOptions): Promise<Combatant[]>;
+
+    /**
+     * 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: `{}`
+     * @returns An array of deleted Combatant documents
+     */
+    static deleteCombatants(tokens: TokenDocument[], options?: CreateCombatantOptions): Promise<Combatant[]>;
+
+    /**
+     * 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`
+     */
+    updateVisionMode(
+      visionMode: typeof CONFIG.Canvas.visionModes,
+      defaults?: boolean,
+    ): Promise<ReturnType<this["update"]>>;
+
+    override getEmbeddedCollection<DocType extends Document.Type>(
+      embeddedName: DocType,
+    ): Collection<Document.ConfiguredInstanceForName<DocType>>;
+
+    /**
+     * @privateRemarks _onCreate, _preUpdate, _onUpdate, _onDelete, preCreateOperation, _preUpdateOperation, _onCreateOperation,
+     * _onUpdateOperation, _onDeleteOperation, _preCreateDescendantDocuments, _preUpdateDescendantDocuments, _preDeleteDescendantDocuments,
+     * _onUpdateDescendantDocuments, and _onDeleteDescendantDocuments are all overridden but with no signature changes.
+     * For type simplicity they are left off. These methods historically have been the source of a large amount of computation from tsc.
+     */
+
+    /**
+     * 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: SchemaField.InnerAssignmentType<foundry.documents.BaseToken.Schema>,
+    ): boolean;
+
+    /**
+     * When the base Actor for a TokenDocument changes, we may need to update its Actor instance
+     */
+    protected _onUpdateBaseActor(
+      update?: DeepPartial<Actor.ConfiguredInstance["_source"]>,
+      options?: Document.OnUpdateOptions<"Actor">,
+    ): void;
+
+    /**
+     * Whenever the token's actor delta changes, or the base actor changes, perform associated refreshes.
+     * @param update  - The update delta.
+     * @param options - The options provided to the update.
+     */
+    protected _onRelatedUpdate(
+      update?: DeepPartial<Actor.ConfiguredInstance["_source"]>,
+      /** @privateRemarks foundry calls this field operation
+       * but it's being passed options (and then ignores them)
+       */
+      operation?: Document.OnUpdateOptions<"Actor">,
+    ): void;
+
+    /**
+     * Get an Array of attribute choices which could be tracked for Actors in the Combat Tracker
+     * @param _path - (default: `[]`)
+     */
+    // TODO: There's some very complex handling for non-datamodel Actor system implementations if we want
+    static getTrackedAttributes(
+      data?: Actor.ConfiguredInstance["system"],
+      _path?: string[],
+    ): TrackedAttributesDescription;
+
+    /**
+     * Retrieve an Array of attribute choices from a plain object.
+     * @param schema - The schema to explore for attributes.
+     */
+    protected static _getTrackedAttributesFromObject(data: object, _path?: string[]): TrackedAttributesDescription;
+
+    /**
+     * Retrieve an Array of attribute choices from a SchemaField.
+     * @param schema - The schema to explore for attributes.
+     */
+    protected static _getTrackedAttributesFromSchema(
+      schema: foundry.data.fields.SchemaField.Any,
+      _path?: string[],
+    ): TrackedAttributesDescription;
+
+    /**
+     * Retrieve any configured attributes for a given Actor type.
+     * @param type - The Actor type.
+     */
+    static _getConfiguredTrackedAttributes(type: string): 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
+     * @returns A nested object of attribute choices to display
+     */
+    static getTrackedAttributeChoices(attributes?: TrackedAttributesDescription): Record<string, string[]>;
+
+    /**
+     * @deprecated since v11
+     * @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."`
+     */
+    getActor(): Actor.ConfiguredInstance;
+
+    /**
+     * @deprecated since v11
+     */
+    get actorData(): this["delta"]["_source"];
+
+    /**
+     * @deprecated since v11
+     */
+    set actorData(actorData: this["delta"]["_source"]);
+
+    /**
+     * A helper function to toggle a status effect which includes an Active Effect template
+     * @param effectData - The Active Effect data, including statusId
+     * @param options    - Options to configure application of the Active Effect
+     *                     (default: `{}`)
+     * @returns Whether the Active Effect is now on or off
+     * @deprecated since v12
+     * @remarks `TokenDocument#toggleActiveEffect is deprecated in favor of Actor#toggleStatusEffect"`
+     */
+    toggleActiveEffect(
+      effectData: StatusEffect,
+      options?: InexactPartial<ToggleActiveEffectOptions> | undefined,
+    ): Promise<boolean>;
+  }
+
+  // The getBarAttribute monkeypatch is simply inside the data model definition at `src\foundry\common\data\data.d.mts`
+
+  interface TrackedAttributesDescription {
+    /** A list of property path arrays to attributes with both a value and a max property. */
+    bar: string[][];
+    /** A list of property path arrays to attributes that have only a value property. */
+    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 | undefined;
+  }
+}
+
+interface SingleAttributeBar {
+  type: "value";
+  attribute: string;
+  value: number;
+  editable: boolean;
+}
+
+interface ObjectAttributeBar {
+  type: "bar";
+  attribute: string;
+  value: number;
+  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;
+}
+
+export type StatusEffect = foundry.documents.BaseActiveEffect.ConstructorData & { id: string };