@7h3laughingman/foundry-types 13.351.0

package/src/client/applications/ux/context-menu.d.mts

@@ -0,0 +1,202 @@
+export interface ContextMenuEntry {
+    /** The context menu label. Can be localized. */
+    name: string;
+    /** A string containing an HTML icon element for the menu item. */
+    icon?: string;
+    /** Additional CSS classes to apply to this menu item. */
+    classes?: string;
+    /** An identifier for a group this entry belongs to. */
+    group?: string;
+    /** The function to call when the menu item is clicked. */
+    callback: ContextMenuCallback;
+    /** A function to call or boolean value to determine if this entry appears in the menu. */
+    condition?: ContextMenuCondition | boolean;
+}
+
+export type ContextMenuCondition = (html: HTMLElement) => boolean;
+export type ContextMenuCallback = (target: HTMLElement) => unknown;
+
+export interface ContextMenuOptions {
+    /**
+     * Optionally override the triggering event which can spawn the menu. If the menu is using fixed positioning, this
+     * event must be a PointerEvent.
+     */
+    eventName?: string;
+
+    /** A function to call when the context menu is opened. */
+    onOpen?: ContextMenuCallback;
+
+    /** A function to call when the context menu is closed. */
+    onClose?: ContextMenuCallback;
+
+    /** If true, the context menu is given a fixed position rather than being injected into the target. */
+    fixed?: boolean;
+
+    /** If true, callbacks will be passed jQuery objects instead of HTMLElement instances. */
+    jQuery: false;
+}
+
+export interface ContextMenuRenderOptions {
+    /** The event that triggered the context menu opening. */
+    event?: Event;
+    /** Animate the context menu opening. */
+    animate?: boolean;
+}
+
+/**
+ * Display a right-click activated Context Menu which provides a dropdown menu of options.
+ * A ContextMenu is constructed by designating a parent HTML container and a target selector.
+ * An Array of menuItems defines the entries of the menu which is displayed.
+ */
+export default class ContextMenu {
+    /**
+     * @param container The HTML element that contains the context menu targets.
+     * @param selector A CSS selector which activates the context menu.
+     * @param menuItems An Array of entries to display in the menu
+     * @param options Additional options to configure the context menu.
+     */
+    constructor(container: HTMLElement | JQuery, selector: string, menuItems: ContextMenuEntry[], options: ContextMenuOptions);
+
+    /* -------------------------------------------- */
+    /*  Properties                                  */
+    /* -------------------------------------------- */
+
+    /**
+     * The menu element.
+     */
+    get element(): HTMLElement;
+
+    /**
+     * A CSS selector to identify context menu targets.
+     */
+    get selector(): string;
+
+    /**
+     * The event name to listen for.
+     */
+    get eventName(): string;
+
+    /**
+     * The array of menu items to render.
+     */
+    menuItems: ContextMenuEntry & { element: HTMLElement };
+
+    /**
+     * A function to call when the context menu is opened.
+     */
+    onOpen: ContextMenuCallback;
+
+    /**
+     * A function to call when the context menu is closed.
+     */
+    onClose: ContextMenuCallback;
+
+    /**
+     * Check which direction the menu is expanded in.
+     */
+    get expandUp(): boolean;
+
+    /**
+     * Whether to position the context menu as a fixed element, or inject it into the target.
+     */
+    get fixed(): boolean;
+
+    /**
+     * The parent HTML element to which the context menu is attached
+     */
+    get target(): HTMLElement;
+
+    /* -------------------------------------------- */
+    /*  Rendering                                   */
+    /* -------------------------------------------- */
+
+    /**
+     * Animate the context menu's height when opening or closing.
+     * @param open Whether the menu is opening or closing.
+     * @returns A Promise that resolves when the animation completes.
+     */
+    protected _animate(open?: boolean): Promise<void>;
+
+    /**
+     * Closes the menu and removes it from the DOM.
+     * @param options Options to configure the closing behavior.
+     * @param options.animate Animate the context menu closing.
+     */
+    close(options?: { animate?: boolean }): Promise<void>;
+
+    /**
+     * Close the menu and remove it from the DOM.
+     */
+    protected _close(): void;
+
+    /**
+     * Called before the context menu begins rendering.
+     */
+    protected _preRender(target: HTMLElement, options?: ContextMenuRenderOptions): Promise<void>;
+
+    /**
+     * Render the Context Menu by iterating over the menuItems it contains.
+     * Check the visibility of each menu item, and only render ones which are allowed by the item's logical condition.
+     * Attach a click handler to each item which is rendered.
+     * @returns A Promise that resolves when the open animation has completed.
+     */
+    render(target: HTMLElement, options?: ContextMenuRenderOptions): Promise<void>;
+
+    /**
+     * Called after the context menu has finished rendering and animating open.
+     */
+    protected _onRender(options?: ContextMenuRenderOptions): Promise<void>;
+
+    /**
+     * Set the position of the context menu, taking into consideration whether the menu should expand upward or downward
+     * @param menu          The context menu element.
+     * @param target        The element that the context menu was spawned on.
+     * @param options.event The event that triggered the context menu opening.
+     */
+    protected _setPosition(menu: HTMLElement, target: HTMLElement, options?: { event?: Event }): void;
+
+    /**
+     * Inject the menu inside the target.
+     * @param menu   The menu element.
+     * @param target The context target.
+     */
+    protected _injectMenu(menu: HTMLElement, target: HTMLElement): void;
+
+    /**
+     * Set the context menu at a fixed position in the viewport.
+     * @param menu   The menu element.
+     * @param target The context target.
+     * @param options.event The event that triggered the context menu opening.
+     */
+    protected _setFixedPosition(menu: HTMLElement, target: HTMLElement, options?: { event?: Event }): void;
+
+    /* -------------------------------------------- */
+    /*  Event Listeners & Handlers                  */
+    /* -------------------------------------------- */
+
+    /**
+     * Local listeners which apply to each ContextMenu instance which is created.
+     * @param menu The context menu element.
+     */
+    activateListeners(menu: HTMLElement): void;
+
+    /**
+     * Handle context menu activation.
+     * @param event The triggering event.
+     */
+    protected _onActivate(event: Event): void | Promise<void>;
+
+    /**
+     * Global listeners which apply once only to the document.
+     */
+    static eventListeners(): void;
+
+    /* -------------------------------------------- */
+    /*  Factory Methods                             */
+    /* -------------------------------------------- */
+
+    /**
+     * Retrieve the configured DragDrop implementation.
+     */
+    static get implementation(): typeof ContextMenu;
+}

