@startsimpli/ui 0.4.142 → 0.4.144

package/src/components/track-changes/read-marks.ts

@@ -0,0 +1,262 @@
+/**
+ * Marks in the rendered Read view (bd startsim-whwxd.3; design startsim-xyn25
+ * section d): a rehype transform that wraps text runs by their SOURCE position.
+ *
+ * The markdown parser keeps, on every text node, the offsets of the source it
+ * came from. Server offsets are offsets into that same source string, so a
+ * suggestion, comment or authorship span can be drawn over the rendered prose
+ * exactly where it sits in the markdown.
+ *
+ * NEVER PAINT A GUESS. A text node's value is not always its source slice:
+ * `\_` renders `_`, `&` renders `&`. When the value is a subsequence of
+ * the slice (escapes, entities that decode to a character of their own
+ * spelling) the characters are aligned one by one. When it is not (`'`
+ * renders a quote that appears nowhere in its source), the node is left
+ * alone, and anything inside it is reported UNPLACED so the host says so
+ * instead of drawing it a few characters off.
+ *
+ * Every run the transform writes carries `data-src-from`, the source offset
+ * of its first character, so a DOM selection maps back to source offsets for
+ * "comment on selection".
+ */
+
+/* Minimal hast shapes: this file is the only reader, and keeping them local
+   avoids a dependency on @types/hast for one transform. */
+export interface HastPoint {
+  offset?: number;
+}
+export interface HastText {
+  type: 'text';
+  value: string;
+  position?: { start?: HastPoint; end?: HastPoint };
+}
+export interface HastElement {
+  type: 'element';
+  tagName: string;
+  properties?: Record<string, unknown>;
+  children: HastNode[];
+  position?: { start?: HastPoint; end?: HastPoint };
+}
+export interface HastRoot {
+  type: 'root';
+  children: HastNode[];
+}
+export type HastNode = HastText | HastElement | HastRoot | { type: string; [k: string]: unknown };
+
+export type ReadMarkKind = 'blame' | 'suggestion' | 'comment';
+
+/** One thing to draw, in SOURCE offsets (UTF-16, as JavaScript strings are). */
+export interface ReadMark {
+  id: string;
+  kind: ReadMarkKind;
+  from: number;
+  to: number;
+  /** The accessible sentence; becomes the title. */
+  title: string;
+  /** Suggestion: the text it would insert, drawn after the struck range. */
+  insert?: string;
+  /** Classes for the wrapper. */
+  className?: string;
+}
+
+/** Character-level map from a text node's value to source offsets, or null
+ *  when the value cannot be aligned to its source. */
+export function alignToSource(value: string, source: string, start: number, end: number): number[] | null {
+  if (!(start >= 0) || !(end >= start) || end > source.length) return null;
+  const slice = source.slice(start, end);
+  const map: number[] = new Array(value.length);
+  if (slice === value) {
+    for (let i = 0; i < value.length; i++) map[i] = start + i;
+    return map;
+  }
+  let j = 0;
+  for (let i = 0; i < value.length; i++) {
+    while (j < slice.length && slice[j] !== value[i]) j++;
+    if (j >= slice.length) return null;
+    map[i] = start + j;
+    j++;
+  }
+  return map;
+}
+
+function isText(n: HastNode): n is HastText {
+  return n.type === 'text' && typeof (n as HastText).value === 'string';
+}
+
+function hasChildren(n: HastNode): n is HastElement | HastRoot {
+  return Array.isArray((n as HastElement).children);
+}
+
+const TAG: Record<ReadMarkKind, string> = { suggestion: 'del', comment: 'mark', blame: 'span' };
+const NEST: ReadMarkKind[] = ['blame', 'comment', 'suggestion'];
+
+function element(tagName: string, properties: Record<string, unknown>, children: HastNode[]): HastElement {
+  return { type: 'element', tagName, properties, children };
+}
+
+/**
+ * Wrap the text runs of one aligned text node. Runs break at every mark
+ * boundary and at every place the source skips characters (an escape), so
+ * each run is contiguous in both the value and the source.
+ */
+function wrapText(
+  node: HastText,
+  map: number[],
+  marks: ReadMark[],
+  placed: Set<string>,
+  insertsDone: Set<string>,
+): HastNode[] {
+  const value = node.value;
+  if (!value.length) return [node];
+  const nodeFrom = map[0];
+  const nodeTo = map[value.length - 1] + 1;
+  const here = marks.filter((m) => m.from < nodeTo && m.to > nodeFrom);
+
+  const cuts = new Set<number>([0, value.length]);
+  for (let i = 1; i < value.length; i++) if (map[i] !== map[i - 1] + 1) cuts.add(i);
+  for (const m of here) {
+    for (const edge of [m.from, m.to]) {
+      for (let i = 1; i < value.length; i++) if (map[i] === edge) cuts.add(i);
+    }
+  }
+  // Pure inserts and the insert half of a replacement are drawn at a point.
+  const points = marks.filter((m) => m.kind === 'suggestion' && m.insert && !insertsDone.has(m.id));
+  for (const p of points) {
+    for (let i = 1; i < value.length; i++) if (map[i] === p.to) cuts.add(i);
+  }
+  const bounds = [...cuts].sort((a, b) => a - b);
+
+  const out: HastNode[] = [];
+  const emitInsertsAt = (srcPos: number) => {
+    for (const p of points) {
+      if (insertsDone.has(p.id) || p.to !== srcPos) continue;
+      insertsDone.add(p.id);
+      placed.add(p.id);
+      out.push(
+        element(
+          'ins',
+          { className: ['tc-read-ins'], dataTcId: p.id, title: p.title },
+          [{ type: 'text', value: p.insert ?? '' }],
+        ),
+      );
+    }
+  };
+
+  for (let b = 0; b < bounds.length - 1; b++) {
+    const i = bounds[b];
+    const k = bounds[b + 1];
+    const srcFrom = map[i];
+    const srcTo = map[k - 1] + 1;
+    emitInsertsAt(srcFrom);
+    let piece: HastNode = element('span', { dataSrcFrom: String(srcFrom) }, [{ type: 'text', value: value.slice(i, k) }]);
+    const covering = here.filter((m) => m.from <= srcFrom && m.to >= srcTo && m.to > m.from);
+    for (const kind of NEST) {
+      for (const m of covering.filter((x) => x.kind === kind)) {
+        placed.add(m.id);
+        piece = element(
+          TAG[kind],
+          { className: ['tc-read-' + kind, ...(m.className ? m.className.split(/\s+/) : [])], dataTcId: m.id, title: m.title },
+          [piece],
+        );
+      }
+    }
+    out.push(piece);
+    if (b === bounds.length - 2) emitInsertsAt(srcTo);
+  }
+  return out;
+}
+
+export interface MarkTreeResult {
+  /** Mark ids drawn at least partly. */
+  placed: Set<string>;
+}
+
+/**
+ * Transform a hast tree in place. `source` is the string the tree was parsed
+ * from. A mark is placed when at least one of its characters (or, for a pure
+ * insert, its point) is drawn.
+ */
+export function markTree(tree: HastNode, source: string, marks: ReadMark[]): MarkTreeResult {
+  const placed = new Set<string>();
+  const insertsDone = new Set<string>();
+  const visit = (parent: HastElement | HastRoot) => {
+    // Never inside code: a fenced block is re-highlighted by its own renderer
+    // and an inline code span is literal. Marks there are reported unplaced.
+    if ((parent as HastElement).tagName === 'code' || (parent as HastElement).tagName === 'pre') return;
+    const next: HastNode[] = [];
+    for (const child of parent.children) {
+      if (isText(child)) {
+        const start = child.position?.start?.offset;
+        const end = child.position?.end?.offset;
+        const map =
+          typeof start === 'number' && typeof end === 'number' ? alignToSource(child.value, source, start, end) : null;
+        if (map) next.push(...wrapText(child, map, marks, placed, insertsDone));
+        else next.push(child);
+      } else {
+        if (hasChildren(child)) visit(child);
+        next.push(child);
+      }
+    }
+    parent.children = next;
+  };
+  if (hasChildren(tree)) visit(tree);
+  return { placed };
+}
+
+/** The rehype plugin form of {@link markTree}, for MarkdownRenderer. */
+export function rehypeTrackMarks(options: {
+  source: string;
+  marks: ReadMark[];
+  onPlaced?: (placed: Set<string>) => void;
+}) {
+  return () => (tree: HastNode) => {
+    const { placed } = markTree(tree, options.source, options.marks);
+    options.onPlaced?.(placed);
+  };
+}
+
+/** A plain-text field as a one-node tree, so plain text takes the same path. */
+export function plainTree(source: string): HastRoot {
+  return {
+    type: 'root',
+    children: [{ type: 'text', value: source, position: { start: { offset: 0 }, end: { offset: source.length } } }],
+  };
+}
+
+/** Source offset of a DOM point inside a marked tree, or null when the point
+ *  is not inside a run that carries `data-src-from`. */
+export function sourceOffsetOf(node: Node | null, offset: number): number | null {
+  if (!node) return null;
+  if (node.nodeType !== 3) {
+    // An element point: use the child it sits before, or after the last.
+    const el = node as Element;
+    const child = el.childNodes[offset] ?? null;
+    if (child) return sourceOffsetOf(firstText(child), 0);
+    const last = el.childNodes[el.childNodes.length - 1] ?? null;
+    const t = last ? lastText(last) : null;
+    return t ? sourceOffsetOf(t, t.textContent?.length ?? 0) : null;
+  }
+  const run = (node.parentElement as Element | null)?.closest('[data-src-from]');
+  if (!run || run.closest('ins')) return null;
+  const from = Number(run.getAttribute('data-src-from'));
+  return Number.isFinite(from) ? from + offset : null;
+}
+
+function firstText(n: Node): Node | null {
+  if (n.nodeType === 3) return n;
+  for (const c of Array.from(n.childNodes)) {
+    const t = firstText(c);
+    if (t) return t;
+  }
+  return null;
+}
+
+function lastText(n: Node): Node | null {
+  if (n.nodeType === 3) return n;
+  const kids = Array.from(n.childNodes);
+  for (let i = kids.length - 1; i >= 0; i--) {
+    const t = lastText(kids[i]);
+    if (t) return t;
+  }
+  return null;
+}