@league-of-foundry-developers/foundry-vtt-types 12.331.2-beta → 12.331.4-beta

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

@@ -1,20 +1,27 @@
-import type { DatabaseBackend } from "../abstract/module.d.mts";
 import type { DataModel } from "../abstract/data.d.mts";
-import type { fields } from "./module.d.mts";
-import type * as documents from "../documents/_module.d.mts";
-import type { AnyObject, EmptyObject, ValueOf } from "../../../types/utils.d.mts";
-
-// TODO: Implement all of the necessary options
-
-declare global {
-  type LightAnimationData = fields.SchemaField.InnerInitializedType<LightData.LightAnimationDataSchema>;
-}
+import type {
+  AnyMutableObject,
+  EmptyObject,
+  GetKey,
+  NullishCoalesce,
+  RemoveIndexSignatures,
+  ToMethod,
+  ValueOf,
+} from "fvtt-types/utils";
+import fields = foundry.data.fields;
+import documents = foundry.documents;
+
+type DataSchema = foundry.data.fields.DataSchema;
 
 declare namespace LightData {
-  export interface LightAnimationDataSchema extends DataSchema {
+  type Parent = TokenDocument.Implementation | AmbientLightDocument.Implementation;
+
+  interface LightAnimationDataSchema extends DataSchema {
     /**
      * The animation type which is applied
      * @defaultValue `null`
+     * @remarks While not enforced by the data model, this should be in `keyof CONFIG.Canvas.lightAnimations`
+     * (or `.darknessAnimations` as appropriate) or the animation will be ignored
      */
     type: fields.StringField<{ nullable: true; blank: false; initial: null }>;
 
@@ -53,16 +60,16 @@ declare namespace LightData {
     reverse: fields.BooleanField;
   }
 
-  export interface DarknessSchema extends DataSchema {
+  interface DarknessSchema extends DataSchema {
     /**
      * @defaultValue `0`
      */
-    min: fields.NumberField<{ initial: 0 }>;
+    min: fields.AlphaField<{ initial: 0 }>;
 
     /**
      * @defaultValue `1`
      */
-    max: fields.NumberField<{ initial: 1 }>;
+    max: fields.AlphaField<{ initial: 1 }>;
   }
 
   interface Schema extends DataSchema {
@@ -104,6 +111,7 @@ declare namespace LightData {
     /**
      * The coloration technique applied in the shader
      * @defaultValue `1`
+     * @remarks This should match the `id` of the desired property of {@link AdaptiveLightingShader.SHADER_TECHNIQUES | `AdaptiveLightingShader.SHADER_TECHNIQUES`}
      */
     coloration: fields.NumberField<{ required: true; integer: true; initial: 1 }>;
 
@@ -156,7 +164,7 @@ declare namespace LightData {
     darkness: fields.SchemaField<
       DarknessSchema,
       {
-        validate: (d: fields.SchemaField.InnerAssignmentType<DarknessSchema>) => boolean;
+        validate: (d: unknown) => boolean;
         validationError: "darkness.max may not be less than darkness.min";
       }
     >;
@@ -167,15 +175,13 @@ declare namespace LightData {
  * A reusable document structure for the internal data used to render the appearance of a light source.
  * This is re-used by both the AmbientLightData and TokenData classes.
  */
-declare class LightData extends DataModel<LightData.Schema> {
+declare class LightData extends DataModel<LightData.Schema, LightData.Parent> {
   static override defineSchema(): LightData.Schema;
 
-  /**
-   * @defaultValue `["LIGHT"]`
-   */
+  /** @defaultValue `["LIGHT"]` */
   static override LOCALIZATION_PREFIXES: string[];
 
-  static migrateData(source: AnyObject): AnyObject;
+  static override migrateData(source: AnyMutableObject): AnyMutableObject;
 }
 
 declare namespace ShapeData {
@@ -232,17 +238,21 @@ declare class ShapeData extends DataModel<ShapeData.Schema> {
 }
 
 declare namespace BaseShapeData {
-  interface Schema extends DataSchema {
+  interface Schema<ShapeType extends ShapeTypes = ShapeTypes> extends DataSchema {
     /**
      * The type of shape, a value in BaseShapeData.TYPES.
      * @defaultValue `this.TYPE`
+     * @remarks `this.TYPE` is `""` in `BaseShapeData`, and must be defined by subclasses
      */
     type: fields.StringField<{
       required: true;
       blank: false;
-      initial: string;
-      validate: (value: string) => boolean;
-      validationError: `must be equal to "${string}"`;
+      initial: ShapeType;
+      validate: (value: unknown) => value is ShapeType;
+      // TODO: The following `choices` does not exist in Foundry, it's a type hack to get this field to report as the only valid value it can have
+      // TODO: The validation function enough might be able to be made to sufficiently limit the value
+      choices: [ShapeType];
+      validationError: `must be equal to "${ShapeType}"`;
     }>;
 
     /**
@@ -252,18 +262,22 @@ declare namespace BaseShapeData {
     hole: fields.BooleanField;
   }
 
-  interface Types {
-    rectangle: RectangleShapeData;
-    circle: CircleShapeData;
-    ellipse: EllipseShapeData;
-    polygon: PolygonShapeData;
+  type ShapeTypes = keyof RemoveIndexSignatures<BaseShapeData.Types>;
+
+  interface Types extends foundry.data.fields.TypedSchemaField.Types {
+    rectangle: typeof RectangleShapeData;
+    circle: typeof CircleShapeData;
+    ellipse: typeof EllipseShapeData;
+    polygon: typeof PolygonShapeData;
   }
 }
 
 /**
  * A data model intended to be used as an inner EmbeddedDataField which defines a geometric shape.
  */
-declare abstract class BaseShapeData extends DataModel<BaseShapeData.Schema> {
+declare abstract class BaseShapeData<
+  ShapeSchema extends BaseShapeData.Schema = BaseShapeData.Schema,
+> extends DataModel<ShapeSchema> {
   /**
    * The possible shape types.
    */
@@ -280,7 +294,7 @@ declare abstract class BaseShapeData extends DataModel<BaseShapeData.Schema> {
 }
 
 declare namespace RectangleShapeData {
-  interface Schema extends BaseShapeData.Schema {
+  interface Schema extends BaseShapeData.Schema<"rectangle"> {
     /**
      * The top-left x-coordinate in pixels before rotation.
      * @defaultValue `undefined`
@@ -316,17 +330,14 @@ declare namespace RectangleShapeData {
 /**
  * The data model for a rectangular shape.
  */
-declare class RectangleShapeData extends BaseShapeData {
-  /**
-   * @defaultValue `"rectangle"`
-   */
-  static override TYPE: string;
+declare class RectangleShapeData extends BaseShapeData<RectangleShapeData.Schema> {
+  static override TYPE: "rectangle";
 
   static override defineSchema(): RectangleShapeData.Schema;
 }
 
 declare namespace CircleShapeData {
-  interface Schema extends BaseShapeData.Schema {
+  interface Schema extends BaseShapeData.Schema<"circle"> {
     /**
      * The x-coordinate of the center point in pixels.
      * @defaultValue `undefined`
@@ -350,17 +361,14 @@ declare namespace CircleShapeData {
 /**
  * The data model for a circle shape.
  */
-declare class CircleShapeData extends BaseShapeData {
-  /**
-   * @defaultValue `"circle"`
-   */
-  static override TYPE: string;
+declare class CircleShapeData extends BaseShapeData<CircleShapeData.Schema> {
+  static override TYPE: "circle";
 
   static override defineSchema(): CircleShapeData.Schema;
 }
 
 declare namespace EllipseShapeData {
-  interface Schema extends BaseShapeData.Schema {
+  interface Schema extends BaseShapeData.Schema<"ellipse"> {
     /**
      * The x-coordinate of the center point in pixels.
      * @defaultValue `undefined`
@@ -396,17 +404,14 @@ declare namespace EllipseShapeData {
 /**
  * The data model for an ellipse shape.
  */
-declare class EllipseShapeData extends BaseShapeData {
-  /**
-   * @defaultValue `"ellipse"`
-   */
-  static override TYPE: string;
+declare class EllipseShapeData extends BaseShapeData<EllipseShapeData.Schema> {
+  static override TYPE: "ellipse";
 
   static override defineSchema(): EllipseShapeData.Schema;
 }
 
 declare namespace PolygonShapeData {
-  interface Schema extends BaseShapeData.Schema {
+  interface Schema extends BaseShapeData.Schema<"polygon"> {
     /**
      * The points of the polygon ([x0, y0, x1, y1, ...]).
      * The polygon must not be self-intersecting.
@@ -422,97 +427,172 @@ declare namespace PolygonShapeData {
 /**
  * The data model for a polygon shape.
  */
-declare class PolygonShapeData extends BaseShapeData {
-  /**
-   * @defaultValue `"polygon"`
-   */
-  static override TYPE: string;
+declare class PolygonShapeData extends BaseShapeData<PolygonShapeData.Schema> {
+  static override TYPE: "polygon";
 
   static override defineSchema(): PolygonShapeData.Schema;
 }
 
 declare namespace TextureData {
+  /** The parameter defaults for `srcOptions` in the {@link TextureData} constructor */
   interface DefaultOptions {
     categories: ["IMAGE", "VIDEO"];
-    // initial: {};
+    initial: EmptyObject;
     wildcard: false;
     label: "";
   }
 
-  interface Schema<SrcOptions extends FilePathFieldOptions> extends DataSchema {
+  /**
+   * @internal
+   * The `initial` property of the `srcOptions` parameter of the {@link TextureData | `TextureData`} constructor
+   * is not the `initial` for any one field, but instead is an object that gets parcelled out by key to the
+   * fields of the schema
+   */
+  type _SrcOptionsInitial<T> = {
+    [K in keyof T]: fields.DataField.Options.InitialType<T[K]>;
+  };
+
+  /** @remarks The keys picked directly are passed on to the `src: FilePathField` field, but `initial` is an object of initial values for potentially every field in the schema */
+  interface SrcOptions extends Pick<fields.FilePathField.Options, "categories" | "wildcard" | "label"> {
+    initial: _SrcOptionsInitial<fields.SchemaField.AssignmentData<Schema<DefaultOptions>>>;
+  }
+
+  interface Schema<Options extends SrcOptions = DefaultOptions> extends DataSchema {
     /**
      * The URL of the texture source.
      * @defaultValue `initial.src ?? null`
-     */
-    src: fields.FilePathField<SrcOptions>;
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@link TextureData | `TextureData`} constructor
+     */
+    src: fields.FilePathField<{
+      categories: NullishCoalesce<Options["categories"], DefaultOptions["categories"]>;
+      initial: NullishCoalesce<GetKey<Options["initial"], "src", null>, null>;
+      wildcard: NullishCoalesce<Options["wildcard"], DefaultOptions["wildcard"]>;
+      label: NullishCoalesce<Options["label"], DefaultOptions["label"]>;
+    }>;
 
     /**
      * The X coordinate of the texture anchor.
      * @defaultValue `initial.anchorX ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@link TextureData | `TextureData`} constructor
      */
-    anchorX: fields.NumberField<{ nullable: false; initial: number }>;
+    anchorX: fields.NumberField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "anchorX", 0>, 0>;
+    }>;
 
     /**
      * The Y coordinate of the texture anchor.
      * @defaultValue `initial.anchorY ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@link TextureData | `TextureData`} constructor
      */
-    anchorY: fields.NumberField<{ nullable: false; initial: number }>;
+    anchorY: fields.NumberField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "anchorY", 0>, 0>;
+    }>;
 
     /**
      * The X offset of the texture with (0,0) in the top left.
      * @defaultValue `initial.offsetX ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@link TextureData | `TextureData`} constructor
      */
-    offsetX: fields.NumberField<{ nullable: false; integer: true; initial: number }>;
+    offsetX: fields.NumberField<{
+      nullable: false;
+      integer: true;
+      initial: NullishCoalesce<GetKey<Options["initial"], "offsetX", 0>, 0>;
+    }>;
 
     /**
      * The Y offset of the texture with (0,0) in the top left.
      * @defaultValue `initial.offsetY ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@link TextureData | `TextureData`} constructor
      */
-    offsetY: fields.NumberField<{ nullable: false; integer: true; initial: number }>;
+    offsetY: fields.NumberField<{
+      nullable: false;
+      integer: true;
+      initial: NullishCoalesce<GetKey<Options["initial"], "offsetY", 0>, 0>;
+    }>;
 
     /**
      * @defaultValue `initial.fit ?? "fill"`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@link TextureData | `TextureData`} constructor
      */
-    fit: fields.StringField<{ initial: string; choices: typeof CONST.TEXTURE_DATA_FIT_MODES }>;
+    fit: fields.StringField<
+      {
+        initial: NullishCoalesce<GetKey<Options["initial"], "fit", "fill">, "fill">;
+        choices: typeof CONST.TEXTURE_DATA_FIT_MODES;
+      },
+      ValueOf<typeof CONST.TEXTURE_DATA_FIT_MODES> | null | undefined,
+      ValueOf<typeof CONST.TEXTURE_DATA_FIT_MODES>,
+      ValueOf<typeof CONST.TEXTURE_DATA_FIT_MODES>
+    >;
 
     /**
      * The scale of the texture in the X dimension.
      * @defaultValue `initial.scaleX ?? 1`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@link TextureData | `TextureData`} constructor
      */
-    scaleX: fields.NumberField<{ nullable: false; initial: number }>;
+    scaleX: fields.NumberField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "scaleX", 1>, 1>;
+    }>;
 
     /**
      * The scale of the texture in the Y dimension.
      * @defaultValue `initial.scaleY ?? 1`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@link TextureData | `TextureData`} constructor
      */
-    scaleY: fields.NumberField<{ nullable: false; initial: number }>;
+    scaleY: fields.NumberField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "scaleY", 1>, 1>;
+    }>;
 
     /**
      * An angle of rotation by which this texture is rotated around its center.
      * @defaultValue `initial.rotation ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@link TextureData | `TextureData`} constructor
      */
-    rotation: fields.AngleField<{ initial: number }>;
+    rotation: fields.AngleField<{
+      initial: NullishCoalesce<GetKey<Options["initial"], "rotation", 0>, 0>;
+    }>;
 
     /**
      * The tint applied to the texture.
      * @defaultValue `initial.tint ?? "#ffffff"`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@link TextureData | `TextureData`} constructor
      */
-    tint: fields.ColorField<{ nullable: false; initial: string }>;
-
+    tint: fields.ColorField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "tint", "#ffffff">, "#ffffff">;
+    }>;
     /**
      * Only pixels with an alpha value at or above this value are consider solid
      * w.r.t. to occlusion testing and light/weather blocking.
      * @defaultValue `initial.alphaThreshold ?? 0`
+     * @remarks The `initial` in the above default value is the property from the `srcOptions`
+     * parameter of the {@link TextureData | `TextureData`} constructor
      */
-    alphaThreshold: fields.AlphaField<{ nullable: false; initial: number }>;
+    alphaThreshold: fields.AlphaField<{
+      nullable: false;
+      initial: NullishCoalesce<GetKey<Options["initial"], "alphaThreshold", 0>, 0>;
+    }>;
   }
 }
 
 /**
- * A {@link fields.SchemaField} subclass used to represent texture data.
+ * A {@link fields.SchemaField | `fields.SchemaField`} subclass used to represent texture data.
  */
 declare class TextureData<
-  SrcOptions extends FilePathFieldOptions = TextureData.DefaultOptions,
+  SrcOptions extends TextureData.SrcOptions = TextureData.DefaultOptions,
   SchemaOptions extends fields.SchemaField.Options<TextureData.Schema<SrcOptions>> = EmptyObject,
 > extends fields.SchemaField<TextureData.Schema<SrcOptions>, SchemaOptions> {
   /**
@@ -525,7 +605,10 @@ declare class TextureData<
 declare namespace PrototypeToken {
   type Parent = documents.BaseActor;
 
-  // Not otherwise used
+  /**
+   * @internal
+   * The fields foundry omits from the BaseToken schema. Not used, left as reference
+   */
   type ExcludedProperties =
     | "_id"
     | "actorId"
@@ -538,29 +621,51 @@ declare namespace PrototypeToken {
     | "locked"
     | "_regions";
 
-  interface Schema extends foundry.documents.BaseToken.SharedProtoSchema {
-    name: fields.StringField<{ required: true; blank: true; textSearch: boolean }>;
+  /**
+   * @remarks This has `PrototypeToken.#applyDefaultTokenSettings` run on it before actually being returned, so `initial`
+   * values may not be exactly accurate as typed
+   * @privateRemarks Since the {@link TokenDocument.Schema | `TokenDocument` schema} also extends `SharedProtoSchema`,
+   * overrides & extensions specific to {@link PrototypeToken | `PrototypeToken`} must go here
+   */
+  interface Schema extends TokenDocument.SharedProtoSchema {
+    /**
+     * The name used to describe the Token
+     * @defaultValue `""`
+     * @privateRemarks Only change from parent schema is `textSearch: false`
+     */
+    name: fields.StringField<{ required: true; blank: true; textSearch: false }>;
 
     /**
      * Does the prototype token use a random wildcard image?
      * @defaultValue `false`
+     * @privateRemarks New field, not in parent schema
      */
     randomImg: fields.BooleanField;
   }
 
-  type ConstructorData = fields.SchemaField.InnerAssignmentType<Schema>;
+  /**
+   * {@link PrototypeToken.CreateData | `PrototypeToken.CreateData`}
+   */
+  type ConstructorData = CreateData;
+
+  interface CreateData extends fields.SchemaField.CreateData<Schema> {}
 }
 
 /**
  * Extend the base TokenData to define a PrototypeToken which exists within a parent Actor.
  */
-declare class PrototypeToken extends DataModel<PrototypeToken.Schema, any> {
-  constructor(data?: PrototypeToken.ConstructorData, options?: DataModel.ConstructorOptions<PrototypeToken.Parent>);
+declare class PrototypeToken extends DataModel<PrototypeToken.Schema, PrototypeToken.Parent> {
+  // options: not null (destructured when passed to super)
+  constructor(
+    data?: PrototypeToken.ConstructorData | null,
+    options?: DataModel.DataValidationOptions<PrototypeToken.Parent>,
+  );
 
-  declare parent: PrototypeToken.Parent;
-
-  /** @defaultValue `{}` */
-  apps: Record<string, Application>;
+  /**
+   * @defaultValue `{}`
+   * @remarks Created via `defineProperty` in constructor
+   */
+  apps: Record<string, Application.Any | foundry.applications.api.ApplicationV2.Any>;
 
   static override defineSchema(): PrototypeToken.Schema;
 
@@ -575,9 +680,9 @@ declare class PrototypeToken extends DataModel<PrototypeToken.Schema, any> {
   get actor(): this["parent"];
 
   override toObject(source: true): this["_source"] & { actorId: string | undefined };
-  override toObject(source?: boolean): ReturnType<this["schema"]["toObject"]>;
+  override toObject(source?: boolean): ReturnType<this["schema"]["toObject"]> & { actorId: string | undefined };
 
-  static get database(): DatabaseBackend;
+  static get database(): CONFIG["DatabaseBackend"];
 
   /**
    * Apply configured default token settings to the schema.
@@ -586,44 +691,45 @@ declare class PrototypeToken extends DataModel<PrototypeToken.Schema, any> {
   static #applyDefaultTokenSettings(schema: DataSchema): void;
 
   /**
-   * @see foundry.abstract.Document#update
+   * @see {@link foundry.abstract.Document.update | `foundry.abstract.Document#update`}
    */
   update(data: unknown, options: unknown): unknown;
 
   /**
-   * @see foundry.abstract.Document#getFlag
+   * @see {@link foundry.abstract.Document.getFlag | `foundry.abstract.Document#getFlag`}
    */
   getFlag(args: unknown): unknown;
 
   /**
-   * @see foundry.abstract.Document#setFlag
+   * @see {@link foundry.abstract.Document.setFlag | `foundry.abstract.Document#setFlag`}
    */
   setFlag(args: unknown): unknown;
 
   /**
-   * @see foundry.abstract.Document#unsetFlag
+   * @see {@link foundry.abstract.Document.unsetFlag | `foundry.abstract.Document#unsetFlag`}
    */
   unsetFlag(args: unknown): Promise<unknown>;
 
   /**
-   * @see foundry.abstract.Document#testUserPermission
+   * @see {@link foundry.abstract.Document.testUserPermission | `foundry.abstract.Document#testUserPermission`}
    */
   testUserPermission(
-    user: documents.BaseUser,
+    user: User.Implementation,
     permission: unknown,
     { exact }: { exact: boolean },
   ): ReturnType<this["actor"]["testUserPermission"]>;
 
   /**
-   * @see foundry.abstract.Document#isOwner
+   * @see {@link foundry.abstract.Document.isOwner | `foundry.abstract.Document#isOwner`}
    */
   get isOwner(): boolean;
 
-  // Monkey patched in from `token.js`, put here due to issues with the merge process
   /**
-   * @see TokenDocument#getBarAttribute
+   * @see {@link TokenDocument.getBarAttribute | `TokenDocument#getBarAttribute`}
+   *
+   * @remarks This is monkey patched in from `token.js`, put here due to issues with the merge process
    */
-  getBarAttribute: TokenDocument["getBarAttribute"];
+  getBarAttribute: ToMethod<TokenDocument.Implementation["getBarAttribute"]>;
 }
 
 declare namespace TombstoneData {
@@ -640,7 +746,7 @@ declare namespace TombstoneData {
      */
     _tombstone: fields.BooleanField<{
       initial: true;
-      validate: (v: boolean) => boolean;
+      validate: (v: unknown) => boolean;
       validationError: "must be true";
     }>;
   }