@league-of-foundry-developers/foundry-vtt-types 12.331.3-beta → 13.340.0

package/src/foundry/client-esm/_module.d.mts

@@ -0,0 +1,112 @@
+// In Foundry itself this file contains re-exports of these other modules.
+// Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
+// While `.mts` could work, to avoid `import-x/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import-x/extensions */
+
+// /* -------------------------------------------- */
+// /*  Commons                                     */
+// /* -------------------------------------------- */
+
+// import * as globalUI from "./ui.mjs";
+
+export * as CONST from "@common/constants.mjs";
+
+// // declare global {
+// //   const logger: typeof console;
+// // }
+
+/**
+ * Document definitions used throughout the Foundry Virtual Tabletop framework.
+ */
+export * as documents from "./documents/_module.mjs";
+
+/**
+ * A module which defines data architecture components.
+ */
+export * as data from "./data/_module.mjs";
+
+/**
+ * Package data definitions, validations, and schema.
+ */
+export * as packages from "./packages/_module.mjs";
+
+/**
+ * Abstract class definitions for fundamental concepts used throughout the Foundry Virtual Tabletop framework.
+ */
+export * as abstract from "@common/abstract/_module.mjs";
+
+/**
+ * Utility functions providing helpful functionality.
+ */
+export * as utils from "./utils/_module.mjs";
+
+/**
+ * Application configuration options
+ */
+export * as config from "@common/config.mjs";
+
+/**
+ * A library for providing rich text editing using ProseMirror within the Foundry Virtual Tabletop game client.
+ */
+export * as prosemirror from "@common/prosemirror/_module.mjs";
+
+/**
+ * Grid classes.
+ */
+export * as grid from "@common/grid/_module.mjs";
+
+// /* -------------------------------------------- */
+// /*  Client                                      */
+// /* -------------------------------------------- */
+
+/**
+ * A library for rendering and managing HTML user interface elements within the Foundry Virtual Tabletop game client.
+ */
+export * as applications from "./applications/_module.mjs";
+
+/**
+ * A library for legacy ApplicationV1 classes and helpers.
+ */
+export * as appv1 from "./appv1/_module.mjs";
+
+/**
+ * Audio/video over WebRTC.
+ */
+export * as av from "./av/_module.mjs";
+
+/**
+ * A library for controlling audio playback within the Foundry Virtual Tabletop game client.
+ */
+export * as audio from "./audio/_module.mjs";
+
+/**
+ * A submodule defining concepts related to canvas rendering.
+ */
+export * as canvas from "./canvas/_module.mjs";
+
+/**
+ * A module for parsing and executing dice roll syntax.
+ */
+export * as dice from "./dice/_module.mjs";
+
+/**
+ * A submodule containing core helper classes.
+ */
+export * as helpers from "./helpers/_module.mjs";
+
+/**
+ * A module containing utilities and tools for improving new user experience.
+ */
+export * as nue from "./nue/_module.mjs";
+
+export { default as Game } from "./game.mjs";
+
+// /**
+//  * A collection of application instances
+//  */
+// // export const ui = {...globalUI};
+
+/**
+ * Client/shared importable types.
+ */
+export * as types from "./_types.mjs";

package/src/foundry/client-esm/_types.d.mts

@@ -0,0 +1,8 @@
+// After seeing that none of these types add anything or are even exported a
+// very reasonable question may be: Why on earth does this file exist?
+//
+// Well this is the file in which Foundry defines these types. We don't house
+// them here because it has poor discoverability. The names Foundry has chosen
+// also overlaps with other existing names, such as SettingConfig vs. ClientSetting.SettingConfig
+
+export * from "@common/_types.mjs";

package/src/foundry/client-esm/applications/_module.d.mts

@@ -1,21 +1,26 @@
 // In Foundry itself this file contains re-exports of these other modules.
 // Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
-// While `.mts` could work, to avoid `import/no-unresolved` from erroring `.mjs` is used.
-/* eslint-disable import/extensions */
+// While `.mts` could work, to avoid `import-x/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import-x/extensions */
 
-export * as types from "./_types.mjs";
 export * as api from "./api/_module.mjs";
