tgui-core 1.1.7 → 1.1.9

package/lib/common/storage.ts

@@ -0,0 +1,207 @@
+/**
+ * Browser-agnostic abstraction of key-value web storage.
+ *
+ * @file
+ * @copyright 2020 Aleksej Komarov
+ * @license MIT
+ */
+
+export const IMPL_MEMORY = 0;
+export const IMPL_LOCAL_STORAGE = 1;
+export const IMPL_INDEXED_DB = 2;
+
+const INDEXED_DB_VERSION = 1;
+const INDEXED_DB_NAME = 'tgui';
+const INDEXED_DB_STORE_NAME = 'storage-v1';
+
+const READ_ONLY = 'readonly';
+const READ_WRITE = 'readwrite';
+
+const testGeneric = (testFn) => () => {
+  try {
+    return Boolean(testFn());
+  } catch {
+    return false;
+  }
+};
+
+// Localstorage can sometimes throw an error, even if DOM storage is not
+// disabled in IE11 settings.
+// See: https://superuser.com/questions/1080011
+
+const testLocalStorage = testGeneric(
+  () => window.localStorage && window.localStorage.getItem,
+);
+
+const testIndexedDb = testGeneric(
+  () =>
+    (window.indexedDB || window.msIndexedDB) &&
+    (window.IDBTransaction || window.msIDBTransaction),
+);
+
+class MemoryBackend {
+  impl = IMPL_MEMORY;
+  store: Record<string, any> = {};
+
+  constructor() {
+    this.impl = IMPL_MEMORY;
+    this.store = {};
+  }
+
+  get(key) {
+    return this.store[key];
+  }
+
+  set(key, value) {
+    this.store[key] = value;
+  }
+
+  remove(key) {
+    this.store[key] = undefined;
+  }
+
+  clear() {
+    this.store = {};
+  }
+}
+
+class LocalStorageBackend {
+  impl = IMPL_LOCAL_STORAGE;
+
+  constructor() {
+    this.impl = IMPL_LOCAL_STORAGE;
+  }
+
+  get(key) {
+    const value = localStorage.getItem(key);
+    if (typeof value === 'string') {
+      return JSON.parse(value);
+    }
+  }
+
+  set(key, value) {
+    localStorage.setItem(key, JSON.stringify(value));
+  }
+
+  remove(key) {
+    localStorage.removeItem(key);
+  }
+
+  clear() {
+    localStorage.clear();
+  }
+}
+
+class IndexedDbBackend {
+  impl = IMPL_INDEXED_DB;
+  dbPromise: Promise<IDBDatabase>;
+
+  constructor() {
+    this.impl = IMPL_INDEXED_DB;
+    this.dbPromise = new Promise((resolve, reject) => {
+      const indexedDB = window.indexedDB || window.msIndexedDB;
+      const req = indexedDB.open(INDEXED_DB_NAME, INDEXED_DB_VERSION);
+      req.onupgradeneeded = () => {
+        try {
+          req.result.createObjectStore(INDEXED_DB_STORE_NAME);
+        } catch (err) {
+          reject(new Error('Failed to upgrade IDB: ' + req.error));
+        }
+      };
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => {
+        reject(new Error('Failed to open IDB: ' + req.error));
+      };
+    });
+  }
+
+  getStore(mode) {
+    return this.dbPromise.then((db) =>
+      db
+        .transaction(INDEXED_DB_STORE_NAME, mode)
+        .objectStore(INDEXED_DB_STORE_NAME),
+    );
+  }
+
+  async get(key) {
+    const store = await this.getStore(READ_ONLY);
+    return new Promise((resolve, reject) => {
+      const req = store.get(key);
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  async set(key, value) {
+    // The reason we don't _save_ null is because IE 10 does
+    // not support saving the `null` type in IndexedDB. How
+    // ironic, given the bug below!
+    // See: https://github.com/mozilla/localForage/issues/161
+    if (value === null) {
+      value = undefined;
+    }
+    // NOTE: We deliberately make this operation transactionless
+    const store = await this.getStore(READ_WRITE);
+    store.put(value, key);
+  }
+
+  async remove(key) {
+    // NOTE: We deliberately make this operation transactionless
+    const store = await this.getStore(READ_WRITE);
+    store.delete(key);
+  }
+
+  async clear() {
+    // NOTE: We deliberately make this operation transactionless
+    const store = await this.getStore(READ_WRITE);
+    store.clear();
+  }
+}
+
+/**
+ * Web Storage Proxy object, which selects the best backend available
+ * depending on the environment.
+ */
+class StorageProxy {
+  backendPromise: Promise<any>;
+
+  constructor() {
+    this.backendPromise = (async () => {
+      if (testIndexedDb()) {
+        try {
+          const backend = new IndexedDbBackend();
+          await backend.dbPromise;
+          return backend;
+        } catch {
+          // Ignore errors
+        }
+      }
+      if (testLocalStorage()) {
+        return new LocalStorageBackend();
+      }
+      return new MemoryBackend();
+    })();
+  }
+
+  async get(key) {
+    const backend = await this.backendPromise;
+    return backend.get(key);
+  }
+
+  async set(key, value) {
+    const backend = await this.backendPromise;
+    return backend.set(key, value);
+  }
+
+  async remove(key) {
+    const backend = await this.backendPromise;
+    return backend.remove(key);
+  }
+
+  async clear() {
+    const backend = await this.backendPromise;
+    return backend.clear();
+  }
+}
+
+export const storage = new StorageProxy();

package/lib/common/string.ts

@@ -0,0 +1,169 @@
+/**
+ * Creates a search terms matcher. Returns true if given string matches the search text.
+ *
+ * @example
+ * ```tsx
+ * type Thing = { id: string; name: string };
+ *
+ * const objects = [
+ *   { id: '123', name: 'Test' },
+ *   { id: '456', name: 'Test' },
+ * ];
+ *
+ * const search = createSearch('123', (obj: Thing) => obj.id);
+ *
+ * objects.filter(search); // returns [{ id: '123', name: 'Test' }]
+ * ```
+ */
+export function createSearch<TObj>(
+  searchText: string,
+  stringifier = (obj: TObj) => JSON.stringify(obj),
+): (obj: TObj) => boolean {
+  const preparedSearchText = searchText.toLowerCase().trim();
+
+  return (obj) => {
+    if (!preparedSearchText) {
+      return true;
+    }
+    const str = stringifier(obj);
+    if (!str) {
+      return false;
+    }
+    return str.toLowerCase().includes(preparedSearchText);
+  };
+}
+
+/**
+ * Capitalizes a word and lowercases the rest.
+ *
+ * @example
+ * ```tsx
+ * capitalize('heLLo') // Hello
+ * ```
+ */
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+}
+
+/**
+ * Similar to capitalize, this takes a string and replaces all first letters
+ * of any words.
+ *
+ * @example
+ * ```tsx
+ * capitalizeAll('heLLo woRLd') // 'HeLLo WoRLd'
+ * ```
+ */
+export function capitalizeAll(str: string): string {
+  return str.replace(/(^\w{1})|(\s+\w{1})/g, (letter) => letter.toUpperCase());
+}
+
+/**
+ * Capitalizes only the first letter of the str, leaving others untouched.
+ *
+ * @example
+ * ```tsx
+ * capitalizeFirst('heLLo woRLd') // 'HeLLo woRLd'
+ * ```
+ */
+export function capitalizeFirst(str: string): string {
+  return str.replace(/^\w/, (letter) => letter.toUpperCase());
+}
+
+const WORDS_UPPER = ['Id', 'Tv'] as const;
+
+const WORDS_LOWER = [
+  'A',
+  'An',
+  'And',
+  'As',
+  'At',
+  'But',
+  'By',
+  'For',
+  'For',
+  'From',
+  'In',
+  'Into',
+  'Near',
+  'Nor',
+  'Of',
+  'On',
+  'Onto',
+  'Or',
+  'The',
+  'To',
+  'With',
+] as const;
+
+/**
+ * Converts a string to title case.
+ *
+ * @example
+ * ```tsx
+ * toTitleCase('a tale of two cities') // 'A Tale of Two Cities'
+ * ```
+ */
+export function toTitleCase(str: string): string {
+  if (!str) return str;
+
+  let currentStr = str.replace(/([^\W_]+[^\s-]*) */g, (str) => {
+    return capitalize(str);
+  });
+
+  for (const word of WORDS_LOWER) {
+    const regex = new RegExp('\\s' + word + '\\s', 'g');
+    currentStr = currentStr.replace(regex, (str) => str.toLowerCase());
+  }
+
+  for (const word of WORDS_UPPER) {
+    const regex = new RegExp('\\b' + word + '\\b', 'g');
+    currentStr = currentStr.replace(regex, (str) => str.toLowerCase());
+  }
+
+  return currentStr;
+}
+
+const TRANSLATIONS = {
+  amp: '&',
+  apos: "'",
+  gt: '>',
+  lt: '<',
+  nbsp: ' ',
+  quot: '"',
+} as const;
+
+/**
+ * Decodes HTML entities and removes unnecessary HTML tags.
+ *
+ * @example
+ * ```tsx
+ * decodeHtmlEntities('&amp;') // returns '&'
+ * decodeHtmlEntities('&lt;') // returns '<'
+ * ```
+ */
+export function decodeHtmlEntities(str: string): string {
+  if (!str) return str;
+
+  return (
+    str
+      // Newline tags
+      .replace(/<br>/gi, '\n')
+      .replace(/<\/?[a-z0-9-_]+[^>]*>/gi, '')
+      // Basic entities
+      .replace(
+        /&(nbsp|amp|quot|lt|gt|apos);/g,
+        (_match, entity) => TRANSLATIONS[entity],
+      )
+      // Decimal entities
+      .replace(/&#?([0-9]+);/gi, (_match, numStr) => {
+        const num = parseInt(numStr, 10);
+        return String.fromCharCode(num);
+      })
+      // Hex entities
+      .replace(/&#x?([0-9a-f]+);/gi, (_match, numStr) => {
+        const num = parseInt(numStr, 16);
+        return String.fromCharCode(num);
+      })
+  );
+}

