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

package/src/foundry/client/core/tooltip.d.mts

@@ -0,0 +1,198 @@
+import type { ValueOf } from "../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * A singleton Tooltip Manager class responsible for rendering and positioning a dynamic tooltip element which is
+   * accessible as `game.tooltip`.
+   *
+   * @see {@link Game.tooltip}
+   *
+   * @example API Usage
+   * ```typescript
+   * game.tooltips.activate(htmlElement, {text: "Some tooltip text", direction: "UP"});
+   * game.tooltips.deactivate();
+   * ```
+   *
+   * @example HTML Usage
+   * ```html
+   * <span data-tooltip="Some Tooltip" data-tooltip-direction="LEFT">I have a tooltip</span>
+   * <ol data-tooltip-direction="RIGHT">
+   *   <li data-tooltip="The First One">One</li>
+   *   <li data-tooltip="The Second One">Two</li>
+   *   <li data-tooltip="The Third One">Three</li>
+   * </ol>
+   * ```
+   */
+  class TooltipManager {
+    /**
+     * A cached reference to the global tooltip element
+     */
+    tooltip: HTMLElement;
+
+    /**
+     * A reference to the HTML element which is currently tool-tipped, if any.
+     */
+    element: HTMLElement | null;
+
+    /**
+     * An amount of margin which is used to offset tooltips from their anchored element.
+     * @defaultValue `5`
+     */
+    static TOOLTIP_MARGIN_PX: number;
+
+    /**
+     * The number of milliseconds delay which activates a tooltip on a "long hover".
+     * @defaultValue `500`
+     */
+    static TOOLTIP_ACTIVATION_MS: number;
+
+    /**
+     * The directions in which a tooltip can extend, relative to its tool-tipped element.
+     */
+    static TOOLTIP_DIRECTIONS: {
+      UP: "UP";
+      DOWN: "DOWN";
+      LEFT: "LEFT";
+      RIGHT: "RIGHT";
+      CENTER: "CENTER";
+    };
+
+    /**
+     * The number of pixels buffer around a locked tooltip zone before they should be dismissed.
+     * @defaultValue `50`
+     */
+    static LOCKED_TOOLTIP_BUFFER_PX: number;
+
+    /**
+     * Activate interactivity by listening for hover events on HTML elements which have a data-tooltip defined.
+     */
+    activateEventListeners(): void;
+
+    /**
+     * Activate the tooltip for a hovered HTML element which defines a tooltip localization key.
+     * @param element - The HTML element being hovered.
+     * @param options - Additional options which can override tooltip behavior. (default: `{}`)
+     */
+    activate(
+      element: HTMLElement,
+      options?: {
+        /**
+         * Explicit tooltip text to display. If this is not provided the tooltip text is
+         * acquired from the elements data-tooltip attribute. This text will be
+         * automatically localized
+         */
+        text?: string;
+        /**
+         * An explicit tooltip expansion direction. If this is not provided the direction is acquired
+         * from the data-tooltip-direction attribute of the element or one of its parents.
+         */
+        direction?: TooltipManager.TOOLTIP_DIRECTIONS;
+        /**
+         * An optional, space-separated list of CSS classes to apply to the activated
+         * tooltip. If this is not provided, the CSS classes are acquired from the
+         * data-tooltip-class attribute of the element or one of its parents.
+         */
+        cssClass?: string;
+        /** An optional boolean to lock the tooltip after creation. Defaults to false. */
+        locked?: boolean;
+        /** Explicit HTML content to inject into the tooltip rather than using tooltip text. */
+        content?: HTMLElement;
+      },
+    ): void;
+
+    /**
+     * Deactivate the tooltip from a previously hovered HTML element.
+     * @internal
+     */
+    deactivate(): void;
+
+    /**
+     * Clear any pending activation workflow.
+     * @internal
+     */
+    clearPending(): void;
+
+    /**
+     * Lock the current tooltip.
+     */
+    lockTooltip(): HTMLElement;
+
+    /**
+     * Handle a request to lock the current tooltip.
+     * @param event - The click event.
+     */
+    protected _onLockTooltip(event: MouseEvent): void;
+
+    /**
+     * Handle dismissing a locked tooltip.
+     * @param event - The click event.
+     */
+    protected _onLockedTooltipDismiss(event: MouseEvent): void;
+
+    /**
+     * Dismiss a given locked tooltip.
+     * @param element - The locked tooltip to dismiss.
+     */
+    dismissLockedTooltip(element: HTMLElement): void;
+
+    /**
+     * Dismiss the set of active locked tooltips.
+     */
+    dismissLockedTooltips(): void;
+
+    /**
+     * Create a locked tooltip at the given position.
+     * @param position - A position object with coordinates for where the tooltip should be placed
+     * @param text     - Explicit tooltip text or HTML to display.
+     * @param options  - Additional options which can override tooltip behavior.
+     */
+    createLockedTooltip(
+      position: {
+        /** Explicit top position for the tooltip */
+        top?: string;
+        /** Explicit right position for the tooltip */
+        right?: string;
+        /** Explicit bottom position for the tooltip */
+        bottom?: string;
+        /** Explicit left position for the tooltip */
+        left?: string;
+      },
+      text: string,
+      options?: {
+        /** An optional, space-separated list of CSS classes to apply to the activated  tooltip. */
+        cssClass: string;
+      },
+    ): HTMLElement;
+
+    /**
+     * If an explicit tooltip expansion direction was not specified, figure out a valid direction based on the bounds
+     * of the target element and the screen.
+     */
+    protected _determineDirection(): ValueOf<Pick<typeof TooltipManager.TOOLTIP_DIRECTIONS, "UP" | "DOWN">>;
+
+    /**
+     * Set tooltip position relative to an HTML element using an explicitly provided data-tooltip-direction.
+     * @param direction - The tooltip expansion direction specified by the element or a parent element.
+     */
+    protected _setAnchor(direction: TooltipManager.TOOLTIP_DIRECTIONS): void;
+
+    /**
+     * Apply inline styling rules to the tooltip for positioning and text alignment.
+     * @param position - An object of positioning data, supporting top, right, bottom, left, and textAlign
+     */
+    protected _setStyle(position?: {
+      top?: null | number;
+      right?: null | number;
+      bottom?: null;
+      left?: null;
+      textAlign?: string;
+    }): void;
+  }
+
+  namespace TooltipManager {
+    /**
+     * The directions in which a tooltip can extend, relative to its tool-tipped element.
+     */
+    type TOOLTIP_DIRECTIONS = ValueOf<(typeof TooltipManager)["TOOLTIP_DIRECTIONS"]>;
+  }
+}

