Skip to content

Dock Manager Specification

Ivaylo Barakov edited this page Sep 12, 2023 · 9 revisions

Dock Manager Specification

Contents

  1. Revision History
  2. Overview
  3. User Stories
    1. End User Experience
    2. Developer Experience
  4. Functionality
    1. User Interface
    2. Globalization/Localization
    3. Navigation
    4. API
  5. Acceptance criteria
  6. Accessibility
  7. Internationalization
  8. Assumptions and Limitations
  9. Test Scenarios
  10. References
  • Konstantin Dinev | Date:
  • Radoslav Mirchev | Date:
  • Svilen Dimchevski | Date:
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
0.5 Diyan Dimitrov Aug 11, 2021 CSS Parts
0.5 Ivaylo Barakov Aug 30, 2023 Moved spec from igniteui
0.6 Ivaylo Barakov Sep 12, 2023 Update API section

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.

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.

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

Design Hands-Off:

Handoff for Navigator

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.

IgcDockManagerComponent

Properties
Name Description Type
activePane Gets/sets the active pane of the Dock Manager. IgcContentPane
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
allowFloatingPanesResize Determines whether the end user is allowed to resize floating panes. Defaults to true. boolean
containedInBoundaries Determines whether the floating panes are kept inside the Dock Manager boundaries. Defaults to false. boolean
showHeaderIconOnHover Determines which tab header icons should show when hovering over the tab with the mouse. Defaults to undefined. closeOnly | moreOptionsOnly | all
showPaneHeaders Determines whether pane headers are only shown on hover or always visible. Defaults to 'always'. onHoverOnly | always
disableKeyboardNavigation Disables the built-in keyboard shortcuts for pane navigation. Defaults to false. boolean
allowInnerDock Determines whether the end user is allowed to inner dock panes. Defaults to true. boolean
proximityDock Determines whether the end user can dock the dragged pane by dragging it close to the target pane edges. If enabled, docking indicators are not visible. Defaults to false. boolean
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
focusPane Focuses a pane from the layout. Promise<void> contentId: string
Events
Name Description Cancelable Type
splitterResizeStart Raised when a splitter resizing starts false CustomEvent
splitterResizeEnd Raised when a splitter resizing ends false CustomEvent
layoutChange Raised when the layout updates true 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>
paneScroll Raised when pane is scrolled. true CustomEvent<IgcPaneScrollEventArgs>
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>
floatingPaneResizeEnd Raised when a floating pane resize operation ends. false CustomEvent<IgcFloatingPaneResizeEventArgs>
floatingPaneResizeStart Raised when a floating pane resizing operation starts. true CustomEvent<IgcFloatingPaneResizeEventArgs>
floatingPaneResizeMove Raised when a floating pane resizing operation is in progress. true CustomEvent<IgcFloatingPaneResizeMoveEventArgs>
activePaneChanged Raised when a pane is selected/activated true CustomEvent<IgcActivePaneEventArgs>
CSS Parts
Name Description
content-pane The content pane component.
split-pane The split pane component
floating-window Indicates a floating pane
pane-header The content pane header component
pane-header-content The content area of the content pane header
pane-header-actions The actions area of the content pane header
pane-header-close-button The close button of a pane header
pane-header-maximize-button The maximize button of a pane header
pane-header-minimize-button The minimize button of a pane header
pane-header-pin-button The pin button of a pane header
pane-header-unpin-button The unpin button of a pane header
splitter The resizing splitter component
splitter-base The base element of the splitter component
splitter-ghost The ghost element of the splitter component
splitter-handle Indicates the custom splitter handle.
tab-panel The tab panel component
tab-strip-area The tab strip area containing the tab headers.
tab-strip-actions The tab strip area containing the tab actions.
tabs-container The container area of the tabs
tabs-content The content area of the tabs
tabs-minimize-button The minimize button of the tabs
tabs-maximize-button The minimize button of the tabs
tabs-more-button The more button of the tabs
context-menu The context menu component
context-menu-item An item in the context menu component
context-menu-content The content section of the context menu component
context-menu-close-button The close button in the context menu component
context-menu-unpin-button The unpin button in the context menu component
docking-preview The docking preview area
docking-indicator The non-root docking indicator
root-docking-indicator The root docking indicator
pane-navigator The pane navigator component
pane-navigator-header The header area of the pane navigator
pane-navigator-body The body area of the pane navigator
pane-navigator-items-group An items group in the pane navigator component
pane-navigator-items-group-title The title element of an items group in the pane navigator
pane-navigator-item An item in the pane navigator
tab-header The tab header component
header-title The header title area of a tab header.
tab-header-close-button The close button of a tab header
tab-header-more-options-button The more options button of a tab header
unpinned-pane-header The unpinned pane header component
unpinned-tab-area Indicates the unpinned tab area.
unpinned-tab-area--left Indicates the unpinned tab area on the left.
unpinned-tab-area--right Indicates the unpinned tab area on the right.
unpinned-tab-area--bottom Indicates the unpinned tab area on the bottom.
unpinned-tab-area--horizontal Indicates a horizontal unpinned tab area with top or bottom location.
unpinned-tab-area--hidden Indicates an unpinned tab area without any panes.
single-floating Applies to a single floating content-pane.
active Indicates an active state. Applies to pane-header, pane-header-content, pane-header-actions, tab-header, unpinned-pane-header, tab-header-close-button, tab-header-more-options-button .
disabled Indicates a disabled state. Applies to context-menu, pane-navigator, content-pane, pane-header, pane-header-content, pane-header-actions, unpinned-pane-header, tab-header, tab-panel, pane-navigator-item.
floating Indicates a floating pane placement. Applies to pane-header, pane-header-content, pane-header-actions, tab-header-more-options.
window Indicates a floating window placement. Applies to pane-header, pane-header-content, pane-header-actions.
selected Indicates a selected state. Applies to tab-header, tab-header-close-button, pane-navigator-item, tab-panel
document Indicates a document host. Applies to tabs-content.
start Indicates a position at start. Applies to unpinned-pane-header.
end Indicates a position at end. Applies to unpinned-pane-header.
top Indicates a top tabs position. Applies to tab-header, tab-strip-area, tab-strip-actions.
bottom Indicates a bottom tabs position. Applies to tab-header, tab-strip-area, tab-strip-actions.
horizontal Indicates a horizontal position. Applies to unpinned-pane-header, splitter-handle.
vertical Indicates a vertical position. Applies to unpinned-pane-header, splitter-handle.
hovered Indicates a hovered state. Applies to tab-header-close-button
hover-preview-close Indicates the close button shown on hover. Applies to tab-header.
hover-preview-options Indicates the more options button shown on hover. Applies to tab-header.
Slots
Name Description
pinButton The pin button slot.
unpinButton The unpin button slot.
maximizeButton The maximize button slot.
minimizeButton The minimize button slot.
moreOptionsButton The more options button slot.
closeButton The close button in pane and tab headers
moreTabsButton The more tabs button slot in tabs component.
tabHeaderCloseButton The close button slot of a tab header.
paneHeaderCloseButton The close button slot of a pane header.
splitterHandle The splitter handle slot.

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
tabHeaderId The slot attribute's value of the tab header element. If not set, the header property value is used. false string
unpinnedHeaderId The slot attribute's value of the unpinned header element. If not set, the header property value is used. false string
floatingHeaderId The slot attribute's value of the floating header element. If not set, the headerId property value is used. false string
documentOnly Marks that a content pane can be docked only inside a document host. Defaults to false . false boolean
size The relative size of the pane. Defaults to 100. false number
isPinned Describes whether a content pane is pinned or not. Defaults to true. false boolean
isMaximized Determines whether a content pane is maximized or not. Defaults to false. false boolean
unpinnedSize The absolute size of the pane in an unpinned state. Defaults to 200. false number
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
allowMaximize Determines whether the end user is allowed to maximize the pane. Defaults to true. false boolean
acceptsInnerDock Determines whether the end user can inner dock another pane in this one. Defaults to true. false boolean
hidden Determines whether a pane is hidden in the UI. Defaults to false. false boolean
disabled Determines whether a pane is disabled. Defaults to false. false boolean

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
floatingResizable Determines whether floating pane resizing is allowed. Applies only for floating panes. false boolean
allowEmpty Determines whether the pane should present in the UI when empty. false boolean
isMaximized Determines whether a split pane is maximized or not. Defaults to false. false boolean

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
allowEmpty Determines whether the pane should present in the UI when empty. false boolean
isMaximized Determines whether a split pane is maximized or not. Defaults to false. false boolean

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

