@cueloop/client 0.1.0-alpha.10 → 0.1.0-alpha.100

package/src/annotations/discussions.ts

@@ -0,0 +1,77 @@
+/**
+ * Discussions: the conversations an annotated surface hosts inline. A root
+ * annotation, its replies, and the span they mark, grouped so two roots on the
+ * very same text read as one conversation. Pure over the resolved marks, so the
+ * plan thread view and the diff sheet group the same way.
+ */
+
+import type { Annotation, Thread } from "@cueloop/schema";
+import type { Mark } from "../markdown/view-plan";
+import { comparePositions, type TextSpan } from "./thread-selection";
+
+/** One conversation: a root annotation, its replies, and the span they mark. */
+export interface Discussion {
+  key: string;
+  rootId: string;
+  blockIndex: number;
+  span: TextSpan;
+  annotations: Annotation[];
+}
+
+export function spanKey(span: TextSpan): string {
+  return `${span.start.blockIndex}:${span.start.char}:${span.end.blockIndex}:${span.end.char}`;
+}
+
+/**
+ * Roots group by the span they resolved to (two roots on the very same text
+ * read as one conversation); replies join the discussion their replyTo names, or
+ * stand as roots when that root is gone.
+ */
+export function discussionsFrom(session: Thread, marks: Map<number, Mark[]>): Discussion[] {
+  const byId = new Map(session.annotations.map((annotation) => [annotation.id, annotation]));
+  const spanOf = new Map<string, TextSpan>();
+
+  for (const [displayIndex, blockMarks] of marks) {
+    for (const mark of blockMarks) {
+      if (!mark.annotationId || spanOf.has(mark.annotationId)) continue;
+      spanOf.set(
+        mark.annotationId,
+        mark.span ?? {
+          start: { blockIndex: displayIndex, char: mark.start },
+          end: { blockIndex: displayIndex, char: mark.end },
+        },
+      );
+    }
+  }
+  const resolved = [...spanOf.keys()].map((id) => byId.get(id)!).filter(Boolean);
+  const isRoot = (annotation: Annotation): boolean =>
+    annotation.replyTo === undefined || !spanOf.has(annotation.replyTo);
+  const grouped = new Map<string, Discussion>();
+  const discussionOfRoot = new Map<string, Discussion>();
+
+  for (const annotation of resolved.filter(isRoot)) {
+    const span = spanOf.get(annotation.id)!;
+    const key = spanKey(span);
+    const discussion = grouped.get(key) ?? {
+      key,
+      rootId: annotation.id,
+      blockIndex: span.end.blockIndex,
+      span,
+      annotations: [],
+    };
+
+    discussion.annotations.push(annotation);
+    grouped.set(key, discussion);
+    discussionOfRoot.set(annotation.id, discussion);
+  }
+  for (const annotation of resolved.filter((candidate) => !isRoot(candidate))) {
+    discussionOfRoot.get(annotation.replyTo!)?.annotations.push(annotation);
+  }
+  for (const discussion of grouped.values()) {
+    discussion.annotations.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+  }
+
+  return [...grouped.values()].toSorted((left, right) =>
+    comparePositions(left.span.start, right.span.start),
+  );
+}

