Dock Manager Specification

1. Revision History

Version	User	Date	Notes
0.1	Stefan Ivanov	Oct 11, 2019	Initial draft
0.2	Diyan Dimitrov	Aug 25, 2020	API spec
0.3	Diyan Dimitrov	Oct 30, 2020	Update API spec
0.4	Dimitar Dimitrov	Nov 24, 2020	Localization

2. Overview

The Dock Manager provides a framework for complex layouts splitting the view into multiple smaller ones. This can be done recursively in order to create arbitrary layouts that can be manipulated and adjusted at runtime.

3. User Stories

End User Stories

As an end user:

I want to be able to dock a pane to the left, right, top, or bottom to any level of nesting including the global/root one.
I want to split my full-screen window in left and right pane in order to compare document versions.
I want to dock a real-time log pane at the bottom of my window.
I want to dock a pane with commands and operations to the top of my window similar to the MS Office Ribbon.
I expect a visual indication (joystick) about the available positions to dock panes that is contextual to the pane over which my cursor currently is positioned.
I want to be able to maximize/minimize a pane.
I expect to be able to have multiple tabbed views for a certain pane.
I expect to be able to iterate through the tabs of a pane by pressing the Ctrl+F6/Shift+Ctrl+F6 key (Cmd to replace Ctrl on a Mac). Upon reaching the last tab of a pane pressing Ctrl+F6 would take me to the next pane. Upon reaching the first tab of a pane pressing the Shift+Ctrl+F6 would take me to the previous pane.
I expect to be able to iterate through the dock manager windows by pressing the Alt+F6/Alt+Ctrl+F6 key.
I want to be able to reorder the tabs in a pane via drag and drop.
I want to list all tabs of a pane that are not visible in a dropdown when the total amount of tabs cannot be fit in the width available.

I want to stash all the panes that I don't need at the moment in a tray.
I want to pin a docked pane, which would send it (including all the tabs it may have) to the tray for that pane.
I want to open the tray and unpin a certain pane (with all the tabs it may have) to bring it to its last docked position or float it.
I want to close a pane (docked or floating), which would remove it from the dock manager layout, including all the tabs it may have.
I want to open the tray and drag an item to a destination pane and dock it to a certain position.
I want to open/close the tray area similar to how a navigation drawer may slide in and out.
I want to be able to resize the tray by dragging its border towards the panes adjacent to it.
I expect that if I close my application and open it again, it would show the last layout I have created.
I want to be able to save my layout so that I can apply it later and use it again.
I expect that if I have a layout and load another one the panes in my current layout will be taken and docked accordingly to the newly loaded one respecting the tree structure depicting the organization of panes.
I want to move the splitting border between two panes to change their relative sizes.
I want to move the splitting border between a pane and a split-pane which will cause the window to force the resizing of its children accordingly.
When moving the splitting border causes a pane to not be able to fit its visible tabs anymore, I expect the active tab to move to the first position so that it is always visible and the tab that comes last to be removed as a tab and appear in a dropdown. On the contrary, if moving the splitting border makes more space in a pane for a tab, the last tab that got moved to the dropdown will be moved back in as a tab.

I want to take a pane and float it on top of all others.
I want to take a floating pane and drag it outside the dock manager/browser window.
I want to list all applicable actions for a pane in a dropdown that is shown from an action icon.

I want to dock a pane as a tab of another view without splitting the content area.
I expect a dialog that would list all the panes in the dock manager and let me navigate between them choosing which on to move my focus to in the end.
I want to double click a pane header in order to maximize it or restore it to its original size once maximized.
I want to double click a pane header while holding a modifier key CTRL/CMD in order to float it or dock it to its original place once floated.

Developer Stories

As a developer:

