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

package/src/foundry/client/data/abstract/directory-collection-mixin.d.mts

@@ -0,0 +1,135 @@
+import type { Mixin } from "../../../../types/utils.d.mts";
+import type Document from "../../../common/abstract/document.d.mts";
+
+type DirectoryCollectionMixin_DocumentCollection_Static = DirectoryCollection<DirectoryCollection.DirectoryTypes> &
+  DocumentCollection<Document.AnyConstructor, string>;
+
+export interface DirectoryCollectionMixin_DocumentCollection_Interface
+  extends DirectoryCollectionMixin_DocumentCollection_Static {
+  new <T extends Document.AnyConstructor, Name extends string>(
+    ...args: ConstructorParameters<typeof DocumentCollection>
+  ): DirectoryCollection<Document.ToConfiguredInstance<T>> & DocumentCollection<Document.ToConfiguredClass<T>, Name>;
+}
+
+type DirectoryCollectionMixin_Collection_Static = DirectoryCollection<DirectoryCollection.DirectoryTypes> &
+  Collection<CompendiumCollection<CompendiumCollection.Metadata>>;
+
+export interface DirectoryCollectionMixin_Collection_Interface extends DirectoryCollectionMixin_Collection_Static {
+  new (
+    ...args: ConstructorParameters<typeof Collection>
+  ): DirectoryCollection<CompendiumCollection<CompendiumCollection.Metadata>> &
+    Collection<CompendiumCollection<CompendiumCollection.Metadata>>;
+}
+
+/**
+ * An extension of the Collection class which adds behaviors specific to tree-based collections of entries and folders.
+ */
+// TODO: T should probably extend a subset of documents | CompendiumCollection
+declare class DirectoryCollection<T extends DirectoryCollection.DirectoryTypes> {
+  /** @privateRemarks All mixin classses need a constructor like this */
+  constructor(...args: any[]);
+
+  /**
+   * Reference the set of Folders which contain documents in this collection
+   */
+  get folders(): Collection<Folder>;
+
+  /**
+   * The built tree structure of the DocumentCollection
+   */
+  get tree(): DirectoryCollection.TreeNode<T>;
+
+  /**
+   * The current search mode for this collection
+   */
+  get searchMode(): foundry.CONST.DIRECTORY_SEARCH_MODES;
+
+  /**
+   * Toggle the search mode for this collection between "name" and "full" text search
+   */
+  toggleSearchMode(): void;
+
+  /**
+   * The current sort mode used to order the top level entries in this collection
+   */
+  // TODO: Should have a helper type for these sorting modes or something
+  get sortingMode(): "m" | "a";
+
+  /**
+   * Toggle the sorting mode for this collection between "a" (Alphabetical) and "m" (Manual by sort property)
+   */
+  toggleSortingMode(): void;
+
+  /**
+   * The maximum depth of folder nesting which is allowed in this collection
+   * @defaultValue `CONST.FOLDER_MAX_DEPTH`
+   */
+  get maxFolderDepth(): number;
+
+  /**
+   * Return a reference to list of entries which are visible to the User in this tree
+   */
+  protected _getVisibleTreeContents(): T[];
+
+  /**
+   * Initialize the tree by categorizing folders and entries into a hierarchical tree structure.
+   */
+  initializeTree(): void;
+
+  /**
+   * Creates the list of Folder options in this Collection in hierarchical order
+   * for populating the options of a select tag.
+   */
+  protected _formatFolderSelectOptions(): { id: string; name: string }[];
+
+  /**
+   * Sort two Entries by name, alphabetically.
+   * @param a - Some Entry
+   * @param b - Some other Entry
+   * @returns The sort order between entries a and b
+   */
+  protected static _sortAlphabetical(
+    a: DirectoryCollection.AlphabeticalSortEntry,
+    b: DirectoryCollection.AlphabeticalSortEntry,
+  ): number;
+
+  /**
+   * Sort two Entries using their numeric sort fields.
+   * @param a - Some Entry
+   * @param b - Some other Entry
+   * @returns The sort order between Entries a and b
+   */
+  protected static _sortStandard(
+    a: DirectoryCollection.StandardSortEntry,
+    b: DirectoryCollection.StandardSortEntry,
+  ): number;
+}
+
+declare global {
+  /**
+   * A mixin which adds directory functionality to a DocumentCollection, such as folders, tree structures, and sorting.
+   * @param BaseCollection - The base collection class to extend
+   * @returns A Collection mixed with DirectoryCollection functionality
+   */
+  function DirectoryCollectionMixin<
+    T extends DirectoryCollection.DirectoryTypes,
+    BaseCollection extends foundry.utils.Collection.AnyConstructor,
+  >(BaseCollection: BaseCollection): Mixin<typeof DirectoryCollection<T>, BaseCollection>;
+
+  namespace DirectoryCollection {
+    // TODO: Refine type based on CONST.FOLDER_DOCUMENT_TYPES
+    type DirectoryTypes = object;
+
+    interface TreeNode<T> {
+      children: TreeNode<T>[];
+      depth: number;
+      entries: T[];
+      folder: Folder;
+      root: boolean;
+      visible: boolean;
+    }
+
+    type AlphabeticalSortEntry = { name: string } & object;
+    type StandardSortEntry = { sort: number } & object;
+  }
+}

