Overlay Specification

1. Revision History

Version	User	Date	Notes
0.1	Milko Venkov	May 14, 2018	Initial Draft
0.2	Plamena Miteva	May 16, 2018	Test Scenarios
0.3	Milko Venkov	May 22, 2018	Update API
0.4	Milko Venkov	May 23, 2018	Update References and API
0.5	Ivaylo Ganchev	May 29, 2018	Add Strategy Based Test Scenarios
0.6	Milko Venkov	Jun 12, 2018	Update API
0.7	Milko Venkov	Jun 14, 2018	Update scroll strategies
0.8	Milko Venkov	Jun 19, 2018	Update API and test scenarios
0.9	Milko Venkov	Jul 05, 2018	Update the specification
0.10	Milko Venkov	Aug 24, 2018	Update the limitations
0.11	Milko Venkov	Sep 13, 2018	onAnimation event added
0.12	Milko Venkov	Dec 06, 2018	Elastic positioning startegy
0.13	Milko Venkov	Feb 05, 2019	Remove caching of the element height
1.0	Milko Venkov	Feb 26, 2019	API update. Attach method added
1.1	Milko Venkov	Apr 12, 2019	Functionality section updated
1.2	Milko Venkov	Apr 17, 2019	Remove cancelable events
1.3	Milko Venkov	Sep 13, 2019	Container position strategy
1.4	Alexander Marinov	Oct 29, 2019	API update. setOffset method added
1.5	Ivaylo Ganchev	Jan 20, 2020	API update. Add onPositioned event
1.6	Milko Venkov	Jul 17, 2020	CloseOnEscpe added
1.7	Plamena Miteva	Sep 21, 2020	Move target to overlay settings
2.0	Milko Venkov	Apr 04, 2021	API update. Detach method added

2. Overview

Objectives

The igx-overlay should be able to display and position provided Component/ElementRef above all other elements.

The igx-overlay should be able to handle specific mouse and keyboard interactions.

3. User Stories

As an end user, I want

there is no end users stories as igx-overlay should be an Angular Service.

Developer Stories

As a developer, I want to

show a drop down at desired position above all other page elements
show a date picker at desired position above all other page elements
show a time picker at desired position above all other page elements
show context menu at desired position above all other page elements
show tool tip at desired position above all other page elements
show dialog at desired position above all other page elements
handle mouse scroll depending on the scroll strategy used
force an element to show at specific positions (Top, Bottom, Center and so on)
force an element to show at specific position related to an anchor element (Top, Bottom, Left, Right and so on)
force the overlay to be or not in modal state
show an element positioned globally into outlet element

4. Functionality

In order to show any content in igx-overlay developer should provide igx-overlay service as dependency injection. Then developer should call attach method of the igx-overlay instance. This will generate unique id. attach method accepts ElementRef/Component and OverlaySettings. When Component is provided igx-overlay will create the component trough ComponentFactoryResolver. Then igx-overlay will take the ElementRef of created component and will use it when should show its content. In both cases the content will be shown depending on the provided OverlaySettings. If OverlaySettings are not provided default ones will be used. With the id in hand developer may call show method of the igx-overlay instance. show method will take the nativeElement of the ElementRef and will show it. After the content is shown in the overlay developer may reposition the content by calling reposition method. Then developer may hide the content by calling hide method. If several overlays are shown developer may hide all of them by calling hideAll method. At this point developer may call show and hide and same instance of the overlay will be shown. Finally developer may call detach method to remove the overlay instance. If several overlays are shown developer may remove all of them by calling detachAll method.

The way content will be shown in the overlay depends on the provided OverlaySettings. Here is how each setting affects the overlay:

closeOnOutsideClick - this is a boolean property with default value true. When set to true if user clicks outside of the content shown in the overlay, the overlay will close itself. When set to false outside clicks will have no effect.
closeOnEscape - this is a boolean property with the default value of false. When it is set to true, if the user presses the Esc key, the last opened overlay will attempt to close and if the onClosing event is not canceled, it will close. This behavior remains the same no matter if the overlay is modal or not. Note: only the last open overlay will close. If several overlays were open pressing of Esc key will not close the other overlay until close animation of the first overlay is over.
modal - this is boolean property with default value true. When set to true igx-overlay will draw dimmed layer over the entire screen and behind the shown content. igx-overlay will also prevent all possible interaction with all the elements on the screen, but content shown in the overlay. Note: when set to true and closeOnOutsideClick is set to false developer should provide a way to the end user to close the overlay via interaction with shown content. When set to false the page content will remain interactable.
outlet - this is a property of IgxOverlayOutletDirective or ElementRef type. By default outlet is undefined. When overlay is shown it attaches its main element as last child of the document's body. If outlet is provided igx-overlay will attach the overlay as last child of provided outlet's nativeElement.
target - this property is of HTMLElement or Point type. It determines the place where the shown content will be attached to. This property has no effect when GlobalPositionStrategy is used;
positionStrategy - this is property of IPositionStrategy type. By default positionStrategy is set to GlobalPositionStrategy. Position strategy determines how shown in overlay content will be positioned on the screen. There are five positioning strategies:
- GlobalPositionStrategy - positions the content based on directions provided in PositionSettings. The content may be shown to the left, center or right in horizontal direction, and to the top, middle and bottom in vertical direction. By default the content is shown centered on the screen;
- ContainerPositionStrategy - positions the content as GlobalPositionStrategy. Instead of position related to the screen ContainerPositionStrategy positions the content related to the provided in OverlaySettings outlet.
- ConnectedPositioningStrategy - positions the content related to provided HTMLElement or screen point provided in PositionSettings. The content is shown in direction also provided in PositionSettings. By default the content is shown starting from the bottom left point of provided target in bottom right direction. If target is not provided content is shown starting from top left corner of the screen;
- AutoPositionStrategy - positions the content as ConnectedPositioningStrategy. If content does not fit on the screen tries to fit it. Initially it will try to flip the content, e.g. if direction is set to right it will try to show the content to the left. If after the flip the content is still out of the screen igx-overlay will try to push the content on the screen by translating it. If push does not succeed, e.g. content is wider/taller than the screen, igx-overlay will show the content starting from the left/top border of the screen;
- ElasticPositionStrategy - positions the content as ConnectedPositioningStrategy. If the content does not fit on the screen igx-overlay will try to fit it by reducing the content's wrapper size. The size of reduction is limited by the minSize provided in PositionSettings.
Each position strategy accepts PositionSettings parameter when is initialized and also expose setting property of PositionSettings type. PositionSettings determines how position strategy will position overlay's content. These are all the properties of PositionSettings:
- horizontalDirection and verticalDirection - these properties are of HorizontalAlignment/VerticalAlignment type. These properties determines the direction in which the content will be shown. When GlobalPositionStrategy is used these properties determines location of the content related to the screen. When ContainerPositionStrategy is used these properties determines location of the content related to the provided in OverlaySettings outlet.
- horizontalStartPoint and verticalStartPoint - these properties are of HorizontalAlignment/VerticalAlignment type. These properties determines the starting point of the target related to which the content will be shown. These properties has no effect when GlobalPositionStrategy or ContainerPositionStrategy are used, as well as when target is Point.
- openAnimation and closeAnimation - these properties are of AnimationReferenceMetadata type. When provided they determine whit what animation the content will be shown/hidden.
- minSize - this property is of Size type. It has effect only when ElasticPositionStrategy is used. This property determines the minimum size the shown content can be reduced to.
scrollStrategy - this is a property of IScrollStrategy type. By default it is set to NoOpScrollStrategy. Scroll strategy determines how overlay will react to scrolling. There are four scroll strategies:
- NoOpScrollStrategy - this scroll strategy does nothing. If end user scrolls the page overlay will not react and will stay in place;
- BlockScrollStrategy - this scroll strategy will prevent any scrolling on the page. If end user tries to scroll nothing will happen;
- CloseScrollStrategy - this scroll strategy will close the overlay if a tolerance is exceeded. If end user scrolls the scrollContainer (document.body by default) the overlay will close;
- AbsoluteScrollStrategy - this scroll strategy will scroll the page content together with content shown in the overlay. If end user scrolls the scrollContainer (document.body by default) the overlay content will reposition together with page content.

When showing content in the overlay several events will fire. Here is when each of them happens:

onOpening - fires just before the content is shown on the screen and before opening animation, if any, starts.
onOpened - fires after content is shown on the screen. If opening animation is provided this event will fire after animation is over.
onClosing - fires just before the content starts to hide from the screen and before closing animation, if any, starts.
onClosed - fires after content is completely hidden from the screen. If closing animation is provided this event will fire after animation is over.
onAnimation - fires before open or close animation starts.

4.1. End User Experience

4.2. Developer Experience

Developers are able to show a Component or ElementRef at desired position.

4.3. API

Properties

IPositionStrategy

Name	Description	Type
positionSettings	Settings to apply to this position strategy	PositionSettings

OverlaySettings

