@flourish/sdk 3.17.2 → 3.19.0

package/RELEASE_NOTES.md~

@@ -0,0 +1,372 @@
+<<<<<<< HEAD
+# 3.13.1
+
+* Fix a regression that caused errors in a template with no settings: block defined in its template.yml. #63
+=======
+# 3.14.0
+
+* Add a “watch” option for build rules, to use a custom watcher
+>>>>>>> sdk-watch-command
+
+# 3.13.0
+
+* Support is_optional on font type settings so that they can be set to null
+* Support is_optional on color type settings so that they can be set to null
+
+# 3.12.0
+
+* Support hide_if and show_if properties for components so that whole blocks of imported settings can be easily hidden.
+* Support extending (as an alternative to replacing) entities through overrides
+* Support 'property' property of override object being an array of properties
+* Support template show_if/hide_if conditionals referencing imported component properties
+
+# 3.11.7
+
+* Fix bug with boolean-valued show_if/hide_if in settings.yml of modules
+
+# 3.11.6
+
+* Fix show_if and hide_if conditionals involving data bindings
+
+# 3.11.5
+
+* Print date and time when publishing a template.
+
+# 3.11.4
+
+* The “flourish register” command used to fail at the point of asking you to enter a password if you are using Node 10. This version fixes that problem.
+
+# 3.11.3
+
+* Add support for `svg_download`, which you should now set to `false` for templates where SVG download wouldn't produce useful results (for example if the only SVG in the template is a legend, not the main chart)
+
+# 3.11.2
+
+* Do not allow template settings to be conditional on themselves.
+
+# 3.11.1
+
+* Fix bug that broke show_if/hide_if settings rules.
+
+# 3.11.0
+
+* Update all node modules to their current versions. This also means that templates created with “flourish new” will be configured to use the current version of rollup.
+* New design for settings panel (matching flourish.studio). Checkboxes are now iOS-style toggle switches, and editing the color palette opens the palette editor in a separate overlay.
+
+# 3.10.3
+
+* Update the documentation for the `colors` setting type.
+
+# 3.10.2
+
+* One of the dependency packages used by the SDK fails to compile with versions of node earlier than 8.3. Update the "engines" specification in package.json to specify that we require node 8.3 or later.
+
+# 3.10.1
+
+* Template name and author were being inserted into the page unescaped, which would cause problems if either contains characters such as `<` that have a special meaning in HTML. This is now fixed.
+
+# 3.10.0
+
+* Log a warning to the console if the draw() or update() functions are declared to have parameters. #19
+* Support the `--as` flag consistently across commands. (This change only affects internal users at Flourish HQ.)
+
+# 3.9.2
+
+* The “flourish login” command was failing at the password prompt, with Node 10. Change the way we read the password, so it works. #56
+
+# 3.9.1
+
+* Allow "type: hidden" properties under settings in template.yml, for documenting state that isn't an exposed setting. This is intend to help document the template for programmatic use via the upcoming API.
+* Document the suggestion that such state documentation is under a "State documentation" settings block.
+
+# 3.9.0
+
+* Add the “flourish history” command to the output of “flourish help”.
+* Add the optional template id parameter for “flourish list” to the output of “flourish help”.
+* Raise an error if “flourish history” is called with no argument.
+* Set the NODE_ENV environment variable to "production" or "development" depending on whether the build was triggered by `flourish publish` or `flourish run`.
+* New command `flourish assign-version-number`, which must be used to assign a version number to an already-published template before it can be republished.
+
+# 3.8.0
+
+* Add a new undocumented “flourish publish” option `--local-testing`, which is only useful if you are running your own instance of the Flourish server.
+
+# 3.7.1
+
+* Skeleton project: suppress “circular dependency” warnings in the rollup configuration.
+
+# 3.7.0
+
+* Introduces new "font" setting type.
+* Allow headings in imported setting blocks
+* Take metadata from package.json, if present. #35
+  Specifically:
+  * Use the author, description and version fields from package.json if the
+    corresponding field is missing from template.yml.
+  * Use the name from package.json as the template id, if the template.yml has no id.
+* Respect the version number (as per semver.org): if the major version number is not incremented, assume the new version is backwards-compatible and upgrade existing visualisations. If the major version number is incremented, leave existing visualisations connected to the previous version.
+* Add --patch, --prerelease and --release options to “flourish publish”.
+* Make it possible to pass a template id as a parameter to “flourish list”, to list the available versions of a particular template.
+* Add a version parameter to “flourish delete”.
+* Add a “flourish history” command, to show the versions of a template that are available for use in the Live API.
+
+# 3.6.0
+
+* Fix a bug that meant conditional settings could not refer to a setting whose name begins with "data". #45
+* `flourish list` now recognises the `--full` option.
+* `flourish delete` now has a `--force` option that makes it possible to delete a template even if there are associated visualisations, provided they were created by the same user who created the template.
+
+# 3.5.0
+
+* `flourish new` now generates skeleton code for SDK version 3
+* What was called `api_token` is now called `sdk_token`. This is a purely internal change, which should not affect developers using the SDK to develop Flourish templates. (Developers running their own instances of the Flourish app will need to ensure they have an up-to-date version of Flourish. On the other hand, older versions of the SDK are compatible with the newer Flourish app.)
+
+# 3.4.0
+
+* Modules imported using the “import” syntax are now resolved using
+  Node's [`require.resolve` algorithm](https://nodejs.org/api/modules.html#modules_all_together).
+* New “override” property for imported settings.
+
+# 3.3.1
+
+* New `joinable_data` property can be specified in template.yml.
+  This is currently an undocumented feature intended for internal
+  use by Flourish.
+* Since 3.3.0, the SDK now only supports Node 8+. This is now specified in `package.json`.
+
+# 3.3.0
+
+* Added new `colors` setting type for palette picking.
+* New “import” syntax to import groups of settings from a node module.
+
+# 3.2.0
+
+* After upgrading template.yml, write it back out with { flowLevel: 4 }, which makes the YAML come out more like the way we write it in the documentation. In practice this only affects choices for settings in key-value format, since that is the only place currently where the structure is nested four levels deep.
+
+# 3.1.0
+
+* Minor fix to the error handling in the template upgrade code.
+* Having an `autoheight` property in template.yml is now an error rather than a warning.
+* Updated tests.
+
+# 3.0.0
+
+This is a major version change, and a forced upgrade: older versions of the SDK can no longer publish templates to Flourish. The `autoheight` property is no longer supported, and instead iframe height is automatically set using default breakpoints. For templates that need to adjust the iframe height dynamically, there is a new method `Flourish.setHeight()`.
+
+Templates now need to have `sdk_version: 3` in their template.yml. Old templates can be upgraded by running `flourish upgrade`.
+
+# 2.16.1
+
+* Upgrade node modules (mocha → 5.1.1, rollup → 0.58.0)
+* Improve error message from “flourish login” in the case where the server returns something unexpected. (This is mainly useful for testing changes to Flourish itself: this should never happen in normal operation.)
+
+# 2.16.0
+
+* Tweak the Flourish logo, and make it link to the live app.
+* Change the “prepublish” npm script to “prepare”, to be compatible with future versions of NPM.
+* Set the file permissions of the .flourish_sdk file so that only the current user can read it.
+
+# 2.15.2
+
+* Slightly better fix for #40, so that the temporary zip file is still deleted on exit.
+
+# 2.15.1
+
+* Upgrade ws module to 5.1.1.
+* Avoid crash after publishing a template. #40
+
+# 2.15.0
+
+* Upgrade all node module dependencies to their current versions. This will also
+  affect new user projects created with the “flourish new” command.
+* Support the --no-build option for “flourish publish”.
+* New setting type “code”.
+* New “size: large” option for text and code settings.
+
+# 2.14.0
+
+* Drop support for specifying a username in the `id` of `template.yml` by setting id to `<username>/<template>`. Specifying one now throws an error when publishing a template. (This feature was only used internally for Flourish templates on the @flourish account. This should not affect external users of the SDK.)
+
+# 2.13.0
+
+Major change: the preview pane is now embedded using the same height-adjustment
+logic as when a published visualisation is embedded on another site. If the
+preview pane is set to a fixed height, then `Flourish.fixed_height` is true
+in the template.
+
+Bug fixes:
+* Fixes boolean button group bugs
+* With a subhead in place, the new_section line didn't get hidden properly
+* Only send nulls for empty number settings
+
+# 2.12.1
+
+* Handle strings containing U+2028 or U+2029 characters in data.
+
+# 2.12.0
+
+* New `is_master_slide` property can be specified in template.yml.
+  This is currently an undocumented feature intended for internal
+  use by Flourish.
+* New setting width option “three quarters”.
+* Settings display can now be conditional on data bindings being set.
+* Boolean settings can specify `choices` in template.yml to display as buttons.
+* Add tests for template.yml validation, fix some validation bugs, and make some
+  error messages more consistent.
+
+# 2.11.0
+
+* New `credits:` property can be specified in template.yml
+
+# 2.10.1
+
+* Give a sensible error message if conditional settings configuration
+  (`show_if:`) blocks are indented incorrectly.
+* Correct the formatting of the `show_if` examples in README.md
+* Hide section dividers when setting is hidden
+
+# 2.10.0
+
+* The template documentation is now taken from `GUIDE.md` if there is
+  such a file, and only from `README.md` as a fallback if `GUIDE.md`
+  does not exist.
+* Settings can now be displayed conditionally on the values of other settings.
+  See the “Conditional settings” section of the documentation.
+
+# 2.9.1
+
+* Fix botched release (with many missing files) that was caused by
+  a bug in npm: See https://github.com/npm/npm/issues/18461
+
+# 2.9.0
+
+* New settings layout options:
+  * width: half
+  * width: quarter
+  * new_section: true
+  * style: buttons
+
+  See https://flourish.rocks/developers/reference/template-files.html#settings
+
+* Add support for optional column bindings.
+* Add --listen option for `flourish run` to listen on a non-localhost interface.
+* Add support for `image_download: false`
+* Upgrade d3-dsv to 1.0.7. #17
+* Match data table names case-sensitively, even on case-insensitive filesystems. #25
+* Warn if there is no autoheight configuration.
+* Upgrade skeleton project to rollup 0.50.0
+
+# 2.8.0
+
+* Add missing font files. #21
+* Add support for optional number settings. If “optional: true” is specified,
+  and no value is supplied for the setting, then a null value will be passed to
+  the template rather than zero.
+* Fix “Uncaught TypeError: Cannot read property 'fireEvent' of undefined” #22
+
+# 2.7.0
+
+* New metadata property in template.yml “autoheight” to specify how the width of
+  the embed should depend on the height when an auto-height embed is used.
+* String settings can now have a “choices” property which restricts the values
+  users can enter, and displays the setting as a dropdown list rather than a
+  free-text field. If the optional “choices_other” property is also true, the
+  user may type free text in addition to selecting from the listed choices.
+  The choices property should be an array of strings or pairs of strings: if
+  a pair of strings is given, the first element is displayed to the user on the
+  dropdown menu and the second is used as the value of the setting.
+* New data binding description metadata property in template.yml: in the data
+  section, if a second string is supplied immediately following the binding
+  name, it will be treated as the binding decription, and displayed to the
+  user in the data bindings panel.
+* Run “npm install” rather than “npm update” to install modules. (Newer versions
+  of NPM will update package.json and package-lock.json when “npm update” is used.)
+
+# 2.6.0
+
+* Bundle fonts locally, so the SDK doesn’t need an internet connection.
+* Work around a browser-dependent issue where mousewheel scrolling sometimes
+  did not work after the viewport had been resized. #14
+* Fix file watching when the template directory is not the current directory. #15
+
+# 2.5.5
+
+* More efficient generation of HTML: significantly faster reloads for
+  large data tables. #11
+* Avoid reloading many times in parallel when switching branches in git. #12
+
+# 2.5.4
+
+* Don’t show the “pointer” icon on the rotate button when it’s disabled.
+
+# 2.5.3
+
+* Specify in package.json that it only works with Node 6 and later.
+
+# 2.5.2
+
+* Remove another popup that slipped through the net in 2.5.1.
+
+# 2.5.1
+
+* Fix resizing on IE11 and Edge.
+* Remove popups that don’t display properly.
+
+# 2.5.0
+
+* New preview interface, matching the new visualisation editor
+  on flourish.studio
+
+# 2.4.1
+
+* Fix bug affecting error reporting for invalid data bindings
+* Ignore repeated and trailing slashes in build rule directory paths
+* Handle CSV files that have a UTF-8 BOM, as saved by Excel
+
+# 2.4.0
+
+* Add “flourish --version”, to print the SDK version number.
+
+# 2.3.1
+
+* Update top-level “flourish help”.
+* Refer to the help command if you just type “flourish”.
+* Do not include meta tags in SDK HTML.
+* Remove full path to lessc script in the skeleton package.json, because it
+  was not working on Windows.
+
+# 2.3.0
+
+* Add command-line help with “flourish help”.
+* “flourish delete” now takes a template id, not a template directory.
+
+# 2.2.0
+
+* Cross-platform compatibility improvements: it should now work correctly on
+	Windows, Mac and Linux.
+* Run “`npm update`” on build if `package.json` exists but `node_modules` does not
+* Better error reporting if “`flourish upgrade`” is run and neither `template.yml`
+  nor `settings.js` exist.
+* “flourish whoami” prints your username, rather than your email address
+* Remove top menu; "Preview" mode now available as "Standalone" via the view menu
+* Legal nonsense:
+	* Add license
+	* Agree to Terms and Conditions when you register
+* An unfortunate consequence of the previous point is that older versions of
+	the SDK are no longer allowed to communicate with the server, and users are
+	prompted to upgrade
+* Use Handlebars rather than Mustache internally
+* Dogfood note: our internal templates may specify `flourish/identifier` in their
+	`id` field, so when we publish them they’re linked to the `flourish` user.
+	This only works if you’re logged in as an admin user.
+
+# 2.1.0
+
+* Add an option (`--as`) that only works for admin users.
+* Serve source maps (`template.js.map`) for easier debugging of templates.
+* Correct documentation for data bindings. Issue a better error message
+  for data bindings that don’t have suitable `column` or `columns` specifications.
+  Thanks to Tim Brock.
+* Add release notes!
+* Fix the “Editor” link in the SDK header.
+* Mention “flourish register” in the quickstart notes.

