@league-of-foundry-developers/foundry-vtt-types 9.280.1 → 12.331.2-beta

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

@@ -0,0 +1,127 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+import type Sound from "../../../client-esm/audio/sound.d.mts";
+import type Document from "../../../common/abstract/document.d.mts";
+import type { DocumentDatabaseOperations } from "../../../common/abstract/document.d.mts";
+import type BasePlaylistSound from "../../../common/documents/playlist-sound.d.mts";
+
+declare global {
+  namespace PlaylistSound {
+    type Metadata = Document.MetadataFor<PlaylistSound>;
+
+    type ConfiguredClass = Document.ConfiguredClassForName<"PlaylistSound">;
+    type ConfiguredInstance = Document.ConfiguredInstanceForName<"PlaylistSound">;
+
+    interface DatabaseOperations extends DocumentDatabaseOperations<PlaylistSound> {}
+
+    // Helpful aliases
+    type ConstructorData = BasePlaylistSound.ConstructorData;
+    type UpdateData = BasePlaylistSound.UpdateData;
+    type Schema = BasePlaylistSound.Schema;
+    type Source = BasePlaylistSound.Source;
+  }
+
+  /**
+   * The client-side PlaylistSound document which extends the common BasePlaylistSound model.
+   * Each PlaylistSound belongs to the sounds collection of a Playlist document.
+   *
+   * @see {@link Playlist}                       The Playlist document which contains PlaylistSound embedded documents
+   * @see {@link PlaylistSoundConfig}   The PlaylistSound configuration application
+   * @see {@link Sound}                          The Sound API which manages web audio playback
+   *
+   */
+  class PlaylistSound extends ClientDocumentMixin(foundry.documents.BasePlaylistSound) {
+    static override metadata: PlaylistSound.Metadata;
+
+    // Note(LukeAbby): TODO, this constructor just copies from the parent. Should this just be removed?
+    // constructor(
+    //   data: ConstructorParameters<typeof foundry.documents.BasePlaylistSound>[0],
+    //   context?: ConstructorParameters<typeof foundry.documents.BasePlaylistSound>[1],
+    // );
+
+    /**
+     * The debounce tolerance for processing rapid volume changes into database updates in milliseconds
+     * @defaultValue `100`
+     */
+    static VOLUME_DEBOUNCE_MS: number;
+
+    /**
+     * The Sound which manages playback for this playlist sound
+     */
+    sound: Sound | null;
+
+    /**
+     * A debounced function, accepting a single volume parameter to adjust the volume of this sound
+     * @param volume - The desired volume level
+     */
+    debounceVolume: (volume: number) => void;
+
+    /**
+     * Create a Sound used to play this PlaylistSound document
+     * @internal
+     */
+    protected _createSound(): Sound | null;
+
+    /**
+     * Determine the fade duration for this PlaylistSound based on its own configuration and that of its parent.
+     */
+    get fadeDuration(): number;
+
+    /**
+     * The audio context within which this sound is played.
+     * This will be undefined if the audio context is not yet active.
+     */
+    get context(): AudioContext | undefined;
+
+    /**
+     * Synchronize playback for this particular PlaylistSound instance
+     */
+    sync(): void | Promise<void> | Promise<Sound>;
+
+    /**
+     * 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.ConfiguredInstance["stopSound" | "playSound"]>;
+
+    /**
+     * @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.
+     */
+
+    /**
+     * Special handling that occurs when playback of a PlaylistSound is started.
+     * @internal
+     */
+    protected _onStart(): Promise<void>;
+
+    /**
+     * Special handling that occurs when a PlaylistSound reaches the natural conclusion of its playback.
+     * @internal
+     */
+    protected _onEnd(): Promise<void | Playlist.ConfiguredInstance | undefined>;
+
+    /**
+     * Special handling that occurs when a PlaylistSound is manually stopped before its natural conclusion.
+     * @internal
+     */
+    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
+     *
+     */
+    get effectiveVolume(): number;
+  }
+}

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

