bc-deeplib 1.1.3 → 2.0.0

package/README.md

@@ -1,2 +1,26 @@
-## Deep Lib
-Package for easier development of BC mods.
+# ${{\color{#440171}\Large{\textsf{DeepLib}}}}$
+## Active development (there might be a lot of breaking changes)
+
+## What is DeepLib?
+
+DeepLib is an opinionated library for easier development of BC mods, which strives to be a framework :D
+
+## What it has to offer
+
+* **Mod Initialization**: The `initMod()` function allows you to initialize a mod, which includes setting up the Mod SDK, initializing localization, and registering modules and migrators.
+
+* **Modules**: provides a modular architecture, allowing you to create modules for different aspects of your mod.
+
+* **Settings GUI**: provides an easily configurable HTML-based GUI system for creating different sorts of settings screens with a lot of built-in features.
+
+* **Localization**: provides a localization system for creating different languages for your mod.
+
+* **Migrators**: provides a migrator system for creating different migrations for your mod for easy transition between versions.
+
+* **Hidden Events**: provides a hidden event system for sending and listening to events with help of `EventChannel`.
+
+* **Out-Of-Box Themed Support**: custom elements support Themed customizations.
+
+* **Build System**: provides a build system for easily building your mod with `esbuild`.
+
+Take a look at [QUICKSTART.md](docs/QUICKSTART.md) for more information on how to get started.

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. */
@@ -153,6 +179,7 @@ declare module 'bc-deeplib/base/base_subscreen' {
       get pageStructure(): SettingElement[][];
       /** Gets the currently visible page's settings elements. */
       get currentPage(): SettingElement[];
+      getPageLabel(): string;
       /**
        * Changes the visible page in a multi-page subscreen.
        * Automatically wraps around when going past the first or last page.
@@ -195,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.
@@ -203,7 +230,6 @@ declare module 'bc-deeplib/base/base_subscreen' {
        */
       unload(): void;
   }
