@actuate-media/cms-admin 0.13.0 → 0.14.0

package/src/__tests__/components/mentionable-textarea.test.tsx

@@ -0,0 +1,226 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from 'vitest'
+import React, { useState } from 'react'
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
+
+import { MentionableTextarea } from '../../components/MentionableTextarea.js'
+import type { MentionUser } from '../../lib/mention-picker.js'
+
+/**
+ * Mount the textarea against a state-managing host so we exercise the
+ * controlled-value contract. Returning the live `value` lets each
+ * test inspect what the parent ends up with after a selection.
+ */
+function Host({
+  initialValue = '',
+  search,
+  testid = 'ta',
+}: {
+  initialValue?: string
+  search: (q: string) => Promise<MentionUser[]>
+  testid?: string
+}) {
+  const [value, setValue] = useState(initialValue)
+  return (
+    <>
+      <MentionableTextarea value={value} onChange={setValue} search={search} data-testid={testid} />
+      <output data-testid="value">{value}</output>
+    </>
+  )
+}
+
+function fakeSearch(rows: MentionUser[]) {
+  return vi.fn(async (q: string) => {
+    const ql = q.toLowerCase()
+    return rows.filter(
+      (u) => u.name.toLowerCase().includes(ql) || u.email.toLowerCase().includes(ql),
+    )
+  })
+}
+
+const ROWS: MentionUser[] = [
+  { id: 'u_alice', name: 'Alice Anderson', email: 'alice@example.com' },
+  { id: 'u_bob', name: 'Bob Brown', email: 'bob@example.com' },
+  { id: 'u_carol', name: 'Carol Chen', email: 'carol@example.com' },
+]
+
+async function typeAt(testid: string, value: string, caret = value.length) {
+  const ta = screen.getByTestId(testid) as HTMLTextAreaElement
+  await act(async () => {
+    // Manually drive the textarea: testing-library's
+    // `fireEvent.change` resets `selectionStart` to 0 in happy-dom,
+    // which would defeat the mention picker (caret 0 → no mention).
+    // We bypass React's value-tracker the same way testing-library
+    // does, then set the caret BEFORE dispatching `input` so the
+    // React handler sees the correct selection.
+    ta.focus()
+    const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set
+    if (setter) setter.call(ta, value)
+    else ta.value = value
+    ta.setSelectionRange(caret, caret)
+    ta.dispatchEvent(new Event('input', { bubbles: true }))
+  })
+}
+
+describe('MentionableTextarea — picker dropdown', () => {
+  it('does not show the picker before @ is typed', async () => {
+    const search = fakeSearch(ROWS)
+    render(<Host search={search} />)
+    await typeAt('ta', 'hello world')
+    expect(screen.queryByTestId('ta-picker')).toBeNull()
+  })
+
+  it('opens the picker the instant @ is typed and shows the empty state', async () => {
+    const search = fakeSearch(ROWS)
+    render(<Host search={search} />)
+    await typeAt('ta', '@')
+    await waitFor(() => expect(screen.getByTestId('ta-picker')).toBeTruthy())
+  })
+
+  it('populates the dropdown with users that match the query', async () => {
+    const search = fakeSearch(ROWS)
+    render(<Host search={search} />)
+    await typeAt('ta', '@ali')
+    await waitFor(() => expect(screen.getByTestId('ta-picker-row-u_alice')).toBeTruthy())
+    // Bob/Carol should NOT match `ali`.
+    expect(screen.queryByTestId('ta-picker-row-u_bob')).toBeNull()
+  })
+
+  it('shows "No matches" when the query has no hits', async () => {
+    const search = fakeSearch(ROWS)
+    render(<Host search={search} />)
+    await typeAt('ta', '@zzzz')
+    await waitFor(() => expect(screen.getByText(/No matches/i)).toBeTruthy())
+  })
+
+  it('closes the picker on Escape without inserting anything', async () => {
+    const search = fakeSearch(ROWS)
+    render(<Host search={search} />)
+    await typeAt('ta', '@al')
+    await waitFor(() => expect(screen.getByTestId('ta-picker')).toBeTruthy())
+    fireEvent.keyDown(screen.getByTestId('ta'), { key: 'Escape' })
+    expect(screen.queryByTestId('ta-picker')).toBeNull()
+    expect(screen.getByTestId('value').textContent).toBe('@al')
+  })
+
+  it('inserts @<userId> + trailing space when a row is clicked', async () => {
+    const search = fakeSearch(ROWS)
+    render(<Host search={search} />)
+    await typeAt('ta', '@ali')
+    await waitFor(() => expect(screen.getByTestId('ta-picker-row-u_alice')).toBeTruthy())
+    await act(async () => {
+      // We use mousedown intentionally (the component listens for
+      // mousedown to avoid losing focus before commit).
+      fireEvent.mouseDown(screen.getByTestId('ta-picker-row-u_alice'))
+    })
+    expect(screen.getByTestId('value').textContent).toBe('@u_alice ')
+    expect(screen.queryByTestId('ta-picker')).toBeNull()
+  })
+
+  it('Enter commits the highlighted row', async () => {
+    const search = fakeSearch(ROWS)
+    render(<Host search={search} />)
+    await typeAt('ta', '@b')
+    await waitFor(() => expect(screen.getByTestId('ta-picker-row-u_bob')).toBeTruthy())
+    await act(async () => {
+      fireEvent.keyDown(screen.getByTestId('ta'), { key: 'Enter' })
+    })
+    expect(screen.getByTestId('value').textContent).toBe('@u_bob ')
+  })
+
+  it('ArrowDown then Enter commits the second result', async () => {
+    const search = fakeSearch(ROWS)
+    render(<Host search={search} />)
+    // Query 'e' hits Alice/Bob/Carol's emails — three matches.
+    await typeAt('ta', '@e')
+    await waitFor(() => expect(screen.getByTestId('ta-picker-row-u_alice')).toBeTruthy())
+    fireEvent.keyDown(screen.getByTestId('ta'), { key: 'ArrowDown' })
+    fireEvent.keyDown(screen.getByTestId('ta'), { key: 'ArrowDown' })
+    fireEvent.keyDown(screen.getByTestId('ta'), { key: 'ArrowUp' }) // back to row 2
+    await act(async () => {
+      fireEvent.keyDown(screen.getByTestId('ta'), { key: 'Enter' })
+    })
+    // Highlight after Down/Down/Up: 0 → 1 → 2 → 1. Row index 1 should
+    // be Bob (alphabetised by name? Actually fakeSearch returns in
+    // ROWS order — Alice, Bob, Carol). So commit = u_bob.
+    expect(screen.getByTestId('value').textContent).toBe('@u_bob ')
+  })
+
+  it('keyboard does NOT swallow Enter when the picker is closed', async () => {
+    const search = fakeSearch(ROWS)
+    const onKeyDown = vi.fn()
+    const Wrapper = () => {
+      const [v, setV] = useState('')
+      return (
+        <MentionableTextarea
+          value={v}
+          onChange={setV}
+          search={search}
+          onKeyDown={onKeyDown}
+          data-testid="ta"
+        />
+      )
+    }
+    render(<Wrapper />)
+    fireEvent.keyDown(screen.getByTestId('ta'), { key: 'Enter' })
+    expect(onKeyDown).toHaveBeenCalledTimes(1)
+  })
+
+  it('does NOT commit a stale row when Enter fires before a new query resolves (PR #159 review)', async () => {
+    // Regression for PR #159 Copilot finding: typing `@a`, getting
+    // Alice in the dropdown, then quickly typing `@bo` and hitting
+    // Enter before the `@bo` query resolves used to commit Alice
+    // (from the previous query) instead of doing nothing or
+    // committing Bob. The fix clears `users` on every new query so
+    // Enter has no row to commit until the new results land.
+    let resolveSlow: (rows: MentionUser[]) => void = () => undefined
+    const search = vi.fn((q: string) => {
+      if (q === 'bo') {
+        return new Promise<MentionUser[]>((resolve) => {
+          resolveSlow = resolve
+        })
+      }
+      return Promise.resolve(ROWS.filter((u) => u.name.toLowerCase().includes(q.toLowerCase())))
+    })
+    render(<Host search={search} />)
+    await typeAt('ta', '@a')
+    await waitFor(() => expect(screen.getByTestId('ta-picker-row-u_alice')).toBeTruthy())
+    // Now type the new query that hangs. Enter should NOT commit.
+    await typeAt('ta', '@bo')
+    fireEvent.keyDown(screen.getByTestId('ta'), { key: 'Enter' })
+    // Value should still be `@bo` — no token was inserted.
+    expect(screen.getByTestId('value').textContent).toBe('@bo')
+    // Resolve the hung query and confirm Bob is then committable.
+    await act(async () => {
+      resolveSlow(ROWS.filter((u) => u.name.toLowerCase().includes('bo')))
+    })
+    await waitFor(() => expect(screen.getByTestId('ta-picker-row-u_bob')).toBeTruthy())
+  })
+
+  it('drops stale responses when typing quickly (race protection)', async () => {
+    let resolveSlow: (rows: MentionUser[]) => void = () => undefined
+    const search = vi.fn((q: string) => {
+      if (q === 'a') {
+        return new Promise<MentionUser[]>((resolve) => {
+          resolveSlow = resolve
+        })
+      }
+      // Fast path for `ali`.
+      return Promise.resolve(ROWS.filter((u) => u.name.toLowerCase().includes(q.toLowerCase())))
+    })
+    render(<Host search={search} />)
+    // Trigger the slow request.
+    await typeAt('ta', '@a')
+    // Trigger the fast request which will resolve first.
+    await typeAt('ta', '@ali')
+    await waitFor(() => expect(screen.getByTestId('ta-picker-row-u_alice')).toBeTruthy())
+    // Now resolve the older request with the wrong rows — should NOT
+    // appear in the dropdown.
+    await act(async () => {
+      resolveSlow(ROWS)
+    })
+    // Carol should still be filtered out (the fast `ali` query is
+    // what won the race).
+    expect(screen.queryByTestId('ta-picker-row-u_carol')).toBeNull()
+  })
+})

