Docs(web): Introduce Offcanvas readme and bind it to the Header

refs #DS-1012

packages/web/src/scss/components/Header/README.md

@@ -34,6 +34,9 @@ plugins.
 
 Or, feel free to write the controlling script yourself.
 
+The HeaderDialog uses the Offcanvas JS Plugin to toggle the dialog.
+See [Offcanvas documentation][offcanvas-docs] for more details.
+
 ## Accessibility Guidelines
 
 - Ensure accessibility by using a `<nav>` element or, if using a more generic
@@ -474,3 +477,4 @@ some important capabilities. Thank you! 🙏
 [examples]: https://lmc-eu.github.io/spirit-design-system/
 [web-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md
 [mdn-dialog]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
+[offcanvas-docs]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/src/scss/components/Offcanvas/README.md

packages/web/src/scss/components/Offcanvas/README.md

@@ -0,0 +1,79 @@
+# Offcanvas
+
+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 JavaScript plugin.
+
+## JavaScript Plugin
+
+For full functionality, you need to provide Spirit JavaScript, which will handle
+toggling of the Header component:
+
+```html
+<script src="node_modules/@lmc-eu/spirit-web/js/cjs/spirit-web.min.js" async></script>
+```
+
+## Usage
+
+### Via data attributes
+
+Add data-spirit-toggle="offcanvas" and a data-spirit-target or href to the element to automatically assign control of one Offcanvas element.
+The data-spirit-target attribute accepts a CSS selector to apply the Offcanvas to.
+
+### Via JavaScript
+
+Enable manually with:
+
+```js
+const offcanvasElementList = [].slice.call(document.querySelectorAll('.offcanvas'));
+const offcanvasList = offcanvasElementList.map(function (offcanvasElement) {
+  return new Offcanvas(offcanvasElement);
+});
+```
+
+### Options
+
+Options can be passed via data attributes or JavaScript.
+For data attributes, append the option name to data-spirit-, as in data-spirit-breakpointDesktop="".
+
+| Name              | Type   | Default | Description                                                       |
+| ----------------- | ------ | ------- | ----------------------------------------------------------------- |
+| breakpointDesktop | string | 1280 \* | Desktop breakpoint on which opened Offcanvas automatically closes |
+
+\*: Default value of the design token `others.breakpoints.desktop`. Can be also changed via `--spirit-breakpoint-desktop` CSS custom property.
+
+### Methods
+
+Activates your content as an offcanvas element. Accepts an optional options object.
+
+You can create an offcanvas instance with the constructor, for example:
+
+```js
+const customOffcanvas = document.getElementById('customOffcanvas');
+const spiritOffcanvas = new Offcanvas(customOffcanvas);
+```
+
+| 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 show.offcanvas or hidden.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.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.offcanvas event occurs).                                                 |
+| getInstance         | Static method which allows you to get the Offcanvas instance associated with a DOM element                                                                                                               |
+| getOrCreateInstance | Static method which allows you to get the Offcanvas instance associated with a DOM element, or create a new one in case it wasn’t initialised                                                            |
+
+### Events
+
+Spirit's Offcanvas class exposes a few events for hooking into Offcanvas functionality.
+
+| Event type       | Description                                                                                                                  |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| show.offcanvas   | This event fires immediately when the show instance method is called.                                                        |
+| shown.offcanvas  | This event is fired when an offcanvas element has been made visible to the user (will wait for CSS transitions to complete). |
+| hide.offcanvas   | This event is fired immediately when the hide method has been called.                                                        |
+| hidden.offcanvas | This event is fired when an offcanvas element has been hidden from the user (will wait for CSS transitions to complete)      |
+
+```js
+const myOffcanvas = document.getElementById('customOffcanvas');
+customOffcanvas.addEventListener('hidden.offcanvas', function () {
+  // do something...
+});
+```