feat(userlist): click a user to open chat with @<name> prefilled

[JohnMcLear]

Why

Newcomers to a multi-user pad regularly fail to discover the chat panel and the @-mention convention. The current UX is "find the chat icon in the corner, click it, type @, type your collaborator's name." Most people never make it past step 1.

This PR makes the user list itself the discovery affordance: clicking another user's row opens chat (if hidden) and prefills the input with @<their_name> , ready to send.

What changed

• src/static/js/pad_userlist.ts — delegated click handler on #otheruserstable tr[data-authorId]. Skips clicks on .usertdswatch (color-picker keeps its own semantics). Calls chat.show() and prefills #chatinput. Doesn't clobber a real partial message — if the user is mid-typing, the mention is appended.
• src/static/skins/colibris/src/components/users.css — pointer cursor on .usertdname and a hover underline so the affordance is visible. Swatch keeps its existing cursor.
• doc/api/hooks_client-side.md — documents the new chatPrefillFromUser hook.

New hook: chatPrefillFromUser

Bot/AI plugins frequently have a display name that's a useless @-mention (e.g. AI Assistant doesn't trigger anything; the actual trigger is @ai). The new client-side hook lets them substitute the prefill:

exports.chatPrefillFromUser = (hookName, {authorId, name, prefill}, cb) => {
  if (authorId === window.clientVars.ep_my_bot.authorId) return cb('@bot ');
  return cb();
};

First plugin to return a non-empty string wins. Hook errors are caught so a misbehaving plugin can't break the click.

Companion

This unblocks ether/ep_ai_chat#19 (split per discussion) which becomes a tiny hook handler that swaps AI Assistant for the configured trigger. Without this PR, every Etherpad install that wants click-to-mention has to ship its own copy of the click handler.

Test plan

• Open a pad in two browser sessions. From session A, click session B's row → chat opens (if it was hidden), @<sessionB_name> is in the input.
• Type partial text first, then click a user → mention is appended, partial text preserved.
• Click on the swatch (not name) → color picker opens, chat doesn't.
• With chat-and-users sticky, clicking still focuses + prefills.
• With pad.settings.hideChat true, click is a benign no-op.

🤖 Generated with Claude Code

[qodo-code-review]

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Click user list to open chat with prefilled @-mention

✨ Enhancement

Walkthroughs

Description

• Click user row to open chat with @-mention prefilled
• Adds chatPrefillFromUser hook for plugin customization
• Visual affordance: pointer cursor and hover underline
• Preserves partial messages when appending mentions

Diagram

flowchart LR
  UserClick["User clicks row"] --> CheckSwatch{"Click on swatch?"}
  CheckSwatch -->|Yes| ColorPicker["Open color picker"]
  CheckSwatch -->|No| Hook["Call chatPrefillFromUser hook"]
  Hook --> Transform{"Plugin returns<br/>custom prefill?"}
  Transform -->|Yes| UsePrefill["Use plugin prefill"]
  Transform -->|No| DefaultPrefill["Use @name prefill"]
  UsePrefill --> ShowChat["Show chat panel"]
  DefaultPrefill --> ShowChat
  ShowChat --> FillInput["Prefill or append to input"]
  FillInput --> Focus["Focus input & set cursor"]

Loading

File Changes

1. src/static/js/pad_userlist.ts ✨ Enhancement +41/-0

Add click-to-mention handler with hook support

• Added delegated click handler on #otheruserstable tr[data-authorId]
• Skips clicks on .usertdswatch to preserve color-picker semantics
• Calls chatPrefillFromUser hook for plugin customization
• Intelligently handles prefill: replaces only @-mentions or appends to existing text
• Focuses input and positions cursor after prefilling

src/static/js/pad_userlist.ts

---

2. src/static/skins/colibris/src/components/users.css ✨ Enhancement +13/-0

Add visual affordance for clickable user rows

• Added pointer cursor to .usertdname cells
• Added underline on hover for .usertdname to signal clickability
• Preserves color swatch's original cursor behavior

src/static/skins/colibris/src/components/users.css

---

3. doc/api/hooks_client-side.md 📝 Documentation +28/-0

Document chatPrefillFromUser hook API

• Documented new chatPrefillFromUser client-side hook
• Explains use case for AI/bot plugins to customize @-mention trigger
• Provides context properties: authorId, name, prefill
• Includes example implementation for bot plugins

