@quan-erp/shared-frontend-core 1.0.0

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

@@ -0,0 +1,109 @@
+/**
+ * Defines the contract for fetching native host device and application shell hardware performance metrics.
+ */
+export interface ISystem {
+    /**
+     * Retrieves the current CPU utilization ratio.
+     * @returns A promise resolving to a fraction between 0.0 and 1.0.
+     */
+    getCPUUsage(): Promise<number>;
+    /**
+     * Resolves the current host system heap memory metrics.
+     * @returns A promise resolving to an object containing used and total bytes.
+     */
+    getMemoryUsage(): Promise<{
+        used: number;
+        total: number;
+    }>;
+    /**
+     * Fetches detailed host platform and hardware specification indicators.
+     * @returns A promise resolving to general system metadata.
+     */
+    getInfo(): Promise<any>;
+    /**
+     * Resolves the total count of logical CPU core threads present on the host system.
+     * @returns The count or undefined if unsupported.
+     */
+    getCPUCoreCount(): Promise<number | undefined>;
+    /**
+     * Resolves the amount of system physical memory (RAM).
+     * @returns Memory capacity in Gigabytes (GB).
+     */
+    getDeviceMemory(): Promise<number | undefined>;
+    /**
+     * Identifies the system network connection quality profile (effective connection type).
+     * @returns A descriptor string (e.g. '4g', '3g') or undefined.
+     */
+    getNetworkType(): string | undefined;
+}
+/**
+ * Electron desktop system implementation.
+ * Queries CPU, RAM, and hardware metrics via desktop-bound IPC helper bridges.
+ */
+export declare class ElectronSystem implements ISystem {
+    /**
+     * Resolves system platform specifications.
+     */
+    getInfo(): Promise<any>;
+    /**
+     * Queries real-time processor load via desktop shell process monitors.
+     */
+    getCPUUsage(): Promise<number>;
+    /**
+     * Queries real-time memory allocations.
+     */
+    getMemoryUsage(): Promise<{
+        used: number;
+        total: number;
+    }>;
+    /**
+     * Queries physical thread count metrics.
+     */
+    getCPUCoreCount(): Promise<number | undefined>;
+    /**
+     * Resolves total RAM size in Gigabytes.
+     */
+    getDeviceMemory(): Promise<number | undefined>;
+    /**
+     * Queries effective network speed profiles.
+     */
+    getNetworkType(): string | undefined;
+}
+/**
+ * Singleton proxy class routing diagnostic query operations to the resolved platform system helper.
+ */
+export declare class System {
+    private static _instance;
+    private constructor();
+    /**
+     * Internal getter to resolve the target native interface service.
+     */
+    private static get impl();
+    /**
+     * Resolves current CPU usage fraction.
+     */
+    static getCPUUsage(): Promise<number>;
+    /**
+     * Resolves allocated and free heap memory details.
+     */
+    static getMemoryUsage(): Promise<{
+        used: number;
+        total: number;
+    }>;
+    /**
+     * Resolves host system core counts.
+     */
+    static getCPUCoreCount(): Promise<number | undefined>;
+    /**
+     * Resolves physical device memory in GB.
+     */
+    static getDeviceMemory(): Promise<number | undefined>;
+    /**
+     * Resolves network connection speed indicator tags.
+     */
+    static getNetworkType(): string | undefined;
+    /**
+     * Fetches detailed platform environment descriptors.
+     */
+    static getInfo(): Promise<any>;
+}

package/dist/types/core/user-behavior.d.ts

@@ -0,0 +1,24 @@
+type HandType = "left" | "right" | "unknown";
+interface IHandDetector {
+    start(): void;
+    stop(): void;
+    getHand(): HandType;
+    onChange?: (hand: HandType) => void;
+}
+export declare class UserHandBehaviorDetector implements IHandDetector {
+    private hand;
+    private started;
+    private samples;
+    private readonly SAMPLE_SIZE;
+    private readonly TILT_THRESHOLD;
+    private lastReportedHand;
+    private motionsOrientation;
+    onChange?: (hand: HandType) => void;
+    private constructor();
+    static getNewInstance(): UserHandBehaviorDetector;
+    start(): void;
+    stop(): void;
+    getHand(): HandType;
+    private handleOrientation;
+}
+export {};

