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

1. Overview

Objectives

The igx-overlay should be able to display and position provided html element 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
be notified, when mouse scroll happens
be notified, when specific key was pressed
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
set some background color to the overlay

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

IgxOverlayService

Name	Description	Type
isModal	Determines if the overlay should be in modal mode	boolean

IPositionStrategy

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

Methods

IgxOverlayService

Name	Description	Parameters
show	Attaches provided component's native element to the overlay wrapper	component, id, positioningStrategy?, scrollStrategy?
hide	Remove the provided native element of for the component with provided id	id
hideAll	Remove the all native elements and hides the overlay	-

IPositionStrategy

Name	Description	Parameters
position	Positions provided element	element

IScrollStrategy

Name	Description	Parameters
attach	Attaches the strategy	-
detach	Detaches the strategy	-

Events

IgxOverlayService

Name	Description	Cancelable
onClick	Emitted on mouse click	false
onScroll	Emitted on mouse scroll	false
onKeyPress	Emitted on key press	false

4. Assumptions and Limitations

Up to now there are no known limitations.

5. Test Scenarios

Automated

Test with several different fixed window sizes.

I. Positioning Strategy

Center (show components 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 igx-overlay as a last child.
The shown component 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 in the center of igx-overlay (visible window) and no scrollbars should appear.
If the shown component is bigger than the visible window, than it should be centered and the corresponding scrollbars should appear.

ConnectedPositioningStrategy (show components based on a specified position base point, horizontal and vertical alignment)

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 igx-overlay as a last child.
the shown component is positioned according to the options passed (base point / Left, Center, Right / Top, Middle, Bottom).
If using a ConnectedPositioningStrategy without passing options, the omitted default to (Window center point, Center, Middle).
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 Scroll Strategy None: it should be partially hidden and no scrolling possible.
- for Scroll Strategy closingScrollStrategy: it should be partially hidden and no scrolling possible. The component changes state to closed when reaching the threshold (example: expanded DropDown collapses).
- for Scroll Strategy Fixed: it should be partially hidden. When scrolling, the component stays static. Component state remains the same (example: expanded DropDown remains expanded).
- for Scroll Strategy Absolute: it should be partially hidden but can scroll it into view. Component persist state. (example: expanded DropDown remains expanded).

AutoPosition (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 the igx-overlay as a last child.
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.

II. Scroll Strategy

NoOperation

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.

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

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

Fixed

When scrolling, the component stays static and only the background scrolls.
Component persist open state ( expanded DropDown remains expanded ).

4) Absolute

Scrolls everything.
Components persist open state.

III. Interaction

Modal

When igx-overlay is set as modal, the igx-overlay applies a greyed our 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 and Enter selects. PageUp/PageDown/Home/End keys do nothing. --> behavior example.
- When reaching the last focusable element start from the first one again (looping).
- Clicking outside the component does not change its state (Dialog).
When igx-overlay is set as not a modal, the igx-overlay do not apply a greyed our 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 it collapses/closes (DropDown, DatePicker, NavBar etc.)

IV. Keyboard interaction:

Escape - closes (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.
Css leaking: From igx-overlay to the inner components (greyed out modal).
Css leaking: From shown components to igx-overlay.