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

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

@@ -2,12 +2,14 @@ import type {
   MustConform,
   AnyObject,
   DeepPartial,
-  EmptyObject,
   InexactPartial,
   MaybePromise,
+  ValueOf,
+  AnyArray,
   Identity,
 } from "fvtt-types/utils";
-import type EventEmitterMixin from "../../../common/utils/event-emitter.d.mts";
+import type EventEmitterMixin from "#common/utils/event-emitter.d.mts";
+import type ContextMenu from "../ux/context-menu.d.mts";
 
 // TODO: Investigate use of DeepPartial vs Partial vs InexactPartial
 
@@ -56,6 +58,53 @@ 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
+     * @defaultValue `false`
+     */
+    hookResponse: boolean;
+
+    /**
+     * Call hooks for parent classes in the inheritance chain?
+     * @defaultValue `true`
+     */
+    parentClassHooks: boolean;
+  }
+
+  type RenderState = ValueOf<typeof ApplicationV2.RENDER_STATES>;
+
+  interface RenderContext {
+    /** Tab data prepared from an entry in {@link ApplicationV2.TABS} */
+    tabs?: Record<string, Tab>;
+  }
+
   interface Configuration {
     /**
      * An HTML element identifier used for this Application instance
@@ -110,10 +159,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 */
@@ -186,7 +241,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.
@@ -239,8 +294,13 @@ declare namespace ApplicationV2 {
 
     /** Whether the application was closed via keypress. */
     closeKey: boolean;
+
+    /** Is the application being closed because a form was submitted? */
+    submitted: boolean;
   }
 
+  type ActionTarget = HTMLElement & { dataset: { action: string } };
+
   /** An on-click action supported by the Application. Run in the context of a HandlebarsApplication. */
   type ClickAction = (
     /** The originating click event */
@@ -262,14 +322,41 @@ 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;
+  }
+
+  interface Window {
+    header?: HTMLElement | undefined;
+    resize?: HTMLElement | undefined;
+    title: HTMLHeadingElement | undefined;
+    icon: HTMLElement | undefined;
+    close: HTMLButtonElement | undefined;
+    controls: HTMLButtonElement | undefined;
+    controlsDropdown: HTMLDivElement | undefined;
+    onDrag: (event: PointerEvent) => void;
+    onResize: (event: PointerEvent) => void;
+    pointerStartPosition: ApplicationV2.Position | undefined;
+    pointerMoveThrottle: boolean;
+  }
+
   /** @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` */
@@ -303,6 +390,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,6 +424,20 @@ declare namespace ApplicationV2 {
        */
       updatePosition: boolean;
     }> {}
+
+  type CreateContextMenuHandler = () => ContextMenu.Entry<HTMLElement>[];
+
+  interface CreateContextMenuOptions extends ContextMenu.ConstructorOptions<false> {
+    container?: HTMLElement | undefined | null;
+
+    hookName?: string | undefined | null;
+
+    /**
+     * @defaultValue `true`
+     */
+    // non-null due to default value
+    parentClassHooks?: boolean | undefined;
+  }
 }
 
 /**
@@ -332,24 +446,48 @@ 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) {
+> extends EventEmitterMixin() {
   static [__ApplicationV2Brand]: never;
 
   [__RenderContext]: RenderContext;
   [__Configuration]: Configuration;
   [__RenderOptions]: RenderOptions;
 
+  /**
+   * 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;
 
-  // Note(LukeAbby): This `& object` is so that the `DEFAULT_OPTIONS` can be overridden more easily
-  // Without it then `static override DEFAULT_OPTIONS = { unrelatedProp: 123 }` would error.
+  /**
+   * 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;
@@ -359,7 +497,17 @@ declare class ApplicationV2<
     RENDERED: 2;
   };
 
-  static override readonly emittedEvents: ["render", "close", "position"];
+  /**
+   * An incrementing integer Application ID.
+   */
+  static _appId: number;
+
+  /**
+   * The current maximum z-index of any displayed Application.
+   */
+  static _maxZ: number;
+
+  static override readonly emittedEvents: string[];
 
   /**
    * Application instance configuration options.
@@ -369,26 +517,14 @@ declare class ApplicationV2<
   /**
    * Convenience references to window header elements.
    */
-  get window(): {
-    header?: HTMLElement | undefined;
-    resize?: HTMLElement | undefined;
-    title: HTMLHeadingElement | undefined;
-    icon: HTMLElement | undefined;
-    close: HTMLButtonElement | undefined;
-    controls: HTMLButtonElement | undefined;
-    controlsDropdown: HTMLDivElement | undefined;
-    onDrag: (event: PointerEvent) => void;
-    onResize: (event: PointerEvent) => void;
-    pointerStartPosition: ApplicationV2.Position | undefined;
-    pointerMoveThrottle: boolean;
-  };
+  get window(): ApplicationV2.Window;
 
   /**
    * 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
@@ -397,6 +533,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;
 
@@ -410,6 +549,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?
    */
@@ -428,7 +572,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?
@@ -455,17 +599,21 @@ declare class ApplicationV2<
   /**
    * 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 - 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
    */
+  // not: null
   render(options?: DeepPartial<RenderOptions>): Promise<this>;
 
   /**
-   * @deprecated Exists for backwards compatability with the original `ApplicationV1#render` signature.
+   * @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>;
 
   /**
@@ -481,6 +629,18 @@ declare class ApplicationV2<
    */
   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
    */
