@startsimpli/ui 0.4.142 → 0.4.144

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

@@ -0,0 +1,407 @@
+'use client';
+
+/**
+ * useTrackChanges — the ONE owner of the injected client for a tracked field
+ * (bd startsim-sjuai).
+ *
+ * It reads blame, suggestions and comments for one field at one version,
+ * normalizes them against the stored text (UTF-16 offsets, both spellings),
+ * and posts suggesting-mode proposals. The editor is presentational over its
+ * result, and the changes rail (startsim-whwxd.3) reads the SAME result, so
+ * the rail and the editor can never show two different sets of suggestions or
+ * fetch them twice.
+ *
+ * HONEST STATES. A read that fails is not an empty list: it lands in `notices`
+ * as a sentence the host shows. A 404 means the reader may not see this
+ * record or field (the routes are nested under the record's gate). A response
+ * for a version other than the one loaded is held back rather than painted,
+ * because its offsets describe different text.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { blameNotice, normalizeBlame, normalizeRoster, normalizeSuggestions, normalizeThreads } from './normalize';
+import type {
+  AcceptResponseWire,
+  BlameResponseWire,
+  BlameSpan,
+  CommentPageWire,
+  CommentThread,
+  CommentRequest,
+  CommentThreadWire,
+  RosterMember,
+  RosterPageWire,
+  Suggestion,
+  SuggestionPageWire,
+  SuggestionWire,
+  TrackChangesClient,
+} from './types';
+
+export type SourceState = 'off' | 'loading' | 'ready' | 'error';
+
+export interface SourceStatus {
+  state: SourceState;
+  /** A sentence for the reader when `state` is `error`. */
+  message?: string;
+}
+
+export interface UseTrackChangesOptions {
+  client: TrackChangesClient;
+  /** The record's field, as declared (`blog`, `linkedin`). */
+  field: string;
+  /** The stored value at `version`: the text every offset refers to. */
+  value: string;
+  /** The record version `value` was read at; `null` before the record has
+   *  one (then nothing is read and nothing can be proposed). */
+  version: number | null;
+  /** Off: read nothing (e.g. while the record is loading). Default on. */
+  enabled?: boolean;
+}
+
+export interface TrackChanges {
+  blame: BlameSpan[];
+  suggestions: Suggestion[];
+  threads: CommentThread[];
+  status: { blame: SourceStatus; suggestions: SourceStatus; comments: SourceStatus };
+  /** One sentence per source that could not be read. Never empty-by-failure. */
+  notices: string[];
+  /** Re-read all three (after an accept, a reply, a resolve). */
+  reload: () => void;
+  /** 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;
+}
+
+const OFF: Loaded<never> = { status: { state: 'off' }, data: null };
+
+function statusCode(err: unknown): number | undefined {
+  const e = err as { status?: unknown; response?: { status?: unknown } } | null;
+  const s = e?.status ?? e?.response?.status;
+  return typeof s === 'number' ? s : undefined;
+}
+
+function detail(err: unknown): string {
+  const e = err as { body?: { detail?: unknown }; data?: { detail?: unknown }; message?: unknown } | null;
+  const d = e?.body?.detail ?? e?.data?.detail ?? e?.message;
+  return typeof d === 'string' && d.trim() ? d.trim() : 'the server did not say why';
+}
+
+function failure(what: string, err: unknown): SourceStatus {
+  // 404: the record is unreadable. 403: the field is withheld from this
+  // reader (the contract refuses narrowing to a withheld field).
+  const code = statusCode(err);
+  if (code === 404 || code === 403) {
+    return { state: 'error', message: `You cannot see ${what} for this field.` };
+  }
+  return { state: 'error', message: `Could not load ${what}: ${detail(err)}.` };
+}
+
+function versionOf(w: unknown): number | null {
+  if (!w || Array.isArray(w) || typeof w !== 'object') return null;
+  const v = (w as { version?: unknown }).version;
+  return typeof v === 'number' ? v : null;
+}
+
+/** A response is used only if it describes the loaded version (or says
+ *  nothing about versions at all). */
+function matches(w: unknown, version: number | null): boolean {
+  const v = versionOf(w);
+  return v == null || v === version;
+}
+
+type Paged<T> = { results?: T[] | null; next_cursor?: string | null; nextCursor?: string | null } | T[];
+
+/** Read every page, following `next_cursor`, into one page. Stops if the
+ *  server hands back a cursor it already gave (a loop, not more data). */
+function allPages<T, P extends Paged<T>>(
+  fn: (q: { field: string; cursor?: string }) => Promise<P>,
+): (q: { field: string }) => Promise<P> {
+  return async ({ field }) => {
+    const first = await fn({ field });
+    if (Array.isArray(first)) return first;
+    const all: T[] = [...(first.results ?? [])];
+    const seen = new Set<string>();
+    let cursor = first.next_cursor ?? first.nextCursor ?? null;
+    while (cursor && !seen.has(cursor)) {
+      seen.add(cursor);
+      const page = await fn({ field, cursor });
+      if (Array.isArray(page)) {
+        all.push(...(page as T[]));
+        break;
+      }
+      all.push(...(page.results ?? []));
+      cursor = page.next_cursor ?? page.nextCursor ?? null;
+    }
+    return { ...first, results: all, next_cursor: null, nextCursor: null };
+  };
+}
+
+export function useTrackChanges({
+  client,
+  field,
+  value,
+  version,
+  enabled = true,
+}: UseTrackChangesOptions): TrackChanges {
+  const [blame, setBlame] = useState<Loaded<BlameResponseWire>>(OFF);
+  const [sugg, setSugg] = useState<Loaded<SuggestionPageWire | SuggestionWire[]>>(OFF);
+  const [comm, setComm] = useState<Loaded<CommentPageWire | CommentThreadWire[]>>(OFF);
+  const [tick, setTick] = useState(0);
+  const clientRef = useRef(client);
+  clientRef.current = client;
+
+  useEffect(() => {
+    if (!enabled || version == null) {
+      setBlame(OFF);
+      setSugg(OFF);
+      setComm(OFF);
+      return;
+    }
+    let live = true;
+    const c = clientRef.current;
+    function load<T>(
+      fn: ((q: { field: string }) => Promise<T>) | undefined,
+      set: (l: Loaded<T>) => void,
+      what: string,
+    ) {
+      if (!fn) {
+        set(OFF);
+        return;
+      }
+      set({ status: { state: 'loading' }, data: null });
+      fn({ field }).then(
+        (data) => live && set({ status: { state: 'ready' }, data }),
+        (err) => live && set({ status: failure(what, err), data: null }),
+      );
+    }
+    load(c.blame, setBlame, 'who wrote each passage');
+    load(c.listSuggestions && allPages(c.listSuggestions), setSugg, 'suggestions');
+    const lc = c.listComments;
+    load(lc && allPages((q) => lc({ ...q, status: 'all' })), setComm, 'comments');
+    return () => {
+      live = false;
+    };
+  }, [enabled, field, version, tick]);
+
+  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;
+      if (!fn) throw new Error('This host cannot post suggestions.');
+      await fn({ field, base_version: baseVersion, proposed });
+      setTick((t) => t + 1);
+    },
+    [field],
+  );
+
+  const normalized = useMemo(
+    () => ({
+      blame: blame.data && matches(blame.data, version) ? normalizeBlame(blame.data, value) : [],
+      suggestions: sugg.data && matches(sugg.data, version) ? normalizeSuggestions(sugg.data, value) : [],
+      threads: comm.data && matches(comm.data, version) ? normalizeThreads(comm.data, value) : [],
+    }),
+    [blame.data, sugg.data, comm.data, value, version],
+  );
+
+  const status = { blame: blame.status, suggestions: sugg.status, comments: comm.status };
+  const notices = [status.blame, status.suggestions, status.comments].flatMap((s) =>
+    s.state === 'error' && s.message ? [s.message] : [],
+  );
+  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, stale, mentionable, rosterNotice, actions };
+}

