@capillarytech/creatives-library 9.0.59-alpha.2 → 9.0.60

package/v2Components/FormBuilder/index.js

@@ -6,11 +6,10 @@
  * monolith, frozen) and the new functional implementation (./Functional)
  * based on the per-channel, per-org feature flag.
  *
- * Phase 1 migrated SMS behind `ENABLE_NEW_FORMBUILDER_SMS`; Phase 2 migrates
- * MOBILEPUSH behind `ENABLE_NEW_FORMBUILDER_MPUSH`. The new path is taken ONLY
- * when (a) the org has that channel's flag AND (b) this FormBuilder instance is
- * rendering that channel. Every other channel — and every org without the
- * flag — keeps using Classic with byte-identical behavior. The flags default
+ * Phase 1 migrates SMS only, behind `ENABLE_NEW_FORMBUILDER_SMS`. The new path
+ * is taken ONLY when (a) the org has that flag AND (b) this FormBuilder instance
+ * is rendering the SMS channel. Every other channel — and every org without the
+ * flag — keeps using Classic with byte-identical behavior. The flag defaults
  * OFF, so until rollout this gate always renders Classic.
  *
  * This component is a pure pass-through: no defaultProps, no prop mapping, no
@@ -22,30 +21,24 @@
 import React, { useState } from 'react';
 import ClassicFormBuilder from './Classic';
 import FunctionalFormBuilder from './Functional';
