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

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

@@ -0,0 +1,12 @@
+import "./context.d.mts";
+import "./dialog.d.mts";
+import "./drag.d.mts";
+import "./dragdrop.d.mts";
+import "./editor.d.mts";
+import "./filepicker.d.mts";
+import "./filter.d.mts";
+import "./forms.d.mts";
+import "./notifications.d.mts";
+import "./prosemirror.d.mts";
+import "./secrets.d.mts";
+import "./tabs.d.mts";

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

@@ -0,0 +1,136 @@
+export {};
+
+declare global {
+  /**
+   * A common framework for displaying notifications to the client.
+   * Submitted notifications are added to a queue, and up to 3 notifications are displayed at once.
+   * Each notification is displayed for 5 seconds at which point further notifications are pulled from the queue.
+   *
+   * @example Displaying Notification Messages
+   * ```typescript
+   * ui.notifications.info("This is an info message");
+   * ui.notifications.warn("This is a warning message");
+   * ui.notifications.error("This is an error message");
+   * ui.notifications.info("This is a 4th message which will not be shown until the first info message is done");
+   * ```
+   *
+   * @typeParam Options - the type of the options object
+   */
+  class Notifications<Options extends ApplicationOptions = ApplicationOptions> extends Application<Options> {
+    constructor(options?: Partial<Options>);
+
+    /**
+     * Submitted notifications which are queued for display
+     * @defaultValue `[]`
+     */
+    queue: Notifications.Notification[];
+
+    /**
+     * Notifications which are currently displayed
+     * @defaultValue `[]`
+     */
+    active: JQuery[];
+
+    /**
+     * @defaultValue
+     * ```typescript
+     * mergeObject(super.defaultOptions, {
+     *   popOut: false,
+     *   id: "notifications",
+     *   template: "templates/hud/notifications.html"
+     * });
+     * ```
+     */
+    static override get defaultOptions(): ApplicationOptions;
+
+    /**
+     * Initialize the Notifications system by displaying any system-generated messages which were passed from the server.
+     */
+    initialize(): void;
+
+    protected override _renderInner(data: ReturnType<this["getData"]>): Promise<JQuery>;
+
+    protected override _render(force?: boolean, options?: Application.RenderOptions<Options>): Promise<void>;
+
+    /**
+     * Push a new notification into the queue
+     * @param message   - The content of the notification message
+     * @param type      - The type of notification, "info", "warning", and "error" are supported
+     *                    (default: `"info"`)
+     * @param options   - Additional options which affect the notification
+     *                    (default: `{}`)
+     * @returns The ID of the notification (positive integer)
+     */
+    notify(message: string, type?: "info" | "warning" | "error", options?: Notifications.NotifyOptions): number;
+
+    /**
+     * Display a notification with the "info" type
+     * @param message - The content of the notification message
+     * @param options - Notification options passed to the notify function
+     * @returns The ID of the notification (positive integer)
+     */
+    info(message: string, options?: Notifications.NotifyOptions): number;
+
+    /**
+     * Display a notification with the "warning" type
+     * @param message - The content of the notification message
+     * @param options - Notification options passed to the notify function
+     * @returns The ID of the notification (positive integer)
+     */
+    warn(message: string, options?: Notifications.NotifyOptions): number;
+
+    /**
+     * Display a notification with the "error" type
+     * @param message - The content of the notification message
+     * @param options - Notification options passed to the notify function
+     * @returns The ID of the notification (positive integer)
+     */
+    error(message: string, options?: Notifications.NotifyOptions): number;
+
+    /**
+     * Remove the notification linked to the ID.
+     * @param id - The ID of the notification
+     */
+    remove(id: number): void;
+
+    /**
+     * Clear all notifications.
+     */
+    clear(): void;
+
+    /**
+     * Retrieve a pending notification from the queue and display it
+     */
+    protected fetch(): void;
+  }
+
+  namespace Notifications {
+    interface NotifyOptions {
+      /**
+       * Should the notification be permanently displayed until dismissed
+       * @defaultValue `false`
+       */
+      permanent?: boolean;
+
+      /**
+       * Whether to localize the message content before displaying it
+       * @defaultValue `false`
+       */
+      localize?: boolean;
+
+      /**
+       * Whether to log the message to the console
+       * @defaultValue `true`
+       */
+      console?: boolean;
+    }
+
+    interface Notification {
+      message: string;
+      type: "info" | "warning" | "error";
+      timestamp: number;
+      permanent: boolean;
+      console: boolean;
+    }
+  }
+}

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

