bc-deeplib 1.2.0 → 2.0.0

package/dist/deeplib.d.ts

@@ -85,22 +85,55 @@ 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;
   };
   /**
    * 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 +159,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 +222,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,7 +230,6 @@ declare module 'bc-deeplib/base/base_subscreen' {
        */
       unload(): void;
   }
-  export {};
 
 }
 declare module 'bc-deeplib/base/elements_typings' {
@@ -420,13 +445,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 +461,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 +500,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 +536,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 +562,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 +584,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 +612,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 +623,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 +640,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 +675,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 +696,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 +731,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;
@@ -954,31 +986,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 {};
 
 }