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

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

@@ -0,0 +1,74 @@
+import type { AnyConcreteConstructor, AnyConstructor, AnyFunction } from "../../types/utils.d.mts";
+import type { Document } from "./abstract/module.d.mts";
+
+// After seeing that none of these types add anything or are even exported a
+// very reasonable question may be: Why on earth does this file exist?
+//
+// Well this is the file in which Foundry defines these types. We don't house
+// them here because it has poor discoverability. The names Foundry has chosen
+// also overlaps with other existing names, such as SettingConfig vs. ClientSetting.SettingConfig
+
+type DocumentConstructionContext = Document.ConstructionContext<Document.Any | null>;
+
+/**
+ * Make all properties in T recursively readonly.
+ * @privateRemarks We have better tools & this is only used in a private method
+ */
+type DeepReadonly<T> = Readonly<{
+  [K in keyof T]: T[K] extends
+    | undefined
+    | null
+    | boolean
+    | number
+    | string
+    | symbol
+    | bigint
+    | AnyFunction
+    | AnyConstructor
+    | AnyConcreteConstructor
+    ? T[K]
+    : T[K] extends Array<infer V>
+      ? ReadonlyArray<DeepReadonly<V>>
+      : T[K] extends Map<infer K, infer V>
+        ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>>
+        : T[K] extends Set<infer V>
+          ? ReadonlySet<DeepReadonly<V>>
+          : DeepReadonly<T[K]>;
+}>;
+
+/**
+ * A class constructor.
+ * Used for functions with generic class constructor parameters.
+ * @privateRemarks We have better tools like {@link AnyConcreteConstructor} and {@link AnyConstructor}
+ */
+type Constructor = new (...args: any[]) => any;
+
+type Point = Canvas.Point;
+
+type PointArray = Canvas.PointArray;
+
+type Rectangle = Canvas.Rectangle;
+
+type BuiltinTypes = typeof Number | typeof String | typeof Boolean;
+
+type ColorSource = foundry.utils.Color.Source;
+
+type SettingConfig = ClientSettings.SettingConfig;
+
+type SettingSubmenuConfig = ClientSettings.SettingSubmenuConfig;
+
+type KeyBindingActionConfig = ClientKeybindings.KeybindingActionConfig;
+
+type KeybindingActionBinding = ClientKeybindings.KeybindingActionBinding;
+
+type KeybindingAction = ClientKeybindings.KeybindingAction;
+
+type KeyboardEventContext = KeyboardManager.KeyboardEventContext;
+
+type ConnectedGamepad = GamepadManager.ConnectedGamepad;
+
+type RequestData = SocketInterface.RequestData;
+
+type SocketRequest = SocketInterface.SocketRequest;
+
+type SocketResponse = SocketInterface.SocketResponse;

package/src/foundry/common/utils/bitmask.d.mts

@@ -0,0 +1,110 @@
+export default class BitMask extends Number {
+  /**
+   * Create a new BitMask instance.
+   * @param states    - An object containing valid states and their corresponding initial boolean values (default is null).
+   */
+  constructor(states?: Record<string, boolean> | null);
+
+  // a placeholder private method to help subclassing
+  #bitmask: true;
+
+  /**
+   * The enum associated with this structure.
+   * @readonly
+   */
+  states: Record<string, string>;
+
+  /**
+   * True if this bitmask is empty (no active states).
+   */
+  get isEmpty(): boolean;
+
+  /**
+   * Check if a specific state is active.
+   * @param state   - The state to check.
+   * @returns True if the state is active, false otherwise.
+   */
+  hasState(state: string): boolean;
+
+  /**
+   * Add a state to the bitmask.
+   * @param state - The state to add. Throws an error if the provided state is not valid.
+   */
+  addState(state: string): void;
+
+  /**
+   * Remove a state from the bitmask.
+   * @param state   - The state to remove. Throws an error if the provided state is not valid.
+   */
+  removeState(state: string): void;
+
+  /**
+   * Toggle the state of a specific state in the bitmask.
+   * @param state   - The state to toggle. Throws an error if the provided state is not valid.
+   * @param enabled - Toggle on (true) or off (false)? If undefined, the state is switched automatically.
+   */
+  toggleState(state: string, enabled: boolean): void;
+
+  /**
+   * Toggle the state of a specific state in the bitmask.
+   * @param state - The state to toggle.
+   * @returns  The updated bitmask. Throws an error if the provided state is not valid.
+   */
+  toggleState(state: string): number;
+
+  /**
+   * Clear the bitmask, setting all states to inactive.
+   */
+  clear(): void;
+
+  /**
+   * Get the current value of the bitmask.
+   * @returns The current value of the bitmask.
+   */
+  valueOf(): number;
+
+  /**
+   * Get a string representation of the bitmask in binary format.
+   * @returns The string representation of the bitmask.
+   */
+  toString(): string;
+
+  /**
+   * Checks if two bitmasks structures are compatible (the same valid states).
+   * @param otherBitMask  - The bitmask structure to compare with.
+   * @returns True if the two bitmasks have the same structure, false otherwise.
+   */
+  isCompatible(otherBitMask: BitMask): boolean;
+
+  /**
+   * Serializes the bitmask to a JSON string.
+   * @returns The JSON string representing the bitmask.
+   */
+  toJSON(): string;
+
+  /**
+   * Creates a new BitMask instance from a JSON string.
+   * @param jsonString    - The JSON string representing the bitmask.
+   * @returns A new BitMask instance created from the JSON string.
+   */
+  static fromJSON(jsonString: string): BitMask;
+
+  /**
+   * Convert value of this BitMask to object representation according to structure.
+   * @returns The data represented by the bitmask.
+   */
+  toObject(): Record<string, boolean>;
+
+  /**
+   * Creates a clone of this BitMask instance.
+   * @returns A new BitMask instance with the same value and valid states as this instance.
+   */
+  clone(): BitMask;
+
+  /**
+   * Generates shader constants based on the provided states.
+   * @param states    - An array containing valid states.
+   * @returns Shader bit mask constants generated from the states.
+   */
+  static generateShaderBitMaskConstants(states: string[]): string;
+}

