@league-of-foundry-developers/foundry-vtt-types 13.346.0-beta.20250824190511 → 13.346.0-beta.20250825020008

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

@@ -3,7 +3,7 @@
 // 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";
+import type { performIntegerSort } from "./helpers.mjs";
 
 // eslint-disable-next-line import-x/export
 export * from "./_types.mjs";
@@ -15,11 +15,12 @@ export * from "./helpers.mjs";
  * @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: {
+  /**
+   * Given a source object to sort, a target to sort relative to, and an Array of siblings in the container.
+   * @deprecated "`foundry.utils.SortingHelpers.performIntegerSort` has been deprecated. Access this helper at {@linkcode foundry.utils.performIntegerSort} instead." (since v13, until v15)
+   * @ignore
+   */
   performIntegerSort: typeof performIntegerSort;
 };
 
-declare namespace SortingHelpers {
-  interface SortOptions<T, SortKey extends string = "sort"> extends OriginalSortOptions<T, SortKey> {}
-}
-
 export { SortingHelpers };

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

@@ -17,7 +17,17 @@ declare class _InternalDataModel<
 export default DataModel;
 
 /**
- * The abstract base class which defines the data schema contained within a Document.
+ * An abstract class which is a fundamental building block of numerous structures and concepts in Foundry Virtual
+ * Tabletop. Data models perform several essential roles:
+ *
+ * - A static schema definition that all instances of that model adhere to.
+ * - A workflow for data migration, cleaning, validation, and initialization such that provided input data is structured
+ *   according to the rules of the model's declared schema.
+ * - A workflow for transacting differential updates to the instance data and serializing its data into format suitable
+ *   for storage or transport.
+ *
+ * DataModel subclasses can be used for a wide variety of purposes ranging from simple game settings to high complexity
+ * objects like `Scene` documents. Data models are often nested; see the {@linkcode DataModel.parent} property for more.
  */
 declare abstract class DataModel<
   Schema extends DataSchema,
@@ -69,8 +79,40 @@ declare abstract class DataModel<
   readonly parent: Parent;
 
   /**
-   * Define the data schema for documents of this type.
+   * Define the data schema for models of this type.
    * The schema is populated the first time it is accessed and cached for future reuse.
+   *
+   * The schema, through its fields, provide the essential cleaning, validation, and initialization methods to turn the
+   * {@linkcode _source} values into direct properties of the data model. The schema is a static property of the model and
+   * is reused by all instances to perform validation.
+   *
+   * The schemas defined by the core software in classes like {@linkcode foundry.documents.BaseActor} are validated by the
+   * server, where user code does not run. However, almost all documents have a `flags` field to store data, and many
+   * have a `system` field that can be configured to be a {@linkcode foundry.abstract.TypeDataModel} instance. Those models
+   * are *not* constructed on the server and rely purely on client-side code, which means certain extra-sensitive fields
+   * must be also be registered through your package manifest. {@linkcode foundry.packages.AdditionalTypesField.ServerSanitizationFields | ServerSanitizationFields}
+   *
+   * @example
+   * ```js
+   * class SomeModel extends foundry.abstract.DataModel {
+   *   static defineSchema() {
+   *     return {
+   *       foo: new foundry.data.fields.StringField()
+   *     }
+   *   }
+   * }
+   *
+   * class AnotherModel extends SomeModel {
+   *   static defineSchema() {
+   *     // Inheritance and object oriented principles apply to schema definition
+   *     const schema = super.defineSchema()
+   *
+   *     schema.bar = new foundry.data.fields.NumberField()
+   *
+   *     return schema;
+   *   }
+   * }
+   * ```
    * @remarks The returned value MUST be kept up to sync with the `Schema` type parameter.
    */
   static defineSchema(): DataSchema;
