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

package/src/foundry/client/index.d.mts

@@ -1,12 +1,5 @@
-import "./apps/index.d.mts";
-import "./av/index.d.mts";
 import "./config.d.mts";
-import "./core/index.d.mts";
-import "./data/index.d.mts";
 import "./game.d.mts";
 import "./head.d.mts";
 import "./hooks.d.mts";
-import "./pixi/index.d.mts";
 import "./tail.d.mts";
-import "./tours/index.d.mts";
-import "./ui/index.d.mts";

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

@@ -0,0 +1,280 @@
+import type { ValueOf } from "#utils";
+
+/**
+ * A Tour that shows a series of guided steps.
+ */
+declare class Tour {
+  /**
+   * Construct a Tour by providing a configuration.
+   * @param config  - The configuration of the Tour
+   * @param options - Additional options for configuring the tour (default: `{}`)
+   */
+  constructor(config: Tour.Config, options?: Tour.ConstructorOptions);
+
+  static STATUS: Tour.STATUS;
+
+  /**
+   * 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[]): true | void;
+
+  /**
+   * Configuration of the tour. This object is cloned to avoid mutating the original configuration.
+   */
+  config: Tour.Config;
+
+  /**
+   * The HTMLElement which is the focus of the current tour step.
+   */
+  targetElement: HTMLElement | undefined | null;
+
+  /**
+   * 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;
+
+  set id(value: string);
+
+  /**
+   * 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;
+
+  set namespace(value: string);
+
+  /**
+   * 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(): Tour.Step[];
+
+  /**
+   * Return the current Step, or null if the tour has not yet started.
+   */
+  get currentStep(): Tour.Step | 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 circumnstances, 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 started.
+   */
+  start(): Promise<void>;
+
+  /**
+   * Progress the Tour to the next step.
+   */
+  next(): Promise<void>;
+
+  /**
+   * Reward 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
+   * @remarks Returns `new this()` so needs an override per subclass.
+   */
+  static fromJSON(filepath: string): Promise<Tour>;
+
+  /**
+   * Set-up operations performed before a step is shown.
+   * @abstract
+   */
+  protected _preStep(): Promise<void>;
+
+  /**
+   * Clean-up operations performed after a step is completed.
+   * @abstract
+   */
+  protected _postStep(): Promise<void>;
+
+  /**
+   * Renders the current Step of the Tour
+   */
+  protected _renderStep(): Promise<void>;
+
+  /**
+   * Reloads the Tour's current step from the saved progress
+   * @internal
+   */
+  _reloadProgress(): void;
+
+  #tour: true;
+}
+
+declare namespace Tour {
+  /** Tour configuration data */
+  interface Config {
+    /** 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. Localized. */
+    title: string;
+
+    /** The list of Tour Steps */
+    steps: Tour.Step[];
+
+    /** A human-readable description of this Tour. Localized. */
+    description?: string | undefined;
+
+    /** A map of localizations for the Tour that should be merged into the default localizations */
+    localization?: foundry.helpers.Localization.Translations | undefined;
+
+    /** Whether the Tour is restricted to the GM only. Defaults to false. */
+    restricted?: boolean | undefined;
+
+    /** Whether the Tour should be displayed in the Manage Tours UI. Defaults to false. */
+    display?: boolean | undefined;
+
+    /** Whether the Tour can be resumed or if it always needs to start from the beginning. Defaults to false. */
+    canBeResumed?: boolean | undefined;
+
+    /** 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[] | undefined;
+  }
+
+  /** A step in a Tour */
+  interface Step {
+    /** A machine-friendly id of the Tour Step */
+    id: string;
+
+    /** The title of the step, displayed in the tooltip header */
+    title: string;
+
+    /** Raw HTML content displayed during the step */
+    content: string;
+
+    /** A DOM selector which denotes an element to highlight during this step. If omitted, the step is displayed in the center of the screen. */
+    selector?: string | undefined;
+
+    /** How the tooltip for the step should be displayed relative to the target element. If omitted, the best direction will be attempted to be auto-selected. */
+    tooltipDirection?: foundry.helpers.interaction.TooltipManager.TOOLTIP_DIRECTIONS | undefined;
+
+    /** Whether the Step is restricted to the GM only. Defaults to false. */
+    restricted?: boolean | undefined;
+
+    /** Activates a particular sidebar tab. Usable in `SidebarTour` instances. */
+    sidebarTab?: string | undefined;
+
+    /** Activates a particular canvas layer and its respective control group. Usable in `CanvasTour` instances */
+    layer?: string | undefined;
+
+    /** Activates a particular tool. Usable in `CanvasTour` instances. */
+    tool?: string | undefined;
+  }
+
+  type Status = ValueOf<STATUS>;
+
+  interface ConstructorOptions {
+    /** A tour ID that supercedes `TourConfig#id` */
+    id: string;
+
+    /** A tour namespace that supercedes `TourConfig#namespace` */
+    namespace: string;
+  }
+
+  interface STATUS {
+    readonly UNSTARTED: "unstarted";
+    readonly IN_PROGRESS: "in-progress";
+    readonly COMPLETED: "completed";
+  }
+}
+
+export default Tour;

package/src/foundry/client/nue/tours/canvas-tour.d.mts

@@ -0,0 +1,15 @@
+import type Tour from "../tour.mjs";
+
+/**
+ * A tour for demonstrating an aspect of Canvas functionality.
+ * Automatically activates a certain canvas layer or tool depending on the needs of the step.
+ */
+declare class CanvasTour extends Tour {
+  override start(): Promise<void>;
+  override get canStart(): boolean;
+  protected override _preStep(): Promise<void>;
+}
+
+declare namespace CanvasTour {}
+
+export default CanvasTour;

package/src/foundry/client/nue/tours/setup-tour.d.mts

@@ -0,0 +1,31 @@
+import type Tour from "../tour.mjs";
+
+/**
+ * A Tour subclass that handles controlling the UI state of the Setup screen
+ */
+declare class SetupTour extends Tour {
+  constructor(config: SetupTour.Config, options?: Tour.ConstructorOptions);
+
+  /**
+   * Stores a currently open Application for future steps
+   */
+  focusedApp: foundry.appv1.api.Application.Any | foundry.applications.api.ApplicationV2.Any;
+
+  override get canStart(): boolean;
+  override get steps(): Tour.Step[];
+  protected override _preStep(): Promise<void>;
+
+  #setupTour: true;
+}
+
+declare namespace SetupTour {
+  interface Config extends Tour.Config {
+    /**
+     * Whether to close all open windows before beginning the tour.
+     * @defaultValue `true`
+     */
+    closeWindows: boolean;
+  }
+}
+
+export default SetupTour;

package/src/foundry/client/nue/tours/sidebar-tour.d.mts

@@ -0,0 +1,13 @@
+import type Tour from "../tour.mjs";
+
+/**
+ * A Tour subclass for the Sidebar Tour
+ */
+declare class SidebarTour extends Tour {
+  override start(): Promise<void>;
+  protected override _preStep(): Promise<void>;
+}
+
+declare namespace SidebarTour {}
+
+export default SidebarTour;

package/src/foundry/client/packages/_module.d.mts

@@ -0,0 +1,22 @@
+// 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-x/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import-x/extensions */
+
+import Module from "./module.mjs";
+import System from "./system.mjs";
+import World from "./world.mjs";
+
+export * as types from "./_types.mjs";
+export * from "#common/packages/_module.mjs";
+export { default as ClientPackageMixin } from "./client-package.mjs";
+export { Module, System, World };
+
+/**
+ * A mapping of allowed package types and the classes which implement them.
+ */
+export const PACKAGE_TYPES: {
+  world: typeof World;
+  system: typeof System;
+  module: typeof Module;
+};

package/src/foundry/client/packages/client-package.d.mts

@@ -0,0 +1,154 @@
+import type { FixedInstanceType, Mixin } from "#utils";
+import type { CONST } from "#client/client.d.mts";
+import type BasePackage from "#common/packages/base-package.d.mts";
+import type Module from "./module.d.mts";
+import type System from "./system.d.mts";
+
+/**
+ * A client-side mixin used for all Package types.
+ * @param BasePackage - The parent BasePackage class being mixed
+ * @returns A BasePackage subclass mixed with ClientPackage features
+ */
+declare function ClientPackageMixin<BaseClass extends ClientPackageMixin.BaseClass>(
+  BasePackage: BaseClass,
+): Mixin<typeof ClientPackageMixin.ClientPackage, BaseClass>;
+
+declare namespace ClientPackageMixin {
+  interface AnyMixedConstructor extends ReturnType<typeof ClientPackageMixin<BaseClass>> {}
+  interface AnyMixed extends FixedInstanceType<AnyMixedConstructor> {}
+
+  type BaseClass = BasePackage.Internal.Constructor;
+
+  interface PackageCompatibilityBadge {
+    type: "safe" | "unsafe" | "warning" | "neutral" | "error";
+    tooltip: string;
+    label?: string;
+    icon?: string;
+  }
+
+  interface ModuleCreateData extends Module.CreateData {
+    active: boolean;
+  }
+
+  interface SystemCreateData extends foundry.packages.BaseSystem.CreateData {
+    strictDataCleaning?: boolean;
+  }
+
+  interface GetVersionBadgeOptions {
+    /**
+     * A specific collection of modules to test availability against. Tests against the currently installed modules by default.
+     */
+    modules?: Collection<Module>;
+
+    /**
+     * A specific collection of systems to test availability against. Tests against the currently installed systems by default.
+     */
+    systems?: Collection<System>;
+  }
+
+  interface FormatBadDependenciesTooltipOptions {
+    /**
+     * A specific collection of modules to test availability against. Tests against the currently installed modules by default.
+     */
+    modules?: Collection<Module> | undefined;
+
+    /**
+     * A specific collection of systems to test availability against. Tests against the currently installed systems by default.
+     */
+    systems?: Collection<System> | undefined;
+  }
+
+  interface FormatIncompatibleSystemsTooltipOptions {
+    /**
+     * A specific collection of systems to test availability against. Tests against the currently installed systems by default.
+     */
+    systems?: Collection<System> | undefined;
+  }
+
+  interface FromRemoteManifestOptions {
+    /**
+     * Whether to construct the remote package strictly
+     * @defaultValue `true`
+     */
+    strict?: boolean | undefined;
+  }
+
+  class ClientPackage {
+    /** @privateRemarks All mixin classses should accept anything for its constructor. */
+    constructor(...args: any[]);
+
+    /**
+     * Is this package marked as a favorite?
+     * This boolean is currently only populated as true in the /setup view of the software.
+     */
+    favorite: false;
+
+    /**
+     * Associate package availability with certain badge for client-side display.
+     */
+    getVersionBadge(): PackageCompatibilityBadge | null;
+
+    /**
+     * Determine a version badge for the provided compatibility data.
+     * @param availability - The availability level.
+     * @param data         - The compatibility data.
+     * @param options      - (default: `{}`)
+     */
+    static getVersionBadge(
+      availability: CONST.PACKAGE_AVAILABILITY_CODES,
+      data: Partial<PackageManifestData>,
+      options: GetVersionBadgeOptions,
+    ): PackageCompatibilityBadge | null;
+
+    /**
+     * List missing dependencies and format them for display.
+     * @param availability - The availability level.
+     * @param data         - The compatibility data.
+     * @param options      - (default: `{}`)
+     */
+    static _formatBadDependenciesTooltip(
+      availability: CONST.PACKAGE_AVAILABILITY_CODES,
+      data: Partial<PackageManifestData>,
+      options: FormatBadDependenciesTooltipOptions,
+    ): string;
+
+    /**
+     * List missing dependencies and format them for display.
+     * @param availability - The availability level.
+     * @param data         - The compatibility data.
+     * @param options      - (default: `{}`)
+     */
+    static _formatIncompatibleSystemsTooltip(
+      availability: CONST.PACKAGE_AVAILABILITY_CODES,
+      data: Partial<PackageManifestData>,
+      options: FormatIncompatibleSystemsTooltipOptions,
+    ): string;
+
+    /**
+     * When a package has been installed, add it to the local game data.
+     */
+    install(): void;
+
+    /**
+     * When a package has been uninstalled, remove it from the local game data.
+     */
+    uninstall(): void;
+
+    /**
+     * Remove a package from the local game data when it has been uninstalled.
+     * @param id - The package ID.
+     */
+    static uninstall(id: string): void;
+
+    /**
+     * Retrieve the latest Package manifest from a provided remote location.
+     * @param manifest - A remote manifest URL to load
+     * @param options  - Additional options which affect package construction
+     * @returns A Promise which resolves to a constructed ServerPackage instance
+     * @throws An error if the retrieved manifest data is invalid
+     */
+    static fromRemoteManifest(manifest: string, options: FromRemoteManifestOptions): Promise<ClientPackage | null>;
+  }
+}
+
+export default ClientPackageMixin;

package/src/foundry/client/packages/module.d.mts

@@ -0,0 +1,87 @@
+import type BasePackage from "#common/packages/base-package.d.mts";
+import type AdditionalTypesField from "#common/packages/sub-types.d.mts";
+import type ClientPackageMixin from "./client-package.d.mts";
+
+import fields = foundry.data.fields;
+
+declare class Module extends ClientPackageMixin(foundry.packages.BaseModule) {
+  constructor(data: ClientPackageMixin.ModuleCreateData, options: unknown);
+
+  /**
+   * Is this package currently active?
+   */
+  readonly active: boolean;
+}
+
+declare namespace Module {
+  /**
+   * The data put in {@linkcode DataModel._source}. This data is what was
+   * persisted to the database and therefore it must be valid JSON.
+   *
+   * For example a {@link fields.SetField | `SetField`} is persisted to the database as an array
+   * but initialized as a {@linkcode Set}.
+   */
+  interface Source extends fields.SchemaField.SourceData<Schema> {}
+
+  /**
+   * The data necessary to create a data model. Used in places like {@linkcode Module.create}
+   * and {@link Module | `new Module(...)`}.
+   *
+   * For example a {@link fields.SetField | `SetField`} can accept any {@linkcode Iterable}
+   * with the right values. This means you can pass a `Set` instance, an array of values,
+   * a generator, or any other iterable.
+   */
+  interface CreateData extends fields.SchemaField.CreateData<Schema> {}
+
+  /**
+   * The data after a {@linkcode DataModel} has been initialized, for example
+   * {@link Module.name | `Module#name`}.
+   *
+   * This is data transformed from {@linkcode Module.Source} and turned into more
+   * convenient runtime data structures. For example a {@link fields.SetField | `SetField`} is
+   * persisted to the database as an array of values but at runtime it is a `Set` instance.
+   */
+  interface InitializedData extends fields.SchemaField.InitializedData<Schema> {}
+
+  /**
+   * The data used to update a document, for example {@link Module.update | `Module#update`}.
+   * It is a distinct type from {@link Module.CreateData | `DeepPartial<Module.CreateData>`} because
+   * it has different rules for `null` and `undefined`.
+   */
+  interface UpdateData extends fields.SchemaField.UpdateData<Schema> {}
+
+  /**
+   * The schema for {@linkcode Module}. This is the source of truth for how an Module document
+   * must be structured.
+   *
+   * Foundry uses this schema to validate the structure of the {@linkcode Module}. For example
+   * a {@link fields.StringField | `StringField`} will enforce that the value is a string. More
+   * complex fields like {@link fields.SetField | `SetField`} goes through various conversions
+   * starting as an array in the database, initialized as a set, and allows updates with any
+   * iterable.
+   */
+  interface Schema extends BasePackage.Schema {
+    /**
+     * The current package version
+     * @remarks Actually defined in BasePackage but defined here to avoid conflict with BaseWorld
+     */
+    version: fields.StringField<{ required: true; blank: false; initial: "0" }>;
+
+    /**
+     * Does this module provide a translation for the core software?
+     */
+    coreTranslation: fields.BooleanField;
+
+    /**
+     * A library module provides no user-facing functionality and is solely for use by other modules. Loaded before any system or module scripts.
+     */
+    library: fields.BooleanField;
+
+    /**
+     * Additional document sub-types provided by this module.
+     */
+    documentTypes: AdditionalTypesField;
+  }
+}
+
+export default Module;