Name	Description	Type
target	Attaching target for the component to show	Point
positionStrategy	Position strategy to use with this settings	IPositionStrategy
scrollStrategy	Scroll strategy to use with this settings	IScrollStrategy
modal	Set if the overlay should be in modal mode	boolean
closeOnOutsideClick	Set if the overlay should closed on outside click	boolean
closeOnEscape	Set if the overlay should closed on Esc key press	boolean
outlet	IgxOverlayOutletDirective or ElementRef	Set the outlet container to attach the overlay to

PositionSettings

Name	Description	Type
horizontalDirection	Direction in which the component should show	HorizontalAlignment
verticalDirection	Direction in which the component should show	VerticalAlignment
horizontalStartPoint	Target's starting point	HorizontalAlignment
verticalStartPoint	Target's starting point	VerticalAlignment
openAnimation	Animation applied while overlay opens	AnimationReferenceMetadata
closeAnimation	Animation applied while overlay closes	AnimationReferenceMetadata
minSize	The size up to which element could be reduced	Size

Methods

IgxOverlayService

Name	Description	Parameters
attach	Generates Id. Provide this Id when call `show(id, settings?)` method	element, overlaySettings?
attach	Generates Id. Provide this Id when call `show(id, settings?)` method	component, overlaySettings?, moduleRef?
show	Shows the overlay for provided id	id
hide	Hides the overlay for provided id	id
hideAll	Hides all overlays	-
detach	Remove the provided native element of for the component with provided id	id
detachAll	Remove the all native elements	-
reposition	Repositions the native element of the component with provided id	id
setOffset	Repositions the component in the horizontal and/or vertical directions.	id, deltaX, deltaY

IPositionStrategy

Name	Description	Parameters
position	Positions provided element	element, size?, document?, initialCall? target?

IScrollStrategy

Name	Description	Parameters
initialize	Initialize the strategy. Should be called once	document, overlayService, id
attach	Attaches the strategy	-
detach	Detaches the strategy	-

static methods

Name	Description	Parameters
getPointFromPositionsSettings	Calculates the point from which the overlay should start showing	settings
createAbsoluteOverlaySettings	Creates overlay settings with global or container position strategy based on a preset position settings	position?, outlet?
createRelativeOverlaySettings	Creates overlay settings with auto, connected or elastic position strategy based on a preset position settings	target, strategy?, position?

Events

IgxOverlayService

Name	Description	Cancelable
onOpening	Emitted before overlay shows	true
onOpened	Emitted after overlay shows	false
onClosing	Emitted before overlay hides	true
onClosed	Emitted after overlay hides	false
onAnimation	Emitted before animation is started	false

5. Assumptions and Limitations

If you show the overlay in an outlet, and if the outlet is child of element with transform, perspective or filter css set you will not be able to show modal overlay. The reason for this is when one of above mentioned css properties is set the browser creates a new containing block and the overlay is limited to this containing block, as described here.

If you need to set scroll position of shown component you can achieve this in onOpening event. However, if you use ElasticPositionStrategy shown component could be resized and as a result scroll position will be incorrect.

If you try to show element with height set to 100%, the element will shrink its height to its content. If you need to retain element height and set height to 100% you need to set also min-height to some reasonable value.

6. Test Scenarios

Automated

Test with several different fixed window sizes.

I. Positioning Strategy

GlobalPositioningStrategy (show components, by default, in the window center).

igx-overlay is rendered on top of all other views/components (any previously existing html on the page) etc.
igx-overlay covers the whole window 100% width and height.
The shown component is inside the content div, which is inside wrapper div as a last child.
The shown component, by default, is in the center of igx-overlay (visible window).
When adding more than one component to show in igx-overlay:
- When adding a new instance of a component with the same options, it is rendered exactly on top of the previous one.
- When adding a component near the visible window borders (left, right, up, down), it should be rendered, by default, in the center of igx-overlay (visible window) and no scrollbars should appear.
If the shown component is bigger than the visible window, by default it should be centered and no scrollbars should appear.

ConnectedPositioningStrategy (show components based on a specified target (point or Html element), horizontal and vertical alignment, and horizontal and vertical starting directions)

igx-overlay is rendered on top of all other views/components (any previously existing html on the page) etc.
igx-overlay covers the whole window 100% width and height.
The shown component is child element of the content div, which is inside wrapper div.
the shown component is positioned according to the options passed (target / alignment / starting position / animations).
If using a ConnectedPositioningStrategy without passing options, the omitted default to (Window top left corner shown in bottom right direction).
When adding more than one component to show in igx-overlay:
- When adding a new instance of component with the same options, it is rendered exactly on top of the previous one.
- When adding a new component it should be rendered where expected based on the options.
- When adding a component near the visible window borders (left, right, up, down) it should be partially hidden and depending on the scroll strategy used:
  - for NoOpScrollStrategy: scrolling should not be affected in any way.
  - for CloseScrollStrategy: on a scroll the component should hide.
  - for BlockScrollStrategy: it should be partially hidden. When scrolling, no scrolling should happen.
  - for AbsoluteScrollStrategy: it should be partially hidden but can scroll it into view. Component persist state. (example: expanded DropDown remains expanded).