package/src/client/applications/ux/drag-drop.d.mts

@@ -0,0 +1,131 @@
+type DragAction = "dragstart" | "dragover" | "drop" | "dragenter" | "dragleave" | "dragend";
+
+interface DragDropConfiguration {
+    /** The CSS selector used to target draggable elements. */
+    dragSelector: string | null;
+    /** The CSS selector used to target viable drop targets. */
+    dropSelector: string | null;
+    /** Permission tests for each action */
+    permissions: Record<"dragstart" | "drop", (selector: string) => boolean>;
+    /** Callback functions for each action */
+    callbacks: Partial<Record<DragAction, (event: DragEvent) => void>>;
+}
+
+/**
+ * A controller class for managing drag and drop workflows within an Application instance.
+ * The controller manages the following actions: dragstart, dragover, drop.
+ *
+ * @example Activate drag-and-drop handling for a certain set of elements
+ * ```js
+ * 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);
+ * ```
+ */
+export default class DragDrop {
+    constructor(config?: Partial<DragDropConfiguration>);
+
+    /* -------------------------------------------- */
+    /*  Properties                                  */
+    /* -------------------------------------------- */
+
+    /** A set of callback functions for each action of the drag & drop workflow.  */
+    callbacks: DragDropConfiguration["callbacks"];
+
+    /** The HTML selector which identifies draggable elements. */
+    dragSelector: DragDropConfiguration["dragSelector"];
+
+    /** The HTML selector which identifies drop targets. */
+    dropSelector: DragDropConfiguration["dropSelector"];
+
+    /** A set of functions to control authorization to begin drag workflows, and drop content. */
+    permissions: DragDropConfiguration["permissions"];
+
+    /* -------------------------------------------- */
+    /*  Public API                                  */
+    /* -------------------------------------------- */
+
+    /**
+     * 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: DragAction): ((event: DragEvent) => void) | 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: DragAction, selector: string): boolean;
+
+    /* -------------------------------------------- */
+    /*  Event Listeners and Handlers                */
+    /* -------------------------------------------- */
+
+    /**
+     * Handle the start of a drag workflow
+     * @param event The drag event being handled
+     */
+    protected _handleDragStart(event: DragEvent): void;
+
+    /**
+     * Handle a drag workflow ending for any reason.
+     * @param event  The drag event.
+     */
+    protected _handleDragEnd(event: DragEvent): void;
+
+    /**
+     * Handle entering a drop target while dragging.
+     * @param event  The drag event.
+     */
+    protected _handleDragEnter(event: DragEvent): void;
+
+    /**
+     * Handle leaving a drop target while dragging.
+     * @param event  The drag event.
+     */
+    protected _handleDragLeave(event: DragEvent): void;
+
+    /**
+     * Handle a dragged element over a droppable target
+     * @param event  The drag event being handled
+     */
+    protected _handleDragOver(event: DragEvent): boolean;
+
+    /**
+     * Handle a dragged element dropped on a droppable target
+     * @param event  The drag event being handled
+     */
+    protected _handleDrop(event: DragEvent): void;
+
+    /* -------------------------------------------- */
+    /*  Helpers                                     */
+    /* -------------------------------------------- */
+
+    /**
+     * A helper to create an image preview element for use during HTML element dragging.
+     * @param img
+     * @param width
+     * @param height
+     */
+    static createDragImage(img: HTMLImageElement, width: number, height: number): HTMLDivElement;
+
+    /* -------------------------------------------- */
+    /*  Factory Methods                             */
+    /* -------------------------------------------- */
+
+    /** Retrieve the configured DragDrop implementation. */
+    static get implementation(): typeof DragDrop;
+}

