bc-deeplib 2.2.0 → 2.4.0

package/dist/deeplib.d.ts

@@ -1,5 +1,5 @@
 declare module 'bc-deeplib/base/base_module' {
-  import { BaseSettingsModel, Subscreen } from 'bc-deeplib/deeplib';
+  import { BaseSettingsModel, SettingsModel, Subscreen } from 'bc-deeplib/deeplib';
   /**
    * An abstract foundation for modular systems that require:
    *  - Optional settings screens
@@ -57,7 +57,7 @@ declare module 'bc-deeplib/base/base_module' {
        * If some settings already exist, they will be merged with defaults.
        * Existing values will NOT be overwritten.
        */
-      registerDefaultSettings(): void;
+      registerDefaultSettings(target: SettingsModel): void;
       /**
        * Provides default settings for this module.
        * Subclasses should override this getter to return their defaults.
@@ -152,7 +152,7 @@ declare module 'bc-deeplib/base/base_subscreen' {
    */
   export type Subscreen = new (module?: BaseModule) => BaseSubscreen;
   /** Switches the active subscreen in the global `GUI` instance. */
-  export function setSubscreen(subscreen: BaseSubscreen | string | null): Promise<void>;
+  export function setSubscreen(subscreen: BaseSubscreen | string): Promise<void>;
   /**
    * Abstract base class for creating settings/configuration subscreens in a module.
    *
@@ -182,9 +182,11 @@ declare module 'bc-deeplib/base/base_subscreen' {
       static readonly id: string;
       /** Optional configuration flags for a BaseSubscreen instance. */
       protected static readonly subscreenOptions: SubscreenOptions;
+      /** The menu at the top of the subscreen */
+      protected static menu: HTMLDivElement | null;
       constructor(module?: BaseModule);
       /** Changes the currently active subscreen. */
-      setSubscreen(screen: BaseSubscreen | string | null): Promise<void>;
+      setSubscreen(screen: BaseSubscreen | string): Promise<void>;
       /** Gets this subscreen's settings object from its parent module. */
       get settings(): BaseSettingsModel;
       /** Updates this subscreen's settings in its parent module. */
@@ -310,7 +312,7 @@ declare module 'bc-deeplib/base/elements_typings' {
 
 }
 declare module 'bc-deeplib/base/initialization' {
-  import { BaseModule, ModSdkManager, BaseMigrator, ModStorage, MainMenuOptions, TranslationOptions } from 'bc-deeplib/deeplib';
+  import { BaseModule, ModSdkManager, ModStorage, MainMenuOptions, TranslationOptions, Logger } from 'bc-deeplib/deeplib';
   /** Configuration object for initializing a mod via `initMod`. */
   interface InitOptions {
       /**
@@ -327,11 +329,6 @@ declare module 'bc-deeplib/base/initialization' {
        * 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;
       /**
@@ -357,6 +354,11 @@ declare module 'bc-deeplib/base/initialization' {
    * Initialized by `initMod()`.
    */
   export let sdk: ModSdkManager;
+  /**
+   * Mod specific logger instance.
+   * Initialized by `initMod()`.
+   */
+  export let logger: Logger;
   /**
    * Entry point for initializing a mod. Handles:
    *  - Setting up the Mod SDK
@@ -584,10 +586,20 @@ declare module 'bc-deeplib/modules/gui' {
 declare module 'bc-deeplib/modules/version' {
   import { BaseMigrator, BaseModule } from 'bc-deeplib/deeplib';
   export type VersionModuleOptions = {
+      /**
+       * List of data migration handlers to register with the `VersionModule`.
+       * Each `BaseMigrator` handles upgrading data from one version to another.
+       */
+      migrators?: BaseMigrator[];
+      /** Message to display when a new version is detected */
       newVersionMessage?: string;
+      /** Optional lifecycle hook. Runs before each migration */
       beforeEach?: () => void;
+      /** Optional lifecycle hook. Runs after each migration */
       afterEach?: () => void;
+      /** Optional lifecycle hook. Runs before all migrations */
       beforeAll?: () => void;
+      /** Optional lifecycle hook. Runs after all migrations */
       afterAll?: () => void;
   };
   /**
@@ -606,17 +618,12 @@ declare module 'bc-deeplib/modules/version' {
       private static isItNewVersion;
       /** The current mod version (retrieved from `ModSdkManager.ModInfo.version`) */
       private static version;
-      /** Message to display when a new version is detected */
       private static newVersionMessage?;
       /** List of registered migration handlers, sorted by version */
       private static migrators;
-      /** Optional lifecycle hook. Runs before each migration */
       private static beforeEach?;
-      /** Optional lifecycle hook. Runs after each migration */
       private static afterEach?;
-      /** Optional lifecycle hook. Runs before all migrations */
       private static beforeAll?;
-      /** Optional lifecycle hook. Runs after all migrations */
       private static afterAll?;
       constructor(options: VersionModuleOptions);
       /**
@@ -639,11 +646,6 @@ declare module 'bc-deeplib/modules/version' {
        * 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;
       /** Sends the currently configured "new version" message to the local player. */
       static sendNewVersionMessage(): void;
       /**
@@ -705,7 +707,7 @@ declare module 'bc-deeplib/screens/import_export' {
       /** 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>;
+      exportToFile(data: string, defaultFileName: string): Promise<boolean>;
       /** 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. */
@@ -764,13 +766,16 @@ declare module 'bc-deeplib/screens/main_menu' {
 
 }
 declare module 'bc-deeplib/utilities/common' {
+  export type DeepMergeOptions = {
+      concatArrays?: boolean;
+  };
   /**
    * Deeply merges two values into a new value.
    * - Arrays are concatenated.
    * - Plain objects are merged recursively.
    * - Other values are replaced by `source`.
    */
-  export function deepMerge<T, U>(target: T, source: U): T & U;
+  export function deepMerge<T, U>(target: T, source: U, options?: DeepMergeOptions): T & U;
   /**
    * Returns a new array with elements of the input array shuffled.
    * Uses something-something shuffle algorithm by splicing from a cloned array.
@@ -783,12 +788,6 @@ declare module 'bc-deeplib/utilities/common' {
    * Example: `exportToGlobal('MyMod.Utils', value)` creates `globalThis.MyMod.Utils = value`.
    */
   export function exportToGlobal(name: string, value: any): void;
-  /**
-   * 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. */
@@ -853,7 +852,7 @@ declare module 'bc-deeplib/utilities/elements/elements' {
   function elementCreateCustom(options: Omit<Custom, 'type'>): HTMLElement;
   function elementCreateInput(options: Input): HTMLElement;
   function elementCreateLabel(options: Omit<Label, 'type'>): HTMLElement;
-  function elementCreateDropdown(options: Omit<Dropdown, 'type'>): HTMLDivElement;
+  function elementCreateDropdown(options: Omit<Dropdown, 'type'>): HTMLDivElement | HTMLLabelElement;
   function elementCreateTooltip(): HTMLDivElement;
   function elementGetTooltip(): HTMLElement | undefined;
   function elementSetTooltip(text: string): boolean;