@league-of-foundry-developers/foundry-vtt-types 9.268.0 → 9.269.0

package/src/foundry/client/apps/form.d.ts

@@ -0,0 +1,384 @@
+import { ToObjectFalseType } from '../../../types/helperTypes';
+
+declare global {
+  interface FormApplicationOptions extends ApplicationOptions {
+    /**
+     * Whether to automatically close the application when it's contained
+     * form is submitted.
+     * @defaultValue `true`
+     */
+    closeOnSubmit: boolean;
+
+    /**
+     * Whether to automatically submit the contained HTML form when an input
+     * or select element is changed.
+     * @defaultValue `false`
+     */
+    submitOnChange: boolean;
+
+    /**
+     * Whether to automatically submit the contained HTML form when the
+     * application window is manually closed.
+     * @defaultValue `false`
+     */
+    submitOnClose: boolean;
+
+    /**
+     * Whether the application form is editable - if true, it's fields will
+     * be unlocked and the form can be submitted. If false, all form fields
+     * will be disabled and the form cannot be submitted.
+     * @defaultValue `true`
+     */
+    editable: boolean;
+
+    /**
+     * Support configuration of the sheet type used for this application.
+     * @defaultValue `false`
+     */
+    sheetConfig: boolean;
+  }
+
+  /**
+   * An abstract pattern for defining an Application responsible for updating some object using an HTML form
+   *
+   * A few critical assumptions:
+   * 1) This application is used to only edit one object at a time
+   * 2) The template used contains one (and only one) HTML form as it's outer-most element
+   * 3) This abstract layer has no knowledge of what is being updated, so the implementation must define _updateObject
+   *
+   * @typeParam Options        - the type of the options object
+   * @typeParam Data           - The data structure used to render the handlebars template.
+   * @typeParam ConcreteObject - the type of the object or {@link foundry.abstract.Document} which is modified by this form
+   */
+  abstract class FormApplication<
+    Options extends FormApplicationOptions = FormApplicationOptions,
+    Data extends object = FormApplication.Data<{}, Options>,
+    ConcreteObject = Data extends FormApplication.Data<infer T, Options> ? T : {}
+  > extends Application<Options> {
+    /**
+     * @param object  - Some object or entity which is the target to be updated.
+     * @param options - Additional options which modify the rendering of the sheet.
+     *                  (default: `{}`)
+     * @remarks Foundry allows passing no value to the constructor at all.
+     */
+    constructor(object: ConcreteObject, options?: Partial<Options>);
+    constructor(
+      ...args: ConcreteObject extends undefined
+        ? [ConcreteObject?, Partial<Options>?]
+        : [ConcreteObject, Partial<Options>?]
+    );
+
+    /**
+     * The object target which we are using this form to modify
+     */
+    object: ConcreteObject;
+
+    /**
+     * A convenience reference to the form HTLMElement
+     * @defaultValue `null`
+     */
+    form: HTMLElement | null;
+
+    /**
+     * Keep track of any FilePicker instances which are associated with this form
+     * The values of this Array are inner-objects with references to the FilePicker instances and other metadata
+     * @defaultValue `[]`
+     */
+    filepickers: FilePicker[];
+
+    /**
+     * Keep track of any mce editors which may be active as part of this form
+     * The values of this Array are inner-objects with references to the MCE editor and other metadata
+     * @defaultValue `{}`
+     */
+    editors: Record<string, FormApplication.FormApplicationEditor>;
+
+    /**
+     * Assign the default options which are supported by the entity edit sheet.
+     * @returns The default options for this FormApplication class
+     * @see {@link Application.defaultOptions}
+     * @defaultValue
+     * ```typescript
+     * foundry.utils.mergeObject(super.defaultOptions, {
+     *   classes: ["form"],
+     *   closeOnSubmit: true,
+     *   editable: true,
+     *   sheetConfig: false,
+     *   submitOnChange: false,
+     *   submitOnClose: false
+     * });
+     * ```
+     */
+    static override get defaultOptions(): FormApplicationOptions;
+
+    /**
+     * Is the Form Application currently editable?
+     */
+    get isEditable(): boolean;
+
+    /**
+     * @param options - (default: `{}`)
+     */
+    override getData(options?: Partial<Options>): Data | Promise<Data>;
+
+    protected override _render(force?: boolean, options?: Application.RenderOptions<Options>): Promise<void>;
+
+    protected override _renderInner(data: Data): Promise<JQuery>;
+
+    protected override _activateCoreListeners(html: JQuery): void;
+
+    override activateListeners(html: JQuery): void;
+
+    /**
+     * If the form is not editable, disable its input fields
+     * @param form - The form HTML
+     */
+    protected _disableFields(form: HTMLElement): void;
+
+    /**
+     * Handle standard form submission steps
+     * @param event         - The submit event which triggered this handler
+     * @param updateData    - Additional specific data keys/values which override or extend the contents of
+     *                        the parsed form. This can be used to update other flags or data fields at the
+     *                        same time as processing a form submission to avoid multiple database operations.
+     *                        (default: `null`)
+     * @param preventClose  - Override the standard behavior of whether to close the form on submit
+     *                        (default: `false`)
+     * @param preventRender - Prevent the application from re-rendering as a result of form submission
+     *                        (default: `false`)
+     * @returns A promise which resolves to the validated update data
+     */
+    protected _onSubmit(
+      event: Event,
+      { updateData, preventClose, preventRender }?: FormApplication.OnSubmitOptions
+    ): Promise<Partial<Record<string, unknown>>>;
+
+    /**
+     * Get an object of update data used to update the form's target object
+     * @param updateData - Additional data that should be merged with the form data
+     *                     (default: `{}`)
+     * @returns The prepared update data
+     */
+    // TODO: Maybe we can calculate how the flattened `updateData` looks like, then it would be Partial<Record<string, unknown>> & Flattened<T>
+    protected _getSubmitData(updateData?: object | null): Record<string, unknown>;
+
+    /**
+     * Handle changes to an input element, submitting the form if options.submitOnChange is true.
+     * Do not preventDefault in this handler as other interactions on the form may also be occurring.
+     * @param event - The initial change event
+     */
+    protected _onChangeInput(event: JQuery.ChangeEvent): void;
+
+    /**
+     * Handle the change of a color picker input which enters it's chosen value into a related input field
+     */
+    protected _onChangeColorPicker(event: JQuery.ChangeEvent): void;
+
+    /**
+     * Handle changes to a range type input by propagating those changes to the sibling range-value element
+     * @param event - The initial change event
+     */
+    protected _onChangeRange(event: JQuery.ChangeEvent): void;
+
+    /**
+     * Additional handling which should trigger when a FilePicker contained within this FormApplication is submitted.
+     * @param selection  - The target path which was selected
+     * @param filePicker - The FilePicker instance which was submitted
+     */
+    protected _onSelectFile(selection: string, filePicker: FilePicker): void;
+
+    /**
+     * This method is called upon form submission after form data is validated
+     * @param event    - The initial triggering submission event
+     * @param formData - The object of validated form data with which to update the object
+     * @returns A Promise which resolves once the update operation has completed
+     */
+    protected abstract _updateObject(event: Event, formData?: object): Promise<unknown>;
+
+    /**
+     * Activate a named TinyMCE text editor
+     * @param name           - The named data field which the editor modifies.
+     * @param options        - TinyMCE initialization options passed to TextEditor.create
+     *                         (default: `{}`)
+     * @param initialContent - Initial text content for the editor area.
+     *                         (default: `""`)
+     */
+    activateEditor(name: string, options?: TextEditor.Options, initialContent?: string): void;
+
+    /**
+     * Handle saving the content of a specific editor by name
+     * @param name   - The named editor to save
+     * @param remove - Remove the editor after saving its content
+     *                 (default: `true`)
+     */
+    saveEditor(name: string, { remove }?: { remove?: boolean }): Promise<void>;
+
+    /**
+     * Activate a TinyMCE editor instance present within the form
+     */
+    protected _activateEditor(div: HTMLElement): void;
+
+    /**
+     * Activate a FilePicker instance present within the form
+     * @param event - The mouse click event on a file picker activation button
+     */
+    protected _activateFilePicker(event: PointerEvent): void;
+
+    /**
+     * Determine the configuration options used to initialize a FilePicker instance within this FormApplication.
+     * Subclasses can extend this method to customize the behavior of pickers within their form.
+     * @param event - The initiating mouse click event which opens the picker
+     * @returns Options passed to the FilePicker constructor
+     */
+    protected _getFilePickerOptions(event: PointerEvent): FilePickerOptions;
+
+    /**
+     * @param options - (default: `{}`)
+     */
+    override close(options?: FormApplication.CloseOptions): Promise<void>;
+
+    /**
+     * Submit the contents of a Form Application, processing its content as defined by the Application
+     * @param options - Options passed to the _onSubmit event handler
+     *                  (default: `{}`)
+     * @returns Return a self-reference for convenient method chaining
+     */
+    submit(options?: FormApplication.OnSubmitOptions): Promise<this> | void;
+  }
+
+  namespace FormApplication {
+    interface CloseOptions extends Application.CloseOptions {
+      submit?: boolean;
+    }
+
+    /**
+     * @typeParam ConcreteObject - the type of the object
+     * @typeParam Options        - the type of the options object
+     */
+    interface Data<ConcreteObject, Options extends FormApplicationOptions = FormApplicationOptions> {
+      object: ConcreteObject;
+      options: Options;
+      title: string;
+    }
+
+    interface FormApplicationEditor {
+      target: string;
+      button: HTMLElement;
+      hasButton: boolean;
+      mce: tinyMCE.Editor | null;
+      active: boolean;
+      changed: boolean;
+      options: TextEditor.Options;
+      initial: string;
+    }
+
+    interface OnSubmitOptions {
+      /**
+       * Additional specific data keys/values which override or extend the contents of
+       * the parsed form. This can be used to update other flags or data fields at the
+       * same time as processing a form submission to avoid multiple database operations.
+       * @defaultValue `null`
+       */
+      updateData?: object;
+
+      /**
+       * Override the standard behavior of whether to close the form on submit
+       * @defaultValue `false`
+       */
+      preventClose?: boolean;
+
+      /**
+       * Prevent the application from re-rendering as a result of form submission
+       * @defaultValue `false`
+       */
+      preventRender?: boolean;
+    }
+  }
+
+  interface DocumentSheetOptions extends FormApplicationOptions {
+    /**
+     * The default permissions required to view this Document sheet.
+     * @defaultValue {@link CONST.DOCUMENT_PERMISSION_LEVELS.LIMITED}
+     */
+    viewPermission: foundry.CONST.DOCUMENT_PERMISSION_LEVELS;
+  }
+
+  /**
+   * Extend the FormApplication pattern to incorporate specific logic for viewing or editing Document instances.
+   * See the FormApplication documentation for more complete description of this interface.
+   * @param object  - A Document instance which should be managed by this form.
+   * @param options - Optional configuration parameters for how the form behaves.
+   *                  (default: `{}`)
+   *
+   * @typeParam Options          - the type of the options object
+   * @typeParam Data             - The data structure used to render the handlebars template.
+   * @typeParam ConcreteDocument - the type of the Document which should be managed by this form sheet
+   */
+  abstract class DocumentSheet<
+    Options extends DocumentSheetOptions = DocumentSheetOptions,
+    Data extends object = DocumentSheet.Data,
+    ConcreteDocument extends foundry.abstract.Document<any, any> = Data extends DocumentSheet.Data<infer T>
+      ? T
+      : foundry.abstract.Document<any, any>
+  > extends FormApplication<Options, Data, ConcreteDocument> {
+    /**
+     * @defaultValue
+     * ```typescript
+     * foundry.utils.mergeObject(super.defaultOptions, {
+     *   classes: ["sheet"],
+     *   template: `templates/sheets/${this.name.toLowerCase()}.html`,
+     *   viewPermission: CONST.DOCUMENT_PERMISSION_LEVELS.LIMITED,
+     *   sheetConfig: true
+     * });
+     * ```
+     */
+    static get defaultOptions(): DocumentSheetOptions;
+
+    /**
+     * A semantic convenience reference to the Document instance which is the target object for this form.
+     */
+    get document(): ConcreteDocument;
+
+    override get id(): string;
+
+    override get isEditable(): boolean;
+
+    override get title(): string;
+
+    override close(options?: FormApplication.CloseOptions): Promise<void>;
+
+    override getData(options?: Partial<Options>): Data | Promise<Data>;
+
+    override render(force?: boolean, options?: Application.RenderOptions<Options>): this;
+
+    protected override _getHeaderButtons(): Application.HeaderButton[];
+
+    /**
+     * Handle requests to configure the default sheet used by this Document
+     * @internal
+     */
+    protected _onConfigureSheet(event: JQuery.ClickEvent): void;
+
+    protected override _updateObject(event: Event, formData: object): Promise<unknown>;
+  }
+
+  namespace DocumentSheet {
+    /**
+     * @typeParam ConcreteDocument - the type of the {@link foundry.abstract.Document} which should be managed by this form sheet
+     * @typeParam Options          - the type of the options object
+     */
+    interface Data<
+      ConcreteDocument extends foundry.abstract.Document<any, any> = foundry.abstract.Document<any, any>,
+      Options extends DocumentSheetOptions = DocumentSheetOptions
+    > {
+      cssClass: string;
+      editable: boolean;
+      document: ConcreteDocument;
+      data: ToObjectFalseType<ConcreteDocument>;
+      limited: boolean;
+      options: Options;
+      owner: boolean;
+      title: string;
+    }
+  }
+}

