LinkWizard: add method to create a relative link

This is not used, yet. Usage will be added in a future commit.

Since we don't have a proper testing framework in place, yet. Tests have
been added as a standalone script that can be run manually.

Author: splitbrain

lib/scripts/linkwiz.js

@@ -336,6 +336,69 @@ class LinkWizard {
             this.hide();
         }
     }
+
+    /**
+     * Create a relative ID from a given reference ID and a full ID to link to
+     *
+     * Both IDs are expected to be clean, (eg. the result of cleanID()). No relative paths,
+     * leading colons or similar things are alowed. As long as pages have a common prefix,
+     * a relative link is constructed.
+     *
+     * This method is static and meant to be reused by other scripts if needed.
+     *
+     * @todo does currently not create page relative links using ~
+     * @param {string} ref The ID of a page the link is used on
+     * @param {string} id The ID to link to
+     */
+    static createRelativeID(ref, id) {
+        const sourceNs = ref.split(':');
+        [/*sourcePage*/] = sourceNs.pop();
+        const targetNs = id.split(':');
+        const targetPage = targetNs.pop()
+        const relativeID = [];
+
+        // Find the common prefix length
+        let commonPrefixLength = 0;
+        while (
+            commonPrefixLength < sourceNs.length &&
+            commonPrefixLength < targetNs.length &&
+            sourceNs[commonPrefixLength] === targetNs[commonPrefixLength]
+            ) {
+            commonPrefixLength++;
+        }
+
+
+        if (sourceNs.length) {
+            // special treatment is only needed when the reference is a namespaced page
+            if (commonPrefixLength) {
+                if (commonPrefixLength === sourceNs.length && commonPrefixLength === targetNs.length) {
+                    // both pages are in the same namespace
+                    // link consists of simple page only
+                    // namespaces are irrelevant
+                } else if (commonPrefixLength < sourceNs.length) {
+                    // add .. for each missing namespace from common to the target
+                    relativeID.push('..'.repeat(sourceNs.length - commonPrefixLength));
+                } else {
+                    // target is below common prefix, add .
+                    relativeID.push('.');
+                }
+            } else if (targetNs.length === 0) {
+                // target is in the root namespace, but source is not, make it absolute
+                relativeID.push('');
+            }
+            // add any remaining parts of targetNS
+            relativeID.push(...targetNs.slice(commonPrefixLength));
+        } else {
+            // source is in the root namespace, just use target as is
+            relativeID.push(...targetNs);
+        }
+
+        // add targetPage
+        relativeID.push(targetPage);
+
+        return relativeID.join(':');
+    }
+
 }
 
 const dw_linkwiz = new LinkWizard();

lib/scripts/linkwiz.test.js

@@ -0,0 +1,34 @@
+/**
+ * Tests for the LinkWizard class
+ *
+ * This is a simple self-contained test suite until we introduce a proper way to run JavaScript tests
+ * in DokuWiki.
+ *
+ * Needs to be run manually as:
+ *
+ * cat linkwiz.js linkwiz.test.js | node
+ */
+
+function runLinkWizardTests() {
+    const testCases = [
+        { ref: 'a:b:c', id: 'a:b:d', expected: 'd' },
+        { ref: 'a:b:c', id: 'a:b:c:d:e', expected: '.:c:d:e' },
+        { ref: 'a:b:c', id: 'a:b:c:d:e', expected: '.:c:d:e' },
+        { ref: 'a', id: 'a:b:c', expected: 'a:b:c' },
+        { ref: 'a:b', id: 'c:d', expected: 'c:d' },
+        { ref: 'a:b:c', id: 'a:d:e', expected: '..:d:e' },
+        { ref: 'a:b', id: 'c', expected: ':c' },
+    ];
+
+    testCases.forEach(({ ref, id, expected }, index) => {
+        const result = LinkWizard.createRelativeID(ref, id);
+        if (result === expected) {
+            console.log(`Test ${index + 1} passed`);
+        } else {
+            console.log(`Test ${index + 1} failed: expected ${expected}, got ${result}`);
+        }
+    });
+}
+
+// Run the tests
+runLinkWizardTests();