@league-of-foundry-developers/foundry-vtt-types 9.280.0 → 12.331.1-beta

package/src/foundry/client/ui/dialog.d.mts

@@ -0,0 +1,326 @@
+import type { MaybePromise } from "../../../types/utils.d.mts";
+
+declare global {
+  interface DialogOptions extends ApplicationOptions {
+    /**
+     * Whether to provide jQuery objects to callback functions (if true) or plain
+     * HTMLElement instances (if false). This is currently true by default but in the
+     * future will become false by default.
+     * @defaultValue `true`
+     */
+    jQuery?: boolean;
+  }
+
+  interface DialogButton<T = unknown, JQueryOrHtml = JQuery | HTMLElement> {
+    /**
+     * A Font Awesome icon for the button
+     */
+    icon?: string;
+
+    /**
+     * The label for the button
+     */
+    label: string;
+
+    /**
+     * Whether the button is disabled
+     */
+    disabled?: boolean;
+
+    /**
+     * A callback function that fires when the button is clicked
+     */
+    callback?: (html: JQueryOrHtml, event?: MouseEvent) => T;
+  }
+
+  interface DialogData<JQueryOrHtml = JQuery | HTMLElement> {
+    /**
+     * The window title displayed in the dialog header
+     */
+    title: string;
+
+    /**
+     * HTML content for the dialog form
+     */
+    content: string;
+
+    /**
+     * The buttons which are displayed as action choices for the dialog
+     */
+    buttons: Record<string, DialogButton<unknown, JQueryOrHtml>>;
+
+    /**
+     * The name of the default button which should be triggered on Enter keypress
+     */
+    default?: string;
+
+    /**
+     * A callback function invoked when the dialog is rendered
+     */
+    render?: (element: JQueryOrHtml) => void;
+
+    /**
+     * Common callback operations to perform when the dialog is closed
+     */
+    close?: (element: JQueryOrHtml) => void;
+  }
+
+  /**
+   * Create a modal dialog window displaying a title, a message, and a set of buttons which trigger callback functions.
+   *
+   * @example Constructing a custom dialog instance
+   * ```typescript
+   * let d = new Dialog({
+   *  title: "Test Dialog",
+   *  content: "<p>You must choose either Option 1, or Option 2</p>",
+   *  buttons: {
+   *   one: {
+   *    icon: '<i class="fas fa-check"></i>',
+   *    label: "Option One",
+   *    callback: () => console.log("Chose One")
+   *   },
+   *   two: {
+   *    icon: '<i class="fas fa-times"></i>',
+   *    label: "Option Two",
+   *    callback: () => console.log("Chose Two")
+   *   }
+   *  },
+   *  default: "two",
+   *  render: html => console.log("Register interactivity in the rendered dialog"),
+   *  close: html => console.log("This always is logged no matter which option is chosen")
+   * });
+   * d.render(true);
+   * ```
+   * @typeParam Options - the type of the options object
+   */
+  class Dialog<Options extends DialogOptions = DialogOptions> extends Application<Options> {
+    /**
+     * @param data    - An object of dialog data which configures how the modal window is rendered
+     * @param options - Dialog rendering options, see {@link Application}
+     */
+    constructor(data: DialogData, options?: Partial<Options>);
+
+    data: DialogData;
+
+    /**
+     * A bound instance of the _onKeyDown method which is used to listen to keypress events while the Dialog is active.
+     */
+    #onKeyDown: ((event: KeyboardEvent) => MaybePromise<void>) | undefined;
+
+    /**
+     * @defaultValue
+     * ```typescript
+     * foundry.utils.mergeObject(super.defaultOptions, {
+     *   template: "templates/hud/dialog.html",
+     *   focus: true,
+     *   classes: ["dialog"],
+     *   width: 400,
+     *   jQuery: true
+     * })
+     * ```
+     */
+    static override get defaultOptions(): DialogOptions;
+
+    override get title(): string;
+
+    override getData(options?: Partial<Options>): MaybePromise<object>;
+
+    override activateListeners(html: JQuery): void;
+
+    /**
+     * Handle a left-mouse click on one of the dialog choice buttons
+     * @param event - The left-mouse click event
+     */
+    protected _onClickButton(event: MouseEvent): void;
+
+    /**
+     * Handle a keydown event while the dialog is active
+     * @param event - The keydown event
+     */
+    protected _onKeyDown(event: KeyboardEvent & { key: "Escape" }): Promise<void>;
+    protected _onKeyDown(event: KeyboardEvent): void;
+
+    override _renderOuter(): ReturnType<Application["_renderOuter"]>;
+
+    /**
+     * Submit the Dialog by selecting one of its buttons
+     * @param button - The configuration of the chosen button
+     * @param event - The originating click event
+     */
+    protected submit(button: DialogButton, event?: MouseEvent): void;
+
+    override close(options?: Application.CloseOptions): Promise<void>;
+
+    /**
+     * A helper factory method to create simple confirmation dialog windows which consist of simple yes/no prompts.
+     * If you require more flexibility, a custom Dialog instance is preferred.
+     *
+     * @param config - Confirmation dialog configuration (defaultValue: `{}`)
+     * @returns A promise which resolves once the user makes a choice or closes the window.
+     *
+     * @example Prompt the user with a yes or no question
+     * ```typescript
+     * let d = Dialog.confirm({
+     *  title: "A Yes or No Question",
+     *  content: "<p>Choose wisely.</p>",
+     *  yes: () => console.log("You chose ... wisely"),
+     *  no: () => console.log("You chose ... poorly"),
+     *  defaultYes: false
+     * });
+     * ```
+     */
+    static confirm<Yes = true, No = false>(
+      config: Dialog.ConfirmConfig<Yes, No, JQuery> & { options?: { jQuery?: true }; rejectClose: true },
+    ): Promise<Yes | No>;
+    static confirm<Yes = true, No = false>(
+      config: Dialog.ConfirmConfig<Yes, No, JQuery> & { options?: { jQuery?: true } },
+    ): Promise<Yes | No | null>;
+    static confirm<Yes = true, No = false>(
+      config: Dialog.ConfirmConfig<Yes, No, HTMLElement> & { options: { jQuery: false }; rejectClose: true },
+    ): Promise<Yes | No>;
+    static confirm<Yes = true, No = false>(
+      config: Dialog.ConfirmConfig<Yes, No, HTMLElement> & { options: { jQuery: false } },
+    ): Promise<Yes | No | null>;
+    static confirm<Yes = true, No = false>(
+      config: Dialog.ConfirmConfig<Yes, No, JQuery | HTMLElement> & { rejectClose: true },
+    ): Promise<Yes | No>;
+    static confirm<Yes = true, No = false>(
+      config?: Dialog.ConfirmConfig<Yes, No, JQuery | HTMLElement>,
+    ): Promise<Yes | No | null>;
+
+    /**
+     * A helper factory method to display a basic "prompt" style Dialog with a single button
+     * @param config - Dialog configuration options
+     * @returns A promise which resolves when clicked, or rejects if closed
+     */
+    static prompt<T>(
+      config: Dialog.PromptConfig<T, JQuery> & { options?: { jQuery?: true }; rejectClose: false },
+    ): Promise<T | null>;
+    static prompt<T>(config: Dialog.PromptConfig<T, JQuery> & { options?: { jQuery?: true } }): Promise<T>;
+    static prompt<T>(
+      config: Dialog.PromptConfig<T, HTMLElement> & { options: { jQuery: false }; rejectClose: false },
+    ): Promise<T | null>;
+    static prompt<T>(config: Dialog.PromptConfig<T, HTMLElement> & { options: { jQuery: false } }): Promise<T>;
+    static prompt<T>(config: Dialog.PromptConfig<T, JQuery | HTMLElement> & { rejectClose: false }): Promise<T | null>;
+    static prompt<T>(config: Dialog.PromptConfig<T, JQuery | HTMLElement>): Promise<T>;
+
+    /**
+     * Wrap the Dialog with an enclosing Promise which resolves or rejects when the client makes a choice.
+     * @param data - Data passed to the Dialog constructor
+     * @param options - Options passed to the Dialog constructor
+     * @param renderOptions - Options passed to the Dialog render call
+     * @returns A promise which resolves to the dialogs result.
+     */
+    static wait<Options extends DialogOptions = DialogOptions>(
+      data: DialogData<JQuery>,
+      options?: Partial<DialogOptions> & { jQuery?: true },
+      renderOptions?: Application.RenderOptions<Options>,
+    ): Promise<unknown>;
+    static wait<Options extends DialogOptions = DialogOptions>(
+      data: DialogData<HTMLElement>,
+      options?: Partial<DialogOptions> & { jQuery?: false },
+      renderOptions?: Application.RenderOptions<Options>,
+    ): Promise<unknown>;
+    static wait<Options extends DialogOptions = DialogOptions>(
+      data: DialogData<JQuery | HTMLElement>,
+      options?: Partial<DialogOptions>,
+      renderOptions?: Application.RenderOptions<Options>,
+    ): Promise<unknown>;
+  }
+
+  namespace Dialog {
+    /**
+     * @typeParam Yes          - The value returned by the yes callback
+     * @typeParam No           - The value returned by the no callback
+     * @typeParam JQueryOrHtml - The parameter passed to the callbacks, either JQuery or HTMLElement
+     */
+    interface ConfirmConfig<Yes, No, JQueryOrHtml> {
+      /**
+       * The confirmation window title
+       */
+      title?: string;
+
+      /**
+       * The confirmation message
+       */
+      content?: string;
+
+      /**
+       * Callback function upon yes
+       */
+      yes?: (html: JQueryOrHtml) => Yes;
+
+      /**
+       * Callback function upon no
+       */
+      no?: (html: JQueryOrHtml) => No;
+
+      /**
+       * A function to call when the dialog is rendered
+       */
+      render?: (html: JQueryOrHtml) => void;
+
+      /**
+       * Make "yes" the default choice?
+       * @defaultValue `true`
+       */
+      defaultYes?: boolean;
+
+      /**
+       * Reject the Promise if the Dialog is closed without making a choice.
+       * @defaultValue `false`
+       */
+      rejectClose?: boolean;
+
+      /**
+       * Additional rendering options passed to the Dialog
+       * @defaultValue `{}`
+       */
+      options?: Partial<DialogOptions>;
+    }
+
+    /**
+     * @typeParam Value        - The value returned by the callback function
+     * @typeParam JQueryOrHtml - The parameter passed to the callbacks, either JQuery or HTMLElement
+     */
+    interface PromptConfig<Value, JQueryOrHtml> {
+      /**
+       * The confirmation window title
+       */
+      title?: string;
+
+      /**
+       * The confirmation message
+       */
+      content?: string;
+
+      /**
+       * The confirmation button text
+       */
+      label?: string;
+
+      /**
+       * A callback function to fire when the button is clicked
+       */
+      callback: (html: JQueryOrHtml) => Value;
+
+      /**
+       * A function that fires after the dialog is rendered
+       */
+      render?: (html: JQueryOrHtml) => void;
+
+      /**
+       * Reject the promise if the dialog is closed without confirming the
+       * choice, otherwise resolve as null
+       * @defaultValue `true`
+       */
+      rejectClose?: boolean;
+
+      /**
+       * Additional rendering options
+       * @defaultValue `{}`
+       */
+      options?: Partial<DialogOptions>;
+    }
+  }
+}