package/src/foundry/{foundry.js/applications/formApplications/documentSheets/actorSheet.d.ts → client/apps/forms/actor.d.ts}

@@ -1,5 +1,5 @@
-import { ConfiguredDocumentClass, ToObjectFalseType } from '../../../../../types/helperTypes';
-import { DropData as ClientDocumentMixinDropData } from '../../../clientDocumentMixin';
+import { ConfiguredDocumentClass, ToObjectFalseType } from '../../../../types/helperTypes';
+import { DropData as ClientDocumentMixinDropData } from '../../data/abstract/client-document';
 
 declare global {
   /**
@@ -34,11 +34,9 @@ declare global {
      */
     static get defaultOptions(): ActorSheet.Options;
 
-    /** @override */
-    get id(): string;
+    override get id(): string;
 
-    /** @override */
-    get title(): string;
+    override get title(): string;
 
     /**
      * A convenience reference to the Actor document
@@ -50,22 +48,15 @@ declare global {
      */
     get token(): Exclude<this['object']['token'] | this['options']['token'], undefined> | null;
 
-    /** @override */
-    close(options?: FormApplication.CloseOptions): Promise<void>;
+    override close(options?: FormApplication.CloseOptions): Promise<void>;
 
-    /**
-     * @override
-     */
-    getData(options?: Partial<Options>): Data | Promise<Data>;
+    override getData(options?: Partial<Options>): Data | Promise<Data>;
 
-    /** @override */
-    protected _getHeaderButtons(): Application.HeaderButton[];
+    protected override _getHeaderButtons(): Application.HeaderButton[];
 
-    /** @override */
-    protected _getSubmitData(updateData?: object | null): Partial<Record<string, unknown>>;
+    protected override _getSubmitData(updateData?: object | null): Partial<Record<string, unknown>>;
 
-    /** @override */
-    activateListeners(html: JQuery): void;
+    override activateListeners(html: JQuery): void;
 
     /**
      * Handle requests to configure the Token for the Actor
@@ -77,20 +68,13 @@ declare global {
      */
     protected _onEditImage(event: JQuery.ClickEvent): ReturnType<FilePicker['browse']>;
 
-    /** @override */
-    protected _canDragStart(selector: string): boolean;
+    protected override _canDragStart(selector: string): boolean;
 
-    /** @override */
-    protected _canDragDrop(selector: string): boolean;
+    protected override _canDragDrop(selector: string): boolean;
 
-    /** @override */
-    protected _onDragStart(event: DragEvent): void;
+    protected override _onDragStart(event: DragEvent): void;
 
-    /**
-     * @override
-     * @internal
-     */
-    protected _onDrop(event: DragEvent): void;
+    protected override _onDrop(event: DragEvent): void;
 
     /**
      * Handle the dropping of ActiveEffect data onto an Actor Sheet

package/src/foundry/{foundry.js/applications/formApplications/documentSheets/cardConfig.d.ts → client/apps/forms/card-config.d.ts}

@@ -1,5 +1,5 @@
-import type { ConfiguredDocumentClassForName, ConstructorDataType } from '../../../../../types/helperTypes.js';
-import type { CardFaceData } from '../../../../common/data/module.mjs.js';
+import type { ConfiguredDocumentClassForName, ConstructorDataType } from '../../../../types/helperTypes.js';
+import type { CardFaceData } from '../../../common/data/module.mjs.js';
 
 declare global {
   /**

package/src/foundry/{foundry.js/applications/formApplications/documentSheets/cardsConfig.d.ts → client/apps/forms/cards-config.d.ts}

@@ -1,4 +1,4 @@
-import type { ConfiguredDocumentClassForName } from '../../../../../types/helperTypes.js';
+import type { ConfiguredDocumentClassForName } from '../../../../types/helperTypes.js';
 
 declare global {
   /**
@@ -55,12 +55,10 @@ declare global {
      */
     protected _onLazyLoadImage(entries: IntersectionObserverEntry[], observer: IntersectionObserver): void;
 
-    /** @param selector - (unused) */
     protected override _canDragStart(selector: string): boolean;
 
     protected override _onDragStart(event: DragEvent): void;
 
-    /** @param selector - (unused) */
     protected override _canDragDrop(selector: string): boolean;
 
     protected override _onDrop(event: DragEvent): void;
@@ -77,6 +75,48 @@ declare global {
     ): ReturnType<InstanceType<ConfiguredDocumentClassForName<'Cards'>>['updateEmbeddedDocuments']>;
   }
 
