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

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

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

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

@@ -1,4 +1,4 @@
-import type { InexactPartial, Merge } from "fvtt-types/utils";
+import type { AnyObject, Merge } from "#utils";
 import type Sound from "../../../client-esm/audio/sound.d.mts";
 import type Document from "../../../common/abstract/document.d.mts";
 import type { DataSchema } from "../../../common/data/fields.d.mts";
@@ -104,7 +104,7 @@ declare global {
     type Collection = never;
 
     /**
-     * An instance of `PlaylistSound` that comes from the database but failed validation meaining that
+     * An instance of `PlaylistSound` that comes from the database but failed validation meaning that
      * its `system` and `_source` could theoretically be anything.
      */
     interface Invalid extends Document.Invalid<PlaylistSound.Implementation> {}
@@ -175,11 +175,12 @@ declare global {
       /**
        * The name of this sound
        */
-      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 description of this sound
-       * @defaultValue `""`
+       * @defaultValue `undefined`
        */
       description: fields.StringField;
 
@@ -193,7 +194,7 @@ declare global {
        * A channel in CONST.AUDIO_CHANNELS where this sound is are played
        * @defaultValue `"music"`
        */
-      channel: fields.StringField<{ choices: typeof foundry.CONST.AUDIO_CHANNELS; initial: string; blank: false }>;
+      channel: fields.StringField<{ choices: typeof CONST.AUDIO_CHANNELS; initial: string; blank: true }>;
 
       /**
        * Is this sound currently playing?
@@ -413,8 +414,9 @@ declare global {
 
     /**
      * The Sound which manages playback for this playlist sound
+     * @remarks Only `undefined` prior to first {@link PlaylistSound._createSound | `PlaylistSound#_createSound`} call
      */
-    sound: Sound | null;
+    sound: Sound | null | undefined;
 
     /**
      * A debounced function, accepting a single volume parameter to adjust the volume of this sound
@@ -424,7 +426,6 @@ declare global {
 
     /**
      * Create a Sound used to play this PlaylistSound document
-     * @internal
      */
     protected _createSound(): Sound | null;
 
@@ -442,52 +443,44 @@ declare global {
     /**
      * Synchronize playback for this particular PlaylistSound instance
      */
-    sync(): void | Promise<void> | Promise<Sound>;
+    sync(): void;
 
     /**
      * Load the audio for this sound for the current client.
      */
     load(): Promise<void>;
 
-    toAnchor(
-      options?: InexactPartial<{
-        attrs: Record<string, string>;
-        dataset: Record<string, string>;
-        classes: string[];
-        name: string;
-        icon: string;
-      }>,
-    ): HTMLAnchorElement;
-
-    _onClickDocumentLink(event: MouseEvent): ReturnType<Playlist.Implementation["stopSound" | "playSound"]>;
+    // options: not null (destructured)
+    toAnchor(options?: TextEditor.EnrichmentAnchorOptions): HTMLAnchorElement;
 
     /**
-     * @privateRemarks _onCreate, _onUpdate, and _onDelete are all overridden but with no signature changes.
-     * For type simplicity they are left off. These methods historically have been the source of a large amount of computation from tsc.
+     * @remarks Returns {@link Playlist.stopSound | `this.parent.stopSound()`} or {@link Playlist.playSound | `this.parent.playSound()`}
      */
+    override _onClickDocumentLink(event: MouseEvent): Promise<Playlist.Implementation | undefined>;
+
+    // _onCreate, _onUpdate, and _onDelete are all overridden but with no signature changes.
+    // For type simplicity they are left off. These methods historically have been the source of a large amount of computation from tsc.
 
     /**
      * Special handling that occurs when playback of a PlaylistSound is started.
-     * @internal
      */
-    protected _onStart(): Promise<void>;
+    protected _onStart(): Promise<Sound | void>;
 
     /**
      * Special handling that occurs when a PlaylistSound reaches the natural conclusion of its playback.
-     * @internal
      */
-    protected _onEnd(): Promise<void | Playlist.Implementation | undefined>;
+    protected _onEnd(): Promise<void | Playlist.Implementation | null | undefined>;
 
     /**
      * Special handling that occurs when a PlaylistSound is manually stopped before its natural conclusion.
-     * @internal
+     * @remarks Core's implementation is a no-op, this is soft abstract
      */
     protected _onStop(): Promise<void>;
 
     /**
      * The effective volume at which this playlist sound is played, incorporating the global playlist volume setting.
-     * @deprecated PlaylistSound#effectiveVolume is deprecated in favor of using PlaylistSound#volume directly
-     *
+     * @deprecated since v12 until v14
+     * @remarks "`PlaylistSound#effectiveVolume` is deprecated in favor of using {@link PlaylistSound.volume | `PlaylistSound#volume`} directly"
      */
     get effectiveVolume(): number;
 
@@ -505,23 +498,26 @@ declare global {
 
     // Descendant Document operations have been left out because PlaylistSound does not have any descendant documents.
 
+    // context: not null (destructured)
     static override defaultName(
-      context: Document.DefaultNameContext<"base", NonNullable<PlaylistSound.Parent>>,
+      context?: Document.DefaultNameContext<"PlaylistSound", NonNullable<PlaylistSound.Parent>>,
     ): string;
 
+    /** @remarks `context.parent` is required as creation requires one */
     static override createDialog(
-      data: Document.CreateDialogData<PlaylistSound.CreateData>,
-      context: Document.CreateDialogContext<string, NonNullable<PlaylistSound.Parent>>,
+      data: Document.CreateDialogData<PlaylistSound.CreateData> | undefined,
+      context: Document.CreateDialogContext<"PlaylistSound", NonNullable<PlaylistSound.Parent>>,
     ): Promise<PlaylistSound.Stored | null | undefined>;
 
+    // options: not null (parameter default only)
     static override fromDropData(
       data: Document.DropData<PlaylistSound.Implementation>,
-      options?: Document.FromDropDataOptions,
+      options?: AnyObject,
     ): Promise<PlaylistSound.Implementation | undefined>;
 
     static override fromImport(
       source: PlaylistSound.Source,
-      context?: Document.FromImportContext<PlaylistSound.Parent>,
+      context?: Document.FromImportContext<PlaylistSound.Parent> | null,
     ): Promise<PlaylistSound.Implementation>;
 
     // Embedded document operations have been left out because PlaylistSound does not have any embedded documents.

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

@@ -1,4 +1,4 @@
-import type { InexactPartial, Merge } from "fvtt-types/utils";
+import type { AnyObject, InexactPartial, Merge } from "#utils";
 import type { documents } from "../../../client-esm/client.d.mts";
 import type { Document } from "../../../common/abstract/module.d.mts";
 import type { DataSchema } from "../../../common/data/fields.d.mts";
@@ -175,7 +175,7 @@ declare global {
     type Collection = Playlists.Configured;
 
     /**
-     * An instance of `Playlist` that comes from the database but failed validation meaining that
+     * An instance of `Playlist` that comes from the database but failed validation meaning that
      * its `system` and `_source` could theoretically be anything.
      */
     interface Invalid extends Document.Invalid<Playlist.Implementation> {}
@@ -246,11 +246,12 @@ declare global {
       /**
        * The name of this playlist
        */
-      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 description of this playlist
-       * @defaultValue `""`
+       * @defaultValue `undefined`
        */
       description: fields.StringField<{ textSearch: true }>;
 
@@ -264,18 +265,24 @@ declare global {
        * A channel in CONST.AUDIO_CHANNELS where all sounds in this playlist are played
        * @defaultValue `"music"`
        */
-      channel: fields.StringField<{ choices: typeof foundry.CONST.AUDIO_CHANNELS; initial: string; blank: false }>;
+      channel: fields.StringField<{ choices: typeof CONST.AUDIO_CHANNELS; initial: string; blank: false }>;
 
       /**
        * The playback mode for sounds in this playlist
        * @defaultValue `CONST.PLAYLIST_MODES.SEQUENTIAL`
        */
-      mode: fields.NumberField<{
-        required: true;
-        choices: foundry.CONST.PLAYLIST_MODES[];
-        initial: typeof CONST.PLAYLIST_MODES.SEQUENTIAL;
-        validationError: "must be a value in CONST.PLAYLIST_MODES";
-      }>;
+      mode: fields.NumberField<
+        {
+          required: true;
+          choices: CONST.PLAYLIST_MODES[];
+          initial: typeof CONST.PLAYLIST_MODES.SEQUENTIAL;
+          validationError: "must be a value in CONST.PLAYLIST_MODES";
+        },
+        // FIXME: Overrides required to enforce the branded type
+        CONST.PLAYLIST_MODES | null | undefined,
+        CONST.PLAYLIST_MODES,
+        CONST.PLAYLIST_MODES
+      >;
 
       /**
        * Is this playlist currently playing?
@@ -299,12 +306,18 @@ declare global {
        * The sorting mode used for this playlist.
        * @defaultValue `CONST.PLAYLIST_SORT_MODES.ALPHABETICAL`
        */
-      sorting: fields.StringField<{
-        required: true;
-        choices: foundry.CONST.PLAYLIST_SORT_MODES[];
-        initial: typeof CONST.PLAYLIST_SORT_MODES.ALPHABETICAL;
-        validationError: "must be a value in CONST.PLAYLIST_SORTING_MODES";
-      }>;
+      sorting: fields.StringField<
+        {
+          required: true;
+          choices: CONST.PLAYLIST_SORT_MODES[];
+          initial: typeof CONST.PLAYLIST_SORT_MODES.ALPHABETICAL;
+          validationError: "must be a value in CONST.PLAYLIST_SORTING_MODES";
+        },
+        // FIXME: Overrides required to enforce the branded type
+        CONST.PLAYLIST_SORT_MODES | null | undefined,
+        CONST.PLAYLIST_SORT_MODES,
+        CONST.PLAYLIST_SORT_MODES
+      >;
 
       /**
        * A seed used for playlist randomization to guarantee that all clients generate the same random order.
@@ -495,6 +508,19 @@ declare global {
       Playlist.Metadata.Embedded
     >;
 
+    /** @internal */
+    type _PlayNextOptions = InexactPartial<{
+      /**
+       * Whether to advance forward (if 1) or backwards (if -1)
+       * @defaultValue `1`
+       * @remarks Can't be `null` as it only has a parameter default.
+       * @privateRemarks This is only checked for `=== 1`, restricting 'backward' values to `-1` based on core's description
+       */
+      direction: 1 | -1;
+    }>;
+
+    interface PlayNextOptions extends _PlayNextOptions {}
+
     /**
      * @deprecated {@link Playlist.Database.Operation | `Playlist.Database.Operation`}
      */
@@ -515,13 +541,6 @@ declare global {
      * @deprecated {@link Playlist.Implementation | `Playlist.Implementation`}
      */
     type ConfiguredInstance = Implementation;
-    interface PlayNextOptions {
-      /**
-       * Whether to advance forward (if 1) or backwards (if -1)
-       * @defaultValue `1`
-       */
-      direction: 1 | -1;
-    }
   }
 
   /**
@@ -542,7 +561,6 @@ declare global {
     /**
      * Playlists may have a playback order which defines the sequence of Playlist Sounds
      * @defaultValue `undefined`
-     * @internal
      */
     protected _playbackOrder: string[] | undefined;
 
@@ -555,7 +573,7 @@ declare global {
     override get visible(): boolean;
 
     /**
-     * Find all content links belonging to a given {@link Playlist | `Playlist`} or {@link PlaylistSound | `PlaylistSound`}.
+     * Find all content links belonging to a given {@linkcode Playlist} or {@linkcode PlaylistSound}.
      * @param doc - The Playlist or PlaylistSound.
      */
     static _getSoundContentLinks(doc: Playlist.Implementation | PlaylistSound.Implementation): NodeListOf<Element>;
@@ -574,7 +592,8 @@ declare global {
      * @param options - Additional options which configure the next track
      * @returns The updated Playlist document
      */
-    playNext(soundId?: string, options?: Partial<Playlist.PlayNextOptions>): Promise<this | undefined | null>;
+    // options: not null (destructured)
+    playNext(soundId?: string | null, options?: Playlist.PlayNextOptions): Promise<this | undefined | null>;
 
     /**
      * Begin playback of a specific Sound within this Playlist.
@@ -606,13 +625,13 @@ declare global {
 
     /**
      * Get the next sound in the cached playback order. For internal use.
-     * @internal
+     * @private
      */
     protected _getNextSound(soundId: string): PlaylistSound.Implementation | undefined;
 
     /**
      * Get the previous sound in the cached playback order. For internal use.
-     * @internal
+     * @private
      */
     protected _getPreviousSound(soundId: string): PlaylistSound.Implementation | undefined;
 
@@ -620,29 +639,23 @@ declare global {
      * Define the sorting order for the Sounds within this Playlist. For internal use.
      * If sorting alphabetically, the sounds are sorted with a locale-independent comparator
      * to ensure the same order on all clients.
-     * @internal
+     * @private
      */
     protected _sortSounds(a: PlaylistSound.Implementation, b: PlaylistSound.Implementation): number;
 
-    override toAnchor(
-      options?: InexactPartial<{
-        attrs: Record<string, string>;
-        dataset: Record<string, string>;
-        classes: string[];
-        name: string;
-        icon: string;
-      }>,
-    ): HTMLAnchorElement;
-
-    override _onClickDocumentLink(event: MouseEvent): ReturnType<this["playAll" | "stopAll"]>;
+    // options: not null (destructured)
+    override toAnchor(options?: TextEditor.EnrichmentAnchorOptions): HTMLAnchorElement;
 
     /**
-     * @privateRemarks _preUpdate, _onUpdate, _onDelete are all overridden but with no signature changes from the BasePlaylist class.
+     * @remarks Returns {@link Playlist.playAll | `this.playAll()`} or {@link Playlist.stopAll | `this.stopAll()`}
      */
+    override _onClickDocumentLink(event: MouseEvent): Promise<this | undefined>;
+
+    // _preUpdate, _onUpdate, _onDelete are all overridden but with no signature changes from the BasePlaylist class.
 
     /**
      * @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 GurpsPlaylist extends Playlist {
      *   protected override _onCreateDescendantDocuments(...args: Playlist.OnCreateDescendantDocumentsArgs) {
@@ -660,7 +673,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 Ptr2ePlaylist extends Playlist {
      *   protected override _onUpdateDescendantDocuments(...args: Playlist.OnUpdateDescendantDocumentsArgs) {
@@ -678,7 +691,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 BladesPlaylist extends Playlist {
      *   protected override _onDeleteDescendantDocuments(...args: Playlist.OnUpdateDescendantDocuments) {
@@ -697,8 +710,9 @@ declare global {
     /**
      * Handle callback logic when an individual sound within the Playlist concludes playback naturally
      * @internal
+     * @privateRemarks Possibly returns `this.playNext()` so possibly `null`
      */
-    _onSoundEnd(sound: PlaylistSound.Implementation): Promise<this | undefined>;
+    _onSoundEnd(sound: PlaylistSound.Implementation): Promise<this | null | undefined>;
 
     /**
      * Handle callback logic when playback for an individual sound within the Playlist is started.
@@ -707,7 +721,8 @@ declare global {
      */
     _onSoundStart(sound: PlaylistSound.Implementation): Promise<void>;
 
-    toCompendium<Options extends ClientDocument.ToCompendiumOptions>(
+    // options: not null (parameter default only, destructured in super)
+    override toCompendium<Options extends ClientDocument.ToCompendiumOptions | undefined = undefined>(
       pack?: CompendiumCollection<CompendiumCollection.Metadata> | null,
       options?: Options,
     ): ClientDocument.ToCompendiumReturnType<foundry.documents.BasePlaylist, Options>;
@@ -726,7 +741,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 SwadePlaylist extends Playlist {
      *   protected override _preCreateDescendantDocuments(...args: Playlist.PreCreateDescendantDocumentsArgs) {
@@ -744,7 +759,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 LancerPlaylist extends Playlist {
      *   protected override _preUpdateDescendantDocuments(...args: Playlist.OnUpdateDescendantDocuments) {
@@ -762,7 +777,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 KultPlaylist extends Playlist {
      *   protected override _preDeleteDescendantDocuments(...args: Playlist.PreDeleteDescendantDocumentsArgs) {
@@ -778,21 +793,26 @@ declare global {
      */
     protected override _preDeleteDescendantDocuments(...args: Playlist.PreDeleteDescendantDocumentsArgs): void;
 
-    static override defaultName(context?: Document.DefaultNameContext<string, Playlist.Parent>): string;
+    // context: not null (destructured)
+    static override defaultName(context?: Document.DefaultNameContext<"Playlist", Playlist.Parent>): string;
 
+    // data: not null (parameter default only), context: not null (destructured)
     static override createDialog(
       data?: Document.CreateDialogData<Playlist.CreateData>,
-      context?: Document.CreateDialogContext<string, Playlist.Parent>,
+      context?: Document.CreateDialogContext<"Playlist", Playlist.Parent>,
     ): Promise<Playlist.Stored | null | undefined>;
 
+    // options: not null (parameter default only)
     static override fromDropData(
       data: Document.DropData<Playlist.Implementation>,
-      options?: Document.FromDropDataOptions,
+      options?: AnyObject,
     ): Promise<Playlist.Implementation | undefined>;
 
     static override fromImport(
       source: Playlist.Source,
-      context?: Document.FromImportContext<Playlist.Parent>,
+      context?: Document.FromImportContext<Playlist.Parent> | null,
     ): Promise<Playlist.Implementation>;
+
+    #Playlist: true;
   }
 }

package/src/foundry/client/data/documents/region-behavior.d.mts

@@ -1,9 +1,9 @@
+import type { AnyObject, Merge } from "#utils";
 import type { ConfiguredRegionBehavior } from "../../../../configuration/index.d.mts";
 import type Document from "../../../common/abstract/document.d.mts";
 import type { fields } from "../../../common/data/module.d.mts";
 import type BaseRegionBehavior from "../../../common/documents/region-behavior.d.mts";
 import type { DataSchema } from "../../../common/data/fields.d.mts";
-import type { Merge } from "../../../../utils/index.d.mts";
 
 declare global {
   namespace RegionBehavior {
@@ -170,7 +170,7 @@ declare global {
     type Collection = never;
 
     /**
-     * An instance of `RegionBehavior` that comes from the database but failed validation meaining that
+     * An instance of `RegionBehavior` that comes from the database but failed validation meaning that
      * its `system` and `_source` could theoretically be anything.
      */
     interface Invalid<out SubType extends RegionBehavior.SubType = RegionBehavior.SubType>
@@ -469,9 +469,14 @@ declare global {
      */
     protected _handleRegionEvent(event: RegionDocument.RegionEvent): void;
 
+    /**
+     * @remarks No type changes, just removes `executeScript` from `options.types` if the user lacks the `MACRO_SCRIPT` permission
+     *
+     * `context.parent` is required as creation requires one
+     */
     static override createDialog(
-      data: Document.CreateDialogData<RegionBehavior.CreateData>,
-      context: Document.CreateDialogContext<RegionBehavior.SubType, NonNullable<RegionBehavior.Parent>>,
+      data: Document.CreateDialogData<RegionBehavior.CreateData> | undefined,
+      context: Document.CreateDialogContext<"RegionBehavior", NonNullable<RegionBehavior.Parent>>,
     ): Promise<RegionBehavior.Stored | null | undefined>;
 
     /*
@@ -488,20 +493,24 @@ declare global {
 
     // Descendant Document operations have been left out because RegionBehavior does not have any descendant documents.
 
+    // context: not null (destructured)
     static override defaultName(
-      context: Document.DefaultNameContext<RegionBehavior.SubType, NonNullable<RegionBehavior.Parent>>,
+      context?: Document.DefaultNameContext<"RegionBehavior", NonNullable<RegionBehavior.Parent>>,
     ): string;
 
+    // options: not null (parameter default only)
     static override fromDropData(
       data: Document.DropData<RegionBehavior.Implementation>,
-      options?: Document.FromDropDataOptions,
+      options?: AnyObject,
     ): Promise<RegionBehavior.Implementation | undefined>;
 
     static override fromImport(
       source: RegionBehavior.Source,
-      context?: Document.FromImportContext<RegionBehavior.Parent>,
+      context?: Document.FromImportContext<RegionBehavior.Parent> | null,
     ): Promise<RegionBehavior.Implementation>;
 
+    override _onClickDocumentLink(event: MouseEvent): ClientDocument.OnClickDocumentLinkReturn;
+
     // Embedded document operations have been left out because RegionBehavior does not have any embedded documents.
   }
 }