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

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

@@ -0,0 +1,6 @@
+// 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 RollResolver } from "./roll-resolver.mjs";

package/src/foundry/client-esm/applications/dice/roll-resolver.d.mts

@@ -0,0 +1,98 @@
+import type { AnyObject, DeepPartial, EmptyObject, InexactPartial } from "../../../../types/utils.d.mts";
+import type ApplicationV2 from "../api/application.d.mts";
+import type HandlebarsApplicationMixin from "../api/handlebars-application.d.mts";
+
+/**
+ * An application responsible for handling unfulfilled dice terms in a roll.
+ */
+
+declare class RollResolver<
+  RenderContext extends AnyObject = EmptyObject,
+  Configuration extends ApplicationV2.Configuration = ApplicationV2.Configuration,
+  RenderOptions extends ApplicationV2.RenderOptions = ApplicationV2.RenderOptions,
+> extends HandlebarsApplicationMixin(ApplicationV2)<RenderContext, Configuration, RenderOptions> {
+  constructor(roll: Roll, options?: DeepPartial<Configuration>);
+
+  // a placeholder private method to help subclassing
+  #rollResolver: true;
+
+  /**
+   * A collection of fulfillable dice terms.
+   */
+  get fulfillable(): Map<string, RollResolver.DiceTermFulfillmentDescriptor>;
+
+  /**
+   * The roll being resolved.
+   */
+  get roll(): Roll;
+  #roll: Roll;
+
+  /**
+   * Identify any terms in this Roll that should be fulfilled externally, and prompt the user to do so.
+   * @returns Returns a Promise that resolves when the first pass of fulfillment is complete.
+   */
+  awaitFulfillment(): Promise<void>;
+
+  /**
+   * Register a fulfilled die roll.
+   * @param method        - The method used for fulfillment.
+   * @param denomination  - The denomination of the fulfilled die.
+   * @param result        - The rolled number.
+   * @returns               Whether the result was consumed.
+   */
+  registerResult(method: string, denomination: string, result: number): boolean;
+
+  /**
+   * Handle prompting for a single extra result from a term.
+   * @param term                - The term.
+   * @param method              - The method used to obtain the result.
+   * @returns
+   */
+  resolveResult(
+    term: foundry.dice.terms.DiceTerm,
+    method: string,
+    options?: InexactPartial<{
+      /** @defaultValue `false` */
+      reroll: boolean;
+      /** @defaultValue `false` */
+      explode: boolean;
+    }>,
+  ): Promise<number | void>;
+
+  /**
+   * Update the Roll instance with the fulfilled results.
+   * @param event     - The originating form submission event.
+   * @param form      - The form element that was submitted.
+   * @param formData  - Processed data for the submitted form.
+   */
+  static _fulfillRoll(event: SubmitEvent, form: HTMLFormElement, formData: FormDataExtended): Promise<void>;
+
+  /**
+   * Add a new term to the resolver.
+   * @param term        - The term.
+   * @returns  A Promise that resolves when the term's results have been externally fulfilled.
+   */
+  addTerm(term: foundry.dice.terms.DiceTerm): Promise<void>;
+
+  /**
+   * Check if all rolls have been fulfilled.
+   */
+  _checkDone(): void;
+
+  /**
+   * Toggle the state of the submit button.
+   * @param enabled  - Whether the button is enabled.
+   */
+  _toggleSubmission(enabled: boolean): void;
+}
+
+declare namespace RollResolver {
+  interface DiceTermFulfillmentDescriptor {
+    id: string;
+    term: foundry.dice.terms.DiceTerm;
+    method: string;
+    isNew?: boolean | undefined;
+  }
+}
+
+export default RollResolver;

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

@@ -0,0 +1,16 @@
+// 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 AbstractFormInputElement } from "./form-element.mjs";
+export { default as HTMLColorPickerElement } from "./color-picker.mjs";
+export { default as HTMLDocumentTagsElement } from "./document-tags.mjs";
+export { default as HTMLFilePickerElement } from "./file-picker.mjs";
+export { default as HTMLHueSelectorSlider } from "./hue-slider.mjs";
+export { default as HTMLRangePickerElement } from "./range-picker.mjs";
+export { default as HTMLStringTagsElement } from "./string-tags.mjs";
+export { default as HTMLProseMirrorElement } from "./prosemirror-editor.mjs";
+export * from "./multi-select.mjs";
+
+// TODO: Figure out if custom elements need to be otherwise registered for TS compatibility

package/src/foundry/client-esm/applications/elements/color-picker.d.mts

