@league-of-foundry-developers/foundry-vtt-types 12.331.4-beta → 12.331.5

package/src/foundry/client/data/documents/fog-exploration.d.mts

@@ -1,4 +1,4 @@
-import type { Identity, InexactPartial, Merge } from "fvtt-types/utils";
+import type { AnyObject, Identity, IntentionalPartial, Merge, NullishProps } from "#utils";
 import type { documents } from "../../../client-esm/client.d.mts";
 import type { DatabaseGetOperation } from "../../../common/abstract/_types.d.mts";
 import type Document from "../../../common/abstract/document.d.mts";
@@ -114,7 +114,7 @@ declare global {
     type Collection = FogExplorations.Configured;
 
     /**
-     * An instance of `FogExploration` that comes from the database but failed validation meaining that
+     * An instance of `FogExploration` that comes from the database but failed validation meaning that
      * its `system` and `_source` could theoretically be anything.
      */
     interface Invalid extends Document.Invalid<FogExploration.Implementation> {}
@@ -210,7 +210,7 @@ declare global {
        * The timestamp at which this fog exploration was last updated
        * @defaultValue `Date.now()`
        */
-      timestamp: fields.NumberField<{ nullable: false; initial: ReturnType<typeof Date.now> }>;
+      timestamp: fields.NumberField<{ nullable: false; initial: typeof Date.now }>;
 
       /**
        * An object of optional key/value flags
@@ -376,6 +376,28 @@ declare global {
      * @deprecated {@link FogExploration.Implementation | `FogExploration.Implementation`}
      */
     type ConfiguredInstance = Implementation;
+
+    /** @internal */
+    type _LoadQuery = NullishProps<{
+      /**
+       * A certain Scene ID
+       * @defaultValue `canvas.scene`
+       */
+      scene: string;
+
+      /**
+       * A certain User ID
+       * @defaultValue `game.user`
+       */
+      user: string;
+    }>;
+    interface LoadQuery extends _LoadQuery {}
+
+    /**
+     * @remarks {@link FogExploration.load | `FogExploration#load`} takes the `query` property separately as its first argument, then merges that
+     * with this interface via `{query, ...options}` before passing to {@link ClientDatabaseBackend.get | `this.database.get`}
+     */
+    interface LoadOptions extends Omit<IntentionalPartial<DatabaseGetOperation>, "query"> {}
   }
 
   /**
@@ -391,18 +413,13 @@ declare global {
     /**
      * Obtain the fog of war exploration progress for a specific Scene and User.
      * @param query      - Parameters for which FogExploration document is retrieved
-     * @param options    - Additional options passed to DatabaseBackend#get.
-     *                     (default: `{}`)
+     * @param options    - Additional options passed to DatabaseBackend#get. (default: `{}`)
      * @returns
      */
+    // query: not null (destructured)
     static load(
-      query?: InexactPartial<{
-        /** A certain Scene ID **/
-        scene: string;
-        /** A certain User ID **/
-        user: string;
-      }>,
-      options?: InexactPartial<DatabaseGetOperation>,
+      query?: FogExploration.LoadQuery,
+      options?: FogExploration.LoadOptions | null,
     ): Promise<FogExploration.Implementation | null>;
 
     /**
@@ -410,9 +427,27 @@ declare global {
      */
     getTexture(): PIXI.Texture | null;
 
+    // _onCreate, _onUpdate, and _onDelete are all overridden but with no signature changes from BaseFogExploration.
+
+    static override get(
+      documentId: string,
+      options?: FogExploration.Database.GetOptions,
+    ): FogExploration.Implementation | null;
+
+    /**
+     * @deprecated since v12, will be removed in v14
+     * @remarks "You are calling `FogExploration.get` by passing an object. This means you are probably trying to load Fog of War exploration data, an operation which has been renamed to {@link FogExploration.load | `FogExploration.load`}"
+     */
+    static override get(
+      query: FogExploration.LoadQuery,
+      options: FogExploration.LoadOptions,
+    ): Promise<FogExploration.Implementation | null>;
+
     /**
-     * @privateRemarks _onCreate, _onUpdate, and _onDelete are all overridden but with no signature changes from BaseFogExploration.
+     * @deprecated since v11, until v13
+     * @remarks "`explore` is obsolete and always returns `true`. The fog exploration does not record position anymore."
      */
+    explore(source: unknown, force?: boolean): true;
 
     /*
      * After this point these are not really overridden methods.
@@ -428,22 +463,27 @@ declare global {
 
     // Descendant Document operations have been left out because FogExploration does not have any descendant documents.
 
-    static override defaultName(context?: Document.DefaultNameContext<string, FogExploration.Parent>): string;
+    // context: not null (destructured)
+    static override defaultName(context?: Document.DefaultNameContext<"FogExploration", FogExploration.Parent>): string;
 
+    // data: not null (parameter default only), context: not null (destructured)
     static override createDialog(
       data?: FogExploration.CreateData,
-      context?: Document.CreateDialogContext<string, FogExploration.Parent>,
+      context?: Document.CreateDialogContext<"FogExploration", FogExploration.Parent>,
     ): Promise<FogExploration.Stored | null | undefined>;
 
+    // options: not null (parameter default only)
     static override fromDropData(
       data: Document.DropData<FogExploration.Implementation>,
-      options?: Document.FromDropDataOptions,
+      options?: AnyObject,
     ): Promise<FogExploration.Implementation | undefined>;
 
     static override fromImport(
       source: FogExploration.Source,
-      context?: Document.FromImportContext<FogExploration.Parent>,
+      context?: Document.FromImportContext<FogExploration.Parent> | null,
     ): Promise<FogExploration.Implementation>;
+
+    override _onClickDocumentLink(event: MouseEvent): ClientDocument.OnClickDocumentLinkReturn;
   }
 
   namespace FogExploration {

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

@@ -1,5 +1,5 @@
 import type { ConfiguredFolder } from "../../../../configuration/index.d.mts";
-import type { InexactPartial, Merge } from "fvtt-types/utils";
+import type { AnyObject, InexactPartial, IntentionalPartial, Merge, NullishProps } from "#utils";
 import type Document from "../../../common/abstract/document.d.mts";
 import type { DataSchema } from "../../../common/data/fields.d.mts";
 import type { fields } from "../../../common/data/module.d.mts";
@@ -145,7 +145,7 @@ declare global {
     type Collection = Folders.Configured;
 
     /**
-     * An instance of `Folder` that comes from the database but failed validation meaining that
+     * An instance of `Folder` that comes from the database but failed validation meaning that
      * its `system` and `_source` could theoretically be anything.
      */
     interface Invalid<out SubType extends Folder.SubType = Folder.SubType> extends Document.Invalid<OfType<SubType>> {}
@@ -214,9 +214,10 @@ declare global {
       _id: fields.DocumentIdField;
 
       /** The name of this Folder */
-      name: fields.StringField<{ required: true; blank: false; textSearch: true }>;
+      // FIXME: This field is `required` with no `initial`, so actually required for construction; Currently an AssignmentType override is required to enforce this
+      name: fields.StringField<{ required: true; blank: false; textSearch: true }, string>;
 
-      /** The document type which this Folder contains, from CONST.FOLDER_DOCUMENT_TYPES */
+      /** The document type which this Folder contains, from {@linkcode CONST.FOLDER_DOCUMENT_TYPES} */
       type: fields.DocumentTypeField<typeof BaseFolder>;
 
       /**
@@ -413,12 +414,74 @@ declare global {
     /**
      * Actual document types that go in folders
      */
-    type DocumentType = Exclude<foundry.CONST.FOLDER_DOCUMENT_TYPES, "Compendium">;
+    type DocumentType = Exclude<CONST.FOLDER_DOCUMENT_TYPES, "Compendium">;
 
-    interface ExportToCompendiumOptions {
-      /** Update existing entries in the Compendium pack, matching by name */
-      updateByName?: boolean | undefined;
-    }
+    type DocumentCollection<Type extends SubType> = Type extends "Compendium"
+      ? Collection.Any | undefined
+      : WorldCollection.Any;
+
+    /** @internal */
+    type _ExportToCompendiumOptions = NullishProps<{
+      /**
+       * Update existing entries in the Compendium pack, matching by name
+       * @defaultValue `false`
+       */
+      updateByName: boolean;
+
+      /**
+       * Retain the original _id attribute when updating an entity
+       * @defaultValue `false`
+       * @remarks No default applied despite Foundry's typing, but `undefined` will be treated falsily
+       */
+      keepId: boolean;
+
+      /**
+       * Retain the existing Folder structure
+       * @defaultValue `false`
+       * @remarks No default applied despite Foundry's typing, but `undefined` will be treated falsily
+       */
+      keepFolders: boolean;
+
+      /**
+       * A target folder id to which the documents will be exported
+       * @defaultValue `null`
+       */
+      folder: string;
+    }>;
+
+    /** @privateRemarks `keepId` omitted to override comment */
+    interface ExportToCompendiumOptions
+      extends _ExportToCompendiumOptions,
+        Omit<ClientDocument.ToCompendiumOptions, "keepId"> {}
+
+    /** @internal */
+    type _ExportDialogOptions = NullishProps<{
+      /**
+       * @remarks A compendium to preselect in the dialog
+       * @defaultValue `null`
+       */
+      pack: string;
+
+      /**
+       * @remarks Initial state of the `Merge by Name` checkbox in the dialog
+       * @defaultValue `true`
+       */
+      merge: boolean;
+
+      /**
+       * @remarks Initial state of the `Keep Document IDs` checkbox in the dialog
+       * @defaultValue `true`
+       */
+      keepId: boolean;
+
+      /**
+       * @remarks Initial state of the `Keep Folder Structure` checkbox in the dialog
+       * @defaultValue `true`
+       */
+      keepFolders: boolean;
+    }>;
+
+    interface ExportDialogOptions extends _ExportDialogOptions, IntentionalPartial<Dialog.Options> {}
 
     // TODO: Handle compendium. This requires the index to be configured.
     type Contents<SubType extends Folder.SubType> = Document.ImplementationFor<Extract<SubType, Document.Type>>[];
@@ -427,6 +490,16 @@ declare global {
     type DocumentClass<SubType extends Folder.SubType> = Document.ImplementationClassFor<
       Extract<SubType, Document.Type>
     >;
+
+    /**
+     * @remarks Rather than a simple `Dialog`, {@link Folder.createDialog | `Folder.createDialog`} creates a {@link FolderConfig | `FolderConfig`},
+     * passing along the returned `Promise`'s `resolve` to the app.
+     */
+    // TODO (v13): `options.document` is also force set
+    interface CreateDialogOptions extends InexactPartial<Omit<FolderConfig.Options, "resolve">> {
+      /** @deprecated This is force set to the `resolve` of the Promise returned by this `createDialog` call */
+      resolve?: never;
+    }
   }
 
   /**
@@ -449,14 +522,18 @@ declare global {
      *
      * @remarks For folders that have been populated by the {@link SidebarDirectory | `SidebarDirectory`}, this is always be defined
      */
-    depth?: number;
+    depth: number | undefined;
 
     /**
      * An array of other Folders which are the displayed children of this one. This differs from the results of
-     * {@link Folder.getSubfolders | `Folder.getSubfolders`} because reports the subset of child folders which  are displayed to the current User
-     * in the UI.
+     * {@link Folder.getSubfolders | `Folder#getSubfolders`} because reports the subset of child folders which
+     * are displayed to the current User in the UI.
+     * @remarks Despite Foundry's typing, this is not an array of Folder documents.
+     *
+     * Initialized by {@link DirectoryCollection.initializeTree | `DirectoryCollection#initializeTree`}, so always
+     * `undefined` in temporary documents, and prior to first UI render in stored documents
      */
-    children: Folder.Implementation[];
+    children: DirectoryCollectionMixin.TreeNode<Folder.Implementation>[] | undefined;
 
     /**
      * Return whether the folder is displayed in the sidebar to the current User.
@@ -483,7 +560,8 @@ declare global {
      * A world Folder containing CompendiumCollections will have neither.
      */
     // TODO: Compendium Pack index
-    get documentCollection(): this["pack"] extends string ? unknown : undefined;
+    // TODO: Infer specific world collection from SubType
+    get documentCollection(): Folder.DocumentCollection<SubType>;
 
     /**
      * Return whether the folder is currently expanded within the sidebar interface.
@@ -495,24 +573,24 @@ declare global {
      */
     get ancestors(): Folder.Implementation[];
 
-    /**
-     * @privateRemarks _preCreate overridden but with no signature changes.
-     * For type simplicity it is left off. These methods historically have been the source of a large amount of computation from tsc.
-     */
+    // _preCreate overridden but with no signature changes.
+    // For type simplicity it is left off. These methods historically have been the source of a large amount of computation from tsc.
 
+    /** @remarks Creates and renders a {@link FolderConfig | `FolderConfig`} instead of a simple Dialog */
+    // data, options: not null (parameter defaults only)
     static override createDialog(
       data?: Document.CreateDialogData<Folder.CreateData>,
-      context?: InexactPartial<Omit<FolderConfig.Options, "resolve">>,
+      context?: Folder.CreateDialogOptions,
     ): Promise<Folder.Stored | null | undefined>;
 
     /**
      * Export all Documents contained in this Folder to a given Compendium pack.
      * Optionally update existing Documents within the Pack by name, otherwise append all new entries.
      * @param pack    - A Compendium pack to which the documents will be exported
-     * @param options - Additional options which customize how content is exported. See {@link ClientDocument.toCompendium | `ClientDocument#toCompendium`}
-     *                  (default: `{}`)
+     * @param options - Additional options which customize how content is exported. See {@link ClientDocument.toCompendium | `ClientDocument#toCompendium`} (default: `{}`)
      * @returns The updated Compendium Collection instance
      */
+    // options: not null (parameter default only)
     exportToCompendium<Metadata extends CompendiumCollection.Metadata>(
       pack: CompendiumCollection<Metadata>,
       options?: Folder.ExportToCompendiumOptions,
@@ -521,22 +599,21 @@ declare global {
     /**
      * Provide a dialog form that allows for exporting the contents of a Folder into an eligible Compendium pack.
      * @param pack    - A pack ID to set as the default choice in the select input
-     * @param options - Additional options passed to the Dialog.prompt method
-     *                  (default: `{}`)
+     * @param options - Additional options passed to the Dialog.prompt method (default: `{}`)
      * @returns A Promise which resolves or rejects once the dialog has been submitted or closed
      *
-     * @remarks - Foundry documents `pack` as just being a `string` but it is unused and Foundry itself
+     * @remarks - Foundry documents `pack` as just being a `string` but it is unused in favor of `options.pack`, and Foundry itself
      * calls `exportDialog` with `null`.
      */
-    exportDialog(pack: string | null, options?: Dialog.Options): Promise<void>;
+    // options: not null (parameter default only)
+    exportDialog(pack: string | null, options?: Folder.ExportDialogOptions): Promise<void>;
 
     /**
      * Get the Folder documents which are sub-folders of the current folder, either direct children or recursively.
-     * @param recursive - Identify child folders recursively, if false only direct children are returned
-     *                    (default: `false`)
+     * @param recursive - Identify child folders recursively, if false only direct children are returned (default: `false`)
      * @returns An array of Folder documents which are subfolders of this one
      */
-    getSubfolders(recursive?: boolean): Folder.Implementation[];
+    getSubfolders(recursive?: boolean | null): Folder.Implementation[];
 
     /**
      * Get the Folder documents which are parent folders of the current folder or any if its parents.
@@ -558,16 +635,22 @@ declare global {
 
     // Descendant Document operations have been left out because Folder does not have any descendant documents.
 
-    static override defaultName(context?: Document.DefaultNameContext<Folder.SubType, Folder.Parent>): string;
+    // context: not null (destructured)
+    static override defaultName(context?: Document.DefaultNameContext<"Folder", Folder.Parent>): string;
 
+    // options: not null (parameter default only)
     static override fromDropData(
       data: Document.DropData<Folder.Implementation>,
-      options?: Document.FromDropDataOptions,
+      options?: AnyObject,
     ): Promise<Folder.Implementation | undefined>;
 
     static override fromImport(
       source: Folder.Source,
-      context?: Document.FromImportContext<Folder.Parent>,
+      context?: Document.FromImportContext<Folder.Parent> | null,
     ): Promise<Folder.Implementation>;
+
+    override _onClickDocumentLink(event: MouseEvent): ClientDocument.OnClickDocumentLinkReturn;
+
+    #Folder: true;
   }
 }

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

@@ -3,7 +3,7 @@ import type { documents } from "../../../client-esm/client.d.mts";
 import type Document from "../../../common/abstract/document.d.mts";
 import type { fields } from "../../../common/data/module.d.mts";
 import type { DataSchema } from "../../../common/data/fields.d.mts";
-import type { AnyObject, Merge } from "fvtt-types/utils";
+import type { AnyObject, Merge } from "#utils";
 
 declare global {
   namespace Item {
@@ -223,7 +223,7 @@ declare global {
     type Collection = Items.Configured;
 
     /**
-     * An instance of `Item` that comes from the database but failed validation meaining that
+     * An instance of `Item` that comes from the database but failed validation meaning that
      * its `system` and `_source` could theoretically be anything.
      */
     interface Invalid<out SubType extends Item.SubType = Item.SubType> extends Document.Invalid<OfType<SubType>> {}
@@ -292,9 +292,11 @@ declare global {
       _id: fields.DocumentIdField;
 
       /** The name of this Item */
-      name: fields.StringField<{ required: true; blank: false; textSearch: true }>;
+      // FIXME: required with no initial, assignment type override required
+      name: fields.StringField<{ required: true; blank: false; textSearch: true }, string>;
 
       /** An Item subtype which configures the system data model applied */
+      // TODO: required with no initial, needs assignment type override
       type: fields.DocumentTypeField<typeof documents.BaseItem>;
 
       /**
@@ -302,7 +304,7 @@ declare global {
        * @defaultValue `null`
        */
       img: fields.FilePathField<{
-        categories: "IMAGE"[];
+        categories: ["IMAGE"];
         initial: (data: unknown) => string;
       }>;
 
@@ -507,6 +509,11 @@ declare global {
       Item.Metadata.Embedded
     >;
 
+    interface GetDefaultArtworkReturn {
+      /** @defaultValue `Item.DEFAULT_ICON` */
+      img: string;
+    }
+
     /**
      * @deprecated {@link Item.Database | `Item.DatabaseOperation`}
      */
@@ -556,23 +563,23 @@ declare global {
     /**
      * A convenience alias of Item#parent which is more semantically intuitive
      */
-    get actor(): this["parent"];
+    get actor(): Actor.Implementation | null;
 
     /**
      * Provide a thumbnail image path used to represent this document.
      */
-    get thumbnail(): this["img"];
+    get thumbnail(): string;
 
     /**
      * A convenience alias of Item#isEmbedded which is preserves legacy support
      */
-    get isOwned(): this["isEmbedded"];
+    get isOwned(): boolean;
 
     /**
      * Return an array of the Active Effect instances which originated from this Item.
      * The returned instances are the ActiveEffect instances which exist on the Item itself.
      */
-    get transferredEffects(): ReturnType<this["effects"]["filter"]>;
+    get transferredEffects(): ActiveEffect.Implementation[];
 
     /**
      * Prepare a data object which defines the data schema used by dice roll commands against this Item
@@ -580,9 +587,7 @@ declare global {
      */
     getRollData(): AnyObject;
 
-    /**
-     * @privateRemarks _preCreate, _onCreateDocuments and _onDeleteDocuments are all overridden but with no signature changes from BaseItem.
-     */
+    // _preCreate, _onCreateOperation and _onDeleteOperation are all overridden but with no signature changes from BaseItem.
 
     /*
      * After this point these are not really overridden methods.
@@ -598,7 +603,7 @@ declare global {
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class SwadeItem extends Item {
      *   protected override _preCreateDescendantDocuments(...args: Item.PreCreateDescendantDocumentsArgs) {
@@ -616,7 +621,7 @@ declare global {
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class GurpsItem extends Item {
      *   protected override _onCreateDescendantDocuments(...args: Item.OnCreateDescendantDocumentsArgs) {
@@ -634,7 +639,7 @@ declare global {
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class LancerItem extends Item {
      *   protected override _preUpdateDescendantDocuments(...args: Item.OnUpdateDescendantDocuments) {
@@ -652,7 +657,7 @@ declare global {
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class Ptr2eItem extends Item {
      *   protected override _onUpdateDescendantDocuments(...args: Item.OnUpdateDescendantDocumentsArgs) {
@@ -670,7 +675,7 @@ declare global {
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class KultItem extends Item {
      *   protected override _preDeleteDescendantDocuments(...args: Item.PreDeleteDescendantDocumentsArgs) {
@@ -688,7 +693,7 @@ declare global {
 
     /**
      * @remarks To make it possible for narrowing one parameter to jointly narrow other parameters
-     * this method must be overriden like so:
+     * this method must be overridden like so:
      * ```typescript
      * class BladesItem extends Item {
      *   protected override _onDeleteDescendantDocuments(...args: Item.OnUpdateDescendantDocuments) {
@@ -704,21 +709,26 @@ declare global {
      */
     protected override _onDeleteDescendantDocuments(...args: Item.OnDeleteDescendantDocumentsArgs): void;
 
-    static override defaultName(context?: Document.DefaultNameContext<Item.SubType, Item.Parent>): string;
+    // context: not null (destructured)
+    static override defaultName(context?: Document.DefaultNameContext<"Item", Item.Parent>): string;
 
+    // data: not null (parameter default only), context: not null (destructured)
     static override createDialog(
       data?: Document.CreateDialogData<Item.CreateData>,
-      context?: Document.CreateDialogContext<Item.SubType, Item.Parent>,
+      context?: Document.CreateDialogContext<"Item", Item.Parent>,
     ): Promise<Item.Stored | null | undefined>;
 
+    // options: not null (parameter default only)
     static override fromDropData(
       data: Document.DropData<Item.Implementation>,
-      options?: Document.FromDropDataOptions,
+      options?: AnyObject,
     ): Promise<Item.Implementation | undefined>;
 
     static override fromImport(
       source: Item.Source,
-      context?: Document.FromImportContext<Item.Parent>,
+      context?: Document.FromImportContext<Item.Parent> | null,
     ): Promise<Item.Implementation>;
+
+    override _onClickDocumentLink(event: MouseEvent): ClientDocument.OnClickDocumentLinkReturn;
   }
 }