bc-deeplib 1.1.3 → 1.2.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

@@ -153,6 +153,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.
@@ -214,20 +215,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 +248,6 @@ declare module 'bc-deeplib/base/elements_typings' {
       type: 'custom';
       htmlOptions: HTMLOptions<keyof HTMLElementTagNameMap>;
   };
-  export {};
 
 }
 declare module 'bc-deeplib/base/initialization' {
@@ -300,6 +293,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 +305,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 +411,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' {
@@ -694,6 +691,10 @@ 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[];
@@ -739,6 +740,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 +773,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 +838,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 +847,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 +874,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. */
@@ -971,6 +981,45 @@ declare module 'bc-deeplib/utilities/elements/layout' {
   function elementRemoveMiscDiv(): void | undefined;
   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 {};
+
 }
 declare module 'bc-deeplib/utilities/logger' {
   type LogLevel = 'info' | 'log' | 'warn' | 'error' | 'debug';