swimos/swim-toolkit-js

User interface frameworks for advanced real-time applications.

swim-toolkit-js's Issues

Implement TreeView, LeafView, and CellView

A TreeView displays a hierarchical table with disclosable rows containing column-aligned cells. Each row in a TreeView is represented by a LeafView. And each LeafView contains a CellView corresponding to each column defined for the row.

Design

A TreeView is responsible for positioning rows, maintaining column alignment guides, and delegating row activation, selection, and other control logic to a TreeViewController. A LeafView is responsible for laying out its cells, interpreting user interaction, and maintaining, displaying, and animating highlight, selection, focus, disclosure, and depth state.

A LeafView can be activated, selected, and disclosed. On desktop, a LeafView is both selected and activated with a single click. On mobile, a LeafView is activated with a tap, and selected with a long press. Multiple leaf views may be concurrently selected with either a shift-click or a long press. A LeafView is disclosed by activating a DisclosureCellView embedded within the row. Swiping left or right on a LeafView reveals an optional AccessoryView hidden beneath either end of the row. Accessory views can be used to provide row-specific actions, such as removing a row.

CellView is the abstract base class for all tree view cells. Each CellView is anchored to a left and right column alignment guide inherited from its view scope. A CellView can span columns by anchoring itself to non-adjacent column alignment guides.

AccessoryView is the abstract base class for views that hide beneath either end of a LeafView, and can be revealed with a left or right swipe on the LeafView itself. Multiple accessory views can be attached to either end of a LeafView, facilitating small menus of actions.

               Tree Stems (not visible)
                |      |      |      |
            +----------------------------+
            |          Tree View         |
            | +------------------------+ |
            | |                        | |
            | |          Leaf          | |
            | |          View          | |
            | |                        | |
+-----------|-+------------------------+-|-----------+
|           | | +------+------+------+ | |           |
| Accessory | | | Cell | Cell | Cell | | | Accessory |
|   View    | | | View | View | View | | |   View    |
|           | | +------+------+------+ | |           |
+-----------|-+------------------------+-|-----------+
            | | +------+-------------+ | |
            | | | Cell |     Cell    | | |
            | | | View |     View    | | |
            | | +------+-------------+ | |
            | +------------------------+ |
            | |                        | |
            | |          Leaf          | |
            | |          View          | |
            | |                        | |
            | +------------------------+ |
            +----------------------------+

CellView specializations will include IconCellView, TextCellView, and DisclosureCellView, with additional specialized cells implemented by other UX libraries. The primary implementation of AccessoryView will be ButtonAccessoryView.

Implementation

Tree views are implemented by a family of coordinated views, namely TreeView, LeafView, CellView, and AccessoryView.

TreeView

TreeView has three primary responsibilities: propagating configuration parameters to leaf views via the view scope, procedurally positioning leaf views in the DOM, and coordinating with the TreeViewController.

View Scope

TreeView should inject a treeStems item into the view scope containing the named alignment guides to which cell views will align themselves.

@ViewScope(Object)
treeStems: ViewScope<this, TreeStems>;

TreeView should inherit edgeInsets from its environment, aligning its leftmost column vein to the left inset, and aligning its rightmost column vein to the right inset.

@ViewScope(Object, {inherit: true})
edgeInsets: ViewScope<this, ViewEdgeInsets>;

TreeView should also add a treeTransition item to the view scope, which is used to tween leaf view positions when rearranging rows.

@ViewScope(Object, {
  init(): Transition<any> {
    return Transition.duration(250, Ease.cubicOut);
  },
})
treeTransition: ViewScope<this, Transition<any>>;

Tree Layout

TreeView should be positioned relative, with auto overflow and -webkit-overflow-scrolling: touch so that it scrolls internally with momentum. On insertion, child leaf views should be positioned absolute.

TreeView procedurally positions its child leaf views. Procedural positioning is employed for two reasons: to facilitate animated changes in leaf position due to insertion, removal, reordering, expanding, collapsing, and dragging; and to support optimizing long lists by dynamically pruning leaf views from the DOM when not scrolled into view.

Leaf Positioning

Iterate over all child leafs, setting the top style property of each leaf to the running height of the tree view, and then incrementing the running height by the leaf height. The top of the first leaf must be shifted by the height of any pruned leaves. Implementation of leaf pruning may be tackled at a later date.

LeafView

View Scope

View Animators

Leaf States

Cell Layout

Accessory Layout

Position Gestures

Tasks

Implement the tree module iteratively, with progressively more detailed passes over the family of views.

Stubs

Sketch out the basic view classes and associated types.

Tree Module Stubs

• Create tree directory to @swim/navigation/main.
• Add tree/index.ts file to contain all tree directory exports.
• Re-export tree directory from @swim/navigation's main index.ts file (export * from "./tree";).

TreeView Stubs

• Add tree/TreeView.ts; export an empty TreeView class that extends HtmlView.
• Add type TreeStems = {readonly [key: string]: number}; declaration to tree/TreeView.ts.
• Add tree/TreeViewObserver.ts; export an empty TreeViewObserver interface that extends HtmlViewObserver.
• Add tree/TreeViewController.ts; export an empty TreeViewController class that extends HtmlViewController.
• Re-export TreeStems, TreeView, TreeViewObserver, and TreeViewController from tree/index.ts.

LeafView Stubs

• Add tree/LeafView; export an empty LeafView class that extends HtmlView.
• Add tree/LeafViewObserver; export an empty LeafViewObserver interface that extends HtmlViewObserver.
• Add tree/LeafViewController; export an empty LeafViewController class that extends HtmlViewController.
• Re-export LeafView, LeafViewObserver, and LeafViewController from tree/index.ts.

CellView Stubs

• Add tree/CellView; export an empty CellView abstract class that extends HtmlView.
• Add tree/CellViewObserver; export an empty CellViewObserver interface that extends HtmlViewObserver.
• Add tree/CellViewController; export an empty CellViewController class that extends HtmlViewController.
• Re-export CellView, CellViewObserver, and CellViewController from tree/index.ts.

AccessoryView Stubs

• Add tree/AccessoryView; export an empty CellView abstract class that extends HtmlView.
• Re-export AccessoryView from tree/index.ts.

Properties

Fill in essential view properties.

TreeView Properties

• Add treeStems view scope property.
• Add inherited edgeInsets view scope property.
• Add treeTransition view scope property.

LeafView Properties

• Add inherited treeStems view scope property.
• Add depthColor view animator.
• Add highlightColor view animator.
• Add _depth: number field.
• Add _highlighted: boolean field.
• Add _selected: boolean field.
• Add _focussed: boolean field.
• Add _expanded: boolean field.
• Add _gesture: PositionGesture<LeafView> field.

CellView Properties

• Add _leftVein: string field.
• Add _rightVein: string field.