@actuate-media/cms-admin 0.12.1 → 0.14.0

package/dist/lib/mention-picker.js

@@ -0,0 +1,138 @@
+/**
+ * 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 async function searchMentionUsers(query) {
+    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(`/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 };
+}
+/**
+ * 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, caret) {
+    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) {
+    // [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) {
+    // 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;
+}
+export function insertMentionToken(value, context, userId) {
+    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),
+    };
+}
+//# sourceMappingURL=mention-picker.js.map

package/dist/lib/mention-picker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mention-picker.js","sourceRoot":"","sources":["../../src/lib/mention-picker.ts"],"names":[],"mappings":"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"}

package/dist/lib/notifications-client.d.ts

@@ -58,6 +58,59 @@ export declare function listNotifications(opts?: ListNotificationsOptions): Prom
 export declare function unreadCount(): Promise<NotificationOutcome<number>>;
 export declare function markNotificationRead(id: string): Promise<NotificationOutcome<Notification>>;
 export declare function markAllNotificationsRead(): Promise<NotificationOutcome<number>>;
+/**
+ * Subscribe to the per-user SSE push channel that ships notifications
+ * the instant they're persisted server-side. Replaces the 30-second
+ * poll loop in the notification bell.
+ *
+ * The browser's native `EventSource` handles reconnection for us — on
+ * a server-initiated close (the stream caps at ~4 minutes by design),
+ * the connection re-opens automatically. We DO NOT abort the poll
+ * fallback in callers: SSE is a latency-win, the poll is what keeps
+ * multi-node deployments correct (each node only pushes to its own
+ * subscribers).
+ *
+ * Returns a `close()` function that callers MUST invoke on unmount —
+ * otherwise the browser keeps the connection open and we leak event
+ * listeners.
+ *
+ * `EventSource` itself isn't available in the JSDOM test environment;
+ * callers can inject a `factory` to substitute a test double. In
+ * production we fall back to the global `EventSource` when no factory
+ * is supplied.
+ */
+export interface NotificationStreamOptions {
+    /** Called for every `event: notification` frame. */
+    onNotification: (n: Notification) => void;
+    /** Called once on the `event: ready` frame. */
+    onReady?: (payload: {
+        userId: string;
+    }) => void;
+    /** Called on connection errors. Useful for falling back to the poll loop. */
+    onError?: (event: Event) => void;
+    /**
+     * Optional factory so unit tests can inject a fake `EventSource`,
+     * or a null sentinel when the environment lacks one (SSR, JSDOM
+     * without a polyfill). Production code can rely on the default
+     * (global `EventSource`).
+     */
+    factory?: (url: string) => EventSourceLike | null;
+}
+/**
+ * Minimal subset of the `EventSource` interface our subscriber relies
+ * on. Browsers ship the full DOM type; the admin only needs add/remove
+ * event listeners plus `close()`.
+ */
+export interface EventSourceLike {
+    addEventListener: (type: string, listener: (event: MessageEvent | Event) => void) => void;
+    removeEventListener?: (type: string, listener: (event: MessageEvent | Event) => void) => void;
+    close: () => void;
+}
+export interface NotificationStreamHandle {
+    /** Tear down the EventSource and stop receiving events. Idempotent. */
+    close: () => void;
+}
+export declare function subscribeNotificationStream(opts: NotificationStreamOptions): NotificationStreamHandle;
 /**
  * Cheap single-line summary for the bell list — the server gives us a
  * structured payload, but the dropdown wants one human-readable string

package/dist/lib/notifications-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notifications-client.d.ts","sourceRoot":"","sources":["../../src/lib/notifications-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,kBAAkB,GAAG,iBAAiB,CAAA;AAEvF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,kBAAkB,CAAA;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,iBAAiB,CAAA;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,MAAM,mBAAmB,GAC3B,mBAAmB,GACnB,sBAAsB,GACtB,qBAAqB,CAAA;AAEzB,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,gBAAgB,CAAA;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,mBAAmB,CAAA;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,GACvB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhD,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAyBD,wBAAsB,iBAAiB,CACrC,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC,mBAAmB,CAAC,YAAY,EAAE,CAAC,CAAC,CAK9C;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAQxE;AAED,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAC,CAOjG;AAED,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CASrF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAYtE"}
+{"version":3,"file":"notifications-client.d.ts","sourceRoot":"","sources":["../../src/lib/notifications-client.ts"],"names":[],"mappings":"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"}

package/dist/lib/notifications-client.js

@@ -10,7 +10,7 @@
  * shape here to avoid taking a hard dependency on the server module
  * (which carries Prisma types that don't belong in the admin bundle).
  */
-import { cmsApi } from './api.js';
+import { cmsApi, getApiBase } from './api.js';
 function failure(error, status) {
     return { ok: false, error, status };
 }
