flexui - npm explorer

FlexUI v0.2

Example: https://cdn.rawgit.com/rogual/flexui/master/ui-example.html

This implements a non-overlapping tabbed UI for Javascript. It's early days
and, while it should work, you can easily break it by writing to properties
you shouldn't.

Spaces and Panels

Spaces are arranged in a tree. Split spaces have 2 or more children; leaf
spaces have 1 or more panels.

Split spaces can be horizontal or vertical. Each split space is the
opposite orientation from its parent.

The above constraints are enforced by the function space.normalize(), or
its recursive version space.normalizeTree(). These are usually called for
you at the right times, but if you are reaching in and deleting spaces or
moving panels around from code, you will need to normalize any spaces you
touch if you want your tree to stay nice.

Inside each Space, one Panel can be active, and is displayed in the space.

Additionally, Spaces may reserve some of their screen area to draw some
form of UI. By default, a tab bar is drawn.

Panels can be dragged to other Spaces, or to the dividing lines between
spaces, which causes a new Space to open there.

Spaces must all share the same configuration, since FlexUI will
need to create new ones on its own.

Things about Spaces which can be customized:
- How to indicate the panel list and current panel
- If using the default tabstrip view, then:
- Tab elements can be customized
- Tabstrip element itself can be customized
- Otherwise, custom UI and drop targets can be defined.

Theming

Theming is by way of CSS -- see ui-example.html which implements two
themes.

Caveats

* Do not keep references to Spaces -- FlexUI removes Spaces all the time when
it's reshuffling the tree and your references will become invalid very
quickly.

* While this rudimentary documentation exists, this is very much one of those
“read the code” projects. The examples might be a good place to start.

API Reference follows.

Utility functions

FlexUI.installDefaultCSS()

Call this before using FlexUI.

OriTree interface

Tree node where:
| Node either has n>=2 children or is a leaf
| Node has a direction ('row' or 'column')
| Node's direction must be different from its parent's direction
| Root node can have either direction

Implementations: Frame, Area, Space

Properties:
| oritree.parent
| oritree.children
| oritree.direction

Frame: OriTree

OriTree implementation where nodes are HTML elements (frame.elem) laid
out with CSS flexbox.

Examples: frames-fixed, frames-resizable, frames-dynamic

Constructors:
| frame = FlexUI.frame([childFrames])
| frame = FlexUI.separator()

Properties:
frame.elem

Area: OriTree

Layer on top of Frames, where Areas maintain resize handles between
themselves.

Example: areas-dynamic

Constructors:
| area = FlexUI.area([childAreas])

Properties:
| area.frame
| area.elem (= area.frame.elem)

Space: OriTree

Layer on top of Areas implementing a user-configurable non-overlapping
UI panel layout.

Constructors:
| space = FlexUI.splitSpace(childSpaces)
| space = FlexUI.leafSpace(panels)

Properties:
| space.panels
| space.activePanel

Panel

Panels are plain Javascript objects. Each panel needs to have an 'elem'
property referring to its HTML element. The default tabbed space delegate
also expects panels to have 'name' and 'closable' properties.

FlexUI will also create and maintain a 'space' property on each panel.

Drag & Drop Helpers

Utilities for allowing users to drag panels between Spaces. If you are
using the default tabbed space delegate, you probably won't need these.

Functions:
| FlexUI.makeDragSource(elem, panel)
| FlexUI.removeDragSource(elem)

Elements which have been made into drag sources can be dragged to spaces.
Their associated panels will then move to the chosen space.

| FlexUI.makeDragHandle(dragElem, separator)

Makes an element behave as if it were a separator between two spaces. The
separator argument should be the separator element the dragElem should
behave as, or a function returning such. While the function returns null,
the element will not function as a separator.

Space Delegate

You can replace the Space Delegate using FlexUI.setSpaceDelegate(newDg).
The default Space Delegate is FlexUI.tabSpaceDelegate.

Methods:
| delegate.init(space)
| delegate.modified(space)
| delegate.setPanels(space, panels)
| delegate.setActivePanel(space, panel, index)

| delegate.panelDraggedOver(event)
| delegate.panelDraggingOver(event)
| delegate.panelDraggedOut(event)
| delegate.panelDropped(event)

| delegate.makeTab(space, panel)
| delegate.buildTabBar(space)

| delegate.layout()
| delegate.focusPanel(panel)