From 657413b5ad5657efb57cc3f8a0a9204bf90f9037 Mon Sep 17 00:00:00 2001
From: Alexander Wang <alex@terrastruct.com>
Date: Sat, 29 Jul 2023 14:27:12 -0700
Subject: [PATCH] d2oracle updates

---
 docs/tour/api.md                     | 51 ++++++++++++++++++++++------
 static/bespoke-d2/chicken.d2         |  1 +
 static/bespoke-d2/imports-nested.d2  |  1 +
 static/bespoke-d2/lotr.d2            |  1 +
 static/bespoke-d2/tiktok.d2          |  1 +
 static/bespoke-d2/wcc.d2             |  3 +-
 static/d2/imports-nested-serviceB.d2 |  1 +
 7 files changed, 47 insertions(+), 12 deletions(-)

diff --git a/docs/tour/api.md b/docs/tour/api.md
index 0103e898..5a599aa5 100644
--- a/docs/tour/api.md
+++ b/docs/tour/api.md
@@ -16,11 +16,13 @@ All functions in `d2oracle` are pure: they do not mutate the original graph, the
 Create a shape or connection.
 
 ```go
-func Create(g *d2graph.Graph, key string) (newG *d2graph.Graph, newKey string, _ error)
+func Create(g *d2graph.Graph, boardPath []string, key string) (newG *d2graph.Graph, newKey string, _ error)
 ```
 
 **Parameters**:
 - `g`: D2 graph
+- `boardPath`: Path of the board to modify. Only applicable to multi-board diagrams;
+  otherwise, pass in `nil`.
 - `key`: The ID of the shape or connection being created
 
 **Return**:
@@ -34,7 +36,7 @@ for example, if you create a connection between 2 shapes that don't exist, they
 
 ```go
 // This call creates 6 shapes and 1 connection
-d2oracle.Create(g, "a.b.c -> x.y.z")
+d2oracle.Create(g, nil, "a.b.c -> x.y.z")
 ```
 
 If you call `Create` twice with the same shape ID, you will get an
@@ -45,18 +47,35 @@ error. If you call it twice with the same edge ID, you will create another edge.
 For shapes, there may be an ID collision. `Create` appends a counter in this case.
 ```go
 // newKey = "a"
-g, newKey, _ = d2oracle.Create(g, "a")
+g, newKey, _ = d2oracle.Create(g, nil, "a")
 // newKey = "a 2"
-_, newKey, _ = d2oracle.Create(g, "a")
+_, newKey, _ = d2oracle.Create(g, nil, "a")
 ```
 
 
 Connection IDs include the index.
 ```go
 // newKey = "(a -> b[0])"
-g, newKey, _ = d2oracle.Create(g, "a -> b")
+g, newKey, _ = d2oracle.Create(g, nil, "a -> b")
 // newKey = "(a -> b[1])"
-_, newKey, _ = d2oracle.Create(g, "a -> b")
+_, newKey, _ = d2oracle.Create(g, nil, "a -> b")
+```
+
+If you have a multi-board diagram like so:
+
+```d2
+x
+
+layers: {
+  y: {}
+}
+```
+
+```go
+// This creates a shape "a" at the root
+g, _ = d2oracle.Create(g, nil, "a")
+// This creates a shape "a" at layer "y"
+g, _ = d2oracle.Create(g, []string{"y"}, "a")
 ```
 
 ## Set
@@ -64,11 +83,13 @@ _, newKey, _ = d2oracle.Create(g, "a -> b")
 Set an attribute on a shape or connection.
 
 ```go
-func Set(g *d2graph.Graph, key string, tag, value *string) (newG *d2graph.Graph, _ error)
+func Set(g *d2graph.Graph, boardPath []string, key string, tag, value *string) (newG *d2graph.Graph, _ error)
 ```
 
 **Parameters**:
 - `g`: D2 graph
+- `boardPath`: Path of the board to modify. Only applicable to multi-board diagrams;
+  otherwise, pass in `nil`.
 - `key`: The identifier for the attribute
 - `tag`: The language tag. This is only non-nil when text values are set that can be
   different languages, e.g. a code snippet value.
@@ -117,16 +138,20 @@ that object's primary value (usually label).
 g, _ = d2oracle.Set(g, "a", "md", "# I am A")
 ```
 
+
+
 ## Delete
 
 Delete a shape or connection.
 
 ```go
-func Delete(g *d2graph.Graph, key string) (newG *d2graph.Graph, _ error)
+func Delete(g *d2graph.Graph, boardPath []string, key string) (newG *d2graph.Graph, _ error)
 ```
 
 **Parameters**:
 - `g`: D2 graph
+- `boardPath`: Path of the board to modify. Only applicable to multi-board diagrams;
+  otherwise, pass in `nil`.
 - `key`: The identifier for the shape or connection
 
 **Return**:
@@ -149,11 +174,13 @@ Note that the ID != label. If you want to change the label, use `Set`.
 :::
 
 ```go
