@microsoft/omnichannel-chat-widget 1.8.3 → 1.8.4-main.7bdb634

package/lib/types/components/webchatcontainerstateful/webchatcontroller/middlewares/renderingmiddlewares/activities/LazyLoadActivity.d.ts

@@ -0,0 +1,326 @@
+/**
+ * LazyLoadActivity Component
+ *
+ * This component implements a sophisticated lazy loading system for chat history in the webchat widget.
+ * It uses an IntersectionObserver to detect when the user scrolls near the top of the chat container
+ * and then triggers the loading of previous chat messages.
+ *
+ * Key Features:
+ * - Intersection Observer based detection for optimal performance
+ * - Reliable scroll management with retry mechanisms
+ * - Immediate user feedback even during initialization delays
+ * - Handles edge cases like minimize/maximize widget scenarios
+ * - Memory leak prevention with proper cleanup
+ *
+ * Architecture:
+ * - LazyLoadHandler: Static class managing all lazy load logic
+ * - LazyLoadActivity: React component providing the UI and lifecycle integration for lazy loading
+ *
+ * Flow:
+ * 1. Component renders a trigger element at the top of chat history
+ * 2. IntersectionObserver watches when this element becomes visible
+ * 3. When visible, dispatches event to fetch more chat history
+ * 4. Performs controlled scroll to maintain user position
+ * 5. Resets observer for next lazy load cycle
+ */
+import { TelemetryEvent } from "../../../../../../common/telemetry/TelemetryConstants";
+import React from "react";
+import { ILiveChatWidgetProps } from "../../../../../livechatwidget/interfaces/ILiveChatWidgetProps";
+/**
+ * LazyLoadHandler - Static class managing all lazy loading functionality
+ *
+ * This class uses a singleton pattern with static methods to ensure consistent
+ * state management across component re-renders and widget lifecycle events.
+ *
+ * State Management:
+ * - initialized: Tracks if the IntersectionObserver has been set up
+ * - paused: Temporarily disables lazy loading (during initialization/loading)
+ * - pendingScrollAction: Prevents overlapping scroll operations
+ * - isReady: Indicates when the system is fully ready for user interactions
+ * - initializationQueue: Stores user actions while system initializes
+ *
+ * Reliability Features:
+ * - Retry mechanisms with exponential backoff
+ * - Scroll verification with tolerance checking
+ * - Multiple container detection strategies
+ * - Immediate user feedback during delays
+ * - Proper memory management and cleanup
+ */
+declare class LazyLoadHandler {
+    static rootId: string;
+    static targetId: string;
+    static initialized: boolean;
+    static paused: boolean;
+    static observer: IntersectionObserver | null;
+    private static scrollState;
+    private static pendingScrollAction;
+    private static retryTimeouts;
+    static resetPending: boolean;
+    private static initTimer;
+    static logLifecycleEvent(event: TelemetryEvent, description: string, elapsedTime?: number): void;
+    private static resetEventListener;
+    static isReady: boolean;
+    private static initializationQueue;
+    static hasMoreHistoryAvailable: boolean;
+    static setHasMoreHistoryAvailable(value: boolean): void;
+    /**
+     * Direct reset method that can be called externally
+     * This bypasses the broadcast system for more reliable resets
+     */
+    static directReset(): void;
+    /**
+     * Main initialization method for the lazy loading system
+     *
+     * This method sets up the IntersectionObserver that watches for when the trigger
+     * element becomes visible, indicating the user has scrolled near the top.
+     *
+     * Process:
+     * 1. Prevents duplicate initialization
+     * 2. Sets up intersection callback to handle visibility events
+     * 3. Finds appropriate scroll container with fallback strategies
+     * 4. Configures observer with optimal settings for chat history loading
+     * 5. Waits for target element availability with exponential backoff
+     *
+     * Observer Configuration:
+     * - root: The scrollable container (webchat or fallback)
+     * - rootMargin: 20px top margin to trigger slightly before element is visible
+     * - threshold: 0.05 (5%) visibility required to trigger
+     */
+    static useLazyLoadObserver(): void;
+    /**
+     * Waits for the target element to be available in the DOM
+     *
+     * Uses exponential backoff to retry finding the target element.
+     * This is necessary because the target element may not be immediately
+     * available when the observer is being set up.
+     *
+     * @param callback - Function to call when target element is found
+     * @param maxAttempts - Maximum number of retry attempts (default: 10)
+     * @param attempt - Current attempt number (default: 1)
+     */
+    private static waitForTargetElement;
+    /**
+     * Handles immediate scroll requests when system might not be ready
+     *
+     * This is crucial for handling minimize/maximize scenarios where users
+     * immediately scroll up before the observer is fully initialized.
+     *
+     * Two-Path Strategy:
+     * 1. If ready: Execute normal lazy load trigger
+     * 2. If not ready: Provide immediate feedback + queue action for later
+     *
+     * This ensures users always get visual feedback even during initialization delays.
+     */
+    static handleImmediateScrollRequest(): void;
+    /**
+     * Provides immediate scroll feedback during initialization
+     *
+     * When the system isn't ready but user scrolls up, this provides
+     * immediate visual feedback (20px scroll) so the user knows their
+     * action was recognized.
+     */
+    private static executeImmediateScrollFeedback;
+    /**
+     * Forces faster initialization attempts
+     *
+     * When user interacts before system is ready, this tries to
+     * speed up the initialization process.
+     */
+    private static expediteInitialization;
+    /**
+     * Processes all queued actions once system is ready
+     *
+     * During initialization, user actions are queued. Once the system
+     * is ready, this processes all queued actions with small delays
+     * between them to prevent overwhelming the system.
+     */
+    private static processInitializationQueue;
+    /**
+     * Manually checks if target element is visible and triggers lazy load
+     *
+     * This is used when the intersection observer might not be ready yet
+     * but we need to check if the trigger element is already in view.
+     *
+     * Uses getBoundingClientRect() to calculate visibility manually.
+     */
+    static checkVisibilityAndTrigger(): void;
+    /**
+     * Main lazy load trigger handler
+     *
+     * This is the core method that executes when the trigger element becomes visible.
+     * It coordinates the entire lazy loading process:
+     *
+     * 1. Sets flags to prevent concurrent operations
+     * 2. Dispatches event to fetch more chat history
+     * 3. Waits for content to load
+     * 4. Executes scroll adjustment to maintain user position
+     *
+     * Timing: Uses 300ms delay to allow content loading before scroll adjustment
+     */
+    private static handleLazyLoadTrigger;
+    /**
+     * Executes reliable scroll with validation and retry logic
+     *
+     * This method implements a robust scroll system that:
+     * 1. Finds and validates the scroll container
+     * 2. Calculates target scroll position (current + 35px)
+     * 3. Sets up scroll state for tracking and retries
+     * 4. Initiates the scroll attempt process
+     *
+     * If no suitable container is found, schedules a retry.
+     */
+    private static executeReliableScroll;
+    /**
+     * Attempts to perform scroll with verification and retry logic
+     *
+     * This method implements a sophisticated scroll system:
+     *
+     * 1. Uses requestAnimationFrame for smooth execution
+     * 2. Performs the scroll operation
+     * 3. Verifies scroll actually occurred (5px tolerance)
+     * 4. Retries with exponential backoff if failed
+     * 5. Continues operation after max attempts
+     *
+     * The two-frame approach ensures scroll is applied and then verified
+     * after the browser has had time to process the scroll change.
+     */
+    private static attemptScroll;
+    /**
+     * Finishes scroll action and prepares for next cycle
+     *
+     * Cleans up scroll state and schedules the reset cycle.
+     * Uses delays to allow content stabilization before re-enabling
+     * the intersection observer for the next lazy load cycle.
+     */
+    private static finishScrollAction;
+    /**
+     * Schedules retry for failed scroll operations
+     *
+     * Used when scroll container is not available or scrollable.
+     * Provides a longer delay to allow container to become ready.
+     */
+    private static scheduleScrollRetry;
+    /**
+     * Schedules observer reset for next lazy load cycle
+     *
+     * After a lazy load operation completes, the observer needs to be reset
+     * to detect the next time the user scrolls to the top.
+     */
+    private static scheduleReset;
+    /**
+     * Finds the appropriate scroll container using multiple strategies
+     *
+     * Container Detection Priority:
+     * 1. Primary: Specific webchat scroll container (.webchat__basic-transcript__scrollable)
+     * 2. Secondary: Widget root container (ms_lcw_webchat_root)
+     * 3. Tertiary: Any scrollable parent of the target element
+     * 4. Fallback: Best available container (even if not scrollable)
+     *
+     * Returns both the container and whether it's actually scrollable.
+     *
+     * @returns Object containing container element and scrollability status
+     */
+    static findScrollContainer(): {
+        container: HTMLElement | null;
+        isScrollable: boolean;
+    };
+    /**
+     * Determines if an element is scrollable
+     *
+     * Checks two conditions:
+     * 1. Content overflow: scrollHeight > clientHeight (content extends beyond visible area)
+     * 2. CSS overflow settings: overflow/overflowY set to 'auto' or 'scroll'
+     *
+     * @param element - The element to check for scrollability
+     * @returns true if element is scrollable, false otherwise
+     */
+    private static isElementScrollable;
+    /**
+     * Traverses up the DOM tree to find a scrollable parent element
+     *
+     * Starting from the given element, walks up the parent chain
+     * until it finds a scrollable element or reaches document.body.
+     *
+     * @param element - Starting element to search from
+     * @returns Scrollable parent element or null if none found
+     */
+    private static findScrollableParent;
+    /**
+     * Legacy method - redirects to new reliable scroll system
+     *
+     * Maintained for backwards compatibility with existing code
+     * that might call this method directly.
+     */
+    static moveScrollDown(): void;
+    /**
+     * Legacy scroll adjustment method with enhancements
+     *
+     * Enhanced version of the original adjustScroll method:
+     * - Validates container scrollability before attempting scroll
+     * - Uses requestAnimationFrame for smooth execution
+     * - Provides logging for debugging
+     *
+     * @param scrollContainer - The container element to scroll
+     */
+    static adjustScroll(scrollContainer: HTMLElement): void;
+    /**
+     * Handles the NO_MORE_HISTORY_AVAILABLE event
+     *
+     * Called when there's no more chat history to load.
+     * Disables further lazy loading attempts and cleans up the observer.
+     * Also removes the trigger element from the DOM to prevent further triggering.
+     */
+    static handleNoMoreHistoryAvailable(): void;
+    /**
+     * Resets the lazy load system for the next cycle
+     *
+     * This method prepares the system for the next lazy load operation:
+     * 1. Cleans up current state
+     * 2. Resets all flags and queues
+     * 3. Reinitializes the observer with faster timing
+     *
+     * Called after each lazy load cycle completes.
+     */
+    static reset(): void;
+    /**
+     * Comprehensive cleanup method
+     *
+     * Performs complete cleanup of all lazy load resources:
+     * - Clears all pending timeouts to prevent memory leaks
+     * - Removes intersection observer and event listeners
+     * - Resets all state variables to initial values
+     * - Clears action queue
+     *
+     * Critical for preventing memory leaks and ensuring clean component unmounting.
+     */
+    static unmount(): void;
+    /**
+     * Complete cleanup including broadcast event listener
+     *
+     * This method is used for final cleanup when the LazyLoadActivity component is being destroyed completely.
+     * It includes unsubscribing from broadcast events and performing complete cleanup.
+     * This is different from reset() which prepares the system for a new chat session.
+     */
+    static destroy(): void;
+}
+/**
+ * LazyLoadActivity React Component
+ *
+ * This component serves as the React wrapper for the LazyLoadHandler system.
+ * It renders the trigger element and manages the component lifecycle.
+ *
+ * Component Lifecycle:
+ * 1. Mount: Initializes lazy load observer and sets up scroll listener
+ * 2. Active: Monitors user scroll behavior and responds to interactions
+ * 3. Unmount: Cleans up all resources and prevents memory leaks
+ *
+ * Key Features:
+ * - Automatic initialization on mount
+ * - Scroll event monitoring for immediate responsiveness
+ * - Proper cleanup on unmount
+ * - Handles minimize/maximize scenarios
+ * - Reactive rendering based on history availability
+ */
+declare const LazyLoadActivity: (props?: Partial<ILiveChatWidgetProps>) => React.JSX.Element | null;
+export default LazyLoadActivity;
+export { LazyLoadHandler };

