ep_table_of_contents 0.3.132 → 0.3.133

package/.github/workflows/backend-tests.yml

@@ -26,7 +26,7 @@ jobs:
         with:
           repository: ether/etherpad-lite
           path: etherpad-lite
-      - uses: pnpm/action-setup@v3
+      - uses: pnpm/action-setup@v6
         name: Install pnpm
         with:
           version: 10
@@ -35,7 +35,7 @@ jobs:
         shell: bash
         run: |
           echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         name: Setup pnpm cache
         with:
           path: ${{ env.STORE_PATH }}

package/.github/workflows/frontend-tests.yml

@@ -15,7 +15,7 @@ jobs:
         uses: actions/checkout@v6
         with:
           repository: ether/etherpad-lite
-      - uses: pnpm/action-setup@v3
+      - uses: pnpm/action-setup@v6
         name: Install pnpm
         with:
           version: 10
@@ -24,7 +24,7 @@ jobs:
         shell: bash
         run: |
           echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         name: Setup pnpm cache
         with:
           path: ${{ env.STORE_PATH }}

package/.github/workflows/npmpublish.yml

@@ -31,7 +31,7 @@ jobs:
         uses: actions/checkout@v6
         with:
           repository: ether/etherpad-lite
-      - uses: pnpm/action-setup@v5
+      - uses: pnpm/action-setup@v6
         name: Install pnpm
         with:
           version: 10
@@ -59,12 +59,20 @@ jobs:
           [ "${NEW_COMMITS}" -gt 0 ] || exit 0
           git config user.name 'github-actions[bot]'
           git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
-          pnpm i
+          pnpm i --frozen-lockfile
           # `pnpm version patch` bumps package.json, makes a commit, and creates
           # a `v<new-version>` tag. Capture the new tag name from package.json
           # rather than parsing pnpm's output, which has historically varied.
-          pnpm version patch
-          NEW_TAG="v$(node -p "require('./package.json').version")"
+          # Bump the patch component directly with Node. pnpm/action-setup@v6
+          # sometimes installs pnpm 11 pre-releases even when version: 10.x is
+          # requested (pnpm/action-setup#225); those pre-releases either skip
+          # the git commit/tag or reject --no-git-tag-version as unknown.
+          # Doing the bump in Node sidesteps both failure modes.
+          NEW_VERSION=$(node -e "const fs=require('fs');const p=require('./package.json');const v=p.version.split('.');v[2]=String(Number(v[2])+1);p.version=v.join('.');fs.writeFileSync('./package.json',JSON.stringify(p,null,2)+'\n');console.log(p.version);")
+          NEW_TAG="v${NEW_VERSION}"
+          git add package.json
+          git commit -m "${NEW_TAG}"
+          git tag -a "${NEW_TAG}" -m "${NEW_TAG}"
           # CRITICAL: use --atomic so the branch update and the tag update
           # succeed (or fail) as a single transaction on the server. The old
           # `git push --follow-tags` was non-atomic per ref: if a concurrent

package/README.md

@@ -25,6 +25,23 @@ If you want to have a button in the toolbar to toggle the TOC, add following sni
 },
 ```
 
+## Installation
+
+Install from the Etherpad 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` / `npm install` yourself from the Etherpad
+> source tree — Etherpad tracks installed plugins through its own
+> plugin-manager, and hand-editing `package.json` can leave the
+> server unable to start.
+
+After installing, restart Etherpad.
+
 ## License
 Copyright 2014, John McLear
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ep_table_of_contents",
-  "version": "0.3.132",
+  "version": "0.3.133",
   "description": "View a table of contents for your pad",
   "author": {
     "name": "John McLear",
@@ -27,8 +27,8 @@
   },
   "devDependencies": {
     "eslint": "^8.57.1",
-    "eslint-config-etherpad": "^4.0.4",
-    "typescript": "^6.0.2"
+    "eslint-config-etherpad": "^4.0.5",
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "test": "node --test tests/*.test.js",

package/static/js/toc.js

@@ -159,11 +159,34 @@ const tableOfContents = {
     $(`.tocItem[data-toc-index="${activeTocIndex}"]`).addClass('activeTOC');
   },
 
+  // findTags() walks every heading and rebuilds the entire ToC DOM. On
+  // pads with hundreds of headings this blocked the main thread on
+  // every keystroke and produced the 1-char-per-second typing seen in
+  // #51. Debounce the expensive scan — still fast enough to feel
+  // responsive, but no longer fires per keystroke.
+  _findTagsTimer: null,
+  _findTagsPending: false,
+  scheduleFindTags: (rep) => {
+    if (tableOfContents._findTagsTimer != null) {
+      tableOfContents._findTagsPending = true;
+      return;
+    }
+    tableOfContents._findTagsTimer = setTimeout(() => {
+      tableOfContents._findTagsTimer = null;
+      tableOfContents.findTags();
+      if (tableOfContents._findTagsPending) {
+        tableOfContents._findTagsPending = false;
+        tableOfContents.scheduleFindTags();
+      }
+    }, 300);
+  },
+
   update: (rep) => {
     if (rep) {
       tableOfContents.showPosition(rep);
     }
-    tableOfContents.getPadHTML(rep);
+    if (!$('#options-toc').is(':checked')) return;
+    tableOfContents.scheduleFindTags(rep);
   },
 
   scroll: (newY) => {

package/static/tests/backend/specs/debounce.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const assert = require('assert').strict;
+const fs = require('fs');
+const path = require('path');
+
+const tocPath = path.resolve(__dirname, '..', '..', '..', '..', 'static', 'js', 'toc.js');
+
+describe(__filename, function () {
+  let src;
+  before(function () { src = fs.readFileSync(tocPath, 'utf8'); });
+
+  it('update() debounces findTags() via setTimeout (#51)', function () {
+    // findTags walks every heading and rebuilds the #tocItems list. On pads
+    // with hundreds of headings, firing it on every keystroke was the
+    // source of the 1-char-per-second typing seen in #51. The update path
+    // must now schedule findTags via setTimeout instead of calling it
+    // synchronously.
+    const updateBlock = src.match(/update:\s*\([^)]*\)\s*=>\s*\{[\s\S]*?\n\s*\},/);
+    assert(updateBlock, 'expected update() in tableOfContents');
+    assert(!/tableOfContents\.findTags\s*\(\s*\)/.test(updateBlock[0]),
+        'update() must not call findTags() synchronously on every edit');
+    assert(/scheduleFindTags|setTimeout/.test(updateBlock[0]),
+        'update() should defer the heading scan (via scheduleFindTags / setTimeout)');
+    // And the scheduler itself should actually use setTimeout.
+    assert(/scheduleFindTags[\s\S]*?setTimeout/.test(src),
+        'scheduleFindTags should wrap findTags() in setTimeout');
+  });
+});