feat(overlays): align Overlays API + add DynamicOverlay

Co-authored-by: Gerjan van Geest <Gerjan.van.Geest@ing.com>
Co-authored-by: Thijs Louisse <Thijs.Louisse@ing.com>"

Author: daKmoR

packages/core/package.json

@@ -26,7 +26,7 @@
     "docs",
     "src",
     "stories",
-    "test",
+    "test-helpers",
     "translations",
     "*.js"
   ],

packages/core/src/differentKeyEventNamesShimIE.js

@@ -0,0 +1,36 @@
+if (typeof window.KeyboardEvent !== 'function') {
+  // e.g. is IE and needs "polyfill"
+  const event = KeyboardEvent.prototype;
+  const descriptor = Object.getOwnPropertyDescriptor(event, 'key');
+  if (descriptor) {
+    const keys = {
+      Win: 'Meta',
+      Scroll: 'ScrollLock',
+      Spacebar: ' ',
+
+      Down: 'ArrowDown',
+      Left: 'ArrowLeft',
+      Right: 'ArrowRight',
+      Up: 'ArrowUp',
+
+      Del: 'Delete',
+      Apps: 'ContextMenu',
+      Esc: 'Escape',
+
+      Multiply: '*',
+      Add: '+',
+      Subtract: '-',
+      Decimal: '.',
+      Divide: '/',
+    };
+    Object.defineProperty(event, 'key', {
+      // eslint-disable-next-line object-shorthand, func-names
+      get: function() {
+        const key = descriptor.get.call(this);
+
+        // eslint-disable-next-line no-prototype-builtins
+        return keys.hasOwnProperty(key) ? keys[key] : key;
+      },
+    });
+  }
+}

packages/core/test-helpers/keyboardEventShimIE.js

@@ -0,0 +1,49 @@
+if (typeof window.KeyboardEvent !== 'function') {
+  // e.g. is IE and needs "polyfill"
+  const KeyboardEvent = (event, _params) => {
+    // current spec for it https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent
+    const params = {
+      bubbles: false,
+      cancelable: false,
+      view: document.defaultView,
+      key: false,
+      location: false,
+      ctrlKey: false,
+      shiftKey: false,
+      altKey: false,
+      metaKey: false,
+      repeat: false,
+      ..._params,
+    };
+    const modifiersListArray = [];
+    if (params.ctrlKey) {
+      modifiersListArray.push('Control');
+    }
+    if (params.shiftKey) {
+      modifiersListArray.push('Shift');
+    }
+    if (params.altKey) {
+      modifiersListArray.push('Alt');
+    }
+    if (params.metaKey) {
+      modifiersListArray.push('Meta');
+    }
+
+    const ev = document.createEvent('KeyboardEvent');
+    // IE Spec for it https://technet.microsoft.com/en-us/windows/ff975297(v=vs.60)
+    ev.initKeyboardEvent(
+      event,
+      params.bubbles,
+      params.cancelable,
+      params.view,
+      params.key,
+      params.location,
+      modifiersListArray.join(' '),
+      params.repeat ? 1 : 0,
+      params.locale,
+    );
+    return ev;
+  };
+  KeyboardEvent.prototype = window.Event.prototype;
+  window.KeyboardEvent = KeyboardEvent;
+}

packages/overlays/README.md

@@ -8,7 +8,7 @@ Manages their position on the screen relative to other elements, including other
 ## Features
 
 - [**Overlays Manager**](./docs/OverlaysManager.md), a global repository keeping track of all different types of overlays.
-- [**Overlays Occurrences**](./docs/OverlayOccurrences.md), outline of all possible occurrences of overlays. Divided into two main types:
+- [**Overlays System: Scope**](./docs/OverlaySystemScope.md), outline of all possible occurrences of overlays. Divided into two main types:
   - [**Global Overlay Controller**](./docs/GlobalOverlayController.md), controller for overlays relative to the viewport.
   - [**Local Overlay Controller**](./docs/LocalOverlayController.md), controller for overlays positioned next to invokers they are related to.
 

