@envive-ai/react-hooks 0.3.63 → 0.3.65

package/src/contexts/pageContext/__tests__/pageContext.test.tsx

@@ -4,17 +4,13 @@ import { Provider, useAtom } from 'jotai';
 import React from 'react';
 import CommerceApiClient from 'src/application/commerce-api';
 import Logger from 'src/application/logging/logger';
-import { FeatureGates, VariantTypeEnum } from 'src/application/models';
+import { VariantTypeEnum } from 'src/application/models';
 import {
   UrlResolverResponse,
   pageUserEventAtom,
   pageVariantInfoAtom,
   urlResolverAtom,
 } from 'src/atoms/app/variant';
-import {
-  FeatureFlagService,
-  FeatureFlagServiceProvider,
-} from 'src/contexts/featureFlagServiceContext';
 import { mapUrlResolverResponseToVariantInfo } from '../mapping';
 import { PageProvider, usePage } from '../pageContext';
 
@@ -103,21 +99,6 @@ describe('PageProvider', () => {
     );
   };
 
-  // Same as renderWithProviders but with the PDP variant-reset feature gate turned on, so the
-  // client-side re-resolution behavior is exercised (it is gated off by default).
-  const renderWithVariantResetEnabled = (children: React.ReactNode, previewMode = false) => {
-    const featureFlagService = new FeatureFlagService([
-      { name: FeatureGates.IsPdpVariantContextResetEnabled, value: true },
-    ]);
-    return render(
-      <Provider>
-        <FeatureFlagServiceProvider featureFlagService={featureFlagService}>
-          <PageProvider previewMode={previewMode}>{children}</PageProvider>
-        </FeatureFlagServiceProvider>
-      </Provider>,
-    );
-  };
-
   describe('PageProvider Initialization', () => {
     it('should initialize with pageUrl from window.location.href', async () => {
       window.location.href = 'https://example.com/initial-page';
@@ -374,7 +355,7 @@ describe('PageProvider', () => {
           }) as UrlResolverResponse,
       );
 
-      renderWithVariantResetEnabled(<NavComponent />, false);
+      renderWithProviders(<NavComponent />, false);
 
       // Initial resolution to product-a
       await waitFor(() => {
@@ -438,7 +419,7 @@ describe('PageProvider', () => {
         } as UrlResolverResponse;
       });
 
-      renderWithVariantResetEnabled(<MultiNavComponent />, false);
+      renderWithProviders(<MultiNavComponent />, false);
 
       await waitFor(() => {
         expect(screen.getByTestId('variant-info').textContent).toContain('product-a');
@@ -502,7 +483,7 @@ describe('PageProvider', () => {
         );
       };
 
-      renderWithVariantResetEnabled(<OutOfOrderComp />, false);
+      renderWithProviders(<OutOfOrderComp />, false);
 
       // Initial resolution of /a is in flight (aPromise pending).
       await waitFor(() => {
@@ -548,42 +529,6 @@ describe('PageProvider', () => {
         expect(screen.getByTestId('is-loading').textContent).toBe('false');
       });
     });
-
-    it('does NOT re-resolve on a URL change when the feature gate is off (default)', async () => {
-      window.location.href = 'https://example.com/product/variant-a';
-
-      mockResolveUrl.mockImplementation(
-        async (url: string) =>
-          ({
-            variant_type: VariantTypeEnum.Pdp,
-            specific_details: {
-              pdp_attributes: { product_id: url.includes('variant-b') ? 'product-b' : 'product-a' },
-            },
-            ready: true,
-          }) as UrlResolverResponse,
-      );
-
-      // No FeatureFlagServiceProvider -> gate resolves to false -> original behavior.
-      renderWithProviders(<NavComponent />, false);
-
-      await waitFor(() => {
-        expect(screen.getByTestId('variant-info').textContent).toContain('product-a');
-      });
-
-      await act(async () => {
-        screen.getByTestId('navigate').click();
-      });
-      // Give any (unwanted) re-resolution time to happen.
-      await act(async () => {
-        await new Promise<void>(resolve => {
-          setTimeout(resolve, 100);
-        });
-      });
-
-      // The URL change must not have re-resolved; context stays on the original product.
-      expect(mockResolveUrl).not.toHaveBeenCalledWith('https://example.com/product/variant-b');
-      expect(screen.getByTestId('variant-info').textContent).toContain('product-a');
-    });
   });
 
   describe('Variant Info Mapping', () => {

package/src/contexts/pageContext/pageContext.tsx

@@ -17,8 +17,7 @@ import {
   variantInfoAtom,
 } from 'src/atoms/app/variant';
 import { useAtom, useAtomValue } from 'jotai';
-import { FeatureGates, VariantTypeEnum } from 'src/application/models';
-import { FeatureFlagServiceContext } from 'src/contexts/featureFlagServiceContext';
+import { VariantTypeEnum } from 'src/application/models';
 import CommerceApiClient from 'src/application/commerce-api';
 import Logger from 'src/application/logging/logger';
 import { PageVisitCategory, UserEventCategory } from '@spiffy-ai/commerce-api-client';
@@ -60,16 +59,6 @@ export const PageProvider: React.FC<{
   // next navigation misreading it as "atoms were seeded externally" and skipping the API call.
   const hasResolvedOnceRef = useRef(false);
 
-  // Gate: re-resolving the URL on a client-side change (PDP variant reset) is opt-in per org
-  // via Statsig. When off, keep the original behavior (resolve once, then short-circuit).
-  // Read via useContext (not useFeatureFlagService) so a bare PageProvider — e.g. in unit
-  // tests — does not throw; absent provider or gate resolves to false.
-  const featureFlagContext = useContext(FeatureFlagServiceContext);
-  const isVariantResetEnabled =
-    featureFlagContext?.featureFlagService?.isFeatureGateEnabled(
-      FeatureGates.IsPdpVariantContextResetEnabled,
-    ) ?? false;
-
   useEffect(() => {
     setPageUrl(window.location.href);
   }, []);
@@ -123,36 +112,27 @@ export const PageProvider: React.FC<{
 
         const cleansedUrl = pageUrl.toLowerCase().trim();
 
-        if (!isVariantResetEnabled) {
-          // Gate off: original behavior — resolve once, then short-circuit forever while the
-          // variant/userEvent atoms are set (a client-side URL change never re-resolves).
-          if (previewMode || userEvent || variantInfo) {
-            setIsLoading(false);
-            return;
-          }
-        } else {
-          // Gate on: re-resolve when the URL changes so a PDP variant swap follows to the new
-          // product.
-          //
-          // Already resolved this exact URL — guards against the effect re-running once the
-          // resolver writes the variant/userEvent atoms (they are effect dependencies).
-          if (lastResolvedUrlRef.current === cleansedUrl) {
-            setIsLoading(false);
-            return;
-          }
-          // In preview mode, or when the atoms were seeded externally (e.g. by storybook)
-          // before we ourselves resolved anything, honor those atoms and skip the API call.
-          // Once we have resolved at least once (`hasResolvedOnceRef`), a changed URL should
-          // re-resolve even though the previous variant/userEvent atoms are set.
-          if (previewMode || ((userEvent || variantInfo) && !hasResolvedOnceRef.current)) {
-            hasResolvedOnceRef.current = true;
-            lastResolvedUrlRef.current = cleansedUrl;
-            setIsLoading(false);
-            return;
-          }
+        // Re-resolve when the URL changes so a client-side PDP variant swap follows to the new
+        // product.
+        //
+        // Already resolved this exact URL — guards against the effect re-running once the
+        // resolver writes the variant/userEvent atoms (they are effect dependencies).
+        if (lastResolvedUrlRef.current === cleansedUrl) {
+          setIsLoading(false);
+          return;
+        }
+        // In preview mode, or when the atoms were seeded externally (e.g. by storybook)
+        // before we ourselves resolved anything, honor those atoms and skip the API call.
+        // Once we have resolved at least once (`hasResolvedOnceRef`), a changed URL should
+        // re-resolve even though the previous variant/userEvent atoms are set.
+        if (previewMode || ((userEvent || variantInfo) && !hasResolvedOnceRef.current)) {
           hasResolvedOnceRef.current = true;
           lastResolvedUrlRef.current = cleansedUrl;
+          setIsLoading(false);
+          return;
         }
+        hasResolvedOnceRef.current = true;
+        lastResolvedUrlRef.current = cleansedUrl;
 
         const response =
           urlResolverResponse[cleansedUrl] ??
@@ -165,7 +145,7 @@ export const PageProvider: React.FC<{
         // open a window where isLoading=false while variantInfo/isSupported still belong to
         // the previous product (causing widget flashes and a fire-once success ref — see
         // Widgets.tsx — to latch onto the wrong product's state).
-        if (isVariantResetEnabled && lastResolvedUrlRef.current !== cleansedUrl) {
+        if (lastResolvedUrlRef.current !== cleansedUrl) {
           return;
         }
 
@@ -205,7 +185,6 @@ export const PageProvider: React.FC<{
     variantInfo,
     previewMode,
     onUrlResolverNotReady,
-    isVariantResetEnabled,
   ]);
 
   const { trackEvent } = useAmplitude();

package/src/contexts/typesV3.ts

@@ -396,6 +396,12 @@ export enum ProductCarouselLayoutV3 {
   GRID_MOBILE_HORIZONTAL_DESKTOP = 'grid-mobile-horizontal-desktop',
 }
 
+export enum PartialViewModeV3 {
+  ENABLED = 'enabled',
+  MOBILE_ONLY = 'mobile-only',
+  DISABLED = 'disabled',
+}
+
 interface FullPageSalesAgentWidgetV3Config extends BaseWidgetConfig<WidgetTypeV3.FullPageSalesAgentV3> {
   headerContainer?: string;
   autoHeight?: boolean;
@@ -408,12 +414,24 @@ interface FullPageSalesAgentWidgetV3Config extends BaseWidgetConfig<WidgetTypeV3
   suggestionButtonType?: PromptButtonVariant;
   productCarouselLayout?: ProductCarouselLayoutV3;
   /**
-   * When true (or unset), asking a question opens the conversation in a
-   * partial-height sheet that keeps the welcome overlay's product grid
-   * visible above it. Set to false to fall back to the full-screen takeover.
-   * Default true (undefined and true = partial view enabled).
+   * @deprecated Use `partialViewMode` instead. Kept only so a merchant who
+   * set this to `false` before `partialViewMode` existed doesn't silently
+   * revert to partial view enabled — see the fallback resolution in
+   * FullPageSalesAgent.tsx. Never written by the Hub UI anymore.
    */
   partialViewEnabled?: boolean;
+  /**
+   * Whether asking a question opens the conversation in a partial-height
+   * sheet that keeps the welcome overlay's product grid visible above it
+   * (mobile: a bottom sheet; desktop: a side panel), instead of a
+   * full-screen takeover.
+   * - `enabled` (default when unset): partial view on both mobile and desktop.
+   * - `mobile-only`: partial view on mobile; desktop still gets the
+   *   full-screen takeover (the desktop panel doesn't suit every merchant's
+   *   layout the way the mobile sheet does).
+   * - `disabled`: full-screen takeover on both.
+   */
+  partialViewMode?: PartialViewModeV3;
 }
 
 type WidgetConfigV3 =

package/src/hooks/Intersection/useIntersection.ts

@@ -40,12 +40,19 @@ export const useIntersection = (
   element: RefObject<HTMLElement>,
   rootMargin: string,
   logContext?: Record<string, unknown>,
+  // Called the first time visibility is forced by the reconcile fallback (observer stayed
+  // silent for an on-screen element). Lets callers record that this widget's visibility came
+  // from the fallback rather than the observer — the diagnostic for observer failures.
+  onFallbackEngaged?: () => void,
 ) => {
   const [isVisible, setIsVisible] = useState(false);
   const observerRef = useRef<IntersectionObserver | null>(null);
   const observedNodeRef = useRef<HTMLElement | null>(null);
   const logContextRef = useRef(logContext);
   logContextRef.current = logContext;
+  const onFallbackEngagedRef = useRef(onFallbackEngaged);
+  onFallbackEngagedRef.current = onFallbackEngaged;
+  const fallbackEngagedRef = useRef(false);
 
   // Runs after every render so it catches when element.current transitions from null to a
   // mounted DOM node, AND when the node under the ref is replaced. The replacement case is
@@ -112,6 +119,10 @@ export const useIntersection = (
             },
           );
         }
+        if (!fallbackEngagedRef.current) {
+          fallbackEngagedRef.current = true;
+          onFallbackEngagedRef.current?.();
+        }
         setIsVisible(true);
       }
     };

package/src/hooks/TrackComponentVisibleEvent/__tests__/useTrackComponentVisibleEvent.test.tsx

@@ -0,0 +1,64 @@
+import { act, renderHook } from '@testing-library/react';
+import { RefObject } from 'react';
+import { useTrackComponentVisibleEvent } from '../useTrackComponentVisibleEvent';
+
+// Control the observer's isVisible and capture the fallback callback.
+let mockIsVisible = false;
+let capturedOnFallback: (() => void) | undefined;
+
+vi.mock('src/hooks/Intersection/useIntersection', () => ({
+  useIntersection: (
+    _el: unknown,
+    _rm: unknown,
+    _ctx: unknown,
+    onFallback?: () => void,
+  ): boolean => {
+    capturedOnFallback = onFallback;
+    return mockIsVisible;
+  },
+}));
+
+vi.mock('src/contexts/amplitudeContext/amplitudeContext', () => ({
+  useAmplitude: () => ({ trackEvent: vi.fn(), isReady: true }),
+}));
+
+vi.mock('jotai', async (importOriginal: () => Promise<typeof import('jotai')>) => {
+  const actual = await importOriginal();
+  return { ...actual, useAtomValue: () => null };
+});
+
+const ref = { current: document.createElement('div') } as RefObject<HTMLElement>;
+
+beforeEach(() => {
+  mockIsVisible = false;
+  capturedOnFallback = undefined;
+});
+
+describe('useTrackComponentVisibleEvent visibilitySource', () => {
+  it("stays 'pending' until visibility is established (so an eager load never claims 'observer')", () => {
+    const { result } = renderHook(() => useTrackComponentVisibleEvent(ref, {}));
+    expect(result.current.isVisible).toBe(false);
+    expect(result.current.visibilitySource).toBe('pending');
+  });
+
+  it("resolves to 'observer' when the observer reports the element visible", () => {
+    const { result, rerender } = renderHook(() => useTrackComponentVisibleEvent(ref, {}));
+    act(() => {
+      mockIsVisible = true;
+      rerender();
+    });
+    expect(result.current.visibilitySource).toBe('observer');
+  });
+
+  it("records 'fallback' when the reconcile fallback forces visibility (observer stayed silent)", () => {
+    const { result, rerender } = renderHook(() => useTrackComponentVisibleEvent(ref, {}));
+    act(() => {
+      // Fallback fires first (as it does in useIntersection, before its own setIsVisible)...
+      capturedOnFallback?.();
+      // ...then visibility flips true.
+      mockIsVisible = true;
+      rerender();
+    });
+    expect(result.current.visibilitySource).toBe('fallback');
+  });
+});

package/src/hooks/TrackComponentVisibleEvent/useTrackComponentVisibleEvent.ts

@@ -1,5 +1,5 @@
 import { useAtomValue } from 'jotai';
-import { RefObject, useEffect, useRef } from 'react';
+import { RefObject, useEffect, useRef, useState } from 'react';
 import Logger from 'src/application/logging/logger';
 import { pageVariantInfoAtom } from 'src/atoms/app';
 import { useAmplitude } from 'src/contexts/amplitudeContext/amplitudeContext';
@@ -34,10 +34,29 @@ export const useTrackComponentVisibleEvent = (
   eventProps?: Record<string, unknown>,
   rootMargin: string = '0px',
   enabled: boolean = true,
-): { isVisible: boolean } => {
+): { isVisible: boolean; visibilitySource: 'observer' | 'fallback' | 'pending' } => {
+  // How visibility was established, for widget-load diagnostics:
+  //  - 'pending'  — not confirmed by either path yet. Stays this way for a `deferLoading: false`
+  //                 widget whose requests settle before the observer ever reports, so we don't
+  //                 falsely claim 'observer' for a load that never waited on visibility.
+  //  - 'observer' — the IntersectionObserver reported the element visible.
+  //  - 'fallback' — the reconcile fallback had to force it (observer stayed silent on-screen).
+  // State (not a ref) so consumers reliably re-render when the source resolves.
+  const [visibilitySource, setVisibilitySource] = useState<'observer' | 'fallback' | 'pending'>(
+    'pending',
+  );
   // eventProps (widget_config_id, widget_type, …) double as log context so the hook's
   // visibility-fallback error identifies which widget it rescued.
-  const isVisible = useIntersection(element, rootMargin, eventProps);
+  const isVisible = useIntersection(element, rootMargin, eventProps, () => {
+    // The observer stayed silent on-screen and the fallback forced visibility. This is recorded
+    // before useIntersection's own setIsVisible, so it wins over the 'observer' resolution below.
+    setVisibilitySource(prev => (prev === 'pending' ? 'fallback' : prev));
+  });
+  // Resolve 'pending' → 'observer' once the observer establishes visibility; a 'fallback'
+  // already recorded above is preserved.
+  useEffect(() => {
+    if (isVisible) setVisibilitySource(prev => (prev === 'pending' ? 'observer' : prev));
+  }, [isVisible]);
   const hasTrackedEvent = useRef(false);
   const { trackEvent } = useAmplitude();
   const variantInfo = useAtomValue(pageVariantInfoAtom);
@@ -87,5 +106,5 @@ export const useTrackComponentVisibleEvent = (
     });
     hasTrackedEvent.current = true;
   }, [enabled, isVisible, eventProps, trackEvent]);
-  return { isVisible };
+  return { isVisible, visibilitySource };
 };

package/src/hooks/WidgetLoadDiagnostics/__tests__/useWidgetLoadDiagnostics.test.ts

@@ -0,0 +1,161 @@
+import { act, renderHook } from '@testing-library/react';
+import { WidgetTypeV3 } from 'src/contexts/typesV3';
+import {
+  WIDGET_LOAD_STALL_MS,
+  WidgetLoadDiagnosticsInput,
+  useWidgetLoadDiagnostics,
+} from '../useWidgetLoadDiagnostics';
+
+const trackEvent = vi.fn();
+
+vi.mock('src/contexts/amplitudeContext/amplitudeContext', () => ({
+  useAmplitude: () => ({ trackEvent, isReady: true }),
+}));
+
+// Keep jotai's atom() working; only stub useAtomValue so we don't need a Provider.
+vi.mock('jotai', async (importOriginal: () => Promise<typeof import('jotai')>) => {
+  const actual = await importOriginal();
+  return { ...actual, useAtomValue: () => null };
+});
+
+const base: WidgetLoadDiagnosticsInput = {
+  enabled: true,
+  loadId: 'load-1',
+  widgetType: WidgetTypeV3.ProductCardV3,
+  widgetConfigId: 'cfg-1',
+  startLoading: false,
+  ownRequestsSettled: false,
+  hardcopyContent: undefined,
+  visibilitySource: 'observer',
+  pendingRequests: ['hardcopy'],
+  hardcopyErrorReason: undefined,
+};
+
+// Pull the eventProps of the diagnostics call whose `type` matches.
+const propsOfType = (type: string): Record<string, unknown> | undefined =>
+  trackEvent.mock.calls
+    .map((c: [{ eventProps: Record<string, unknown> }]) => c[0].eventProps)
+    .find((p: Record<string, unknown>) => p.type === type);
+
+beforeEach(() => {
+  trackEvent.mockClear();
+});
+
+describe('useWidgetLoadDiagnostics', () => {
+  it('emits nothing while disabled', () => {
+    renderHook(() => useWidgetLoadDiagnostics({ ...base, enabled: false, startLoading: true }));
+    expect(trackEvent).not.toHaveBeenCalled();
+  });
+
+  it('emits widget_mounted on mount regardless of visibility (the ungated baseline)', () => {
+    renderHook(() => useWidgetLoadDiagnostics({ ...base, startLoading: false }));
+    const mounted = propsOfType('widget_mounted');
+    expect(mounted).toBeDefined();
+    expect(mounted).toMatchObject({ load_id: 'load-1', widget_type: WidgetTypeV3.ProductCardV3 });
+    // No outcome/stall — it never became visible.
+    expect(propsOfType('widget_load_outcome')).toBeUndefined();
+  });
+
+  it('emits content_loaded when own requests settle with live api content', () => {
+    const { rerender } = renderHook(props => useWidgetLoadDiagnostics(props), {
+      initialProps: { ...base, startLoading: true },
+    });
+    rerender({
+      ...base,
+      startLoading: true,
+      ownRequestsSettled: true,
+      hardcopyContent: { responseId: 'r', language: 'en', values: {}, servedFrom: 'api' },
+      pendingRequests: [],
+    });
+    const outcome = propsOfType('widget_load_outcome');
+    expect(outcome).toMatchObject({ outcome: 'content_loaded', visibility_source: 'observer' });
+  });
+
+  it('emits static_fallback with the fallback reason', () => {
+    const { rerender } = renderHook(props => useWidgetLoadDiagnostics(props), {
+      initialProps: { ...base, startLoading: true },
+    });
+    rerender({
+      ...base,
+      startLoading: true,
+      ownRequestsSettled: true,
+      hardcopyContent: {
+        responseId: 'r',
+        language: 'en',
+        values: {},
+        servedFrom: 'static',
+        fallbackReason: 'timeout',
+      },
+    });
+    expect(propsOfType('widget_load_outcome')).toMatchObject({
+      outcome: 'static_fallback',
+      reason: 'timeout',
+    });
+  });
+
+  it('emits error when the load settles without content', () => {
+    const { rerender } = renderHook(props => useWidgetLoadDiagnostics(props), {
+      initialProps: { ...base, startLoading: true },
+    });
+    rerender({
+      ...base,
+      startLoading: true,
+      ownRequestsSettled: true,
+      hardcopyContent: undefined,
+      hardcopyErrorReason: 'hardcopy_error',
+    });
+    expect(propsOfType('widget_load_outcome')).toMatchObject({
+      outcome: 'error',
+      reason: 'hardcopy_error',
+    });
+  });
+
+  it('carries visibility_source=fallback through the outcome', () => {
+    const { rerender } = renderHook(props => useWidgetLoadDiagnostics(props), {
+      initialProps: { ...base, startLoading: true, visibilitySource: 'fallback' as const },
+    });
+    rerender({
+      ...base,
+      startLoading: true,
+      visibilitySource: 'fallback',
+      ownRequestsSettled: true,
+      hardcopyContent: { responseId: 'r', language: 'en', values: {}, servedFrom: 'api' },
+    });
+    expect(propsOfType('widget_load_outcome')).toMatchObject({ visibility_source: 'fallback' });
+  });
+
+  describe('stall (abandonment-safe)', () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+
+    it('emits widget_load_stalled if still loading at the threshold', () => {
+      renderHook(() => useWidgetLoadDiagnostics({ ...base, startLoading: true }));
+      act(() => {
+        vi.advanceTimersByTime(WIDGET_LOAD_STALL_MS);
+      });
+      expect(propsOfType('widget_load_stalled')).toMatchObject({ pending_requests: ['hardcopy'] });
+    });
+
+    it('does NOT emit a stall when the widget unmounts first (navigated away)', () => {
+      const { unmount } = renderHook(() =>
+        useWidgetLoadDiagnostics({ ...base, startLoading: true }),
+      );
+      unmount();
+      act(() => {
+        vi.advanceTimersByTime(WIDGET_LOAD_STALL_MS * 2);
+      });
+      expect(propsOfType('widget_load_stalled')).toBeUndefined();
+    });
+
+    it('does NOT emit a stall once the load has settled', () => {
+      const { rerender } = renderHook(props => useWidgetLoadDiagnostics(props), {
+        initialProps: { ...base, startLoading: true },
+      });
+      rerender({ ...base, startLoading: true, ownRequestsSettled: true });
+      act(() => {
+        vi.advanceTimersByTime(WIDGET_LOAD_STALL_MS * 2);
+      });
+      expect(propsOfType('widget_load_stalled')).toBeUndefined();
+    });
+  });
+});

package/src/hooks/WidgetLoadDiagnostics/index.ts

@@ -0,0 +1,5 @@
+export { useWidgetLoadDiagnostics, WIDGET_LOAD_STALL_MS } from './useWidgetLoadDiagnostics';
+export type {
+  WidgetLoadDiagnosticsInput,
+  WidgetVisibilitySource,
+} from './useWidgetLoadDiagnostics';