Splitter Specification

1. Revision History

Version	User	Date	Notes
0.1	Stefan Ivanov	Mar 11, 2020	Initial draft
0.2	Damyan Petev	Apr 13, 2020	API revision, ARIA

2. Overview

The Splitter component provides a framework for a simple layout splitting the view horizontally or vertically into multiple smaller areas called panes.

3. User Stories

End User Stories

As an end-user I want to:

see two or more content areas side by side with a divider between them e.g. a design surface and its corresponding code view
resize the panes by dragging the splitter element
focus the splitter element via the keyboard
use the keyboard to resize the split panes
scroll the content if it doesn't fit in the pane in horizontal, vertical, or in both directions
collapse and expand panes

Developer Stories

As a developer I want to:

provide arbitrary content that is rendered in a splitter's pane
create a splitter that lays out panes horizontally or vertically determined by an orientation property
have the vertical splitter layout to respect the right-to-left support that certain cultures may require
define a default size for each pane
define a min and max values for the width and height of a pane
specify a pane as not resizable, which would not allow the user to drag its handle
specify if a pane is not collapsible, which would remove the collapse buttons for the user (P2)
nest a splitter in another splitter's pane
have right-to-left support out of the box

4. Functionality

User Interface

Design Hands-Off:

A splitter with a vertical orientation and two panes, where the right one contains scrollable content and shows a scroll bar. On both sides of the drag handle for the splitter separator, there are icons for collapsing the pane to the right/left. Splitter with design to the left and code view to the right Splitter with the left pane collapsed Light theme of a collapsed splitter

On hover over the splitter, its indicator changes for the dark theme from grays 800 without alpha channel to grays 500 without alpha channel and for light theme from grays 200 without alpha channel to white. If the user hovers above the expand/collapse icons and their extended target area then only the icon fill color will change in a similar fashion, the splitter drag indication will remain in its normal state.

The splitter and its icons will have an extended target area that will make it easier for interacting with them e.g. if the splitter is 4px wide the interactive area will extend 4px to the left and 4 px to the right. The mouse cursor will change accordingly to indicate resize for the whole splitter except for the expand/collapse icons over which a hand cursor will be shown.

Developer exprerience

Initialization

Initializing an igxSplitter is done through a tag of its own igx-splitter. Inside it multiple panes can be defined via the igx-splitter-pane tag. The content of the pane is templatable and will be rendered in its own resizable containers.

  <igx-splitter>
        <igx-splitter-pane>
            ...
        </igx-splitter-pane>
        <igx-splitter-pane>
            ...
        </igx-splitter-pane>
    </igx-splitter>

More than two splitter panes can be defined under a single igx-splitter.

You can nest splitter components to create a more complex layout inside a splitter pane. For example:

  <igx-splitter>
        <igx-splitter-pane>
            <igx-splitter>
                 <igx-splitter-pane>
                    ...
                </igx-splitter-pane>
                <igx-splitter-pane>
                    ...
                </igx-splitter-pane>
            </igx-splitter>
        </igx-splitter-pane>
        ...
    </igx-splitter>

The splitter can be vertical or horizontal, which is defined by the type Input. The default is Vertical.

The splitter is initially collapsible and the default value of the nonCollapsible Input is false. You can make the splitter component noncollapsible by setting the nonCollapsible Input to true:

    <igx-splitter [nonCollapsible]='true'>
        <igx-splitter-pane>
            ...
        </igx-splitter-pane>
    </igx-splitter>

API

Inputs

igxSplitter

Name	Description	Type
type	The `igxSplitter` type - can be Horizontal (default) or Vertical.	SplitterType
nonCollapsible	The `igxSplitter` nonCollapsible input - can be false (default) or true.	boolean

igxSplitterPane

Name	Description	Type
size	Gets/Sets the size of the pane.	string
minSize	Gets/Sets the minimum allowed size of the current pane. Resizing beyond it is not allowed.	string
maxSize	Gets/Sets the maximum allowed size of the current pane. Resizing beyond it is not allowed.	string
resizable	Sets/Gets if the pane allows resizing. Disabling this will cause the cursor style to no longer change on hover (P2)	boolean
collapsible (P2)	Sets/Gets if the pane can be collapsed. If disabled, buttons on the splitter bar are no longer available.	boolean
collapsed	Sets/Gets if the pane is collapsed	boolean

Methods

igxSplitterPane

Name Description Return type Parameters

toggle Toggles pane visibility. void -

Outputs

igxSplitter

Name	Description	Cancelable	Arguments
resizeStart	Emits when pane resizing starts.	false	ISplitterBarResizeEventArgs
resizing	Emits while panes are being resized.	false	ISplitterBarResizeEventArgs
resizeEnd	Emits when pane resizing ends.	false	ISplitterBarResizeEventArgs

igxSplitterPane

Name Description Cancelable Arguments

onToggle Emits when pane visibility is toggled false IgxSplitterPaneComponent

Key	Result
Arrow up	Move the splitter element 10 px up
Arrow down	Move the splitter element 10 px down
Arrow left	Move the splitter element 10 px left
Arrow right	Move the splitter element 10 px right
Ctrl + Arrow	Expand/Collapse a pane with regard to the direction indicated by the arrow

6.2 ARIA Support

https://www.w3.org/TR/wai-aria-1.1/#separator

https://www.w3.org/TR/wai-aria-practices-1.1/#windowsplitter

https://github.com/w3c/aria-practices/issues/129

The splitter bar has:

role=separator
tabindex (focusable) only if resizable/collapsible
aria-orientation=horizontal(default)|vertical
[?] Potentially aria-value<now|min|max> if those are at all feasible
[?] May consider giving panes a label to be used as aria-labelledby for the bar

Note: https://www.w3.org/WAI/ARIA/1.0/examples/splitter/splitter appears outdated/broken and the pattern design update per the issue above is not finalized, so will ignore further options for now (e.g. expanded state no longer in newer patter).

Automation

Initial view

Should allow defining a vertical/horizontal splitter with panes.
Should allow defining nested splitters.

Interaction

Should allow resizing the panes using the spliiter bar via drag.
Should allow collapsing/expading panes via the splitter bar buttons.

Keyboard Navigation/Interaction

While focus is on the splitter bar:

Should allow moving the splitter bar left/right/up/down via the arrow keys in order to resize the related panes.
Should allow expanding/collapsing panes using CTRL+ arrow keys.