@actuate-media/cms-admin 0.13.0 → 0.14.0

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>
+  )
+}

package/src/lib/mention-picker.ts

@@ -0,0 +1,180 @@
+/**
+ * Mention picker client logic + REST helper.
+ *
+ * Two responsibilities, deliberately separated so each can be unit
+ * tested without rendering React or hitting fetch:
+ *
+ * 1. `searchMentionUsers(query)` — typed wrapper over the new
+ *    `GET /api/cms/users/search` endpoint introduced in Phase 7.
+ *    Returns up to 10 `{ id, name, email }` rows matching the query.
+ * 2. `detectMentionContext(value, caret)` — pure parser that scans a
+ *    text input value backwards from the caret to decide whether the
+ *    user is currently typing a `@`-mention, and if so what the
+ *    query fragment is. Returns `null` when no active mention.
+ *
+ * Wire format note: the picker INSERTS `@<userId>` tokens at the
+ * cursor (matching the server-side `extractMentionedUserIds` regex
+ * in `cms-core/realtime/notifications.ts`). The user sees the chosen
+ * user's *name* in the picker but the textarea always holds the id.
+ * Rendering names back in the comment view is a separate slice that
+ * can ship later without breaking the wire format.
+ */
+import { cmsApi } from './api.js'
+
+export interface MentionUser {
+  id: string
+  name: string
+  email: string
+}
+
+export type MentionSearchOutcome =
+  | { ok: true; result: MentionUser[] }
+  | { ok: false; error: string; status: number }
+
+export async function searchMentionUsers(query: string): Promise<MentionSearchOutcome> {
+  const trimmed = query.trim()
+  if (trimmed.length === 0) {
+    // Mirror the server's contract: an empty query returns an empty
+    // array. We short-circuit here so the picker doesn't spend a
+    // round-trip on a guaranteed-empty response.
+    return { ok: true, result: [] }
+  }
+  const res = await cmsApi<MentionUser[]>(`/users/search?q=${encodeURIComponent(trimmed)}`, {
+    method: 'GET',
+  })
+  if (res.error || !res.data) {
+    return { ok: false, error: res.error ?? `Request failed (${res.status})`, status: res.status }
+  }
+  return { ok: true, result: res.data }
+}
+
+/**
+ * Description of an active `@`-mention being typed in a textarea / input.
+ *
+ *  - `start` and `end` are character offsets into the field value: the
+ *    `@` itself sits at `start`, and `end` is the caret position
+ *    (exclusive end of the query slice).
+ *  - `query` is the substring between the `@` and the caret — exactly
+ *    what we should pass to `searchMentionUsers()`.
+ *
+ * Callers replace `value.slice(start, end)` with the chosen token
+ * (`@<userId> `, including the trailing space) to commit a selection.
+ */
+export interface MentionContext {
+  start: number
+  end: number
+  query: string
+}
+
+/**
+ * Find an active mention at the caret. Mirrors the server-side
+ * `extractMentionedUserIds` regex
+ * (`/(^|\s)@[a-zA-Z0-9_-]{3,64}\b/g`) so the picker's intuition
+ * about what counts as a mention can never disagree with the
+ * server's notification routing.
+ *
+ * Returns `null` whenever:
+ *   - the caret is at offset 0,
+ *   - there is no `@` between the caret and the previous whitespace
+ *     boundary,
+ *   - the `@` is preceded by a non-whitespace, non-newline character
+ *     (so an email address mid-word like `foo@bar` does NOT open
+ *     the picker), or
+ *   - the candidate query contains a character outside the mention
+ *     charset (`[a-zA-Z0-9_-]`).
+ *
+ * The picker DOES open with a 0–2 character query — that's the
+ * "you've started typing a mention" UX. But it can NEVER commit
+ * such a token: `insertMentionToken` only fires for a `MentionUser`
+ * which always has an id of at least 3 chars, matching the server
+ * regex's min-length requirement.
+ */
+export function detectMentionContext(value: string, caret: number): MentionContext | null {
+  if (typeof value !== 'string') return null
+  if (caret <= 0 || caret > value.length) return null
+
+  // Walk back from the caret looking for a `@`. Stop early on any
+  // character that is neither a valid mention char nor `@`. This
+  // means a typed space, newline, punctuation, etc. terminates the
+  // mention candidate the user was building.
+  let i = caret - 1
+  while (i >= 0) {
+    const ch = value.charCodeAt(i)
+    if (ch === 64 /* @ */) break
+    if (!isMentionChar(ch)) return null
+    i -= 1
+  }
+  if (i < 0) return null
+
+  // The `@` must sit at the start of the field or be preceded by
+  // whitespace / newline. Otherwise we're mid-word (think `foo@bar`),
+  // which is not a mention.
+  if (i > 0) {
+    const prev = value.charCodeAt(i - 1)
+    if (!isBoundary(prev)) return null
+  }
+
+  const query = value.slice(i + 1, caret)
+  // Server caps queries at 64 chars; the picker simply stops
+  // suggesting once the typed query exceeds that — extra typing
+  // closes the picker so the user can complete an email or other
+  // long token without staring at a dead dropdown.
+  if (query.length > 64) return null
+
+  return { start: i, end: caret, query }
+}
+
+function isMentionChar(code: number): boolean {
+  // [a-zA-Z0-9_-] — keep this in lock-step with the regex in
+  // `cms-core/realtime/notifications.ts:extractMentionedUserIds`.
+  if (code === 95 /* _ */ || code === 45 /* - */) return true
+  if (code >= 48 && code <= 57) return true // 0-9
+  if (code >= 65 && code <= 90) return true // A-Z
+  if (code >= 97 && code <= 122) return true // a-z
+  return false
+}
+
+function isBoundary(code: number): boolean {
+  // ASCII space, tab, line-feed, or carriage-return. We deliberately
+  // do NOT widen this to the full Unicode whitespace class — the
+  // server-side `extractMentionedUserIds` regex in
+  // `cms-core/realtime/notifications.ts` uses `\s` which DOES match
+  // Unicode whitespace, but its `^` anchor means the only realistic
+  // mid-string boundaries in practice are these four ASCII chars
+  // (a CMS comment body containing U+00A0 NBSP before an `@` would
+  // be both unusual and not worth opening the picker for).
+  return code === 32 || code === 9 || code === 10 || code === 13
+}
+
+/**
+ * Apply a mention selection to a text value. Returns the new value
+ * plus the caret position where the next keystroke should land.
+ *
+ * Inserts `@<userId> ` (trailing space) so the user can keep typing
+ * without manually moving the cursor past the token. If the caret
+ * already sits before a space, we don't insert a duplicate space.
+ */
+export interface MentionInsertion {
+  value: string
+  caret: number
+}
+
+export function insertMentionToken(
+  value: string,
+  context: MentionContext,
+  userId: string,
+): MentionInsertion {
+  const hasTrailingSpace = value.charAt(context.end) === ' '
+  // If the user already has a space immediately after the mention
+  // region, reuse it (don't double-space) but still advance the
+  // caret past that space so the next keystroke continues naturally
+  // rather than landing back in front of the space.
+  const trailingSpace = hasTrailingSpace ? '' : ' '
+  const token = `@${userId}${trailingSpace}`
+  const before = value.slice(0, context.start)
+  const after = value.slice(context.end)
+  return {
+    value: `${before}${token}${after}`,
+    caret: context.start + token.length + (hasTrailingSpace ? 1 : 0),
+  }
+}