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

package/src/foundry/client/apps/hud/chatbubble.d.mts

@@ -0,0 +1,113 @@
+import type { Socket } from "socket.io-client";
+
+declare global {
+  /**
+   * The Chat Bubble Class
+   * This application displays a temporary message sent from a particular Token in the active Scene.
+   * The message is displayed on the HUD layer just above the Token.
+   */
+  class ChatBubbles {
+    constructor();
+
+    /**
+     * @defaultValue `"templates/hud/chat-bubble.html"`
+     */
+    template: string;
+
+    /**
+     * Track active Chat Bubbles
+     * @defaultValue `{}`
+     * @remarks This is never used
+     */
+    bubbles: object;
+
+    /**
+     * Track which Token was most recently panned to highlight
+     * Use this to avoid repeat panning
+     * @defaultValue `null`
+     * @internal
+     */
+    protected _panned: Token | null;
+
+    /**
+     * A reference to the chat bubbles HTML container in which rendered bubbles should live
+     */
+    get container(): JQuery;
+
+    /**
+     * Create a chat bubble message for a certain token which is synchronized for display across all connected clients.
+     * @param token   - The speaking Token Document
+     * @param message - The spoken message text
+     * @param options - Options which affect the bubble appearance
+     */
+    broadcast(token: TokenDocument, message: string, options: ChatBubbles.ChatBubbleOptions): Promise<JQuery | null>;
+
+    /**
+     * Speak a message as a particular Token, displaying it as a chat bubble
+     * @param token   - The speaking Token
+     * @param message - The spoken message text
+     * @param emote   - Whether to style the speech bubble as an emote
+     * @returns A Promise which resolves once the chat bubble has been created
+     */
+    say(token: Token, message: string, { emote }?: { emote?: boolean }): Promise<void>;
+
+    /**
+     * Activate Socket event listeners which apply to the ChatBubbles UI.
+     * @param socket - The active web socket connection
+     */
+    protected static _activateSocketListeners(socket: Socket): Promise<void>;
+
+    /**
+     * Clear any existing chat bubble for a certain Token
+     * @internal
+     */
+    protected _clearBubble(token: Token): Promise<void>;
+
+    /**
+     * Render the HTML template for the chat bubble
+     * @param data - Template data
+     * @returns The rendered HTML
+     * @internal
+     */
+    protected _renderHTML(data: { token: Token; message: string; emote: boolean }): Promise<string>;
+
+    /**
+     * Before displaying the chat message, determine it's constrained and unconstrained dimensions
+     * @param message - The message content
+     * @returns The rendered message dimensions
+     * @internal
+     */
+    protected _getMessageDimensions(message: string): ChatBubbles.Dimensions;
+
+    /**
+     * Assign styling parameters to the chat bubble, toggling either a left or right display (randomly)
+     * @internal
+     */
+    protected _setPosition(token: Token, html: JQuery, dimensions: ChatBubbles.Dimensions): void;
+
+    /**
+     * Determine the length of time for which to display a chat bubble.
+     * Research suggests that average reading speed is 200 words per minute.
+     * Since these are short-form messages, we multiply reading speed by 1.5.
+     * Clamp the result between 1 second (minimum) and 20 seconds (maximum)
+     *
+     * @param html - The HTML message
+     * @returns The number of milliseconds for which to display the message
+     */
+    protected _getDuration(html: JQuery): number;
+  }
+
+  namespace ChatBubbles {
+    interface Dimensions {
+      width: number;
+      height: number;
+      unconstrained: number;
+    }
+
+    interface ChatBubbleOptions {
+      cssClasses?: string;
+      pan: boolean;
+      requireVisible: false;
+    }
+  }
+}

package/src/foundry/client/apps/hud/container.d.mts

