@quan-erp/shared-frontend-core 1.0.0

package/dist/types/core/location.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Common interface defining geolocation and location watch tracking APIs.
+ */
+export interface ILocation {
+    /** Requests native geolocation permissions on the device. */
+    requestPermission(): Promise<boolean>;
+    /** Retrieves the current geographical coordinates of the device. */
+    getCurrentPosition(): Promise<{
+        latitude: number;
+        longitude: number;
+    }>;
+    /** Subscribes to real-time location coordinate changes. */
+    watchPosition(callback: (pos: {
+        latitude: number;
+        longitude: number;
+    }) => void): Promise<string>;
+    /** Cancels an active location watch tracking session. */
+    clearWatch(watchId: string): void;
+}
+export declare class WebLocation implements ILocation {
+    private watchers;
+    private nextId;
+    requestPermission(): Promise<boolean>;
+    getCurrentPosition(): Promise<{
+        latitude: number;
+        longitude: number;
+    }>;
+    watchPosition(callback: (pos: {
+        latitude: number;
+        longitude: number;
+    }) => void): Promise<string>;
+    clearWatch(watchId: string): void;
+}
+export declare class CapacitorLocation extends WebLocation implements ILocation {
+    requestPermission(): Promise<boolean>;
+    getCurrentPosition(): Promise<{
+        latitude: number;
+        longitude: number;
+    }>;
+    watchPosition(callback: (pos: {
+        latitude: number;
+        longitude: number;
+    }) => void): Promise<string>;
+    clearWatch(watchId: string): void;
+}
+export declare class ElectronLocation extends WebLocation {
+}
+/**
+ * Cross-platform Geolocation utility that delegates location tracking and watch requests
+ * to native Capacitor plugins, Electron, or Web Geolocation APIs depending on the runtime environment.
+ */
+export declare class Location implements ILocation {
+    private static _instance;
+    private impl;
+    private constructor();
+    /**
+     * Singleton instance of the Location utility.
+     */
+    static get instance(): Location;
+    /**
+     * Requests location tracking permissions on the current device.
+     * @returns A promise resolving to true if location access was granted.
+     */
+    requestPermission(): Promise<boolean>;
+    /**
+     * Obtains the current static geolocation coordinates.
+     * @returns A promise resolving to coordinates containing latitude and longitude.
+     */
+    getCurrentPosition(): Promise<{
+        latitude: number;
+        longitude: number;
+    }>;
+    /**
+     * Registers a continuous watch listener on the device's location coordinates.
+     * @param callback Callback function executed whenever location updates occur.
+     * @returns A promise resolving to a string watch ID which can be cleared.
+     */
+    watchPosition(callback: (pos: {
+        latitude: number;
+        longitude: number;
+    }) => void): Promise<string>;
+    /**
+     * Cancels an ongoing geolocation watch listener session.
+     * @param watchId The string ID of the watch listener to release.
+     */
+    clearWatch(watchId: string): void;
+}

package/dist/types/core/microphone.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Common interface defining system microphone hardware access and streaming APIs.
+ */
+export interface IMicrophone {
+    /** Starts recording or capturing audio from the microphone sensor. */
+    start(): Promise<void>;
+    /** Stops the active microphone recording and releases media tracks. */
+    stop(): void;
+    /** Retrieves the currently active audio MediaStream. */
+    getStream(): MediaStream | null;
+    /** Requests microphone recording permissions from the user. */
+    requestPermission(): Promise<boolean>;
+}
+declare class WebMicrophone implements IMicrophone {
+    private stream;
+    requestPermission(): Promise<boolean>;
+    start(): Promise<void>;
+    stop(): void;
+    getStream(): MediaStream | null;
+}
+export declare class ElectronMicrophone extends WebMicrophone {
+}
+/**
+ * Cross-platform Microphone utility that delegates audio capture streams and recording permissions
+ * to Capacitor plugins, Electron, or browser MediaStream APIs depending on the environment.
+ */
+export declare class Microphone implements IMicrophone {
+    private static _instance;
+    private impl;
+    private constructor();
+    /**
+     * Singleton instance of the Microphone utility.
+     */
+    static get instance(): Microphone;
+    /**
+     * Requests microphone permissions from the operating system or browser.
+     * @returns A promise resolving to true if permission was granted.
+     */
+    requestPermission(): Promise<boolean>;
+    /**
+     * Initiates the microphone sensor and binds it to an active audio MediaStream.
+     */
+    start(): Promise<void>;
+    /**
+     * Halts microphone streaming and closes all associated audio media tracks.
+     */
+    stop(): void;
+    /**
+     * Obtains the raw HTML5 MediaStream containing active audio tracks.
+     * @returns The active MediaStream or null if not streaming.
+     */
+    getStream(): MediaStream | null;
+}
+export {};

