Toward an Eleventy Plugin

CHANGE.md

@@ -1,3 +1,16 @@
+# Next release
+
+- The web Document renderer now supports a `pageTurnBehavior` option with three
+  modes: 'log' (default, removes options but keeps narrative), 'remove' (removes
+  the entire prior frame), and 'fade' (fades out and removes the prior frame,
+  which requires a CSS transition on the frame element).
+- The `end` handler hook is now called after the final display, allowing handlers
+  to act on the fully rendered narrative.
+- Hyperlinks following the Peruácru convention are now rendered as clickable
+  links in the web Document renderer.
+  Text blocks ending with a URL (e.g., `{Example https://example.com}`) render
+  as anchor tags.
+
 # v4.0.3
 
 - Regenerated `package-lock.json`, dropping references to unpm from these packages:

HACKNI.md

@@ -249,6 +249,19 @@ The Kni document serves as both renderer and dialog controller.
 The web dialog is relatively simple, building a DOM on the fly, with certain CSS
 to allow the containing document to govern its position and animation.
 
+The Document constructor accepts an options object with the following properties:
+
+- `createPage(webDocument, kniDocument)` is a function that creates a new page element.
+- `meterFaultButton` is a button element that the document will use to display
+  meter faults.
+- `pageTurnBehavior` controls how the prior frame is handled when starting a new
+  page. The options are 'log' (default, removes options but keeps narrative),
+  'remove' (removes the entire prior frame), and 'fade' (fades out and removes
+  the prior frame with a CSS transition, which requires a transition style to
+  exist on the frame element).
+
+If a text block like `{Example https://example.com}` ends with a URL, the
+web `Document` renderer will embed a hyperlink instead of the verbatim URL.
 
 ## The Command Line Dialog Renderer
 

MANUAL.md

@@ -803,6 +803,19 @@ supports some operators that assist making common typographical niceties.
 - ``--`` is good for an en-dash, suitable for use in number ranges like 1–10.
 - ``---`` is good for em-dash—suitable for parenthetical phrases.
 
+## Hyperlinks
+
+Kni supports hyperlinks in text blocks. The recommended convention is to
+express hyperlinks in stand-alone blocks with the link text followed by a URL:
+
+```
+{Example https://example.com}
+```
+
+The web Document renderer recognizes this pattern and renders it as a clickable
+anchor tag. The link text becomes the visible text, and the URL becomes the
+href. Links open in a new tab with appropriate security attributes.
+
 ## Multiple Files
 
 A Kni story can span multiple files. Pass all of these files to the `kni`

document.js

@@ -1,5 +1,13 @@
+const linkMatcher = /\s*(\w+:\/\/\S+)$/;
+
 export default class Document {
-  constructor(element, createPage, meterFaultButton) {
+  constructor(element, options = {}) {
+    const {
+      createPage = undefined,
+      meterFaultButton = undefined,
+      pageTurnBehavior = 'log',
+    } = options;
+
     const self = this;
     this.document = element.ownerDocument;
     this.parent = element;
@@ -21,6 +29,7 @@ export default class Document {
     };
     this.createPage = createPage || this.createPage;
     this.meterFaultButton = meterFaultButton;
+    this.pageTurnBehavior = pageTurnBehavior;
 
     Object.seal(this);
   }
@@ -40,8 +49,22 @@ export default class Document {
       this.br = false;
       lift = '';
     }
-    // TODO merge with prior text node
-    this.cursor.appendChild(document.createTextNode(lift + text));
+    const match = linkMatcher.exec(text);
+    if (match === null) {
+        // TODO merge with prior text node
+        this.cursor.appendChild(document.createTextNode(lift + text));
+    } else {
+        // Support a hyperlink convention.
+        if (lift !== '') {
+            this.cursor.appendChild(document.createTextNode(lift));
+        }
+        const link = document.createElement('a');
+        link.href = match[1];
+        link.target = '_blank';
+        link.rel = 'noreferrer';
+        link.appendChild(document.createTextNode(text.slice(0, match.index)));
+        this.cursor.appendChild(link);
+    }
     this.carry = drop;
   }
 
@@ -100,9 +123,15 @@ export default class Document {
 
   clear() {
     if (this.frame) {
-      this.frame.style.opacity = 0;
-      this.frame.style.transform = 'translateX(-2ex)';
-      this.frame.addEventListener('transitionend', this);
+      if (this.pageTurnBehavior === 'log') {
+        this.options.remove();
+      } else if (this.pageTurnBehavior === 'remove') {
+        this.frame.remove();
+      } else if (this.pageTurnBehavior === 'fade') {
+        this.frame.style.opacity = 0;
+        this.frame.style.transform = 'translateX(-2ex)';
+        this.frame.addEventListener('transitionend', this);
+      }
     }
     this.createPage(this.document, this);
     this.cursor = null;
@@ -141,9 +170,8 @@ export default class Document {
   }
 
   handleEvent(event) {
-    if (event.target.parentNode === this.parent) {
-      this.parent.removeChild(event.target);
-    }
+    // transitionend on this.frame, only
+    event.target.remove();
   }
 
   meterFault() {

engine.js

@@ -163,10 +163,10 @@ export default class Engine {
   }
 
   end() {
+    this.display();
     if (this.handler && this.handler.end) {
       this.handler.end(this);
     }
-    this.display();
     this.dialog.close();
     return false;
   }

entry.js

@@ -44,7 +44,10 @@ meterFaultButton.addEventListener('click', () => {
   engine.clearMeterFault();
 });
 
-const doc = new Document(document.body, null, meterFaultButton);
+const doc = new Document(document.body, {
+  meterFaultButton,
+  pageTurnBehavior: 'fade',
+});
 
 const engine = new Engine({
   story: story,