package/src/client/applications/ux/draggable.d.mts

@@ -0,0 +1,108 @@
+import { ApplicationV2 } from "../api/_module.mjs";
+import { Application } from "./../../appv1/api/_module.mjs";
+
+interface DraggableResizeOptions {
+    /** A CSS selector for the resize handle. */
+    selector?: string;
+    /** Enable resizing along the X axis. Default: `true` */
+    resizeX?: boolean;
+    /** Enable resizing along the Y axis. Default: `true` */
+    resizeY?: boolean;
+    /** Modify the resizing direction to be right-to-left. */
+    rtl?: boolean;
+}
+
+/**
+ * A UI utility to make an element draggable.
+ */
+export default class Draggable {
+    /**
+     * @param app       The Application that is being made draggable.
+     * @param element   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 behavior
+     *                  or true to have it automatically configured.
+     */
+    constructor(app: Application | ApplicationV2, element: HTMLElement | JQuery, handle: HTMLElement | false, resizable: boolean | DraggableResizeOptions);
+
+    /* -------------------------------------------- */
+    /*  Properties                                  */
+    /* -------------------------------------------- */
+
+    /** The Application being made draggable. */
+    app: Application | ApplicationV2;
+
+    /** The Application's outer-most element. */
+    element: HTMLElement;
+
+    /** The drag handle, or false to disable dragging. */
+    handle: HTMLElement | false;
+
+    /** Registered event handlers. */
+    handlers: Record<string, Function>;
+
+    /** The Application's starting position, pre-drag. */
+    position: object;
+
+    /** Resize configuration. */
+    resizable: boolean | DraggableResizeOptions;
+
+    /* -------------------------------------------- */
+    /*  Methods                                     */
+    /* -------------------------------------------- */
+
+    /**
+     * 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
+     * @param event
+     */
+    protected _onDragMouseDown(event: PointerEvent): void;
+
+    /**
+     * Move the window with the mouse, bounding the movement to ensure the window stays within bounds of the viewport
+     * @param event
+     */
+    protected _onDragMouseMove(event: PointerEvent): void;
+
+    /**
+     * Conclude the dragging behavior when the mouse is release, setting the final position and removing listeners
+     * @param event
+     */
+    protected _onDragMouseUp(event: PointerEvent): void;
+
+    /**
+     * Handle the initial mouse click which activates dragging behavior for the application
+     * @param event
+     */
+    protected _onResizeMouseDown(event: PointerEvent): void;
+
+    /**
+     * Move the window with the mouse, bounding the movement to ensure the window stays within bounds of the viewport
+     * @param event
+     */
+    protected _onResizeMouseMove(event: PointerEvent): void;
+
+    /**
+     * Conclude the dragging behavior when the mouse is release, setting the final position and removing listeners
+     * @param event
+     */
+    protected _onResizeMouseUp(event: PointerEvent): void;
+
+    /* -------------------------------------------- */
+    /*  Factory Methods                             */
+    /* -------------------------------------------- */
+
+    /** Retrieve the configured Draggable implementation. */
+    static get implementation(): typeof Draggable;
+}

package/src/client/applications/ux/form-data-extended.d.mts

