docs: clarify carousel getInstance timing and pause in events

Add two warning callouts to the carousel documentation:

- In "Via JavaScript": document that `Carousel.getInstance` returns
  `null` for uninitialized carousels and recommend `getOrCreateInstance`
  or the `window` `load` event as alternatives.
- In "Events": clarify that calling `pause` inside a `slide.bs.carousel`
  handler has no effect and recommend using `slid.bs.carousel` instead.

Fixes #35722

Signed-off-by: Pierluigi Lenoci <pierluigilenoci@gmail.com>

Author: pierluigilenoci

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

@@ -349,6 +349,21 @@ Call carousel manually with:
 const carousel = new bootstrap.Carousel('#myCarousel')
 ```
 
+<Callout type="warning">
+`Carousel.getInstance` will return `null` unless the carousel has already been initialized (either explicitly via the constructor, or automatically via `data-bs-ride`). If your carousel contains images or other asynchronous content, auto-initialization may not have completed by the time your script runs. To avoid a `null` reference, either initialize the carousel explicitly with the constructor, use `getOrCreateInstance`, or defer your code until the `window` `load` event:
+
+```js
+// Option 1 – use getOrCreateInstance (recommended)
+const carousel = bootstrap.Carousel.getOrCreateInstance('#myCarousel')
+
+// Option 2 – wait for the window load event
+window.addEventListener('load', () => {
+  const carousel = bootstrap.Carousel.getInstance('#myCarousel')
+  // carousel is now guaranteed to be initialized
+})
+```
+</Callout>
+
 ### Options
 
 <JsDataAttributes />
@@ -411,6 +426,19 @@ All carousel events are fired at the carousel itself (i.e. at the `<div class="c
 | `slide.bs.carousel` | Fires immediately when the `slide` instance method is invoked. |
 </BsTable>
 
+<Callout type="warning">
+Calling `pause` inside a `slide.bs.carousel` handler has no effect because the slide transition is already in progress. To programmatically pause the carousel after a slide change, use the `slid.bs.carousel` event instead:
+
+```js
+const myCarousel = document.getElementById('myCarousel')
+
+myCarousel.addEventListener('slid.bs.carousel', event => {
+  const carousel = bootstrap.Carousel.getInstance(myCarousel)
+  carousel.pause()
+})
+```
+</Callout>
+
 ```js
 const myCarousel = document.getElementById('myCarousel')