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

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

@@ -0,0 +1,151 @@
+import type BasePackage from "#common/packages/base-package.d.mts";
+import type AdditionalTypesField from "#common/packages/sub-types.d.mts";
+import type DataModel from "#common/abstract/data.mjs";
+import type ClientPackageMixin from "./client-package.d.mts";
+import type { SystemNameConfig } from "#configuration";
+import type { GetKey } from "fvtt-types/utils";
+
+import fields = foundry.data.fields;
+import Game = foundry.Game;
+
+declare class System extends ClientPackageMixin(foundry.packages.BaseSystem) {
+  constructor(data: ClientPackageMixin.SystemCreateData, options: unknown);
+
+  // options: not null (parameter default only, destructured in super)
+  protected override _configure(options?: DataModel.ConfigureOptions): void;
+
+  id: GetKey<SystemNameConfig, "name", string>;
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks `"System#template is deprecated in favor of System#documentTypes"`
+   */
+  get template(): Game["model"];
+}
+
+declare namespace System {
+  /**
+   * 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 System.create}
+   * and {@link System | `new System(...)`}.
+   *
+   * 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 System.name | `System#name`}.
+   *
+   * This is data transformed from {@linkcode System.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 System.update | `System#update`}.
+   * It is a distinct type from {@link System.CreateData | `DeepPartial<System.CreateData>`} because
+   * it has different rules for `null` and `undefined`.
+   */
+  interface UpdateData extends fields.SchemaField.UpdateData<Schema> {}
+
+  /**
+   * The schema for {@linkcode System}. This is the source of truth for how an System document
+   * must be structured.
+   *
+   * Foundry uses this schema to validate the structure of the {@linkcode System}. 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" }>;
+
+    /**
+     * Additional document subtypes provided by this system.
+     */
+    documentTypes: AdditionalTypesField;
+
+    /**
+     * A web URL or local file path which provides a default background banner for worlds which are created using this system
+     */
+    background: fields.StringField<{ required: false; blank: false }>;
+
+    /**
+     * A default initiative formula used for this system
+     */
+    initiative: fields.StringField;
+
+    /**
+     * The default grid settings to use for Scenes in this system
+     */
+    grid: fields.SchemaField<{
+      /** A default grid type to use for Scenes in this system */
+      type: fields.NumberField<{
+        required: true;
+        choices: typeof foundry.CONST.GRID_TYPES;
+        initial: typeof foundry.CONST.GRID_TYPES.SQUARE;
+      }>;
+
+      /** A default distance measurement to use for Scenes in this system */
+      distance: fields.NumberField<{
+        required: true;
+        nullable: false;
+        positive: true;
+        initial: 1;
+      }>;
+
+      /** A default unit of measure to use for distance measurement in this system */
+      units: fields.StringField<{
+        required: true;
+      }>;
+
+      /** The default rule used by this system for diagonal measurement on square grids */
+      diagonals: fields.NumberField<{
+        required: true;
+        choices: typeof foundry.CONST.GRID_DIAGONALS;
+        initial: typeof foundry.CONST.GRID_DIAGONALS.EQUIDISTANT;
+      }>;
+    }>;
+
+    /**
+     * An Actor data attribute path to use for Token primary resource bars
+     */
+    primaryTokenAttribute: fields.StringField;
+
+    /**
+     * An Actor data attribute path to use for Token secondary resource bars
+     */
+    secondaryTokenAttribute: fields.StringField;
+
+    /**
+     * A default distance measurement to use for Scenes in this system
+     * @deprecated since v12
+     */
+    gridDistance: fields.NumberField;
+
+    /**
+     * A default unit of measure to use for distance measurement in this system
+     * @deprecated since v12
+     */
+    gridUnits: fields.NumberField;
+  }
+}
+
+export default System;

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

