tgui-core 1.0.0

package/src/events.ts

@@ -0,0 +1,237 @@
+/**
+ * Normalized browser focus events and BYOND-specific focus helpers.
+ *
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+import { EventEmitter } from './common/events';
+import {
+  KEY_ALT,
+  KEY_CTRL,
+  KEY_F1,
+  KEY_F12,
+  KEY_SHIFT,
+} from './common/keycodes';
+
+export const globalEvents = new EventEmitter();
+let ignoreWindowFocus = false;
+
+export const setupGlobalEvents = (
+  options: { ignoreWindowFocus?: boolean } = {}
+): void => {
+  ignoreWindowFocus = !!options.ignoreWindowFocus;
+};
+
+// Window focus
+// --------------------------------------------------------
+
+let windowFocusTimeout: ReturnType<typeof setTimeout> | null;
+let windowFocused = true;
+
+// Pretend to always be in focus.
+const setWindowFocus = (value: boolean, delayed?: boolean) => {
+  if (ignoreWindowFocus) {
+    windowFocused = true;
+    return;
+  }
+  if (windowFocusTimeout) {
+    clearTimeout(windowFocusTimeout);
+    windowFocusTimeout = null;
+  }
+  if (delayed) {
+    windowFocusTimeout = setTimeout(() => setWindowFocus(value));
+    return;
+  }
+  if (windowFocused !== value) {
+    windowFocused = value;
+    globalEvents.emit(value ? 'window-focus' : 'window-blur');
+    globalEvents.emit('window-focus-change', value);
+  }
+};
+
+// Focus stealing
+// --------------------------------------------------------
+
+let focusStolenBy: HTMLElement | null = null;
+
+export const canStealFocus = (node: HTMLElement) => {
+  const tag = String(node.tagName).toLowerCase();
+  return tag === 'input' || tag === 'textarea';
+};
+
+const stealFocus = (node: HTMLElement) => {
+  releaseStolenFocus();
+  focusStolenBy = node;
+  focusStolenBy.addEventListener('blur', releaseStolenFocus);
+};
+
+const releaseStolenFocus = () => {
+  if (focusStolenBy) {
+    focusStolenBy.removeEventListener('blur', releaseStolenFocus);
+    focusStolenBy = null;
+  }
+};
+
+// Focus follows the mouse
+// --------------------------------------------------------
+
+let focusedNode: HTMLElement | null = null;
+let lastVisitedNode: HTMLElement | null = null;
+const trackedNodes: HTMLElement[] = [];
+
+export const addScrollableNode = (node: HTMLElement) => {
+  trackedNodes.push(node);
+};
+
+export const removeScrollableNode = (node: HTMLElement) => {
+  const index = trackedNodes.indexOf(node);
+  if (index >= 0) {
+    trackedNodes.splice(index, 1);
+  }
+};
+
+const focusNearestTrackedParent = (node: HTMLElement | null) => {
+  if (focusStolenBy || !windowFocused) {
+    return;
+  }
+  const body = document.body;
+  while (node && node !== body) {
+    if (trackedNodes.includes(node)) {
+      // NOTE: Contains is a DOM4 method
+      if (node.contains(focusedNode)) {
+        return;
+      }
+      focusedNode = node;
+      node.focus();
+      return;
+    }
+    node = node.parentElement;
+  }
+};
+
+window.addEventListener('mousemove', (e) => {
+  const node = e.target as HTMLElement;
+  if (node !== lastVisitedNode) {
+    lastVisitedNode = node;
+    focusNearestTrackedParent(node);
+  }
+});
+
+// Focus event hooks
+// --------------------------------------------------------
+
+window.addEventListener('focusin', (e) => {
+  lastVisitedNode = null;
+  focusedNode = e.target as HTMLElement;
+  setWindowFocus(true);
+  if (canStealFocus(e.target as HTMLElement)) {
+    stealFocus(e.target as HTMLElement);
+  }
+});
+
+window.addEventListener('focusout', (e) => {
+  lastVisitedNode = null;
+  setWindowFocus(false, true);
+});
+
+window.addEventListener('blur', (e) => {
+  lastVisitedNode = null;
+  setWindowFocus(false, true);
+});
+
+window.addEventListener('beforeunload', (e) => {
+  setWindowFocus(false);
+});
+
+// Key events
+// --------------------------------------------------------
+
+const keyHeldByCode: Record<number, boolean> = {};
+
+export class KeyEvent {
+  event: KeyboardEvent;
+  type: 'keydown' | 'keyup';
+  code: number;
+  ctrl: boolean;
+  shift: boolean;
+  alt: boolean;
+  repeat: boolean;
+  _str?: string;
+
+  constructor(e: KeyboardEvent, type: 'keydown' | 'keyup', repeat?: boolean) {
+    this.event = e;
+    this.type = type;
+    this.code = e.keyCode;
+    this.ctrl = e.ctrlKey;
+    this.shift = e.shiftKey;
+    this.alt = e.altKey;
+    this.repeat = !!repeat;
+  }
+
+  hasModifierKeys() {
+    return this.ctrl || this.alt || this.shift;
+  }
+
+  isModifierKey() {
+    return (
+      this.code === KEY_CTRL || this.code === KEY_SHIFT || this.code === KEY_ALT
+    );
+  }
+
+  isDown() {
+    return this.type === 'keydown';
+  }
+
+  isUp() {
+    return this.type === 'keyup';
+  }
+
+  toString() {
+    if (this._str) {
+      return this._str;
+    }
+    this._str = '';
+    if (this.ctrl) {
+      this._str += 'Ctrl+';
+    }
+    if (this.alt) {
+      this._str += 'Alt+';
+    }
+    if (this.shift) {
+      this._str += 'Shift+';
+    }
+    if (this.code >= 48 && this.code <= 90) {
+      this._str += String.fromCharCode(this.code);
+    } else if (this.code >= KEY_F1 && this.code <= KEY_F12) {
+      this._str += 'F' + (this.code - 111);
+    } else {
+      this._str += '[' + this.code + ']';
+    }
+    return this._str;
+  }
+}
+
+// IE8: Keydown event is only available on document.
+document.addEventListener('keydown', (e) => {
+  if (canStealFocus(e.target as HTMLElement)) {
+    return;
+  }
+  const code = e.keyCode;
+  const key = new KeyEvent(e, 'keydown', keyHeldByCode[code]);
+  globalEvents.emit('keydown', key);
+  globalEvents.emit('key', key);
+  keyHeldByCode[code] = true;
+});
+
+document.addEventListener('keyup', (e) => {
+  if (canStealFocus(e.target as HTMLElement)) {
+    return;
+  }
+  const code = e.keyCode;
+  const key = new KeyEvent(e, 'keyup');
+  globalEvents.emit('keyup', key);
+  globalEvents.emit('key', key);
+  keyHeldByCode[code] = false;
+});

package/src/focus.ts

@@ -0,0 +1,25 @@
+/**
+ * Various focus helpers.
+ *
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+/**
+ * Moves focus to the BYOND map window.
+ */
+export const focusMap = () => {
+  Byond.winset('mapwindow.map', {
+    focus: true,
+  });
+};
+
+/**
+ * Moves focus to the browser window.
+ */
+export const focusWindow = () => {
+  Byond.winset(Byond.windowId, {
+    focus: true,
+  });
+};

