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

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

@@ -0,0 +1,268 @@
+import type { AnyFunction, DeepPartial, EmptyObject } from "../../../../types/utils.d.mts";
+import type ApplicationV2 from "./application.d.mts";
+
+/**
+ * A lightweight Application that renders a dialog containing a form with arbitrary content, and some buttons.
+ *
+ * @example Prompt the user to confirm an action.
+ * ```js
+ * const proceed = await foundry.applications.api.DialogV2.confirm({
+ *   content: "Are you sure?",
+ *   rejectClose: false,
+ *   modal: true
+ * });
+ * if ( proceed ) console.log("Proceed.");
+ * else console.log("Do not proceed.");
+ * ```
+ *
+ * @example Prompt the user for some input.
+ * ```js
+ * let guess;
+ * try {
+ *   guess = await foundry.applications.api.DialogV2.prompt({
+ *     window: { title: "Guess a number between 1 and 10" },
+ *     content: '<input name="guess" type="number" min="1" max="10" step="1" autofocus>',
+ *     ok: {
+ *       label: "Submit Guess",
+ *       callback: (event, button, dialog) => button.form.elements.guess.valueAsNumber
+ *     }
+ *   });
+ * } catch {
+ *   console.log("User did not make a guess.");
+ *   return;
+ * }
+ * const n = Math.ceil(CONFIG.Dice.randomUniform() * 10);
+ * if ( n === guess ) console.log("User guessed correctly.");
+ * else console.log("User guessed incorrectly.");
+ * ```
+ *
+ * @example A custom dialog.
+ * ```js
+ * new foundry.applications.api.DialogV2({
+ *   window: { title: "Choose an option" },
+ *   content: `
+ *     <label><input type="radio" name="choice" value="one" checked> Option 1</label>
+ *     <label><input type="radio" name="choice" value="two"> Option 2</label>
+ *     <label><input type="radio" name="choice" value="three"> Options 3</label>
+ *   `,
+ *   buttons: [{
+ *     action: "choice",
+ *     label: "Make Choice",
+ *     default: true,
+ *     callback: (event, button, dialog) => button.form.elements.choice.value
+ *   }, {
+ *     action: "all",
+ *     label: "Take All"
+ *   }],
+ *   submit: result => {
+ *     if ( result === "all" ) console.log("User picked all options.");
+ *     else console.log(`User picked option: ${result}`);
+ *   }
+ * }).render({ force: true });
+ * ```
+ */
+declare class DialogV2 extends ApplicationV2<EmptyObject, DialogV2.Configuration> {
+  static override DEFAULT_OPTIONS: DeepPartial<ApplicationV2.Configuration>;
+
+  protected override _initializeApplicationOptions(
+    options: DeepPartial<DialogV2.Configuration>,
+  ): DeepPartial<DialogV2.Configuration>;
+
+  protected override _renderHTML(_context: unknown, _options: ApplicationV2.RenderOptions): Promise<HTMLFormElement>;
+
+  /**
+   * Render configured buttons.
+   */
+  protected _renderButtons(): string;
+
+  /**
+   * Handle submitting the dialog.
+   * @param target - The button that was clicked or the default button.
+   * @param event - The triggering event.
+   */
+  protected _onSubmit(target: HTMLButtonElement, event: PointerEvent | SubmitEvent): Promise<DialogV2>;
+
+  protected override _onFirstRender(_context: EmptyObject, _options: DeepPartial<ApplicationV2.RenderOptions>): void;
+
+  protected override _replaceHTML(
+    result: HTMLFormElement,
+    content: HTMLElement,
+    _options: DeepPartial<ApplicationV2.RenderOptions>,
+  ): void;
+
+  /**
+   * Handle keypresses within the dialog.
+   * @param event - The triggering event.
+   */
+  protected _onKeyDown(event: KeyboardEvent): void;
+
+  /**
+   * @param event - The originating click event.
+   * @param target - The button element that was clicked.
+   */
+  protected static _onClickButton(this: DialogV2, event: PointerEvent, target: HTMLButtonElement): void;
+
+  /**
+   * A utility helper to generate a dialog with yes and no buttons.
+   * @returns Resolves to true if the yes button was pressed, or false if the no button
+   *          was pressed. If additional buttons were provided, the Promise resolves to
+   *          the identifier of the one that was pressed, or the value returned by its
+   *          callback. If the dialog was dismissed, and rejectClose is false, the
+   *          Promise resolves to null.
+   */
+  static confirm<Options extends Partial<DialogV2.WaitOptions>, YesReturn = true, NoReturn = false>(
+    options?: Options & {
+      /** Options to overwrite the default yes button configuration. */
+      yes?: DialogV2.Button<YesReturn>;
+      /** Options to overwrite the default no button configuration. */
+      no?: DialogV2.Button<NoReturn>;
+    },
+  ): Promise<YesReturn | NoReturn | InferButtonReturnTypes<Options> | InferDismissType<Options>>;
+
+  /**
+   * A utility helper to generate a dialog with a single confirmation button.
+   * @returns  - Resolves to the identifier of the button used to submit the dialog,
+   *             or the value returned by that button's callback. If the dialog was
+   *             dismissed, and rejectClose is false, the Promise resolves to null.
+   */
+  static prompt<Options extends Partial<DialogV2.WaitOptions>, OKReturn = string>(
+    options?: Options & {
+      /** Options to overwrite the default confirmation button configuration. */
+      ok?: Partial<DialogV2.Button<OKReturn>>;
+    },
+  ): Promise<OKReturn | InferButtonReturnTypes<Options> | InferDismissType<Options>>;
+
+  /**
+   * Spawn a dialog and wait for it to be dismissed or submitted.
+   * @returns Resolves to the identifier of the button used to submit the
+   *          dialog, or the value returned by that button's callback. If the
+   *          dialog was dismissed, and rejectClose is false, the Promise
+   *          resolves to null.
+   * @remarks Despite being the `wait` function this doesn't actually use that interface
+   */
+  static wait<Options extends Partial<DialogV2.Configuration>>(
+    options?: Options & {
+      /** A function to invoke whenever the dialog is rendered. */
+      render?: DialogV2.RenderCallback;
+      /** A function to invoke when the dialog is closed under any circumstances. */
+      close?: DialogV2.CloseCallback;
+      /**
+       * Throw a Promise rejection if the dialog is dismissed.
+       * @defaultValue `true`
+       */
+      rejectClose?: boolean;
+    },
+  ): Promise<InferButtonReturnTypes<Options> | InferDismissType<Options>>;
+}
+
+declare namespace DialogV2 {
+  export interface Button<CallBackReturn> {
+    /**
+     * The button action identifier.
+     */
+    action: string;
+
+    /**
+     * The button label. Will be localized.
+     */
+    label: string;
+
+    /**
+     * FontAwesome icon classes.
+     */
+    icon?: string;
+
+    /**
+     * CSS classes to apply to the button.
+     */
+    class?: string;
+
+    /**
+     * Whether this button represents the default action to take if the user
+     * submits the form without pressing a button, i.e. with an Enter
+     * keypress.
+     */
+    default?: boolean;
+
+    /**
+     * A function to invoke when the button is clicked. The value returned
+     * from this function will be used as the dialog's submitted value.
+     * Otherwise, the button's identifier is used.
+     */
+    callback?: ButtonCallback<CallBackReturn>;
+  }
+
+  export type ButtonCallback<T> = (
+    event: PointerEvent | SubmitEvent,
+    button: HTMLButtonElement,
+    dialog: HTMLDialogElement,
+  ) => Promise<T>;
+
+  export interface Configuration extends ApplicationV2.Configuration {
+    /**
+     * Modal dialogs prevent interaction with the rest of the UI until they
+     * are dismissed or submitted.
+     */
+    modal?: boolean;
+
+    /**
+     * Button configuration.
+     */
+    buttons: Button<any>[];
+
+    /**
+     * The dialog content.
+     */
+    content?: string;
+
+    /**
+     * A function to invoke when the dialog is submitted. This will not be
+     * called if the dialog is dismissed.
+     */
+    submit?: SubmitCallback;
+  }
+
+  // TODO(LukeAbby): I moved these types over from `_types.d.mts` mostly as-is. However this usage of `any` is suspicious and needs auditing.
+
+  export type RenderCallback = (event: Event, dialog: HTMLDialogElement) => any;
+
+  export type CloseCallback = (event: Event, dialog: DialogV2) => any;
+
+  export type SubmitCallback = (result: any) => Promise<void>;
+
+  export interface WaitOptions extends Configuration {
+    /**
+     * A synchronous function to invoke whenever the dialog is rendered.
+     */
+    render?: RenderCallback;
+
+    /**
+     * A synchronous function to invoke when the dialog is closed under any
+     * circumstances.
+     */
+    close?: CloseCallback;
+
+    /**
+     * Throw a Promise rejection if the dialog is dismissed.
+     * @defaultValue `true`
+     */
+    rejectClose?: boolean;
+  }
+}
+
+type InferDismissType<Options extends Partial<DialogV2.WaitOptions>> = Options["rejectClose"] extends boolean
+  ? Options["rejectClose"] extends true
+    ? never
+    : null
+  : never;
+
+type InferButtonReturnTypes<Options extends Partial<DialogV2.WaitOptions>> =
+  Options["buttons"] extends Array<infer Button>
+    ? Button extends DialogV2.Button<infer Callback>
+      ? Button["callback"] extends AnyFunction
+        ? Callback
+        : string
+      : never
+    : never;
+
+export default DialogV2;

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