@@ -0,0 +1,54 @@
+import type { MaybePromise } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * Render the HUD container
+   * @typeParam Options - the type of the options object
+   */
+  class HeadsUpDisplay<Options extends ApplicationOptions = ApplicationOptions> extends Application<Options> {
+    /**
+     * Token HUD
+     */
+    token: TokenHUD;
+
+    /**
+     * Tile HUD
+     */
+    tile: TileHUD;
+
+    /**
+     * Drawing HUD
+     */
+    drawing: DrawingHUD;
+
+    /**
+     * Chat Bubbles
+     */
+    bubbles: ChatBubbles;
+
+    /**
+     * @defaultValue
+     * ```
+     * mergeObject(super.defaultOptions, {
+     *   id: "hud",
+     *   template: "templates/hud/hud.html",
+     *   popOut: false,
+     * })
+     * ```
+     */
+    static override get defaultOptions(): ApplicationOptions;
+
+    override getData(options?: Partial<Options>): MaybePromise<object>;
+
+    protected override _render(force?: boolean, options?: Application.RenderOptions<Options>): Promise<void>;
+
+    /**
+     * Align the position of the HUD layer to the current position of the canvas
+     */
+    align(): void;
+  }
+
+  namespace HeadsUpDisplay {
+    type Any = HeadsUpDisplay<any>;
+  }
+}

package/src/foundry/client/apps/hud/controls.d.mts

@@ -0,0 +1,166 @@
+export {};
+
+declare global {
+  interface SceneControlToolBase {
+    name: string;
+    title: string;
+    icon: string;
+    visible?: boolean;
+    active?: boolean;
+    toolclip?: ToolclipConfiguration;
+  }
+
+  interface SceneControlToolToggle extends SceneControlToolBase {
+    toggle: true;
+    onClick?: (toggled: boolean) => void;
+  }
+
+  interface SceneControlToolNoToggle extends SceneControlToolBase {
+    toggle?: false;
+    button?: boolean;
+    onClick?: () => void;
+  }
+
+  type SceneControlTool = SceneControlToolToggle | SceneControlToolNoToggle;
+
+  interface SceneControl {
+    name: string;
+    title: string;
+    layer: string;
+    icon: string;
+    visible: boolean;
+    tools: SceneControlTool[];
+    activeTool: string;
+  }
+
+  interface ToolclipConfiguration {
+    /** The filename of the toolclip video. */
+    src: string;
+
+    /** The heading string. */
+    heading: string;
+
+    /** The items in the toolclip body. */
+    items: ToolclipConfigurationItem[];
+  }
+
+  interface ToolclipConfigurationItem {
+    /** A plain paragraph of content for this item. */
+    paragraph?: string;
+
+    /** A heading for the item. */
+    heading?: string;
+
+    /** Content for the item. */
+    content?: string;
+
+    /** If the item is a single key reference, use this instead of content. */
+    reference?: string;
+  }
+
+  /**
+   * Scene controls navigation menu
+   * @typeParam Options - the type of the options object
+   */
+  class SceneControls<Options extends ApplicationOptions = ApplicationOptions> extends Application<Options> {
+    constructor(options?: Partial<Options>);
+
+    /**
+     * The name of the active Scene Control toolset
+     * @defaultValue `"token"`
+     */
+    activeControl: string;
+
+    /**
+     * The Array of Scene Control buttons which are currently rendered
+     */
+    controls: SceneControl[];
+
+    /**
+     * @defaultValue
+     * ```
+     * foundry.utils.mergeObject(super.defaultOptions, {
+     *   width: 100,
+     *   id: "controls",
+     *   template: "templates/hud/controls.html",
+     *   popOut: false,
+     * })
+     * ```
+     */
+    static override get defaultOptions(): ApplicationOptions;
+
+    /**
+     * Return the active control set
+     */
+    get control(): SceneControl | null;
+
+    /**
+     * Return the name of the active tool within the active control set
+     */
+    get activeTool(): string | null;
+
+    /**
+     * Return the actively controlled tool
+     */
+    get tool(): SceneControlTool | null;
+
+    /**
+     * A convenience reference for whether the currently active tool is a Ruler
+     */
+    get isRuler(): boolean;
+
+    /**
+     * Initialize the Scene Controls by obtaining the set of control buttons and rendering the HTML
+     * @param options - Options which modify how the controls UI is initialized
+     *                  (defaultValue: `{}`)
+     */
+    initialize(options?: InitializeOptions): void;
+
+    override getData(options?: Partial<Options>): {
+      controls: SceneControl[];
+      active: boolean;
+      cssClass: "" | "disabled";
+    };
+
+    override activateListeners(html: JQuery): void;
+
+    /**
+     * Handle click events on a Control set
+     * @param event - A click event on a tool control
+     */
+    protected _onClickLayer(event: JQuery.ClickEvent): void;
+
+    /**
+     * Handle click events on Tool controls
+     * @param event - A click event on a tool control
+     */
+    protected _onClickTool(event: JQuery.ClickEvent): void;
+
+    /**
+     * Get the set of Control sets and tools that are rendered as the Scene Controls.
+     * These controls may be extended using the "getSceneControlButtons" Hook.
+     */
+    protected _getControlButtons(): SceneControl[];
+  }
+
+  namespace SceneControls {
+    type Any = SceneControls<any>;
+  }
+
+  interface InitializeOptions {
+    /**
+     * An optional control set to set as active
+     */
+    control?: string;
+
+    /**
+     * An optional layer name to target as the active control
+     */
+    layer?: string;
+
+    /**
+     * A specific named tool to set as active for the palette
+     */
+    tool?: string;
+  }
+}