package/src/foundry/client/data/abstract/document-collection.d.mts

@@ -0,0 +1,204 @@
+import type { DeepPartial, InexactPartial } from "../../../../types/utils.d.mts";
+import type Document from "../../../common/abstract/document.d.mts";
+
+declare global {
+  /**
+   * An abstract subclass of the Collection container which defines a collection of Document instances.
+   */
+  class DocumentCollection<T extends Document.AnyConstructor, Name extends string> extends foundry.utils.Collection<
+    Document.ToConfiguredStored<T>
+  > {
+    constructor(data: InstanceType<T>["_source"][]);
+
+    /**
+     * The source data array from which the Documents in the WorldCollection are created
+     */
+    _source: InstanceType<T>["_source"][];
+
+    /**
+     * An Array of application references which will be automatically updated when the collection content changes
+     * @defaultValue `[]`
+     */
+    apps: Application[];
+
+    /**
+     * Initialize the DocumentCollection by constructing any initially provided Document instances
+     * @internal
+     */
+    protected _initialize(): void;
+
+    /**
+     * A reference to the Document class definition which is contained within this DocumentCollection.
+     */
+    get documentClass(): Document.ToConfiguredClass<T>;
+
+    /**
+     * A reference to the named Document class which is contained within this DocumentCollection.
+     * @remarks This accessor is abstract: A subclass of DocumentCollection must implement the documentName getter
+     */
+    get documentName(): Document.ToConfiguredClass<T>["metadata"]["name"];
+
+    /**
+     * The base Document type which is contained within this DocumentCollection
+     */
+    static documentName: string;
+
+    /**
+     * Record the set of document ids where the Document was not initialized because of invalid source data
+     */
+    invalidDocumentIds: Set<string>;
+
+    /**
+     * The Collection class name
+     */
+    get name(): Name;
+
+    /**
+     * Instantiate a Document for inclusion in the Collection.
+     * @param data    - The Document data
+     * @param context - Document creation context
+     */
+    createDocument(
+      // TODO: This probably needs refinement for mandatory assignment fields like name
+      data: DeepPartial<InstanceType<T>["_source"]>,
+      context: Document.ConstructionContext<Document.Any | null>,
+    ): InstanceType<T>;
+
+    /**
+     * Obtain a temporary Document instance for a document id which currently has invalid source data.
+     * @param id - A document ID with invalid source data.
+     * @param options - Additional options to configure retrieval.
+     * @returns An in-memory instance for the invalid Document
+     * @throws If strict is true and the requested ID is not in the set of invalid IDs for this collection.
+     */
+    getInvalid(
+      id: string,
+      options?: InexactPartial<{
+        /**
+         * Throw an Error if the requested ID is not in the set of invalid IDs for this collection.
+         */
+        strict: boolean;
+      }>,
+    ): unknown;
+
+    get(
+      key: string,
+      options?: InexactPartial<{
+        /**
+         * Throw an Error if the requested Embedded Document does not exist.
+         * @defaultValue `false`
+         */
+        strict: false;
+        /**
+         * Allow retrieving an invalid Embedded Document.
+         * @defaultValue `false`
+         */
+        invalid: false;
+      }>,
+    ): Document.ToConfiguredStored<T> | undefined;
+    get(key: string, options: { strict: true; invalid?: false }): Document.ToConfiguredStored<T>;
+    get(key: string, options: { strict?: boolean; invalid: true }): unknown;
+
+    /**
+     * @remarks The parameter `id` is ignored, instead `document.id` is used as the key.
+     */
+    set(id: string, document: Document.ToConfiguredStored<T>): this;
+
+    /** @remarks Actually returns void */
+    delete: (id: string) => boolean;
+
+    /**
+     * Render any Applications associated with this DocumentCollection.
+     */
+    render(force?: boolean, options?: ApplicationOptions): void;
+
+    /**
+     * Get the searchable fields for a given document or index, based on its data model
+     * @param documentName    - The document type name
+     * @param documentSubtype - The document subtype name
+     * @param isEmbedded      - Whether the document is an embedded object
+     * @returns The dot-delimited property paths of searchable fields
+     */
+    // TODO: Could significantly improve this with type defs
+    static getSearchableFields(
+      documentName: foundry.CONST.DOCUMENT_TYPES,
+      documentSubtype?: string,
+      isEmbedded?: boolean,
+    ): Set<string>;
+
+    /**
+     * Find all Documents which match a given search term using a full-text search against their indexed HTML fields and their name.
+     * If filters are provided, results are filtered to only those that match the provided values.
+     * @param search   - An object configuring the search
+     */
+    search(
+      search?: InexactPartial<{
+        /**
+         * A case-insensitive search string
+         * @defaultValue `""`
+         */
+        query: string;
+        /**
+         * An array of filters to apply
+         * @defaultValue `[]`
+         */
+        filters: FieldFilter[];
+        /**
+         * An array of document IDs to exclude from search results
+         * @defaultValue `[]`
+         */
+        exclude: string[];
+      }>,
+    ): Document.ToConfiguredInstance<T>[];
+
+    /**
+     * Update all objects in this DocumentCollection with a provided transformation.
+     * Conditionally filter to only apply to Entities which match a certain condition.
+     * @param transformation - An object of data or function to apply to all matched objects
+     * @param condition      - A function which tests whether to target each object
+     *                         (default: `null`)
+     * @param options        - Additional options passed to Document.updateDocuments
+     *                         (default: `{}`)
+     * @returns An array of updated data once the operation is complete
+     */
+    updateAll(
+      transformation:
+        | DeepPartial<Document.ToConfiguredInstance<T>["_source"]>
+        | ((doc: Document.ToConfiguredStored<T>) => DeepPartial<Document.ToConfiguredInstance<T>["_source"]>),
+      condition?: ((obj: Document.ToConfiguredStored<T>) => boolean) | null,
+      options?: Document.OnUpdateOptions<T["metadata"]["name"]>,
+    ): ReturnType<this["documentClass"]["updateDocuments"]>;
+  }
+
+  namespace DocumentCollection {
+    type Any = DocumentCollection<any, any>;
+
+    namespace RenderContext {
+      interface Base<T extends Document.AnyConstructor> {
+        documentType: T["metadata"]["name"];
+        documents: Document.ToConfiguredStored<T>[];
+
+        /** @deprecated The "entities" render context is deprecated. Please use "documents" instead. */
+        get entities(): this["documents"];
+
+        /** @deprecated The "entityType" render context is deprecated. Please use "documentType" instead. */
+        get entityType(): this["documentType"];
+      }
+
+      interface Create<T extends Document.AnyConstructor> extends Base<T> {
+        action: "create";
+        data: (InstanceType<T>["_source"] & { _id: string })[];
+      }
+
+      interface Update<T extends Document.AnyConstructor> extends Base<T> {
+        action: "update";
+        data: (DeepPartial<InstanceType<T>["_source"]> & { _id: string })[];
+      }
+
+      interface Delete<T extends Document.AnyConstructor> extends Base<T> {
+        action: "delete";
+        data: string[];
+      }
+    }
+  }
+}