package/dist/types/core/user-hand-behavior.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Defines identified device-holding orientation signatures: Left hand, Right hand, or Unknown.
+ */
+export type HandType = "left" | "right" | "unknown";
+/**
+ * Defines a structural interface for holding posture detectors.
+ */
+interface IHandDetector {
+    /**
+     * Starts continuous tracking and monitoring.
+     */
+    start(): void;
+    /**
+     * Terminated monitoring and frees resources.
+     */
+    stop(): void;
+    /**
+     * Resolves the current holding hand signature.
+     */
+    getHand(): HandType;
+    /**
+     * Custom hook event listener for state modifications.
+     */
+    onChange?: (hand: HandType) => void;
+}
+/**
+ * Typings for change listeners tracking device-holding hand states.
+ */
+export type UserHandBehaviorOnChange = (hand: HandType) => void;
+/**
+ * Core utility class that leverages continuous dynamic device gyroscope and accelerometer sensors
+ * to predict if the user is holding their phone in their left or right hand.
+ */
+export declare class UserHandBehaviorDetector implements IHandDetector {
+    private hand;
+    private started;
+    private samples;
+    private readonly SAMPLE_SIZE;
+    private readonly TILT_THRESHOLD;
+    private CHANGE_DELAY;
+    private lastReportedHand;
+    private pendingHand;
+    private changeTimer?;
+    private motionsOrientation;
+    private isInitial;
+    /**
+     * Dynamic event listener callback called when holding posture matches change thresholds.
+     */
+    onChange?: UserHandBehaviorOnChange;
+    /**
+     * Private constructor initializing standard sensor listeners and checking platform permissions.
+     */
+    private constructor();
+    /**
+     * Factory instantiator method to construct new instances of `UserHandBehaviorDetector`.
+     */
+    static getNewInstance(): UserHandBehaviorDetector;
+    /**
+     * Activates continuous data tracking and registers the initial posture feedback callback.
+     * @param callback Callback receiving left/right hand classifications.
+     */
+    start(callback?: UserHandBehaviorOnChange): void;
+    /**
+     * Terminates continuous gyroscope updates and resets buffers.
+     */
+    stop(): void;
+    /**
+     * Resolves the current holding hand prediction.
+     */
+    getHand(): HandType;
+    /**
+     * Sets the classification confirmation delay.
+     * @param delay Confirmation threshold timing in milliseconds.
+     */
+    setDelay(delay: number): void;
+    /**
+     * Internally flags classification match transitions and dispatches event listeners.
+     */
+    private confirmHandChange;
+    /**
+     * Throttles hand-holding prediction shifts to prevent rapid toggling noise.
+     */
+    private scheduleChange;
+    /**
+     * Continuous gyroscope feed event reader.
+     * Computes orientation averages and applies geometric thresholds to resolve holding fingers/thumb angles.
+     */
+    private handleOrientation;
+}
+export {};

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