@@ -0,0 +1,26 @@
+import type { FormInputConfig } from "../forms/fields.d.mts";
+import type AbstractFormInputElement from "./form-element.d.mts";
+
+/**
+ * A custom HTMLElement used to select a color using a linked pair of input fields.
+ */
+export default class HTMLColorPickerElement extends AbstractFormInputElement<string> {
+  constructor();
+
+  static override tagName: "color-picker";
+
+  protected override _buildElements(): HTMLInputElement[];
+
+  protected override _refresh(): void;
+
+  protected override _activateListeners(): void;
+
+  protected override _toggleDisabled(disabled: boolean): void;
+
+  protected override _onClick(event: PointerEvent): void;
+
+  /**
+   * Create a HTMLColorPickerElement using provided configuration data.
+   */
+  static create(config: FormInputConfig): HTMLColorPickerElement;
+}

package/src/foundry/client-esm/applications/elements/document-tags.d.mts

@@ -0,0 +1,90 @@
+import type { FormInputConfig } from "../forms/fields.d.mts";
+import type AbstractFormInputElement from "./form-element.d.mts";
+
+/**
+ * A custom HTMLElement used to render a set of associated Documents referenced by UUID.
+ */
+declare class HTMLDocumentTagsElement extends AbstractFormInputElement<Record<string, string> | string | string[]> {
+  constructor();
+
+  protected _value: Record<string, string>;
+
+  set type(value: string);
+
+  /**
+   * Restrict this element to documents of a particular type.
+   */
+  get type(): string | null;
+
+  /**
+   * Restrict to only allow referencing a single Document instead of an array of documents.
+   */
+  get single(): boolean;
+  set single(value: boolean);
+
+  set max(value: number);
+
+  /**
+   * Allow a maximum number of documents to be tagged to the element.
+   */
+  get max(): number;
+
+  /**
+   * Initialize innerText or an initial value attribute of the element as a serialized JSON array.
+   */
+  protected _initializeTags(): void;
+
+  protected override _buildElements(): (HTMLButtonElement | HTMLDivElement)[];
+
+  protected override _refresh(): void;
+
+  /**
+   * Create an HTML string fragment for a single document tag.
+   * @param uuid     - The document UUID
+   * @param name     - The document name
+   * @param editable - Is the tag editable?
+   *                   (default: `true`)
+   */
+  static renderTag(uuid: string, name: string, editable?: boolean): HTMLDivElement;
+
+  /**
+   * Validate that the tagged document is allowed to be added to this field.
+   * Subclasses may impose more strict validation as to which types of documents are allowed.
+   * @param document - A candidate document or compendium index entry to tag
+   * @throws An error if the candidate document is not allowed
+   */
+  _validateDocument(document: foundry.abstract.Document.Any | Record<string, unknown>): void;
+
+  protected override _getValue(): string | string[];
+
+  protected override _setValue(value: string | string[]): void;
+
+  protected override _toggleDisabled(disabled: boolean): void;
+
+  /**
+   * Create a HTMLDocumentTagsElement using provided configuration data.
+   */
+  static create(config: HTMLDocumentTagsElement.DocumentTagsInputConfig): HTMLDocumentTagsElement;
+}
+
+declare namespace HTMLDocumentTagsElement {
+  interface DocumentTagsInputConfig extends FormInputConfig {
+    /**
+     * A specific document type in CONST.ALL_DOCUMENT_TYPES
+     */
+    type?: foundry.CONST.ALL_DOCUMENT_TYPES;
+
+    /**
+     * Only allow referencing a single document. In this case the submitted form value will
+     *    be a single UUID string rather than an array
+     */
+    single?: boolean;
+
+    /**
+     * Only allow attaching a maximum number of documents
+     */
+    max?: number;
+  }
+}
+
+export default HTMLDocumentTagsElement;

package/src/foundry/client-esm/applications/elements/file-picker.d.mts