packages/overlays/docs/GlobalOverlayController.md

@@ -1,7 +1,8 @@
 # GlobalOverlayController
 
-This is a base class for different global overlays (e.g. a dialog, see [Overlay Occurrences](./OverlayOccurrences.md) - the ones positioned relatively to the viewport.
-You should not use this controller directly unless you want to create a unique type of global overlays which is not supported out of the box.
+This is a base class for different global overlays (e.g. a dialog, see [Overlay System: Scope](./OverlaySystemScope.md) - the ones positioned relatively to the viewport).
+
+You should not use this controller directly unless you want to create a unique type of global overlays which is not supported out of the box. But for implementation details check out [Overlay System: Implementation](./OverlaySystemImplementation.md).
 
 All supported types of global overlays are described below.
 

packages/overlays/docs/LocalOverlayController.md

@@ -1,7 +1,10 @@
 # LocalOverlayController
 
-This is a base class for different local overlays (e.g. a [tooltip](../../tooltip/), see [Overlay System Implementation](./OverlaySystemImplementation.md) - the ones positioned next to invokers they are related to. For more information strictly about the positioning of the content element to the reference element (invoker), please refer to the [positioning documentation](./LocalOverlayPositioning.md)
-You should not use this controller directly unless you want to create a unique type of local overlays which is not supported out of the box.
+This is a base class for different local overlays (e.g. a [tooltip](../../tooltip/), see [Overlay System: Scope](./OverlaySystemScope.md) - the ones positioned next to invokers they are related to).
+
+For more information strictly about the positioning of the content element to the reference element (invoker), please refer to the [positioning documentation](./LocalOverlayPositioning.md).
+
+You should not use this controller directly unless you want to create a unique type of local overlays which is not supported out of the box. But for implementation details check out [Overlay System: Implementation](./OverlaySystemImplementation.md).
 
 All supported types of local overlays are described below.
 

packages/overlays/docs/OverlaySystemImplementation.md

@@ -1,142 +1,115 @@
 # Overlay System: Implementation
 
-This document provides an outline of all possible occurrences of overlays found in applications in
-general and thus provided by Lion.
-For all concepts referred to in this document, please read [Overlay System Scope](./OverlaySystemScope.md).
+This document provides an outline of all possible occurrences of overlays found in applications in general and thus provided by Lion. For all concepts referred to in this document, please read [Overlay System Scope](./OverlaySystemScope.md).
 
-## Local and global overlay controllers
-
-Currently, we have a global and a local overlay controller, as two separate entities.
-Based on provided config, they handle all positioning logic, accessibility and interaction patterns.
-All of their configuration options will be described below as part of the _Responsive overlay_ section.
+## Base controller
 
-### Connection points and placement contexts
+The BaseController handles the basics of all controllers, and has the following public functions:
 
-It's currently not clear where the border between global and local overlays lie. They seem to be
-separated based on their 'dom connection point' (body vs 'page cursor'(usually invoker sibling)).
-However, there is no required relationship here: we can create a modal dialog from
-local context('page cursor') as well.
+- **show()**, to show the overlay.
+- **hide()**, to hide the overlay.
+- **toggle()**, to toggle between show and hide.
 
-Only, we would have a few concerns when creating global overlays from a local connection point:
+All overlays exists of an invoker and a content
 
-- Accessibility will be harder to implement. When wai-aria 1.0 needs to be supported, all siblings
-  need to have aria-hidden="true" and all parents role="presentation". Not always straightforward
-  in shadow dom. If we only need to support wai-aria 1.1, we could use aria-modal="true" on the
-  element with role="dialog". (we basically need to test our supported browsers and screen readers
-  for compatibility with aria-modal).
-- Stacking context need to be managed: the whole 'z-index chain' should win (it's a battle between
-  parents in the hierarchy). This would require some complex code to cover all edge cases.
-- Side effects of parents adding transforms or clipping become a risk. This is hard to detect and
-  'counter'.
+- **invoker**, the element that can trigger showing (and hiding) the overlay.
+  - invokerNode
+- **content**, the toggleable overlays content
+  - contentTemplate, in most cases the content will be placed inside a template as one of the controller configuration options.
+  - contentNode, a node can also be used as the content for local overlays (see next section), such as is done in the [popup](../../popup/).
 
-When the dom connection point is 'body', content projection will not work, but a template that
-can be rendered without being dependent on its context will be required.
+## Local and global overlay controllers
 
-There usually also is a correllation with their relative positioning context: invoker/other
-relative element for local(tooltip/popover/dropdown) vs. 'window/viewport level' for global
-(dialog/toast/sheet).
+Currently, we have a global and a local overlay controller, as two separate entities.
+Based on provided config, they handle all positioning logic, accessibility and interaction patterns.
 
-For responsive overlays (see below for an elaborate explanation), we need to switch from global to
-local. When we switch the dom connection point, (think of rotating a mobile or tablet), we
-will loose the current focus, which can be an a11y concern. This can eventually be 'catched' by
-syncing the activeElement (we would only loose the screenreader active element (for instance,
-focused cell in table mode))
+- [GlobalOverlayController](./GlobalOverlayController.md), the ones positioned relatively to the viewport.
+- [LocalOverlayController](./LocalOverlayController.md), the ones positioned next to invokers they are related to.
 
-For maximum flexibility, it should be up to the developer to decide how overlays should be rendered,
-per instance of an overlay.
+All of their configuration options will be described below as part of the _Configuration options_ section.
 
-### Responsive overlay
+### DynamicOverlayController
 
 Based on screen size, we might want to switch the appearance of an overlay.
 For instance: an application menu can be displayed as a dropdown on desktop,
 but as a bottom sheet on mobile.
-Similarly, a dialog can be displayed as a popover on desktop, but as a (global) dialog on mobile.
 
-To implement such a flexible overlay, we need an 'umbrella' layer that allows for switching between
-different configuration options, also between the connection point in dom (global and local).
+Similarly, a dialog can be displayed as a popover on desktop, but as a (global) dialog on mobile.
 
-Luckily, interfaces of Global and OverlayControllers are very similar.
-Therefore we can make a wrapping ResponsiveOverlayController.
+The DynamicOverlayController is a flexible overlay that can switch between different controllers, also between the connection point in dom (global and local). The switch is only done when the overlay is closed, so the focus isn't lost while switching from one overlay to another.
 
-### Configuration options for local and global overlays
+### Configuration options
 
 In total, we should end up with configuration options as depicted below, for all possible overlays.
 All boolean flags default to 'false'.
-Some options are mutually exclusive, in which case their dependent options and requirement will be
-mentioned.
-Note: a more generic and precise term for all mentionings of `invoker` below would actually be
-`relative positioning element`.
+Some options are mutually exclusive, in which case their dependent options and requirement will be mentioned.
+
+> Note: a more generic and precise term for all mentionings of `invoker` below would actually be `relative positioning element`.
+
+#### Shared configuration options
 
 ```text
-- {Element} elementToFocusAfterHide - the element that should be called `.focus()` on after dialog closes
-- {Boolean} hasBackdrop - whether it should have a backdrop (currently exclusive to globalOverlayController)
-- {Boolean} isBlocking - hides other overlays when mutiple are opened (currently exclusive to globalOverlayController)
-- {Boolean} preventsScroll - prevents scrolling body content when overlay opened (currently exclusive to globalOverlayController)
-- {Boolean} trapsKeyboardFocus - rotates tab, implicitly set when 'isModal'
-- {Boolean} hidesOnEsc - hides the overlay when pressing [esc]
-- {Boolean} hidesOnOutsideClick - hides the overlay when clicking next to it, exluding invoker. (currently exclusive to localOverlayController)
-- {String} cssPosition - 'absolute' or 'fixed'. TODO: choose name that cannot be mistaken for placement like cssPosition or positioningTechnique: https://github.com/ing-bank/lion/pull/61
-- {TemplateResult} contentTemplate
-- {TemplateResult} invokerTemplate (currently exclusive to LocalOverlayController)
-- {Element} invokerNode (currently exclusive to LocalOverlayController)
-- {Element} contentNode (currently exclusive to LocalOverlayController)
+- {Boolean} trapsKeyboardFocus - rotates tab, implicitly set when 'isModal'.
+- {Boolean} hidesOnEsc - hides the overlay when pressing [esc].
 ```
 
-These options are suggested to be added to the current ones:
+#### Global specific configuration options
 
 ```text
-- {Boolean} isModal - sets aria-modal and/or aria-hidden="true" on siblings
-- {Boolean} isGlobal - determines the connection point in DOM (body vs handled by user) TODO: rename to renderToBody?
-- {Boolean} isTooltip - has a totally different interaction - and accessibility pattern from all
-other overlays, so needed for internals.
+- {Element} elementToFocusAfterHide - the element that should be called `.focus()` on after dialog closes.
+- {Boolean} hasBackdrop - whether it should have a backdrop.
+- {Boolean} isBlocking - hides other overlays when multiple are opened.
+- {Boolean} preventsScroll - prevents scrolling body content when overlay opened.
+- {Object} viewportConfig
+  - {String} placement: 'top-left' | 'top' | 'top-right' | 'right' | 'bottom-left' |'bottom' |'bottom-right' |'left' | 'center'
+```
+
+#### Local specific configuration options
+
+```text
+- {Boolean} hidesOnOutsideClick - hides the overlay when clicking next to it, excluding invoker.
+- {String} cssPosition - 'absolute' or 'fixed'. TODO: choose name that cannot be mistaken for placement like cssPosition or positioningTechnique: <https://github.com/ing-bank/lion/pull/61>.
+- For positioning checkout [localOverlayPositioning](./localOverlayPositioning.md).
+```
+
+#### Suggested additions
+
+```text
+- {Boolean} isModal - sets [aria-modal] and/or [aria-hidden="true"] on siblings
+- {Boolean} isTooltip - has a totally different interaction - and accessibility pattern from all other overlays, so needed for internals.
 - {Boolean} handlesUserInteraction - sets toggle on click, or hover when `isTooltip`
 - {Boolean} handlesAccessibility -
   - For non `isTooltip`:
-    - sets aria-expanded="true/false" and aria-haspopup="true" on invokerNode
-    - sets aria-controls on invokerNode
+    - sets [aria-expanded="true/false"] and [aria-haspopup="true"] on invokerNode
+    - sets [aria-controls] on invokerNode
     - returns focus to invokerNode on hide
     - sets focus to overlay content(?)
   - For `isTooltip`:
-    - sets role="tooltip" and aria-labelledby/aria-describedby on the content
-- {Object} popperConfig
-  - {String} placement - vertical/horizontal position to be supplied to `managePosition`. See https://github.com/ing-bank/lion/pull/61 for current api. Consists of a primary part (where the overlay is located relative from invoker) and secondary alignnment part (how the overlay 'snaps' to the perpendicular boundary of the invoker), separated via '-'.
-    - primary : 'bottom' | 'top' | 'left' | 'right' | 'over' (this means the overlay will be positioned on top of the invoker. Think for instance of a select dropdown that opens a selected option on top of the invoker (default behavior of `<select>` on iOS))
-    - secondary : 'start' | 'end' | 'fill' (occupies width of invoker) | 'middle' (implicit option that will be choosen by default when none of the previous are specified)
-  - all other configuration as described by [Popper.js](https://popper.js.org/)
+    - sets [role="tooltip"] and [aria-labelledby]/[aria-describedby] on the content
 ```
 
-What we should think about more properly is a global placement option (positioned relative to window instead of invoker)
-
-```text
-// TODO: namings very much under construction (we should also reconsider 'placement' names, see: https://github.com/ing-bank/lion/pull/61)
-// Something like the drawing Joren made: https://github.com/ing-bank/lion/issues/36#issuecomment-491855381
-- {String} viewportPlacement - consists of a vertical alignment part and an horizontal alignment part,
-  separated via '-'
-  - vertical align : 'center' | 'bottom' | 'top' | 'left' | 'right' | 'fullheight'
-  - horizontal align: 'middle' | 'start' | 'end' | 'fullwidth'
-  Examples: 'center-middle' (dialog, alertdialog), 'top-fullwidth' (top sheet)
-```
-
-## Controllers/behaviors
+## Specific Controllers
 
 Controllers/behaviors provide preconfigured configuration objects for the global/local
 overlay controllers.
+
 They provide an imperative and very flexible api for creating overlays and should be used by
 Subclassers, inside webcomponents.
 
 ### Dialog Controller
 
 ```js
 {
-  isGlobal: true,
   isModal: true,
   hasBackdrop: true,
   preventsScroll: true,
   trapsKeyboardFocus: true,
   hidesOnEsc: true,
   handlesUserInteraction: true,
   handlesAccessibility: true,
-  viewportPlacement: 'center-middle',
+  viewportConfig: {
+    placement: 'center',
+  },
 }
 ```
 
@@ -181,17 +154,18 @@ TODO:
 
 ```js
 {
-  ...Dialog,
-  viewportPlacement: 'top-right', (?)
-}
+  viewportconfig: {
+    placement: 'top-right',
+},
 ```
 
-### Sheet Controller (bottom, top, left, right)
+### Bottomsheet Controller
 
 ```js
 {
-  ...Dialog,
-  viewportPlacement: '{top|bottom|left|right}-fullwidth', (?)
+  viewportConfig: {
+    placement: 'bottom',
+  },
 }
 ```
 
@@ -212,11 +186,9 @@ config based on media query from Dropdown to BottomSheet/CenteredDialog
 
 ## Web components
 
-Web components provide a declaritive, developer friendly interface with a prewconfigured styling
-that fits the Design System and makes it really easy for Application Developers to build
-user interfaces.
-Web components should use
-The ground layers for the webcomponents in Lion are the following:
+Web components provide a declarative, developer friendly interface with a preconfigured styling that fits the Design System and makes it really easy for Application Developers to build user interfaces.
+
+Web components should use the ground layers for the webcomponents in Lion are the following:
 
 ### Dialog Component
 
@@ -242,7 +214,7 @@ Imperative might be better here? We can add a web component later if needed.
 
 ### Dropdown Component
 
-Like the name suggests, the default placement will be button
+Like the name suggests, the default placement will be bottom
 
 ```html
 <lion-dropdown>
@@ -267,6 +239,6 @@ Imperative might be better here?
 
 ### Select, Combobox/autocomplete, Application menu
 
-Those will be separate web components with a lot of form and a11y logic that will be described
-in detail in different sections.
-They will imoplement the Overlay configuration as described above under 'Controllers/behaviors'.
+Those will be separate web components with a lot of form and a11y logic that will be described in detail in different sections.
+
+They will implement the Overlay configuration as described above under 'Controllers/behaviors'.

packages/overlays/docs/OverlaysManager.md

@@ -0,0 +1,5 @@
+# Overlay Manager
+
+An overlay manager is a global repository keeping track of all different types of overlays. The need for a global housekeeping mainly arises when multiple overlays are opened simultaneously.
+
+The overlay manager keeps track of all registered overlays and controls which one to show.