package/dist/types/core/morientation.d.ts

@@ -0,0 +1,14 @@
+export interface IOrientation {
+    getOrientation(): "portrait" | "landscape";
+    onChange(callback: (orientation: "portrait" | "landscape") => void): void;
+    offChange(callback: (orientation: "portrait" | "landscape") => void): void;
+}
+export declare class Orientation implements IOrientation {
+    private static _instance;
+    private impl;
+    private constructor();
+    static get instance(): Orientation;
+    getOrientation(): "portrait" | "landscape";
+    onChange(callback: (orientation: "portrait" | "landscape") => void): void;
+    offChange(callback: (orientation: "portrait" | "landscape") => void): void;
+}

package/dist/types/core/motion-orientation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Common interface defining device motion orientation tracking APIs.
+ */
+export interface IMotionOrientation {
+    /** Starts listening to device motion orientation changes (alpha, beta, gamma). */
+    start(callback: (data: {
+        alpha: number | null;
+        beta: number | null;
+        gamma: number | null;
+    }) => void): void;
+    /** Stops listening to device motion orientation changes. */
+    stop(): void;
+    /** Requests native orientation event permissions (especially for iOS Safari). */
+    requestOrientationPermission(): Promise<boolean>;
+}
+/**
+ * Cross-platform Motion Orientation helper class that yields platform-specific trackers.
+ */
+export declare class MotionOrientation {
+    /**
+     * Creates and returns a new instance of IMotionOrientation optimized for the current platform.
+     * @returns A platform-specific instance of IMotionOrientation.
+     */
+    static getNewinstance(): IMotionOrientation;
+}

package/dist/types/core/network.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Cross-platform Network connection and status tracking utility.
+ */
+export declare class Network {
+    /**
+     * Checks if the device is currently online.
+     * @returns A promise resolving to true if connected, false otherwise.
+     */
+    static isOnline(): Promise<boolean>;
+    /**
+     * Registers a listener to observe changes in the device's online/offline connection state.
+     * @param callback Callback function executed whenever network state changes.
+     */
+    static listenNetwork(callback: (online: boolean) => void): Promise<void>;
+}

package/dist/types/core/notification.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Defines the contract for cross-platform notification services.
+ */
+export interface INotifications {
+    /**
+     * Requests authorization/permission from the user to display notifications.
+     * @returns A promise resolving to `true` if permission was granted, `false` otherwise.
+     */
+    requestPermission(): Promise<boolean>;
+    /**
+     * Triggers or schedules a local system notification.
+     * @param title The title text of the notification.
+     * @param options Configuration options including message body and unique ID.
+     */
+    sendNotification(title: string, options?: {
+        body?: string;
+        id?: number;
+    }): Promise<void>;
+}
+/**
+ * Capacitor-specific implementation of INotifications for mobile platforms (Android/iOS).
+ * Uses `@capacitor/local-notifications` to schedule push-like local system notifications.
+ */
+export declare class CapacitorNotifications implements INotifications {
+    private permissionGranted;
+    private channelCreated;
+    /**
+     * Requests notification permissions from the Capacitor local notification manager.
+     * @returns A promise resolving to `true` if display permissions are granted, `false` otherwise.
+     */
+    requestPermission(): Promise<boolean>;
+    /**
+     * Sends a local notification on mobile platforms.
+     * Automatically registers a default notification channel if not already created.
+     * @param title The notification title.
+     * @param options Additional options containing body string and custom channel ID.
+     */
+    sendNotification(title: string, options?: {
+        body?: string;
+        id?: number;
+    }): Promise<void>;
+}
+/**
+ * Electron-specific notification implementation for desktop environments.
+ * Delegates to the default system-level Chromium Notification API.
+ */
+export declare class ElectronNotifications implements INotifications {
+    /**
+     * Requests notification permission. Electron apps usually have notification rights by default.
+     * @returns A promise resolving to `true`.
+     */
+    requestPermission(): Promise<boolean>;
+    /**
+     * Triggers a desktop notification using Chromium's HTML5 Notification API.
+     * @param title The title of the desktop notification.
+     * @param options Options containing the body of the notification.
+     */
+    sendNotification(title: string, options?: {
+        body?: string;
+    }): Promise<void>;
+}
+/**
+ * Standard browser/web notification implementation.
+ * Wraps browser-native HTML5 Web Notification API.
+ */
+export declare class WebNotifications implements INotifications {
+    /**
+     * Requests permission using the standard browser Web Notification API.
+     * @returns A promise resolving to `true` if permission is granted, `false` otherwise.
+     */
+    requestPermission(): Promise<boolean>;
+    /**
+     * Triggers a standard browser notification when permitted.
+     * @param title The notification title.
+     * @param options Options containing the body of the notification.
+     */
+    sendNotification(title: string, options?: {
+        body?: string;
+    }): Promise<void>;
+}
+/**
+ * Singleton wrapper and router for cross-platform local notification features.
+ * Automatically delegates calls to the appropriate platform-specific implementation.
+ */
+export declare class Notifications implements INotifications {
+    private static _instance;
+    private impl;
+    /**
+     * Private constructor to enforce singleton usage pattern.
+     * Selects and instantiates the underlying notification engine based on platform type.
+     */
+    private constructor();
+    /**
+     * Gets the current active global singleton instance of `Notifications`.
+     */
+    static get instance(): Notifications;
+    /**
+     * Requests authorization/permission from the user to display notifications.
+     * Delegates to the active platform implementation.
+     * @returns A promise resolving to `true` if permission was granted, `false` otherwise.
+     */
+    requestPermission(): Promise<boolean>;
+    /**
+     * Triggers or schedules a local notification.
+     * Delegates to the active platform implementation.
+     * @param title The title text of the notification.
+     * @param options Configuration options including message body and unique ID.
+     */
+    sendNotification(title: string, options?: {
+        body?: string;
+        id?: number;
+    }): Promise<void>;
+}