@@ -0,0 +1,155 @@
+import type { CONST } from "#client/client.d.mts";
+import type BasePackage from "#common/packages/base-package.d.mts";
+import type ClientPackageMixin from "./client-package.d.mts";
+import type Module from "./module.d.mts";
+import type System from "./system.d.mts";
+
+import fields = foundry.data.fields;
+
+declare class World extends ClientPackageMixin(foundry.packages.BaseWorld) {
+  static override getVersionBadge(
+    availability: CONST.PACKAGE_AVAILABILITY_CODES,
+    data: Partial<PackageManifestData>,
+    options: World.GetVersionBadgeOptions,
+  ): ClientPackageMixin.PackageCompatibilityBadge | null;
+
+  /**
+   * Provide data for a system badge displayed for the world which reflects the system ID and its availability
+   * @param system - A specific system to use, otherwise use the installed system.
+   */
+  getSystemBadge(system?: System): ClientPackageMixin.PackageCompatibilityBadge | null;
+
+  static override _formatBadDependenciesTooltip(
+    availability: CONST.PACKAGE_AVAILABILITY_CODES,
+    data: Partial<PackageManifestData>,
+    options: World.FormatBadDependenciesTooltip,
+  ): string;
+}
+
+declare namespace World {
+  /**
+   * 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 World.create}
+   * and {@link World | `new World(...)`}.
+   *
+   * 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 World.name | `World#name`}.
+   *
+   * This is data transformed from {@linkcode World.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 World.update | `World#update`}.
+   * It is a distinct type from {@link World.CreateData | `DeepPartial<World.CreateData>`} because
+   * it has different rules for `null` and `undefined`.
+   */
+  interface UpdateData extends fields.SchemaField.UpdateData<Schema> {}
+
+  /**
+   * The schema for {@linkcode World}. This is the source of truth for how an World document
+   * must be structured.
+   *
+   * Foundry uses this schema to validate the structure of the {@linkcode World}. 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 game system name which this world relies upon
+     */
+    system: fields.StringField<{ required: true; blank: false }>;
+
+    /**
+     * A web URL or local file path which provides a background banner image
+     */
+    background: fields.StringField<{ required: false; blank: false }>;
+
+    /**
+     * The theme to use for this world's join page.
+     */
+    joinTheme: fields.StringField<{
+      required: false;
+      initial: undefined;
+      nullable: false;
+      blank: false;
+      choices: typeof foundry.CONST.WORLD_JOIN_THEMES;
+    }>;
+
+    /**
+     * The version of the core software for which this world has been migrated
+     */
+    coreVersion: fields.StringField<{ required: true; blank: false }>;
+
+    /**
+     * The version of the game system for which this world has been migrated
+     */
+    systemVersion: fields.StringField<{ required: true; blank: false; initial: "0" }>;
+
+    lastPlayed: fields.StringField;
+
+    playtime: fields.NumberField<{ integer: true; min: 0; initial: 0 }>;
+
+    /**
+     * An ISO datetime string when the next game session is scheduled to occur
+     */
+    nextSession: fields.StringField<{ blank: false; nullable: true; initial: null }>;
+
+    /**
+     * Should user access keys be reset as part of the next launch?
+     */
+    resetKeys: fields.BooleanField<{ required: false; initial: undefined }>;
+
+    /**
+     * Should the world launch in safe mode?
+     */
+    safeMode: fields.BooleanField<{ required: false; initial: undefined }>;
+
+    version: fields.StringField<{ required: true; blank: false; nullable: true; initial: null }>;
+  }
+
+  interface GetVersionBadgeOptions {
+    /**
+     * 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 FormatBadDependenciesTooltip {
+    /**
+     * 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;
+  }
+}
+
+export default World;

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

@@ -0,0 +1,25 @@
+// 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 type { SortOptions as OriginalSortOptions, performIntegerSort } from "./helpers.mjs";
+
+// eslint-disable-next-line import-x/export
+export * from "./_types.mjs";
+export * from "#common/utils/_module.mjs";
+export * from "./helpers.mjs";
+
+/**
+ * @deprecated since v13
+ * @remarks With the move to ESM, foundry no longer appears to need/want classes that only exist to host static functions in a namespace
+ */
+declare const SortingHelpers: {
+  performIntegerSort: typeof performIntegerSort;
+};
+
+declare namespace SortingHelpers {
+  interface SortOptions<T, SortKey extends string = "sort"> extends OriginalSortOptions<T, SortKey> {}
+}
+
+export { SortingHelpers };

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

@@ -0,0 +1,3 @@
+// Only exists to re-export these types
+// eslint-disable-next-line import-x/export
+export * from "#common/utils/_types.mjs";

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

@@ -0,0 +1,213 @@
+import type { AnyObject, InexactPartial, MustBeValidUuid } from "#utils";
+import type Document from "#common/abstract/document.d.mts";
+
+/**
+ * Clean a provided HTML fragment, closing unbalanced tags and stripping some undesirable properties
+ * @param raw - A raw HTML string
+ * @returns The cleaned HTML content
+ */
+export function cleanHTML(raw: string): string;
+
+/**
+ * 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
+ */
+export 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
+ */
+export function readTextFromFile(file: File): Promise<string>;
+
+/** @internal */
+type _FromUuidOptions = InexactPartial<{
+  /** A Document to resolve relative UUIDs against. */
+  relative: Document.Any;
+
+  /**
+   * Allow retrieving an invalid Document.
+   * @defaultValue `false`
+   */
+  invalid: boolean;
+}>;
+
+export interface FromUuidOptions extends _FromUuidOptions {}
+
+/**
+ * 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.
+ */
+export function fromUuid<ConcreteDocument extends Document.Any = __UnsetDocument, const Uuid extends string = string>(
+  uuid: FromUuidValidate<ConcreteDocument, Uuid> | null | undefined,
+  options?: FromUuidOptions,
+): Promise<(__UnsetDocument extends ConcreteDocument ? FromUuid<Uuid> : ConcreteDocument) | null>;
+
+/** @internal */
+type _FromUuidSyncOptions = InexactPartial<{
+  /**
+   * Throw an error if the UUID cannot be resolved synchronously.
+   * @defaultValue `true`
+   */
+  strict: boolean;
+}>;
+
+export interface FromUuidSyncOptions extends _FromUuidOptions, _FromUuidSyncOptions {}
+
+/**
+ * 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 options - Options to configure how a UUID is resolved.
+ * @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.
+ */
+export function fromUuidSync<
+  ConcreteDocument extends Document.Any = __UnsetDocument,
+  const Uuid extends string = string,
+>(
+  uuid: FromUuidValidate<ConcreteDocument, Uuid> | null | undefined,
+  options?: FromUuidSyncOptions,
+): (__UnsetDocument extends ConcreteDocument ? FromUuid<Uuid> : ConcreteDocument) | AnyObject | null;
+
+declare const __Unset: unique symbol;
+
+type __UnsetDocument = Document.Any & {
+  [__Unset]: true;
+};
+
+declare class InvalidUuid extends foundry.abstract.Document<any, any, any> {}
+
+type FromUuid<Uuid extends string> = Uuid extends `${string}.${string}.${infer Rest}`
+  ? FromUuid<Rest>
+  : Uuid extends `${infer DocumentType extends Document.Type}.${string}`
+    ? Document.ImplementationFor<DocumentType>
+    : InvalidUuid;
+
+// TODO(LukeAbby): The usage of `Document.Type` when it's unset will not be necessary once `Document.Any` is more type safe.
+type FromUuidValidate<
+  ConcreteDocument extends Document.Any,
+  Uuid extends string,
+> = __UnsetDocument extends ConcreteDocument
+  ? MustBeValidUuid<Uuid, Document.Type>
+  : string extends Uuid
+    ? string
+    : MustBeValidUuid<Uuid, ConcreteDocument["documentName"]>;
+
+/**
+ * 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
+ * @privateRemarks Foundry types this as `| undefined` but they can't enforce passing a valid Document type
+ */
+export function getDocumentClass<Name extends Document.Type>(documentName: Name): Document.ImplementationClassFor<Name>;
+
+/**
+ * Return a reference to the PlaceableObject class implementation which is configured for use.
+ * @param documentName - The canonical Document name, for example "Actor"
+ * @returns The configured PlaceableObject class implementation
+ * @privateRemarks Consider if the generic should be broader; this returns undefined, rather than errors, if the Name isn't a placeable type
+ */
+export function getPlaceableObjectClass<Name extends Document.PlaceableType>(
+  documentName: Name,
+): Document.ObjectClassFor<Name> | undefined;
+
+export interface SortOptions<T, SortKey extends string = "sort"> {
+  /**
+   * The target object relative which to sort
+   * @defaultValue `null`
+   */
+  target?: T | null | undefined;
+
+  /**
+   * The sorted Array of siblings which share the same sorted container
+   * @defaultValue `[]`
+   */
+  siblings?: T[] | undefined;
+
+  /**
+   * The name of the data property within the source object which defines the sort key
+   * @defaultValue `"sort"`
+   */
+  sortKey?: SortKey | undefined;
+
+  /**
+   * 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 | undefined;
+}
+
+/**
+ * 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
+ * @template T   - the type of the source and target object
+ *
+ * @returns An Array of updates for the caller of the helper function to perform
+ */
+export function performIntegerSort<T, SortKey extends string = "sort">(
+  source: T,
+  options?: SortOptions<T, SortKey>,
+): Array<{
+  target: T;
+  update: {
+    [Key in SortKey]: number;
+  };
+}>;
+
+/**
+ * Express a timestamp as a relative string
+ * @param timeStamp - A timestamp string or Date object to be formatted as a relative time
+ * @returns A string expression for the relative time
+ */
+export function timeSince(timeStamp: Date | string): string;
+
+/**
+ * Parse an HTML string, returning a processed HTMLElement or HTMLCollection.
+ * A single HTMLElement is returned if the provided string contains only a single top-level element.
+ * An HTMLCollection is returned if the provided string contains multiple top-level elements.
+ */
+export function parseHTML(htmlString: string): HTMLCollection | HTMLElement;
+
+/**
+ * Return a URL with a cache-busting query parameter appended.
+ * @param src - The source URL being attempted
+ * @returns The new URL, or false on a failure.
+ */
+export function getCacheBustURL(src: string): string | false;
+
+/** @internal */
+type _FetchResourceOptions = InexactPartial<{
+  /**
+   * Append a cache-busting query parameter to the request.
+   * @defaultValue `false`
+   */
+  bustCache: boolean;
+}>;
+
+interface FetchResourceOptions extends _FetchResourceOptions {}
+
+/**
+ * Use the Fetch API to retrieve a resource and return a Blob instance for it.
+ * @param src     - The resource URL
+ * @param options - Options to configure the loading behaviour.
+ * @returns A Blob containing the loaded data
+ */
+export function fetchResource(src: string, options?: FetchResourceOptions): Promise<Blob>;

package/src/foundry/common/_types.d.mts

@@ -1,6 +1,15 @@
-import type { AnyConcreteConstructor, AnyConstructor, AnyFunction } from "fvtt-types/utils";
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import type { AnyConcreteConstructor, AnyConstructor, AnyFunction } from "#utils";
+import type { Canvas } from "#client/canvas/_module.d.mts";
 import type { Document } from "./abstract/_module.d.mts";
 
+import ClientSettings = foundry.helpers.ClientSettings;
+import ClientKeybindings = foundry.helpers.interaction.ClientKeybindings;
+import SocketInterface = foundry.helpers.SocketInterface;
+
+export {};
+
 // After seeing that none of these types add anything or are even exported a
 // very reasonable question may be: Why on earth does this file exist?
 //
@@ -39,7 +48,7 @@ type DeepReadonly<T> = Readonly<{
 /**
  * A class constructor.
  * Used for functions with generic class constructor parameters.
- * @privateRemarks We have better tools like {@link AnyConcreteConstructor} and {@link AnyConstructor}
+ * @privateRemarks We have better tools like {@linkcode AnyConcreteConstructor} and {@linkcode AnyConstructor}
  */
 type Constructor = new (...args: any[]) => any;
 
@@ -47,6 +56,8 @@ type Point = Canvas.Point;
 
 type PointArray = Canvas.PointTuple;
 
+type ElevatedPoint = Canvas.ElevatedPoint;
+
 type Rectangle = Canvas.Rectangle;
 
 type BuiltinTypes = typeof Number | typeof String | typeof Boolean;
@@ -57,15 +68,15 @@ type SettingConfig = ClientSettings.SettingConfig;
 
 type SettingSubmenuConfig = ClientSettings.SettingSubmenuConfig;
 
-type KeyBindingActionConfig = ClientKeybindings.KeybindingActionConfig;
+type KeyBindingActionConfig = ClientKeybindings.StoredKeybindingActionConfig;
 
-type KeybindingActionBinding = ClientKeybindings.KeybindingActionBinding;
+type KeybindingActionBinding = ClientKeybindings.StoredKeybindingActionBinding;
 
 type KeybindingAction = ClientKeybindings.KeybindingAction;
 
-type KeyboardEventContext = KeyboardManager.KeyboardEventContext;
+type KeyboardEventContext = foundry.helpers.interaction.KeyboardManager.KeyboardEventContext;
 
-type ConnectedGamepad = GamepadManager.ConnectedGamepad;
+type ConnectedGamepad = foundry.helpers.interaction.GamepadManager.ConnectedGamepad;
 
 type RequestData = SocketInterface.RequestData;
 

package/src/foundry/common/abstract/_module.d.mts

@@ -3,6 +3,7 @@
 // While `.mts` could work, to avoid `import-x/no-unresolved` from erroring `.mjs` is used.
 /* eslint-disable import-x/extensions */
 
+export * as types from "./_types.mjs";
 export { default as DataModel } from "./data.mjs";
 export { default as TypeDataModel } from "./type-data.mjs";
 export { default as Document } from "./document.mjs";