ep_special_characters 0.0.59 → 0.0.61

package/AGENTS.md

@@ -0,0 +1,68 @@
+# Agent Guide — ep_special_characters
+
+Insert special characters into a pad.
+
+## Tech stack
+
+* Etherpad plugin framework (hooks declared in `ep.json`)
+* EJS templates rendered server-side via `eejsBlock_*` hooks
+
+## Project structure
+
+```
+ep_special_characters/
+├── AGENTS.md
+├── CONTRIBUTING.md
+├── ep.json
+├── hooks.js
+├── package.json
+├── static/
+│   ├── css/
+│   ├── html/
+│   ├── js/
+│   ├── tests/
+├── templates/
+│   ├── editbarButtons.ejs
+│   ├── modals.ejs
+│   ├── scripts.ejs
+│   ├── special_characters_menu.ejs
+│   ├── styles.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_special_characters` runs inside Etherpad's test harness. From an etherpad checkout that has installed this plugin via `pnpm run plugins i --path ../ep_special_characters`:
+
+```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_editbarMenuLeft`, `eejsBlock_scripts`, `eejsBlock_styles`, `eejsBlock_body`, `eejsBlock_dd_insert`
+* Client: `aceInitInnerdocbodyHead`, `aceAttribsToClasses`, `aceCreateDomLine`
+
+When adding a hook, register it in both `ep.json` *and* the matching `exports.<hook> = ...` in the JS file.

package/README.md

@@ -1,10 +1,5 @@
 [![Backend Tests Status](https://github.com/ether/ep_special_characters/actions/workflows/test-and-release.yml/badge.svg)](https://github.com/ether/ep_special_characters/actions/workflows/test-and-release.yml)
 
-> ⚠️ **Known issue:** Clicking a character in the picker currently throws
-> `ReferenceError: require is not defined` because [`static/js/main.js:16`](static/js/main.js)
-> uses a browser-side `require()` that Etherpad's current esbuild bundler
-> doesn't expose. Tracking fix in [#87](https://github.com/ether/ep_special_characters/issues/87).
-
 # Special Character Picker for Etherpad
 TODO: Describe the plugin.
 

package/ep.json

@@ -10,6 +10,7 @@
         "eejsBlock_dd_insert" : "ep_special_characters/hooks"
       },
       "client_hooks": {
+        "postAceInit": "ep_special_characters/static/js/hooks:postAceInit",
         "aceInitInnerdocbodyHead": "ep_special_characters/static/js/hooks:aceInitInnerdocbodyHead",
         "aceAttribsToClasses": "ep_special_characters/static/js/hooks:aceAttribsToClasses",
         "aceCreateDomLine": "ep_special_characters/static/js/hooks:aceCreateDomLine"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ep_special_characters",
   "description": "Insert special characters into a pad",
-  "version": "0.0.59",
+  "version": "0.0.61",
   "author": {
     "name": "Johnyma22",
     "email": "john@mclear.co.uk",

package/static/js/hooks.js

@@ -1,5 +1,9 @@
 'use strict';
 
+exports.postAceInit = (hookName, context) => {
+  window.epSpecialCharactersAce = context.ace;
+};
+
 exports.aceInitInnerdocbodyHead = (hookName, args, cb) => {
   const path = '../static/plugins/ep_special_characters/static/css/ace.css';
   args.iframeHTML.push(

package/static/js/main.js

@@ -1,8 +1,24 @@
 'use strict';
 
 $(document).ready(() => {
+  const SPECIAL_CHARACTER_START_CODE_POINT = 0x20;
+  const SPECIAL_CHARACTER_END_CODE_POINT = 0x2FF;
   const module = $('#specialCharactersModal');
+  const specialChars = $('.specialChars');
+  let isSpecialCharactersPopulated = false;
+
+  const populateSpecialCharacters = () => {
+    if (isSpecialCharactersPopulated) return;
+    const chars = [];
+    for (let i = SPECIAL_CHARACTER_START_CODE_POINT; i <= SPECIAL_CHARACTER_END_CODE_POINT; i++) {
+      chars.push(`<li class='specialChar'>&#${i}</li>`);
+    }
+    specialChars.append(chars.join(''));
+    isSpecialCharactersPopulated = true;
+  };
+
   $('.insertSpecialCharacter').click(() => {
+    populateSpecialCharacters();
     module.toggleClass('popup-show');
   });
 
@@ -13,18 +29,13 @@ $(document).ready(() => {
     const char = ($(this).text());
     $('.usedSpecialCharacters').append(this);
     $('.usedSpecialCharactersLabel').show();
-    const padeditor = require('ep_etherpad-lite/static/js/pad_editor').padeditor;
+    const ace = window.epSpecialCharactersAce;
     module.toggleClass('popup-show');
-    return padeditor.ace.callWithAce((ace) => {
-      const rep = ace.ace_getRep();
-      ace.ace_replaceRange(rep.selStart, rep.selEnd, char);
-      ace.ace_focus();
+    if (!ace) return;
+    return ace.callWithAce((editor) => {
+      const rep = editor.ace_getRep();
+      editor.ace_replaceRange(rep.selStart, rep.selEnd, char);
+      editor.ace_focus();
     }, 'specialCharacters');
   });
-
-  let i = 0;
-  while (i <= 5000) {
-    $('.specialChars').append(`<li class='specialChar'>&#${i}</li>`);
-    i++;
-  }
 });

package/static/tests/frontend-new/specs/smoke.spec.ts

@@ -1,6 +1,8 @@
 import {expect, test} from '@playwright/test';
 import {getPadBody, goToNewPad} from 'ep_etherpad-lite/tests/frontend-new/helper/padHelper';
 
+const expectedSpecialCharacterCount = (0x2FF - 0x20) + 1;
+
 test.beforeEach(async ({page}) => {
   await goToNewPad(page);
 });
@@ -10,4 +12,25 @@ test.describe('ep_special_characters', () => {
     const padBody = await getPadBody(page);
     await expect(padBody).toBeVisible();
   });
+
+  test('special characters are populated lazily on first modal open', async ({page}) => {
+    await expect(page.locator('.specialChars .specialChar')).toHaveCount(0);
+
+    await page.locator('.insertSpecialCharacter').first().click();
+    await expect(page.locator('#specialCharactersModal')).toHaveClass(/popup-show/);
+    await expect(page.locator('.specialChars .specialChar')).toHaveCount(expectedSpecialCharacterCount);
+  });
+
+  test('clicking a special character inserts it without page errors', async ({page}) => {
+    const pageErrors: Error[] = [];
+    page.on('pageerror', (error) => pageErrors.push(error));
+    const padBody = await getPadBody(page);
+    await padBody.click();
+
+    await page.locator('.insertSpecialCharacter').first().click();
+    await page.locator('.specialChars .specialChar', {hasText: 'Æ'}).first().click();
+
+    await expect(padBody).toContainText('Æ');
+    expect(pageErrors).toEqual([]);
+  });
 });