package/dist/types/core/number-formatter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Utility class for high-performance locale-aware number and currency formatting.
+ * Features an internal cache to reuse Intl.NumberFormat instances across repetitive calls.
+ */
+export declare class NumberFormatter {
+    /**
+     * Map cache key-value store holding instantiated Intl.NumberFormat objects.
+     */
+    private static formats;
+    /**
+     * Formats a numeric value according to the specified locale and formatting configuration.
+     * Caches the underlying Intl.NumberFormat instance based on a normalized cache key.
+     *
+     * @param num The numeric value to format.
+     * @param locale The RFC 5646 language tag representing the locale (e.g., 'en-US', 'my-MM'). Defaults to 'en-US'.
+     * @param options Standard ECMAScript Internationalization API number format options.
+     * @returns The formatted string representation of the number.
+     */
+    static format(num: number, locale?: string, options?: Intl.NumberFormatOptions): string;
+}

package/dist/types/core/orientation.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Defines the contract for monitoring and managing device screen orientation.
+ */
+export interface IOrientation {
+    /**
+     * Retrieves the current device orientation.
+     * @returns Either 'portrait' or 'landscape'.
+     */
+    getOrientation(): "portrait" | "landscape";
+    /**
+     * Registers a callback listener to trigger when screen orientation changes.
+     * @param callback The function to invoke, receiving the new orientation string.
+     */
+    onChange(callback: (orientation: "portrait" | "landscape") => void): void;
+    /**
+     * Unregisters a previously registered orientation change listener.
+     * @param callback The listener function to remove.
+     */
+    offChange(callback: (orientation: "portrait" | "landscape") => void): void;
+}
+/**
+ * Singleton wrapper and router for managing screen and window orientation states across platforms.
+ */
+export declare class Orientation implements IOrientation {
+    private static _instance;
+    private impl;
+    /**
+     * Enforces single instance behavior and resolves target device implementation at runtime.
+     */
+    private constructor();
+    /**
+     * Accesses the active, platform-resolved singleton orientation service.
+     */
+    static get instance(): Orientation;
+    /**
+     * Retrieves current viewport or physical device screen orientation.
+     */
+    getOrientation(): "portrait" | "landscape";
+    /**
+     * Subscribes a listener to orientation modification events.
+     * @param callback Callback receiving standard landscape/portrait codes.
+     */
+    onChange(callback: (orientation: "portrait" | "landscape") => void): void;
+    /**
+     * Unsubscribes a listener.
+     * @param callback Callback to remove.
+     */
+    offChange(callback: (orientation: "portrait" | "landscape") => void): void;
+}