-import {
-  hasNewFormBuilderEnabledForSms,
-  hasNewFormBuilderEnabledForMpush,
-} from '../../utils/common';
-import { SMS, MOBILE_PUSH } from '../../v2Containers/CreativesContainer/constants';
+import { hasNewFormBuilderEnabledForSms } from '../../utils/common';
+import { SMS } from '../../v2Containers/CreativesContainer/constants';
 
 const FormBuilder = (props) => {
-  // One-time org-flag read (API-provisioned via Auth.hasFeatureAccess); the try/catch
-  // guards early bootstrap where window.capAuth is not ready — any failure routes to Classic.
-  const [newBuilderFlags] = useState(() => {
+  // The try/catch guards the early bootstrap / test case where window.capAuth is not yet initialized — any failure routes safely to Classic.
+  const [isSmsNewBuilderOrg] = useState(() => {
     try {
-      return {
-        [SMS]: Boolean(hasNewFormBuilderEnabledForSms()),
-        [MOBILE_PUSH]: Boolean(hasNewFormBuilderEnabledForMpush()),
-      };
+      console.log('### ENABLE_NEW_FORMBUILDER_SMS enabled for org:', hasNewFormBuilderEnabledForSms());
+      return Boolean(hasNewFormBuilderEnabledForSms());
     } catch (e) {
-      return {};
+      return false;
     }
   });
 
-  // Derived every render: the schema (and therefore the channel) arrives asynchronously.
   const channel = (props?.channel || props.schema?.channel)?.toUpperCase();
 
-  return newBuilderFlags[channel] ? (
+  const useNewFormBuilder = isSmsNewBuilderOrg && channel === SMS;
+  return useNewFormBuilder ? (
     <FunctionalFormBuilder {...props} />
   ) : (
     <ClassicFormBuilder {...props} />

package/v2Components/FormBuilder/tests/entryGate.test.js

@@ -5,10 +5,10 @@
  * implementations are mocked with trivial stubs so this stays a fast unit test
  * of the gate, independent of the 4,400-line monolith.
  *
- * Contract pinned here (per-channel flag map — SMS Phase 1, MOBILEPUSH Phase 2):
- *   - flags OFF -> Classic, for every channel (the default until rollout)
- *   - a channel's flag ON + that channel (via `channel` prop OR `schema.channel`) -> Functional
- *   - a channel's flag ON + any OTHER channel -> Classic (flags are independent)
+ * Contract pinned here:
+ *   - flag OFF  -> Classic, for every channel (the default until rollout)
+ *   - flag ON + SMS channel (via `channel` prop OR `schema.channel`) -> Functional
+ *   - flag ON + non-SMS channel -> Classic (other channels untouched)
  *   - flag ON + channel unknown (async schema not yet arrived) -> Classic
  *   - flag read throws (bootstrap/test race) -> Classic, no crash
  */
@@ -25,26 +25,20 @@ jest.mock('../Functional', () => (props) => (
   <div data-testid="impl-functional">functional:{(props.schema && props.schema.channel) || props.channel || ''}</div>
 ));
 
-// Mock only the flag readers the gate uses; keep the rest of common.js intact.
+// Mock only the one flag reader the gate uses; keep the rest of common.js intact.
 jest.mock('../../../utils/common', () => ({
   ...jest.requireActual('../../../utils/common'),
   hasNewFormBuilderEnabledForSms: jest.fn(),
-  hasNewFormBuilderEnabledForMpush: jest.fn(),
 }));
 
 // eslint-disable-next-line import/first
 import FormBuilder from '../index';
 // eslint-disable-next-line import/first
-import { hasNewFormBuilderEnabledForSms, hasNewFormBuilderEnabledForMpush } from '../../../utils/common';
+import { hasNewFormBuilderEnabledForSms } from '../../../utils/common';
 
 const renderGate = (props = {}) => render(<FormBuilder {...props} />);
 
 describe('FormBuilder entry gate — routing', () => {
-  beforeEach(() => {
-    hasNewFormBuilderEnabledForSms.mockReturnValue(false);
-    hasNewFormBuilderEnabledForMpush.mockReturnValue(false);
-  });
-
   describe('flag OFF (default)', () => {
     beforeEach(() => hasNewFormBuilderEnabledForSms.mockReturnValue(false));
 
@@ -99,73 +93,8 @@ describe('FormBuilder entry gate — routing', () => {
     });
   });
 
-  describe('MPUSH flag (ENABLE_NEW_FORMBUILDER_MPUSH — Phase 2)', () => {
-    it('flag OFF: MOBILEPUSH renders Classic', () => {
-      renderGate({ schema: { channel: 'MOBILEPUSH' } });
-      expect(screen.getByTestId('impl-classic')).toBeInTheDocument();
-    });
-
-    it('flag ON: routes MOBILEPUSH to Functional (schema.channel)', () => {
-      hasNewFormBuilderEnabledForMpush.mockReturnValue(true);
-      renderGate({ schema: { channel: 'MOBILEPUSH' } });
-      expect(screen.getByTestId('impl-functional')).toBeInTheDocument();
-      expect(screen.queryByTestId('impl-classic')).toBeNull();
-    });
-
-    it('flag ON: is case-insensitive and honors the channel prop', () => {
-      hasNewFormBuilderEnabledForMpush.mockReturnValue(true);
-      renderGate({ channel: 'mobilepush', schema: {} });
-      expect(screen.getByTestId('impl-functional')).toBeInTheDocument();
-    });
-
-    it('flags are independent: MPUSH flag ON does not move SMS (and vice versa)', () => {
-      hasNewFormBuilderEnabledForMpush.mockReturnValue(true);
-      renderGate({ schema: { channel: 'SMS' } });
-      expect(screen.getByTestId('impl-classic')).toBeInTheDocument();
-    });
-
-    it('SMS flag ON does not move MOBILEPUSH', () => {
-      hasNewFormBuilderEnabledForSms.mockReturnValue(true);
-      renderGate({ schema: { channel: 'MOBILEPUSH' } });
-      expect(screen.getByTestId('impl-classic')).toBeInTheDocument();
-    });
-
-    it('both flags ON route each channel to Functional', () => {
-      hasNewFormBuilderEnabledForSms.mockReturnValue(true);
-      hasNewFormBuilderEnabledForMpush.mockReturnValue(true);
-      renderGate({ schema: { channel: 'MOBILEPUSH' } });
-      expect(screen.getByTestId('impl-functional')).toHaveTextContent('functional:MOBILEPUSH');
-    });
-
-    it('unmigrated channels stay on Classic even with both flags ON', () => {
-      hasNewFormBuilderEnabledForSms.mockReturnValue(true);
-      hasNewFormBuilderEnabledForMpush.mockReturnValue(true);
-      renderGate({ schema: { channel: 'EMAIL' } });
-      expect(screen.getByTestId('impl-classic')).toBeInTheDocument();
-    });
-  });
-
-  describe('the gate is purely org-flag controlled (no localStorage override)', () => {
-    afterEach(() => {
-      window.localStorage.removeItem('ENABLE_NEW_FORMBUILDER_MPUSH');
-    });
-
-    it('a localStorage key does NOT enable the new path when the org flag is OFF', () => {
-      window.localStorage.setItem('ENABLE_NEW_FORMBUILDER_MPUSH', 'true');
-      renderGate({ schema: { channel: 'MOBILEPUSH' } });
-      expect(screen.getByTestId('impl-classic')).toBeInTheDocument();
-    });
-
-    it('a localStorage key does NOT disable the new path when the org flag is ON', () => {
-      hasNewFormBuilderEnabledForMpush.mockReturnValue(true);
-      window.localStorage.setItem('ENABLE_NEW_FORMBUILDER_MPUSH', 'false');
-      renderGate({ schema: { channel: 'MOBILEPUSH' } });
-      expect(screen.getByTestId('impl-functional')).toBeInTheDocument();
-    });
-  });
-
   describe('resilience', () => {
-    it('falls back to Classic if a flag read throws (window.capAuth not initialized)', () => {
+    it('falls back to Classic if the flag read throws (window.capAuth not initialized)', () => {
       hasNewFormBuilderEnabledForSms.mockImplementation(() => {
         throw new Error('capAuth not initialized');
       });
@@ -173,14 +102,5 @@ describe('FormBuilder entry gate — routing', () => {
       expect(screen.getByTestId('impl-classic')).toBeInTheDocument();
       expect(screen.queryByTestId('impl-functional')).toBeNull();
     });
-
-    it('one flag reader throwing routes EVERY channel to Classic (whole map falls back)', () => {
-      hasNewFormBuilderEnabledForSms.mockReturnValue(true);
-      hasNewFormBuilderEnabledForMpush.mockImplementation(() => {
-        throw new Error('capAuth not initialized');
-      });
-      renderGate({ schema: { channel: 'SMS' } });
-      expect(screen.getByTestId('impl-classic')).toBeInTheDocument();
-    });
   });
 });

package/v2Containers/CommunicationFlow/CommunicationFlow.js

@@ -20,7 +20,7 @@ import CapNotification from '@capillarytech/cap-ui-library/CapNotification';
 import injectReducer from '../../utils/injectReducer';
 import { makeSelectAuthenticated } from '../Cap/selectors';
 import capReducer from '../Cap/reducer';
-import { createCommDefinition, editCommDefinition, getCommDefinition, getCommDefinitionVersion } from '../../services/api';
+import { createCommDefinition, editCommDefinition } from '../../services/api';
 import DynamicControlsStep from './steps/DynamicControlsStep';
 import MessageTypeStep from './steps/MessageTypeStep';
 import CommunicationStrategyStep from './steps/CommunicationStrategyStep';
@@ -44,7 +44,7 @@ import {
   SINGLE_TEMPLATE,
 } from './constants';
 import { getEnabledSteps } from './utils/getEnabledSteps';
-import { fetchAndMapCommDefinition } from './utils/mapCommDefinitionToStepData';
+import useFetchCommDefinition from './hooks/useFetchCommDefinition';
 import messages from './messages';
 import './CommunicationFlow.scss';
 
@@ -79,23 +79,18 @@ const CommunicationFlow = ({
   const { formatMessage } = intl || {};
   const { messageTypeData = {}, communicationStrategyData = {}, contentTemplateData = {} } = config?.features || {};
 
-  // A consumer other than CapNotify (which always pre-fetches and passes full initialData
-  // itself) may hand CommunicationFlow only a commDefinitionId — no local content copy at all
-  // — and rely on CommunicationFlow to fetch + populate its own content (see the fetch effect
-  // below, and mapCommDefinitionToStepData). Captured once at mount: initialData/config aren't
-  // expected to change identity across the component's lifetime for this decision.
+  // Other consumers may provide only commDefinitionId and rely on CommunicationFlow to fetch
+  // content; captured once at mount so it also seeds messageType/communicationStrategy below,
+  // before useFetchCommDefinition's effect (mount-only) has a chance to run.
   const [shouldFetchCommDefinition] = useState(
     () => !!config?.context?.existingCommDefinitionId && !initialData?.contentItems?.length,
   );
-  const [isFetchingCommDefinition, setIsFetchingCommDefinition] = useState(shouldFetchCommDefinition);
 
   // Initialize step data from initialData or defaults
   const [stepData, setStepData] = useState(() => {
     const defaultMessageType = messageTypeData.defaultOption?.value || MESSAGE_TYPES_OPTIONS?.[1]?.value || null;
     return {
-      // Pre-set to CCS's only supported strategy so the Channel Selection step (which only
-      // renders once communicationStrategy is set) is already mounted — showing its own
-      // loading state — while the fetch below is in flight, instead of staying blank/unmounted.
+      // Pre-set CCS's only supported strategy so Channel Selection mounts and shows its loading state while the fetch is in flight.
       messageType: initialData?.messageType || (shouldFetchCommDefinition ? 'transactional' : defaultMessageType),
       communicationStrategy: initialData?.communicationStrategy || (shouldFetchCommDefinition ? SINGLE_TEMPLATE : null),
       channel: initialData?.channel || config.channel || null,
@@ -109,27 +104,13 @@ const CommunicationFlow = ({
   const [validationErrors, setValidationErrors] = useState({});
 
   // Fetch-by-id: populate stepData from the CommDefinition itself when the consumer only
-  // supplied a commDefinitionId (see shouldFetchCommDefinition above). Runs once on mount.
-  useEffect(() => {
-    if (!shouldFetchCommDefinition) return;
-    let cancelled = false;
-    (async () => {
-      try {
-        const mapped = await fetchAndMapCommDefinition(config.context.existingCommDefinitionId, {
-          getCommDefinition,
-          getCommDefinitionVersion,
-        });
-        if (!cancelled && mapped) {
-          setStepData((prevStepData) => ({ ...prevStepData, ...mapped }));
-        }
-      } catch (error) {
-        console.error('[CommunicationFlow] fetchAndMapCommDefinition error:', error);
-      } finally {
-        if (!cancelled) setIsFetchingCommDefinition(false);
-      }
-    })();
-    return () => { cancelled = true; };
-  }, []);
+  // supplied a commDefinitionId (see shouldFetchCommDefinition above). Shared with
+  // CommunicationFlowCard.js via useFetchCommDefinition.
+  const isFetchingCommDefinition = useFetchCommDefinition({
+    existingCommDefinitionId: config?.context?.existingCommDefinitionId,
+    hasLocalContent: !!initialData?.contentItems?.length,
+    onFetched: (mapped) => setStepData((prevStepData) => ({ ...prevStepData, ...mapped })),
+  });
 
   // Memoize enabled steps
   const enabledSteps = useMemo(() => getEnabledSteps(config), [config]);

package/v2Containers/CommunicationFlow/CommunicationFlowCard.js

@@ -27,8 +27,7 @@ import {
   VIBER, SMS, EMAIL, WHATSAPP, RCS, ZALO,
 } from '../CreativesContainer/constants';
 import getContentBody from './utils/getContentBody';
-import { getCommDefinition, getCommDefinitionVersion } from '../../services/api';
-import { fetchAndMapCommDefinition } from './utils/mapCommDefinitionToStepData';
+import useFetchCommDefinition from './hooks/useFetchCommDefinition';
 import messages from './messages';
 import addCreativesIllustration from '../Assets/images/addCreativesIllustration.svg';
 import './CommunicationFlow.scss';
@@ -93,39 +92,14 @@ const CommunicationFlowCard = ({
     }
   }, [initialData]);
 
-  // A consumer other than CapNotify (which always pre-fetches and passes full initialData
-  // itself) may hand this card only a commDefinitionId — no local content copy at all — and
-  // rely on CommunicationFlowCard to fetch + show the configured summary itself, instead of
-  // the empty "Add creatives" state. Mirrors CommunicationFlow.js's own fetch-by-id path
-  // (config.context.existingCommDefinitionId); doing it here too means the SUMMARY CARD
-  // reflects fetched content immediately, without the user having to open the slidebox and
-  // click Save first — CommunicationFlow's own fetch would only ever reach this card's
-  // savedData via that save round-trip, since nothing here listens for its internal onChange.
-  const [isFetchingCommDefinition, setIsFetchingCommDefinition] = useState(
-    () => !!config?.context?.existingCommDefinitionId && !initialData?.contentItems?.length,
-  );
-
-  useEffect(() => {
-    const existingCommDefinitionId = config?.context?.existingCommDefinitionId;
-    if (!existingCommDefinitionId || initialData?.contentItems?.length) return undefined;
-    let cancelled = false;
-    (async () => {
-      try {
-        const mapped = await fetchAndMapCommDefinition(existingCommDefinitionId, {
-          getCommDefinition,
-          getCommDefinitionVersion,
-        });
-        if (!cancelled && mapped) {
-          setSavedData((prevSavedData) => ({ ...prevSavedData, ...mapped }));
-        }
-      } catch (error) {
-        console.error('[CommunicationFlowCard] fetchAndMapCommDefinition error:', error);
-      } finally {
-        if (!cancelled) setIsFetchingCommDefinition(false);
-      }
-    })();
-    return () => { cancelled = true; };
-  }, []);
+  // Other consumers may provide only commDefinitionId; fetch it here so the summary card shows
+  // configured content immediately instead of "Add creatives". Shared with CommunicationFlow.js
+  // via useFetchCommDefinition.
+  const isFetchingCommDefinition = useFetchCommDefinition({
+    existingCommDefinitionId: config?.context?.existingCommDefinitionId,
+    hasLocalContent: !!initialData?.contentItems?.length,
+    onFetched: (mapped) => setSavedData((prevSavedData) => ({ ...prevSavedData, ...mapped })),
+  });
 
   const handleSave = useCallback((data) => {
     setSavedData(data);
@@ -241,7 +215,7 @@ const CommunicationFlowCard = ({
           className="communication-flow-card-loading"
           bodyStyle={{ padding: 0, height: 152 }}
         >
-          <CapRow type="flex" justify="center" align="middle" style={{ height: '100%' }}>
+          <CapRow type="flex" justify="center" align="middle" className="loading-card-body-row">
             <CapSpin spinning />
           </CapRow>
         </CapCard>

package/v2Containers/CommunicationFlow/Tests/CommunicationFlow.test.js

@@ -3,6 +3,12 @@ import React from 'react';
 jest.mock('../../../services/api', () => ({
   createCommDefinition: jest.fn(),
   editCommDefinition: jest.fn(),
+  getCommDefinition: jest.fn(),
+  getCommDefinitionVersion: jest.fn(),
+}));
+
+jest.mock('../utils/mapCommDefinitionToStepData', () => ({
+  fetchAndMapCommDefinition: jest.fn(),
 }));
 
 jest.mock('@capillarytech/cap-ui-library/CapNotification', () => ({
@@ -47,6 +53,7 @@ import { initialReducer } from '../../../initialReducer';
 import CommunicationFlow from '../CommunicationFlow';
 import CapNotification from '@capillarytech/cap-ui-library/CapNotification';
 import { createCommDefinition, editCommDefinition } from '../../../services/api';
+import { fetchAndMapCommDefinition } from '../utils/mapCommDefinitionToStepData';
 import { getEnabledSteps } from '../utils/getEnabledSteps';
 import {
   CHANNELS,
@@ -921,6 +928,82 @@ describe('handleSave — CCS flow', () => {
   });
 });
 
+describe('CommunicationFlow — fetch-by-id (config.context.existingCommDefinitionId, no local content)', () => {
+  const ccsConfig = { ...baseConfig, context: { name: 'Order Placed Notification' }, features: {} };
+  const configWithId = {
+    ...ccsConfig,
+    context: { ...ccsConfig.context, existingCommDefinitionId: 'cd_fetch_1' },
+  };
+
+  beforeEach(() => {
+    fetchAndMapCommDefinition.mockReset();
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('fetches and merges the mapped data into stepData when only a commDefinitionId is supplied', async () => {
+    fetchAndMapCommDefinition.mockResolvedValue({
+      channel: 'SMS',
+      contentItems: [{ contentId: 'cd_fetch_1', channel: 'SMS', templateData: { messageBody: 'Hi' } }],
+      ccsCommDefinition: { id: 'cd_fetch_1', referenceId: 'ref_1', version: 1, status: 'DRAFT' },
+    });
+    const onChange = jest.fn();
+    renderWithFlow({ features: {}, config: configWithId, initialData: null, onChange });
+
+    await waitFor(() => expect(fetchAndMapCommDefinition).toHaveBeenCalledWith(
+      'cd_fetch_1',
+      expect.objectContaining({
+        getCommDefinition: expect.any(Function),
+        getCommDefinitionVersion: expect.any(Function),
+      }),
+    ));
+
+    await waitFor(() => {
+      const payload = onChange.mock.calls[onChange.mock.calls.length - 1][0];
+      expect(payload.contentItems).toEqual([
+        { contentId: 'cd_fetch_1', channel: 'SMS', templateData: { messageBody: 'Hi' } },
+      ]);
+    });
+  });
+
+  it('does not crash and leaves stepData unchanged when the fetch resolves with nothing mappable', async () => {
+    fetchAndMapCommDefinition.mockResolvedValue(null);
+    const onChange = jest.fn();
+    renderWithFlow({ features: {}, config: configWithId, initialData: null, onChange });
+
+    await waitFor(() => expect(fetchAndMapCommDefinition).toHaveBeenCalledTimes(1));
+    const payload = onChange.mock.calls[onChange.mock.calls.length - 1][0];
+    expect(payload.contentItems).toEqual([]);
+  });
+
+  it('does not crash when the fetch rejects', async () => {
+    fetchAndMapCommDefinition.mockRejectedValue(new Error('network error'));
+    renderWithFlow({ features: {}, config: configWithId, initialData: null });
+
+    await waitFor(() => expect(fetchAndMapCommDefinition).toHaveBeenCalledTimes(1));
+  });
+
+  it('does not fetch when initialData already has contentItems (e.g. CapNotify, which always pre-fetches itself)', async () => {
+    renderWithFlow({
+      features: {},
+      config: configWithId,
+      initialData: { contentItems: [{ channel: 'SMS', templateData: {} }] },
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(fetchAndMapCommDefinition).not.toHaveBeenCalled();
+  });
+
+  it('does not fetch when config.context.existingCommDefinitionId is absent', async () => {
+    renderWithFlow({ features: {}, config: ccsConfig, initialData: null });
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(fetchAndMapCommDefinition).not.toHaveBeenCalled();
+  });
+});
+
 describe('renderSteps — null returns and edge cases', () => {
   it('returns null for CHANNEL_SELECTION when communicationStrategy is null', () => {
     renderWithFlow({

package/v2Containers/CommunicationFlow/hooks/Tests/useFetchCommDefinition.test.js

@@ -0,0 +1,118 @@
+import { renderHook } from '@testing-library/react-hooks';
+import { waitFor } from '@testing-library/react';
+
+jest.mock('../../../../services/api', () => ({
+  getCommDefinition: jest.fn(),
+  getCommDefinitionVersion: jest.fn(),
+}));
+
+jest.mock('../../utils/mapCommDefinitionToStepData', () => ({
+  fetchAndMapCommDefinition: jest.fn(),
+}));
+
+import useFetchCommDefinition from '../useFetchCommDefinition';
+import { getCommDefinition, getCommDefinitionVersion } from '../../../../services/api';
+import { fetchAndMapCommDefinition } from '../../utils/mapCommDefinitionToStepData';
+
+describe('useFetchCommDefinition', () => {
+  beforeEach(() => {
+    fetchAndMapCommDefinition.mockReset();
+  });
+
+  it('starts in a fetching state and calls onFetched with the mapped result once the fetch resolves', async () => {
+    fetchAndMapCommDefinition.mockResolvedValue({ channel: 'SMS', contentItems: [{ contentId: 'cd_1' }] });
+    const onFetched = jest.fn();
+
+    const { result } = renderHook(() => useFetchCommDefinition({
+      existingCommDefinitionId: 'cd_1',
+      hasLocalContent: false,
+      onFetched,
+    }));
+
+    expect(result.current).toBe(true);
+
+    await waitFor(() => expect(result.current).toBe(false));
+    expect(fetchAndMapCommDefinition).toHaveBeenCalledWith('cd_1', {
+      getCommDefinition,
+      getCommDefinitionVersion,
+    });
+    expect(onFetched).toHaveBeenCalledWith({ channel: 'SMS', contentItems: [{ contentId: 'cd_1' }] });
+  });
+
+  it('does not call onFetched when the fetch resolves with nothing mappable, but still stops fetching', async () => {
+    fetchAndMapCommDefinition.mockResolvedValue(null);
+    const onFetched = jest.fn();
+
+    const { result } = renderHook(() => useFetchCommDefinition({
+      existingCommDefinitionId: 'cd_1',
+      hasLocalContent: false,
+      onFetched,
+    }));
+
+    await waitFor(() => expect(result.current).toBe(false));
+    expect(onFetched).not.toHaveBeenCalled();
+  });
+
+  it('does not crash and stops fetching when the fetch rejects', async () => {
+    fetchAndMapCommDefinition.mockRejectedValue(new Error('network error'));
+    const onFetched = jest.fn();
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    const { result } = renderHook(() => useFetchCommDefinition({
+      existingCommDefinitionId: 'cd_1',
+      hasLocalContent: false,
+      onFetched,
+    }));
+
+    await waitFor(() => expect(result.current).toBe(false));
+    expect(onFetched).not.toHaveBeenCalled();
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('never fetches, and reports isFetchingCommDefinition as false throughout, when hasLocalContent is true', async () => {
+    const onFetched = jest.fn();
+
+    const { result } = renderHook(() => useFetchCommDefinition({
+      existingCommDefinitionId: 'cd_1',
+      hasLocalContent: true,
+      onFetched,
+    }));
+
+    expect(result.current).toBe(false);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(fetchAndMapCommDefinition).not.toHaveBeenCalled();
+  });
+
+  it('never fetches when existingCommDefinitionId is absent', async () => {
+    const onFetched = jest.fn();
+
+    const { result } = renderHook(() => useFetchCommDefinition({
+      existingCommDefinitionId: undefined,
+      hasLocalContent: false,
+      onFetched,
+    }));
+
+    expect(result.current).toBe(false);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(fetchAndMapCommDefinition).not.toHaveBeenCalled();
+  });
+
+  it('does not call onFetched after unmount, even if the fetch resolves late', async () => {
+    let resolveFetch;
+    fetchAndMapCommDefinition.mockReturnValue(new Promise((resolve) => { resolveFetch = resolve; }));
+    const onFetched = jest.fn();
+
+    const { unmount } = renderHook(() => useFetchCommDefinition({
+      existingCommDefinitionId: 'cd_1',
+      hasLocalContent: false,
+      onFetched,
+    }));
+
+    unmount();
+    resolveFetch({ channel: 'SMS', contentItems: [{ contentId: 'cd_1' }] });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(onFetched).not.toHaveBeenCalled();
+  });
+});

package/v2Containers/CommunicationFlow/hooks/useFetchCommDefinition.js

@@ -0,0 +1,49 @@
+/**
+ * Shared by CommunicationFlow.js and CommunicationFlowCard.js — both need to fetch + reverse-map
+ * a CommDefinition by id when a consumer supplies only config.context.existingCommDefinitionId
+ * and no local content copy (see mapCommDefinitionToStepData.js). Previously duplicated in both
+ * files; this hook is the single place that owns the fetch, its loading state, and error handling.
+ */
+import { useState, useEffect } from 'react';
+import { getCommDefinition, getCommDefinitionVersion } from '../../../services/api';
+import { fetchAndMapCommDefinition } from '../utils/mapCommDefinitionToStepData';
+
+/**
+ * @param {string|undefined} existingCommDefinitionId - config.context.existingCommDefinitionId
+ * @param {boolean} hasLocalContent - true when the consumer already supplied content
+ *   (e.g. CapNotify, which always pre-fetches and passes full initialData itself) — skips the fetch.
+ * @param {(mapped: object) => void} onFetched - called once, only when the fetch resolves with
+ *   mappable data; the caller merges `mapped` into its own state (stepData/savedData).
+ * @returns {boolean} isFetchingCommDefinition - true from mount until the fetch settles; always
+ *   false when existingCommDefinitionId is absent or hasLocalContent is true.
+ */
+export default function useFetchCommDefinition({ existingCommDefinitionId, hasLocalContent, onFetched }) {
+  // Captured once at mount — existingCommDefinitionId/hasLocalContent aren't expected to change
+  // identity across the component's lifetime for this decision.
+  const [shouldFetch] = useState(() => !!existingCommDefinitionId && !hasLocalContent);
+  const [isFetchingCommDefinition, setIsFetchingCommDefinition] = useState(shouldFetch);
+
+  useEffect(() => {
+    if (!shouldFetch) return undefined;
+    let cancelled = false;
+    (async () => {
+      try {
+        const mapped = await fetchAndMapCommDefinition(existingCommDefinitionId, {
+          getCommDefinition,
+          getCommDefinitionVersion,
+        });
+        if (!cancelled && mapped) {
+          onFetched(mapped);
+        }
+      } catch (error) {
+        console.error('[useFetchCommDefinition] fetchAndMapCommDefinition error:', error);
+      } finally {
+        if (!cancelled) setIsFetchingCommDefinition(false);
+      }
+    })();
+    return () => { cancelled = true; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return isFetchingCommDefinition;
+}

package/v2Containers/CommunicationFlow/steps/ChannelSelectionStep/ChannelSelectionStep.js

@@ -55,11 +55,7 @@ const ChannelSelectionStep = ({
   intl,
   capData, // From Redux - contains user/org info needed by CouponsWrapper
   config,
-  // True while CommunicationFlow is fetching an existing CommDefinition's content by id (see
-  // config.context.existingCommDefinitionId in CommunicationFlow.js) — shown in place of the
-  // empty "Add creative" state so a consumer that only stored a commDefinitionId doesn't flash
-  // an empty content step before the fetched content arrives.
-  isContentLoading = false,
+  isContentLoading = false, // True while fetching existing CommDefinition content by id.
 }) => {
   const contentItems = value?.contentItems || [];
   const [showCreativesContainer, setShowCreativesContainer] = useState(false);

package/v2Containers/CommunicationFlow/steps/ChannelSelectionStep/Tests/ChannelSelectionStep.test.js

@@ -138,6 +138,34 @@ describe('ChannelSelectionStep', () => {
     expect(screen.queryByTestId('creatives-mock')).not.toBeInTheDocument();
   });
 
+  it('shows a loading spinner instead of the "Add creative" empty state while isContentLoading is true', () => {
+    renderStep(
+      <ChannelSelectionStep
+        value={{ contentItems: [] }}
+        onChange={jest.fn()}
+        channels={CHANNELS}
+        isContentLoading
+      />,
+    );
+
+    expect(screen.queryByRole('button', { name: /add creative/i })).not.toBeInTheDocument();
+    expect(document.querySelector('.content-loading')).toBeInTheDocument();
+  });
+
+  it('shows the empty "Add creative" state (not the loading spinner) once isContentLoading is false, even with no content', () => {
+    renderStep(
+      <ChannelSelectionStep
+        value={{ contentItems: [] }}
+        onChange={jest.fn()}
+        channels={CHANNELS}
+        isContentLoading={false}
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: /add creative/i })).toBeInTheDocument();
+    expect(document.querySelector('.content-loading')).not.toBeInTheDocument();
+  });
+
   it('shows validation error when error prop is set', () => {
     renderStep(
       <ChannelSelectionStep