@@ -0,0 +1,127 @@
+import type { AnyObject, DeepPartial, EmptyObject } from "../../../../types/utils.d.mts";
+import type ApplicationV2 from "./application.d.mts";
+
+declare namespace DocumentSheetV2 {
+  type Any = DocumentSheetV2<any, any, any, any>;
+
+  type AnyConstructor = typeof AnyDocumentSheetV2;
+
+  interface Configuration<Document extends foundry.abstract.Document.Any = foundry.abstract.Document.Any>
+    extends ApplicationV2.Configuration {
+    /**
+     * The Document instance associated with this sheet
+     */
+    document: Document;
+
+    /**
+     * A permission level in CONST.DOCUMENT_OWNERSHIP_LEVELS
+     */
+    viewPermission: typeof foundry.CONST.DOCUMENT_OWNERSHIP_LEVELS;
+
+    /**
+     * A permission level in CONST.DOCUMENT_OWNERSHIP_LEVELS
+     */
+    editPermission: typeof foundry.CONST.DOCUMENT_OWNERSHIP_LEVELS;
+
+    /**
+     * Allow sheet configuration as a header button
+     */
+    sheetConfig: boolean;
+  }
+
+  interface RenderOptions extends ApplicationV2.RenderOptions {
+    /** A string with the format "\{operation\}\{documentName\}" providing context */
+    renderContext: string;
+
+    /** Data describing the document modification that occurred */
+    renderData: object;
+  }
+}
+
+/**
+ * The Application class is responsible for rendering an HTMLElement into the Foundry Virtual Tabletop user interface.
+ */
+declare class DocumentSheetV2<
+  Document extends foundry.abstract.Document.Any,
+  RenderContext extends AnyObject = EmptyObject,
+  Configuration extends DocumentSheetV2.Configuration<Document> = DocumentSheetV2.Configuration<Document>,
+  RenderOptions extends DocumentSheetV2.RenderOptions = DocumentSheetV2.RenderOptions,
+> extends ApplicationV2<RenderContext, Configuration, RenderOptions> {
+  constructor(options: DeepPartial<Configuration> & { document: Document });
+
+  static DEFAULT_OPTIONS: DeepPartial<DocumentSheetV2.Configuration>;
+
+  get document(): Document;
+
+  override get title(): string;
+
+  /**
+   * Is this Document sheet visible to the current User?
+   * This is governed by the viewPermission threshold configured for the class.
+   */
+  get isVisible(): boolean;
+
+  /**
+   * Is this Document sheet editable by the current User?
+   * This is governed by the editPermission threshold configured for the class.
+   */
+  get isEditable(): boolean;
+
+  protected _initializeApplicationOptions(
+    options: DeepPartial<Configuration>,
+  ): DeepPartial<Configuration> & Record<string, unknown>;
+
+  protected override _headerControlsButtons(): Generator<ApplicationV2.HeaderControlsEntry>;
+
+  protected override _renderFrame(options: DeepPartial<RenderOptions>): Promise<HTMLElement>;
+
+  protected override _canRender(options: DeepPartial<RenderOptions>): false | void;
+
+  protected override _onFirstRender(context: DeepPartial<RenderContext>, options: DeepPartial<RenderOptions>): void;
+
+  protected override _onClose(options: DeepPartial<RenderOptions>): void;
+
+  /**
+   * Prepare data used to update the Item upon form submission.
+   * This data is cleaned and validated before being returned for further processing.
+   * @param event    - The originating form submission event
+   * @param form     - The form element that was submitted
+   * @param formData - Processed data for the submitted form
+   * @returns Prepared submission data as an object
+   * @throws Subclasses may throw validation errors here to prevent form submission
+   */
+  // TODO: Improve typing?
+  protected _prepareSubmitData(event: SubmitEvent, form: HTMLFormElement, formData: FormDataExtended): object;
+
+  /**
+   * Customize how form data is extracted into an expanded object.
+   * @param event    - The originating form submission event
+   * @param form     - The form element that was submitted
+   * @param formData - Processed data for the submitted form
+   * @returns An expanded object of processed form data
+   * @throws Subclasses may throw validation errors here to prevent form submission
+   */
+  _processFormData(event: SubmitEvent, form: HTMLFormElement, formData: FormDataExtended): object;
+
+  /**
+   * Submit a document update based on the processed form data.
+   * @param event    - The originating form submission event
+   * @param form     - The form element that was submitted
+   * @param formData - Processed and validated form data to be used for a document update
+   */
+  _processSubmitData(event: SubmitEvent, form: HTMLFormElement, formData: FormDataExtended): Promise<void>;
+
+  /**
+   * Programmatically submit a DocumentSheetV2 instance, providing additional data to be merged with form data.
+   */
+  submit(options?: {
+    /** Additional data merged with processed form data */
+    updateData: object;
+  }): Promise<void>;
+}
+
+export default DocumentSheetV2;
+
+declare abstract class AnyDocumentSheetV2 extends DocumentSheetV2<any, any, any, any> {
+  constructor(arg0: never, ...args: never[]);
+}

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

