@league-of-foundry-developers/foundry-vtt-types 9.280.0 → 12.331.1-beta

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

@@ -0,0 +1,291 @@
+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(): 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(): 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(): 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(): 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: ColorSource | 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: 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: 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: 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: RGBColorVector): Color;
+}

package/src/foundry/common/utils/event-emitter.d.mts

@@ -0,0 +1,62 @@
+import type { InexactPartial, Mixin } from "../../../types/utils.d.mts";
+
+/**
+ * A mixin class which implements the behavior of EventTarget.
+ * This is useful in cases where a class wants EventTarget-like behavior but needs to extend some other class.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
+ */
+declare class EventEmitter {
+  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+  constructor(...args: any[]);
+
+  /**
+   * An array of event types which are valid for this class.
+   */
+  static emittedEvents: string[];
+
+  /**
+   * Add a new event listener for a certain type of event.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
+   * @param type     - The type of event being registered for
+   * @param listener - The listener function called when the event occurs
+   * @param options  - Options which configure the event listener
+   */
+  addEventListener(
+    type: string,
+    listener: EventEmitter.EmittedEventListener,
+    options?: InexactPartial<{
+      /**
+       * Should the event only be responded to once and then removed
+       * @defaultValue `false`
+       */
+      once: boolean;
+    }>,
+  ): void;
+
+  /**
+   * Remove an event listener for a certain type of event.
+   * @param type     - The type of event being removed
+   * @param listener - The listener function being removed
+   */
+  removeEventListener(type: string, listener: EventEmitter.EmittedEventListener): void;
+
+  /**
+   * Dispatch an event on this target.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent
+   * @param event - The Event to dispatch
+   * @returns Was default behavior for the event prevented?
+   */
+  dispatchEvent(event: Event): boolean;
+}
+
+declare namespace EventEmitter {
+  type EmittedEventListener = (event: Event) => void;
+}
+
+/**
+ * Augment a base class with EventEmitter behavior.
+ * @param BaseClass - Some base class augmented with event emitter functionality
+ */
+export default function EventEmitterMixin<ExtendedClass extends abstract new (...args: any[]) => any>(
+  BaseClass: ExtendedClass,
+): Mixin<typeof EventEmitter, ExtendedClass>;

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

