@startsimpli/ui 0.4.141 → 0.4.143

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

@@ -0,0 +1,74 @@
+/**
+ * @startsimpli/ui/track-changes — the track-changes editor surface
+ * (bd startsim-sjuai; design startsim-xyn25; epic startsim-whwxd).
+ *
+ * A SEPARATE SUBPATH ON PURPOSE, and never re-exported from the root barrel:
+ * it imports CodeMirror, which is an OPTIONAL peer dependency. An app that
+ * never mounts the editor must not need CodeMirror installed, and one that
+ * does should load it with a dynamic import on the page that edits.
+ *
+ * Install in the consuming app:
+ *   @codemirror/state @codemirror/view @codemirror/commands
+ *   @codemirror/language @codemirror/lang-markdown
+ *
+ * Wiring, in the host:
+ *
+ * ```tsx
+ * const tc = useTrackChanges({ client, field: 'blog', value, version });
+ * <TrackedTextEditor
+ *   label="Blog (markdown)" value={value} version={version}
+ *   currentActorSub={me.sub} canEdit={canEdit}
+ *   blame={tc.blame} suggestions={tc.suggestions} threads={tc.threads}
+ *   notices={tc.notices} onPropose={tc.propose}
+ *   onChange={save}            // editing mode only; never called while suggesting
+ * />
+ * ```
+ */
+export { TrackedTextEditor } from './TrackedTextEditor';
+export type { TrackMode, TrackedTextEditorHandle, TrackedTextEditorProps } from './TrackedTextEditor';
+
+export { useTrackChanges } from './useTrackChanges';
+export type { SourceState, SourceStatus, TrackChanges, UseTrackChangesOptions } from './useTrackChanges';
+
+export {
+  DEFAULT_KEYS,
+  LINE_SEPARATOR,
+  activeMarkOf,
+  computeMarks,
+  enterSuggesting,
+  focusMark,
+  isAuthorship,
+  isChangeOrComment,
+  isSuggesting,
+  leaveSuggesting,
+  marksOf,
+  moveToMark,
+  ownSuggestions,
+  proposedText,
+  rebaseOnto,
+  selectionAnchorOf,
+  setAnnotations,
+  trackChanges,
+  trackingOf,
+} from './extension';
+export type { AnnotationsInput, MarkKind, MarkVisibility, TrackKeys, TrackMark, Tracking } from './extension';
+
+export {
+  ANCHOR_CONTEXT,
+  anchorFor,
+  blameNotice,
+  BLAME_REASON_TEXT,
+  codePointToUtf16,
+  normalizeActor,
+  normalizeBlame,
+  normalizeSuggestions,
+  normalizeThreads,
+  toServerOffsets,
+  utf16ToCodePoint,
+} from './normalize';
+
+export { describeBlame, describeSuggestion, describeThread } from './describe';
+export { applyTextChanges, tokenize, wordChanges } from './word-diff';
+export type { TextChange } from './word-diff';
+
+export type * from './types';

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

