Attempt to return focus explicitly to dropdown trigger (#41365)

Co-authored-by: Mark Otto <mdo@heypierre.app>

build/vnu-jar.mjs

@@ -35,7 +35,9 @@ execFile('java', ['-version'], (error, stdout, stderr) => {
     'Attribute “is:raw” is not serializable as XML 1.0.',
     'Attribute “is:raw” not allowed on element “code” at this point.',
     // Astro's expecting trailing slashes on HTML tags such as <br />
-    'Trailing slash on void elements has no effect and interacts badly with unquoted attribute values.'
+    'Trailing slash on void elements has no effect and interacts badly with unquoted attribute values.',
+    // Allow `switch` attribute.
+    'Attribute “switch” not allowed on element “input” at this point.'
   ].join('|')
 
   const args = [

js/src/base-component.js

@@ -45,6 +45,7 @@ class BaseComponent extends Config {
     }
   }
 
+  // Private
   _queueCallback(callback, element, isAnimated = true) {
     executeAfterTransition(callback, element, isAnimated)
   }

js/src/dropdown.js

@@ -207,6 +207,9 @@ class Dropdown extends BaseComponent {
     this._element.setAttribute('aria-expanded', 'false')
     Manipulator.removeDataAttribute(this._menu, 'popper')
     EventHandler.trigger(this._element, EVENT_HIDDEN, relatedTarget)
+
+    // Explicitly return focus to the trigger element
+    this._element.focus()
   }
 
   _getConfig(config) {

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...
+})
+```

site/src/content/docs/components/list-group.mdx

@@ -30,22 +30,12 @@ Add `.active` to a `.list-group-item` to indicate the current active selection.
     <li class="list-group-item">And a fifth one</li>
   </ul>`} />
 
-## Disabled items
-
-Add `.disabled` to a `.list-group-item` to make it _appear_ disabled. Note that some elements with `.disabled` will also require custom JavaScript to fully disable their click events (e.g., links).
-
-<Example code={`<ul class="list-group">
-    <li class="list-group-item disabled" aria-disabled="true">A disabled item</li>
-    <li class="list-group-item">A second item</li>
-    <li class="list-group-item">A third item</li>
-    <li class="list-group-item">A fourth item</li>
-    <li class="list-group-item">And a fifth one</li>
-  </ul>`} />
-
 ## Links and buttons
 
 Use `<a>`s or `<button>`s to create _actionable_ list group items with hover, disabled, and active states by adding `.list-group-item-action`. We separate these pseudo-classes to ensure list groups made of non-interactive elements (like `<li>`s or `<div>`s) don’t provide a click or tap affordance.
 
+Make `.list-group-item-action` instances _appear_ disabled by adding `.disabled`, and `aria-disabled="true"` to inform assistive technologies that the element is disabled. You may require additional JavaScript to fully disable links and buttons.
+
 Be sure to **not use the standard `.btn` classes here**.
 
 <Example code={`<div class="list-group">
@@ -55,7 +45,7 @@ Be sure to **not use the standard `.btn` classes here**.
     <a href="#" class="list-group-item list-group-item-action">A second link item</a>
     <a href="#" class="list-group-item list-group-item-action">A third link item</a>
     <a href="#" class="list-group-item list-group-item-action">A fourth link item</a>
-    <a class="list-group-item list-group-item-action disabled" aria-disabled="true">A disabled link item</a>
+    <a href="#" class="list-group-item list-group-item-action disabled" aria-disabled="true">A disabled link item</a>
   </div>`} />
 
 With `<button>`s, you can also make use of the `disabled` attribute instead of the `.disabled` class. Sadly, `<a>`s don’t support the disabled attribute.

site/src/content/docs/forms/checks-radios.mdx

@@ -9,7 +9,7 @@ toc: true
 
 Browser default checkboxes and radios are replaced with the help of `.form-check`, a series of classes for both input types that improves the layout and behavior of their HTML elements, that provide greater customization and cross browser consistency. Checkboxes are for selecting one or several options in a list, while radios are for selecting one option from many.
 
