tgui-core 1.0.0

package/src/common/color.ts

@@ -0,0 +1,94 @@
+/**
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+const EPSILON = 0.0001;
+
+export class Color {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+
+  constructor(r = 0, g = 0, b = 0, a = 1) {
+    this.r = r;
+    this.g = g;
+    this.b = b;
+    this.a = a;
+  }
+
+  toString(): string {
+    // Alpha component needs to permit fractional values, so cannot use |
+    let alpha = this.a;
+    if (typeof alpha === 'string') {
+      alpha = parseFloat(this.a as any);
+    }
+    if (isNaN(alpha)) {
+      alpha = 1;
+    }
+    return `rgba(${this.r | 0}, ${this.g | 0}, ${this.b | 0}, ${alpha})`;
+  }
+
+  /**  Darkens a color by a given percent. Returns a color, which can have toString called to get it's rgba() css value. */
+  darken(percent: number): Color {
+    percent /= 100;
+    return new Color(
+      this.r - this.r * percent,
+      this.g - this.g * percent,
+      this.b - this.b * percent,
+      this.a,
+    );
+  }
+
+  /** Brightens a color by a given percent. Returns a color, which can have toString called to get it's rgba() css value. */
+  lighten(percent: number): Color {
+    // No point in rewriting code we already have.
+    return this.darken(-percent);
+  }
+
+  /**
+   * Creates a color from the CSS hex color notation.
+   */
+  static fromHex(hex: string): Color {
+    return new Color(
+      parseInt(hex.slice(1, 3), 16),
+      parseInt(hex.slice(3, 5), 16),
+      parseInt(hex.slice(5, 7), 16),
+    );
+  }
+
+  /**
+   * Linear interpolation of two colors.
+   */
+  static lerp(c1: Color, c2: Color, n: number): Color {
+    return new Color(
+      (c2.r - c1.r) * n + c1.r,
+      (c2.g - c1.g) * n + c1.g,
+      (c2.b - c1.b) * n + c1.b,
+      (c2.a - c1.a) * n + c1.a,
+    );
+  }
+
+  /**
+   * Loops up the color in the provided list of colors
+   * with linear interpolation.
+   */
+  static lookup(value: number, colors: Color[]): Color {
+    const len = colors.length;
+    if (len < 2) {
+      throw new Error('Needs at least two colors!');
+    }
+    const scaled = value * (len - 1);
+    if (value < EPSILON) {
+      return colors[0];
+    }
+    if (value >= 1 - EPSILON) {
+      return colors[len - 1];
+    }
+    const ratio = scaled % 1;
+    const index = scaled | 0;
+    return this.lerp(colors[index], colors[index + 1], ratio);
+  }
+}

package/src/common/events.ts

@@ -0,0 +1,45 @@
+/**
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+type Fn = (...args: any[]) => void;
+
+export class EventEmitter {
+  private listeners: Record<string, Fn[]>;
+
+  constructor() {
+    this.listeners = {};
+  }
+
+  on(name: string, listener: Fn): void {
+    this.listeners[name] = this.listeners[name] || [];
+    this.listeners[name].push(listener);
+  }
+
+  off(name: string, listener: Fn): void {
+    const listeners = this.listeners[name];
+    if (!listeners) {
+      throw new Error(`There is no listeners for "${name}"`);
+    }
+    this.listeners[name] = listeners.filter((existingListener) => {
+      return existingListener !== listener;
+    });
+  }
+
+  emit(name: string, ...params: any[]): void {
+    const listeners = this.listeners[name];
+    if (!listeners) {
+      return;
+    }
+    for (let i = 0, len = listeners.length; i < len; i += 1) {
+      const listener = listeners[i];
+      listener(...params);
+    }
+  }
+
+  clear(): void {
+    this.listeners = {};
+  }
+}

package/src/common/exhaustive.ts

@@ -0,0 +1,19 @@
+/**
+ * Throws an error such that a non-exhaustive check will error at compile time
+ * when using TypeScript, rather than at runtime.
+ *
+ * For example:
+ * enum Color { Red, Green, Blue }
+ * switch (color) {
+ *  case Color.Red:
+ *    return "red";
+ *  case Color.Green:
+ *    return "green";
+ *  default:
+ *    // This will error at compile time that we forgot blue.
+ *    exhaustiveCheck(color);
+ * }
+ */
+export const exhaustiveCheck = (input: never) => {
+  throw new Error(`Unhandled case: ${input}`);
+};