I want to define a tree structure that defines the hierarchy of my panes.
I want to define relative proportions for the area that siblings occupy from a certain pane.
I want to be able to dock panes programmatically by making changes to the tree.
I want to be able to persist the organization of panes and load it next time that the dock manager is opened.
I want to be able to exclude certain panes from the organization upon persisting it.
I want to be able to define a special content pane (document content), which would be the main one and cannot be unpinned/minimized/sent to the tray. Its tabs are positioned at the top of the window unlike panes that have tabs at the bottom
I want to be able to freeze/unfreeze tabs in the document pane via pin/unpin action icon which would keep them in view under any circumstances - if necessary multiple rows of frozen tabs will be shown with the ones not frozen filling up the available space.
I expect that it is easy to distinguish the document area from the docked panes i.e. document area has tabs at the top, while for a pane they are always rendered at the bottom.
I want to be able to unpin and pin panes programatically.
I want to be able to determine whether an action (unpin, close etc.)on a given pane affects all its child panes recursively (default) or affects just the parent and makes its former children into present siblings.
I want to be able to set a certain pane as floatable which will make it appear above all others programmatically.
I want to be able to close a certain pane programmatically persisting its state upon closing e.g. pinned/unpinned.
I want to load a set of documents each in its own tab for a certain pane.
I expect that each tab sizes according to the document name it has to display.
I expect to have a tray, which can be opened or closed and it comes out of the box.
I expect to have a suggestive layout visualization (joystick), which shows all possible docking action and it comes out of the box.
I want to be able to define allowable docking positions for a give pane, by default it can be docked in all directions.
I want to be able to freeze the arrangement of panes so that the user cannot resize or rearrange them but may only flip through the tabs in a certain pane and browse the document that it displays.
I want to be able to set a minimum width and height values for every pane of the dock manager.
I expect to be provided with a template for the tab name that by default displays only text allowing icons or images to be added to it.
I expect to be provided with a template for the pane name that by default displays only text allowing icons or images to be added to it.
I want to be able to change the language of all strings shown in context menus, tooltips, etc. and/or provide custom strings for each of them

4. Functionality

User Interface

Design Hands-Off:

Globalization/Localization

The Dock Manager component supports localizing the strings shown in the context menus, tooltips and aria attributes. By default the Dock Manager detects the language of the page by searching for a lang attribute on any of its parents. If the lang attribute is not set or is set to a value which the Dock Manager does not support, the default language used is English(en). The Dock Manager exposes resourceStrings property which allows the user to modify the strings. If the resourceStrings property is set by the user, the Dock Manager will use it no matter what lang attribute is set.

The Dock Manager provides built-in localized strings for the following languages: English(en), Japanese(jp), Korean(ko) and Spanish(es). In order to provide resource strings for another language use the addResourceStrings(language, resourceStrings) method where language is the custom string that has to be set to the lang attribute and resourceStrings is an implementation of IgcDockManagerResourceStrings containing all custom resource strings.

API

IgcDockManagerComponent

Properties

Name	Description	Type
allowMaximize	Specifies whether the end user is allowed to maximize panes. Defaults to true.	`boolean`
draggedPane	Gets/sets the currently dragged pane.	`IgcContentPane` \| `IgcSplitPane` \| `IgcTabGroupPane`
dropPosition	Gets/sets the current drop position when performing custom drag/drop.	`IgcDockManagerPoint`
layout	Gets/sets the layout configuration of the Dock Manager.	`IgcDockManagerLayout`
maximizedPane	Gets/sets the maximized pane.	`IgcContentPane` \| `IgcSplitPane` \| `IgcTabGroupPane`
resourceStrings	Gets/sets the resource strings.	`IgcDockManagerResourceStrings`

Methods

Name	Description	Return type	Parameters
dropPane	Performs drop of the `draggedPane` into the specified `dropPosition`. Returns true if the pane has been docked otherwise returns false.	`Promise<boolean>`
removePane	Removes a pane from the layout.	`Promise<void>`	pane: `IgcDockManagerPane`

Events

Name	Description	Cancelable	Type
splitterResizeStart	Raised when a splitter resizing starts	false	`CustomEvent`
splitterResizeEnd	Raised when a splitter resizing ends	false	`CustomEvent`
paneHeaderConnected	Raised when a pane header element is connected	false	`CustomEvent<IgcPaneHeaderConnectionEventArgs>`
paneHeaderDisconnected	Raised when a pane header element is disconnected	false	`CustomEvent<IgcPaneHeaderConnectionEventArgs>`
tabHeaderConnected	Raised when a tab header element is connected	false	`CustomEvent<IgcTabHeaderConnectionEventArgs>`
tabHeaderDisconnected	Raised when a tab header element is disconnected	false	`CustomEvent<IgcTabHeaderConnectionEventArgs>`
paneClose	Raised when panes are about to close	true	`CustomEvent<IgcPaneCloseEventArgs>`
paneDragStart	Raised when a pane drag starts	true	`CustomEvent<IgcPaneDragStartEventArgs>`
paneDragOver	Raised when a pane is dragged over	true	`CustomEvent<IgcPaneDragOverEventArgs>`
paneDragEnd	Raised when a pane drag ends	false	`CustomEvent<IgcPaneDragEndEventArgs>`
panePinnedToggle	Raised when panes are about to get pinned/unpinned	true	`CustomEvent<IgcPanePinnedEventArgs>`

IgcDockManagerLayout

