Editorial: add a diagram for storage model

Fixes #151.

Co-authored-by: Anne van Kesteren <[email protected]>
Co-authored-by: Domenic Denicola <[email protected]>

.gitignore

@@ -1,3 +1,5 @@
 /storage.spec.whatwg.org/
 /deploy.sh
 /storage.html
+/node_modules/
+/package-lock.json

Makefile

@@ -20,4 +20,5 @@ local: storage.bs
 
 deploy: storage.bs
 	curl --remote-name --fail https://resources.whatwg.org/build/deploy.sh
+	EXTRA_FILES="assets/*" \
 	bash ./deploy.sh

model-diagram.mmd

@@ -0,0 +1,12 @@
+erDiagram
+
+%% This is the source file for `assets/model-diagram.svg`.
+%% Build command: `npm i && npm run build-diagram`
+%% Don't forget to adjust the size in storage.bs when modifying this.
+%% (See viewBox attribute of the resulting SVG)
+
+"User agent" ||--|| "Storage shed" : "holds (local)"
+"Traversable navigable" ||--|| "Storage shed" : "holds (session)"
+"Storage shed" ||--o{ "Storage shelf" : "for each storage key"
+"Storage shelf" ||--|| "Storage bucket" : "holds (default)"
+"Storage bucket" ||--|{ "Storage bottle" : "for each storage endpoint"

package.json

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "description": "Builds and compresses the diagram",
+  "dependencies": {
+    "@mermaid-js/mermaid-cli": "^9.2.2",
+    "svgo": "^3.0.2"
+  },
+  "scripts": {
+    "mmdc": "mmdc -c scripts/mmdc.config.json -i model-diagram.mmd -o assets/model-diagram.svg",
+    "svgo": "svgo --config scripts/svgo.config.js -f assets -o assets/",
+    "build-diagram": "npm run mmdc && npm run svgo"
+  }
+}

scripts/mmdc.config.json

@@ -0,0 +1,6 @@
+{
+  "useMaxWidth": false,
+  "er": {
+    "fontSize": 16
+  }
+}

scripts/svgo.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  multipass: true,
+  js2svg: {
+    indent: 2,
+    pretty: true,
+  },
+};

storage.bs

@@ -129,6 +129,8 @@ either the <a>obtain a local storage bottle map</a> or the
 <p class=note>If you are defining a standard for such an API, consider filing an issue against this
 standard for assistance and review.
 
+<p><img src=assets/model-diagram.svg alt="Storage model diagram (described in the next paragraph)." width=434 height=815>
+
 <p>To isolate this data this standard defines a <a for=/>storage shed</a> which segments
 <a>storage shelves</a> by a <a>storage key</a>. A <a>storage shelf</a> in turn consists of a
 <a>storage bucket</a> and will likely consist of multiple <a>storage buckets</a> in the future to