@actuate-media/cms-admin 0.12.1 → 0.14.0

package/src/__tests__/lib/notifications-client.test.ts

@@ -3,6 +3,10 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 const cmsApiMock = vi.fn()
 vi.mock('../../lib/api.js', () => ({
   cmsApi: (...args: unknown[]) => cmsApiMock(...args),
+  // SSE uses EventSource, which doesn't go through cmsApi. The
+  // helper resolves the URL via getApiBase() — return the production
+  // default so tests don't need to know the prefix.
+  getApiBase: () => '/api/cms',
 }))
 
 const {
@@ -10,9 +14,14 @@ const {
   markAllNotificationsRead,
   markNotificationRead,
   notificationSummary,
+  subscribeNotificationStream,
   unreadCount,
 } = await import('../../lib/notifications-client.js')
-import type { Notification } from '../../lib/notifications-client.js'
+import type {
+  EventSourceLike,
+  Notification,
+  NotificationStreamOptions,
+} from '../../lib/notifications-client.js'
 
 function row(overrides: Partial<Notification> = {}): Notification {
   return {
@@ -193,3 +202,138 @@ describe('notificationSummary', () => {
     ).toMatch(/^Someone replied/)
   })
 })
+
+// ---------------------------------------------------------------------------
+// SSE push channel — subscribeNotificationStream
+// ---------------------------------------------------------------------------
+
+/**
+ * In-memory `EventSource` double. Tests drive the wire by invoking
+ * `emit(event, payload)`; the subscriber dispatches the right
+ * listener. We deliberately keep the shape minimal — `EventSource`
+ * has dozens of properties our admin doesn't touch.
+ */
+function makeFakeSource() {
+  const listeners = new Map<string, Set<(e: MessageEvent | Event) => void>>()
+  let closed = false
+  const source: EventSourceLike = {
+    addEventListener: (type, listener) => {
+      if (closed) return
+      let set = listeners.get(type)
+      if (!set) {
+        set = new Set()
+        listeners.set(type, set)
+      }
+      set.add(listener)
+    },
+    removeEventListener: (type, listener) => {
+      listeners.get(type)?.delete(listener)
+    },
+    close: () => {
+      closed = true
+      listeners.clear()
+    },
+  }
+  return {
+    source,
+    listenerCount: (type: string) => listeners.get(type)?.size ?? 0,
+    isClosed: () => closed,
+    emit(type: string, payload: unknown) {
+      const set = listeners.get(type)
+      if (!set) return
+      const event =
+        typeof payload === 'string'
+          ? ({ data: payload } as MessageEvent)
+          : payload === undefined
+            ? (new Event(type) as Event)
+            : ({ data: JSON.stringify(payload) } as MessageEvent)
+      for (const l of [...set]) l(event)
+    },
+  }
+}
+
+function startStream(
+  fake: ReturnType<typeof makeFakeSource>,
+  overrides: Partial<NotificationStreamOptions> = {},
+) {
+  return subscribeNotificationStream({
+    onNotification: () => undefined,
+    factory: () => fake.source,
+    ...overrides,
+  })
+}
+
+describe('subscribeNotificationStream', () => {
+  it('dispatches `notification` frames as Notification objects', () => {
+    const fake = makeFakeSource()
+    const seen: Notification[] = []
+    startStream(fake, { onNotification: (n) => seen.push(n) })
+    fake.emit('notification', row({ id: 'sse-1' }))
+    expect(seen.map((n) => n.id)).toEqual(['sse-1'])
+  })
+
+  it('dispatches `ready` frames once via onReady', () => {
+    const fake = makeFakeSource()
+    const readys: Array<{ userId: string }> = []
+    startStream(fake, { onReady: (p) => readys.push(p) })
+    fake.emit('ready', { userId: 'user-1' })
+    expect(readys).toEqual([{ userId: 'user-1' }])
+  })
+
+  it('ignores malformed payloads (defence against wire drift)', () => {
+    const fake = makeFakeSource()
+    const seen: Notification[] = []
+    startStream(fake, { onNotification: (n) => seen.push(n) })
+    // Missing id + payload — must not throw, must not deliver.
+    fake.emit('notification', { userId: 'user-1', createdAt: 'now' })
+    fake.emit('notification', 'not json')
+    expect(seen).toEqual([])
+  })
+
+  it('removes its listeners and closes the underlying source on close()', () => {
+    const fake = makeFakeSource()
+    const handle = startStream(fake)
+    expect(fake.listenerCount('notification')).toBe(1)
+    expect(fake.listenerCount('ready')).toBe(1)
+    expect(fake.listenerCount('error')).toBe(1)
+    handle.close()
+    expect(fake.isClosed()).toBe(true)
+    // Second close() is a no-op — guards against double-unmount loops.
+    handle.close()
+    expect(fake.isClosed()).toBe(true)
+  })
+
+  it('returns a no-op handle when no EventSource is available', () => {
+    // No factory + no global EventSource (vitest jsdom env doesn't
+    // ship one). The subscriber must NOT throw — admin code must
+    // remain mountable in SSR / Node environments.
+    const handle = subscribeNotificationStream({
+      onNotification: () => undefined,
+      factory: () => null,
+    })
+    expect(() => handle.close()).not.toThrow()
+  })
+
+  it('forwards error events to onError without crashing the page', () => {
+    const fake = makeFakeSource()
+    const errors: Event[] = []
+    startStream(fake, { onError: (e) => errors.push(e) })
+    fake.emit('error', undefined)
+    expect(errors).toHaveLength(1)
+  })
+
+  it('builds the stream URL from getApiBase() so consumers with a custom prefix connect to the right host', () => {
+    // Custom factory inspects the URL it's handed. Verifies the
+    // subscriber composes /<base>/notifications/stream rather than
+    // hardcoding the production prefix.
+    const seen: string[] = []
+    subscribeNotificationStream({
+      onNotification: () => undefined,
+      factory: (url) => {
+        seen.push(url)
+        return null
+      },
+    })
+    expect(seen).toEqual(['/api/cms/notifications/stream'])
+  })
+})

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