package/src/foundry/client/ui/drag.d.mts

@@ -0,0 +1,128 @@
+export {};
+
+declare global {
+  /**
+   * A UI utility to make an element draggable.
+   */
+  class Draggable<R extends boolean | Draggable.Resizable = false> {
+    /**
+     * @param app       - The Application that is being made draggable.
+     * @param element   - A JQuery reference to the Application's outer-most element.
+     * @param handle    - The element that acts as a drag handle. Supply false to disable dragging.
+     * @param resizable - Is the application resizable? Supply an object to configure resizing behaviour
+     *                    or true to have it automatically configured.
+     */
+    constructor(app: Draggable["app"], element: JQuery, handle: Draggable["handle"], resizable?: R);
+
+    app: Application;
+
+    element: HTMLElement;
+
+    handle: HTMLElement | boolean;
+
+    /**
+     * @defaultValue `false`
+     */
+    resizable: R;
+
+    /**
+     * Duplicate the application's starting position to track differences
+     * @defaultValue `null`
+     */
+    position: foundry.utils.Duplicated<Application.Position> | null;
+
+    /**
+     * Remember event handlers associated with this Draggable class so they may be later unregistered
+     */
+    // prettier-ignore
+    handlers: this["resizable"] extends true
+    ? Draggable.ResizableHandlers
+    : this["resizable"] extends false
+      ? Draggable.Handlers
+      : Draggable.Handlers | Draggable.ResizableHandlers;
+
+    /**
+     * Throttle mousemove event handling to 60fps
+     * @defaultValue `0`
+     */
+    protected _moveTime: number;
+
+    /**
+     * Activate event handling for a Draggable application
+     * Attach handlers for floating, dragging, and resizing
+     */
+    activateListeners(): void;
+
+    /**
+     * Attach handlers for dragging and floating.
+     */
+    protected _activateDragListeners(): void;
+
+    /**
+     * Attach handlers for resizing.
+     */
+    protected _activateResizeListeners(): void;
+
+    /**
+     * Handle the initial mouse click which activates dragging behavior for the application
+     */
+    protected _onDragMouseDown(event: Event): void;
+
+    /**
+     * Move the window with the mouse, bounding the movement to ensure the window stays within bounds of the viewport
+     */
+    protected _onDragMouseMove(event: Event): void;
+
+    /**
+     * Conclude the dragging behavior when the mouse is release, setting the final position and removing listeners
+     */
+    protected _onDragMouseUp(event: Event): void;
+
+    /**
+     * Handle the initial mouse click which activates dragging behavior for the application
+     */
+    protected _onResizeMouseDown(event: Event): void;
+
+    /**
+     * Move the window with the mouse, bounding the movement to ensure the window stays within bounds of the viewport
+     */
+    protected _onResizeMouseMove(event: Event): void;
+
+    /**
+     * Conclude the dragging behavior when the mouse is release, setting the final position and removing listeners
+     */
+    protected _onResizeMouseUp(event: Event): void;
+  }
+
+  namespace Draggable {
+    interface Resizable {
+      /** A selector for the resize handle. */
+      selector?: string;
+      //     * @param {boolean} [resizable.resizeX=true]  Enable resizing in the X direction.
+      /**
+       * Enable resizing in the X direction.
+       * @defaultValue `true`
+       */
+      resizeX?: boolean;
+      /**
+       * Enable resizing in the y direction.
+       * @defaultValue `true`
+       */
+      resizeY?: boolean;
+    }
+
+    interface Handlers {
+      click: ["click", (e: MouseEvent) => void, { capture: boolean; passive: boolean }];
+
+      dragDown: ["pointerdown", (e: Event) => void, false];
+      dragMove: ["pointermove", (e: Event) => void, false];
+      dragUp: ["pointerup", (e: Event) => void, false];
+    }
+
+    interface ResizableHandlers extends Handlers {
+      resizeDown: ["pointerdown", (e: Event) => void, false];
+      resizeMove: ["pointermove", (e: Event) => void, false];
+      resizeUp: ["pointerup", (e: Event) => void, false];
+    }
+  }
+}

