tw5-graph 1.7.1

package/README.md

@@ -0,0 +1,65 @@
+# Graph for Tiddlywiki
+
+Tiddlywiki is a great non-linear notebook.   
+The internet has countless amazing visualization libraries for creating graphs.
+
+TW5-Graph brings them together.
+
+It is a framework plugin for creating graphs in Tiddlywiki. It has a quick and simple interface to make graphs quickly, but is also highly customizable so you can create the exact style of graphs you need.
+
+For a demonstration and documentation, see the [demo site](https://flibbles.github.io/tw5-graph/).
+
+**TW5-Graph is still being developed! But I'm making a point of not adding features unless someone wants it, so if this plugin doesn't have a feature you think it should have, then open up an issue and make a feature request!**
+
+## How to install
+
+TW5-Graph requires you to install it **and** at least one other plugin wrapping a visualization engine. Currently, only one is supported.
+
+[Vis-network](https://github.com/flibbles/tw5-vis-network)
+
+If you're using a single-file tiddlywiki, all you have to do is visit the [demo site](https://flibbles.github.io/tw5-graph/), where both TW5-Graph and all its supported engines are available for a quick drag-and-drop install.
+
+### For Node.js
+
+The following is an abridged version of the [instructions found here](https://tiddlywiki.com/#Installing%20custom%20plugins%20on%20Node.js).
+
+First, check out the source code using git. Then add its`plugins` directory to your TIDDLYWIKI_PLUGIN_PATH environment variable.
+
+For instance, if you check out the project to a "~/Documents/Graph" directory. Then run `echo "TIDDLYWIKI_PLUGIN_PATH=${TIDDLYWIKI_PLUGIN_PATH}:~/Documents/Graph/plugins" >> .profile`
+
+**You will need to repeat this process for the visualization libraries you plan to pair TW5-Graph with.**
+
+Afterward, add the plugin inside your projects' `tiddlywiki.info` file.
+The plugins section will look something like:
+```
+{
+   ...
+   "plugins": [
+      ...
+      "flibbles/graph",
+      "flibbles/(vis-network or some other visualization plugin)"
+   ],
+   ...
+}
+```
+
+Alternatively, you can also copy the `plugins` directly into your projects'
+root directory. Though this makes the install local only to those specific
+projects.
+
+## How to test
+
+### With npm
+
+The simplest way is through npm. This will manage all dependencies. From the project's root directory, do the following:
+
+1. Run `npm install` to build a few dependencies.
+2. Run `npm test` to run the tests.
+
+### Without npm
+
+This project is simple enough that you can run the tests without having to deal with npm. If you have tiddlywiki available, all you have to do is run the following from the root directory:
+
+`tiddlywiki --build test`
+
+However, not all tests may run if you don't have _relink_ and _relink-fieldnames_ available on your `TIDDLYWIKI_PLUGIN_PATH` enviroment variable. See the [relink project page](https://github.com/flibbles/tw5-relink) for instructions on how to set that up.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "tw5-graph",
+  "version": "1.7.1",
+  "description": "Lightweight and programmable graphing for Tiddlywiki",
+  "main": "index.js",
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "build": "tiddlywiki ++node_modules/tw5-vis-network/plugins/vis-network ++node_modules/mermaid-tw5/mermaid-tw5/plugins/mermaid-tw5 --build index bundle",
+    "test": "tiddlywiki ++node_modules/tw5-vis-network/plugins/vis-network ++node_modules/mermaid-tw5/mermaid-tw5/plugins/mermaid-tw5 ++node_modules/tw5-relink/plugins/relink ++node_modules/tw5-relink/plugins/relink-fieldnames --build test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flibbles/tw5-graph.git"
+  },
+  "keywords": [
+    "tiddlywiki5",
+    "tiddlywiki-plugin",
+    "visualization-tools"
+  ],
+  "author": "Flibbles",
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/flibbles/tw5-graph/issues"
+  },
+  "files": [
+    "plugins/"
+  ],
+  "homepage": "https://github.com/flibbles/tw5-graph#readme",
+  "dependencies": {
+    "tiddlywiki": "^5.3.8"
+  },
+  "devDependencies": {
+    "tw5-relink": "github:flibbles/tw5-relink",
+    "tw5-vis-network": "github:flibbles/tw5-vis-network#v10.6.3",
+    "mermaid-tw5": "github:flibbles/mermaid-tw5"
+  }
+}

