Add clear method, make skipsDiagramUpdate optional, update packages

Author: jonchardy

CHANGELOG.md

@@ -1,5 +1,10 @@
 # gojs-react Change Log
 
+## 1.1.0
+- [ReactDiagram.skipsDiagramUpdate](https://github.com/NorthwoodsSoftware/gojs-react#optional---skipsdiagramupdate-reactdiagram-only) is now an optional prop.
+We still encourage using it in most cases.
+- Added [clear](https://github.com/NorthwoodsSoftware/gojs-react#clear-reactdiagram-and-reactpalette-only) method to allow clearing of the diagram and treating the next state update as a Diagram reinitialization.
+
 ## 1.0.10
 - Model data is now merged into the GoJS model before node and link data in case any ofModel bindings depend upon it.
 
@@ -15,5 +20,5 @@ new data as necessary.
 - The GoJS model change listener is now active during model initialization and any merges of data.
 This means all changes that take place in GoJS - including side effects like laying out newly added nodes -
 will call the [onModelChange](https://github.com/NorthwoodsSoftware/gojs-react#optional---onmodelchange-reactdiagram-only) handler.
-Make sure to set [skipsDiagramUpdate](https://github.com/NorthwoodsSoftware/gojs-react#skipsdiagramupdate-reactdiagram-only)
+Make sure to set [skipsDiagramUpdate](https://github.com/NorthwoodsSoftware/gojs-react#optional---skipsdiagramupdate-reactdiagram-only)
 to true when making state updates in that handler.

IMPLEMENTATION.md

@@ -37,24 +37,12 @@ public componentDidMount() {
 
   // delay initialization of the diagram so all initial model data is merged before any animations/layouts
   diagram.delayInitialization(() => {
-    const model = diagram.model;
-    model.commit((m: go.Model) => {
-      if (this.props.modelData !== undefined) {
-        m.assignAllDataProperties(m.modelData, this.props.modelData);
-      }
-      m.mergeNodeDataArray(this.props.nodeDataArray);
-      if (this.props.linkDataArray !== undefined && m instanceof go.GraphLinksModel) {
-        m.mergeLinkDataArray(this.props.linkDataArray);
-      }
-    }, 'gojs-react init merge');
+    this.mergeData(diagram, true);
   });
 }
 ```
 
 ### Updating the GoJS Model based on React state changes
-#### componentDidUpdate
-The componentDidUpdate method is where any changes to React state are merged into the GoJS model.
-
 When state is updated in React, it is important to keep the GoJS model up-to-date.
 The methods used to do this are [Model.mergeNodeDataArray](https://gojs.net/latest/api/symbols/Model.html#mergeNodeDataArray) and
 [GraphLinksModel.mergeLinkDataArray](https://gojs.net/latest/api/symbols/GraphLinksModel.html#mergeLinkDataArray).
@@ -64,6 +52,9 @@ using [Model.cloneDeep](https://gojs.net/latest/api/symbols/Model.html#cloneDeep
 
 _Properties should not be removed, but rather set to undefined if they are no longer needed; GoJS avoids destructive merging._
 
+#### componentDidUpdate
+The componentDidUpdate method calls mergeData where any changes to React state are merged into the GoJS model.
+
 ```ts
 /**
  * When the component updates, merge all data changes into the GoJS model to ensure everything stays in sync.
@@ -73,16 +64,15 @@ _Properties should not be removed, but rather set to undefined if they are no lo
 public componentDidUpdate(prevProps: DiagramProps, prevState: any) {
   const diagram = this.getDiagram();
   if (diagram !== null) {
-    const model = diagram.model;
-    model.startTransaction('update data');
-    if (this.props.modelData !== undefined) {
-      model.assignAllDataProperties(model.modelData, this.props.modelData);
-    }
-    model.mergeNodeDataArray(this.props.nodeDataArray);
-    if (this.props.linkDataArray !== undefined && model instanceof go.GraphLinksModel) {
-      model.mergeLinkDataArray(this.props.linkDataArray);
+    // if clear was just called, treat this as initial
+    if (this.wasCleared) {
+      diagram.delayInitialization(() => {
+        this.mergeData(diagram, true);
+        this.wasCleared = false;
+      });
+    } else {
+      this.mergeData(diagram, false);
     }
-    model.commitTransaction('update data');
   }
 }
 ```
@@ -108,6 +98,24 @@ public shouldComponentUpdate(nextProps: DiagramProps, nextState: any) {
 }
 ```
 
+#### mergeData
+The mergeData method is where any changes to React state are merged into the GoJS model. It is called by componentDidMount and componentDidUpdate.
+
+```ts
+private mergeData(diagram: go.Diagram, isInit: boolean) {
+  const model = diagram.model;
+  model.commit((m: go.Model) => {
+    if (this.props.modelData !== undefined) {
+      m.assignAllDataProperties(m.modelData, this.props.modelData);
+    }
+    m.mergeNodeDataArray(this.props.nodeDataArray);
+    if (this.props.linkDataArray !== undefined && m instanceof go.GraphLinksModel) {
+      m.mergeLinkDataArray(this.props.linkDataArray);
+    }
+  }, isInit ? null : 'merge data');
+}
+```
+
 ### Tearing down the GoJS Diagram
 #### componentWillUnmount
 The componentWillUnmount method is responsible for tearing down the diagram and all listeners.

README.md

@@ -142,8 +142,8 @@ Specifies a modelData object for the Diagram's model, only necessary when using
 that will be shared by the model as a whole.
 See [Model.modelData](https://gojs.net/latest/api/symbols/Model.html#modelData).
 
-#### skipsDiagramUpdate (ReactDiagram only)
-Specifies whether the component should skip updating, often set to true when updating state from a GoJS model change.
+#### Optional - skipsDiagramUpdate (ReactDiagram only)
+Specifies whether the component should skip updating, often set to true when updating state originating from a GoJS model change.
 This flag is checked during shouldComponentUpdate. Because GoJS Palettes are read-only by default,
 this prop is not present on ReactPalette.
 
@@ -177,6 +177,42 @@ function handleModelChange(data) {
 #### observedDiagram (ReactOverview only)
 Specifies the go.Diagram which the Overview will observe.
 
+### Component Methods
+
+#### getDiagram/getPalette/getOverview
+Gets a reference to the GoJS Diagram/Palette/Overview.
+
+```ts
+const diagram = this.diagramRef.current.getDiagram();
+if (diagram instanceof go.Diagram) {
+  // ...
+}
+```
+
+#### clear (ReactDiagram and ReactPalette only)
+Clears the diagram and allows the next update to be treated as an initial load of the model.
+
+```ts
+// clear out the diagram
+this.diagramRef.current.clear();
+// provide new diagram data, which will be treated as initial data
+this.setState({
+  nodeDataArray: [
+    { key: 'Epsilon', color: 'lightblue' },
+    { key: 'Zeta', color: 'orange' },
+    { key: 'Eta', color: 'lightgreen' },
+    { key: 'Theta', color: 'pink' }
+  ],
+  linkDataArray: [
+    { key: -1, from: 'Epsilon', to: 'Zeta' },
+    { key: -2, from: 'Epsilon', to: 'Eta' },
+    { key: -3, from: 'Zeta', to: 'Zeta' },
+    { key: -4, from: 'Zeta', to: 'Theta' },
+    { key: -5, from: 'Theta', to: 'Epsilon' }
+  ]
+});
+```
+
 ## License
 
 This project is intended to be used alongside [GoJS](https://gojs.net/latest/index.html),