package/src/foundry/client/data/abstract/index.d.mts

@@ -0,0 +1,5 @@
+import "./canvas-document.d.mts";
+import "./client-document.d.mts";
+import "./directory-collection-mixin.d.mts";
+import "./document-collection.d.mts";
+import "./world-collection.d.mts";

package/src/foundry/client/data/abstract/world-collection.d.mts

@@ -0,0 +1,171 @@
+import type { DeepPartial, InexactPartial } from "../../../../types/utils.d.mts";
+import type Document from "../../../common/abstract/document.d.mts";
+import type { DirectoryCollectionMixin_DocumentCollection_Interface } from "./directory-collection-mixin.d.mts";
+
+declare const DirectoryCollectionMixin_DocumentCollection: DirectoryCollectionMixin_DocumentCollection_Interface;
+
+declare global {
+  /**
+   * A collection of world-level Document objects with a singleton instance per primary Document type.
+   * Each primary Document type has an associated subclass of WorldCollection which contains them.
+   * @see {@link Game#collections}
+   */
+  abstract class WorldCollection<
+    T extends Document.AnyConstructor,
+    Name extends string,
+  > extends DirectoryCollectionMixin_DocumentCollection<T, Name> {
+    /**
+     * Reference the set of Folders which contain documents in this collection
+     */
+    get folders(): Collection<Folder>;
+
+    /**
+     * Return a reference to the SidebarDirectory application for this WorldCollection.
+     * @remarks
+     * In the case where `Lowercase<Name>` is not a property of {@link ui}, this actually always returns `undefined`,
+     * but {@link RollTables} overrides this, so we need to allow a wider return type.
+     */
+    get directory(): Lowercase<Name> extends keyof typeof ui
+      ? (typeof ui)[Lowercase<Name>]
+      :
+          | (Document.ToConfiguredClass<T>["metadata"]["name"] extends foundry.CONST.FOLDER_DOCUMENT_TYPES
+              ? DocumentDirectory<Document.ToConfiguredClass<T>["metadata"]["name"]>
+              : never)
+          | SidebarTab
+          | undefined
+          | null;
+
+    /**
+     * Return a reference to the singleton instance of this WorldCollection, or null if it has not yet been created.
+     */
+    static get instance(): WorldCollection<Document.AnyConstructor, any>; // TODO: Find a way to type this more concretely. One option would be to separate the static and non static side of this class, which allows accessing the the static this type to use the `documentName`.
+
+    protected override _getVisibleTreeContents(): Document.ToConfiguredInstance<T>[];
+
+    /**
+     * Import a Document from a Compendium collection, adding it to the current World.
+     * @param pack       - The CompendiumCollection instance from which to import
+     * @param id         - The ID of the compendium entry to import
+     * @param updateData - Optional additional data used to modify the imported Document before it is created
+     *                     (default: `{}`)
+     * @param options    - Optional arguments passed to the {@link WorldCollection#fromCompendium} and {@link Document.create} methods
+     *                     (default: `{}`)
+     * @returns The imported Document instance
+     */
+
+    /**
+     * @privateRemarks We've added everything in WorldCollection.FromCompendiumOptions to DatabaseCreateOperation
+     * because they get passed through to Document.create() by this function.  So the
+     * union type isn't really needed.  Leaving it because it feels like foundry will pull
+     * those back out in the future (and we could miss it because we added them to
+     * DatabaseCreateOperation but the foundry typedef doesn't have them).
+     */
+    importFromCompendium(
+      pack: CompendiumCollection<
+        CompendiumCollection.Metadata & { type: Document.ToConfiguredClass<T>["metadata"]["name"] }
+      >,
+      id: string,
+      updateData?: DeepPartial<Document.ToConfiguredInstance<T>["_source"]>,
+      options?: InexactPartial<Document.OnCreateOptions<T["metadata"]["name"]> & WorldCollection.FromCompendiumOptions>,
+    ): Promise<Document.ToConfiguredStored<T>>;
+
+    /**
+     * Apply data transformations when importing a Document from a Compendium pack
+     * @param document - The source Document, or a plain data object
+     * @param options  - Additional options which modify how the document is imported
+     *                   (default: `{}`)
+     * @returns The processed data ready for world Document creation
+     * @remarks FromCompendiumOptions is inflated to account for expanded downstream use
+     */
+    fromCompendium<
+      FolderOpt extends boolean = false,
+      SortOpt extends boolean = true,
+      OwnershipOpt extends boolean = false,
+      IdOpt extends boolean = false,
+    >(
+      document: Document.ToConfiguredInstance<T> | Document.ConstructorDataFor<T>,
+      options?: InexactPartial<WorldCollection.FromCompendiumOptions<FolderOpt, SortOpt, OwnershipOpt, IdOpt>>,
+    ): Omit<
+      Document.ToConfiguredInstance<T>["_source"],
+      | ClientDocument.OmitProperty<FolderOpt, "folder">
+      | ClientDocument.OmitProperty<SortOpt, "sort" | "navigation" | "navOrder">
+      | ClientDocument.OmitProperty<OwnershipOpt, "ownership">
+      | (IdOpt extends false ? "_id" : never)
+    >;
+
+    /**
+     * Register a Document sheet class as a candidate which can be used to display Documents of a given type.
+     * See {@link DocumentSheetConfig.registerSheet} for details.
+     * @see DocumentSheetConfig.registerSheet
+     *
+     * @example <caption>Register a new ActorSheet subclass for use with certain Actor types.</caption>
+     * ```typescript
+     * Actors.registerSheet("dnd5e", ActorSheet5eCharacter, { types: ["character], makeDefault: true });
+     * ```
+     */
+    static registerSheet(...args: DropFirst<Parameters<typeof DocumentSheetConfig.registerSheet>>): void;
+
+    /**
+     * Unregister a Document sheet class, removing it from the list of available sheet Applications to use.
+     * See {@link DocumentSheetConfig.unregisterSheet} for details.
+     * @see DocumentSheetConfig.unregisterSheet
+     *
+     * @example <caption>Deregister the default ActorSheet subclass to replace it with others.</caption>
+     * Actors.unregisterSheet("core", ActorSheet);
+     */
+    static unregisterSheet(...args: DropFirst<Parameters<typeof DocumentSheetConfig.unregisterSheet>>): void;
+
+    /**
+     * Return an array of currently registered sheet classes for this Document type.
+     * @remarks
+     * This is documented to return only {@link DocumentSheet}s but {@link DrawingConfig} is just a
+     * {@link FormApplication}. See https://gitlab.com/foundrynet/foundryvtt/-/issues/6454.
+     */
+    static get registeredSheets(): FormApplication[];
+  }
+
+  namespace WorldCollection {
+    interface FromCompendiumOptions<
+      FolderOpt extends boolean = false,
+      SortOpt extends boolean = true,
+      OwnershipOpt extends boolean = false,
+      IdOpt extends boolean = false,
+      StateOpt extends boolean = false,
+    > {
+      /**
+       * Add flags which track the import source
+       * @defaultValue `false`
+       */
+      addFlags: boolean;
+
+      /**
+       * Clear the currently assigned folder
+       * @defaultValue
+       */
+      clearFolder: FolderOpt;
+
+      /**
+       * Clear the currently assigned folder and sort order
+       * @defaultValue `true`
+       */
+      clearSort: SortOpt;
+
+      /**
+       * Clear document permissions
+       * @defaultValue `true`
+       */
+      clearOwnership: OwnershipOpt;
+
+      /**
+       * Retain the Document id from the source Compendium
+       * @defaultValue `false`
+       */
+      keepId: IdOpt;
+
+      /** @remarks used by Scene#fromCompendium */
+      clearState: StateOpt;
+    }
+  }
+}
+
+type DropFirst<T extends Array<unknown>> = T extends [unknown, ...infer V] ? V : T;