package/src/common/fp.ts

@@ -0,0 +1,38 @@
+/**
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+type Func = (...args: any[]) => any;
+
+/**
+ * Creates a function that returns the result of invoking the given
+ * functions, where each successive invocation is supplied the return
+ * value of the previous.
+ *
+ * @example
+ * ```tsx
+ * const add2 = (x) => x + 2;
+ * const multiplyBy3 = (x) => x * 3;
+ * const subtract5 = (x) => x - 5;
+ *
+ * const composedFunction = flow(add2, multiplyBy3, subtract5); // ((4 + 2) * 3) - 5 = 13
+ * const composedFunction2 = flow([add2, multiplyBy3], subtract5); // ((4 + 2) * 3) - 5 = 13
+ *
+ */
+export const flow =
+  (...funcs: Array<Func | Func[]>) =>
+  (input: any, ...rest: any[]): any => {
+    let output = input;
+
+    for (let func of funcs) {
+      // Recurse into the array of functions
+      if (Array.isArray(func)) {
+        output = flow(...func)(output, ...rest);
+      } else if (func) {
+        output = func(output, ...rest);
+      }
+    }
+    return output;
+  };

package/src/common/keycodes.ts

@@ -0,0 +1,86 @@
+/**
+ * All possible browser keycodes, in one file.
+ *
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+export const KEY_BACKSPACE = 8;
+export const KEY_TAB = 9;
+export const KEY_ENTER = 13;
+export const KEY_SHIFT = 16;
+export const KEY_CTRL = 17;
+export const KEY_ALT = 18;
+export const KEY_PAUSE = 19;
+export const KEY_CAPSLOCK = 20;
+export const KEY_ESCAPE = 27;
+export const KEY_SPACE = 32;
+export const KEY_PAGEUP = 33;
+export const KEY_PAGEDOWN = 34;
+export const KEY_END = 35;
+export const KEY_HOME = 36;
+export const KEY_LEFT = 37;
+export const KEY_UP = 38;
+export const KEY_RIGHT = 39;
+export const KEY_DOWN = 40;
+export const KEY_INSERT = 45;
+export const KEY_DELETE = 46;
+export const KEY_0 = 48;
+export const KEY_1 = 49;
+export const KEY_2 = 50;
+export const KEY_3 = 51;
+export const KEY_4 = 52;
+export const KEY_5 = 53;
+export const KEY_6 = 54;
+export const KEY_7 = 55;
+export const KEY_8 = 56;
+export const KEY_9 = 57;
+export const KEY_A = 65;
+export const KEY_B = 66;
+export const KEY_C = 67;
+export const KEY_D = 68;
+export const KEY_E = 69;
+export const KEY_F = 70;
+export const KEY_G = 71;
+export const KEY_H = 72;
+export const KEY_I = 73;
+export const KEY_J = 74;
+export const KEY_K = 75;
+export const KEY_L = 76;
+export const KEY_M = 77;
+export const KEY_N = 78;
+export const KEY_O = 79;
+export const KEY_P = 80;
+export const KEY_Q = 81;
+export const KEY_R = 82;
+export const KEY_S = 83;
+export const KEY_T = 84;
+export const KEY_U = 85;
+export const KEY_V = 86;
+export const KEY_W = 87;
+export const KEY_X = 88;
+export const KEY_Y = 89;
+export const KEY_Z = 90;
+export const KEY_F1 = 112;
+export const KEY_F2 = 113;
+export const KEY_F3 = 114;
+export const KEY_F4 = 115;
+export const KEY_F5 = 116;
+export const KEY_F6 = 117;
+export const KEY_F7 = 118;
+export const KEY_F8 = 119;
+export const KEY_F9 = 120;
+export const KEY_F10 = 121;
+export const KEY_F11 = 122;
+export const KEY_F12 = 123;
+export const KEY_SEMICOLON = 186;
+export const KEY_EQUAL = 187;
+export const KEY_COMMA = 188;
+export const KEY_MINUS = 189;
+export const KEY_PERIOD = 190;
+export const KEY_SLASH = 191;
+export const KEY_LEFT_BRACKET = 219;
+export const KEY_BACKSLASH = 220;
+export const KEY_RIGHT_BRACKET = 221;
+export const KEY_QUOTE = 222;

package/src/common/keys.ts

@@ -0,0 +1,39 @@
+/**
+ * ### Key codes.
+ * event.keyCode is deprecated, use this reference instead.
+ *
+ * Handles modifier keys (Shift, Alt, Control) and arrow keys.
+ *
+ * For alphabetical keys, use the actual character (e.g. 'a') instead of the key code.
+ *
+ * Something isn't here that you want? Just add it:
+ * @url https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values
+ * @usage
+ * ```ts
+ * import { KEY } from 'tgui/common/keys';
+ *
+ * if (event.key === KEY.Enter) {
+ *   // do something
+ * }
+ * ```
+ */
+export enum KEY {
+  Alt = 'Alt',
+  Backspace = 'Backspace',
+  Control = 'Control',
+  Delete = 'Delete',
+  Down = 'ArrowDown',
+  End = 'End',
+  Enter = 'Enter',
+  Escape = 'Escape',
+  Home = 'Home',
+  Insert = 'Insert',
+  Left = 'ArrowLeft',
+  PageDown = 'PageDown',
+  PageUp = 'PageUp',
+  Right = 'ArrowRight',
+  Shift = 'Shift',
+  Space = ' ',
+  Tab = 'Tab',
+  Up = 'ArrowUp',
+}

