Merge pull request #42827 from twbs/docs/accordion-expand-collapse-all

Document accordion expand/collapse all toggle

Author: mdo

.cspell.json

@@ -112,6 +112,7 @@
     "llms",
     "llmstxt",
     "longdesc",
+    "longhands",
     "Lowercased",
     "markdownify",
     "maxlength",

.gitignore

@@ -37,7 +37,7 @@ Thumbs.db
 # Folders to ignore
 /dist-sass/
 /js/coverage/
-/node_modules/
+/node_modules
 
 # Site
 /site/dist

node_modules

@@ -128,6 +128,36 @@ export default () => {
   }
   // js-docs-end live-alert
 
+  // -------------------------------
+  // Accordion expand / collapse all
+  // -------------------------------
+  // js-docs-start accordion-expand-collapse
+  const accordion = document.getElementById('accordionExpandCollapse')
+  const toggleBtn = document.getElementById('btnAccordionToggleAll')
+
+  if (accordion && toggleBtn) {
+    const items = accordion.querySelectorAll('.accordion-item')
+    const groupName = 'accordionExpandCollapse'
+
+    toggleBtn.addEventListener('click', () => {
+      const expand = toggleBtn.getAttribute('aria-expanded') !== 'true'
+
+      for (const item of items) {
+        if (expand) {
+          item.removeAttribute('name')
+          item.open = true
+        } else {
+          item.open = false
+          item.setAttribute('name', groupName)
+        }
+      }
+
+      toggleBtn.setAttribute('aria-expanded', String(expand))
+      toggleBtn.textContent = expand ? 'Collapse all' : 'Expand all'
+    })
+  }
+  // js-docs-end accordion-expand-collapse
+
   // --------
   // Carousels
   // --------

site/src/assets/partials/snippets.js

@@ -190,6 +190,46 @@ Omit the `name` attribute on each `<details>` element to allow multiple accordio
     <!-- More accordion items here -->
   </div>`} />
 
+## Expand & Collapse all
+
+To enable expanding and collapsing of all accordion items at once, remove the `name` attribute from each `<details>` element using JavaScript. This allows multiple accordion items to be open simultaneously. Restore the `name` attribute when you collapse the items again if you want exclusive behavior back.
+
+<Example code={`<button type="button" class="btn-subtle btn-sm theme-secondary mb-3" id="btnAccordionToggleAll" aria-expanded="false">Expand all</button>
+
+  <div class="accordion accordion-sm" id="accordionExpandCollapse">
+    <details class="accordion-item" name="accordionExpandCollapse" open>
+      <summary class="accordion-header">
+        Accordion Item #1
+        <svg class="accordion-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"><path d="m2 5 6 6 6-6"/></svg>
+      </summary>
+      <div class="accordion-body">
+        <strong>This is the first item’s accordion body.</strong> Use Expand all to open every item, even when they share a <code>name</code>.
+      </div>
+    </details>
+    <details class="accordion-item" name="accordionExpandCollapse">
+      <summary class="accordion-header">
+        Accordion Item #2
+        <svg class="accordion-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"><path d="m2 5 6 6 6-6"/></svg>
+      </summary>
+      <div class="accordion-body">
+        <strong>This is the second item’s accordion body.</strong> Collapse all closes every item and restores exclusive <code>name</code> grouping.
+      </div>
+    </details>
+    <details class="accordion-item" name="accordionExpandCollapse">
+      <summary class="accordion-header">
+        Accordion Item #3
+        <svg class="accordion-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"><path d="m2 5 6 6 6-6"/></svg>
+      </summary>
+      <div class="accordion-body">
+        <strong>This is the third item’s accordion body.</strong> If your accordion has no <code>name</code>, you only need to set <code>open</code> on each item.
+      </div>
+    </details>
+  </div>`} />
+
+We use the following JavaScript for this demo:
+
+<JsDocs name="accordion-expand-collapse" file="site/src/assets/partials/snippets.js" />
+
 ## Nested
 
 Accordions can be nested inside each other by placing a full `.accordion` within an `.accordion-body`. Use unique `name` attribute values for each level so the parent and child accordions operate independently.

site/src/content/docs/components/accordion.mdx

@@ -40,7 +40,7 @@ Or remove borders:
 
 ## Width
 
-Border width utilities are available in increments of 1px from 0 to 5px.
+Border width utilities are available in increments of 1px from 0 to 5px. These set `border-width` on all sides.
 
 <Example class="bd-example-border-utils" code={`<span class="border border-keyline"></span>
 <span class="border border-1"></span>
@@ -49,6 +49,64 @@ Border width utilities are available in increments of 1px from 0 to 5px.
 <span class="border border-4"></span>
 <span class="border border-5"></span>`} />
 
+### Per-side widths
+
+We do not ship per-side border width utilities. Combine a side utility with a width utility when one side needs a thicker border:
+
+<Example class="bd-example-border-utils" code={`<span class="border-top border-2"></span>
+<span class="border-end border-3"></span>
+<span class="border-bottom border-4"></span>
+<span class="border-start border-5"></span>`} />
+
+### Extend utilities
+
+Extend the border classes with our [utilities API]([[docsref:/utilities/api#add-utilities]]) when you need different widths on different sides, without combining classes as shown above. Here‘s an example using the width longhands instead of the border shorthand so values from `$border-widths` apply cleanly.
+
+```scss
+// _my-utilities.scss
+@use "sass:map";
+@use "bootstrap/scss/config" as *;
+@use "bootstrap/scss/utilities";
+
+$border-width-values: map.merge($border-widths, (keyline: var(--border-width-keyline)));
+
+$utilities: map.merge(
+  $utilities,
+  (
+    "border-top-width": (
+      property: border-block-start-width,
+      class: border-t,
+      values: $border-width-values
+    ),
+    "border-end-width": (
+      property: border-inline-end-width,
+      class: border-e,
+      values: $border-width-values
+    ),
+    "border-bottom-width": (
+      property: border-block-end-width,
+      class: border-b,
+      values: $border-width-values
+    ),
+    "border-start-width": (
+      property: border-inline-start-width,
+      class: border-s,
+      values: $border-width-values
+    )
+  )
+);
+```
+
+Load that partial before Bootstrap:
+
+```scss
+// my-bootstrap.scss
+@use "my-utilities";
+@use "bootstrap/scss/bootstrap";
+```
+
+This adds classes like `.border-t-5`, `.border-e-5`, `.border-b-5`, and `.border-s-5`. Pair them with `.border` or a side utility such as `.border-bottom` so the border still has a style and color.
+
 ## CSS
 
 ### Variables