@@ -100,7 +142,49 @@ declare abstract class DataModel<
   #validationFailures: { fields: DataModelValidationFailure | null; joint: DataModelValidationFailure | null };
 
   /**
-   * A set of localization prefix paths which are used by this DataModel.
+   * A set of localization prefix paths which are used by this DataModel. This provides an alternative to defining the
+   * `label` and `hint` property of each field by having foundry map the labels to a structure inside the path
+   * provided by the prefix.
+   *
+   * @example
+   * JavaScript class definition and localization call.
+   * ```js
+   * class MyDataModel extends foundry.abstract.DataModel {
+   *   static defineSchema() {
+   *     return {
+   *       foo: new foundry.data.fields.StringField(),
+   *       bar: new foundry.data.fields.NumberField()
+   *     };
+   *   }
+   *   static LOCALIZATION_PREFIXES = ["MYMODULE.MYDATAMODEL"];
+   * }
+   *
+   * Hooks.on("i18nInit", () => {
+   *   // Foundry will attempt to automatically localize models registered for a document subtype, so this step is only
+   *   // needed for other data model usage, e.g. for a Setting.
+   *   Localization.localizeDataModel(MyDataModel);
+   * });
+   * ```
+   *
+   * JSON localization file
+   * ```json
+   * {
+   *   "MYMODULE": {
+   *     "MYDATAMODEL": {
+   *       "FIELDS" : {
+   *         "foo": {
+   *           "label": "Foo",
+   *           "hint": "Instructions for foo"
+   *         },
+   *         "bar": {
+   *           "label": "Bar",
+   *           "hint": "Instructions for bar"
+   *         }
+   *       }
+   *     }
+   *   }
+   * }
+   * ```
    */
   static LOCALIZATION_PREFIXES: string[];
 

package/src/foundry/common/abstract/embedded-collection.d.mts

@@ -107,7 +107,7 @@ declare class EmbeddedCollection<
   ): void;
 
   /**
-   * Get an element from the EmbeddedCollection by its ID.
+   * Get a document from the EmbeddedCollection by its ID.
    * @param id      - The ID of the Embedded Document to retrieve.
    * @param options - Additional options to configure retrieval.
    */
@@ -129,21 +129,21 @@ declare class EmbeddedCollection<
   ): ContainedDocument | undefined;
 
   /**
-   * Get an element from the EmbeddedCollection by its ID.
+   * Get a document from the EmbeddedCollection by its ID.
    * @param id      - The ID of the Embedded Document to retrieve.
    * @param options - Additional options to configure retrieval.
    */
   get(id: string, options: { strict: true; invalid?: false }): ContainedDocument;
 
   /**
-   * Get an element from the EmbeddedCollection by its ID.
+   * Get a document from the EmbeddedCollection by its ID.
    * @param id      - The ID of the Embedded Document to retrieve.
    * @param options - Additional options to configure retrieval.
    */
   get(id: string, options: { strict?: boolean; invalid: true }): unknown;
 
   /**
-   * Add an item to the collection
+   * Add a document to the collection
    * @param key     - The embedded Document ID
    * @param value   - The embedded Document instance
    * @param options - Additional options to the set operation
@@ -168,6 +168,7 @@ declare class EmbeddedCollection<
   protected _set(key: string, value: ContainedDocument): void;
 
   /**
+   * Remove a document from the collection.
    * @param key     - The embedded Document ID.
    * @param options - Additional options to the delete operation.
    */

package/src/foundry/common/abstract/type-data.d.mts

@@ -210,9 +210,8 @@ declare abstract class AnyTypeDataModel extends TypeDataModel<any, any, any, any
  * Systems or Modules that provide DataModel implementations for sub-types of Documents (such as Actors or Items)
  * should subclass this class instead of the base DataModel class.
  *
- *
- * @example Registering a custom sub-type for a Module.
- *
+ * @example
+ * Registering a custom sub-type for a Module.
  * **module.json**
  * ```json
  * {
@@ -260,6 +259,23 @@ declare abstract class AnyTypeDataModel extends TypeDataModel<any, any, any, any
  *   }
  * }
  * ```
+ *
+ * **en.json** To provide the localization for methods like `ClientDocument.createDialog`
+ *
+ * ```json
+ * {
+ *   "TYPES": {
+ *     "Actor": {
+ *       "sidekick": "Sidekick",
+ *       "villain": "Villain"
+ *     },
+ *     "JournalEntryPage": {
+ *       "dossier": "Dossier",
+ *       "quest": "Quest"
+ *     }
+ *   }
+ * }
+ * ```
  */
 declare abstract class TypeDataModel<
   Schema extends DataSchema,
