@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.345.1-beta.20250704.94554

package/src/foundry/client/applications/ui/scene-controls.d.mts

@@ -0,0 +1,117 @@
+import type { Identity } from "#utils";
+import type ApplicationV2 from "../api/application.d.mts";
+import type HandlebarsApplicationMixin from "../api/handlebars-application.d.mts";
+
+declare module "#configuration" {
+  namespace Hooks {
+    interface ApplicationV2Config {
+      SceneControls: SceneControls.Any;
+    }
+  }
+}
+
+/**
+ * The Scene Controls UI element.
+ * @remarks TODO: Stub
+ */
+declare class SceneControls<
+  RenderContext extends SceneControls.RenderContext = SceneControls.RenderContext,
+  Configuration extends SceneControls.Configuration = SceneControls.Configuration,
+  RenderOptions extends SceneControls.RenderOptions = SceneControls.RenderOptions,
+> extends HandlebarsApplicationMixin(ApplicationV2)<RenderContext, Configuration, RenderOptions> {}
+
+declare namespace SceneControls {
+  interface Any extends AnySceneControls {}
+  interface AnyConstructor extends Identity<typeof AnySceneControls> {}
+
+  /**
+   * @remarks Foundry's override of `_prepareContext` does not call `super`. Therefore it does not
+   * inherit context from its parent class.
+   */
+  interface RenderContext {
+    controls: Control[];
+    tools: Tool[];
+  }
+
+  /**
+   * The data structure for a set of controls in the {@link SceneControls#controls} record.
+   */
+  interface Control {
+    name: string;
+    order: number;
+    title: string;
+    icon: string;
+    visible?: boolean | undefined;
+    tools: Record<string, Tool>;
+
+    /**
+     * @remarks Should be an key in {@linkcode Control.tools | this.tools}.
+     */
+    activeTool: string;
+
+    /** A callback invoked when control set is activated or deactivated */
+    onChange?: ((event: Event, active: boolean) => void) | undefined;
+
+    /** A callback invoked when the active tool changes */
+    onToolChange?: ((event: Event, tool: Tool) => void) | undefined;
+  }
+
+  /**
+   * The data structure for a single tool in the {@link Control#tools} record.
+   */
+  interface Tool {
+    name: string;
+    order: number;
+    title: string;
+    icon: string;
+
+    visible?: boolean | undefined;
+    toggle?: boolean | undefined;
+    active?: boolean | undefined;
+    button?: boolean | undefined;
+
+    /** A callback invoked when the tool is activated or deactivated */
+    onChange?: ((event: Event, active: boolean) => void) | undefined;
+
+    /** Configuration for rendering the tool's toolclip */
+    toolclip?: ToolclipConfiguration | undefined;
+  }
+
+  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;
+  }
+
+  interface Configuration extends ApplicationV2.Configuration {}
+  interface RenderOptions extends ApplicationV2.RenderOptions {}
+}
+
+declare abstract class AnySceneControls extends SceneControls<
+  SceneControls.RenderContext,
+  SceneControls.Configuration,
+  SceneControls.RenderOptions
+> {
+  constructor(...args: never);
+}
+
+export default SceneControls;

package/src/foundry/client/applications/ui/scene-navigation.d.mts

@@ -0,0 +1,55 @@
+import type { Identity } from "#utils";
+import type ApplicationV2 from "../api/application.d.mts";
+import type HandlebarsApplicationMixin from "../api/handlebars-application.d.mts";
+
+declare module "#configuration" {
+  namespace Hooks {
+    interface ApplicationV2Config {
+      SceneNavigation: SceneNavigation.Any;
+    }
+  }
+}
+
+/**
+ * The Scene Navigation UI element.
+ * @remarks TODO: Stub
+ */
+declare class SceneNavigation<
+  RenderContext extends SceneNavigation.RenderContext = SceneNavigation.RenderContext,
+  Configuration extends SceneNavigation.Configuration = SceneNavigation.Configuration,
+  RenderOptions extends SceneNavigation.RenderOptions = SceneNavigation.RenderOptions,
+> extends HandlebarsApplicationMixin(ApplicationV2)<RenderContext, Configuration, RenderOptions> {}
+
+declare namespace SceneNavigation {
+  interface Any extends AnySceneNavigation {}
+  interface AnyConstructor extends Identity<typeof AnySceneNavigation> {}
+
+  interface PreparedScene {
+    id: string;
+  }
+
+  /**
+   * @remarks Foundry's override of `_prepareContext` does not call `super`. Therefore it does not
+   * inherit context from its parent class.
+   */
+  interface RenderContext {
+    scenes: {
+      inactive: PreparedScene[];
+      active: PreparedScene[];
+    };
+    canExpand: number;
+  }
+
+  interface Configuration extends HandlebarsApplicationMixin.Configuration, ApplicationV2.Configuration {}
+  interface RenderOptions extends HandlebarsApplicationMixin.RenderOptions, ApplicationV2.RenderOptions {}
+}
+
+declare abstract class AnySceneNavigation extends SceneNavigation<
+  SceneNavigation.RenderContext,
+  SceneNavigation.Configuration,
+  SceneNavigation.RenderOptions
+> {
+  constructor(...args: never);
+}
+
+export default SceneNavigation;

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

