@league-of-foundry-developers/foundry-vtt-types 9.255.2 → 9.268.1

package/src/foundry/{foundry.js/contextMenu.d.ts → client/ui/context.d.ts}

@@ -1,3 +1,25 @@
+interface ContextMenuEntry {
+  /**
+   * The context menu label. Can be localized.
+   */
+  name: string;
+
+  /**
+   * A string containing an HTML icon element for the menu item
+   */
+  icon: string;
+
+  /**
+   * The function to call when the menu item is clicked. Receives the HTML element of the SidebarTab entry that this context menu is for.
+   */
+  callback: (target: JQuery) => void;
+
+  /**
+   * A function to call to determine if this item appears in the menu. Receives the HTML element of the SidebarTab entry that this context menu is for.
+   */
+  condition?: boolean | ((target: JQuery) => 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
@@ -14,7 +36,7 @@ declare class ContextMenu {
   constructor(
     element: JQuery,
     selector: string | null | undefined,
-    menuItems: ContextMenu.Item[],
+    menuItems: ContextMenuEntry[],
     { eventName }?: { eventName?: string }
   );
 
@@ -37,7 +59,7 @@ declare class ContextMenu {
   /**
    * The array of menu items being rendered
    */
-  menuItems: ContextMenu.Item[];
+  menuItems: ContextMenuEntry[];
 
   /**
    * Track which direction the menu is expanded in
@@ -50,18 +72,41 @@ declare class ContextMenu {
    */
   get menu(): JQuery;
 
+  /**
+   * 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 hookName  - The name of the hook to call.
+   *                    (default: `'EntryContext'`)
+   */
+  static create(
+    app: Application,
+    html: JQuery,
+    selector: string,
+    menuItems: ContextMenuEntry[],
+    hookName?: string
+  ): ContextMenu;
+
   /**
    * Attach a ContextMenu instance to an HTML selector
    */
   bind(): void;
 
   /**
-   * Animate closing the menu by sliding up and removing from the DOM
+   * Closes the menu and removes it from the DOM.
+   * @param options - Options to configure the closing behavior.
    */
-  close(): Promise<void>;
+  close(options?: ContextMenu.CloseOptions | undefined): Promise<void>;
+
+  /** @internal */
+  protected _close(): void;
 
+  /** @internal */
   protected _animateOpen(menu: JQuery): Promise<void>;
 
+  /** @internal */
   protected _animateClose(menu: JQuery): Promise<void>;
 
   /**
@@ -80,48 +125,12 @@ declare class ContextMenu {
   static eventListeners(): void;
 }
 
-interface ContextMenuEntry {
-  /**
-   * The context menu label. Can be localized.
-   */
-  name: string;
-
-  /**
-   * A string containing an HTML icon element for the menu item
-   */
-  icon: string;
-
-  /**
-   * The function to call when the menu item is clicked. Receives the HTML element of the SidebarTab entry that this context menu is for.
-   */
-  callback: (target: JQuery) => void;
-
-  /**
-   * A function to call to determine if this item appears in the menu. Receives the HTML element of the SidebarTab entry that this context menu is for.
-   */
-  condition?: boolean | ((target: JQuery) => boolean);
-}
-
 declare namespace ContextMenu {
-  interface Item {
-    /**
-     * The displayed item name
-     */
-    name: string;
-
-    /**
-     * An icon glyph HTML string
-     */
-    icon: string;
-
-    /**
-     * A function which returns a Boolean for whether or not to display the item
-     */
-    condition?: boolean | ((target: JQuery) => boolean);
-
+  interface CloseOptions {
     /**
-     * A callback function to trigger when the entry of the menu is clicked
+     * Animate the context menu closing.
+     * @defaultValue `true`
      */
-    callback: (target: JQuery) => void;
+    animate?: boolean;
   }
 }

package/src/foundry/{foundry.js/applications → client/ui}/dialog.d.ts

@@ -46,7 +46,6 @@ declare class Dialog<Options extends DialogOptions = DialogOptions> extends Appl
   data: Dialog.Data;
 
   /**
-   * @override
    * @defaultValue
    * ```typescript
    * foundry.utils.mergeObject(super.defaultOptions, {
@@ -57,22 +56,13 @@ declare class Dialog<Options extends DialogOptions = DialogOptions> extends Appl
    * })
    * ```
    */
-  static get defaultOptions(): DialogOptions;
+  static override get defaultOptions(): DialogOptions;
 
-  /**
-   * @override
-   */
   static get title(): string;
 
-  /**
-   * @override
-   */
-  getData(options?: Partial<Options>): { content: string; buttons: Record<string, Dialog.Button> };
+  override getData(options?: Partial<Options>): { content: string; buttons: Record<string, Dialog.Button> };
 
-  /**
-   * @override
-   */
-  activateListeners(html: JQuery): void;
+  override activateListeners(html: JQuery): void;
 
   /**
    * Handle a left-mouse click on one of the dialog choice buttons
@@ -93,10 +83,7 @@ declare class Dialog<Options extends DialogOptions = DialogOptions> extends Appl
    */
   protected submit(button: Dialog.Button): void;
 
-  /**
-   * @override
-   */
-  close(options?: Application.CloseOptions): Promise<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.

package/src/foundry/client/ui/editor.d.ts

@@ -0,0 +1,321 @@
+import type { ConfiguredDocumentClassForName } from '../../../types/helperTypes';
+
+declare global {
+  /**
+   * A collection of helper functions and utility methods related to the rich text editor
+   */
+  class TextEditor {
+    /**
+     * Create a Rich Text Editor. The current implementation uses TinyMCE
+     * @param options - Configuration options provided to the Editor init
+     * @param content - Initial HTML or text content to populate the editor with
+     *                  (default: `""`)
+     * @returns The editor instance.
+     */
+    static create(options: TextEditor.Options, content: string): Promise<tinyMCE.Editor>;
+
+    /**
+     * A list of elements that are retained when truncating HTML.
+     * @internal
+     */
+    protected static _PARAGRAPH_ELEMENTS: Set<string>;
+
+    /**
+     * Safely decode an HTML string, removing invalid tags and converting entities back to unicode characters.
+     * @param html - The original encoded HTML string
+     * @returns The decoded unicode string
+     */
+    static decodeHTML(html: string): string;
+
+    /**
+     * Enrich HTML content by replacing or augmenting components of it
+     * @param content  - The original HTML content (as a string)
+     * @param options  - Additional options which configure how HTML is enriched
+     *                   (default: `{}`)
+     * @returns The enriched HTML content
+     */
+    static enrichHTML(content: string, options?: Partial<TextEditor.EnrichOptions>): string;
+
+    /**
+     * Preview an HTML fragment by constructing a substring of a given length from its inner text.
+     * @param content - The raw HTML to preview
+     * @param length  - The desired length
+     *                  (default: `250`)
+     * @returns The previewed HTML
+     */
+    static previewHTML(content: string, length?: number): string;
+
+    /**
+     * Sanitises an HTML fragment and removes any non-paragraph-style text.
+     * @param html       - The root HTML element.
+     */
+    static truncateHTML(html: HTMLElement): HTMLElement;
+
+    /**
+     * Truncate a fragment of text to a maximum number of characters.
+     * @param text       - The original text fragment that should be truncated to a maximum length
+     * @param maxLength  - The maximum allowed length of the truncated string.
+     *                     (default: `50`)
+     * @param splitWords - Whether to truncate by splitting on white space (if true) or breaking words.
+     *                     (default: `true`)
+     * @param suffix     - A suffix string to append to denote that the text was truncated.
+     *                     (default: `'…'`)
+     */
+    static truncateText(
+      text: string,
+      { maxLength, splitWords, suffix }?: { maxLength?: number; splitWords?: boolean; suffix?: string }
+    ): string;
+
+    /**
+     * Recursively identify the text nodes within a parent HTML node for potential content replacement.
+     * @param parent - The parent HTML Element
+     * @returns An array of contained Text nodes
+     * @internal
+     */
+    protected static _getTextNodes(parent: HTMLElement): Text[];
+
+    /**
+     * Facilitate the replacement of text node content using a matching regex rule and a provided replacement function.
+     * @internal
+     */
+    protected static _replaceTextContent(
+      text: Text[],
+      rgx: RegExp,
+      func: (...match: RegExpMatchArray) => Node
+    ): boolean;
+
+    /**
+     * Replace a matched portion of a Text node with a replacement Node
+     * @internal
+     */
+    protected static _replaceTextNode(text: Text, match: RegExpMatchArray, replacement: Node): void;
+
+    /**
+     * Create a dynamic document link from a regular expression match
+     * @param match  - The full matched string
+     * @param type   - The matched document type or "Compendium"
+     * @param target - The requested match target (_id or name)
+     * @param name   - A customized or over-ridden display name for the link
+     * @returns An HTML element for the document link
+     * @internal
+     */
+    protected static _createContentLink(match: string, type: string, target: string, name: string): HTMLAnchorElement;
+
+    /**
+     * Replace a hyperlink-like string with an actual HTML &lt;a&gt; tag
+     * @param match - The full matched string
+     * @returns An HTML element for the document link
+     * @internal
+     */
+    protected static _createHyperlink(match: string): HTMLAnchorElement;
+
+    /**
+     * Replace an inline roll formula with a rollable &lt;a&gt; element or an eagerly evaluated roll result
+     * @param match   - The matched string
+     * @param command - An optional command
+     * @param formula - The matched formula
+     * @param closing - The closing brackets for the inline roll
+     * @param label   - An optional label which configures the button text
+     * @returns The replaced match
+     * @internal
+     */
+    protected static _createInlineRoll(
+      match: string,
+      command: string,
+      formula: string,
+      closing: string,
+      label?: string,
+      ...args: object[]
+    ): HTMLAnchorElement | null;
+
+    static activateListeners(): void;
+
+    /**
+     * Handle click events on Document Links
+     * @internal
+     */
+    protected static _onClickContentLink(event: MouseEvent): void;
+
+    /**
+     * Handle left-mouse clicks on an inline roll, dispatching the formula or displaying the tooltip
+     * @param event - The initiating click event
+     * @internal
+     */
+    protected static _onClickInlineRoll(event: MouseEvent): void;
+
+    /**
+     * Toggle playing or stopping an embedded {@link PlaylistSound} link.
+     * @param doc - The PlaylistSound document to play/stop.
+     * @internal
+     */
+    protected static _onPlaySound(doc: InstanceType<ConfiguredDocumentClassForName<'PlaylistSound'>>): void;
+
+    /**
+     * Find all content links belonging to a given {@link PlaylistSound}.
+     * @param doc - The PlaylistSound.
+     * @internal
+     */
+    protected static _getSoundContentLinks(
+      doc: InstanceType<ConfiguredDocumentClassForName<'PlaylistSound'>>
+    ): NodeListOf<Element>;
+
+    /**
+     * Begin a Drag+Drop workflow for a dynamic content link
+     * @param event - The originating drag event
+     * @internal
+     */
+    protected static _onDragContentLink(event: DragEvent): void;
+
+    /**
+     * Handle dropping of transferred data onto the active rich text editor
+     * @param event  - The originating drop event which triggered the data transfer
+     * @param editor - The TinyMCE editor instance being dropped on
+     * @internal
+     */
+    protected static _onDropEditorData(event: DragEvent, editor: tinyMCE.Editor): void;
+
+    /**
+     * Extract JSON data from a drag/drop event.
+     * @param event - The drag event which contains JSON data.
+     * @returns The extracted JSON data. The object will be empty if the DragEvent did not contain
+     *          JSON-parseable data.
+     */
+    protected static getDragEventData(event: DragEvent): object;
+
+    /**
+     * Given a Drop event, returns a Content link if possible such as `@Actor[ABC123]`, else null
+     * @param eventData - The parsed object of data provided by the transfer event
+     */
+    // TODO: improve as part of https://github.com/League-of-Foundry-Developers/foundry-vtt-types/issues/928
+    static getContentLink(eventData: object): Promise<string | null>;
+
+    /**
+     * @deprecated since v9 - Use _onDragContentLink instead.
+     * @internal
+     */
+    protected static _onDragEntityLink(
+      ...args: Parameters<typeof TextEditor['_onDragContentLink']>
+    ): ReturnType<typeof TextEditor['_onDragContentLink']>;
+
+    /**
+     * Singleton decoder area
+     * @internal
+     */
+    protected static _decoder: HTMLTextAreaElement;
+  }
+
+  namespace TextEditor {
+    interface Options {
+      /**
+       * @defaultValue `false`
+       */
+      branding?: boolean;
+
+      /**
+       * @defaultValue `['/css/mce.css']`
+       */
+      content_css?: string[];
+
+      /**
+       * @defaultValue `false`
+       */
+      menubar?: boolean;
+
+      /**
+       * @defaultValue `'lists image table hr code save link'`
+       */
+      plugins?: string;
+
+      /**
+       * @defaultValue `true`
+       */
+      save_enablewhendirty?: boolean;
+
+      /**
+       * @defaultValue `false`
+       */
+      statusbar?: boolean;
+
+      style_formats?: [
+        {
+          items?: [
+            {
+              /**
+               * @defaultValue `'section'`
+               */
+              block?: string;
+
+              /**
+               * @defaultValue `'secrect'`
+               */
+              classes?: string;
+
+              /**
+               * @defaultValue `'Secret'`
+               */
+              title?: string;
+
+              /**
+               * @defaultValue `true`
+               */
+              wrapper?: boolean;
+            }
+          ];
+
+          /**
+           * @defaultValue `'Custom'`
+           */
+          title?: string;
+        }
+      ];
+
+      /**
+       * @defaultValue `true`
+       */
+      style_formats_merge?: boolean;
+
+      /**
+       * @defaultValue `{}`
+       */
+      table_default_styles?: object;
+
+      target: HTMLElement;
+
+      /**
+       * @defaultValue `'styleselect bullist numlist image table hr link removeformat code save'`
+       */
+      toolbar?: string;
+    }
+
+    interface EnrichOptions {
+      /**
+       * Include secret tags in the final HTML? If false secret blocks will be removed.
+       * @defaultValue `false`
+       */
+      secrets: boolean;
+
+      /**
+       * Replace dynamic document links?
+       * @defaultValue `true`
+       */
+      documents: boolean;
+
+      /**
+       * Replace hyperlink content?
+       * @defaultValue `true`
+       */
+      links: boolean;
+
+      /**
+       * Replace inline dice rolls?
+       * @defaultValue `true`
+       */
+      rolls: boolean;
+
+      /**
+       * The data object providing context for inline rolls
+       */
+      rollData: object | (() => object);
+    }
+  }
+}