Rework structure not to impact third party sites but keep rgaa requirements (#203)

Uses neutral html tags with `roles` to keep the best practices for accessibility and screen readers but avoid injecting HTML structure that could impact third party websites that integrates our widget.

Author: FranceBe

accessibility/ACCESSIBILITY_DOCUMENTATION.md

@@ -23,12 +23,12 @@ const DesktopModal: FC<Props> = ({ children, isSomePlanDeferred, cards, isCurren
     aria-modal="true"
     aria-labelledby="modal-title"
   >
-    <aside className={cx([s.block, s.left, STATIC_CUSTOMISATION_CLASSES.leftSide])}>
+    <div className={cx([s.block, s.left, STATIC_CUSTOMISATION_CLASSES.leftSide])}>
       <Title isSomePlanDeferred={isSomePlanDeferred} isCurrentPlanP1X={isCurrentPlanP1X} />
       <Info id="payment-info" isCurrentPlanP1X={isCurrentPlanP1X} />
       {cards && <Cards cards={cards} />}
       <AlmaLogo className={s.logo} width="75" />
-    </aside>
+    </div>
     <div className={cx(s.block, STATIC_CUSTOMISATION_CLASSES.rightSide)}>{children}</div>
   </div>
 )

src/Widgets/EligibilityModal/DesktopModal/index.tsx

@@ -45,12 +45,12 @@ const EligibilityPlansButtons: FC<{
 
   return (
     <div>
-      <h5 id="payment-plans-title" className="sr-only">
+      <div id="payment-plans-title" className="sr-only" role="heading" aria-level={2}>
         {intl.formatMessage({
           id: 'accessibility.payment-plans.section-title',
           defaultMessage: 'Options de paiement disponibles',
         })}
-      </h5>
+      </div>
       <div
         id={id}
         className={cx(s.buttons, STATIC_CUSTOMISATION_CLASSES.eligibilityOptions)}

src/Widgets/EligibilityModal/components/EligibilityPlansButtons/index.tsx

@@ -19,12 +19,12 @@ const Info: FC<{ isCurrentPlanP1X: boolean; id?: string }> = ({ isCurrentPlanP1X
     aria-describedby="payment-info-description"
     tabIndex={-1}
   >
-    <h5 id="payment-info-title" className="sr-only">
+    <div id="payment-info-title" className="sr-only" role="heading" aria-level={2}>
       <FormattedMessage
         id="eligibility-modal.info-title"
         defaultMessage="Comment procéder au paiement"
       />
-    </h5>{' '}
+    </div>{' '}
     <ol className={s.listContainer} id="payment-info-description">
       <li className={s.listItem}>
         <div className={cx(s.bullet, STATIC_CUSTOMISATION_CLASSES.bullet)}>1</div>

src/Widgets/EligibilityModal/components/Info/index.tsx

@@ -18,12 +18,12 @@ const Schedule: FC<{ currentPlan: EligibilityPlan; id?: string }> = ({ currentPl
     aria-describedby="payment-schedule-description"
     tabIndex={-1}
   >
-    <h6 id="payment-schedule-title" className="sr-only">
+    <div id="payment-schedule-title" className="sr-only" role="heading" aria-level={2}>
       <FormattedMessage
         id="accessibility.payment-schedule-title"
         defaultMessage="Calendrier de paiement"
       />
-    </h6>
+    </div>
     <div id="payment-schedule-description">
       <ul
         className={cx(s.schedule, STATIC_CUSTOMISATION_CLASSES.scheduleDetails)}

src/Widgets/EligibilityModal/components/Schedule/index.tsx

@@ -10,10 +10,12 @@ const Title: FC<{ isSomePlanDeferred: boolean; isCurrentPlanP1X: boolean }> = ({
   isSomePlanDeferred,
   isCurrentPlanP1X,
 }) => (
-  <h5
+  <div
     id="modal-title"
     className={cx(s.title, STATIC_CUSTOMISATION_CLASSES.title)}
     data-testid="modal-title-element"
+    role="heading"
+    aria-level={1}
   >
     {isSomePlanDeferred && (
       <FormattedMessage
@@ -33,7 +35,7 @@ const Title: FC<{ isSomePlanDeferred: boolean; isCurrentPlanP1X: boolean }> = ({
         defaultMessage="Payez en plusieurs fois par carte bancaire avec Alma."
       />
     )}
-  </h5>
+  </div>
 )
 
 export default Title

src/Widgets/EligibilityModal/components/Title/index.tsx

@@ -101,18 +101,18 @@ const EligibilityModal: FunctionComponent<Props> = ({
         )}
         {status === statusResponse.SUCCESS && eligiblePlans.length >= 1 && (
           <>
-            <section aria-labelledby="payment-plans-title">
+            <div role="region" aria-labelledby="payment-plans-title">
               <EligibilityPlansButtons
                 id="payment-plans"
                 eligibilityPlans={eligiblePlans}
                 currentPlanIndex={currentPlanIndex}
                 setCurrentPlanIndex={setCurrentPlanIndex}
               />
-            </section>
-            <section className={s.scheduleArea} aria-labelledby="payment-schedule-title">
+            </div>
+            <div className={s.scheduleArea} role="region" aria-labelledby="payment-schedule-title">
               <div className={s.verticalLine} />
               <Schedule id="payment-schedule" currentPlan={currentPlan} />
-            </section>
+            </div>
           </>
         )}
       </ModalComponent>

src/Widgets/EligibilityModal/index.tsx

@@ -19,13 +19,13 @@ const mockUseFetchEligibility = require('hooks/useFetchEligibility').default as
   typeof import('hooks/useFetchEligibility').default
 >
 
-describe('PaymentPlans ARIA Landmarks (RGAA 12.6)', () => {
+describe('PaymentPlans ARIA Landmarks (RGAA 12.6) - Widget-Safe Structure', () => {
   beforeEach(() => {
     jest.clearAllMocks()
     mockUseFetchEligibility.mockImplementation(() => [mockButtonPlans, statusResponse.SUCCESS])
   })
 
-  it('should have proper landmark structure for RGAA 12.6 compliance', async () => {
+  it('should have proper widget-safe landmark structure for RGAA compliance', async () => {
     render(
       <PaymentPlanWidget
         purchaseAmount={40000}
@@ -35,35 +35,50 @@ describe('PaymentPlans ARIA Landmarks (RGAA 12.6)', () => {
 
     await screen.findByTestId('widget-container')
 
-    // Check widget container exists (now a simple div without aria-label)
+    // Check widget container exists (neutral div without semantic interference)
     const widgetContainer = screen.getByTestId('widget-container')
     expect(widgetContainer).toBeInTheDocument()
+    expect(widgetContainer.tagName).toBe('DIV')
+    expect(widgetContainer).toHaveAttribute('id', 'alma-widget-payment-plans-main-container')
 
-    // Check section landmark exists at top level
-    const sectionLandmark = screen.getByRole('region')
-    expect(sectionLandmark).toBeInTheDocument()
-    expect(sectionLandmark).toHaveAttribute('aria-labelledby', 'payment-plans-title')
+    // Check both region landmarks exist with proper ARIA labeling
+    const regionLandmarks = screen.getAllByRole('region')
+    expect(regionLandmarks).toHaveLength(2)
 
-    // Check aside landmark exists at top level (not nested)
-    const asideLandmark = screen.getByRole('complementary')
-    expect(asideLandmark).toBeInTheDocument()
-    expect(asideLandmark).toHaveAttribute('aria-labelledby', 'payment-info-title')
+    // Payment plans region
+    const paymentPlansRegion = screen.getByRole('region', {
+      name: 'Options de paiement disponibles',
+    })
+    expect(paymentPlansRegion).toBeInTheDocument()
+    expect(paymentPlansRegion).toHaveAttribute('aria-labelledby', 'payment-plans-title')
+
+    // Payment info region
+    const paymentInfoRegion = screen.getByRole('region', {
+      name: /Informations sur le plan de paiement/,
+    })
+    expect(paymentInfoRegion).toBeInTheDocument()
+    expect(paymentInfoRegion).toHaveAttribute('aria-labelledby', 'payment-info-title')
 
-    // Verify aside is not nested inside section (fixes landmark-complementary-is-top-level)
-    expect(sectionLandmark.contains(asideLandmark)).toBe(false)
+    // Verify regions are siblings (not nested) for proper landmark structure
+    expect(paymentPlansRegion.contains(paymentInfoRegion)).toBe(false)
+    expect(paymentInfoRegion.contains(paymentPlansRegion)).toBe(false)
 
-    // Check screen reader only titles exist
+    // Check ARIA-based heading structure (widget-safe)
     const paymentPlansTitle = document.getElementById('payment-plans-title')
     expect(paymentPlansTitle).toBeInTheDocument()
+    expect(paymentPlansTitle).toHaveAttribute('role', 'heading')
+    expect(paymentPlansTitle).toHaveAttribute('aria-level', '2')
     expect(paymentPlansTitle).toHaveClass('sr-only')
 
     const paymentInfoTitle = document.getElementById('payment-info-title')
     expect(paymentInfoTitle).toBeInTheDocument()
+    expect(paymentInfoTitle).toHaveAttribute('role', 'heading')
+    expect(paymentInfoTitle).toHaveAttribute('aria-level', '2')
     expect(paymentInfoTitle).toHaveClass('sr-only')
   })
 
-  it('should have no accessibility violations with new landmark structure', async () => {
-    const { container } = render(
+  it('should have proper ARIA-based heading hierarchy for screen readers', async () => {
+    render(
       <PaymentPlanWidget
         purchaseAmount={40000}
         apiData={{ domain: ApiMode.TEST, merchantId: '11gKoO333vEXacMNMUMUSc4c4g68g2Les4' }}
@@ -72,19 +87,53 @@ describe('PaymentPlans ARIA Landmarks (RGAA 12.6)', () => {
 
     await screen.findByTestId('widget-container')
 
-    // Test accessibility with all rules including landmarks
-    const results = await axe(container, {
-      rules: {
-        'landmark-one-main': { enabled: true },
-        'landmark-unique': { enabled: true },
-        region: { enabled: true },
-      },
+    // Check ARIA headings exist with proper levels
+    const headings = screen.getAllByRole('heading', { level: 2 })
+    expect(headings).toHaveLength(2)
+
+    const paymentPlansHeading = screen.getByRole('heading', {
+      name: 'Options de paiement disponibles',
     })
+    expect(paymentPlansHeading).toBeInTheDocument()
+    expect(paymentPlansHeading).toHaveTextContent('Options de paiement disponibles')
 
-    expect(results).toHaveNoViolations()
+    const paymentInfoHeading = screen.getByRole('heading', {
+      name: /Informations sur le plan de paiement/,
+    })
+    expect(paymentInfoHeading).toBeInTheDocument()
+    expect(paymentInfoHeading.textContent).toMatch(/Informations sur le plan de paiement/)
+
+    // Verify headings are properly hidden from visual display but accessible to screen readers
+    expect(paymentPlansHeading).toHaveClass('sr-only')
+    expect(paymentInfoHeading).toHaveClass('sr-only')
+  })
+
+  it('should not inject semantic HTML elements that could interfere with host pages', async () => {
+    const { container } = render(
+      <PaymentPlanWidget
+        purchaseAmount={40000}
+        apiData={{ domain: ApiMode.TEST, merchantId: '11gKoO333vEXacMNMUMUSc4c4g68g2Les4' }}
+      />,
+    )
+
+    await screen.findByTestId('widget-container')
+
+    // Verify no problematic semantic HTML tags are injected
+    expect(container.querySelector('section')).not.toBeInTheDocument()
+    expect(container.querySelector('aside')).not.toBeInTheDocument()
+    expect(container.querySelector('article')).not.toBeInTheDocument()
+    expect(container.querySelector('main')).not.toBeInTheDocument()
+    expect(container.querySelector('header')).not.toBeInTheDocument()
+    expect(container.querySelector('footer')).not.toBeInTheDocument()
+    expect(container.querySelector('nav')).not.toBeInTheDocument()
+    expect(container.querySelector('h1, h2, h3, h4, h5, h6')).not.toBeInTheDocument()
+
+    // Verify ARIA-based semantics are used instead
+    expect(screen.getAllByRole('region')).toHaveLength(2)
+    expect(screen.getAllByRole('heading')).toHaveLength(2)
   })
 
-  it('should have proper heading hierarchy for screen readers', async () => {
+  it('should maintain accessibility with listbox pattern for payment options', async () => {
     render(
       <PaymentPlanWidget
         purchaseAmount={40000}
@@ -94,17 +143,86 @@ describe('PaymentPlans ARIA Landmarks (RGAA 12.6)', () => {
 
     await screen.findByTestId('widget-container')
 
-    // Check heading hierarchy exists (h5 for main section, h6 for aside)
-    const h5Heading = screen.getByRole('heading', { level: 5 })
-    expect(h5Heading).toBeInTheDocument()
-    expect(h5Heading).toHaveTextContent('Options de paiement disponibles')
+    // Check listbox exists with proper labeling
+    const listbox = screen.getByRole('listbox')
+    expect(listbox).toBeInTheDocument()
+    expect(listbox).toHaveAttribute('aria-label', 'Options de paiement disponibles')
+
+    // Check options exist within listbox
+    const options = screen.getAllByRole('option')
+    expect(options.length).toBeGreaterThan(0)
+
+    // Verify at least one option is selected
+    const selectedOptions = options.filter(
+      (option) => option.getAttribute('aria-selected') === 'true',
+    )
+    expect(selectedOptions).toHaveLength(1)
+
+    // Check all options have proper ARIA attributes
+    options.forEach((option) => {
+      expect(option).toHaveAttribute('role', 'option')
+      expect(option).toHaveAttribute('aria-selected')
+      expect(option).toHaveAttribute('aria-describedby', 'payment-info-text')
+      expect(option).toHaveAttribute('aria-label')
+    })
+  })
+
+  it('should have no accessibility violations when using widget-safe structure', async () => {
+    const { container } = render(
+      <PaymentPlanWidget
+        purchaseAmount={40000}
+        apiData={{ domain: ApiMode.TEST, merchantId: '11gKoO333vEXacMNMUMUSc4c4g68g2Les4' }}
+      />,
+    )
+
+    await screen.findByTestId('widget-container')
+
+    // Run axe accessibility tests
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+
+    // Specifically check for heading hierarchy issues that could affect host pages
+    const headingViolations = results.violations.filter(
+      (violation) => violation.id.includes('heading') || violation.id.includes('landmark'),
+    )
+    expect(headingViolations).toHaveLength(0)
+  })
+
+  it('should support multiple widget instances without conflicts', async () => {
+    render(
+      <div>
+        <PaymentPlanWidget
+          purchaseAmount={40000}
+          apiData={{ domain: ApiMode.TEST, merchantId: '11gKoO333vEXacMNMUMUSc4c4g68g2Les4' }}
+        />
+        <PaymentPlanWidget
+          purchaseAmount={50000}
+          apiData={{ domain: ApiMode.TEST, merchantId: '11gKoO333vEXacMNMUMUSc4c4g68g2Les4' }}
+        />
+      </div>,
+    )
+
+    // Wait for both widgets to render
+    const containers = await screen.findAllByTestId('widget-container')
+    expect(containers).toHaveLength(2)
+
+    // Verify each widget has its own ID and doesn't conflict
+    const widgetIds = containers.map((container) => container.id)
+    expect(widgetIds[0]).toBe('alma-widget-payment-plans-main-container')
+    expect(widgetIds[1]).toBe('alma-widget-payment-plans-main-container')
+
+    // Note: In real implementation, we might want unique IDs for multiple instances
+    // But current single-instance use case is acceptable
 
-    const h6Heading = screen.getByRole('heading', { level: 6 })
-    expect(h6Heading).toBeInTheDocument()
-    expect(h6Heading).toHaveTextContent('Informations sur le plan de paiement sélectionné')
+    // Verify both widgets have proper ARIA structure
+    const allRegions = screen.getAllByRole('region')
+    expect(allRegions.length).toBeGreaterThanOrEqual(4) // At least 2 regions per widget
+
+    const allHeadings = screen.getAllByRole('heading')
+    expect(allHeadings.length).toBeGreaterThanOrEqual(4) // At least 2 headings per widget
   })
 
-  it('should maintain existing listbox functionality with new structure', async () => {
+  it('should maintain focus management and keyboard navigation', async () => {
     render(
       <PaymentPlanWidget
         purchaseAmount={40000}
@@ -114,13 +232,21 @@ describe('PaymentPlans ARIA Landmarks (RGAA 12.6)', () => {
 
     await screen.findByTestId('widget-container')
 
-    // Check listBox still exists and functions within the section
-    const listBox = screen.getByRole('listbox')
-    expect(listBox).toBeInTheDocument()
-    expect(listBox).toHaveAttribute('aria-label', 'Options de paiement disponibles')
+    // Check main interactive button exists and is focusable
+    const mainButton = screen.getByRole('button', { name: /Ouvrir les options de paiement Alma/ })
+    expect(mainButton).toBeInTheDocument()
+    expect(mainButton).toHaveAttribute('aria-haspopup', 'dialog')
 
-    // Check option buttons still exist within the structure
+    // Check payment option buttons are focusable
     const optionButtons = screen.getAllByRole('option')
-    expect(optionButtons.length).toBeGreaterThan(0)
+    optionButtons.forEach((button) => {
+      expect(button).toHaveAttribute('tabindex')
+      expect(button).toHaveAttribute('type', 'button')
+    })
+
+    // Verify live region exists for screen reader announcements
+    const alertRegion = screen.getByRole('alert')
+    expect(alertRegion).toBeInTheDocument()
+    expect(alertRegion).toHaveAttribute('aria-live', 'assertive')
   })
 })