package/lib/types/components/webchatcontainerstateful/webchatcontroller/middlewares/renderingmiddlewares/activities/LoadInlineBannerActivity.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+import { ILiveChatWidgetProps } from "../../../../../livechatwidget/interfaces/ILiveChatWidgetProps";
+declare const LoadInlineBannerActivity: ({ webChatContainerProps, persistentChatHistory, id }: {
+    webChatContainerProps?: ILiveChatWidgetProps["webChatContainerProps"];
+    persistentChatHistory?: ILiveChatWidgetProps["persistentChatHistoryProps"];
+    id: string;
+}) => React.JSX.Element;
+export default LoadInlineBannerActivity;

package/lib/types/components/webchatcontainerstateful/webchatcontroller/middlewares/renderingmiddlewares/activityStatusMiddleware.d.ts

@@ -1 +1,2 @@
 export declare const activityStatusMiddleware: () => (next: any) => (args: any) => any;
+export declare const createActivityStatusMiddleware: (locale?: string) => () => (next: any) => (args: any) => any;

package/lib/types/components/webchatcontainerstateful/webchatcontroller/middlewares/renderingmiddlewares/defaultStyles/defaultInLineBannerStyle.d.ts

@@ -0,0 +1,2 @@
+import { IStyle } from "@fluentui/react";
+export declare const defaultInlineBannerStyle: IStyle;