AutoPositionStrategy (fit the shown component into the visible window.)

igx-overlay is rendered on top of all other views/components (any previously existing html on the page) etc.
igx-overlay covers the whole window 100% width and height.
The shown component is inside content div, which is inside wrapper div.
igx-overlay displays each shown component based on the options specified if the component fits into the visible window.
The component repositioned and rendered correctly in the window even when the rendering options passed should result in otherwise a partially hidden component. No scrollbars should appear.
igx-overlay margins should be rendered correctly
igx-overlay displays each shown component in the browser’s visible window and tries to fit it in case of AutoPosition.
When adding more than one component to show in igx-overlay:
- When the options used fit the component in the window - adding a new instance of the component with the same options will render it on top of the previous one.
- When the options used will not fit the component in the window and AutoPosition is used - adding a new instance of the component with the same options, will render it on top of the previous one.(For both scenarios when options used fit the component in the window and when AutoPosition is used to fit the component)
When adding a component like Menu that has a sub-menu near the visible window, upon opening the submenu, no scrollbar will appear but the submenus are rearranged in order to fit in the visible window.
If the width/height allows, the submenu should be show in the window and if not, it should be positioned in the window.

ElasticPositionStrategy (resize the shown component to fit into the visible window.)

igx-overlay is rendered on top of all other views/components (any previously existing html on the page) etc.
igx-overlay covers the whole window 100% width and height.
The shown component is inside content div, which is inside wrapper div.
igx-overlay displays each shown component based on the options specified if the component fits into the visible window.
The component repositioned and rendered correctly in the window even when the rendering options passed should result in otherwise a partially hidden component.
igx-overlay margins should be rendered correctly
igx-overlay displays each shown component in the browser’s visible window and tries to fit it in case of ElasticPosition.
When adding more than one component to show in igx-overlay:
- When the options used fit the component in the window - adding a new instance of the component with the same options will render it on top of the previous one.
- When the options used will not fit the component in the window and ElasticPosition is used - adding a new instance of the component with the same options, will render it on top of the previous one.(For both scenarios when options used fit the component in the window and when ElasticPosition is used to fit the component)
When adding a component like Menu that has a sub-menu near the visible window, upon opening the submenu, no scrollbar will appear but the submenus are rearranged in order to fit in the visible window.
If the width/height allows, the submenu should be show in the window and if not, it should be positioned in the window.

ContainerPositionStrategy

The shown component, by default, is in the center of the outlet.

II. Scroll Strategy

NoOperation

Does nothing.

Block

The component do not scroll with the window. The event is canceled. No scrolling happens.
The component shown in igx-overlay do not change its state. For example, an expanded DropDown stays expanded during a scrolling attempt.

Close (Uses a tolerance and closes an expanded component upon scrolling if the tolerance is exceeded.(example: DropDown or Dialog component collapses/closes after scrolling 10px.)

Till tolerance scrolling happens.
The component shown in igx-overlay do not change its state until it exceeds the scrolling tolerance set.
The component shown in igx-overlay changes its state when it exceeds the scrolling tolerance set (an expanded DropDown, Menu, DatePicker, etc. collapses).

Absolute

Scrolls everything.
Components persist open state.

III. Interaction

Modal

When igx-overlay is set as modal, the igx-overlay applies a greyed out mask layer and interaction is allowed only for the shown component (dialog window only). This includes mouse and keyboard interactions (Tab allows changing focus only through the component shown inside igx-overlay and it’s children. PageUp/PageDown/Home/End keys do nothing. --> behavior example.
When reaching the last focusable element start from the first one again (looping).
When igx-overlay is set as not a modal, the igx-overlay do not apply a greyed out mask layer and interactions via mouse and keyboard for the window are allowed. Tab allows changing focus to other components/elements on the window which are not shown via the igx-overlay (For example, set focus on existing links).
Clicking outside the component may or may not close the overlay depending on closeOnOutSideclick settings.
Pressing Esc key may or may not close the overlay depending on closeOnEscape click settings.

IV. Keyboard interaction:

V. General:

1) Css:

All appropriate css classes should be applied on igx-overlay initialization. (“class overlay”, incl. position, width, height, etc.)
All css properties set should be actually applied.