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

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

@@ -0,0 +1,156 @@
+import type Application from "#client/appv1/api/application-v1.mjs";
+import type ApplicationV2 from "#client/applications/api/application.d.mts";
+import type { Identity } from "#utils";
+
+/**
+ * A UI utility to make an element draggable.
+ */
+declare class Draggable<R extends boolean | Draggable.Resizable = false> {
+  /**
+   * @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: Draggable["app"], element: JQuery | HTMLElement, handle: Draggable["handle"], resizable?: R);
+
+  /**
+   * The Application being made draggable.
+   */
+  app: Application.Any | ApplicationV2.Any;
+
+  /**
+   * The Application's outer-most element.
+   */
+  element: HTMLElement;
+
+  /**
+   * The drag handle, or false to disable dragging.
+   */
+  handle: HTMLElement | boolean;
+
+  /**
+   * Registered event handlers.
+   * @defaultValue `{}`
+   */
+  handlers: Draggable.RegisteredHandlers<R>;
+
+  /**
+   * The Application's starting position, pre-drag.
+   * @defaultValue `null`
+   */
+  position: foundry.utils.Duplicated<Application.Position> | null;
+
+  /**
+   * Resize configuration.
+   * @defaultValue `false`
+   */
+  resizable: R;
+
+  /**
+   * 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
+   */
+  protected _onDragMouseDown(event: PointerEvent): void;
+
+  /**
+   * Move the window with the mouse, bounding the movement to ensure the window stays within bounds of the viewport
+   */
+  protected _onDragMouseMove(event: PointerEvent): void;
+
+  /**
+   * Conclude the dragging behavior when the mouse is release, setting the final position and removing listeners
+   */
+  protected _onDragMouseUp(event: PointerEvent): void;
+
+  /**
+   * Handle the initial mouse click which activates dragging behavior for the application
+   */
+  protected _onResizeMouseDown(event: PointerEvent): void;
+
+  /**
+   * Move the window with the mouse, bounding the movement to ensure the window stays within bounds of the viewport
+   */
+  protected _onResizeMouseMove(event: PointerEvent): void;
+
+  /**
+   * Conclude the dragging behavior when the mouse is release, setting the final position and removing listeners
+   */
+  protected _onResizeMouseUp(event: PointerEvent): void;
+
+  /**
+   * Retrieve the configured Draggable implementation.
+   * @remarks TODO: Link up with CONFIG
+   */
+  static get implementation(): typeof Draggable;
+}
+
+declare namespace Draggable {
+  interface Any extends AnyDraggable {}
+  interface AnyConstructor extends Identity<typeof AnyDraggable> {}
+
+  interface Resizable {
+    /**
+     * A CSS selector for the resize handle.
+     */
+    selector?: string | undefined;
+
+    /**
+     * Enable resizing in the X direction.
+     * @defaultValue `true`
+     */
+    resizeX?: boolean | undefined;
+
+    /**
+     * Enable resizing in the y direction.
+     * @defaultValue `true`
+     */
+    resizeY?: boolean | undefined;
+
+    /**
+     * Modify the resizing direction to be right-to-left.
+     */
+    rt1?: boolean | null | undefined;
+  }
+
+  type RegisteredHandlers<R extends boolean | Resizable> = R extends true
+    ? ResizableHandlers
+    : R extends false
+      ? Handlers
+      : Handlers | ResizableHandlers;
+
+  interface Handlers {
+    click: ["click", (e: MouseEvent) => void, { capture: boolean; passive: boolean }];
+    dragDown: ["pointerdown", (e: Event) => void, false];
+    dragMove: ["pointermove", (e: Event) => void, false];
+    dragUp: ["pointerup", (e: Event) => void, false];
+  }
+
+  interface ResizableHandlers extends Handlers {
+    resizeDown: ["pointerdown", (e: Event) => void, false];
+    resizeMove: ["pointermove", (e: Event) => void, false];
+    resizeUp: ["pointerup", (e: Event) => void, false];
+  }
+}
+
+declare abstract class AnyDraggable extends Draggable<boolean | Draggable.Resizable> {
+  constructor(...args: never);
+}
+
+export default Draggable;

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