@@ -0,0 +1,198 @@
+/**
+ * Determine the relative orientation of three points in two-dimensional space.
+ * The result is also an approximation of twice the signed area of the triangle defined by the three points.
+ * This method is fast - but not robust against issues of floating point precision. Best used with integer coordinates.
+ * Adapted from https://github.com/mourner/robust-predicates
+ *
+ * @param a - An endpoint of segment AB, relative to which point C is tested
+ * @param b - An endpoint of segment AB, relative to which point C is tested
+ * @param c - A point that is tested relative to segment AB
+ *
+ * @returns The relative orientation of points A, B, and C
+ *          A positive value if the points are in counter-clockwise order (C lies to the left of AB)
+ *          A negative value if the points are in clockwise order (C lies to the right of AB)
+ *          Zero if the points A, B, and C are collinear.
+ */
+export declare function orient2dFast(a: Point, b: Point, c: Point): number;
+
+/**
+ * Quickly test whether the line segment AB intersects with the line segment CD.
+ * This method does not determine the point of intersection, for that use lineLineIntersection
+ *
+ * @param a - The first endpoint of segment AB
+ * @param b - The second endpoint of segment AB
+ * @param c - The first endpoint of segment CD
+ * @param d - The second endpoint of segment CD
+ *
+ * @returns Do the line segments intersect?
+ */
+export declare function lineSegmentIntersects(a: Point, b: Point, c: Point, d: Point): boolean;
+
+export interface LineIntersection {
+  /** The x-coordinate of intersection */
+  x: number;
+
+  /** The y-coordinate of intersection */
+  y: number;
+
+  /** The vector distance from A to B on segment AB */
+  t0: number;
+
+  /** The vector distance from C to D on segment CD */
+  t1?: number | undefined;
+}
+
+interface LineIntersectionOptions {
+  /**
+   * Return the optional vector distance from C to D on CD
+   * @defaultValue `false`
+   */
+  t1?: boolean;
+}
+
+/**
+ * An internal helper method for computing the intersection between two infinite-length lines.
+ * Adapted from http://paulbourke.net/geometry/pointlineplane/
+ *
+ * @param a       - The first endpoint of segment AB
+ * @param b       - The second endpoint of segment AB
+ * @param c       - The first endpoint of segment CD
+ * @param d       - The second endpoint of segment CD
+ * @param options - Options which affect the intersection test
+ *
+ * @returns An intersection point, or null if no intersection occurred
+ */
+export declare function lineLineIntersection(
+  a: Point,
+  b: Point,
+  c: Point,
+  d: Point,
+  options?: LineIntersectionOptions,
+): LineIntersection | null;
+
+/**
+ * An internal helper method for computing the intersection between two finite line segments.
+ * Adapted from http://paulbourke.net/geometry/pointlineplane/
+ *
+ * @param a       - The first endpoint of segment AB
+ * @param b       - The second endpoint of segment AB
+ * @param c       - The first endpoint of segment CD
+ * @param d       - The second endpoint of segment CD
+ * @param epsilon - A small epsilon which defines a tolerance for near-equality
+ *                  (default: `1e-8`)
+ *
+ * @returns An intersection point, or null if no intersection occurred
+ */
+export declare function lineSegmentIntersection(
+  a: Point,
+  b: Point,
+  c: Point,
+  d: Point,
+  epsilon?: number,
+): LineIntersection | null;
+
+export interface LineCircleIntersection {
+  /** Is point A inside the circle? */
+  aInside: boolean;
+
+  /** Is point B inside the circle? */
+  bInside: boolean;
+
+  /** Is the segment AB contained within the circle? */
+  contained: boolean;
+
+  /** Is the segment AB fully outside the circle? */
+  outside: boolean;
+
+  /** Is the segment AB tangent to the circle? */
+  tangent: boolean;
+
+  /** Intersection points: zero, one, or two */
+  intersections: [Point?, Point?];
+}
+
+/**
+ * Determine the intersection between a candidate wall and the circular radius of the polygon.
+ *
+ * @param a       - The initial vertex of the candidate edge
+ * @param b       - The second vertex of the candidate edge
+ * @param center  - The center of the bounding circle
+ * @param radius  - The radius of the bounding circle
+ * @param epsilon - A small tolerance for floating point precision
+ *                  (default: `1e-8`)
+ *
+ * @returns The intersection of the segment AB with the circle
+ */
+export declare function lineCircleIntersection(
+  a: Point,
+  b: Point,
+  center: Point,
+  radius: number,
+  epsilon?: number,
+): LineCircleIntersection;
+
+/**
+ * Identify the point closest to C on segment AB
+ *
+ * @param c - The reference point C
+ * @param a - Point A on segment AB
+ * @param b - Point B on segment AB
+ *
+ * @returns The closest point to C on segment AB
+ */
+export declare function closestPointToSegment(c: Point, a: Point, b: Point): Point;
+
+/**
+ * Determine the points of intersection between a line segment (p0,p1) and a circle.
+ * There will be zero, one, or two intersections
+ * See https://math.stackexchange.com/a/311956
+ *
+ * @param p0      - The initial point of the line segment
+ * @param p1      - The terminal point of the line segment
+ * @param center  - The center of the circle
+ * @param radius  - The radius of the circle
+ * @param epsilon - A small tolerance for floating point precision
+ *                  (default: `0`)
+ */
+export declare function quadraticIntersection(
+  p0: Point,
+  p1: Point,
+  center: Point,
+  radius: number,
+  epsilon?: number,
+): [Point?, Point?];
+
+declare type Points = Point[] | number[];
+
+/**
+ * Calculate the centroid non-self-intersecting closed polygon.
+ * See https://en.wikipedia.org/wiki/Centroid#Of_a_polygon.
+ *
+ * @param points    - The points of the polygon
+ * @returns         - The centroid of the polygon
+ */
+export declare function polygonCentroid(points: Points): Point;
+
+/**
+ * Test whether the circle given by the center and radius intersects the path (open or closed).
+ *
+ * @param points    - The points of the path
+ * @param close     - If true, the edge from the last to the first point is tested
+ * @param center    - The center of the circle
+ * @param radius    - The radius of the circle
+ * @returns         - Whether the circle intersect the path
+ */
+export declare function pathCircleIntersects(points: Points, close: boolean, center: Point, radius: number): boolean;
+
+/**
+ * Test whether two circles (with position and radius) intersect.
+ *
+ * @param x0        - x center coordinate of circle A.
+ * @param y0        - y center coordinate of circle A.
+ * @param r0        - radius of circle A.
+ * @param x1        - x center coordinate of circle B.
+ * @param y1        - y center coordinate of circle B.
+ * @param r1        - radius of circle B.
+ * @returns         - True if the two circles intersect, false otherwise.
+ */
+export function circleCircleIntersects(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): boolean;