bc-deeplib 1.2.0 → 2.1.0

package/dist/deeplib.d.ts

@@ -85,22 +85,70 @@ 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 = {
+  export 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;
+      /**
+       * Logical name of this subscreen.
+       * Used for localization key resolution in `load()`.
+       * Subclasses should override this with a meaningful identifier.
+       */
+      name: string;
+      /**
+       * Path to or Base64 data for an icon representing this subscreen.
+       * Defaults to empty string (no icon).
+       */
+      icon?: string;
+      /**
+       * An optional help button to open a subscreen or URL or run a function when clicked.
+       */
+      help?: {
+          /** A URL or BaseSubscreen to open or a function to run when the help button is clicked  */
+          onClick: URL | string | BaseSubscreen | (() => void);
+          /** A tooltip to display when the help button is hovered over */
+          tooltip?: string;
+          /** An icon to display on the help button */
+          icon?: string;
+      };
+      /**
+       * Screen to return to when exiting this subscreen.
+       * If not configured, the default is the main menu for all screens, but main menu itself.
+       * For main menu, the default is the Extensions menu
+       */
+      returnScreen?: (() => ScreenSpecifier | BaseSubscreen) | ScreenSpecifier | BaseSubscreen;
+      /**
+       * The background image for this subscreen.
+       * Currently supports only images from the Club.
+       */
+      background?: string;
+      /**
+       * If `true`, the exit button will be shown on the subscreen.
+       * Defaults to `true`.
+       */
+      doShowExitButton?: boolean;
+      /**
+       * If `true`, the title will be shown on the subscreen.
+       * Defaults to `true`.
+       */
+      doShowTitle?: boolean;
+      /**
+       * The width of the settings div in canvas pixels.
+       * Defaults to 1000.
+       */
+      settingsWidth?: number;
   };
   /**
    * 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;
+  export type Subscreen = new (module?: BaseModule) => BaseSubscreen;
   /** Switches the active subscreen in the global `GUI` instance. */
-  export function setSubscreen(subscreen: BaseSubscreen | string | null): BaseSubscreen | null;
+  export function setSubscreen(subscreen: BaseSubscreen | string | null): Promise<void>;
   /**
    * Abstract base class for creating settings/configuration subscreens in a module.
    *
@@ -126,20 +174,13 @@ declare module 'bc-deeplib/base/base_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;
+      /** Identifier for internal use to avoid screen name collisions. */
+      static readonly id: string;
+      /** Optional configuration flags for a BaseSubscreen instance. */
+      protected static readonly subscreenOptions: SubscreenOptions;
+      constructor(module?: BaseModule);
       /** Changes the currently active subscreen. */
-      setSubscreen(screen: BaseSubscreen | string | null): BaseSubscreen | null;
+      setSubscreen(screen: BaseSubscreen | string | null): Promise<void>;
       /** Gets this subscreen's settings object from its parent module. */
       get settings(): BaseSettingsModel;
       /** Updates this subscreen's settings in its parent module. */
@@ -196,7 +237,7 @@ declare module 'bc-deeplib/base/base_subscreen' {
        * Called when the window is resized.
        * Also checks for overflow in the settings div and applies styling accordingly.
        */
-      resize(onLoad?: boolean): void;
+      resize(_onLoad?: boolean): void;
       /**
        * Called when this subscreen is being removed.
        * Resets the static element registry and removes the subscreen from the layout.
@@ -204,50 +245,64 @@ declare module 'bc-deeplib/base/base_subscreen' {
        */
       unload(): void;
   }
