@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.340.1

package/src/foundry/client-esm/canvas/tokens/ring-config.d.mts

@@ -1,5 +1,5 @@
+import type { InitializedOn } from "fvtt-types/utils";
 import type DynamicRingData from "./ring-data.d.mts";
-import type TokenRing from "./ring.d.mts";
 
 /**
  * Token Ring configuration Singleton Class.
@@ -76,14 +76,17 @@ import type TokenRing from "./ring.d.mts";
  * ```
  */
 declare class TokenRingConfig {
-  #TokenRingConfig: true;
-
   constructor();
 
   /**
    * Core token rings used in Foundry VTT.
    * Each key is a string identifier for a ring, and the value is an object containing the ring's data.
    * This object is frozen to prevent any modifications.
+   * @remarks The outer object is frozen, but the individual rings' data isn't, and that object gets passed into a {@link DynamicRingData | `DynamicRingData`} constructor, leading to, for example,
+   * ```js
+   * CONFIG.Token.ring.getConfig("coreSteel")._source === TokenRingConfig.CORE_TOKEN_RINGS.coreSteel
+   * ```
+   * after {@link TokenRingConfig.initialize | `initialize`} has been called, which happens between the `setup` and `ready` hooks
    */
   static CORE_TOKEN_RINGS: TokenRingConfig.CoreTokenRings;
 
@@ -92,13 +95,21 @@ declare class TokenRingConfig {
    */
   static CORE_TOKEN_RINGS_FIT_MODES: TokenRingConfig.CoreTokenRingsFitModes;
 
-  /** Register the token ring config and initialize it */
+  /**
+   * Register the token ring config and initialize it
+   * @remarks Calls the {@link Hooks.StaticCallbacks.initializeDynamicTokenRingConfig | `initializeDynamicTokenRingConfig`} hook via {@link Hooks.callAll | `Hooks.callAll`}
+   */
   static initialize(): void;
 
   /** Register game settings used by the Token Ring */
   static registerSettings(): void;
 
-  /** A mapping of token subject paths where modules or systems have configured subject images. */
+  /**
+   * A mapping of token subject paths where modules or systems have configured subject images.
+   * @defaultValue `{}`
+   * @remarks Not directly used anywhere in this class, essentially just a global cache. The system's `flags.tokenRingSubjectMappings`, if any, get assigned here in {@link Game.initializeConfig | `Game#initializeConfig`},
+   * and they're read in {@link TokenDocument._inferRingSubjectTexture | `TokenDocument#_inferRingSubjectTexture`}
+   */
   subjectPaths: Record<string, string>;
 
   /**
@@ -109,42 +120,51 @@ declare class TokenRingConfig {
 
   /**
    * Get the current ring class.
+   * @remarks Since `##currentConfig` is a reference to a `##configs` entry, not a copy, setting this will persist in that config
    */
-  get ringClass(): typeof TokenRing;
+  get ringClass(): DynamicRingData["framework"]["ringClass"];
   set ringClass(value);
 
   /** Get the current effects. */
-  get effects(): Record<string, string>;
+  get effects(): DynamicRingData["effects"];
 
   /** Get the current spritesheet. */
-  get spritesheet(): string;
+  get spritesheet(): DynamicRingData["spritesheet"];
 
-  /** Get the current shader class. */
-  get shaderClass(): typeof PrimaryBaseSamplerShader;
+  /**
+   * Get the current shader class.
+   * @remarks Since `##currentConfig` is a reference to a `##configs` entry, not a copy, setting this will persist in that config
+   */
+  get shaderClass(): DynamicRingData["framework"]["shaderClass"];
   set shaderClass(value);
 
   /** Get the current localized label */
-  get label(): string;
+  get label(): DynamicRingData["label"];
 
   /** Get the current id. */
-  get id(): string;
+  get id(): DynamicRingData["id"];
 
-  /** Is a custom fit mode active? */
+  /**
+   * Is a custom fit mode active?
+   * @remarks Anything other than `subject` is "custom", but the only other fit mode is `grid`
+   */
   get isGridFitMode(): boolean;
 
   /**
    * Add a new ring configuration.
    * @param id      - The id of the ring configuration.
    * @param config  - The configuration object for the ring.
+   * @throws If called outside a callback for the {@link Hooks.StaticCallbacks.initializeDynamicTokenRingConfig | `initializeDynamicTokenRingConfig`} hook
+   * @remarks The actual error thrown incorrectly refers to a non-existent `registerDynamicTokenRing` hook
    */
-  addConfig(id: string, config: TokenRingConfig): void;
+  addConfig(id: string, config: DynamicRingData): void;
 
   /**
    * Get a ring configuration.
    * @param id  - The id of the ring configuration.
    * @returns   - The ring configuration object.
    */
-  getConfig(id: string): TokenRingConfig;
+  getConfig(id: string): DynamicRingData;
 
   /**
    * Use a ring configuration.
@@ -159,11 +179,19 @@ declare class TokenRingConfig {
   /** Get the labels of all configurations. */
   get configLabels(): Record<string, string>;
 
-  /** @deprecated since v11 */
+  /**
+   * @deprecated since v12, until v14
+   * @remarks "TokenRingConfig#configNames is deprecated and replaced by TokenRingConfig#configIDs"
+   *
+   * Foundry comment claims deprecated since v11 - possibly a dnd5e-implementation-related deprecation?
+   */
   get configNames(): string[];
 }
 
 declare namespace TokenRingConfig {
+  interface Any extends AnyTokenRingConfig {}
+  type AnyConstructor = typeof AnyTokenRingConfig;
+
   /** Token ring fit modes for dynamic token ring visualization */
   interface RingFitMode {
     /** The fit mode identifier. */
@@ -173,18 +201,52 @@ declare namespace TokenRingConfig {
     label: string;
   }
 
-  /** Dynamic ring id. */
-  type DynamicRingId = string;
+  /**
+   * Core token rings fit modes used in Foundry VTT.
+   * @remarks Only the two provided core fit modes are checked against, by hardcoded IDs
+   */
+  interface CoreTokenRingsFitModes {
+    readonly subject: RingFitMode;
+    readonly grid: RingFitMode;
+  }
+
+  type CoreRingIDs = "coreSteel" | "coreBronze";
+
+  /**
+   * @remarks The type of any given {@link TokenRingConfig.CORE_TOKEN_RINGS | `TokenRingConfig.CORE_TOKEN_RINGS`} entry prior to
+   * {@link TokenRingConfig.initialize | `TokenRingConfig#initialize`} being called between the `setup` and `ready` hooks; Plain objects at this point
+   */
+  interface InitialCoreRingData extends Required<Pick<SourceCoreRingData, "id" | "label" | "spritesheet">> {}
+
+  interface InitialCoreRings extends Record<CoreRingIDs, InitialCoreRingData> {}
+
+  /**
+   * @remarks Due to the way the core configs are initialized, {@link TokenRingConfig.CORE_TOKEN_RINGS | `TokenRingConfig.CORE_TOKEN_RINGS`}
+   * ends up becoming the `_source` of the constructed DataModels in {@link CONFIG.Token.ring | `CONFIG.Token.ring`}, that is:
+   * ```js
+   * CONFIG.Token.ring.getConfig("coreSteel")._source === TokenRingConfig.CORE_TOKEN_RINGS.coreSteel
+   * ```
+   * after {@link TokenRingConfig.initialize | `TokenRingConfig#initialize`} has been called, which happens between the `setup` and `ready` hooks
+   */
+  interface SourceCoreRingData extends foundry.data.fields.SchemaField.SourceData<DynamicRingData.Schema> {}
+
+  interface SourceCoreRings extends Record<CoreRingIDs, SourceCoreRingData> {}
 
   /**
    * Core token rings used in Foundry VTT.
    * Each key is a string identifier for a ring, and the value is an object containing the ring's data.
    * This object is frozen to prevent any modifications.
+   * @remarks The outer object is frozen, but the individual rings' data isn't, and that object gets passed into a {@link DynamicRingData | `DynamicRingData`} constructor, leading to, for example,
+   * ```js
+   * CONFIG.Token.ring.getConfig("coreSteel")._source === TokenRingConfig.CORE_TOKEN_RINGS.coreSteel
+   * ```
+   * after {@link TokenRingConfig.initialize | `TokenRingConfig#initialize`} has been called, which happens between the `setup` and `ready` hooks
    */
-  interface CoreTokenRings extends Readonly<Record<DynamicRingId, DynamicRingData.RingData>> {}
+  type CoreTokenRings = InitializedOn<SourceCoreRings, "ready", InitialCoreRings>;
+}
 
-  /** Core token rings fit modes used in Foundry VTT. */
-  interface CoreTokenRingsFitModes extends Readonly<Record<string, RingFitMode>> {}
+declare abstract class AnyTokenRingConfig extends TokenRingConfig {
+  constructor(...args: never);
 }
 
 export default TokenRingConfig;

package/src/foundry/client-esm/canvas/tokens/ring-data.d.mts

@@ -1,5 +1,5 @@
-import type DataModel from "@common/abstract/data.d.mts";
-import type { DataField, DataSchema } from "@common/data/fields.d.mts";
+import type DataModel from "#common/abstract/data.d.mts";
+import type { DataField, DataSchema } from "#common/data/fields.d.mts";
 import type { AnyConstructor, SimpleMerge } from "fvtt-types/utils";
 import type TokenRing from "./ring.d.mts";
 
@@ -52,6 +52,7 @@ declare namespace DynamicRingData {
       /**
        * The manager class responsible for rendering token rings.
        * @defaultValue `TokenRing`
+       * @remarks Stays `typeof TokenRing` as its constructor must take a `Token.Implementation` argument
        */
       ringClass: ClassReferenceField<typeof TokenRing, { initial: typeof TokenRing; baseClass: typeof TokenRing }>;
 
@@ -60,115 +61,87 @@ declare namespace DynamicRingData {
        * @defaultValue `TokenRingSamplerShader`
        */
       shaderClass: ClassReferenceField<
-        typeof PrimaryBaseSamplerShader,
-        { initial: typeof TokenRingSamplerShader; baseClass: typeof PrimaryBaseSamplerShader }
+        PrimaryBaseSamplerShader.AnyConstructor,
+        { initial: PrimaryBaseSamplerShader.AnyConstructor; baseClass: PrimaryBaseSamplerShader.AnyConstructor }
       >;
     }>;
   }
+}
 
-  interface RingData {
-    /** The id of this Token Ring configuration. */
-    id: string;
+/**
+ * A special subclass of [DataField]{@link DataField} used to reference a class definition.
+ * @typeParam BaseClass - The base class constructor linked to this data field.
+ * @typeParam Options         - the options of the ClassReferenceField instance
+ * @typeParam AssignmentType  - the type of the allowed assignment values of the ClassReferenceField
+ * @typeParam InitializedType - the type of the initialized values of the ClassReferenceField
+ * @typeParam PersistedType   - the type of the persisted values of the ClassReferenceField
+ */
+declare class ClassReferenceField<
+  BaseClass extends AnyConstructor,
+  Options extends ClassReferenceField.Options<BaseClass> = ClassReferenceField.DefaultOptions,
+  AssignmentType = ClassReferenceField.AssignmentType<BaseClass, Options>,
+  InitializedType = ClassReferenceField.InitializedType<BaseClass, Options>,
+  PersistedType = InitializedType,
+> extends DataField<Options, AssignmentType, InitializedType, PersistedType> {
+  #ClassReferenceField: true;
 
-    /** The label of this Token Ring configuration. */
-    label: string;
+  constructor(options?: Options);
 
-    /** The spritesheet path which provides token ring frames for various sized creatures. */
-    spritesheet: string;
+  static override get _defaults(): DataField.Options.Any;
 
-    /** Registered special effects which can be applied to a token ring. */
-    effects: Record<string, string>;
+  protected override _cast(value: AssignmentType): InitializedType;
 
-    framework: {
-      /**
-       * The manager class responsible for rendering token rings.
-       * @defaultValue `TokenRing`
-       */
-      ringClass: typeof TokenRing;
-
-      /**
-       * The shader class used to render the TokenRing.
-       * @defaultValue `TokenRingSamplerShader`
-       */
-      shaderClass: typeof PrimaryBaseSamplerShader;
-    };
-  }
-
-  namespace ClassReferenceField {
-    /**
-     * A shorthand for the options of a ClassReferenceField class.
-     * @typeParam BaseClass - The base class constructor linked to this data field.
-     */
-    interface Options<BaseClass extends AnyConstructor> extends DataField.Options<BaseClass> {
-      /**
-       *The base class linked to this data field.
-       */
-      baseClass?: BaseClass;
-    }
-
-    type DefaultOptions = SimpleMerge<
-      DataField.DefaultOptions,
-      {
-        required: true;
-      }
-    >;
-
-    /**
-     * A helper type for the given options type merged into the default options of the ClassReferenceField class.
-     * @typeParam BaseClass - The base class constructor linked to this data field.
-     * @typeParam Options - the options that override the default options
-     */
-    type MergedOptions<
-      BaseClass extends AnyConstructor,
-      Options extends ClassReferenceField.Options<BaseClass>,
-    > = SimpleMerge<DefaultOptions, Options>;
-
-    /**
-     * A shorthand for the assignment type of a ClassReferenceField class.
-     * @typeParam BaseClass - The base class constructor linked to this data field.
-     * @typeParam Options - the options that override the default options
-     */
-    type AssignmentType<
-      BaseClass extends AnyConstructor,
-      Options extends ClassReferenceField.Options<BaseClass>,
-    > = DataField.DerivedAssignmentType<AnyConstructor, MergedOptions<BaseClass, Options>>;
+  override getInitialValue(data: DataField.CleanOptions["source"]): InitializedType;
+}
 
+declare namespace ClassReferenceField {
+  /**
+   * A shorthand for the options of a ClassReferenceField class.
+   * @typeParam BaseClass - The base class constructor linked to this data field.
+   */
+  interface Options<BaseClass extends AnyConstructor> extends DataField.Options<BaseClass> {
     /**
-     * A shorthand for the initialized type of a NumberField class.
-     * @typeParam BaseClass - The base class constructor linked to this data field.
-     * @typeParam Options - the options that override the default options
+     *The base class linked to this data field.
      */
-    type InitializedType<
-      BaseClass extends AnyConstructor,
-      Options extends ClassReferenceField.Options<BaseClass>,
-    > = DataField.DerivedInitializedType<BaseClass, MergedOptions<BaseClass, Options>>;
+    baseClass?: BaseClass;
   }
 
+  type DefaultOptions = SimpleMerge<
+    DataField.DefaultOptions,
+    {
+      required: true;
+    }
+  >;
+
   /**
-   * A special subclass of [DataField]{@link DataField} used to reference a class definition.
+   * A helper type for the given options type merged into the default options of the ClassReferenceField class.
    * @typeParam BaseClass - The base class constructor linked to this data field.
-   * @typeParam Options         - the options of the ClassReferenceField instance
-   * @typeParam AssignmentType  - the type of the allowed assignment values of the ClassReferenceField
-   * @typeParam InitializedType - the type of the initialized values of the ClassReferenceField
-   * @typeParam PersistedType   - the type of the persisted values of the ClassReferenceField
+   * @typeParam Options - the options that override the default options
    */
-  class ClassReferenceField<
+  type MergedOptions<
     BaseClass extends AnyConstructor,
-    Options extends ClassReferenceField.Options<BaseClass> = ClassReferenceField.DefaultOptions,
-    AssignmentType = ClassReferenceField.AssignmentType<BaseClass, Options>,
-    InitializedType = ClassReferenceField.InitializedType<BaseClass, Options>,
-    PersistedType = InitializedType,
-  > extends DataField<Options, AssignmentType, InitializedType, PersistedType> {
-    #ClassReferenceField: true;
+    Options extends ClassReferenceField.Options<BaseClass>,
+  > = SimpleMerge<DefaultOptions, Options>;
 
-    constructor(options?: Options);
-
-    static override get _defaults(): DataField.Options.Any;
-
-    protected override _cast(value: AssignmentType): InitializedType;
+  /**
+   * A shorthand for the assignment type of a ClassReferenceField class.
+   * @typeParam BaseClass - The base class constructor linked to this data field.
+   * @typeParam Options - the options that override the default options
+   */
+  type AssignmentType<
+    BaseClass extends AnyConstructor,
+    Options extends ClassReferenceField.Options<BaseClass>,
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+  > = DataField.DerivedAssignmentType<AnyConstructor, MergedOptions<BaseClass, Options>>;
 
-    override getInitialValue(data: DataField.CleanOptions["source"]): InitializedType;
-  }
+  /**
+   * A shorthand for the initialized type of a NumberField class.
+   * @typeParam BaseClass - The base class constructor linked to this data field.
+   * @typeParam Options - the options that override the default options
+   */
+  type InitializedType<
+    BaseClass extends AnyConstructor,
+    Options extends ClassReferenceField.Options<BaseClass>,
+  > = DataField.DerivedInitializedType<BaseClass, MergedOptions<BaseClass, Options>>;
 }
-
 export default DynamicRingData;