package/src/foundry/client/core/tour.d.mts

@@ -0,0 +1,279 @@
+import type { ValueOf } from "../../../types/utils.d.mts";
+
+export { Tour };
+
+declare global {
+  /** A step in a Tour */
+  interface TourStep {
+    /** A machine-friendly id of the Tour Step */
+    id: string;
+
+    /** A DOM selector which denotes an element to highlight during this step */
+    selector?: string;
+
+    /** The title of the step, displayed in the tooltip header */
+    title: string;
+
+    /** Raw HTML content displayed during the step */
+    content: string;
+
+    /** How the tooltip for the step should be displayed relative to the target elemen */
+    tooltipDirection?: TooltipManager.TOOLTIP_DIRECTIONS;
+
+    /** Whether the Step is restricted to the GM only */
+    restricted?: boolean;
+  }
+
+  /** Tour configuration data */
+  interface TourConfig {
+    /** The namespace this Tour belongs to. Typically, the name of the package which implements the tour should be used */
+    namespace?: string;
+
+    /** A machine-friendly id of the Tour, must be unique within the provided namespace */
+    id?: string;
+
+    /** A human-readable name for this Tour */
+    title: string;
+
+    /** A human-readable description of this Tour */
+    description?: string;
+
+    /** The list of Tour Steps */
+    steps: TourStep[];
+
+    /** A map of translations for the Tour that should be merged into the default translations */
+    localization?: Localization.Translations;
+
+    /** Whether the Tour is restricted to the GM only */
+    restricted?: boolean;
+
+    /** Whether the Tour should be displayed in the Manage Tours UI */
+    display?: boolean;
+
+    /** Whether the Tour can be resumed or if it always needs to start from the beginning */
+    canBeResumed?: boolean;
+
+    /**
+     * A list of namespaced Tours that might be suggested to the user when this Tour is completed.
+     * The first non-completed Tour in the array will be recommended.
+     */
+    suggestedNextTours?: string[];
+  }
+
+  namespace Tour {
+    type STATUS = ValueOf<typeof Tour.STATUS>;
+  }
+
+  /**
+   * A Tour that shows a series of guided steps.
+   */
+  class Tour {
+    /**
+     * @param config - The configuration of the Tour
+     */
+    constructor(config: TourConfig, { id, namespace }?: { id?: TourConfig["id"]; namespace?: TourConfig["namespace"] });
+    /**
+     * The configuration of the tour. Cloned to avoid mutating the original configuration.
+     */
+    config: TourConfig;
+
+    static STATUS: Readonly<{
+      UNSTARTED: "unstarted";
+      IN_PROGRESS: "in-progress";
+      COMPLETED: "completed";
+    }>;
+
+    /**
+     * Indicates if a Tour is currently in progress.
+     */
+    static get tourInProgress(): boolean;
+
+    /**
+     * Returns the active tour, if any.
+     */
+    static get activeTour(): Tour | null;
+
+    /**
+     * Handle a movement action to either progress or regress the Tour.
+     * @param movementDirections - The Directions being moved in
+     */
+    static onMovementAction(movementDirections: string[]): boolean;
+
+    /**
+     * The HTMLElement which is the focus of the current tour step.
+     */
+    targetElement: HTMLElement | undefined;
+
+    /**
+     * The HTMLElement that fades out the rest of the screen
+     */
+    fadeElement: HTMLElement | undefined;
+
+    /**
+     * The HTMLElement that blocks input while a Tour is active
+     */
+    overlayElement: HTMLElement | undefined;
+
+    /**
+     * Padding around a Highlighted Element
+     * @defaultValue `10`
+     */
+    static HIGHLIGHT_PADDING: number;
+
+    /**
+     * The unique identifier of the tour.
+     */
+    get id(): string | undefined;
+
+    set id(value: string | undefined);
+
+    /**
+     * The human-readable title for the tour.
+     */
+    get title(): string;
+
+    /**
+     * The human-readable description of the tour.
+     */
+    get description(): string | undefined;
+
+    /**
+     * The package namespace for the tour.
+     */
+    get namespace(): string | undefined;
+
+    set namespace(value: string | undefined);
+
+    /**
+     * The key the Tour is stored under in game.tours, of the form `${namespace}.${id}`
+     */
+    get key(): string;
+
+    /**
+     * The configuration of tour steps
+     */
+    get steps(): TourStep[];
+
+    /**
+     * Return the current Step, or null if the tour has not yet started.
+     */
+    get currentStep(): TourStep | null;
+
+    /**
+     * The index of the current step; -1 if the tour has not yet started, or null if the tour is finished.
+     */
+    get stepIndex(): number | null;
+
+    /**
+     * Returns True if there is a next TourStep
+     */
+    get hasNext(): boolean;
+
+    /**
+     * Returns True if there is a previous TourStep
+     */
+    get hasPrevious(): boolean;
+
+    /**
+     * Return whether this Tour is currently eligible to be started?
+     * This is useful for tours which can only be used in certain circumstances, like if the canvas is active.
+     */
+    get canStart(): boolean;
+
+    /**
+     * The current status of the Tour
+     */
+    get status(): Tour.STATUS;
+
+    /**
+     * Advance the tour to a completed state.
+     */
+    complete(): Promise<void>;
+
+    /**
+     * Exit the tour at the current step.
+     */
+    exit(): void;
+
+    /**
+     * Reset the Tour to an un-started state.
+     */
+    reset(): Promise<void>;
+
+    /**
+     * Start the Tour at its current step, or at the beginning if the tour has not yet been started.
+     */
+    start(): Promise<void>;
+
+    /**
+     * Progress the Tour to the next step.
+     */
+    next(): Promise<void>;
+
+    /**
+     * Rewind the Tour to the previous step.
+     */
+    previous(): Promise<void>;
+
+    /**
+     * Progresses to a given Step
+     * @param stepIndex - The step to progress to
+     */
+    progress(stepIndex: number): Promise<void>;
+
+    /**
+     * Query the DOM for the target element using the provided selector
+     * @param selector - A CSS selector
+     * @returns The target element, or null if not found
+     */
+    protected _getTargetElement(selector: string): Element | null;
+
+    /**
+     * Creates and returns a Tour by loading a JSON file
+     * @param filepath - The path to the JSON file
+     */
+    static fromJSON(filepath: string): Promise<Tour>;
+
+    /**
+     * Set-up operations performed before a step is shown.
+     * @virtual
+     */
+    protected _preStep(): Promise<void>;
+
+    /**
+     * Clean-up operations performed after a step is completed.
+     * @virtual
+     */
+    protected _postStep(): Promise<void>;
+
+    /**
+     * Renders the current Step of the Tour
+     */
+    protected _renderStep(): Promise<void>;
+
+    /**
+     * Handle Tour Button clicks
+     * @param event - A click event
+     * @internal
+     */
+    protected _onButtonClick(event: MouseEvent): Promise<void>;
+
+    /**
+     * Saves the current progress of the Tour to a world setting
+     * @internal
+     */
+    protected _saveProgress(): void;
+
+    /**
+     * Returns the User's current progress of this Tour
+     * @internal
+     */
+    protected _loadProgress(): null | number;
+
+    /**
+     * Reloads the Tour's current step from the saved progress
+     * @internal
+     */
+    _reloadProgress(): void;
+  }
+}

