Introduce testcase widget so that we can reuse testcases as documentation examples

There's still a bit to do: adding tabs to the source panel of the testcase display, and tweaking the CSS.

core/modules/widgets/data.js

@@ -1,5 +1,5 @@
 /*\
-title: $:/plugins/tiddlywiki/innerwiki/data.js
+title: $:/core/modules/widgets/data.js
 type: application/javascript
 module-type: widget
 
@@ -53,6 +53,5 @@ DataWidget.prototype.refresh = function(changedTiddlers) {
 };
 
 exports.data = DataWidget;
-exports.anchor = DataWidget;
 
 })();

core/modules/widgets/testcase-transclude.js

@@ -0,0 +1,68 @@
+/*\
+title: $:/core/modules/widgets/testcase-transclude.js
+type: application/javascript
+module-type: widget
+
+Widget to transclude a tiddler from a test case
+
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false */
+"use strict";
+
+var Widget = require("$:/core/modules/widgets/widget.js").widget,
+	TestCaseWidget = require("$:/core/modules/widgets/testcase.js").testcase;
+
+var TestCaseTranscludeWidget = function(parseTreeNode,options) {
+	this.initialise(parseTreeNode,options);
+};
+
+/*
+Inherit from the base widget class
+*/
+TestCaseTranscludeWidget.prototype = new Widget();
+
+/*
+Render this widget into the DOM
+*/
+TestCaseTranscludeWidget.prototype.render = function(parent,nextSibling) {
+	this.parentDomNode = parent;
+	this.computeAttributes();
+	this.execute();
+	// Find the parent testcase
+	var pointer = this.parentWidget;
+	while(pointer && !(pointer instanceof TestCaseWidget)) {
+		pointer = pointer.parentWidget;
+	}
+	// Render the transclusion
+	if(pointer && pointer.testcaseRenderTiddler) {
+		pointer.testcaseRenderTiddler(parent,nextSibling,this.testcaseTranscludeTiddler,this.testcaseTranscludeMode)
+	}
+};
+
+/*
+Compute the internal state of the widget
+*/
+TestCaseTranscludeWidget.prototype.execute = function() {
+	this.testcaseTranscludeTiddler = this.getAttribute("tiddler");
+	this.testcaseTranscludeMode = this.getAttribute("mode");
+};
+
+/*
+Selectively refreshes the widget if needed. Returns true if the widget or any of its children needed re-rendering
+*/
+TestCaseTranscludeWidget.prototype.refresh = function(changedTiddlers) {
+	var changedAttributes = this.computeAttributes();
+	if($tw.utils.count(changedAttributes) > 0) {
+		this.refreshSelf();
+		return true;
+	} else {
+		return false;
+	}
+};
+
+exports["testcase-transclude"] = TestCaseTranscludeWidget;
+
+})();

core/modules/widgets/testcase-view.js

@@ -0,0 +1,67 @@
+/*\
+title: $:/core/modules/widgets/testcase-view.js
+type: application/javascript
+module-type: widget
+
+Widget to render a plain text view of a tiddler from a test case
+
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false */
+"use strict";
+
+var Widget = require("$:/core/modules/widgets/widget.js").widget,
+	TestCaseWidget = require("$:/core/modules/widgets/testcase.js").testcase;
+
+var TestCaseViewWidget = function(parseTreeNode,options) {
+	this.initialise(parseTreeNode,options);
+};
+
+/*
+Inherit from the base widget class
+*/
+TestCaseViewWidget.prototype = new Widget();
+
+/*
+Render this widget into the DOM
+*/
+TestCaseViewWidget.prototype.render = function(parent,nextSibling) {
+	this.parentDomNode = parent;
+	this.computeAttributes();
+	this.execute();
+	// Find the parent testcase
+	var pointer = this.parentWidget;
+	while(pointer && !(pointer instanceof TestCaseWidget)) {
+		pointer = pointer.parentWidget;
+	}
+	// Render the transclusion
+	if(pointer && pointer.testcaseRawTiddler) {
+		pointer.testcaseRawTiddler(parent,nextSibling,this.testcaseViewTiddler)
+	}
+};
+
+/*
+Compute the internal state of the widget
+*/
+TestCaseViewWidget.prototype.execute = function() {
+	this.testcaseViewTiddler = this.getAttribute("tiddler");
+};
+
+/*
+Selectively refreshes the widget if needed. Returns true if the widget or any of its children needed re-rendering
+*/
+TestCaseViewWidget.prototype.refresh = function(changedTiddlers) {
+	var changedAttributes = this.computeAttributes();
+	if($tw.utils.count(changedAttributes) > 0) {
+		this.refreshSelf();
+		return true;
+	} else {
+		return false;
+	}
+};
+
+exports["testcase-view"] = TestCaseViewWidget;
+
+})();