-  export {};
 
 }
 declare module 'bc-deeplib/base/elements_typings' {
-  export type SettingElement = Button | Checkbox | Input | Label | Custom;
+  export type SettingElement = Button | Checkbox | Input | Label | Dropdown | Custom;
   export type BaseElementModel = {
       id: string;
       size?: [width: number | null, height: number | null] | (() => [width: number | null, height: number | null]);
       position?: [x: number, y: number] | (() => [x: number, y: number]);
       disabled?: boolean | (() => boolean);
   };
-  export type Button = Omit<BaseElementModel, 'id'> & {
+  export type Button = Prettify<{
       id: Parameters<typeof ElementButton.Create>[0];
       type: 'button';
       onClick?: Parameters<typeof ElementButton.Create>[1];
       options?: Parameters<typeof ElementButton.Create>[2];
       htmlOptions?: Parameters<typeof ElementButton.Create>[3];
-  };
-  export type Checkbox = BaseElementModel & {
+  } & Omit<BaseElementModel, 'id'>>;
+  export type Checkbox = Prettify<{
       type: 'checkbox';
       label?: string;
       description?: string;
       setElementValue?: () => boolean;
       setSettingValue?: (val: boolean) => void;
-      htmlOptions?: Omit<HTMLOptions<any>, 'tag'>;
-  };
-  export type Input = BaseElementModel & {
+      htmlOptions?: Partial<Record<'container' | 'checkbox' | 'label', Omit<HTMLOptions<any>, 'tag'>>> | null | undefined;
+  } & BaseElementModel>;
+  export type Input = Prettify<{
       type: 'text' | 'number' | 'color';
       label?: string;
       description?: string;
       setElementValue?: () => string;
       setSettingValue?: (val: string) => void;
-      htmlOptions?: Omit<HTMLOptions<any>, 'tag'>;
-  };
-  export type Label = BaseElementModel & {
+      htmlOptions?: Partial<Record<'container' | 'input' | 'label', Omit<HTMLOptions<any>, 'tag'>>> | null | undefined;
+  } & BaseElementModel>;
+  export type Dropdown = Prettify<{
+      id: Parameters<typeof ElementCreateDropdown>[0];
+      type: 'dropdown';
+      label?: string;
+      description?: string;
+      optionsList: Parameters<typeof ElementCreateDropdown>[1];
+      setElementValue?: () => string;
+      setSettingValue?: (val: string) => void;
+      options?: Parameters<typeof ElementCreateDropdown>[3];
+      htmlOptions?: {
+          container?: Partial<Omit<HTMLOptions<any>, 'tag'>>;
+          select?: Parameters<typeof ElementCreateDropdown>[4];
+          label?: Partial<Omit<HTMLOptions<'label'>, 'tag'>>;
+      };
+  } & Omit<BaseElementModel, 'id' | 'disabled'>>;
+  export type Label = Prettify<{
       type: 'label';
       label?: string;
       description?: string;
       htmlOptions?: Omit<HTMLOptions<any>, 'tag'>;
-  };
-  export type Custom = BaseElementModel & {
+  } & BaseElementModel>;
+  export type Custom = Prettify<{
       type: 'custom';
       htmlOptions: HTMLOptions<keyof HTMLElementTagNameMap>;
-  };
+  } & BaseElementModel>;
 
 }
 declare module 'bc-deeplib/base/initialization' {
@@ -306,20 +361,6 @@ declare module 'bc-deeplib/base/initialization' {
    *  - Delaying initialization until login (if necessary)
    */
   export function initMod(options: InitOptions): void;
-  /**
-   * 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.
@@ -391,6 +432,7 @@ declare module 'bc-deeplib/base/modules' {
 declare module 'bc-deeplib/deeplib' {
   export * from 'bc-deeplib/base/base_module';
   export * from 'bc-deeplib/base/base_subscreen';
+  export * from 'bc-deeplib/base/elements_typings';
   export * from 'bc-deeplib/base/initialization';
   export * from 'bc-deeplib/base/modules';
   export * from 'bc-deeplib/migrators/base_migrator';
@@ -420,13 +462,13 @@ declare module 'bc-deeplib/migrators/base_migrator' {
    *
    * 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.
+   * 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).
+   * 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 {
       /**
@@ -436,17 +478,17 @@ declare module 'bc-deeplib/migrators/base_migrator' {
        * - 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 get migrationVersion(): string;
       /**
        * Executes the migration logic for this version.
        *
        * @remarks
-       * - Called once when upgrading from a version earlier than {@link MigrationVersion}.
+       * - 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;
+      abstract migrate(): void;
   }
 
 }
@@ -475,22 +517,26 @@ 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 = {
+  type GuiOptions = {
       /**
        * Unique identifier for the mod's settings button.
        * Used internally by the preference system to track the button.
        */
-      Identifier: string;
+      identifier: string;
       /**
        * The label displayed on the settings button.
        * Can be a string or a function that returns a string dynamically.
        */
-      ButtonText: string | (() => string);
+      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);
+      image: string | (() => string);
+      /**
+       * The main menu screen for the mod.
+       */
+      mainMenu?: typeof MainMenu;
   };
   /**
    * Central mod GUI controller that manages all subscreens.
@@ -507,29 +553,18 @@ declare module 'bc-deeplib/modules/gui' {
       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);
+      constructor(guiOptions?: GuiOptions | null);
       /**
        * Loads the GUI and registers the mod's settings button in the extensions menu.
        *
@@ -544,6 +579,13 @@ declare module 'bc-deeplib/modules/gui' {
 }
 declare module 'bc-deeplib/modules/version' {
   import { BaseMigrator, BaseModule } from 'bc-deeplib/deeplib';
+  export type VersionModuleOptions = {
+      newVersionMessage?: string;
+      beforeEach?: () => void;
+      afterEach?: () => void;
+      beforeAll?: () => void;
+      afterAll?: () => void;
+  };
   /**
    * Handles version tracking, new version detection, and version-based migrations
    * for the mod. Also manages displaying a "new version" message to players and
@@ -559,11 +601,20 @@ declare module 'bc-deeplib/modules/version' {
       /** 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;
+      private static version;
       /** Message to display when a new version is detected */
