@7h3laughingman/foundry-types 13.351.0

package/src/client/applications/elements/document-embed.d.mts

@@ -0,0 +1,14 @@
+/**
+ * A custom HTMLElement that is used to wrap enriched content that requires additional interactivity.
+ */
+export default class HTMLDocumentEmbedElement extends HTMLElement {
+    /**
+     * The HTML tag named used by this element.
+     */
+    static tagName: "document-embed";
+
+    /**
+     * Invoke the Document#onEmbed callback when it is added to the DOM.
+     */
+    connectedCallback(): void;
+}

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

@@ -0,0 +1,50 @@
+import { FormInputConfig } from "./../../../common/data/_types.mjs";
+import { DocumentUUID } from "./../../utils/_module.mjs";
+import AbstractFormInputElement from "./form-element.mjs";
+
+/**
+ * A custom HTMLElement used to render a set of associated Documents referenced by UUID.
+ */
+export default class HTMLDocumentTagsElement extends AbstractFormInputElement<Record<string, string>, string | string[] | null> {
+    static override tagName: "document-tags";
+
+    /** Restrict this element to documents of a particular type. */
+    get type(): string | null;
+    set type(value: string | null);
+
+    /** Restrict to only allow referencing a single Document instead of an array of documents. */
+    get single(): boolean;
+    set single(value: boolean);
+
+    /** Allow a maximum number of documents to be tagged to the element. */
+    get max(): number;
+    set max(value: number | null);
+
+    /** Initialize innerText or an initial value attribute of the element as a serialized JSON array. */
+    protected _initializeTags(): void;
+
+    /**
+     * Create an HTML string fragment for a single document tag.
+     * @param uuid     The document UUID
+     * @param name     The document name
+     * @param [editable=true] Is the tag editable?
+     */
+    static renderTag(uuid: DocumentUUID, name: string, editable?: boolean): string;
+
+    /** Create a HTMLDocumentTagsElement using provided configuration data. */
+    static create(config: DocumentTagsInputConfig): HTMLDocumentTagsElement;
+}
+
+declare global {
+    interface DocumentTagsInputConfig extends FormInputConfig<string[]> {
+        /** A specific document type in CONST.ALL_DOCUMENT_TYPES */
+        type?: string;
+        /**
+         * 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;
+    }
+}

package/src/client/applications/elements/enriched-content.d.mts

@@ -0,0 +1,31 @@
+/**
+ * A custom HTMLElement that is used to wrap enriched content that requires additional interactivity.
+ */
+export default class HTMLEnrichedContentElement extends HTMLElement {
+    /**
+     * The HTML tag named used by this element.
+     */
+    static tagName: string;
+
+    /**
+     * Attributes requiring change notifications
+     */
+    static observedAttributes: string[];
+
+    /* -------------------------------------------- */
+    /*  Element Lifecycle                           */
+    /* -------------------------------------------- */
+
+    /**
+     * Invoke the enricher onRender callback when it is added to the DOM.
+     */
+    connectedCallback(): void;
+
+    /**
+     * Fire a callback on change to an observed attribute.
+     * @param attrName The name of the attribute
+     * @param oldValue The old value: null indicates the attribute was not present.
+     * @param newValue The new value: null indicates the attribute is removed.
+     */
+    attributeChangedCallback(attrName: string, oldValue: string | null, newValue: string | null): void;
+}

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

@@ -0,0 +1,59 @@
+import FilePicker, { FilePickerFileType } from "../apps/file-picker.mjs";
+import { FormInputConfig } from "./../../../common/data/_module.mjs";
+import AbstractFormInputElement from "./form-element.mjs";
+
+export interface FilePickerInputConfig extends FormInputConfig<string> {
+    type?: FilePickerFileType;
+    placeholder?: string;
+    noupload?: boolean;
+}
+
+/**
+ * A custom HTML element responsible for rendering a file input field and associated FilePicker button.
+ */
+export default class HTMLFilePickerElement extends AbstractFormInputElement<string> {
+    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 foundry.applications.apps.FilePicker.FILE_TYPES}
+     */
+    get type(): FilePickerFileType;
+
+    set type(value);
+
+    /**
+     * Prevent uploading new files as part of this element's FilePicker dialog.
+     */
+    get noupload(): boolean;
+
+    set noupload(value);
+
+    protected override _buildElements(): HTMLElement[];
+
+    protected override _refresh(): void;
+
+    protected override _toggleDisabled(disabled: boolean): void;
+
+    protected override _activateListeners(): void;
+
+    /**
+     * Create a HTMLFilePickerElement using provided configuration data.
+     */
+    static create(config: FilePickerInputConfig): HTMLFilePickerElement;
+}

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

@@ -0,0 +1,105 @@
+/**
+ * An abstract custom HTMLElement designed for use with form inputs.
+ *
+ * @fires {Event} input           An "input" event when the value of the input changes
+ * @fires {Event} change          A "change" event when the value of the element changes
+ */
+export default abstract class AbstractFormInputElement<TInternalValue, TInputValue = TInternalValue> extends HTMLElement {
+    /** The HTML tag name used by this element. */
+    static tagName: string;
+
+    /** Declare that this custom element provides form element functionality. */
+    static formAssociated: boolean;
+
+    /** Attributes requiring change notifications */
+    static observedAttributes: string[];
+
+    /** Attached ElementInternals which provides form handling functionality. */
+    protected _internals: ElementInternals;
+
+    /**
+     * The primary input (if any). Used to determine what element should receive focus when an associated label is clicked
+     * on.
+     */
+    protected _primaryInput: HTMLElement;
+
+    /** The form this element belongs to. */
+    get form(): HTMLFormElement;
+
+    /* -------------------------------------------- */
+    /*  Element Properties                          */
+    /* -------------------------------------------- */
+
+    /** The input element name. */
+    get name(): string;
+    set name(value);
+
+    /** The value of the input element. */
+    get value(): TInputValue;
+    set value(value: string | TInputValue);
+
+    /** The underlying value of the element. */
+    protected _value: TInternalValue;
+
+    /** Return the value of the input element which should be submitted to the form. */
+    protected _getValue(): TInternalValue;
+
+    /**
+     * 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: TInputValue): void;
+
+    /** Is this element disabled? */
+    get disabled(): boolean;
+    set disabled(value: 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;
+
+    /* -------------------------------------------- */
+    /*  Element Lifecycle                           */
+    /* -------------------------------------------- */
+
+    /** 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
+     */
+    _applyInputAttributes(input: HTMLInputElement): void;
+
+    /**
+     * Fire a callback on change to an observed attribute.
+     * @param attrName The name of the attribute
+     * @param oldValue The old value: null indicates the attribute was not present.
+     * @param newValue The new value: null indicates the attribute is removed.
+     */
+    attributeChangedCallback(attrName: string, oldValue: string | null, newValue: string | null): 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/client/applications/elements/hue-slider.d.mts

@@ -0,0 +1,35 @@
+import { HexColorString } from "./../../../common/constants.mjs";
+import { FormInputConfig } from "./../../../common/data/_types.mjs";
+import AbstractFormInputElement from "./form-element.mjs";
+
+/**
+ * A class designed to standardize the behavior for a hue selector UI component.
+ */
+export default class HTMLHueSelectorSlider extends AbstractFormInputElement<number> {
+    static override tagName: "hue-slider";
+
+    protected override _buildElements(): [HTMLInputElement];
+
+    /**
+     * Refresh the active state of the custom element.
+     */
+    protected _refresh(): void;
+
+    /**
+     * Activate event listeners which add dynamic behavior to the custom element.
+     */
+    protected _activateListeners(): void;
+
+    /* -------------------------------------------- */
+    /*  Form Handling                               */
+    /* -------------------------------------------- */
+
+    protected override _setValue(value: string | number): void;
+
+    protected override _toggleDisabled(disabled: boolean): void;
+
+    /**
+     * Create a HTMLHueSelectorSlider using provided configuration data.
+     */
+    static create(config: FormInputConfig<HexColorString>): HTMLHueSelectorSlider;
+}

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

@@ -0,0 +1,89 @@
+import { MultiSelectInputConfig } from "../forms/fields.mjs";
+import AbstractFormInputElement from "./form-element.mjs";
+
+/**
+ * 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 abstract class AbstractMultiSelectElement extends AbstractFormInputElement<string[], 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;
+
+    /* -------------------------------------------- */
+    /*  Form Handling                               */
+    /* -------------------------------------------- */
+
+    override _getValue(): string[];
+
+    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 {
+    static override tagName: "multi-select";
+
+    /**
+     * Create a HTMLMultiSelectElement using provided configuration data.
+     * @param {FormInputConfig<string[]> & Omit<SelectInputConfig, "blank">} config
+     * @returns {HTMLMultiSelectElement}
+     */
+    static create(config: MultiSelectInputConfig): HTMLMultiSelectElement;
+}
+
+/**
+ * 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 {
+    static override tagName: "multi-checkbox";
+}

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

@@ -0,0 +1,32 @@
+import * as ProseMirror from "prosemirror-state";
+import { FormInputConfig } from "./../../../common/data/_types.mjs";
+import { DocumentUUID } from "./../../utils/_module.mjs";
+import AbstractFormInputElement from "./form-element.mjs";
+
+/**
+ * A custom HTML element responsible displaying a ProseMirror rich text editor.
+ */
+export default class HTMLProseMirrorElement extends AbstractFormInputElement<string> {
+    static override tagName: "prose-mirror";
+
+    disconnectedCallback(): void;
+
+    /** Configure ProseMirror editor plugins. */
+    protected _configurePlugins(): Record<string, ProseMirror.Plugin>;
+
+    /** Create a HTMLProseMirrorElement using provided configuration data. */
+    static create(config: ProseMirrorInputConfig): HTMLProseMirrorElement;
+}
+
+declare global {
+    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;
+        /** A Document UUID. Required for collaborative editing */
+        documentUUID?: DocumentUUID;
+    }
+}

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

@@ -0,0 +1,23 @@
+import { FormInputConfig } from "./../../../common/data/_module.mjs";
+import AbstractFormInputElement from "./form-element.mjs";
+
+/**
+ * A custom HTML element responsible selecting a value on a range slider with a linked number input field.
+ */
+export default class HTMLRangePickerElement extends AbstractFormInputElement<number> {
+    static override tagName: "range-picker";
+
+    /** The value of the input element. */
+    get valueAsNumber(): number;
+
+    protected override _buildElements(): HTMLInputElement[];
+
+    /** Create a HTMLRangePickerElement using provided configuration data. */
+    static create(config: RangePickerInputConfig): HTMLRangePickerElement;
+}
+
+export interface RangePickerInputConfig extends FormInputConfig<number> {
+    min: number;
+    max: number;
+    step?: number;
+}

package/src/client/applications/elements/secret-block.d.mts

@@ -0,0 +1,28 @@
+/**
+ * A custom HTML element used to wrap secret blocks in HTML content in order to provide additional interactivity.
+ */
+export default class HTMLSecretBlockElement extends HTMLElement {
+    /**
+     * The HTML tag named used by this element.
+     */
+    static tagName: "secret-block";
+
+    /**
+     * The wrapped secret block.
+     */
+    get secret(): HTMLElement;
+
+    /**
+     * The revealed state of the secret block.
+     */
+    get revealed(): boolean;
+
+    connectedCallback(): void;
+
+    /**
+     * Toggle the secret revealed or hidden state in content that this secret block represents.
+     * @param content The raw string content for this secret.
+     * @returns The modified raw content.
+     */
+    toggleRevealed(content: string): string;
+}

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

@@ -0,0 +1,50 @@
+import { FormInputConfig } from "./../../../common/data/_module.mjs";
+import AbstractFormInputElement from "./form-element.mjs";
+
+/**
+ * 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.
+ */
+export default class HTMLStringTagsElement extends AbstractFormInputElement<Set<string>, string[]> {
+    static override tagName: "string-tags";
+
+    static icons: {
+        add: string;
+        remove: string;
+    };
+
+    static labels: {
+        add: string;
+        remove: string;
+        placeholder: 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;
+
+    /**
+     * Render the HTML fragment used to represent a tag.
+     * @param tag       The raw tag value
+     * @param label     An optional tag element
+     * @param [editable=true] Is the tag editable?
+     * @returns         An HTML string for the tag
+     */
+    static renderTag(tag: string, label?: string, editable?: boolean): string;
+
+    /* -------------------------------------------- */
+    /*  Form Handling                               */
+    /* -------------------------------------------- */
+
+    /** Create a HTMLStringTagsElement using provided configuration data. */
+    static create(config: FormInputConfig<string>): HTMLStringTagsElement;
+}

package/src/client/applications/forms/fields.d.mts

@@ -0,0 +1,132 @@
+import { HTMLMultiSelectElement } from "../elements/multi-select.mjs";
+import { FormGroupConfig, FormInputConfig } from "./../../../common/data/_types.mjs";
+
+/** Create a standardized form field group. */
+export function createFormGroup(config: FormGroupConfig): HTMLDivElement;
+
+/** Create an `<input type="checkbox">` element for a BooleanField. */
+export function createCheckboxInput(config: FormInputConfig<boolean>): HTMLInputElement;
+
+/** Create a `<div class="editor">` element for a StringField. */
+export function createEditorInput(config: EditorInputConfig): HTMLDivElement;
+
+/** Create a `<multi-select>` element for a StringField. */
+export function createMultiSelectInput(config: MultiSelectInputConfig): HTMLMultiSelectElement;
+
+/** Create an `<input type="number">` element foFormInputConfig<number> & NumberInputConfigr a NumberField. */
+export function createNumberInput(config: NumberInputConfig): HTMLInputElement;
+
+/** Create a `<select>` element for a StringField. */
+export function createSelectInput(config: SelectInputConfig): HTMLSelectElement;
+
+/** Create a `<textarea>` element for a StringField. */
+export function createTextareaInput(config: TextAreaInputConfig): HTMLTextAreaElement;
+
+/** Create an `<input type="text">` element for a StringField. */
+export function createTextInput(config: FormInputConfig<string>): HTMLInputElement;
+
+/* ---------------------------------------- */
+/*  Helper Methods                          */
+/* ---------------------------------------- */
+
+/**
+ * Structure a provided array of select options into a standardized format for rendering optgroup and option elements.
+ *
+ * @example
+ * const options = [
+ *   {value: "bar", label: "Bar", selected: true, group: "Good Options"},
+ *   {value: "foo", label: "Foo", disabled: true, group: "Bad Options"},
+ *   {value: "baz", label: "Baz", group: "Good Options"}
+ * ];
+ * const groups = ["Good Options", "Bad Options", "Unused Options"];
+ * const optgroups = foundry.applications.fields.prepareSelectOptionGroups({options, groups, blank: true, sort: true});
+ */
+export function prepareSelectOptionGroups(config: FormInputConfig<string> & SelectInputConfig): { group: string; options: FormSelectOption[] }[];
+
+/**
+ * Apply standard attributes to all input elements.
+ * @param input The element being configured
+ * @param config Configuration for the element
+ */
+export function setInputAttributes<TValue extends string | boolean = string | boolean>(input: HTMLElement, config: FormInputConfig<TValue>): void;
+
+/**
+ * Create an HTML element for a FontAwesome icon
+ * @param glyph A FontAwesome glyph name, such as "file" or "user"
+ * @param options Additional options to configure the icon
+ * @param options.style The style name for the icon
+ * @param options.fixedWidth Should icon be fixed-width?
+ * @param options.classes Additional classes to append to the class list
+ * @returns The configured FontAwesome icon element
+ * @see {@link https://fontawesome.com/search}
+ */
+export function createFontAwesomeIcon(
+    glyph: string,
+    options?: { style?: "solid" | "regular" | "duotone"; fixedWidth?: boolean; classes?: string[] },
+): HTMLElement;
+
+export type CustomFormGroup = (field: foundry.data.fields.DataField, groupConfig: FormGroupConfig) => HTMLDivElement;
+
+export type CustomFormInput = (field: foundry.data.fields.DataField, config: FormInputConfig) => HTMLElement | HTMLCollection;
+
+export interface EditorInputConfig extends FormInputConfig<string> {
+    /** Default: `prosemirror` */
+    engine?: string;
+    height?: number;
+    /** Default: `true` */
+    editable?: boolean;
+    /** Default: `false` */
+    button?: boolean;
+    /** Default: `false` */
+    collaborate?: boolean;
+}
+
+export interface FormSelectOption {
+    value: string;
+    label: string;
+    /** An optional `optgoup` for this option */
+    group?: string;
+    disabled?: boolean;
+    selected?: boolean;
+}
+
+export interface SelectInputConfig extends FormInputConfig<string> {
+    /** The name of the form element */
+    name: string;
+    /** The select options */
+    options: FormSelectOption[];
+    /**
+     * An option to control the order and display of optgroup elements. The order of
+     *  strings defines the displayed order of optgroup elements.
+     *  A blank string may be used to define the position of ungrouped options.
+     *  If not defined, the order of groups corresponds to the order of options.
+     */
+    groups?: string[];
+    /** Adds a blank option with the `blank` value as the label */
+    blank?: string;
+    /** An alternative value key of the object passed to the options array */
+    valueAttr?: string;
+    /** An alternative label key of the object passed to the options array */
+    labelAttr?: string;
+    /** Localize value labels. Default: `false` */
+    localize?: boolean;
+    /** Sort options alphabetically by label within groups. Default: `false` */
+    sort?: boolean;
+}
+
+export type MultiSelectInputConfig = Omit<SelectInputConfig, "blank"> & {
+    /** Creates a multi-checkbox element instead */
+    type?: "checkboxes";
+    /** The currently selected values */
+    value?: string[];
+};
+
+export interface NumberInputConfig extends FormInputConfig<number> {
+    min: number;
+    max: number;
+    step: number | "any";
+}
+
+export interface TextAreaInputConfig extends FormInputConfig<string> {
+    rows: number;
+}