core/modules/widgets/testcase.js

@@ -0,0 +1,207 @@
+/*\
+title: $:/core/modules/widgets/testcase.js
+type: application/javascript
+module-type: widget
+
+Widget to display a test case
+
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false */
+"use strict";
+
+var Widget = require("$:/core/modules/widgets/widget.js").widget;
+
+var TestCaseWidget = function(parseTreeNode,options) {
+	this.initialise(parseTreeNode,options);
+};
+
+/*
+Inherit from the base widget class
+*/
+TestCaseWidget.prototype = new Widget();
+
+/*
+Render this widget into the DOM
+*/
+TestCaseWidget.prototype.render = function(parent,nextSibling) {
+	this.parentDomNode = parent;
+	this.computeAttributes();
+	this.execute();
+	// Render the children into a hidden DOM node
+	var parser = {
+		tree: [{
+			type: "widget",
+			attributes: {},
+			orderedAttributes: [],
+			children: this.parseTreeNode.children || []
+		}]
+	};
+	this.contentRoot = this.wiki.makeWidget(parser,{
+		document: $tw.fakeDocument,
+		parentWidget: this
+	});
+	this.contentContainer = $tw.fakeDocument.createElement("div");
+	this.contentRoot.render(this.contentContainer,null);
+	// Create a wiki
+	this.testcaseWiki = new $tw.Wiki();
+	// Load tiddlers from child data widgets
+	var tiddlers = this.readTiddlerDataWidgets(this.contentRoot.children);
+	this.testcaseWiki.addTiddlers(tiddlers);
+	// Load tiddlers from the optional testcaseTiddler
+	if(this.testcaseTiddler) {
+		var tiddler = this.wiki.getTiddler(this.testcaseTiddler);
+		if(tiddler && tiddler.fields.type === "text/vnd.tiddlywiki-multiple") {
+			var tiddlers = this.extractMultipleTiddlers(tiddler.fields.text);
+			this.testcaseWiki.addTiddlers(tiddlers);
+		}
+	}
+	// Unpack plugin tiddlers
+	this.testcaseWiki.readPluginInfo();
+	this.testcaseWiki.registerPluginTiddlers("plugin");
+	this.testcaseWiki.unpackPluginTiddlers();
+	this.testcaseWiki.addIndexersToWiki();
+	// Render children from the template
+	this.renderChildren(parent,nextSibling);
+};
+
+TestCaseWidget.prototype.extractMultipleTiddlers = function(text) {
+	// Duplicates code found in $:/plugins/tiddlywiki/jasmine/run-wiki-based-tests.js
+	var rawTiddlers = text.split("\n+\n"),
+		tiddlers = [];
+	$tw.utils.each(rawTiddlers,function(rawTiddler) {
+		var fields = Object.create(null),
+			split = rawTiddler.split(/\r?\n\r?\n/mg);
+		if(split.length >= 1) {
+			fields = $tw.utils.parseFields(split[0],fields);
+		}
+		if(split.length >= 2) {
+			fields.text = split.slice(1).join("\n\n");
+		}
+		tiddlers.push(fields);
+	});
+	return tiddlers;
+};
+
+/*
+Render a test case
+*/
+TestCaseWidget.prototype.testcaseRenderTiddler = function(parent,nextSibling,title,mode) {
+	var self = this;
+	// Parse and render a tiddler
+	var rootWidget = this.testcaseWiki.makeTranscludeWidget(title,{document: this.document, parseAsInline: mode === "inline", parentWidget: this});
+	rootWidget.render(parent,nextSibling);
+};
+
+/*
+View a test case tiddler in plain text
+*/
+TestCaseWidget.prototype.testcaseRawTiddler = function(parent,nextSibling,title) {
+	var self = this;
+	// Render a text widget with the text of a tiddler
+	var text = this.testcaseWiki.getTiddlerText(title);
+	parent.insertBefore(this.document.createTextNode(text),nextSibling);
+};
+
+/*
+Find child data widgets
+*/
+TestCaseWidget.prototype.findDataWidgets = function(children,tag,callback) {
+	var self = this;
+	$tw.utils.each(children,function(child) {
+		if(child.dataWidgetTag === tag) {
+			callback(child);
+		}
+		if(child.children) {
+			self.findDataWidgets(child.children,tag,callback);
+		}
+	});
+};
+
+/*
+Find the child data widgets
+*/
+TestCaseWidget.prototype.readTiddlerDataWidgets = function(children) {
+	var self = this,
+		results = [];
+	this.findDataWidgets(children,"data",function(widget) {
+		Array.prototype.push.apply(results,self.readTiddlerDataWidget(widget));
+	});
+	return results;
+};
+
+/*
+Read the value(s) from a data widget
+*/
+TestCaseWidget.prototype.readTiddlerDataWidget = function(dataWidget) {
+	var self = this;
+	// Start with a blank object
+	var item = Object.create(null);
+	// Read any attributes not prefixed with $
+	$tw.utils.each(dataWidget.attributes,function(value,name) {
+		if(name.charAt(0) !== "$") {
+			item[name] = value;			
+		}
+	});
+	// Deal with $tiddler or $filter attributes
+	var titles;
+	if(dataWidget.hasAttribute("$tiddler")) {
+		titles = [dataWidget.getAttribute("$tiddler")];
+	} else if(dataWidget.hasAttribute("$filter")) {
+		titles = this.wiki.filterTiddlers(dataWidget.getAttribute("$filter"));
+	}
+	if(titles) {
+		var self = this;
+		var results = [];
+		$tw.utils.each(titles,function(title,index) {
+			var tiddler = self.wiki.getTiddler(title),
+				fields;
+			if(tiddler) {
+				fields = tiddler.getFieldStrings();
+			}
+			results.push($tw.utils.extend({},fields,item));
+		})
+		return results;
+	} else {
+		return [item];
+	}
+};
+
+/*
+Compute the internal state of the widget
+*/
+TestCaseWidget.prototype.execute = function() {
+	this.testcaseTiddler = this.getAttribute("testcase-tiddler");
+	this.testcaseTemplate = this.getAttribute("template","$:/core/ui/testcases/DefaultTemplate");
+	// Make child widgets
+	var parseTreeNodes = [{
+		type: "transclude",
+		attributes: {
+			tiddler: {
+				name: "tiddler",
+				type: "string",
+				value: this.testcaseTemplate
+			}
+		},
+		isBlock: true}];
+	this.makeChildWidgets(parseTreeNodes);
+};
+
+/*
+Selectively refreshes the widget if needed. Returns true if the widget or any of its children needed re-rendering
+*/
+TestCaseWidget.prototype.refresh = function(changedTiddlers) {
+	var changedAttributes = this.computeAttributes();
+	if($tw.utils.count(changedAttributes) > 0) {
+		this.refreshSelf();
+		return true;
+	} else {
+		return this.refreshChildren(changedTiddlers);
+	}
+};
+
+exports["testcase"] = TestCaseWidget;
+
+})();