package/src/annotations/thread-selection.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, test } from "bun:test";
+import {
+  isCollapsed,
+  isDoubleClick,
+  nextWordStart,
+  orderedSpan,
+  positionAt,
+  previousWordStart,
+  snapSpanToWords,
+  snapToWords,
+  spanRangeInBlock,
+  tightenSpan,
+  wordRangeAt,
+  type LineGeometry,
+} from "./thread-selection";
+
+const TEXT = "All persistence lives in a new module.";
+const BULLET = "store.ts - the store";
+// block 3 wraps onto two rows, a blank row, then bullet block 4 on one row
+const LINES: LineGeometry[] = [
+  { blockIndex: 3, start: 0, end: 21, x: 4, y: 10 },
+  { blockIndex: 3, start: 22, end: 38, x: 4, y: 11 },
+  { blockIndex: 4, start: 0, end: 20, x: 6, y: 13 },
+];
+const textLengthOf = (blockIndex: number): number =>
+  blockIndex === 3 ? TEXT.length : BULLET.length;
+
+describe("positionAt", () => {
+  test("maps a cell inside a line to the character under it", () => {
+    // Act
+    const position = positionAt(LINES, 4 + 6, 10);
+
+    // Assert: column 6 of the first line is the "r" in "persistence"
+    expect(position).toEqual({ blockIndex: 3, char: 6 });
+    expect(TEXT[6]).toBe("r");
+  });
+
+  test("past the right edge resolves to the position after the line's last char", () => {
+    // Assert
+    expect(positionAt(LINES, 90, 10)).toEqual({ blockIndex: 3, char: 21 });
+  });
+
+  test("a row without text resolves to the end of the closest line above", () => {
+    // Assert: the blank row between the blocks, and a row below everything
+    expect(positionAt(LINES, 30, 12)).toEqual({ blockIndex: 3, char: 38 });
+    expect(positionAt(LINES, 30, 40)).toEqual({ blockIndex: 4, char: 20 });
+  });
+
+  test("rows above all text resolve to the first character", () => {
+    // Assert
+    expect(positionAt(LINES, 30, 2)).toEqual({ blockIndex: 3, char: 0 });
+  });
+
+  test("a row of another block maps into that block", () => {
+    // Act
+    const position = positionAt(LINES, 6 + 3, 13);
+
+    // Assert
+    expect(position).toEqual({ blockIndex: 4, char: 3 });
+    expect(positionAt([], 5, 10)).toBeNull();
+  });
+});
+
+describe("orderedSpan and tightenSpan", () => {
+  test("a backward drag normalizes to document order", () => {
+    // Act
+    const span = orderedSpan({
+      anchor: { blockIndex: 4, char: 5 },
+      head: { blockIndex: 3, char: 6 },
+    });
+
+    // Assert
+    expect(span).toEqual({
+      start: { blockIndex: 3, char: 6 },
+      end: { blockIndex: 4, char: 5 },
+    });
+  });
+
+  test("a collapsed selection is no span", () => {
+    // Arrange
+    const selection = {
+      anchor: { blockIndex: 3, char: 6 },
+      head: { blockIndex: 3, char: 6 },
+    };
+
+    // Assert
+    expect(isCollapsed(selection)).toBe(true);
+    expect(orderedSpan(selection)).toBeNull();
+  });
+
+  test("a span opening at a block's end moves onto the next block", () => {
+    // Act: the pointer sat on the blank row above the bullet when the press landed
+    const tightened = tightenSpan(
+      {
+        start: { blockIndex: 3, char: TEXT.length },
+        end: { blockIndex: 4, char: 5 },
+      },
+      textLengthOf,
+    );
+
+    // Assert
+    expect(tightened).toEqual({
+      start: { blockIndex: 4, char: 0 },
+      end: { blockIndex: 4, char: 5 },
+    });
+  });
+
+  test("a span closing at a block's start moves back onto the previous block", () => {
+    // Act
+    const tightened = tightenSpan(
+      { start: { blockIndex: 3, char: 10 }, end: { blockIndex: 4, char: 0 } },
+      textLengthOf,
+    );
+
+    // Assert
+    expect(tightened).toEqual({
+      start: { blockIndex: 3, char: 10 },
+      end: { blockIndex: 3, char: TEXT.length },
+    });
+  });
+
+  test("a span with nothing left in it is null", () => {
+    // Assert
+    expect(
+      tightenSpan(
+        {
+          start: { blockIndex: 3, char: TEXT.length },
+          end: { blockIndex: 4, char: 0 },
+        },
+        textLengthOf,
+      ),
+    ).toBeNull();
+  });
+});
+
+describe("spanRangeInBlock", () => {
+  const span = {
+    start: { blockIndex: 3, char: 22 },
+    end: { blockIndex: 5, char: 4 },
+  };
+
+  test("the first block runs from the start to its end, middles fully, the last to the end char", () => {
+    // Assert
+    expect(spanRangeInBlock(span, 3, TEXT.length)).toEqual({
+      start: 22,
+      end: TEXT.length,
+    });
+    expect(spanRangeInBlock(span, 4, BULLET.length)).toEqual({
+      start: 0,
+      end: BULLET.length,
+    });
+    expect(spanRangeInBlock(span, 5, 30)).toEqual({ start: 0, end: 4 });
+  });
+
+  test("blocks outside the span have no range", () => {
+    // Assert
+    expect(spanRangeInBlock(span, 2, 10)).toBeNull();
+    expect(spanRangeInBlock(span, 6, 10)).toBeNull();
+  });
+});
+
+describe("word rules", () => {
+  test("the boundary rule attributes trailing whitespace to the preceding word", () => {
+    // Assert: char 3 is the space after "All"
+    expect(wordRangeAt(TEXT, 3)).toEqual({ start: 0, end: 3 });
+  });
+
+  test("snapToWords grows a partial range to whole words on both sides", () => {
+    // Assert: "rsistence liv" -> "persistence lives"
+    expect(snapToWords(TEXT, { start: 6, end: 19 })).toEqual({
+      start: 4,
+      end: 21,
+    });
+  });
+
+  test("snapSpanToWords snaps each end of a cross-block span within its own block", () => {
+    // Act: "rsistence ... st" -> "persistence ... store.ts"
+    const snapped = snapSpanToWords(
+      { start: { blockIndex: 3, char: 6 }, end: { blockIndex: 4, char: 2 } },
+      (blockIndex) => (blockIndex === 3 ? TEXT : BULLET),
+    );
+
+    // Assert
+    expect(snapped).toEqual({
+      start: { blockIndex: 3, char: 4 },
+      end: { blockIndex: 4, char: 8 },
+    });
+  });
+
+  test("word starts step in both directions and stop at the ends", () => {
+    // Assert
+    expect(nextWordStart(TEXT, 0)).toBe(4);
+    expect(nextWordStart(TEXT, 31)).toBeNull();
+    expect(previousWordStart(TEXT, 22)).toBe(16);
+    expect(previousWordStart(TEXT, 0)).toBeNull();
+  });
+});
+
+describe("isDoubleClick", () => {
+  test("same cell within the window counts, a moved or late press does not", () => {
+    // Arrange
+    const first = { time: 1000, x: 5, y: 7 };
+
+    // Assert
+    expect(isDoubleClick(first, { time: 1300, x: 5, y: 7 })).toBe(true);
+    expect(isDoubleClick(first, { time: 1300, x: 6, y: 7 })).toBe(false);
+    expect(isDoubleClick(first, { time: 1500, x: 5, y: 7 })).toBe(false);
+    expect(isDoubleClick(null, { time: 1300, x: 5, y: 7 })).toBe(false);
+  });
+});

