Fix for PR comments

1. Made terminology and variable naming consistent (see README changes)
2. Fixed caught bugs in PR review
3. Right aligned inspection tab

Author: wenli-cai

workflow-trace-viewer/README.md

@@ -10,6 +10,14 @@ It can be run via Gradle using:
 ./gradlew :workflow-trace-viewer:run
 ```
 
+### Terminology
+
+**Trace**: A trace is a file — made up of frames — that contains the execution history of a Workflow. It includes information about render passes, how states have changed within workflows, and the specific props being passed through. The data collected to generate these should be in chronological order, and allows developers to step through the process easily.
+
+**Frame**: Essentially a "snapshot" of the current "state" of the whole Workflow tree. It contains relevant information about the changes in workflow states and how props are passed throughout.
+
+- Note that "snapshot" and "state" are different from `snapshotState` and `State`, which are idiomatic to the Workflow library.
+
 ### External Libraries
 
 [FileKit](https://github.com/vinceglb/FileKit) is an external library made to apply file operations on Kotlin and KMP projects. It's purpose in this app is to allow developers to upload their own json trace files. The motivation for its use is to quickly implement a file picker.

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/App.kt

@@ -9,12 +9,12 @@ import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
-import com.squareup.workflow1.traceviewer.model.WorkflowNode
+import com.squareup.workflow1.traceviewer.model.Node
 import com.squareup.workflow1.traceviewer.ui.InfoPanel
 import com.squareup.workflow1.traceviewer.ui.RenderDiagram
 import com.squareup.workflow1.traceviewer.ui.StateSelectTab
-import com.squareup.workflow1.traceviewer.utils.SandboxBackground
-import com.squareup.workflow1.traceviewer.utils.UploadFile
+import com.squareup.workflow1.traceviewer.util.SandboxBackground
+import com.squareup.workflow1.traceviewer.util.UploadFile
 import io.github.vinceglb.filekit.PlatformFile
 
 /**
@@ -24,40 +24,43 @@ import io.github.vinceglb.filekit.PlatformFile
 public fun App(
   modifier: Modifier = Modifier
 ) {
-  var selectedFile by remember { mutableStateOf<PlatformFile?>(null) }
-  var selectedNode by remember { mutableStateOf<WorkflowNode?>(null) }
-  var workflowTrace by remember { mutableStateOf<List<WorkflowNode>>(emptyList()) }
-  var snapshotIndex by remember { mutableIntStateOf(0) }
+  var selectedTraceFile by remember { mutableStateOf<PlatformFile?>(null) }
+  var selectedNode by remember { mutableStateOf<Node?>(null) }
+  var workflowFrames by remember { mutableStateOf<List<Node>>(emptyList()) }
+  var frameIndex by remember { mutableIntStateOf(0) }
 
   Box {
     // Main content
-    if (selectedFile != null) {
+    if (selectedTraceFile != null) {
       SandboxBackground {
         RenderDiagram(
-          file = selectedFile!!,
-          traceInd = snapshotIndex,
-          onFileParse = { workflowTrace = it },
+          traceFile = selectedTraceFile!!,
+          traceInd = frameIndex,
+          onFileParse = { workflowFrames = it },
           onNodeSelect = { selectedNode = it }
         )
       }
     }
 
     // Top trace selector row
     StateSelectTab(
-      trace = workflowTrace,
-      currentIndex = snapshotIndex,
-      onIndexChange = { snapshotIndex = it },
+      frames = workflowFrames,
+      currentIndex = frameIndex,
+      onIndexChange = { frameIndex = it },
       modifier = Modifier.align(Alignment.TopCenter)
     )
 
-    // Left side information panel
+    // Right side information panel
     InfoPanel(selectedNode)
 
-    // Bottom right upload button
+    // Bottom left upload button
     val onReset = {
       selectedNode = null
-      snapshotIndex = 0
+      frameIndex = 0
     }
-    UploadFile(onReset = onReset, onFileSelect = { selectedFile = it })
+    UploadFile(
+      onReset = onReset,
+      onFileSelect = { selectedTraceFile = it }
+    )
   }
 }

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/model/WorkflowNode.kt

@@ -7,8 +7,8 @@ package com.squareup.workflow1.traceviewer.model
  *
  * TBD what more metadata should be involved with each node, e.g. (props, states, # of render passes)
  */
-public data class WorkflowNode(
+public class Node(
   val id: String,
   val name: String,
-  val children: List<WorkflowNode>
+  val children: List<Node>
 )

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/StateSelectTab.kt renamed to workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/FrameSelectTab.kt

@@ -12,14 +12,14 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.unit.dp
-import com.squareup.workflow1.traceviewer.model.WorkflowNode
+import com.squareup.workflow1.traceviewer.model.Node
 
 /**
  * A trace tab selector that allows devs to switch between different states within the provided trace.
  */
 @Composable
 public fun StateSelectTab(
-  trace: List<WorkflowNode>,
+  frames: List<Node>,
   currentIndex: Int,
   onIndexChange: (Int) -> Unit,
   modifier: Modifier = Modifier
@@ -36,7 +36,7 @@ public fun StateSelectTab(
         .padding(8.dp),
       state = state
     ) {
-      items(trace.size) { index ->
+      items(frames.size) { index ->
         Text(
           text = "State ${index + 1}",
           color = if (index == currentIndex) Color.Black else Color.LightGray,

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/WorkflowInfoPanel.kt

@@ -3,6 +3,7 @@ package com.squareup.workflow1.traceviewer.ui
 import androidx.compose.foundation.background
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxHeight
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
@@ -23,7 +24,7 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
-import com.squareup.workflow1.traceviewer.model.WorkflowNode
+import com.squareup.workflow1.traceviewer.model.Node
 
 /**
  * A panel that displays information about the selected workflow node.
@@ -33,19 +34,14 @@ import com.squareup.workflow1.traceviewer.model.WorkflowNode
  */
 @Composable
 public fun InfoPanel(
-  selectedNode: WorkflowNode?,
+  selectedNode: Node?,
   modifier: Modifier = Modifier
 ) {
+  // This row is ordered RTL
   Row {
-    var panelOpen by remember { mutableStateOf(false) }
+    Spacer(modifier = Modifier.weight(1f))
 
-    // based on open/close, display the node details (Column)
-    if (panelOpen) {
-      PanelDetails(
-        selectedNode,
-        Modifier.fillMaxWidth(.35f)
-      )
-    }
+    var panelOpen by remember { mutableStateOf(false) }
 
     IconButton(
       onClick = { panelOpen = !panelOpen },
@@ -60,39 +56,43 @@ public fun InfoPanel(
         modifier = Modifier
       )
     }
+
+    // based on open/close, display the node details (Column)
+    if (panelOpen) {
+      PanelDetails(
+        selectedNode,
+        Modifier.fillMaxWidth(.35f)
+      )
+    }
   }
 }
 
 /**
- * The text details of the selected node. This should be closely coupled with the [WorkflowNode]
+ * The text details of the selected node. This should be closely coupled with the [Node]
  * data class to see what information should be displayed.
  */
 @Composable
 private fun PanelDetails(
-  node: WorkflowNode?,
+  node: Node?,
   modifier: Modifier = Modifier
 ) {
   Column(
-    modifier
+    modifier = modifier
       .fillMaxHeight()
       .background(Color.LightGray)
+      .padding(8.dp),
+    horizontalAlignment = Alignment.CenterHorizontally
   ) {
     if (node == null) {
       Text("No node selected")
       return@Column
     }
 
-    Column(
-      modifier = Modifier
-        .padding(8.dp),
-      horizontalAlignment = Alignment.CenterHorizontally
-    ) {
-      Text("only visible with a node selected")
-      Text(
-        text = "This is a node panel for ${node.name}",
-        fontSize = 20.sp,
-        modifier = Modifier.padding(8.dp)
-      )
-    }
+    Text("only visible with a node selected")
+    Text(
+      text = "This is a node panel for ${node.name}",
+      fontSize = 20.sp,
+      modifier = Modifier.padding(8.dp)
+    )
   }
 }

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/ui/WorkflowTree.kt

@@ -19,8 +19,8 @@ import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.unit.dp
-import com.squareup.workflow1.traceviewer.model.WorkflowNode
-import com.squareup.workflow1.traceviewer.utils.fetchTrace
+import com.squareup.workflow1.traceviewer.model.Node
+import com.squareup.workflow1.traceviewer.util.fetchTrace
 import io.github.vinceglb.filekit.PlatformFile
 
 /**
@@ -29,22 +29,23 @@ import io.github.vinceglb.filekit.PlatformFile
  */
 @Composable
 public fun RenderDiagram(
-  file: PlatformFile,
+  traceFile: PlatformFile,
   traceInd: Int,
-  onFileParse: (List<WorkflowNode>) -> Unit,
-  onNodeSelect: (WorkflowNode) -> Unit,
+  onFileParse: (List<Node>) -> Unit,
+  onNodeSelect: (Node) -> Unit,
 ) {
-  var workflowNodes by remember { mutableStateOf<List<WorkflowNode>>(emptyList()) }
+  var nodes by remember { mutableStateOf<List<Node>>(emptyList()) }
   var isLoading by remember { mutableStateOf(true) }
 
-  LaunchedEffect(file) {
-    workflowNodes = fetchTrace(file)
-    onFileParse(workflowNodes)
+  LaunchedEffect(traceFile) {
+    isLoading = true
+    nodes = fetchTrace(traceFile)
+    onFileParse(nodes)
     isLoading = false
   }
 
   if (!isLoading) {
-    DrawTree(workflowNodes[traceInd], onNodeSelect)
+    DrawTree(nodes[traceInd], onNodeSelect)
   }
 
   // TODO: catch errors and display UI here
@@ -56,8 +57,8 @@ public fun RenderDiagram(
  */
 @Composable
 private fun DrawTree(
-  node: WorkflowNode,
-  onNodeSelect: (WorkflowNode) -> Unit,
+  node: Node,
+  onNodeSelect: (Node) -> Unit,
   modifier: Modifier = Modifier,
 ) {
   Column(
@@ -87,8 +88,8 @@ private fun DrawTree(
  */
 @Composable
 private fun DrawNode(
-  node: WorkflowNode,
-  onNodeSelect: (WorkflowNode) -> Unit,
+  node: Node,
+  onNodeSelect: (Node) -> Unit,
 ) {
   Box(
     modifier = Modifier

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/util/JsonParser.kt

@@ -0,0 +1,42 @@
+package com.squareup.workflow1.traceviewer.util
+
+import androidx.compose.ui.Modifier
+import com.squareup.moshi.JsonAdapter
+import com.squareup.moshi.JsonDataException
+import com.squareup.moshi.Moshi
+import com.squareup.moshi.Types
+import com.squareup.moshi.kotlin.reflect.KotlinJsonAdapterFactory
+import com.squareup.workflow1.traceviewer.model.Node
+import io.github.vinceglb.filekit.PlatformFile
+import io.github.vinceglb.filekit.readString
+import java.io.IOException
+
+/**
+ * Parses the data from the given file and initiates the workflow tree
+ */
+public suspend fun fetchTrace(
+  file: PlatformFile?,
+  modifier: Modifier = Modifier
+): List<Node> {
+  val jsonString = file?.readString()
+  return jsonString?.let { parseTrace(it) } ?: emptyList()
+}
+
+/**
+ * Parses a JSON string into [Node] with Moshi adapters. Moshi automatically throws JsonDataException
+ * and IOException
+ * @throws JsonDataException malformed JSON data or an error reading.
+ * @throws IOException JSON is correct, but mismatch between class and JSON structure.
+ */
+public fun parseTrace(
+  json: String
+): List<Node> {
+  val moshi = Moshi.Builder()
+    .add(KotlinJsonAdapterFactory())
+    .build()
+
+  val workflowList = Types.newParameterizedType(List::class.java, Node::class.java)
+  val workflowAdapter: JsonAdapter<List<Node>> = moshi.adapter(workflowList)
+  val root = workflowAdapter.fromJson(json) ?: emptyList()
+  return root
+}

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/utils/SandboxBackground.kt renamed to workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/util/SandboxBackground.kt

@@ -1,4 +1,4 @@
-package com.squareup.workflow1.traceviewer.utils
+package com.squareup.workflow1.traceviewer.util
 
 import androidx.compose.foundation.gestures.awaitEachGesture
 import androidx.compose.foundation.gestures.detectDragGestures

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/utils/UploadFile.kt renamed to workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/util/UploadFile.kt

@@ -1,4 +1,4 @@
-package com.squareup.workflow1.traceviewer.utils
+package com.squareup.workflow1.traceviewer.util
 
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
@@ -39,10 +39,11 @@ public fun UploadFile(
       onReset()
       onFileSelect(it)
     }
+
     Button(
       onClick = { launcher.launch() },
       modifier = Modifier
-        .align(Alignment.BottomEnd),
+        .align(Alignment.BottomStart),
       shape = CircleShape,
       colors = buttonColors(Color.Black)
     ) {