Docs: add Usage section with JavaScript guide for Accordion component (#40768)

Co-authored-by: Julien Déramond <juderamond@gmail.com>
Co-authored-by: Tommaso Allegretti <tommasoallegretti@users.noreply.github.com>

diff --git a/site/src/content/docs/components/accordion.mdx b/site/src/content/docs/components/accordion.mdx
index e452a07de4b224961e78a5e4aa8b9dcd437e6edd..06c95d4a2209c37729554f2b482b81020eed22df 100644 (file)
--- a/site/src/content/docs/components/accordion.mdx
+++ b/site/src/content/docs/components/accordion.mdx
@@ -157,3 +157,84 @@ As part of Bootstrap’s evolving CSS variables approach, accordions now use loc
 ### Sass variables
 
 <ScssDocs name="accordion-variables" file="scss/_variables.scss" />
+
+## Usage
+
+The collapse plugin utilizes a few classes to handle the heavy lifting:
+
+- `.collapse` hides the content
+- `.collapse.show` shows the content
+- `.collapsing` is added when the transition starts, and removed when it finishes
+
+These classes can be found in `_transitions.scss`.
+
+### Via data attributes
+
+Just add `data-bs-toggle="collapse"` and a `data-bs-target` to the element to automatically assign control of one or more collapsible elements. The `data-bs-target` attribute accepts a CSS selector to apply the collapse to. Be sure to add the class `collapse` to the collapsible element. If you’d like it to default open, add the additional class `show`.
+
+To add accordion group management to a collapsible area, add the data attribute `data-bs-parent="#selector"`.
+
+### Via JavaScript
+
+Enable manually with:
+
+```js
+const accordionCollapseElementList = document.querySelectorAll('#myAccordion.collapse')
+const accordionCollapseList = [...accordionCollapseElementList].map(accordionCollapseEl => new bootstrap.Collapse(accordionCollapseEl))
+```
+
+### Options
+
+<JsDataAttributes />
+
+<BsTable>
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+`parent` | selector, DOM element | `null` | If parent is provided, then all collapsible elements under the specified parent will be closed when this collapsible item is shown. (similar to traditional accordion behavior - this is dependent on the `card` class). The attribute has to be set on the target collapsible area. |
+`toggle` | boolean | `true` | Toggles the collapsible element on invocation. |
+</BsTable>
+
+### Methods
+
+<Callout name="danger-async-methods" type="danger" />
+
+Activates your content as a collapsible element. Accepts an optional options `object`.
+
+You can create a collapse instance with the constructor, for example:
+
+```js
+const bsCollapse = new bootstrap.Collapse('#myCollapse', {
+  toggle: false
+})
+```
+
+<BsTable>
+| Method | Description |
+| --- | --- |
+| `dispose` | Destroys an element’s collapse. (Removes stored data on the DOM element) |
+| `getInstance` | Static method which allows you to get the collapse instance associated to a DOM element, you can use it like this: `bootstrap.Collapse.getInstance(element)`. |
+| `getOrCreateInstance` | Static method which returns a collapse instance associated to a DOM element or create a new one in case it wasn’t initialized. You can use it like this: `bootstrap.Collapse.getOrCreateInstance(element)`. |
+| `hide` | Hides a collapsible element. **Returns to the caller before the collapsible element has actually been hidden** (e.g., before the `hidden.bs.collapse` event occurs). |
+| `show` | Shows a collapsible element. **Returns to the caller before the collapsible element has actually been shown** (e.g., before the `shown.bs.collapse` event occurs). |
+| `toggle` | Toggles a collapsible element to shown or hidden. **Returns to the caller before the collapsible element has actually been shown or hidden** (i.e. before the `shown.bs.collapse` or `hidden.bs.collapse` event occurs). |
+</BsTable>
+
+### Events
+
+Bootstrap’s collapse class exposes a few events for hooking into collapse functionality.
+
+<BsTable>
+| Event type | Description |
+| --- | --- |
+| `hide.bs.collapse` | This event is fired immediately when the `hide` method has been called. |
+| `hidden.bs.collapse` | This event is fired when a collapse element has been hidden from the user (will wait for CSS transitions to complete). |
+| `show.bs.collapse` | This event fires immediately when the `show` instance method is called. |
+| `shown.bs.collapse` | This event is fired when a collapse element has been made visible to the user (will wait for CSS transitions to complete). |
+</BsTable>
+
+```js
+const myCollapsible = document.getElementById('myCollapsible')
+myCollapsible.addEventListener('hidden.bs.collapse', event => {
+  // do something...
+})
+```