package/src/annotations/thread-selection.ts

@@ -0,0 +1,242 @@
+/**
+ * The thread view's text-selection model: a pure, renderer-free description
+ * of where the caret is and what is marked, plus the hit-testing that maps a
+ * pointer cell onto a character. Character-precise (partial words), spanning
+ * wrapped lines and consecutive blocks, normalized for backward drags. Word snapping
+ * happens only where the grammar asks for it: the typing anchor for a bare
+ * caret, and double-click word mode.
+ *
+ * Isolated on purpose: the interaction can be unit-tested and benchmarked
+ * without a terminal, and the view layer only wires events to it.
+ */
+
+export interface TextPosition {
+  blockIndex: number;
+  char: number;
+}
+
+/** Where one visual line of a block sits on screen, in cells. */
+export interface LineGeometry {
+  blockIndex: number;
+  start: number;
+  end: number;
+  x: number;
+  y: number;
+}
+
+/** The held selection: `anchor` is where the press landed, `head` follows the pointer. */
+export interface Selection {
+  anchor: TextPosition;
+  head: TextPosition;
+}
+
+export interface CharRange {
+  start: number;
+  end: number;
+}
+
+/** An ordered stretch of text, possibly across consecutive blocks. */
+export interface TextSpan {
+  start: TextPosition;
+  end: TextPosition;
+}
+
+/** Document order: block first, then character. */
+export function comparePositions(left: TextPosition, right: TextPosition): number {
+  return left.blockIndex - right.blockIndex || left.char - right.char;
+}
+
+/** Word boundaries of a block's text. */
+export function wordRanges(text: string): CharRange[] {
+  const ranges: CharRange[] = [];
+  const matcher = /\S+/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = matcher.exec(text)) !== null) {
+    ranges.push({ start: match.index, end: match.index + match[0].length });
+  }
+
+  return ranges;
+}
+
+/**
+ * The marked word for a char offset: the word containing it, or - when the
+ * caret sits in the whitespace immediately after a word - that preceding
+ * word, never the next one.
+ */
+export function wordIndexAt(text: string, char: number): number {
+  const words = wordRanges(text);
+
+  for (let index = 0; index < words.length; index++) {
+    if (char < words[index]!.start) return Math.max(0, index - 1);
+    if (char < words[index]!.end) return index;
+  }
+
+  return Math.max(0, words.length - 1);
+}
+
+/** The word range the boundary rule assigns to a char offset; null for empty text. */
+export function wordRangeAt(text: string, char: number): CharRange | null {
+  const words = wordRanges(text);
+
+  return words[wordIndexAt(text, char)] ?? null;
+}
+
+/**
+ * Map a pointer cell to a text position over every registered line. A row
+ * without text (a blank row, a card) resolves to the end of the closest line
+ * above it, rows above all text to the first character, and a cell past a
+ * line's last cell to the position after that line's last character, so a
+ * drag that runs off the right edge still selects to the line end.
+ */
+export function positionAt(lines: LineGeometry[], x: number, y: number): TextPosition | null {
+  if (lines.length === 0) return null;
+  const ordered = lines.toSorted((left, right) => left.y - right.y || left.x - right.x);
+  const onRow = ordered.find((line) => line.y === y);
+
+  if (onRow) {
+    const column = Math.max(0, Math.min(onRow.end - onRow.start, x - onRow.x));
+
+    return { blockIndex: onRow.blockIndex, char: onRow.start + column };
+  }
+  const above = ordered.findLast((line) => line.y < y);
+
+  if (above) return { blockIndex: above.blockIndex, char: above.end };
+  const first = ordered[0]!;
+
+  return { blockIndex: first.blockIndex, char: first.start };
+}
+
+/** True when nothing is held: the caret is a point, not a range. */
+export function isCollapsed(selection: Selection): boolean {
+  return comparePositions(selection.anchor, selection.head) === 0;
+}
+
+/** The selection in document order, or null when collapsed. */
+export function orderedSpan(selection: Selection): TextSpan | null {
+  if (isCollapsed(selection)) return null;
+
+  return comparePositions(selection.anchor, selection.head) < 0
+    ? { start: selection.anchor, end: selection.head }
+    : { start: selection.head, end: selection.anchor };
+}
+
+/**
+ * Pull a span's edges off block boundaries: opening at a block's end or
+ * closing at a block's start marks nothing there, so the edge moves onto the
+ * neighbouring block. Null when nothing remains.
+ */
+export function tightenSpan(
+  span: TextSpan,
+  textLengthOf: (blockIndex: number) => number,
+): TextSpan | null {
+  let { start, end } = span;
+
+  while (start.blockIndex < end.blockIndex && start.char >= textLengthOf(start.blockIndex)) {
+    start = { blockIndex: start.blockIndex + 1, char: 0 };
+  }
+  while (end.blockIndex > start.blockIndex && end.char === 0) {
+    end = {
+      blockIndex: end.blockIndex - 1,
+      char: textLengthOf(end.blockIndex - 1),
+    };
+  }
+  const clampedEnd = {
+    blockIndex: end.blockIndex,
+    char: Math.min(end.char, textLengthOf(end.blockIndex)),
+  };
+
+  return comparePositions(start, clampedEnd) < 0 ? { start, end: clampedEnd } : null;
+}
+
+/** The part of a span that falls on one block, as a char range; null when none. */
+export function spanRangeInBlock(
+  span: TextSpan,
+  blockIndex: number,
+  textLength: number,
+): CharRange | null {
+  if (blockIndex < span.start.blockIndex || blockIndex > span.end.blockIndex) return null;
+  const start = blockIndex === span.start.blockIndex ? span.start.char : 0;
+  const end = blockIndex === span.end.blockIndex ? Math.min(span.end.char, textLength) : textLength;
+
+  return end > start ? { start, end } : null;
+}
+
+/** Grow a char range outward to the word boundaries it touches (double-click word mode). */
+export function snapToWords(text: string, range: CharRange): CharRange {
+  const words = wordRanges(text);
+  const first = words.find((word) => range.start < word.end) ?? words[words.length - 1];
+  const last = words.toReversed().find((word) => range.end > word.start) ?? words[0];
+
+  if (!first || !last) return range;
+
+  return {
+    start: Math.min(first.start, range.start),
+    end: Math.max(last.end, range.end),
+  };
+}
+
+/** Snap both ends of a span to word boundaries, each within its own block. */
+export function snapSpanToWords(span: TextSpan, textOf: (blockIndex: number) => string): TextSpan {
+  if (span.start.blockIndex === span.end.blockIndex) {
+    const snapped = snapToWords(textOf(span.start.blockIndex), {
+      start: span.start.char,
+      end: span.end.char,
+    });
+
+    return {
+      start: { blockIndex: span.start.blockIndex, char: snapped.start },
+      end: { blockIndex: span.end.blockIndex, char: snapped.end },
+    };
+  }
+  const startText = textOf(span.start.blockIndex);
+  const endText = textOf(span.end.blockIndex);
+
+  return {
+    start: {
+      blockIndex: span.start.blockIndex,
+      char: snapToWords(startText, {
+        start: span.start.char,
+        end: startText.length,
+      }).start,
+    },
+    end: {
+      blockIndex: span.end.blockIndex,
+      char: snapToWords(endText, { start: 0, end: span.end.char }).end,
+    },
+  };
+}
+
+export interface ClickStamp {
+  time: number;
+  x: number;
+  y: number;
+}
+
+/** Two presses on the same cell inside this window read as a double-click. */
+export const DOUBLE_CLICK_WINDOW_MS = 400;
+
+export function isDoubleClick(previous: ClickStamp | null, current: ClickStamp): boolean {
+  return (
+    previous !== null &&
+    previous.x === current.x &&
+    previous.y === current.y &&
+    current.time - previous.time <= DOUBLE_CLICK_WINDOW_MS
+  );
+}
+
+/** Next word start after `char`, or null past the last word. */
+export function nextWordStart(text: string, char: number): number | null {
+  const next = wordRanges(text).find((word) => word.start > char);
+
+  return next ? next.start : null;
+}
+
+/** Previous word start before `char`, or null before the first word. */
+export function previousWordStart(text: string, char: number): number | null {
+  const previous = wordRanges(text)
+    .toReversed()
+    .find((word) => word.start < char);
+
+  return previous ? previous.start : null;
+}