@@ -0,0 +1,78 @@
+/**
+ * Standard union configuration types representing vibration duration parameters or custom pattern blocks.
+ */
+type VibrateOption = number | number[] | {
+    duration: number;
+    intensity: number;
+}[];
+/**
+ * Defines the contract for initiating haptic feedback and vibrations across web, mobile, and desktop systems.
+ */
+export interface IVibration {
+    /**
+     * Triggers a system haptic impact or vibration.
+     * @param duration A single value in milliseconds, a pattern array of durations, or objects defining detailed vibration parameters.
+     */
+    vibrate(duration: VibrateOption): Promise<void> | void;
+    /**
+     * Cancels any active hardware vibration patterns.
+     */
+    cancel(): void;
+}
+/**
+ * Web client haptic engine utilizing browser standard `navigator.vibrate` or `web-haptics` utilities.
+ */
+export declare class WebVibration implements IVibration {
+    private haptics;
+    /**
+     * Initializes the WebVibration instance and registers fallback web-haptics listeners.
+     */
+    constructor();
+    /**
+     * Triggers standard browser-native vibration patterns.
+     * @param vibration Haptic duration options.
+     */
+    vibrate(vibration: VibrateOption): Promise<void>;
+    /**
+     * Resets browser vibration activity by sending a zero-intensity trigger.
+     */
+    cancel(): void;
+}
+/**
+ * Electron desktop vibration controller fallback.
+ */
+export declare class ElectronVibration implements IVibration {
+    /**
+     * Mock vibration method warning users that desktop hardware lacks vibration motors.
+     */
+    vibrate(duration: VibrateOption): Promise<void> | void;
+    /**
+     * No-op cancel routine.
+     */
+    cancel(): void;
+}
+/**
+ * Singleton wrapper and router managing device vibrations across platforms.
+ */
+export declare class Vibration implements IVibration {
+    private static _instance;
+    private impl;
+    /**
+     * Private constructor to enforce standard singleton instantiation, resolving target driver at runtime.
+     */
+    private constructor();
+    /**
+     * Retrieves the global active, platform-resolved singleton vibration engine instance.
+     */
+    static get instance(): Vibration;
+    /**
+     * Triggers vibration using the platform resolved driver.
+     * @param duration A numeric duration in milliseconds or a structured pattern array.
+     */
+    vibrate(duration: number | number[]): void;
+    /**
+     * Cancels all active vibration outputs.
+     */
+    cancel(): void;
+}
+export {};

package/dist/types/dto/dto.d.ts

@@ -0,0 +1,9 @@
+export declare class ResponseDto<T> {
+    status: string;
+    message?: string;
+    payload: T;
+}
+export declare class RequestDto<T> {
+    payload: T;
+    constructor(payload: T);
+}

package/dist/types/dto/index.d.ts

@@ -0,0 +1,2 @@
+export * from './dto.js';
+export * from './pagination.dto.js';

package/dist/types/dto/pagination.dto.d.ts