@@ -0,0 +1,89 @@
+import type { AnyMutableObject } from "#utils";
+
+/**
+ * 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
+ */
+declare class FormDataExtended extends FormData {
+  /**
+   * @param form    - The form being processed
+   * @param options - Options which configure form processing
+   */
+  constructor(form: HTMLFormElement, options?: FormDataExtended.Options);
+
+  /**
+   * A mapping of data types requested for each form field.
+   * @defaultValue `{}`
+   */
+  dtypes: Record<string, string>;
+
+  /**
+   * A record of TinyMCE editors which are linked to this form.
+   * @defaultValue `{}`
+   */
+  editors: Record<string, foundry.appv1.api.FormApplication.FormApplicationEditor>;
+
+  /**
+   * The object representation of the form data, available once processed.
+   */
+  get object(): AnyMutableObject;
+
+  /**
+   * 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: FormDataExtended.Options): 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 name - The field name
+   * @param value - The raw extracted value from the field
+   */
+  override set(name: string, value: any): 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: any): void;
+}
+
+declare namespace FormDataExtended {
+  interface Options {
+    /**
+     * A record of TinyMCE editor metadata objects, indexed by their update key
+     * (default: `{}`)
+     */
+    editors?: FormDataExtended["editors"] | undefined;
+
+    /**
+     * A mapping of data types for form fields
+     * (default: `{}`)
+     */
+    dtypes?: FormDataExtended["dtypes"] | undefined;
+
+    /**
+     * Include disabled fields?
+     * (default: `false`)
+     */
+    disabled?: boolean | undefined;
+
+    /**
+     * Include readonly fields?
+     * (default: `true`)
+     */
+    readonly?: boolean | undefined;
+  }
+}
+
+export default FormDataExtended;

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

@@ -0,0 +1,75 @@
+import type Document from "#common/abstract/document.d.mts";
+
+/**
+ * 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);
+ * ```
+ */
+declare class HTMLSecret<ConcreteDocument extends Document.Any = Document.Any> {
+  /**
+   * @param config - Configuration options.
+   */
+  constructor(config: HTMLSecret.Configuration<ConcreteDocument>);
+
+  /** The CSS selector used to target secret blocks. */
+  readonly parentSelector: string;
+
+  /** An object of callback functions for each operation. */
+  readonly callbacks: Readonly<HTMLSecret.Callbacks<ConcreteDocument>>;
+
+  /**
+   * 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;
+}
+
+declare namespace HTMLSecret {
+  /**
+   * @param secret - The secret element whose surrounding content we wish to retrieve.
+   * @returns The content where the secret is housed.
+   */
+  type ContentCallback = (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 UpdateCallback<ConcreteDocument extends Document.Any = Document.Any> = (
+    secret: HTMLElement,
+    content: string,
+  ) => Promise<ConcreteDocument>;
+
+  interface Configuration<ConcreteDocument extends Document.Any = Document.Any> {
+    /** The CSS selector used to target content that contains secret blocks. */
+    parentSelector: string;
+
+    /** An object of callback functions for each operation. */
+    callbacks?: Callbacks<ConcreteDocument> | undefined;
+  }
+
+  interface Callbacks<ConcreteDocument extends Document.Any = Document.Any> {
+    content: HTMLSecret.ContentCallback;
+    update: HTMLSecret.UpdateCallback<ConcreteDocument>;
+  }
+}
+
+export default HTMLSecret;

package/src/foundry/client/applications/ux/prosemirror-editor.d.mts

@@ -0,0 +1,199 @@
+import type { EditorState, Plugin } from "prosemirror-state";
+import type { Step } from "prosemirror-transform";
+import type { EditorProps, EditorView } from "prosemirror-view";
+import type { Socket } from "socket.io-client";
+
+/**
+ * A class responsible for managing state and collaborative editing of a single ProseMirror instance.
+ */
+declare 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: ProseMirrorEditor.History[]): 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?: ProseMirrorEditor.CreateOptions,
+  ): 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 ProseMirror editor plugins to load.
+   * @param props   - Additional ProseMirror editor properties.
+   */
+  protected static _createLocalEditorView(
+    target: HTMLElement,
+    state: EditorState,
+    plugins: Plugin[],
+    props: ProseMirrorEditor.Props,
+  ): 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;
+}
+
+declare namespace ProseMirrorEditor {
+  type Props = EditorProps;
+
+  /** @internal */
+  interface _CreateOptions {
+    /** A string to uniquely identify this ProseMirror instance. Ignored for a collaborative editor. */
+    uuid?: string | null | undefined;
+
+    /** A Document whose content is being edited. Required for collaborative editing and relative UUID generation. */
+    document?: foundry.abstract.Document.Any | null | undefined;
+
+    /** The field within the Document that is being edited. Required for collaborative editing. */
+    fieldName?: string | null | undefined;
+
+    /** Plugins to include with the editor. */
+    plugins?: Record<string, Plugin> | undefined;
+
+    /**
+     * Whether to enable collaborative editing for this editor.
+     * @defaultValue `false`
+     */
+    collaborate?: boolean | undefined;
+
+    /**
+     * Whether to generate relative UUID links to Documents that are dropped on the editor.
+     * @defaultValue `false`
+     */
+    relativeLinks?: boolean | undefined;
+
+    /** Additional ProseMirror editor properties. */
+    props?: Props | undefined;
+  }
+
+  type CreateOptions = Partial<_CreateOptions> &
+    ({ collaborate?: false } | ({ collaborate: true } & Pick<_CreateOptions, "document" | "fieldName">));
+
+  interface Options {
+    document?: ClientDocument | undefined;
+  }
+
+  interface History {
+    /** The ID of the user who submitted the step. */
+    userId: string;
+
+    /** The step that was submitted. */
+    step: Step;
+  }
+}
+
+export default ProseMirrorEditor;