package/src/format.ts

@@ -0,0 +1,173 @@
+/**
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+const SI_SYMBOLS = [
+  'f', // femto
+  'p', // pico
+  'n', // nano
+  'μ', // micro
+  'm', // milli
+  // NOTE: This is a space for a reason. When we right align si numbers,
+  // in monospace mode, we want to units and numbers stay in their respective
+  // columns. If rendering in HTML mode, this space will collapse into
+  // a single space anyway.
+  ' ', // base
+  'k', // kilo
+  'M', // mega
+  'G', // giga
+  'T', // tera
+  'P', // peta
+  'E', // exa
+  'Z', // zetta
+  'Y', // yotta
+  'R', // ronna
+  'Q', // quecca
+  'F',
+  'N',
+  'H',
+] as const;
+
+const SI_BASE_INDEX = SI_SYMBOLS.indexOf(' ');
+
+// Formats a number to a human readable form, with a custom unit
+export const formatSiUnit = (
+  value: number,
+  minBase1000 = -SI_BASE_INDEX,
+  unit = '',
+): string => {
+  if (!isFinite(value)) {
+    return value.toString();
+  }
+
+  const realBase10 = Math.floor(Math.log10(Math.abs(value)));
+  const base10 = Math.max(minBase1000 * 3, realBase10);
+  const base1000 = Math.floor(base10 / 3);
+  const symbol =
+    SI_SYMBOLS[Math.min(base1000 + SI_BASE_INDEX, SI_SYMBOLS.length - 1)];
+
+  const scaledValue = value / Math.pow(1000, base1000);
+
+  let formattedValue = scaledValue.toFixed(2);
+  if (formattedValue.endsWith('.00')) {
+    formattedValue = formattedValue.slice(0, -3);
+  } else if (formattedValue.endsWith('.0')) {
+    formattedValue = formattedValue.slice(0, -2);
+  }
+
+  return `${formattedValue} ${symbol.trim()}${unit}`.trim();
+};
+
+// Formats a number to a human readable form, with power (W) as the unit
+export const formatPower = (value: number, minBase1000 = 0) => {
+  return formatSiUnit(value, minBase1000, 'W');
+};
+
+export const formatEnergy = (value: number, minBase1000 = 0) => {
+  return formatSiUnit(value, minBase1000, 'J');
+};
+
+// Formats a number as a currency string
+export const formatMoney = (value: number, precision = 0) => {
+  if (!Number.isFinite(value)) {
+    return String(value);
+  }
+
+  // Round the number and make it fixed precision
+  const roundedValue = Number(value.toFixed(precision));
+
+  // Handle the negative sign
+  const isNegative = roundedValue < 0;
+  const absoluteValue = Math.abs(roundedValue);
+
+  // Convert to string and place thousand separators
+  const parts = absoluteValue.toString().split('.');
+  parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, '\u2009'); // Thin space
+
+  const formattedValue = parts.join('.');
+
+  return isNegative ? `-${formattedValue}` : formattedValue;
+};
+
+// Formats a floating point number as a number on the decibel scale
+export const formatDb = (value: number) => {
+  const db = 20 * Math.log10(value);
+  const sign = db >= 0 ? '+' : '-';
+  let formatted: string | number = Math.abs(db);
+
+  if (formatted === Infinity) {
+    formatted = 'Inf';
+  } else {
+    formatted = formatted.toFixed(2);
+  }
+
+  return `${sign}${formatted} dB`;
+};
+
+const SI_BASE_TEN_UNITS = [
+  '',
+  '· 10³', // kilo
+  '· 10⁶', // mega
+  '· 10⁹', // giga
+  '· 10¹²', // tera
+  '· 10¹⁵', // peta
+  '· 10¹⁸', // exa
+  '· 10²¹', // zetta
+  '· 10²⁴', // yotta
+  '· 10²⁷', // ronna
+  '· 10³⁰', // quecca
+  '· 10³³',
+  '· 10³⁶',
+  '· 10³⁹',
+] as const;
+
+// Converts a number to a string with SI base 10 units
+export const formatSiBaseTenUnit = (
+  value: number,
+  minBase1000 = 0,
+  unit = '',
+): string => {
+  if (!isFinite(value)) {
+    return 'NaN';
+  }
+
+  const realBase10 = Math.floor(Math.log10(value));
+  const base10 = Math.max(minBase1000 * 3, realBase10);
+  const base1000 = Math.floor(base10 / 3);
+  const symbol = SI_BASE_TEN_UNITS[base1000];
+
+  const scaledValue = value / Math.pow(1000, base1000);
+  const precision = Math.max(0, 2 - (base10 % 3));
+  const formattedValue = scaledValue.toFixed(precision);
+
+  return `${formattedValue} ${symbol} ${unit}`.trim();
+};
+
+/**
+ * Formats decisecond count into HH:MM:SS display by default
+ * "short" format does not pad and adds hms suffixes
+ */
+export const formatTime = (
+  val: number,
+  formatType: 'short' | 'default' = 'default',
+): string => {
+  const totalSeconds = Math.floor(val / 10);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  if (formatType === 'short') {
+    const hoursFormatted = hours > 0 ? `${hours}h` : '';
+    const minutesFormatted = minutes > 0 ? `${minutes}m` : '';
+    const secondsFormatted = seconds > 0 ? `${seconds}s` : '';
+    return `${hoursFormatted}${minutesFormatted}${secondsFormatted}`;
+  }
+
+  const hoursPadded = String(hours).padStart(2, '0');
+  const minutesPadded = String(minutes).padStart(2, '0');
+  const secondsPadded = String(seconds).padStart(2, '0');
+
+  return `${hoursPadded}:${minutesPadded}:${secondsPadded}`;
+};