core/ui/TestCases/DefaultTemplate.tid

@@ -0,0 +1,18 @@
+title: $:/core/ui/testcases/DefaultTemplate
+
+\whitespace trim
+<div class="tc-testcase-wrapper">
+<div class="tc-testcase-header">
+<h2><$testcase-transclude tiddler="Description" mode="inline"/></h2>
+</div>
+<div class="tc-testcase-panes">
+<div class="tc-testcase-source">
+<pre>
+<$testcase-view tiddler="Output"/>
+</pre>
+</div>
+<div class="tc-testcase-output">
+<$testcase-transclude tiddler="Output"/>
+</div>
+</div>
+</div>

editions/geospatialdemo/tiddlers/Example Test Case.tid

@@ -0,0 +1,26 @@
+title: Example Test Case
+type: text/vnd.tiddlywiki-multiple
+
+title: Description
+
+Testing the geonearest operator
++
+title: Output
+
+\whitespace trim
+<$let
+	oxford={{{ [geopoint[51.751944],[-1.257778]jsonset[id],[Oxford]] }}}
+	winchester={{{ [geopoint[51.0632],[-1.308]jsonset[id],[Winchester]] }}}
+	new-york={{{ [geopoint[40.730610],[-73.935242]jsonset[id],[New York]] }}}
+>
+
+<$text text={{{ =[<oxford>] =[<winchester>] +[geonearestpoint<new-york>jsonget[id]] }}}/>,
+<$text text={{{ =[<oxford>] =[[Not a point]] +[geonearestpoint<new-york>jsonget[id]] }}}/>,
+<$text text={{{ =[[Not a point]] +[geonearestpoint<new-york>jsonget[id]] }}}/>
+
+</$let>
+
++
+title: ExpectedResult
+
+<p>Winchester,Oxford,</p>