package/dist/types/core/permissions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Central system utility class for managing, requesting, and query-checking application permissions.
+ * Serves as a standard interface for handling high-security mobile device feature access (Camera, Location, Push, etc.).
+ */
+export declare class Permissions {
+}

package/dist/types/core/platform.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Utility service to identify the active application shell context (Desktop, Mobile, or Web).
+ * Used for dynamic feature detection and directing API requests to Capacitor, Electron, or browser-native APIs.
+ */
+export declare class Platforms {
+    /**
+     * Determines if the application is running inside an Electron desktop window context.
+     * Checks if the `electron` IPC bridge object has been injected into the global `window` scope.
+     *
+     * @returns `true` if executed in an Electron shell environment, `false` otherwise.
+     */
+    static isDesktop(): boolean;
+    /**
+     * Determines if the application is running as a native mobile application (Android/iOS).
+     * Inspects the global Capacitor plugin bridge interface properties.
+     *
+     * @returns `true` if executed within a native mobile app container, `false` otherwise.
+     */
+    static isMobile(): boolean;
+    /**
+     * Determines if the application is running in a traditional web browser environment.
+     * Checks that neither Electron desktop bindings nor Capacitor native app plugins are initialized.
+     *
+     * @returns `true` if running strictly on a standard web page, `false` otherwise.
+     */
+    static isWeb(): boolean;
+}

package/dist/types/core/plugin-api.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Registry interface for dynamic runtime plugin interoperability and component exporting/importing.
+ * Allows plugins within the modular ERP system to expose functional APIs securely and consume external capabilities dynamically.
+ */
+export declare class PluginAPI {
+    /**
+     * Exposes a specific API service from a plugin, registering it within the shared system registry.
+     * Prevents re-definition of keys once registered to ensure runtime immutability and prevent injection attacks.
+     *
+     * @param pluginName The unique namespace name of the exporting plugin.
+     * @param apiName The identifying key representing the exported service.
+     * @param value The functional API surface, class instance, or utility being shared.
+     * @throws Error if the plugin namespace and API key combination is already registered.
+     */
+    static expose<T>(pluginName: string, apiName: string, value: T): void;
+    /**
+     * Resolves and retrieves an exposed API service from another plugin namespace.
+     *
+     * @param pluginName The namespace of the target plugin.
+     * @param apiName The key identifying the requested API surface.
+     * @returns The resolved service instance cast to generic type T.
+     */
+    static use<T>(pluginName: string, apiName: string): T;
+    /**
+     * Gets the current raw internal registry map of all exposed APIs.
+     */
+    static get store(): any;
+    /**
+     * Lists the keys of all registered APIs in the system for inspection and debugging.
+     * @returns An array of API identifiers in the format: "pluginName|apiName".
+     */
+    static debug(): string[];
+}

package/dist/types/core/printer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Defines the contract for printing raw HTML templates across diverse system targets.
+ */
+export interface IPrinter {
+    /**
+     * Renders and dispatches an HTML content string to a system printer interface.
+     * @param html The full HTML document structure or snippet to print.
+     */
+    printHTML(html: string): void;
+}
+/**
+ * Web-native printer helper using browser standard `window.print()` workflows.
+ * Opens a temporary hidden frame or window to present the content dialog to the user.
+ */
+export declare class WebPrinter implements IPrinter {
+    /**
+     * Opens a temporary tab frame and initiates the native system print pop-up.
+     * @param html HTML text content to print.
+     */
+    printHTML(html: string): void;
+}
+/**
+ * Electron-specific printer helper to coordinate with physical native queues.
+ * Currently serves as a feature placeholder.
+ */
+export declare class ElectronPrinter implements IPrinter {
+    /**
+     * Desktop platform custom print dispatcher.
+     * @param html HTML source code to print.
+     */
+    printHTML(html: string): Promise<void>;
+}
+/**
+ * Mobile-specific printer implementation utilizing native OS print spoolers.
+ * Currently serves as a feature placeholder.
+ */
+export declare class MobilePrinter implements IPrinter {
+    /**
+     * Mobile platform custom print dispatcher.
+     * @param html HTML source code to print.
+     */
+    printHTML(html: string): Promise<void>;
+}
+/**
+ * Singleton wrapper and dynamic platform router for the system print engine services.
+ */
+export declare class Printer {
+    private static _instance;
+    /**
+     * Retrieves the global active singleton printing service instance.
+     * Resolves the target implementation at runtime according to the platform profile.
+     */
+    static get instance(): IPrinter;
+}

