ep_spellcheck 0.0.97 → 0.0.99

package/AGENTS.md

@@ -0,0 +1,71 @@
+# Agent Guide — ep_spellcheck
+
+Add support to do 'Spell checking', with a toggle on/off option in Settings.
+
+## Tech stack
+
+* Etherpad plugin framework (hooks declared in `ep.json`)
+* EJS templates rendered server-side via `eejsBlock_*` hooks
+* html10n for i18n (`locales/<lang>.json`, `data-l10n-id` in templates)
+
+## Project structure
+
+```
+ep_spellcheck/
+├── AGENTS.md
+├── CONTRIBUTING.md
+├── ep.json
+├── locales/
+│   ├── ar.json
+│   ├── be-tarask.json
+│   ├── bn.json
+│   ├── br.json
+│   ├── ca.json
+│   ├── cs.json
+│   └── ...
+├── package.json
+├── spellcheck.js
+├── static/
+│   ├── js/
+│   ├── tests/
+├── templates/
+│   ├── spellcheck_entry.ejs
+```
+
+## Helpers used
+
+_None — `ep_plugin_helpers` is not a dependency. Adoption is part of the helpers-adoption sweep (Phase 4)._
+
+
+## Helpers NOT used
+
+_To be audited in the helpers-adoption sweep (Phase 4)._
+
+
+## Running tests locally
+
+`ep_spellcheck` runs inside Etherpad's test harness. From an etherpad checkout that has installed this plugin via `pnpm run plugins i --path ../ep_spellcheck`:
+
+```bash
+# Backend (Mocha) — harness boots its own server
+pnpm --filter ep_etherpad-lite run test
+
+# Playwright — needs `pnpm run dev` in a second terminal
+pnpm --filter ep_etherpad-lite run test-ui
+```
+
+## Standing rules for agent edits
+
+* PRs target `main`. Linear commits, no merge commits.
+* Every bug fix includes a regression test in the same commit.
+* All user-facing strings in `locales/`. No hardcoded English in templates.
+* No hardcoded `aria-label` on icon-only controls — etherpad's html10n auto-populates `aria-label` from the localized string when (a) the element has a `data-l10n-id` and (b) no author-supplied `aria-label` is present. Adding a hardcoded English `aria-label` blocks that and leaves it untranslated. (See `etherpad-lite/src/static/js/vendors/html10n.ts:665-678`.)
+* No nested interactive elements (no `<button>` inside `<a>`).
+* LLM/Agent contributions are explicitly welcomed by maintainers.
+
+## Quick reference: hooks declared in `ep.json`
+
+* Server: `eejsBlock_mySettings`, `eejsBlock_dd_view`
+* Client: `postAceInit`
+
+When adding a hook, register it in both `ep.json` *and* the matching `exports.<hook> = ...` in the JS file.

package/ep.json