package/src/__tests__/lib/mention-picker.test.ts

@@ -0,0 +1,145 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const cmsApiMock = vi.fn()
+vi.mock('../../lib/api.js', () => ({
+  cmsApi: (...args: unknown[]) => cmsApiMock(...args),
+  getApiBase: () => '/api/cms',
+}))
+
+const { detectMentionContext, insertMentionToken, searchMentionUsers } =
+  await import('../../lib/mention-picker.js')
+
+beforeEach(() => {
+  cmsApiMock.mockReset()
+})
+
+describe('detectMentionContext', () => {
+  it('returns null when there is no @ before the caret', () => {
+    expect(detectMentionContext('hello world', 5)).toBeNull()
+  })
+
+  it('matches a fresh @ at the start of the field', () => {
+    expect(detectMentionContext('@ali', 4)).toEqual({ start: 0, end: 4, query: 'ali' })
+  })
+
+  it('matches @ after a leading space', () => {
+    expect(detectMentionContext('hey @bob', 8)).toEqual({ start: 4, end: 8, query: 'bob' })
+  })
+
+  it('opens immediately with an empty query the moment @ is typed', () => {
+    expect(detectMentionContext('@', 1)).toEqual({ start: 0, end: 1, query: '' })
+  })
+
+  it('does NOT open mid-word for email-like input (`foo@bar`)', () => {
+    expect(detectMentionContext('foo@bar', 7)).toBeNull()
+  })
+
+  it('terminates on a whitespace character between @ and caret', () => {
+    expect(detectMentionContext('@ali ce', 7)).toBeNull()
+  })
+
+  it('terminates on a non-mention punctuation character', () => {
+    expect(detectMentionContext('@ali.ce', 7)).toBeNull()
+  })
+
+  it('supports underscores and hyphens (id-shape charset)', () => {
+    expect(detectMentionContext('@user_id-42', 11)).toEqual({
+      start: 0,
+      end: 11,
+      query: 'user_id-42',
+    })
+  })
+
+  it('matches when the caret is mid-query (not at end of value)', () => {
+    // value: "@ali rest", caret after the `i`
+    expect(detectMentionContext('@ali rest', 4)).toEqual({ start: 0, end: 4, query: 'ali' })
+  })
+
+  it('handles newline as a boundary', () => {
+    expect(detectMentionContext('line\n@bob', 9)).toEqual({ start: 5, end: 9, query: 'bob' })
+  })
+
+  it('returns null when the caret is at offset 0', () => {
+    expect(detectMentionContext('@ali', 0)).toBeNull()
+  })
+
+  it('returns null when the caret is past the end of value', () => {
+    expect(detectMentionContext('@ali', 99)).toBeNull()
+  })
+
+  it('rejects queries that exceed the 64-char server cap', () => {
+    const long = 'a'.repeat(65)
+    expect(detectMentionContext(`@${long}`, 1 + long.length)).toBeNull()
+  })
+
+  it('returns null for non-string input (defensive)', () => {
+    // @ts-expect-error — runtime guard against caller misuse
+    expect(detectMentionContext(undefined, 0)).toBeNull()
+  })
+})
+
+describe('insertMentionToken', () => {
+  it('replaces the @<query> slice with @<userId> + trailing space', () => {
+    const ctx = { start: 0, end: 4, query: 'ali' }
+    expect(insertMentionToken('@ali rest', ctx, 'user_123')).toEqual({
+      value: '@user_123 rest',
+      caret: '@user_123 '.length,
+    })
+  })
+
+  it('does not duplicate a trailing space when one is already present', () => {
+    const ctx = { start: 0, end: 4, query: 'ali' }
+    const out = insertMentionToken('@ali extra', ctx, 'u1')
+    expect(out.value).toBe('@u1 extra')
+    expect(out.value.slice(out.caret)).toBe('extra')
+  })
+
+  it('preserves text before the @ token', () => {
+    const ctx = { start: 4, end: 8, query: 'bob' }
+    expect(insertMentionToken('hey @bob', ctx, 'u_99').value).toBe('hey @u_99 ')
+  })
+
+  it('places the caret immediately past the inserted token + space', () => {
+    const ctx = { start: 0, end: 1, query: '' }
+    const out = insertMentionToken('@', ctx, 'u_xyz')
+    expect(out.value).toBe('@u_xyz ')
+    expect(out.caret).toBe(out.value.length)
+  })
+})
+
+describe('searchMentionUsers', () => {
+  it('short-circuits an empty query without hitting the wire', async () => {
+    const out = await searchMentionUsers('')
+    expect(out).toEqual({ ok: true, result: [] })
+    expect(cmsApiMock).not.toHaveBeenCalled()
+  })
+
+  it('short-circuits a whitespace-only query', async () => {
+    const out = await searchMentionUsers('   ')
+    expect(out).toEqual({ ok: true, result: [] })
+    expect(cmsApiMock).not.toHaveBeenCalled()
+  })
+
+  it('URL-encodes the query and forwards the result array', async () => {
+    cmsApiMock.mockResolvedValueOnce({
+      data: [{ id: 'u-1', name: 'Alice', email: 'a@x.com' }],
+      status: 200,
+    })
+    const out = await searchMentionUsers('a li ce')
+    expect(cmsApiMock).toHaveBeenCalledWith(`/users/search?q=${encodeURIComponent('a li ce')}`, {
+      method: 'GET',
+    })
+    expect(out.ok).toBe(true)
+    if (!out.ok) return
+    expect(out.result.map((u) => u.id)).toEqual(['u-1'])
+  })
+
+  it('propagates server errors as { ok: false }', async () => {
+    cmsApiMock.mockResolvedValueOnce({ error: 'CSRF', status: 403 })
+    const out = await searchMentionUsers('ali')
+    expect(out.ok).toBe(false)
+    if (out.ok) return
+    expect(out.error).toBe('CSRF')
+    expect(out.status).toBe(403)
+  })
+})