package/lib/common/timer.ts

@@ -0,0 +1,63 @@
+/**
+ * Returns a function, that, as long as it continues to be invoked, will
+ * not be triggered. The function will be called after it stops being
+ * called for N milliseconds. If `immediate` is passed, trigger the
+ * function on the leading edge, instead of the trailing.
+ */
+export function debounce<F extends (...args: any[]) => any>(
+  fn: F,
+  time: number,
+  immediate = false,
+): (...args: Parameters<F>) => void {
+  let timeout: ReturnType<typeof setTimeout> | null;
+  return (...args: Parameters<F>) => {
+    function later() {
+      timeout = null;
+      if (!immediate) {
+        fn(...args);
+      }
+    }
+    const callNow = immediate && !timeout;
+    clearTimeout(timeout!);
+    timeout = setTimeout(later, time);
+    if (callNow) {
+      fn(...args);
+    }
+  };
+}
+
+/**
+ * Returns a function, that, when invoked, will only be triggered at most once
+ * during a given window of time.
+ */
+export function throttle<F extends (...args: any[]) => any>(
+  fn: F,
+  time: number,
+): (...args: Parameters<F>) => void {
+  let previouslyRun: number | null,
+    queuedToRun: ReturnType<typeof setTimeout> | null;
+  return function invokeFn(...args: Parameters<F>) {
+    const now = Date.now();
+    if (queuedToRun) {
+      clearTimeout(queuedToRun);
+    }
+    if (!previouslyRun || now - previouslyRun >= time) {
+      fn(...args);
+      previouslyRun = now;
+    } else {
+      queuedToRun = setTimeout(
+        () => invokeFn(...args),
+        time - (now - (previouslyRun ?? 0)),
+      );
+    }
+  };
+}
+
+/**
+ * Suspends an asynchronous function for N milliseconds.
+ *
+ * @param {number} time
+ */
+export function sleep(time: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, time));
+}

