bc-deeplib 1.1.2 → 1.1.3

package/dist/deeplib.d.ts

@@ -99,8 +99,6 @@ declare module 'bc-deeplib/base/base_subscreen' {
    * configuration options and a parent module reference.
    */
   export type Subscreen = new (subscreenOptions?: SubscreenOptions, module?: BaseModule) => BaseSubscreen;
-  /** Retrieves the currently active subscreen from the global `GUI` instance. */
-  export function getCurrentSubscreen(): BaseSubscreen | null;
   /** Switches the active subscreen in the global `GUI` instance. */
   export function setSubscreen(subscreen: BaseSubscreen | string | null): BaseSubscreen | null;
   /**
@@ -456,8 +454,14 @@ declare module 'bc-deeplib/migrators/base_migrator' {
 
 }
 declare module 'bc-deeplib/models/base' {
+  /**
+   * Represents the base settings structure for a mod.
+   * Present for all mods.
+   */
   export type BaseSettingsModel = {
+      /** Whether the mod is currently active. */
       modEnabled: boolean;
+      /** Whether to display a notification when a new version is detected. */
       doShowNewVersionMessage: boolean;
   };
 
@@ -473,28 +477,69 @@ declare module 'bc-deeplib/models/settings' {
 }
 declare module 'bc-deeplib/modules/gui' {
   import { BaseModule, BaseSubscreen, MainMenu } from 'bc-deeplib/deeplib';
+  /** Options for configuring a mod's main button in the extensions menu. */
   type ModButtonOptions = {
+      /**
+       * Unique identifier for the mod's settings button.
+       * Used internally by the preference system to track the button.
+       */
       Identifier: string;
+      /**
+       * The label displayed on the settings button.
+       * Can be a string or a function that returns a string dynamically.
+       */
       ButtonText: string | (() => string);
+      /**
+       * The path to or Base64 data of the icon for the settings button.
+       * Can be a string or a function that returns a string dynamically.
+       */
       Image: string | (() => string);
-      load?: () => void;
-      click?: () => void;
-      run?: () => void;
-      unload?: () => void;
-      exit?: () => boolean | void;
   };
+  /**
+   * Central mod GUI controller that manages all subscreens.
+   *
+   * This module is responsible for:
+   * - Registering the mod's settings button in the game's preferences.
+   * - Managing subscreens (including settings screens for all registered modules).
+   * - Routing lifecycle events (load, run, click, exit, unload) to the active subscreen.
+   */
   export class GUI extends BaseModule {
+      /** The singleton instance of the GUI controller. */
       static instance: GUI | null;
+      /** All subscreens managed by this GUI, including the main menu and module settings screens. */
       private _subscreens;
+      /** The mod's main menu screen. */
       private _mainMenu;
+      /** The currently active subscreen, or `null` if none is active. */
       private _currentSubscreen;
+      /** Options defining how the mod's settings button is displayed and behaves. */
       private _modButtonOptions;
+      /** Returns all registered subscreens. */
       get subscreens(): BaseSubscreen[];
+      /** Returns the main menu subscreen instance. */
       get mainMenu(): MainMenu;
+      /** Returns the currently active subscreen. */
       get currentSubscreen(): BaseSubscreen | null;
+      /**
+       * 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: BaseSubscreen | string | null);
+      /**
+       * Creates the GUI instance and initializes the main menu.
+       *
+       * @throws If another `GUI` instance already exists.
+       */
       constructor(modButtonOptions: ModButtonOptions);
-      get defaultSettings(): 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(): void;
   }
   export {};
@@ -502,19 +547,64 @@ declare module 'bc-deeplib/modules/gui' {
 }
 declare module 'bc-deeplib/modules/version' {
   import { BaseMigrator, BaseModule } from 'bc-deeplib/deeplib';
+  /**
+   * Handles version tracking, new version detection, and version-based migrations
+   * for the mod. Also manages displaying a "new version" message to players and
+   * executing registered migration routines when an update occurs.
+   *
+   * **Key Responsibilities:**
+   * - Track and store the current mod version in persistent player storage.
+   * - Detect if the mod has been updated since the last session.
+   * - Run version-specific migrations via registered `BaseMigrator` instances.
+   * - Optionally display a message to the user upon detecting a new version.
+   */
   export class VersionModule extends BaseModule {
+      /** Whether the current session is running a new version compared to stored data */
       private static isItNewVersion;
+      /** The current mod version (retrieved from `ModSdkManager.ModInfo.version`) */
       static Version: string;
+      /** Message to display when a new version is detected */
       static NewVersionMessage: string;
+      /** List of registered migration handlers, sorted by version */
       private static Migrators;
+      /**
+       * Initializes the module on load:
+       * - Stores the current mod version.
+       * - Hooks into `ChatRoomSync` to show a "new version" message when applicable.
+       */
       load(): void;
+      /**
+       * 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(): void;
+      /**
+       * Executes migrations for all registered migrators whose `MigrationVersion`
+       * is newer than the previously stored version.
+       */
       private static checkVersionMigration;
+      /**
+       * Registers a new migrator for handling version-specific changes.
+       * Migrators are sorted by their `MigrationVersion` in ascending order.
+       */
       static registerMigrator(migrator: BaseMigrator): void;
+      /** Sets the message that will be displayed when a new version is detected. */
       static setNewVersionMessage(newVersionMessage: string): void;
+      /** Sends the currently configured "new version" message to the local player. */
       static sendNewVersionMessage(): void;
+      /**
+       * Determines if a given `candidate` version is newer than the `current` version.
+       *
+       * Version strings are expected in `MAJOR.MINOR.PATCH` format.
+       */
       private static isNewVersion;
+      /** Saves the current mod version into persistent player storage. */
       private static saveVersion;
+      /** Loads the stored mod version from persistent player storage. */
       private static loadVersion;
   }
 
@@ -530,26 +620,47 @@ declare module 'bc-deeplib/screens/debug' {
 }
 declare module 'bc-deeplib/screens/import_export' {
   import { BaseSubscreen } from 'bc-deeplib/deeplib';
+  /**
+   * Configuration options for the {@link GuiImportExport} class.
+   */
   export type ImportExportOptions = {
-      /** A custom save file extension. */
+      /**
+       * A custom save file extension (e.g., ".mydata").
+       * If it doesn't start with a dot, it will be automatically prefixed.
+       */
       customFileExtension: string;
-      /** A callback to be called after data is imported. */
+      /** Optional callback invoked after data has been successfully imported. */
       onImport?: () => void;
-      /** A callback to be called after data is exported. */
+      /** Optional callback invoked after data has been successfully exported. */
       onExport?: () => void;
   };
+  /**
+   * Possible data transfer methods for import/export operations.
+   * - `clipboard`: Uses the system clipboard.
+   * - `file`: Uses file save/load dialogs.
+   */
   type DataTransferMethod = 'clipboard' | 'file';
+  /**
+   * GUI screen for importing and exporting mod data.
+   * Provides buttons to import/export data either via file or clipboard.
+   */
   export class GuiImportExport extends BaseSubscreen {
       private importExportOptions;
       get name(): string;
       constructor(importExportOptions: ImportExportOptions);
       load(): void;
       resize(): void;
+      /** Exports the mod data using the specified method. */
       dataExport(transferMethod: DataTransferMethod): Promise<void>;
+      /** Imports mod data using the specified method. */
       dataImport(transferMethod: DataTransferMethod): Promise<void>;
+      /** Saves data to a file using the browser's save dialog. */
       exportToFile(data: string, defaultFileName: string): Promise<void>;
+      /** Opens a file picker and reads the selected file's contents, importing the data. */
       importFromFile(): Promise<string | null>;
+      /** Copies the given data to the clipboard. */
       exportToClipboard(data: string): Promise<void>;
+      /** Prompts the user to enter data and returns it. */
       importFromClipboard(): Promise<string | null>;
   }
   export {};
@@ -558,10 +669,30 @@ declare module 'bc-deeplib/screens/import_export' {
 declare module 'bc-deeplib/screens/main_menu' {
   import { BaseSubscreen, GUI } from 'bc-deeplib/deeplib';
   import { GuiImportExport } from 'bc-deeplib/screens/import_export';
+  /**
+   * Configuration options for the main menu.
+   *
+   * If these are defined, new button for each option will be added to the main menu.
+   */
   export type MainMenuOptions = {
+      /**
+       * Optional URL to the project's repository.
+       * Example: "https://github.com/user/project"
+       */
       repoLink?: string;
+      /**
+       * Optional URL to the project's wiki or documentation.
+       * Example: "https://github.com/user/project/wiki"
+       */
       wikiLink?: string;
+      /**
+       * Optional subscreen to use for the "reset" action.
+       */
       resetSubscreen?: BaseSubscreen;
+      /**
+       * Optional subscreen for import/export functionality.
+       * Provides tools to import or export data to or from the mod.
+       */
       importExportSubscreen?: GuiImportExport;
   };
   export class MainMenu extends BaseSubscreen {
@@ -579,19 +710,52 @@ declare module 'bc-deeplib/screens/main_menu' {
 
 }
 declare module 'bc-deeplib/utilities/common' {
+  /**
+   * Deeply merges properties from `source` into `target`.
+   * - If both target and source properties are arrays, concatenates them.
+   * - If both are objects, recursively merges them.
+   * - Otherwise, source overwrites target.
+   */
   export function deepMerge(target: any, source: any): any;
+  /**
+   * Returns a new array with elements of the input array shuffled.
+   * Uses something-something shuffle algorithm by splicing from a cloned array.
+   */
   export function shuffleArray(array: string[]): string[];
+  /**
+   * Exports a value to the global object under a nested namespace path.
+   * Creates intermediate objects if they do not exist.
+   *
+   * Example: `exportToGlobal('MyMod.Utils', value)` creates `globalThis.MyMod.Utils = value`.
+   */
   export function exportToGlobal(name: string, value: any): void;
-  /** Merges matching properties from `mergeFrom` into `mergeTo`. */
+  /**
+   * Deeply merges only matching properties from `mergeFrom` into `mergeTo`.
+   * Properties not present in `mergeTo` are ignored.
+   * Objects are recursively merged, primitive properties overwritten.
+   */
   export function deepMergeMatchingProperties<T extends object>(mergeTo: T, mergeFrom: T): T;
+  /** Checks if the given property has a getter defined on the object or its prototype chain. */
   export function hasGetter<T extends object>(obj: T, prop: keyof T | string): boolean;
+  /** Checks if the given property has a setter defined on the object or its prototype chain. */
   export function hasSetter<T extends object>(obj: T, prop: keyof T | string): boolean;
 
 }
 declare module 'bc-deeplib/utilities/data' {
   import { SettingsModel } from 'bc-deeplib/deeplib';
+  /**
+   * ModStorage is a singleton class responsible for managing
+   * mod-specific persistent storage both in player settings
+   * and in browser localStorage.
+   *
+   * It provides methods to load and save mod data compressed
+   * as base64 strings, and exposes typed accessors for
+   * playerStorage and extensionStorage.
+   */
   export class ModStorage<T extends SettingsModel = SettingsModel> {
+      /** Singleton instance of ModStorage */
       private static _instance;
+      /** The unique mod identifier used as key prefix in storage */
       private modName;
       constructor(modName: string);
       get playerStorage(): T;
@@ -609,6 +773,10 @@ declare module 'bc-deeplib/utilities/data' {
 }
 declare module 'bc-deeplib/utilities/elements/elements' {
   import { Button, Checkbox, Custom, Input, Label } from 'bc-deeplib/base/elements_typings';
+  /**
+   * Collection of element creation utilities.
+   * Provides convenience wrappers for generating commonly used UI elements.
+   */
   export const advElement: {
       createButton: typeof elementCreateButton;
       createCheckbox: typeof elementCreateCheckbox;
@@ -643,41 +811,79 @@ declare module 'bc-deeplib/utilities/elements/elements' {
   }
   function elementPrevNext(options: PrevNext): HTMLElement;
   export type ModalButton<T extends string = string> = {
+      /** Button label text. */
       text: string;
+      /** Action identifier returned when the button is clicked. */
       action: T;
+      /** Whether the button is disabled. */
       disabled?: boolean;
   };
   export type ModalInputOptions = {
+      /** Default input value. */
       defaultValue?: string;
+      /** Makes the input read-only if true. */
       readOnly?: boolean;
+      /** Placeholder text. */
       placeholder?: string;
+      /** Input type. */
       type: 'input' | 'textarea';
+      /** Validation callback to check if the input value is valid. */
       validate?: (value: string) => string | null;
   };
   export type ModalOptions<T extends string = string> = {
+      /** Content or DOM node displayed in the modal header. */
       prompt: string | Node;
+      /** Optional input configuration. */
       input?: ModalInputOptions;
+      /** Buttons to display in the modal. */
       buttons?: ModalButton<T>[];
+      /** Whether clicking backdrop closes the modal (default: true). */
       closeOnBackdrop?: boolean;
+      /** Auto-close timeout in milliseconds. */
       timeoutMs?: number;
   };
+  /**
+   * Modal dialog implementation with queuing, buttons, optional input, and focus trapping.
+   * Multiple modals are queued to ensure only one is visible at a time.
+   */
   export class Modal<T extends string = string> {
       private opts;
       private dialog;
       private blocker;
       private inputEl?;
       private timeoutId?;
+      /** Static modal queue. */
       private static queue;
+      /** Flag to indicate if a modal is currently being shown. */
       private static processing;
       constructor(opts: ModalOptions<T>);
+      /**
+       * Displays the modal and resolves with the chosen action and input value.
+       */
       show(): Promise<[T, string | null]>;
+      /**
+       * Shows a simple alert modal with a single "OK" button.
+       */
       static alert(msg: string, timeoutMs?: number): Promise<void>;
+      /**
+       * Shows a confirmation modal with "Cancel" and "OK" buttons.
+       * Returns true if "OK" is clicked.
+       */
       static confirm(msg: string): Promise<boolean>;
+      /**
+       * Shows a prompt modal with an input field and "Submit"/"Cancel" buttons.
+       * Returns the input value if submitted, otherwise null.
+       */
       static prompt(msg: string, defaultValue?: string): Promise<string | null>;
+      /** Creates the input element for the modal, applying configuration and validation. */
       private renderInput;
+      /** Creates modal action buttons from configuration. */
       private renderButtons;
+      /** Creates the modal backdrop blocker with optional click-to-close behavior. */
       private createBlocker;
+      /** Implements a focus trap to keep keyboard navigation inside the modal. */
       private setupFocusTrap;
+      /** Closes the modal, cleans up DOM, resolves promise, and shows next queued modal. */
       private close;
       /**
        * An internal function where we will save promise function.
@@ -694,10 +900,34 @@ declare module 'bc-deeplib/utilities/elements/elements' {
 declare module 'bc-deeplib/utilities/elements/helpers' {
   import { SettingElement } from 'bc-deeplib/base/elements_typings';
   export const 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: typeof 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: typeof autoSetSize;
+      /**
+       * Hides the element by setting its CSS display property to 'none'.
+       * If the element cannot be found, the function does nothing.
+       */
       hide: typeof hide;
+      /**
+       * Unhides the element by clearing its CSS display property (sets it to '').
+       * If the element cannot be found, the function does nothing.
+       */
       unhide: typeof 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: typeof hasOverflow;
   };
   function autoSetPosition(_: ElementHelp.ElementOrId, position: SettingElement['position']): void;
@@ -770,6 +1000,10 @@ declare module 'bc-deeplib/utilities/messages' {
 
 }
 declare module 'bc-deeplib/utilities/sdk' {
+  /**
+   * Defines priority levels for hooking functions.
+   * Hooks with higher priority are called first in hook chain.
+   */
   export const HookPriority: {
       Observe: number;
       AddBehavior: number;
@@ -777,7 +1011,12 @@ declare module 'bc-deeplib/utilities/sdk' {
       OverrideBehavior: number;
       Top: number;
   };
+  /** Type alias representing module of hook? */
   export type ModuleCategory = number | string;
+  /**
+   * Interface representing data about a patched function,
+   * including the function name and all hooks applied to it.
+   */
   interface IPatchedFunctionData {
       name: string;
       hooks: {
@@ -787,16 +1026,41 @@ declare module 'bc-deeplib/utilities/sdk' {
           removeCallback: () => void;
       }[];
   }
+  /**
+   * Manager class for mod SDK integration,
+   * provides methods to register mods, hook functions, and manage patches.
+   */
   export class ModSdkManager {
       private static SDK;
       private static patchedFunctions;
       static ModInfo: ModSDKModInfo;
+      /** Registers a mod with the SDK and stores mod information. */
       constructor(info: ModSDKModInfo, options?: ModSDKModOptions);
+      /** Retrieves or initializes patch data for a given target function. */
       initPatchableFunction(target: string): IPatchedFunctionData;
+      /**
+       * Hooks a function with a callback at a given priority.
+       *
+       * Prevents duplicate hooks.
+       */
       hookFunction<TargetName extends string>(target: TargetName, priority: number, hook: PatchHook<GetDotedPathType<typeof globalThis, TargetName>>, module?: ModuleCategory | null): () => void;
+      /**
+       * Applies patches to a target function.
+       *
+       * **This method is DANGEROUS** to use and has high potential to conflict with other mods.
+       */
       patchFunction(target: string, patches: Record<string, string>): void;
+      /**
+       * Removes all patches from a target function.
+       */
       unpatchFunction(target: string): void;
+      /**
+       * Removes all hooks associated with a specific module from a target function.
+       */
       removeHookByModule(target: string, module: ModuleCategory): boolean;
+      /**
+       * Removes all hooks associated with a specific module across all patched functions.
+       */
       removeAllHooksByModule(module: ModuleCategory): boolean;
   }
   export {};
@@ -804,36 +1068,78 @@ declare module 'bc-deeplib/utilities/sdk' {
 }
 declare module 'bc-deeplib/utilities/style' {
   export const 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: string, styleSource: string): void;
+      /**
+       * 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: string, styleLink: string): void;
+      /**
+       * Removes a style element from the document head by its ID.
+       * Does nothing if the element is not found.
+       */
       eject(id: string): void;
+      /**
+       * Reloads an inline style by removing the existing style element (if any)
+       * and injecting the new styles inline again.
+       */
       reload(styleId: string, styleSource: string): void;
+      /** Fetches the text content of a stylesheet or any resource at the given link. */
       fetch(link: string): Promise<string>;
   };
 
 }
 declare module 'bc-deeplib/utilities/translation' {
+  /**
+   * Options for initializing the Localization system.
+   */
   export interface TranslationOptions {
       /** The path to the folder where the translations are stored. */
       pathToTranslationsFolder?: string;
       /** The default language to use. */
       defaultLanguage?: string;
-      /** If true, the localization will be fixed to the default language. */
+      /** If true, the localization will be fixed to the default language, ignoring user language settings. */
       fixedLanguage?: boolean;
   }
+  /**
+   * Localization class handles loading and retrieving translation strings
+   * from library and mod-specific language files.
+   */
   export class Localization {
       private static LibTranslation;
       private static ModTranslation;
       private static PathToModTranslation;
       private static PathToLibTranslation;
       private static DefaultLanguage;
+      /** Flag to prevent re-initialization */
       private static initialized;
+      /** Initialize the localization system by loading translation files. */
       static init(initOptions?: TranslationOptions): Promise<void>;
+      /** Get a translated string from mod translations by source tag. */
       static getTextMod(srcTag: string): string | undefined;
+      /** Get a translated string from library translations by source tag. */
       static getTextLib(srcTag: string): string | undefined;
+      /**
+       * 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.
+       */
       private static fetchLanguageFile;
+      /**
+       * Parse the raw content of a language file into a TranslationDict.
+       * Ignores empty lines and comments starting with '#'.
+       */
       private static parseLanguageFile;
   }
+  /**
+   * Retrieve a localized string for the given source tag.
+   * First attempts to get the mod-specific translation,
+   * then falls back to the library translation,
+   * and if neither exist, returns the source tag itself.
+   */
   export const getText: (srcTag: string) => string;
 
 }