package/src/foundry/common/utils/collection.d.mts

@@ -0,0 +1,176 @@
+interface MapReplacementMembers<K, V> {
+  set(key: K, value: V): this;
+}
+
+type PatchedMap<K, V> = Omit<Map<K, V>, "forEach" | typeof Symbol.iterator | "get" | "set"> &
+  MapReplacementMembers<K, V>;
+
+declare namespace PatchedMap {
+  type Any = PatchedMap<any, any>;
+}
+
+interface PatchedMapConstructor {
+  new (): PatchedMap.Any;
+  new <K, V>(entries?: readonly (readonly [K, V])[] | null): PatchedMap<K, V>;
+  new <K, V>(iterable: Iterable<readonly [K, V]>): PatchedMap<K, V>;
+  readonly [Symbol.species]: PatchedMapConstructor;
+  readonly prototype: PatchedMap.Any;
+}
+
+declare const Map: PatchedMapConstructor;
+
+/**
+ * A reusable storage concept which blends the functionality of an Array with the efficient key-based lookup of a Map.
+ * This concept is reused throughout Foundry VTT where a collection of uniquely identified elements is required.
+ * @typeParam T - The type of the objects contained in the Collection
+ */
+declare class Collection<V> extends Map<string, V> {
+  constructor(entries?: readonly (readonly [string, V])[] | null);
+
+  /**
+   * When iterating over a Collection, we should iterate over its values instead of over its entries
+   */
+  [Symbol.iterator](): IterableIterator<V>;
+
+  /**
+   * Return an Array of all the entry values in the Collection
+   */
+  get contents(): V[];
+
+  /**
+   * Find an entry in the Map using an functional condition.
+   * @see {@link Array#find}
+   *
+   * @param condition - The functional condition to test. Positional arguments are the value, the index of
+   *                    iteration, and the collection being searched.
+   * @returns The value, if found, otherwise undefined
+   *
+   * @example Create a new Collection and reference its contents
+   * ```typescript
+   * let c = new Collection([["a", "A"], ["b", "B"], ["c", "C"]]);
+   * c.get("a") === c.find(entry => entry === "A"); // true
+   * ```
+   */
+  find<S extends V>(condition: (e: V, index: number, collection: Collection<V>) => e is S): S | undefined;
+  find(condition: (e: V, index: number, collection: Collection<V>) => boolean): V | undefined;
+
+  /**
+   * Filter the Collection, returning an Array of entries which match a functional condition.
+   * @see {@link Array#filter}
+   *
+   * @param condition - The functional condition to test. Positional arguments are the value, the
+   *                    index of iteration, and the collection being filtered.
+   * @returns An Array of matched values
+   *
+   * @example Filter the Collection for specific entries
+   * ```typescript
+   * let c = new Collection([["a", "AA"], ["b", "AB"], ["c", "CC"]]);
+   * let hasA = c.filters(entry => entry.slice(0) === "A");
+   * ```
+   */
+  filter<S extends V>(condition: (e: V, index: number, collection: Collection<V>) => e is S): S[];
+  filter(condition: (e: V, index: number, collection: Collection<V>) => boolean): V[];
+
+  /**
+   * Apply a function to each element of the collection
+   * @see Array#forEach
+   * @param fn - The function to apply to each element
+   *
+   * @example Apply a function to each value in the collection
+   * ```typescript
+   * let c = new Collection([["a", {active: false}], ["b", {active: false}], ["c", {active: false}]]);
+   * c.forEach(e => e.active = true);
+   * ```
+   */
+  forEach(fn: (e: V) => void): void;
+
+  /**
+   * Get an element from the Collection by its key.
+   * @param key     - The key of the entry to retrieve
+   * @param strict  - Throw an Error if the requested key does not exist,
+   *                  otherwise return undefined. (default: `false`)
+   * @returns The retrieved entry value, if the key exists, otherwise undefined
+   *
+   * @example Get an element from the Collection by key
+   * ```typescript
+   * let c = new Collection([["a", "A"], ["b", "B"], ["c", "C"]]);
+   * c.get("a"); // "A"
+   * c.get("d"); // null
+   * c.get("d", {strict: true}); // throws Error
+   * ```
+   */
+  get(key: string, { strict }: { strict: true }): V;
+  get(key: string, { strict }?: { strict?: false }): V | undefined;
+
+  /**
+   * Get an entry from the Collection by name.
+   * Use of this method assumes that the objects stored in the collection have a "name" attribute.
+   * @param name    - The name of the entry to retrieve
+   * @param strict  - Throw an Error if the requested name does not exist,
+   *                  otherwise return undefined. (default: `false`)
+   * @returns The retrieved Entity, if one was found, otherwise undefined
+   *
+   * @example Get an element from the Collection by name (if applicable)
+   * ```typescript
+   * let c = new Collection([["a", "Alfred"], ["b", "Bob"], ["c", "Cynthia"]]);
+   * c.getName("Alfred"); // "Alfred"
+   * c.getName("D"); // undefined
+   * c.getName("D", {strict: true}); // throws Error
+   * ```
+   */
+  getName(name: string, { strict }: { strict: true }): V;
+  getName(name: string, { strict }?: { strict?: false }): V | undefined;
+
+  /**
+   * Transform each element of the Collection into a new form, returning an Array of transformed values
+   * @param transformer - A transformation function applied to each entry value. Positional arguments are the value, the
+   *                      index of iteration, and the collection being mapped.
+   * @typeParam M       - The type of the mapped values
+   * @returns An Array of transformed values
+   */
+  map<M>(transformer: (entity: V, index: number, collection: Collection<V>) => M): M[];
+
+  /**
+   * Reduce the Collection by applying an evaluator function and accumulating entries
+   * @see {@link Array#reduce}
+   * @param reducer   - A reducer function applied to each entry value. Positional arguments are the accumulator, the
+   *                    value, the index of iteration, and the collection being reduced.
+   * @param initial   - An initial value which accumulates with each iteration
+   * @typeParam A     - The type of the accumulator and the return value
+   * @returns The accumulated result
+   *
+   * @example Reduce a collection to an array of transformed values
+   * ```typescript
+   * let c = new Collection([["a", "A"], ["b", "B"], ["c", "C"]]);
+   * let letters = c.reduce((s, l) => {
+   *   return s + l;
+   * }, ""); // "ABC"
+   * ```
+   */
+  reduce<A>(evaluator: (accumulator: A, entity: V, index: number, collection: Collection<V>) => A, initial: A): A;
+
+  /**
+   * Test whether a condition is met by some entry in the Collection.
+   * @see Array#some
+   * @param condition - The functional condition to test. Positional arguments are the value, the index of iteration,
+   *                    and the collection being tested.
+   * @returns Was the test condition passed by at least one entry?
+   */
+  some(condition: (e: V, index: number, collection: Collection<V>) => boolean): boolean;
+
+  /**
+   * Convert the Collection to a primitive array of its contents.
+   * @returns An array of contained values
+   */
+  toJSON(): Array<V extends { toJSON: (...args: any[]) => infer U } ? U : V>;
+}
+
+declare namespace Collection {
+  type AnyConstructor = typeof AnyCollection;
+}
+
+declare abstract class AnyCollection extends Collection<any> {
+  constructor(arg0: never, ...args: never[]);
+}
+
+export default Collection;