@@ -0,0 +1,62 @@
+import type { FormInputConfig } from "../forms/fields.d.mts";
+import type AbstractFormInputElement from "./form-element.d.mts";
+
+/**
+ * A custom HTML element responsible for rendering a file input field and associated FilePicker button.
+ */
+declare class HTMLFilePickerElement extends AbstractFormInputElement<string> {
+  constructor();
+
+  static override tagName: "file-picker";
+
+  /**
+   * The file path selected.
+   */
+  input: HTMLInputElement;
+
+  /**
+   * A button to open the file picker interface.
+   */
+  button: HTMLButtonElement;
+
+  /**
+   * A reference to the FilePicker application instance originated by this element.
+   */
+  picker: FilePicker;
+
+  /**
+   * A type of file which can be selected in this field.
+   * @see {@link FilePicker.FILE_TYPES}
+   */
+  get type(): FilePicker.Type;
+  set type(value: FilePicker.Type);
+
+  /**
+   * Prevent uploading new files as part of this element's FilePicker dialog.
+   */
+  get noupload(): boolean;
+  set noupload(value: boolean);
+
+  protected override _buildElements(): (HTMLInputElement | HTMLButtonElement)[];
+
+  protected override _toggleDisabled(disabled: boolean): void;
+
+  protected override _activateListeners(): void;
+
+  protected override _onClick(event: PointerEvent): void;
+
+  /**
+   * Create a HTMLFilePickerElement using provided configuration data.
+   */
+  static create(config: HTMLFilePickerElement.FilePickerInputConfig): HTMLElement;
+}
+
+declare namespace HTMLFilePickerElement {
+  interface FilePickerInputConfig extends FormInputConfig<string> {
+    type?: FilePicker.Type;
+    placeholder?: string;
+    noupload?: boolean;
+  }
+}
+
+export default HTMLFilePickerElement;

package/src/foundry/client-esm/applications/elements/form-element.d.mts

@@ -0,0 +1,106 @@
+/**
+ * An abstract custom HTMLElement designed for use with form inputs.
+ * @remarks Fires input  - An "input" event when the value of the input changes
+ * @remarks Fires change - A "change" event when the value of the element changes
+ */
+export default abstract class AbstractFormInputElement<FormInputValueType> extends HTMLElement {
+  constructor();
+
+  /**
+   * The HTML tag name used by this element.
+   */
+  static tagName: string;
+
+  /**
+   * Declare that this custom element provides form element functionality.
+   */
+  static formAssociated: boolean;
+
+  /**
+   * Attached ElementInternals which provides form handling functionality.
+   */
+  protected _internals: ElementInternals;
+
+  /**
+   * The form this element belongs to.
+   */
+  get form(): HTMLFormElement;
+  set name(value: string);
+
+  /**
+   * The input element name.
+   */
+  get name(): string;
+  set value(value: FormInputValueType);
+
+  /**
+   * The value of the input element.
+   */
+  get value(): FormInputValueType;
+
+  /**
+   * The underlying value of the element.
+   */
+  protected _value: FormInputValueType;
+
+  /**
+   * Return the value of the input element which should be submitted to the form.
+   */
+  protected _getValue(): FormInputValueType;
+
+  /**
+   * Translate user-provided input value into the format that should be stored.
+   * @param value - A new value to assign to the element
+   * @throws An error if the provided value is invalid
+   */
+  protected _setValue(value: FormInputValueType): void;
+
+  set disabled(value: boolean);
+  /**
+   * Is this element disabled?
+   */
+  get disabled(): boolean;
+  /**
+   * Is this field editable? The field can be neither disabled nor readonly.
+   */
+  get editable(): boolean;
+
+  /**
+   * Special behaviors that the subclass should implement when toggling the disabled state of the input.
+   * @param disabled - The new disabled state
+   */
+  protected _toggleDisabled(disabled: boolean): void;
+
+  /**
+   * Initialize the custom element, constructing its HTML.
+   */
+  connectedCallback(): void;
+
+  /**
+   * Create the HTML elements that should be included in this custom element.
+   * Elements are returned as an array of ordered children.
+   */
+  protected _buildElements(): HTMLElement[];
+
+  /**
+   * Refresh the active state of the custom element.
+   */
+  protected _refresh(): void;
+
+  /**
+   * Apply key attributes on the containing custom HTML element to input elements contained within it.
+   * @internal
+   */
+  protected _applyInputAttributes(input: HTMLInputElement): void;
+
+  /**
+   * Activate event listeners which add dynamic behavior to the custom element.
+   */
+  protected _activateListeners(): void;
+
+  /**
+   * Special handling when the custom element is clicked. This should be implemented to transfer focus to an
+   * appropriate internal element.
+   */
+  protected _onClick(event: PointerEvent): void;
+}

package/src/foundry/client-esm/applications/elements/hue-slider.d.mts

@@ -0,0 +1,20 @@
+import type AbstractFormInputElement from "./form-element.d.mts";
+
+/**
+ * A class designed to standardize the behavior for a hue selector UI component.
+ */
+export default class HTMLHueSelectorSlider extends AbstractFormInputElement<number> {
+  constructor();
+
+  static override tagName: "hue-slider";
+
+  protected override _buildElements(): HTMLInputElement[];
+
+  protected override _refresh(): void;
+
+  protected override _activateListeners(): void;
+
+  protected override _setValue(value: number): void;
+
+  protected override _toggleDisabled(disabled: boolean): void;
+}

