@microblink/blinkid-ux-manager 7.0.0-next.4 → 7.0.0-next.7

package/README.md

@@ -0,0 +1,9 @@
+# BlinkID UX Manager
+
+`@microblink/blinkid-ux-manager` parses the results from `@microblink/blinkid-core` and guides the user through the scanning process.
+
+It also controls `@microblink/camera-manager` when it's required during the scanning process.
+
+This package provides a headless component and a UI component which is the feedback overlay used in the camera manager component.
+
+For details, check out the documentation at https://github.com/BlinkID/blinkid-next-web

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@microblink/blinkid-ux-manager",
-  "version": "7.0.0-next.4",
-  "author": "",
+  "version": "7.0.0-next.7",
+  "author": "Microblink",
   "type": "module",
   "main": "./dist/blinkid-ux-manager.js",
   "module": "./dist/blinkid-ux-manager.js",
@@ -11,12 +11,17 @@
     "types"
   ],
   "dependencies": {
-    "@microblink/blinkid-core": "^7.0.0-next.4",
-    "@microblink/camera-manager": "^7.0.0-next.4"
+    "@microblink/blinkid-core": "^7.0.0-next.7",
+    "@microblink/camera-manager": "^7.0.0-next.7"
   },
   "access": "public",
   "registry": "https://registry.npmjs.org/",
   "types": "./types/index.rollup.d.ts",