@@ -0,0 +1,171 @@
+import type { EditorState, Plugin } from "prosemirror-state";
+import type { Step } from "prosemirror-transform";
+import type { EditorView } from "prosemirror-view";
+import type { Socket } from "socket.io-client";
+
+declare global {
+  interface ProseMirrorHistory {
+    /** The ID of the user who submitted the step. */
+    userId: string;
+    /** The step that was submitted. */
+    step: Step;
+  }
+  namespace ProseMirrorEditor {
+    interface Options {
+      document?: ClientDocument;
+    }
+    interface CreateOptions {
+      /** A string to uniquely identify this ProseMirror instance. Ignored for a collaborative editor. */
+      uuid: string;
+      /** A Document whose content is being edited. Required for collaborative editing. */
+      document: ClientDocument;
+      /** The field within the Document that is being edited. Required for collaborative editing. */
+      fieldName: string;
+      /** Plugins to include with the editor. */
+      plugins: Record<string, Plugin>;
+      /** Whether to enable collaborative editing for this editor. */
+      collaborate: boolean;
+    }
+  }
+  /**
+   * A class responsible for managing state and collaborative editing of a single ProseMirror instance.
+   */
+  class ProseMirrorEditor {
+    /**
+     * A string that uniquely identifies this ProseMirror instance.
+     */
+    readonly uuid: string;
+
+    /**
+     * The ProseMirror EditorView.
+     */
+    readonly view: EditorView;
+
+    /**
+     * Whether this is a collaborative editor.
+     */
+    readonly collaborate: boolean;
+
+    options: ProseMirrorEditor.Options;
+
+    /**
+     * @param uuid          - A string that uniquely identifies this ProseMirror instance.
+     * @param view          - The ProseMirror EditorView.
+     * @param isDirtyPlugin - The plugin to track the dirty state of the editor.
+     * @param collaborate   - Whether this is a collaborative editor.
+     * @param options       - Additional options.
+     */
+    constructor(
+      uuid: string,
+      view: EditorView,
+      isDirtyPlugin: Plugin,
+      collaborate: boolean,
+      options?: ProseMirrorEditor.Options,
+    );
+
+    /**
+     * Retire this editor instance and clean up.
+     */
+    destroy(): void;
+
+    /**
+     * Reset and destroy the editor so that it can be activated again.
+     * @param fieldName - The field name that this editor is responsible for.
+     */
+    reset(fieldName?: string): void;
+
+    /**
+     * Have the contents of the editor been edited by the user?
+     */
+    isDirty(): boolean;
+
+    /**
+     * Handle new editing steps supplied by the server.
+     * @param offset  - The offset into the history, representing the point at which it was last truncated.
+     * @param history - The entire edit history.
+     */
+    protected _onNewSteps(offset: string, history: ProseMirrorHistory[]): void;
+
+    /**
+     * Disable source code editing if the user was editing it when new steps arrived.
+     */
+    protected _disableSourceCodeEditing(): void;
+
+    /**
+     * The state of this ProseMirror editor has fallen too far behind the central authority's and must be re-synced.
+     */
+    protected _resync(): void;
+
+    /**
+     * Handle users joining or leaving collaborative editing.
+     * @param users - The IDs of users currently editing (including ourselves).
+     */
+    protected _updateUserDisplay(users: string[]): void;
+
+    /**
+     * Create a ProseMirror editor instance.
+     * @param target                  - An HTML element to mount the editor to.
+     * @param content                 - Content to populate the editor with. (default: `""`)
+     * @param options                    - Additional options to configure the ProseMirror instance.
+     */
+    static create(
+      target: HTMLElement,
+      content?: string,
+      options?: Partial<ProseMirrorEditor.CreateOptions> &
+        (
+          | { collaborate?: false }
+          | ({ collaborate: true } & Pick<ProseMirrorEditor.CreateOptions, "document" | "fieldName">)
+        ),
+    ): Promise<ProseMirrorEditor>;
+
+    /**
+     * Create an EditorView with collaborative editing enabled.
+     * @param uuid    - The ProseMirror instance UUID.
+     * @param target  - An HTML element to mount the editor view to.
+     * @param state   - The ProseMirror editor state.
+     * @param plugins - The editor plugins to load.
+     */
+    protected static _createCollaborativeEditorView(
+      uuid: string,
+      target: HTMLElement,
+      state: EditorState,
+      plugins: Plugin[],
+    ): Promise<EditorView>;
+
+    /**
+     * Create a plain EditorView without collaborative editing.
+     * @param target  - An HTML element to mount the editor view to.
+     * @param state   - The ProseMirror editor state.
+     * @param plugins - The editor plugins to load.
+     */
+    protected static _createLocalEditorView(target: HTMLElement, state: EditorState, plugins: Plugin[]): EditorView;
+
+    /**
+     * Handle new editing steps supplied by the server.
+     * @param uuid    - The UUID that uniquely identifies the ProseMirror instance.
+     * @param offset  - The offset into the history, representing the point at which it was last truncated.
+     * @param history - The entire edit history.
+     */
+    protected static _onNewSteps(uuid: string, offset: number, history: ProseMirrorEditor[]): void;
+
+    /**
+     * Our client is too far behind the central authority's state and must be re-synced.
+     * @param uuid - The UUID that uniquely identifies the ProseMirror instance.
+     */
+    protected static _onResync(uuid: string): void;
+
+    /**
+     * Handle users joining or leaving collaborative editing.
+     * @param uuid  - The UUID that uniquely identifies the ProseMirror instance.
+     * @param users - The IDs of the users currently editing (including ourselves).
+     */
+    protected static _onUsersEditing(uuid: string, users: string[]): void;
+
+    /**
+     * Listen for ProseMirror collaboration events.
+     * @param socket - The open websocket.
+     * @internal
+     */
+    static _activateSocketListeners(socket: Socket): void;
+  }
+}

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

