@league-of-foundry-developers/foundry-vtt-types 9.280.1 → 12.331.2-beta

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

@@ -0,0 +1,354 @@
+import type { DatabaseOperationsFor } from "../../../../types/helperTypes.d.mts";
+import type { DeepPartial, InexactPartial } from "../../../../types/utils.d.mts";
+import type { fields } from "../../../common/data/module.d.mts";
+import type { DocumentDatabaseOperations } from "../../../common/abstract/document.d.mts";
+import type Document from "../../../common/abstract/document.d.mts";
+import type BaseCards from "../../../common/documents/cards.d.mts";
+
+declare global {
+  namespace Cards {
+    type Metadata = Document.MetadataFor<Cards>;
+
+    type ConfiguredClass = Document.ConfiguredClassForName<"Cards">;
+    type ConfiguredInstance = Document.ConfiguredInstanceForName<"Cards">;
+
+    interface DatabaseOperations extends DocumentDatabaseOperations<Cards> {}
+
+    // Helpful aliases
+    type TypeNames = BaseCards.TypeNames;
+    type ConstructorData = BaseCards.ConstructorData;
+    type UpdateData = BaseCards.UpdateData;
+    type Schema = BaseCards.Schema;
+    type Source = BaseCards.Source;
+
+    type CardsAction = "deal" | "pass";
+
+    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;
+
+      /**
+       * Modifications to make to each Card as part of the deal operation,
+       * for example the displayed face
+       * @defaultValue `{}`
+       */
+      updateData: DeepPartial<Cards["_source"]>;
+
+      /**
+       * The name of the action being performed, used as part of the dispatched Hook event
+       * @defaultValue `"deal"`
+       */
+      action: CardsAction;
+    }
+
+    /** Additional context which describes the operation */
+    interface DealContext {
+      /** The action name being performed, i.e. "deal", "pass" */
+      action: CardsAction;
+
+      /** An array of Card creation operations to be performed in each destination Cards document */
+      toCreate: Card["_source"][][];
+
+      /** Card update operations to be performed in the origin Cards document */
+      fromUpdate: { _id: string; drawn: true }[];
+
+      /** 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<Card["_source"]> | undefined;
+
+      /**
+       * The name of the action being performed, used as part of the dispatched Hook event
+       * @defaultValue `"pass"`
+       */
+      action: string | undefined;
+
+      /**
+       * Create a ChatMessage which notifies that this action has occurred
+       * @defaultValue `true`
+       */
+      chatNotification: boolean | undefined;
+    }
+
+    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;
+
+      /**
+       * Modifications to make to each Card as part of the draw operation,
+       * for example the displayed face
+       * @defaultValue `{}`
+       */
+      updateData: DeepPartial<Card["_source"]>;
+    }
+
+    interface ShuffleOptions extends BaseOperationOptions {
+      /**
+       * Modifications to make to each Card as part of the shuffle operation,
+       * for example the displayed face
+       * @defaultValue `{}`
+       */
+      updateData: DeepPartial<Card["_source"]>;
+
+      /** Create a ChatMessage which notifies that this action has occurred
+       *  @defaultValue `true`
+       */
+      chatNotification: boolean | 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<Card["_source"]>;
+    }
+
+    /** 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<Card["_source"]>[]>;
+
+      /**
+       * Card deletion operations to be performed on the origin Cards
+       * document.
+       */
+      fromDelete: string[];
+    }
+  }
+
+  /**
+   * The client-side Cards document which extends the common BaseCards model.
+   * Each Cards document contains CardsData which defines its data schema.
+   *
+   * @see {@link CardStacks}                        The world-level collection of Cards documents
+   * @see {@link CardsConfig}                       The Cards configuration application
+   */
+  class Cards extends ClientDocumentMixin(foundry.documents.BaseCards) {
+    static override metadata: Cards.Metadata;
+
+    /**
+     * Provide a thumbnail image path used to represent this document.
+     */
+    get thumbnail(): this["img"];
+
+    /**
+     * The Card documents within this stack which are able to be drawn.
+     */
+    get availableCards(): Card.ConfiguredInstance[];
+
+    /**
+     * The Card documents which belong to this stack but have already been drawn.
+     */
+    get drawnCards(): Card.ConfiguredInstance[];
+
+    /**
+     * Returns the localized Label for the type of Card Stack this is
+     */
+    get typeLabel(): string;
+
+    /**
+     * Can this Cards document be cloned in a duplicate workflow?
+     */
+    get canClone(): boolean;
+
+    static createDocuments<T extends Document.AnyConstructor, Temporary extends boolean | undefined>(
+      this: T,
+      data: Array<fields.SchemaField.AssignmentType<InstanceType<T>["schema"]["fields"]> & Record<string, unknown>>,
+      operation?: InexactPartial<Omit<DatabaseOperationsFor<T["metadata"]["name"], "create">, "data">> & {
+        temporary?: Temporary;
+      },
+    ): Promise<Document.ToStoredIf<T, Temporary>[] | undefined>;
+
+    /**
+     * 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: Cards.ConfiguredInstance[],
+      number?: number,
+      options?: InexactPartial<Cards.DealOptions>,
+    ): Promise<Cards.ConfiguredInstance>;
+
+    /**
+     * 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 - Additional options which modify the pass operation
+     *                  (default: `{}`)
+     * @returns An array of the Card embedded documents created within the destination stack
+     */
+    pass(
+      to: Cards.ConfiguredInstance,
+      ids: string[],
+      options?: InexactPartial<Cards.PassOptions>,
+    ): Promise<Card.ConfiguredInstance[]>;
+
+    /**
+     * 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: Cards.ConfiguredInstance,
+      number?: number,
+      options?: InexactPartial<Cards.DrawOptions>,
+    ): Promise<Card.ConfiguredInstance[]>;
+
+    /**
+     * 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
+     */
+    shuffle(options?: InexactPartial<Cards.ShuffleOptions>): Promise<Cards.ConfiguredInstance>;
+
+    /**
+     * 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
+     */
+    reset(options?: InexactPartial<Cards.ResetOptions>): Promise<Cards.ConfiguredInstance>;
+
+    /**
+     * 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
+     */
+    protected _resetDeck(options?: InexactPartial<Cards.ResetOptions>): Promise<Cards.ConfiguredInstance>;
+
+    /**
+     * 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?: InexactPartial<Cards.ResetOptions>): Promise<Cards.ConfiguredInstance>;
+
+    /**
+     * 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: Card, b: Card): 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: Card, b: Card): 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): Card.ConfiguredInstance[];
+
+    /**
+     * 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: Cards.ConfiguredInstance,
+      action: string,
+      context: Record<string, unknown>,
+    ): Promise<ChatMessage.ConfiguredInstance | undefined>;
+
+    /**
+     * @privateRemarks _preCreate, _onUpdate, and _preDelete 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.
+     */
+
+    /**
+     * Display a dialog which prompts the user to deal cards to some number of hand-type Cards documents.
+     * @see {@link Cards#deal}
+     */
+    dealDialog(): Promise<Cards.ConfiguredInstance | null>;
+
+    /**
+     * Display a dialog which prompts the user to draw cards from some other deck-type Cards documents.
+     * @see {@link Cards#draw}
+     */
+    drawDialog(): Promise<Card.ConfiguredInstance[] | 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<Cards.ConfiguredInstance | 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
+     */
+    playDialog(card: Card.ConfiguredInstance): Promise<Card.ConfiguredInstance[] | void | null>;
+
+    /**
+     * Display a confirmation dialog for whether or not the user wishes to reset a Cards stack
+     * @see {@link Cards#reset}
+     */
+    resetDialog(): Promise<Cards.ConfiguredInstance | false | null>;
+
+    override deleteDialog(options?: Partial<DialogOptions>): Promise<this | false | null | undefined>;
+
+    static override createDialog<T extends Document.AnyConstructor>(
+      this: T,
+      data?: DeepPartial<Document.ConstructorDataFor<T> & Record<string, unknown>>,
+      context?: Pick<DatabaseOperationsFor<Cards["documentName"], "create">, "parent" | "pack"> &
+        InexactPartial<
+          DialogOptions & {
+            /** A restriction the selectable sub-types of the Dialog. */
+            types: string[];
+          }
+        >,
+    ): Promise<Document.ToConfiguredInstance<T> | null | undefined>;
+  }
+}

