@league-of-foundry-developers/foundry-vtt-types 0.8.9-6 → 9.238.0

package/src/foundry/foundry.js/clientDocuments/cards.d.ts

@@ -0,0 +1,384 @@
+import type {
+  ConfiguredDocumentClass,
+  ConfiguredDocumentClassForName,
+  ConstructorDataType,
+  DocumentConstructor
+} from '../../../types/helperTypes';
+import type { DocumentModificationOptions } from '../../common/abstract/document.mjs';
+
+declare global {
+  /**
+   * The client-side Cards document which extends the common BaseCards model.
+   * Each Cards document contains CardsData which defines its data schema.
+   *
+   * @see {@link data.CardsData}                     The Cards data schema
+   * @see {@link CardStacks}                         The world-level collection of Cards documents
+   */
+  class Cards extends ClientDocumentMixin(foundry.documents.BaseCards) {
+    /**
+     * Provide a thumbnail image path used to represent this document.
+     */
+    get thumbnail(): string | null;
+
+    /**
+     * The Card documents within this stack which are able to be drawn.
+     */
+    get availableCards(): InstanceType<ConfiguredDocumentClassForName<'Card'>>[];
+
+    /**
+     * The Card documents which belong to this stack but have already been drawn.
+     */
+    get drawnCards(): InstanceType<ConfiguredDocumentClassForName<'Card'>>[];
+
+    /** @override */
+    static createDocuments(
+      data: Array<
+        | ConstructorDataType<foundry.data.CardsData>
+        | (ConstructorDataType<foundry.data.CardsData> & Record<string, unknown>)
+      >,
+      context: DocumentModificationContext & { temporary: false }
+    ): Promise<StoredDocument<InstanceType<ConfiguredDocumentClassForName<'Cards'>>>[]>;
+    static createDocuments(
+      data: Array<
+        | ConstructorDataType<foundry.data.CardsData>
+        | (ConstructorDataType<foundry.data.CardsData> & Record<string, unknown>)
+      >,
+      context: DocumentModificationContext & { temporary: boolean }
+    ): Promise<InstanceType<ConfiguredDocumentClassForName<'Cards'>>[]>;
+    static createDocuments(
+      data: Array<
+        | ConstructorDataType<foundry.data.CardsData>
+        | (ConstructorDataType<foundry.data.CardsData> & Record<string, unknown>)
+      >,
+      context?: DocumentModificationContext
+    ): Promise<StoredDocument<InstanceType<ConfiguredDocumentClassForName<'Cards'>>>[]>;
+
+    /**
+     * Deal one or more cards from this Cards document to each of a provided array of Cards destinations.
+     * Cards are allocated from the top of the deck in cyclical order until the required number of Cards have been dealt.
+     * @param to      - An array of other Cards documents to which cards are dealt
+     * @param number  - The number of cards to deal to each other document
+     *                  (default: `1`)
+     * @param options - (default: `{}`)
+     * @returns This Cards document after the deal operation has completed
+     */
+    deal(
+      to: InstanceType<ConfiguredDocumentClassForName<'Cards'>>[],
+      number?: number | undefined,
+      options?: Cards.DealOptions | undefined
+    ): Promise<InstanceType<ConfiguredDocumentClassForName<'Cards'>>>;
+
+    /**
+     * Pass an array of specific Card documents from this document to some other Cards stack.
+     * @param to      - Some other Cards document that is the destination for the pass operation
+     * @param ids     - The embedded Card ids which should be passed
+     * @param options - (default: `{}`)
+     * @returns An array of the Card embedded documents created within the destination stack
+     */
+    pass(
+      to: InstanceType<ConfiguredDocumentClassForName<'Cards'>>,
+      ids: string[],
+      options?: Cards.PassOptions | undefined
+    ): Promise<InstanceType<ConfiguredDocumentClassForName<'Card'>>[]>;
+
+    /**
+     * Draw one or more cards from some other Cards document.
+     * @param from    - Some other Cards document from which to draw
+     * @param number  - The number of cards to draw
+     *                  (default: `1`)
+     * @param options - (default: `{}`)
+     * @returns An array of the Card documents which were drawn
+     */
+    draw(
+      from: InstanceType<ConfiguredDocumentClassForName<'Cards'>>,
+      number?: number | undefined,
+      options?: Cards.DrawOptions | undefined
+    ): Promise<InstanceType<ConfiguredDocumentClassForName<'Card'>>[]>;
+
+    /**
+     * Shuffle this Cards stack, randomizing the sort order of all the cards it contains.
+     * @param options - (default: `{}`)
+     * @returns The Cards document after the shuffle operation has completed
+     * @remarks The returns documentaion is incorrect (https://gitlab.com/foundrynet/foundryvtt/-/issues/6367).
+     */
+    shuffle(
+      options?: Cards.ShuffleOptions | undefined
+    ): Promise<InstanceType<ConfiguredDocumentClassForName<'Card'>>[]>;
+
+    /**
+     * Reset the Cards stack, retrieving all original cards from other stacks where they may have been drawn if this is a
+     * deck, otherwise returning all the cards in this stack to the decks where they originated.
+     * @param options - Options which modify the reset operation
+     *                  (default: `{}`)
+     * @returns The Cards document after the reset operation has completed
+     * @remarks The returns documentaion is incorrect (https://gitlab.com/foundrynet/foundryvtt/-/issues/6367).
+     */
+    reset(
+      options?: Cards.ResetOptions | undefined
+    ): Promise<
+      InstanceType<ConfiguredDocumentClassForName<'Card'>>[] | InstanceType<ConfiguredDocumentClassForName<'Cards'>>
+    >;
+
+    /**
+     * Perform a reset operation for a deck, retrieving all original cards from other stacks where they may have been
+     * drawn.
+     * @param options - Options which modify the reset operation.
+     *                  (default: `{}`)
+     * @returns The Cards document after the reset operation has completed.
+     * @internal
+     * @remarks The returns documentaion is incorrect (https://gitlab.com/foundrynet/foundryvtt/-/issues/6367).
+     */
+    protected _resetDeck(
+      options?: Cards.ResetOptions | undefined
+    ): Promise<InstanceType<ConfiguredDocumentClassForName<'Card'>>[]>;
+
+    /**
+     * Return all cards in this stack to their original decks.
+     * @param options - Options which modify the return operation.
+     *                  (default: `{}`)
+     * @returns The Cards document after the return operation has completed.
+     * @internal
+     */
+    protected _resetStack(
+      options?: Cards.ResetOptions | undefined
+    ): Promise<InstanceType<ConfiguredDocumentClassForName<'Cards'>>>;
+
+    /**
+     * A sorting function that is used to determine the standard order of Card documents within an un-shuffled stack.
+     * @param a - The card being sorted
+     * @param b - Another card being sorted against
+     */
+    protected sortStandard(a: foundry.data.CardData, b: foundry.data.CardData): number;
+
+    /**
+     * A sorting function that is used to determine the order of Card documents within a shuffled stack.
+     * @param a - The card being sorted
+     * @param b - Another card being sorted against
+     */
+    protected sortShuffled(a: foundry.data.CardData, b: foundry.data.CardData): number;
+
+    /**
+     * An internal helper method for drawing a certain number of Card documents from this Cards stack.
+     * @param number - The number of cards to draw
+     * @param how    - A draw mode from CONST.CARD_DRAW_MODES
+     * @returns An array of drawn Card documents
+     */
+    protected _drawCards(
+      number: number,
+      how: foundry.CONST.CARD_DRAW_MODES
+    ): InstanceType<ConfiguredDocumentClassForName<'Card'>>[];
+
+    /**
+     * Create a ChatMessage which provides a notification of the cards operation which was just performed.
+     * Visibility of the resulting message is linked to the default roll mode selected in the chat log dropdown.
+     * @param source  - The source Cards document from which the action originated
+     * @param action  - The localization key which formats the chat message notification
+     * @param context - Data passed to the i18n.format method for the localization key
+     * @returns A created ChatMessage document
+     * @internal
+     */
+    protected _postChatNotification(
+      source: InstanceType<ConfiguredDocumentClassForName<'Cards'>>,
+      action: string,
+      context: Record<string, unknown>
+    ): Promise<InstanceType<ConfiguredDocumentClassForName<'ChatMessage'>> | undefined>;
+
+    /** @override */
+    protected _onUpdate(
+      data: DeepPartial<foundry.data.CardsData>,
+      options: DocumentModificationOptions,
+      userId: string
+    ): void;
+
+    // TODO: It's a bit weird that we have to do it in this generic way but otherwise there is an error overriding this. Investigate later.
+    /** @override */
+    static deleteDocuments<T extends DocumentConstructor>(
+      this: T,
+      ids?: string[] | undefined,
+      context?: DocumentModificationContext | undefined
+    ): Promise<InstanceType<ConfiguredDocumentClass<T>>[]>;
+
+    /**
+     * Display a dialog which prompts the user to deal cards to some number of hand-type Cards documents.
+     * @see {@link Cards#deal}
+     */
+    dealDialog(): Promise<InstanceType<ConfiguredDocumentClassForName<'Cards'>> | null>;
+
+    /**
+     * Display a dialog which prompts the user to draw cards from some other deck-type Cards documents.
+     * @see {@link Cards#draw}
+     */
+    drawDialog(): Promise<InstanceType<ConfiguredDocumentClassForName<'Card'>>[] | null>;
+
+    /**
+     * Display a dialog which prompts the user to pass cards from this document to some other other Cards document.
+     * @see {@link Cards#deal}
+     */
+    passDialog(): Promise<InstanceType<ConfiguredDocumentClassForName<'Cards'>> | null>;
+
+    /**
+     * Display a dialog which prompts the user to play a specific Card to some other Cards document
+     * @see {@link Cards#pass}
+     * @param card - The specific card being played as part of this dialog
+     * @remarks returns documentation is incorrect.
+     */
+    playDialog(
+      card: InstanceType<ConfiguredDocumentClassForName<'Card'>>
+    ): Promise<
+      | InstanceType<ConfiguredDocumentClassForName<'Card'>>[]
+      | InstanceType<ConfiguredDocumentClassForName<'Cards'>>
+      | null
+    >;
+
+    /**
+     * Display a confirmation dialog for whether or not the user wishes to reset a Cards stack
+     * @see {@link Cards#reset}
+     */
+    resetDialog(): Promise<InstanceType<ConfiguredDocumentClassForName<'Cards'>> | false | null>;
+
+    /** @override */
+    deleteDialog(options?: Partial<Dialog.Options> | undefined): Promise<this | false | null | undefined>;
+
+    // TODO: It's a bit weird that we have to do it in this generic way but otherwise there is an error overriding this. Investigate later.
+    /** @override */
+    static createDialog<T extends DocumentConstructor>(
+      this: T,
+      data?:
+        | DeepPartial<
+            | ConstructorDataType<foundry.data.CardsData>
+            | (ConstructorDataType<foundry.data.CardsData> & Record<string, unknown>)
+          >
+        | undefined,
+      context?: (Pick<DocumentModificationContext, 'parent' | 'pack'> & Partial<Dialog.Options>) | undefined
+    ): Promise<InstanceType<ConfiguredDocumentClass<T>> | null | undefined>;
+  }
+
+  namespace Cards {
+    interface BaseOperationOptions {
+      /**
+       * Create a ChatMessage which notifies that this action has occurred
+       * @defaultValue `true`
+       */
+      chatNotification?: boolean | undefined;
+    }
+
+    interface DealOptions extends BaseOperationOptions {
+      /**
+       * How to draw, a value from CONST.CARD_DRAW_MODES
+       * @defaultValue `foundry.CONST.CARD_DRAW_MODES.FIRST`
+       */
+      how?: foundry.CONST.CARD_DRAW_MODES | undefined;
+
+      /**
+       * Modifications to make to each Card as part of the deal operation,
+       * for example the displayed face
+       * @defaultValue `{}`
+       */
+      updateData?: DeepPartial<ConstructorDataType<foundry.data.CardData>> | undefined;
+
+      /**
+       * The name of the action being performed, used as part of the dispatched Hook event
+       * @defaultValue `'deal'`
+       */
+      action?: string | undefined;
+    }
+
+    /** Additional context which describes the operation */
+    interface DealContext {
+      /** The action name being performed, i.e. "deal", "pass" */
+      action: string;
+
+      /** An array of Card creation operations to be performed in each destination Cards document */
+      toCreate: ConstructorDataType<foundry.data.CardData>[][];
+
+      /** Card update operations to be performed in the origin Cards document */
+      fromUpdate: DeepPartial<ConstructorDataType<foundry.data.CardData>>[];
+
+      /** Card deletion operations to be performed in the origin Cards document */
+      fromDelete: string[];
+    }
+
+    interface PassOptions extends BaseOperationOptions {
+      /**
+       * Modifications to make to each Card as part of the pass operation,
+       * for example the displayed face
+       * @defaultValue `{}`
+       */
+      updateData?: DeepPartial<ConstructorDataType<foundry.data.CardData>> | undefined;
+
+      /**
+       * The name of the action being performed, used as part of the dispatched Hook event
+       * @defaultValue `'pass'`
+       */
+      action?: string | undefined;
+    }
+
+    /** Additional context which describes the operation */
+    interface PassContext {
+      /** The action name being performed, i.e. "pass", "play", "discard", "draw" */
+      action: string;
+
+      /** Card creation operations to be performed in the destination Cards document */
+      toCreate: ConstructorDataType<foundry.data.CardData>[];
+
+      /** Card update operations to be performed in the destination Cards document */
+      toUpdate: DeepPartial<ConstructorDataType<foundry.data.CardData>>[];
+
+      /** Card update operations to be performed in the origin Cards document */
+      fromUpdate: DeepPartial<ConstructorDataType<foundry.data.CardData>>[];
+
+      /** Card deletion operations to be performed in the origin Cards document */
+      fromDelete: string[];
+    }
+
+    interface DrawOptions extends PassOptions {
+      /**
+       * How to draw, a value from CONST.CARD_DRAW_MODES
+       * @defaultValue `foundry.CONST.CARD_DRAW_MODES.FIRST`
+       */
+      how?: foundry.CONST.CARD_DRAW_MODES | undefined;
+
+      /**
+       * Modifications to make to each Card as part of the draw operation,
+       * for example the displayed face
+       * @defaultValue `{}`
+       */
+      updateData?: DeepPartial<ConstructorDataType<foundry.data.CardData>> | undefined;
+    }
+
+    interface ShuffleOptions extends BaseOperationOptions {
+      /**
+       * Modifications to make to each Card as part of the shuffle operation,
+       * for example the displayed face
+       * @defaultValue `{}`
+       * @remarks This is not actually used by {@link Cards.shuffle}.
+       */
+      updateData?: DeepPartial<ConstructorDataType<foundry.data.CardData>> | undefined;
+    }
+
+    /** Options which modify the reset operation */
+    interface ResetOptions extends BaseOperationOptions {
+      /**
+       * Modifications to make to each Card as part of the reset operation,
+       * for example the displayed face
+       * @defaultValue `{}`
+       */
+      updateData?: DeepPartial<ConstructorDataType<foundry.data.CardData>> | undefined;
+    }
+
+    /** Additional context which describes the operation. */
+    interface ReturnContext {
+      /**
+       * A mapping of Card deck IDs to the update operations that
+       * will be performed on them.
+       */
+      toUpdate: Record<string, DeepPartial<ConstructorDataType<foundry.data.CardData>>[]>;
+
+      /**
+       * Card deletion operations to be performed on the origin Cards
+       * document.
+       */
+      fromDelete: string[];
+    }
+  }
+}