@@ -0,0 +1,207 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+import type { DocumentDatabaseOperations } from "../../../common/abstract/document.d.mts";
+import type { Document } from "../../../common/abstract/module.d.mts";
+import type BasePlaylist from "../../../common/documents/playlist.d.mts";
+import type { ClientDocument } from "../abstract/client-document.d.mts";
+
+declare global {
+  namespace Playlist {
+    type Metadata = Document.MetadataFor<Playlist>;
+
+    type ConfiguredClass = Document.ConfiguredClassForName<"Playlist">;
+    type ConfiguredInstance = Document.ConfiguredInstanceForName<"Playlist">;
+
+    interface DatabaseOperations extends DocumentDatabaseOperations<Playlist> {}
+
+    // Helpful aliases
+    type ConstructorData = BasePlaylist.ConstructorData;
+    type UpdateData = BasePlaylist.UpdateData;
+    type Schema = BasePlaylist.Schema;
+    type Source = BasePlaylist.Source;
+
+    interface PlayNextOptions {
+      /**
+       * Whether to advance forward (if 1) or backwards (if -1)
+       * @defaultValue `1`
+       */
+      direction: 1 | -1;
+    }
+  }
+
+  /**
+   * The client-side Playlist document which extends the common BasePlaylist model.
+   *
+   * @see {@link Playlists}             The world-level collection of Playlist documents
+   * @see {@link PlaylistSound}         The PlaylistSound embedded document within a parent Playlist
+   * @see {@link PlaylistConfig}        The Playlist configuration application
+   *
+   */
+  class Playlist extends ClientDocumentMixin(foundry.documents.BasePlaylist) {
+    static override metadata: Playlist.Metadata;
+
+    /**
+     * Playlists may have a playback order which defines the sequence of Playlist Sounds
+     * @defaultValue `undefined`
+     * @internal
+     */
+    protected _playbackOrder: string[] | undefined;
+
+    /**
+     * The order in which sounds within this playlist will be played (if sequential or shuffled)
+     * Uses a stored seed for randomization to guarantee that all clients generate the same random order.
+     */
+    get playbackOrder(): string[];
+
+    override get visible(): boolean;
+
+    /**
+     * Find all content links belonging to a given {@link Playlist} or {@link PlaylistSound}.
+     * @param doc - The Playlist or PlaylistSound.
+     */
+    static _getSoundContentLinks(doc: Playlist | PlaylistSound): NodeListOf<Element>;
+
+    override prepareDerivedData(): void;
+
+    /**
+     * Begin simultaneous playback for all sounds in the Playlist.
+     * @returns The updated Playlist document
+     */
+    playAll(): Promise<this | undefined>;
+
+    /**
+     * Play the next Sound within the sequential or shuffled Playlist.
+     * @param soundId - The currently playing sound ID, if known
+     * @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>;
+
+    /**
+     * Begin playback of a specific Sound within this Playlist.
+     * Determine which other sounds should remain playing, if any.
+     * @param sound - The desired sound that should play
+     * @returns The updated Playlist
+     */
+    playSound(sound: PlaylistSound.ConfiguredInstance): Promise<this | undefined>;
+
+    /**
+     * Stop playback of a specific Sound within this Playlist.
+     * Determine which other sounds should remain playing, if any.
+     * @param sound - The desired sound that should play
+     * @returns The updated Playlist
+     */
+    stopSound(sound: PlaylistSound.ConfiguredInstance): Promise<this | undefined>;
+
+    /**
+     * End playback for any/all currently playing sounds within the Playlist.
+     * @returns The updated Playlist document
+     */
+    stopAll(): Promise<this | undefined>;
+
+    /**
+     * Cycle the playlist mode
+     * @returns A promise which resolves to the updated Playlist instance
+     */
+    cycleMode(): Promise<this | undefined>;
+
+    /**
+     * Get the next sound in the cached playback order. For internal use.
+     * @internal
+     */
+    protected _getNextSound(soundId: string): PlaylistSound.ConfiguredInstance | undefined;
+
+    /**
+     * Get the previous sound in the cached playback order. For internal use.
+     * @internal
+     */
+    protected _getPreviousSound(soundId: string): PlaylistSound.ConfiguredInstance | undefined;
+
+    /**
+     * 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
+     */
+    protected _sortSounds(a: PlaylistSound.ConfiguredInstance, b: PlaylistSound.ConfiguredInstance): 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"]>;
+
+    /**
+     * @privateRemarks _preUpdate, _onUpdate, _onDelete, _onCreateDescendantDocuments, _onUpdateDescendantDocuments, and _onDeleteDescendantDocuments 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.
+     */
+
+    protected override _onCreateDescendantDocuments(
+      parent: ClientDocument<Document.Any>,
+      collection: string,
+      documents: ClientDocument<Document.Any>[],
+      data: unknown[],
+      options: Document.OnCreateOptions<"PlaylistSound">,
+      userId: string,
+    ): void;
+
+    protected override _onUpdateDescendantDocuments(
+      parent: ClientDocument<Document.Any>,
+      collection: string,
+      documents: ClientDocument<Document.Any>[],
+      changes: unknown[],
+      options: Document.OnUpdateOptions<"PlaylistSound">,
+      userId: string,
+    ): void;
+
+    protected override _onDeleteDescendantDocuments(
+      parent: ClientDocument<Document.Any>,
+      collection: string,
+      documents: ClientDocument<Document.Any>[],
+      ids: string,
+      options: Document.OnDeleteOptions<"PlaylistSound">,
+      userId: string,
+    ): void;
+
+    /**
+     * Handle callback logic when an individual sound within the Playlist concludes playback naturally
+     * @internal
+     */
+    _onSoundEnd(sound: PlaylistSound.ConfiguredInstance): Promise<this | undefined>;
+
+    /**
+     * Handle callback logic when playback for an individual sound within the Playlist is started.
+     * Schedule auto-preload of next track
+     * @internal
+     */
+    _onSoundStart(sound: PlaylistSound.ConfiguredInstance): Promise<void>;
+
+    override toCompendium<
+      FlagsOpt extends boolean = false,
+      SourceOpt extends boolean = true,
+      SortOpt extends boolean = true,
+      FolderOpt extends boolean = false,
+      OwnershipOpt extends boolean = false,
+      StateOpt extends boolean = true,
+      IdOpt extends boolean = false,
+    >(
+      pack?: CompendiumCollection<CompendiumCollection.Metadata> | null,
+      options?: InexactPartial<
+        ClientDocument.CompendiumExportOptions<FlagsOpt, SourceOpt, SortOpt, FolderOpt, OwnershipOpt, StateOpt, IdOpt>
+      >,
+    ): Omit<
+      this["_source"],
+      | (IdOpt extends false ? "_id" : never)
+      | ClientDocument.OmitProperty<SortOpt, "sort" | "navigation" | "navOrder">
+      | ClientDocument.OmitProperty<FolderOpt, "folder">
+      | ClientDocument.OmitProperty<FlagsOpt, "flags">
+      | ClientDocument.OmitProperty<OwnershipOpt, "ownership">
+      | ClientDocument.OmitProperty<StateOpt, "active" | "fogReset" | "playing"> // does not model the sounds.playing = false
+    >;
+  }
+}

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