package/lib/types/components/webchatcontainerstateful/webchatcontroller/middlewares/renderingmiddlewares/timestamps/HistoryMessageTimestamp.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export declare const HistoryMessageTimestamp: ({ args }: any) => React.JSX.Element;

package/lib/types/contexts/common/ILiveChatWidgetLocalizedTexts.d.ts

@@ -1,4 +1,5 @@
 export interface ILiveChatWidgetLocalizedTexts {
+    PREVIOUS_MESSAGES_LOADING?: string;
     MIDDLEWARE_BANNER_FILE_NULL_ERROR?: string;
     MIDDLEWARE_BANNER_FILE_SIZE_WITHOUT_EXTENSION_ERROR?: string;
     MIDDLEWARE_BANNER_FILE_SIZE_EXTENSION_ERROR?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/omnichannel-chat-widget",
-  "version": "1.8.3",
+  "version": "1.8.4-main.7bdb634",
   "description": "Microsoft Omnichannel Chat Widget",
   "main": "lib/cjs/index.js",
   "types": "lib/types/index.d.ts",
@@ -87,7 +87,7 @@
     "@azure/core-tracing": "^1.2.0",
     "@microsoft/applicationinsights-web": "^3.3.6",
     "@microsoft/omnichannel-chat-components": "1.1.15",
-    "@microsoft/omnichannel-chat-sdk": "^1.11.6",
+    "@microsoft/omnichannel-chat-sdk": "^1.11.7-main.3418dc3",
     "@opentelemetry/api": "^1.9.0",
     "abort-controller": "^3",
     "abort-controller-es5": "^2.0.1",