@microblink/blinkid-ux-manager 7.3.2 → 7.4.1

package/dist/blinkid-ux-manager.js

@@ -698,33 +698,75 @@ function getKeyWithHighestValue(obj) {
   return maxKey;
 }
 class FeedbackStabilizer {
+  /** The initial key. */
   initialKey;
+  /** The UI state map. */
   uiStateMap;
+  /** Time window (in ms) for considering UI state events. */
   timeWindow = 3e3;
+  /** The decay rate. */
+  /** Rate at which event weights decay over time */
   decayRate = 0.95;
+  /** Queue of regular UI state events within the time window */
   eventQueue = [];
-  /** this is a special queue as min duration of the event can be longer than the `timeWindow` */
+  /** Special queue for single-emit events that bypass normal stabilization */
   singleEventQueue = [];
-  // used for tracking current state
+  /** Currently displayed state key */
   currentKey;
+  /** Timestamp when current state started displaying */
   currentStateStartTime = performance.now();
+  /** Accumulated scores for each state in current calculation */
   summedScores = {};
+  /** History of scores for each state */
   scoreBoard = {};
+  /**
+   * Gets the currently active UI state configuration.
+   *
+   * @returns The currently active UI state configuration.
+   */
   get currentState() {
     return this.uiStateMap[this.currentKey];
   }
+  /**
+   * Gets a copy of the current event queue for debugging.
+   *
+   * @returns A copy of the current event queue.
+   */
   getEventQueue() {
     return structuredClone(this.eventQueue);
   }
+  /**
+   * Gets the current summed scores for each state.
+   *
+   * @returns The current summed scores for each state.
+   */
   getScores() {
     return structuredClone(this.summedScores);
   }
+  /**
+   * Gets the score history for each state.
+   *
+   * @returns The score history for each state.
+   */
   getScoreBoard() {
     return structuredClone(this.scoreBoard);
   }
+  /**
+   * Updates the time window used for state stabilization
+   *
+   * @param timeWindow - New time window in milliseconds
+   */
   setTimeWindow(timeWindow) {
     this.timeWindow = timeWindow;
   }
+  /**
+   * Creates a new FeedbackStabilizer instance.
+   *
+   * @param uiStateMap - Map of all possible UI states and their configurations
+   * @param initialKey - Key of the initial UI state to display
+   * @param timeWindow - Optional custom time window (in ms) for state averaging
+   * @param decayRate - Optional custom decay rate for event weights
+   */
   constructor(uiStateMap, initialKey, timeWindow, decayRate) {
     this.uiStateMap = uiStateMap;
     this.initialKey = initialKey;
@@ -737,17 +779,35 @@ class FeedbackStabilizer {
       this.decayRate = decayRate;
     }
   }
+  /**
+   * Resets the stabilizer to its initial state.
+   *
+   * @returns The initial state.
+   */
   reset() {
     this.currentKey = this.initialKey;
     this.eventQueue = [];
     this.singleEventQueue = [];
     this.summedScores = {};
   }
+  /**
+   * Checks if enough time has passed to show a new UI state
+   *
+   * @returns true if the current state's minimum duration has elapsed
+   */
   canShowNewUiState = () => {
     return performance.now() - this.currentStateStartTime >= this.currentState.minDuration;
   };
   /**
-   * Returns a weighted UI state based on the history
+   * Processes a new UI state event and determines the state to display.
+   *
+   * This method:
+   * 1. Handles single-emit events that bypass normal stabilization
+   * 2. Maintains a time-windowed queue of regular events
+   * 3. Applies temporal averaging with decay to determine the winning state
+   *
+   * @param incomingUiStateKey - Key of the new UI state event
+   * @returns The UI state that should be displayed.
    */
   getNewUiState(incomingUiStateKey) {
     const now = performance.now();
@@ -814,8 +874,11 @@ async function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 class BlinkIdUxManager {
+  /** The success process result. */
   #successProcessResult;
+  /** Whether the thread is busy. */
   #threadBusy = false;
+  /** The scanning session timeout ID. */
   #timeoutId;
   /** Timeout duration in ms for the scanning session. If null, timeout won't be triggered ever. */
   #timeoutDuration = 1e4;
@@ -826,12 +889,24 @@ class BlinkIdUxManager {
   /** Time in ms before the help tooltip is hidden. If null, tooltip won't be auto hidden. */
   #helpTooltipHideDelay = 5e3;
   // 5s
+  /** The callbacks for when the UI state changes. */
   #onUiStateChangedCallbacks = /* @__PURE__ */ new Set();
+  /** The callbacks for when a scan result is available. */
   #onResultCallbacks = /* @__PURE__ */ new Set();
+  /** The callbacks for when a frame is processed. */
   #onFrameProcessCallbacks = /* @__PURE__ */ new Set();
+  /** The callbacks for when an error occurs during processing. */
   #onErrorCallbacks = /* @__PURE__ */ new Set();
+  /** The callbacks for when a document is filtered. */
   #onDocumentFilteredCallbacks = /* @__PURE__ */ new Set();
+  /** The document class filter. */
   #documentClassFilter;
+  /**
+   * The constructor for the BlinkIdUxManager class.
+   *
+   * @param cameraManager - The camera manager.
+   * @param scanningSession - The scanning session.
+   */
   constructor(cameraManager, scanningSession) {
     this.cameraManager = cameraManager;
     this.scanningSession = scanningSession;
@@ -864,56 +939,58 @@ class BlinkIdUxManager {
         }
       }
     );
-    const unsubscribeVideoObserver = cameraManager.subscribe(
+    const unsubscribeVideoObserver = this.cameraManager.subscribe(
       (s2) => s2.videoElement,
       (videoElement) => {
         if (!videoElement) {
-          console.debug("Removing timeout subscriptions");
+          console.debug("Removing camera manager subscriptions");
           this.reset();
           unsubscribeVideoObserver();
           unsubscribePlaybackState();
         }
       }
     );
-    cameraManager.addFrameCaptureCallback(this.#frameCaptureCallback);
+    this.cameraManager.addFrameCaptureCallback(this.#frameCaptureCallback);
   }
   /**
-   * Indicates whether the UI should display the demo overlay. Controlled by the license property.
+   * Indicates whether the UI should display the demo overlay. Controlled by the
+   * license property.
    */
   getShowDemoOverlay() {
     return this.showDemoOverlay;
   }
   /**
-   * Indicates whether the UI should display the production overlay. Controlled by the license property.
+   * Indicates whether the UI should display the production overlay. Controlled by
+   * the license property.
    */
   getShowProductionOverlay() {
     return this.showProductionOverlay;
   }
   /**
    * Returns the timeout duration in ms. Null if timeout won't be triggered ever.
-   * @returns The timeout duration in ms.
    */
   getTimeoutDuration() {
     return this.#timeoutDuration;
   }
   /**
    * Returns the time in ms before the help tooltip is shown. Null if tooltip won't be auto shown.
-   * @returns The time in ms before the help tooltip is shown.
    */
   getHelpTooltipShowDelay() {
     return this.#helpTooltipShowDelay;
   }
   /**
    * Returns the time in ms before the help tooltip is hidden. Null if tooltip won't be auto hidden.
-   * @returns The time in ms before the help tooltip is hidden.
    */
   getHelpTooltipHideDelay() {
     return this.#helpTooltipHideDelay;
   }
   /**
    * 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.
+   *
+   * @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);
@@ -929,8 +1006,10 @@ class BlinkIdUxManager {
   }
   /**
    * 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.
+   * @returns A cleanup function that, when called, will remove the registered
+   * callback.
    *
    * @example
    *
@@ -949,8 +1028,11 @@ class BlinkIdUxManager {
   }
   /**
    * Registers a callback function to filter document classes.
-   * @param callback - A function that will be called with the document class info.
-   * @returns A cleanup function that, when called, will remove the registered callback.
+   *
+   * @param callback - A function that will be called with the document class
+   * info.
+   * @returns A cleanup function that, when called, will remove the registered
+   * callback.
    *
    * @example
    * const cleanup = manager.addDocumentClassFilter((docClassInfo) => {
@@ -968,8 +1050,11 @@ class BlinkIdUxManager {
   }
   /**
    * 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.
+   *
+   * @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) => {
@@ -986,9 +1071,12 @@ class BlinkIdUxManager {
     };
   }
   /**
-   * Registers a callback function to be called when an error occurs during processing.
+   * 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.
+   * @returns A cleanup function that, when called, will remove the registered
+   * callback.
    *
    * @example
    * const cleanup = manager.addOnErrorCallback((error) => {
@@ -1004,6 +1092,11 @@ class BlinkIdUxManager {
       this.#onErrorCallbacks.delete(callback);
     };
   }
+  /**
+   * Invokes the onError callbacks.
+   *
+   * @param errorState - The error state.
+   */
   #invokeOnErrorCallbacks = (errorState) => {
     for (const callback of this.#onErrorCallbacks) {
       try {
@@ -1013,12 +1106,33 @@ class BlinkIdUxManager {
       }
     }
   };
+  /**
+   * Registers a callback function to be called when a document is filtered.
+   *
+   * @param callback - A function that will be called with the document class
+   * info.
+   * @returns A cleanup function that, when called, will remove the registered
+   * callback.
+   *
+   * @example
+   * const cleanup = manager.addOnDocumentFilteredCallback((docClassInfo) => {
+   *   console.log('Document filtered:', docClassInfo);
+   * });
+   *
+   * // Later, to remove the callback:
+   * cleanup();
+   */
   addOnDocumentFilteredCallback(callback) {
     this.#onDocumentFilteredCallbacks.add(callback);
     return () => {
       this.#onDocumentFilteredCallbacks.delete(callback);
     };
   }
+  /**
+   * Invokes the onDocumentFiltered callbacks.
+   *
+   * @param documentClassInfo - The document class info.
+   */
   #invokeOnDocumentFilteredCallbacks = (documentClassInfo) => {
     for (const callback of this.#onDocumentFilteredCallbacks) {
       try {
@@ -1028,6 +1142,11 @@ class BlinkIdUxManager {
       }
     }
   };
+  /**
+   * Invokes the onResult callbacks.
+   *
+   * @param result - The scan result.
+   */
   #invokeOnResultCallbacks = (result) => {
     for (const callback of this.#onResultCallbacks) {
       try {
@@ -1037,6 +1156,11 @@ class BlinkIdUxManager {
       }
     }
   };
+  /**
+   * Invokes the onFrameProcess callbacks.
+   *
+   * @param frameResult - The frame result.
+   */
   #invokeOnFrameProcessCallbacks = (frameResult) => {
     for (const callback of this.#onFrameProcessCallbacks) {
       try {
@@ -1046,6 +1170,11 @@ class BlinkIdUxManager {
       }
     }
   };
+  /**
+   * Invokes the onUiStateChanged callbacks.
+   *
+   * @param uiState - The UI state.
+   */
   #invokeOnUiStateChangedCallbacks = (uiState) => {
     for (const callback of this.#onUiStateChangedCallbacks) {
       try {
@@ -1055,6 +1184,33 @@ class BlinkIdUxManager {
       }
     }
   };
+  /**
+   * Handles document class filtering if configured.
+   * Returns true if the document should be processed, false if it was filtered out.
+   *
+   * @param processResult - The result of processing the current frame
+   * @returns boolean indicating if the document should be processed
+   */
+  #handleDocumentClassFiltering(processResult) {
+    if (this.#documentClassFilter === void 0) {
+      return true;
+    }
+    const documentClassInfo = this.#extractDocumentClassInfo(processResult);
+    if (!this.#isDocumentClassified(documentClassInfo) || this.#documentClassFilter(documentClassInfo)) {
+      return true;
+    }
+    this.cameraManager.stopFrameCapture();
+    this.#invokeOnDocumentFilteredCallbacks(documentClassInfo);
+    this.#invokeOnFrameProcessCallbacks(processResult);
+    return false;
+  }
+  /**
+   * The frame capture callback. This is the main function that is called when a
+   * new frame is captured. It is responsible for processing the frame and
+   * updating the UI state.
+   *
+   * @param imageData - The image data.
+   */
   #frameCaptureCallback = async (imageData) => {
     if (this.#threadBusy) {
       return;
@@ -1077,22 +1233,23 @@ class BlinkIdUxManager {
     }
     const processResult = await this.scanningSession.process(imageDataLike);
     this.#threadBusy = false;
-    if (this.#documentClassFilter !== void 0) {
-      const documentClassInfo = this.#extractDocumentClassInfo(processResult);
-      if (this.#isDocumentClassified(documentClassInfo) && !this.#documentClassFilter(documentClassInfo)) {
-        this.#invokeOnDocumentFilteredCallbacks(documentClassInfo);
-      }
+    if (!this.#handleDocumentClassFiltering(processResult)) {
+      return processResult.arrayBuffer;
     }
     this.#handleUiStateChanges(processResult);
     this.#invokeOnFrameProcessCallbacks(processResult);
     return processResult.arrayBuffer;
   };
   /**
-   * Sets the duration after which the scanning session will timeout. The timeout can occur in various scenarios
-   * and may be restarted by different scanning events.
+   * Sets the duration after which the scanning session will timeout. The
+   * timeout can occur in various scenarios and may be restarted by different
+   * scanning events.
    *
-   * @param duration The timeout duration in milliseconds. If null, timeout won't be triggered ever.
-   * @param setHelpTooltipShowDelay If true, also sets the help tooltip show delay to half of the provided duration. If timeout duration is null, help tooltip show delay will be set to null. Defaults to true.
+   * @param duration The timeout duration in milliseconds. If null, timeout won't
+   * be triggered ever.
+   * @param setHelpTooltipShowDelay If true, also sets the help tooltip show
+   * delay to half of the provided duration. If timeout duration is null, help
+   * tooltip show delay will be set to null. Defaults to true.
    * @throws {Error} Throws an error if duration is less than or equal to 0 when not null.
    */
   setTimeoutDuration(duration, setHelpTooltipShowDelay = true) {
@@ -1107,8 +1264,11 @@ class BlinkIdUxManager {
   /**
    * Sets the duration in milliseconds before the help tooltip is shown.
    * A value of null means the help tooltip will not be auto shown.
-   * @param duration The duration in milliseconds before the help tooltip is shown. If null, tooltip won't be auto shown.
-   * @throws {Error} Throws an error if duration is less than or equal to 0 when not null.
+   *
+   * @param duration The duration in milliseconds before the help tooltip is
+   * shown. If null, tooltip won't be auto shown.
+   * @throws {Error} Throws an error if duration is less than or equal to 0 when
+   * not null.
    */
   setHelpTooltipShowDelay(duration) {
     if (duration !== null && duration <= 0) {
@@ -1119,8 +1279,11 @@ class BlinkIdUxManager {
   /**
    * Sets the duration in milliseconds before the help tooltip is hidden.
    * A value of null means the help tooltip will not be auto hidden.
-   * @param duration The duration in milliseconds before the help tooltip is hidden. If null, tooltip won't be auto hidden.
-   * @throws {Error} Throws an error if duration is less than or equal to 0 when not null.
+   *
+   * @param duration The duration in milliseconds before the help tooltip is
+   * hidden. If null, tooltip won't be auto hidden.
+   * @throws {Error} Throws an error if duration is less than or equal to 0 when
+   * not null.
    */
   setHelpTooltipHideDelay(duration) {
     if (duration !== null && duration <= 0) {
@@ -1128,6 +1291,11 @@ class BlinkIdUxManager {
     }
     this.#helpTooltipHideDelay = duration;
   }
+  /**
+   * Sets the timeout for the scanning session.
+   *
+   * @param uiState - The UI state.
+   */
   #setTimeout = (uiState) => {
     if (this.#timeoutDuration === null) {
       console.debug("⏳🟢 timeout duration is null, not starting timeout");
@@ -1139,10 +1307,16 @@ class BlinkIdUxManager {
       console.debug("⏳🟢 timeout triggered");
       this.cameraManager.stopFrameCapture();
       this.#invokeOnErrorCallbacks("timeout");
-      this.feedbackStabilizer.reset();
-      this.uiState = this.feedbackStabilizer.currentState;
+      this.#resetUiState();
     }, this.#timeoutDuration);
   };
+  /**
+   * Handles the UI state changes. This is the main function that is called
+   * when a new frame is processed. It is responsible for updating the UI state,
+   * handling the timeout, and handling the first side captured states.
+   *
+   * @param processResult - The process result.
+   */
   #handleUiStateChanges = (processResult) => {
     const nextUiStateKey = getUiStateKey(
       processResult,
@@ -1160,7 +1334,14 @@ class BlinkIdUxManager {
     this.#invokeOnUiStateChangedCallbacks(newUiState);
     void this.#handleUiStateChange(newUiState);
   };
-  // Side-effects are handled here
+  /**
+   * Handles the UI state change. This is the main function that is called
+   * when a new UI state is set. It is responsible for handling the timeout,
+   * handling the first side captured states, and handling the UNSUPPORTED_DOCUMENT
+   * state.
+   *
+   * @param uiState - The UI state.
+   */
   #handleUiStateChange = async (uiState) => {
     if (this.#timeoutDuration !== null) {
       this.#setTimeout(uiState);
@@ -1185,14 +1366,34 @@ class BlinkIdUxManager {
       return;
     }
   };
+  /**
+   * Extracts the document class info from the process result.
+   *
+   * @param processResult - The process result.
+   * @returns The document class info.
+   */
   #extractDocumentClassInfo(processResult) {
     return processResult.inputImageAnalysisResult.documentClassInfo;
   }
+  /**
+   * Checks if the document class is classified.
+   *
+   * @param documentClassInfo - The document class info.
+   * @returns Whether the document class is classified.
+   */
   #isDocumentClassified(documentClassInfo) {
     return documentClassInfo?.country !== void 0 && documentClassInfo?.type !== void 0;
   }
   /**
-   * Clears any active timeout.
+   * Resets the feedback stabilizer and invokes the onUiStateChanged callbacks.
+   */
+  #resetUiState = () => {
+    this.feedbackStabilizer.reset();
+    this.uiState = this.feedbackStabilizer.currentState;
+    this.#invokeOnUiStateChangedCallbacks(this.uiState);
+  };
+  /**
+   * Clears the scanning session timeout.
    */
   clearScanTimeout = () => {
     if (!this.#timeoutId) {
@@ -1202,11 +1403,31 @@ class BlinkIdUxManager {
     window.clearTimeout(this.#timeoutId);
   };
   /**
-   * Resets the manager and clears all callbacks.
+   * Resets the scanning session.
    *
-   * Does not reset the camera manager or the BlinkID core instance.
+   * @param startFrameCapture Whether to start frame processing.
+   */
+  async resetScanningSession(startFrameCapture = true) {
+    console.debug("🔁 Resetting scanning session");
+    this.clearScanTimeout();
+    this.#threadBusy = false;
+    this.#successProcessResult = void 0;
+    this.#resetUiState();
+    await this.scanningSession.reset();
+    if (startFrameCapture) {
+      if (!this.cameraManager.isActive) {
+        await this.cameraManager.startCameraStream();
+      }
+      await this.cameraManager.startFrameCapture();
+    }
+  }
+  /**
+   * Resets the BlinkIdUxManager. Clears all callbacks.
+   *
+   * Does not reset the camera manager or the scanning session.
    */
   reset() {
+    console.debug("🔁 Resetting BlinkIdUxManager");
     this.clearScanTimeout();
     this.#threadBusy = false;
     this.#successProcessResult = void 0;
@@ -2874,6 +3095,9 @@ const BlinkIdUiStoreProvider = (props) => {
     showOnboardingGuide: props.showOnboardingGuide,
     showHelpTooltipTimeout: props.showHelpTooltipTimeout,
     showHelpButton: props.showHelpButton,
+    showDocumentFilteredModal: props.showDocumentFilteredModal,
+    showTimeoutModal: props.showTimeoutModal,
+    showUnsupportedDocumentModal: props.showUnsupportedDocumentModal,
     dismountFeedbackUi: props.dismountFeedbackUi
     /* eslint-enable solid/reactivity */
   });
@@ -3532,7 +3756,8 @@ const ErrorModal = (props) => {
   } = useBlinkIdUiStore();
   const hideModal = () => {
     updateStore({
-      errorState: void 0
+      errorState: void 0,
+      documentFiltered: false
     });
   };
   const dismountCameraManagerUi = () => {
@@ -3541,7 +3766,7 @@ const ErrorModal = (props) => {
   const handlePrimaryClick = async () => {
     hideModal();
     if (props.shouldResetScanningSession) {
-      await store.blinkIdUxManager.scanningSession.reset();
+      await store.blinkIdUxManager.resetScanningSession(false);
     }
     await store.blinkIdUxManager.cameraManager.startFrameCapture();
   };
@@ -3600,13 +3825,12 @@ const BlinkIdFeedbackUi = (props) => {
     onCleanup(() => errorCallbackCleanup());
   });
   createEffect(() => {
-    const errorCallbackCleanup = store.blinkIdUxManager.addOnDocumentFilteredCallback((_2) => {
-      store.blinkIdUxManager.cameraManager.stopFrameCapture();
+    const documentFilteredCallbackCleanup = store.blinkIdUxManager.addOnDocumentFilteredCallback((_2) => {
       updateStore({
         documentFiltered: true
       });
     });
-    onCleanup(() => errorCallbackCleanup());
+    onCleanup(() => documentFilteredCallbackCleanup());
   });
   const playbackState = createWithSignal(cameraManagerStore)((s2) => s2.playbackState);
   const isProcessing = () => playbackState() === "capturing";
@@ -3646,7 +3870,7 @@ const BlinkIdFeedbackUi = (props) => {
               get children() {
                 return [createComponent(Match, {
                   get when() {
-                    return store.errorState === "timeout";
+                    return store.showTimeoutModal && store.errorState === "timeout";
                   },
                   get children() {
                     return createComponent(ErrorModal, {
@@ -3661,7 +3885,7 @@ const BlinkIdFeedbackUi = (props) => {
                   }
                 }), createComponent(Match, {
                   get when() {
-                    return uiState().key === "UNSUPPORTED_DOCUMENT";
+                    return memo(() => !!store.showUnsupportedDocumentModal)() && uiState().key === "UNSUPPORTED_DOCUMENT";
                   },
                   get children() {
                     return createComponent(ErrorModal, {
@@ -3676,7 +3900,7 @@ const BlinkIdFeedbackUi = (props) => {
                   }
                 }), createComponent(Match, {
                   get when() {
-                    return store.documentFiltered;
+                    return store.showDocumentFilteredModal && store.documentFiltered;
                   },
                   get children() {
                     return createComponent(ErrorModal, {
@@ -3750,7 +3974,10 @@ function createBlinkIdFeedbackUi(blinkIdUxManager, cameraManagerComponent, {
   // todo - implement this
   preserveSdkInstance,
   showOnboardingGuide = true,
-  showHelpButton = true
+  showHelpButton = true,
+  showDocumentFilteredModal = true,
+  showTimeoutModal = true,
+  showUnsupportedDocumentModal = true
 } = {}) {
   const dismountFeedbackUiRef = {
     current: () => {
@@ -3764,6 +3991,9 @@ function createBlinkIdFeedbackUi(blinkIdUxManager, cameraManagerComponent, {
     cameraManagerComponent,
     showOnboardingGuide,
     showHelpButton,
+    showDocumentFilteredModal,
+    showTimeoutModal,
+    showUnsupportedDocumentModal,
     dismountFeedbackUi: () => dismountFeedbackUiRef.current(),
     get children() {
       return createComponent(BlinkIdFeedbackUi, {