unconed · sritchie · Jan 12, 2023 · Jan 12, 2023 · Jan 12, 2023 · sritchie
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,6 +1,14 @@
-### MathBox Changelog
+## MathBox Changelog
+
+### [unreleased]
+
+- Add a `root` function to the API with the same 2-argument interface as all
+  other primitives. The map provided to the first argument is passed to
+  `mathbox.set`, and the second argument is passed to `mathbox.bind`. `root`
+  returns the root node.
 
 ### 2.2.1
+
 - Add Typescript support for live properties and `bind`. [#43](https://github.com/unconed/mathbox/pull/43)
 
 ### 2.2.0

diff --git a/docs/intro.md b/docs/intro.md
@@ -82,9 +82,9 @@ view
     width: 3,
   })
   .grid({
-    width: 2,  
+    width: 2,
     divideX: 20,
-    divideY: 10,        
+    divideY: 10,
   });
 ```
 
@@ -110,7 +110,7 @@ mathbox.select('axis').set('color', 'black');
 As the on-screen size of elements depends on the position of the camera, we can calibrate our units by setting the `focus` on the `<root>` to match the camera distance:
 
 ```javascript
-mathbox.set('focus', 3);
+mathbox.root({focus: 3});
 ```
 
 Which gives us:

diff --git a/examples/test/root.html b/examples/test/root.html
@@ -0,0 +1,95 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>MathBox - Empty</title>
+    <script
+      type="text/javascript"
+      src="https://cdn.jsdelivr.net/npm/[email protected]/build/three.min.js"
+    ></script>
+    <script
+      type="text/javascript"
+      src="https://cdn.jsdelivr.net/npm/[email protected]/examples/js/controls/OrbitControls.js"
+    ></script>
+    <script
+      type="text/javascript"
+      src="https://cdn.jsdelivr.net/npm/[email protected]/examples/js/controls/TrackballControls.js"
+    ></script>
+
+    <!--
+      - a minified version mathbox.min.js is also available;
+      - recommend using a specific version (not @latest) in public sites
+    -->
+    <script
+      type="text/javascript"
+      src="https://cdn.jsdelivr.net/npm/mathbox@latest/build/bundle/mathbox.js"
+    ></script>
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/mathbox@latest/build/mathbox.css"
+    />
+    <meta name="viewport" content="initial-scale=1, maximum-scale=1" />
+  </head>
+  <body>
+    <script>
+      var mathbox = MathBox.mathBox({
+        plugins: ["core", "controls", "cursor", "mathbox"],
+        controls: {
+          klass: THREE.OrbitControls,
+        },
+      });
+      if (mathbox.fallback) throw "WebGL not supported";
+
+      var three = mathbox.three;
+      three.renderer.setClearColor(new THREE.Color(0xffffff), 1.0);
+      var camera = mathbox.camera({
+        proxy: true,
+        position: [0, 0, 3],
+      });
+      var view = mathbox.cartesian({
+        range: [
+          [-2, 2],
+          [-1, 1],
+        ],
+        scale: [2, 1],
+      });
+      view
+        .axis({
+          axis: 1,
+          width: 3,
+        })
+        .axis({
+          axis: 2,
+          width: 3,
+        })
+        .grid({
+          width: 2,
+          divideX: 20,
+          divideY: 10,
+        });
+
+      // Set a static property and a dynamic property.
+      mathbox.root(
+        { id: "mathbox-root" },
+        {
+          focus: (time, delta) => 5 * Math.sin(time * 0.5),
+        }
+      );
+
+      // Add some data
+      var data = view.interval({
+        expr: function (emit, x, i, t) {
+          emit(x, Math.sin(x + t));
+        },
+        width: 64,
+        channels: 2,
+      });
+
+      // Draw a curve
+      var curve = view.line({
+        width: 5,
+        color: "#3090FF",
+      });
+    </script>
+  </body>
+</html>
diff --git a/src/stage/api.js b/src/stage/api.js
@@ -43,6 +43,11 @@ export class API {
         this[type] = (options, binds) => this.add(type, options, binds);
       }
     }
+    this["root"] = (options, binds) => {
+      root.set(options);
+      root.bind(binds);
+      return this._reset();
+    };
   }
 
   select(selector) {
@@ -166,7 +171,7 @@ export class API {
   }
   _reset() {
     let left;
-    return (left = this._up != null ? this._up.reset() : undefined) != null
+    return (left = this._up != null ? this._up._reset() : undefined) != null
       ? left
       : this;
   }

diff --git a/test/bind.spec.ts b/test/bind.spec.ts
@@ -70,7 +70,7 @@ describe("live properties", () => {
 
     const size1 = p.get("size")
     const opacity1 = p.get("opacity")
-    expect(Math.abs(size1 - 20.5)).toBeLessThan(0.2)
-    expect(Math.abs(opacity1 - 0.5)).toBeLessThan(0.2)
+    expect(Math.abs(size1 - 20.5)).toBeLessThan(0.3)
+    expect(Math.abs(opacity1 - 0.5)).toBeLessThan(0.3)
   })
 });
diff --git a/test/primitives/types/base/root.js b/test/primitives/types/base/root.js
@@ -0,0 +1,22 @@
+import * as MB from "../../../../src";
+
+describe("primitives.types.base.root", () => {
+  it("returns the root from any selection", async () => {
+    const mathbox = MB.mathBox();
+    const root = mathbox.cartesian().root();
+
+    expect(root).toBe(mathbox);
+  });
+
+  it("reacts to changes in properties", async () => {
+    const mathbox = MB.mathBox();
+    const root = mathbox.root();
+
+    // default focus
+    expect(mathbox.get("focus")).toBe(1);
+
+    // set via root and see the change reflected in mathbox.
+    mathbox.root({ focus: 10 });
+    expect(mathbox.get("focus")).toBe(10);
+  });
+});