diff --git a/.bundlewatch.config.json b/.bundlewatch.config.json index a68eeb85be48..4a28264b3a99 100644 --- a/.bundlewatch.config.json +++ b/.bundlewatch.config.json @@ -26,35 +26,35 @@ }, { "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": { diff --git a/build/build-plugins.js b/build/build-plugins.js index d1930b8556ed..7175df4dd562 100644 --- a/build/build-plugins.js +++ b/build/build-plugins.js @@ -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 } diff --git a/js/index.esm.js b/js/index.esm.js index b1bbf53a8f71..c041beffe255 100644 --- a/js/index.esm.js +++ b/js/index.esm.js @@ -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, diff --git a/js/index.umd.js b/js/index.umd.js index 5c44ce8d2def..a99a3be896a3 100644 --- a/js/index.umd.js +++ b/js/index.umd.js @@ -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 index 000000000000..148f003e9634 --- /dev/null +++ b/js/src/offcanvas.js @@ -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 index 000000000000..d2f3919e6c7a --- /dev/null +++ b/js/src/util/scrollbar.js @@ -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 index 000000000000..d07c0c61021f --- /dev/null +++ b/js/tests/unit/offcanvas.spec.js @@ -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 = [ + '
', + ' Close', + '
' + ].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 = '
' + + 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 = '
' + + 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 = '
' + + 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 = '
' + + 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 = '
' + + 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 = '
' + + 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 = '
' + + 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 = '
' + + 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 = '
' + + 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 = '
' + + 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 = [ + '', + '
' + ].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 = [ + '', + '
' + ].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 = '
' + + 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 = '
' + + 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 = '
' + + 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 = '
' + + 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 = '
' + + 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 = '
' + + 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 index 000000000000..eb344a0aa64c --- /dev/null +++ b/js/tests/unit/util/scrollbar.spec.js @@ -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 = [ + '
' + ].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 = [ + '
' + ].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 = [ + '
' + ].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 = [ + '
' + ].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 = [ + '
' + + '
', + '
', + '
' + ].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 = [ + '
' + + '
', + '
' + ].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 = [ + '
' + ].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 index 000000000000..1eeb989666d1 --- /dev/null +++ b/scss/_offcanvas.scss @@ -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; +} diff --git a/scss/_variables.scss b/scss/_variables.scss index 4ffcf18edc45..2668a790cb77 100644 --- a/scss/_variables.scss +++ b/scss/_variables.scss @@ -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; diff --git a/scss/bootstrap.scss b/scss/bootstrap.scss index f5f411753399..2687d099154a 100644 --- a/scss/bootstrap.scss +++ b/scss/bootstrap.scss @@ -42,6 +42,7 @@ @import "popover"; @import "carousel"; @import "spinners"; +@import "offcanvas"; // Helpers @import "helpers"; diff --git a/site/assets/scss/_component-examples.scss b/site/assets/scss/_component-examples.scss index b997689ed1af..91b5bbfd3e9a 100644 --- a/site/assets/scss/_component-examples.scss +++ b/site/assets/scss/_component-examples.scss @@ -201,6 +201,18 @@ } } +.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 index 000000000000..9eacfd6b40fa --- /dev/null +++ b/site/content/docs/5.0/components/offcanvas.md @@ -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" >}} +
+
+
Offcanvas
+ +
+
+ Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here. +
+
+{{< /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 >}} + + Link with href + + + +
+
+
Offcanvas
+ +
+
+
+ Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc. +
+
+ + +
+
+
+{{< /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 >}} + + +
+
+
Offcanvas right
+ +
+
+ ... +
+
+{{< /example >}} + +{{< example >}} + + +
+
+
Offcanvas bottom
+ +
+
+ ... +
+
+{{< /example >}} + +## Options + +By default, we disable scrolling on the `` when an offcanvas is visible and use a gray backdrop. Use the `data-bs-body` attribute to enable `` scrolling, or a combination of both options + +{{< example >}} + + + + +
+
+
Colored with scrolling
+ +
+
+

Try scrolling the rest of the page to see this option in action.

+
+
+
+
+
Offcanvas with backdrop
+ +
+
+

.....

+
+
+
+
+
Backdroped with scrolling
+ +
+
+

Try scrolling the rest of the page to see this option in action.

+
+
+{{< /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 `` scrolling when offcanvas is open +- `data-bs-body="backdrop"` disables scrolling and creates a backdrop over the `` when offcanvas is open `(default)` +- `data-bs-body="backdrop,scroll"` combines both options to enable `` scrolling and create a backdrop over the `` 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 `