ep_table_of_contents 0.3.133 → 0.3.135

package/README.md

@@ -5,6 +5,23 @@
 Enable under settings.
 Create headings, watch the TOC populate in real time.
 
+## Installation
+
+Install the way Etherpad expects plugins to be installed — via the admin
+UI (**Admin → Manage Plugins → Search** for `ep_table_of_contents` and
+click *Install*), or from the Etherpad root directory:
+
+```sh
+pnpm run plugins install ep_table_of_contents
+```
+
+> ⚠️ Don't run `npm i ep_table_of_contents` yourself from the Etherpad
+> source tree. It adds the plugin to the top-level `package.json` but
+> doesn't hook it into Etherpad's own plugin registry, which can leave
+> Etherpad unable to start with `npm ls` errors (see #154).
+
+After installing, restart Etherpad.
+
 ## Configuration
 
 If you want to have the TOC shown by default, add following snippet to your `settings.json`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ep_table_of_contents",
-  "version": "0.3.133",
+  "version": "0.3.135",
   "description": "View a table of contents for your pad",
   "author": {
     "name": "John McLear",

package/static/js/aceEditEvent.js

@@ -1,14 +1,23 @@
-/* global tableOfContents */
 'use strict';
 
+// aceEditEvent fires inside ACE's inner iframe, which has its own `globalThis`
+// separate from the outer pad page where toc.js runs. Reach across the
+// iframe boundary via `window.top` (the topmost frame, i.e. the outer pad
+// page). If toc.js hasn't executed yet — e.g. during very early pad init —
+// silently skip; it will be called again on the next edit event.
+const getToc = () => (typeof globalThis !== 'undefined' && globalThis.tableOfContents) ||
+    (window.top && window.top.tableOfContents) || null;
+
 exports.aceEditEvent = (hookName, args) => {
   // dont do anything on idle work timer, wait for changes..
   if (args.callstack && args.callstack.type === 'idleWorkTimer') return false;
+  const toc = getToc();
+  if (!toc) return;
   if (args.rep) {
-    tableOfContents.showPosition(args.rep);
+    toc.showPosition(args.rep);
   }
 
   if ($('#toc:visible').length > 0) {
-    tableOfContents.update();
+    toc.update();
   }
 };

package/static/js/postAceInit.js

@@ -1,6 +1,14 @@
-/* global tableOfContents */
 'use strict';
 
+// postAceInit is loaded as a CommonJS plugin hook module; its scope is not
+// the same as the <script> tag that loads toc.js, so `tableOfContents` is
+// not visible via the normal scope chain. Look it up explicitly on the
+// topmost window (where toc.js runs) with a globalThis fallback for the
+// case where both happen to share a realm.
+const getToc = () => (typeof globalThis !== 'undefined' && globalThis.tableOfContents) ||
+    (window.top && window.top.tableOfContents) ||
+    window.tableOfContents || null;
+
 exports.postAceInit = () => {
   if (!$('#editorcontainerbox').hasClass('flex-layout')) {
     $.gritter.add({
@@ -11,28 +19,30 @@ exports.postAceInit = () => {
       class_name: 'error',
     });
   }
+  const toc = getToc();
+  if (!toc) return;
   const optionToc = $('#options-toc');
   /* on click */
   optionToc.on('click', () => {
     if (optionToc.is(':checked')) {
-      tableOfContents.enable(); // enables line tocping
+      toc.enable(); // enables line tocping
     } else {
       optionToc.prop('checked', false);
-      tableOfContents.disable(); // disables line tocping
+      toc.disable(); // disables line tocping
     }
   });
   if (optionToc.is(':checked')) {
-    tableOfContents.enable();
+    toc.enable();
   } else {
-    tableOfContents.disable();
+    toc.disable();
   }
 
-  const tocParam = tableOfContents.getParam('toc');
+  const tocParam = toc.getParam('toc');
   if (tocParam === true) {
     optionToc.prop('checked', true);
-    tableOfContents.enable();
+    toc.enable();
   } else if (tocParam === false) {
     optionToc.prop('checked', false);
-    tableOfContents.disable();
+    toc.disable();
   }
 };

package/static/js/toc.js

@@ -63,7 +63,14 @@ if (typeof $ !== 'undefined') {
   });
 }
 
-const tableOfContents = {
+// Expose on globalThis so other plugin scripts (postAceInit.js,
+// aceEditEvent.js) that run in their own CommonJS-style module scopes can
+// still reach it. Top-level `const` in a <script> tag is script-scoped,
+// not a global, so without this the bare `tableOfContents` identifier in
+// those modules throws `ReferenceError: tableOfContents is not defined`
+// on pad load. globalThis resolves to `window` in the browser and to
+// `global` in Node.js, so the Node unit tests keep working too.
+const tableOfContents = globalThis.tableOfContents = {
 
   enable() {
     $('#toc').show();