package/plugins/graph/DefaultColourMappings.multids

@@ -0,0 +1,8 @@
+title: $:/config/DefaultColourMappings/
+
+graph-banner-background: <<colour sidebar-tab-background>>
+graph-banner-foreground: <<colour sidebar-tab-foreground>>
+graph-background: <<colour background>>
+graph-border: <<colour tiddler-border>>
+graph-node-color: <<colour primary>>
+graph-font-color: <<colour foreground>>

package/plugins/graph/ViewTemplateBodyFilter/graph.tid

@@ -0,0 +1,5 @@
+title: $:/plugins/flibbles/graph/ViewTemplateBodyFilter/graph
+list-before: $:/config/ViewTemplateBodyFilters/code-body
+tags: $:/tags/ViewTemplateBodyFilter
+
+[{!!title}] [get[draft.of]] +[prefix[$:/graph/]then[$:/plugins/flibbles/graph/ui/ViewTemplate/graph]]

package/plugins/graph/ViewTemplateBodyFilter/properties.tid

@@ -0,0 +1,5 @@
+title: $:/plugins/flibbles/graph/ViewTemplateBodyFilter/properties
+list-before: $:/config/ViewTemplateBodyFilters/code-body
+tags: $:/tags/ViewTemplateBodyFilter
+
+[removeprefix[$:/config/flibbles/graph/]search:title[/]then[$:/plugins/flibbles/graph/ui/ViewTemplate/graph-object]]

package/plugins/graph/edges/fields/list.tid

@@ -0,0 +1,7 @@
+title: $:/config/flibbles/graph/edges/fields/list
+description: The tiddler lists another resource in its list field.
+type: application/json
+
+{
+    "label": "lists"
+}

package/plugins/graph/edges/fields/tags.tid

@@ -0,0 +1,7 @@
+title: $:/config/flibbles/graph/edges/fields/tags
+description: The tiddler is tagged by another resource.
+type: application/json
+
+{
+    "label": "tagged with"
+}

package/plugins/graph/edges/functions/links.tid

@@ -0,0 +1,8 @@
+title: $:/config/flibbles/graph/edges/functions/links
+description: The tiddler contains a links of another resource.
+filter: [links[]]
+type: application/json
+
+{
+    "label": "links to"
+}

package/plugins/graph/edges/functions/transcludes.tid

@@ -0,0 +1,8 @@
+title: $:/config/flibbles/graph/edges/functions/transcludes
+description: The tiddler contains a transclusion of another resource.
+filter: [transcludes[]]
+type: application/json
+
+{
+    "label": "transcludes"
+}

package/plugins/graph/fieldtypes/filter.js

