Add jlab_link script to link local changes into development Jupyterlab

docs/md/development.md

@@ -91,6 +91,34 @@ To install this specific version of Emscripten:
 ./emsdk install 2.0.6
 ```
 
+### `perspective-jupyterlab`
+
+To install the Jupyterlab plugin from your local working directory, give
+`jupyter labextension install` the path to the `perspective-jupyterlab`
+package:
+
+```bash
+jupyter labextension install ./packages/perspective-jupyterlab
+```
+
+Afterwards, you should see it listed as a "local extension" when you run
+`jupyter labextension list`.
+
+Because we do not inline Perspective into the Jupyterlab plugin, your local
+changes will not show up in Jupyterlab **unless** you use `yarn link`
+according to the directions below:
+
+1. Ensure that your Jupyterlab is built by running `jupyter lab build`.
+2. Inside each directory in `packages`, run [`yarn link`](https://classic.yarnpkg.com/en/docs/cli/link).
+This will create a symlink to your local build that we will use inside Jupyterlab.
+3. From the Perspective root, run `yarn jlab_link`. This is a script that will
+find your Jupyterlab installation and tell Jupyterlab to use these symlinks
+when it looks for Perspective packages, instead of fetching them from NPM.
+4. When you make a local change, make sure you run `yarn build` **and**
+`jupyter lab build` so that it fetches the newest changes.
+5. Whenever you run `jupyter lab clean`, you will need to run `yarn jlab_link`
+again to re-register the symlinks.
+
 ## `perspective-python`
 
 To build the Python library, first configure your project to Python via

docs/md/python.md

@@ -68,8 +68,10 @@ pip install perspective-python
 `PerspectiveWidget` is a JupyterLab widget that implements the same API as
 `<perspective-viewer>`, allowing for fast, intuitive
 transformations/visualizations of various data formats within JupyterLab.
-To use it, make sure you have installed `perspective-python`
-and then install the extension from the Jupyter lab extension directory
+
+`PerspectiveWidget` is compatible with Jupyterlab 3. To use it, make sure you
+have installed `perspective-python` and then install the extension from the
+Jupyter lab extension directory:
 
 ```bash
 jupyter labextension install @finos/perspective-jupyterlab

docs/static/css/custom.css