@@ -0,0 +1,364 @@
+/**
+ * Wire → editor shapes for the track-changes surface (bd startsim-sjuai).
+ *
+ * Three jobs, each the kind of thing that fails silently if done per caller:
+ *
+ * 1. READ BOTH SPELLINGS. The shared API client camelCases every response key,
+ *    so `actor_kind` may arrive as `actorKind` (see history/types.ts).
+ * 2. CONVERT OFFSETS. The server counts code points, the editor counts UTF-16
+ *    code units (see types.ts). Converted here, once, against the text the
+ *    offsets describe.
+ * 3. NEVER PAINT A GUESS. An anchor whose quote does not match the text at its
+ *    converted offsets is reported `orphaned`, and a span outside the text is
+ *    clipped or dropped. Painting a comment on the wrong words is worse than
+ *    listing it as orphaned, which is what the design asks for anyway.
+ */
+import type { ActorKind, ActorKindSource } from '../ActorIdentity';
+import type {
+  AnchorState,
+  AnchorWire,
+  BlameReason,
+  BlameResponseWire,
+  BlameSpan,
+  BlameSpanWire,
+  BlameVia,
+  CommentPageWire,
+  CommentThread,
+  CommentThreadWire,
+  OffsetUnit,
+  SelectionAnchor,
+  Suggestion,
+  SuggestionPageWire,
+  SuggestionStatus,
+  SuggestionWire,
+  PositionWire,
+  TrackActor,
+  WireActor,
+  WireAuthor,
+} from './types';
+
+/* -------------------------------------------------------------------------- */
+/*  Offsets                                                                   */
+/* -------------------------------------------------------------------------- */
+
+const ASTRAL = /[\uD800-\uDBFF][\uDC00-\uDFFF]/;
+
+/** UTF-16 offset of the `cp`-th code point of `text`. Clamped to the text. */
+export function codePointToUtf16(text: string, cp: number): number {
+  if (!(cp > 0)) return 0;
+  if (!ASTRAL.test(text)) return Math.min(cp, text.length);
+  let units = 0;
+  let points = 0;
+  while (units < text.length && points < cp) {
+    const c = text.charCodeAt(units);
+    units += c >= 0xd800 && c <= 0xdbff && units + 1 < text.length ? 2 : 1;
+    points++;
+  }
+  return units;
+}
+
+/** Code-point offset of UTF-16 offset `u` in `text`. */
+export function utf16ToCodePoint(text: string, u: number): number {
+  if (!(u > 0)) return 0;
+  const end = Math.min(u, text.length);
+  if (!ASTRAL.test(text)) return end;
+  return Array.from(text.slice(0, end)).length;
+}
+
+/** An editor range in the server's unit, for posting an anchor. */
+export function toServerOffsets(
+  text: string,
+  range: { from: number; to: number },
+  unit: OffsetUnit = 'code_point',
+): { from: number; to: number } {
+  if (unit === 'utf16') return { from: range.from, to: range.to };
+  return { from: utf16ToCodePoint(text, range.from), to: utf16ToCodePoint(text, range.to) };
+}
+
+/** The design's anchor (section c): the range, its text, and 32 characters of
+ *  context each side for the server's quote fallback. UTF-16 offsets. */
+export const ANCHOR_CONTEXT = 32;
+
+export function anchorFor(text: string, a: number, b: number): SelectionAnchor {
+  const from = Math.max(0, Math.min(a, b, text.length));
+  const to = Math.min(text.length, Math.max(a, b, 0));
+  return {
+    from,
+    to,
+    quote: text.slice(from, to),
+    prefix: text.slice(Math.max(0, from - ANCHOR_CONTEXT), from),
+    suffix: text.slice(to, to + ANCHOR_CONTEXT),
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Actors                                                                    */
+/* -------------------------------------------------------------------------- */
+
+const str = (v: unknown): string => (typeof v === 'string' ? v : '');
+
+function kindOf(v: unknown): ActorKind {
+  return v === 'person' || v === 'machine' ? v : 'unknown';
+}
+
+function kindSourceOf(v: unknown): ActorKindSource | undefined {
+  return v === 'claim' || v === 'inferred' ? v : undefined;
+}
+
+function isNested(w: object): w is WireAuthor {
+  return 'sub' in w || 'label' in w || 'kind' in w;
+}
+
+/** Reads flat actor columns (`actor_label`), a nested author object
+ *  (`{sub, label, kind, kind_source}`), or a bare label. */
+export function normalizeActor(w: WireActor | WireAuthor | string | null | undefined): TrackActor {
+  if (typeof w === 'string') return { sub: '', label: w, kind: 'unknown' };
+  if (w && isNested(w)) {
+    return {
+      sub: str(w.sub),
+      label: str(w.label).trim(),
+      kind: kindOf(w.kind),
+      kindSource: kindSourceOf(w.kind_source ?? w.kindSource),
+    };
+  }
+  w = w as WireActor | null | undefined;
+  return {
+    sub: str(w?.actor_sub ?? w?.actorSub),
+    label: str(w?.actor_label ?? w?.actorLabel).trim(),
+    kind: kindOf(w?.actor_kind ?? w?.actorKind),
+    kindSource: kindSourceOf(w?.actor_kind_source ?? w?.actorKindSource),
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Ranges                                                                    */
+/* -------------------------------------------------------------------------- */
+
+function unitOf(w: { offset_unit?: OffsetUnit | null; offsetUnit?: OffsetUnit | null } | null | undefined): OffsetUnit {
+  return (w?.offset_unit ?? w?.offsetUnit) === 'utf16' ? 'utf16' : 'code_point';
+}
+
+function convert(text: string, n: number, unit: OffsetUnit): number {
+  if (unit === 'utf16') return Math.max(0, Math.min(Math.trunc(n), text.length));
+  return codePointToUtf16(text, Math.trunc(n));
+}
+
+function isNum(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v);
+}
+
+const ANCHOR_STATES: AnchorState[] = ['mapped', 'reanchored', 'orphaned'];
+
+function anchorStateOf(v: unknown): AnchorState {
+  return ANCHOR_STATES.includes(v as AnchorState) ? (v as AnchorState) : 'mapped';
+}
+
+/** Resolve an anchor to UTF-16 offsets in `text`, or report it orphaned. */
+function resolveAnchor(
+  text: string,
+  anchor: AnchorWire | null | undefined,
+  declared: AnchorState,
+  unit: OffsetUnit,
+): { from: number | null; to: number | null; quote: string; state: AnchorState } {
+  const quote = str(anchor?.quote);
+  if (!anchor || declared === 'orphaned' || !isNum(anchor.from) || !isNum(anchor.to)) {
+    return { from: null, to: null, quote, state: anchor ? 'orphaned' : declared };
+  }
+  const from = convert(text, anchor.from, unit);
+  const to = convert(text, anchor.to, unit);
+  // An anchor is never clamped: past the end means it describes other text.
+  const max = unit === 'utf16' ? text.length : utf16ToCodePoint(text, text.length);
+  if (anchor.from < 0 || anchor.to < anchor.from || anchor.to > max) {
+    return { from: null, to: null, quote, state: 'orphaned' };
+  }
+  // A quote that does not match is a disagreement about the text, so the
+  // offsets mean nothing. `quote` absent (null) is not checked: a server that
+  // withheld it under the field gate still placed the range.
+  if (anchor.quote != null && text.slice(from, to) !== quote) {
+    return { from: null, to: null, quote, state: 'orphaned' };
+  }
+  // A pure insert has no quote, so the check above passes for ANY offset. Its
+  // neighbours are checked instead: the nearest INSERT_CONTEXT characters of
+  // prefix and suffix. Only when BOTH sides disagree is it orphaned, because
+  // an edit a few words away legitimately changes one side's wider context
+  // while the server still (correctly) reports the insert point as mapped.
+  if (from === to && !contextFits(text, from, anchor.prefix, anchor.suffix)) {
+    return { from: null, to: null, quote, state: 'orphaned' };
+  }
+  return { from, to, quote: anchor.quote != null ? quote : text.slice(from, to), state: declared };
+}
+
+const INSERT_CONTEXT = 8;
+
+function contextFits(text: string, at: number, prefix?: string | null, suffix?: string | null): boolean {
+  const before = prefix ? prefix.slice(-INSERT_CONTEXT) : '';
+  const after = suffix ? suffix.slice(0, INSERT_CONTEXT) : '';
+  if (!before && !after) return true; // nothing to check against (start of an empty field)
+  const beforeOk = !!before && text.slice(Math.max(0, at - before.length), at) === before;
+  const afterOk = !!after && text.slice(at, at + after.length) === after;
+  return beforeOk || afterOk;
+}
+
+/** The anchor to place and its declared state: `position` (the contract)
+ *  first, then the older spellings. A position's quote is the anchor's. */
+function placement(
+  w: {
+    position?: PositionWire | null;
+    mapped_anchor?: AnchorWire | null;
+    mappedAnchor?: AnchorWire | null;
+    current?: AnchorWire | null;
+    anchor?: AnchorWire | null;
+    anchor_status?: string | null;
+    anchorStatus?: string | null;
+  },
+): { anchor: AnchorWire | null | undefined; state: AnchorState } {
+  const pos = w.position;
+  // An explicit null: the server placed nothing (a suggestion that is no
+  // longer open, or a record/field comment). Not placed, and not orphaned.
+  if (pos === null) return { anchor: null, state: 'mapped' };
+  if (pos) {
+    const state = anchorStateOf(pos.state);
+    if (!isNum(pos.from) || !isNum(pos.to)) {
+      return { anchor: { from: NaN, to: NaN, quote: w.anchor?.quote ?? null }, state: 'orphaned' };
+    }
+    return {
+      anchor: { from: pos.from, to: pos.to, quote: w.anchor?.quote ?? null, prefix: w.anchor?.prefix, suffix: w.anchor?.suffix },
+      state,
+    };
+  }
+  return {
+    anchor: w.mapped_anchor ?? w.mappedAnchor ?? w.current ?? w.anchor,
+    state: anchorStateOf(w.anchor_status ?? w.anchorStatus),
+  };
+}
+
+function results<T>(w: { results?: T[] | null } | T[] | null | undefined): T[] {
+  if (Array.isArray(w)) return w;
+  return w?.results ?? [];
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Blame                                                                     */
+/* -------------------------------------------------------------------------- */
+
+const VIAS: BlameVia[] = ['edit', 'accepted_suggestion', 'restore', 'unknown'];
+
+/** What each reason code means, for when the server sends no `detail`. */
+export const BLAME_REASON_TEXT: Record<BlameReason, string> = {
+  before_history: 'written before the history began',
+  truncated: 'a revision was too large to store in full',
+  values_omitted: 'a revision was too large to store its values',
+  chain_break: 'the history has a gap here',
+  unrecorded_change: 'changed without a recorded revision',
+};
+
+function reasonOf(v: unknown): BlameReason | null {
+  return typeof v === 'string' && v in BLAME_REASON_TEXT ? (v as BlameReason) : null;
+}
+
+export function normalizeBlame(w: BlameResponseWire | null | undefined, text: string): BlameSpan[] {
+  const unit = unitOf(w);
+  const out: BlameSpan[] = [];
+  for (const s of w?.spans ?? []) {
+    if (!isNum(s.from) || !isNum(s.to)) continue;
+    const from = convert(text, s.from, unit);
+    const to = convert(text, s.to, unit);
+    if (to <= from) continue;
+    const via = VIAS.includes(s.via as BlameVia) ? (s.via as BlameVia) : null;
+    const rawReason = str(s.reason).trim();
+    const actor = normalizeActor(s);
+    // Unknown when the server says so (via or a reason), or when there is no
+    // one to credit. Never an author invented from a partial row.
+    const unknown = via === 'unknown' || !!rawReason || !(actor.label || actor.sub);
+    const reason = reasonOf(rawReason);
+    const said =
+      str(s.detail).trim() ||
+      (reason ? BLAME_REASON_TEXT[reason] : rawReason) ||
+      'author not recorded';
+    const acceptedRaw = s.accepted_by ?? s.acceptedBy;
+    const restored = s.restored_from ?? s.restoredFrom;
+    out.push({
+      id: `blame:${from}`,
+      from,
+      to,
+      author: unknown ? null : actor,
+      unknownReason: unknown ? said : null,
+      reason: unknown ? reason : null,
+      version: isNum(s.version) ? s.version : null,
+      at: s.at ?? null,
+      via: unknown ? 'unknown' : via,
+      acceptedBy: !unknown && acceptedRaw ? normalizeActor(acceptedRaw) : null,
+      restoredFrom: isNum(restored) ? restored : null,
+    });
+  }
+  return out.sort((a, b) => a.from - b.from);
+}
+
+/** A sentence when the field's authorship is not recorded at all (history
+ *  off on the type: `recorded: false`, `spans: null`), else null. */
+export function blameNotice(w: BlameResponseWire | null | undefined): string | null {
+  if (!w || (w.recorded !== false && w.spans !== null)) return null;
+  const why = str(w.detail).trim();
+  return `Who wrote each passage is not recorded${why ? `: ${why}` : '.'}`;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Suggestions                                                               */
+/* -------------------------------------------------------------------------- */
+
+const STATUSES: SuggestionStatus[] = ['open', 'accepted', 'rejected', 'withdrawn', 'superseded'];
+
+export function normalizeSuggestions(
+  w: SuggestionPageWire | SuggestionWire[] | null | undefined,
+  text: string,
+): Suggestion[] {
+  const unit = Array.isArray(w) ? 'code_point' : unitOf(w);
+  return results(w).map((s) => {
+    const { anchor, state } = placement(s);
+    const r = resolveAnchor(text, anchor, state, unit);
+    const status = STATUSES.includes(s.status as SuggestionStatus) ? (s.status as SuggestionStatus) : 'open';
+    return {
+      id: String(s.id),
+      setId: (s.set_id ?? s.setId ?? null) as string | null,
+      from: r.from ?? 0,
+      to: r.to ?? 0,
+      quote: r.quote,
+      replacement: str(s.replacement),
+      status,
+      anchorState: r.state,
+      author: normalizeActor(s.author ?? s),
+      createdAt: s.created_at ?? s.createdAt ?? null,
+    };
+  });
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Comments                                                                  */
+/* -------------------------------------------------------------------------- */
+
+export function normalizeThreads(
+  w: CommentPageWire | CommentThreadWire[] | null | undefined,
+  text: string,
+): CommentThread[] {
+  const unit = Array.isArray(w) ? 'code_point' : unitOf(w);
+  return results(w).map((t) => {
+    const { anchor, state } = placement(t);
+    const r = resolveAnchor(text, anchor, state, unit);
+    return {
+      id: String(t.thread_id ?? t.threadId ?? t.id ?? ''),
+      from: r.from,
+      to: r.to,
+      quote: r.quote,
+      anchorState: r.state,
+      resolved: t.status === 'resolved' || Boolean(t.resolved),
+      redacted: Boolean(t.redacted),
+      comments: (t.comments ?? []).map((c) => ({
+        id: String(c.id),
+        body: c.deleted ? null : (c.body ?? null),
+        deleted: Boolean(c.deleted),
+        author: normalizeActor(c.author ?? c),
+        createdAt: c.created_at ?? c.createdAt ?? null,
+      })),
+    };
+  });
+}