@league-of-foundry-developers/foundry-vtt-types 13.346.0-beta.20250723121215 → 13.346.0-beta.20250724011756

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@league-of-foundry-developers/foundry-vtt-types",
-  "version": "13.346.0-beta.20250723121215",
+  "version": "13.346.0-beta.20250724011756",
   "description": "TypeScript type definitions for Foundry VTT",
   "type": "module",
   "types": "./src/index.d.mts",

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

@@ -62,7 +62,8 @@ declare namespace Module {
    */
   interface Schema extends BasePackage.Schema {
     /**
-     * The current package version
+     * The current package version. It is recommended to stick to dot-separated numbers like "5.0.3"
+     * and to not include a leading "v" to avoid string comparison. See {@linkcode foundry.utils.isNewerVersion}.
      * @remarks Actually defined in BasePackage but defined here to avoid conflict with BaseWorld
      */
     version: fields.StringField<{ required: true; blank: false; initial: "0" }>;

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

@@ -72,7 +72,8 @@ declare namespace System {
    */
   interface Schema extends BasePackage.Schema {
     /**
-     * The current package version
+     * The current package version. It is recommended to stick to dot-separated numbers like "5.0.3"
+     * and to not include a leading "v" to avoid string comparison. See {@linkcode foundry.utils.isNewerVersion}.
      * @remarks Actually defined in BasePackage but defined here to avoid conflict with BaseWorld
      */
     version: fields.StringField<{ required: true; blank: false; initial: "0" }>;

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

@@ -64,16 +64,22 @@ declare namespace BasePackage {
   }
 
   interface PackageMediaSchema extends DataSchema {
+    /** Usage type for the media asset. "setup" means it will be used on the setup screen. */
     type: fields.StringField<OptionalString>;
 
+    /** A web url link to the media element. */
     url: fields.StringField<OptionalString>;
 
+    /** A caption for the media element. */
     caption: fields.StringField<OptionalString>;
 
+    /** Should the media play on loop? */
     loop: fields.BooleanField<{ required: false; blank: false; initial: false }>;
 
+    /** A link to the thumbnail for the media element. */
     thumbnail: fields.StringField<OptionalString>;
 
+    /** An object of optional key/value flags. */
     flags: fields.ObjectField;
   }
 
@@ -228,14 +234,21 @@ declare namespace BasePackage {
 
   /** @internal */
   interface _PackageCompendiumFolderSchema extends DataSchema {
+    /** Name for the folder. Multiple packages with identical folder names will merge by name. */
     name: fields.StringField<{ required: true; blank: false }>;
+
+    /** Alphabetical or manual sorting. */
     sorting: fields.StringField<{
       required: false;
       blank: false;
       initial: undefined;
       choices: typeof BaseFolder.SORTING_MODES;
     }>;
+
+    /** A hex string for the pack's color. */
     color: fields.ColorField;
+
+    /** A list of the pack names to include in this folder. */
     packs: fields.SetField<fields.StringField<{ required: true; blank: false }>>;
   }
 
@@ -244,6 +257,7 @@ declare namespace BasePackage {
 
   type PackageCompendiumFolderSchema<Depth> = Depth extends number
     ? _PackageCompendiumFolderSchema & {
+        /** Nested folder data, up to three levels. */
         folders: fields.SetField<fields.SchemaField<PackageCompendiumFolderSchema<FolderRecursion[Depth]>>>;
       }
     : _PackageCompendiumFolderSchema;
@@ -300,34 +314,37 @@ declare namespace BasePackage {
      */
     changelog: fields.StringField<OptionalString>;
 
+    /**
+     * An object of optional key/value flags. Packages can use this namespace for their own purposes,
+     * preferably within a namespace matching their package ID.
+     */
     flags: fields.ObjectField;
 
+    /** An array of objects containing media info about the package. */
     media: fields.SetField<fields.SchemaField<PackageMediaSchema>>;
 
     // Moved to base-module and base-system to avoid conflict with base-world
 
-    /**
-     * The current package version
-     */
     // version: fields.StringField<{ required: true; blank: false; initial: "0" }>;
 
     /**
-     * The compatibility of this version with the core Foundry software
+     * The compatibility of this version with the core Foundry software. See https://foundryvtt.com/article/versioning/
+     * for more info on how the core software structures its releases.
      */
     compatibility: PackageCompatibility;
 
     /**
-     * An array of urls or relative file paths for JavaScript files which should be included
+     * An array of urls or relative file paths for JavaScript files to include
      */
     scripts: fields.SetField<fields.StringField<{ required: true; blank: false }>>;
 
     /**
-     * An array of urls or relative file paths for ESModule files which should be included
+     * An array of urls or relative file paths for ESModule files to include
      */
     esmodules: fields.SetField<fields.StringField<{ required: true; blank: false }>>;
 
     /**
-     * An array of urls or relative file paths for CSS stylesheet files which should be included
+     * An array of urls or relative file paths for CSS stylesheet files to include
      */
     styles: fields.SetField<fields.StringField<{ required: true; blank: false }>>;
 
@@ -341,6 +358,9 @@ declare namespace BasePackage {
      */
     packs: PackageCompendiumPacks<fields.SchemaField<PackageCompendiumSchema>>;
 
+    /**
+     * An array of pack folders that will be initialized once per world.
+     */
     packFolders: fields.SetField<fields.SchemaField<PackageCompendiumFolderSchema<1>>>;
 
     /**
@@ -368,11 +388,63 @@ declare namespace BasePackage {
      */
     protected: fields.BooleanField;
 
+    /**
+     * Whether this package is a free Exclusive pack.
+     */
     exclusive: fields.BooleanField;
 
+    /**
+     * Whether updates should leave the contents of the package's /storage folder.
+     */
     persistentStorage: fields.BooleanField;
   }
 
+  /**
+   * @remarks Package flags do not operate under the same rules as Document flags
+   * 1. They are constructed directly from the provided manifest.json files
+   * 2. There are no helper getFlag/setFlag functions
+   * 3. There is no enforced namespacing
+   * 4. There are *many* layers that accept flags, rather than just the top level
+   */
+  namespace Flags {
+    /**
+     * Flags used by the core software.
+     * @remarks Flags for the top level of the schema. Notably *not* namespaced as "core..."
+     */
+    interface Core {
+      /** Can you upload to this package's folder using the built-in FilePicker. */
+      canUpload?: boolean | undefined;
+
+      /** Configuration information for hot reload logic */
+      hotReload?: HotReloadConfig | undefined;
+
+      /**
+       * Mapping information for CompendiumArt.
+       * Each key is a unique system ID, e.g. "dnd5e" or "pf2e".
+       */
+      compendiumArtMappings?: Record<string, CompendiumArtFlag> | undefined;
+
+      /** A mapping of token subject paths to configured subject images. */
+      tokenRingSubjectMappings?: Record<string, string> | undefined;
+    }
+
+    interface HotReloadConfig {
+      /** A list of file extensions, e.g. `["css", "hbs", "json"]` */
+      extensions?: string[] | undefined;
+
+      /** File paths to watch, e.g. `["src/styles", "templates", "lang"]` */
+      paths?: string[] | undefined;
+    }
+
+    interface CompendiumArtFlag {
+      /** The path to the art mapping file. */
+      mapping: string;
+
+      /** An optional credit string for use by the game system to apply in an appropriate place. */
+      credit?: string | undefined;
+    }
+  }
+
   interface PackageManifestData {
     availability: foundry.CONST.PACKAGE_AVAILABILITY_CODES;
     locked: boolean;

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

@@ -13,14 +13,14 @@ declare class AdditionalTypesField<
 > extends ObjectField<
   Options,
   // Note(LukeAbby): `{}` is a valid initial so `| null | undefined` is added. Needs to respect overriden `initial` in the future.
-  AdditionalTypesField.ServerTypeDeclarations | null | undefined,
-  AdditionalTypesField.ServerTypeDeclarations,
-  AdditionalTypesField.ServerTypeDeclarations
+  AdditionalTypesField.DocumentTypesConfiguration | null | undefined,
+  AdditionalTypesField.DocumentTypesConfiguration,
+  AdditionalTypesField.DocumentTypesConfiguration
 > {
   static get _defaults(): AdditionalTypesField.DefaultOptions;
 
   protected _validateType(
-    value: AdditionalTypesField.ServerTypeDeclarations,
+    value: AdditionalTypesField.DocumentTypesConfiguration,
     options?: DataField.ValidateOptions<this>,
   ): boolean | void;
 }
@@ -36,5 +36,34 @@ declare namespace AdditionalTypesField {
     }
   >;
 
-  type ServerTypeDeclarations = Record<Document.SystemType, Record<string, Record<string, unknown>>>;
+  /**
+   * Document subtype registration information for systems and modules.
+   * 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>>;
+
+  /** @deprecated Internal type will be removed */
+  type ServerTypeDeclarations = DocumentTypesConfiguration;
+
+  /**
+   * Fields that need dedicated server-side handling. Paths are automatically relative to `system`.
+   */
+  interface ServerSanitationFields {
+    /**
+     * HTML fields that must be cleaned by the server, e.g. "description.value"
+     */
+    htmlFields?: string[] | undefined;
+
+    /**
+     * File path fields that must be cleaned by the server.
+     * Each key is a field path and the values are an array of keys in {@linkcode CONST.FILE_CATEGORIES}.
+     */
+    filePathFields?: Record<string, CONST.FILE_CATEGORIES> | undefined;
+
+    /**
+     * Fields that can only be updated by a GM user.
+     */
+    gmOnlyFields?: string[] | undefined;
+  }
 }