bc-deeplib 1.1.0 → 1.1.2

package/dist/deeplib.d.ts

@@ -1,15 +1,82 @@
 declare module 'bc-deeplib/base/base_module' {
   import { BaseSettingsModel, Subscreen } from 'bc-deeplib/deeplib';
+  /**
+   * An abstract foundation for modular systems that require:
+   *  - Optional settings screens
+   *  - Persistent settings storage per module
+   *  - Default settings registration
+   *  - Lifecycle hooks for loading, running, and unloading
+   *
+   * ### Responsibilities
+   * This class defines the base contract for all modules in the system:
+   *  - Provides a standardized interface for retrieving and storing settings
+   *  - Ensures default settings are registered if missing
+   *  - Integrates with the module storage system (`modStorage`)
+   *  - Offers overridable lifecycle methods (`init`, `load`, `run`, `unload`)
+   *
+   * **Subclass Requirements:**
+   *  - Must extend `BaseModule`
+   *  - Should override `defaultSettings` to define defaults for its settings, if any
+   *  - May override `settingsScreen` to provide a UI component
+   *  - May override lifecycle methods as needed
+   */
   export abstract class BaseModule {
+      /**
+       * An optional UI screen for configuring this module's settings.
+       * Subclasses can override this getter to provide a `Subscreen` instance.
+       * Modules with screens are automatically registered to the main menu.
+       */
       get settingsScreen(): Subscreen | null;
+      /**
+       * The storage key under which this module's settings will be saved.
+       * Defaults to the class name.
+       *
+       * Subclasses can override this if they require a custom storage key.
+       */
       get settingsStorage(): string | null;
+      /**
+       * Retrieves the current settings for this module.
+       * If no settings exist yet, registers default settings first.
+       */
       get settings(): BaseSettingsModel;
+      /**
+       * Persists new settings for this module.
+       * Automatically initializes storage and defaults if they don't exist.
+       */
       set settings(value: BaseSettingsModel);
+      /**
+       * Initializes the module.
+       * Default implementation registers default settings immediately.
+       * Subclasses can override to perform additional setup.
+       */
       init(): void;
+      /**
+       * Registers default settings for this module in persistent storage.
+       * Only runs if a storage key and default settings are defined.
+       *
+       * If some settings already exist, they will be merged with defaults.
+       * Existing values will NOT be overwritten.
+       */
       registerDefaultSettings(): void;
+      /**
+       * Provides default settings for this module.
+       * Subclasses should override this getter to return their defaults.
+       */
       get defaultSettings(): BaseSettingsModel | null;
+      /**
+       * Called when the module is loaded into the system.
+       * Subclasses should override to perform data loading or initialization.
+       */
       load(): void;
+      /**
+       * By default doesn't get called each frame, only once when the module is loaded.
+       * Subclasses can override to implement runtime logic.
+       */
       run(): void;
+      /**
+       * Called when the module is being removed.
+       * Subclasses can override to perform cleanup or save final state.
+       */
       unload(): void;
   }
 
@@ -17,33 +84,125 @@ declare module 'bc-deeplib/base/base_module' {
 declare module 'bc-deeplib/base/base_subscreen' {
   import { BaseModule, BaseSettingsModel } from 'bc-deeplib/deeplib';
   import { SettingElement } from 'bc-deeplib/base/elements_typings';
+  /** Optional configuration flags for a `BaseSubscreen` instance. */
   type SubscreenOptions = {
+      /**
+       * If `true`, the subscreen will draw the player's character model
+       * in the UI when `run()` is called.
+       * Also shift the UI to the right to make room for the character.
+       */
       drawCharacter?: boolean;
   };
+  /**
+   * Represents a constructor type for a subscreen.
+   * Allows dynamic instantiation of subscreen classes with optional
+   * 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;
+  /**
+   * Abstract base class for creating settings/configuration subscreens in a module.
+   *
+   * ### Responsibilities
+   * This class defines the base contract for all modules in the system:
+   *  - Provides a standardized interface for retrieving and storing settings
+   *  - Ensures default settings are registered if missing
+   *  - Integrates with the module storage system (`modStorage`)
+   *  - Offers overridable lifecycle methods (`init`, `load`, `run`, `unload`)
+   *
+   * **Subclass Requirements:**
+   *  - Must extend `BaseSubscreen`
+   *  - Should override `name`, `icon` to define subscreen metadata
+   *  - May override `pageStructure` to define UI layout and controls
+   *  - May override lifecycle methods as needed
+   */
   export abstract class BaseSubscreen {
+      /** Global registry of currently rendered elements and their definitions. */
       static currentElements: [HTMLElement, SettingElement][];
+      /** Tracks the currently visible page number (1-based index). */
       static currentPage: number;
+      /** Runtime options for this subscreen. */
       readonly options: SubscreenOptions;
+      /** Reference to the module this subscreen belongs to. */
       readonly module: BaseModule;
       constructor(subscreenOptions?: SubscreenOptions, module?: BaseModule);
+      /**
+       * Logical name of this subscreen.
+       * Used for localization key resolution in `load()`.
+       * Subclasses should override this with a meaningful identifier.
+       */
       get name(): string;
+      /**
+       * Path to or Base64 data for an icon representing this subscreen.
+       * Defaults to empty string (no icon).
+       */
       get icon(): string;
-      get subscreenName(): string;
+      /** Changes the currently active subscreen. */
       setSubscreen(screen: BaseSubscreen | string | null): BaseSubscreen | null;
+      /** Gets this subscreen's settings object from its parent module. */
       get settings(): BaseSettingsModel;
+      /** Updates this subscreen's settings in its parent module. */
       set settings(value: BaseSettingsModel);
+      /**
+       * Defines the paginated layout of the subscreen's settings UI.
+       * Each element in the outer array is a page; each page contains `SettingElement`s.
+       *
+       * Subclasses should override to define their actual UI structure.
+       */
       get pageStructure(): SettingElement[][];
+      /** Gets the currently visible page's settings elements. */
       get currentPage(): SettingElement[];
+      /**
+       * Changes the visible page in a multi-page subscreen.
+       * Automatically wraps around when going past the first or last page.
+       */
       changePage(page: number, setLabel: (label: string) => void): void;
+      /**
+       * Updates the DOM to show only elements belonging to the current page.
+       * All elements on other pages are hidden.
+       */
       managePageElementsVisibility(): void;
+      /**
+       * Called when this subscreen is first displayed.
+       * Builds the layout, initializes navigation, and renders all settings elements.
+       *
+       * Handles:
+       *  - Ensuring each module with a settings screen has its defaults loaded
+       *  - Creating navigation menus and back/next page controls
+       *  - Building and appending UI elements based on `pageStructure`
+       *  - Setting up exit button and tooltip
+       *  - Resetting to page 1
+       */
       load(): void;
+      /**
+       * Called each frame while this subscreen is active.
+       * Default behavior draws the player's character if `drawCharacter` is enabled.
+       */
       run(): void;
+      /**
+       * Handles mouse clicks *on canvas* while the subscreen is active.
+       * Default implementation is empty — subclasses may override.
+       */
       click(): void;
+      /**
+       * Exits this subscreen, returning to the main menu.
+       * Also saves persistent storage changes.
+       * Called after the `unload`.
+       */
       exit(): void;
+      /**
+       * Called when the window is resized.
+       * Also checks for overflow in the settings div and applies styling accordingly.
+       */
       resize(onLoad?: boolean): void;
+      /**
+       * Called when this subscreen is being removed.
+       * Resets the static element registry and removes the subscreen from the layout.
+       * Called before `exit`.
+       */
       unload(): void;
   }
   export {};
@@ -101,33 +260,137 @@ declare module 'bc-deeplib/base/elements_typings' {
 
 }
 declare module 'bc-deeplib/base/initialization' {
-  import { BaseModule, ModSdkManager, BaseMigrator, ModStorage, MainMenuOptions } from 'bc-deeplib/deeplib';
+  import { BaseModule, ModSdkManager, BaseMigrator, ModStorage, MainMenuOptions, TranslationOptions } from 'bc-deeplib/deeplib';
+  /** Configuration object for initializing a mod via `initMod`. */
   interface InitOptions {
+      /**
+       * Information about the mod being initialized.
+       * - `info`    — Required metadata describing the mod.
+       * - `options` — Optional runtime configuration for the Mod SDK.
+       */
       modInfo: {
           info: ModSDKModInfo;
           options?: ModSDKModOptions;
       };
+      /**
+       * List of modules (`BaseModule` subclasses) to register with the mod system.
+       * Modules are initialized, loaded, and run in order.
+       */
       modules?: BaseModule[];
+      /**
+       * List of data migration handlers to register with the `VersionModule`.
+       * Each `BaseMigrator` handles upgrading data from one version to another.
+       */
       migrators?: BaseMigrator[];
+      /** Configuration for customizing the main menu when the mod is active. */
       mainMenuOptions?: MainMenuOptions;
+      /**
+       * Optional hook executed *before* login when the player is not yet authenticated.
+       * Useful for pre-login setup or display changes.
+       */
       beforeLogin?: () => (void);
+      /**
+       * Optional async/sync function run after modules and translations are initialized.
+       * Can be used to perform additional setup tasks.
+       */
       initFunction?: () => (void | Promise<void>);
-      pathToTranslationsFolder?: string;
+      /** Options for initializing the localization/translation system. */
+      translationOptions?: TranslationOptions;
   }
+  /**
+   * Global storage handler for mod.
+   * Initialized by `initMod()` and mod data loaded by `init()`.
+   */
   export let modStorage: ModStorage;
+  /**
+   * Entry point for initializing a mod. Handles:
+   *  - Setting up the Mod SDK
+   *  - Preparing persistent storage
+   *  - Injecting required styles
+   *  - Delaying initialization until login (if necessary)
+   */
   export function initMod(options: InitOptions): {
       sdk: ModSdkManager;
   };
+  /**
+   * Fully initializes the mod after login.
+   * Handles:
+   *  - Preventing double-load
+   *  - Loading mod data
+   *  - Initializing localization
+   *  - Registering modules and migrators
+   *  - Running optional init functions
+   *  - Applying main menu changes
+   *  - Merging default settings into module settings
+   *
+   * @param options {InitOptions} Configuration for mod initialization.
+   */
   export function init(options: InitOptions): Promise<void>;
+  /**
+   * Cleans up and removes the mod from memory.
+   * Calls `unload()` on all modules and removes the global loaded flag.
+   */
   export function unloadMod(): true;
   export {};
 
 }
 declare module 'bc-deeplib/base/modules' {
   import { BaseModule } from 'bc-deeplib/deeplib';
+  /**
+   * Global registry of all loaded modules, keyed by their class name.
+   *
+   * The map is populated via {@link registerModule} and accessed via {@link modules} or {@link getModule}.
+   * This is the central storage for active `BaseModule` instances during the mod lifecycle.
+   */
   export const modulesMap: Map<string, BaseModule>;
+  /**
+   * Retrieves all registered module instances.
+   *
+   * @returns An array containing every module currently stored in {@link modulesMap}.
+   *
+   * @remarks
+   * The returned array is a **shallow copy** of the `Map` values, meaning that
+   * changes to the array do not affect the registry itself.
+   *
+   * @example
+   * ```ts
+   * for (const mod of modules()) {
+   *   mod.run();
+   * }
+   * ```
+   */
   export function modules(): BaseModule[];
+  /**
+   * Registers a module instance in the global registry.
+   *
+   * @returns The same module instance passed in, for chaining or immediate use.
+   *
+   * @remarks
+   * - If a module with the same constructor name already exists, it will be **overwritten**.
+   * - Keys are based on the class name (`module.constructor.name`), so name collisions are possible
+   *   if two different classes share the same name.
+   *
+   * @example
+   * ```ts
+   * registerModule(new MyGlobalModule());
+   * ```
+   */
   export function registerModule<T extends BaseModule>(module: T): T;
+  /**
+   * Retrieves a registered module by its type name.
+   *
+   * @returns The matching module instance cast to type `T`, or `undefined` if not found.
+   *
+   * @remarks
+   * This function does not perform runtime type checks. If the type parameter `T`
+   * does not match the actual module type, you may get runtime errors when using the result.
+   *
+   * @example
+   * ```ts
+   * const themeModule = getModule<ThemeModule>('ThemeModule');
+   * themeModule?.reloadTheme();
+   * ```
+   */
   export function getModule<T extends BaseModule>(moduleType: string): T;
 
 }
@@ -145,9 +408,9 @@ declare module 'bc-deeplib/deeplib' {
   export * from 'bc-deeplib/screens/main_menu';
   export * from 'bc-deeplib/screens/import_export';
   export * from 'bc-deeplib/utilities/data';
-  export * from 'bc-deeplib/utilities/elements/advanced_elements';
-  export * from 'bc-deeplib/utilities/elements/element_helpers';
-  export * from 'bc-deeplib/utilities/elements/layout_elements';
+  export * from 'bc-deeplib/utilities/elements/elements';
+  export * from 'bc-deeplib/utilities/elements/helpers';
+  export * from 'bc-deeplib/utilities/elements/layout';
   export * from 'bc-deeplib/utilities/common';
   export * from 'bc-deeplib/utilities/logger';
   export * from 'bc-deeplib/utilities/messages';
@@ -157,9 +420,38 @@ declare module 'bc-deeplib/deeplib' {
 
 }
 declare module 'bc-deeplib/migrators/base_migrator' {
+  /**
+   * Abstract base class for versioned migration handlers.
+   *
+   * A migrator is responsible for upgrading or transforming stored data
+   * when the mod version changes. Each migrator targets a specific version
+   * and executes its {@link Migrate} method once when needed.
+   *
+   * @remarks
+   * To create a new migrator:
+   * 1. Extend `BaseMigrator`.
+   * 2. Implement the {@link MigrationVersion} getter to return the target version string.
+   * 3. Implement {@link Migrate} with the migration logic (e.g., data structure changes).
+   */
   export abstract class BaseMigrator {
+      /**
+       * Gets the target version string for this migration.
+       *
+       * @remarks
+       * - This should exactly match the version format used by the mod
+       * - Used by the migration system to determine if this migration should be executed.
+       */
       abstract get MigrationVersion(): string;
-      abstract Migrate(): boolean;
+      /**
+       * Executes the migration logic for this version.
+       *
+       * @remarks
+       * - Called once when upgrading from a version earlier than {@link MigrationVersion}.
+       * - Should handle any necessary data transformations, cleanup, or initialization
+       *   to bring the mod's state up to date with the new version.
+       * - Must be idempotent — running it multiple times should not cause data corruption.
+       */
+      abstract Migrate(): void;
   }
 
 }
@@ -239,8 +531,11 @@ declare module 'bc-deeplib/screens/debug' {
 declare module 'bc-deeplib/screens/import_export' {
   import { BaseSubscreen } from 'bc-deeplib/deeplib';
   export type ImportExportOptions = {
+      /** A custom save file extension. */
       customFileExtension: string;
+      /** A callback to be called after data is imported. */
       onImport?: () => void;
+      /** A callback to be called after data is exported. */
       onExport?: () => void;
   };
   type DataTransferMethod = 'clipboard' | 'file';
@@ -287,6 +582,7 @@ declare module 'bc-deeplib/utilities/common' {
   export function deepMerge(target: any, source: any): any;
   export function shuffleArray(array: string[]): string[];
   export function exportToGlobal(name: string, value: any): void;
+  /** Merges matching properties from `mergeFrom` into `mergeTo`. */
   export function deepMergeMatchingProperties<T extends object>(mergeTo: T, mergeFrom: T): T;
   export function hasGetter<T extends object>(obj: T, prop: keyof T | string): boolean;
   export function hasSetter<T extends object>(obj: T, prop: keyof T | string): boolean;
@@ -311,9 +607,9 @@ declare module 'bc-deeplib/utilities/data' {
   }
 
 }
-declare module 'bc-deeplib/utilities/elements/advanced_elements' {
+declare module 'bc-deeplib/utilities/elements/elements' {
   import { Button, Checkbox, Custom, Input, Label } from 'bc-deeplib/base/elements_typings';
-  export const advancedElement: {
+  export const advElement: {
       createButton: typeof elementCreateButton;
       createCheckbox: typeof elementCreateCheckbox;
       createInput: typeof elementCreateInput;
@@ -362,7 +658,6 @@ declare module 'bc-deeplib/utilities/elements/advanced_elements' {
       prompt: string | Node;
       input?: ModalInputOptions;
       buttons?: ModalButton<T>[];
-      custom?: readonly (string | Node | HTMLOptions<keyof HTMLElementTagNameMap> | null | undefined)[] | undefined;
       closeOnBackdrop?: boolean;
       timeoutMs?: number;
   };
@@ -384,14 +679,19 @@ declare module 'bc-deeplib/utilities/elements/advanced_elements' {
       private createBlocker;
       private setupFocusTrap;
       private close;
+      /**
+       * An internal function where we will save promise function.
+       */
       private resolve;
+      /** A function that adds a modal to the queue and returns a promise */
       private static enqueue;
+      /** A function that processes the queue, removing the first modal */
       private static dequeue;
   }
   export {};
 
 }
-declare module 'bc-deeplib/utilities/elements/element_helpers' {
+declare module 'bc-deeplib/utilities/elements/helpers' {
   import { SettingElement } from 'bc-deeplib/base/elements_typings';
   export const domUtil: {
       autoSetPosition: typeof autoSetPosition;
@@ -412,12 +712,12 @@ declare module 'bc-deeplib/utilities/elements/element_helpers' {
   export {};
 
 }
-declare module 'bc-deeplib/utilities/elements/layout_elements' {
-  export const layoutElement: {
-      createSubscreenDiv: typeof elementCreateSubscreenDiv;
-      getSubscreenDiv: typeof elementGetSubscreenDiv;
-      appendToSubscreenDiv: typeof elementAppendToSubscreenDiv;
-      removeSubscreenDiv: typeof elementRemoveSubscreenDiv;
+declare module 'bc-deeplib/utilities/elements/layout' {
+  export const layout: {
+      createSubscreen: typeof elementCreateSubscreenDiv;
+      getSubscreen: typeof elementGetSubscreenDiv;
+      appendToSubscreen: typeof elementAppendToSubscreenDiv;
+      removeSubscreen: typeof elementRemoveSubscreenDiv;
       createSettingsDiv: typeof elementCreateSettingsDiv;
       getSettingsDiv: typeof elementGetSettingsDiv;
       appendToSettingsDiv: typeof elementAppendToSettingsDiv;
@@ -513,23 +813,28 @@ declare module 'bc-deeplib/utilities/style' {
 
 }
 declare module 'bc-deeplib/utilities/translation' {
-  interface InitOptions {
-      pathToTranslationsFolder: string;
+  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. */
+      fixedLanguage?: boolean;
   }
   export class Localization {
       private static LibTranslation;
       private static ModTranslation;
       private static PathToModTranslation;
       private static PathToLibTranslation;
+      private static DefaultLanguage;
       private static initialized;
-      static init(initOptions: InitOptions): Promise<void>;
+      static init(initOptions?: TranslationOptions): Promise<void>;
       static getTextMod(srcTag: string): string | undefined;
       static getTextLib(srcTag: string): string | undefined;
       private static fetchLanguageFile;
       private static parseLanguageFile;
   }
   export const getText: (srcTag: string) => string;
-  export {};
 
 }
 declare module 'bc-deeplib' {