Merged css files into one

Added markdown annotations to samples

Author: BasicPrimitives

docs/AddingNewItemsToChartAtRuntime.md

@@ -0,0 +1,9 @@
+# Adding new items to chart at runtime
+
+Component is designed to update only visual elements effected by the scope of changed properties. For example on screen annotations positions depend on positions of nodes they are bound to, so when we make changes to on-screen annotations there is no need to redraw diagram nodes. The same applies to other visual elements, chart compares current properties to the new one and in case of changes it triggers rendering of effected visual elements.
+
+Chart does not track individual items, if we add or remove one of them then the whole collection of items is considered to be changed, so control will layout diagram again. But at the same time if we change properties of items not effecting their layout positions, then component will refresh only items content without layout changes. The component is designed to be used in React, so end user may change any API properties on every rendering cycle, the control will check properties and make visual updates in the scope of changed properties only. The point of this statement is that if we assign new items array to items property, but we make no changes to actual items, chart will not perform any layout calculations and rendering, so resulting React virtual DOM of the component will stay the same.
+
+The following example demonstrates adding new items to organizational chart at run time, application keeps state of items collection via adding and deleting nodes. For more complex implementation of chart editing functionality see chart editor demo.
+
+[React](../src/Samples/AddingNewItemsToChartAtRuntime.js)

docs/AdviserAndAssistantItemTypes.md

@@ -0,0 +1,33 @@
+# Custom Placement of Children
+## Adviser & Assistant Item Types
+
+Organizational Chart items are defined in form of regular hierarchy, so every item may have only one parent. This is conceptually easy to understand for end user who edits organizational chart and software devloper to maintain required structures in database and in application.
+
+In the reality pure hierarchical relations are rare, so organizational chart provides means to represent none hierarchical realations in form of item types and on-screen annotations.
+
+Chart supports following `itemType`s:
+
+* `primitives.orgdiagram.ItemType.Regular`
+* `primitives.orgdiagram.ItemType.Adviser`
+* `primitives.orgdiagram.ItemType.Assistant`
+* `primitives.orgdiagram.ItemType.SubAdviser`
+* `primitives.orgdiagram.ItemType.SubAssistant`
+* `primitives.orgdiagram.ItemType.GeneralPartner`
+* `primitives.orgdiagram.ItemType.LimitedPartner`
+* `primitives.orgdiagram.ItemType.AdviserPartner`
+
+All of them control child placement relative to its logial parent in the hierarchy. The following example demonstrates  `Adviser` and `Assistant` types. `Adviser` item placed on the side of its logical parent and connected to it horizontally. `Assistant` item is placed at level in between its parent and remaining `Regular` children and horizontally connected to connection line connecting parent and its `Regular` children.
+
+Use `adviserPlacementType` property of `ItemConfig` to place `Adviser` or `Assistant` on the left or right side of the hierarchy
+* `primitives.common.AdviserPlacementType.Left`
+* `primitives.common.AdviserPlacementType.Right`
+
+[React](../src/Samples/AdviserAndAssistantItemTypes.js)
+
+## Sub Adviser & Sub Assistant item types
+
+Sub Adviser & Sub Assistant item types are variations of regular Adviser & Assistant types. The only difference is they are shift down one level relative to their parents, so they are connected by their top side to the hierarchy.
+
+Use `adviserPlacementType` property to place them on the left or right side of parent's hierarchy as well.
+
+[React](../src/Samples/SubAdviserAndSubAssistantItemTypes.js)

docs/Buttons.md

@@ -0,0 +1,28 @@
+# Buttons panel
+
+Component provides options to preserve some space around nodes to render custom controls or buttons. Buttons rendered in diagram layout provides better UI discoverability compared to context popup panel.
+
+Buttons panel visibility can be enabled at component scope with `hasButtons` property:
+* `primitives.common.Enabled.Auto` - Buttons visible only for cursor item.
+* `primitives.common.Enabled.True` - Every normal item has buttons visible.
+* `primitives.common.Enabled.False` - No buttons.
+
+Buttons panel visibility can be enabled individually per `ItemConfig` with similar 'hasButtons' property:
+* `primitives.common.Enabled.Auto` - Buttons panel visibility depends on component scope `hasButtons` value.
+* `primitives.common.Enabled.True` - Has buttons visible.
+* `primitives.common.Enabled.False` - No buttons panel.
+
+The size of the buttons panel set in component `Config` `buttonsPanelSize` property. It is regular numeric value in `px`.
+
+Buttons panel content can be customized per component or per item template with `onButtonsRender` callback function. See item template definition in the following example:
+
+Please, pay attention that every button `onClick` event handler suppresses even propogation, it is needed to avoid chart cursor item change and following layout
+
+```JavaScript
+onClick={(event) => {
+  event.stopPropagation();
+  alert(`User clicked on Coffe button for node ${itemConfig.title}`)
+}}>
+```
+
+[React](../src/Samples/ButtonsPanel.js)