-      static NewVersionMessage: string;
+      private static newVersionMessage?;
       /** List of registered migration handlers, sorted by version */
-      private static Migrators;
+      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);
       /**
        * Initializes the module on load:
        * - Stores the current mod version.
@@ -578,7 +629,7 @@ declare module 'bc-deeplib/modules/version' {
        * - Updates stored version in player data.
        * - Saves `modStorage`.
        */
-      static checkVersionUpdate(): void;
+      private static checkVersionUpdate;
       /**
        * Executes migrations for all registered migrators whose `MigrationVersion`
        * is newer than the previously stored version.
@@ -589,8 +640,6 @@ declare module 'bc-deeplib/modules/version' {
        * 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;
       /**
@@ -608,15 +657,15 @@ declare module 'bc-deeplib/modules/version' {
 }
 declare module 'bc-deeplib/screens/debug' {
   import { SettingElement } from 'bc-deeplib/base/elements_typings';
-  import { BaseSubscreen } from 'bc-deeplib/deeplib';
+  import { BaseSubscreen, SubscreenOptions } from 'bc-deeplib/deeplib';
   export class GuiDebug extends BaseSubscreen {
-      get name(): string;
+      protected static subscreenOptions: SubscreenOptions;
       get pageStructure(): SettingElement[][];
   }
 
 }
 declare module 'bc-deeplib/screens/import_export' {
-  import { BaseSubscreen } from 'bc-deeplib/deeplib';
+  import { BaseSubscreen, SubscreenOptions } from 'bc-deeplib/deeplib';
   /**
    * Configuration options for the {@link GuiImportExport} class.
    */