package/src/foundry/client/ui/dragdrop.d.mts

@@ -0,0 +1,124 @@
+import type { InexactPartial } from "../../../types/utils.d.mts";
+
+export {};
+
+declare global {
+  interface DragDropConfiguration {
+    /**
+     * The CSS selector used to target draggable elements.
+     */
+    dragSelector?: DragDrop["dragSelector"];
+
+    /**
+     * The CSS selector used to target viable drop targets.
+     */
+    dropSelector?: DragDrop["dropSelector"];
+
+    /**
+     * An object of permission test functions for each action
+     * @defaultValue `{}`
+     */
+    permissions?: DragDrop["permissions"];
+
+    /**
+     * An object of callback functions for each action
+     * @defaultValue `{}`
+     */
+    callbacks?: DragDrop["callbacks"];
+  }
+
+  /**
+   * A controller class for managing drag and drop workflows within an Application instance.
+   * The controller manages the following actions: dragstart, dragover, drop
+   * @see {@link Application}
+   *
+   * @example Activate drag-and-drop handling for a certain set of elements
+   * ```typescript
+   * const dragDrop = new DragDrop({
+   *   dragSelector: ".item",
+   *   dropSelector: ".items",
+   *   permissions: { dragstart: this._canDragStart.bind(this), drop: this._canDragDrop.bind(this) },
+   *   callbacks: { dragstart: this._onDragStart.bind(this), drop: this._onDragDrop.bind(this) }
+   * });
+   * dragDrop.bind(html);
+   * ```
+   */
+  class DragDrop {
+    /**
+     * @param options - (default: `{}`)
+     */
+    constructor({ dragSelector, dropSelector, permissions, callbacks }?: InexactPartial<DragDropConfiguration>);
+
+    /**
+     * The HTML selector which identifies draggable elements
+     * @defaultValue `undefined`
+     */
+    dragSelector: string | null | undefined;
+
+    /**
+     * The HTML selector which identifies drop targets
+     * @defaultValue `undefined`
+     */
+    dropSelector: string | null | undefined;
+
+    /**
+     * A set of permission checking functions for each action of the Drag and Drop workflow
+     * @defaultValue `{}`
+     */
+    permissions: Partial<Record<DragDrop.Action, (selector: this["dragSelector"]) => boolean>>;
+
+    /**
+     * A set of callback functions for each action of the Drag and Drop workflow
+     * @defaultValue `{}`
+     */
+    callbacks: InexactPartial<Record<DragDrop.Action, (event: DragEvent) => void>>;
+
+    /**
+     * Bind the DragDrop controller to an HTML application
+     * @param html - The HTML element to which the handler is bound
+     */
+    bind(html: HTMLElement): this;
+
+    /**
+     * Execute a callback function associated with a certain action in the workflow
+     * @param event  - The drag event being handled
+     * @param action - The action being attempted
+     */
+    callback(event: DragEvent, action: DragDrop.Action): void;
+
+    /**
+     * Test whether the current user has permission to perform a step of the workflow
+     * @param action   - The action being attempted
+     * @param selector - The selector being targeted
+     * @returns Can the action be performed?
+     */
+    can(action: DragDrop.Action, selector?: this["dragSelector"]): boolean;
+
+    /**
+     * Handle the start of a drag workflow
+     * @param event - The drag event being handled
+     * @internal
+     */
+    protected _handleDragStart(event: DragEvent): void;
+
+    /**
+     * Handle a dragged element over a droppable target
+     * @param event - The drag event being handled
+     * @internal
+     */
+    protected _handleDragOver(event: DragEvent): false;
+
+    /**
+     * Handle a dragged element dropped on a droppable target
+     * @param event - The drag event being handled
+     * @internal
+     */
+    protected _handleDrop(event: DragEvent): unknown;
+
+    static createDragImage(img: HTMLImageElement, width: number, height: number): HTMLDivElement;
+  }
+
+  namespace DragDrop {
+    type Action = "dragstart" | "dragover" | "drop";
+  }
+}