+export * as apps from "./apps/_module.mjs";
 export * as dice from "./dice/_module.mjs";
 export * as elements from "./elements/_module.mjs";
 export * as fields from "./forms/fields.mjs";
-export * as apps from "./apps/_module.mjs";
+export * as handlebars from "./handlebars.mjs";
+export * as hud from "./hud/_module.mjs";
+export * as settings from "./settings/_module.mjs";
 export * as sheets from "./sheets/_module.mjs";
+export * as sidebar from "./sidebar/_module.mjs";
+export * as types from "./_types.mjs";
+export * as ux from "./ux/_module.mjs";
 export * as ui from "./ui/_module.mjs";
 
 /**
  * A registry of currently rendered ApplicationV2 instances.
  */
-export const instances: Map<number, foundry.applications.api.ApplicationV2>;
+export const instances: Map<string, foundry.applications.api.ApplicationV2.Any>;
 
 /**
  * Parse an HTML string, returning a processed HTMLElement or HTMLCollection.

package/src/foundry/client-esm/applications/_types.d.mts

@@ -1,7 +1,5 @@
 import type ApplicationV2 from "./api/application.d.mts";
 
-export {};
-
 // After seeing that none of these types add anything or are even exported a
 // very reasonable question may be: Why on earth does this file exist?
 //
@@ -29,6 +27,8 @@ type ApplicationClickAction = ApplicationV2.ClickAction;
 
 type ApplicationFormSubmission = ApplicationV2.FormSubmission;
 
+type ApplicationTabsConfiguration = ApplicationV2.TabsConfiguration;
+
 type ApplicationTab = ApplicationV2.Tab;
 
 type FormNode = ApplicationV2.FormNode;

package/src/foundry/client-esm/applications/api/_module.d.mts

@@ -1,9 +1,10 @@
 // In Foundry itself this file contains re-exports of these other modules.
 // Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
-// While `.mts` could work, to avoid `import/no-unresolved` from erroring `.mjs` is used.
-/* eslint-disable import/extensions */
+// While `.mts` could work, to avoid `import-x/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import-x/extensions */
 
-export { default as ApplicationV2 } from "./application.mjs";
-export { default as DialogV2 } from "./dialog.mjs";
-export { default as DocumentSheetV2 } from "./document-sheet.mjs";
+export { default as ApplicationV2, default as Application } from "./application.mjs";
+export { default as DialogV2, default as Dialog } from "./dialog.mjs";
+export { default as DocumentSheetV2, default as DocumentSheet } from "./document-sheet.mjs";
 export { default as HandlebarsApplicationMixin } from "./handlebars-application.mjs";
+export { default as CategoryBrowser } from "./category-browser.mjs";

package/src/foundry/client-esm/applications/api/application.d.mts

@@ -1,6 +1,13 @@
-import type { MustConform } from "../../../../types/helperTypes.d.mts";
-import type { AnyObject, DeepPartial, EmptyObject, InexactPartial, MaybePromise } from "../../../../types/utils.d.mts";
-import type EventEmitterMixin from "../../../common/utils/event-emitter.d.mts";
+import type {
+  MustConform,
+  AnyObject,
+  DeepPartial,
+  InexactPartial,
+  MaybePromise,
+  ValueOf,
+  AnyArray,
+} from "../../../../utils/index.d.mts";
+import type EventEmitterMixin from "@common/utils/event-emitter.d.mts";
 
 // TODO: Investigate use of DeepPartial vs Partial vs InexactPartial
 
