@microblink/blinkid-ux-manager 7.2.2 → 7.3.0

package/dist/blinkid-ux-manager.js

@@ -817,9 +817,15 @@ class BlinkIdUxManager {
   #successProcessResult;
   #threadBusy = false;
   #timeoutId;
-  /** Timeout duration in ms */
+  /** Timeout duration in ms for the scanning session. If null, timeout won't be triggered ever. */
   #timeoutDuration = 1e4;
   // 10s
+  /** Time in ms before the help tooltip is shown. If null, tooltip won't be auto shown. */
+  #helpTooltipShowDelay = 5e3;
+  // 5s
+  /** Time in ms before the help tooltip is hidden. If null, tooltip won't be auto hidden. */
+  #helpTooltipHideDelay = 5e3;
+  // 5s
   #onUiStateChangedCallbacks = /* @__PURE__ */ new Set();
   #onResultCallbacks = /* @__PURE__ */ new Set();
   #onFrameProcessCallbacks = /* @__PURE__ */ new Set();
@@ -847,6 +853,9 @@ class BlinkIdUxManager {
       (s2) => s2.playbackState,
       (playbackState) => {
         console.debug(`⏯️ ${playbackState}`);
+        if (this.#timeoutDuration === null) {
+          return;
+        }
         if (playbackState !== "capturing") {
           this.clearScanTimeout();
         } else {
@@ -880,6 +889,27 @@ class BlinkIdUxManager {
   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.
@@ -1058,15 +1088,55 @@ class BlinkIdUxManager {
     return processResult.arrayBuffer;
   };
   /**
-   * Set the duration of the timeout in milliseconds.
+   * 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.
+   * @throws {Error} Throws an error if duration is less than or equal to 0 when not null.
    */
-  setTimeoutDuration(duration) {
+  setTimeoutDuration(duration, setHelpTooltipShowDelay = true) {
+    if (duration !== null && duration <= 0) {
+      throw new Error("Timeout duration must be greater than 0");
+    }
     this.#timeoutDuration = duration;
+    if (setHelpTooltipShowDelay) {
+      this.setHelpTooltipShowDelay(duration !== null ? duration / 2 : null);
+    }
+  }
+  /**
+   * 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.
+   */
+  setHelpTooltipShowDelay(duration) {
+    if (duration !== null && duration <= 0) {
+      throw new Error("Help tooltip show delay must be greater than 0");
+    }
+    this.#helpTooltipShowDelay = duration;
+  }
+  /**
+   * 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.
+   */
+  setHelpTooltipHideDelay(duration) {
+    if (duration !== null && duration <= 0) {
+      throw new Error("Help tooltip display duration must be greater than 0");
+    }
+    this.#helpTooltipHideDelay = duration;
   }
   #setTimeout = (uiState) => {
+    if (this.#timeoutDuration === null) {
+      console.debug("⏳🟢 timeout duration is null, not starting timeout");
+      return;
+    }
     this.clearScanTimeout();
     console.debug(`⏳🟢 starting timeout for ${uiState.key}`);
     this.#timeoutId = window.setTimeout(() => {
+      console.debug("⏳🟢 timeout triggered");
       this.cameraManager.stopFrameCapture();
       this.#invokeOnErrorCallbacks("timeout");
       this.feedbackStabilizer.reset();
@@ -1092,7 +1162,9 @@ class BlinkIdUxManager {
   };
   // Side-effects are handled here
   #handleUiStateChange = async (uiState) => {
-    this.#setTimeout(uiState);
+    if (this.#timeoutDuration !== null) {
+      this.#setTimeout(uiState);
+    }
     if (firstSideCapturedStates.includes(uiState.key)) {
       this.cameraManager.stopFrameCapture();
       await sleep(
@@ -1123,6 +1195,9 @@ class BlinkIdUxManager {
    * Clears any active timeout.
    */
   clearScanTimeout = () => {
+    if (!this.#timeoutId) {
+      return;
+    }
     console.debug("⏳🔴 clearing timeout");
     window.clearTimeout(this.#timeoutId);
   };
@@ -2453,13 +2528,6 @@ const UiFeedbackOverlay = (props) => {
           get children() {
             return createComponent(SuccessFeedback, {});
           }
-        }), createComponent(Match, {
-          get when() {
-            return props.uiState.reticleType === "done" || showSuccessOnly();
-          },
-          get children() {
-            return createComponent(SuccessFeedback, {});
-          }
         }), createComponent(Match, {
           get when() {
             return memo(() => props.uiState.reticleType === "flip")() && !showSuccessOnly();
@@ -2805,6 +2873,7 @@ const BlinkIdUiStoreProvider = (props) => {
     cameraManagerComponent: props.cameraManagerComponent,
     showOnboardingGuide: props.showOnboardingGuide,
     showHelpTooltipTimeout: props.showHelpTooltipTimeout,
+    showHelpButton: props.showHelpButton,
     dismountFeedbackUi: props.dismountFeedbackUi
     /* eslint-enable solid/reactivity */
   });
@@ -3362,26 +3431,47 @@ const HelpButton = (props) => {
     updateStore
   } = useBlinkIdUiStore();
   const [tooltipOpen, setTooltipOpen] = createSignal(false);
-  let timeoutId;
-  onCleanup(() => {
-    if (timeoutId !== void 0) {
-      window.clearTimeout(timeoutId);
+  const [wasAutoShown, setWasAutoShown] = createSignal(false);
+  let showTooltipTimeoutId;
+  let hideTooltipTimeoutId;
+  const clearTimeouts = () => {
+    if (showTooltipTimeoutId !== void 0) {
+      window.clearTimeout(showTooltipTimeoutId);
+      showTooltipTimeoutId = void 0;
+    }
+    if (hideTooltipTimeoutId !== void 0) {
+      window.clearTimeout(hideTooltipTimeoutId);
+      hideTooltipTimeoutId = void 0;
     }
-  });
+  };
+  const scheduleAutoHide = () => {
+    const displayDuration = store.blinkIdUxManager.getHelpTooltipHideDelay();
+    if (displayDuration && displayDuration > 0) {
+      hideTooltipTimeoutId = window.setTimeout(() => {
+        setTooltipOpen(false);
+      }, displayDuration);
+    }
+  };
+  const showTooltipAutomatically = () => {
+    const timeout = store.blinkIdUxManager.getHelpTooltipShowDelay();
+    if (timeout && timeout > 0) {
+      showTooltipTimeoutId = window.setTimeout(() => {
+        setTooltipOpen(true);
+        setWasAutoShown(true);
+        scheduleAutoHide();
+      }, timeout);
+    }
+  };
+  onCleanup(clearTimeouts);
   createEffect(() => {
-    if (timeoutId !== void 0) {
-      window.clearTimeout(timeoutId);
-      timeoutId = void 0;
+    if (!props.isProcessing) {
+      setTooltipOpen(false);
+      setWasAutoShown(false);
+      clearTimeouts();
+      return;
     }
-    if (props.isProcessing && !tooltipOpen()) {
-      const {
-        showHelpTooltipTimeout
-      } = store;
-      if (showHelpTooltipTimeout && showHelpTooltipTimeout > 0) {
-        timeoutId = window.setTimeout(() => {
-          setTooltipOpen(true);
-        }, showHelpTooltipTimeout);
-      }
+    if (!tooltipOpen() && !wasAutoShown()) {
+      showTooltipAutomatically();
     }
   });
   return createComponent(Tooltip.Root, {
@@ -3396,6 +3486,7 @@ const HelpButton = (props) => {
     onOpenChange: (details) => setTooltipOpen(details.open),
     get children() {
       return [createComponent(Tooltip.Trigger, {
+        part: "help-button-part",
         get ["aria-label"]() {
           return t2.help_aria_label;
         },
@@ -3411,6 +3502,7 @@ const HelpButton = (props) => {
       }), createComponent(Tooltip.Positioner, {
         get children() {
           return createComponent(Tooltip.Content, {
+            part: "help-button-tooltip-part",
             get ["class"]() {
               return styles$1.tooltip;
             },
@@ -3634,9 +3726,16 @@ const BlinkIdFeedbackUi = (props) => {
                 effect(() => className(_el$4, styles.microblinkOverlay));
                 return _el$4;
               }
-            }), createComponent(HelpButton, {
-              get isProcessing() {
-                return isProcessing();
+            }), createComponent(Show, {
+              get when() {
+                return store.showHelpButton;
+              },
+              get children() {
+                return createComponent(HelpButton, {
+                  get isProcessing() {
+                    return isProcessing();
+                  }
+                });
               }
             })];
           }
@@ -3651,7 +3750,7 @@ function createBlinkIdFeedbackUi(blinkIdUxManager, cameraManagerComponent, {
   // todo - implement this
   preserveSdkInstance,
   showOnboardingGuide = true,
-  showHelpTooltipTimeout = 8e3
+  showHelpButton = true
 } = {}) {
   const dismountFeedbackUiRef = {
     current: () => {
@@ -3664,7 +3763,7 @@ function createBlinkIdFeedbackUi(blinkIdUxManager, cameraManagerComponent, {
     blinkIdUxManager,
     cameraManagerComponent,
     showOnboardingGuide,
-    showHelpTooltipTimeout,
+    showHelpButton,
     dismountFeedbackUi: () => dismountFeedbackUiRef.current(),
     get children() {
       return createComponent(BlinkIdFeedbackUi, {