feat: add Imperaitive Handle to public API

apis/nucleus/src/__tests__/viz.test.js

@@ -20,6 +20,7 @@ describe('viz', () => {
   let setSnPlugins;
   let takeSnapshot;
   let exportImage;
+  let getImperativeHandle;
   let convertToMock;
 
   beforeAll(() => {
@@ -29,13 +30,17 @@ describe('viz', () => {
     setSnPlugins = jest.fn();
     takeSnapshot = jest.fn();
     exportImage = jest.fn();
+    getImperativeHandle = jest.fn(async () => ({
+      api: 'api',
+    }));
     cellRef = {
       current: {
         setSnOptions,
         setSnContext,
         setSnPlugins,
         takeSnapshot,
         exportImage,
+        getImperativeHandle,
       },
     };
     glue = jest.fn().mockReturnValue([unmountMock, cellRef]);
@@ -101,11 +106,14 @@ describe('viz', () => {
     test('should throw if already mounted', async () => {
       try {
         mounted = api.__DO_NOT_USE__.mount('element');
+        /*
+        // This code never runs, as these tests are meant to run together, don't want to mess more with it
         const { onMount } = glue.mock.lastCall[0];
         onMount();
         await mounted;
         const result = await api.__DO_NOT_USE__.mount.bind('element2');
         await result();
+        */
       } catch (error) {
         expect(error.message).toBe('Already mounted');
       }
@@ -150,7 +158,28 @@ describe('viz', () => {
       const opts = {};
       api.__DO_NOT_USE__.options(opts);
       await mounted;
-      expect(cellRef.current.setSnOptions).toHaveBeenCalledWith(opts);
+      const args = cellRef.current.setSnOptions.mock.lastCall[0];
+      expect(args.onInitialRender).toBeInstanceOf(Function);
+      expect(Object.keys(args).length).toEqual(1);
+    });
+
+    test('should set extended sn options', async () => {
+      const opts = { myops: 'myopts' };
+      api.__DO_NOT_USE__.options(opts);
+      await mounted;
+      const args = cellRef.current.setSnOptions.mock.lastCall[0];
+      expect(args.onInitialRender).toBeInstanceOf(Function);
+      expect(args.myops).toEqual('myopts');
+      expect(Object.keys(args).length).toEqual(2);
+    });
+
+    test('should override and call onIntialRender', async () => {
+      const opts = { myops: 'myopts', onInitialRender: jest.fn() };
+      api.__DO_NOT_USE__.options(opts);
+      await mounted;
+      const args = cellRef.current.setSnOptions.mock.lastCall[0];
+      args.onInitialRender();
+      expect(opts.onInitialRender).toHaveBeenCalled();
     });
   });
 
@@ -199,4 +228,16 @@ describe('viz', () => {
       expect(props).toBe('props');
     });
   });
+
+  describe('getImperativeHandle', () => {
+    test('should await the rendering and then call cell', async () => {
+      const opts = { myops: 'myopts', onInitialRender: jest.fn() };
+      api.__DO_NOT_USE__.options(opts);
+      await mounted;
+      const args = cellRef.current.setSnOptions.mock.lastCall[0];
+      args.onInitialRender();
+      const handle = await api.getImperativeHandle();
+      expect(handle.api).toEqual('api');
+    });
+  });
 });

apis/nucleus/src/components/Cell.jsx

@@ -457,6 +457,12 @@ const Cell = forwardRef(
         },
         setSnOptions,
         setSnPlugins,
+        getImperativeHandle() {
+          if (state.sn?.component && typeof state.sn.component.getImperativeHandle === 'function') {
+            return state.sn.component.getImperativeHandle();
+          }
+          return {};
+        },
         async takeSnapshot() {
           const { width, height } = cellRect;
 

apis/nucleus/src/viz.js

@@ -12,29 +12,46 @@ export default function viz({ model, halo, initialError, onDestroy = async () =>
   let cellRef = null;
   let mountedReference = null;
   let onMount = null;
+  let onRender = null;
   const mounted = new Promise((resolve) => {
     onMount = resolve;
   });
 
+  const rendered = new Promise((resolve) => {
+    onRender = resolve;
+  });
+
+  const createOnInitialRender = (override) => () => {
+    override && override();
+    onRender();
+  };
+
   let initialSnOptions = {};
   let initialSnPlugins = [];
 
   const emitter = new EventEmitter();
 
   const setSnOptions = async (opts) => {
+    const override = opts.onInitialRender;
     if (mountedReference) {
       (async () => {
         await mounted;
         cellRef.current.setSnOptions({
           ...initialSnOptions,
           ...opts,
+          ...{
+            onInitialRender: createOnInitialRender(override),
+          },
         });
       })();
     } else {
       // Handle setting options before mount
       initialSnOptions = {
         ...initialSnOptions,
         ...opts,
+        ...{
+          onInitialRender: createOnInitialRender(override),
+        },
       };
     }
   };
@@ -130,6 +147,14 @@ export default function viz({ model, halo, initialError, onDestroy = async () =>
     removeListener(eventName, listener) {
       emitter.removeListener(eventName, listener);
     },
+    /**
+     * Gets the specific api that a Viz exposes.
+     * @returns {Promise<object>} object that contains the internal Viz api.
+     */
+    async getImperativeHandle() {
+      await rendered;
+      return cellRef.current.getImperativeHandle();
+    },
     // ===== unexposed experimental API - use at own risk ======
     __DO_NOT_USE__: {
       mount(element) {

apis/stardust/api-spec/spec.json

@@ -476,6 +476,37 @@
         "// it is up to you use and implement the provided options\nimport { useOptions } from '@nebula.js/stardust';\nimport { useEffect } from '@nebula.js/stardust';\n// ...\nconst options = useOptions();\nuseEffect(() => {\n  if (!options.showNavigation) {\n    // hide navigation\n  } else {\n    // show navigation\n  }\n}, [options.showNavigation]);"
       ]
     },
+    "useImperativeHandle": {
+      "description": "This is an empty object by default, but enables you to provide a custom API of your visualization to\nmake it possible to control after it has been rendered.\n\nYou can only use this hook once, calling it more than once is considered an error.",
+      "templates": [
+        {
+          "name": "T"
+        }
+      ],
+      "kind": "function",
+      "params": [
+        {
+          "name": "factory",
+          "kind": "function",
+          "params": [],
+          "returns": {
+            "type": "T"
+          }
+        },
+        {
+          "name": "deps",
+          "optional": true,
+          "kind": "array",
+          "items": {
+            "type": "any"
+          }
+        }
+      ],
+      "examples": [
+        "import { useImperativeHandle } form '@nebula.js/stardust';\n// ...\nuseImperativeHandle(() => ({\n  resetZoom() {\n    setZoomed(false);\n  }\n}));",
+        "// when embedding the visualization, you can get a handle to this API\n// and use it to control the visualization\nconst ctl = await embed(app).render({\n  element,\n  type: 'my-chart',\n});\nctl.getImperativeHandle().resetZoom();"
+      ]
+    },
     "onTakeSnapshot": {
       "description": "Registers a callback that is called when a snapshot is taken.",
       "kind": "function",
@@ -1281,6 +1312,20 @@
               "params": []
             }
           ]
+        },
+        "getImperativeHandle": {
+          "description": "Gets the specific api that a Viz exposes.",
+          "kind": "function",
+          "params": [],
+          "returns": {
+            "description": "object that contains the internal Viz api.",
+            "type": "Promise",
+            "generics": [
+              {
+                "type": "object"
+              }
+            ]
+          }
         }
       },
       "examples": [

apis/stardust/types/index.d.ts

@@ -156,6 +156,16 @@ export function useInteractionState(): stardust.Interactions;
  */
 export function useOptions(): object;
 
+/**
+ * This is an empty object by default, but enables you to provide a custom API of your visualization to
+ * make it possible to control after it has been rendered.
+ * 
+ * You can only use this hook once, calling it more than once is considered an error.
+ * @param factory
+ * @param deps
+ */
+export function useImperativeHandle<T>(factory: ()=>T, deps?: any[]): void;
+
 /**
  * Registers a callback that is called when a snapshot is taken.
  * @param snapshotCallback
@@ -405,6 +415,11 @@ declare namespace stardust {
          */
         removeListener(eventName: string, listener: ()=>void): void;
 
+        /**
+         * Gets the specific api that a Viz exposes.
+         */
+        getImperativeHandle(): Promise<object>;
+
     }
 
     interface Flags {

apis/supernova/src/hooks.js

@@ -983,15 +983,11 @@ export function useOptions() {
 }
 
 /**
- * TODO before making public - expose getImperativeHandle on Viz
- * Exposes an API to the external environment.
- *
  * This is an empty object by default, but enables you to provide a custom API of your visualization to
  * make it possible to control after it has been rendered.
  *
  * You can only use this hook once, calling it more than once is considered an error.
  * @entry
- * @private
  * @template T
  * @param {function():T} factory
  * @param {Array<any>=} deps