package/src/common/math.ts

@@ -0,0 +1,98 @@
+/**
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+/**
+ * Limits a number to the range between 'min' and 'max'.
+ */
+export const clamp = (value, min, max) => {
+  return value < min ? min : value > max ? max : value;
+};
+
+/**
+ * Limits a number between 0 and 1.
+ */
+export const clamp01 = (value) => {
+  return value < 0 ? 0 : value > 1 ? 1 : value;
+};
+
+/**
+ * Scales a number to fit into the range between min and max.
+ */
+export const scale = (value, min, max) => {
+  return (value - min) / (max - min);
+};
+
+/**
+ * Robust number rounding.
+ *
+ * Adapted from Locutus, see: http://locutus.io/php/math/round/
+ *
+ * @param  {number} value
+ * @param  {number} precision
+ * @return {number}
+ */
+export const round = (value, precision) => {
+  if (!value || isNaN(value)) {
+    return value;
+  }
+  // helper variables
+  let m, f, isHalf, sgn;
+  // making sure precision is integer
+  precision |= 0;
+  m = Math.pow(10, precision);
+  value *= m;
+  // sign of the number
+  sgn = +(value > 0) | -(value < 0);
+  // isHalf = value % 1 === 0.5 * sgn;
+  isHalf = Math.abs(value % 1) >= 0.4999999999854481;
+  f = Math.floor(value);
+  if (isHalf) {
+    // rounds .5 away from zero
+    value = f + (sgn > 0);
+  }
+  return (isHalf ? value : Math.round(value)) / m;
+};
+
+/**
+ * Returns a string representing a number in fixed point notation.
+ */
+export const toFixed = (value, fractionDigits = 0) => {
+  return Number(value).toFixed(Math.max(fractionDigits, 0));
+};
+
+/**
+ * Checks whether a value is within the provided range.
+ *
+ * Range is an array of two numbers, for example: [0, 15].
+ */
+export const inRange = (value, range) => {
+  return range && value >= range[0] && value <= range[1];
+};
+
+/**
+ * Walks over the object with ranges, comparing value against every range,
+ * and returns the key of the first matching range.
+ *
+ * Range is an array of two numbers, for example: [0, 15].
+ */
+export const keyOfMatchingRange = (value, ranges) => {
+  for (let rangeName of Object.keys(ranges)) {
+    const range = ranges[rangeName];
+    if (inRange(value, range)) {
+      return rangeName;
+    }
+  }
+};
+
+/**
+ * Get number of digits following the decimal point in a number
+ */
+export const numberOfDecimalDigits = (value) => {
+  if (Math.floor(value) !== value) {
+    return value.toString().split('.')[1].length || 0;
+  }
+  return 0;
+};

package/src/common/perf.ts