doc/api/hooks_client-side.md

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (3) 📘 Rule violations (1) 📎 Requirement gaps (0)

1. Click-to-chat lacks feature flag 📘 Rule violation ⚙ Maintainability

Description

The new click handler on user list rows changes default behavior by opening chat and prefilling an
@name mention without any feature flag gating. This violates the requirement that new features be
disabled by default unless explicitly enabled.

Code

src/static/js/pad_userlist.ts[R379-411]

+      $('#otheruserstable').on('click', 'tr[data-authorId]', async function (event) {
+        // Skip clicks on the color swatch — that has its own click handler
+        // (color-picker semantics) and shouldn't double up as a chat trigger.
+        if ($(event.target).closest('.usertdswatch').length) return;
+        const tr = $(this);
+        const authorId = tr.attr('data-authorId');
+        if (!authorId) return;
+        const name = (tr.find('.usertdname').text() || '').trim();
+        let prefill = name ? `@${name.replace(/\s+/g, '_')} ` : '';
+        try {
+          const transforms = await hooks.aCallAll(
+              'chatPrefillFromUser', {authorId, name, prefill});
+          if (Array.isArray(transforms)) {
+            for (const tr2 of transforms) {
+              if (typeof tr2 === 'string' && tr2.length > 0) { prefill = tr2; break; }
+            }
+          }
+        } catch { /* never let a misbehaving plugin break the click */ }
+        try { chat.show(); } catch { /* */ }
+        setTimeout(() => {
+          const $input = $('#chatinput');
+          if (!$input.length) return;
+          const current = ($input.val() || '') as string;
+          if (!current.trim() || /^@\S+\s*$/.test(current.trim())) {
+            $input.val(prefill);
+          } else if (!current.includes(prefill.trim())) {
+            $input.val(`${current.trimEnd()} ${prefill}`);
+          }
+          $input.trigger('focus');
+          const elem = $input[0] as HTMLTextAreaElement;
+          try { elem.setSelectionRange(elem.value.length, elem.value.length); } catch (_e) { /* */ }
+        }, 50);
+      });

Evidence

PR Compliance ID 6 requires new features to be behind a feature flag and disabled by default. The
added code unconditionally registers a click handler on #otheruserstable tr[data-authorId] that
opens chat and prefills #chatinput, making the feature enabled by default.