@@ -0,0 +1,256 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+import type Document from "../../../common/abstract/document.d.mts";
+import type { DocumentDatabaseOperations } from "../../../common/abstract/document.d.mts";
+import type BaseScene from "../../../common/documents/scene.d.mts";
+
+declare global {
+  namespace Scene {
+    type Metadata = Document.MetadataFor<Scene>;
+
+    type ConfiguredClass = Document.ConfiguredClassForName<"Scene">;
+    type ConfiguredInstance = Document.ConfiguredInstanceForName<"Scene">;
+
+    /* eslint-disable @typescript-eslint/no-empty-object-type */
+    export interface DatabaseOperations
+      extends DocumentDatabaseOperations<
+        Scene,
+        {},
+        { thumb: (string | null)[]; autoReposition: boolean; animateDarkness: number },
+        {}
+      > {}
+    /* eslint-enable @typescript-eslint/no-empty-object-type */
+
+    // Helpful aliases
+    type ConstructorData = BaseScene.ConstructorData;
+    type UpdateData = BaseScene.UpdateData;
+    type Schema = BaseScene.Schema;
+    type Source = BaseScene.Source;
+  }
+
+  /**
+   * The client-side Scene document which extends the common BaseScene model.
+   *
+   * @see {@link Scenes}            The world-level collection of Scene documents
+   * @see {@link SceneConfig}       The Scene configuration application
+   *
+   */
+  class Scene extends ClientDocumentMixin(foundry.documents.BaseScene) {
+    static override metadata: Scene.Metadata;
+
+    /**
+     * Track the viewed position of each scene (while in memory only, not persisted)
+     * When switching back to a previously viewed scene, we can automatically pan to the previous position.
+     * @defaultValue `{}`
+     * @remarks This is intentionally public because it is used in Canvas._initializeCanvasPosition() and Canvas.pan()
+     */
+    _viewPosition: Canvas.ViewPosition;
+
+    /**
+     * Track whether the scene is the active view
+     */
+    protected _view: this["active"];
+
+    /**
+     * The grid instance
+     */
+    grid: foundry.grid.BaseGrid;
+
+    /**
+     * Determine the canvas dimensions this Scene would occupy, if rendered
+     * @defaultValue `{}`
+     */
+    dimensions: ReturnType<this["getDimensions"]>;
+
+    /**
+     * Provide a thumbnail image path used to represent this document.
+     */
+    get thumbnail(): this["thumb"];
+
+    /**
+     * A convenience accessor for whether the Scene is currently viewed
+     */
+    get isView(): boolean;
+
+    /**
+     * Set this scene as currently active
+     * @returns A Promise which resolves to the current scene once it has been successfully activated
+     */
+    activate(): Promise<this | undefined>;
+
+    /**
+     * Set this scene as the current view
+     */
+    view(): Promise<this | undefined>;
+
+    /**
+     * @param createData - (default: `{}`)
+     * @param options    - (default: `{}`)
+     */
+    override clone<Save extends boolean = false>(
+      createData?: foundry.documents.BaseScene.ConstructorData,
+      context?: InexactPartial<
+        {
+          /**
+           * Save the clone to the World database?
+           * @defaultValue `false`
+           */
+          save: Save;
+
+          /**
+           * Keep the same ID of the original document
+           * @defaultValue `false`
+           */
+          keepId: boolean;
+        } & Document.ConstructionContext<this["parent"]>
+      >,
+    ): Save extends true ? Promise<this> : this;
+
+    override reset(): void;
+
+    override prepareBaseData(): void;
+
+    /**
+     * Get the Canvas dimensions which would be used to display this Scene.
+     * Apply padding to enlarge the playable space and round to the nearest 2x grid size to ensure symmetry.
+     * The rounding accomplishes that the padding buffer around the map always contains whole grid spaces.
+     */
+    getDimensions(): SceneDimensions;
+
+    override _onClickDocumentLink(event: MouseEvent): unknown;
+
+    /**
+     * @privateRemarks _onCreate, _preUpdate, _onUpdate, _preDelete, 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.
+     */
+
+    /**
+     * Handle repositioning of placed objects when the Scene dimensions change
+     */
+    protected _repositionObject(
+      sceneUpdateData: foundry.documents.BaseScene.ConstructorData,
+    ): foundry.documents.BaseScene.ConstructorData;
+
+    /**
+     * Handle Scene activation workflow if the active state is changed to true
+     * @param active - Is the scene now active?
+     */
+    protected _onActivate(active: boolean): ReturnType<this["view"]> | ReturnType<Canvas["draw"]>;
+
+    /**
+     * @privateRemarks _preCreateDescendantDocuments, _preUpdateDescendantDocuments, _preDeleteDescendantDocuments, and_onUpdateDescendantDocuments 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.
+     */
+
+    override toCompendium<
+      FlagsOpt extends boolean = false,
+      SourceOpt extends boolean = true,
+      SortOpt extends boolean = true,
+      FolderOpt extends boolean = false,
+      OwnershipOpt extends boolean = false,
+      StateOpt extends boolean = true,
+      IdOpt extends boolean = false,
+    >(
+      pack?: CompendiumCollection<CompendiumCollection.Metadata> | null,
+      options?: InexactPartial<
+        ClientDocument.CompendiumExportOptions<FlagsOpt, SourceOpt, SortOpt, FolderOpt, OwnershipOpt, StateOpt, IdOpt>
+      >,
+    ): Omit<
+      this["_source"],
+      | (IdOpt extends false ? "_id" : never)
+      | ClientDocument.OmitProperty<SortOpt, "sort" | "navigation" | "navOrder">
+      | ClientDocument.OmitProperty<FolderOpt, "folder">
+      | ClientDocument.OmitProperty<FlagsOpt, "flags">
+      | ClientDocument.OmitProperty<OwnershipOpt, "ownership">
+      | ClientDocument.OmitProperty<StateOpt, "active" | "fogReset" | "playing">
+    >;
+
+    /**
+     * Create a 300px by 100px thumbnail image for this scene background
+     * @param data - (default: `{}`)
+     * @returns The created thumbnail data.
+     */
+    createThumbnail(data?: InexactPartial<ThumbnailCreationData>): ReturnType<(typeof ImageHelper)["createThumbnail"]>;
+  }
+
+  interface SceneDimensions {
+    /** The width of the canvas. */
+    width: number;
+
+    /** The height of the canvas. */
+    height: number;
+
+    /** The grid size. */
+    size: number;
+
+    /** The canvas rectangle. */
+    rect: Canvas.Rectangle;
+
+    /** The X coordinate of the scene rectangle within the larger canvas. */
+    sceneX: number;
+
+    /** The Y coordinate of the scene rectangle within the larger canvas. */
+    sceneY: number;
+
+    /** The width of the scene. */
+    sceneWidth: number;
+
+    /** The height of the scene. */
+    sceneHeight: number;
+
+    /** The scene rectangle. */
+    sceneRect: Canvas.Rectangle;
+
+    /** The number of distance units in a single grid space. */
+    distance: number;
+
+    /** The factor to convert distance units to pixels */
+    distancePixels: number;
+
+    /** The units of distance */
+    units: string;
+
+    /** The aspect ratio of the scene rectangle. */
+    ratio: number;
+
+    /** The length of the longest line that can be drawn on the canvas. */
+    maxR: number;
+
+    /** The number of grid rows on the canvas */
+    rows: number;
+
+    /** The number of grid columns on the canvas */
+    columns: number;
+  }
+}
+
+interface ThumbnailCreationData extends ImageHelper.TextureToImageOptions {
+  /**
+   * A background image to use for thumbnail creation, otherwise the current scene
+   * background is used.
+   */
+  img: string;
+
+  /**
+   * The desired thumbnail width. Default is 300px
+   * @defaultValue `300`
+   */
+  width: number;
+
+  /**
+   * The desired thumbnail height. Default is 100px;
+   * @defaultValue `100`
+   */
+  height: number;
+
+  /**
+   * Which image format should be used? image/png, image/jpg, or image/webp
+   * @defaultValue `"image/webp"`
+   */
+  format: "image/png" | "image/jpg" | "image/webp";
+
+  /**
+   * What compression quality should be used for jpeg or webp, between 0 and 1
+   * @defaultValue `0.8`
+   */
+  quality: number;
+}

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