@@ -0,0 +1,76 @@
+import { TinyMCEEditorData } from "../../appv1/api/form-application-v1.mjs";
+import ProseMirrorEditor from "./prosemirror-editor.mjs";
+
+/**
+ * An extension of the native FormData implementation.
+ *
+ * This class functions the same way that the default FormData does, but it is more opinionated about how
+ * input fields of certain types should be evaluated and handled.
+ *
+ * It also adds support for certain Foundry VTT specific concepts including:
+ *  Support for defined data types and type conversion
+ *  Support for TinyMCE editors
+ *  Support for editable HTML elements
+ */
+export default class FormDataExtended extends FormData {
+    /**
+     *
+     * @param form    The form being processed
+     * @param options Options which configure form processing
+     */
+    constructor(form: HTMLFormElement, options?: Partial<FormDataExtendedOptions>);
+
+    /**
+     * A mapping of data types requested for each form field.
+     */
+    dtypes: Record<string, string>;
+
+    /**
+     * A record of TinyMCE editors which are linked to this form.
+     */
+    editors: Record<string, TinyMCE.Editor | ProseMirrorEditor>;
+
+    /**
+     * The object representation of the form data, available once processed.
+     */
+    readonly object: Record<string, unknown>;
+
+    /**
+     * Process the HTML form element to populate the FormData instance.
+     * @param form    The HTML form being processed
+     * @param options Options forwarded from the constructor
+     */
+    process(form: HTMLFormElement, options: FormDataExtendedOptions): void;
+
+    /**
+     * Assign a value to the FormData instance which always contains JSON strings.
+     * Also assign the cast value in its preferred data type to the parsed object representation of the form data.
+     * @param {string} name     The field name
+     * @param {string} value       The raw extracted value from the field
+     */
+    override set(name: string, value: string | Blob): void;
+
+    /**
+     * Append values to the form data, adding them to an array.
+     * @param name  The field name to append to the form
+     * @param value The value to append to the form data
+     */
+    override append(name: string, value: unknown): void;
+}
+
+interface FormDataExtendedOptions {
+    /** A record of TinyMCE editor metadata objects, indexed by their update key */
+    editors: Record<string, TinyMCEEditorData>;
+    /** A mapping of data types for form fields */
+    dtypes: string[];
+    /**
+     * Include disabled fields?
+     * @default false
+     */
+    disabled: boolean;
+    /**
+     * Include readonly fields?
+     * @default false
+     */
+    readonly: boolean;
+}

package/src/client/applications/ux/html-secret.d.mts

@@ -0,0 +1,61 @@
+import { ClientDocument } from "./../../documents/abstract/client-document.mjs";
+
+export interface HTMLSecretConfiguration {
+    /** The CSS selector used to target content that contains secret blocks. */
+    parentSelector: string;
+    /** An object of callback functions for each operation. */
+    callbacks: {
+        /**
+         * @param secret The secret element whose surrounding content we wish to retrieve.
+         * @returns The content where the secret is housed.
+         */
+        content: (secret: HTMLElement) => string;
+        /**
+         * @param secret  The secret element that is being manipulated.
+         * @param content The content block containing the updated secret element.
+         * @returns The updated Document.
+         */
+        update: (secret: HTMLElement, content: string) => Promise<ClientDocument>;
+    };
+}
+
+/**
+ * A composable class for managing functionality for secret blocks within DocumentSheets.
+ * @see {@link foundry.applications.api.DocumentSheet}
+ * @example Activate secret revealing functionality within a certain block of content.
+ * ```js
+ * const secrets = new HTMLSecret({
+ *   selector: "section.secret[id]",
+ *   callbacks: {
+ *     content: this._getSecretContent.bind(this),
+ *     update: this._updateSecret.bind(this)
+ *   }
+ * });
+ * secrets.bind(html);
+ * ```
+ */
+export default class HTMLSecret {
+    /** The CSS selector used to target secret blocks. */
+    parentSelector: HTMLSecretConfiguration["parentSelector"];
+
+    /** An object of callback functions for each operation. */
+    callbacks: HTMLSecretConfiguration["callbacks"];
+
+    /**
+     *  @param config Configuration options.
+     */
+    constructor(config: HTMLSecretConfiguration);
+
+    /**
+     * Add event listeners to the targeted secret blocks.
+     * @param html The HTML content to select secret blocks from.
+     */
+    bind(html: HTMLElement): void;
+
+    /**
+     * Handle toggling a secret's revealed state.
+     * @param event The triggering click event.
+     * @returns The Document whose content was modified.
+     */
+    protected _onToggleSecret(event: PointerEvent): Promise<ClientDocument | void>;
+}