Merge pull request #568 from ing-bank/chore/fix-demos-overlays

chore(overlays): fix demos

packages/overlays/README.md

@@ -1,4 +1,4 @@
-# Overlays System
+# Overlay System
 
 [//]: # 'AUTO INSERT HEADER PREPUBLISH'
 
@@ -6,9 +6,10 @@ Supports different types of overlays like dialogs, toasts, tooltips, dropdown, e
 
 Manages their position on the screen relative to other elements, including other overlays.
 
-Exports `lion-overlay`, which is a generic component wrapping OverlayController.
 Its purpose is to make it easy to use our Overlay System declaratively. It can be easily extended where needed, to override event listeners and more.
 
+See [lion-dialog](../dialog) and [lion-tooltip](../tooltip) for example Web Component implementations using the Overlay System.
+
 ## Features
 
 - lion-overlay web component:
@@ -22,19 +23,21 @@ Its purpose is to make it easy to use our Overlay System declaratively. It can b
 
 ## How to use
 
+Usually you will use `lion-dialog` (or `lion-tooltip` if this makes more sense).
+
 ### Installation
 
 ```sh
-npm i --save @lion/overlays
+npm i --save @lion/dialog
 ```
 
 ### Example
 
 ```js
-import '@lion/overlays/lion-overlay.js';
+import '@lion/dialog/lion-dialog.js';
 
 html`
-  <lion-overlay .config=${{
+  <lion-dialog .config=${{
     placementMode: 'global',
     viewportConfig: { placement: 'bottom-right' },
   }}>
@@ -47,12 +50,16 @@ html`
     <button slot="invoker">
       Click me
     </button>
-  </lion-overlay>
+  </lion-dialog>
 `;
 ```
 
 Or by creating a controller yourself
 
+```sh
+npm i --save @lion/overlays
+```
+
 ```js
 import { OverlayController } from '@lion/overlays';
 
@@ -63,9 +70,51 @@ const ctrl = new OverlayController({
 });
 ```
 
+Or creating your own Web Component which uses the Overlay System
+
+```js
+import { LitElement } from '@lion/core';
+import { OverlayMixin, withModalDialogConfig } from '@lion/overlays';
+
+class MyOverlayComponent extends LitElement {
+  _defineOverlayConfig() {
+    return {
+      ...withModalDialogConfig,
+    };
+  }
+
+  _setupOpenCloseListeners() {
+    super._setupOpenCloseListeners();
+    this.__toggle = () => {
+      this.opened = !this.opened;
+    };
+
+    if (this._overlayInvokerNode) {
+      this._overlayInvokerNode.addEventListener('click', this.__toggle);
+    }
+  }
+
+  _teardownOpenCloseListeners() {
+    super._teardownOpenCloseListeners();
+
+    if (this._overlayInvokerNode) {
+      this._overlayInvokerNode.removeEventListener('click', this.__toggle);
+    }
+  }
+
+  render() {
+    return html`
+      <slot name="invoker"></slot>
+      <slot name="content"></slot>
+      <slot name="_overlay-shadow-outlet"></slot>
+    `;
+  }
+}
+```
+
 ## Rationales
 
-For rationales, please check the [docs](./docs) folder, where we go more in-depth.
+For rationales, please check the [docs](./docs) folder, where we go more in-depth. Or check out the Storybook demos which also contains more info.
 
 ### Aria roles
 

packages/overlays/stories/20-index.stories.mdx

@@ -7,7 +7,7 @@ import {
 } from '../index.js';
 
 import './demo-overlay-system.js';
-import './applyDemoOverlayStyles.js';1
+import './applyDemoOverlayStyles.js';
 import { ref as r } from './directives/ref.js';
 
 <Meta title="Overlays/System/Overview" parameters={{ component: 'demo-overlay-system' }} />
@@ -119,7 +119,15 @@ const ctrl = new OverlayController({
 });
 ```
 
-or in your Web Component with `OverlayMixin`
+or in your Web Component with `OverlayMixin`, make sure you override these methods to:
+
+- Define configuration
+- Handle setting up event listeners of toggling the opened state of your overlay
+- Handle the tearing down of those event listeners
+- Define a template which includes
+  - invoker slot for your user to provide the invoker node (the element that invokes the overlay content)
+  - content slot for your user to provide the content that shows when the overlay is opened
+  - _overlay-shadow-outlet, this slot is currently necessary under the hood for acting as a wrapper element for placement purposes, but is not something your end user should be concerned with, unless they are extending your component.
 
 ```js
 _defineOverlayConfig() {
@@ -127,6 +135,33 @@ _defineOverlayConfig() {
     ...withModalDialogConfig
   };
 }
+
+_setupOpenCloseListeners() {
+  super._setupOpenCloseListeners();
+  this.__toggle = () => {
+    this.opened = !this.opened;
+  };
+
+  if (this._overlayInvokerNode) {
+    this._overlayInvokerNode.addEventListener('click', this.__toggle);
+  }
+}
+
+_teardownOpenCloseListeners() {
+  super._teardownOpenCloseListeners();
+
+  if (this._overlayInvokerNode) {
+    this._overlayInvokerNode.removeEventListener('click', this.__toggle);
+  }
+}
+
+render() {
+  return html`
+    <slot name="invoker"></slot>
+    <slot name="content"></slot>
+    <slot name="_overlay-shadow-outlet"></slot>
+  `;
+}
 ```
 
 or declaratively in your template with the `.config` property

yarn.lock

@@ -8936,20 +8936,13 @@ listr@^0.14.2:
     p-map "^2.0.0"
     rxjs "^6.3.3"
 
-lit-element@^2.0.1:
+lit-element@^2.0.1, lit-element@^2.2.1:
   version "2.2.1"
   resolved "https://registry.yarnpkg.com/lit-element/-/lit-element-2.2.1.tgz#79c94d8cfdc2d73b245656e37991bd1e4811d96f"
   integrity sha512-ipDcgQ1EpW6Va2Z6dWm79jYdimVepO5GL0eYkZrFvdr0OD/1N260Q9DH+K5HXHFrRoC7dOg+ZpED2XE0TgGdXw==
   dependencies:
     lit-html "^1.0.0"
 
-lit-element@~2.1.0:
-  version "2.1.0"
-  resolved "https://registry.yarnpkg.com/lit-element/-/lit-element-2.1.0.tgz#85bc3f1da0227f4b13de8a1be978229b9fa327e9"
-  integrity sha512-0z/KHm1xZweivfOVRr8AKR06+D3k02u15m9s4jkuRdnGe5wfmEwePzrQQBsSZNILdnfJvfo3TJOeGhBCVZaPbw==
-  dependencies:
-    lit-html "^1.0.0"
-
 lit-html@^1.0.0:
   version "1.1.2"
   resolved "https://registry.yarnpkg.com/lit-html/-/lit-html-1.1.2.tgz#2e3560a7075210243649c888ad738eaf0daa8374"