Name	Description	Required	Type
rootPane	The root split pane of the layout.	true	`IgcSplitPane`
floatingPanes	The floating panes of the layout.	false	`IgcSplitPane[]`

IgcContentPane

Name	Description	Required	Type
id	The id of the pane. If not set the Dock Manager generates it automatically.	false	`string`
type	The type of the pane.	true	`IgcDockManagerPaneType.contentPane`
contentId	The slot attribute's value of the content element.	true	`string`
header	The text header of the content pane.	false	`string`
headerId	The slot attribute's value of the header element. If headerId is set, the header will be disregarded.	false	`string`
size	The relative size of the pane. Defaults to 100.	false	`number`
unpinnedSize	The absolute size of the pane in an unpinned state. Defaults to 200.	false	`number`
isPinned	Describes whether a content pane is pinned or not. Defaults to true.	false	`boolean`
unpinnedLocation	If not set the Dock Manager automatically calculates it based on the location of the pane relatively to the document host. If more than one document host is presented, the closest one in the pane hierarchy will be used for the calculation. If there is no document host, the default location is left.	false	`IgcUnpinnedLocation`
allowClose	Specifies whether the end user is allowed to close the pane. Defaults to true.	false	`boolean`
allowPinning	Specifies whether the end user is allowed to pin/unpin the pane. Defaults to true.	false	`boolean`
allowDocking	Specifies whether the end user is allowed to dock the pane. Defaults to true.	false	`boolean`
allowFloating	Specifies whether the end user is allowed to make the pane floating. Defaults to true.	false	`boolean`

* - Marked API members are still not implemented.

IgcSplitPane

Name	Description	Required	Type
id	The id of the pane. If not set the Dock Manager generates it automatically.	false	`string`
type	The type of the pane.	true	`IgcDockManagerPaneType.splitPane`
orientation	The slot attribute's value of the content element.	true	`IgcSplitPaneOrientation`
panes	The child panes of the split pane.	true	`IgcDockManagerPane[]`
size	The relative size of the pane. Defaults to 100.	false	`number`
floatingLocation	The absolute location point of the pane. Applies only for floating panes.	false	`IgcDockManagerPoint`
floatingWidth	The absolute width of the pane. Applies only for floating panes. Defaults to 100.	false	`number`
floatingHeight	The absolute height of the pane. Applies only for floating panes. Defaults to 100.	false	`number`

IgcTabGroupPane

Name	Description	Required	Type
id	The id of the pane. If not set the Dock Manager generates it automatically.	false	`string`
type	The type of the pane.	true	`IgcDockManagerPaneType.tabGroupPane`
panes	The child content panes of the tab group.	true	`IgcDockManagerPane[]`
size	The relative size of the pane. Defaults to 100.	false	`number`
selectedIndex	The index of the selected tab.	false	`number`

IgcDocumentHost

Name	Description	Required	Type
id	The id of the pane. If not set the Dock Manager generates it automatically.	false	`string`
type	The type of the pane.	true	`IgcDockManagerPaneType.documentHost`
rootPane	The root split pane of the document host.	true	`IgcSplitPane`
size	The relative size of the pane. Defaults to 100.	false	`number`

IgcPaneHeaderElement/IgcTabHeaderElement

Name	Description	Type
dragService	Gets/sets the drag service.	`IgcDragService`

IgcDockManagerResourceStrings

Name	Required	Type
close	false	`string`
pin	false	`string`
unpin	false	`string`
maximize	false	`string`
minimize	false	`string`
moreOptions	false	`string`

Other

Name	Description	Return type	Parameters
addResourceStrings	Adds custom resource strings.		language: `string`, resourceStrings: `IgcDockManagerResourceStrings`

Key	Result
Shift + Arrow up	With multiple tabs in a tab group splits the view and docks the focused tab above
Cmd/Ctrl + Shift + Arrow up	Dock to global top
Shift + Arrow down	With multiple tabs in a tab group splits the view and docks the focused tab below
Cmd/Ctrl + Shift + Arrow down	Dock to global bottom
Shift + Arrow right	With multiple tabs in a tab group splits the view and docks the focused tab right
Cmd/Ctrl + Shift + Arrow right	Dock to global right
Shift + Arrow left	With multiple tabs in a tab group splits the view and docks the focused tab left
Cmd/Ctrl + Shift + Arrow left	Dock to global left
Shift + Esc	Closes document/tab
Cmd/Ctrl + F6	Focus next tab in document host
Cmd/Ctrl + Shift + F6	Focus previous tab in document host
Alt + F6	Focus next content pane
Alt + Shift + F6	Focus previous content pane
Alt + F7	Show the window nav dialog