package/src/foundry/common/utils/color.d.mts

@@ -0,0 +1,299 @@
+export default Color;
+/**
+ * A representation of a color in hexadecimal format.
+ * This class provides methods for transformations and manipulations of colors.
+ */
+// @ts-expect-error 2417: Override of Color.fromString does not match Number.fromString
+declare class Color extends Number {
+  /**
+   * Is this a valid color?
+   */
+  get valid(): boolean;
+
+  /**
+   * A CSS-compatible color string.
+   * If this color is not valid, the empty string is returned.
+   * An alias for Color#toString.
+   */
+  get css(): string;
+
+  /**
+   * The color represented as an RGB array.
+   */
+  get rgb(): Color.RGBColorVector;
+
+  /**
+   * The numeric value of the red channel between [0, 1].
+   */
+  get r(): number;
+
+  /**
+   * The numeric value of the green channel between [0, 1].
+   */
+  get g(): number;
+
+  /**
+   * The numeric value of the blue channel between [0, 1].
+   */
+  get b(): number;
+
+  /**
+   * The maximum value of all channels.
+   */
+  get maximum(): number;
+
+  /**
+   * The minimum value of all channels.
+   */
+  get minimum(): number;
+
+  /**
+   * Get the value of this color in little endian format.
+   */
+  get littleEndian(): number;
+
+  /**
+   * The color represented as an HSV array.
+   * Conversion formula adapted from {@link http://en.wikipedia.org/wiki/HSV_color_space}.
+   * Assumes r, g, and b are contained in the set [0, 1] and returns h, s, and v in the set [0, 1].
+   */
+  get hsv(): Color.HSVColorVector;
+
+  /**
+   * The color represented as an HSL array.
+   * Assumes r, g, and b are contained in the set [0, 1] and returns h, s, and l in the set [0, 1].
+   */
+  get hsl(): Color.HSLColorVector;
+
+  /**
+   * The color represented as a linear RGB array.
+   * Assumes r, g, and b are contained in the set [0, 1] and returns linear r, g, and b in the set [0, 1].
+   * {@link https://en.wikipedia.org/wiki/SRGB#Transformation}
+   */
+  get linear(): Color.RGBColorVector;
+
+  override toString(): string;
+
+  /**
+   * Serialize the Color.
+   * @returns The color as a CSS string
+   */
+  toJSON(): string;
+
+  /**
+   * Returns the color as a CSS string.
+   * @returns The color as a CSS string
+   */
+  toHTML(): string;
+
+  /**
+   * Test whether this color equals some other color
+   * @param other - Some other color or hex number
+   * @returns Are the colors equal?
+   */
+  equals(other: Color | number): boolean;
+
+  /**
+   * Get a CSS-compatible RGBA color string.
+   * @param alpha - The desired alpha in the range [0, 1]
+   * @returns A CSS-compatible RGBA string
+   */
+  toRGBA(alpha: number): string;
+
+  /**
+   * Mix this Color with some other Color using a provided interpolation weight.
+   * @param other  - Some other Color to mix with
+   * @param weight - The mixing weight placed on this color where weight is placed on the other color
+   * @returns The resulting mixed Color
+   */
+  mix(other: Color, weight: number): Color;
+
+  /**
+   * Multiply this Color by another Color or a static scalar.
+   * @param other - Some other Color or a static scalar.
+   * @returns The resulting Color.
+   */
+  multiply(other: Color | number): Color;
+
+  /**
+   * Add this Color by another Color or a static scalar.
+   * @param other - Some other Color or a static scalar.
+   * @returns The resulting Color.
+   */
+  add(other: Color | number): Color;
+
+  /**
+   * Subtract this Color by another Color or a static scalar.
+   * @param other - Some other Color or a static scalar.
+   * @returns The resulting Color.
+   */
+  subtract(other: Color | number): Color;
+
+  /**
+   * Max this color by another Color or a static scalar.
+   * @param other - Some other Color or a static scalar.
+   * @returns The resulting Color.
+   */
+  maximize(other: Color | number): Color;
+
+  /**
+   * Min this color by another Color or a static scalar.
+   * @param other - Some other Color or a static scalar.
+   * @returns The resulting Color.
+   */
+  minimize(other: Color | number): Color;
+
+  /**
+   * Iterating over a Color is equivalent to iterating over its [r,g,b] color channels.
+   */
+  [Symbol.iterator](): Generator<number>;
+
+  /**
+   * Set an rgb array with the rgb values contained in this Color class.
+   * @param vec3 - Receive the result. Must be an array with at least a length of 3.
+   */
+  applyRGB(vec: number[]): void;
+
+  /**
+   * Apply a linear interpolation between two colors, according to the weight.
+   * @param color1 - The first color to mix.
+   * @param color2 - The second color to mix.
+   * @param weight - Weight of the linear interpolation.
+   * @returns The resulting mixed color
+   */
+  static mix(color1: number, color2: number, weight: number): number;
+
+  /**
+   * Multiply a color by a scalar
+   * @param color  - The color to multiply.
+   * @param scalar - A static scalar to multiply with.
+   * @returns The resulting color as a number.
+   */
+  static multiplyScalar(color: number, scalar: number): number;
+
+  /**
+   * Maximize two colors.
+   * @param color1 - The first color.
+   * @param color2 - The second color.
+   * @returns The resulting color as a number.
+   */
+  static maximize(color1: number, color2: number): number;
+
+  /**
+   * Maximize a color by a static scalar.
+   * @param color  - The color to maximize.
+   * @param scalar - Scalar to maximize with (normalized).
+   * @returns The resulting color as a number.
+   */
+  static maximizeScalar(color: number, scalar: number): number;
+
+  /**
+   * Add two colors.
+   * @param color1 - The first color.
+   * @param color2 - The second color.
+   * @returns The resulting color as a number.
+   */
+  static add(color1: number, color2: number): number;
+
+  /**
+   * Add a static scalar to a color.
+   * @param color  - The color.
+   * @param scalar - Scalar to add with (normalized).
+   * @returns The resulting color as a number.
+   */
+  static addScalar(color: number, scalar: number): number;
+
+  /**
+   * Subtract two colors.
+   * @param color1 - The first color.
+   * @param color2 - The second color.
+   * @returns The resulting color as a number.
+   */
+  static subtract(color1: number, color2: number): number;
+
+  /**
+   * Subtract a color by a static scalar.
+   * @param color  - The color.
+   * @param scalar - Scalar to subtract with (normalized).
+   * @returns The resulting color as a number.
+   */
+  static subtractScalar(color: number, scalar: number): number;
+
+  /**
+   * Minimize two colors.
+   * @param color1 - The first color.
+   * @param color2 - The second color.
+   * @returns The resulting color as a number.
+   */
+  static minimize(color1: number, color2: number): number;
+
+  /**
+   * Minimize a color by a static scalar.
+   * @param color  - The color.
+   * @param scalar - Scalar to minimize with (normalized).
+   * @returns The resulting color as a number.
+   */
+  static minimizeScalar(color: number, scalar: number): number;
+
+  /**
+   * Convert a color to RGB and assign values to a passed array.
+   * @param color - The color to convert to RGB values.
+   * @param vec3  - Receive the result. Must be an array with at least a length of 3.
+   */
+  static applyRGB(color: number, vec3: number[]): void;
+
+  /**
+   * Create a Color instance from an RGB array.
+   * @param color - A color input
+   * @returns The hex color instance or NaN
+   */
+  static from(color: Color.Source | null | undefined): Color;
+
+  /**
+   * Create a Color instance from a color string which either includes or does not include a leading #.
+   * @param color - A color string
+   * @returns The hex color instance
+   */
+  static fromString(color: string): Color;
+
+  /**
+   * Create a Color instance from an RGB array.
+   * @param rgb - An RGB tuple
+   * @returns The hex color instance
+   */
+  static fromRGB(rgb: Color.RGBColorVector): Color;
+
+  /**
+   * Create a Color instance from an HSV array.
+   * Conversion formula adapted from {@link http://en.wikipedia.org/wiki/HSV_color_space}.
+   * Assumes h, s, and v are contained in the set [0, 1].
+   * @param hsv - An HSV tuple
+   * @returns The hex color instance
+   */
+  static fromHSV(hsv: Color.HSVColorVector): Color;
+
+  /**
+   * Create a Color instance from an HSL array.
+   * Assumes h, s, and l are contained in the set [0, 1].
+   * @param hsl - An HSL tuple
+   * @returns The hex color instance
+   */
+  static fromHSL(hsl: Color.HSLColorVector): Color;
+
+  /**
+   * Create a Color instance (sRGB) from a linear rgb array.
+   * Assumes r, g, and b are contained in the set [0, 1].
+   * {@link https://en.wikipedia.org/wiki/SRGB#Transformation}
+   * @param linear - The linear rgb array
+   * @returns The hex color instance
+   */
+  static fromLinearRGB(linear: Color.RGBColorVector): Color;
+}
+
+declare namespace Color {
+  type RGBColorVector = [r: number, g: number, b: number];
+  type HSVColorVector = [h: number, s: number, v: number];
+  type HSLColorVector = [h: number, s: number, l: number];
+
+  type Source = number | RGBColorVector | string | Color;
+}