package/src/foundry/client/data/documents/chat-message.d.mts

@@ -0,0 +1,230 @@
+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";
+import type BaseChatMessage from "../../../common/documents/chat-message.d.mts";
+
+declare global {
+  namespace ChatMessage {
+    type Metadata = Document.MetadataFor<ChatMessage>;
+
+    type ConfiguredClass = Document.ConfiguredClassForName<"ChatMessage">;
+    type ConfiguredInstance = Document.ConfiguredInstanceForName<"ChatMessage">;
+
+    /* eslint-disable @typescript-eslint/no-empty-object-type */
+    interface DatabaseOperations
+      extends DocumentDatabaseOperations<
+        ChatMessage,
+        { rollMode: foundry.CONST.DICE_ROLL_MODES; chatBubble: boolean },
+        {},
+        {}
+      > {}
+    /* eslint-enable @typescript-eslint/no-empty-object-type */
+
+    // Helpful aliases
+    type TypeNames = BaseChatMessage.TypeNames;
+    type ConstructorData = BaseChatMessage.ConstructorData;
+    type UpdateData = BaseChatMessage.UpdateData;
+    type Schema = BaseChatMessage.Schema;
+    type Source = BaseChatMessage.Source;
+
+    interface GetSpeakerOptions {
+      /** The Scene in which the speaker resides */
+      scene: Scene | null;
+
+      /** The Actor whom is speaking */
+      actor: Actor | null | undefined;
+
+      /** The Token whom is speaking */
+      token: TokenDocument | Token | null | undefined;
+
+      /** The name of the speaker to display */
+      alias: string | undefined;
+    }
+
+    interface MessageData {
+      message: Document.ToObjectFalseType<ChatMessage>;
+      user: Document.Stored<User.ConfiguredInstance>;
+      author: User.ConfiguredInstance | undefined;
+      alias: string;
+      cssClass: string;
+      isWhisper: boolean;
+      canDelete: boolean;
+      whisperTo: string;
+    }
+  }
+
+  /**
+   * The client-side ChatMessage document which extends the common BaseChatMessage abstraction.
+   * Each ChatMessage document contains ChatMessageData which defines its data schema.
+   *
+   * @see {@link Messages}                The world-level collection of ChatMessage documents
+   *
+   */
+  class ChatMessage extends ClientDocumentMixin(foundry.documents.BaseChatMessage) {
+    static override metadata: ChatMessage.Metadata;
+
+    /**
+     * Is the display of dice rolls in this message collapsed (false) or expanded (true)
+     * @defaultValue `false`
+     * @internal
+     */
+    protected _rollExpanded: boolean;
+
+    /**
+     * Is this ChatMessage currently displayed in the sidebar ChatLog?
+     * @defaultValue `false`
+     */
+    logged: boolean;
+
+    /**
+     * Return the recommended String alias for this message.
+     * The alias could be a Token name in the case of in-character messages or dice rolls.
+     * Alternatively it could be a User name in the case of OOC chat or whispers.
+     */
+    get alias(): string;
+
+    /**
+     * Is the current User the author of this message?
+     */
+    get isAuthor(): boolean;
+
+    /**
+     * Return whether the content of the message is visible to the current user.
+     * For certain dice rolls, for example, the message itself may be visible while the content of that message is not.
+     */
+    get isContentVisible(): boolean;
+
+    /**
+     * Test whether the chat message contains a dice roll
+     */
+    get isRoll(): boolean;
+
+    /**
+     * Return whether the ChatMessage is visible to the current User.
+     * Messages may not be visible if they are private whispers.
+     */
+    get visible(): boolean;
+
+    override prepareDerivedData(): void;
+
+    /**
+     * Transform a provided object of ChatMessage data by applying a certain rollMode to the data object.
+     * @param chatData - The object of ChatMessage data prior to applying a rollMode preference
+     * @param rollMode - The rollMode preference to apply to this message data
+     * @returns The modified ChatMessage data with rollMode preferences applied
+     */
+    static applyRollMode(
+      chatData: foundry.documents.BaseChatMessage.ConstructorData,
+      rollMode: keyof typeof CONFIG.Dice.rollModes | "roll",
+    ): foundry.documents.BaseChatMessage.ConstructorData;
+
+    /**
+     * 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: keyof typeof CONFIG.Dice.rollModes | "roll"): void;
+
+    /**
+     * Attempt to determine who is the speaking character (and token) for a certain Chat Message
+     * First assume that the currently controlled Token is the speaker
+     *
+     * @param options - (default: `{}`)
+     *
+     * @returns The identified speaker data
+     */
+    static getSpeaker(options?: InexactPartial<ChatMessage.GetSpeakerOptions>): ChatMessage["_source"]["speaker"];
+
+    /**
+     * A helper to prepare the speaker object based on a target TokenDocument
+     * @param options - Options which affect speaker identification
+     * @returns The identified speaker data
+     */
+    protected static _getSpeakerFromToken(options: {
+      /** The TokenDocument of the speaker */
+      token: TokenDocument;
+
+      /** The name of the speaker to display */
+      alias?: string | undefined;
+    }): ChatMessage["_source"]["speaker"];
+
+    /**
+     * A helper to prepare the speaker object based on a target Actor
+     * @param options - Options which affect speaker identification
+     * @returns The identified speaker data
+     */
+    protected static _getSpeakerFromActor(options: {
+      /** The Scene is which the speaker resides */
+      scene?: Scene | undefined;
+
+      /** The Actor that is speaking */
+      actor: Actor;
+
+      /** The name of the speaker to display */
+      alias?: string | undefined;
+    }): ChatMessage["_source"]["speaker"];
+
+    /**
+     * A helper to prepare the speaker object based on a target User
+     * @param options - Options which affect speaker identification
+     * @returns The identified speaker data
+     */
+    protected static _getSpeakerFromUser(options: {
+      /** The Scene in which the speaker resides */
+      scene?: Scene | undefined;
+
+      /** The User who is speaking */
+      user: User;
+
+      /** The name of the speaker to display */
+      alias?: string | undefined;
+    }): ChatMessage["_source"]["speaker"];
+
+    /**
+     * Obtain an Actor instance which represents the speaker of this message (if any)
+     * @param speaker - The speaker data object
+     */
+    static getSpeakerActor(speaker: ChatMessage["_source"]["speaker"]): Actor.ConfiguredInstance | null;
+
+    /**
+     * Obtain a data object used to evaluate any dice rolls associated with this particular chat message
+     */
+    getRollData(): Record<string, unknown>;
+
+    /**
+     * Given a string whisper target, return an Array of the user IDs which should be targeted for the whisper
+     *
+     * @param name - The target name of the whisper target
+     * @returns An array of User instances
+     */
+    static getWhisperRecipients(name: string): Document.Stored<User.ConfiguredInstance>[];
+
+    /**
+     * Render the HTML for the ChatMessage which should be added to the log
+     */
+    getHTML(): Promise<JQuery>;
+
+    /**
+     * Render the inner HTML content for ROLL type messages.
+     * @param messageData - The chat message data used to render the message HTML
+     * @internal
+     */
+    protected _renderRollContent(messageData: ChatMessage.MessageData): Promise<void>;
+
+    /**
+     * Render HTML for the array of Roll objects included in this message.
+     * @param isPrivate - Is the chat message private?
+     * @returns The rendered HTML string
+     */
+    protected _renderRollHTML(isPrivate: boolean): Promise<string>;
+
+    /**
+     * @privateRemarks _preCreate, _onCreate, _onUpdate, and _onDelete 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.
+     */
+
+    /**
+     * Export the content of the chat message into a standardized log format
+     */
+    export(): string;
+  }
+}