@@ -0,0 +1,327 @@
+import type { Coalesce, Identity } from "#utils";
+import type Application from "#client/appv1/api/application-v1.d.mts";
+
+/**
+ * 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.
+ */
+declare class ContextMenu<UsesJQuery extends boolean = true> {
+  /**
+   * @param container - The containing HTML element within which the menu is positioned
+   * @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,
+    selector: string | null | undefined,
+    menuItems: ContextMenu.Entry<HTMLElement>[],
+    options: ContextMenu.ConstructorOptions<false>,
+  );
+
+  /**
+   * @deprecated "ContextMenu is changing to no longer transact jQuery objects for menu item callbacks.
+   * Because the jQuery option provided to the ContextMenu constructor was undefined, your  callbacks will receive jQuery objects.
+   * You may opt-out and receive HTMLElement references instead by passing jQuery: false to the constructor.
+   * This parameter will be false by default in v14 and deprecated entirely in v15 at which point only HTMLElement references will be used."
+   */
+  constructor(
+    element: HTMLElement | JQuery,
+    selector: string | null | undefined,
+    menuItems: ContextMenu.Entry<HTMLElement | JQuery>[],
+    options?: Omit<ContextMenu.ConstructorOptions<UsesJQuery>, "jQuery"> & { jQuery?: false | undefined },
+  );
+
+  /**
+   * Create a ContextMenu for this Application and dispatch hooks.
+   * @param app       - The Application this ContextMenu belongs to.
+   * @param html      - The Application's rendered HTML.
+   * @param selector  - The target CSS selector which activates the menu.
+   * @param menuItems - The array of menu items being rendered.
+   * @param options   - Additional options to configure context menu initialization. (default: `"EntryContext"`)
+   *
+   * @deprecated "ContextMenu.create is deprecated and only supports Application (v1) instances."
+   */
+  static create<UsesJQuery extends boolean | undefined = true>(
+    app: Application.Any | foundry.applications.api.ApplicationV2.Any,
+    html: HTMLElement | JQuery,
+    selector: string,
+    menuItems: ContextMenu.Entry<ContextMenu.JQueryOrHTML<UsesJQuery>>[],
+    options: Omit<ContextMenu.CreateOptions<never>, "jQuery"> & { jQuery?: false | undefined },
+  ): ContextMenu<Coalesce<UsesJQuery, true>>;
+
+  /**
+   * The menu element.
+   */
+  get element(): HTMLElement;
+
+  /**
+   * A CSS selector to identify context menu targets.
+   * @defaultValue `container.attr("id")`
+   */
+  get selector(): string;
+
+  /**
+   * The event name to listen for.
+   * @defaultValue `"contextmenu"`
+   */
+  get eventName(): string;
+
+  /**
+   * The array of menu items to render.
+   */
+  menuItems: ContextMenu.Entry<ContextMenu.JQueryOrHTML<UsesJQuery>>[];
+
+  /**
+   * A function to call when the context menu is opened.
+   */
+  onOpen: ContextMenu.ContextMenuCallback | null | undefined;
+
+  /**
+   * A function to call when the context menu is closed.
+   */
+  onClose: ContextMenu.ContextMenuCallback | null | undefined;
+
+  /**
+   * Check which direction the menu is expanded in.
+   * @defaultValue `false`
+   */
+  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;
+
+  /**
+   * 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.
+   *                  (default: `{}`)
+   */
+  close(options?: ContextMenu.CloseOptions): Promise<void>;
+
+  /**
+   * Close the menu and remove it from the DOM.
+   * @param options - (default: `{}`)
+   */
+  protected _close({ target }: ContextMenu.CloseOptions): void;
+
+  /**
+   * Called before the context menu begins rendering.
+   * @param target - The context target
+   * @param options - (default: `{}`)
+   */
+  protected _preRender(target: HTMLElement, options?: ContextMenu.RenderOptions): 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
+   * @param target  - The target element to which the context menu is attached
+   * @param options - (default: `{}`)
+   */
+  render(target: HTMLElement, options?: ContextMenu.RenderOptions): Promise<void>;
+
+  /**
+   * Called after the context menu has finished rendering and animating open.
+   * @param options - (default: `{}`)
+   */
+  protected _onRender(options?: ContextMenu.RenderOptions): Promise<void>;
+
+  /**
+   * Set the position of the context menu, taking into consideration whether the menu should expand upward or downward
+   * @param html    - The context menu element.
+   * @param target  - The element that the context menu was spawned on.
+   * @param options - (default: `{}`)
+   */
+  protected _setPosition(html: HTMLElement, target: HTMLElement, options?: ContextMenu.RenderOptions): 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 html    - The menu element.
+   * @param target  - The context target.
+   * @param options - (default: `{}`)
+   */
+  protected _setFixedPosition(menu: HTMLElement, target: HTMLElement, options?: ContextMenu.RenderOptions): void;
+
+  /**
+   * Local listeners which apply to each ContextMenu instance which is created.
+   * @param html - The context menu element.
+   */
+  activateListeners(html: HTMLElement): void;
+
+  /**
+   * Handle context menu activation.
+   * @param event - The triggering event.
+   */
+  protected _onActivate(event: PointerEvent): Promise<void>;
+
+  /**
+   * Global listeners which apply once only to the document.
+   */
+  static eventListeners(): void;
+
+  /**
+   * Retrieve the configured DragDrop implementation
+   * @privateRemarks TODO: Config.ux handling
+   */
+  static get implementation(): typeof ContextMenu;
+
+  /**
+   * @deprecated since v13 until v15
+   * @remarks "ContextMenu#_expandUp is deprecated. Please use ContextMenu#expandUp instead."
+   */
+  get _expandUp(): boolean;
+
+  /**
+   * @deprecated since v13 until v15
+   * @remarks "ContextMenu#menu is deprecated. Please use ContextMenu#element instead."
+   */
+  get menu(): JQuery;
+
+  #private: true;
+}
+
+declare namespace ContextMenu {
+  interface Any extends AnyContextMenu {}
+  interface AnyConstructor extends Identity<typeof AnyContextMenu> {}
+
+  interface Entry<ElementType extends JQuery | HTMLElement> {
+    /**
+     * The context menu label. Can be localized.
+     */
+    name: string;
+
+    /**
+     * A string containing an HTML icon element for the menu item
+     */
+    icon?: string;
+
+    /**
+     * An identifier for a group this entry belongs to.
+     * @defaultValue `_none`
+     */
+    group?: string | null | undefined;
+
+    /**
+     * The element that the context menu has been triggered for. Will
+     * either be a jQuery object or an HTMLElement instance, depending
+     * on how the ContextMenu was configured.
+     */
+    callback: (target: ElementType) => void;
+
+    /**
+     * A function to call or boolean value to determine if this entry
+     * appears in the menu.
+     * @remarks `null` equivalent to `false`
+     */
+    condition?: boolean | Condition<ElementType> | null | undefined;
+  }
+
+  /**
+   * @param html - The element of the context menu entry.
+   * @returns Whether the entry should be rendered in the context menu.
+   * @remarks `null` equivalent to `false`
+   */
+  type Condition<ElementType extends JQuery | HTMLElement> = (target: ElementType) => boolean | null;
+
+  interface RenderOptions {
+    /**
+     * The event that triggered the context menu opening.
+     */
+    event?: PointerEvent | undefined | null;
+
+    /**
+     * Animate the context menu opening
+     * @defaultValue `true`
+     * @remarks No null because an explicit check for `options.animate !== false` would treat null as truthy
+     */
+    animate?: boolean | undefined;
+  }
+
+  interface CloseOptions {
+    /**
+     * Animate the context menu closing.
+     * @defaultValue `true`
+     * @remarks `null` equivalent to `false`
+     */
+    animate?: boolean | null;
+
+    /**
+     * The target element to close on.
+     */
+    target: HTMLElement;
+  }
+
+  type ContextMenuCallback =
+    /**
+     * @param target - The element that the context menu has been triggered for.
+     */
+    (target: HTMLElement) => void;
+
+  interface ConstructorOptions<IsJQuery extends boolean = true> {
+    /**
+     * Optionally override the triggering event which can spawn the menu. If the menu is using a fixed position, this event must be a MouseEvent
+     * @defaultValue `"contextmenu"`
+     */
+    eventName?: string;
+
+    /**
+     * A function to call when the context menu is opened.
+     */
+    onOpen?: ContextMenuCallback | null | undefined;
+
+    /**
+     * A function to call when the context menu is closed.
+     */
+    onClose?: ContextMenuCallback | null | undefined;
+
+    /**
+     * If true, callbacks will be passed jQuery objects instead of HTMLElement instances
+     * @defaultValue `true`
+     */
+    jQuery: IsJQuery;
+
+    /**
+     * If true, the context menu is given a fixed position rather than being injected into the target.
+     * @defaultValue `false`
+     */
+    fixed?: boolean | undefined;
+  }
+
+  interface CreateOptions<IsJQuery extends boolean = true> extends ConstructorOptions<IsJQuery> {
+    /**
+     * The name of the hook to call
+     * @defaultValue `EntryContext`
+     */
+    hookName?: string;
+  }
+
+  type JQueryOrHTML<IsJQuery extends boolean | undefined> = IsJQuery extends false | undefined ? HTMLElement : JQuery;
+}
+
+declare abstract class AnyContextMenu extends ContextMenu<boolean> {
+  constructor(...args: never);
+}
+
+export default ContextMenu;

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

