Feat: allow link to section mark

core/modules/parsers/wikiparser/rules/anchor.js

@@ -0,0 +1,49 @@
+/*\
+title: $:/core/modules/parsers/wikiparser/rules/anchor.js
+type: application/javascript
+module-type: wikirule
+
+Use hash as a tag for paragraph, we call it anchor.
+
+1. Hash won't change, it can be written by hand or be generated, and it is a ` \^\S+$` string after line: `text ^cb9d485` or `text ^1`, so it can be human readable (while without space), here are the parse rule for this.
+2. When creating widgets for rendering, omit this hash, so it's invisible in view mode. But this widget will create an anchor to jump to.
+
+\*/
+exports.name = "anchor";
+exports.types = {inline: true};
+
+/*
+Instantiate parse rule
+*/
+exports.init = function(parser) {
+	this.parser = parser;
+	// Regexp to match the anchor.
+	// 1. inlineId: located on the end of the line, with a space before it, means it's the id of the current block.
+	// 2. blockId: located at start of the line, no space, means it's the id of the previous block. Because some block can't have id suffix, otherwise id break the block mode parser like codeblock.
+	this.matchRegExp = /[ ]\^(\S+)$|^\^(\S+)$/mg;
+};
+
+/*
+Parse the most recent match
+*/
+exports.parse = function() {
+	// Move past the match
+	this.parser.pos = this.matchRegExp.lastIndex;
+	// will be one of following case, another will be undefined
+	var inlineId = this.match[1];
+	var blockId = this.match[2];
+	var id = inlineId || blockId || '';
+	var anchorStart = this.parser.pos;
+	var anchorEnd = anchorStart + id.length;
+	// Parse tree nodes to return
+	return [{
+		type: "anchor",
+		attributes: {
+			id: {type: "string", value: id, start: anchorStart, end: anchorEnd},
+			// `yes` means the block that this anchor pointing to, is before this node, both anchor and the block, is in a same parent node's children list.
+			// empty means the block is this node's direct parent node.
+			previousSibling: {type: "string", value: Boolean(blockId) ? "yes" : ""},
+		},
+		children: []
+	}];
+};

core/modules/parsers/wikiparser/rules/prettylink.js