IgcDockingIndicator

Name Description Required Type
position Gets the position of the docking indicator. false IgcDockingIndicatorPosition
isRoot Gets a value indicating whether the docking indicator is a root one. true boolean
direction Gets a value indicating the direction of the docking indicator. true string

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
panes false string
documents false string
moreTabs false string
moreOptions false string
Other
Name Description Return type Parameters
addResourceStrings Adds custom resource strings. language: string, resourceStrings: IgcDockManagerResourceStrings

A

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
Alt + F3. Closes document/tab
Cmd/Ctrl + F6 Focus next tab in document host
Cmd/Ctrl + Arrow right Focus next tab in document host
Cmd/Ctrl + Shift + F6 Focus previous tab in document host
Cmd/Ctrl + Arrow left Focus previous tab in document host
Alt + F6 Focus next content pane
Alt + Shift + F6 Focus previous content pane
Cmd/Ctrl + F7 Show the navigator and iterate panes and documents starting from the first document forward
Cmd/Ctrl + F8 Show the navigator and iterate panes and documents starting from the first document forward
Alt + F7 Show the navigator and iterate panes and documents starting from the first pane forward
Alt + F8 Show the navigator and iterate panes and documents starting from the first pane forward
Cmd/Ctrl + Shift + F7 Show the navigator and iterate panes and documents starting from the last document backwards
Cmd/Ctrl + Shift + F8 Show the navigator and iterate panes and documents starting from the last document backwards
Alt + Shift + F7 Show the navigator and iterate panes and documents starting from the last pane backwards
Alt + Shift + F8 Show the navigator and iterate panes and documents starting from the last pane backwards

A

A

A

Automation

Initial view

  • S

Interaction

  • S

Keyboard Navigation/Interaction

  • S

API <-> UI updates

  • A

Localization

  • S

Manual

  • S