package/src/foundry/client-esm/applications/elements/multi-select.d.mts

@@ -0,0 +1,95 @@
+import type { FormInputConfig, SelectInputConfig } from "../forms/fields.d.mts";
+import type AbstractFormInputElement from "./form-element.d.mts";
+
+/**
+ * An abstract base class designed to standardize the behavior for a multi-select UI component.
+ * Multi-select components return an array of values as part of form submission.
+ * Different implementations may provide different experiences around how inputs are presented to the user.
+ */
+export class AbstractMultiSelectElement extends AbstractFormInputElement<Set<string> | string[]> {
+  constructor();
+
+  protected _value: Set<string>;
+
+  /**
+   * Predefined <option> and <optgroup> elements which were defined in the original HTML.
+   */
+  protected _options: (HTMLOptionElement | HTMLOptGroupElement)[];
+
+  /**
+   * An object which maps option values to displayed labels.
+   */
+  protected _choices: Record<string, string>;
+
+  /**
+   * Preserve existing <option> and <optgroup> elements which are defined in the original HTML.
+   */
+  protected _initialize(): void;
+
+  /**
+   * Mark a choice as selected.
+   * @param value - The value to add to the chosen set
+   */
+  select(value: string): void;
+
+  /**
+   * Mark a choice as un-selected.
+   * @param value - The value to delete from the chosen set
+   */
+  unselect(value: string): void;
+
+  protected override _getValue(): string[];
+
+  protected override _setValue(value: string[]): void;
+}
+/**
+ * Provide a multi-select workflow using a select element as the input mechanism.
+ *
+ * @example Multi-Select HTML Markup
+ * ```html
+ * <multi-select name="select-many-things">
+ *   <optgroup label="Basic Options">
+ *     <option value="foo">Foo</option>
+ *     <option value="bar">Bar</option>
+ *     <option value="baz">Baz</option>
+ *   </optgroup>
+ *   <optgroup label="Advanced Options">
+ *    <option value="fizz">Fizz</option>
+ *     <option value="buzz">Buzz</option>
+ *   </optgroup>
+ * </multi-select>
+ * ```
+ */
+export class HTMLMultiSelectElement extends AbstractMultiSelectElement {
+  /**
+   * Create a HTMLMultiSelectElement using provided configuration data.
+   */
+  static create(config: FormInputConfig<string[]> & Omit<SelectInputConfig, "blank">): HTMLMultiSelectElement;
+
+  protected override _buildElements(): (HTMLDivElement | HTMLSelectElement)[];
+
+  protected override _toggleDisabled(disabled: boolean): void;
+}
+/**
+ * Provide a multi-select workflow as a grid of input checkbox elements.
+ *
+ * @example Multi-Checkbox HTML Markup
+ * ```html
+ * <multi-checkbox name="check-many-boxes">
+ *   <optgroup label="Basic Options">
+ *     <option value="foo">Foo</option>
+ *     <option value="bar">Bar</option>
+ *     <option value="baz">Baz</option>
+ *   </optgroup>
+ *   <optgroup label="Advanced Options">
+ *    <option value="fizz">Fizz</option>
+ *     <option value="buzz">Buzz</option>
+ *   </optgroup>
+ * </multi-checkbox>
+ * ```
+ */
+export class HTMLMultiCheckboxElement extends AbstractMultiSelectElement {
+  protected override _buildElements(): (HTMLFieldSetElement | HTMLLabelElement)[];
+
+  protected override _toggleDisabled(disabled: boolean): void;
+}

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