@@ -533,14 +693,14 @@ declare class ApplicationV2<
    * @param element - The element to insert
    * @returns The inserted element
    */
-  // TODO: Actual function def appears to be void?
-  protected _insertElement(element: HTMLElement): HTMLElement;
+  protected _insertElement(element: HTMLElement): void;
 
   /**
    * Close the Application, removing it from the DOM.
    * @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>;
 
   /**
@@ -550,11 +710,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.
@@ -568,9 +733,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): Promise<void>;
 
   /**
    * Minimize the Application, collapsing it to a minimal header.
@@ -594,11 +763,36 @@ 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;
 
+  /**
+   * Programmatically submit an ApplicationV2 instance which implements a single top-level form.
+   * @param submitOptions - Arbitrary options which are supported by and provided to the configured form submission handler.
+   * @returns A promise that resolves to the returned result of the form submission handler, if any.
+   * @remarks Return is accurate to 13.340, but https://github.com/foundryvtt/foundryvtt/issues/12661 classifies it as a bug.
+   * Correct return is based on the handler.
+   * @privateRemarks TODO: More precisely type the submitOptions, as they vary with the handler
+   * which means on DocumentSheet they can be the document's create or update operations
+   */
+  submit(submitOptions?: AnyObject): Promise<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
@@ -616,11 +810,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.
@@ -632,11 +825,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.
@@ -670,6 +862,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
@@ -677,7 +874,7 @@ declare class ApplicationV2<
    * @param event  - The originating click event
    * @param target - The capturing HTML element which defined a [data-action]
    */
-  protected _onClickAction(event: PointerEvent, target: HTMLElement & { dataset: { action: string } }): void;
+  protected _onClickAction(event: PointerEvent, target: ApplicationV2.ActionTarget): void;
 
   /**
    * Handle submission for an Application which uses the form element.
@@ -691,7 +888,7 @@ declare class ApplicationV2<
    * @param formConfig - The form configuration for which this handler is bound
    * @param event      - The form submission event
    */
-  _onChangeForm(formConfig: ApplicationV2.FormConfiguration, event: Event): void;
+  protected _onChangeForm(formConfig: ApplicationV2.FormConfiguration, event: Event): void;
 
   /**
    * Parse a CSS style rule into a number of pixels which apply to that dimension.
@@ -699,7 +896,7 @@ declare class ApplicationV2<
    * @param parentDimension - The relevant dimension of the parent element
    * @returns The parsed style dimension in pixels
    */
-  static parseCSSDimensions(style: string, parentDimension: number): number;
+  static parseCSSDimensions(style: string, parentDimension: number): number | undefined;
 
   /**
    * Wait for a CSS transition to complete for an element.
@@ -709,6 +906,25 @@ declare class ApplicationV2<
    */
   protected _awaitTransition(element: HTMLElement, timeout: number): Promise<void>;
 
+  /**
+   * Create a ContextMenu instance used in this Application.
+   * @param handler   - A handler function that provides initial context options
+   * @param selector  - A CSS selector to which the ContextMenu will be bound
+   * @param options   - Additional options which affect ContextMenu construction
+   * @returns A created ContextMenu or null if no menu items were defined
+   */
+  protected _createContextMenu(
+    handler: ApplicationV2.CreateContextMenuHandler,
+    selector: string,
+    options: ApplicationV2.CreateContextMenuOptions,
+  ): ContextMenu | null;
+
+  /**
+   * 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."`

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

@@ -0,0 +1,40 @@
+import type ApplicationV2 from "./application.d.mts";
+import type HandlebarsApplicationMixin from "./handlebars-application.d.mts";
+
+/**
+ * An abstract class responsible for displaying a 2-pane Application that allows for entries to be grouped and filtered
+ * by category.
+ * @remarks TODO: Stub
+ * @remarks This is not actually *imported* anywhere it can be used, it appears to be for internal FVTT use only.
+ */
+declare class CategoryBrowser<
+  RenderContext extends CategoryBrowser.RenderContext = CategoryBrowser.RenderContext,
+  Configuration extends CategoryBrowser.Configuration = CategoryBrowser.Configuration,
+  RenderOptions extends
+    HandlebarsApplicationMixin.ApplicationV2RenderOptions = HandlebarsApplicationMixin.ApplicationV2RenderOptions,
+> extends HandlebarsApplicationMixin(ApplicationV2)<RenderContext, Configuration, RenderOptions> {}
+
+declare namespace CategoryBrowser {
+  interface Configuration extends ApplicationV2.Configuration {
+    /** The initial category tab: omitting this will result in an initial active tab that corresponds with the first category by insertion order. */
+    initialCategory: string | null;
+
+    /** Additional Template partials for specific use with this class */
+    subtemplates: Subtemplates;
+  }
+
+  interface Subtemplates {
+    /** The markup used for each category: required to be set by any subclass */
+    category: string;
+
+    /** Optional template for secondary filtering (aside from text search) */
+    filter: string | null;
+
+    /** Optional sidebar footer content */
+    sidebarFooter: string | null;
+  }
+
+  interface RenderContext extends ApplicationV2.RenderContext {}
+}
+
+export default CategoryBrowser;