@@ -0,0 +1,72 @@
+/**
+ * Ghetto performance measurement tools.
+ *
+ * Uses NODE_ENV to remove itself from production builds.
+ *
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+const FPS = 60;
+const FRAME_DURATION = 1000 / FPS;
+
+// True if Performance API is supported
+const supportsPerf = !!window.performance?.now;
+// High precision markers
+let hpMarkersByName: Record<string, number> = {};
+// Low precision markers
+let lpMarkersByName: Record<string, number> = {};
+
+/**
+ * Marks a certain spot in the code for later measurements.
+ */
+function mark(name: string, timestamp?: number): void {
+  if (process.env.NODE_ENV !== 'production') {
+    if (supportsPerf && !timestamp) {
+      hpMarkersByName[name] = performance.now();
+    }
+    lpMarkersByName[name] = timestamp || Date.now();
+  }
+}
+
+/**
+ * Calculates and returns the difference between two markers as a string.
+ *
+ * Use logger.log() to print the measurement.
+ */
+function measure(markerNameA: string, markerNameB: string): string | undefined {
+  if (process.env.NODE_ENV === 'production') return;
+
+  let markerA = hpMarkersByName[markerNameA];
+  let markerB = hpMarkersByName[markerNameB];
+
+  if (!markerA || !markerB) {
+    markerA = lpMarkersByName[markerNameA];
+    markerB = lpMarkersByName[markerNameB];
+  }
+
+  const duration = Math.abs(markerB - markerA);
+
+  return formatDuration(duration);
+}
+
+/**
+ * Formats a duration in milliseconds and frames.
+ */
+function formatDuration(duration: number): string {
+  const durationInFrames = duration / FRAME_DURATION;
+
+  return (
+    duration.toFixed(duration < 10 ? 1 : 0) +
+    'ms ' +
+    '(' +
+    durationInFrames.toFixed(2) +
+    ' frames)'
+  );
+}
+
+export const perf = {
+  mark,
+  measure,
+};

package/src/common/random.ts

@@ -0,0 +1,32 @@
+import { clamp } from './math';
+
+/**
+ * Returns random number between lowerBound exclusive and upperBound inclusive
+ */
+export const randomNumber = (lowerBound: number, upperBound: number) => {
+  return Math.random() * (upperBound - lowerBound) + lowerBound;
+};
+
+/**
+ * Returns random integer between lowerBound exclusive and upperBound inclusive
+ */
+export const randomInteger = (lowerBound: number, upperBound: number) => {
+  lowerBound = Math.ceil(lowerBound);
+  upperBound = Math.floor(upperBound);
+  return Math.floor(Math.random() * (upperBound - lowerBound) + lowerBound);
+};
+
+/**
+ * Returns random array element
+ */
+export const randomPick = <T>(array: T[]) => {
+  return array[Math.floor(Math.random() * array.length)];
+};
+
+/**
+ * Return 1 with probability P percent; otherwise 0
+ */
+export const randomProb = (probability: number) => {
+  const normalized = clamp(probability, 0, 100) / 100;
+  return Math.random() <= normalized;
+};

package/src/common/react.ts

@@ -0,0 +1,65 @@
+/**
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+/**
+ * Helper for conditionally adding/removing classes in React
+ */
+export const classes = (classNames: (string | BooleanLike)[]) => {
+  let className = '';
+  for (let i = 0; i < classNames.length; i++) {
+    const part = classNames[i];
+    if (typeof part === 'string') {
+      className += part + ' ';
+    }
+  }
+  return className;
+};
+
+/**
+ * Normalizes children prop, so that it is always an array of VDom
+ * elements.
+ */
+export const normalizeChildren = <T>(children: T | T[]) => {
+  if (Array.isArray(children)) {
+    return children.flat().filter((value) => value) as T[];
+  }
+  if (typeof children === 'object') {
+    return [children];
+  }
+  return [];
+};
+
+/**
+ * Shallowly checks if two objects are different.
+ * Credit: https://github.com/developit/preact-compat
+ */
+export const shallowDiffers = (a: object, b: object) => {
+  let i;
+  for (i in a) {
+    if (!(i in b)) {
+      return true;
+    }
+  }
+  for (i in b) {
+    if (a[i] !== b[i]) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/**
+ * A common case in tgui, when you pass a value conditionally, these are
+ * the types that can fall through the condition.
+ */
+export type BooleanLike = number | boolean | null | undefined;
+
+/**
+ * A helper to determine whether the object is renderable by React.
+ */
+export const canRender = (value: unknown) => {
+  return value !== undefined && value !== null && typeof value !== 'boolean';
+};