@@ -277,23 +293,49 @@ declare abstract class TypeDataModel<
 
   modelProvider: foundry.packages.System | foundry.packages.Module | null;
 
-  /**
-   * A set of localization prefix paths which are used by this data model.
-   */
-  static LOCALIZATION_PREFIXES: string[];
+  static override LOCALIZATION_PREFIXES: string[];
 
   /**
-   * Prepare data related to this DataModel itself, before any derived data is computed.
+   * Prepare data related to this DataModel itself, before any derived data (including Active Effects)
+   * is computed. This is especially useful for initializing numbers, arrays, and sets you expect to be
+   * modified by active effects.
+   *
+   * Called before {@linkcode foundry.documents.abstract.ClientDocumentMixin.AnyMixed.prepareBaseData | ClientDocument#prepareBaseData} in
+   * {@linkcode foundry.documents.abstract.ClientDocumentMixin.AnyMixed.prepareData | ClientDocument#prepareData}.
    *
-   * Called before {@link ClientDocument.prepareBaseData | `ClientDocument#prepareBaseData`} in {@link ClientDocument.prepareData | `ClientDocument#prepareData`}.
+   * @example
+   * ```js
+   * prepareBaseData() {
+   *   // Ensures an active effect of `system.encumbrance.max | ADD | 10` doesn't produce `NaN`
+   *   this.encumbrance = {
+   *     max: 0
+   *   }
+   *   // If you need to access the owning Document, `this.parent` provides a reference for properties like the name
+   *   // or embedded collections, e.g. `this.parent.name` or `this.parent.items`
+   * }
+   * ```
    */
   prepareBaseData(this: TypeDataModel.PrepareBaseDataThis<this>): void;
 
   /**
-   * Apply transformations of derivations to the values of the source data object.
+   * Apply transformations or derivations to the values of the source data object.
    * Compute data fields whose values are not stored to the database.
    *
-   * Called before {@link ClientDocument.prepareDerivedData | `ClientDocument#prepareDerivedData`} in {@link ClientDocument.prepareData | `ClientDocument#prepareData`}.
+   * Called before {@linkcode foundry.abstract.ClientDocumentMixin.AnyMixed.prepareDerivedData | ClientDocument#prepareDerivedData} in
+   * {@linkcode foundry.abstract.ClientDocumentMixin.AnyMixed.prepareData | ClientDocument#prepareData}.
+   *
+   * @example
+   * ```js
+   * prepareDerivedData() {
+   *   this.hp.bloodied = Math.floor(this.hp.max / 2);
+   *
+   *   // this.parent accesses the Document, allowing access to embedded collections
+   *   this.encumbrance.value = this.parent.items.reduce((total, item) => {
+   *     total += item.system.weight;
+   *     return total;
+   *   }, 0)
+   * }
+   * ```
    */
   prepareDerivedData(this: TypeDataModel.PrepareDerivedDataThis<this>): void;
 

package/src/foundry/common/data/fields.d.mts