package/src/foundry/client/applications/ux/search-filter.d.mts

@@ -0,0 +1,148 @@
+import type { ValueOf } from "#utils";
+
+/**
+ * A controller class for managing a text input widget that filters the contents of some other UI element.
+ */
+declare class SearchFilter {
+  /**
+   * @param options - Options which customize the behavior of the filter
+   */
+  constructor(options: SearchFilter.Configuration);
+
+  /**
+   * The value of the current query string
+   */
+  query: string;
+
+  /**
+   * A callback function to trigger when the tab is changed
+   */
+  callback: SearchFilter.Callback;
+
+  /**
+   * The allowed Filter Operators which can be used to define a search filter
+   */
+  static OPERATORS: Readonly<SearchFilter.Operators>;
+
+  /**
+   * The regular expression corresponding to the query that should be matched against
+   * @defaultValue `undefined`
+   */
+  rgx: RegExp | undefined;
+
+  /**
+   * A reference to the HTML navigation element the tab controller is bound to
+   */
+  _input: HTMLElement | null;
+
+  /**
+   * Bind the SearchFilter controller to an HTML application
+   */
+  bind(html: HTMLElement): void;
+
+  /**
+   * Release all bound HTML elements and reset the query.
+   */
+  unbind(): void;
+
+  /**
+   * Perform a filtering of the content by invoking the callback function
+   * @param event - The triggering keyboard event
+   * @param query - The input search string
+   */
+  filter(event: KeyboardEvent, query: string): void;
+
+  /**
+   * Clean a query term to standardize it for matching.
+   * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize
+   * @param query - An input string which may contain leading/trailing spaces or diacritics
+   * @returns A cleaned string of ASCII characters for comparison
+   */
+  static cleanQuery(query: string): string;
+
+  /**
+   * A helper method to test a value against a precomposed regex pattern.
+   * @param rgx   - The regular expression to test
+   * @param value - THe value to test against
+   * @returns Does the query match?
+   */
+  static testQuery(rgx: RegExp, value: string): boolean;
+
+  /**
+   * Test whether a given object matches a provided filter
+   * @param obj    - An object to test against
+   * @param filter - The filter to test
+   * @returns Whether the object matches the filter
+   * @remarks obj needs to work with both Document.Any *and* plain objects
+   */
+  static evaluateFilter(obj: object, filter: SearchFilter.FieldFilter): boolean;
+}
+
+declare namespace SearchFilter {
+  type Callback = (event: KeyboardEvent | null, query: string, rgx: RegExp, content: HTMLElement | null) => void;
+
+  interface Operators {
+    EQUALS: "equals";
+    CONTAINS: "contains";
+    STARTS_WITH: "starts_with";
+    ENDS_WITH: "ends_with";
+    LESS_THAN: "lt";
+    LESS_THAN_EQUAL: "lte";
+    GREATER_THAN: "gt";
+    GREATER_THAN_EQUAL: "gte";
+    BETWEEN: "between";
+    IS_EMPTY: "is_empty";
+  }
+
+  /** Options which customize the behavior of the filter */
+  interface Configuration {
+    /**
+     * The CSS selector used to target the text input element.
+     */
+    inputSelector: string;
+
+    /**
+     * The CSS selector used to target the content container for these tabs.
+     */
+    contentSelector: string;
+
+    /**
+     * A callback function which executes when the filter changes.
+     */
+    callback?: Callback | undefined;
+
+    /**
+     * The initial value of the search query.
+     * @defaultValue `""`
+     */
+    initial?: SearchFilter["query"] | undefined;
+
+    /**
+     * The number of milliseconds to wait for text input before processing.
+     * @defaultValue `200`
+     */
+    delay?: number | undefined;
+  }
+
+  interface FieldFilter {
+    /** The dot-delimited path to the field being filtered */
+    field: string;
+
+    /**
+     * The search operator, from CONST.OPERATORS
+     * @defaultValue `SearchFilter.OPERATORS.EQUALS`
+     */
+    operator?: ValueOf<typeof SearchFilter.OPERATORS> | undefined;
+
+    /**
+     * Negate the filter, returning results which do NOT match the filter criteria
+     * @remarks Defaults to false because undefined is falsy
+     */
+    negate?: boolean | undefined;
+
+    /** The value against which to test */
+    value: any;
+  }
+}
+
+export default SearchFilter;