package/src/components/MentionableTextarea.tsx

@@ -0,0 +1,328 @@
+'use client'
+
+import React, { useCallback, useEffect, useId, useRef, useState } from 'react'
+
+import {
+  type MentionUser,
+  detectMentionContext,
+  insertMentionToken,
+  searchMentionUsers,
+} from '../lib/mention-picker.js'
+
+/**
+ * `<MentionableTextarea />` — drop-in replacement for `<textarea>` /
+ * `<input type="text">` that opens a Radix-styled mention picker
+ * whenever the user types `@`.
+ *
+ * Behaviour
+ * ─────────
+ * - The picker appears anchored to the textarea, below the input.
+ *   We intentionally do NOT track the caret pixel position (that
+ *   requires a textarea-mirror trick which doesn't add enough UX to
+ *   justify the complexity); GitHub, Linear, and Asana all anchor
+ *   their pickers this way on simple textareas.
+ * - Arrow Up / Arrow Down move the highlight. Enter / Tab commit the
+ *   selection. Escape closes the picker without inserting anything.
+ *   Mouse click on a row also commits.
+ * - The picker only fires server queries while a real mention is
+ *   being typed; it short-circuits an empty `query` so the dropdown
+ *   shows up immediately after `@` is typed (with an empty state)
+ *   and only flips to "no matches" once the user has typed at least
+ *   one character.
+ * - The textarea value is fully controlled by the parent — we never
+ *   keep a separate copy. `onChange` is called with the next value
+ *   on every keystroke AND every mention insertion.
+ *
+ * Dependency-injection seam
+ * ─────────────────────────
+ * The `search` prop accepts an override so tests can substitute a
+ * synchronous fake. Production callers leave it unset and the
+ * component uses the real `searchMentionUsers()` REST helper.
+ */
+export interface MentionableTextareaProps {
+  value: string
+  onChange: (next: string) => void
+  /** Forwarded to the underlying textarea. */
+  placeholder?: string
+  /** Forwarded to the underlying textarea. */
+  rows?: number
+  className?: string
+  /** Forwarded — useful for keyboard shortcuts the parent owns. */
+  onKeyDown?: (event: React.KeyboardEvent<HTMLTextAreaElement>) => void
+  /** Forwarded — useful for click-to-stop-propagation in nested cards. */
+  onClick?: (event: React.MouseEvent<HTMLTextAreaElement>) => void
+  /** Test hook — required when rendering with React state assertions. */
+  'data-testid'?: string
+  /**
+   * Override the user search. The default uses the REST helper.
+   * Tests inject an in-memory fake so dropdown contents are
+   * deterministic without HTTP mocking.
+   */
+  search?: (query: string) => Promise<MentionUser[]>
+  /**
+   * Optional fixed id for the picker dropdown — pass when the parent
+   * wires up `aria-controls`. We generate one with `useId()` when
+   * unset.
+   */
+  pickerId?: string
+  /**
+   * Format the displayed token. By default we show `@<name>` while
+   * the underlying value stores `@<userId>`. A future slice can swap
+   * to a rich-text editor where these diverge; the prop lets that
+   * land without changing the picker.
+   */
+  formatLabel?: (user: MentionUser) => string
+}
+
+interface PickerState {
+  open: boolean
+  query: string
+  highlight: number
+  users: MentionUser[]
+}
+
+const initialPicker: PickerState = {
+  open: false,
+  query: '',
+  highlight: 0,
+  users: [],
+}
+
+export function MentionableTextarea({
+  value,
+  onChange,
+  placeholder,
+  rows = 3,
+  className,
+  onKeyDown,
+  onClick,
+  'data-testid': testId,
+  search = (q) => searchMentionUsers(q).then((r) => (r.ok ? r.result : [])),
+  pickerId: pickerIdProp,
+  formatLabel = (u) => `@${u.name}`,
+}: MentionableTextareaProps): React.JSX.Element {
+  const generatedId = useId()
+  const pickerId = pickerIdProp ?? `actuate-mention-picker-${generatedId}`
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null)
+  const [picker, setPicker] = useState<PickerState>(initialPicker)
+  // `pickerRef` mirrors `picker` for the keydown handler so the
+  // arrow-key / enter listeners don't go stale between renders.
+  const pickerRef = useRef(picker)
+  useEffect(() => {
+    pickerRef.current = picker
+  }, [picker])
+  const requestSeq = useRef(0)
+  const mountedRef = useRef(true)
+  useEffect(() => {
+    return () => {
+      mountedRef.current = false
+    }
+  }, [])
+
+  const closePicker = useCallback(() => {
+    setPicker((p) => (p.open ? initialPicker : p))
+  }, [])
+
+  // Recompute the active mention context whenever the value or
+  // selection changes. Centralising this in one effect keeps the
+  // open/close logic in a single place — every textarea event
+  // (input, click, keyup) just calls `recompute()`.
+  const recompute = useCallback(
+    async (nextValue: string, caret: number) => {
+      const ctx = detectMentionContext(nextValue, caret)
+      if (!ctx) {
+        closePicker()
+        return
+      }
+      const id = ++requestSeq.current
+      // Open immediately so the user sees a dropdown the moment they
+      // type `@`. Clear the `users` array on every new query so the
+      // user can never press Enter / Tab and commit a stale row
+      // from the previous query while the new request is in flight
+      // (PR #159 Copilot finding — type `@a` then `@bo` quickly and
+      // hit Enter before the `@bo` results arrive: without this
+      // reset, the picker would commit a row from `@a`).
+      setPicker((p) => ({
+        open: true,
+        query: ctx.query,
+        highlight: 0,
+        users: p.query === ctx.query ? p.users : [],
+      }))
+      try {
+        const users = await search(ctx.query)
+        if (!mountedRef.current) return
+        // Drop stale responses — only commit if our request is still
+        // the latest one. Otherwise the user has typed more and a
+        // newer query is in flight.
+        if (id !== requestSeq.current) return
+        setPicker((p) =>
+          // If the picker was closed (Escape) between request and
+          // response, don't reopen it.
+          p.open ? { ...p, users, highlight: 0 } : p,
+        )
+      } catch {
+        if (!mountedRef.current) return
+        if (id !== requestSeq.current) return
+        // Surface no rows on failure — the textarea must keep
+        // working when the user is offline. The poll loop / native
+        // submit path is unaffected.
+        setPicker((p) => (p.open ? { ...p, users: [] } : p))
+      }
+    },
+    [closePicker, search],
+  )
+
+  const commitMention = useCallback(
+    (user: MentionUser) => {
+      const el = textareaRef.current
+      if (!el) return
+      const caret = el.selectionStart ?? value.length
+      const ctx = detectMentionContext(value, caret)
+      if (!ctx) {
+        closePicker()
+        return
+      }
+      const next = insertMentionToken(value, ctx, user.id)
+      onChange(next.value)
+      closePicker()
+      // Move the caret past the inserted token AFTER React paints
+      // the new value, so the selection isn't clobbered by the
+      // controlled update.
+      requestAnimationFrame(() => {
+        const live = textareaRef.current
+        if (!live) return
+        live.focus()
+        live.setSelectionRange(next.caret, next.caret)
+      })
+    },
+    [closePicker, onChange, value],
+  )
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    const next = event.target.value
+    const caret = event.target.selectionStart ?? next.length
+    onChange(next)
+    void recompute(next, caret)
+  }
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    const p = pickerRef.current
+    if (p.open && p.users.length > 0) {
+      if (event.key === 'ArrowDown') {
+        event.preventDefault()
+        setPicker((s) => ({ ...s, highlight: (s.highlight + 1) % s.users.length }))
+        return
+      }
+      if (event.key === 'ArrowUp') {
+        event.preventDefault()
+        setPicker((s) => ({
+          ...s,
+          highlight: (s.highlight - 1 + s.users.length) % s.users.length,
+        }))
+        return
+      }
+      if (event.key === 'Enter' || event.key === 'Tab') {
+        event.preventDefault()
+        // Defensive: highlight could theoretically point past the
+        // end of `users` if state went stale between renders. Guard
+        // it so we never `undefined`-bang.
+        const target = p.users[p.highlight]
+        if (target) commitMention(target)
+        return
+      }
+    }
+    if (event.key === 'Escape' && p.open) {
+      event.preventDefault()
+      closePicker()
+      return
+    }
+    onKeyDown?.(event)
+  }
+
+  const handleClick = (event: React.MouseEvent<HTMLTextAreaElement>) => {
+    onClick?.(event)
+    const el = textareaRef.current
+    if (!el) return
+    void recompute(el.value, el.selectionStart ?? el.value.length)
+  }
+
+  // Closing on outside click — when the user clicks anywhere outside
+  // the textarea or the picker, the dropdown should disappear so it
+  // doesn't sit on top of unrelated UI.
+  useEffect(() => {
+    if (!picker.open) return
+    const onDocMouseDown = (ev: MouseEvent) => {
+      const t = ev.target as Node | null
+      if (!t) return
+      const parent = textareaRef.current?.parentElement
+      if (parent && parent.contains(t)) return
+      closePicker()
+    }
+    document.addEventListener('mousedown', onDocMouseDown)
+    return () => document.removeEventListener('mousedown', onDocMouseDown)
+  }, [picker.open, closePicker])
+
+  return (
+    <div className="relative">
+      <textarea
+        ref={textareaRef}
+        value={value}
+        onChange={handleChange}
+        onKeyDown={handleKeyDown}
+        onClick={handleClick}
+        placeholder={placeholder}
+        rows={rows}
+        className={className}
+        aria-autocomplete="list"
+        aria-controls={picker.open ? pickerId : undefined}
+        aria-expanded={picker.open}
+        data-testid={testId}
+      />
+      {picker.open && (
+        <div
+          id={pickerId}
+          role="listbox"
+          aria-label="Mention a teammate"
+          className="absolute top-full left-0 z-30 mt-1 max-h-56 w-64 overflow-y-auto rounded border border-gray-200 bg-white shadow-lg"
+          data-testid={testId ? `${testId}-picker` : 'mention-picker'}
+        >
+          {picker.users.length === 0 ? (
+            <p className="px-3 py-2 text-xs text-gray-500">
+              {picker.query ? 'No matches' : 'Type a name…'}
+            </p>
+          ) : (
+            <ul>
+              {picker.users.map((u, idx) => (
+                <li key={u.id}>
+                  <button
+                    type="button"
+                    role="option"
+                    aria-selected={idx === picker.highlight}
+                    onMouseDown={(e) => {
+                      // mousedown (not click) — prevents the
+                      // textarea from losing focus before we
+                      // commit, which would otherwise hide the
+                      // selection and feel janky.
+                      e.preventDefault()
+                      commitMention(u)
+                    }}
+                    onMouseEnter={() => setPicker((s) => ({ ...s, highlight: idx }))}
+                    className={`block w-full px-3 py-1.5 text-left text-xs ${
+                      idx === picker.highlight
+                        ? 'bg-blue-50 text-blue-900'
+                        : 'text-gray-800 hover:bg-gray-50'
+                    }`}
+                    data-testid={testId ? `${testId}-picker-row-${u.id}` : `mention-row-${u.id}`}
+                  >
+                    <div className="font-medium">{formatLabel(u)}</div>
+                    <div className="text-[10px] text-gray-500">{u.email}</div>
+                  </button>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}