bc-deeplib 1.1.2 → 1.1.3

package/dist/deeplib.js

@@ -958,20 +958,34 @@ var GUI = class _GUI extends BaseModule {
   static {
     __name(this, "GUI");
   }
+  /** The singleton instance of the GUI controller. */
   static instance = null;
+  /** All subscreens managed by this GUI, including the main menu and module settings screens. */
   _subscreens;
+  /** The mod's main menu screen. */
   _mainMenu;
+  /** The currently active subscreen, or `null` if none is active. */
   _currentSubscreen = null;
+  /** Options defining how the mod's settings button is displayed and behaves. */
   _modButtonOptions;
+  /** Returns all registered subscreens. */
   get subscreens() {
     return this._subscreens;
   }
+  /** Returns the main menu subscreen instance. */
   get mainMenu() {
     return this._mainMenu;
   }
+  /** Returns the currently active subscreen. */
   get currentSubscreen() {
     return this._currentSubscreen;
   }
+  /**
+   * Sets the current subscreen.
+   * Accepts either a `BaseSubscreen` instance or the `name` of a subscreen.
+   *
+   * @throws If a string is provided but no subscreen with that name exists.
+   */
   set currentSubscreen(subscreen) {
     if (this._currentSubscreen) {
       this._currentSubscreen.unload();
@@ -988,7 +1002,11 @@ var GUI = class _GUI extends BaseModule {
       this._currentSubscreen.resize(true);
     }
   }
-  /** Creates the GUI instance and initializes the main menu. */
+  /** 
+   * Creates the GUI instance and initializes the main menu. 
+   * 
+   * @throws If another `GUI` instance already exists.
+   */
   constructor(modButtonOptions) {
     super();
     if (_GUI.instance) {
@@ -1002,9 +1020,13 @@ var GUI = class _GUI extends BaseModule {
     this._modButtonOptions = modButtonOptions;
     _GUI.instance = this;
   }
-  get defaultSettings() {
-    return null;
-  }
+  /**
+   * Loads the GUI and registers the mod's settings button in the extensions menu.
+   *
+   * - Creates subscreens for each module's settings screen.
+   * - Registers lifecycle callbacks for subscreens events.
+   * - Sets up the main menu and its subscreens.
+   */
   load() {
     for (const module of modules()) {
       if (!module.settingsScreen) continue;
@@ -1015,36 +1037,34 @@ var GUI = class _GUI extends BaseModule {
       Identifier: this._modButtonOptions.Identifier,
       ButtonText: this._modButtonOptions.ButtonText,
       Image: this._modButtonOptions.Image,
-      load: this._modButtonOptions.load || (() => {
+      load: /* @__PURE__ */ __name(() => {
         setSubscreen(new MainMenu(this));
-      }),
-      run: this._modButtonOptions.run || (() => {
+      }, "load"),
+      run: /* @__PURE__ */ __name(() => {
         if (this._currentSubscreen) {
-          MainCanvas.textAlign = "left";
           this._currentSubscreen.run();
-          MainCanvas.textAlign = "center";
           const newCanvasPosition = [MainCanvas.canvas.offsetLeft, MainCanvas.canvas.offsetTop, MainCanvas.canvas.clientWidth, MainCanvas.canvas.clientHeight];
           if (!CommonArraysEqual(newCanvasPosition, DrawCanvasPosition)) {
             DrawCanvasPosition = newCanvasPosition;
             this._currentSubscreen.resize(false);
           }
         }
-      }),
-      click: this._modButtonOptions.click || (() => {
+      }, "run"),
+      click: /* @__PURE__ */ __name(() => {
         if (this._currentSubscreen) {
           this._currentSubscreen.click();
         }
-      }),
-      exit: this._modButtonOptions.exit || (() => {
+      }, "click"),
+      exit: /* @__PURE__ */ __name(() => {
         if (this._currentSubscreen) {
           this._currentSubscreen.exit();
         }
-      }),
-      unload: this._modButtonOptions.unload || (() => {
+      }, "exit"),
+      unload: /* @__PURE__ */ __name(() => {
         if (this._currentSubscreen) {
           this._currentSubscreen.unload();
         }
-      })
+      }, "unload")
     });
   }
 };
@@ -1054,10 +1074,19 @@ var VersionModule = class _VersionModule extends BaseModule {
   static {
     __name(this, "VersionModule");
   }
+  /** Whether the current session is running a new version compared to stored data */
   static isItNewVersion = false;
+  /** The current mod version (retrieved from `ModSdkManager.ModInfo.version`) */
   static Version;
+  /** Message to display when a new version is detected */
   static NewVersionMessage = "";
+  /** List of registered migration handlers, sorted by version */
   static Migrators = [];
+  /**
+   * Initializes the module on load:
+   * - Stores the current mod version.
+   * - Hooks into `ChatRoomSync` to show a "new version" message when applicable.
+   */
   load() {
     _VersionModule.Version = ModSdkManager.ModInfo.version;
     ModSdkManager.prototype.hookFunction(
@@ -1072,6 +1101,14 @@ var VersionModule = class _VersionModule extends BaseModule {
       "VersionModule"
     );
   }
+  /**
+   * Checks if the stored version differs from the current version.
+   * If a new version is detected:
+   * - Flags the session as updated.
+   * - Runs applicable migrations.
+   * - Updates stored version in player data.
+   * - Saves `modStorage`.
+   */
   static checkVersionUpdate() {
     const PreviousVersion = _VersionModule.loadVersion();
     const CurrentVersion = _VersionModule.Version;
@@ -1082,6 +1119,10 @@ var VersionModule = class _VersionModule extends BaseModule {
     }
     modStorage.save();
   }
+  /**
+   * Executes migrations for all registered migrators whose `MigrationVersion`
+   * is newer than the previously stored version.
+   */
   static checkVersionMigration() {
     const PreviousVersion = _VersionModule.loadVersion();
     for (const migrator of _VersionModule.Migrators) {
@@ -1091,16 +1132,27 @@ var VersionModule = class _VersionModule extends BaseModule {
       }
     }
   }
+  /**
+   * Registers a new migrator for handling version-specific changes.
+   * Migrators are sorted by their `MigrationVersion` in ascending order.
+   */
   static registerMigrator(migrator) {
     _VersionModule.Migrators.push(migrator);
     _VersionModule.Migrators.sort((a, b) => a.MigrationVersion.localeCompare(b.MigrationVersion));
   }
+  /** Sets the message that will be displayed when a new version is detected. */
   static setNewVersionMessage(newVersionMessage) {
     _VersionModule.NewVersionMessage = newVersionMessage;
   }
+  /** Sends the currently configured "new version" message to the local player. */
   static sendNewVersionMessage() {
     sendLocalMessage("deeplib-new-version", _VersionModule.NewVersionMessage);
   }
+  /**
+   * Determines if a given `candidate` version is newer than the `current` version.
+   * 
+   * Version strings are expected in `MAJOR.MINOR.PATCH` format.
+   */
   static isNewVersion(current, candidate) {
     if (current !== void 0) {
       const CURRENT_ = current.split("."), CANDIDATE_ = candidate.split(".");
@@ -1116,11 +1168,13 @@ var VersionModule = class _VersionModule extends BaseModule {
     }
     return false;
   }
+  /** Saves the current mod version into persistent player storage. */
   static saveVersion() {
     if (modStorage.playerStorage) {
       Player[ModSdkManager.ModInfo.name].Version = _VersionModule.Version;
     }
   }
+  /** Loads the stored mod version from persistent player storage. */
   static loadVersion() {
     return modStorage.playerStorage?.Version;
   }
@@ -1686,22 +1740,39 @@ var Modal = class _Modal {
   blocker;
   inputEl;
   timeoutId;
+  /** Static modal queue. */
   static queue = [];
+  /** Flag to indicate if a modal is currently being shown. */
   static processing = false;
+  /**
+   * Displays the modal and resolves with the chosen action and input value.
+   */
   show() {
     return _Modal.enqueue(this);
   }
+  /**
+   * Shows a simple alert modal with a single "OK" button.
+   */
   static async alert(msg, timeoutMs) {
     await new _Modal({ prompt: msg, buttons: [{ action: "close", text: "OK" }], timeoutMs }).show();
   }
+  /**
+   * Shows a confirmation modal with "Cancel" and "OK" buttons.
+   * Returns true if "OK" is clicked.
+   */
   static async confirm(msg) {
     const [action] = await new _Modal({ prompt: msg, buttons: [{ text: "Cancel", action: "cancel" }, { text: "OK", action: "ok" }] }).show();
     return action === "ok";
   }
+  /**
+   * Shows a prompt modal with an input field and "Submit"/"Cancel" buttons.
+   * Returns the input value if submitted, otherwise null.
+   */
   static async prompt(msg, defaultValue = "") {
     const [action, value] = await new _Modal({ prompt: msg, timeoutMs: 0, input: { type: "input", defaultValue }, buttons: [{ text: "Cancel", action: "cancel" }, { text: "Submit", action: "submit" }] }).show();
     return action === "submit" ? value : null;
   }
+  /** Creates the input element for the modal, applying configuration and validation. */
   renderInput(cfg) {
     const el = document.createElement(cfg.type);
     el.classList.add("deeplib-modal-input");
@@ -1716,6 +1787,7 @@ var Modal = class _Modal {
     this.inputEl = el;
     return el;
   }
+  /** Creates modal action buttons from configuration. */
   renderButtons() {
     const container = document.createElement("div");
     container.classList.add("deeplib-modal-button-container");
@@ -1731,6 +1803,7 @@ var Modal = class _Modal {
     });
     return container;
   }
+  /** Creates the modal backdrop blocker with optional click-to-close behavior. */
   createBlocker() {
     const blocker = document.createElement("div");
     blocker.classList.add("deeplib-modal-blocker");
@@ -1739,6 +1812,7 @@ var Modal = class _Modal {
       blocker.addEventListener("click", () => this.close("close"));
     return blocker;
   }
+  /** Implements a focus trap to keep keyboard navigation inside the modal. */
   setupFocusTrap() {
     const focusable = 'button, [href], input, textarea, select, [tabindex]:not([tabindex="-1"])';
     const elements = Array.from(this.dialog.querySelectorAll(focusable));
@@ -1770,6 +1844,7 @@ var Modal = class _Modal {
       (this.inputEl || first)?.focus();
     });
   }
+  /** Closes the modal, cleans up DOM, resolves promise, and shows next queued modal. */
   close(action) {
     if (this.timeoutId) clearTimeout(this.timeoutId);
     this.dialog.close();
@@ -1802,7 +1877,6 @@ var Modal = class _Modal {
     }
   }
 };
-window.Modal = Modal;
 
 // src/screens/main_menu.ts
 var MainMenu = class _MainMenu extends BaseSubscreen {
@@ -1994,6 +2068,7 @@ var GuiImportExport = class extends BaseSubscreen {
   resize() {
     super.resize();
   }
+  /** Exports the mod data using the specified method. */
   async dataExport(transferMethod) {
     try {
       const data = LZString.compressToBase64(JSON.stringify(modStorage.playerStorage));
@@ -2009,6 +2084,7 @@ var GuiImportExport = class extends BaseSubscreen {
       deepLibLogger.error(`Data export failed for ${ModSdkManager.ModInfo.name}.`, error);
     }
   }
+  /** Imports mod data using the specified method. */
   async dataImport(transferMethod) {
     try {
       let importedData = "";
@@ -2032,6 +2108,7 @@ var GuiImportExport = class extends BaseSubscreen {
       deepLibLogger.error(`Data import failed for ${ModSdkManager.ModInfo.name}.`, error);
     }
   }
+  /** Saves data to a file using the browser's save dialog. */
   async exportToFile(data, defaultFileName) {
     const CUSTOM_EXTENSION = this.importExportOptions.customFileExtension.startsWith(".") ? this.importExportOptions.customFileExtension : "." + this.importExportOptions.customFileExtension;
     const suggestedName = defaultFileName.endsWith(CUSTOM_EXTENSION) ? defaultFileName : defaultFileName + CUSTOM_EXTENSION;
@@ -2071,6 +2148,7 @@ var GuiImportExport = class extends BaseSubscreen {
       URL.revokeObjectURL(link.href);
     }
   }
+  /** Opens a file picker and reads the selected file's contents, importing the data. */
   async importFromFile() {
     const CUSTOM_EXTENSION = this.importExportOptions.customFileExtension.startsWith(".") ? this.importExportOptions.customFileExtension : "." + this.importExportOptions.customFileExtension;
     async function importFromFileInternal(file) {
@@ -2123,11 +2201,13 @@ var GuiImportExport = class extends BaseSubscreen {
       });
     }
   }
+  /** Copies the given data to the clipboard. */
   async exportToClipboard(data) {
     return navigator.clipboard.writeText(data).catch((error) => {
       throw new Error("Failed to copy data to clipboard." + error);
     });
   }
+  /** Prompts the user to enter data and returns it. */
   async importFromClipboard() {
     return Modal.prompt("Enter data to import").catch((error) => {
       throw new Error("Failed to read data from clipboard." + error);
@@ -2140,7 +2220,9 @@ var ModStorage = class _ModStorage {
   static {
     __name(this, "ModStorage");
   }
+  /** Singleton instance of ModStorage */
   static _instance = null;
+  /** The unique mod identifier used as key prefix in storage */
   modName;
   constructor(modName) {
     if (!_ModStorage._instance) {
@@ -2206,10 +2288,34 @@ var ModStorage = class _ModStorage {
 
 // src/utilities/elements/helpers.ts
 var domUtil = {
+  /**
+   * Automatically sets the position of the element based on the given position.
+   * The position can be either a [x, y] tuple or a function returning such a tuple.
+   * If both x and y are defined, the element's position is updated accordingly.
+   */
   autoSetPosition,
+  /**
+   * Automatically sets the size of the element based on the given size.
+   * The size can be either a [width, height] tuple or a function returning such a tuple.
+   * If both width and height are defined, the element's size is updated accordingly.
+   */
   autoSetSize,
+  /**
+   * Hides the element by setting its CSS display property to 'none'.
+   * If the element cannot be found, the function does nothing.
+   */
   hide,
+  /**
+   * Unhides the element by clearing its CSS display property (sets it to '').
+   * If the element cannot be found, the function does nothing.
+   */
   unhide,
+  /**
+   * Checks if the element has overflow content.
+   * Returns an object indicating if there is any overflow,
+   * and specifically if there is vertical or horizontal overflow.
+   * Returns null if the element is not found.
+   */
   hasOverflow
 };
 function autoSetPosition(_, position) {
@@ -2487,10 +2593,12 @@ var ModSdkManager = class _ModSdkManager {
   static SDK;
   static patchedFunctions = /* @__PURE__ */ new Map();
   static ModInfo;
+  /** Registers a mod with the SDK and stores mod information. */
   constructor(info, options) {
     _ModSdkManager.SDK = bcModSdkRef.registerMod(info, options);
     _ModSdkManager.ModInfo = info;
   }
+  /** Retrieves or initializes patch data for a given target function. */
   initPatchableFunction(target) {
     let result = _ModSdkManager.patchedFunctions.get(target);
     if (!result) {
@@ -2502,6 +2610,11 @@ var ModSdkManager = class _ModSdkManager {
     }
     return result;
   }
+  /**
+   * Hooks a function with a callback at a given priority. 
+   * 
+   * Prevents duplicate hooks.
+   */
   hookFunction(target, priority, hook, module = null) {
     const data = this.initPatchableFunction(target);
     if (data.hooks.some((h) => h.hook === hook)) {
@@ -2517,12 +2630,23 @@ var ModSdkManager = class _ModSdkManager {
     data.hooks.sort((a, b) => b.priority - a.priority);
     return removeCallback;
   }
+  /**
+   * Applies patches to a target function.
+   * 
+   * **This method is DANGEROUS** to use and has high potential to conflict with other mods.
+   */
   patchFunction(target, patches) {
     _ModSdkManager.SDK?.patchFunction(target, patches);
   }
+  /**
+   * Removes all patches from a target function.
+   */
   unpatchFunction(target) {
     _ModSdkManager.SDK?.removePatches(target);
   }
+  /**
+   * Removes all hooks associated with a specific module from a target function.
+   */
   removeHookByModule(target, module) {
     const data = this.initPatchableFunction(target);
     for (let i = data.hooks.length - 1; i >= 0; i--) {
@@ -2533,6 +2657,9 @@ var ModSdkManager = class _ModSdkManager {
     }
     return true;
   }
+  /**
+   * Removes all hooks associated with a specific module across all patched functions.
+   */
   removeAllHooksByModule(module) {
     for (const data of _ModSdkManager.patchedFunctions.values()) {
       for (let i = data.hooks.length - 1; i >= 0; i--) {
@@ -2548,6 +2675,10 @@ var ModSdkManager = class _ModSdkManager {
 
 // src/utilities/style.ts
 var Style = {
+  /**
+   * Injects a CSS style block directly into the document head using a <style> tag.
+   * If a style element with the same `styleId` already exists, it won't inject again.
+   */
   injectInline(styleId, styleSource) {
     const isStyleLoaded = document.getElementById(styleId);
     if (isStyleLoaded) return;
@@ -2556,6 +2687,10 @@ var Style = {
     styleElement.appendChild(document.createTextNode(styleSource));
     document.head.appendChild(styleElement);
   },
+  /**
+   * Injects a CSS stylesheet link into the document head using a <link> tag.
+   * If a link element with the same `styleId` already exists, it won't inject again.
+   */
   injectEmbed(styleId, styleLink) {
     const isStyleLoaded = document.getElementById(styleId);
     if (isStyleLoaded) return;
@@ -2565,15 +2700,24 @@ var Style = {
     styleElement.href = styleLink;
     document.head.appendChild(styleElement);
   },
+  /**
+   * Removes a style element from the document head by its ID.
+   * Does nothing if the element is not found.
+   */
   eject(id) {
     const style = document.getElementById(id);
     if (!style) return;
     style.remove();
   },
+  /**
+   * Reloads an inline style by removing the existing style element (if any)
+   * and injecting the new styles inline again.
+   */
   reload(styleId, styleSource) {
     Style.eject(styleId);
     Style.injectInline(styleId, styleSource);
   },
+  /** Fetches the text content of a stylesheet or any resource at the given link. */
   async fetch(link) {
     return fetch(link).then((res) => res.text());
   }
@@ -2589,7 +2733,9 @@ var Localization = class _Localization {
   static PathToModTranslation;
   static PathToLibTranslation = `${PUBLIC_URL}/dl_translations/`;
   static DefaultLanguage = "en";
+  /** Flag to prevent re-initialization */
   static initialized = false;
+  /** Initialize the localization system by loading translation files. */
   static async init(initOptions) {
     if (_Localization.initialized) return;
     _Localization.initialized = true;
@@ -2615,12 +2761,18 @@ var Localization = class _Localization {
       _Localization.ModTranslation = { ...fallbackTranslation, ...modTranslation };
     }
   }
+  /** Get a translated string from mod translations by source tag. */
   static getTextMod(srcTag) {
     return _Localization.ModTranslation?.[srcTag] || void 0;
   }
+  /** Get a translated string from library translations by source tag. */
   static getTextLib(srcTag) {
     return _Localization.LibTranslation?.[srcTag] || void 0;
   }
+  /**
+   * Fetch and parse a language file from the given base URL and language code.
+   * Falls back to default language if the requested language file is unavailable.
+   */
   static async fetchLanguageFile(baseUrl, lang) {
     const response = await fetch(`${baseUrl}${lang}.lang`);
     if (lang !== _Localization.DefaultLanguage && !response.ok) {
@@ -2632,6 +2784,10 @@ var Localization = class _Localization {
     const langFileContent = await response.text();
     return this.parseLanguageFile(langFileContent);
   }
+  /**
+   * Parse the raw content of a language file into a TranslationDict.
+   * Ignores empty lines and comments starting with '#'.
+   */
   static parseLanguageFile(content) {
     const translations = {};
     const lines = content.split("\n");