@envive-ai/react-widgets-v3 0.3.62 → 0.3.64

package/src/hocs/withBaseWidget/__tests__/withBaseWidget.test.tsx

@@ -79,6 +79,15 @@ vi.mock('@envive-ai/react-hooks/hooks/TrackComponentVisibleEvent', () => ({
   useTrackComponentVisibleEvent: (...args: unknown[]) => mockUseTrackComponentVisibleEvent(...args),
 }));
 
+vi.mock('@envive-ai/react-hooks/contexts/featureFlagServiceContext', () => ({
+  useFeatureFlagService: () => ({ featureFlagService: undefined }),
+}));
+
+// Diagnostics pulls its own amplitude context internally; stub it here like the other sub-hooks.
+vi.mock('@envive-ai/react-hooks/hooks/WidgetLoadDiagnostics', () => ({
+  useWidgetLoadDiagnostics: vi.fn(),
+}));
+
 // Test widget component
 interface TestWidgetProps extends BaseWidgetProps {
   testId?: string;
@@ -153,6 +162,7 @@ describe('withBaseWidget', () => {
         {
           widget_config_id: 'test-config-1',
           widget_type: WidgetTypeV3.PromptCarouselV3,
+          load_id: expect.any(String),
         },
         '0px',
         true,
@@ -173,6 +183,7 @@ describe('withBaseWidget', () => {
         {
           widget_config_id: 'test-config-2',
           widget_type: WidgetTypeV3.ChatPreviewV3,
+          load_id: expect.any(String),
         },
         '100px',
         true,
@@ -198,6 +209,7 @@ describe('withBaseWidget', () => {
         {
           widget_config_id: 'test-config-4',
           widget_type: WidgetTypeV3.SocialProofV3,
+          load_id: expect.any(String),
           custom_prop: 'custom_value',
           another_prop: 123,
         },
@@ -408,6 +420,42 @@ describe('withBaseWidget', () => {
       });
     });
 
+    it('stays loading until its OWN hardcopy settles even after the shared flag clears', async () => {
+      // Complements INTERRUPT-424: that fix stops a settled widget being reverted when a
+      // shared flag flips TRUE. This is the mirror case — another widget's hardcopy finishing
+      // flips the single shared HardcopyProvider boolean to FALSE while THIS widget's own
+      // hardcopy is still in flight. isLoading must track this widget's own requests, not
+      // follow the shared flag down and paint empty content early.
+      mockHardcopyLoading = false;
+      mockPageLoading = false;
+      mockWidgetConfigLoading = false;
+      mockUiConfigLoading = false;
+      let resolveHardcopy!: (value: HardcopyResponse) => void;
+      mockGetHardcopy.mockReturnValue(
+        new Promise<HardcopyResponse>(resolve => {
+          resolveHardcopy = resolve;
+        }),
+      );
+
+      const WrappedWidget = withBaseWidget(TestWidget);
+      render(
+        <WrappedWidget
+          widgetConfigId="test-config-own-hardcopy"
+          widgetType={WidgetTypeV3.PromptCarouselV3}
+        />,
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('is-loading')).toHaveTextContent('true');
+      });
+
+      resolveHardcopy({ responseId: 'r', language: 'en', values: {} });
+
+      await waitFor(() => {
+        expect(screen.getByTestId('is-loading')).toHaveTextContent('false');
+      });
+    });
+
     it.each([
       [
         'widgetConfig',
@@ -611,6 +659,7 @@ describe('withBaseWidget', () => {
         {
           widget_config_id: 'test-config-integration',
           widget_type: WidgetTypeV3.PromptCarouselV3,
+          load_id: expect.any(String),
           test_integration: true,
         },
         '0px',
@@ -686,6 +735,7 @@ describe('withBaseWidget', () => {
         {
           widget_config_id: 'widget-1',
           widget_type: WidgetTypeV3.PromptCarouselV3,
+          load_id: expect.any(String),
         },
         '0px',
         true,
@@ -695,6 +745,7 @@ describe('withBaseWidget', () => {
         {
           widget_config_id: 'widget-2',
           widget_type: WidgetTypeV3.ChatPreviewV3,
+          load_id: expect.any(String),
         },
         '0px',
         true,

package/src/hocs/withBaseWidget/types.ts

@@ -15,6 +15,13 @@ export interface BaseWidgetProps {
   uiConfig?: OrgUIConfigV3;
   isLoading?: boolean;
   isHardcopyLoading?: boolean;
+  /**
+   * True once THIS widget's own hardcopy request has settled (resolved or errored),
+   * regardless of whether it produced content. Lets a widget tell "hardcopy not received
+   * yet" apart from "hardcopy finished with no content" so it can leave a loading placeholder
+   * after a failed fetch instead of showing it forever.
+   */
+  isHardcopySettled?: boolean;
   isPageLoading?: boolean;
   isWidgetConfigLoading?: boolean;
   isUiConfigLoading?: boolean;

package/src/hocs/withBaseWidget/withBaseWidget.tsx

@@ -8,6 +8,9 @@ import { usePage } from '@envive-ai/react-hooks/contexts/pageContext';
 import { useWidgetConfig } from '@envive-ai/react-hooks/contexts/widgetConfigContext';
 import { OrgUIConfigV3, WidgetConfigV3 } from '@envive-ai/react-hooks/contexts/typesV3';
 import { useUiConfig } from '@envive-ai/react-hooks/contexts/uiConfigContext';
+import { FeatureGates } from '@envive-ai/react-hooks/application/models';
+import { useFeatureFlagService } from '@envive-ai/react-hooks/contexts/featureFlagServiceContext';
+import { useWidgetLoadDiagnostics } from '@envive-ai/react-hooks/hooks/WidgetLoadDiagnostics';
 import { BaseWidgetProps, WithBaseWidgetOptions } from './types';
 
 const logger = new Logger('withBaseWidget');
@@ -51,16 +54,28 @@ export function withBaseWidget<P extends BaseWidgetProps>(
     const [uiConfigSettled, setUiConfigSettled] = useState(false);
     const ownRequestsSettled = hardcopySettled && widgetConfigSettled && uiConfigSettled;
 
-    const isLoading =
-      !ownRequestsSettled &&
-      (isHardcopyLoading || isPageLoading || isWidgetConfigLoading || isUiConfigLoading);
+    // --- Widget load diagnostics (see useWidgetLoadDiagnostics) ---
+    // load_id correlates this widget's mount / rendered / outcome / stall events for one load.
+    const loadId = useRef(
+      `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
+    ).current;
+    const { featureFlagService } = useFeatureFlagService();
+    // Diagnostics are ON by default; the gate is a kill switch (default false → enabled) so we
+    // can gather a cross-merchant baseline. Flip it true (globally or per-org) via Statsig to stop.
+    const diagnosticsEnabled = !featureFlagService?.isFeatureGateEnabled(
+      FeatureGates.IsWidgetDiagnosticsDisabled,
+    );
+    // Reason this widget's own hardcopy request rejected (distinct from a served static fallback).
+    const hardcopyErrorRef = useRef<string | undefined>(undefined);
 
     const visibilityEventProps = {
       widget_config_id: widgetConfigId,
       widget_type: widgetType,
+      // Threaded onto [Envive] Widget Rendered so it can be joined to the diagnostics events.
+      load_id: loadId,
       ...options?.visibilityEventProps,
     };
-    const { isVisible } = useTrackComponentVisibleEvent(
+    const { isVisible, visibilitySource } = useTrackComponentVisibleEvent(
       widgetRef,
       visibilityEventProps,
       options?.rootMargin || '0px',
@@ -74,6 +89,15 @@ export function withBaseWidget<P extends BaseWidgetProps>(
       return isVisible && !!widgetConfigId && !!widgetType;
     }, [isVisible, widgetConfigId, widgetType]);
 
+    // A widget is loading only while its OWN requests are in flight. Deliberately NOT
+    // derived from the shared provider isLoading flags (isHardcopyLoading, isPageLoading,
+    // …): each of those is a single boolean shared by every widget, so any widget issuing a
+    // fetch flips them for all of them — which let another widget's activity pin this one in
+    // (or stuck in) its loading state even after its own requests had settled. `startLoading`
+    // gates the leading edge so a not-yet-started widget doesn't report loading off the
+    // still-false latches.
+    const isLoading = startLoading && !ownRequestsSettled;
+
     // Watchdog: a widget that is still in its loading state this long after it started
     // fetching is stuck (or on a very slow connection). Log a console error so session
     // tools that capture the console (Quantum Metric, Datadog RUM) can count and segment
@@ -120,8 +144,14 @@ export function withBaseWidget<P extends BaseWidgetProps>(
       hardcopyFetchedRef.current = true;
       getHardcopy({ widgetType, userEvent })
         .then(setHardcopyContent)
-        .catch(() => {
-          // Silently handle errors - widget will render without hardcopy content
+        .catch(error => {
+          // Silently handle errors - widget will render without hardcopy content. Record the
+          // reason for the load-outcome diagnostic (the served static-fallback path resolves
+          // rather than rejects, so reaching here means no content at all).
+          hardcopyErrorRef.current =
+            error instanceof Error && error.message.includes('timed out')
+              ? 'hardcopy_timeout'
+              : 'hardcopy_error';
         })
         .finally(() => {
           setHardcopySettled(true);
@@ -157,12 +187,32 @@ export function withBaseWidget<P extends BaseWidgetProps>(
         });
     }, [startLoading, widgetConfigId, widgetType, getWidgetConfig]);
 
+    const pendingRequests = [
+      hardcopySettled ? null : 'hardcopy',
+      widgetConfigSettled ? null : 'widgetConfig',
+      uiConfigSettled ? null : 'uiConfig',
+    ].filter((name): name is string => name !== null);
+
+    useWidgetLoadDiagnostics({
+      enabled: diagnosticsEnabled,
+      loadId,
+      widgetType,
+      widgetConfigId,
+      startLoading,
+      ownRequestsSettled,
+      hardcopyContent,
+      visibilitySource,
+      pendingRequests,
+      hardcopyErrorReason: hardcopyErrorRef.current,
+    });
+
     return (
       <span ref={widgetRef}>
         <Widget
           {...props}
           isLoading={isLoading}
           isHardcopyLoading={isHardcopyLoading}
+          isHardcopySettled={hardcopySettled}
           isPageLoading={isPageLoading}
           isWidgetConfigLoading={isWidgetConfigLoading}
           isUiConfigLoading={isUiConfigLoading}

package/src/stories/FullPageSalesAgentWidget.stories.tsx

@@ -1,13 +1,43 @@
+import {
+  HardcopyProvider,
+  HardcopyResponse,
+} from '@envive-ai/react-hooks/contexts/hardcopyContext';
 import {
   PageVisitCategory,
   useSalesAgent,
 } from '@envive-ai/react-hooks/contexts/salesAgentContext';
+import { WidgetTypeV3 } from '@envive-ai/react-hooks/contexts/typesV3';
+import { MockHardcopyService } from '@envive-ai/react-hooks/services/hardcopyService';
 import { UserEventCategory } from '@spiffy-ai/commerce-api-client';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useEffect } from 'react';
 import { v4 as uuid } from 'uuid';
 import { FullPageSalesAgentWidget } from '../widgets/FullPageSalesAgentWidget/FullPageSalesAgentWidget';
 
+// Overlay content for the PartialView story below — needs welcomeOverlayTitle
+// set for FullPageSalesAgent's own overlayEnabled check to pass, since
+// partialViewActive is `partialViewEnabled && overlayEnabled`.
+const partialViewHardcopy: HardcopyResponse = {
+  responseId: 'mock-fpsa-partial-view',
+  language: 'en',
+  values: {
+    welcomeMessageTitle: "Hi! I'm your personal shopping assistant",
+    welcomeMessageText: 'How can I help you today?',
+    chatFooterTextFieldPlaceholderText: 'Ask me anything...',
+    welcomeOverlayTitle: 'How can I help you find the right product?',
+    welcomeOverlayPromptSuggestions: [
+      'Help me find my size',
+      'What are your best sellers?',
+      'Gift ideas for a friend',
+    ],
+    welcomeOverlayProductCarouselTitle: 'Fan favorites',
+    welcomeOverlayProductIds: [
+      'mix-match-nursing-pumping-bra-bundle',
+      'mothers-day-morning-bundle',
+    ],
+  },
+};
+
 const meta = {
   title: 'Widgets V3/FullPageSalesAgentWidget',
   component: FullPageSalesAgentWidget,
@@ -66,3 +96,37 @@ export const Playground: Story = {
     },
   },
 };
+
+export const PartialView: Story = {
+  name: 'Partial View (default)',
+  // 'fake-widget-config-id' short-circuits withBaseWidget's real widget-config
+  // fetch (see WidgetConfigProvider.getWidgetConfig) and resolves to `{}` —
+  // partialViewEnabled then comes out `undefined`, which now correctly
+  // defaults to enabled regardless of which merchant is selected in the
+  // toolbar or what that merchant's own backend config has configured.
+  args: {
+    widgetConfigId: 'fake-widget-config-id',
+  },
+  decorators: [
+    Story => (
+      <HardcopyProvider
+        hardcopyService={
+          new MockHardcopyService({ [WidgetTypeV3.FullPageSalesAgentV3]: partialViewHardcopy })
+        }
+      >
+        <Story />
+      </HardcopyProvider>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Partial view is enabled by default — submitting a question opens the conversation in a ' +
+          "closed/partial/full bottom sheet instead of taking over the whole screen, and the widget's " +
+          'own product grid stays visible above it. Self-contained (a fake widgetConfigId plus mocked ' +
+          "hardcopy) so it renders the same regardless of the toolbar's selected merchant.",
+      },
+    },
+  },
+};

package/src/widgets/ProductCardWidget/ProductCardWidget.tsx

@@ -23,30 +23,24 @@ import { useCallback } from 'react';
 import { BaseWidgetProps, withBaseWidget } from '../../hocs/withBaseWidget';
 import { RawValues, getStringIdForText } from '../utils/functions';
 
-const mockPrompts = [
-  'Loading prompt 1',
-  'Loading prompt 2',
-  'Loading prompt 3',
-  'Loading prompt 4',
-  'Loading prompt 5',
-];
-
-const mockHeadline = 'Loading...';
-const mockAnimatedText = ['Loading...'];
-
 const ProductCardWidgetHandler = (props: BaseWidgetProps) => {
   const { onTypedMessageSubmitted } = useSalesAgent();
   const { openChat } = useChatToggle();
-  const { hardcopyContent, widgetConfig, uiConfig, isLoading } = props;
+  const { hardcopyContent, widgetConfig, uiConfig, isLoading, isHardcopySettled } = props;
+
+  // Show the skeleton while the card is loading, or while its hardcopy hasn't arrived yet (a
+  // widget deferred until visible has none). Gate the "no content yet" case on the hardcopy
+  // NOT having settled — otherwise a request that finishes without content (a failed/timed-out
+  // fetch) would leave `hardcopyContent` undefined and pin the skeleton on forever. Once the
+  // hardcopy settles empty, fall through to the normal render (static-copy fallback / empty
+  // state) instead of an endless skeleton.
+  const showSkeleton = isLoading || (!hardcopyContent && !isHardcopySettled);
 
-  const hardCopyHeadline = hardcopyContent?.values?.headline as string | undefined;
-  const headline = isLoading ? mockHeadline : hardCopyHeadline || '';
+  const headline = (hardcopyContent?.values?.headline as string | undefined) || '';
 
-  const hardCopyAnimatedText = (hardcopyContent?.values?.animatedText as string[]) || [];
-  const animatedText = isLoading ? mockAnimatedText : hardCopyAnimatedText;
+  const animatedText = (hardcopyContent?.values?.animatedText as string[]) || [];
 
-  const hardCopyPrompts = (hardcopyContent?.values?.prompts as string[]) || [];
-  const prompts = isLoading ? mockPrompts : hardCopyPrompts;
+  const prompts = (hardcopyContent?.values?.prompts as string[]) || [];
 
   const hardCopyPlaceholder = hardcopyContent?.values?.placeholder as string | undefined;
   const placeholder = hardCopyPlaceholder;
@@ -141,6 +135,7 @@ const ProductCardWidgetHandler = (props: BaseWidgetProps) => {
     <ProductCard
       theme={Theme.GLOBAL_CUSTOM}
       variant={variant}
+      isLoading={showSkeleton}
       imageSrc={imageSrc}
       fallbackColor={fallbackColor}
       headline={headline}

package/src/widgets/ProductCardWidget/__tests__/ProductCardWidget.test.tsx

@@ -10,8 +10,21 @@ const mockUseTrackComponentVisibleEvent = vi.fn(() => ({ isVisible: true }));
 
 vi.mock('@envive-ai/react-toolkit-v3/ProductCard', () => ({
   ProductCardVariant: { DARK: 'dark', LIGHT: 'light' },
-  ProductCard: ({ prompts, onSelect }: { prompts: string[]; onSelect: (text: string) => void }) => (
-    <div data-testid="product-card-mock">
+  // Expose isLoading (the widget's showSkeleton decision) so tests can assert the loading
+  // placeholder vs. rendered content across the deferred / resolved / failed fetch paths.
+  ProductCard: ({
+    prompts,
+    onSelect,
+    isLoading,
+  }: {
+    prompts: string[];
+    onSelect: (text: string) => void;
+    isLoading?: boolean;
+  }) => (
+    <div
+      data-testid="product-card-mock"
+      data-loading={String(Boolean(isLoading))}
+    >
       {prompts.map(text => (
         <button
           key={text}
@@ -47,6 +60,11 @@ vi.mock('@envive-ai/react-hooks/contexts/featureFlagServiceContext', () => ({
   useFeatureFlagService: () => ({ featureFlagService: undefined }),
 }));
 
+// Diagnostics pulls its own amplitude context internally; stub it like the other sub-hooks.
+vi.mock('@envive-ai/react-hooks/hooks/WidgetLoadDiagnostics', () => ({
+  useWidgetLoadDiagnostics: vi.fn(),
+}));
+
 vi.mock('@envive-ai/react-hooks/contexts/hardcopyContext', () => ({
   useHardcopy: () => ({
     getHardcopy: mockGetHardcopy,
@@ -118,6 +136,7 @@ describe('ProductCardWidget analytics', () => {
           {
             widget_config_id: 'test-config-1',
             widget_type: WidgetTypeV3.ProductCardV3,
+            load_id: expect.any(String),
           },
           '0px',
           true,
@@ -151,3 +170,57 @@ describe('ProductCardWidget analytics', () => {
     });
   }, 5000);
 });
+
+describe('ProductCardWidget loading state', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const hardcopy = {
+    responseId: 'test-response-id',
+    language: 'en',
+    values: { prompts: ['Prompt 1', 'Prompt 2'] },
+    rawValues: { prompts: [{ id: 'id-1', value: 'Prompt 1' }] },
+  };
+
+  const loadingState = () => screen.getByTestId('product-card-mock').dataset.loading;
+
+  it('shows the skeleton while the hardcopy is pending, then renders content once it resolves', async () => {
+    let resolveHardcopy: (value: typeof hardcopy) => void = () => {};
+    mockGetHardcopy.mockReturnValue(
+      new Promise<typeof hardcopy>(resolve => {
+        resolveHardcopy = resolve;
+      }),
+    );
+
+    render(<ProductCardWidget widgetConfigId="loading-1" />);
+
+    // Hardcopy not received yet → skeleton.
+    await waitFor(() => expect(loadingState()).toBe('true'), { timeout: 3000 });
+
+    resolveHardcopy(hardcopy);
+
+    // Content arrived → skeleton gone.
+    await waitFor(() => expect(loadingState()).toBe('false'), { timeout: 3000 });
+    expect(screen.getByText('Prompt 1')).toBeInTheDocument();
+  }, 5000);
+
+  it('renders content and drops the skeleton after a successful fetch', async () => {
+    mockGetHardcopy.mockResolvedValue(hardcopy);
+
+    render(<ProductCardWidget widgetConfigId="loading-2" />);
+
+    await waitFor(() => expect(loadingState()).toBe('false'), { timeout: 3000 });
+    expect(screen.getByText('Prompt 1')).toBeInTheDocument();
+  }, 5000);
+
+  it('drops the skeleton after the hardcopy fetch fails instead of hanging on it forever', async () => {
+    // A rejected (or timed-out) hardcopy settles without content. The widget must fall through
+    // to the normal render rather than pinning the skeleton on indefinitely.
+    mockGetHardcopy.mockRejectedValue(new Error('hardcopy failed'));
+
+    render(<ProductCardWidget widgetConfigId="loading-3" />);
+
+    await waitFor(() => expect(loadingState()).toBe('false'), { timeout: 3000 });
+  }, 5000);
+});