package/src/foundry/client/apps/hud/hotbar.d.mts

@@ -0,0 +1,169 @@
+import type { GetDataReturnType, MaybePromise } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * The global action bar displayed at the bottom of the game view.
+   * The Hotbar is a UI element at the bottom of the screen which contains Macros as interactive buttons.
+   * The Hotbar supports 5 pages of global macros which can be dragged and dropped to organize as you wish.
+   *
+   * Left-clicking a Macro button triggers its effect.
+   * Right-clicking the button displays a context menu of Macro options.
+   * The number keys 1 through 0 activate numbered hotbar slots.
+   * Pressing the delete key while hovering over a Macro will remove it from the bar.
+   *
+   * @see {@link Macros}
+   * @see {@link Macro}
+   *
+   * @typeParam Options - the type of the options object
+   */
+  class Hotbar<Options extends ApplicationOptions = ApplicationOptions> extends Application<Options> {
+    constructor(options?: Partial<Options>);
+
+    /**
+     * The currently viewed macro page
+     * @defaultValue `1`
+     */
+    page: number;
+
+    /**
+     * The currently displayed set of macros
+     * @defaultValue `[]`
+     */
+    macros: Macro.ConfiguredInstance[];
+
+    /**
+     * Track collapsed state
+     * @defaultValue `false`
+     */
+    protected _collapsed: boolean;
+
+    /**
+     * Track which hotbar slot is the current hover target, if any
+     * @defaultValue `null`
+     */
+    protected _hover: number | null;
+
+    /**
+     * @defaultValue
+     * ```typescript
+     * mergeObject(super.defaultOptions, {
+     *   id: "hotbar",
+     *   template: "templates/hud/hotbar.html",
+     *   popOut: false,
+     *   dragDrop: [{ dragSelector: ".macro-icon", dropSelector: "#macro-list" }]
+     * })
+     * ```
+     */
+    static override get defaultOptions(): ApplicationOptions;
+
+    override getData(options?: Partial<Options>): MaybePromise<GetDataReturnType<Hotbar.HotbarData>>;
+
+    /**
+     * Whether the hotbar is locked.
+     */
+    get locked(): boolean;
+
+    /**
+     * Get the Array of Macro (or null) values that should be displayed on a numbered page of the bar
+     * @param page -
+     */
+    protected _getMacrosByPage(page: number): Macro.ConfiguredInstance[];
+
+    /**
+     * Collapse the Hotbar, minimizing its display.
+     * @returns A promise which resolves once the collapse animation completes
+     */
+    collapse(): Promise<boolean>;
+
+    /**
+     * Expand the Hotbar, displaying it normally.
+     * @returns A promise which resolves once the expand animation completes
+     */
+    expand(): Promise<boolean>;
+
+    /**
+     * Change to a specific numbered page from 1 to 5
+     * @param page - The page number to change to.
+     *               (default: `1` )
+     */
+    changePage(page?: number): void;
+
+    /**
+     * Change the page of the hotbar by cycling up (positive) or down (negative)
+     * @param direction - The direction to cycle
+     */
+    cyclePage(direction?: number): void;
+
+    override activateListeners(html: JQuery): void;
+
+    protected override _contextMenu(html: JQuery): void;
+
+    /**
+     * Get the Macro entry context options
+     * @returns The Macro entry context options
+     * @internal
+     */
+    protected _getEntryContextOptions(): ContextMenuEntry[];
+
+    /**
+     * Handle left-click events to
+     * @param event - The originating click event
+     */
+    protected _onClickMacro(event: JQuery.ClickEvent): Promise<void>;
+
+    /**
+     * Handle pagination controls
+     * @param event - The originating click event
+     */
+    protected _onClickPageControl(event: JQuery.ClickEvent): void;
+
+    protected override _canDragStart(selector: string): boolean;
+
+    protected override _onDragStart(event: DragEvent): false | void;
+
+    protected override _canDragDrop(selector: string): boolean;
+
+    protected override _onDrop(event: DragEvent): void;
+
+    /**
+     * Create a Macro which rolls a RollTable when executed
+     * @param table - The RollTable document
+     */
+    protected _createRollTableRollMacro(table: RollTable): Promise<Macro.ConfiguredInstance>;
+
+    /**
+     * Create a Macro document which can be used to toggle display of a Journal Entry.
+     * @param doc - A Document which should be toggled
+     * @returns A created Macro document to add to the bar
+     */
+    protected _createDocumentSheetToggle(doc: ClientDocument): Promise<Macro.ConfiguredInstance>;
+
+    /**
+     * Handle click events to toggle display of the macro bar
+     */
+    protected _onToggleBar(event: JQuery.ClickEvent): void;
+
+    /**
+     * Toggle the hotbar's lock state
+     */
+    protected _toggleHotBarLock(): Promise<this>;
+
+    /**
+     * Handle toggling a document sheet.
+     * @param uuid - The Document UUID to display
+     * @remarks Returns a ui notification number if doc could not be found
+     */
+    static toggleDocumentSheet(uuid: string): Promise<void> | Application | number;
+  }
+
+  namespace Hotbar {
+    type Any = Hotbar<any>;
+
+    interface HotbarData {
+      page: Hotbar["page"];
+      macros: Hotbar["macros"];
+      barClass: "collapsed" | "";
+      locked: boolean;
+    }
+  }
+}