@@ -0,0 +1,75 @@
+import type Document from "../../common/abstract/document.d.mts";
+
+declare global {
+  /**
+   * @param secret - The secret element whose surrounding content we wish to retrieve.
+   * @returns The content where the secret is housed.
+   */
+  type HTMLSecretContentCallback = (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.
+   */
+  type HTMLSecretUpdateCallback<
+    ConcreteDocument extends Document.Internal.Instance.Any = Document.Internal.Instance.Any,
+  > = (secret: HTMLElement, content: string) => Promise<ConcreteDocument>;
+
+  interface HTMLSecretConfiguration<
+    ConcreteDocument extends Document.Internal.Instance.Any = Document.Internal.Instance.Any,
+  > {
+    /** The CSS selector used to target content that contains secret blocks. */
+    parentSelector: string;
+
+    /** An object of callback functions for each operation. */
+    callbacks: {
+      content: HTMLSecretContentCallback;
+      update: HTMLSecretUpdateCallback<ConcreteDocument>;
+    };
+  }
+
+  /**
+   * A composable class for managing functionality for secret blocks within DocumentSheets.
+   * @see 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);
+   * ```
+   */
+  class HTMLSecret<ConcreteDocument extends foundry.abstract.Document.Any = foundry.abstract.Document.Any> {
+    /**
+     * @param config - Configuration options.
+     */
+    constructor(
+      config: Omit<HTMLSecretConfiguration<ConcreteDocument>, "callbacks"> &
+        Partial<Pick<HTMLSecretConfiguration<ConcreteDocument>, "callbacks">>,
+    );
+
+    /** The CSS selector used to target secret blocks. */
+    readonly parentSelector: string;
+
+    /** An object of callback functions for each operation. */
+    readonly callbacks: Readonly<HTMLSecretConfiguration<ConcreteDocument>["callbacks"]>;
+
+    /**
+     * 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: MouseEvent): ConcreteDocument | void;
+  }
+}

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

@@ -0,0 +1,117 @@
+export {};
+
+declare global {
+  interface TabsConfiguration {
+    /**
+     * The name of the tabs group
+     */
+    group?: string;
+
+    /**
+     * The CSS selector used to target the navigation element for these tabs
+     */
+    navSelector: string;
+
+    /**
+     * The CSS selector used to target the content container for these tabs
+     */
+    contentSelector?: string;
+
+    /**
+     * The tab name of the initially active tab
+     */
+    initial?: string;
+
+    /**
+     * An optional callback function that executes when the active tab is changed
+     */
+    callback?: ((event: MouseEvent | null, tabs: Tabs, tabName: string) => unknown) | null;
+  }
+
+  /**
+   * A controller class for managing tabbed navigation within an Application instance.
+   * @see {@link Application}
+   *
+   * @example Configure tab-control for a set of HTML elements
+   * ```html
+   * <!-- Example HTML -->
+   * <nav class="tabs" data-group="primary-tabs">
+   *   <a class="item" data-tab="tab1">Tab 1</li>
+   *   <a class="item" data-tab="tab2">Tab 2</li>
+   * </nav>
+   *
+   * <section class="content">
+   *   <div class="tab" data-tab="tab1" data-group="primary-tabs">Content 1</div>
+   *   <div class="tab" data-tab="tab2" data-group="primary-tabs">Content 2</div>
+   * </section>
+   * ```
+   * Activate tab control in JavaScript
+   * ```typescript
+   * // JavaScript
+   * const tabs = new Tabs({navSelector: ".tabs", contentSelector: ".content", initial: "tab1"});
+   * tabs.bind(html);
+   * ```
+   */
+  class Tabs {
+    /**
+     * @param config - The Tabs Configuration to use for this tabbed container
+     */
+    constructor(config: TabsConfiguration);
+
+    /**
+     * The name of the tabs group
+     */
+    group: TabsConfiguration["group"];
+
+    /**
+     * The value of the active tab
+     */
+    active: TabsConfiguration["initial"];
+
+    /**
+     * A callback function to trigger when the tab is changed
+     */
+    callback: TabsConfiguration["callback"];
+
+    /**
+     * The CSS selector used to target the tab navigation element
+     */
+    protected _navSelector: TabsConfiguration["navSelector"];
+
+    /**
+     * A reference to the HTML navigation element the tab controller is bound to
+     * @defaultValue `null`
+     */
+    protected _nav: HTMLElement | null;
+
+    /**
+     * The CSS selector used to target the tab content element
+     */
+    protected _contentSelector: TabsConfiguration["contentSelector"];
+
+    /**
+     * A reference to the HTML container element of the tab content
+     * @defaultValue `null`
+     */
+    protected _content: HTMLElement | null;
+
+    /**
+     * Bind the Tabs controller to an HTML application
+     */
+    bind(html: HTMLElement): void;
+
+    /**
+     * Activate a new tab by name
+     * @param triggerCallback - (default: `false`)
+     */
+    activate(tabName: string, { triggerCallback }?: { triggerCallback?: boolean }): void;
+
+    /**
+     * Handle click events on the tab navigation entries
+     * @param event - A left click event
+     */
+    protected _onClickNav(event: MouseEvent): void;
+  }
+
+  const TabsV2: typeof Tabs;
+}

package/src/foundry/client-esm/applications/_module.d.mts

@@ -0,0 +1,25 @@
+// In Foundry itself this file contains re-exports of these other modules.
+// Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
+// While `.mts` could work, to avoid `import/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import/extensions */
+
+export * as types from "./_types.mjs";
+export * as api from "./api/_module.mjs";
+export * as dice from "./dice/_module.mjs";
+export * as elements from "./elements/_module.mjs";
+export * as fields from "./forms/fields.mjs";
+export * as apps from "./apps/_module.mjs";
+export * as sheets from "./sheets/_module.mjs";
+export * as ui from "./ui/_module.mjs";
+
+/**
+ * A registry of currently rendered ApplicationV2 instances.
+ */
+export const instances: Map<number, foundry.applications.api.ApplicationV2>;
+
+/**
+ * Parse an HTML string, returning a processed HTMLElement or HTMLCollection.
+ * A single HTMLElement is returned if the provided string contains only a single top-level element.
+ * An HTMLCollection is returned if the provided string contains multiple top-level elements.
+ */
+export function parseHTML(htmlString: string): HTMLCollection | HTMLElement;

package/src/foundry/client-esm/applications/_types.d.mts

@@ -0,0 +1,38 @@
+// Open question - this is just types?
+
+import type ApplicationV2 from "./api/application.d.mts";
+
+export {};
+
+// After seeing that none of these types add anything or are even exported a
+// very reasonable question may be: Why on earth does this file exist?
+//
+// Well this is the file in which Foundry defines these types. We don't house
+// them here because it has poor discoverability. The names Foundry has chosen
+// also overlaps with other existing names. For example `ApplicationConfiguration`
+// is also a class in `src/foundry/common/config.d.mts`. It's also just nice to
+// have as reference to keep us synced with the latest version of Foundry.
+
+type ApplicationConfiguration = ApplicationV2.Configuration;
+
+type ApplicationFormConfiguration = ApplicationV2.FormConfiguration;
+
+type ApplicationHeaderControlsEntry = ApplicationV2.HeaderControlsEntry;
+
+type ApplicationConstructorParams = ApplicationV2.ConstructorParams;
+
+type ApplicationRenderOptions = ApplicationV2.RenderOptions;
+
+type ApplicationWindowRenderOptions = ApplicationV2.WindowRenderOptions;
+
+type ApplicationClosingOptions = ApplicationV2.ClosingOptions;
+
+type ApplicationClickAction = ApplicationV2.ClickAction;
+
+type ApplicationFormSubmission = ApplicationV2.FormSubmission;
+
+type ApplicationTab = ApplicationV2.Tab;
+
+type FormNode = ApplicationV2.FormNode;
+
+type FormFooterButton = ApplicationV2.FormFooterButton;

package/src/foundry/client-esm/applications/api/_module.d.mts

@@ -0,0 +1,9 @@
+// In Foundry itself this file contains re-exports of these other modules.
+// Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
+// While `.mts` could work, to avoid `import/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import/extensions */
+
+export { default as ApplicationV2 } from "./application.mjs";
+export { default as DialogV2 } from "./dialog.mjs";
+export { default as DocumentSheetV2 } from "./document-sheet.mjs";
+export { default as HandlebarsApplicationMixin } from "./handlebars-application.mjs";