@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.345.1-beta.20250704.94554

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

@@ -0,0 +1,132 @@
+import type { FixedInstanceType, Mixin } from "#utils";
+
+/**
+ * An extension of the Collection class which adds behaviors specific to tree-based collections of entries and folders.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+declare class DirectoryCollection {
+  /** @privateRemarks All mixin classes need a constructor like this */
+  constructor(...args: any[]);
+
+  // Note(LukeAbby): This isn't really a property on this class but rather it exists on `Collection`.
+  // However since this is only used when merged with a Collection class, it's fine to define it here.
+  contents: unknown;
+
+  /**
+   * Reference the set of Folders which contain documents in this collection
+   */
+  get folders(): Collection<Folder.Stored, Collection.Methods.Any>;
+
+  /**
+   * The built tree structure of the DocumentCollection
+   */
+  get tree(): DirectoryCollectionMixin.TreeNode<this["contents"]>;
+
+  /**
+   * 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(): this["contents"];
+
+  /**
+   * 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: DirectoryCollectionMixin.AlphabeticalSortEntry,
+    b: DirectoryCollectionMixin.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: DirectoryCollectionMixin.StandardSortEntry,
+    b: DirectoryCollectionMixin.StandardSortEntry,
+  ): number;
+
+  // Note(LukeAbby): This override has been commented out because it was being added as an overload
+  // with `DocumentCollection` and causing problems. The main solution would be to use `this` but
+  // that's awkward. This method really only makes sense on `DocumentCollection` subclasses as well.
+
+  // protected _onModifyContents<A extends DatabaseAction>(
+  //   action: A,
+  //   documents: readonly Document.AnyStored[],
+  //   result: readonly AnyObject[] | readonly string[],
+  //   operation: DatabaseOperationMap[A],
+  //   user: User.Implementation,
+  // ): void;
+}
+
+/**
+ * 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
+ */
+declare function DirectoryCollectionMixin<BaseCollection extends foundry.utils.Collection.AnyConstructor>(
+  BaseCollection: BaseCollection,
+): Mixin<typeof DirectoryCollection, BaseCollection>;
+
+declare namespace DirectoryCollectionMixin {
+  interface AnyMixedConstructor
+    extends ReturnType<typeof DirectoryCollectionMixin<foundry.utils.Collection.AnyConstructor>> {}
+  interface AnyMixed extends FixedInstanceType<AnyMixedConstructor> {}
+
+  type BaseClass = foundry.utils.Collection.AnyConstructor;
+
+  interface TreeNode<T> {
+    children: TreeNode<T>[];
+    depth: number;
+    entries: T[];
+    folder: Folder.Implementation;
+    root: boolean;
+    visible: boolean;
+  }
+
+  type AlphabeticalSortEntry = { name: string } & object;
+  type StandardSortEntry = { sort: number } & object;
+}
+
+export default DirectoryCollectionMixin;

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