package/src/hotkeys.ts

@@ -0,0 +1,212 @@
+/**
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+import * as keycodes from './common/keycodes';
+
+import { globalEvents, KeyEvent } from './events';
+
+// BYOND macros, in `key: command` format.
+const byondMacros: Record<string, string> = {};
+
+// Default set of acquired keys, which will not be sent to BYOND.
+const hotKeysAcquired = [
+  keycodes.KEY_ESCAPE,
+  keycodes.KEY_ENTER,
+  keycodes.KEY_SPACE,
+  keycodes.KEY_TAB,
+  keycodes.KEY_CTRL,
+  keycodes.KEY_SHIFT,
+  keycodes.KEY_UP,
+  keycodes.KEY_DOWN,
+  keycodes.KEY_LEFT,
+  keycodes.KEY_RIGHT,
+  keycodes.KEY_F5,
+];
+
+// State of passed-through keys.
+const keyState: Record<string, boolean> = {};
+
+// Custom listeners for key events
+const keyListeners: ((key: KeyEvent) => void)[] = [];
+
+/**
+ * Converts a browser keycode to BYOND keycode.
+ */
+const keyCodeToByond = (keyCode: number) => {
+  if (keyCode === 16) return 'Shift';
+  if (keyCode === 17) return 'Ctrl';
+  if (keyCode === 18) return 'Alt';
+  if (keyCode === 33) return 'Northeast';
+  if (keyCode === 34) return 'Southeast';
+  if (keyCode === 35) return 'Southwest';
+  if (keyCode === 36) return 'Northwest';
+  if (keyCode === 37) return 'West';
+  if (keyCode === 38) return 'North';
+  if (keyCode === 39) return 'East';
+  if (keyCode === 40) return 'South';
+  if (keyCode === 45) return 'Insert';
+  if (keyCode === 46) return 'Delete';
+
+  if ((keyCode >= 48 && keyCode <= 57) || (keyCode >= 65 && keyCode <= 90)) {
+    return String.fromCharCode(keyCode);
+  }
+  if (keyCode >= 96 && keyCode <= 105) {
+    return 'Numpad' + (keyCode - 96);
+  }
+  if (keyCode >= 112 && keyCode <= 123) {
+    return 'F' + (keyCode - 111);
+  }
+  if (keyCode === 188) return ',';
+  if (keyCode === 189) return '-';
+  if (keyCode === 190) return '.';
+};
+
+/**
+ * Keyboard passthrough logic. This allows you to keep doing things
+ * in game while the browser window is focused.
+ */
+const handlePassthrough = (key: KeyEvent) => {
+  const keyString = String(key);
+  // In addition to F5, support reloading with Ctrl+R and Ctrl+F5
+  if (keyString === 'Ctrl+F5' || keyString === 'Ctrl+R') {
+    location.reload();
+    return;
+  }
+  // Prevent passthrough on Ctrl+F
+  if (keyString === 'Ctrl+F') {
+    return;
+  }
+  // NOTE: Alt modifier is pretty bad and sticky in IE11.
+
+  if (
+    key.event.defaultPrevented ||
+    key.isModifierKey() ||
+    hotKeysAcquired.includes(key.code)
+  ) {
+    return;
+  }
+  const byondKeyCode = keyCodeToByond(key.code);
+  if (!byondKeyCode) {
+    return;
+  }
+  // Macro
+  const macro = byondMacros[byondKeyCode];
+  if (macro) {
+    return Byond.command(macro);
+  }
+  // KeyDown
+  if (key.isDown() && !keyState[byondKeyCode]) {
+    keyState[byondKeyCode] = true;
+    const command = `KeyDown "${byondKeyCode}"`;
+    return Byond.command(command);
+  }
+  // KeyUp
+  if (key.isUp() && keyState[byondKeyCode]) {
+    keyState[byondKeyCode] = false;
+    const command = `KeyUp "${byondKeyCode}"`;
+    return Byond.command(command);
+  }
+};
+
+/**
+ * Acquires a lock on the hotkey, which prevents it from being
+ * passed through to BYOND.
+ */
+export const acquireHotKey = (keyCode: number) => {
+  hotKeysAcquired.push(keyCode);
+};
+
+/**
+ * Makes the hotkey available to BYOND again.
+ */
+export const releaseHotKey = (keyCode: number) => {
+  const index = hotKeysAcquired.indexOf(keyCode);
+  if (index >= 0) {
+    hotKeysAcquired.splice(index, 1);
+  }
+};
+
+export const releaseHeldKeys = () => {
+  for (let byondKeyCode of Object.keys(keyState)) {
+    if (keyState[byondKeyCode]) {
+      keyState[byondKeyCode] = false;
+      Byond.command(`KeyUp "${byondKeyCode}"`);
+    }
+  }
+};
+
+type ByondSkinMacro = {
+  command: string;
+  name: string;
+};
+
+export const setupHotKeys = () => {
+  // Read macros
+  Byond.winget('default.*').then((data: Record<string, string>) => {
+    // Group each macro by ref
+    const groupedByRef: Record<string, ByondSkinMacro> = {};
+    for (let key of Object.keys(data)) {
+      const keyPath = key.split('.');
+      const ref = keyPath[1];
+      const prop = keyPath[2];
+      if (ref && prop) {
+        // This piece of code imperatively adds each property to a
+        // ByondSkinMacro object in the order we meet it, which is hard
+        // to express safely in typescript.
+        if (!groupedByRef[ref]) {
+          groupedByRef[ref] = {} as any;
+        }
+        groupedByRef[ref][prop] = data[key];
+      }
+    }
+    // Insert macros
+    const escapedQuotRegex = /\\"/g;
+
+    const unescape = (str: string) =>
+      str.substring(1, str.length - 1).replace(escapedQuotRegex, '"');
+    for (let ref of Object.keys(groupedByRef)) {
+      const macro = groupedByRef[ref];
+      const byondKeyName = unescape(macro.name);
+      byondMacros[byondKeyName] = unescape(macro.command);
+    }
+  });
+  // Setup event handlers
+  globalEvents.on('window-blur', () => {
+    releaseHeldKeys();
+  });
+  globalEvents.on('key', (key: KeyEvent) => {
+    for (const keyListener of keyListeners) {
+      keyListener(key);
+    }
+    handlePassthrough(key);
+  });
+};
+
+/**
+ * Registers for any key events, such as key down or key up.
+ * This should be preferred over directly connecting to keydown/keyup
+ * as it lets tgui prevent the key from reaching BYOND.
+ *
+ * If using in a component, prefer KeyListener, which automatically handles
+ * stopping listening when unmounting.
+ *
+ * @param callback The function to call whenever a key event occurs
+ * @returns A callback to stop listening
+ */
+export const listenForKeyEvents = (callback: (key: KeyEvent) => void) => {
+  keyListeners.push(callback);
+
+  let removed = false;
+
+  return () => {
+    if (removed) {
+      return;
+    }
+
+    removed = true;
+    keyListeners.splice(keyListeners.indexOf(callback), 1);
+  };
+};

package/src/http.ts

@@ -0,0 +1,16 @@
+/**
+ * An equivalent to `fetch`, except will automatically retry.
+ */
+export const fetchRetry = (
+  url: string,
+  options?: RequestInit,
+  retryTimer: number = 1000,
+): Promise<Response> => {
+  return fetch(url, options).catch(() => {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        fetchRetry(url, options, retryTimer).then(resolve);
+      }, retryTimer);
+    });
+  });
+};