package/dist/types/core/safearea.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Utility service to retrieve and query hardware display safe area offsets (notch/home insets).
+ * Useful for building responsive mobile headers, navbars, and viewport content padding.
+ */
+export declare class SafeArea {
+    /**
+     * Retrieves the top safe area inset value in pixels.
+     * Maps to the CSS environment variable `safe-area-inset-top`.
+     * @returns The pixel height offset.
+     */
+    static getTop(): number;
+    /**
+     * Retrieves the bottom safe area inset value in pixels (e.g., home indicator bar).
+     * Maps to the CSS environment variable `safe-area-inset-bottom`.
+     * @returns The pixel height offset.
+     */
+    static getBottom(): number;
+    /**
+     * Retrieves the left safe area inset value in pixels (landscape notch alignment).
+     * Maps to the CSS environment variable `safe-area-inset-left`.
+     * @returns The pixel width offset.
+     */
+    static getLeft(): number;
+    /**
+     * Retrieves the right safe area inset value in pixels (landscape notch alignment).
+     * Maps to the CSS environment variable `safe-area-inset-right`.
+     * @returns The pixel width offset.
+     */
+    static getRight(): number;
+}

package/dist/types/core/shared-preferences.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Standard contract for cross-platform local storage and application preference engines.
+ */
+export interface IStorage {
+    /**
+     * Persists a key-value string pair in local storage.
+     * @param key The identification key.
+     * @param value The string value to store.
+     */
+    setItem(key: string, value: string): Promise<void>;
+    /**
+     * Resolves a key value from local storage.
+     * @param key The identification key.
+     * @returns A promise resolving to the string value if found, or `null` if empty.
+     */
+    getItem(key: string): Promise<string | null>;
+    /**
+     * Deletes a key-value record from local storage.
+     * @param key The identification key to delete.
+     */
+    removeItem(key: string): Promise<void>;
+    /**
+     * Purges and clears all entries stored under this engine namespace.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Singleton wrapper and router for managing persistent configurations and keys across different runtime systems.
+ */
+export declare class Storage implements IStorage {
+    private static _instance;
+    private impl;
+    /**
+     * Intitializes the target platform storage client implementation at runtime.
+     */
+    private constructor();
+    /**
+     * Accesses the active, platform-resolved singleton Storage engine service.
+     */
+    static get instance(): Storage;
+    /**
+     * Persists a key-value record in localized storage.
+     * @param key Identifer key.
+     * @param value Text payload.
+     */
+    setItem(key: string, value: string): Promise<void>;
+    /**
+     * Retrieves a key record from local storage.
+     * @param key Identifer key.
+     */
+    getItem(key: string): Promise<string | null>;
+    /**
+     * Deletes a key record from local storage.
+     * @param key Identifer key.
+     */
+    removeItem(key: string): Promise<void>;
+    /**
+     * Clears all persisted storage entries.
+     */
+    clear(): Promise<void>;
+}

package/dist/types/core/sqlite.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Placeholder interface and configuration utilities for SQLite database connection management.
+ *
+ * > [!NOTE]
+ * > Local SQLite instance connections, initializations, and transactions on mobile and desktop platforms
+ * > are actively managed by the dynamic helper class `Database` and the functional accessor `getDB()`
+ * > implemented in `database.ts` (relying on `@capacitor-community/sqlite`).
+ */
+export declare class SQLitePlaceholder {
+    /**
+     * Informational utility function that returns database module metadata.
+     * @returns An object containing sqlite configuration details.
+     */
+    static getMetadata(): {
+        name: string;
+        engine: string;
+    };
+}

package/dist/types/core/system-locale.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Represents string locale identifiers (e.g. "en", "zh-CN", "my-MM").
+ */
+export type Locales = string;
+/**
+ * Defines the contract for fetching localized user system configuration parameters.
+ */
+export interface ILocale {
+    /**
+     * Resolves the primary native system language code or locale identifier.
+     * @returns A promise resolving to the language string tag (e.g., 'en').
+     */
+    getDeviceLocale(): Promise<Locales>;
+}
+/**
+ * Singleton service wrapper and router for managing, retrieving, and query-caching system locale settings.
+ */
+export declare class SystemLocale {
+    private static _instance;
+    /**
+     * Accesses the active global, platform-resolved singleton locale service instance.
+     */
+    static get instance(): ILocale;
+}