-func Rename(g *d2graph.Graph, key, newName string) (newG *d2graph.Graph, err error)
+func Rename(g *d2graph.Graph, boardPath []string, key, newName string) (newG *d2graph.Graph, err error)
 ```
 
 **Parameters**:
 - `g`: D2 graph
+- `boardPath`: Path of the board to modify. Only applicable to multi-board diagrams;
+  otherwise, pass in `nil`.
 - `key`: The current identifier for the shape or connection
 - `newName`: The new identifier for the shape or connection
 
@@ -173,7 +200,7 @@ g, _ = d2oracle.Rename(g, "a", "z)
 Move a given shape or connection to a different container.
 
 ```go
-func Move(g *d2graph.Graph, key, newKey string) (newG *d2graph.Graph, err error)
+func Move(g *d2graph.Graph, boardPath []string, key, newKey string) (newG *d2graph.Graph, err error)
 ```
 
 :::info
@@ -182,6 +209,8 @@ If you give two keys of the same scope (e.g. "a" to "b"), it's the same as `Rena
 
 **Parameters**:
 - `g`: D2 graph
+- `boardPath`: Path of the board to modify. Only applicable to multi-board diagrams;
+  otherwise, pass in `nil`.
 - `key`: The current identifier for the shape or connection
 - `newKey`: The new identifier for the shape or connection
 
@@ -226,7 +255,7 @@ y
 x -> z
 ```
 
-`deltas, err := MoveIDDeltas(g, "x", "y.x")`
+`deltas, err := MoveIDDeltas(g, nil, "x", "y.x")`
 
 `deltas`:
 ```json
diff --git a/static/bespoke-d2/chicken.d2 b/static/bespoke-d2/chicken.d2
index b8983c7a..dae4a813 100644
--- a/static/bespoke-d2/chicken.d2
+++ b/static/bespoke-d2/chicken.d2
@@ -3,6 +3,7 @@ Chicken's plan: {
   near: top-center
   shape: text
 }
+
 steps: {
   1: {
     Approach road
diff --git a/static/bespoke-d2/imports-nested.d2 b/static/bespoke-d2/imports-nested.d2
index 7b6b7112..41a8fab1 100644
--- a/static/bespoke-d2/imports-nested.d2
+++ b/static/bespoke-d2/imports-nested.d2
@@ -1,5 +1,6 @@
 serviceA -> serviceB
 serviceB.link: layers.serviceB
+
 layers: {
   serviceB: @../d2/imports-nested-serviceB
 }
diff --git a/static/bespoke-d2/lotr.d2 b/static/bespoke-d2/lotr.d2
index 206e4762..946db996 100644
--- a/static/bespoke-d2/lotr.d2
+++ b/static/bespoke-d2/lotr.d2
@@ -14,6 +14,7 @@ layers: {
     go deeper: {
       link: layers.moria
     }
+    
     layers: {
       moria: {
         dwarves
diff --git a/static/bespoke-d2/tiktok.d2 b/static/bespoke-d2/tiktok.d2
index dba7a45f..55cc76bb 100644
--- a/static/bespoke-d2/tiktok.d2
+++ b/static/bespoke-d2/tiktok.d2
@@ -20,6 +20,7 @@ layers: {
     Virginia data center <-> Hong Kong data center
     Virginia data center.link: layers.virginia
     Hong Kong data center.link: layers.hongkong
+    
     layers: {
       virginia: {
         direction: right
diff --git a/static/bespoke-d2/wcc.d2 b/static/bespoke-d2/wcc.d2
index bd9dcdf2..f4759379 100644
--- a/static/bespoke-d2/wcc.d2
+++ b/static/bespoke-d2/wcc.d2
@@ -34,6 +34,7 @@ layers: {
       link: steps.1
       style.font-size: 24
     }
+    
     steps: {
       1: {
         titled: Earn pre-requisite titles (IM)
@@ -149,7 +150,7 @@ layers: {
 
     best of 14 games -> tiebreaks: if needed
     tiebreaks.link: layers.tiebreaks
-
+    
     layers: {
       tiebreaks: {
         description: |md
diff --git a/static/d2/imports-nested-serviceB.d2 b/static/d2/imports-nested-serviceB.d2
index 3a534154..73d41997 100644
--- a/static/d2/imports-nested-serviceB.d2
+++ b/static/d2/imports-nested-serviceB.d2
@@ -9,6 +9,7 @@ aws vault.key -> data
 aws vault.token -> data
 stripe.customer id -> data
 data.link: layers.data
+
 layers: {
   data: @imports-nested-data
 }