@@ -0,0 +1,243 @@
+import type { AnyObject, DeepPartial, InexactPartial, GetKey } from "#utils";
+import type { DatabaseAction, DatabaseOperationMap, DatabaseUpdateOperation } from "#common/abstract/_types.d.mts";
+import type Document from "#common/abstract/document.d.mts";
+import type Application from "#client/appv1/api/application-v1.d.mts";
+import type ApplicationV2 from "#client/applications/api/application.d.mts";
+
+/**
+ * An abstract subclass of the Collection container which defines a collection of Document instances.
+ */
+declare class DocumentCollection<
+  DocumentType extends Document.Type,
+  Methods extends Collection.Methods.Any = DocumentCollection.Methods<DocumentType>,
+> extends foundry.utils.Collection<Document.StoredForName<DocumentType>, Methods> {
+  constructor(data: Document.SourceForName<DocumentType>[]);
+
+  /**
+   * The source data array from which the Documents in the WorldCollection are created
+   */
+  _source: Document.SourceForName<DocumentType>[];
+
+  /**
+   * An Array of application references which will be automatically updated when the collection content changes
+   * @defaultValue `[]`
+   */
+  apps: (Application.Any | ApplicationV2.Any)[];
+
+  /**
+   * 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.ImplementationClassFor<DocumentType>;
+
+  /**
+   * 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(): DocumentType;
+
+  /**
+   * 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(): string;
+
+  /**
+   * Instantiate a Document for inclusion in the Collection.
+   * @param data    - The Document data
+   * @param context - Document creation context
+   */
+  createDocument(
+    data: Document.CreateDataForName<DocumentType>,
+    // TODO: Should be `Document.ParentOf<T>` or some equivalent.
+    context: Document.ConstructionContext<Document.Any | null>,
+  ): DocumentType;
+
+  /**
+   * 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?: DocumentCollection.GetInvalidOptions): Document.InvalidForName<DocumentType>;
+
+  get: Methods["get"];
+
+  /**
+   * @remarks The parameter `id` is ignored, instead `document.id` is used as the key.
+   */
+  set(id: string, document: Document.StoredForName<DocumentType>): this;
+
+  /** @remarks Actually returns void */
+  delete: (id: string) => boolean;
+
+  /**
+   * Render any Applications associated with this DocumentCollection.
+   * @param force   - Force rendering  (default: `false`)
+   * @param options - Optional options (default: `{}`)
+   */
+  render(force?: boolean, options?: Application.Options | ApplicationV2.RenderOptions): void;
+
+  /**
+   * Get the searchable fields for a given document or index, based on its data model
+   * @param documentName - The document name
+   * @param type         - A document subtype
+   * @returns A record of searchable DataField definitions
+   */
+  // TODO: Could significantly improve this with type defs
+  static getSearchableFields<T extends foundry.abstract.Document.Type>(
+    documentName: T,
+    type?: foundry.abstract.Document.SubTypesOf<T>,
+  ): Record<string, DocumentCollection.SearchableField>;
+
+  /**
+   * 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?: DocumentCollection.SearchOptions): Document.ImplementationFor<DocumentType>[];
+
+  /**
+   * 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:
+      | Document.UpdateDataForName<DocumentType>
+      | ((doc: Document.StoredForName<DocumentType>) => Document.UpdateDataForName<DocumentType>),
+    condition?: ((obj: Document.StoredForName<DocumentType>) => boolean) | null,
+    options?: Document.Database.UpdateDocumentsOperation<DatabaseUpdateOperation>,
+  ): ReturnType<this["documentClass"]["updateDocuments"]>;
+
+  /**
+   * Follow-up actions to take when a database operation modifies Documents in this DocumentCollection.
+   * @param action    - The database action performed
+   * @param documents - The array of modified Documents
+   * @param result    - The result of the database operation
+   * @param operation - Database operation details
+   * @param user      - The User who performed the operation
+   */
+  _onModifyContents<A extends DatabaseAction>(
+    action: A,
+    documents: Document.StoredForName<DocumentType>[],
+    result: readonly AnyObject[] | readonly string[],
+    operation: DatabaseOperationMap[A],
+    user: User.Implementation,
+  ): void;
+}
+
+declare namespace DocumentCollection {
+  interface Any extends DocumentCollection<Document.Type, Collection.Methods.Any> {}
+
+  interface Methods<T extends Document.Type> {
+    get<Options extends DocumentCollection.GetOptions | undefined = undefined>(
+      key: string,
+      options?: Options,
+    ): DocumentCollection.GetReturnType<T, Options>;
+  }
+
+  namespace RenderContext {
+    interface Base<T extends Document.Type> {
+      documentType: T;
+      documents: Document.StoredForName<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.Type> extends Base<T> {
+      action: "create";
+      data: (Document.SourceForName<T> & { _id: string })[];
+    }
+
+    interface Update<T extends Document.Type> extends Base<T> {
+      action: "update";
+      data: (DeepPartial<Document.SourceForName<T>> & { _id: string })[];
+    }
+
+    interface Delete<T extends Document.Type> extends Base<T> {
+      action: "delete";
+      data: string[];
+    }
+  }
+
+  /** @internal */
+  interface _SearchOptions {
+    /**
+     * A case-insensitive search string
+     * @defaultValue `""`
+     */
+    query: string;
+
+    /**
+     * An array of filters to apply
+     * @defaultValue `[]`
+     */
+    filters: foundry.applications.ux.SearchFilter.FieldFilter[];
+
+    /**
+     * An array of document IDs to exclude from search results
+     * @defaultValue `[]`
+     */
+    exclude: string[];
+  }
+
+  interface SearchOptions extends InexactPartial<_SearchOptions> {}
+
+  type SearchableField =
+    | foundry.data.fields.DataField
+    | {
+        [K in string]: SearchableField;
+      };
+
+  interface GetInvalidOptions {
+    /**
+     * Throw an Error if the requested ID is not in the set of invalid IDs for this collection.
+     */
+    strict?: boolean | undefined;
+  }
+
+  interface GetOptions extends Collection.GetOptions {
+    /**
+     * Allow retrieving an invalid Embedded Document.
+     * @defaultValue `false`
+     */
+    invalid?: boolean | undefined;
+  }
+
+  type GetReturnType<DocumentType extends Document.Type, Options extends GetOptions | undefined> = _ApplyInvalid<
+    DocumentType,
+    GetKey<Options, "invalid", false>
+  >;
+
+  /** @internal */
+  type _ApplyInvalid<DocumentType extends Document.Type, Invalid extends boolean | undefined> = Invalid extends true
+    ? Document.InvalidForName<DocumentType> | Document.StoredForName<DocumentType>
+    : Document.StoredForName<DocumentType>;
+}
+
+export default DocumentCollection;

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

@@ -0,0 +1,192 @@
+import type { DeepPartial, GetKey, Identity, InexactPartial } from "#utils";
+import type Document from "#common/abstract/document.d.mts";
+import type { DatabaseCreateOperation } from "#common/abstract/_types.d.mts";
+import type { AbstractSidebarTab, DocumentDirectory } from "#client/applications/sidebar/_module.mjs";
+
+import DocumentSheet = foundry.appv1.api.DocumentSheet;
+import DocumentSheetV2 = foundry.applications.api.DocumentSheetV2;
+import DocumentSheetConfig = foundry.applications.apps.DocumentSheetConfig;
+
+/**
+ * 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 | `Game#collections`}
+ */
+declare abstract class WorldCollection<
+  DocumentName extends Document.WorldType,
+  Name extends string,
+> extends foundry.documents.abstract.DirectoryCollectionMixin(
+  foundry.documents.abstract.DocumentCollection,
+)<DocumentName> {
+  // Note: This isn't a real override but it's here to make the type more specific.
+  override get name(): Name;
+
+  /**
+   * Reference the set of Folders which contain documents in this collection
+   */
+  get folders(): WorldCollection.Folders<DocumentName>;
+
+  /**
+   * Return a reference to the SidebarDirectory application for this WorldCollection.
+   * @remarks
+   * In the case where `Lowercase<Name>` is not a property of {@linkcode ui}, this actually always returns `undefined`,
+   * but {@linkcode RollTables} overrides this, so we need to allow a wider return type.
+   */
+  get directory(): Lowercase<Name> extends keyof typeof ui
+    ? (typeof ui)[Lowercase<Name>]
+    :
+        | (DocumentName extends foundry.CONST.FOLDER_DOCUMENT_TYPES
+            ? DocumentDirectory<Document.ImplementationClassFor<DocumentName>>
+            : never)
+        | AbstractSidebarTab.Any
+        | 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.WorldType, 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`.
+
+  // Note(LukeAbby): Due to the usage of `this["contents"]` in the parent class the override has
+  // to stay like this.
+  protected override _getVisibleTreeContents(): this["contents"];
+
+  /**
+   * 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 {@linkcode WorldCollection.fromCompendium} and {@linkcode 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: WorldCollection.Pack<DocumentName>,
+    id: string,
+    // The name `updateData` is a misnomer. It's merged with the create data.
+    updateData?: DeepPartial<Document.CreateDataForName<DocumentName>>,
+    options?: InexactPartial<
+      Document.Database.CreateOperation<DatabaseCreateOperation> & WorldCollection.FromCompendiumOptions
+    >,
+  ): Promise<Document.StoredForName<DocumentName>>;
+
+  /**
+   * 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<Options extends WorldCollection.FromCompendiumOptions | undefined>(
+    document: Document.ImplementationFor<DocumentName> | Document.CreateDataForName<DocumentName>,
+    options?: Options,
+  ): WorldCollection.FromCompendiumReturnType<DocumentName, Options>;
+
+  /**
+   * Register a Document sheet class as a candidate which can be used to display Documents of a given type.
+   * See {@linkcode DocumentSheetConfig.registerSheet} for details.
+   * @see {@linkcode 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(
+    scope: string,
+    sheetClass: DocumentSheet.AnyConstructor | DocumentSheetV2.AnyConstructor,
+    options?: DocumentSheetConfig.SheetRegistrationOptions,
+  ): void;
+
+  /**
+   * Unregister a Document sheet class, removing it from the list of available sheet Applications to use.
+   * See {@linkcode DocumentSheetConfig.unregisterSheet} for details.
+   * @see {@linkcode DocumentSheetConfig.unregisterSheet}
+   *
+   * @example <caption>Deregister the default ActorSheet subclass to replace it with others.</caption>
+   * Actors.unregisterSheet("core", ActorSheet);
+   */
+  static unregisterSheet(
+    scope: string,
+    sheetClass: DocumentSheet.AnyConstructor | DocumentSheetV2.AnyConstructor,
+    options?: DocumentSheetConfig.UnregisterSheetOptions,
+  ): void;
+
+  /**
+   * Return an array of currently registered sheet classes for this Document type.
+   */
+  static get registeredSheets(): (
+    | foundry.appv1.api.DocumentSheet.AnyConstructor
+    | foundry.applications.api.ApplicationV2.AnyConstructor
+  )[];
+}
+
+declare namespace WorldCollection {
+  interface Any extends AnyWorldCollection {}
+  interface AnyConstructor extends Identity<typeof AnyWorldCollection> {}
+
+  type Folders<DocumentName extends Document.WorldType> = Collection<
+    DocumentName extends Folder.DocumentType ? Folder.Stored<DocumentName> : never
+  >;
+
+  interface FromCompendiumOptions {
+    /**
+     * Clear the currently assigned folder
+     * @defaultValue `false`
+     */
+    clearFolder?: boolean | undefined;
+
+    /**
+     * Clear the currently sort order
+     * @defaultValue `true`
+     */
+    clearSort?: boolean | undefined;
+
+    /**
+     * Clear Document ownership
+     * @defaultValue `true`
+     */
+    clearOwnership?: boolean | undefined;
+
+    /**
+     * Retain the Document ID from the source Compendium
+     * @defaultValue `false`
+     */
+    keepId?: boolean | undefined;
+
+    /** @remarks used by Scenes#fromCompendium */
+    clearState?: boolean | undefined;
+  }
+
+  type FromCompendiumReturnType<
+    DocumentType extends Document.WorldType,
+    Options extends FromCompendiumOptions | undefined,
+  > = Omit<
+    Document.SourceForName<DocumentType>,
+    | ClientDocument._OmitProperty<GetKey<Options, "clearFolder", undefined>, false, "folder">
+    | ClientDocument._OmitProperty<GetKey<Options, "clearSort", undefined>, true, "sort" | "navigation" | "navOrder">
+    | ClientDocument._OmitProperty<GetKey<Options, "clearOwnership", undefined>, true, "ownership">
+    | (GetKey<Options, "keepId", undefined> extends true ? never : never)
+  >;
+
+  type Pack<DocumentName extends Document.WorldType> =
+    DocumentName extends foundry.documents.collections.CompendiumCollection.DocumentName
+      ? foundry.documents.collections.CompendiumCollection<DocumentName>
+      : never;
+}
+
+declare abstract class AnyWorldCollection extends WorldCollection<Document.WorldType, string> {
+  constructor(...args: never[]);
+}
+
+export default WorldCollection;