]> git.ipfire.org Git - thirdparty/bootstrap.git/commitdiff
Offcanvas as component (#29017)
authorGeoSot <geo.sotis@gmail.com>
Tue, 2 Mar 2021 17:10:10 +0000 (19:10 +0200)
committerGitHub <noreply@github.com>
Tue, 2 Mar 2021 17:10:10 +0000 (19:10 +0200)
* Add a new offcanvas component

* offcanvas.js: switch to string constants and `event.key`

* Remove unneeded code

* Sass optimizations

* Fixes

Make sure the element is hidden and not offscreen when inactive
fix close icon negative margins
Add content in right & bottom examples
Re-fix bottom offcanvas height not to cover all viewport

* Wording tweaks

* update tests and offcanvas class

* separate scrollbar functionality and use it in offcanvas

* Update .bundlewatch.config.json

* fix focus

* update btn-close / fix focus on close

* add aria-modal and role
return focus on trigger when offcanvas is closed
change body scrolling timings

* move common code to reusable functions

* add aria-labelledby

* Replace lorem ipsum text

* fix focus when offcanvas is closed

* updates

* revert modal, add tests for scrollbar

* show backdrop by default

* Update offcanvas.md

* Update offcanvas CSS to better match modals

- Add background-clip for borders
- Move from outline to border (less clever, more consistent)
- Add scss-docs in vars

* Revamp offcanvas docs

- Add static example to show and explain the components
- Split live examples and rename them
- Simplify example content
- Expand docs notes elsewhere
- Add sass docs

* Add .offcanvas-title instead of .modal-title

* Rename offcanvas example to offcanvas-navbar to reflect it's purpose

* labelledby references title and not header

* Add default shadow to offcanvas

* enable offcanvas-body to fill all the remaining wrapper area

* Be more descriptive, on Accessibility area

* remove redundant classes

* ensure in case of an already open offcanvas, not to open another one

* bring back backdrop|scroll combinations

* bring back toggling class

* refactor scrollbar method, plus tests

* add check if element is not full-width, according to #30621

* revert all in modal

* use documentElement innerWidth

* Rename classes to -start and -end

Also copyedit some docs wording

* omit some things on scrollbar

* PASS BrowserStack tests

-- IOS devices, Android devices and Browsers on Mac, hide scrollbar by default and appear it, only while scrolling.

* Rename '_handleClosing' to '_addEventListeners'

* change pipe usage to comma

* change Data.getData to Data.get

Co-authored-by: XhmikosR <xhmikosr@gmail.com>
Co-authored-by: Martijn Cuppens <martijn.cuppens@gmail.com>
Co-authored-by: Mark Otto <markdotto@gmail.com>
20 files changed:
.bundlewatch.config.json
build/build-plugins.js
js/index.esm.js
js/index.umd.js
js/src/offcanvas.js [new file with mode: 0644]
js/src/util/scrollbar.js [new file with mode: 0644]
js/tests/unit/offcanvas.spec.js [new file with mode: 0644]
js/tests/unit/util/scrollbar.spec.js [new file with mode: 0644]
scss/_offcanvas.scss [new file with mode: 0644]
scss/_variables.scss
scss/bootstrap.scss
site/assets/scss/_component-examples.scss
site/content/docs/5.0/components/offcanvas.md [new file with mode: 0644]
site/content/docs/5.0/examples/offcanvas-navbar/index.html [moved from site/content/docs/5.0/examples/offcanvas/index.html with 99% similarity]
site/content/docs/5.0/examples/offcanvas-navbar/offcanvas.css [moved from site/content/docs/5.0/examples/offcanvas/offcanvas.css with 100% similarity]
site/content/docs/5.0/examples/offcanvas-navbar/offcanvas.js [moved from site/content/docs/5.0/examples/offcanvas/offcanvas.js with 100% similarity]
site/data/examples.yml
site/data/sidebar.yml
site/static/docs/5.0/assets/img/examples/offcanvas-navbar.png [moved from site/static/docs/5.0/assets/img/examples/offcanvas.png with 100% similarity]
site/static/docs/5.0/assets/img/examples/offcanvas-navbar@2x.png [moved from site/static/docs/5.0/assets/img/examples/offcanvas@2x.png with 100% similarity]

index a68eeb85be487b86e10a7a8bb44ff9d0aaf0143d..4a28264b3a9919ecf18668091bd217e3c3854690 100644 (file)
     },
     {
       "path": "./dist/css/bootstrap.css",
-      "maxSize": "24 kB"
+      "maxSize": "24.25 kB"
     },
     {
       "path": "./dist/css/bootstrap.min.css",
-      "maxSize": "22 kB"
+      "maxSize": "22.25 kB"
     },
     {
       "path": "./dist/js/bootstrap.bundle.js",
-      "maxSize": "42 kB"
+      "maxSize": "43 kB"
     },
     {
       "path": "./dist/js/bootstrap.bundle.min.js",
-      "maxSize": "22 kB"
+      "maxSize": "22.5 kB"
     },
     {
       "path": "./dist/js/bootstrap.esm.js",
-      "maxSize": "27 kB"
+      "maxSize": "28.5 kB"
     },
     {
       "path": "./dist/js/bootstrap.esm.min.js",
-      "maxSize": "18 kB"
+      "maxSize": "19 kB"
     },
     {
       "path": "./dist/js/bootstrap.js",
-      "maxSize": "28 kB"
+      "maxSize": "29 kB"
     },
     {
       "path": "./dist/js/bootstrap.min.js",
-      "maxSize": "15.75 kB"
+      "maxSize": "16.25 kB"
     }
   ],
   "ci": {
index d1930b8556edf5ef2e18c45d9fb892ca9820051e..7175df4dd562efe0bf9edbb5cef437a6fe5e98f3 100644 (file)
@@ -35,6 +35,7 @@ const bsPlugins = {
   Collapse: path.resolve(__dirname, '../js/src/collapse.js'),
   Dropdown: path.resolve(__dirname, '../js/src/dropdown.js'),
   Modal: path.resolve(__dirname, '../js/src/modal.js'),
+  OffCanvas: path.resolve(__dirname, '../js/src/offcanvas.js'),
   Popover: path.resolve(__dirname, '../js/src/popover.js'),
   ScrollSpy: path.resolve(__dirname, '../js/src/scrollspy.js'),
   Tab: path.resolve(__dirname, '../js/src/tab.js'),
@@ -71,7 +72,7 @@ const getConfigByPluginKey = pluginKey => {
     }
   }
 
-  if (pluginKey === 'Alert' || pluginKey === 'Tab') {
+  if (pluginKey === 'Alert' || pluginKey === 'Tab' || pluginKey === 'OffCanvas') {
     return defaultPluginConfig
   }
 
index b1bbf53a8f71d4152408cf2adc2b9bdfc8dfa71a..c041beffe25555e915acb62d8e652413ddb06992 100644 (file)
@@ -11,6 +11,7 @@ import Carousel from './src/carousel'
 import Collapse from './src/collapse'
 import Dropdown from './src/dropdown'
 import Modal from './src/modal'
+import OffCanvas from './src/offcanvas'
 import Popover from './src/popover'
 import ScrollSpy from './src/scrollspy'
 import Tab from './src/tab'
@@ -24,6 +25,7 @@ export {
   Collapse,
   Dropdown,
   Modal,
+  OffCanvas,
   Popover,
   ScrollSpy,
   Tab,
index 5c44ce8d2def56f66423a7418e61c790c528a545..a99a3be896a3d98489c2b0eb02ec0084e9b6e2dd 100644 (file)
@@ -11,6 +11,7 @@ import Carousel from './src/carousel'
 import Collapse from './src/collapse'
 import Dropdown from './src/dropdown'
 import Modal from './src/modal'
+import OffCanvas from './src/offcanvas'
 import Popover from './src/popover'
 import ScrollSpy from './src/scrollspy'
 import Tab from './src/tab'
@@ -24,6 +25,7 @@ export default {
   Collapse,
   Dropdown,
   Modal,
+  OffCanvas,
   Popover,
   ScrollSpy,
   Tab,
diff --git a/js/src/offcanvas.js b/js/src/offcanvas.js
new file mode 100644 (file)
index 0000000..148f003
--- /dev/null
@@ -0,0 +1,239 @@
+/**
+ * --------------------------------------------------------------------------
+ * Bootstrap (v5.0.0-beta2): offcanvas.js
+ * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE)
+ * --------------------------------------------------------------------------
+ */
+
+import {
+  defineJQueryPlugin,
+  getElementFromSelector,
+  getSelectorFromElement,
+  getTransitionDurationFromElement,
+  isVisible
+} from './util/index'
+import { hide as scrollBarHide, reset as scrollBarReset } from './util/scrollbar'
+import Data from './dom/data'
+import EventHandler from './dom/event-handler'
+import BaseComponent from './base-component'
+import SelectorEngine from './dom/selector-engine'
+
+/**
+ * ------------------------------------------------------------------------
+ * Constants
+ * ------------------------------------------------------------------------
+ */
+
+const NAME = 'offcanvas'
+const DATA_KEY = 'bs.offcanvas'
+const EVENT_KEY = `.${DATA_KEY}`
+const DATA_API_KEY = '.data-api'
+const ESCAPE_KEY = 'Escape'
+const DATA_BODY_ACTIONS = 'data-bs-body'
+
+const CLASS_NAME_BACKDROP_BODY = 'offcanvas-backdrop'
+const CLASS_NAME_DISABLED = 'disabled'
+const CLASS_NAME_SHOW = 'show'
+const CLASS_NAME_TOGGLING = 'offcanvas-toggling'
+const ACTIVE_SELECTOR = `.offcanvas.show, .${CLASS_NAME_TOGGLING}`
+
+const EVENT_SHOW = `show${EVENT_KEY}`
+const EVENT_SHOWN = `shown${EVENT_KEY}`
+const EVENT_HIDE = `hide${EVENT_KEY}`
+const EVENT_HIDDEN = `hidden${EVENT_KEY}`
+const EVENT_FOCUSIN = `focusin${EVENT_KEY}`
+const EVENT_CLICK_DATA_API = `click${EVENT_KEY}${DATA_API_KEY}`
+const EVENT_CLICK_DISMISS = `click.dismiss${EVENT_KEY}`
+
+const SELECTOR_DATA_DISMISS = '[data-bs-dismiss="offcanvas"]'
+const SELECTOR_DATA_TOGGLE = '[data-bs-toggle="offcanvas"]'
+
+/**
+ * ------------------------------------------------------------------------
+ * Class Definition
+ * ------------------------------------------------------------------------
+ */
+
+class OffCanvas extends BaseComponent {
+  constructor(element) {
+    super(element)
+
+    this._isShown = element.classList.contains(CLASS_NAME_SHOW)
+    this._bodyOptions = element.getAttribute(DATA_BODY_ACTIONS) || ''
+    this._addEventListeners()
+  }
+
+  // Public
+
+  toggle(relatedTarget) {
+    return this._isShown ? this.hide() : this.show(relatedTarget)
+  }
+
+  show(relatedTarget) {
+    if (this._isShown) {
+      return
+    }
+
+    const showEvent = EventHandler.trigger(this._element, EVENT_SHOW, { relatedTarget })
+
+    if (showEvent.defaultPrevented) {
+      return
+    }
+
+    this._isShown = true
+    this._element.style.visibility = 'visible'
+
+    if (this._bodyOptionsHas('backdrop') || !this._bodyOptions.length) {
+      document.body.classList.add(CLASS_NAME_BACKDROP_BODY)
+    }
+
+    if (!this._bodyOptionsHas('scroll')) {
+      scrollBarHide()
+    }
+
+    this._element.classList.add(CLASS_NAME_TOGGLING)
+    this._element.removeAttribute('aria-hidden')
+    this._element.setAttribute('aria-modal', true)
+    this._element.setAttribute('role', 'dialog')
+    this._element.classList.add(CLASS_NAME_SHOW)
+
+    const completeCallBack = () => {
+      this._element.classList.remove(CLASS_NAME_TOGGLING)
+      EventHandler.trigger(this._element, EVENT_SHOWN, { relatedTarget })
+      this._enforceFocusOnElement(this._element)
+    }
+
+    setTimeout(completeCallBack, getTransitionDurationFromElement(this._element))
+  }
+
+  hide() {
+    if (!this._isShown) {
+      return
+    }
+
+    const hideEvent = EventHandler.trigger(this._element, EVENT_HIDE)
+
+    if (hideEvent.defaultPrevented) {
+      return
+    }
+
+    this._element.classList.add(CLASS_NAME_TOGGLING)
+    EventHandler.off(document, EVENT_FOCUSIN)
+    this._element.blur()
+    this._isShown = false
+    this._element.classList.remove(CLASS_NAME_SHOW)
+
+    const completeCallback = () => {
+      this._element.setAttribute('aria-hidden', true)
+      this._element.removeAttribute('aria-modal')
+      this._element.removeAttribute('role')
+      this._element.style.visibility = 'hidden'
+
+      if (this._bodyOptionsHas('backdrop') || !this._bodyOptions.length) {
+        document.body.classList.remove(CLASS_NAME_BACKDROP_BODY)
+      }
+
+      if (!this._bodyOptionsHas('scroll')) {
+        scrollBarReset()
+      }
+
+      EventHandler.trigger(this._element, EVENT_HIDDEN)
+      this._element.classList.remove(CLASS_NAME_TOGGLING)
+    }
+
+    setTimeout(completeCallback, getTransitionDurationFromElement(this._element))
+  }
+
+  _enforceFocusOnElement(element) {
+    EventHandler.off(document, EVENT_FOCUSIN) // guard against infinite focus loop
+    EventHandler.on(document, EVENT_FOCUSIN, event => {
+      if (document !== event.target &&
+        element !== event.target &&
+        !element.contains(event.target)) {
+        element.focus()
+      }
+    })
+    element.focus()
+  }
+
+  _bodyOptionsHas(option) {
+    return this._bodyOptions.split(',').includes(option)
+  }
+
+  _addEventListeners() {
+    EventHandler.on(this._element, EVENT_CLICK_DISMISS, SELECTOR_DATA_DISMISS, () => this.hide())
+
+    EventHandler.on(document, 'keydown', event => {
+      if (event.key === ESCAPE_KEY) {
+        this.hide()
+      }
+    })
+
+    EventHandler.on(document, EVENT_CLICK_DATA_API, event => {
+      const target = SelectorEngine.findOne(getSelectorFromElement(event.target))
+      if (!this._element.contains(event.target) && target !== this._element) {
+        this.hide()
+      }
+    })
+  }
+
+  // Static
+
+  static jQueryInterface(config) {
+    return this.each(function () {
+      const data = Data.get(this, DATA_KEY) || new OffCanvas(this)
+
+      if (typeof config === 'string') {
+        if (typeof data[config] === 'undefined') {
+          throw new TypeError(`No method named "${config}"`)
+        }
+
+        data[config](this)
+      }
+    })
+  }
+}
+
+/**
+ * ------------------------------------------------------------------------
+ * Data Api implementation
+ * ------------------------------------------------------------------------
+ */
+
+EventHandler.on(document, EVENT_CLICK_DATA_API, SELECTOR_DATA_TOGGLE, function (event) {
+  const target = getElementFromSelector(this)
+
+  if (['A', 'AREA'].includes(this.tagName)) {
+    event.preventDefault()
+  }
+
+  if (this.disabled || this.classList.contains(CLASS_NAME_DISABLED)) {
+    return
+  }
+
+  EventHandler.one(target, EVENT_HIDDEN, () => {
+    // focus on trigger when it is closed
+    if (isVisible(this)) {
+      this.focus()
+    }
+  })
+
+  // avoid conflict when clicking a toggler of an offcanvas, while another is open
+  const allReadyOpen = SelectorEngine.findOne(ACTIVE_SELECTOR)
+  if (allReadyOpen && allReadyOpen !== target) {
+    return
+  }
+
+  const data = Data.get(target, DATA_KEY) || new OffCanvas(target)
+  data.toggle(this)
+})
+
+/**
+ * ------------------------------------------------------------------------
+ * jQuery
+ * ------------------------------------------------------------------------
+ */
+
+defineJQueryPlugin(NAME, OffCanvas)
+
+export default OffCanvas
diff --git a/js/src/util/scrollbar.js b/js/src/util/scrollbar.js
new file mode 100644 (file)
index 0000000..d2f3919
--- /dev/null
@@ -0,0 +1,70 @@
+/**
+ * --------------------------------------------------------------------------
+ * Bootstrap (v5.0.0-beta2): util/scrollBar.js
+ * Licensed under MIT (https://github.com/twbs/bootstrap/blob/main/LICENSE)
+ * --------------------------------------------------------------------------
+ */
+
+import SelectorEngine from '../dom/selector-engine'
+import Manipulator from '../dom/manipulator'
+
+const SELECTOR_FIXED_CONTENT = '.fixed-top, .fixed-bottom, .is-fixed'
+const SELECTOR_STICKY_CONTENT = '.sticky-top'
+
+const getWidth = () => {
+  // https://developer.mozilla.org/en-US/docs/Web/API/Window/innerWidth#usage_notes
+  const documentWidth = document.documentElement.clientWidth
+  return Math.abs(window.innerWidth - documentWidth)
+}
+
+const hide = (width = getWidth()) => {
+  document.body.style.overflow = 'hidden'
+  _setElementAttributes(SELECTOR_FIXED_CONTENT, 'paddingRight', calculatedValue => calculatedValue + width)
+  _setElementAttributes(SELECTOR_STICKY_CONTENT, 'marginRight', calculatedValue => calculatedValue - width)
+  _setElementAttributes('body', 'paddingRight', calculatedValue => calculatedValue + width)
+}
+
+const _setElementAttributes = (selector, styleProp, callback) => {
+  const scrollbarWidth = getWidth()
+  SelectorEngine.find(selector)
+    .forEach(element => {
+      if (element !== document.body && window.innerWidth > element.clientWidth + scrollbarWidth) {
+        return
+      }
+
+      const actualValue = element.style[styleProp]
+      const calculatedValue = window.getComputedStyle(element)[styleProp]
+      Manipulator.setDataAttribute(element, styleProp, actualValue)
+      element.style[styleProp] = callback(Number.parseFloat(calculatedValue)) + 'px'
+    })
+}
+
+const reset = () => {
+  document.body.style.overflow = 'auto'
+  _resetElementAttributes(SELECTOR_FIXED_CONTENT, 'paddingRight')
+  _resetElementAttributes(SELECTOR_STICKY_CONTENT, 'marginRight')
+  _resetElementAttributes('body', 'paddingRight')
+}
+
+const _resetElementAttributes = (selector, styleProp) => {
+  SelectorEngine.find(selector).forEach(element => {
+    const value = Manipulator.getDataAttribute(element, styleProp)
+    if (typeof value === 'undefined' && element === document.body) {
+      element.style.removeProperty(styleProp)
+    } else {
+      Manipulator.removeDataAttribute(element, styleProp)
+      element.style[styleProp] = value
+    }
+  })
+}
+
+const isBodyOverflowing = () => {
+  return getWidth() > 0
+}
+
+export {
+  getWidth,
+  hide,
+  isBodyOverflowing,
+  reset
+}
diff --git a/js/tests/unit/offcanvas.spec.js b/js/tests/unit/offcanvas.spec.js
new file mode 100644 (file)
index 0000000..d07c0c6
--- /dev/null
@@ -0,0 +1,324 @@
+import OffCanvas from '../../src/offcanvas'
+import EventHandler from '../../src/dom/event-handler'
+
+/** Test helpers */
+import { clearFixture, getFixture, jQueryMock, createEvent } from '../helpers/fixture'
+
+describe('OffCanvas', () => {
+  let fixtureEl
+
+  beforeAll(() => {
+    fixtureEl = getFixture()
+  })
+
+  afterEach(() => {
+    clearFixture()
+    document.body.classList.remove('offcanvas-open')
+  })
+
+  describe('VERSION', () => {
+    it('should return plugin version', () => {
+      expect(OffCanvas.VERSION).toEqual(jasmine.any(String))
+    })
+  })
+
+  describe('constructor', () => {
+    it('should call hide when a element with data-bs-dismiss="offcanvas" is clicked', () => {
+      fixtureEl.innerHTML = [
+        '<div class="offcanvas">',
+        '  <a href="#" data-bs-dismiss="offcanvas">Close</a>',
+        '</div>'
+      ].join('')
+
+      const offCanvasEl = fixtureEl.querySelector('.offcanvas')
+      const closeEl = fixtureEl.querySelector('a')
+      const offCanvas = new OffCanvas(offCanvasEl)
+
+      spyOn(offCanvas, 'hide')
+
+      closeEl.click()
+
+      expect(offCanvas.hide).toHaveBeenCalled()
+    })
+
+    it('should hide if esc is pressed', () => {
+      fixtureEl.innerHTML = '<div class="offcanvas"></div>'
+
+      const offCanvasEl = fixtureEl.querySelector('.offcanvas')
+      const offCanvas = new OffCanvas(offCanvasEl)
+      const keyDownEsc = createEvent('keydown')
+      keyDownEsc.key = 'Escape'
+
+      spyOn(offCanvas, 'hide')
+
+      document.dispatchEvent(keyDownEsc)
+
+      expect(offCanvas.hide).toHaveBeenCalled()
+    })
+
+    it('should not hide if esc is not pressed', () => {
+      fixtureEl.innerHTML = '<div class="offcanvas"></div>'
+
+      const offCanvasEl = fixtureEl.querySelector('.offcanvas')
+      const offCanvas = new OffCanvas(offCanvasEl)
+      const keydownTab = createEvent('keydown')
+      keydownTab.key = 'Tab'
+
+      spyOn(offCanvas, 'hide')
+
+      document.dispatchEvent(keydownTab)
+
+      expect(offCanvas.hide).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('toggle', () => {
+    it('should call show method if show class is not present', () => {
+      fixtureEl.innerHTML = '<div class="offcanvas"></div>'
+
+      const offCanvasEl = fixtureEl.querySelector('.offcanvas')
+      const offCanvas = new OffCanvas(offCanvasEl)
+
+      spyOn(offCanvas, 'show')
+
+      offCanvas.toggle()
+
+      expect(offCanvas.show).toHaveBeenCalled()
+    })
+
+    it('should call hide method if show class is present', () => {
+      fixtureEl.innerHTML = '<div class="offcanvas show"></div>'
+
+      const offCanvasEl = fixtureEl.querySelector('.show')
+      const offCanvas = new OffCanvas(offCanvasEl)
+
+      spyOn(offCanvas, 'hide')
+
+      offCanvas.toggle()
+
+      expect(offCanvas.hide).toHaveBeenCalled()
+    })
+  })
+
+  describe('show', () => {
+    it('should do nothing if already shown', () => {
+      fixtureEl.innerHTML = '<div class="offcanvas show"></div>'
+
+      spyOn(EventHandler, 'trigger')
+
+      const offCanvasEl = fixtureEl.querySelector('div')
+      const offCanvas = new OffCanvas(offCanvasEl)
+
+      offCanvas.show()
+
+      expect(EventHandler.trigger).not.toHaveBeenCalled()
+    })
+
+    it('should show a hidden element', done => {
+      fixtureEl.innerHTML = '<div class="offcanvas"></div>'
+
+      const offCanvasEl = fixtureEl.querySelector('div')
+      const offCanvas = new OffCanvas(offCanvasEl)
+
+      offCanvasEl.addEventListener('shown.bs.offcanvas', () => {
+        expect(offCanvasEl.classList.contains('show')).toEqual(true)
+        done()
+      })
+
+      offCanvas.show()
+    })
+
+    it('should not fire shown when show is prevented', done => {
+      fixtureEl.innerHTML = '<div class="offcanvas"></div>'
+
+      const offCanvasEl = fixtureEl.querySelector('div')
+      const offCanvas = new OffCanvas(offCanvasEl)
+
+      const expectEnd = () => {
+        setTimeout(() => {
+          expect().nothing()
+          done()
+        }, 10)
+      }
+
+      offCanvasEl.addEventListener('show.bs.offcanvas', e => {
+        e.preventDefault()
+        expectEnd()
+      })
+
+      offCanvasEl.addEventListener('shown.bs.offcanvas', () => {
+        throw new Error('should not fire shown event')
+      })
+
+      offCanvas.show()
+    })
+  })
+
+  describe('hide', () => {
+    it('should do nothing if already shown', () => {
+      fixtureEl.innerHTML = '<div class="offcanvas"></div>'
+
+      spyOn(EventHandler, 'trigger')
+
+      const offCanvasEl = fixtureEl.querySelector('div')
+      const offCanvas = new OffCanvas(offCanvasEl)
+
+      offCanvas.hide()
+
+      expect(EventHandler.trigger).not.toHaveBeenCalled()
+    })
+
+    it('should hide a shown element', done => {
+      fixtureEl.innerHTML = '<div class="offcanvas show"></div>'
+
+      const offCanvasEl = fixtureEl.querySelector('div')
+      const offCanvas = new OffCanvas(offCanvasEl)
+
+      offCanvasEl.addEventListener('hidden.bs.offcanvas', () => {
+        expect(offCanvasEl.classList.contains('show')).toEqual(false)
+        done()
+      })
+
+      offCanvas.hide()
+    })
+
+    it('should not fire hidden when hide is prevented', done => {
+      fixtureEl.innerHTML = '<div class="offcanvas show"></div>'
+
+      const offCanvasEl = fixtureEl.querySelector('div')
+      const offCanvas = new OffCanvas(offCanvasEl)
+
+      const expectEnd = () => {
+        setTimeout(() => {
+          expect().nothing()
+          done()
+        }, 10)
+      }
+
+      offCanvasEl.addEventListener('hide.bs.offcanvas', e => {
+        e.preventDefault()
+        expectEnd()
+      })
+
+      offCanvasEl.addEventListener('hidden.bs.offcanvas', () => {
+        throw new Error('should not fire hidden event')
+      })
+
+      offCanvas.hide()
+    })
+  })
+
+  describe('data-api', () => {
+    it('should not prevent event for input', done => {
+      fixtureEl.innerHTML = [
+        '<input type="checkbox" data-bs-toggle="offcanvas" data-bs-target="#offcanvasdiv1" />',
+        '<div id="offcanvasdiv1" class="offcanvas"></div>'
+      ].join('')
+
+      const target = fixtureEl.querySelector('input')
+      const offCanvasEl = fixtureEl.querySelector('#offcanvasdiv1')
+
+      offCanvasEl.addEventListener('shown.bs.offcanvas', () => {
+        expect(offCanvasEl.classList.contains('show')).toEqual(true)
+        expect(target.checked).toEqual(true)
+        done()
+      })
+
+      target.click()
+    })
+
+    it('should not call toggle on disabled elements', () => {
+      fixtureEl.innerHTML = [
+        '<a href="#" data-bs-toggle="offcanvas" data-bs-target="#offcanvasdiv1" class="disabled"></a>',
+        '<div id="offcanvasdiv1" class="offcanvas"></div>'
+      ].join('')
+
+      const target = fixtureEl.querySelector('a')
+
+      spyOn(OffCanvas.prototype, 'toggle')
+
+      target.click()
+
+      expect(OffCanvas.prototype.toggle).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('jQueryInterface', () => {
+    it('should create an offcanvas', () => {
+      fixtureEl.innerHTML = '<div></div>'
+
+      const div = fixtureEl.querySelector('div')
+
+      jQueryMock.fn.offcanvas = OffCanvas.jQueryInterface
+      jQueryMock.elements = [div]
+
+      jQueryMock.fn.offcanvas.call(jQueryMock)
+
+      expect(OffCanvas.getInstance(div)).toBeDefined()
+    })
+
+    it('should not re create an offcanvas', () => {
+      fixtureEl.innerHTML = '<div></div>'
+
+      const div = fixtureEl.querySelector('div')
+      const offCanvas = new OffCanvas(div)
+
+      jQueryMock.fn.offcanvas = OffCanvas.jQueryInterface
+      jQueryMock.elements = [div]
+
+      jQueryMock.fn.offcanvas.call(jQueryMock)
+
+      expect(OffCanvas.getInstance(div)).toEqual(offCanvas)
+    })
+
+    it('should throw error on undefined method', () => {
+      fixtureEl.innerHTML = '<div></div>'
+
+      const div = fixtureEl.querySelector('div')
+      const action = 'undefinedMethod'
+
+      jQueryMock.fn.offcanvas = OffCanvas.jQueryInterface
+      jQueryMock.elements = [div]
+
+      try {
+        jQueryMock.fn.offcanvas.call(jQueryMock, action)
+      } catch (error) {
+        expect(error.message).toEqual(`No method named "${action}"`)
+      }
+    })
+
+    it('should call offcanvas method', () => {
+      fixtureEl.innerHTML = '<div></div>'
+
+      const div = fixtureEl.querySelector('div')
+
+      spyOn(OffCanvas.prototype, 'show')
+
+      jQueryMock.fn.offcanvas = OffCanvas.jQueryInterface
+      jQueryMock.elements = [div]
+
+      jQueryMock.fn.offcanvas.call(jQueryMock, 'show')
+      expect(OffCanvas.prototype.show).toHaveBeenCalled()
+    })
+  })
+
+  describe('getInstance', () => {
+    it('should return offcanvas instance', () => {
+      fixtureEl.innerHTML = '<div></div>'
+
+      const div = fixtureEl.querySelector('div')
+      const offCanvas = new OffCanvas(div)
+
+      expect(OffCanvas.getInstance(div)).toEqual(offCanvas)
+      expect(OffCanvas.getInstance(div)).toBeInstanceOf(OffCanvas)
+    })
+
+    it('should return null when there is no offcanvas instance', () => {
+      fixtureEl.innerHTML = '<div></div>'
+
+      const div = fixtureEl.querySelector('div')
+
+      expect(OffCanvas.getInstance(div)).toEqual(null)
+    })
+  })
+})
diff --git a/js/tests/unit/util/scrollbar.spec.js b/js/tests/unit/util/scrollbar.spec.js
new file mode 100644 (file)
index 0000000..eb344a0
--- /dev/null
@@ -0,0 +1,182 @@
+import * as Scrollbar from '../../../src/util/scrollbar'
+import { clearFixture, getFixture } from '../../helpers/fixture'
+
+describe('ScrollBar', () => {
+  let fixtureEl
+  const windowCalculations = () => {
+    return {
+      htmlClient: document.documentElement.clientWidth,
+      htmlOffset: document.documentElement.offsetWidth,
+      docClient: document.body.clientWidth,
+      htmlBound: document.documentElement.getBoundingClientRect().width,
+      bodyBound: document.body.getBoundingClientRect().width,
+      window: window.innerWidth,
+      width: Math.abs(window.innerWidth - document.documentElement.clientWidth)
+    }
+  }
+
+  const isScrollBarHidden = () => { // IOS devices, Android devices and Browsers on Mac, hide scrollbar by default and appear it, only while scrolling. So the tests for scrollbar would fail
+    const calc = windowCalculations()
+    return calc.htmlClient === calc.htmlOffset && calc.htmlClient === calc.window
+  }
+
+  beforeAll(() => {
+    fixtureEl = getFixture()
+    // custom fixture to avoid extreme style values
+    fixtureEl.removeAttribute('style')
+  })
+
+  afterAll(() => {
+    fixtureEl.remove()
+    document.documentElement.style.overflowY = 'auto'
+    document.body.style.overflowY = 'auto'
+  })
+
+  afterEach(() => {
+    clearFixture()
+    document.documentElement.removeAttribute('style')
+  })
+
+  beforeEach(() => {
+    document.documentElement.removeAttribute('style')
+  })
+
+  describe('isBodyOverflowing', () => {
+    it('should return true if body is overflowing', () => {
+      document.documentElement.style.overflowY = 'scroll'
+      document.body.style.overflowY = 'scroll'
+      fixtureEl.innerHTML = [
+        '<div style="height: 110vh; width: 100%"></div>'
+      ].join('')
+      const result = Scrollbar.isBodyOverflowing()
+
+      if (isScrollBarHidden()) {
+        expect(result).toEqual(false)
+      } else {
+        expect(result).toEqual(true)
+      }
+    })
+
+    it('should return false if body is overflowing', () => {
+      document.documentElement.style.overflowY = 'hidden'
+      document.body.style.overflowY = 'hidden'
+      fixtureEl.innerHTML = [
+        '<div style="height: 110vh; width: 100%"></div>'
+      ].join('')
+      const result = Scrollbar.isBodyOverflowing()
+
+      expect(result).toEqual(false)
+    })
+  })
+
+  describe('getWidth', () => {
+    it('should return an integer greater than zero, if body is overflowing', () => {
+      document.documentElement.style.overflowY = 'scroll'
+      document.body.style.overflowY = 'scroll'
+      fixtureEl.innerHTML = [
+        '<div style="height: 110vh; width: 100%"></div>'
+      ].join('')
+      const result = Scrollbar.getWidth()
+
+      if (isScrollBarHidden()) {
+        expect(result).toBe(0)
+      } else {
+        expect(result).toBeGreaterThan(1)
+      }
+    })
+
+    it('should return 0 if body is not overflowing', () => {
+      document.documentElement.style.overflowY = 'hidden'
+      document.body.style.overflowY = 'hidden'
+      fixtureEl.innerHTML = [
+        '<div style="height: 110vh; width: 100%"></div>'
+      ].join('')
+
+      const result = Scrollbar.getWidth()
+
+      expect(result).toEqual(0)
+    })
+  })
+
+  describe('hide - reset', () => {
+    it('should adjust the inline padding of fixed elements which are full-width', done => {
+      fixtureEl.innerHTML = [
+        '<div style="height: 110vh; width: 100%">' +
+        '<div class="fixed-top" id="fixed1" style="padding-right: 0px; width: 100vw"></div>',
+        '<div class="fixed-top" id="fixed2" style="padding-right: 5px; width: 100vw"></div>',
+        '</div>'
+      ].join('')
+      document.documentElement.style.overflowY = 'scroll'
+
+      const fixedEl = fixtureEl.querySelector('#fixed1')
+      const fixedEl2 = fixtureEl.querySelector('#fixed2')
+      const originalPadding = Number.parseInt(window.getComputedStyle(fixedEl).paddingRight, 10)
+      const originalPadding2 = Number.parseInt(window.getComputedStyle(fixedEl2).paddingRight, 10)
+      const expectedPadding = originalPadding + Scrollbar.getWidth()
+      const expectedPadding2 = originalPadding2 + Scrollbar.getWidth()
+
+      Scrollbar.hide()
+
+      let currentPadding = Number.parseInt(window.getComputedStyle(fixedEl).paddingRight, 10)
+      let currentPadding2 = Number.parseInt(window.getComputedStyle(fixedEl2).paddingRight, 10)
+      expect(fixedEl.getAttribute('data-bs-padding-right')).toEqual('0px', 'original fixed element padding should be stored in data-bs-padding-right')
+      expect(fixedEl2.getAttribute('data-bs-padding-right')).toEqual('5px', 'original fixed element padding should be stored in data-bs-padding-right')
+      expect(currentPadding).toEqual(expectedPadding, 'fixed element padding should be adjusted while opening')
+      expect(currentPadding2).toEqual(expectedPadding2, 'fixed element padding should be adjusted while opening')
+
+      Scrollbar.reset()
+      currentPadding = Number.parseInt(window.getComputedStyle(fixedEl).paddingRight, 10)
+      currentPadding2 = Number.parseInt(window.getComputedStyle(fixedEl2).paddingRight, 10)
+      expect(fixedEl.getAttribute('data-bs-padding-right')).toEqual(null, 'data-bs-padding-right should be cleared after closing')
+      expect(fixedEl2.getAttribute('data-bs-padding-right')).toEqual(null, 'data-bs-padding-right should be cleared after closing')
+      expect(currentPadding).toEqual(originalPadding, 'fixed element padding should be reset after closing')
+      expect(currentPadding2).toEqual(originalPadding2, 'fixed element padding should be reset after closing')
+      done()
+    })
+
+    it('should adjust the inline margin of sticky elements', done => {
+      fixtureEl.innerHTML = [
+        '<div style="height: 110vh">' +
+        '<div class="sticky-top" style="margin-right: 0px; width: 100vw; height: 10px"></div>',
+        '</div>'
+      ].join('')
+      document.documentElement.style.overflowY = 'scroll'
+
+      const stickyTopEl = fixtureEl.querySelector('.sticky-top')
+      const originalMargin = Number.parseInt(window.getComputedStyle(stickyTopEl).marginRight, 10)
+      const expectedMargin = originalMargin - Scrollbar.getWidth()
+      Scrollbar.hide()
+
+      let currentMargin = Number.parseInt(window.getComputedStyle(stickyTopEl).marginRight, 10)
+      expect(stickyTopEl.getAttribute('data-bs-margin-right')).toEqual('0px', 'original sticky element margin should be stored in data-bs-margin-right')
+      expect(currentMargin).toEqual(expectedMargin, 'sticky element margin should be adjusted while opening')
+
+      Scrollbar.reset()
+      currentMargin = Number.parseInt(window.getComputedStyle(stickyTopEl).marginRight, 10)
+
+      expect(stickyTopEl.getAttribute('data-bs-margin-right')).toEqual(null, 'data-bs-margin-right should be cleared after closing')
+      expect(currentMargin).toEqual(originalMargin, 'sticky element margin should be reset after closing')
+      done()
+    })
+
+    it('should not adjust the inline margin and padding of sticky and fixed elements when element do not have full width', () => {
+      fixtureEl.innerHTML = [
+        '<div class="sticky-top" style="margin-right: 0px; padding-right: 0px; width: 50vw"></div>'
+      ].join('')
+
+      const stickyTopEl = fixtureEl.querySelector('.sticky-top')
+      const originalMargin = Number.parseInt(window.getComputedStyle(stickyTopEl).marginRight, 10)
+      const originalPadding = Number.parseInt(window.getComputedStyle(stickyTopEl).paddingRight, 10)
+
+      Scrollbar.hide()
+
+      const currentMargin = Number.parseInt(window.getComputedStyle(stickyTopEl).marginRight, 10)
+      const currentPadding = Number.parseInt(window.getComputedStyle(stickyTopEl).paddingRight, 10)
+
+      expect(currentMargin).toEqual(originalMargin, 'sticky element\'s margin should not be adjusted while opening')
+      expect(currentPadding).toEqual(originalPadding, 'sticky element\'s padding should not be adjusted while opening')
+
+      Scrollbar.reset()
+    })
+  })
+})
diff --git a/scss/_offcanvas.scss b/scss/_offcanvas.scss
new file mode 100644 (file)
index 0000000..1eeb989
--- /dev/null
@@ -0,0 +1,77 @@
+.offcanvas {
+  position: fixed;
+  bottom: 0;
+  z-index: $zindex-offcanvas;
+  display: flex;
+  flex-direction: column;
+  max-width: 100%;
+  color: $offcanvas-color;
+  visibility: hidden;
+  background-color: $offcanvas-bg-color;
+  background-clip: padding-box;
+  outline: 0;
+  @include box-shadow($offcanvas-box-shadow);
+  @include transition(transform $offcanvas-transition-duration ease-in-out);
+}
+
+.offcanvas-header {
+  display: flex;
+  justify-content: space-between;
+  padding: $offcanvas-padding-y $offcanvas-padding-x;
+
+  .btn-close {
+    padding: ($offcanvas-padding-y / 2) ($offcanvas-padding-x / 2);
+    margin: ($offcanvas-padding-y / -2) ($offcanvas-padding-x / -2) ($offcanvas-padding-y / -2) auto;
+  }
+}
+
+.offcanvas-title {
+  margin-bottom: 0;
+  line-height: $offcanvas-title-line-height;
+}
+
+.offcanvas-body {
+  flex-grow: 1;
+  padding: $offcanvas-padding-y $offcanvas-padding-x;
+  overflow-y: auto;
+}
+
+.offcanvas-start {
+  top: 0;
+  left: 0;
+  width: $offcanvas-horizontal-width;
+  border-right: $offcanvas-border-width solid $offcanvas-border-color;
+  transform: translateX(-100%);
+}
+
+.offcanvas-end {
+  top: 0;
+  right: 0;
+  width: $offcanvas-horizontal-width;
+  border-left: $offcanvas-border-width solid $offcanvas-border-color;
+  transform: translateX(100%);
+}
+
+.offcanvas-bottom {
+  right: 0;
+  left: 0;
+  height: $offcanvas-vertical-height;
+  max-height: 100%;
+  border-top: $offcanvas-border-width solid $offcanvas-border-color;
+  transform: translateY(100%);
+}
+
+.offcanvas.show {
+  transform: none;
+}
+
+.offcanvas-backdrop::before {
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: $zindex-offcanvas - 1;
+  width: 100vw;
+  height: 100vh;
+  content: "";
+  background-color: $offcanvas-body-backdrop-color;
+}
index 4ffcf18edc45497bbbf4b9ffe42b79461cc6da09..2668a790cb778042c1826d0dc69144b143f83406 100644 (file)
@@ -902,10 +902,11 @@ $form-validation-states: (
 $zindex-dropdown:                   1000 !default;
 $zindex-sticky:                     1020 !default;
 $zindex-fixed:                      1030 !default;
-$zindex-modal-backdrop:             1040 !default;
-$zindex-modal:                      1050 !default;
-$zindex-popover:                    1060 !default;
-$zindex-tooltip:                    1070 !default;
+$zindex-offcanvas:                  1040 !default;
+$zindex-modal-backdrop:             1050 !default;
+$zindex-modal:                      1060 !default;
+$zindex-popover:                    1070 !default;
+$zindex-tooltip:                    1080 !default;
 // scss-docs-end zindex-stack
 
 
@@ -1431,6 +1432,23 @@ $btn-close-white-filter:     invert(1) grayscale(100%) brightness(200%) !default
 // scss-docs-end close-variables
 
 
+// Offcanvas
+
+// scss-docs-start offcanvas-variables
+$offcanvas-padding-y:               $modal-inner-padding !default;
+$offcanvas-padding-x:               $modal-inner-padding !default;
+$offcanvas-horizontal-width:        400px !default;
+$offcanvas-vertical-height:         30vh !default;
+$offcanvas-transition-duration:     .3s !default;
+$offcanvas-border-color:            $modal-content-border-color !default;
+$offcanvas-border-width:            $modal-content-border-width !default;
+$offcanvas-title-line-height:       $modal-title-line-height !default;
+$offcanvas-bg-color:                $modal-content-bg !default;
+$offcanvas-color:                   $modal-content-color !default;
+$offcanvas-body-backdrop-color:     rgba($modal-backdrop-bg, $modal-backdrop-opacity) !default;
+$offcanvas-box-shadow:              $modal-content-box-shadow-xs !default;
+// scss-docs-end offcanvas-variables
+
 // Code
 
 $code-font-size:                    $small-font-size !default;
index f5f411753399a157d01ada34753069dc6081b78e..2687d099154ad74e43b448a2048b66341c20e72d 100644 (file)
@@ -42,6 +42,7 @@
 @import "popover";
 @import "carousel";
 @import "spinners";
+@import "offcanvas";
 
 // Helpers
 @import "helpers";
index b997689ed1af5a9bf6891dbb9bd88ddea45d13ad..91b5bbfd3e9a626e68cd2a29ed5df8d4eb125d6d 100644 (file)
   }
 }
 
+.bd-example-offcanvas {
+  @include border-start-radius(0);
+
+  .offcanvas {
+    position: static;
+    display: block;
+    height: 200px;
+    visibility: visible;
+    transform: translateX(0);
+  }
+}
+
 // Tooltips
 .tooltip-demo a {
   white-space: nowrap;
diff --git a/site/content/docs/5.0/components/offcanvas.md b/site/content/docs/5.0/components/offcanvas.md
new file mode 100644 (file)
index 0000000..9eacfd6
--- /dev/null
@@ -0,0 +1,256 @@
+---
+layout: docs
+title: Offcanvas
+description: Build hidden sidebars into your project for navigation, shopping carts, and more with a few classes and our JavaScript plugin.
+group: components
+toc: true
+---
+
+## How it works
+
+Offcanvas is a sidebar component that can be toggled via JavaScript to appear from the left, right, or bottom edge of the viewport. Buttons or anchors are used as triggers that are attached to specific elements you toggle, and `data` attributes are used to invoke our JavaScript.
+
+- Offcanvas shares some of the same JavaScript code as modals. Conceptually, they are quite similar, but they are separate plugins.
+- Similarly, some [source Sass](#sass) variables for offcanvas's styles and dimensions are inherited from the modal's variables.
+- When shown, offcanvas includes a default backdrop that can be clicked to hide the offcanvas.
+- Similar to modals, only one offcanvas can be shown at a time.
+
+**Heads up!** Given how CSS handles animations, you cannot use `margin` or `translate` on an `.offcanvas` element. Instead, use the class as an independent wrapping element.
+
+{{< callout info >}}
+{{< partial "callout-info-prefersreducedmotion.md" >}}
+{{< /callout >}}
+
+## Examples
+
+### Offcanvas components
+
+Below is a _static_ offcanvas example (meaning its `position`, `display`, and `visibility` have been overridden). Offcanvas includes support for a header with a close button and an optional body class for some initial `padding`. We suggest that you include offcanvas headers with dismiss actions whenever possible, or provide an explicit dismiss action.
+
+{{< example class="bd-example-offcanvas p-0 bg-light" >}}
+<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvas" aria-labelledby="offcanvasLabel">
+  <div class="offcanvas-header">
+    <h5 class="offcanvas-title" id="offcanvasLabel">Offcanvas</h5>
+    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
+  </div>
+  <div class="offcanvas-body">
+    Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here.
+  </div>
+</div>
+{{< /example >}}
+
+### Live demo
+
+Use the buttons below to show and hide an offcanvas element via JavaScript that toggles the `.show` class on an element with the `.offcanvas` class.
+
+- `.offcanvas` hides content (default)
+- `.offcanvas.show` shows content
+
+You can use a link with the `href` attribute, or a button with the `data-bs-target` attribute. In both cases, the `data-bs-toggle="offcanvas"` is required.
+
+{{< example >}}
+<a class="btn btn-primary" data-bs-toggle="offcanvas" href="#offcanvasExample" role="button" aria-controls="offcanvasExample">
+  Link with href
+</a>
+<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasExample" aria-controls="offcanvasExample">
+  Button with data-bs-target
+</button>
+
+<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasExample" aria-labelledby="offcanvasExampleLabel">
+  <div class="offcanvas-header">
+    <h5 class="offcanvas-title" id="offcanvasExampleLabel">Offcanvas</h5>
+    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
+  </div>
+  <div class="offcanvas-body">
+    <div class="">
+      Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.
+    </div>
+    <div class="dropdown mt-3">
+      <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-bs-toggle="dropdown">
+        Dropdown button
+      </button>
+      <ul class="dropdown-menu" aria-labelledby="dropdownMenuButton">
+        <li><a class="dropdown-item" href="#">Action</a></li>
+        <li><a class="dropdown-item" href="#">Another action</a></li>
+        <li><a class="dropdown-item" href="#">Something else here</a></li>
+      </ul>
+    </div>
+  </div>
+</div>
+{{< /example >}}
+
+## Placement
+
+There's no default placement for offcanvas components, so you must add one of the modifier classes below;
+
+- `.offcanvas-start` places offcanvas on the left of the viewport (shown above)
+- `.offcanvas-end` places offcanvas on the right of the viewport
+- `.offcanvas-bottom` places offcanvas on the bottom of the viewport
+
+Try the right and bottom examples out below.
+
+{{< example >}}
+<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasRight" aria-controls="offcanvasRight">Toggle right offcanvas</button>
+
+<div class="offcanvas offcanvas-end" tabindex="-1" id="offcanvasRight" aria-labelledby="offcanvasRightLabel">
+  <div class="offcanvas-header">
+    <h5 id="offcanvasRightLabel">Offcanvas right</h5>
+    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
+  </div>
+  <div class="offcanvas-body">
+    ...
+  </div>
+</div>
+{{< /example >}}
+
+{{< example >}}
+<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasBottom" aria-controls="offcanvasBottom">Toggle bottom offcanvas</button>
+
+<div class="offcanvas offcanvas-bottom" tabindex="-1" id="offcanvasBottom" aria-labelledby="offcanvasBottomLabel">
+  <div class="offcanvas-header">
+    <h5 class="offcanvas-title" id="offcanvasBottomLabel">Offcanvas bottom</h5>
+    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
+  </div>
+  <div class="offcanvas-body small">
+    ...
+  </div>
+</div>
+{{< /example >}}
+
+## Options
+
+By default, we disable scrolling on the `<body>` when an offcanvas is visible and use a gray backdrop. Use the `data-bs-body` attribute to enable `<body>` scrolling, or a combination of both options
+
+{{< example >}}
+<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasScrolling" aria-controls="offcanvasScrolling">Enable body scrolling</button>
+<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBackdrop" aria-controls="offcanvasWithBackdrop">Enable backdrop (default)</button>
+<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBothOptions" aria-controls="offcanvasWithBothOptions">Enable both scrolling & backdrop</button>
+
+<div class="offcanvas offcanvas-start" data-bs-body="scroll" tabindex="-1" id="offcanvasScrolling" aria-labelledby="offcanvasScrollingLabel">
+  <div class="offcanvas-header">
+    <h5 class="offcanvas-title" id="offcanvasScrollingLabel">Colored with scrolling</h5>
+    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
+  </div>
+  <div class="offcanvas-body">
+    <p>Try scrolling the rest of the page to see this option in action.</p>
+  </div>
+</div>
+<div class="offcanvas offcanvas-start" data-bs-body="backdrop" tabindex="-1" id="offcanvasWithBackdrop" aria-labelledby="offcanvasWithBackdropLabel">
+  <div class="offcanvas-header">
+    <h5 class="offcanvas-title" id="offcanvasWithBackdropLabel">Offcanvas with backdrop</h5>
+    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
+  </div>
+  <div class="offcanvas-body">
+    <p>.....</p>
+  </div>
+</div>
+<div class="offcanvas offcanvas-start" data-bs-body="scroll,backdrop" tabindex="-1" id="offcanvasWithBothOptions" aria-labelledby="offcanvasWithBothOptionsLabel">
+  <div class="offcanvas-header">
+    <h5 class="offcanvas-title" id="offcanvasWithBothOptionsLabel">Backdroped with scrolling</h5>
+    <button type="button" class="btn-close text-reset" data-bs-dismiss="offcanvas" aria-label="Close"></button>
+  </div>
+  <div class="offcanvas-body">
+    <p>Try scrolling the rest of the page to see this option in action.</p>
+  </div>
+</div>
+{{< /example >}}
+
+## Accessibility
+
+Since the offcanvas panel is conceptually a modal dialog, be sure to add `aria-labelledby="..."`—referencing the offcanvas title—to `.offcanvas`. Note that you don’t need to add `role="dialog"` since we already add it via JavaScript.
+
+## Sass
+
+### Variables
+
+{{< scss-docs name="offcanvas-variables" file="scss/_variables.scss" >}}
+
+## Usage
+
+The offcanvas plugin utilizes a few classes and attributes to handle the heavy lifting:
+
+- `.offcanvas` hides the content
+- `.offcanvas.show` shows the content
+- `.offcanvas-start` hides the offcanvas on the left
+- `.offcanvas-end` hides the offcanvas on the right
+- `.offcanvas-bottom` hides the offcanvas on the bottom
+- `data-bs-body="scroll"` enables `<body>` scrolling when offcanvas is open
+- `data-bs-body="backdrop"` disables scrolling and creates a backdrop over the `<body>` when offcanvas is open `(default)`
+- `data-bs-body="backdrop,scroll"` combines both options to enable `<body>` scrolling and create a backdrop over the `<body>` when offcanvas is open
+
+Add a dismiss button with the `data-bs-dismiss="offcanvas"` attribute, which triggers the JavaScript functionality. Be sure to use the `<button>` element with it for proper behavior across all devices.
+
+### Via data attributes
+
+Add `data-bs-toggle="offcanvas"` and a `data-bs-target` or `href` to the element to automatically assign control of one offcanvas element. The `data-bs-target` attribute accepts a CSS selector to apply the offcanvas to. Be sure to add the class `offcanvas` to the offcanvas element. If you'd like it to default open, add the additional class `show`.
+
+### Via JavaScript
+
+Enable manually with:
+
+```js
+var offcanvasElementList = [].slice.call(document.querySelectorAll('.offcanvas'))
+var offcanvasList = offcanvasElementList.map(function (offcanvasEl) {
+  return new bootstrap.Offcanvas(offcanvasEl)
+})
+```
+
+### Methods
+
+{{< callout danger >}}
+{{< partial "callout-danger-async-methods.md" >}}
+{{< /callout >}}
+
+Activates your content as an offcanvas element. Accepts an optional options `object`.
+
+You can create an offcanvas instance with the constructor, for example:
+
+```js
+var myOffcanvas = document.getElementById('myOffcanvas')
+var bsOffcanvas = new bootstrap.Offcanvas(myOffcanvas)
+```
+
+| Method | Description |
+| --- | --- |
+| `toggle` | Toggles an offcanvas element to shown or hidden. **Returns to the caller before the offcanvas element has actually been shown or hidden** (i.e. before the `shown.bs.offcanvas` or `hidden.bs.offcanvas` event occurs). |
+| `show` | Shows an offcanvas element. **Returns to the caller before the offcanvas element has actually been shown** (i.e. before the `shown.bs.offcanvas` event occurs).|
+| `hide` | Hides an offcanvas element. **Returns to the caller before the offcanvas element has actually been hidden** (i.e. before the `hidden.bs.offcanvas` event occurs).|
+| `_getInstance` | *Static* method which allows you to get the offcanvas instance associated with a DOM element |
+
+### Events
+
+Bootstrap's offcanvas class exposes a few events for hooking into offcanvas functionality.
+
+<table class="table table-bordered table-striped">
+  <thead>
+    <tr>
+      <th style="width: 150px;">Event Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>show.bs.offcanvas</td>
+      <td>This event fires immediately when the <code>show</code> instance method is called.</td>
+    </tr>
+    <tr>
+      <td>shown.bs.offcanvas</td>
+      <td>This event is fired when an offcanvas element has been made visible to the user (will wait for CSS transitions to complete).</td>
+    </tr>
+    <tr>
+      <td>hide.bs.offcanvas</td>
+      <td>This event is fired immediately when the <code>hide</code> method has been called.</td>
+    </tr>
+    <tr>
+      <td>hidden.bs.offcanvas</td>
+      <td>This event is fired when an offcanvas element has been hidden from the user (will wait for CSS transitions to complete).</td>
+    </tr>
+  </tbody>
+</table>
+
+```js
+var myOffcanvas = document.getElementById('myOffcanvas')
+myOffcanvas.addEventListener('hidden.bs.offcanvas', function () {
+  // do something...
+})
+```
similarity index 99%
rename from site/content/docs/5.0/examples/offcanvas/index.html
rename to site/content/docs/5.0/examples/offcanvas-navbar/index.html
index 9aed0aed7dc70a17045cd90704cf3499133a38db..12bb91e07930714fb920e10a64562e565604ed7d 100644 (file)
@@ -1,6 +1,6 @@
 ---
 layout: examples
-title: Offcanvas template
+title: Offcanvas navbar template
 extra_css:
   - "offcanvas.css"
 extra_js:
index 0ddafaf416494b03c5dcbf39cb0772dd86001d87..d243bdad0dcc3b6910b68a3e90a2b74f1ddd85b1 100644 (file)
       description: "Single navbar example with a fixed top navbar along with some additional content."
     - name: Navbar bottom
       description: "Single navbar example with a bottom navbar along with some additional content."
-
-- category: Experiments
-  description: "Examples that focus on future-friendly features or techniques."
-  examples:
-    - name: Offcanvas
-      description: "Turn your expandable navbar into a sliding offcanvas menu."
+    - name: Offcanvas navbar
+      description: "Turn your expandable navbar into a sliding offcanvas menu (doesn't use our offcanvas component)."
 
 - category: RTL
   description: "See Bootstrap's RTL version in action with these modified Custom Components examples."
index 2c8f9b45c965a1080123c338e72495860be7176d..4e43255a3b6e66b2d0ee7aff5ff3758565e197ec 100644 (file)
@@ -72,6 +72,7 @@
     - title: Modal
     - title: Navs & tabs
     - title: Navbar
+    - title: Offcanvas
     - title: Pagination
     - title: Popovers
     - title: Progress