package/src/components/track-changes/word-diff.ts

@@ -0,0 +1,97 @@
+/**
+ * The smallest word-sized change from one value of a field to another, as
+ * editor change specs (bd startsim-sjuai).
+ *
+ * WHAT THIS IS FOR, AND WHAT IT IS NOT. The editor uses it in exactly one
+ * place: when the stored value changes underneath it (an accept, another
+ * reviewer's save), it applies the difference as a CHANGE rather than
+ * replacing the document, so every decoration and the cursor map through it
+ * instead of collapsing to the start. It is NOT the diff that decides span
+ * boundaries for blame, anchors or suggestion hunks: that is the shared
+ * server module (startsim-whwxd.1), and the editor always paints the server's
+ * offsets. A disagreement here can only make a mapped mark land a few
+ * characters differently until the next read, never paint wrong authorship.
+ *
+ * REUSES `diffLines` from history/text-diff (rule #1): that LCS takes any
+ * `string[]`, so handing it word tokens instead of lines makes it word-level.
+ * The text the live drafts carry (design startsim-xyn25 section 0) is one
+ * ~500-character line per paragraph, which is why a line diff is not enough.
+ */
+import { diffLines } from '../history/text-diff';
+
+export interface TextChange {
+  from: number;
+  to: number;
+  insert: string;
+}
+
+/** Han, Hiragana and Katakana have no spaces between words, so each character
+ *  is its own token; otherwise a whole CJK sentence would be one "word". */
+const TOKEN =
+  /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]|[\p{L}\p{N}\p{M}_]+|\s+|[^\s\p{L}\p{N}\p{M}_]/gu;
+
+export function tokenize(text: string): string[] {
+  return text.match(TOKEN) ?? [];
+}
+
+/** Above this many DP cells (tokens x tokens) the middle is replaced whole.
+ *  A 4 KB blog is ~1,300 tokens, so a whole-text rewrite is ~1.7M cells. */
+const MAX_CELLS = 4_000_000;
+
+const isHigh = (c: number) => c >= 0xd800 && c <= 0xdbff;
+const isLow = (c: number) => c >= 0xdc00 && c <= 0xdfff;
+
+/** Changes in `a`'s coordinates, sorted and non-overlapping, that turn `a`
+ *  into `b`. Empty when they are equal. */
+export function wordChanges(a: string, b: string): TextChange[] {
+  if (a === b) return [];
+  const max = Math.min(a.length, b.length);
+  let p = 0;
+  while (p < max && a.charCodeAt(p) === b.charCodeAt(p)) p++;
+  // Never split a surrogate pair.
+  if (p > 0 && isHigh(a.charCodeAt(p - 1))) p--;
+  let s = 0;
+  while (s < max - p && a.charCodeAt(a.length - 1 - s) === b.charCodeAt(b.length - 1 - s)) s++;
+  if (s > 0 && isLow(a.charCodeAt(a.length - s))) s--;
+
+  const midA = a.slice(p, a.length - s);
+  const midB = b.slice(p, b.length - s);
+  const tA = tokenize(midA);
+  const tB = tokenize(midB);
+  // tokenize covers every character (the last class matches anything that is
+  // not whitespace, a letter, a number or a mark), so tokens re-join exactly.
+  if (tA.join('') !== midA || tB.join('') !== midB || tA.length * tB.length > MAX_CELLS) {
+    return [{ from: p, to: a.length - s, insert: midB }];
+  }
+
+  const out: TextChange[] = [];
+  let pos = p;
+  let pending: TextChange | null = null;
+  for (const op of diffLines(tA, tB)) {
+    if (op.type === 'eq') {
+      if (pending) out.push(pending);
+      pending = null;
+      pos += op.line.length;
+    } else if (op.type === 'del') {
+      pending = pending ?? { from: pos, to: pos, insert: '' };
+      pending.to += op.line.length;
+      pos += op.line.length;
+    } else {
+      pending = pending ?? { from: pos, to: pos, insert: '' };
+      pending.insert += op.line;
+    }
+  }
+  if (pending) out.push(pending);
+  return out;
+}
+
+/** Apply sorted, non-overlapping changes expressed in `text`'s coordinates. */
+export function applyTextChanges(text: string, changes: TextChange[]): string {
+  let out = '';
+  let last = 0;
+  for (const c of changes) {
+    out += text.slice(last, c.from) + c.insert;
+    last = c.to;
+  }
+  return out + text.slice(last);
+}