fix: add docs and address PR comments

packages/bundle/elements.ts

@@ -31,6 +31,7 @@ import '@spectrum-web-components/color-loupe/sp-color-loupe.js';
 import '@spectrum-web-components/color-slider/sp-color-slider.js';
 import '@spectrum-web-components/color-wheel/sp-color-wheel.js';
 import '@spectrum-web-components/dialog/sp-dialog.js';
+import '@spectrum-web-components/dialog/sp-dialog-base.js';
 import '@spectrum-web-components/dialog/sp-dialog-wrapper.js';
 import '@spectrum-web-components/divider/sp-divider.js';
 import '@spectrum-web-components/dropzone/sp-dropzone.js';

packages/dialog/dialog-base.md

@@ -0,0 +1,56 @@
+## Description
+
+`sp-dialog-base` accepts slotted dialog content (often an `<sp-dialog>`) and presents that content in a container that is animated into place when toggling the `open` attribute. In concert with the [Overlay API](../overlay) or [Overlay Trigger](../overlay-trigger), the provided dialog content will be displayed on over the rest of the page. Leverage the `interaction = modal` and `receivesFocus = 'auto'` setting in the Overlay API to ensure that focus is thrown into the dialog content when opened and that the tab order will be trapped with in that content while open.
+
+### Usage
+
+[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/dialog?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/dialog)
+[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/dialog?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/dialog)
+[![Try it on webcomponents.dev](https://img.shields.io/badge/Try%20it%20on-webcomponents.dev-green?style=for-the-badge)](https://webcomponents.dev/edit/collection/fO75441E1Q5ZlI0e9pgq/MLYDVWpWhNxJZDW3Ywqq/src/index.ts)
+
+```
+yarn add @spectrum-web-components/dialog
+```
+
+Import the side effectful registration of `<sp-dialog-base>` via:
+
+```
+import '@spectrum-web-components/dialog/sp-dialog-base.js';
+```
+
+When looking to leverage the `DialogBase` base class as a type and/or for extension purposes, do so via:
+
+```
+import { DialogBase } from '@spectrum-web-components/dialog';
+```
+
+## Example
+
+```html
+<overlay-trigger type="modal" placement="none">
+    <sp-dialog-base underlay slot="click-content">
+        <sp-dialog size="s">
+            <h2 slot="heading">A thing is about to happen</h2>
+            <p>Something that might happen a lot is about to happen.</p>
+            <p>
+                The click events for the "OK" button are bound to the story not
+                to the components in specific.
+            </p>
+            <sp-button
+                variant="secondary"
+                treatment="fill"
+                slot="button"
+                onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
+            >
+                Ok
+            </sp-button>
+            <sp-checkbox slot="footer">Don't show me this again</sp-checkbox>
+        </sp-dialog>
+    </sp-dialog-base>
+    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
+</overlay-trigger>
+```
+
+## Dialog
+
+`sp-dialog-base` expects a single slotted child element to play the role of the dialog that it will deliver within your application. When leveraging it as a base class be sure to customize the `dialog` getter to ensure that it acquires the appropriate element for your use case in order to correctly pass focus into your content when the dialog is opened.

packages/dialog/src/DialogBase.ts

@@ -30,7 +30,7 @@ import { FocusVisiblePolyfillMixin } from '@spectrum-web-components/shared';
 import { firstFocusableIn } from '@spectrum-web-components/shared/src/first-focusable-in.js';
 
 /**
- * @element sp-dialog-wrapper
+ * @element sp-dialog-base
  *
  * @slot - A Dialog element to display.
  * @fires close - Announces that the dialog has been closed.
@@ -65,9 +65,19 @@ export class DialogBase extends FocusVisiblePolyfillMixin(SpectrumElement) {
     public underlay = false;
 
     protected get dialog(): Dialog {
-        return (
+        const dialog = (
             this.shadowRoot.querySelector('slot') as HTMLSlotElement
         ).assignedElements()[0] as Dialog;
+        if (window.__swc.DEBUG) {
+            if (!dialog) {
+                window.__swc.warn(
+                    this,
+                    `<${this.localName}> expects to be provided dialog content via its default slot.`,
+                    'https://opensource.adobe.com/spectrum-web-components/components/dialog-base/#dialog'
+                );
+            }
+        }
+        return dialog || this;
     }
 
     public override focus(): void {

packages/dialog/src/DialogWrapper.ts

@@ -103,8 +103,8 @@ export class DialogWrapper extends DialogBase {
                 ?dismissable=${this.dismissable}
                 ?no-divider=${this.noDivider}
                 ?error=${this.error}
-                mode=${ifDefined(this.mode ? this.mode : undefined)}
-                size=${ifDefined(this.size ? this.size : undefined)}
+                mode=${ifDefined(this.mode)}
+                size=${ifDefined(this.size)}
             >
                 ${this.hero
                     ? html`

packages/dialog/test/dialog-wrapper.test.ts

@@ -105,8 +105,9 @@ describe('Dialog Wrapper', () => {
         expect(el.open).to.be.false;
         expect(closeSpy.callCount).to.equal(1);
     });
-    xit('opens and closes', async () => {
-        // There is an `sp-dialog-base` recyling issue in Chromium and Firefox
+    xit('opens and closes when element is recycled', async () => {
+        // Skip while there is an `sp-dialog-base` recyling issue in Chromium and Firefox,
+        // this test passes outside of the testing context and in Safari...
         const closeSpy = spy();
         const test = await styledFixture<OverlayTrigger>(longContent());
         const el = test.querySelector('sp-dialog-wrapper') as DialogWrapper;

packages/theme/README.md

@@ -142,7 +142,7 @@ When bundling your application, be sure to consult the documentation of your bun
 
 ### Language Context
 
-The `<sp-theme>` element provides a language context for its descendents in the DOM. Descendents can resolve this context by dispatching a `sp-language-context` DOM event and supplying a `callback(lang: string) => void` method in the `detail` entry of the Custom Event. These callbacks will be reactively envoked when the `lang` attribute on the `<sp-theme>` element is updated. In this way you can control the resolved language in [`<sp-number-field>`](./components/number-field), [`<sp-slider>`](./components/slider), and more elements in one centralized place.
+The `<sp-theme>` element provides a language context for its descendents in the DOM. Descendents can resolve this context by dispatching a `sp-language-context` DOM event and supplying a `callback(lang: string) => void` method in the `detail` entry of the Custom Event. These callbacks will be reactively envoked when the `lang` attribute on the `<sp-theme>` element is updated. In this way you can control the resolved language in [`<sp-number-field>`](../components/number-field), [`<sp-slider>`](./components/slider), and more elements in one centralized place.
 
 ## Light theme