Expand docs on allDefined()

docs/docs/usage.md

@@ -12,6 +12,8 @@ If you're new to custom elements, often referred to as "web components," this se
 
 Unlike traditional frameworks, custom elements don't have a centralized initialization phase. This means you need to verify that a custom element has been properly registered before attempting to interact with its properties or methods.
 
+### Individual components: `customElements.whenDefined()` { #when-defined}
+
 You can use the [`customElements.whenDefined()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined) method to ensure a specific component is ready:
 
 ```ts
@@ -21,6 +23,8 @@ await customElements.whenDefined('wa-button');
 const button = document.querySelector('wa-button');
 ```
 
+### All Web Awesome components: `allDefined()` { #all-defined }
+
 When working with multiple components, checking each one individually can become tedious. For convenience, Web Awesome provides the `allDefined()` function which automatically detects and waits for all Web Awesome components in the DOM to be initialized before resolving.
 
 ```ts
@@ -32,6 +36,33 @@ await allDefined();
 // All Web Awesome components on the page are ready!
 ```
 
+#### Advanced Usage
+
+By default, `allDefined()` will wait for all `wa-` prefixed custom elements within the current `document` to be registered.
+You can customize this behavior by passing in options:
+- `root` allows you to pass in a different element to search within, or a different document entirely (defaults to `document`).
+- `match` allows you to specify a custom function to determine which elements to wait for. This function should return `true` for elements you want to wait for and `false` for those you don't.
+- `additionalElements` allows you to wait for custom elements to be defined that may not be present in the DOM at the time `allDefined()` is called. This can be useful for elements that are loaded dynamically via JS.
+
+Here is an example of using `match` and `root` to await registration of Web Awesome components inside an element with an id of `sidebar`, plus a `<my-component>` element if present in the DOM, and `<wa-slider>` and `<other-slider>` elements whether present in the DOM or not:
+
+```js
+import { allDefined } from '/dist/webawesome.js';
+
+await allDefined({
+  match: tagName => tagName.startsWith('wa-') || tagName === 'my-component',
+  root: document.getElementById('sidebar'),
+  additionalElements: ['wa-slider', 'other-slider']
+});
+```
+
+:::warning
+`additionalElements` will only wait for elements to be registered — it will not load them.
+If you're using the autoloader plus custom JS to inject HTML dynamically, **you need to make sure your JS runs _before_ the `await allDefined()` call**,
+otherwise you could run into a chicken and egg issue:
+since the autoloader will not load elements until they are present in the DOM, the promise will never resolve and your JS to inject them will not run.
+:::
+
 ## Attributes & Properties
 
 Many components have properties that can be set using attributes. For example, buttons accept a `size` attribute that maps to the `size` property which dictates the button's size.