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

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

@@ -1,7 +1,8 @@
-import type { FolderDocumentTypes, InexactPartial, FixedInstanceType, Merge } from "fvtt-types/utils";
+import type { AnyObject, FolderDocumentTypes, InexactPartial, Merge, NullishProps } from "#utils";
 import type { fields } from "../../../common/data/module.d.mts";
 import type Document from "../../../common/abstract/document.d.mts";
 import type { DataSchema } from "../../../common/data/fields.d.mts";
+import type DataModel from "#common/abstract/data.mjs";
 
 declare global {
   namespace Adventure {
@@ -102,7 +103,7 @@ declare global {
     type Collection = never;
 
     /**
-     * An instance of `Adventure` that comes from the database but failed validation meaining that
+     * An instance of `Adventure` that comes from the database but failed validation meaning that
      * its `system` and `_source` could theoretically be anything.
      */
     interface Invalid extends Document.Invalid<Adventure.Implementation> {}
@@ -173,13 +174,17 @@ declare global {
       /**
        * The human-readable name of the Adventure
        */
-      name: fields.StringField<{
-        required: true;
-        blank: false;
-        label: "ADVENTURE.Name";
-        hint: "ADVENTURE.NameHint";
-        textSearch: true;
-      }>;
+      // FIXME: required with no initial, assignment type override required
+      name: fields.StringField<
+        {
+          required: true;
+          blank: false;
+          label: "ADVENTURE.Name";
+          hint: "ADVENTURE.NameHint";
+          textSearch: true;
+        },
+        string
+      >;
 
       /**
        * The file path for the primary image of the adventure
@@ -408,21 +413,49 @@ declare global {
       type Get<Scope extends Flags.Scope, Key extends Flags.Key<Scope>> = Document.GetFlag<Name, Scope, Key>;
     }
 
-    interface PrepareImportOptions {
+    type DocumentDataRecord = {
+      [K in ContainedDocumentType]?: Document.CreateDataForName<K>[];
+    };
+
+    type DocumentResult = {
+      [K in ContainedDocumentType]?: Document.ImplementationFor<K>[];
+    };
+
+    type ContainedDocumentType = Exclude<FolderDocumentTypes, "Adventure"> | "Folder";
+
+    interface ImportData {
+      toCreate: DocumentDataRecord;
+      toUpdate: DocumentDataRecord;
+      documentCount: number;
+    }
+
+    interface ImportResult {
+      created: DocumentResult;
+      updated: DocumentResult;
+    }
+
+    /** @internal */
+    type _PrepareImportOptions = InexactPartial<{
       /**
        * A subset of adventure fields to import.
+       * @defaultValue `[]`
+       * @remarks Can't be `null` as it only has a parameter default
        */
-      // TODO: This isn't *quite* right as the keyof is including all the nevers.
       importFields: Array<keyof typeof foundry.documents.BaseAdventure.contentFields | "all">;
-    }
+    }>;
 
-    interface ImportOptions extends PrepareImportOptions {
+    interface PrepareImportOptions extends _PrepareImportOptions {}
+
+    /** @internal */
+    type _ImportOptions = NullishProps<{
       /**
        * Display a warning dialog if existing documents would be overwritten
        * @defaultValue `true`
        */
       dialog: boolean;
-    }
+    }>;
+
+    interface ImportOptions extends _ImportOptions, PrepareImportOptions {}
 
     /**
      * @deprecated {@link Adventure.Database | `Adventure.DatabaseOperation`}
@@ -444,17 +477,6 @@ declare global {
      * @deprecated {@link Adventure.Implementation | `Adventure.Implementation`}
      */
     type ConfiguredInstance = Implementation;
-
-    interface ImportData {
-      toCreate?: DocumentDataRecord;
-      toUpdate?: DocumentDataRecord;
-      documentCount: number;
-    }
-
-    interface ImportResult {
-      created: DocumentResult;
-      updated: DocumentResult;
-    }
   }
 
   /**
@@ -467,25 +489,39 @@ declare global {
      */
     constructor(...args: Adventure.ConstructorArgs);
 
+    /**
+     * @remarks If this creation is happening in a provided `pack`, and that pack is **not** system-specific,
+     * strips `Actor`s, `Item`s, and `Actor` and `Item` `Folders` from `source`s
+     */
+    // options: not null (parameter default only, destructured in super)
+    static override fromSource(
+      source: Adventure.CreateData,
+      context?: DataModel.FromSourceOptions,
+    ): Adventure.Implementation;
+
     /**
      * Perform a full import workflow of this Adventure.
      * Create new and update existing documents within the World.
      * @param options - Options which configure and customize the import process
      * @returns The import result
      */
-    import(options?: InexactPartial<Adventure.ImportOptions>): Promise<Adventure.ImportResult>;
+    // options: not null (destructured)
+    import(options?: Adventure.ImportOptions): Promise<Adventure.ImportResult>;
 
     /**
      * Prepare Adventure data for import into the World.
      * @param options - Options passed in from the import dialog to configure the import behavior
      * @returns A subset of adventure fields to import.
      */
-    prepareImport(options?: InexactPartial<Adventure.PrepareImportOptions>): Promise<Adventure.ImportData>;
+    // options: not null (destructured)
+    prepareImport(options?: Adventure.PrepareImportOptions): Promise<Adventure.ImportData>;
 
     /**
      * Execute an Adventure import workflow, creating and updating documents in the World.
+     * @remarks Despite having a parameter default, neither `data` nor any of its keys are optional, as the keys themselves have no defaults,
+     * and `toCreate` and `toUpdate` get passed to `Object.entries` which throws on nullish values, and `documentCount`is used as a divisor
      */
-    importContent(data?: InexactPartial<Adventure.ImportData>): Promise<Adventure.ImportResult>;
+    importContent(data: Adventure.ImportData): Promise<Adventure.ImportResult>;
 
     /*
      * After this point these are not really overridden methods.
@@ -501,22 +537,27 @@ declare global {
 
     // Descendant Document operations have been left out because Adventure does not have any descendant documents.
 
-    static override defaultName(context: Document.DefaultNameContext<"base", Adventure.Parent>): string;
+    // context: not null (destructured)
+    static override defaultName(context?: Document.DefaultNameContext<"Adventure", Adventure.Parent>): string;
 
+    /** @remarks `context.parent` is required as creation requires one */
     static override createDialog(
-      data: Document.CreateDialogData<Adventure.CreateData>,
-      context: Document.CreateDialogContext<string, Adventure.Parent>,
+      data: Document.CreateDialogData<Adventure.CreateData> | undefined,
+      context: Document.CreateDialogContext<"Adventure", Adventure.Parent>,
     ): Promise<Adventure.Stored | null | undefined>;
 
+    // options: not null (parameter default only)
     static override fromDropData(
       data: Document.DropData<Adventure.Implementation>,
-      options?: Document.FromDropDataOptions,
+      options?: AnyObject,
     ): Promise<Adventure.Implementation | undefined>;
 
     static override fromImport(
       source: Adventure.Source,
-      context?: Document.FromImportContext<Adventure.Parent>,
+      context?: Document.FromImportContext<Adventure.Parent> | null,
     ): Promise<Adventure.Implementation>;
+
+    override _onClickDocumentLink(event: MouseEvent): ClientDocument.OnClickDocumentLinkReturn;
   }
 
   /** @deprecated {@link Adventure.ImportData | `Adventure.ImportData`} */
@@ -525,15 +566,3 @@ declare global {
   /** @deprecated {@link Adventure.ImportResult | `Adventure.ImportResult`} */
   type AdventureImportResult = Adventure.ImportResult;
 }
-
-type DocumentDataRecord = {
-  [K in AdventureDocumentTypes]?: foundry.data.fields.SchemaField.AssignmentData<
-    ReturnType<Document.ImplementationClassFor<K>["defineSchema"]>
-  >[];
-};
-
-type DocumentResult = {
-  [K in AdventureDocumentTypes]?: FixedInstanceType<Document.ImplementationClassFor<K>>[];
-};
-
-type AdventureDocumentTypes = Exclude<FolderDocumentTypes, "Adventure"> | "Folder";

package/src/foundry/client/data/documents/ambient-light.d.mts

@@ -1,4 +1,4 @@
-import type { InterfaceToObject, Merge } from "../../../../utils/index.d.mts";
+import type { AnyObject, InterfaceToObject, Merge } from "#utils";
 import type Document from "../../../common/abstract/document.d.mts";
 import type { DataSchema } from "../../../common/data/fields.d.mts";
 import type { fields, LightData } from "../../../common/data/module.d.mts";
@@ -101,7 +101,7 @@ declare global {
     type Collection = never;
 
     /**
-     * An instance of `AmbientLightDocument` that comes from the database but failed validation meaining that
+     * An instance of `AmbientLightDocument` that comes from the database but failed validation meaning that
      * its `system` and `_source` could theoretically be anything.
      */
     interface Invalid extends Document.Invalid<AmbientLightDocument.Implementation> {}
@@ -402,9 +402,7 @@ declare global {
      */
     constructor(...args: AmbientLightDocument.ConstructorArgs);
 
-    /**
-     * @privateRemarks _onUpdate is overridden but with no signature changes from its implementation in BaseAmbientLight.
-     */
+    // _onUpdate is overridden but with no signature changes from its implementation in BaseAmbientLight.
 
     /**
      * Is this ambient light source global in nature?
@@ -425,23 +423,28 @@ declare global {
 
     // Descendant Document operations have been left out because AmbientLight does not have any descendant documents.
 
+    // context: not null (destructured)
     static override defaultName(
-      context: Document.DefaultNameContext<"base", NonNullable<AmbientLightDocument.Parent>>,
+      context?: Document.DefaultNameContext<"AmbientLight", NonNullable<AmbientLightDocument.Parent>>,
     ): string;
 
+    /** @remarks `context.parent` is required as creation requires one */
     static override createDialog(
-      data: Document.CreateDialogData<AmbientLightDocument.CreateData>,
-      context: Document.CreateDialogContext<string, NonNullable<AmbientLightDocument.Parent>>,
+      data: Document.CreateDialogData<AmbientLightDocument.CreateData> | undefined,
+      context: Document.CreateDialogContext<"AmbientLight", NonNullable<AmbientLightDocument.Parent>>,
     ): Promise<AmbientLightDocument.Stored | null | undefined>;
 
+    // options: not null (parameter default only)
     static override fromDropData(
       data: Document.DropData<AmbientLightDocument.Implementation>,
-      options?: Document.FromDropDataOptions,
+      options?: AnyObject,
     ): Promise<AmbientLightDocument.Implementation | undefined>;
 
     static override fromImport(
       source: AmbientLightDocument.Source,
-      context?: Document.FromImportContext<AmbientLightDocument.Parent>,
+      context?: Document.FromImportContext<AmbientLightDocument.Parent> | null,
     ): Promise<AmbientLightDocument.Implementation>;
+
+    override _onClickDocumentLink(event: MouseEvent): ClientDocument.OnClickDocumentLinkReturn;
   }
 }

package/src/foundry/client/data/documents/ambient-sound.d.mts

@@ -1,4 +1,4 @@
-import type { Merge } from "../../../../utils/index.d.mts";
+import type { AnyObject, Merge } 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";
@@ -102,7 +102,7 @@ declare global {
     type Collection = never;
 
     /**
-     * An instance of `AmbientSoundDocument` that comes from the database but failed validation meaining that
+     * An instance of `AmbientSoundDocument` that comes from the database but failed validation meaning that
      * its `system` and `_source` could theoretically be anything.
      */
     interface Invalid extends Document.Invalid<AmbientSoundDocument.Implementation> {}
@@ -467,23 +467,28 @@ declare global {
 
     // Descendant Document operations have been left out because Wall does not have any descendant documents.
 
+    // context: not null (destructured)
     static override defaultName(
-      context: Document.DefaultNameContext<"base", NonNullable<AmbientSoundDocument.Parent>>,
+      context?: Document.DefaultNameContext<"AmbientSound", NonNullable<AmbientSoundDocument.Parent>>,
     ): string;
 
+    /** @remarks `context.parent` is required as creation requires one */
     static override createDialog(
-      data: Document.CreateDialogData<AmbientSoundDocument.CreateData>,
-      context: Document.CreateDialogContext<string, NonNullable<AmbientSoundDocument.Parent>>,
+      data: Document.CreateDialogData<AmbientSoundDocument.CreateData> | undefined,
+      context: Document.CreateDialogContext<"AmbientSound", NonNullable<AmbientSoundDocument.Parent>>,
     ): Promise<AmbientSoundDocument.Stored | null | undefined>;
 
+    // options: not null (parameter default only)
     static override fromDropData(
       data: Document.DropData<AmbientSoundDocument.Implementation>,
-      options?: Document.FromDropDataOptions,
+      options?: AnyObject,
     ): Promise<AmbientSoundDocument.Implementation | undefined>;
 
     static override fromImport(
       source: AmbientSoundDocument.Source,
-      context?: Document.FromImportContext<AmbientSoundDocument.Parent>,
+      context?: Document.FromImportContext<AmbientSoundDocument.Parent> | null,
     ): Promise<AmbientSoundDocument.Implementation>;
+
+    override _onClickDocumentLink(event: MouseEvent): ClientDocument.OnClickDocumentLinkReturn;
   }
 }

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

@@ -1,5 +1,5 @@
 import type { ConfiguredCard } from "../../../../configuration/index.d.mts";
-import type { DeepPartial, Merge } from "fvtt-types/utils";
+import type { AnyObject, DeepPartial, Merge } from "#utils";
 import type { documents } from "../../../client-esm/client.d.mts";
 import type Document from "../../../common/abstract/document.d.mts";
 import type { DataSchema } from "../../../common/data/fields.d.mts";
@@ -162,7 +162,7 @@ declare global {
     type Collection = never;
 
     /**
-     * An instance of `Card` that comes from the database but failed validation meaining that
+     * An instance of `Card` that comes from the database but failed validation meaning that
      * its `system` and `_source` could theoretically be anything.
      */
     interface Invalid<out SubType extends Card.SubType = Card.SubType> extends Document.Invalid<OfType<SubType>> {}
@@ -231,7 +231,8 @@ declare global {
       _id: fields.DocumentIdField;
 
       /** The text name of this card */
-      name: fields.StringField<{ required: true; blank: false; label: "CARD.Name" }>;
+      // 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; label: "CARD.Name" }, string>;
 
       /**
        * A text description of this card which applies to all faces
@@ -241,14 +242,9 @@ declare global {
 
       /**
        * A category of card (for example, a suit) to which this card belongs
-       * @defaultValue `BaseCard.TYPES[0]`
+       * @defaultValue `"base"`
        */
-      type: fields.DocumentTypeField<
-        typeof BaseCard,
-        {
-          initial: typeof foundry.CONST.BASE_DOCUMENT_TYPE;
-        }
-      >;
+      type: fields.DocumentTypeField<typeof BaseCard, { initial: typeof CONST.BASE_DOCUMENT_TYPE }>;
 
       /**
        * Game system data which is defined by the system template.json model
@@ -258,7 +254,7 @@ declare global {
 
       /**
        * An optional suit designation which is used by default sorting
-       * @defaultValue `""`
+       * @defaultValue `undefined`
        */
       suit: fields.StringField<{ label: "CARD.Suit" }>;
 
@@ -270,12 +266,11 @@ declare global {
 
       /**
        * An object of face data which describes the back of this card
-       * @defaultValue see properties
        */
       back: fields.SchemaField<{
         /**
          * A name for this card face
-         * @defaultValue `""`
+         * @defaultValue `undefined`
          */
         name: fields.StringField<{ label: "CARD.BackName" }>;
 
@@ -292,6 +287,10 @@ declare global {
         img: fields.FilePathField<{ categories: ["IMAGE", "VIDEO"]; label: "CARD.BackImage" }>;
       }>;
 
+      /**
+       * An array of face data which represent displayable faces of this card
+       * @defaultValue `[]`
+       */
       faces: fields.ArrayField<fields.SchemaField<Card.FaceSchema>>;
 
       /**
@@ -348,7 +347,7 @@ declare global {
     interface FaceSchema extends DataSchema {
       /**
        * A name for this card face
-       * @defaultValue `""`
+       * @defaultValue `undefined`
        */
       name: fields.StringField<{ label: "CARD.FaceName" }>;
 
@@ -493,6 +492,21 @@ declare global {
       type Get<Scope extends Flags.Scope, Key extends Flags.Key<Scope>> = Document.GetFlag<Name, Scope, Key>;
     }
 
+    /**
+     * @remarks {@link Card.pass | `Card#pass`} calls {@link Cards.pass | `this.parent.pass`} with `action: "pass"` provided
+     */
+    interface PassOptions extends Omit<Cards.PassOptions, "action"> {}
+
+    /**
+     * @remarks {@link Card.play | `Card#play`} calls {@link Cards.pass | `this.parent.pass`} with `action: "play"` provided
+     */
+    interface PlayOptions extends PassOptions {}
+
+    /**
+     * @remarks {@link Card.discard | `Card#discard`} calls {@link Cards.pass | `this.parent.pass`} with `action: "discard"` provided
+     */
+    interface DiscardOptions extends PassOptions {}
+
     /**
      * @deprecated {@link Card.Database | `Card.DatabaseOperation`}
      */
@@ -541,13 +555,14 @@ declare global {
 
     /**
      * The image of the currently displayed card face or back
+     * @remarks Falls back to {@linkcode Card.DEFAULT_ICON}
      */
     get img(): string;
 
     /**
      * A reference to the source Cards document which defines this Card.
      */
-    get source(): Cards.Implementation | undefined | null;
+    get source(): Cards.Implementation | null;
 
     /**
      * A convenience property for whether or not the Card is within its source Cards stack. Cards in decks are always
@@ -570,6 +585,7 @@ declare global {
      */
     get hasPreviousFace(): boolean;
 
+    /** @remarks Provides fallback value for `back.img`, and overrides `name` with the face/back's name if appropriate */
     override prepareDerivedData(): void;
 
     /**
@@ -584,39 +600,41 @@ declare global {
     /**
      * Pass this Card to some other Cards document.
      * @param to      - A new Cards document this card should be passed to
-     * @param options - (default: `{}`)
+     * @param options - Options which modify the pass operation (default: `{}`)
      * @returns A reference to this card after the it has been passed to another parent document
      */
-    pass(to: Cards.Implementation, options?: Cards.PassOptions): Promise<Card.Implementation | undefined>;
+    // options: not null (destructured)
+    pass(to: Cards.Implementation, options?: Card.PassOptions): Promise<Card.Implementation | undefined>;
 
     /**
      * Play a specific card to some other Cards document.
-     * This method is currently a more semantic alias for {@link Card.pass | `Card#pass`}.
      * @see {@link Card.pass | `Card#pass`}
+     * @remarks This method is currently a more semantic alias for {@link Card.pass | `Card#pass`}.
      */
-    play(to: Cards.Implementation, options?: Cards.PassOptions): Promise<Card.Implementation | undefined>;
+    // options: not null (destructured)
+    play(to: Cards.Implementation, options?: Card.PlayOptions): Promise<Card.Implementation | undefined>;
 
     /**
      * Discard a specific card to some other Cards document.
-     * This method is currently a more semantic alias for {@link Card.pass | `Card#pass`}.
      * @see {@link Card.pass | `Card#pass`}
+     * @remarks This method is currently a more semantic alias for {@link Card.pass | `Card#pass`}.
      */
-    discard(to: Cards.Implementation, options?: Cards.PassOptions): Promise<Card.Implementation | undefined>;
+    // options: not null (destructured)
+    discard(to: Cards.Implementation, options?: Card.DiscardOptions): Promise<Card.Implementation | undefined>;
 
     /**
      * Recall this Card to its original Cards parent.
-     * @param options - Options which modify the recall operation
-     *                  (default: `{}`)
-     * @returns A reference to the recallled card belonging to its original parent
+     * @param options - Options which modify the recall operation (default: `{}`)
+     * @returns A reference to the recalled card belonging to its original parent
+     * @remarks Core's implementation doesn't use `options` at all
      */
-    recall(options?: Cards.ResetOptions): Promise<Card.Implementation>;
+    // options: not null (parameter default only)
+    recall(options?: AnyObject): Promise<Card.Implementation | undefined>;
 
     /**
      * Create a chat message which displays this Card.
-     * @param messageData - Additional data which becomes part of the created ChatMessageData
-     *                      (default: `{}`)
-     * @param options     - Options which modify the message creation operation
-     *                      (default: `{}`)
+     * @param messageData - Additional data which becomes part of the created ChatMessageData (default: `{}`)
+     * @param options     - Options which modify the message creation operation (default: `{}`)
      * @returns The created chat message
      */
     toMessage<Temporary extends boolean | undefined = false>(
@@ -638,21 +656,26 @@ declare global {
 
     // Descendant Document operations have been left out because Card does not have any descendant documents.
 
-    static override defaultName(context: Document.DefaultNameContext<Card.SubType, NonNullable<Card.Parent>>): string;
+    // context: not null (destructured)
+    static override defaultName(context?: Document.DefaultNameContext<"Card", NonNullable<Card.Parent>>): string;
 
+    /** @remarks `context.parent` is required as creation requires one */
     static override createDialog(
-      data: Document.CreateDialogData<Card.CreateData>,
-      context: Document.CreateDialogContext<Card.SubType, NonNullable<Card.Parent>>,
+      data: Document.CreateDialogData<Card.CreateData> | undefined,
+      context: Document.CreateDialogContext<"Card", NonNullable<Card.Parent>>,
     ): Promise<Card.Stored | null | undefined>;
 
+    // options: not null (parameter default only)
     static override fromDropData(
       data: Document.DropData<Card.Implementation>,
-      options?: Document.FromDropDataOptions,
+      options?: AnyObject,
     ): Promise<Card.Implementation | undefined>;
 
     static override fromImport(
       source: Card.Source,
-      context?: Document.FromImportContext<Card.Parent>,
+      context?: Document.FromImportContext<Card.Parent> | null,
     ): Promise<Card.Implementation>;
+
+    override _onClickDocumentLink(event: MouseEvent): ClientDocument.OnClickDocumentLinkReturn;
   }
 }