@@ -0,0 +1,167 @@
+import type { Identity, InexactPartial } from "#utils";
+
+/**
+ * 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);
+ * ```
+ */
+declare class DragDrop {
+  /**
+   * @param options - (default: `{}`)
+   */
+  constructor({ dragSelector, dropSelector, permissions, callbacks }?: DragDrop.Configuration);
+
+  /**
+   * A set of callback functions for each action of the drag & drop workflow.
+   * @defaultValue `{}`
+   */
+  callbacks: DragDrop.Callbacks;
+
+  /**
+   * 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;
+
+  /**
+   * A set of functions to control authorization to begin drag workflows, and drop content.
+   * @defaultValue `{}`
+   */
+  permissions: DragDrop.Permissions;
+
+  /**
+   * 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.PermissionKey, selector?: DragDrop.DragSelector): boolean;
+
+  /**
+   * Handle the start of a drag workflow
+   * @param event - The drag event being handled
+   * @internal
+   */
+  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
+   * @internal
+   */
+  protected _handleDragOver(event: DragEvent): void;
+
+  /**
+   * Handle a dragged element dropped on a droppable target
+   * @param event - The drag event being handled
+   * @internal
+   */
+  protected _handleDrop(event: DragEvent): void;
+
+  /**
+   * A helper to create an image preview element for use during HTML element dragging.
+   */
+  static createDragImage(img: HTMLImageElement, width: number, height: number): HTMLDivElement;
+
+  /**
+   * Retrieve the configured DragDrop implementation.
+   */
+  static get implementation(): typeof DragDrop;
+}
+
+declare namespace DragDrop {
+  interface Any extends AnyDragDrop {}
+  interface AnyConstructor extends Identity<typeof AnyDragDrop> {}
+
+  type Action = "dragstart" | "dragover" | "drop" | "dragenter" | "dragleave" | "dragend";
+
+  type PermissionKey = "dragstart" | "drop";
+
+  type DragSelector = string | null | undefined;
+
+  interface Callbacks extends InexactPartial<Record<Action, (event: DragEvent) => void>> {}
+
+  interface Permissions extends Partial<Record<PermissionKey, (selector: DragSelector) => boolean>> {}
+
+  /** @internal */
+  interface _Configuration {
+    /**
+     * The CSS selector used to target draggable elements.
+     * @defaultValue `null`
+     */
+    dragSelector?: DragDrop["dragSelector"];
+
+    /**
+     * The CSS selector used to target viable drop targets.
+     * @defaultValue `null`
+     */
+    dropSelector?: DragDrop["dropSelector"];
+
+    /**
+     * Permission tests for each action
+     * @defaultValue `{}`
+     */
+    permissions?: DragDrop["permissions"];
+
+    /**
+     * Callback functions for each action
+     * @defaultValue `{}`
+     */
+    callbacks: Callbacks;
+  }
+
+  interface Configuration extends InexactPartial<_Configuration> {}
+}
+
+declare abstract class AnyDragDrop extends DragDrop {
+  constructor(...args: never);
+}
+
+export default DragDrop;