@@ -15,6 +22,7 @@ type _InstanceMustBeAssignableToInternal = MustConform<ApplicationV2, Applicatio
 
 declare namespace ApplicationV2 {
   type Any = ApplicationV2<any, any, any>;
+  type AnyConstructor = typeof AnyApplicationV2;
 
   // Documented at https://gist.github.com/LukeAbby/c7420b053d881db4a4d4496b95995c98
   namespace Internal {
@@ -48,6 +56,44 @@ declare namespace ApplicationV2 {
     }
   }
 
+  type EmittedEvents = Readonly<["render", "close", "position"]>;
+
+  interface DoEventOptions<HandlerArgs extends AnyArray, Async extends boolean | undefined = false> {
+    /**
+     * Await the result of the handler function?
+     * @defaultValue `false`
+     */
+    async: Async;
+
+    /**
+     * Arguments passed to the handler function
+     * @defaultValue `[]`
+     */
+    handlerArgs: HandlerArgs;
+
+    /** Debugging text to log for the event */
+    debugText: string;
+
+    /** An event name to dispatch for registered listeners */
+    eventName: string;
+
+    /** A hook name to dispatch for this and all parent classes */
+    hookName: string;
+
+    /** Arguments passed to the requested hook function */
+    hookArgs: string;
+
+    /** Add the handler response to hookArgs */
+    hookResponse: boolean;
+  }
+
+  type RenderState = ValueOf<typeof ApplicationV2.RENDER_STATES>;
+
+  export interface RenderContext {
+    /** Tab data prepared from an entry in {@link ApplicationV2.TABS} */
+    tabs?: Record<string, Tab>;
+  }
+
   export interface Configuration {
     /**
      * An HTML element identifier used for this Application instance
@@ -102,10 +148,16 @@ declare namespace ApplicationV2 {
     /** Window offset pixels from left */
     left: number;
 
-    /** Un-scaled pixels in width or "auto" */
+    /**
+     * Un-scaled pixels in width or "auto"
+     * @defaultValue "auto"
+     */
     width: number | "auto";
 
-    /** Un-scaled pixels in height or "auto" */
+    /**
+     * Un-scaled pixels in height or "auto"
+     * @defaultValue "auto"
+     */
     height: number | "auto";
 
     /** A numeric scaling factor applied to application dimensions */
@@ -178,7 +230,7 @@ declare namespace ApplicationV2 {
     action: string;
 
     /** Is the control button visible for the current client? */
-    visible?: boolean | undefined;
+    visible?: boolean | (() => boolean) | undefined;
 
     /**
      * A key or value in CONST.DOCUMENT_OWNERSHIP_LEVELS that restricts visibility of this option for the current user.
@@ -231,6 +283,9 @@ declare namespace ApplicationV2 {
 
     /** Whether the application was closed via keypress. */
     closeKey: boolean;
+
+    /** Is the application being closed because a form was submitted? */
+    submitted: boolean;
   }
 
   /** An on-click action supported by the Application. Run in the context of a HandlebarsApplication. */
@@ -254,14 +309,27 @@ declare namespace ApplicationV2 {
     formData: FormDataExtended,
   ) => MaybePromise<void>;
 
+  interface TabsConfiguration {
+    /** An array of tab configuration data */
+    tabs: Omit<Tab, "group" | "active">[];
+
+    /** The tab in this group that will be active on first render */
+    initial?: string | null | undefined;
+    /**
+     * A localization path prefix for all tabs in the group: if set, a label is generated
+     * for each tab using a full path of `${labelPrefix}.${tabId}`.
+     */
+    labelPrefix?: string | null | undefined;
+  }
+
   /** @remarks Used with `templates/generic/tab-navigation.hbs` */
   interface Tab {
     id: string;
     group: string;
-    icon: string;
-    label: string;
     active: boolean;
     cssClass: string;
+    icon?: string | null | undefined;
+    label?: string | null | undefined;
   }
 
   /** @remarks Used with `templates/generic/form-fields.hbs` */
@@ -274,7 +342,7 @@ declare namespace ApplicationV2 {
 
     field?: foundry.data.fields.DataField | undefined;
 
-    value?: unknown | undefined;
+    value?: unknown;
   }
 
   /** @remarks Used with `templates/generic/form-footer.hbs` */
@@ -295,6 +363,19 @@ declare namespace ApplicationV2 {
     disabled?: boolean | undefined;
   }
 
+  interface ToggleControlOptions {
+    /**
+     * Animate the controls toggling.
+     * @defaultValue `true`
+     * @remarks `null` equivalent to `false`
+     */
+    animate?: boolean | null | undefined;
+  }
+
+  /**
+   * @remarks InexactPartial is used over NullishProps because event/navElement are not called with null as a possible value,
+   *          and null interferes with the defaults of force/updatePosition
+   */
   interface ChangeTabOptions
     extends InexactPartial<{
       /**
@@ -324,7 +405,8 @@ declare namespace ApplicationV2 {
 declare class ApplicationV2<
   // Foundry doesn't define this generic in its documentation but it's necessary
   // in fvtt-types to type `_prepareContext` etc.
-  RenderContext extends AnyObject = EmptyObject,
+  // `extends object` is to avoid having to call `InterfaceToObject` everywhere
+  RenderContext extends object = ApplicationV2.RenderContext,
   Configuration extends ApplicationV2.Configuration = ApplicationV2.Configuration,
   RenderOptions extends ApplicationV2.RenderOptions = ApplicationV2.RenderOptions,
 > extends EventEmitterMixin(Object) {
@@ -334,12 +416,37 @@ declare class ApplicationV2<
   [__RenderOptions]: RenderOptions;
   [__RenderContext]: RenderContext;
 
-  constructor(options: DeepPartial<Configuration>);
+  /**
+   * Applications are constructed by providing an object of configuration options.
+   * @param options - Options used to configure the Application instance
+   *                  (default: `{}`)
+   */
+  // not: null
+  constructor(options?: DeepPartial<Configuration>);
 
+  /**
+   * Designates which upstream Application class in this class' inheritance chain is the base application.
+   * Any DEFAULT_OPTIONS of super-classes further upstream of the BASE_APPLICATION are ignored.
+   * Hook events for super-classes further upstream of the BASE_APPLICATION are not dispatched.
+   */
   static BASE_APPLICATION: typeof ApplicationV2;
 
-  static DEFAULT_OPTIONS: DeepPartial<ApplicationV2.Configuration>;
+  /**
+   * The default configuration options which are assigned to every instance of this Application class.
+   * @privateRemarks This `& object` is so that the `DEFAULT_OPTIONS` can be overridden more easily
+   * Without it then `static override DEFAULT_OPTIONS = { unrelatedProp: 123 }` would error.
+   */
+  static DEFAULT_OPTIONS: DeepPartial<ApplicationV2.Configuration> & object;
+
+  /**
+   * Configuration of application tabs, with an entry per tab group.
+   * @defaultValue `{}`
+   */
+  static TABS: Record<string, ApplicationV2.TabsConfiguration>;
 
+  /**
+   * The sequence of rendering states that describe the Application life-cycle.
+   */
   static readonly RENDER_STATES: {
     ERROR: -3;
     CLOSING: -2;
@@ -349,12 +456,12 @@ declare class ApplicationV2<
     RENDERED: 2;
   };
 
-  static override readonly emittedEvents: ["render", "close", "position"];
+  static override readonly emittedEvents: string[];
 
   /**
    * Application instance configuration options.
    */
-  options: Readonly<DeepPartial<Configuration>>;
+  options: Readonly<Configuration>;
 
   /**
    * Convenience references to window header elements.
@@ -375,10 +482,10 @@ declare class ApplicationV2<
 
   /**
    * If this Application uses tabbed navigation groups, this mapping is updated whenever the changeTab method is called.
-   * Reports the active tab for each group.
+   * Reports the active tab for each group, with a value of `null` indicating no tab is active.
    * Subclasses may override this property to define default tabs for each group.
    */
-  tabGroups: Record<string, string>;
+  tabGroups: Record<string, string | null>;
 
   /**
    * The CSS class list of this Application instance
@@ -387,6 +494,9 @@ declare class ApplicationV2<
 
   /**
    * The HTML element ID of this Application instance.
+   * This provides a readonly view into the internal ID used by this application.
+   * This getter should not be overridden by subclasses, which should instead configure the ID in `DEFAULT_OPTIONS` or
+   * by defining a `uniqueId` during `_initializeApplicationOptions`.
    */
   get id(): string;
 
@@ -400,6 +510,11 @@ declare class ApplicationV2<
    */
   get element(): HTMLElement;
 
+  /**
+   * Does this Application have a top-level form element?
+   */
+  get form(): HTMLFormElement | null;
+
   /**
    * Is this Application instance currently minimized?
    */
@@ -418,7 +533,7 @@ declare class ApplicationV2<
   /**
    * The current render state of the Application.
    */
-  get state(): typeof ApplicationV2.RENDER_STATES;
+  get state(): ApplicationV2.RenderState;
 
   /**
    * Does this Application instance render within an outer window frame?
@@ -429,7 +544,7 @@ declare class ApplicationV2<
    * Iterate over the inheritance chain of this Application.
    * The chain includes this Application itself and all parents until the base application is encountered.
    */
-  static inheritanceChain(): Generator<typeof ApplicationV2>;
+  static inheritanceChain(): Generator<ApplicationV2.AnyConstructor>;
 
   /**
    * Initialize configuration options for the Application instance.
@@ -440,20 +555,27 @@ declare class ApplicationV2<
    * @param options - Options provided directly to the constructor
    * @returns Configured options for the application instance
    */
-  protected _initializeApplicationOptions(
-    options: DeepPartial<Configuration>,
-  ): DeepPartial<Configuration> & Record<string, unknown>;
+  protected _initializeApplicationOptions(options: DeepPartial<Configuration>): Configuration;
 
   /**
    * Render the Application, creating its HTMLElement and replacing its innerHTML.
    * Add it to the DOM if it is not currently rendered and rendering is forced. Otherwise, re-render its contents.
-   * @param options  - Options which configure application rendering behavior.
-   *                   A boolean is interpreted as the "force" option.
-   * @param _options - Legacy options for backwards-compatibility with the original
-   *                   ApplicationV1#render signature.
+   * @param options - Options which configure application rendering behavior.
+   *                  A boolean is interpreted as the "force" option.
+   *                  (default: `{}`)
    * @returns A Promise which resolves to the rendered Application instance
    */
-  render(options?: DeepPartial<Configuration> | boolean, _options?: DeepPartial<RenderOptions>): Promise<this>;
+  // not: null
+  render(options?: DeepPartial<RenderOptions>): Promise<this>;
+
+  /**
+   * @deprecated Exists for backwards compatibility with the original `ApplicationV1#render` signature.
+   *
+   * @param _options - Legacy options for backwards-compatibility with the original ApplicationV1#render signature.
+   *                   (default: `{}`)
+   */
+  // not: null
+  render(options: boolean, _options?: DeepPartial<RenderOptions>): Promise<this>;
 
   /**
    * Modify the provided options passed to a render request.
@@ -466,7 +588,19 @@ declare class ApplicationV2<
    * @param options - Options which configure application rendering behavior
    * @returns Context data for the render operation
    */
-  protected _prepareContext(options: DeepPartial<RenderOptions>): Promise<RenderContext>;
+  protected _prepareContext(options: DeepPartial<RenderOptions> & { isFirstRender: boolean }): Promise<RenderContext>;
+
+  /**
+   * Prepare application tab data for a single tab group.
+   * @param group - The ID of the tab group to prepare
+   */
+  protected _prepareTabs(group: string): Record<string, ApplicationV2.Tab>;
+
+  /**
+   * Get the configuration for a tabs group.
+   * @param group - The ID of a tabs group
+   */
+  protected _getTabsConfig(group: string): ApplicationV2.TabsConfiguration | null;
 
   /**
    * Configure the array of header control menu options
@@ -528,6 +662,7 @@ declare class ApplicationV2<
    * @param options - Options which modify how the application is closed.
    * @returns A Promise which resolves to the closed Application instance
    */
+  // not: null
   close(options?: DeepPartial<ApplicationV2.ClosingOptions>): Promise<this>;
 
   /**
@@ -537,11 +672,16 @@ declare class ApplicationV2<
    */
   protected _removeElement(element: HTMLElement): void;
 
+  /**
+   * Remove elements from the DOM and trigger garbage collection as part of application closure.
+   */
+  protected _tearDown(options: DeepPartial<ApplicationV2.ClosingOptions>): void;
+
   /**
    * Update the Application element position using provided data which is merged with the prior position.
    * @param position - New Application positioning data
    */
-  setPosition(position: DeepPartial<ApplicationV2.Position>): ApplicationV2.Position;
+  setPosition(position: DeepPartial<ApplicationV2.Position>): ApplicationV2.Position | void;
 
   /**
    * Translate a requested application position updated into a resolved allowed position for the Application.
@@ -555,9 +695,13 @@ declare class ApplicationV2<
    * Toggle display of the Application controls menu.
    * Only applicable to window Applications.
    * @param expanded - Set the controls visibility to a specific state.
-   *                   Otherwise, the visible state is toggled from its current value
+   *                   Otherwise, the visible state is toggled from its current value.
+   *                   `null` is same as undefined
+   * @param options  - Options to configure the toggling behavior
+   * @returns A Promise which resolves once the control expansion animation is complete
    */
-  toggleControls(expanded?: boolean): void;
+  // not: null
+  toggleControls(expanded?: boolean | null, options?: ApplicationV2.ToggleControlOptions): void;
 
   /**
    * Minimize the Application, collapsing it to a minimal header.
@@ -581,11 +725,25 @@ declare class ApplicationV2<
    * @param tab     - The name of the tab which should become active
    * @param group   - The name of the tab group which defines the set of tabs
    * @param options - Additional options which affect tab navigation
-   * @remarks InexactPartial is used over NullishProps because event/navElement are not called with null as a possible value,
-   *          and null interferes with the defaults of force/updatePosition
+   *                  (default: `{}`)
    */
+  // not: null
   changeTab(tab: string, group: string, options?: ApplicationV2.ChangeTabOptions): void;
 
+  /**
+   * Perform an event in the application life-cycle.
+   * Await an internal life-cycle method defined by the class.
+   * Optionally dispatch an event for any registered listeners.
+   * @param handler - A handler function to call
+   * @param options - Options which configure event handling
+   * @returns A promise which resoles once the handler is complete if async is true
+   */
+  // not: null
+  protected _doEvent<HandlerArgs extends AnyArray, Async extends boolean | undefined = false>(
+    handler: (...args: HandlerArgs) => Async extends true ? Promise<void> : void,
+    options?: InexactPartial<ApplicationV2.DoEventOptions<HandlerArgs, Async>>,
+  ): Async extends true ? Promise<void> : void;
+
   /**
    * Test whether this Application is allowed to be rendered.
    * @param options - Provided render options
@@ -603,11 +761,10 @@ declare class ApplicationV2<
 
   /**
    * Actions performed after a first render of the Application.
-   * Post-render steps are not awaited by the render process.
    * @param context - Prepared context data
    * @param options - Provided render options
    */
-  protected _onFirstRender(context: DeepPartial<RenderContext>, options: DeepPartial<RenderOptions>): void;
+  protected _onFirstRender(context: DeepPartial<RenderContext>, options: DeepPartial<RenderOptions>): Promise<void>;
 
   /**
    * Actions performed before any render of the Application.
@@ -619,11 +776,10 @@ declare class ApplicationV2<
 
   /**
    * Actions performed after any render of the Application.
-   * Post-render steps are not awaited by the render process.
    * @param context - Prepared context data
    * @param options - Provided render options
    */
-  protected _onRender(context: DeepPartial<RenderContext>, options: DeepPartial<RenderOptions>): void;
+  protected _onRender(context: DeepPartial<RenderContext>, options: DeepPartial<RenderOptions>): Promise<void>;
 
   /**
    * Actions performed before closing the Application.
@@ -657,6 +813,11 @@ declare class ApplicationV2<
    */
   protected _attachFrameListeners(): void;
 
+  /**
+   * Handle click events on a tab within the Application.
+   */
+  protected _onClickTab(event: PointerEvent): void;
+
   /**
    * A generic event handler for action clicks which can be extended by subclasses.
    * Action handlers defined in DEFAULT_OPTIONS are called first. This method is only called for actions which have
@@ -696,6 +857,12 @@ declare class ApplicationV2<
    */
   protected _awaitTransition(element: HTMLElement, timeout: number): Promise<void>;
 
+  /**
+   * Wait for any images in the given element to load.
+   * @param element - The element.
+   */
+  static waitForImages(element: HTMLElement): Promise<void>;
+
   /**
    * @deprecated since v12, will be removed in v14
    * @remarks `"ApplicationV2#bringToTop is not a valid function and redirects to ApplicationV2#bringToFront. This shim will be removed in v14."`
@@ -703,4 +870,8 @@ declare class ApplicationV2<
   bringToTop(): void;
 }
 
+declare abstract class AnyApplicationV2 extends ApplicationV2<any, any, any> {
+  constructor(arg0: never, ...args: never[]);
+}
+
 export default ApplicationV2;