package/src/foundry/client/data/collections/actors.d.mts

@@ -0,0 +1,41 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * The singleton collection of Actor documents which exist within the active World.
+   * This Collection is accessible within the Game object as game.actors.
+   *
+   * @see {@link Actor} The Actor document
+   * @see {@link ActorDirectory} The ActorDirectory sidebar directory
+   *
+   * @example <caption>Retrieve an existing Actor by its id</caption>
+   * ```typescript
+   * let actor = game.actors.get(actorId);
+   * ```
+   */
+  class Actors extends WorldCollection<typeof foundry.documents.BaseActor, "Actors"> {
+    /**
+     * A mapping of synthetic Token Actors which are currently active within the viewed Scene.
+     * Each Actor is referenced by the Token.id.
+     */
+    get tokens(): Partial<Record<string, Actor.ConfiguredInstance>>;
+
+    static documentName: "Actor";
+
+    override fromCompendium<
+      FolderOpt extends boolean = false,
+      SortOpt extends boolean = true,
+      OwnershipOpt extends boolean = false,
+      IdOpt extends boolean = false,
+    >(
+      document: Actor.ConfiguredInstance | foundry.documents.BaseActor.ConstructorData,
+      options?: InexactPartial<WorldCollection.FromCompendiumOptions<FolderOpt, SortOpt, OwnershipOpt, IdOpt>>,
+    ): Omit<
+      Actor["_source"],
+      | ClientDocument.OmitProperty<FolderOpt, "folder">
+      | ClientDocument.OmitProperty<SortOpt, "sort" | "navigation" | "navOrder">
+      | ClientDocument.OmitProperty<OwnershipOpt, "ownership">
+      | (IdOpt extends false ? "_id" : never)
+    >;
+  }
+}

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