@@ -0,0 +1,54 @@
+import type Document from "../../../common/abstract/document.d.mts";
+import type { DocumentDatabaseOperations } from "../../../common/abstract/document.d.mts";
+import type BaseSetting from "../../../common/documents/setting.d.mts";
+
+declare global {
+  namespace Setting {
+    type Metadata = Document.MetadataFor<Setting>;
+
+    type ConfiguredClass = Document.ConfiguredClassForName<"Setting">;
+    type ConfiguredInstance = Document.ConfiguredInstanceForName<"Setting">;
+
+    interface DatabaseOperations extends DocumentDatabaseOperations<Setting> {}
+
+    // Helpful aliases
+    type ConstructorData = BaseSetting.ConstructorData;
+    type UpdateData = BaseSetting.UpdateData;
+    type Schema = BaseSetting.Schema;
+    type Source = BaseSetting.Source;
+  }
+
+  /**
+   * The client-side Setting document which extends the common BaseSetting model.
+   *
+   * @see {@link WorldSettings}       The world-level collection of Setting documents
+   */
+  class Setting extends ClientDocumentMixin(foundry.documents.BaseSetting) {
+    static override metadata: Setting.Metadata;
+
+    /**
+     * @privateRemarks This exists to let ts know that this class has a private property
+     */
+    static #PRIMITIVE_TYPES: any;
+
+    /**
+     * The setting configuration for this setting document.
+     */
+    get config(): SettingsConfig | undefined;
+
+    // TODO: This is the same as `DataModel._initialize`
+    protected _initialize(options?: any): void;
+
+    /**
+     * @privateRemarks _onCreate and _preUpdate are 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.
+     */
+
+    /**
+     * Cast the value of the Setting into its defined type.
+     * @returns The initialized type of the Setting document.
+     */
+    // TODO: This could probably be derived
+    protected _castType(): any;
+  }
+}