-Structurally, our `<input>`s and `<label>`s are sibling elements as opposed to an `<input>` within a `<label>`. This is slightly more verbose as you must specify `id` and `for` attributes to relate the `<input>` and `<label>`. We use the sibling selector (`~`) for all our `<input>` states, like `:checked` or `:disabled`. When combined with the `.form-check-label` class, we can easily style the text for each item based on the `<input>`’s state.
+Structurally, our `<input>`s and `<label>`s are sibling elements as opposed to an `<input>` within a `<label>`. This is slightly more verbose as you must specify `id` and `for` attributes to relate the `<input>` and `<label>`. We use the sibling selector (`~`) for all our `<input>` states, like `:checked` or `:disabled`. When combined with the `.form-check-label` class, we can easily style the text for each item based on the `<input>`'s state.
 
 Our checks use custom Bootstrap icons to indicate checked or indeterminate states.
 
@@ -41,7 +41,7 @@ Checkboxes can utilize the `:indeterminate` pseudo class when manually set via J
 
 ### Disabled
 
-Add the `disabled` attribute and the associated `<label>`s are automatically styled to match with a lighter color to help indicate the input’s state.
+Add the `disabled` attribute and the associated `<label>`s are automatically styled to match with a lighter color to help indicate the input's state.
 
 <Example addStackblitzJs class="bd-example-indeterminate" code={`<div class="form-check">
     <input class="form-check-input" type="checkbox" value="" id="checkIndeterminateDisabled" disabled>
@@ -79,7 +79,7 @@ Add the `disabled` attribute and the associated `<label>`s are automatically sty
 
 ### Disabled
 
-Add the `disabled` attribute and the associated `<label>`s are automatically styled to match with a lighter color to help indicate the input’s state.
+Add the `disabled` attribute and the associated `<label>`s are automatically styled to match with a lighter color to help indicate the input's state.
 
 <Example code={`<div class="form-check">
     <input class="form-check-input" type="radio" name="radioDisabled" id="radioDisabled" disabled>
@@ -115,6 +115,19 @@ A switch has the markup of a custom checkbox but uses the `.form-switch` class t
     <label class="form-check-label" for="switchCheckCheckedDisabled">Disabled checked switch checkbox input</label>
   </div>`} />
 
+### Native switches
+
+Progressively enhance your switches for mobile Safari (iOS 17.4+) by adding a `switch` attribute to your input to enable haptic feedback when toggling switches, just like native iOS switches. There are no style changes attached to using this attribute in Bootstrap as all our switches use custom styles.
+
+<Example code={`<div class="form-check form-switch">
+  <input class="form-check-input" type="checkbox" value="" id="checkNativeSwitch" switch>
+  <label class="form-check-label" for="checkNativeSwitch">
+    Native switch haptics
+  </label>
+</div>`} />
+
+Be sure to read more about [the switch attribute on the WebKit blog](https://webkit.org/blog/15054/an-html-switch-control/). Safari 17.4+ on macOS and iOS both have native-style switches in HTML while other browsers simply fall back to the standard checkbox appearance. Applying the attribute to a non-Bootstrap checkbox in more recent versions of Safari will render a native switch.
+
 ## Default (stacked)
 
 By default, any number of checkboxes and radios that are immediate sibling will be vertically stacked and appropriately spaced with `.form-check`.
@@ -240,7 +253,7 @@ Create button-like checkboxes and radio buttons by using `.btn` styles rather th
 <label class="btn" for="btn-check-6">Disabled</label>`} />
 
 <Callout>
-Visually, these checkbox toggle buttons are identical to the [button plugin toggle buttons]([[docsref:/components/buttons#button-plugin]]). However, they are conveyed differently by assistive technologies: the checkbox toggles will be announced by screen readers as “checked”/“not checked” (since, despite their appearance, they are fundamentally still checkboxes), whereas the button plugin toggle buttons will be announced as “button”/“button pressed”. The choice between these two approaches will depend on the type of toggle you are creating, and whether or not the toggle will make sense to users when announced as a checkbox or as an actual button.
+Visually, these checkbox toggle buttons are identical to the [button plugin toggle buttons]([[docsref:/components/buttons#button-plugin]]). However, they are conveyed differently by assistive technologies: the checkbox toggles will be announced by screen readers as "checked"/"not checked" (since, despite their appearance, they are fundamentally still checkboxes), whereas the button plugin toggle buttons will be announced as "button"/"button pressed". The choice between these two approaches will depend on the type of toggle you are creating, and whether or not the toggle will make sense to users when announced as a checkbox or as an actual button.
 </Callout>
 
 ### Radio toggle buttons