@@ -0,0 +1,29 @@
+export type Pagination<T = {}> = {
+    skip: number;
+    limit: number;
+} & T;
+export type RequestIndexPaginationDto<Q = string, P = number, S = number, D = Record<any, any>> = {
+    query?: Q | null;
+    currentPage?: P | null;
+    pageSize?: S | null;
+} & D;
+export type IndexPagination<D> = {
+    data: D;
+    total: number;
+    size: number;
+    currentPage: number;
+    totalPages: number;
+};
+export type RequestCursorPaginationDto<Q = string, B = string, A = string, D = Record<any, any>> = {
+    query?: Q | null;
+    before?: B | null;
+    after?: A | null;
+} & D;
+export type CursorPagination<D, N> = {
+    data: D;
+    total: number;
+    hasNext?: boolean;
+    hasPrevious?: boolean;
+    nextCursor?: N;
+    prevCursor?: N;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+import './security/websecurity.js';
+export * from './core/index.js';
+export * from './utilities/index.js';
+export * from './dto/index.js';

package/dist/types/security/websecurity.d.ts

@@ -0,0 +1,4 @@
+declare const browserOrignalNavigator: Navigator;
+declare const browserOriginalLocalStorage: Storage;
+declare const browserOriginalSessionStorage: Storage;
+export { browserOrignalNavigator, browserOriginalLocalStorage, browserOriginalSessionStorage };

package/dist/types/utilities/index.d.ts

@@ -0,0 +1 @@
+export * from './version.util.js';

package/dist/types/utilities/plugin-expose.d.ts

@@ -0,0 +1,5 @@
+export declare class PluginAPI {
+    static expose<T>(pluginName: string, apiName: string, value: T): void;
+    static use<T>(pluginName: string, apiName: string): T;
+    static debug(): string[];
+}

package/dist/types/utilities/version.util.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Results dictionary returned by the version analyzer helper.
+ */
+interface VersionCheckResult {
+    /**
+     * Set to `true` if the compared version is mathematically newer.
+     */
+    isNewer: boolean;
+    /**
+     * Set to `true` if the compared version is mathematically older.
+     */
+    isOlder: boolean;
+    /**
+     * Set to `true` if the compared version matches exactly.
+     */
+    isSame: boolean;
+    /**
+     * Set to `true` if a major version bump has occurred (implying potential breaking API shifts).
+     */
+    isBreaking: boolean;
+}
+/**
+ * Utility class for parsing, checking, and comparing Semantic Versioning (SemVer) format strings.
+ */
+export declare class Version {
+    /**
+     * Compares two semantic version strings to determine their precedence.
+     * Supports basic SemVer standards (`major.minor.patch[-prerelease]`).
+     *
+     * @param version The source version string to compare.
+     * @param withVersion The target version string to compare against.
+     * @returns `1` if the source version is newer, `-1` if the target is newer, or `0` if they are identical.
+     */
+    static compare(version: string, withVersion: string): number;
+    /**
+     * Determines whether transitioning from an old version to a new version introduces breaking changes.
+     * Breaking changes are defined as a change in the major version component (e.g., `1.x.x` to `2.x.x`).
+     *
+     * @param oldV The existing/old version string.
+     * @param newV The incoming/new version string.
+     * @returns `true` if a major upgrade bump occurs, `false` otherwise.
+     */
+    static isBreakingChange(oldV: string, newV: string): boolean;
+    /**
+     * Performs a comprehensive version shift analysis, providing flag indicators.
+     *
+     * @param oldV The existing reference version.
+     * @param newV The target version to analyze.
+     * @returns A structured result state describing the upgrade relationship.
+     */
+    static analyzeVersion(oldV: string, newV: string): VersionCheckResult;
+}
+export {};

package/external-global-rollup-config.json

@@ -0,0 +1,61 @@
+{
+    "capacitor-file-picker": "CapacitorFilePicker",
+    "@capacitor/core": "Capacitor",
+    "@capacitor-community/bluetooth-le": "CapacitorBluetooth",
+    "@capacitor-community/camera-preview": "CapacitorCameraPreview",
+    "@capacitor/camera": "CapacitorCamera",
+    "@capacitor/clipboard": "CapacitorClipboard",
+    "@capacitor/filesystem": "CapacitorFileSystem",
+    "@capacitor/haptics": "CapacitorHaptic",
+    "@capacitor/local-notifications": "CapacitorLocalNotification",
+    "@capacitor/network": "CapacitorNetwork",
+    "@capacitor-community/sqlite": "CapacitorSQLite",
+    "@capacitor/device": "Device",
+    "@capacitor/geolocation": "CapacitorGeolocation",
+    "@capacitor-community/contacts": "CapacitorContacts",
+    "@awesome-cordova-plugins/screen-orientation": "CapacitorScreenOrientation",
+    "electron": "require('electron')",
+    "react": "React",
+    "react-dom": "ReactDOM",
+    "react-router-dom": "ReactRouterDOM",
+    "@tanstack/react-query": "ReactQuery",
+    "@tanstack/react-virtual": "ReactVirtual",
+    "@quan-erp-capacitor-pluigins/background-location": "BackgroundLocationService",
+    "@quan-erp/shared-frontend-core": "SharedFrontendCore",
+    "@quan-erp/shared-ui": "SharedUI",
+    "@quan-erp/shared-types": "SharedTypes",
+    "@quan-erp/web-thermal-printer": "QuanERPWebThermalPrinter",
+    "@quan-erp/base-frontend": "QuanERPBase",
+    "axios": "Axios",
+    "@icon-park/react": "IconPark",
+    "react-hook-form": "ReactForm",
+    "zod": "Zod",
+    "zustand": "Zustand",
+    "@hookform/resolvers": "HookFormResolver",
+    "dayjs": "Dayjs",
+    "sonner": "Sonner",
+    "date-fns": "DateFns",
+    "uuid": "Uuid",
+    "tailwind-merge": "TailwindMerge",
+    "lucide-react": "LucidReact",
+    "lodash": "Lodash",
+    "@tanstack/react-table": "TanStackReactTable",
+    "@xyflow/react": "ReactFlow",
+    "@dnd-kit/core": "DnDCore",
+    "@dnd-kit/sortable": "DnDSortable",
+    "@dnd-kit/utilities": "DnDUtilities",
+    "@dnd-kit/accessibility": "DnDAccessibility",
+    "exceljs": "ExcelJs",
+    "nextstepjs": "NextStepJs",
+    "react-qr-barcode-scanner": "ReactQRBarcodeScanner",
+    "@zxing/library": "ZxingLibrary",
+    "@zxing/text-encoding": "ZxingTextEncoding",
+    "react-photo-view": "ReactPhotoView",
+    "web-haptics": "WebHaptics",
+    "recharts": "Recharts",
+    "html2canvas": "Html2Canvas",
+    "@fingerprintjs/fingerprintjs": "FingerprintJS",
+    "firebase/messaging": "FirebaseMessaging",
+    "firebase": "Firebase",
+    "qrcode.react": "QrcodeReact"
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+    "name": "@quan-erp/shared-frontend-core",
+    "version": "1.0.0",
+    "description": "",
+    "scripts": {
+        "publish:registry": "npm run build && npm publish --tag beta",
+        "publish:npm-registry": "npm run build && npm publish --access public --registry https://registry.npmjs.org/ --@quan-erp:registry=https://registry.npmjs.org/",
+        "test": "echo \"Error: no test specified\" && exit 1",
+        "build": "rollup -c",
+        "dev": "rollup -c -w"
+    },
+    "keywords": [],
+    "author": "jianshangquan",
+    "license": "UNLICENSED",
+    "type": "module",
+    "files": [
+        "dist",
+        "./external-global-rollup-config.json",
+        "!**/*.map"
+    ],
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs",
+            "types": "./dist/types/index.d.ts"
+        },
+        "./external-global-rollup-config.json": "./external-global-rollup-config.json"
+    },
+    "devDependencies": {
+        "@rollup/plugin-alias": "^6.0.0",
+        "@rollup/plugin-commonjs": "^29.0.0",
+        "@rollup/plugin-json": "^6.1.0",
+        "@rollup/plugin-node-resolve": "^16.0.3",
+        "@rollup/plugin-terser": "^0.4.4",
+        "@rollup/plugin-typescript": "^12.3.0",
+        "@types/bcrypt": "^6.0.0",
+        "@types/cors": "^2.8.19",
+        "@types/express": "^5.0.5",
+        "@types/node": "^24.9.2",
+        "@types/node-cron": "^3.0.11",
+        "@types/redis": "^4.0.10",
+        "builtin-modules": "^5.0.0",
+        "javascript-obfuscator": "^4.1.1",
+        "rollup": "^4.62.2",
+        "tslib": "^2.8.1",
+        "typescript": "^6.0.2"
+    },
+    "peerDependencies": {
+        "@awesome-cordova-plugins/screen-orientation": "^8.1.0",
+        "@capacitor-community/bluetooth-le": "^7.2.0",
+        "@capacitor-community/camera-preview": "^7.0.2",
+        "@capacitor-community/sqlite": "^7.0.2",
+        "@capacitor/camera": "^7.0.2",
+        "@capacitor/clipboard": "^7.0.2",
+        "@capacitor/device": "^7.0.2",
+        "@capacitor/filesystem": "^7.1.4",
+        "@capacitor/geolocation": "^7.1.6",
+        "@capacitor/haptics": "^7.0.2",
+        "@capacitor/local-notifications": "^7.0.3",
+        "@capacitor/network": "^7.0.2",
+        "@capacitor/preferences": "^7.0.2",
+        "@fingerprintjs/fingerprintjs": "^4.6.2",
+        "@quan-erp-capacitor-pluigins/background-location": "^0.0.1-beta.1",
+        "@quan-erp/shared-types": "^1.0.0-beta.65",
+        "@tanstack/react-query": "^5.90.10",
+        "axios": "^1.13.2",
+        "react": "19.2.6",
+        "react-dom": "19.2.6",
+        "react-router-dom": "19.2.6",
+        "web-haptics": "^0.0.6",
+        "zustand": "^5.0.9"
+    }
+}