@@ -203,7 +203,6 @@ ol li {
 ol li::before {
     content: counter(list-counter) ".";
     font-weight: bold;
-    font-size: 2rem;
     margin-right: 0.5rem;
     font-family: "Public Sans", Arial, Helvetica, sans-serif;
     line-height: 1;

docs/static/css/material.dark.css

@@ -167,6 +167,7 @@ perspective-viewer,
   --color: #cfd8dc;
   --plugin--background: #2f3136;
   --select--background: url(data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDIwLjAuMCwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCA0LjkgMTAiIHN0eWxlPSJlbmFibGUtYmFja2dyb3VuZDpuZXcgMCAwIDQuOSAxMDsiIHhtbDpzcGFjZT0icHJlc2VydmUiPgo8c3R5bGUgdHlwZT0idGV4dC9jc3MiPgoJLnN0MHtmaWxsOiM0NDQ0NDQ7fQo8L3N0eWxlPgo8dGl0bGU+YXJyb3dzPC90aXRsZT4KPHBvbHlnb24gY2xhc3M9InN0MCIgcG9pbnRzPSIxLjQsNC43IDIuNSwzLjIgMy41LDQuNyAiLz4KPHBvbHlnb24gY2xhc3M9InN0MCIgcG9pbnRzPSIzLjUsNS4zIDIuNSw2LjggMS40LDUuMyAiLz4KPC9zdmc+Cg==) no-repeat 95% 50%;
+  --select--background-color: #242526;
   --inactive--color: #666;
   --active--background: #135d78;
   --active--color: #22a0ce;

docs/static/js/animation.js

@@ -42,16 +42,16 @@ var freq = 1,
     freqdir = 1,
     elem;
 
-function update() {
+function update(table) {
     var viewport_height = document.documentElement.clientHeight;
     if (viewport_height - window.scrollY > 0) {
-        elem.update([newRow(), newRow(), newRow()]);
+        table.update([newRow(), newRow(), newRow()]);
     }
     if (freq === 0) {
-        setTimeout(update, 3000);
+        setTimeout(() => update(table), 3000);
         freqdir = 1;
     } else {
-        setTimeout(update, Math.max(20, 200 / freq));
+        setTimeout(() => update(table), Math.max(20, 200 / freq));
     }
     if (freq > 60) {
         freqdir = -1;
@@ -138,13 +138,13 @@ window.addEventListener("WebComponentsReady", function() {
         data.push(newRow());
     }
     elem = Array.prototype.slice.call(document.querySelectorAll("perspective-viewer"))[0];
-    var worker = elem.worker;
+    var worker = perspective.worker();
     var tbl = worker.table(data, {index: "id"});
     elem.load(tbl);
     elem._toggle_config();
 
     setTimeout(function() {
-        update(0);
+        update(tbl, 0);
     });
 
     document.querySelector("#grid").addEventListener("mouseenter", () => select("#grid"));
@@ -175,7 +175,10 @@ window.addEventListener("WebComponentsReady", function() {
             plugin: "d3_heatmap",
             "column-pivots": ["Sub-Category"],
             "row-pivots": ["State"],
-            sort: [["Sales","desc"],["Profit","col desc"]],
+            sort: [
+                ["Sales", "desc"],
+                ["Profit", "col desc"]
+            ],
             columns: ["Profit"],
             aggregates: {Profit: "low"}
         });

package.json

@@ -133,6 +133,7 @@
         "fix:python": "node scripts/lint_python.js --fix",
         "fix": "npm-run-all --silent fix:*",
         "toggle_puppeteer": "node scripts/toggle_puppeteer.js",
-        "version": "python3 python/perspective/scripts/write_version.py && git add python/perspective/perspective/core/_version.py"
+        "version": "python3 python/perspective/scripts/write_version.py && git add python/perspective/perspective/core/_version.py",
+        "jlab_link": "node scripts/jlab_link.js"
     }
 }

packages/perspective-jupyterlab/package.json

@@ -32,6 +32,7 @@
         "version": "yarn build"
     },
     "dependencies": {
+        "@finos/perspective": "^0.6.0",
         "@finos/perspective-viewer": "^0.6.0",
         "@finos/perspective-viewer-d3fc": "^0.6.0",
         "@finos/perspective-viewer-datagrid": "^0.6.0",

packages/perspective/src/js/perspective.js

@@ -1799,7 +1799,6 @@ export default function(Module) {
                 throw new Error("WebAssembly not supported");
             } else {
                 console.log("Loading wasm");
-                console.log(msg.buffer.byteLength);
                 __MODULE__({
                     wasmBinary: msg.buffer,
                     wasmJSMethod: "native-wasm"

scripts/jlab_link.js

@@ -0,0 +1,71 @@
+/******************************************************************************
+ *
+ * Copyright (c) 2017, the Perspective Authors.
+ *
+ * This file is part of the Perspective library, distributed under the terms of
+ * the Apache License 2.0.  The full license can be found in the LICENSE file.
+ *
+ */
+const path = require("path");
+const {existsSync} = require("fs");
+const {execute, execute_return} = require("./script_utils.js");
+
+// Packages listed as dependencies & dev dependencies inside Jupyterlab plugin
+const packages = ["perspective", "perspective-viewer", "perspective-viewer-datagrid", "perspective-viewer-d3fc", "perspective-test", "perspective-webpack-plugin"].map(pkg => `@finos/${pkg}`);
+
+/**
+ * In order for Jupyterlab to pick up changes to @finos/perspective-* in the
+ * local working directory, we use `yarn link` to force Jupyterlab to look
+ * locally for all `perspective` packages, instead of pulling them from NPM
+ * during `jupyter lab install`. This script should be run whenever
+ * `jupyter lab clean` has been run, as cleaning the Jupyterlab dir will
+ * also break links.
+ *
+ * This allows us to distribute just the Jupyterlab plugin without inlining
+ * the rest of Perspective, but also allows for developers to see their local
+ * changes picked up in their current Jupyterlab installation.
+ *
+ * To set up your Jupyterlab environment with the local
+ * `perspective-jupyterlab` plugin, run
+ * `jupyter labextension install ./packages/perspective-jupyterlab` to link
+ * to the local plugin.
+ */
+(async function() {
+    try {
+        // check if @finos packages are already linked
+        const link_path = path.resolve(process.env.HOME, ".config/yarn/link", "@finos");
+
+        if (!existsSync(link_path)) {
+            throw Error(`No @finos links found in ${link_path} - run \`yarn link\` inside all Perspective packages first.`);
+        }
+
+        const paths = await execute_return("jupyter lab path");
+        const app_path = paths["stdout"]
+            .split("\n")[0]
+            .split(":")[1]
+            .trim();
+        const staging_path = path.resolve(app_path, "staging");
+
+        if (!existsSync(staging_path)) {
+            throw Error("Jupyterlab staging path does not exist - run `jupyter lab build` first.");
+        }
+
+        process.chdir(staging_path);
+
+        // Run yarn link inside jlab staging
+        for (const pkg of packages) {
+            execute(`yarn link ${pkg}`);
+        }
+
+        // Build from Perspective root
+        process.chdir(path.resolve(__dirname, ".."));
+        console.log("--------------------------");
+        execute("jupyter lab build");
+
+        console.log("--------------------------");
+        console.log("Jupyterlab should now have all changes from the current working directory. To pick up new changes, run `yarn build` and `jupyter lab build`.");
+    } catch (e) {
+        console.error(e);
+        process.exit(1);
+    }
+})();

scripts/script_utils.js

@@ -13,6 +13,8 @@ const execSync = require("child_process").execSync;
 const _path = require("path");
 const fs = require("fs");
 const rimraf = require("rimraf");
+const {promisify} = require("util");
+
 const isWin = process.platform === "win32";
 
 /*******************************************************************************
@@ -70,6 +72,16 @@ const execute_throw = cmd => {
     execSync(cmd, {stdio: "inherit"});
 };
 
+const execute_return = async cmd => {
+    if (process.argv.indexOf("--debug") > -1) {
+        console.log(`$ ${cmd}`);
+    }
+
+    const ex = promisify(require("child_process").exec);
+
+    return await ex(cmd);
+}
+
 /*******************************************************************************
  *
  * Public
@@ -186,6 +198,18 @@ exports.execute = (strings, ...args) => execute(Array.isArray(strings) ? bash(st
  */
 exports.execute_throw = (strings, ...args) => execute_throw(Array.isArray(strings) ? bash(strings, ...args) : strings);
 
+/**
+ * Just like `execute`, except it will return the output of the command
+ * it runs.
+ *
+ * @async
+ * @param {string} expression a bash command to be templated.
+ * @returns {string} A command with the missing argument's flags removed.
+ * @example
+ * execute`run -t${1} -u"${undefined}" task`;
+ */
+exports.execute_return = async (strings, ...args) => await execute_return(Array.isArray(strings) ? bash(strings, ...args) : strings);
+
 /**
  * Returns the value after this command-line flag, or `true` if it is the last
  * arg.  This makes it easy to null-pun for boolean flags, and capture the