src/static/js/pad_userlist.ts[379-411]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A new UX feature (click user row to open chat and prefill `@name`) is enabled by default, but compliance requires new features to be behind a feature flag and disabled by default.
## Issue Context
The click handler is currently registered unconditionally, so all installs get the new behavior without opting in.
## Fix Focus Areas
- src/static/js/pad_userlist.ts[379-411]
- src/static/skins/colibris/src/components/users.css[11-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Click steals rename focus ☑ 🐞 Bug ≡ Correctness

Description

Clicking the editable name <input> for unnamed users will also trigger the new row click handler,
which then focuses #chatinput and interrupts the rename workflow. This makes it difficult or
impossible to name unnamed users from the user list.

Code

src/static/js/pad_userlist.ts[R379-410]

+      $('#otheruserstable').on('click', 'tr[data-authorId]', async function (event) {
+        // Skip clicks on the color swatch — that has its own click handler
+        // (color-picker semantics) and shouldn't double up as a chat trigger.
+        if ($(event.target).closest('.usertdswatch').length) return;
+        const tr = $(this);
+        const authorId = tr.attr('data-authorId');
+        if (!authorId) return;
+        const name = (tr.find('.usertdname').text() || '').trim();
+        let prefill = name ? `@${name.replace(/\s+/g, '_')} ` : '';
+        try {
+          const transforms = await hooks.aCallAll(
+              'chatPrefillFromUser', {authorId, name, prefill});
+          if (Array.isArray(transforms)) {
+            for (const tr2 of transforms) {
+              if (typeof tr2 === 'string' && tr2.length > 0) { prefill = tr2; break; }
+            }
+          }
+        } catch { /* never let a misbehaving plugin break the click */ }
+        try { chat.show(); } catch { /* */ }
+        setTimeout(() => {
+          const $input = $('#chatinput');
+          if (!$input.length) return;
+          const current = ($input.val() || '') as string;
+          if (!current.trim() || /^@\S+\s*$/.test(current.trim())) {
+            $input.val(prefill);
+          } else if (!current.includes(prefill.trim())) {
+            $input.val(`${current.trimEnd()} ${prefill}`);
+          }
+          $input.trigger('focus');
+          const elem = $input[0] as HTMLTextAreaElement;
+          try { elem.setSelectionRange(elem.value.length, elem.value.length); } catch (_e) { /* */ }
+        }, 50);

Evidence

The user list already supports renaming unnamed users via an <input> inside the .usertdname cell;
the new handler only excludes swatch clicks and then focuses the chat input, so clicks intended for
that rename <input> will bubble to the <tr> handler and be hijacked.

src/static/js/pad_userlist.ts[183-196]
src/static/js/pad_userlist.ts[373-410]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new delegated click handler on `#otheruserstable tr[data-authorId]` triggers even when the click target is the existing rename `<input>` in the name cell, and it later focuses `#chatinput`. This breaks the unnamed-user rename interaction.
### Issue Context
Unnamed users are rendered with an `<input>` in the `.usertdname` cell and are wired up via `#otheruserstable input.newinput`.
### Fix Focus Areas
- src/static/js/pad_userlist.ts[373-410]
- src/static/js/pad_userlist.ts[183-196]
### Suggested change
Add early-return guards before doing any prefill/show work, for example:
- Return if `$(event.target).closest('input, textarea, select, button, a, [contenteditable=true]').length`.
- Or at minimum return if `$(event.target).closest('.usertdname input').length`.
This keeps the row-click behavior while preserving rename semantics.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Prefill runs when chat hidden 🐞 Bug ☼ Reliability

Description

If chat is disabled (hideChat true), chat.show() is a no-op but the handler still sets and focuses
#chatinput, so the click is not a benign no-op and may steal focus or mutate hidden UI state. This
contradicts the stated intent for pads where chat is hidden/disabled.

Code

src/static/js/pad_userlist.ts[R397-410]

+        try { chat.show(); } catch { /* */ }
+        setTimeout(() => {
+          const $input = $('#chatinput');
+          if (!$input.length) return;
+          const current = ($input.val() || '') as string;
+          if (!current.trim() || /^@\S+\s*$/.test(current.trim())) {
+            $input.val(prefill);
+          } else if (!current.includes(prefill.trim())) {
+            $input.val(`${current.trimEnd()} ${prefill}`);
+          }
+          $input.trigger('focus');
+          const elem = $input[0] as HTMLTextAreaElement;
+          try { elem.setSelectionRange(elem.value.length, elem.value.length); } catch (_e) { /* */ }
+        }, 50);

Evidence

chat.show() explicitly returns early when chat is disabled, but disabling chat hides #chatbox
without removing #chatinput from the DOM, so the handler’s timeout block can still find and
mutate/focus the hidden input.

src/static/js/chat.ts[36-44]
src/static/js/pad.ts[613-622]
src/static/js/pad_userlist.ts[397-410]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
When chat is disabled, the handler still prefills and focuses `#chatinput` even though `chat.show()` returns early.
### Issue Context
- `chat.show()` returns immediately if chat is hidden.
- `applyShowChat(false)` hides `#chatbox` but `#chatinput` remains in the DOM.
### Fix Focus Areas
- src/static/js/pad_userlist.ts[397-410]
- src/static/js/chat.ts[36-44]
- src/static/js/pad.ts[613-622]
### Suggested change
After attempting to show chat, guard the prefill/focus block. For example:
- Call `chat.show();` then `if (!$('#chatbox').hasClass('visible')) return;` (or check the relevant hideChat flag if accessible).
This ensures the click is a true no-op when chat is disabled.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Hook await blocks click 🐞 Bug ☼ Reliability

Description

The click handler awaits hooks.aCallAll('chatPrefillFromUser', ...) before showing/prefilling
chat, and aCallAll waits for all hook functions to settle. A plugin hook that is very slow or
never resolves will delay the click action indefinitely (try/catch does not help for never-resolving
Promises).

Code

src/static/js/pad_userlist.ts[R388-397]

+        try {
+          const transforms = await hooks.aCallAll(
+              'chatPrefillFromUser', {authorId, name, prefill});
+          if (Array.isArray(transforms)) {
+            for (const tr2 of transforms) {
+              if (typeof tr2 === 'string' && tr2.length > 0) { prefill = tr2; break; }
+            }
+          }
+        } catch { /* never let a misbehaving plugin break the click */ }
+        try { chat.show(); } catch { /* */ }

Evidence

aCallAll uses Promise.all(...) across every registered hook and only resolves after they all
settle; therefore the click handler’s await can be blocked by any misbehaving or slow plugin hook.

src/static/js/pad_userlist.ts[388-397]
src/static/js/pluginfw/hooks.ts[346-352]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Awaiting `hooks.aCallAll()` blocks the UI action until *all* plugin hook handlers finish. If any plugin never resolves its callback/Promise, the click action never completes.
### Issue Context
`aCallAll()` awaits `Promise.all(...)` across all hooks. `try/catch` only catches thrown/rejected errors, not never-settling Promises.
### Fix Focus Areas
- src/static/js/pad_userlist.ts[388-397]
- src/static/js/pluginfw/hooks.ts[346-352]
### Suggested change options
Pick one:
1) **Timeout protection**: wrap the await in `Promise.race([hooks.aCallAll(...), timeoutPromiseResolvingToEmptyArray])`.
2) **Stop early**: use `hooks.aCallFirst()` with a predicate that accepts the first non-empty string result, so later plugins aren’t waited on.
3) **Best UX**: show chat and prefill default immediately, then apply transformed prefill only if it arrives quickly and the user hasn’t edited the input.
Any of these avoids an installation-wide stall from a single plugin.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Substring dedupe misses mention 🐞 Bug ≡ Correctness