-  export {};
 
 }
 declare module 'bc-deeplib/base/elements_typings' {
@@ -214,20 +240,13 @@ declare module 'bc-deeplib/base/elements_typings' {
       position?: [x: number, y: number] | (() => [x: number, y: number]);
       disabled?: boolean | (() => boolean);
   };
-  type CustomButtonOptions = {
-      id?: Parameters<typeof ElementButton.Create>[0];
+  export type Button = Omit<BaseElementModel, 'id'> & {
+      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 Button = BaseElementModel & {
-      type: 'button';
-      image?: string;
-      label?: string;
-      tooltip?: string;
-      onClick?: () => void;
-      htmlOptions?: CustomButtonOptions;
-  };
   export type Checkbox = BaseElementModel & {
       type: 'checkbox';
       label?: string;
@@ -254,7 +273,6 @@ declare module 'bc-deeplib/base/elements_typings' {
       type: 'custom';
       htmlOptions: HTMLOptions<keyof HTMLElementTagNameMap>;
   };
-  export {};
 
 }
 declare module 'bc-deeplib/base/initialization' {
@@ -300,6 +318,11 @@ declare module 'bc-deeplib/base/initialization' {
    * Initialized by `initMod()` and mod data loaded by `init()`.
    */
   export let modStorage: ModStorage;
+  /**
+   * Global Mod SDK manager.
+   * Initialized by `initMod()`.
+   */
+  export let sdk: ModSdkManager;
   /**
    * Entry point for initializing a mod. Handles:
    *  - Setting up the Mod SDK
@@ -307,9 +330,7 @@ declare module 'bc-deeplib/base/initialization' {
    *  - Injecting required styles
    *  - Delaying initialization until login (if necessary)
    */
-  export function initMod(options: InitOptions): {
-      sdk: ModSdkManager;
-  };
+  export function initMod(options: InitOptions): void;
   /**
    * Fully initializes the mod after login.
    * Handles:
@@ -415,6 +436,7 @@ declare module 'bc-deeplib/deeplib' {
   export * from 'bc-deeplib/utilities/sdk';
   export * from 'bc-deeplib/utilities/style';
   export * from 'bc-deeplib/utilities/translation';
+  export * from 'bc-deeplib/utilities/event_channel';
 
 }
 declare module 'bc-deeplib/migrators/base_migrator' {
@@ -423,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 {
       /**
@@ -439,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;
   }
 
 }
@@ -478,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.
@@ -510,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.
        *
@@ -547,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
@@ -562,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.
@@ -581,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.
@@ -592,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;
       /**
@@ -611,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.
    */
@@ -646,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;
@@ -667,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.
@@ -694,11 +723,15 @@ declare module 'bc-deeplib/screens/main_menu' {
        * Provides tools to import or export data to or from the mod.
        */
       importExportSubscreen?: GuiImportExport;
+      /**
+       * Optional boolean flag to enable the mod storage fullness indicator.
+       */
+      storageFullnessIndicator?: boolean;
   };
   export class MainMenu extends BaseSubscreen {
       subscreens: BaseSubscreen[];
       private static options;
-      get name(): string;
+      protected static subscreenOptions: SubscreenOptions;
       constructor(module: GUI);
       load(): void;
       run(): void;
@@ -739,6 +772,10 @@ declare module 'bc-deeplib/utilities/common' {
   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;
+  /**
+   * Converts bytes to kilobytes.
+   */
+  export const byteToKB: (nByte: number) => number;
 
 }
 declare module 'bc-deeplib/utilities/data' {
@@ -768,6 +805,7 @@ declare module 'bc-deeplib/utilities/data' {
       save(): void;
       static dataDecompress<T = object>(string: string): T | null;
       static dataCompress(object: object): string;
+      static measureSize(data: unknown): number;
   }
 
 }
@@ -832,7 +870,7 @@ declare module 'bc-deeplib/utilities/elements/elements' {
   };
   export type ModalOptions<T extends string = string> = {
       /** Content or DOM node displayed in the modal header. */
-      prompt: string | Node;
+      prompt: ElementButton.StaticNode;
       /** Optional input configuration. */
       input?: ModalInputOptions;
       /** Buttons to display in the modal. */
@@ -841,6 +879,10 @@ declare module 'bc-deeplib/utilities/elements/elements' {
       closeOnBackdrop?: boolean;
       /** Auto-close timeout in milliseconds. */
       timeoutMs?: number;
+      /** Action sent when Escape key is pressed. */
+      escapeAction?: T;
+      /** Action sent when Enter key is pressed. */
+      enterAction?: T;
   };
   /**
    * Modal dialog implementation with queuing, buttons, optional input, and focus trapping.
@@ -864,17 +906,17 @@ declare module 'bc-deeplib/utilities/elements/elements' {
       /**
        * Shows a simple alert modal with a single "OK" button.
        */
-      static alert(msg: string, timeoutMs?: number): Promise<void>;
+      static alert(msg: ElementButton.StaticNode, 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>;
+      static confirm(msg: ElementButton.StaticNode): 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>;
+      static prompt(msg: ElementButton.StaticNode, defaultValue?: string): Promise<string | null>;
       /** Creates the input element for the modal, applying configuration and validation. */
       private renderInput;
       /** Creates modal action buttons from configuration. */
@@ -944,31 +986,64 @@ 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 {};
+
+}
+declare module 'bc-deeplib/utilities/event_channel' {
+  type DeepLibMessageDictionaryEntry<Type extends string, Data> = {
+      type: Type;
+      data: Data;
+  };
+  type Listener<Payload> = (data: Payload, sender: Character) => void;
+  export interface UnverifiedMessage extends ServerChatRoomMessageBase {
+      Target?: number;
+      Content: ServerChatRoomMessageContentType;
+      Type: ServerChatRoomMessageType;
+      Dictionary?: {
+          type: string;
+          data?: any;
+      }[];
+      Timeout?: number;
+  }
+  export interface EventChannelMessage<TEvents extends Record<string, unknown> = Record<string, unknown>, TEvent extends keyof TEvents & string = keyof TEvents & string> extends ServerChatRoomMessageBase {
+      Target?: number;
+      Content: string;
+      Type: 'Hidden';
+      Dictionary: [
+          DeepLibMessageDictionaryEntry<TEvent, TEvents[TEvent]>
+      ];
+      Timeout?: number;
+      Sender: number;
+  }
+  export class EventChannel<TEvents extends Record<string, unknown>, TChannelName extends string> {
+      private channelName;
+      private listeners;
+      constructor(channelName: TChannelName);
+      unload(): void;
+      sendEvent<K extends keyof TEvents & string>(type: K, data: TEvents[K], target?: number | null): void;
+      registerListener<K extends keyof TEvents & string>(event: K, listener: Listener<TEvents[K]>): () => void;
+      unregisterListener<K extends keyof TEvents & string>(event: K, listener: Listener<TEvents[K]>): void;
+      private isChannelMessage;
+  }
   export {};
 
 }