package/bin/{flourish → flourish.js}

@@ -55,59 +55,48 @@ process.on("unhandledRejection", function(reason, p) {
 	throw reason;
 });
 
+const COMMANDS = [
+	"help",
+	"version",
+	"new",
+	"build",
+	"run",
+	"register",
+	"login",
+	"logout",
+	"whoami",
+	"assign-version-number",
+	"publish",
+	"delete",
+	"upgrade",
+	"list",
+	"history"
+];
+
 function main() {
 	const args = minimist(process.argv.slice(2), OPTS);
 
+	if (args._[0] === "is" && args._[1] === "the") {
+		return log.victory("Word!");
+	}
+
 	// minimist unhelpfully treats numeric strings as numbers;
 	// which means we have to turn them back into strings.
-	args._ = args._.map(x => "" + x);
-
-	let command = args._[0];
-
-	const server_opts = {
-		host: args.host,
-		user: args.user,
-		password: args.password,
-	};
+	args._ = args._.map(String);
 
+	let [command] = args._;
 	if (args.version) command = "version";
 	else if (args.help) command = "help";
 
-	switch (command) {
-		case "help":
-		case "version":
-
-		case "new":
-		case "build":
-		case "run":
-
-		case "register":
-		case "login":
-		case "logout":
-
-		case "whoami":
-
-		case "assign-version-number":
-		case "publish":
-		case "delete":
-		case "upgrade":
-		case "list":
-		case "history":
-			require("../lib/cmd/" + command)(args, server_opts);
-			break;
-
-		case "is":
-			if (args._[1] === "the") {
-				log.victory("Word!");
-				break;
-			}
-
-		default:
-			log.die("Unknown command '" + command + "'. Type 'flourish help' for help.");
+	if (!command) {
+		return log.die("No command specified. Type ‘flourish help’ for help.");
+	}
 
-		case undefined:
-			log.die("No command specified. Type ‘flourish help’ for help.");
+	if (!COMMANDS.includes(command)) {
+		return log.die(`Unknown command '${command}'. Type 'flourish help' for help.`);
 	}
+
+	require("../lib/cmd/" + command).command(args);
 }
 
 main();

package/lib/cmd/assign-version-number.js

@@ -5,7 +5,7 @@ const semver = require("@flourish/semver");
 const log = require("../log"),
       sdk = require("../sdk");
 
-function assign_version_number(args, server_opts) {
+exports.command = function assign_version_number(args) {
 	let template_id_promise, template_version;
 	if (args._.length == 2) {
 		// Assume the supplied argument is a version number, and try to get the id from the current directory
@@ -27,7 +27,7 @@ function assign_version_number(args, server_opts) {
 
 	template_id_promise.then(template_id => {
 		if (args.as) template_id = args.as + "/" + template_id;
-		return sdk.request(server_opts, "template/assign-version-number", { id: template_id, version: template_version })
+		return sdk.request(args, "template/assign-version-number", { id: template_id, version: template_version })
 		.then(() => {
 			log.success(`Assigned version number ${template_version} to template ${template_id}`);
 		});
@@ -36,14 +36,12 @@ function assign_version_number(args, server_opts) {
 		if (args.debug) log.die("Failed to assign version number", error.message, error.stack);
 		else log.die("Failed to assign version number", error.message);
 	});
-}
+};
 
-assign_version_number.help = `
+exports.help = `
 flourish assign-version-number [template-id] version
 
 Assign a version number to a template that does not have one yet.
 If template-id is omitted, uses the id of the template in the
 current directory.
 `;
-
-module.exports = assign_version_number;

package/lib/cmd/build.js

@@ -5,7 +5,7 @@ var fs = require("fs"),
     log = require("../log"),
     sdk = require("../sdk");
 
-function build(args) {
+exports.command = function build(args) {
 	const template_dir = ".";
 	if (!fs.existsSync("template.yml")) {
 		log.die("No template.yml file found in the current directory");
@@ -20,7 +20,7 @@ function build(args) {
 	}
 
 	sdk.buildRules(template_dir)
-		.then((rules) => {
+		.then(async rules => {
 			const script_by_key = new Map();
 			for (const rule of rules) script_by_key.set(rule.key, rule.script);
 
@@ -32,17 +32,15 @@ function build(args) {
 				scripts_to_run.push(script_by_key.get(key));
 			}
 
-			let p = Promise.resolve();
-			for (let script of scripts_to_run) {
-				p = p.then(() => sdk.runBuildCommand(template_dir, script, args.env));
+			for (const script of scripts_to_run) {
+				await sdk.runBuildCommand(template_dir, script, args.env);
 			}
-			return p;
 		})
 		.then(() => log.victory("Done!"))
 		.catch((error) => log.die("Failed to build template", error.message, error.stack));
-}
+};
 
-build.help = `
+exports.help = `
 flourish build [options] [build rules...]
 
 Build the template in the current directory.
@@ -61,5 +59,3 @@ Options:
 	Set the NODE_ENV environment variable to the specified value before running
 	the build script.
 `;
-
-module.exports = build;

package/lib/cmd/delete.js

@@ -3,7 +3,7 @@
 var log = require("../log"),
     sdk = require("../sdk");
 
-function _delete(args, server_opts) {
+exports.command = function _delete(args) {
 	let template_id = args._[1],
 	    template_version = args._[2];
 
@@ -14,7 +14,7 @@ function _delete(args, server_opts) {
 		template_id = args.as + "/" + template_id;
 	}
 
-	sdk.request(server_opts, "template/delete", { id: template_id, version: template_version, force: !!args.force })
+	sdk.request(args, "template/delete", { id: template_id, version: template_version, force: !!args.force })
 		.then(() => {
 			if (template_version) {
 				log.success(`Deleted template ${template_id} version ${template_version}`);
@@ -27,9 +27,9 @@ function _delete(args, server_opts) {
 			if (args.debug) log.die("Failed to delete template", error.message, error.stack);
 			else log.die("Failed to delete template", error.message);
 		});
-}
+};
 
-_delete.help = `
+exports.help = `
 flourish delete [--force] template_id version
 
 Deletes the specified template from the server, assuming it has previously
@@ -44,5 +44,3 @@ If the template is in use by users other than you, it will not be possible
 to delete it. If you have used it, you can pass the --force flag to delete
 the template and associated visualisations.
 `;
-
-module.exports = _delete;

package/lib/cmd/help.js

@@ -4,7 +4,7 @@ var path = require("path"),
 
     log = require("../log");
 
-function help(args) {
+exports.command = function help(args) {
 	const topic = args._[args._[0] === "help" ? 1 : 0] || "help";
 
 	if (topic.indexOf(path.sep) == -1
@@ -18,9 +18,9 @@ function help(args) {
 			log.die("No such help topic: " + topic);
 		}
 	}
-}
+};
 
-help.help = `
+exports.help = `
 Commands:
 	flourish assign-version-number [template id] version
 	flourish build [build rules...]
@@ -43,5 +43,3 @@ Type “flourish help [command]” for more on a particular command.
 To get started, use “flourish new” to create a new template and
 “flourish run” to run it.
 `;
-
-module.exports = help;

package/lib/cmd/history.js

@@ -9,7 +9,7 @@ function byVersion(a, b) {
 	return semver.cmp(semver.parse(a.version), semver.parse(b.version));
 }
 
-function history(args, server_opts) {
+exports.command = function history(args) {
 	const username_template_id = args._[1];
 	if (!username_template_id) {
 		log.die("Please specify a template id. E.g. flourish history my-template");
@@ -28,7 +28,7 @@ function history(args, server_opts) {
 	else if (username_template_id) {
 		template_id = username_template_id;
 	}
-	sdk.request(server_opts, "template/history", { username, id: template_id })
+	sdk.request(args, "template/history", { username, id: template_id })
 		.then((result) => {
 			const template_versions = result.sort(byVersion);
 
@@ -40,9 +40,9 @@ function history(args, server_opts) {
 			}
 		})
 		.catch((error) => log.die("Failed to list template history", error.message, error.stack));
-}
+};
 
-history.help = `
+exports.help = `
 flourish history [template id]
 
 List the version numbers of a published template.
@@ -55,5 +55,3 @@ With the --full option, prints all the template metadata in JSON format.
 
 This command requires you to be logged in to an account.
 `;
-
-module.exports = history;

package/lib/cmd/list.js

@@ -16,7 +16,7 @@ function byExternalIdAndVersion(a, b) {
 	return semver.cmp(semver.parse(a.version), semver.parse(b.version));
 }
 
-function list(args, server_opts) {
+exports.command = function list(args) {
 	const username_template_id = args._[1];
 	let username = args.as,
 	    template_id;
@@ -33,7 +33,7 @@ function list(args, server_opts) {
 	else if (username_template_id) {
 		template_id = username_template_id;
 	}
-	sdk.request(server_opts, "template/list", { username })
+	sdk.request(args, "template/list", { username })
 		.then((result) => {
 			let templates = result.templates;
 
@@ -55,9 +55,9 @@ function list(args, server_opts) {
 			}
 		})
 		.catch((error) => log.die("Failed to list templates", error.message, error.stack));
-}
+};
 
-list.help = `
+exports.help = `
 flourish list [template id]
 
 List the ids and versions of your published templates.
@@ -69,5 +69,3 @@ With the --full option, prints all the template metadata in JSON format.
 
 This command requires you to be logged in to an account.
 `;
-
-module.exports = list;