package/lib/common/type-utils.ts

@@ -0,0 +1,41 @@
+/**
+ * Helps visualize highly complex ui data on the fly.
+ * @example
+ * ```tsx
+ * const { data } = useBackend<CargoData>();
+ * logger.log(getShallowTypes(data));
+ * ```
+ */
+export function getShallowTypes(
+  data: Record<string, any>,
+): Record<string, any> {
+  const output = {};
+
+  for (const key in data) {
+    if (Array.isArray(data[key])) {
+      const arr: any[] = data[key];
+
+      // Return the first array item if it exists
+      if (data[key].length > 0) {
+        output[key] = arr[0];
+        continue;
+      }
+
+      output[key] = 'emptyarray';
+    } else if (typeof data[key] === 'object' && data[key] !== null) {
+      // Please inspect it further and make a new type for it
+      output[key] = 'object (inspect) || Record<string, any>';
+    } else if (typeof data[key] === 'number') {
+      const num = Number(data[key]);
+
+      // 0 and 1 could be booleans from byond
+      if (num === 1 || num === 0) {
+        output[key] = `${num}, BooleanLike?`;
+        continue;
+      }
+      output[key] = data[key];
+    }
+  }
+
+  return output;
+}

package/lib/common/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns the arguments of a function F as an array.
+ */
+export type ArgumentsOf<F extends Fn> = F extends (...args: infer A) => unknown
+  ? A
+  : never;
+
+/**
+ * A function. Use this instead of `Function` to avoid issues with
+ * type inference.
+ */
+export type Fn = (...args: any[]) => void;

package/lib/common/uuid.ts

@@ -0,0 +1,18 @@
+/**
+ * Creates a UUID v4 string
+ *
+ * @example
+ * ```tsx
+ * createUuid(); // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+ * ```
+ */
+export function createUuid(): string {
+  let d = new Date().getTime();
+
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (d + Math.random() * 16) % 16 | 0;
+    d = Math.floor(d / 16);
+
+    return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+  });
+}

package/lib/components/AnimatedNumber.tsx