package/src/foundry/client/core/tours.d.mts

@@ -0,0 +1,22 @@
+export {};
+
+declare global {
+  /**
+   * A singleton Tour Collection class responsible for registering and activating Tours, accessible as game.tours
+   * @see {@link Game.tours}
+   */
+  class Tours extends foundry.utils.Collection<Tour> {
+    /** @throws `"You can only have one TourManager instance"` */
+    constructor();
+
+    /**
+     * Register a new Tour
+     * @param namespace - The namespace of the Tour
+     * @param id        - The machine-readable id of the Tour
+     * @param tour      - The constructed Tour
+     */
+    register(namespace: string, id: string, tour: Tour): void;
+
+    override set(key: string, tour: Tour): this;
+  }
+}

package/src/foundry/client/core/utils.d.mts

@@ -0,0 +1,71 @@
+import type { GetKey } from "../../../types/helperTypes.d.mts";
+
+declare global {
+  /**
+   * Export data content to be saved to a local file
+   * @param data     - Data content converted to a string
+   * @param type     - The type of
+   * @param filename - The filename of the resulting download
+   */
+  function saveDataToFile(data: string, type: string, filename: string): void;
+
+  /**
+   * Read text data from a user provided File object
+   * @param file - A File object
+   * @returns A Promise which resolves to the loaded text data
+   */
+  function readTextFromFile(file: File): Promise<string>;
+
+  /**
+   * Retrieve an Entity or Embedded Entity by its Universally Unique Identifier (uuid).
+   * @param uuid    - The uuid of the Entity or Embedded Entity to retrieve
+   * @param options - Options to configure how a UUID is resolved.
+   */
+  function fromUuid(
+    uuid: string,
+    options?: {
+      /** A Document to resolve relative UUIDs against. */
+      relative?: ClientDocument;
+      /** Allow retrieving an invalid Document. (default: `false`) */
+      invalid?: boolean;
+    },
+  ): Promise<foundry.abstract.Document.Any | null>;
+
+  /**
+   * Retrieve a Document by its Universally Unique Identifier (uuid) synchronously. If the uuid resolves to a compendium
+   * document, that document's index entry will be returned instead.
+   * @param uuid     - The uuid of the Document to retrieve.
+   * @param relative - A document to resolve relative UUIDs against.
+   * @returns The Document or its index entry if it resides in a Compendium, otherwise null.
+   * @throws If the uuid resolves to a Document that cannot be retrieved synchronously.
+   */
+  function fromUuidSync(
+    uuid: string,
+    options?: {
+      /** A Document to resolve relative UUIDs against. */
+      relative?: ClientDocument;
+      /** Allow retrieving an invalid Document. (default: `false`) */
+      invalid?: boolean;
+      /** Throw an error if the UUID cannot be resolved synchronously. (default: `true`) */
+      strict?: boolean;
+    },
+  ): foundry.abstract.Document.Any | Record<string, unknown> | null;
+
+  /**
+   * Resolve a series of embedded document UUID parts against a parent Document.
+   * @param parent - The parent Document.
+   * @param parts  - A series of Embedded Document UUID parts.
+   * @returns The resolved Embedded Document.
+   * @internal
+   */
+  function _resolveEmbedded(parent: foundry.abstract.Document.Any, parts: string[]): foundry.abstract.Document.Any;
+
+  /**
+   * Return a reference to the Document class implementation which is configured for use.
+   * @param documentName - The canonical Document name, for example "Actor"
+   * @returns configured Document class implementation
+   */
+  function getDocumentClass<DocumentName extends string>(
+    documentName: DocumentName,
+  ): GetKey<GetKey<CONFIG, DocumentName, never>, "documentClass", undefined>;
+}