Revamp tabs & follow ARIA 1.1 practices (#33079)

* Tab: Revamp tab.js & add support Aria features

* Tab: Add tab support, just to keep backwards compatibility. Better to remove it on v6

* Revert "Tab: Add tab support, just to keep backwards compatibility. Better to remove it on v6"

* Support arrow down/up functionality

* add prevent default to avoid scrolling the page during up/down keys handling

* remove panel tabindex handling

* Expand documentation text for JS plugin

* Rearrange new docs to specifically call out a11y

* properly place section

Co-authored-by: XhmikosR <xhmikosr@gmail.com>
Co-authored-by: Patrick H. Lauke <redux@splintered.co.uk>
Co-authored-by: Mark Otto <markdotto@gmail.com>

1 files changed, 197 insertions, 29 deletions

diff --git a/js/tests/unit/tab.spec.js b/js/tests/unit/tab.spec.js
index a0fb89bd47..4b8fb62de6 100644
--- a/js/tests/unit/tab.spec.js
+++ b/js/tests/unit/tab.spec.js
@@ -1,5 +1,5 @@
 import Tab from '../../src/tab'
-import { clearFixture, getFixture, jQueryMock } from '../helpers/fixture'
+import { clearFixture, createEvent, getFixture, jQueryMock } from '../helpers/fixture'
 
 describe('Tab', () => {
   let fixtureEl
@@ -38,6 +38,19 @@ describe('Tab', () => {
     })
   })
 
+  describe('constructor', () => {
+    it('Do not Throw exception if not parent', () => {
+      fixtureEl.innerHTML = [
+        fixtureEl.innerHTML = '<div class=""><div class="nav-link"></div></div>'
+      ].join('')
+      const navEl = fixtureEl.querySelector('.nav-link')
+
+      expect(() => {
+        new Tab(navEl) // eslint-disable-line no-new
+      }).not.toThrowError(TypeError)
+    })
+  })
+
   describe('show', () => {
     it('should activate element by tab id (using buttons, the preferred semantic way)', () => {
       return new Promise(resolve => {
@@ -168,9 +181,9 @@ describe('Tab', () => {
 
     it('should not fire shown when show is prevented', () => {
       return new Promise((resolve, reject) => {
-        fixtureEl.innerHTML = '<div class="nav"></div>'
+        fixtureEl.innerHTML = '<div class="nav"><div class="nav-link"></div></div>'
 
-        const navEl = fixtureEl.querySelector('div')
+        const navEl = fixtureEl.querySelector('.nav > div')
         const tab = new Tab(navEl)
         const expectDone = () => {
           setTimeout(() => {
@@ -256,7 +269,7 @@ describe('Tab', () => {
         fixtureEl.innerHTML = [
           '<ul class="nav" role="tablist">',
           '  <li><button type="button" data-bs-target="#home" role="tab">Home</button></li>',
-          '  <li><button type="button" data-bs-target="#profile">Profile</button></li>',
+          '  <li><button type="button" data-bs-target="#profile" role="tab">Profile</button></li>',
           '</ul>'
         ].join('')
 
@@ -374,10 +387,10 @@ describe('Tab', () => {
 
   describe('dispose', () => {
     it('should dispose a tab', () => {
-      fixtureEl.innerHTML = '<div></div>'
+      fixtureEl.innerHTML = '<div class="nav"><div class="nav-link"></div></div>'
 
-      const el = fixtureEl.querySelector('div')
-      const tab = new Tab(fixtureEl.querySelector('div'))
+      const el = fixtureEl.querySelector('.nav > div')
+      const tab = new Tab(fixtureEl.querySelector('.nav > div'))
 
       expect(Tab.getInstance(el)).not.toBeNull()
 
@@ -387,11 +400,161 @@ describe('Tab', () => {
     })
   })
 
+  describe('_activate', () => {
+    it('should not be called if element argument is null', () => {
+      fixtureEl.innerHTML = [
+        '<ul class="nav" role="tablist">',
+        '  <li class="nav-link"></li>',
+        '</ul>'
+      ].join('')
+
+      const tabEl = fixtureEl.querySelector('.nav-link')
+      const tab = new Tab(tabEl)
+      const spy = jasmine.createSpy('spy')
+
+      spyOn(tab, '_queueCallback')
+      tab._activate(null, spy)
+      expect(tab._queueCallback).not.toHaveBeenCalled()
+      expect(spy).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('_setInitialAttributes', () => {
+    it('should put aria attributes', () => {
+      fixtureEl.innerHTML = [
+        '<ul class="nav">',
+        '  <li class="nav-link" id="foo" data-bs-target="#panel"></li>',
+        '  <li class="nav-link" data-bs-target="#panel2"></li>',
+        '</ul>',
+        '<div id="panel"></div>',
+        '<div id="panel2"></div>'
+      ].join('')
+
+      const tabEl = fixtureEl.querySelector('.nav-link')
+      const parent = fixtureEl.querySelector('.nav')
+      const children = fixtureEl.querySelectorAll('.nav-link')
+      const tabPanel = fixtureEl.querySelector('#panel')
+      const tabPanel2 = fixtureEl.querySelector('#panel2')
+
+      expect(parent.getAttribute('role')).toEqual(null)
+      expect(tabEl.getAttribute('role')).toEqual(null)
+      expect(tabPanel.getAttribute('role')).toEqual(null)
+      const tab = new Tab(tabEl)
+      tab._setInitialAttributes(parent, children)
+
+      expect(parent.getAttribute('role')).toEqual('tablist')
+      expect(tabEl.getAttribute('role')).toEqual('tab')
+
+      expect(tabPanel.getAttribute('role')).toEqual('tabpanel')
+      expect(tabPanel2.getAttribute('role')).toEqual('tabpanel')
+      expect(tabPanel.hasAttribute('tabindex')).toBeFalse()
+      expect(tabPanel.hasAttribute('tabindex2')).toBeFalse()
+
+      expect(tabPanel.getAttribute('aria-labelledby')).toEqual('#foo')
+      expect(tabPanel2.hasAttribute('aria-labelledby')).toBeFalse()
+    })
+  })
+
+  describe('_keydown', () => {
+    it('if event is not one of left/right/up/down arrow, ignore it', () => {
+      fixtureEl.innerHTML = [
+        '<ul class="nav">',
+        '  <li class="nav-link" data-bs-toggle="tab"></li>',
+        '</ul>'
+      ].join('')
+
+      const tabEl = fixtureEl.querySelector('.nav-link')
+      const tab = new Tab(tabEl)
+
+      const keydown = createEvent('keydown')
+      keydown.key = 'Enter'
+      spyOn(Event.prototype, 'stopPropagation').and.callThrough()
+      spyOn(Event.prototype, 'preventDefault').and.callThrough()
+      spyOn(tab, '_keydown')
+      spyOn(tab, '_getChildren')
+
+      tabEl.dispatchEvent(keydown)
+      expect(tab._keydown).toHaveBeenCalled()
+      expect(tab._getChildren).not.toHaveBeenCalled()
+
+      expect(Event.prototype.stopPropagation).not.toHaveBeenCalled()
+      expect(Event.prototype.preventDefault).not.toHaveBeenCalled()
+    })
+
+    it('if keydown event is right/down arrow, handle it', () => {
+      fixtureEl.innerHTML = [
+        '<div class="nav">',
+        '  <span id="tab1" class="nav-link" data-bs-toggle="tab"></span>',
+        '  <span id="tab2" class="nav-link" data-bs-toggle="tab"></span>',
+        '</div>'
+      ].join('')
+
+      const tabEl = fixtureEl.querySelector('#tab1')
+      const tabEl2 = fixtureEl.querySelector('#tab2')
+      const tab = new Tab(tabEl)
+      const tab2 = new Tab(tabEl2)
+      spyOn(tab, 'show').and.callThrough()
+      spyOn(tab2, 'show').and.callThrough()
+
+      spyOn(Event.prototype, 'stopPropagation').and.callThrough()
+      spyOn(Event.prototype, 'preventDefault').and.callThrough()
+
+      let keydown = createEvent('keydown')
+      keydown.key = 'ArrowRight'
+
+      tabEl.dispatchEvent(keydown)
+      expect(tab2.show).toHaveBeenCalled()
+
+      keydown = createEvent('keydown')
+      keydown.key = 'ArrowDown'
+
+      tabEl2.dispatchEvent(keydown)
+      expect(tab.show).toHaveBeenCalled()
+
+      expect(Event.prototype.stopPropagation).toHaveBeenCalledTimes(2)
+      expect(Event.prototype.preventDefault).toHaveBeenCalledTimes(2)
+    })
+
+    it('if keydown event is left arrow, handle it', () => {
+      fixtureEl.innerHTML = [
+        '<div class="nav">',
+        '  <span id="tab1" class="nav-link" data-bs-toggle="tab"></span>',
+        '  <span id="tab2" class="nav-link" data-bs-toggle="tab"></span>',
+        '</div>'
+      ].join('')
+
+      const tabEl = fixtureEl.querySelector('#tab1')
+      const tabEl2 = fixtureEl.querySelector('#tab2')
+      const tab = new Tab(tabEl)
+      const tab2 = new Tab(tabEl2)
+      spyOn(tab, 'show').and.callThrough()
+      spyOn(tab2, 'show').and.callThrough()
+
+      spyOn(Event.prototype, 'stopPropagation').and.callThrough()
+      spyOn(Event.prototype, 'preventDefault').and.callThrough()
+
+      let keydown = createEvent('keydown')
+      keydown.key = 'ArrowLeft'
+
+      tabEl2.dispatchEvent(keydown)
+      expect(tab.show).toHaveBeenCalled()
+
+      keydown = createEvent('keydown')
+      keydown.key = 'ArrowUp'
+
+      tabEl.dispatchEvent(keydown)
+      expect(tab2.show).toHaveBeenCalled()
+
+      expect(Event.prototype.stopPropagation).toHaveBeenCalledTimes(2)
+      expect(Event.prototype.preventDefault).toHaveBeenCalledTimes(2)
+    })
+  })
+
   describe('jQueryInterface', () => {
     it('should create a tab', () => {
-      fixtureEl.innerHTML = '<div></div>'
+      fixtureEl.innerHTML = '<div class="nav"><div class="nav-link"></div></div>'
 
-      const div = fixtureEl.querySelector('div')
+      const div = fixtureEl.querySelector('.nav > div')
 
       jQueryMock.fn.tab = Tab.jQueryInterface
       jQueryMock.elements = [div]
@@ -402,9 +565,9 @@ describe('Tab', () => {
     })
 
     it('should not re create a tab', () => {
-      fixtureEl.innerHTML = '<div></div>'
+      fixtureEl.innerHTML = '<div class="nav"><div class="nav-link"></div></div>'
 
-      const div = fixtureEl.querySelector('div')
+      const div = fixtureEl.querySelector('.nav > div')
       const tab = new Tab(div)
 
       jQueryMock.fn.tab = Tab.jQueryInterface
@@ -416,9 +579,9 @@ describe('Tab', () => {
     })
 
     it('should call a tab method', () => {
-      fixtureEl.innerHTML = '<div></div>'
+      fixtureEl.innerHTML = '<div class="nav"><div class="nav-link"></div></div>'
 
-      const div = fixtureEl.querySelector('div')
+      const div = fixtureEl.querySelector('.nav > div')
       const tab = new Tab(div)
 
       spyOn(tab, 'show')
@@ -433,9 +596,9 @@ describe('Tab', () => {
     })
 
     it('should throw error on undefined method', () => {
-      fixtureEl.innerHTML = '<div></div>'
+      fixtureEl.innerHTML = '<div class="nav"><div class="nav-link"></div></div>'
 
-      const div = fixtureEl.querySelector('div')
+      const div = fixtureEl.querySelector('.nav > div')
       const action = 'undefinedMethod'
 
       jQueryMock.fn.tab = Tab.jQueryInterface
@@ -453,9 +616,9 @@ describe('Tab', () => {
     })
 
     it('should return this instance', () => {
-      fixtureEl.innerHTML = '<div></div>'
+      fixtureEl.innerHTML = '<div class="nav"><div class="nav-link"></div></div>'
 
-      const divEl = fixtureEl.querySelector('div')
+      const divEl = fixtureEl.querySelector('.nav > div')
       const tab = new Tab(divEl)
 
       expect(Tab.getInstance(divEl)).toEqual(tab)
@@ -465,7 +628,7 @@ describe('Tab', () => {
 
   describe('getOrCreateInstance', () => {
     it('should return tab instance', () => {
-      fixtureEl.innerHTML = '<div></div>'
+      fixtureEl.innerHTML = '<div class="nav"><div class="nav-link"></div></div>'
 
       const div = fixtureEl.querySelector('div')
       const tab = new Tab(div)
@@ -476,7 +639,7 @@ describe('Tab', () => {
     })
 
     it('should return new instance when there is no tab instance', () => {
-      fixtureEl.innerHTML = '<div></div>'
+      fixtureEl.innerHTML = '<div class="nav"><div class="nav-link"></div></div>'
 
       const div = fixtureEl.querySelector('div')
 
@@ -651,11 +814,8 @@ describe('Tab', () => {
         const tabProfileEl = fixtureEl.querySelector('#profile')
         const tabHomeEl = fixtureEl.querySelector('#home')
 
-        triggerTabProfileEl.addEventListener('shown.bs.tab', () => {
-          expect(tabProfileEl).toHaveClass('fade')
-          expect(tabProfileEl).toHaveClass('show')
-
-          triggerTabHomeEl.addEventListener('shown.bs.tab', () => {
+        triggerTabHomeEl.addEventListener('shown.bs.tab', () => {
+          setTimeout(() => {
             expect(tabProfileEl).toHaveClass('fade')
             expect(tabProfileEl).not.toHaveClass('show')
 
@@ -663,16 +823,22 @@ describe('Tab', () => {
             expect(tabHomeEl).toHaveClass('show')
 
             resolve()
-          })
+          }, 10)
+        })
 
-          triggerTabHomeEl.click()
+        triggerTabProfileEl.addEventListener('shown.bs.tab', () => {
+          setTimeout(() => {
+            expect(tabProfileEl).toHaveClass('fade')
+            expect(tabProfileEl).toHaveClass('show')
+            triggerTabHomeEl.click()
+          }, 10)
         })
 
         triggerTabProfileEl.click()
       })
     })
 
-    it('should not add show class to tab panes if there is no `.fade` class', () => {
+    it('should not add `show` class to tab panes if there is no `.fade` class', () => {
       return new Promise(resolve => {
         fixtureEl.innerHTML = [
           '<ul class="nav nav-tabs" role="tablist">',
@@ -720,8 +886,10 @@ describe('Tab', () => {
         const secondNavEl = fixtureEl.querySelector('#secondNav')
 
         secondNavEl.addEventListener('shown.bs.tab', () => {
-          expect(fixtureEl.querySelectorAll('.show')).toHaveSize(1)
-          resolve()
+          setTimeout(() => {
+            expect(fixtureEl.querySelectorAll('.show')).toHaveSize(1)
+            resolve()
+          }, 10)
         })
 
         secondNavEl.click()