@@ -0,0 +1,180 @@
+import { Component, createRef } from 'react';
+
+import { clamp, toFixed } from '../common/math';
+
+type Props = {
+  /**
+   * If provided, a function that formats the inner string. By default,
+   * attempts to match the numeric precision of `value`.
+   */
+  format?: (value: number) => string;
+
+  /**
+   * If provided, the initial value displayed. By default, the same as `value`.
+   * If `initial` and `value` are different, the component immediately starts
+   * animating.
+   */
+  initial?: number;
+
+  /**
+   * The target value to approach.
+   */
+  value: number;
+};
+
+function isSafeNumber(value: number): boolean {
+  return (
+    typeof value === 'number' && Number.isFinite(value) && !Number.isNaN(value)
+  );
+}
+
+/**
+ * Animated numbers are animated at roughly 60 frames per second.
+ */
+const SIXTY_HZ = 1_000.0 / 60.0;
+
+/**
+ * The exponential moving average coefficient. Larger values result in a faster
+ * convergence.
+ */
+const Q = 0.8333;
+
+/**
+ * A small number.
+ */
+const EPSILON = 10e-4;
+
+/**
+ * An animated number label. Shows a number, formatted with an optionally
+ * provided function, and animates it towards its target value.
+ */
+export class AnimatedNumber extends Component<Props> {
+  /**
+   * The inner `<span/>` being updated sixty times per second.
+   */
+  ref = createRef<HTMLSpanElement>();
+
+  /**
+   * The interval being used to update the inner span.
+   */
+  interval?: NodeJS.Timeout;
+
+  /**
+   * The current value. This values approaches the target value.
+   */
+  currentValue: number = 0;
+
+  constructor(props: Props) {
+    super(props);
+
+    const { initial, value } = props;
+
+    if (initial !== undefined && isSafeNumber(initial)) {
+      this.currentValue = initial;
+    } else if (isSafeNumber(value)) {
+      this.currentValue = value;
+    }
+  }
+
+  componentDidMount() {
+    if (this.currentValue !== this.props.value) {
+      this.startTicking();
+    }
+  }
+
+  componentWillUnmount() {
+    // Stop animating when the component is unmounted.
+    this.stopTicking();
+  }
+
+  shouldComponentUpdate(newProps: Props) {
+    if (newProps.value !== this.props.value) {
+      // The target value has been adjusted; start animating if we aren't
+      // already.
+      this.startTicking();
+    }
+
+    return false;
+  }
+
+  /**
+   * Starts animating the inner span. If the inner span is already animating,
+   * this is a no-op.
+   */
+  startTicking() {
+    if (this.interval !== undefined) {
+      // We're already ticking; do nothing.
+      return;
+    }
+
+    this.interval = setInterval(() => this.tick(), SIXTY_HZ);
+  }
+
+  /**
+   * Stops animating the inner span.
+   */
+  stopTicking() {
+    if (this.interval === undefined) {
+      // We're not ticking; do nothing.
+      return;
+    }
+
+    clearInterval(this.interval);
+
+    this.interval = undefined;
+  }
+
+  /**
+   * Steps forward one frame.
+   */
+  tick() {
+    const { currentValue } = this;
+    const { value } = this.props;
+
+    if (isSafeNumber(value)) {
+      // Converge towards the value.
+      this.currentValue = currentValue * Q + value * (1 - Q);
+    } else {
+      // If the value is unsafe, we're never going to converge, so stop ticking.
+      this.stopTicking();
+    }
+
+    if (
+      Math.abs(value - this.currentValue) < Math.max(EPSILON, EPSILON * value)
+    ) {
+      // We're about as close as we're going to get--snap to the value and
+      // stop ticking.
+      this.currentValue = value;
+      this.stopTicking();
+    }
+
+    if (this.ref.current) {
+      this.ref.current.textContent = this.getText();
+    }
+  }
+
+  /**
+   * Gets the inner text of the span.
+   */
+  getText() {
+    const { props, currentValue } = this;
+    const { format, value } = props;
+
+    if (!isSafeNumber(value)) {
+      return String(value);
+    }
+
+    if (format) {
+      return format(this.currentValue);
+    }
+
+    const fraction = String(value).split('.')[1];
+    const precision = fraction ? fraction.length : 0;
+
+    return toFixed(currentValue, clamp(precision, 0, 8));
+  }
+
+  render() {
+    return <span ref={this.ref}>{this.getText()}</span>;
+  }
+}

package/lib/components/Autofocus.tsx

@@ -0,0 +1,23 @@
+import { PropsWithChildren, useEffect, useRef } from 'react';
+
+/** Used to force the window to steal focus on load. Children optional */
+export function Autofocus(props: PropsWithChildren) {
+  const { children } = props;
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      ref.current?.focus();
+    }, 1);
+
+    return () => {
+      clearTimeout(timer);
+    };
+  }, []);
+
+  return (
+    <div ref={ref} tabIndex={-1}>
+      {children}
+    </div>
+  );
+}