@@ -643,7 +692,7 @@ declare module 'bc-deeplib/screens/import_export' {
    */
   export class GuiImportExport extends BaseSubscreen {
       private importExportOptions;
-      get name(): string;
+      static subscreenOptions: SubscreenOptions;
       constructor(importExportOptions: ImportExportOptions);
       load(): void;
       resize(): void;
@@ -664,7 +713,7 @@ declare module 'bc-deeplib/screens/import_export' {
 
 }
 declare module 'bc-deeplib/screens/main_menu' {
-  import { BaseSubscreen, GUI } from 'bc-deeplib/deeplib';
+  import { BaseSubscreen, GUI, SubscreenOptions } from 'bc-deeplib/deeplib';
   import { GuiImportExport } from 'bc-deeplib/screens/import_export';
   /**
    * Configuration options for the main menu.
@@ -699,7 +748,7 @@ declare module 'bc-deeplib/screens/main_menu' {
   export class MainMenu extends BaseSubscreen {
       subscreens: BaseSubscreen[];
       private static options;
-      get name(): string;
+      protected static subscreenOptions: SubscreenOptions;
       constructor(module: GUI);
       load(): void;
       run(): void;
@@ -712,12 +761,12 @@ 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.
+   * 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(target: any, source: any): any;
+  export function deepMerge<T, U>(target: T, source: U): T & U;
   /**
    * Returns a new array with elements of the input array shuffled.
    * Uses something-something shuffle algorithm by splicing from a cloned array.
@@ -778,7 +827,7 @@ 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';
+  import { Button, Checkbox, Custom, Dropdown, Input, Label } from 'bc-deeplib/base/elements_typings';
   /**
    * Collection of element creation utilities.
    * Provides convenience wrappers for generating commonly used UI elements.
@@ -789,6 +838,7 @@ declare module 'bc-deeplib/utilities/elements/elements' {
       createInput: typeof elementCreateInput;
       createLabel: typeof elementCreateLabel;
       createCustom: typeof elementCreateCustom;
+      createDropdown: typeof elementCreateDropdown;
       createTooltip: typeof elementCreateTooltip;
       getTooltip: typeof elementGetTooltip;
       setTooltip: typeof elementSetTooltip;
@@ -799,6 +849,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 elementCreateTooltip(): HTMLDivElement;
   function elementGetTooltip(): HTMLElement | undefined;
   function elementSetTooltip(text: string): boolean;
@@ -954,31 +1005,25 @@ declare module 'bc-deeplib/utilities/elements/helpers' {
 }
 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;
       removeSettingsDiv: typeof elementRemoveSettingsDiv;
-      createMiscDiv: typeof elementCreateMiscDiv;
       getMiscDiv: typeof elementGetMiscDiv;
       appendToMiscDiv: typeof elementAppendToMiscDiv;
       removeMiscDiv: typeof elementRemoveMiscDiv;
   };
-  function elementCreateSubscreenDiv(): HTMLElement;
-  function elementGetSubscreenDiv(): HTMLElement | undefined;
-  function elementRemoveSubscreenDiv(): void | undefined;
-  function elementAppendToSubscreenDiv(...element: HTMLElement[]): void | undefined;
-  function elementCreateSettingsDiv(): HTMLElement;
-  function elementGetSettingsDiv(): HTMLElement | undefined;
-  function elementAppendToSettingsDiv(...element: HTMLElement[]): void | undefined;
-  function elementRemoveSettingsDiv(): void | undefined;
-  function elementCreateMiscDiv(): HTMLElement;
-  function elementGetMiscDiv(): HTMLElement | null;
-  function elementAppendToMiscDiv(...element: HTMLElement[]): void | undefined;
-  function elementRemoveMiscDiv(): void | undefined;
+  function elementGetSubscreenDiv(): HTMLElement;
+  function elementRemoveSubscreenDiv(): void;
+  function elementAppendToSubscreenDiv(...element: HTMLElement[]): void;
+  function elementGetSettingsDiv(): HTMLElement;
+  function elementAppendToSettingsDiv(...element: HTMLElement[]): void;
+  function elementRemoveSettingsDiv(): void;
+  function elementGetMiscDiv(): HTMLElement;
+  function elementAppendToMiscDiv(...element: HTMLElement[]): void;
+  function elementRemoveMiscDiv(): void;
   export {};
 
 }