@@ -3795,6 +3795,13 @@ declare namespace ColorField {
 
 /**
  * A special {@linkcode StringField} which records a file path or inline base64 data.
+ *
+ * When using the `FilePathField` in a data model that is persisted to the database, for example a Document sub-type,
+ * it is essential to declare this field in the package manifest so that it receives proper server-side validation of
+ * its contents.
+ *
+ * See {@linkcode foundry.packages.AdditionalTypesField.ServerSanitizationFields | ServerSanitizationFields} for information about this structure.
+ *
  * @template Options         - the options of the FilePathField instance
  * @template AssignmentType  - the type of the allowed assignment values of the FilePathField
  * @template InitializedType - the type of the initialized values of the FilePathField
@@ -4438,9 +4445,16 @@ declare class AnyField extends DataField<DataField.Options.Any, unknown, unknown
 }
 
 /**
- * A subclass of {@linkcode StringField} which contains a sanitized HTML string.
+ * A subclass of {@linkcode foundry.data.fields.StringField | StringField} which contains a sanitized HTML string.
  * This class does not override any StringField behaviors, but is used by the server-side to identify fields which
  * require sanitization of user input.
+ *
+ * When using the `HTMLField` in a data model that is persisted to the database, for example a Document sub-type,
+ * it is essential to declare this field in the package manifest so that it receives proper server-side validation
+ * of its contents.
+ *
+ * See {@linkcode foundry.packages.AdditionalTypesField.ServerSanitizationFields | ServerSanitizationFields} for information about this structure.
+ *
  * @template Options         - the options of the HTMLField instance
  * @template AssignmentType  - the type of the allowed assignment values of the HTMLField
  * @template InitializedType - the type of the initialized values of the HTMLField

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

@@ -5,11 +5,11 @@
 
 import type { SchemaField } from "../data/fields.d.mts";
 
-export { default as BasePackage } from "./base-package.mjs";
+export { default as BasePackage, PackageCompatibility, RelatedPackage } from "./base-package.mjs";
 export { default as BaseWorld } from "./base-world.mjs";
 export { default as BaseSystem } from "./base-system.mjs";
 export { default as BaseModule } from "./base-module.mjs";
-export { PackageCompatibility, RelatedPackage } from "./base-package.mjs";
+export { default as AdditionalTypesField } from "./sub-types.mjs";
 
 declare global {
   type PackageAuthorData = SchemaField.CreateData<foundry.packages.BasePackage.PackageAuthorSchema>;

package/src/foundry/common/packages/base-package.d.mts

@@ -84,8 +84,8 @@ declare namespace BasePackage {
   }
 
   type OwnershipRecord = Record<
-    keyof typeof foundry.CONST.USER_ROLES,
-    keyof typeof foundry.CONST.DOCUMENT_OWNERSHIP_LEVELS | undefined
+    keyof typeof CONST.USER_ROLES,
+    keyof typeof CONST.DOCUMENT_OWNERSHIP_LEVELS | undefined
   >;
 
   interface PackageCompendiumSchema extends DataSchema {
@@ -104,6 +104,13 @@ declare namespace BasePackage {
      */
     label: fields.StringField<{ required: true; blank: false }>;
 
+    /**
+     * A file path to a banner image that will be used in the Compendium sidebar. This should
+     * be hosted within your package, e.g. `modules/my-module/assets/banners/bestiary.webp`.
+     * The dimensions are 290 x 70; you can either have each be an individual landscape or
+     * slice them up to form a composite with your other compendiums, but keep in mind that
+     * users can reorder compendium packs as well as filter them to break up the composite.
+     */
     banner: fields.StringField<OptionalString>;
 
     /**
@@ -122,7 +129,9 @@ declare namespace BasePackage {
     }>;
 
     /**
-     * Denote that this compendium pack requires a specific game system to function properly
+     * Denote that this compendium pack requires a specific game system to function properly.
+     * Required for "Actor" and "Item" packs, but even others should keep in mind that system
+     * specific features and subtypes (e.g. JournalEntryPage) may present limitations.
      */
     system: fields.StringField<OptionalString>;
 

package/src/foundry/common/packages/sub-types.d.mts

@@ -41,17 +41,20 @@ declare namespace AdditionalTypesField {
    * The first layer of keys are document types, e.g. "Actor" or "Item".
    * The second layer of keys are document subtypes, e.g. "character" or "feature".
    */
-  type DocumentTypesConfiguration = Record<Document.SystemType, Record<string, ServerSanitationFields>>;
+  type DocumentTypesConfiguration = Record<Document.SystemType, Record<string, ServerSanitizationFields>>;
 
   /** @deprecated Internal type will be removed */
   type ServerTypeDeclarations = DocumentTypesConfiguration;
 
+  /** @deprecated Use {@linkcode ServerSanitizationFields} instead. This warning will be removed in v14. */
+  type ServerSanitationFields = ServerSanitizationFields;
+
   /**
    * Fields that need dedicated server-side handling. Paths are automatically relative to `system`.
    */
-  interface ServerSanitationFields {
+  interface ServerSanitizationFields {
     /**
-     * HTML fields that must be cleaned by the server, e.g. "description.value"
+     * HTML fields that must be cleaned by the server, e.g. `"description.value"`
      */
     htmlFields?: string[] | undefined;