editions/geospatialdemo/tiddlers/HelloThere.tid

@@ -26,3 +26,22 @@ This demo requires that the API keys needed to access external services be obtai
 />
 
 <<tabs tabsList:"[all[tiddlers+shadows]tag[$:/tags/GeospatialDemo]]" default:"GeoMarkers">>
+
+---
+
+! Test Cases
+
+<$testcase testcase-tiddler="Example Test Case">
+</$testcase>
+
+<$testcase>
+<$data title="Description" text="Testing the ways JavaScript macros can be invoked"/>
+<$data title="Output" text="""\whitespace trim
+
+<<makedatauri text:"Wildebeest" type:"text/plain">>
+
+<$macrocall $name="makedatauri" text="Wildebeest" type="text/plain"/>
+"""/>
+<$data title="ExpectedResult" text="""<p><a class="tc-tiddlylink-external" href="data:text/plain,Wildebeest" rel="noopener noreferrer" target="_blank">data:text/plain,Wildebeest</a></p><p><a class="tc-tiddlylink-external" href="data:text/plain,Wildebeest" rel="noopener noreferrer" target="_blank">data:text/plain,Wildebeest</a></p>
+"""/>
+</$testcase>

editions/tw5.com/tiddlers/widgets/DataWidget.tid

@@ -0,0 +1,43 @@
+caption: data
+created: 20230406161341763
+modified: 20230406161341763
+tags: Widgets
+title: DataWidget
+type: text/vnd.tiddlywiki
+
+! Introduction
+
+The data widget is used with the <<.wlink TestCaseWidget>> widget and the [[Innerwiki Plugin]] to specify payload tiddlers that are to be included in the test case or innerwiki.
+
+! Content and Attributes
+
+The content of the data widget is rendered as if the data widget were not present. It supports the following attributes:
+
+|!Attribute |!Description |
+|<<.attr $tiddler>> |The title of a tiddler to be used as a payload tiddler (optional) |
+|<<.attr $filter>> |A filter string identifying tiddlers to be used as payload tiddlers (optional) |
+|//any attribute<br>not starting<br>with $// |Field values to be assigned to the payload tiddler(s) |
+
+The data widget can be used in three different ways:
+
+* Without the `$tiddler` or `$filter` attributes, the remaining attributes provide the fields for a single payload tiddler
+* With the `$tiddler` attribute present, the payload tiddler takes its fields from that tiddler with the remaining attributes overriding those fields
+* With the `$filter` attribute present, the payload is a copy of all of the tiddlers identified by the filter, with the remaining attributes overriding those fields of each one
+
+This example injects a tiddler with the title "Epsilon" and the text "Theta":
+
+```
+<$data title="Epsilon" text="Theta"/>
+```
+
+This example injects a copy of the "HelloThere" tiddler with the addition of the field "custom" set to "Alpha":
+
+```
+<$data $tiddler="HelloThere" custom="Alpha"/>
+```
+
+This example injects all image tiddlers with the addition of the field "custom" set to "Beta":
+
+```
+<$data $filter="[is[image]]" custom="Beta"/>
+```