package/src/foundry/client/apps/hud/hud.d.mts

@@ -0,0 +1,87 @@
+import type { MaybePromise } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * An abstract base class for displaying a heads-up-display interface bound to a Placeable Object on the canvas
+   * @typeParam Object - the type of the PlaceableObject
+   * @typeParam Options - the type of the options object
+   */
+  abstract class BasePlaceableHUD<
+    Object extends PlaceableObject.Any = PlaceableObject,
+    Options extends ApplicationOptions = ApplicationOptions,
+  > extends Application<Options> {
+    /**
+     * Reference a PlaceableObject this HUD is currently bound to
+     * @defaultValue `undefined`
+     */
+    object: Object | undefined;
+
+    /**
+     * @defaultValue
+     * ```
+     * foundry.utils.mergeObject(super.defaultOptions, {
+     *   classes: ["placeable-hud"],
+     *   popOut: false
+     * })
+     * ```
+     */
+    static override get defaultOptions(): ApplicationOptions;
+
+    /**
+     * Convenience access for the canvas layer which this HUD modifies
+     * @remarks Returns undefined only if there's no object
+     */
+    get layer(): Object["layer"] | undefined;
+
+    /**
+     * Bind the HUD to a new PlaceableObject and display it
+     * @param object - A PlaceableObject instance to which the HUD should be bound
+     */
+    bind(object: Object): void;
+
+    /**
+     * Clear the HUD by fading out it's active HTML and recording the new display state
+     */
+    clear(): void;
+
+    override _render(...args: Parameters<Application<Options>["_render"]>): Promise<void>;
+
+    override getData(options?: Partial<Options>): MaybePromise<object>;
+
+    override setPosition({ left, top, width, height, scale }?: Partial<Application.Position>): void;
+
+    override activateListeners(html: JQuery): void;
+
+    /**
+     * Handle mouse clicks to control a HUD control button
+     * @param event - The originating click event
+     * @remarks This will always return a promise with documents is overridden by TokenHUD.
+     */
+    protected _onClickControl(event: JQuery.ClickEvent): void;
+
+    /**
+     * Toggle the visible state of all controlled objects in the Layer
+     * @param event - The originating click event
+     * @internal
+     */
+    protected _onToggleVisibility(event: JQuery.ClickEvent): Promise<Array<Object["document"]>>;
+
+    /**
+     * Toggle locked state of all controlled objects in the Layer
+     * @param event - The originating click event
+     * @internal
+     */
+    protected _onToggleLocked(event: JQuery.ClickEvent): Promise<Array<Object["document"]>>;
+
+    /**
+     * Handle sorting the z-order of the object
+     * @param up    - Move the object upwards in the vertical stack?
+     * @param event - The originating mouse click event
+     */
+    protected _onSort(up: boolean, event: JQuery.ClickEvent): Promise<Array<Object["document"]>>;
+  }
+
+  namespace BasePlaceableHUD {
+    type Any = BasePlaceableHUD<any, any>;
+  }
+}