@@ -23,8 +23,8 @@ exports.types = {inline: true};
 
 exports.init = function(parser) {
 	this.parser = parser;
-	// Regexp to match
-	this.matchRegExp = /\[\[(.*?)(?:\|(.*?))?\]\]/mg;
+	// Regexp to match `[[Alias|Title^blockId]]`, the `Alias|` and `^blockId` are optional.
+	this.matchRegExp = /\[\[(.*?)(?:\|(.*?)?)?(?:\^([^|\s^]+)?)?\]\]/mg;
 };
 
 exports.parse = function() {
@@ -34,13 +34,18 @@ exports.parse = function() {
 	// Process the link
 	var text = this.match[1],
 		link = this.match[2] || text,
+		anchor = this.match[3] || "",
 		textEndPos = this.parser.source.indexOf("|", start);
 	if (textEndPos < 0 || textEndPos > this.matchRegExp.lastIndex) {
 		textEndPos = this.matchRegExp.lastIndex - 2;
 	}
 	var linkStart = this.match[2] ? (start + this.match[1].length + 1) : start;
 	var linkEnd = linkStart + link.length;
 	if($tw.utils.isLinkExternal(link)) {
+		// add back the part after `^` to the ext link, if it happen to has one. Here is is not an anchor, but a part of the external URL.
+		if(anchor) {
+			link = link + "^" + anchor;
+		}
 		return [{
 			type: "element",
 			tag: "a",
@@ -55,10 +60,13 @@ exports.parse = function() {
 			}]
 		}];
 	} else {
+		var anchorStart = anchor ? (linkEnd + 1) : linkEnd;
+		var anchorEnd = anchorStart + anchor.length;
 		return [{
 			type: "link",
 			attributes: {
-				to: {type: "string", value: link, start: linkStart, end: linkEnd}
+				to: {type: "string", value: link, start: linkStart, end: linkEnd},
+				toAnchor: {type: "string", value: anchor, start: anchorStart, end: anchorEnd},
 			},
 			children: [{
 				type: "text", text: text, start: start, end: textEndPos

core/modules/story.js

@@ -90,12 +90,12 @@ Story.prototype.saveStoryList = function(storyList) {
 	));
 };
 
-Story.prototype.addToHistory = function(navigateTo,navigateFromClientRect) {
+Story.prototype.addToHistory = function(navigateTo,fromPageRect,anchor) {
 	var titles = $tw.utils.isArray(navigateTo) ? navigateTo : [navigateTo];
 	// Add a new record to the top of the history stack
 	var historyList = this.wiki.getTiddlerData(this.historyTitle,[]);
 	$tw.utils.each(titles,function(title) {
-		historyList.push({title: title, fromPageRect: navigateFromClientRect});
+		historyList.push({title: title, fromPageRect: fromPageRect, anchor: anchor});
 	});
 	this.wiki.setTiddlerData(this.historyTitle,historyList,{"current-tiddler": titles[titles.length-1]});
 };

core/modules/storyviews/classic.js

@@ -26,12 +26,23 @@ ClassicStoryView.prototype.navigateTo = function(historyInfo) {
 	}
 	var listItemWidget = this.listWidget.children[listElementIndex],
 		targetElement = listItemWidget.findFirstDomNode();
+	// If anchor is provided, find the element the anchor pointing to
+	var foundAnchor = false;
+	if(listItemWidget && historyInfo.anchor) {
+		var anchorWidget = $tw.utils.findChildNodeInTree(listItemWidget, function(widget) {
+			return widget.anchorId === historyInfo.anchor;
+		});
+		if(anchorWidget) {
+			targetElement = anchorWidget.findAnchorTargetDomNode()
+			foundAnchor = true;
+		}
+	}
 	// Abandon if the list entry isn't a DOM element (it might be a text node)
 	if(!targetElement || targetElement.nodeType === Node.TEXT_NODE) {
 		return;
 	}
 	// Scroll the node into view
-	this.listWidget.dispatchEvent({type: "tm-scroll", target: targetElement});
+	this.listWidget.dispatchEvent({type: "tm-scroll", target: targetElement, highlight: foundAnchor});
 };
 
 ClassicStoryView.prototype.insert = function(widget) {

core/modules/storyviews/pop.js

@@ -23,12 +23,23 @@ PopStoryView.prototype.navigateTo = function(historyInfo) {
 	}
 	var listItemWidget = this.listWidget.children[listElementIndex],
 		targetElement = listItemWidget.findFirstDomNode();
+	// If anchor is provided, find the element the anchor pointing to
+	var foundAnchor = false;
+	if(listItemWidget && historyInfo.anchor) {
+		var anchorWidget = $tw.utils.findChildNodeInTree(listItemWidget, function(widget) {
+			return widget.anchorId === historyInfo.anchor;
+		});
+		if(anchorWidget) {
+			targetElement = anchorWidget.findAnchorTargetDomNode()
+			foundAnchor = true;
+		}
+	}
 	// Abandon if the list entry isn't a DOM element (it might be a text node)
 	if(!targetElement || targetElement.nodeType === Node.TEXT_NODE) {
 		return;
 	}
 	// Scroll the node into view
-	this.listWidget.dispatchEvent({type: "tm-scroll", target: targetElement});
+	this.listWidget.dispatchEvent({type: "tm-scroll", target: targetElement, highlight: foundAnchor});
 };
 
 PopStoryView.prototype.insert = function(widget) {

core/modules/storyviews/zoomin.js

@@ -51,6 +51,16 @@ ZoominListView.prototype.navigateTo = function(historyInfo) {
 	}
 	var listItemWidget = this.listWidget.children[listElementIndex],
 		targetElement = listItemWidget.findFirstDomNode();
+	// If anchor is provided, find the element the anchor pointing to
+	var anchorElement = null;
+	if(listItemWidget && historyInfo.anchor) {
+		var anchorWidget = $tw.utils.findChildNodeInTree(listItemWidget, function(widget) {
+			return widget.anchorId === historyInfo.anchor;
+		});
+		if(anchorWidget) {
+			anchorElement = anchorWidget.findAnchorTargetDomNode()
+		}
+	}
 	// Abandon if the list entry isn't a DOM element (it might be a text node)
 	if(!targetElement) {
 		return;
@@ -119,7 +129,10 @@ ZoominListView.prototype.navigateTo = function(historyInfo) {
 		},duration);
 	}
 	// Scroll the target into view
-//	$tw.pageScroller.scrollIntoView(targetElement);
+	if(anchorElement) {
+		this.listWidget.dispatchEvent({type: "tm-scroll", target: anchorElement, highlight: true});
+	}
+  //	$tw.pageScroller.scrollIntoView(targetElement);
 };
 
 /*

core/modules/utils/dom/scroller.js

@@ -49,7 +49,9 @@ Handle an event
 */
 PageScroller.prototype.handleEvent = function(event) {
 	if(event.type === "tm-scroll") {
-		var options = {};
+		var options = {
+			highlight: event.highlight,
+		};
 		if($tw.utils.hop(event.paramObject,"animationDuration")) {
 			options.animationDuration = event.paramObject.animationDuration;
 		}
@@ -65,14 +67,21 @@ PageScroller.prototype.handleEvent = function(event) {
 
 /*
 Handle a scroll event hitting the page document
+
+options:
+- animationDuration: total time of scroll animation
+- highlight: highlight the element after scrolling, to make it evident. Usually to focus an anchor in the middle of the tiddler.
 */
 PageScroller.prototype.scrollIntoView = function(element,callback,options) {
 	var self = this,
 		duration = $tw.utils.hop(options,"animationDuration") ? parseInt(options.animationDuration) : $tw.utils.getAnimationDuration(),
+		highlight = options.highlight || false,
 		srcWindow = element ? element.ownerDocument.defaultView : window;
 	// Now get ready to scroll the body
 	this.cancelScroll(srcWindow);
 	this.startTime = Date.now();
+	// toggle class to allow trigger the highlight animation
+	$tw.utils.removeClass(element,"tc-focus-highlight");
 	// Get the height of any position:fixed toolbars
 	var toolbar = srcWindow.document.querySelector(".tc-adjust-top-of-scroll"),
 		offset = 0;
@@ -121,6 +130,12 @@ PageScroller.prototype.scrollIntoView = function(element,callback,options) {
 			srcWindow.scrollTo(scrollPosition.x + (endX - scrollPosition.x) * t,scrollPosition.y + (endY - scrollPosition.y) * t);
 			if(t < 1) {
 				self.idRequestFrame = self.requestAnimationFrame.call(srcWindow,drawFrame);
+			} else {
+				// the animation is end.
+				if(highlight) {
+					element.focus({ focusVisible: true });
+					$tw.utils.addClass(element,"tc-focus-highlight");
+				}
 			}
 		};
 	drawFrame();

core/modules/utils/parsetree.js

@@ -103,6 +103,21 @@ exports.findParseTreeNode = function(nodeArray,search) {
 	return undefined;
 };
 
+exports.findChildNodeInTree = function(root,searchFn) {
+  if(searchFn(root)) {
+    return root;
+  }
+  if(root.children && root.children.length > 0) {
+    for(var i=0; i<root.children.length; i++) {
+      var result = exports.findChildNodeInTree(root.children[i], searchFn);
+      if(result) {
+        return result;
+      }
+    }
+  }
+  return undefined;
+};
+
 /*
 Helper to get the text of a parse tree node or array of nodes
 */

core/modules/widgets/anchor.js

@@ -0,0 +1,76 @@
+/*\
+title: $:/core/modules/widgets/anchor.js
+type: application/javascript
+module-type: widget
+
+An invisible element with anchor id metadata.
+\*/
+var Widget = require("$:/core/modules/widgets/widget.js").widget;
+var AnchorWidget = function(parseTreeNode,options) {
+	this.initialise(parseTreeNode,options);
+	// only this widget knows target info (if the block is before this node or not), so we need to hook the focus event, and process it here, instead of in the root widget.
+};
+AnchorWidget.prototype = new Widget();
+
+AnchorWidget.prototype.render = function(parent,nextSibling) {
+	// Save the parent dom node
+	this.parentDomNode = parent;
+	// Compute our attributes
+	this.computeAttributes();
+	// Execute our logic
+	this.execute();
+	// Create an invisible DOM element with data that can be accessed from JS or CSS
+	this.idNode = this.document.createElement("span");
+	this.idNode.setAttribute("data-anchor-id",this.anchorId);
+	this.idNode.setAttribute("data-anchor-title",this.tiddlerTitle);
+	// if the actual block is before this node, we need to add a flag to the node
+	if(this.previousSibling) {
+		this.idNode.setAttribute("data-anchor-previous-sibling","true");
+	}
+	this.idNode.className = "tc-anchor";
+	parent.insertBefore(this.idNode,nextSibling);
+	this.domNodes.push(this.idNode);
+};
+
+/*
+Compute the internal state of the widget
+*/
+AnchorWidget.prototype.execute = function() {
+	// Get the id from the parse tree node or manually assigned attributes
+	this.anchorId = this.getAttribute("id");
+	this.tiddlerTitle = this.getVariable("currentTiddler");
+	this.previousSibling = this.getAttribute("previousSibling") === "yes";
+	// Make the child widgets
+	this.makeChildWidgets();
+};
+
+/*
+Find the DOM node pointed by this anchor
+*/
+Widget.prototype.findAnchorTargetDomNode = function() {
+	if(!this.idNode) {
+		return null;
+	}
+	// the actual block is always at the parent level
+	targetElement = this.idNode.parentNode;
+	// need to check if the block is before this node
+	if(this.previousSibling) {
+		targetElement = targetElement.previousSibling;
+	}
+	return targetElement;
+};
+
+/*
+Selectively refreshes the widget if needed. Returns true if the widget or any of its children needed re-rendering
+*/
+AnchorWidget.prototype.refresh = function(changedTiddlers) {
+	var changedAttributes = this.computeAttributes();
+	if(($tw.utils.count(changedAttributes) > 0)) {
+		this.refreshSelf();
+		return true;
+	} else {
+		return this.refreshChildren(changedTiddlers);
+	}
+};
+
+exports.anchor = AnchorWidget;

core/modules/widgets/link.js

@@ -160,6 +160,7 @@ LinkWidget.prototype.handleClickEvent = function(event) {
 	this.dispatchEvent({
 		type: "tm-navigate",
 		navigateTo: this.to,
+		toAnchor: this.toAnchor,
 		navigateFromTitle: this.getVariable("storyTiddler"),
 		navigateFromNode: this,
 		navigateFromClientRect: { top: bounds.top, left: bounds.left, width: bounds.width, right: bounds.right, bottom: bounds.bottom, height: bounds.height
@@ -190,6 +191,7 @@ Compute the internal state of the widget
 LinkWidget.prototype.execute = function() {
 	// Pick up our attributes
 	this.to = this.getAttribute("to",this.getVariable("currentTiddler"));
+	this.toAnchor = this.getAttribute("toAnchor");
 	this.tooltip = this.getAttribute("tooltip");
 	this["aria-label"] = this.getAttribute("aria-label");
 	this.linkClasses = this.getAttribute("class");

core/modules/widgets/navigator.js

@@ -138,9 +138,10 @@ NavigatorWidget.prototype.addToStory = function(title,fromTitle) {
 Add a new record to the top of the history stack
 title: a title string or an array of title strings
 fromPageRect: page coordinates of the origin of the navigation
+anchor:optional anchor id in this tiddler
 */
-NavigatorWidget.prototype.addToHistory = function(title,fromPageRect) {
-	this.story.addToHistory(title,fromPageRect,this.historyTitle);
+NavigatorWidget.prototype.addToHistory = function(title,fromPageRect,anchor) {
+	this.story.addToHistory(title,fromPageRect,anchor);
 };
 
 /*
@@ -151,7 +152,7 @@ NavigatorWidget.prototype.handleNavigateEvent = function(event) {
 	if(event.navigateTo) {
 		this.addToStory(event.navigateTo,event.navigateFromTitle);
 		if(!event.navigateSuppressNavigation) {
-			this.addToHistory(event.navigateTo,event.navigateFromClientRect);
+			this.addToHistory(event.navigateTo,event.navigateFromClientRect,event.toAnchor);
 		}
 	}
 	return false;

core/ui/EditTemplate/title.tid

@@ -4,7 +4,7 @@ tags: $:/tags/EditTemplate
 \whitespace trim
 <$edit-text field="draft.title" class="tc-titlebar tc-edit-texteditor" focus={{{ [{$:/config/AutoFocus}match[title]then[true]] ~[[false]] }}} tabindex={{$:/config/EditTabIndex}} cancelPopups="yes"/>
 
-<$vars pattern="""[\|\[\]{}]""" bad-chars="""`| [ ] { }`""">
+<$vars pattern="""[\^\|\[\]{}]""" bad-chars="""`| ^ [ ] { }`""">
 
 <$list filter="[all[current]regexp:draft.title<pattern>]" variable="listItem">
 

editions/dev/tiddlers/mechanism/HistoryMechanism.tid

@@ -0,0 +1,8 @@
+created: 20230922141042399
+modified: 20230922141423022
+tags: 
+title: HistoryMechanism
+
+The story view is created by [[$:/core/ui/PageTemplate/story]] core page template, which uses list widget to render tiddlers. In this way, page template will reflect to history's change.
+
+List widget has a `history="$:/HistoryList"` parameter, that will be used in list widget's `handleHistoryChanges` method, and pass to the `this.storyview.navigateTo`, you can read [[storyview module]] for how storyview use the changed history.