Description

The dedupe check uses current.includes(prefill.trim()), which can treat partial matches as
already-mentioned (e.g., current contains @bobcat and clicking bob won’t append @bob). This is
rare but can silently skip inserting the intended mention when usernames share prefixes.

Code

src/static/js/pad_userlist.ts[R402-406]

+          if (!current.trim() || /^@\S+\s*$/.test(current.trim())) {
+            $input.val(prefill);
+          } else if (!current.includes(prefill.trim())) {
+            $input.val(`${current.trimEnd()} ${prefill}`);
+          }

Evidence

The code uses a raw substring search rather than checking for a whole-token mention, so prefix
collisions can produce false positives and prevent insertion.

src/static/js/pad_userlist.ts[401-406]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The mention dedupe logic uses substring matching, which can mis-detect similar names.
### Issue Context
`prefill.trim()` is something like `@bob`. `includes('@bob')` is true for `@bobcat`.
### Fix Focus Areas
- src/static/js/pad_userlist.ts[401-406]
### Suggested change
Replace `includes()` with a safer check for a mention token, such as a regex that enforces boundaries:
- Escape `prefill.trim()` for regex use.
- Test something like `/(^|\s)@bob(\s|$)/` (or equivalent) against `current`.
This avoids false positives for prefix-colliding names.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-free-for-open-source-projects]

1. Click-to-chat lacks feature flag 📘 Rule violation ⚙ Maintainability

The new click handler on user list rows changes default behavior by opening chat and prefilling an
@name mention without any feature flag gating. This violates the requirement that new features be
disabled by default unless explicitly enabled.

Agent Prompt

## Issue description
A new UX feature (click user row to open chat and prefill `@name`) is enabled by default, but compliance requires new features to be behind a feature flag and disabled by default.

## Issue Context
The click handler is currently registered unconditionally, so all installs get the new behavior without opting in.

## Fix Focus Areas
- src/static/js/pad_userlist.ts[379-411]
- src/static/skins/colibris/src/components/users.css[11-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[JohnMcLear]

Going with a reasoned decline on the feature-flag part of this comment. Replying so the rationale is on the record:

• Etherpad doesn't gate UX changes behind feature flags. The current settings.json surface is reserved for things that materially change the contract (auth, storage, transport, security knobs, skin selection). Recent UX additions — chat-and-users mode, sticky chat, the showsidebar editbar button, etc. — all shipped on by default with no flag. Adding a flag here would be inconsistent with project precedent.
• Blast radius is small. Before this PR clicking a user list row was a no-op; nothing depended on that. Anyone who wants the click to do nothing can ship a tiny CSS override (#otheruserstable tr[data-authorId] { pointer-events: none; }) without a settings change.
• Plugins already have the override they need. The chatPrefillFromUser hook lets a plugin return a non-empty string to substitute the prefill. A plugin that wanted to globally suppress the behavior could trivially return an empty-but-truthy value or hide rows via CSS.

The other comment on this review (rename-input click steals focus) was a real bug and is fixed in a494307a, plus a Playwright spec covering the supported flows and that regression.

[SamTV12345]

That's cool :)