@@ -2,12 +2,15 @@
   "parts": [
     {
       "name": "ep_spellcheck",
-      "client_hooks": {
-        "postAceInit": "ep_spellcheck/static/js/spellcheck:postAceInit"
-      },
       "hooks": {
+        "loadSettings": "ep_spellcheck/spellcheck",
+        "clientVars": "ep_spellcheck/spellcheck",
         "eejsBlock_mySettings": "ep_spellcheck/spellcheck",
-        "eejsBlock_dd_view" : "ep_spellcheck/spellcheck"
+        "eejsBlock_padSettings": "ep_spellcheck/spellcheck"
+      },
+      "client_hooks": {
+        "postAceInit": "ep_spellcheck/static/js/spellcheck:postAceInit",
+        "handleClientMessage_CLIENT_MESSAGE": "ep_spellcheck/static/js/spellcheck:handleClientMessage_CLIENT_MESSAGE"
       }
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ep_spellcheck",
-  "version": "0.0.97",
+  "version": "0.0.99",
   "keywords": [
     "spell",
     "check",
@@ -21,6 +21,9 @@
     "type": "individual",
     "url": "https://etherpad.org/"
   },
+  "dependencies": {
+    "ep_plugin_helpers": "^0.5.2"
+  },
   "devDependencies": {
     "eslint": "^8.57.1",
     "eslint-config-etherpad": "^4.0.5",

package/spellcheck.js

@@ -1,21 +1,29 @@
 'use strict';
 
-const eejs = require('ep_etherpad-lite/node/eejs/');
-const settings = require('ep_etherpad-lite/node/utils/Settings');
+const {padToggle} = require('ep_plugin_helpers/pad-toggle-server');
 
-exports.eejsBlock_mySettings = (hookName, args, cb) => {
-  let checkedState = 'checked';
-  if (settings.ep_spellcheck) {
-    if (settings.ep_spellcheck.disabledByDefault === true) {
-      checkedState = '';
-    }
+// Parallel User Settings + Pad Wide Settings checkboxes for "Spell Check".
+// Helper owns markup, storage, broadcast, enforce, and i18n wiring.
+const spellcheckToggle = padToggle({
+  pluginName: 'ep_spellcheck',
+  settingId: 'spellcheck',
+  l10nId: 'ep_spellcheck.spellcheck',
+  defaultLabel: 'Spell Check',
+  defaultEnabled: true,
+});
+
+// Older settings.json used `ep_spellcheck.disabledByDefault: true` to flip
+// the checkbox off. Translate to the helper's `defaultEnabled` so existing
+// installs keep their current behavior after the conversion.
+exports.loadSettings = async (hookName, args) => {
+  const ps = args && args.settings && args.settings.ep_spellcheck;
+  if (ps && typeof ps.defaultEnabled !== 'boolean' &&
+      typeof ps.disabledByDefault === 'boolean') {
+    ps.defaultEnabled = !ps.disabledByDefault;
   }
-  const ejsPath = 'ep_spellcheck/templates/spellcheck_entry.ejs';
-  args.content += eejs.require(ejsPath, {checked: checkedState});
-  return cb();
+  return spellcheckToggle.loadSettings(hookName, args);
 };
 
-exports.eejsBlock_dd_view = (hookName, args, cb) => {
-  const li = "<li><a href='#' onClick='$(\"#options-spellcheck\").click();'>Spell Check</a></li>";
-  args.content += li;
-};
+exports.clientVars = spellcheckToggle.clientVars;
+exports.eejsBlock_mySettings = spellcheckToggle.eejsBlock_mySettings;
+exports.eejsBlock_padSettings = spellcheckToggle.eejsBlock_padSettings;

package/static/js/spellcheck.js

@@ -1,51 +1,35 @@
 'use strict';
 
-const padcookie = require('ep_etherpad-lite/static/js/pad_cookie').padcookie;
+// Sub-path import keeps the client bundle clean — the top-level
+// `ep_plugin_helpers` index pulls in server-only modules (eejs, Settings).
+const {padToggle} = require('ep_plugin_helpers/pad-toggle');
 
-const postAceInit = (hook, context) => {
-  const $outer = $('iframe[name="ace_outer"]').contents().find('iframe');
-  const $inner = $outer.contents().find('#innerdocbody');
-  // The `spellcheck` attribute is inherited from the nearest ancestor that
-  // sets it, so we only need to toggle it on #innerdocbody. The previous
-  // implementation walked every <div>/<span> descendant on every toggle,
-  // which is O(n) in line count and multiplied the browser's already-slow
-  // per-keystroke spellchecking work — observable as typing lag on pads
-  // with more than a few hundred lines (#26). Setting the attribute once
-  // on the contenteditable root is equivalent for the browser's checker.
-  const spellcheck = {
-    enable: () => { $inner.attr('spellcheck', 'true'); },
-    disable: () => { $inner.attr('spellcheck', 'false'); },
-  };
-  /* init */
-  if (padcookie.getPref('spellcheck') === false) {
-    $('#options-spellcheck').val();
-    $('#options-spellcheck').attr('checked', 'unchecked');
-    $('#options-spellcheck').attr('checked', false);
-  } else {
-    $('#options-spellcheck').attr('checked', 'checked');
-  }
+// Same config as the server-side instance — must agree on pluginName,
+// settingId, l10nId, and defaultLabel so checkbox ids and clientVars line up.
+const spellcheckToggle = padToggle({
+  pluginName: 'ep_spellcheck',
+  settingId: 'spellcheck',
+  l10nId: 'ep_spellcheck.spellcheck',
+  defaultLabel: 'Spell Check',
+  defaultEnabled: true,
+});
+
+// Re-export so the helper sees pad-wide broadcasts and refreshes our state
+// when another user toggles the pad-wide checkbox.
+exports.handleClientMessage_CLIENT_MESSAGE = spellcheckToggle.handleClientMessage_CLIENT_MESSAGE;
 
-  if ($('#options-spellcheck').is(':checked')) {
-    spellcheck.enable();
-  } else {
-    spellcheck.disable();
-  }
+exports.postAceInit = () => {
+  // The `spellcheck` attribute is inherited from the nearest ancestor that
+  // sets it, so we only need to toggle it on #innerdocbody. Walking every
+  // <div>/<span> descendant (the previous behavior) is O(n) in line count
+  // and multiplied the browser's already-slow per-keystroke spellchecking
+  // work — observable as typing lag on pads with > a few hundred lines (#26).
+  const $inner = $('iframe[name="ace_outer"]').contents().find('iframe')
+      .contents().find('#innerdocbody');
 
-  /* on click */
-  $('#options-spellcheck').on('click', () => {
-    if ($('#options-spellcheck').is(':checked')) {
-      padcookie.setPref('spellcheck', true);
-      spellcheck.enable();
-    } else {
-      padcookie.setPref('spellcheck', false);
-      spellcheck.disable();
-    }
-    // The previous code force-reloaded the page on Chrome via
-    // `window.browser.chrome`. That check was always a no-op on Chrome
-    // (Chrome has no `window.browser` object — it's the Firefox
-    // WebExtension API) and would have thrown a TypeError on Firefox.
-    // Toggling the spellcheck attribute takes effect in every current
-    // browser without a reload, so just drop the reload.
+  spellcheckToggle.init({
+    onChange: (enabled) => {
+      $inner.attr('spellcheck', enabled ? 'true' : 'false');
+    },
   });
 };
-exports.postAceInit = postAceInit;

package/templates/spellcheck_entry.ejs

@@ -1,4 +0,0 @@
-<p>
-    <input type="checkbox" id="options-spellcheck" <%= checked %>></input> 
-    <label for="options-spellcheck" data-l10n-id="ep_spellcheck.spellcheck">Spell Check</label>
-</p>