package/src/foundry/client/apps/hud/index.d.mts

@@ -0,0 +1,9 @@
+import "./chatbubble.d.mts";
+import "./container.d.mts";
+import "./controls.d.mts";
+import "./hotbar.d.mts";
+import "./hud.d.mts";
+import "./menu.d.mts";
+import "./navigation.d.mts";
+import "./pause.d.mts";
+import "./players.d.mts";

package/src/foundry/client/apps/hud/menu.d.mts

@@ -0,0 +1,77 @@
+import type { MaybePromise } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * The main menu application which is toggled via the ESC key.
+   */
+  class MainMenu extends Application {
+    /**
+     * @defaultValue
+     * ```typescript
+     * return foundry.utils.mergeObject(super.defaultOptions, {
+     *   id: "menu",
+     *   template: "templates/hud/menu.html",
+     *   popOut: false
+     * });
+     * ```
+     * */
+    static override get defaultOptions(): ApplicationOptions;
+
+    /**
+     * The structure of menu items
+     * @defaultValue
+     * ```typescript
+     * {
+     *   reload: {
+     *     label: "MENU.Reload",
+     *     icon: "<i class="fas fa-redo"></i>",
+     *     enabled: true,
+     *     onClick: () => window.location.reload()
+     *   },
+     *   logout: {
+     *     label: "MENU.Logout",
+     *     icon: "<i class="fas fa-user"></i>",
+     *     enabled: true,
+     *     onClick: () => game.logOut()
+     *   },
+     *   players: {
+     *     label: "MENU.Players",
+     *     icon: "<i class="fas fa-users"></i>",
+     *     enabled: game.user.isGM && !game.data.demoMode,
+     *     onClick: () => (window.location.href = "./players")
+     *   },
+     *   world: {
+     *     label: "GAME.ReturnSetup",
+     *     icon: "<i class="fas fa-globe"></i>",
+     *     enabled: game.user.hasRole("GAMEMASTER")  && !game.data.demoMode,
+     *     onClick: () => {
+     *       this.close();
+     *       game.shutDown();
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    get items(): MainMenu.MenuStructure;
+
+    override getData(options?: Partial<ApplicationOptions>): MaybePromise<object>;
+
+    override activateListeners(html: JQuery): void;
+
+    /**
+     * Toggle display of the menu (or render it in the first place)
+     */
+    toggle(): void;
+  }
+
+  namespace MainMenu {
+    interface MenuItem {
+      label: string;
+      icon: string;
+      enabled: boolean;
+      onClick: () => void;
+    }
+
+    type MenuStructure = Record<string, MenuItem>;
+  }
+}