@@ -0,0 +1,12 @@
+export {};
+
+declare global {
+  /**
+   * The collection of Cards documents which exist within the active World.
+   * This Collection is accessible within the Game object as game.cards.
+   * @see {@link Cards} The Cards document
+   */
+  class CardStacks extends WorldCollection<typeof foundry.documents.BaseCards, "Cards"> {
+    static documentName: "Cards";
+  }
+}

package/src/foundry/client/data/collections/combats.d.mts

@@ -0,0 +1,43 @@
+import type Document from "../../../common/abstract/document.d.mts";
+
+declare global {
+  /**
+   * The singleton collection of Combat documents which exist within the active World.
+   * This Collection is accessible within the Game object as game.combats.
+   *
+   * @see {@link Combat} The Combat document
+   * @see {@link CombatTracker} The CombatTracker sidebar directory
+   */
+  class CombatEncounters extends WorldCollection<typeof foundry.documents.BaseCombat, "CombatEncounters"> {
+    static documentName: "Combat";
+
+    /**
+     * Provide the settings object which configures the Combat document
+     */
+    static get settings(): ClientSettings.SettingInitializedType<"core", Combat.CONFIG_SETTING>;
+
+    override get directory(): (typeof ui)["combat"];
+
+    /**
+     * Get an Array of Combat instances which apply to the current canvas scene
+     */
+    get combats(): ReturnType<this["filter"]>;
+
+    /**
+     * The currently active Combat instance
+     */
+    get active(): ReturnType<this["find"]>;
+
+    /**
+     * The currently viewed Combat encounter
+     */
+    get viewed(): Document.Stored<Combat.ConfiguredInstance> | null;
+
+    /**
+     * When a Token is deleted, remove it as a combatant from any combat encounters which included the Token
+     * @param sceneId - The Scene id within which a Token is being deleted
+     * @param tokenId - The Token id being deleted
+     */
+    protected _onDeleteToken(sceneId: string, tokenId: string): Promise<void>;
+  }
+}