package/src/foundry/client/data/documents/table-result.d.mts

@@ -0,0 +1,41 @@
+import type Document from "../../../common/abstract/document.d.mts";
+import type { DocumentDatabaseOperations } from "../../../common/abstract/document.d.mts";
+import type BaseTableResult from "../../../common/documents/table-result.d.mts";
+
+declare global {
+  namespace TableResult {
+    type Metadata = Document.MetadataFor<TableResult>;
+
+    type ConfiguredClass = Document.ConfiguredClassForName<"TableResult">;
+    type ConfiguredInstance = Document.ConfiguredInstanceForName<"TableResult">;
+
+    interface DatabaseOperations extends DocumentDatabaseOperations<TableResult> {}
+
+    // Helpful aliases
+    type TypeNames = BaseTableResult.TypeNames;
+    type ConstructorData = BaseTableResult.ConstructorData;
+    type UpdateData = BaseTableResult.UpdateData;
+    type Schema = BaseTableResult.Schema;
+    type Source = BaseTableResult.Source;
+  }
+
+  /**
+   * The client-side TableResult document which extends the common BaseTableResult model.
+   *
+   * @see {@link RollTable}         The RollTable document which contains TableResult embedded documents
+   */
+  class TableResult extends ClientDocumentMixin(foundry.documents.BaseTableResult) {
+    static override metadata: TableResult.Metadata;
+
+    /**
+     * A path reference to the icon image used to represent this result
+     */
+    get icon(): string;
+
+    /**
+     * Prepare a string representation for the result which (if possible) will be a dynamic link or otherwise plain text
+     * @returns The text to display
+     */
+    getChatText(): string;
+  }
+}