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

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 start, Top end, Bottom start, Bottom end 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 html element at desired position.

3.3. API

Properties

OverlayService

Name	Description	Type
isModal	Determines if the overlay should be in modal mode	boolean
transparancy	Determines how transparent should be the overlay	number

PositioningStrategy

Name	Description	Type
relativePosition	Absolute position where the component will be shown	RelativePosition
horizontalAlignment	Determines the horizontal alignment of the component	HorizontalAlignment
verticalAlignment	Determines the vertical alignment of the component	VerticalAlignment

RelativePosition

Name	Description	Type
left	Absolute distance in px from to the left	number
top	Absolute distance in px from to the top	number

Methods

Overlay Service

Name	Description	Parameters
showComponent	Creates an instance of the provided component, attaches it to ApplicationRef, and shows it as a child element of OverlayElement	component, positioningStrategy?
hideComponent	Remove the provided component, deattaches it from ApplicationRef, and destroys its Html elements	component, positioningStrategy?

Events

Overlay Service

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 an option, 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 Block: it should be partially hidden. When scrolling, the component stays static. Component state remains the same (example: expanded DropDown remains expanded). *for Scroll Strategy Repositioning: it should be partially hidden but can scroll it into view. Component persist state. (example: expanded DropDown remains expanded).

AutoPositin (fit the shown component into the visible window. Can set excluding rectangle )

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 taking an excluding rectangle that the strategy will provide (so it does not overlap with the main menu).

II. Scroll Strategy

None

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

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

Block

When scrolling, the component stays static and only the background scrolls.
The component state stays the same ( expanded DropDown remains expanded ).

4) Repositioning

Scrolls everything.
Components persist states (open/closed).

III. InteractionStrategy

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:

Tab – focus. Pressing Tab in the igx-overlay should have the same behavior for the shown components as if the components are outside of an igx-overlay.
Arrow Keys.

If the focus is in the igx-overlay, should scroll where scrollbars are available to scroll into view.

PageUp/PageDown/Home/End keys, should scroll where scrollbars are available to scroll into view.(based on the scroll strategy set)

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.