@@ -63,6 +63,94 @@ export async function markAllNotificationsRead() {
     }
     return { ok: true, result: res.data.count };
 }
+export function subscribeNotificationStream(opts) {
+    // The `cmsApi()` helper handles base-path / origin resolution for
+    // fetch calls, but EventSource takes a raw URL. We mirror its
+    // logic locally — `/api/cms/notifications/stream` is correct for
+    // both the local dev server and any production deploy that mounts
+    // the CMS API at the default prefix. Custom prefixes are handled by
+    // the consumer override (factory).
+    // Resolve against `setApiBase()` so a consumer mounting the CMS at
+    // a non-default prefix (e.g. `/cms-api`) still hits the right SSE
+    // endpoint — `EventSource` doesn't go through `cmsApi()`, so we
+    // can't rely on its url-construction logic.
+    const url = `${getApiBase()}/notifications/stream`;
+    const make = opts.factory ?? defaultEventSourceFactory;
+    const source = make(url);
+    if (!source) {
+        // No EventSource available (SSR? JSDOM without polyfill? Or the
+        // injected factory deliberately returns null in tests). Return a
+        // no-op handle so callers can compose without conditional logic.
+        return { close: () => { } };
+    }
+    let closed = false;
+    const onReady = (event) => {
+        if (!opts.onReady)
+            return;
+        const data = parseEventData(event);
+        if (data && typeof data.userId === 'string') {
+            opts.onReady({ userId: data.userId });
+        }
+    };
+    const onNotification = (event) => {
+        const data = parseEventData(event);
+        if (data && isNotification(data)) {
+            opts.onNotification(data);
+        }
+    };
+    const onError = (event) => {
+        opts.onError?.(event);
+    };
+    source.addEventListener('ready', onReady);
+    source.addEventListener('notification', onNotification);
+    source.addEventListener('error', onError);
+    return {
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            source.removeEventListener?.('ready', onReady);
+            source.removeEventListener?.('notification', onNotification);
+            source.removeEventListener?.('error', onError);
+            source.close();
+        },
+    };
+}
+function defaultEventSourceFactory(url) {
+    if (typeof EventSource === 'undefined')
+        return null;
+    // `withCredentials: true` so the admin session cookie travels with
+    // the connection upgrade — every notification stream requires auth
+    // and the same-origin cookie is the only credential we trust here.
+    return new EventSource(url, { withCredentials: true });
+}
+function parseEventData(event) {
+    // EventSource emits MessageEvents with `data: string`. Plain
+    // `Event` (e.g. the `error` event) has no payload; ignore.
+    const data = event.data;
+    if (typeof data !== 'string')
+        return null;
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+function isNotification(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    // Defensive: don't trust the wire blindly — verify the discriminant
+    // properties our consumers will read. A drift in the server-side
+    // wire format must surface as "missing fields" in the test suite,
+    // not as runtime errors deep in the bell's render path.
+    return (typeof v.id === 'string' &&
+        typeof v.userId === 'string' &&
+        typeof v.createdAt === 'string' &&
+        !!v.payload &&
+        typeof v.payload.kind === 'string');
+}
 /**
  * Cheap single-line summary for the bell list — the server gives us a
  * structured payload, but the dropdown wants one human-readable string

package/dist/lib/notifications-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"notifications-client.js","sourceRoot":"","sources":["../../src/lib/notifications-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"notifications-client.js","sourceRoot":"","sources":["../../src/lib/notifications-client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actuate-media/cms-admin",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/actuate-media/actuatecms.git",
@@ -87,7 +87,7 @@
     "tailwindcss": "^4.0.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@actuate-media/cms-core": "0.22.0",
+    "@actuate-media/cms-core": "0.25.0",
     "@actuate-media/component-blocks": "0.2.0"
   },
   "scripts": {

package/src/__tests__/components/comment-side-panel.test.tsx

@@ -341,3 +341,137 @@ describe('CommentSidePanel — reply, edit, resolve, delete', () => {
     expect(onActive).toHaveBeenCalledWith('c1')
   })
 })
+
+// ---------------------------------------------------------------------------
+// Mention picker integration — Phase 7 carry-over
+// ---------------------------------------------------------------------------
+
+describe('CommentSidePanel — mention picker integration', () => {
+  /**
+   * Drive a `<textarea>` the same way the picker test does. The
+   * comment panel's three composer surfaces (new thread, reply,
+   * edit) are all `<MentionableTextarea>` now, so this helper works
+   * uniformly across them.
+   */
+  async function typeAt(el: HTMLTextAreaElement, value: string, caret = value.length) {
+    await act(async () => {
+      el.focus()
+      const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set
+      if (setter) setter.call(el, value)
+      else el.value = value
+      el.setSelectionRange(caret, caret)
+      el.dispatchEvent(new Event('input', { bubbles: true }))
+    })
+  }
+
+  function fakeMentionSearch() {
+    return vi.fn(async (q: string) => {
+      const all = [
+        { id: 'u_alice', name: 'Alice Anderson', email: 'alice@example.com' },
+        { id: 'u_bob', name: 'Bob Brown', email: 'bob@example.com' },
+      ]
+      const ql = q.toLowerCase()
+      return all.filter(
+        (u) => u.name.toLowerCase().includes(ql) || u.email.toLowerCase().includes(ql),
+      )
+    })
+  }
+
+  it('opens the mention picker from the new-thread composer and submits @<userId>', async () => {
+    const fake = createFakeApi()
+    const mentionSearch = fakeMentionSearch()
+    render(
+      <CommentSidePanel
+        documentId="doc-1"
+        currentUserId="current"
+        api={fake.api}
+        mentionSearch={mentionSearch}
+      />,
+    )
+    await waitFor(() => expect(screen.getByText('No comments yet.')).toBeTruthy())
+
+    const composer = screen.getByTestId('comment-composer') as HTMLTextAreaElement
+    await typeAt(composer, '@ali')
+    await waitFor(() => expect(screen.getByTestId('comment-composer-picker')).toBeTruthy())
+    await act(async () => {
+      fireEvent.mouseDown(screen.getByTestId('comment-composer-picker-row-u_alice'))
+    })
+    expect((composer as HTMLTextAreaElement).value).toBe('@u_alice ')
+
+    // Continue typing then submit — the resulting comment body must
+    // carry the `@<userId>` token so `extractMentionedUserIds` picks
+    // it up server-side.
+    await typeAt(composer, '@u_alice please review')
+    await act(async () => {
+      fireEvent.click(screen.getByTestId('comment-submit'))
+    })
+    expect(fake.api.create).toHaveBeenCalledWith(
+      expect.objectContaining({ body: '@u_alice please review' }),
+    )
+  })
+
+  it('opens the mention picker from a reply input and inserts @<userId>', async () => {
+    const fake = createFakeApi()
+    fake.rows.push(comment({ id: 'root', body: 'root' }))
+    const mentionSearch = fakeMentionSearch()
+    render(
+      <CommentSidePanel
+        documentId="doc-1"
+        currentUserId="current"
+        api={fake.api}
+        mentionSearch={mentionSearch}
+      />,
+    )
+    await waitFor(() => expect(screen.getByTestId('comment-thread-root')).toBeTruthy())
+
+    const reply = screen.getByTestId('reply-input-root') as HTMLTextAreaElement
+    await typeAt(reply, '@bo')
+    await waitFor(() => expect(screen.getByTestId('reply-input-root-picker')).toBeTruthy())
+    fireEvent.keyDown(reply, { key: 'Enter' })
+    await waitFor(() => expect(reply.value).toBe('@u_bob '))
+  })
+
+  it('opens the mention picker from the edit-textarea while editing a comment', async () => {
+    const fake = createFakeApi()
+    fake.rows.push(comment({ id: 'c1', userId: 'current', body: 'before' }))
+    const mentionSearch = fakeMentionSearch()
+    render(
+      <CommentSidePanel
+        documentId="doc-1"
+        currentUserId="current"
+        api={fake.api}
+        mentionSearch={mentionSearch}
+      />,
+    )
+    await waitFor(() => expect(screen.getByTestId('comment-thread-c1')).toBeTruthy())
+    fireEvent.click(screen.getByTestId('edit-c1'))
+    const edit = screen.getByTestId('edit-textarea-c1') as HTMLTextAreaElement
+    await typeAt(edit, '@al')
+    await waitFor(() => expect(screen.getByTestId('edit-textarea-c1-picker')).toBeTruthy())
+    await act(async () => {
+      fireEvent.mouseDown(screen.getByTestId('edit-textarea-c1-picker-row-u_alice'))
+    })
+    expect(edit.value).toBe('@u_alice ')
+  })
+
+  it('escape closes the picker without committing a selection', async () => {
+    const fake = createFakeApi()
+    const mentionSearch = fakeMentionSearch()
+    render(
+      <CommentSidePanel
+        documentId="doc-1"
+        currentUserId="current"
+        api={fake.api}
+        mentionSearch={mentionSearch}
+      />,
+    )
+    await waitFor(() => expect(screen.getByText('No comments yet.')).toBeTruthy())
+
+    const composer = screen.getByTestId('comment-composer') as HTMLTextAreaElement
+    await typeAt(composer, '@al')
+    await waitFor(() => expect(screen.getByTestId('comment-composer-picker')).toBeTruthy())
+    fireEvent.keyDown(composer, { key: 'Escape' })
+    expect(screen.queryByTestId('comment-composer-picker')).toBeNull()
+    expect((composer as HTMLTextAreaElement).value).toBe('@al')
+  })
+})