@actuate-media/cms-admin 0.12.1 → 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__/components/notification-bell.test.tsx

@@ -4,7 +4,12 @@ import React from 'react'
 import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
 
 import { NotificationBell, type NotificationsApi } from '../../components/NotificationBell.js'
-import type { Notification, NotificationOutcome } from '../../lib/notifications-client.js'
+import type {
+  Notification,
+  NotificationOutcome,
+  NotificationStreamHandle,
+  NotificationStreamOptions,
+} from '../../lib/notifications-client.js'
 
 function ok<T>(value: T): NotificationOutcome<T> {
   return { ok: true, result: value }
@@ -211,3 +216,164 @@ describe('NotificationBell — dropdown', () => {
     await waitFor(() => expect(onError).toHaveBeenCalledWith('CSRF'))
   })
 })
+
+// ---------------------------------------------------------------------------
+// SSE push channel (Phase 7) — verify the bell wires up subscribe(),
+// processes incoming notifications, and tears down on unmount.
+// ---------------------------------------------------------------------------
+describe('NotificationBell — SSE push', () => {
+  function withSubscribe(api: NotificationsApi) {
+    let captured: NotificationStreamOptions | undefined
+    let closed = false
+    const handle: NotificationStreamHandle = {
+      close: () => {
+        closed = true
+      },
+    }
+    const subscribe = vi.fn((opts: NotificationStreamOptions) => {
+      captured = opts
+      return handle
+    })
+    return {
+      api: { ...api, subscribe },
+      push: (n: Notification) => captured?.onNotification(n),
+      pushError: (e: Event) => captured?.onError?.(e),
+      isClosed: () => closed,
+    }
+  }
+
+  it('subscribes on mount and bumps the badge when a new notification arrives', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} />)
+    await waitFor(() => expect(fake.api.unread).toHaveBeenCalled())
+    await act(async () => {
+      wired.push(row({ id: 'sse-1' }))
+    })
+    await waitFor(() => expect(screen.getByTestId('bell-badge').textContent).toBe('1'))
+  })
+
+  it('does not double-count a notification that arrives via both SSE and REST', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    fake.setRows([row({ id: 'race' })])
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} />)
+    // Open the dropdown so the row is in `items` from the REST list.
+    await waitFor(() => expect(screen.getByTestId('bell-badge').textContent).toBe('1'))
+    fireEvent.click(screen.getByTestId('bell-button'))
+    await waitFor(() => expect(screen.getByTestId('bell-row-race')).toBeTruthy())
+    // Now push the same row via SSE — must NOT add a duplicate or
+    // bump the badge above 1.
+    await act(async () => {
+      wired.push(row({ id: 'race' }))
+    })
+    expect(screen.getAllByTestId('bell-row-race')).toHaveLength(1)
+    expect(screen.getByTestId('bell-badge').textContent).toBe('1')
+  })
+
+  it('prepends new pushed rows to the open dropdown', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    fake.setRows([row({ id: 'old' })])
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} />)
+    await waitFor(() => expect(screen.getByTestId('bell-badge').textContent).toBe('1'))
+    fireEvent.click(screen.getByTestId('bell-button'))
+    await waitFor(() => expect(screen.getByTestId('bell-row-old')).toBeTruthy())
+    await act(async () => {
+      wired.push(row({ id: 'fresh' }))
+    })
+    const rows = screen.getAllByTestId(/^bell-row-/)
+    expect(rows[0]!.getAttribute('data-testid')).toBe('bell-row-fresh')
+  })
+
+  it('does NOT bump the badge when the pushed notification is already read', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} />)
+    await waitFor(() => expect(fake.api.unread).toHaveBeenCalled())
+    await act(async () => {
+      wired.push(row({ id: 'already-read', readAt: '2026-01-02T00:00:00.000Z' }))
+    })
+    // Already-read notifications still appear in the list when the
+    // user opens the dropdown with includeRead=true, but they must
+    // NOT register a fresh unread bump.
+    expect(screen.queryByTestId('bell-badge')).toBeNull()
+  })
+
+  it('closes the SSE subscription when the bell unmounts', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    const { unmount } = render(<NotificationBell api={wired.api} pollIntervalMs={0} />)
+    await waitFor(() => expect(fake.api.unread).toHaveBeenCalled())
+    unmount()
+    expect(wired.isClosed()).toBe(true)
+  })
+
+  it('does not surface transient SSE errors via onError (poll loop handles convergence)', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    const onError = vi.fn()
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} onError={onError} />)
+    await waitFor(() => expect(fake.api.unread).toHaveBeenCalled())
+    await act(async () => {
+      wired.pushError(new Event('error'))
+    })
+    // Deliberately quiet — see NotificationBell SSE handler comment.
+    expect(onError).not.toHaveBeenCalled()
+  })
+
+  it('mark-all-read failure does not drop SSE rows that arrived mid-flight', async () => {
+    const fake = createFakeApi()
+    const wired = withSubscribe(fake.api)
+    fake.setRows([row({ id: 'before' })])
+    // Hold the markAllRead promise so we can interleave an SSE push.
+    let resolveMark: (v: NotificationOutcome<number>) => void = () => undefined
+    ;(wired.api.markAllRead as ReturnType<typeof vi.fn>).mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveMark = resolve
+        }),
+    )
+    const onError = vi.fn()
+    render(<NotificationBell api={wired.api} pollIntervalMs={0} onError={onError} />)
+    await waitFor(() => expect(screen.getByTestId('bell-badge').textContent).toBe('1'))
+    fireEvent.click(screen.getByTestId('bell-button'))
+    await waitFor(() => expect(screen.getByTestId('bell-row-before')).toBeTruthy())
+
+    // Click mark-all — handler optimistically marks 'before' read,
+    // but the API promise is still pending.
+    await act(async () => {
+      fireEvent.click(screen.getByTestId('bell-mark-all'))
+    })
+    // While in flight, a fresh notification arrives via SSE.
+    await act(async () => {
+      wired.push(row({ id: 'mid-flight' }))
+    })
+
+    // Now resolve the API with a failure.
+    await act(async () => {
+      resolveMark({ ok: false, error: 'server', status: 500 })
+      // flush promise chain
+      await Promise.resolve()
+    })
+
+    expect(onError).toHaveBeenCalledWith('server')
+    // The original row was rolled back to unread...
+    expect(screen.getByTestId('bell-row-before').getAttribute('data-read')).toBe('false')
+    // ...and the SSE arrival is still present (not dropped by the
+    // legacy snapshot-replace rollback).
+    expect(screen.getByTestId('bell-row-mid-flight')).toBeTruthy()
+  })
+
+  it('still mounts cleanly when api.subscribe is undefined (no SSE support)', async () => {
+    const fake = createFakeApi()
+    // Strip the `subscribe` member entirely — defaultApi has it,
+    // but consumer-provided test APIs may not.
+    const apiWithoutSubscribe: NotificationsApi = { ...fake.api }
+    delete (apiWithoutSubscribe as { subscribe?: unknown }).subscribe
+    render(<NotificationBell api={apiWithoutSubscribe} pollIntervalMs={0} />)
+    await waitFor(() => expect(fake.api.unread).toHaveBeenCalled())
+    // No crash, badge from unread() shows nothing, no items.
+    expect(screen.queryByTestId('bell-badge')).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)
+  })
+})