@startsimpli/ui 0.4.143 → 0.4.145

package/src/components/track-changes/useTrackChanges.ts

@@ -19,13 +19,17 @@
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
-import { blameNotice, normalizeBlame, normalizeSuggestions, normalizeThreads } from './normalize';
+import { blameNotice, normalizeBlame, normalizeRoster, normalizeSuggestions, normalizeThreads } from './normalize';
 import type {
+  AcceptResponseWire,
   BlameResponseWire,
   BlameSpan,
   CommentPageWire,
   CommentThread,
+  CommentRequest,
   CommentThreadWire,
+  RosterMember,
+  RosterPageWire,
   Suggestion,
   SuggestionPageWire,
   SuggestionWire,
@@ -65,8 +69,79 @@ export interface TrackChanges {
   /** Post the whole proposed text against `version`. Rejects on failure, so
    *  the editor keeps the proposal and says it was not sent. */
   propose: (proposed: string, baseVersion: number) => Promise<void>;
+  /** True when a read came back for a DIFFERENT version than the one loaded:
+   *  someone changed the record. Its offsets describe other text, so it is
+   *  not painted, and `notices` says so (never a silent empty list). */
+  stale: boolean;
+  /** Colleagues who may be @mentioned: the org roster, plus everyone already
+   *  on this field's trail (blame, suggestions, comments), deduped by `sub`.
+   *  The trail half is what keeps mentions working when the roster read is
+   *  unavailable. */
+  mentionable: RosterMember[];
+  /** Why the org roster could not be read (a viewer-role token gets central's
+   *  403 relayed), or null. Mentions still offer the people on the trail. */
+  rosterNotice: string | null;
+  /** The rail's writes. Each rejects with the server's sentence on failure and
+   *  re-reads all three sources on success. Absent when the client has not
+   *  bound the call. */
+  actions: TrackChangesActions;
 }
 
+export interface TrackChangesActions {
+  /** Resolves the accept answer: the RECORD at its new version. The host
+   *  must adopt it (text and version) before any other write. */
+  accept?: (ids: string[], expectedVersion: number) => Promise<AcceptResponseWire>;
+  reject?: (ids: string[], reason?: string) => Promise<void>;
+  withdraw?: (id: string) => Promise<void>;
+  comment?: (req: CommentRequest) => Promise<void>;
+  reply?: (threadId: string, body: string, mentions: string[]) => Promise<void>;
+  resolve?: (threadId: string) => Promise<void>;
+  reopen?: (threadId: string) => Promise<void>;
+}
+
+/** A failed write, with the server's own sentence when it gave one. */
+export class TrackChangesActionError extends Error {
+  readonly status?: number;
+  readonly reason?: string;
+  constructor(message: string, status?: number, reason?: string) {
+    super(message);
+    this.name = 'TrackChangesActionError';
+    this.status = status;
+    this.reason = reason;
+  }
+}
+
+const REASON_TEXT: Record<string, string> = {
+  conflicted: 'the text under this suggestion changed, so it no longer applies',
+  orphaned: 'the text this suggestion was made on is gone',
+  not_open: 'it was already accepted, rejected or withdrawn',
+  machine_actor: 'machine accounts cannot suggest or comment',
+  history_disabled: 'this record keeps no history, so it cannot carry suggestions or comments',
+  already_resolved: 'it is already resolved',
+  not_resolved: 'it is not resolved',
+  base_unknown: 'the text it was made on can no longer be rebuilt',
+};
+
+function actionError(what: string, err: unknown): TrackChangesActionError {
+  const code = statusCode(err);
+  const e = err as { body?: { reason?: unknown; detail?: unknown } } | null;
+  const reason = typeof e?.body?.reason === 'string' ? e.body.reason : undefined;
+  if (code === 412) {
+    return new TrackChangesActionError(
+      `Could not ${what}: someone changed this record since you loaded it. Reload, then try again.`,
+      code,
+      reason,
+    );
+  }
+  if (code === 403 && !reason) return new TrackChangesActionError(`You may not ${what} here.`, code);
+  const why = (reason && REASON_TEXT[reason]) || detail(err);
+  return new TrackChangesActionError(`Could not ${what}: ${why}.`, code, reason);
+}
+
+/** Roster pages read before giving up on more (a guard, not a limit anyone
+ *  should reach: central serves 100 per page). */
+const ROSTER_MAX_PAGES = 50;
+
 interface Loaded<T> {
   status: SourceStatus;
   data: T | null;
@@ -176,7 +251,8 @@ export function useTrackChanges({
     }
     load(c.blame, setBlame, 'who wrote each passage');
     load(c.listSuggestions && allPages(c.listSuggestions), setSugg, 'suggestions');
-    load(c.listComments && allPages(c.listComments), setComm, 'comments');
+    const lc = c.listComments;
+    load(lc && allPages((q) => lc({ ...q, status: 'all' })), setComm, 'comments');
     return () => {
       live = false;
     };
@@ -184,6 +260,45 @@ export function useTrackChanges({
 
   const reload = useCallback(() => setTick((t) => t + 1), []);
 
+  // The roster is the org's, not the field's: read once per client.
+  const [roster, setRoster] = useState<RosterMember[]>([]);
+  const [rosterNotice, setRosterNotice] = useState<string | null>(null);
+  const rosterFn = client.roster;
+  useEffect(() => {
+    if (!enabled || !rosterFn) return;
+    let live = true;
+    (async () => {
+      const pages: RosterPageWire[] = [];
+      let cursor: string | undefined;
+      const seen = new Set<string>();
+      for (let i = 0; i < ROSTER_MAX_PAGES; i++) {
+        const page = await rosterFn(cursor ? { cursor } : {});
+        pages.push(page);
+        const next = page?.next_cursor ?? page?.nextCursor ?? null;
+        if (!next || seen.has(next)) break;
+        seen.add(next);
+        cursor = next;
+      }
+      if (live) {
+        setRoster(normalizeRoster(pages));
+        setRosterNotice(null);
+      }
+    })().catch((err) => {
+      // Mentions fall back to the people on the trail; a roster that cannot be
+      // read is not a reason to stop anyone commenting, but it is said.
+      if (!live) return;
+      const code = statusCode(err);
+      setRosterNotice(
+        code === 403
+          ? 'Your account cannot read the colleague list, so you can only @mention people already on this draft.'
+          : 'The colleague list could not be loaded, so you can only @mention people already on this draft.',
+      );
+    });
+    return () => {
+      live = false;
+    };
+  }, [enabled, rosterFn]);
+
   const propose = useCallback(
     async (proposed: string, baseVersion: number) => {
       const fn = clientRef.current.propose;
@@ -209,6 +324,84 @@ export function useTrackChanges({
   );
   const unrecorded = blame.data ? blameNotice(blame.data) : null;
   if (unrecorded) notices.unshift(unrecorded);
+  const stale = [blame.data, sugg.data, comm.data].some((d) => d != null && !matches(d, version));
+  if (stale) {
+    notices.unshift(
+      'Someone changed this record since you opened it, so its suggestions and comments are not shown. Reload to see the latest.',
+    );
+  }
+
+  const mentionable = useMemo(() => {
+    const bySub = new Map<string, RosterMember>();
+    for (const m of roster) bySub.set(m.sub, m);
+    const add = (a: { sub: string; label: string; kind: string } | null | undefined) => {
+      if (!a || !a.sub || a.kind === 'machine' || bySub.has(a.sub)) return;
+      bySub.set(a.sub, { sub: a.sub, label: a.label });
+    };
+    for (const b of normalized.blame) add(b.author);
+    for (const s of normalized.suggestions) add(s.author);
+    for (const t of normalized.threads) for (const c of t.comments) add(c.author);
+    return [...bySub.values()].sort((a, b) => (a.label || a.sub).localeCompare(b.label || b.sub));
+  }, [roster, normalized]);
+
+  const actions = useMemo<TrackChangesActions>(() => {
+    const c = client;
+    const run = async <T,>(what: string, fn: () => Promise<T>): Promise<T> => {
+      let out: T;
+      try {
+        out = await fn();
+      } catch (err) {
+        throw actionError(what, err);
+      }
+      setTick((t) => t + 1);
+      return out;
+    };
+    const a: TrackChangesActions = {};
+    if (c.accept) {
+      const f = c.accept;
+      a.accept = (ids, expectedVersion) =>
+        run(ids.length > 1 ? 'accept these suggestions' : 'accept this suggestion', () => f({ ids, expectedVersion }));
+    }
+    if (c.reject) {
+      const f = c.reject;
+      a.reject = async (ids, reason) => {
+        await run(ids.length > 1 ? 'reject these suggestions' : 'reject this suggestion', () =>
+          f(reason ? { ids, reason } : { ids }),
+        );
+      };
+    }
+    if (c.withdraw) {
+      const f = c.withdraw;
+      a.withdraw = async (id) => {
+        await run('withdraw your suggestion', () => f(id));
+      };
+    }
+    if (c.comment) {
+      const f = c.comment;
+      a.comment = async (req) => {
+        await run('add the comment', () => f(req));
+      };
+    }
+    if (c.reply) {
+      const f = c.reply;
+      a.reply = async (threadId, body, mentions) => {
+        await run('reply', () => f(threadId, mentions.length ? { body, mentions } : { body }));
+      };
+    }
+    if (c.resolveThread) {
+      const f = c.resolveThread;
+      a.resolve = async (id) => {
+        await run('resolve the thread', () => f(id));
+      };
+    }
+    if (c.reopenThread) {
+      const f = c.reopenThread;
+      a.reopen = async (id) => {
+        await run('reopen the thread', () => f(id));
+      };
+    }
+    return a;
+  }, [client]);
 
-  return { ...normalized, status, notices, reload, propose };
+  return { ...normalized, status, notices, reload, propose, stale, mentionable, rosterNotice, actions };
 }