+  "homepage": "https://github.com/BlinkID/blinkid-next-web",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BlinkID/blinkid-next-web.git"
+  },
   "exports": {
     ".": {
       "types": "./types/index.rollup.d.ts",

package/types/index.rollup.d.ts

@@ -0,0 +1,219 @@
+import { BlinkIdCore } from '@microblink/blinkid-core';
+import { BlinkIdResult } from '@microblink/blinkid-core';
+import type { CameraManager } from '@microblink/camera-manager';
+import { CameraManagerComponent } from '@microblink/camera-manager';
+import { FrameAnalysisResult } from '@microblink/blinkid-core';
+
+/**
+ * Copyright (c) 2025 Microblink Ltd. All rights reserved.
+ */
+/**
+ * BlinkID processing error. These errors are usually unrecoverable and require
+ * the user to retry the scanning process.
+ */
+export declare type BlinkIdProcessingError = "timeout" | "unsupported-document" | "unknown";
+
+export declare type BlinkIdReticleType = "searching" | "processing" | "error" | "done" | "flip";
+
+export declare type BlinkIdUiState = BlinkIdUiStateMap[keyof BlinkIdUiStateMap];
+
+export declare type BlinkIdUiStateKey = "PROCESSING" | "SIDE_CAPTURED" | "DOCUMENT_CAPTURED" | "SENSING_FRONT" | "SENSING_BACK" | "LOW_QUALITY_FRONT" | "LOW_QUALITY_BACK" | "DOCUMENT_FRAMING_CAMERA_TOO_FAR" | "DOCUMENT_FRAMING_CAMERA_TOO_CLOSE" | "DOCUMENT_FRAMING_CAMERA_ANGLE_TOO_STEEP" | "DOCUMENT_TOO_CLOSE_TO_FRAME_EDGE" | "BLUR_DETECTED" | "GLARE_DETECTED" | "OCCLUDED" | "SCAN_BARCODE" | "WRONG_SIDE";
+
+/**
+ * Extended UI state for BlinkID.
+ */
+export declare type BlinkIdUiStateMap = {
+    [K in BlinkIdUiStateKey]: UiState & {
+        key: K;
+        reticleType: BlinkIdReticleType;
+    };
+};
+
+export declare const blinkIdUiStateMap: BlinkIdUiStateMap;
+
+/**
+ * Manages the UX of the BlinkID SDK.
+ */
+export declare class BlinkIdUxManager {
+    #private;
+    cameraManager: CameraManager;
+    blinkIdCore: BlinkIdCore;
+    uiState: BlinkIdUiState;
+    errorState?: BlinkIdProcessingError;
+    rawUiStateKey: BlinkIdUiStateKey;
+    feedbackStabilizer: FeedbackStabilizer<typeof blinkIdUiStateMap>;
+    clearScanTimeout: () => void;
+    /**
+     * Adds a callback function to be executed when the UI state changes.
+     * @param callback - Function to be called when UI state changes. Receives the new UI state as parameter.
+     * @returns A cleanup function that removes the callback when called.
+     * @example
+     * const cleanup = manager.addOnUiStateChangedCallback((newState) => {
+     *   console.log('UI state changed to:', newState);
+     * });
+     *
+     * cleanup();
+     */
+    addOnUiStateChangedCallback(callback: (uiState: BlinkIdUiState) => void): () => void;
+    /**
+     * Registers a callback function to be called when a scan result is available.
+     * @param callback - A function that will be called with the scan result.
+     * @returns A cleanup function that, when called, will remove the registered callback.
+     *
+     * @example
+     *
+     * const cleanup = manager.addOnResultCallback((result) => {
+     *   console.log('Scan result:', result);
+     * });
+     *
+     * // Later, to remove the callback:
+     * cleanup();
+     */
+    addOnResultCallback(callback: (result: BlinkIdResult) => void): () => void;
+    /**
+     * Registers a callback function to be called when a frame is processed.
+     * @param callback - A function that will be called with the frame analysis result.
+     * @returns A cleanup function that, when called, will remove the registered callback.
+     *
+     * @example
+     * const cleanup = manager.addOnFrameProcessCallback((frameResult) => {
+     *   console.log('Frame processed:', frameResult);
+     * });
+     *
+     * // Later, to remove the callback:
+     * cleanup();
+     */
+    addOnFrameProcessCallback(callback: (frameResult: FrameAnalysisResult) => void): () => void;
+    /**
+     * Registers a callback function to be called when an error occurs during processing.
+     * @param callback - A function that will be called with the error state.
+     * @returns A cleanup function that, when called, will remove the registered callback.
+     *
+     * @example
+     * const cleanup = manager.addOnErrorCallback((error) => {
+     *   console.error('Processing error:', error);
+     * });
+     *
+     * // Later, to remove the callback:
+     * cleanup();
+     */
+    addOnErrorCallback(callback: (errorState: BlinkIdProcessingError) => void): () => void;
+    /**
+     * Registers a callback function to be called when the user cancels the scanning process.
+     * @param callback - A function that will be called with the cancellation reason.
+     * @returns A cleanup function that, when called, will remove the registered callback.
+     *
+     * @example
+     * const cleanup = manager.addOnUserCancelCallback((reason) => {
+     *   console.log('User cancelled scan:', reason);
+     * });
+     *
+     * // Later, to remove the callback:
+     * cleanup();
+     */
+    addOnUserCancelCallback(callback: (reason: unknown) => void): () => void;
+    constructor(cameraManager: CameraManager, blinkIdCore: BlinkIdCore);
+    /**
+     * Set the duration of the timeout in milliseconds.
+     */
+    setTimeoutDuration(duration: number): void;
+    handleUiStateChange(uiState: BlinkIdUiState): Promise<void>;
+}
+
+export declare function createBlinkIdFeedbackUi(blinkIdUxManager: BlinkIdUxManager, cameraManagerComponent: CameraManagerComponent, options?: FeedbackUiOptions): () => void;
+
+/**
+ * Copyright (c) 2025 Microblink Ltd. All rights reserved.
+ */
+declare const _default: {
+    readonly scan_the_front_side: "Scan the front side of the document";
+    readonly flip_document: "Flip the document";
+    readonly scan_the_back_side: "Scan the back side of the document";
+    readonly scan_the_barcode: "Scan the barcode";
+    readonly scanning_wrong_side: "Scanning wrong side";
+    readonly move_closer: "Move closer";
+    readonly move_farther: "Move farther";
+    readonly camera_angle_too_steep: "Keep document parallel to phone";
+    readonly document_too_close_to_edge: "Move farther";
+    readonly blur_detected: "Keep document and phone still";
+    readonly glare_detected: "Tilt or move document to remove reflection";
+    readonly occluded: "Keep the document fully visible";
+};
+
+export declare class FeedbackStabilizer<SdkSpecificStateMap extends UiStateMap> {
+    private initialKey;
+    private uiStateMap;
+    private timeWindow;
+    private decayRate;
+    private eventQueue;
+    /** this is a special queue as min duration of the event can be longer than the `timeWindow` */
+    private singleEventQueue;
+    private currentKey;
+    private currentStateStartTime;
+    private summedScores;
+    private scoreBoard;
+    get currentState(): SdkSpecificStateMap[`${Extract<keyof SdkSpecificStateMap, string | number>}`];
+    getEventQueue(): UiStateEvent[];
+    getScores(): Record<string, number>;
+    getScoreBoard(): Record<string, number[]>;
+    setTimeWindow(timeWindow: number): void;
+    constructor(uiStateMap: SdkSpecificStateMap, initialKey: StringKeyOf<SdkSpecificStateMap>, timeWindow?: number, decayRate?: number);
+    reset(): void;
+    canShowNewUiState: () => boolean;
+    /**
+     * Returns a weighted UI state based on the history
+     */
+    getNewUiState(incomingUiStateKey: StringKeyOf<SdkSpecificStateMap>): SdkSpecificStateMap[StringKeyOf<SdkSpecificStateMap>];
+}
+
+export declare type FeedbackUiOptions = {
+    localizationStrings?: Partial<LocalizationStrings>;
+    /**
+     * If set to `true`, the BlinkID instance will not be terminated when the
+     * feedback UI is unmounted.
+     *
+     * @defaultValue false
+     */
+    preserveSdkInstance?: boolean;
+};
+
+/**
+ * Used temporarily as processing status was added after the tests were written
+ */
+export declare type FrameAnalysisResultWithoutProcessingStatus = Omit<FrameAnalysisResult, "processingStatus">;
+
+export declare function getUiStateKeyFromFrameResult(frameAnalysisResult: FrameAnalysisResultWithoutProcessingStatus): BlinkIdUiStateKey;
+
+export declare type LocaleRecord = typeof _default;
+
+export declare type LocalizationStrings = {
+    [K in keyof LocaleRecord]: LocaleRecord[K] | (string & {});
+};
+
+declare type StringKeyOf<BaseType> = `${Extract<keyof BaseType, string | number>}`;
+
+export declare type UiState = {
+    key: string;
+    minDuration: number;
+    /**
+     * If true, the event will be emmited once the previous event is done.
+     * It's not going through the averaging process
+     */
+    singleEmit?: boolean;
+    initialWeight?: number;
+};
+
+export declare type UiStateEvent = {
+    key: string;
+    timeStamp: DOMHighResTimeStamp;
+    currentWeight: number;
+    /**
+     * If true, the event will be emmited once the previous event is done.
+     * It's not going through the averaging process
+     */
+    singleEmit?: boolean;
+};
+
+export declare type UiStateMap = Record<string, UiState>;
+
+export { }