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

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

@@ -1,4 +1,4 @@
-import type { AnyFunction, DeepPartial, EmptyObject } from "../../../../types/utils.d.mts";
+import type { DeepPartial, EmptyObject, InexactPartial, MaybePromise, NullishCoalesce } from "fvtt-types/utils";
 import type ApplicationV2 from "./application.d.mts";
 
 /**
@@ -61,14 +61,19 @@ import type ApplicationV2 from "./application.d.mts";
  * }).render({ force: true });
  * ```
  */
-declare class DialogV2 extends ApplicationV2<EmptyObject, DialogV2.Configuration> {
+declare class DialogV2<
+  RenderContext extends object = EmptyObject,
+  Configuration extends DialogV2.Configuration = DialogV2.Configuration,
+  RenderOptions extends ApplicationV2.RenderOptions = ApplicationV2.RenderOptions,
+> extends ApplicationV2<RenderContext, Configuration, RenderOptions> {
   static override DEFAULT_OPTIONS: DeepPartial<ApplicationV2.Configuration>;
 
-  protected override _initializeApplicationOptions(
-    options: DeepPartial<DialogV2.Configuration>,
-  ): DeepPartial<DialogV2.Configuration>;
+  protected override _initializeApplicationOptions(options: DeepPartial<DialogV2.Configuration>): Configuration;
 
-  protected override _renderHTML(_context: unknown, _options: ApplicationV2.RenderOptions): Promise<HTMLFormElement>;
+  protected override _renderHTML(
+    _context: RenderContext,
+    _options: DeepPartial<RenderOptions>,
+  ): Promise<HTMLFormElement>;
 
   /**
    * Render configured buttons.
@@ -82,12 +87,12 @@ declare class DialogV2 extends ApplicationV2<EmptyObject, DialogV2.Configuration
    */
   protected _onSubmit(target: HTMLButtonElement, event: PointerEvent | SubmitEvent): Promise<DialogV2>;
 
-  protected override _onFirstRender(_context: EmptyObject, _options: DeepPartial<ApplicationV2.RenderOptions>): void;
+  protected override _onFirstRender(_context: RenderContext, _options: DeepPartial<RenderOptions>): Promise<void>;
 
   protected override _replaceHTML(
     result: HTMLFormElement,
     content: HTMLElement,
-    _options: DeepPartial<ApplicationV2.RenderOptions>,
+    _options: DeepPartial<RenderOptions>,
   ): void;
 
   /**
@@ -110,14 +115,9 @@ declare class DialogV2 extends ApplicationV2<EmptyObject, DialogV2.Configuration
    *          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>>;
+  static confirm<Options extends DialogV2.ConfirmConfig<unknown, unknown>>(
+    config?: Options,
+  ): Promise<DialogV2.ConfirmReturn<Options>>;
 
   /**
    * A utility helper to generate a dialog with a single confirmation button.
@@ -125,12 +125,9 @@ declare class DialogV2 extends ApplicationV2<EmptyObject, DialogV2.Configuration
    *             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>>;
+  static prompt<Options extends DialogV2.PromptConfig<unknown>>(
+    config?: Options,
+  ): Promise<DialogV2.PromptReturn<Options>>;
 
   /**
    * Spawn a dialog and wait for it to be dismissed or submitted.
@@ -138,25 +135,38 @@ declare class DialogV2 extends ApplicationV2<EmptyObject, DialogV2.Configuration
    *          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>>;
+  static wait<Options extends DialogV2.WaitOptions>(config?: Options): Promise<DialogV2.WaitReturn<Options>>;
+
+  /**
+   * Present an asynchronous Dialog query to a specific User for response.
+   * @param user   - A User instance or a User id
+   * @param type   - The type of Dialog to present
+   * @param config - Dialog configuration forwarded on to the Dialog.prompt, Dialog.confirm, or
+   *                 Dialog.wait function depending on the query type. Callback options are not supported.
+   * @returns The query response or null if no response was provided
+   *
+   * @see {@link DialogV2.prompt}
+   * @see {@link DialogV2.confirm}
+   * @see {@link DialogV2.wait}
+   */
+  static query<T extends DialogV2.Type, Options extends DialogV2.QueryConfig<T>>(
+    user: User.ConfiguredInstance | string,
+    type: T,
+    config?: Options,
+  ): Promise<DialogV2.QueryReturn<T, Options>>;
+
+  /**
+   * The dialog query handler.
+   */
+  static _handleQuery<T extends DialogV2.Type, Options extends DialogV2.QueryConfig<T>>(config: {
+    type: T;
+    config: Options;
+  }): Promise<DialogV2.QueryReturn<T, Options>>;
 }
 
 declare namespace DialogV2 {
-  export interface Button<CallBackReturn> {
+  export interface Button<CallbackReturn = string> {
     /**
      * The button action identifier.
      */
@@ -189,80 +199,148 @@ declare namespace DialogV2 {
      * from this function will be used as the dialog's submitted value.
      * Otherwise, the button's identifier is used.
      */
-    callback?: ButtonCallback<CallBackReturn>;
+    callback?: ButtonCallback<CallbackReturn>;
   }
 
   export type ButtonCallback<T> = (
     event: PointerEvent | SubmitEvent,
     button: HTMLButtonElement,
     dialog: HTMLDialogElement,
-  ) => Promise<T>;
+  ) => MaybePromise<T>;
+
+  type NoCallbackButton = Omit<Button, "callback">;
 
   export interface Configuration extends ApplicationV2.Configuration {
     /**
-     * Modal dialogs prevent interaction with the rest of the UI until they
-     * are dismissed or submitted.
+     * Modal dialogs prevent interaction with the rest of the UI until they are dismissed or submitted.
      */
     modal?: boolean;
 
     /**
      * Button configuration.
      */
-    buttons: Button<any>[];
+    buttons: Button<unknown>[];
 
     /**
-     * The dialog content.
+     * The dialog content: a HTML string or a <div> element.
+     * If string, the content is cleaned with {@link foundry.utils.cleanHTML}.
+     * Otherwise, the content is not cleaned.
+     * @defaultValue `''`
      */
-    content?: string;
+    content: string | HTMLDivElement;
 
     /**
-     * A function to invoke when the dialog is submitted. This will not be
-     * called if the dialog is dismissed.
+     * A function to invoke when the dialog is submitted.
+     * This will not be called if the dialog is dismissed.
      */
-    submit?: SubmitCallback;
+    submit?: SubmitCallback | null | undefined;
   }
 
-  // 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) => void;
 
-  export type RenderCallback = (event: Event, dialog: HTMLDialogElement) => any;
+  export type CloseCallback = (event: Event, dialog: DialogV2) => void;
 
-  export type CloseCallback = (event: Event, dialog: DialogV2) => any;
+  // This is nominally receiving the results of the button callbacks,
+  // but that just further complicates the conditional types
+  export type SubmitCallback = (result: unknown) => Promise<void>;
 
-  export type SubmitCallback = (result: any) => Promise<void>;
-
-  export interface WaitOptions extends Configuration {
+  export interface WaitOptions extends DeepPartial<Configuration> {
     /**
      * A synchronous function to invoke whenever the dialog is rendered.
      */
-    render?: RenderCallback;
+    render?: RenderCallback | null | undefined;
 
     /**
-     * A synchronous function to invoke when the dialog is closed under any
-     * circumstances.
+     * A synchronous function to invoke when the dialog is closed under any circumstances.
      */
-    close?: CloseCallback;
+    close?: CloseCallback | null | undefined;
 
     /**
      * Throw a Promise rejection if the dialog is dismissed.
-     * @defaultValue `true`
+     * @defaultValue `false`
+     * @remarks `null` equivalent to `false`
+     */
+    rejectClose?: boolean | null | undefined;
+
+    /**
+     * The user that the dialog should be shown to.
      */
-    rejectClose?: boolean;
+    user?: User.ConfiguredInstance;
   }
-}
 
-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;
+  interface ConfirmConfig<YesReturn, NoReturn> extends WaitOptions {
+    /** Options to overwrite the default yes button configuration. */
+    yes?: InexactPartial<Button<YesReturn>> | null | undefined;
+
+    /** Options to overwrite the default no button configuration. */
+    no?: InexactPartial<Button<NoReturn>> | null | undefined;
+  }
+
+  interface PromptConfig<OKReturn> extends WaitOptions {
+    /** Options to overwrite the default confirmation button configuration. */
+    ok?: InexactPartial<Button<OKReturn>> | null | undefined;
+  }
+
+  type Type = "prompt" | "confirm" | "wait";
+
+  /**
+   * @remarks Query gets passed through a socket which means it can't take a callback function on its buttons
+   */
+  type QueryConfig<T extends Type> = Omit<
+    | (T extends "wait" ? WaitOptions : never)
+    | (T extends "prompt" ? PromptConfig<never> : never)
+    | (T extends "confirm" ? ConfirmConfig<never, never> : never),
+    "buttons"
+  > & {
+    /**
+     * Button configuration.
+     */
+    buttons?: NoCallbackButton[];
+  };
+
+  type WaitReturn<Options extends WaitOptions> = Internal.ButtonReturnType<Options> | Internal.DismissType<Options>;
+
+  type ConfirmReturn<Options extends ConfirmConfig<unknown, unknown>> =
+    | Internal.ConfirmReturnType<Options>
+    | WaitReturn<Options>;
+
+  type PromptReturn<Options extends PromptConfig<unknown>> = Internal.PromptReturnType<Options> | WaitReturn<Options>;
+
+  type QueryReturn<T extends Type, Options extends QueryConfig<T>> =
+    | (T extends "confirm" ? boolean : string)
+    | DialogV2.Internal.DismissType<Options>;
+
+  namespace Internal {
+    type DismissType<Options extends { rejectClose?: boolean | null | undefined }> = Options["rejectClose"] extends true
+      ? never
+      : null;
+
+    type ButtonReturnType<Options extends { buttons?: Button<unknown>[] }> =
+      // Two cases - one for where all buttons have a defined callback, the other where they don't
+      Options["buttons"] extends ReadonlyArray<{ callback: ButtonCallback<infer Callback> }>
+        ? Callback extends undefined
+          ? string
+          : Callback
+        : Options["buttons"] extends ReadonlyArray<Button<infer Callback>>
+          ? Callback | string
+          : never;
+
+    type ConfirmReturnType<Options extends ConfirmConfig<unknown, unknown>> =
+      | (Options extends { yes: { readonly callback: ButtonCallback<infer YesReturn> } }
+          ? NullishCoalesce<YesReturn, true>
+          : true)
+      | (Options extends { no: { readonly callback: ButtonCallback<infer NoReturn> } }
+          ? NullishCoalesce<NoReturn, false>
+          : false);
+
+    type PromptReturnType<Options extends PromptConfig<unknown>> = Options extends {
+      ok: {
+        readonly callback: ButtonCallback<infer OKReturn>;
+      };
+    }
+      ? NullishCoalesce<OKReturn, string>
+      : string;
+  }
+}
 
 export default DialogV2;

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

@@ -1,4 +1,4 @@
-import type { AnyObject, DeepPartial, EmptyObject } from "../../../../types/utils.d.mts";
+import type { DeepPartial, SimpleMerge } from "fvtt-types/utils";
 import type ApplicationV2 from "./application.d.mts";
 
 declare namespace DocumentSheetV2 {
@@ -6,6 +6,15 @@ declare namespace DocumentSheetV2 {
 
   type AnyConstructor = typeof AnyDocumentSheetV2;
 
+  interface RenderContext<Document extends foundry.abstract.Document.Any = foundry.abstract.Document.Any>
+    extends ApplicationV2.RenderContext {
+    document: Document;
+    source: Document["_source"];
+    fields: Document["schema"]["fields"];
+    editable: boolean;
+    rootId: string;
+  }
+
   interface Configuration<Document extends foundry.abstract.Document.Any = foundry.abstract.Document.Any>
     extends ApplicationV2.Configuration {
     /**
@@ -43,13 +52,16 @@ declare namespace DocumentSheetV2 {
  */
 declare class DocumentSheetV2<
   Document extends foundry.abstract.Document.Any,
-  RenderContext extends AnyObject = EmptyObject,
+  RenderContext extends object = DocumentSheetV2.RenderContext<Document>,
   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 });
+  // Note(LukeAbby): This is a fix for https://github.com/microsoft/TypeScript/issues/60927
+  constructor(options: SimpleMerge<DeepPartial<Configuration>, { document: Document }>);
 
-  static DEFAULT_OPTIONS: DeepPartial<DocumentSheetV2.Configuration>;
+  // 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.
+  static DEFAULT_OPTIONS: DeepPartial<DocumentSheetV2.Configuration> & object;
 
   get document(): Document;
 
@@ -67,9 +79,7 @@ declare class DocumentSheetV2<
    */
   get isEditable(): boolean;
 
-  protected _initializeApplicationOptions(
-    options: DeepPartial<Configuration>,
-  ): DeepPartial<Configuration> & Record<string, unknown>;
+  protected _initializeApplicationOptions(options: DeepPartial<Configuration>): Configuration;
 
   protected override _headerControlsButtons(): Generator<ApplicationV2.HeaderControlsEntry>;
 
@@ -77,7 +87,10 @@ declare class DocumentSheetV2<
 
   protected override _canRender(options: DeepPartial<RenderOptions>): false | void;
 
-  protected override _onFirstRender(context: DeepPartial<RenderContext>, options: DeepPartial<RenderOptions>): void;
+  protected override _onFirstRender(
+    context: DeepPartial<RenderContext>,
+    options: DeepPartial<RenderOptions>,
+  ): Promise<void>;
 
   protected override _onClose(options: DeepPartial<RenderOptions>): void;