+  /**
+   * A subclass of CardsConfig which provides a sheet representation for Cards documents with the "hand" type.
+   *
+   * @typeParam Options - The type of the options object
+   * @typeParam Data    - The data structure used to render the handlebars template.
+   */
+  class CardsHand<
+    Options extends DocumentSheetOptions = DocumentSheetOptions,
+    Data extends CardsConfig.Data<Options> = CardsConfig.Data<Options>
+  > extends CardsConfig<Options, Data> {
+    /**
+     * @defaultValue
+     * ```typescript
+     * foundry.utils.mergeObject(super.defaultOptions, {
+     *   template: "templates/cards/cards-hand.html"
+     * })
+     * ```
+     */
+    static override get defaultOptions(): DocumentSheetOptions;
+  }
+
+  /**
+   * A subclass of CardsConfig which provides a sheet representation for Cards documents with the "pile" type.
+   *
+   * @typeParam Options - The type of the options object
+   * @typeParam Data    - The data structure used to render the handlebars template.
+   */
+  class CardsPile<
+    Options extends DocumentSheetOptions = DocumentSheetOptions,
+    Data extends CardsConfig.Data<Options> = CardsConfig.Data<Options>
+  > extends CardsConfig<Options, Data> {
+    /**
+     * @defaultValue
+     * ```typescript
+     * foundry.utils.mergeObject(super.defaultOptions, {
+     *   template: "templates/cards/cards-pile.html"
+     * })
+     * ```
+     */
+    static override get defaultOptions(): DocumentSheetOptions;
+  }
+
   namespace CardsConfig {
     interface Data<Options extends DocumentSheetOptions>
       extends DocumentSheet.Data<InstanceType<ConfiguredDocumentClassForName<'Cards'>>, Options> {

package/src/foundry/client/apps/forms/combat-config.d.ts

@@ -0,0 +1,41 @@
+export {};
+
+declare global {
+  /**
+   * The Application responsible for configuring the CombatTracker and its contents.
+   * @typeParam Options - The type of the options object
+   * @typeParam Data    - The data structure used to render the handlebars template.
+   */
+  class CombatTrackerConfig<
+    Options extends FormApplicationOptions = FormApplicationOptions,
+    Data extends object = CombatTrackerConfig.Data
+  > extends FormApplication<Options, Data, undefined> {
+    /**
+     * @defaultValue
+     * ```typescript
+     * foundry.utils.mergeObject(super.defaultOptions, {
+     *   id: "combat-config",
+     *   title: game.i18n.localize("COMBAT.Settings"),
+     *   classes: ["sheet", "combat-sheet"],
+     *   template: "templates/sheets/combat-config.html",
+     *   width: 420,
+     * })
+     * ```
+     */
+    static override get defaultOptions(): FormApplicationOptions;
+
+    override getData(options?: Partial<Options>): Data | Promise<Data>;
+
+    protected override _updateObject(
+      event: Event,
+      formData: ClientSettings.Values['core.combatTrackerConfig']
+    ): Promise<unknown>;
+  }
+
+  namespace CombatTrackerConfig {
+    interface Data {
+      settings: ClientSettings.Values['core.combatTrackerConfig'];
+      attributeChoices: Record<string, string[]>;
+    }
+  }
+}

package/src/foundry/{foundry.js/applications/formApplications/documentSheets/combatantConfig.d.ts → client/apps/forms/combatant-config.d.ts}

@@ -1,4 +1,4 @@
-import { ConfiguredDocumentClass } from '../../../../../types/helperTypes';
+import { ConfiguredDocumentClass } from '../../../../types/helperTypes';
 
 declare global {
   /**
@@ -12,7 +12,6 @@ declare global {
     Data extends CombatantConfig.Data<Options> = CombatantConfig.Data<Options>
   > extends DocumentSheet<Options, Data, InstanceType<ConfiguredDocumentClass<typeof Combatant>>> {
     /**
-     * @override
      * @defaultValue
      * ```typescript
      * foundry.utils.mergeObject(super.defaultOptions, {
@@ -24,16 +23,11 @@ declare global {
      * });
      * ```
      */
-    static get defaultOptions(): CombatantConfig.Options;
+    static override get defaultOptions(): CombatantConfig.Options;
 
-    /** @override */
-    get title(): string;
+    override get title(): string;
 
-    /**
-     * @param event - (unused)
-     * @override
-     */
-    protected _updateObject(event: Event, formData: CombatantConfig.FormData): Promise<unknown>;
+    protected override _updateObject(event: Event, formData: CombatantConfig.FormData): Promise<unknown>;
   }
 
   namespace CombatantConfig {

package/src/foundry/{foundry.js/applications/formApplications/documentSheets/activeEffectConfig.d.ts → client/apps/forms/effect-config.d.ts}

@@ -1,4 +1,4 @@
-import { ConfiguredDocumentClass } from '../../../../../types/helperTypes';
+import { ConfiguredDocumentClass } from '../../../../types/helperTypes';
 
 declare global {
   /**
@@ -12,7 +12,6 @@ declare global {
     Data extends object = ActiveEffectConfig.Data
   > extends DocumentSheet<Options, Data, InstanceType<ConfiguredDocumentClass<typeof ActiveEffect>>> {
     /**
-     * @override
      * @defaultValue
      * ```typescript
      * foundry.utils.mergeObject(super.defaultOptions, {
@@ -24,21 +23,13 @@ declare global {
      * });
      * ```
      */
-    static get defaultOptions(): ActiveEffectConfig.Options;
+    static override get defaultOptions(): ActiveEffectConfig.Options;
 
-    /** @override */
-    get title(): string;
+    override get title(): string;
 
-    /**
-     * @override
-     *
-     * @remarks The implementation doesn't return a `Promise` but the return type includes it to allow extending
-     * classes to do that.
-     */
-    getData(options?: Partial<Options>): Data | Promise<Data>;
+    override getData(options?: Partial<Options>): Data | Promise<Data>;
 
-    /** @override */
-    activateListeners(html: JQuery): void;
+    override activateListeners(html: JQuery): void;
 
     /**
      * Provide centralized handling of mouse clicks on control buttons.
@@ -53,10 +44,9 @@ declare global {
     protected _addEffectChange(): Promise<this>;
 
     /**
-     * @override
      * @param updateData - (default: `{}`)
      */
-    _getSubmitData(updateData?: FormApplication.OnSubmitOptions['updateData']): Record<string, unknown>;
+    override _getSubmitData(updateData?: FormApplication.OnSubmitOptions['updateData']): Record<string, unknown>;
     // TODO: Can we type this better?
   }