@cueloop/client 0.1.0-alpha.64 → 0.1.0-alpha.66

package/src/thread-chords.ts

@@ -0,0 +1,144 @@
+/**
+ * The session-level chords of the thread view. Letters in the thread view
+ * type a comment, so everything that acts on the session as a whole - submit,
+ * share, edit, the rail - lives on ctrl chords (cmd where the terminal
+ * delivers it). The guided walk is a diff-review mode and has no chord here. Pure: the view reports whether a composer is open, this maps
+ * a key to an intent or to nothing.
+ */
+
+import type { Intent } from "./keymap";
+
+export interface ThreadChordKey {
+  name: string;
+  ctrl?: boolean;
+  meta?: boolean;
+  super?: boolean;
+}
+
+export interface ThreadChordContext {
+  /** A composer owns the keyboard: chords never fire while one is open. */
+  composing: boolean;
+  /** Collaborators annotate only; submit, edit, and share are the owner's. */
+  isOwner: boolean;
+  /** A resolved session has nothing left to submit. */
+  resolved: boolean;
+  /** The rail shows the tree: next / previous move its selection instead of the cards. */
+  treeActive: boolean;
+}
+
+/** The cheatsheet rows for the chords, in the same order they are resolved. */
+export const THREAD_CHORD_ENTRIES = [
+  { keys: "⌃enter", label: "submit the review" },
+  { keys: "⌃e", label: "edit in $EDITOR" },
+  { keys: "⌃s", label: "share" },
+  { keys: "⌃r", label: "cycle the rail" },
+] as const;
+
+/** The rail and curation chords: option (alt) plus the plan sheet's old letter. */
+export const RAIL_CHORD_ENTRIES = [
+  { keys: "⌥n / ⌥p", label: "next / previous card" },
+  { keys: "⌥e", label: "edit the card" },
+  { keys: "⌥⌫", label: "delete the card" },
+  { keys: "⌥r", label: "rename the author" },
+  { keys: "⌥x", label: "cut the block" },
+  { keys: "⌥u", label: "restore the last cut" },
+  { keys: "⌥w / ⌥s", label: "widen / narrow the rail" },
+] as const;
+
+/** The tree chords: option plus a letter, all on the rail's Tree tab. */
+export const TREE_CHORD_ENTRIES = [
+  { keys: "⌥t", label: "show / hide the tree" },
+  { keys: "⌥n / ⌥p", label: "next / previous entry" },
+  { keys: "⌥g", label: "go to the entry" },
+  { keys: "⌥b", label: "branch off the tip" },
+  { keys: "⌥l", label: "label a checkpoint" },
+  { keys: "⌥f", label: "fork the path" },
+  { keys: "⌥h", label: "fork and hand off" },
+] as const;
+
+export function resolveThreadChord(
+  key: ThreadChordKey,
+  context: ThreadChordContext,
+): Intent | null {
+  if (context.composing) return null;
+  const modified = Boolean(key.ctrl || key.meta || key.super);
+
+  if (!modified) return null;
+  if (key.name === "return" || key.name === "enter") {
+    if (!context.isOwner) return READ_ONLY;
+
+    return context.resolved ? null : { type: "openSubmit" };
+  }
+  if (key.ctrl) return resolveSessionChord(key.name, context);
+  if (key.meta) return resolveRailChord(key.name, context);
+
+  return null;
+}
+
+/** The answers a blocked primitive gets - the same words the keymap uses. */
+const READ_ONLY: Intent = { type: "status", message: "observer - read-only" };
+const RESOLVED: Intent = { type: "status", message: "review submitted - read-only" };
+
+/** Editing, deleting, cutting, and restoring change the review: gated by role and by a verdict. */
+function mutating(intent: Intent, context: ThreadChordContext): Intent {
+  if (!context.isOwner) return READ_ONLY;
+  if (context.resolved) return RESOLVED;
+
+  return intent;
+}
+
+function resolveSessionChord(name: string, context: ThreadChordContext): Intent | null {
+  switch (name) {
+    case "e":
+      return mutating({ type: "edit" }, context);
+    case "s":
+      return context.isOwner ? { type: "share" } : READ_ONLY;
+    case "r":
+      return { type: "cycleReviewPanel" };
+    default:
+      return null;
+  }
+}
+
+// option arrives as meta in this terminal stack; the letters mirror the
+// plan sheet's keymap so the rail keeps its muscle memory
+function resolveRailChord(name: string, context: ThreadChordContext): Intent | null {
+  switch (name) {
+    case "n":
+      return context.treeActive ? { type: "treeMove", direction: 1 } : { type: "nextAnnotation" };
+    case "p":
+      return context.treeActive ? { type: "treeMove", direction: -1 } : { type: "prevAnnotation" };
+    case "t":
+      return { type: "toggleTree" };
+    // the tree is the owner's: a move, a branch, or a label changes what everyone sees
+    case "g":
+      return mutating({ type: "treeGo" }, context);
+    case "b":
+      return mutating({ type: "treeBranch" }, context);
+    case "l":
+      return mutating({ type: "treeLabel" }, context);
+    // a fork can be taken from a resolved review: only the role gates it
+    case "f":
+      return context.isOwner ? { type: "treeFork" } : READ_ONLY;
+    case "h":
+      return context.isOwner ? { type: "treeForkShare" } : READ_ONLY;
+    case "e":
+      return mutating({ type: "editCard" }, context);
+    case "backspace":
+      return mutating({ type: "removeAnnotation" }, context);
+    // renaming an author is a local display choice, open to every role
+    case "r":
+      return { type: "openRename" };
+    case "x":
+      return mutating({ type: "cut" }, context);
+    case "u":
+      return mutating({ type: "restoreCuration" }, context);
+    // letters only: escape-prefixed punctuation reads as control sequences, not keys
+    case "w":
+      return { type: "resizeReviewPanel", direction: 1 };
+    case "s":
+      return { type: "resizeReviewPanel", direction: -1 };
+    default:
+      return null;
+  }
+}

package/src/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/thread-selection.ts

@@ -0,0 +1,243 @@
+/**
+ * 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;
+  /** Char range of the block's text this line shows. */
+  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;
+}