@@ -0,0 +1,180 @@
+import type { DeepPartial, Mixin } from "../../../../types/utils.d.mts";
+import type ApplicationV2 from "./application.d.mts";
+
+declare namespace HandlebarsApplication {
+  // Note(LukeAbby): `unknown` is returned in the false case instead of `never` because otherwise errors will crop up at usage sites like "any cannot be assigned to `never`".
+  type ConfigurationFor<Instance extends HandlebarsApplication> =
+    Instance extends ApplicationV2.Internal.Instance<infer Configuration, any, any> ? Configuration : unknown;
+
+  type RenderOptionsFor<Instance extends HandlebarsApplication> =
+    Instance extends ApplicationV2.Internal.Instance<any, infer RenderOptions, any> ? RenderOptions : unknown;
+
+  type RenderContextFor<Instance extends HandlebarsApplication> =
+    Instance extends ApplicationV2.Internal.Instance<any, any, infer RenderContext> ? RenderContext : unknown;
+}
+
+/**
+ * The mixed application class augmented with [Handlebars](https://handlebarsjs.com) template rendering behavior.
+ */
+declare class HandlebarsApplication {
+  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+  constructor(...args: any[]);
+
+  /**
+   * Configure a registry of template parts which are supported for this application for partial rendering.
+   * @defaultValue `{}`
+   */
+  static PARTS: Record<string, HandlebarsApplicationMixin.HandlebarsTemplatePart>;
+
+  /**
+   * A record of all rendered template parts.
+   * @defaultValue `{}`
+   */
+  get parts(): Record<string, HTMLElement>;
+
+  protected _configureRenderOptions(options: DeepPartial<HandlebarsApplicationMixin.HandlebarsRenderOptions>): void;
+
+  protected _preFirstRender(
+    context: DeepPartial<HandlebarsApplication.RenderContextFor<this>>,
+    options: DeepPartial<HandlebarsApplication.RenderOptionsFor<this>>,
+  ): Promise<void>;
+
+  /**
+   * Render each configured application part using Handlebars templates.
+   * @param context - Context data for the render operation
+   * @param options - Options which configure application rendering behavior
+   * @returns A single rendered HTMLElement for each requested part
+   */
+  protected _renderHTML(
+    context: HandlebarsApplication.RenderContextFor<this>,
+    options: DeepPartial<HandlebarsApplication.RenderOptionsFor<this>>,
+  ): Promise<Record<string, HTMLElement>>;
+
+  /**
+   * Prepare context that is specific to only a single rendered part.
+   *
+   * It is recommended to augment or mutate the shared context so that downstream methods like _onRender have
+   * visibility into the data that was used for rendering. It is acceptable to return a different context object
+   * rather than mutating the shared context at the expense of this transparency.
+   *
+   * @param partId  - The part being rendered
+   * @param context - Shared context provided by _prepareContext
+   * @param options - Options which configure application rendering behavior
+   * @returns Context data for a specific part
+   */
+  protected _preparePartContext(
+    partId: string,
+    context: HandlebarsApplication.RenderContextFor<this>,
+    options: DeepPartial<HandlebarsApplicationMixin.HandlebarsRenderOptions>,
+  ): Promise<HandlebarsApplication.RenderContextFor<this>>;
+
+  /**
+   * Replace the HTML of the application with the result provided by Handlebars rendering.
+   * @param result  - The result from Handlebars template rendering
+   * @param content - The content element into which the rendered result must be inserted
+   * @param options - Options which configure application rendering behavior
+   */
+  protected _replaceHTML(
+    result: Record<string, HTMLElement>,
+    content: HTMLElement,
+    options: DeepPartial<HandlebarsApplication.RenderOptionsFor<this>>,
+  ): void;
+
+  /**
+   * Prepare data used to synchronize the state of a template part.
+   * @param partId       - The id of the part being rendered
+   * @param newElement   - The new rendered HTML element for the part
+   * @param priorElement - The prior rendered HTML element for the part
+   * @param state        - A state object which is used to synchronize after replacement
+   */
+  protected _preSyncPartState(
+    partId: string,
+    newElement: HTMLElement,
+    priorElement: HTMLElement,
+    state: HandlebarsApplicationMixin.PartState,
+  ): void;
+
+  /**
+   * Synchronize the state of a template part after it has been rendered and replaced in the DOM.
+   * @param partId       - The id of the part being rendered
+   * @param newElement   - The new rendered HTML element for the part
+   * @param priorElement - The prior rendered HTML element for the part
+   * @param state        - A state object which is used to synchronize after replacement
+   */
+  protected _syncPartState(
+    partId: string,
+    newElement: HTMLElement,
+    priorElement: HTMLElement,
+    state: HandlebarsApplicationMixin.PartState,
+  ): void;
+
+  /**
+   * Attach event listeners to rendered template parts.
+   * @param partId      - The id of the part being rendered
+   * @param htmlElement - The rendered HTML element for the part
+   * @param options     - Rendering options passed to the render method
+   */
+  protected _attachPartListeners(
+    partId: string,
+    htmlElement: HTMLElement,
+    options: DeepPartial<HandlebarsApplicationMixin.HandlebarsRenderOptions>,
+  ): void;
+}
+
+/**
+ * Augment an Application class with [Handlebars](https://handlebarsjs.com) template rendering behavior.
+ */
+declare function HandlebarsApplicationMixin<BaseClass extends ApplicationV2.Internal.Constructor>(
+  BaseApplication: BaseClass,
+): Mixin<typeof HandlebarsApplication, BaseClass>;
+
+declare namespace HandlebarsApplicationMixin {
+  interface PartState {
+    scrollPositions: Array<[el1: HTMLElement, scrollTop: number, scrollLeft: number]>;
+    focus?: string | undefined;
+  }
+
+  // TODO: How does this merge with DocumentSheetRenderOptions?
+  interface HandlebarsRenderOptions extends ApplicationV2.RenderOptions {
+    parts: string[];
+  }
+
+  interface HandlebarsTemplatePart {
+    /**
+     * The template entry-point for the part
+     */
+    template: string;
+
+    /**
+     * A CSS id to assign to the top-level element of the rendered part.
+     * This id string is automatically prefixed by the application id.
+     */
+    id?: string;
+
+    /**
+     * An array of CSS classes to apply to the top-level element of the
+     * rendered part.
+     */
+    classes?: string[];
+
+    /**
+     * An array of templates that are required to render the part.
+     * If omitted, only the entry-point is inferred as required.
+     */
+    templates?: string[];
+
+    /**
+     * An array of selectors within this part whose scroll positions should
+     * be persisted during a re-render operation. A blank string is used
+     * to denote that the root level of the part is scrollable.
+     */
+    scrollabe?: string[];
+
+    /**
+     * A registry of forms selectors and submission handlers.
+     */
+    forms?: Record<string, ApplicationV2.FormConfiguration>;
+  }
+}
+
+export default HandlebarsApplicationMixin;

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