package/src/components/CommentSidePanel.tsx

@@ -15,6 +15,8 @@ import {
   type CommentThread,
   type CommentOutcome,
 } from '../lib/comments-client.js'
+import type { MentionUser } from '../lib/mention-picker.js'
+import { MentionableTextarea } from './MentionableTextarea.js'
 
 /**
  * Side-panel view of the slice-4 comments API. Renders threaded comments
@@ -69,6 +71,13 @@ export interface CommentSidePanelProps {
    * should leave this unset.
    */
   api?: CommentsApi
+  /**
+   * Override the mention search — tests pass a synchronous fake so
+   * the picker is deterministic without HTTP mocking. Production
+   * callers leave this unset and the textarea uses the real
+   * `/users/search` REST helper.
+   */
+  mentionSearch?: (query: string) => Promise<MentionUser[]>
   className?: string
 }
 
@@ -111,6 +120,7 @@ export function CommentSidePanel({
   onActiveCommentChange,
   onError,
   api = defaultApi,
+  mentionSearch,
   className,
 }: CommentSidePanelProps): React.JSX.Element {
   const [comments, setComments] = useState<Comment[]>([])
@@ -236,13 +246,14 @@ export function CommentSidePanel({
       </header>
 
       <section className="flex flex-col gap-1.5">
-        <textarea
+        <MentionableTextarea
           className="w-full resize-none rounded border border-gray-300 p-2 text-sm focus:border-blue-500 focus:outline-none"
           rows={3}
-          placeholder="Write a comment…"
+          placeholder="Write a comment…  Type @ to mention a teammate."
           value={draft}
-          onChange={(e) => setDraft(e.target.value)}
+          onChange={setDraft}
           data-testid="comment-composer"
+          search={mentionSearch}
         />
         <div className="flex justify-end">
           <button
@@ -276,6 +287,7 @@ export function CommentSidePanel({
                 onEdit={(id, body) => handleEdit(id, body)}
                 onToggleResolve={(id, alreadyResolved) => handleResolve(id, alreadyResolved)}
                 onDelete={(id) => handleDelete(id)}
+                mentionSearch={mentionSearch}
               />
             ))}
           </ul>
@@ -295,6 +307,7 @@ interface CommentThreadViewProps {
   onEdit: (id: string, body: string) => Promise<boolean>
   onToggleResolve: (id: string, alreadyResolved: boolean) => void
   onDelete: (id: string) => void
+  mentionSearch?: (query: string) => Promise<MentionUser[]>
 }
 
 function CommentThreadView({
@@ -307,6 +320,7 @@ function CommentThreadView({
   onEdit,
   onToggleResolve,
   onDelete,
+  mentionSearch,
 }: CommentThreadViewProps): React.JSX.Element {
   const [replyDraft, setReplyDraft] = useState('')
   const cardClass = `rounded border bg-gray-50 p-2 ${
@@ -327,6 +341,7 @@ function CommentThreadView({
         onEdit={onEdit}
         onToggleResolve={() => onToggleResolve(thread.root.id, thread.root.isResolved)}
         onDelete={() => onDelete(thread.root.id)}
+        mentionSearch={mentionSearch}
       />
       {thread.replies.length > 0 && (
         <ul className="mt-2 flex flex-col gap-1 border-l-2 border-gray-200 pl-2">
@@ -341,20 +356,25 @@ function CommentThreadView({
                 // expose delete here.
                 onToggleResolve={null}
                 onDelete={() => onDelete(reply.id)}
+                mentionSearch={mentionSearch}
               />
             </li>
           ))}
         </ul>
       )}
-      <div className="mt-2 flex gap-1">
-        <input
-          className="flex-1 rounded border border-gray-300 px-2 py-1 text-xs focus:border-blue-500 focus:outline-none"
-          placeholder="Reply…"
-          value={replyDraft}
-          onChange={(e) => setReplyDraft(e.target.value)}
-          data-testid={`reply-input-${thread.root.id}`}
-          onClick={(e) => e.stopPropagation()}
-        />
+      <div className="mt-2 flex items-start gap-1">
+        <div className="flex-1">
+          <MentionableTextarea
+            className="w-full resize-none rounded border border-gray-300 px-2 py-1 text-xs focus:border-blue-500 focus:outline-none"
+            placeholder="Reply…  Type @ to mention."
+            rows={1}
+            value={replyDraft}
+            onChange={setReplyDraft}
+            data-testid={`reply-input-${thread.root.id}`}
+            onClick={(e) => e.stopPropagation()}
+            search={mentionSearch}
+          />
+        </div>
         <button
           type="button"
           className="rounded bg-gray-700 px-2 py-1 text-xs font-medium text-white hover:bg-gray-600 disabled:opacity-50"
@@ -380,6 +400,7 @@ interface CommentRowProps {
   onEdit: (id: string, body: string) => Promise<boolean>
   onToggleResolve: null | (() => void)
   onDelete: () => void
+  mentionSearch?: (query: string) => Promise<MentionUser[]>
 }
 
 function CommentRow({
@@ -389,6 +410,7 @@ function CommentRow({
   onEdit,
   onToggleResolve,
   onDelete,
+  mentionSearch,
 }: CommentRowProps): React.JSX.Element {
   const [editing, setEditing] = useState(false)
   const [draft, setDraft] = useState(comment.body)
@@ -409,13 +431,14 @@ function CommentRow({
       {meta}
       {editing ? (
         <>
-          <textarea
+          <MentionableTextarea
             className="w-full resize-none rounded border border-gray-300 p-1 text-sm"
             rows={3}
             value={draft}
-            onChange={(e) => setDraft(e.target.value)}
+            onChange={setDraft}
             data-testid={`edit-textarea-${comment.id}`}
             onClick={(e) => e.stopPropagation()}
+            search={mentionSearch}
           />
           <div className="flex gap-1">
             <button