package/src/foundry/foundry.js/clientDocuments/chatMessage.d.ts

@@ -1,5 +1,6 @@
-import { ConfiguredDocumentClass, ConstructorDataType } from '../../../types/helperTypes';
+import { ConfiguredDocumentClass } from '../../../types/helperTypes';
 import { DocumentModificationOptions } from '../../common/abstract/document.mjs';
+import type { ChatMessageDataConstructorData } from '../../common/data/data.mjs/chatMessageData.js';
 
 declare global {
   /**
@@ -72,15 +73,15 @@ declare global {
      * @returns The modified ChatMessage data with rollMode preferences applied
      */
     static applyRollMode(
-      chatData: ConstructorDataType<foundry.data.ChatMessageData>,
-      rollMode: foundry.CONST.DiceRollMode
-    ): ConstructorDataType<foundry.data.ChatMessageData>;
+      chatData: ChatMessageDataConstructorData,
+      rollMode: foundry.CONST.DICE_ROLL_MODES
+    ): ChatMessageDataConstructorData;
 
     /**
      * Update the data of a ChatMessage instance to apply a requested rollMode
      * @param rollMode - The rollMode preference to apply to this message data
      */
-    applyRollMode(rollMode: foundry.CONST.DiceRollMode): void;
+    applyRollMode(rollMode: foundry.CONST.DICE_ROLL_MODES): void;
 
     /**
      * Attempt to determine who is the speaking character (and token) for a certain Chat Message
@@ -99,10 +100,10 @@ declare global {
       token,
       alias
     }?: {
-      scene?: InstanceType<ConfiguredDocumentClass<typeof Scene>>;
-      actor?: InstanceType<ConfiguredDocumentClass<typeof Actor>>;
-      token?: InstanceType<ConfiguredDocumentClass<typeof TokenDocument>>;
-      alias?: string;
+      scene?: InstanceType<ConfiguredDocumentClass<typeof Scene>> | undefined;
+      actor?: InstanceType<ConfiguredDocumentClass<typeof Actor>> | undefined;
+      token?: InstanceType<ConfiguredDocumentClass<typeof TokenDocument>> | undefined;
+      alias?: string | undefined;
     }): foundry.data.ChatMessageData['speaker']['_source'];
 
     /**
@@ -197,7 +198,7 @@ declare global {
 
     /** @override */
     _preCreate(
-      data: ConstructorDataType<foundry.data.ChatMessageData>,
+      data: ChatMessageDataConstructorData,
       options: DocumentModificationOptions,
       user: foundry.documents.BaseUser
     ): Promise<void>;