@@ -0,0 +1,7 @@
+// 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 */
+
+export { default as CompendiumArtConfig } from "./compendium-art-config.mjs";
+export { default as PermissionConfig } from "./permission-config.mjs";

package/src/foundry/client-esm/applications/apps/compendium-art-config.d.mts

@@ -0,0 +1,53 @@
+import type { ConformRecord, InterfaceToObject, MustConform } from "../../../../types/helperTypes.d.mts";
+import type { DeepPartial } from "../../../../types/utils.d.mts";
+import type { CompendiumArtDescriptor } from "../../helpers/_types.d.mts";
+import type ApplicationV2 from "../api/application.d.mts";
+import type HandlebarsApplicationMixin from "../api/handlebars-application.d.mts";
+
+type CompendiumArtConfigRenderContext = InterfaceToObject<CompendiumArtConfig.RenderContext>;
+
+type CompendiumArtConfigParts = ConformRecord<
+  CompendiumArtConfig.Parts,
+  HandlebarsApplicationMixin.HandlebarsTemplatePart
+>;
+
+/**
+ * An application for configuring compendium art priorities.
+ */
+declare class CompendiumArtConfig<
+  RenderContext extends CompendiumArtConfigRenderContext = CompendiumArtConfigRenderContext,
+  Configuration extends ApplicationV2.Configuration = ApplicationV2.Configuration,
+  RenderOptions extends ApplicationV2.RenderOptions = ApplicationV2.RenderOptions,
+> extends HandlebarsApplicationMixin(ApplicationV2)<RenderContext, Configuration, RenderOptions> {
+  // placeholder private member to help subclassing
+  #compendiumArtConfig: true;
+
+  static override DEFAULT_OPTIONS: Partial<ApplicationV2.Configuration>;
+  static override PARTS: CompendiumArtConfigParts;
+
+  /* -------------------------------------------- */
+  /*  Rendering                                   */
+  /* -------------------------------------------- */
+
+  /** @override */
+  override _prepareContext(_options: DeepPartial<ApplicationV2.RenderOptions>): Promise<RenderContext>;
+}
+
+declare namespace CompendiumArtConfig {
+  interface RenderContext {
+    config: CompendiumArtDescriptor[];
+    buttons: ApplicationV2.FormFooterButton[];
+  }
+
+  interface Parts {
+    priorities: HandlebarsApplicationMixin.HandlebarsTemplatePart;
+    footer: HandlebarsApplicationMixin.HandlebarsTemplatePart;
+  }
+}
+
+type _PartsMustBeValid = MustConform<
+  InterfaceToObject<CompendiumArtConfig.Parts>,
+  Record<string, HandlebarsApplicationMixin.HandlebarsTemplatePart>
+>;
+
+export default CompendiumArtConfig;