@@ -0,0 +1,53 @@
+import type ProseMirrorPlugin from "../../../common/prosemirror/plugin.d.mts";
+import type { FormInputConfig } from "../forms/fields.d.mts";
+import type AbstractFormInputElement from "./form-element.d.mts";
+
+/**
+ * A custom HTML element responsible displaying a ProseMirror rich text editor.
+ */
+declare class HTMLProseMirrorElement extends AbstractFormInputElement<string> {
+  constructor();
+
+  static override tagName: "prose-mirror";
+
+  /**
+   * Actions to take when the custom element is removed from the document.
+   */
+  disconnectedCallback(): void;
+
+  override _buildElements(): (HTMLButtonElement | HTMLDivElement)[];
+
+  override _getValue(): string;
+  /**
+   * Configure ProseMirror editor plugins.
+   */
+  protected _configurePlugins(): Record<string, ProseMirrorPlugin>;
+
+  override _toggleDisabled(disabled: boolean): void;
+
+  /**
+   * Create a HTMLProseMirrorElement using provided configuration data.
+   */
+  static create(config: HTMLProseMirrorElement.ProseMirrorInputConfig): HTMLProseMirrorElement;
+}
+
+declare namespace HTMLProseMirrorElement {
+  interface ProseMirrorInputConfig extends FormInputConfig<string> {
+    /** Is this editor toggled (true) or always active (false) */
+    toggled: boolean;
+
+    /** If the editor is toggled, provide the enrichedHTML which is displayed while the editor is not active. */
+    enriched: string;
+
+    /** Does this editor instance support collaborative editing? */
+    collaborate: boolean;
+
+    /** Should the editor be presented in compact mode? */
+    compact: boolean;
+
+    /** A Document UUID. Required for collaborative editing */
+    documentUUID: string;
+  }
+}
+
+export default HTMLProseMirrorElement;

package/src/foundry/client-esm/applications/elements/range-picker.d.mts

@@ -0,0 +1,41 @@
+import type { FormInputConfig } from "../forms/fields.d.mts";
+import type AbstractFormInputElement from "./form-element.d.mts";
+
+/**
+ * A custom HTML element responsible selecting a value on a range slider with a linked number input field.
+ */
+declare class HTMLRangePickerElement extends AbstractFormInputElement<number> {
+  constructor();
+
+  static override tagName: "range-picker";
+
+  /**
+   * The value of the input element.
+   */
+  get valueAsNumber(): number;
+
+  protected override _buildElements(): HTMLInputElement[];
+
+  protected override _setValue(value: number): void;
+
+  protected override _refresh(): void;
+
+  protected override _activateListeners(): void;
+
+  protected override _toggleDisabled(disabled: boolean): void;
+
+  /**
+   * Create a HTMLRangePickerElement using provided configuration data.
+   */
+  static create(config: HTMLRangePickerElement.RangePickerInputConfig): HTMLRangePickerElement;
+}
+
+declare namespace HTMLRangePickerElement {
+  interface RangePickerInputConfig extends FormInputConfig<number> {
+    min: number;
+    max: number;
+    step?: number;
+  }
+}
+
+export default HTMLRangePickerElement;

package/src/foundry/client-esm/applications/elements/string-tags.d.mts

@@ -0,0 +1,73 @@
+import type { FormInputConfig } from "../forms/fields.d.mts";
+import type AbstractFormInputElement from "./form-element.d.mts";
+
+/**
+ * A custom HTML element which allows for arbitrary assignment of a set of string tags.
+ * This element may be used directly or subclassed to impose additional validation or functionality.
+ */
+declare class HTMLStringTagsElement extends AbstractFormInputElement<Set<string> | string[]> {
+  constructor();
+
+  static override tagName: "string-tags";
+
+  static icons: {
+    add: string;
+    remove: string;
+  };
+
+  static labels: {
+    add: string;
+    remove: string;
+    placeholder: string;
+  };
+
+  _value: Set<string>;
+
+  /**
+   * Initialize innerText or an initial value attribute of the element as a comma-separated list of currently assigned
+   * string tags.
+   */
+  protected _initializeTags(): void;
+
+  /**
+   * Subclasses may impose more strict validation on what tags are allowed.
+   * @param tag - A candidate tag
+   * @throws An error if the candidate tag is not allowed
+   */
+  protected _validateTag(tag: string): void;
+
+  protected override _buildElements(): (HTMLButtonElement | HTMLDivElement)[];
+
+  protected override _refresh(): void;
+
+  /**
+   * Render the tagged string as an HTML element.
+   * @param tag      - The raw tag value
+   * @param label    - An optional tag label
+   * @param editable - Is the tag editable?
+   * @returns A rendered HTML element for the tag
+   */
+  static renderTag(tag: string, label?: string, editable?: boolean): HTMLDivElement;
+
+  protected override _activateListeners(): void;
+
+  protected override _getValue(): string[];
+
+  protected override _setValue(value: string[] | Set<string>): void;
+
+  protected override _toggleDisabled(disabled: boolean): void;
+
+  /**
+   * Create a HTMLStringTagsElement using provided configuration data.
+   */
+  static create(config: HTMLStringTagsElement.StringTagsInputConfig): HTMLElement;
+}
+
+declare namespace HTMLStringTagsElement {
+  interface StringTagsInputConfig extends FormInputConfig<Set<string> | string[]> {
+    /** Automatically slugify provided strings? */
+    slug: boolean;
+  }
+}
+
+export default HTMLStringTagsElement;