editions/tw5.com/tiddlers/widgets/TestCaseWidget.tid

@@ -0,0 +1,30 @@
+caption: testcase
+created: 20230406161341763
+modified: 20230406161341763
+tags: Widgets
+title: TestCaseWidget
+type: text/vnd.tiddlywiki
+
+! Introduction
+
+The testcase widget creates an independent subwiki loaded with specified tiddlers and then renders a template that can display and render tiddlers from within the subwiki. This makes it possible to run independent tests that also serve as documentation examples.
+
+! Content and Attributes
+
+The content of the `<$testcase>` widget is not displayed but instead is scanned for <<.wlink DataWidget>> widgets that define tiddlers to be included in the test case.
+
+|!Attribute |!Description |
+|<<.attr testcase-tiddler>> |Optional title of a tiddler containing a test case in `text/vnd.tiddlywiki-multiple` format (see below) |
+|<<.attr template>> |Optional title of the template used to display the testcase (defaults to $:/core/ui/testcases/DefaultTemplate) |
+
+! Example
+
+<$testcase>
+<$data $tiddler="$:/core"/>
+<$data title="Description" text="Simple example of a test case"/>
+<$data title="Output" text="""<$testcase>
+<$data title="Description" text="How to calculate 2 plus 2"/>
+<$data title="Output" text="<$text text={{{ =2 =[add[2]] }}}/>"/>
+</$testcase>
+"""/>
+</$testcase>

plugins/tiddlywiki/innerwiki/anchor.js

@@ -0,0 +1,17 @@
+/*\
+title: $:/plugins/tiddlywiki/innerwiki/anchor.js
+type: application/javascript
+module-type: widget
+
+Anchor widget to represent an innerwiki graphical anchor. Clone of the data widget
+
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false */
+"use strict";
+
+exports.anchor = require("$:/core/modules/widgets/data.js").data;
+
+})();

plugins/tiddlywiki/innerwiki/innerwiki.js

@@ -15,7 +15,7 @@ Widget to display an innerwiki in an iframe
 var DEFAULT_INNERWIKI_TEMPLATE = "$:/plugins/tiddlywiki/innerwiki/template";
 
 var Widget = require("$:/core/modules/widgets/widget.js").widget,
-	DataWidget = require("$:/plugins/tiddlywiki/innerwiki/data.js").data,
+	DataWidget = require("$:/core/modules/widgets/data.js").data,
 	dm = $tw.utils.domMaker;
 
 var InnerWikiWidget = function(parseTreeNode,options) {

themes/tiddlywiki/vanilla/base.tid

@@ -3156,6 +3156,52 @@ select {
 	fill: <<colour background>>;
 }
 
+/*
+** Test Cases
+*/
+
+.tc-testcase-wrapper {
+	border: 1px solid <<colour foreground>>;
+	background-color: <<colour muted-foreground>>;
+	border-radius: 3px;
+}
+
+.tc-testcase-header {
+	font-weight: normal;
+	margin: 0.5em 0;
+	padding: 0 0.5em;
+}
+
+.tc-testcase-header > h2,
+.tc-testcase-source > pre {
+	margin: 0;
+}
+
+.tc-testcase-source > pre {
+	height: 100%;
+}
+
+.tc-testcase-panes {
+	background: <<colour background>>;
+	display: flex;
+	align-items: stretch;
+	flex-wrap: wrap;
+	padding: 0.5em;
+}
+
+.tc-testcase-source {
+	border: 1px solid <<colour background>>;
+	flex: 1 0 50%;
+	min-width: 250px;
+}
+
+.tc-testcase-output {
+	border: 1px solid <<colour background>>;
+	flex: 1 0 50%;
+	min-width: 250px;
+}
+
+
 /*
 ** Flexbox utility classes
 */