From 548be2ed6604ddfc8488cd4a793c6271c2caf485 Mon Sep 17 00:00:00 2001 From: GeoSot Date: Tue, 2 Mar 2021 19:10:10 +0200 Subject: Offcanvas as component (#29017) * 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 Co-authored-by: Martijn Cuppens Co-authored-by: Mark Otto --- site/content/docs/5.0/components/offcanvas.md | 256 +++++++++++++++++++++ .../docs/5.0/examples/offcanvas-navbar/index.html | 139 +++++++++++ .../5.0/examples/offcanvas-navbar/offcanvas.css | 67 ++++++ .../5.0/examples/offcanvas-navbar/offcanvas.js | 7 + .../content/docs/5.0/examples/offcanvas/index.html | 139 ----------- .../docs/5.0/examples/offcanvas/offcanvas.css | 67 ------ .../docs/5.0/examples/offcanvas/offcanvas.js | 7 - 7 files changed, 469 insertions(+), 213 deletions(-) create mode 100644 site/content/docs/5.0/components/offcanvas.md create mode 100644 site/content/docs/5.0/examples/offcanvas-navbar/index.html create mode 100644 site/content/docs/5.0/examples/offcanvas-navbar/offcanvas.css create mode 100644 site/content/docs/5.0/examples/offcanvas-navbar/offcanvas.js delete mode 100644 site/content/docs/5.0/examples/offcanvas/index.html delete mode 100644 site/content/docs/5.0/examples/offcanvas/offcanvas.css delete mode 100644 site/content/docs/5.0/examples/offcanvas/offcanvas.js (limited to 'site/content/docs/5.0') 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 0000000000..9eacfd6b40 --- /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 ` + + + + + +
+ +
+ +
+
+ +
+

Bootstrap

+ Since 2011 +
+
+ +
+
Recent updates
+
+ {{< placeholder width="32" height="32" background="#007bff" color="#007bff" class="flex-shrink-0 me-2 rounded" >}} +

+ @username + Some representative placeholder content, with some information about this user. Imagine this being some sort of status update, perhaps? +

+
+
+ {{< placeholder width="32" height="32" background="#e83e8c" color="#e83e8c" class="flex-shrink-0 me-2 rounded" >}} +

+ @username + Some more representative placeholder content, related to this other user. Another status update, perhaps. +

+
+
+ {{< placeholder width="32" height="32" background="#6f42c1" color="#6f42c1" class="flex-shrink-0 me-2 rounded" >}} +

+ @username + This user also gets some representative placeholder content. Maybe they did something interesting, and you really want to highlight this in the recent updates. +

+
+ + All updates + +
+ +
+
Suggestions
+
+ {{< placeholder width="32" height="32" background="#007bff" color="#007bff" class="flex-shrink-0 me-2 rounded" >}} +
+
+ Full Name + Follow +
+ @username +
+
+
+ {{< placeholder width="32" height="32" background="#007bff" color="#007bff" class="flex-shrink-0 me-2 rounded" >}} +
+
+ Full Name + Follow +
+ @username +
+
+
+ {{< placeholder width="32" height="32" background="#007bff" color="#007bff" class="flex-shrink-0 me-2 rounded" >}} +
+
+ Full Name + Follow +
+ @username +
+
+ + All suggestions + +
+
diff --git a/site/content/docs/5.0/examples/offcanvas-navbar/offcanvas.css b/site/content/docs/5.0/examples/offcanvas-navbar/offcanvas.css new file mode 100644 index 0000000000..29e26b11bd --- /dev/null +++ b/site/content/docs/5.0/examples/offcanvas-navbar/offcanvas.css @@ -0,0 +1,67 @@ +html, +body { + overflow-x: hidden; /* Prevent scroll on narrow devices */ +} + +body { + padding-top: 56px; +} + +@media (max-width: 991.98px) { + .offcanvas-collapse { + position: fixed; + top: 56px; /* Height of navbar */ + bottom: 0; + left: 100%; + width: 100%; + padding-right: 1rem; + padding-left: 1rem; + overflow-y: auto; + visibility: hidden; + background-color: #343a40; + transition: transform .3s ease-in-out, visibility .3s ease-in-out; + } + .offcanvas-collapse.open { + visibility: visible; + transform: translateX(-100%); + } +} + +.nav-scroller { + position: relative; + z-index: 2; + height: 2.75rem; + overflow-y: hidden; +} + +.nav-scroller .nav { + display: flex; + flex-wrap: nowrap; + padding-bottom: 1rem; + margin-top: -1px; + overflow-x: auto; + color: rgba(255, 255, 255, .75); + text-align: center; + white-space: nowrap; + -webkit-overflow-scrolling: touch; +} + +.nav-underline .nav-link { + padding-top: .75rem; + padding-bottom: .75rem; + font-size: .875rem; + color: #6c757d; +} + +.nav-underline .nav-link:hover { + color: #007bff; +} + +.nav-underline .active { + font-weight: 500; + color: #343a40; +} + +.text-white-50 { color: rgba(255, 255, 255, .5); } + +.bg-purple { background-color: #6f42c1; } diff --git a/site/content/docs/5.0/examples/offcanvas-navbar/offcanvas.js b/site/content/docs/5.0/examples/offcanvas-navbar/offcanvas.js new file mode 100644 index 0000000000..793ea86cd3 --- /dev/null +++ b/site/content/docs/5.0/examples/offcanvas-navbar/offcanvas.js @@ -0,0 +1,7 @@ +(function () { + 'use strict' + + document.querySelector('[data-bs-toggle="offcanvas"]').addEventListener('click', function () { + document.querySelector('.offcanvas-collapse').classList.toggle('open') + }) +})() diff --git a/site/content/docs/5.0/examples/offcanvas/index.html b/site/content/docs/5.0/examples/offcanvas/index.html deleted file mode 100644 index 9aed0aed7d..0000000000 --- a/site/content/docs/5.0/examples/offcanvas/index.html +++ /dev/null @@ -1,139 +0,0 @@ ---- -layout: examples -title: Offcanvas template -extra_css: - - "offcanvas.css" -extra_js: - - src: "offcanvas.js" -body_class: "bg-light" ---- - - - -
- -
- -
-
- -
-

Bootstrap

- Since 2011 -
-
- -
-
Recent updates
-
- {{< placeholder width="32" height="32" background="#007bff" color="#007bff" class="flex-shrink-0 me-2 rounded" >}} -

- @username - Some representative placeholder content, with some information about this user. Imagine this being some sort of status update, perhaps? -

-
-
- {{< placeholder width="32" height="32" background="#e83e8c" color="#e83e8c" class="flex-shrink-0 me-2 rounded" >}} -

- @username - Some more representative placeholder content, related to this other user. Another status update, perhaps. -

-
-
- {{< placeholder width="32" height="32" background="#6f42c1" color="#6f42c1" class="flex-shrink-0 me-2 rounded" >}} -

- @username - This user also gets some representative placeholder content. Maybe they did something interesting, and you really want to highlight this in the recent updates. -

-
- - All updates - -
- -
-
Suggestions
-
- {{< placeholder width="32" height="32" background="#007bff" color="#007bff" class="flex-shrink-0 me-2 rounded" >}} -
-
- Full Name - Follow -
- @username -
-
-
- {{< placeholder width="32" height="32" background="#007bff" color="#007bff" class="flex-shrink-0 me-2 rounded" >}} -
-
- Full Name - Follow -
- @username -
-
-
- {{< placeholder width="32" height="32" background="#007bff" color="#007bff" class="flex-shrink-0 me-2 rounded" >}} -
-
- Full Name - Follow -
- @username -
-
- - All suggestions - -
-
diff --git a/site/content/docs/5.0/examples/offcanvas/offcanvas.css b/site/content/docs/5.0/examples/offcanvas/offcanvas.css deleted file mode 100644 index 29e26b11bd..0000000000 --- a/site/content/docs/5.0/examples/offcanvas/offcanvas.css +++ /dev/null @@ -1,67 +0,0 @@ -html, -body { - overflow-x: hidden; /* Prevent scroll on narrow devices */ -} - -body { - padding-top: 56px; -} - -@media (max-width: 991.98px) { - .offcanvas-collapse { - position: fixed; - top: 56px; /* Height of navbar */ - bottom: 0; - left: 100%; - width: 100%; - padding-right: 1rem; - padding-left: 1rem; - overflow-y: auto; - visibility: hidden; - background-color: #343a40; - transition: transform .3s ease-in-out, visibility .3s ease-in-out; - } - .offcanvas-collapse.open { - visibility: visible; - transform: translateX(-100%); - } -} - -.nav-scroller { - position: relative; - z-index: 2; - height: 2.75rem; - overflow-y: hidden; -} - -.nav-scroller .nav { - display: flex; - flex-wrap: nowrap; - padding-bottom: 1rem; - margin-top: -1px; - overflow-x: auto; - color: rgba(255, 255, 255, .75); - text-align: center; - white-space: nowrap; - -webkit-overflow-scrolling: touch; -} - -.nav-underline .nav-link { - padding-top: .75rem; - padding-bottom: .75rem; - font-size: .875rem; - color: #6c757d; -} - -.nav-underline .nav-link:hover { - color: #007bff; -} - -.nav-underline .active { - font-weight: 500; - color: #343a40; -} - -.text-white-50 { color: rgba(255, 255, 255, .5); } - -.bg-purple { background-color: #6f42c1; } diff --git a/site/content/docs/5.0/examples/offcanvas/offcanvas.js b/site/content/docs/5.0/examples/offcanvas/offcanvas.js deleted file mode 100644 index 793ea86cd3..0000000000 --- a/site/content/docs/5.0/examples/offcanvas/offcanvas.js +++ /dev/null @@ -1,7 +0,0 @@ -(function () { - 'use strict' - - document.querySelector('[data-bs-toggle="offcanvas"]').addEventListener('click', function () { - document.querySelector('.offcanvas-collapse').classList.toggle('open') - }) -})() -- cgit v1.2.3