Update documentation

QubitPi · Nov 22, 2023 · 533760d · 533760d
1 parent 01d3a7b
commit 533760d
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 5 deletions.
diff --git a/docs/modules/ROOT/pages/neo4j-arc/index.adoc b/docs/modules/ROOT/pages/neo4j-arc/index.adoc
@@ -99,8 +99,6 @@ export default function MyGraphComponent(): JSX.Element {
 
 = Neo4J Browser Internals
 
-neo4j-arc does not genreate node ID. It is 
-
 The Neo4J Browser is logically composed of 2 parts:
 
 . The neo4j-arc, which is the current part we are discussing
@@ -117,6 +115,15 @@ The Neo4J Browser is logically composed of 2 parts:
    Note: the displayed `<id>` is the value of NodeMode.id
    ====
 
+   CAUTION
+   ====
+
+   neo4j-arc does not generate or manage node/rel ID. Any xref:operations/on-canvas-operations.adoc[on-canvas operation]
+   generates nodes/rel with *transient ID* only. Any node/rel ID that is to be persisted needs to be generated and
+   managed by external logics, such as database auto-ID or library user
+
+   ====
+
 . A user-interface that combines the graph rendering (supported by the graphing module), database, and user
    interaction together
 

diff --git a/docs/modules/ROOT/pages/operations/on-canvas-operations.adoc b/docs/modules/ROOT/pages/operations/on-canvas-operations.adoc
@@ -8,7 +8,27 @@
 
 *Double clicking the white area* on canvas will automatically generate a new node with
 
-1. an auto-incremented ID, i.e. (the max ID of nodes on canvas) + 1
+1. a transient ID prefixed with "transient-" followed by a random string. For example "transient-rxnnzr6t4x"
+
+   [NOTE]
+   ====
+
+   The reason that the ID being transient is due to the fact that this ID won't be persisted into database. Refreshing
+   the browser will replace this transient ID with a database-generated ID (in the form of a number, such as 65).
+
+   Normally, neo4j-browser feeds into neo4j-arc, which is the graphing module of neo4j-browser, with a set of
+   fully-hydrated set of nodes and relationships. This results in the design in neo4j-arc which is: to render a node or
+   relationship, the ID of it must be provided (i.e. a required argument to node/rel constructor).
+
+   Generating a new node by double-clicking, however, is an operation manged by neo4j-arc, which by design is not
+   responsible for generating and managing node/relationship ID's. But to implement the "realtime editing" effect, the
+   new node/rel ID has to be genreated at the beginning. 
+
+   To resolve the conflict between original neo4j-browser design and on-canvas operation, any node/rel generated
+   "on-canvas" will have this transient ID.
+
+   ====
+
 2. a label of "Undefined"
 3. the node caption of "New Node"
 

diff --git a/src/neo4j-arc/graph-visualization/GraphVisualizer/Graph/GraphEventHandlerModel.ts b/src/neo4j-arc/graph-visualization/GraphVisualizer/Graph/GraphEventHandlerModel.ts
@@ -245,7 +245,7 @@ export class GraphEventHandlerModel {
 
   onCanvasDblClicked(): void {
     const transientId: string =
-      'transient' + Math.random().toString(36).slice(2)
+      'transient-' + Math.random().toString(36).slice(2)
 
     this.graph.addNodes([
       new NodeModel(
@@ -298,7 +298,7 @@ export class GraphEventHandlerModel {
       this.altCreatedRelTargetNode = node
 
       const transientId: string =
-        'transient' + Math.random().toString(36).slice(2)
+        'transient-' + Math.random().toString(36).slice(2)
 
       const altCreatedRel: RelationshipModel = new RelationshipModel(
         transientId,