Overlay Specification

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. 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.

2. User Stories

As an end user, I want

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

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

3. Functionality

3.1. End User Experience

3.2. Developer Experience

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

3.3. API

Properties

IPositionStrategy

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

OverlaySettings

Name	Description	Type
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
outlet	IgxOverlayOutletDirective or ElementRef	Set the outlet container to attach the overlay to

PositionSettings

Name	Description	Type
target	Attaching target for the component to show	Point
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, overlaySettings?
hide	Remove the provided native element of for the component with provided id	id
hideAll	Remove the all native elements and hides the overlay	-
reposition	Repositions the native element of the component with provided id	id

IPositionStrategy

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

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

Events

IgxOverlayService

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

4. 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.

5. 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 contend 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 contend 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 contend 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 contend 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.

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. Esc key closes the dialog. 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 closeOnOutSide click settings.

IV. Keyboard interaction:

Escape - closes overlay if it is in modal mode and does nothing when in no modal mode (DropDown, DIalog, etc.).

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.