docs/ChildrenLayout.md

@@ -0,0 +1,13 @@
+# Regular Children Layout
+
+Children Placement Layout can be defined individually per item or globally for all chart items. Following component and individual items properties are used to define layout of the children:
+
+* `childrenPlacementType` - this property is available for chart and for individual items, it defines shape of children with enumeration `primitives.common.ChildrenPlacementType` it provides following options `Vertical`, `Horizontal` & `Matrix`
+* `leavesPlacementType` - this option is available only at component scope and it is used to control children layout having no sub children, so it is only for children of the last level in hierarchy.
+* `maximumColumnsInMatrix` - by default children in matrix are shaped into square, in order to form them into rectangular shape you have to limit maximum number of columns in matrix, so rectangular shape would grow vertically.
+
+In general children layouts are all matrix, the only difference is that horizontal layout has only one row and vertical layout has only one column.
+
+The `maximumColumnsInMatrix` value should limit children matrix growth outside of the view port width, in order to avoid the necessety of simultanious horizontal and vertical scrolling of nodes. Keeping square shape of nodes is good for small matrixes which easely fit into view port, but large groups of children are better shaped into wide columns.
+
+[React](../src/Samples/ChildrenPlacementType.js)

docs/ConnectorAnnotation.md

@@ -0,0 +1,21 @@
+# Connector Annotations
+
+Connector annotation is on screen direct connection line between two nodes of diagram. Use them the same way as highlight markers for temporary or per transaction drawings over diagram nodes. See following example for how it works:
+
+## Styles
+Connector annotations are drawn on top of exisiting diagram, so sometimes space between nodes is not enough to fit annotation label and arrow, so for this case connector annotation supports offbeat style of drawing, so instead of straight line connecting two nodes, the connector is drawn as free hand spline on side of them.
+* `primitives.common.ConnectorPlacementType.Offbeat` - Free hand drawing of connector annotation
+* `primitives.common.ConnectorPlacementType.Straight` - Straight line between nodes
+
+## Shapes
+In general shape of connector annotation may indicate various business relations, so component supports following simple use case:
+* `primitives.common.ConnectorShapeType.OneWay` - The arrow line between `fromItem` and `toItem` nodes
+* `primitives.common.ConnectorShapeType.TwoWay` - Two opposite direction arrow lines between `fromItem` and `toItem` nodes
+* `primitives.common.ConnectorShapeType.BothWay` - One line having arrows on both ends
+
+The more complex use cases can be built with multiple connector annotations originating from the same `fromItem` and `toItem` nodes. Component supports simple conflict resolution, for example in the above mentioned case if multiple straight line connectors overlap each other, the diagram will try to offset them and draw side by side in parallel.
+
+## Labels
+Connector annotations labels are defined as a plane text or JSX elements. Please, pay attention that component does not resolve connector annotations labels overlapping, so large number of labels can clutter view and diagram in general.
+
+[React](../src/Samples/ConnectorAnnotation.js)

docs/CursorTemplate.md