@@ -0,0 +1,212 @@
+/*\
+title: $:/plugins/flibbles/graph/fieldtypes/filter.js
+type: application/javascript
+module-type: fieldtype
+
+\*/
+
+"use strict";
+
+exports.name = "filter";
+
+exports.get = function(tiddler, field, options) {
+	// We optimize by storing a cache of compiled filters for this tiddler
+	// We will need them a lot, especially if our graphs are doing neighbor
+	// evaluation, which will call on these filters with every single change.
+	var fieldCache = options.wiki.getCacheForTiddler(tiddler.fields.title, "filter-fields", function() {
+		return Object.create(null);
+	});
+	var method = fieldCache[field];
+	if (method === undefined) {
+		// We haven't cached this filter function yet
+		var filterStr = tiddler.getFieldString(field);
+		fieldCache[field] = method = getFilterFunction(filterStr, options.wiki);
+	}
+	return method.call(options.wiki, null, options.widget);
+};
+
+exports.add = function(tiddler, field, value, options) {
+	var filterString = tiddler && tiddler.getFieldString(field);
+	var changed = false;
+	// We don't want to add the title if it's already a filter result.
+	while (options.wiki.filterTiddlers(filterString, options.widget).indexOf(value) < 0) {
+		changed = true;
+		var filterTree = options.wiki.parseFilter(filterString);
+		var found = false;
+		// Search backwards for any explicit removal of the target Ref
+		// Otherwise, we might get `... -value value`
+		for (let i = filterTree.length-1; i>= 0; i--) {
+		var run = filterTree[i];
+		var title = runIsSingleTitle(run);
+		if (title !== null) {
+			if (run.prefix === "-" && title === value) {
+				// We found an explicit removal. Remove the removal.
+				filterTree.splice(i, 1);
+				found = true;
+				break;
+			}
+		} else if (run.prefix) {
+			// This filter has gotten complicated.
+			// Forget searching for explicit removals.
+			break;
+		}
+		}
+		if (!found) {
+		// We didn't find an explicit removal (expected),
+		// so we add the title to the list.
+		filterTree.push({
+			prefix: "",
+			operators: [{operator: "title", operands: [{text: value}]}]});
+		}
+		filterString = reassembleFilter(filterTree);
+		// Now we go back and try again to make sure it actually took.
+	}
+	if (changed) {
+		return filterString;
+	}
+};
+
+exports.remove = function(tiddler, field, value, options) {
+	var filterString = tiddler && tiddler.getFieldString(field);
+	var changed = false;
+	// We don't want to remove a title that's not already there
+	while (filterString && options.wiki.filterTiddlers(filterString, options.widget).indexOf(value) >= 0) {
+		changed = true;
+		var filterTree = options.wiki.parseFilter(filterString);
+		var found = false;
+		for (let i = filterTree.length-1; i >= 0; i--) {
+			let run = filterTree[i];
+			let title = runIsSingleTitle(run);
+			if (title !== null) {
+				if (!run.prefix && title === value) {
+					// This is the title we're looking for. Remove it.
+					filterTree.splice(i, 1);
+					found = true;
+					break;
+				}
+			} else if (run.prefix) {
+				break;
+			}
+		}
+		if (!found) {
+			// We couldn't find it. So it must be a complicated filter.
+			// We'll put in a manual removal.
+			filterTree.push({
+				prefix: "-",
+				operators: [{operator: "title", operands: [{text: value}]}]});
+		}
+		filterString = reassembleFilter(filterTree, this.actionClean);
+		// Now we do it again to make sure it was actually removed
+	}
+	if (changed) {
+		return filterString;
+	}
+};
+
+// This returns a compiled filter given a string. It optimizes where it can.
+function getFilterFunction(filterStr, wiki) {
+	var method;
+	if (filterStr) {
+		method = wiki.compileFilter(filterStr);
+		// A further optimization here.
+		// If the filter is very simple, as in nothing by titles,
+		// then we can just call it now and cache the output,
+		// because it will never change.
+		if (filterStr.indexOf("[") < 0) {
+			var results = method.call(wiki);
+			method = function() { return results; };
+		}
+	} else {
+		method = function() { return []; };
+	}
+	return method;
+};
+
+// If this is a single title, return the title, otherwise null
+function runIsSingleTitle(run) {
+	if (run.operators.length === 1 && !run.namedPrefix) {
+		var op = run.operators[0];
+		if (op.operator === "title"
+		&& op.operands.length === 1
+		&& !op.suffix
+		&& !op.prefix) {
+			var operand = op.operands[0];
+			if (!operand.variable && !operand.indirect) {
+				return operand.text;
+			}
+		}
+	}
+	return null;
+};
+
+function reassembleFilter(parseTree, clean) {
+	// This will hold all of the filter parts
+	const fragments = [];
+	// Rebuild the filter.
+	for (var i = 0; i < parseTree.length; i++) {
+		var run = parseTree[i];
+		if (fragments.length > 0) {
+			fragments.push(" ");
+		}
+		fragments.push(run.prefix);
+		let title = runIsSingleTitle(run);
+		if (title) {
+			fragments.push(bestQuoteFor(title));
+		} else if (run.operators.length > 0) {
+			fragments.push("[");
+			for (let j = 0; j < run.operators.length; j++) {
+				let op = run.operators[j];
+				let firstOperand = true;
+				if (op.prefix) {
+					fragments.push(op.prefix);
+				}
+				if (op.operator !== "title" || op.suffix) {
+					fragments.push(op.operator);
+				}
+				if (op.suffix) {
+					fragments.push(':', op.suffix);
+				}
+				if (op.regexp) {
+					fragments.push("/", op.regexp.source, "/");
+					if (op.regexp.flags) {
+						fragments.push("(", op.regexp.flags, ")");
+					}
+				} else {
+					for (let k = 0; k < op.operands.length; k++) {
+						let operand = op.operands[k];
+						if (!firstOperand) {
+							fragments.push(',');
+						}
+						firstOperand = false;
+						if (operand.variable) {
+							fragments.push('<', operand.text, '>');
+						} else if (operand.indirect) {
+							fragments.push('{', operand.text, '}');
+						} else {
+							fragments.push('[', operand.text, ']');
+						}
+					}
+				}
+			}
+			fragments.push(']');
+		}
+	}
+	// Return compiled filter string, if there is one
+	if (clean && fragments.length == 0) {
+		return undefined;
+	}
+	return fragments.join("");
+};
+
+function bestQuoteFor(title) {
+	if (/^[^\s\[\]\-+~=:'"][^\s\[\]]*$/.test(title)) {
+		return title;
+	}
+	if (title.indexOf("]") < 0) {
+		return "[[" + title + "]]";
+	}
+	if (title.indexOf("'") < 0) {
+		return "'" + title + "'";
+	}
+	return '"' + title + '"';
+};

package/plugins/graph/fieldtypes/list.js

@@ -0,0 +1,31 @@
+/*\
+title: $:/plugins/flibbles/graph/fieldtypes/list.js
+type: application/javascript
+module-type: fieldtype
+
+\*/
+
+"use strict";
+
+exports.name = "list";
+
+exports.add = function(tiddler, field, value, options) {
+	var array = (tiddler && tiddler.getFieldList(field)) || [];
+	if (array.indexOf(value) < 0) {
+		array.push(value);
+		return $tw.utils.stringifyList(array);
+	}
+};
+
+exports.remove = function(tiddler, field, value, options) {
+	var array = (tiddler && tiddler.getFieldList(field)) || [];
+	var index = array.indexOf(value);
+	if (index >= 0) {
+		array.splice(index, 1);
+		return $tw.utils.stringifyList(array);
+	}
+};
+
+exports.get = function(tiddler, field, options) {
+	return tiddler.getFieldList(field);
+};

package/plugins/graph/fieldtypes/title.js

@@ -0,0 +1,27 @@
+/*\
+title: $:/plugins/flibbles/graph/fieldtypes/title.js
+type: application/javascript
+module-type: fieldtype
+
+\*/
+
+"use strict";
+
+exports.name = "title";
+
+exports.add = function(tiddler, field, value, options) {
+	if (!tiddler || tiddler.fields[field] !== value) {
+		return value;
+	}
+};
+
+exports.remove = function(tiddler, field, value, options) {
+	if (tiddler && tiddler.fields[field] === value) {
+		return "";
+	}
+};
+
+exports.get = function(tiddler, field) {
+	var value = tiddler.getFieldString(field);
+	return value? [value]: [];
+};

package/plugins/graph/filterrunprefixes/cache.js

@@ -0,0 +1,118 @@
+/*\
+title: $:/plugins/flibbles/graph/filterrunprefixes/cache.js
+type: application/javascript
+module-type: filterrunprefix
+
+Allows the results of a filter run to be cached for later filter executions.
+The runs MUST be generator functions. Local-run input is ignored, but run is
+executed each time
+
+\*/
+
+"use strict";
+
+// The counter is an incrementing  value we use to uniquely identify
+// instances of opFunction. opFunction, in turn, is cached by TW's limited
+// cache of compiled filters.
+var counter = 0;
+
+exports.cache = function(operationSubFunction, options) {
+	var opFunction = function(results, _/*ignored source*/, widget) {
+		// Use the input from previous runs as currentTiddlers.
+		// If there was not input, then we'll introduce an empty string as
+		// currentTiddler.
+		var inputTitles = results.toArray();
+		if (inputTitles.length == 0) {
+			inputTitles.push("");
+		}
+		results.clear();
+		var root = options.wiki.getGlobalCache("filterPrefix-" + opFunction.cacheKey, function() { return Object.create(null); });
+		for (var i = 0; i < inputTitles.length; i++) {
+			var current = inputTitles[i];
+			// Roots start as {}, or a Node that is not yet Branch or Leaf
+			root[current] = root[current] || {};
+			var output = execute(current, root[current], operationSubFunction, widget);
+			results.push.apply(results, output);
+		}
+	};
+	opFunction.cacheKey = counter++;
+	return opFunction;
+};
+
+/*
+Node = { } // A node begins as undefined until we make it a branch or node.
+Branch = {
+	variable: "Variable name",
+	options: (options that came with getVariable call)
+	children: { "variable value": <Node>, ...},
+}
+Leaf = {
+	value: ["Outputs", ...]
+}
+*/
+
+function execute(currentTiddler, root, operationSubFunction, widget) {
+	// First, try to retrieve from cache if it's available
+	var node = root;
+	var variables = {currentTiddler: currentTiddler};
+	var mockWidget = widget.makeFakeWidgetWithVariables(variables);
+	do {
+		if (node.value !== undefined) {
+			// We have a value to return
+			return node.value;
+		}
+		if (node.variable === undefined) {
+			// No value, and no variable either. Must be a fresh cache.
+			// This should only happen with the root node. It's the only one
+			// that isn't necessarily a Branch or Leaf when execute starts.
+			break;
+		}
+		var info = mockWidget.getVariableInfo(node.variable, node.options);
+		node = node.children[info.text];
+	} while (node !== undefined);
+	// It wasn't cached. We must now start back at the root and begin recording
+	node = root;
+	var trackWidget = widget.makeFakeWidgetWithVariables(variables);
+	var visited = Object.create(null);
+	trackWidget.oldVariable = trackWidget.getVariable;
+	trackWidget.getVariable = function(name, options) {
+		var value = this.oldVariable(name, options);
+		extendTree(name, value, options);
+		return value;
+	};
+	trackWidget.oldVariableInfo = trackWidget.getVariableInfo;
+	trackWidget.getVariableInfo = function(name, options) {
+		var info = this.oldVariableInfo(name, options);
+		extendTree(name, info.text, options);
+		return info;
+	};
+	function extendTree(name, value, options) {
+		// We don't need to extend the tree for currentTiddler.
+		// It's already accounted for.
+		// Also, if we've already encountered this variable, no need to
+		// extend the tree again.
+		if (name !== "currentTiddler" && !visited[name]) {
+			visited[name] = true;
+			// Logically, we're pointing at a node that does not have a value.
+			if (node.variable === undefined) {
+				// It's an undefined node. Make it a branch.
+				node.variable = name;
+				node.options = options;
+				node.children = Object.create(null);
+			} else if (node.variable !== name) {
+				// Unexpected. Variables should always be called in
+				// the same order that they were before.
+				throw "Non-deterministic filter";
+			}
+			var child = node.children[value];
+			if (child === undefined) {
+				child = node.children[value] = {};
+			}
+			node = child;
+		}
+	}
+	var output = operationSubFunction(function() {/*No source*/}, trackWidget);
+	// Change the current node (which is undefined) into a leaf.
+	node.value = output;
+	return output;
+};

package/plugins/graph/filters/gettyped.js

@@ -0,0 +1,26 @@
+/*\
+title: $:/plugins/flibbles/graph/filters/gettyped.js
+type: application/javascript
+module-type: filteroperator
+
+Filter operator which replcaes tiddler titles with the values of the field of the specified operand, but does so in a way that's responsive to the type of field, depending on how it's configured by Relink.
+
+\*/
+
+"use strict";
+
+var typeOperators = $tw.modules.getModulesByTypeAsHashmap("fieldtype");
+var relinkPrefix = "$:/config/flibbles/relink/fields/" ;
+
+exports.gettyped = function(source, operator, options) {
+	var results = [];
+	var field = operator.operand;
+	var typeName = options.wiki.getTiddlerText(relinkPrefix + field, "list");
+	var type = typeOperators[typeName] || typeOperators.list;
+	source(function(tiddler, title) {
+		if (tiddler) {
+			results.push.apply(results, type.get(tiddler, field, options));
+		}
+	});
+	return results;
+};

package/plugins/graph/graphengine.js

@@ -0,0 +1,38 @@
+/*\
+title: $:/plugins/flibbles/graph/graphengine.js
+type: application/javascript
+module-type: macro
+
+Macro returns the graph engine of choice within the current context.
+
+\*/
+
+"use strict";
+
+var utils = require("./utils.js");
+var config = "$:/config/flibbles/graph/engine";
+
+exports.name = "graphengine";
+exports.params = [];
+
+exports.run = function() {
+	return exports.get(this.wiki);
+};
+
+exports.get = function(wiki) {
+	return wiki.getCacheForTiddler(config, "graphengine", function() {
+		var specified = wiki.getTiddlerText(config);
+		if (specified) {
+			return specified;
+		} else {
+			var engineMap = utils.getEngineMap();
+			var keys = Object.keys(engineMap);
+			if (keys.length > 0) {
+				// We go with the first one by alphabetical order
+				keys.sort();
+				return keys[0];
+			}
+		}
+		return "";
+	});
+};

package/plugins/graph/icon.tid

@@ -0,0 +1,16 @@
+title: $:/plugins/flibbles/graph/icon
+
+\parameters (size:"22pt")
+\procedure pi() 3.141592653589793
+\function pair() [all[]sin[]] [all[]cos[]] +[multiply[-50]join[ ]]
+\procedure nodes() [range[0],[4]divide[6]multiply[2]multiply<pi>] :map[function[pair]] "0 0"
+\whitespace trim
+
+<$wikify name=edge-color text="<<colour muted-foreground>>" >
+<svg class="graph-icon" width=<<size>> height=<<size>> version="1.1" viewBox="-64 -64 128 128">
+<path class="graph-icon-splash" stroke-width=15 d=`M 0 0 S ${[subfilter<nodes>join[ ]]}$` style=`fill:$(edge-color)$;` />
+<$list variable=pos filter="[subfilter<nodes>putlast[]butfirst[3]]">
+<circle class="graph-icon-node" r=14
+	cx={{{ [<pos>split[ ]first[]] }}}
+	cy={{{ [<pos>split[ ]last[]] }}}
+	fill=<<node-color>> />

package/plugins/graph/images/drag.tid

@@ -0,0 +1,13 @@
+title: $:/plugins/flibbles/graph/images/drag
+tags: $:/tags/Image
+
+\whitespace trim
+\parameters (size:"22pt")
+<svg width=<<size>> height=<<size>> class="tc-draggable-button tc-image-button" viewBox="0 0 30 30">
+<circle r=3 cx=10 cy=5 />
+<circle r=3 cx=10 cy=15 />
+<circle r=3 cx=10 cy=25 />
+<circle r=3 cx=20 cy=5 />
+<circle r=3 cx=20 cy=15 />
+<circle r=3 cx=20 cy=25 />
+</svg>

package/plugins/graph/macros/action.addedge.tid

@@ -0,0 +1,16 @@
+\widget $action.addedge()
+\whitespace trim
+<$parameters
+	$$fromTiddler={{{ [<fromTiddler>!match[]else<currentTiddler>] }}}
+	$$toTiddler={{{ [<toTiddler>!match[]else<currentTiddler>] }}} >
+
+<$action-modal $tiddler="$:/plugins/flibbles/graph/ui/Modals/SelectField">
+
+  <$action-addtyped $tiddler=<<$fromTiddler>> $field=<<selection>> $value=<<$toTiddler>> />
+
+</$action-modal>
+<$action-sendmessage $message=tm-focus-selector $param="input.graph-select" />
+
+\end
+
+\relink $action.addedge $fromTiddler:title $oTiddler:title