docs: refactor navigation and settings UI to leverage trigger directi…

…ve (#4247)

* docs: refactor navigation and settings UI to leverage sp-overlay

* docs: power nav and settings panels with the "trigger" directive

* docs: prevent underlay outside of "mobile"

* refactor: move around some code for bundle shape management

packages/overlay/package.json

@@ -77,6 +77,10 @@
             "development": "./src/VirtualTrigger.dev.js",
             "default": "./src/VirtualTrigger.js"
         },
+        "./src/events.js": {
+            "development": "./src/events.dev.js",
+            "default": "./src/events.js"
+        },
         "./src/fullSizePlugin.js": {
             "development": "./src/fullSizePlugin.dev.js",
             "default": "./src/fullSizePlugin.js"

packages/overlay/src/AbstractOverlay.ts

@@ -19,7 +19,6 @@ import type {
     OverlayState,
     OverlayTypes,
     Placement,
-    TriggerInteractions,
     TriggerInteractionsV1,
 } from './overlay-types.js';
 import type { Overlay } from './Overlay.js';
@@ -34,65 +33,6 @@ export const noop = (): void => {
     return;
 };
 
-export class BeforetoggleClosedEvent extends Event {
-    currentState = 'open';
-    newState = 'closed';
-    constructor() {
-        super('beforetoggle', {
-            bubbles: false,
-            composed: false,
-        });
-    }
-}
-
-export class BeforetoggleOpenEvent extends Event {
-    currentState = 'closed';
-    newState = 'open';
-    constructor() {
-        super('beforetoggle', {
-            bubbles: false,
-            composed: false,
-        });
-    }
-}
-
-export class OverlayStateEvent extends Event {
-    detail!: {
-        interaction: string;
-        reason?: 'external-click';
-    };
-
-    constructor(
-        type: string,
-        public overlay: HTMLElement,
-        {
-            publish,
-            interaction,
-            reason,
-        }: {
-            publish?: boolean;
-            interaction: TriggerInteractions;
-            reason?: 'external-click';
-        }
-    ) {
-        super(type, {
-            bubbles: publish,
-            composed: publish,
-        });
-        this.detail = {
-            interaction,
-            reason,
-        };
-    }
-}
-
-declare global {
-    interface GlobalEventHandlersEventMap {
-        'sp-open': OverlayStateEvent;
-        'sp-close': OverlayStateEvent;
-    }
-}
-
 /**
  * Apply a "transitionend" listener to an element that may not transition but
  * guarantee the callback will be fired either way.

packages/overlay/src/OverlayDialog.ts

@@ -16,13 +16,12 @@ import {
 } from '@spectrum-web-components/shared/src/first-focusable-in.js';
 import { VirtualTrigger } from './VirtualTrigger.js';
 import { Constructor, OpenableElement } from './overlay-types.js';
+import { guaranteedAllTransitionend, nextFrame } from './AbstractOverlay.js';
 import {
     BeforetoggleClosedEvent,
     BeforetoggleOpenEvent,
-    guaranteedAllTransitionend,
-    nextFrame,
     OverlayStateEvent,
-} from './AbstractOverlay.js';
+} from './events.js';
 import type { AbstractOverlay } from './AbstractOverlay.js';
 import { userFocusableSelector } from '@spectrum-web-components/shared';
 

packages/overlay/src/OverlayNoPopover.ts

@@ -17,13 +17,15 @@ import type { SpectrumElement } from '@spectrum-web-components/base';
 import { VirtualTrigger } from './VirtualTrigger.js';
 import { Constructor, OpenableElement } from './overlay-types.js';
 import {
-    BeforetoggleClosedEvent,
-    BeforetoggleOpenEvent,
     guaranteedAllTransitionend,
     nextFrame,
-    OverlayStateEvent,
     overlayTimer,
 } from './AbstractOverlay.js';
+import {
+    BeforetoggleClosedEvent,
+    BeforetoggleOpenEvent,
+    OverlayStateEvent,
+} from './events.js';
 import type { AbstractOverlay } from './AbstractOverlay.js';
 import { userFocusableSelector } from '@spectrum-web-components/shared';
 

packages/overlay/src/OverlayPopover.ts

@@ -17,13 +17,15 @@ import type { SpectrumElement } from '@spectrum-web-components/base';
 import { VirtualTrigger } from './VirtualTrigger.js';
 import { Constructor, OpenableElement } from './overlay-types.js';
 import {
-    BeforetoggleClosedEvent,
-    BeforetoggleOpenEvent,
     guaranteedAllTransitionend,
     nextFrame,
-    OverlayStateEvent,
     overlayTimer,
 } from './AbstractOverlay.js';
+import {
+    BeforetoggleClosedEvent,
+    BeforetoggleOpenEvent,
+    OverlayStateEvent,
+} from './events.js';
 import type { AbstractOverlay } from './AbstractOverlay.js';
 import { userFocusableSelector } from '@spectrum-web-components/shared';
 

packages/overlay/src/OverlayTrigger.ts

@@ -24,7 +24,7 @@ import {
 } from '@spectrum-web-components/base/src/decorators.js';
 import type { Placement } from '@floating-ui/dom';
 
-import type { BeforetoggleOpenEvent } from './AbstractOverlay.js';
+import type { BeforetoggleOpenEvent } from './events.js';
 import type { Overlay } from './Overlay.js';
 import type { OverlayTriggerInteractions } from './overlay-types';
 

packages/overlay/src/events.ts

@@ -0,0 +1,65 @@
+/*
+Copyright 2024 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import type { TriggerInteractions } from './overlay-types.js';
+
+export class BeforetoggleClosedEvent extends Event {
+    currentState = 'open';
+    newState = 'closed';
+    constructor() {
+        super('beforetoggle', {
+            bubbles: false,
+            composed: false,
+        });
+    }
+}
+
+export class BeforetoggleOpenEvent extends Event {
+    currentState = 'closed';
+    newState = 'open';
+    constructor() {
+        super('beforetoggle', {
+            bubbles: false,
+            composed: false,
+        });
+    }
+}
+
+export class OverlayStateEvent extends Event {
+    detail!: {
+        interaction: string;
+        reason?: 'external-click';
+    };
+
+    constructor(
+        type: string,
+        public overlay: HTMLElement,
+        {
+            publish,
+            interaction,
+            reason,
+        }: {
+            publish?: boolean;
+            interaction: TriggerInteractions;
+            reason?: 'external-click';
+        }
+    ) {
+        super(type, {
+            bubbles: publish,
+            composed: publish,
+        });
+        this.detail = {
+            interaction,
+            reason,
+        };
+    }
+}

packages/overlay/src/overlay-trigger-directive.ts

@@ -17,13 +17,13 @@ import {
 } from '@spectrum-web-components/base';
 import { directive } from 'lit/async-directive.js';
 import { strategies } from './strategies.js';
-import { OverlayOptions, TriggerInteraction } from './overlay-types.js';
-import { ClickController } from './ClickController.js';
-import { HoverController } from './HoverController.js';
-import { LongpressController } from './LongpressController.js';
+import type { OverlayOptions, TriggerInteraction } from './overlay-types.js';
+import type { ClickController } from './ClickController.js';
+import type { HoverController } from './HoverController.js';
+import type { LongpressController } from './LongpressController.js';
 import {
     removeSlottableRequest,
-    SlottableRequestEvent,
+    type SlottableRequestEvent,
 } from './slottable-request-event.js';
 import { SlottableRequestDirective } from './slottable-request-directive.js';
 import { AbstractOverlay } from './AbstractOverlay.js';
@@ -47,7 +47,6 @@ export class OverlayTriggerDirective extends SlottableRequestDirective {
     protected defaultOptions: OverlayTriggerOptions = {
         triggerInteraction: 'click',
         overlayOptions: {
-            placement: 'top-start',
             type: 'auto',
             offset: 0,
         },

projects/documentation/src/components/layout.css

@@ -262,6 +262,7 @@ aside .manage-theme {
     flex-direction: column;
     display: flex;
     padding: 0px 24px 24px;
+    order: 1;
 }
 
 .scrim {
@@ -281,12 +282,12 @@ aside .theme-control {
     margin: 0 0 calc(var(--swc-scale-factor) * 24px);
 }
 
-aside.show {
+sp-underlay[open] + aside {
     transition-delay: 0ms, 0ms;
     visibility: visible;
 }
 
-aside:not(.show) {
+sp-underlay:not([open]) + aside {
     transform: translateX(100%);
     visibility: hidden;
 }