@@ -0,0 +1,36 @@
+# Cursor template
+The diagram in general is collection component, so it supports concept of current cursor item, which enables navigation related functionality. The current cursor item is supposed to have visual feedback on diagram, by default it is solid `2px` wide border line around it. The general idea about cursor template is to provide convenient API to customize that border line around cursor item.
+
+## Properties:
+Component customizes visual representaion of items with `templates`, every template has customization properties for item content, cursor and highlight visualizations. By default if properties are not set then component uses built in default functionality. The following properties customize cursor template:
+* `cursorPadding` - Reserves space around item, for example: `{left: 3, top: 3, right: 50, bottom: 3}` will provide extra `50px` on right side of item for sursor content.
+* `cursorBorderWidth` - some sort of legacy property, it is used to align cursor position around item properly.
+* `onCursorRender` - callback method to render cursor content for given item of diagram
+
+See Item template for more details.
+
+```JavaScript
+  onCursorRender: ({ context: itemConfig }) => {
+    return <div style={{ borderColor: itemConfig.badgeColor }} />;
+  }
+```
+
+## Cursor item & preserving space for context control panel
+The conventional approach is to place controls for current cursor item in diagram in the panel on the side of the diagram and change its content as user navigates from item to item, this approach takes a cut of screen space out of the diagram layout. The similar approach is to draw context menu panel on top of the diagram on the side of the cursor item, but this obstructs view of other diagram nodes. The compromise UI design is to expand space around cursor node and place context controls into that space, so cursor template provides `cursorPadding` property to preserve that required space around cursor node.
+
+```JavaScript
+  <OrgDiagram config={{
+    cursorPadding: {left: 3, top: 3, right: 50, bottom: 3}
+  }} />
+```
+
+## Avoiding conflicts between custom controls & annotations
+User controls in cursor item template plays a role of in-layout annotation, non-blocking neighboring items in diagram. In case when every full size item is supposed to have UI controls then item template should be customized instead. Use `z-index` style attribute to layer controls properly, otherwise they can be blocked by annotations. Ideally only cursor item should have controls inside, so annotations will not be drawn over edit boxes or drop down combo boxes. If you draw connector annotations only for current cursor item, then you avoid conflicts with annotations.
+
+Every time we change cursor node control recalculates layout, so this slows down rendering of large diagram. Our design view on this problem is to limit number of simultaneously shown nodes in diagram. Control provides default mechanism to reduce nodes into dots, but general approach is to replace groups of diagram nodes with single node and expand them as user moves cursor close to them. This kind of design approach is implemented in Dynamic Data Loading demo.
+
+## Custom cursor template border
+The following example demonstrates how to create custom cursor border having item specific color and tag element.
+
+[React](../src/Samples/CursorTemplate.js)
+

docs/CustomLayoutWithInvisibleItems.md

@@ -0,0 +1,15 @@
+# Custom layout with Invisible items
+Organizational chart navigation is defined by parent-children relations between items. When user selects cursor item, component shows all its neighbours i.e. children, parents and siblings in full size, so user can proceed navigation from item to item in diagram. The invisible items are not shown in layout so they cannot be shown in full size, so chart shows all neighbours of invisible items in full size instead. This feature combined with custom item types and children layouts provides great flexibility to visualize various logical parent child relations.
+
+Following example demonstrates how to use invisible items to display multiple groups of children attached to one parent item. It has two rows of assistants and two levels of children. In order to implement this layout we create two invisible items of regular item type. Children of invisible items logically belong to their parent in our case it is root item of organizational chart, so when cursor is set to root then all items in chart become selected and displayed in full size, so user may navigate to any of them directly.
+
+See custom item types, children layout and inactive items samples as well.
+
+[React](../src/Samples/CustomLayoutWithInvisibleItems.js)
+
+## Skipped Levels
+
+Invisible items can be used to skip levels in organizational chart. This is actually workaround, invisible items occupy space, so they can be used to shift children items down one level relative to their parents. See `primitives.orgdiagram.ItemConfig.isVisible` property.
+
+[React](../src/Samples/SkippedLevels.js)
+

docs/DiagramSizing.md

