@league-of-foundry-developers/foundry-vtt-types 13.346.0-beta.20250823115730 → 13.346.0-beta.20250825015921

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

@@ -465,7 +465,7 @@ declare abstract class DataField<
     delta: InitializedType,
     model: DataModel.Any,
     change: ActiveEffect.ChangeData,
-  ): InitializedType;
+  ): InitializedType | undefined;
 
   /**
    * Apply an UPGRADE change to this field.
@@ -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;