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

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

@@ -0,0 +1,76 @@
+import type { InexactPartial } from "../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * A collection of functions related to sorting objects within a parent container.
+   */
+  class SortingHelpers {
+    /**
+     * Given a source object to sort, a target to sort relative to, and an Array of siblings in the container:
+     * Determine the updated sort keys for the source object, or all siblings if a reindex is required.
+     * Return an Array of updates to perform, it is up to the caller to dispatch these updates.
+     * Each update is structured as:
+     * ```typescript
+     * {
+     *   target: object,
+     *   update: {sortKey: sortValue}
+     * }
+     * ```
+     *
+     * @param source  - source object being sorted
+     * @param options - Options which modify the sort behavior
+     * @typeParam T   - the type of the source and target object
+     *
+     * @returns An Array of updates for the caller of the helper function to perform
+     */
+    static performIntegerSort<T, SortKey extends string = "sort">(
+      source: T,
+      options?: InexactPartial<SortingHelpers.SortOptions<T, SortKey>>,
+    ): Array<{
+      target: T;
+      update: {
+        [Key in SortKey]: number;
+      };
+    }>;
+
+    /**
+     * Given an ordered Array of siblings and a target position, return the [min,max] indices to sort before the target
+     */
+    protected static _sortBefore<T>(siblings: T[], idx: number, sortKey: string): [T, T];
+
+    /**
+     * Given an ordered Array of siblings and a target position, return the [min,max] indices to sort after the target
+     */
+    protected static _sortAfter<T>(siblings: T[], idx: number, sortKey: string): [T, T];
+  }
+
+  namespace SortingHelpers {
+    interface SortOptions<T, SortKey extends string = "sort"> {
+      /**
+       * The target object relative which to sort
+       * @defaultValue `null`
+       */
+      target: T | null;
+
+      /**
+       * The sorted Array of siblings which share the same sorted container
+       * @defaultValue `[]`
+       */
+      siblings: T[];
+
+      /**
+       * The name of the data property within the source object which defines the sort key
+       * @defaultValue `"sort"`
+       */
+      sortKey: SortKey;
+
+      /**
+       * Whether to explicitly sort before (true) or sort after (false). If nothing is passed
+       * the sort order will be automatically determined, preferring before.
+       *
+       * @defaultValue `true`
+       */
+      sortBefore: boolean;
+    }
+  }
+}

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

@@ -0,0 +1,73 @@
+import type Document from "../../common/abstract/document.d.mts";
+
+declare global {
+  /**
+   * A singleton class {@link game#time} which keeps the official Server and World time stamps.
+   * Uses a basic implementation of https://www.geeksforgeeks.org/cristians-algorithm/ for synchronization.
+   */
+  class GameTime {
+    constructor(socket?: io.Socket | null);
+
+    /**
+     * The most recently synchronized timestamps retrieved from the server.
+     * @defaultValue `{}`
+     */
+    protected _time: GameTime.Timestamps;
+
+    /**
+     * The average one-way latency across the most recent 5 trips
+     * @defaultValue `0`
+     */
+    protected _dt: number;
+
+    /**
+     * The most recent five synchronization durations
+     * @defaultValue `[]`
+     */
+    protected _dts: number[];
+
+    /**
+     * The amount of time to delay before re-syncing the official server time.
+     * @defaultValue `1000 * 60 * 5`
+     */
+    static SYNC_INTERVAL_MS: number;
+
+    /**
+     * The current server time based on the last synchronization point and the approximated one-way latency.
+     */
+    get serverTime(): number;
+
+    /**
+     * The current World time based on the last recorded value of the core.time setting
+     */
+    get worldTime(): number;
+
+    /**
+     * Advance the game time by a certain number of seconds
+     * @param seconds - The number of seconds to advance (or rewind if negative) by
+     * @param options - Additional options passed to game.settings.set
+     * @returns The new game time
+     */
+    advance(seconds: number, options?: Document.OnUpsertOptions<"Setting">): Promise<number>;
+
+    /**
+     * Synchronize the local client game time with the official time kept by the server
+     * @param socket - The connected server Socket instance
+     */
+    sync(socket?: io.Socket | null): Promise<this>;
+
+    /**
+     * Handle follow-up actions when the official World time is changed
+     * @param worldTime - The new canonical World time.
+     */
+    onUpdateWorldTime(worldTime: number): void;
+  }
+
+  namespace GameTime {
+    interface Timestamps {
+      clientTime: number;
+      serverTime: number;
+      worldTime: number;
+    }
+  }
+}

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;
+  }
+}