package/src/foundry/foundry.js/clientDocuments/combat.d.ts

@@ -1,6 +1,7 @@
-import { ConfiguredDocumentClass, ConstructorDataType, PropertiesToSource } from '../../../types/helperTypes';
+import { ConfiguredDocumentClass, PropertiesToSource } from '../../../types/helperTypes';
 import { DocumentModificationOptions } from '../../common/abstract/document.mjs';
 import { CombatantDataProperties } from '../../common/data/data.mjs/combatantData';
+import type { CombatDataConstructorData } from '../../common/data/data.mjs/combatData.js';
 
 declare global {
   /**
@@ -183,18 +184,13 @@ declare global {
 
     /** @deprecated since 0.8.0 */
     createCombatant(
-      data:
-        | ConstructorDataType<foundry.data.CombatData>
-        | (ConstructorDataType<foundry.data.CombatData> & Record<string, unknown>),
+      data: CombatDataConstructorData | (CombatDataConstructorData & Record<string, unknown>),
       options?: DocumentModificationContext
     ): this['createEmbeddedDocuments'];
 
     /** @deprecated since 0.8.0 */
     updateCombatant(
-      data: DeepPartial<
-        | ConstructorDataType<foundry.data.CombatData>
-        | (ConstructorDataType<foundry.data.CombatData> & Record<string, unknown>)
-      >,
+      data: DeepPartial<CombatDataConstructorData | (CombatDataConstructorData & Record<string, unknown>)>,
       options?: DocumentModificationContext
     ): NonNullable<ReturnType<this['combatants']['get']>>['update'];
 

package/src/foundry/foundry.js/clientDocuments/combatant.d.ts

@@ -75,7 +75,7 @@ declare global {
     /** @override */
     testUserPermission(
       user: BaseUser,
-      permission: keyof typeof foundry.CONST.ENTITY_PERMISSIONS | foundry.CONST.EntityPermission,
+      permission: keyof typeof foundry.CONST.DOCUMENT_PERMISSION_LEVELS | foundry.CONST.DOCUMENT_PERMISSION_LEVELS,
       { exact }?: { exact?: boolean }
     ): boolean;
 

package/src/foundry/foundry.js/clientDocuments/folder.d.ts

@@ -1,5 +1,6 @@
+import { ConfiguredDocumentClass } from '../../../types/helperTypes';
 import { DocumentModificationOptions } from '../../common/abstract/document.mjs';
-import { ConfiguredDocumentClass, ConstructorDataType } from '../../../types/helperTypes';
+import type { FolderDataConstructorData } from '../../common/data/data.mjs/folderData.js';
 
 declare global {
   /**
@@ -69,11 +70,8 @@ declare global {
      * Document is returned.
      */
     static createDialog(
-      data?: DeepPartial<
-        | ConstructorDataType<foundry.data.FolderData>
-        | (ConstructorDataType<foundry.data.FolderData> & Record<string, unknown>)
-      >,
-      options?: Dialog.Options
+      data?: DeepPartial<FolderDataConstructorData | (FolderDataConstructorData & Record<string, unknown>)> | undefined,
+      options?: Dialog.Options | undefined
     ): any;
 
     /**

package/src/foundry/foundry.js/clientDocuments/index.d.ts

@@ -1,6 +1,8 @@
 import './activeEffect';
 import './actor';
 import './canvasDocuments';
+import './card';
+import './cards';
 import './chatMessage';
 import './combat';
 import './combatant';
@@ -11,6 +13,7 @@ import './journalEntry';
 import './macro';
 import './playlist';
 import './playlistSound';
+import './prototypeToken';
 import './rollTable';
 import './scene';
 import './setting';

package/src/foundry/foundry.js/clientDocuments/item.d.ts

@@ -1,4 +1,5 @@
-import { ConfiguredDocumentClass, ConstructorDataType } from '../../../types/helperTypes';
+import { ConfiguredDocumentClass } from '../../../types/helperTypes';
+import type { ItemDataConstructorData } from '../../common/data/data.mjs/itemData.js';
 
 declare global {
   /**
@@ -69,9 +70,7 @@ declare global {
      * @deprecated since 0.8.1
      */
     static createOwned(
-      itemData:
-        | ConstructorDataType<foundry.data.ItemData>
-        | (ConstructorDataType<foundry.data.ItemData> & Record<string, unknown>),
+      itemData: ItemDataConstructorData | (ItemDataConstructorData & Record<string, unknown>),
       actor: InstanceType<ConfiguredDocumentClass<typeof foundry.documents.BaseActor>>
     ): InstanceType<ConfiguredDocumentClass<typeof foundry.documents.BaseItem>>;
   }

package/src/foundry/foundry.js/clientDocuments/playlist.d.ts

@@ -1,5 +1,6 @@
-import type { ConfiguredDocumentClass, ConstructorDataType } from '../../../types/helperTypes';
+import type { ConfiguredDocumentClass } from '../../../types/helperTypes';
 import type { DocumentModificationOptions } from '../../common/abstract/document.mjs';
+import type { PlaylistDataConstructorData } from '../../common/data/data.mjs/playlistData.js';
 
 declare global {
   /**
@@ -38,7 +39,7 @@ declare global {
     /**
      * The playback mode for the Playlist instance
      */
-    get mode(): foundry.CONST.PlaylistMode;
+    get mode(): foundry.CONST.PLAYLIST_MODES;
 
     /**
      * The order in which sounds within this playlist will be played (if sequential or shuffled)
@@ -128,7 +129,7 @@ declare global {
 
     /** @override */
     protected _preUpdate(
-      changed: DeepPartial<ConstructorDataType<foundry.data.PlaylistData>>,
+      changed: DeepPartial<PlaylistDataConstructorData>,
       options: DocumentModificationOptions,
       user: foundry.documents.BaseUser
     ): Promise<void>;

package/src/foundry/foundry.js/clientDocuments/prototypeToken.d.ts

@@ -0,0 +1,15 @@
+/**
+ * An extended Document definition used specifically
+ * This ensures that the PrototypeTokenData schema is used instead of the standard TokenData.
+ * This exists specifically for prototype Token configuration in the TokenConfig app and should not be used otherwise.
+ * @internal
+ * @remarks The types for this are incorrect, in particular everything related to the data should use
+ * {@link foundry.data.PrototypeTokenData} instead of {@link foundry.data.TokenData}. However, with the current approach
+ * to type documents, we don't see a way to do this. This class is just added for reference. As the documentation above
+ * says, don't use it (there really shouldn't be a need to do so).
+ */
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+declare class PrototypeTokenDocument extends TokenDocument {
+  static get schema(): typeof foundry.data.PrototypeTokenData;
+}

package/src/foundry/foundry.js/clientDocuments/rollTable.d.ts

@@ -158,7 +158,7 @@ declare global {
       /**
        * The chat roll mode to use when displaying the result
        */
-      rollMode: foundry.CONST.DiceRollMode;
+      rollMode: foundry.CONST.DICE_ROLL_MODES;
     }
 
     /**