@@ -0,0 +1,45 @@
+# Diagram Sizing
+## Responsive Design
+Like any other Data Visualization component it combines scalable and non-scalable graphics elements. For example we would like to show 10'000 labels but it is just physically impossible to fit them, because their total square size is multiple times bigger than available screen space. At the same time we cannot scale all of them down to points, since they become simply unreadable. Try to disable "fit to page" for large hierarchy demo, the resulting diagram is going to be so big that its visualization makes no sense, this rendering mode is useful only for PDF generation for reporting purposes only. If we speak about BI applications designed for data analysis then we need to show nodes only in the scope of current user focus of interest, so diagramming applications should be dynamic and adopt to user data and requirements. Another argument in favour of diagramming applications having auto layout is the fact that in large organizations where we have over 500 people the rate of changes is so high that any organizational structure becomes obsolete as soon as we make its hard copy. So we use various strategies to show as mush data as possible to the user within available screen space, so control needs to be notified about its placeholder size changes in order to trigger rendering cycle. 
+
+## Diagram placeholder sizing is applications responsibility
+Component occupies all available space inside parent `div`, so if application changes size of `div` containing diagram component it triggers component state change and following rendering cycle. Component uses [`resize-observer-polyfill`](https://www.npmjs.com/package/resize-observer-polyfill) to handle diagram size change.
+
+## Component Sizing with CSS @Media
+The main point of CSS @Media based control sizing is to keep diagram component size less than screen size. We want to have diagram to be as large as possible, but we need to avoid situation when user has to scroll diagram and page srollbars altogether in order to see diagram content. The first image shows unusable scroll bars.
+
+![Unusable scrollbars](./images/PageSizeDiagram1.png "Unusable scrollbars")
+
+Having scroll bars enabled for components is fine if they fit into the page view port. So we can place diagram component and stack it verticaly with other components on the page. The following image shows 2 components having scrollable content, both of them are usable, since user can scroll them into the current view port and work with their content scrollbars individually.
+
+![Usable control scrollbars](./images/PageSizeDiagram2.png "Usable control scrollbars")
+
+The "classic" and the most popular approach for desktop applications is to fit page and diagram 100%. In that case you have to design your web site appropriatly.
+
+![Classic desktop layout](./images/PageSizeDiagram2.png "Classic desktop layout")
+
+The following sample control hight is sized by CSS @Media rules to be within current page view port size. Try to resize your browser window in order to see how it works. The diagraming component has minimum vertical size set to hardcoded 250px.
+
+See [CSS @Media](https://developer.mozilla.org/en-US/docs/Web/CSS/@media) for more reference
+
+[Sample of diagram size controlled by CSS @Media](../src/Samples/PageSizeDiagram.js)
+
+## Auto Size Diagram in Article
+Another diagram integration scenario is diagram placement inside article, so component needs to auto expand its size in order to accommodate all nodes of diagram without minimization or trancation. Set `pageFitMode` to `primitives.common.PageFitMode.AutoSize` and component will size itself to show all nodes of diagram. 
+
+Use following options to constrain component auto size:
+
+* `autoSizeMinimum` - it limits minimal size of diagram, so if it is empty then you are going to see empty `div` of this size.
+* `autoSizeMaximum` - does not allow to grow component beyond this size. Set maximum size to some value if you need to avoid humongous diagram on your page.
+
+for example in order to set widget minimal size: 
+
+```JavaScript
+<OrgDiagram centerOnCursor={true} config={{
+  autoSizeMinimum: new primitives.common.Size(800, 600),
+  autoSizeMaximum: new primitives.common.Size(1024, 768)
+  // other properties
+}} />
+```
+
+[React](../src/Samples/AutoSize.js)

docs/FamilyChartItemsOrdering.md

@@ -0,0 +1,20 @@
+# Family diagram items ordering
+Family diagram supports multiple parents and children per node, so there is no deterministic way to define groups of items and their order inside of the group, so family diagram provides non-determenistic API to order items. That means if items expected to be in one layout group then user can use following properties to guide layout engine about user preferred relative order of items:
+
+1. `relativeItem` - item position and placement type defined relative to this property referenced item
+2. `placementType` - item placement on the left or right side of relative item. Property has following values:
+    * `primitives.common.AdviserPlacementType.Left`
+    * `primitives.common.AdviserPlacementType.Right`
+3. `position` - if several items reference the same `relativeItem` and placement then this `position` property defines order of them.
+
+This relative optional ordering approach gives none ordered nodes to be placed optimally, so if item has no relative item defined then layout engine will try to find the best place for it based on its relations.
+
+Please, pay attention that loops in references are completely ignored, so don't create mutual references between items.
+
+## Family Items Ordering Sample
+
+[React](../src/Samples/FamilyChartItemsOrdering.js)
+
+## Multiple Families Ordering Sample
+
+[React](../src/Samples/MultipleFamiliesOrdering.js)