@cueloop/client 0.1.0-alpha.21 → 0.1.0-alpha.23

package/src/intent-dispatch.test.ts

@@ -0,0 +1,213 @@
+/**
+ * The intent reducer in isolation: with the App component's dependencies
+ * mocked, each Intent maps to exactly the controller call or state update it
+ * should - the navigation clamps, the annotation wrap-around, the verdict
+ * cycle, and the submit-reveal fix, none of which needed a rendered TUI.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+import type { ReviewSession } from "@cueloop/schema";
+import { createIntentDispatch, type IntentDispatchDeps } from "./intent-dispatch";
+import type { DisplayBlock } from "./view-plan";
+
+function block(text: string): DisplayBlock {
+  return { text, kind: "text", work: true } as unknown as DisplayBlock;
+}
+
+function sessionWith(annotationIds: string[]): ReviewSession {
+  return {
+    annotations: annotationIds.map((id) => ({ id })),
+    workingCopy: undefined,
+  } as unknown as ReviewSession;
+}
+
+/** A deps bag where every effect is a mock and every read has a plain default. */
+function makeDeps(overrides: Partial<IntentDispatchDeps> = {}): IntentDispatchDeps {
+  const controller = {
+    setStatus: mock(),
+    open: mock(),
+    cut: mock(),
+    annotate: mock(),
+    updateAnnotation: mock(),
+    removeAnnotation: mock(),
+    walkStart: mock(),
+    walkForward: mock(),
+    walkBack: mock(),
+    walkLeave: mock(),
+    submit: mock(),
+    share: mock(),
+    finishReview: mock(),
+    optInAutoClose: mock(),
+    dismissCompletion: mock(),
+    saveReviewPanel: mock(),
+  };
+  return {
+    controller: controller as unknown as IntentDispatchDeps["controller"],
+    onExit: mock(),
+    isDiff: false,
+    display: [],
+    rows: [],
+    cursor: 0,
+    inbox: null,
+    inboxCursor: 0,
+    mode: { type: "normal" },
+    session: null,
+    reviewMode: "expanded",
+    reviewWidth: 34,
+    terminalWidth: 120,
+    focusedAnnotationId: undefined,
+    liveInput: { current: "" },
+    reviewWidthRef: { current: 34 },
+    planSheetRef: { current: null },
+    setCursor: mock(),
+    setInboxCursor: mock(),
+    setMode: mock(),
+    setReviewMode: mock(),
+    setReviewWidth: mock(),
+    setRailTab: mock(),
+    setFocusedAnnotationId: mock(),
+    setPulsedAnnotationId: mock(),
+    selectCardFromDocument: mock(),
+    runEditorHandOff: mock(),
+    openCardEdit: mock(),
+    ...overrides,
+  };
+}
+
+describe("move", () => {
+  test("down clamps at the last row and up clamps at the first", () => {
+    // Arrange
+    const deps = makeDeps({ display: [block("a"), block("b"), block("c")] });
+    const dispatch = createIntentDispatch(deps);
+
+    // Act
+    dispatch({ type: "move", to: "down" });
+
+    // Assert
+    const advance = (deps.setCursor as ReturnType<typeof mock>).mock.calls[0]![0] as (current: number) => number;
+    expect(advance(2)).toBe(2); // already at the end, stays
+    expect(advance(0)).toBe(1);
+  });
+
+  test("bottom jumps to the last navigable row", () => {
+    // Arrange
+    const deps = makeDeps({ display: [block("a"), block("b"), block("c")] });
+    const dispatch = createIntentDispatch(deps);
+
+    // Act
+    dispatch({ type: "move", to: "bottom" });
+
+    // Assert
+    expect(deps.setCursor).toHaveBeenCalledWith(2);
+  });
+});
+
+describe("annotation navigation", () => {
+  test("nextAnnotation wraps from the last annotation back to the first", () => {
+    // Arrange
+    const deps = makeDeps({ session: sessionWith(["a1", "a2", "a3"]), focusedAnnotationId: "a3" });
+    const dispatch = createIntentDispatch(deps);
+
+    // Act
+    dispatch({ type: "nextAnnotation" });
+
+    // Assert
+    expect(deps.selectCardFromDocument).toHaveBeenCalledWith("a1");
+  });
+
+  test("prevAnnotation wraps from the first annotation to the last", () => {
+    // Arrange
+    const deps = makeDeps({ session: sessionWith(["a1", "a2", "a3"]), focusedAnnotationId: "a1" });
+    const dispatch = createIntentDispatch(deps);
+
+    // Act
+    dispatch({ type: "prevAnnotation" });
+
+    // Assert
+    expect(deps.selectCardFromDocument).toHaveBeenCalledWith("a3");
+  });
+
+  test("cycling skips annotations a revision already addressed", () => {
+    // Arrange: a2 is addressed, so next from a1 lands on a3
+    const session = sessionWith(["a1", "a2", "a3"]);
+    (session.annotations[1] as { resolution?: object }).resolution = { revision: 2, source: "agent" };
+    const deps = makeDeps({ session, focusedAnnotationId: "a1" });
+    const dispatch = createIntentDispatch(deps);
+
+    // Act
+    dispatch({ type: "nextAnnotation" });
+
+    // Assert
+    expect(deps.selectCardFromDocument).toHaveBeenCalledWith("a3");
+  });
+});
+
+describe("cycleVerdict", () => {
+  test("advances through the verdict list in the submit overlay", () => {
+    // Arrange
+    const deps = makeDeps({ mode: { type: "submit", verdict: "approve", summary: "" } });
+    const dispatch = createIntentDispatch(deps);
+
+    // Act
+    dispatch({ type: "cycleVerdict", direction: 1 });
+
+    // Assert
+    expect(deps.setMode).toHaveBeenCalledWith({ type: "submit", verdict: "request_changes", summary: "" });
+  });
+});
+
+describe("openSubmit", () => {
+  test("force-opens the review rail so the confirm card can never be hidden", () => {
+    // Arrange
+    const deps = makeDeps({ session: sessionWith([]), reviewMode: "hidden" });
+    const dispatch = createIntentDispatch(deps);
+
+    // Act
+    dispatch({ type: "openSubmit" });
+
+    // Assert
+    expect(deps.setReviewMode).toHaveBeenCalledWith("expanded");
+    expect(deps.setRailTab).toHaveBeenCalledWith("review");
+    expect(deps.setMode).toHaveBeenCalledWith({ type: "submit", verdict: "approve", summary: "" });
+  });
+
+  test("does nothing without a session", () => {
+    // Arrange
+    const deps = makeDeps({ session: null });
+    const dispatch = createIntentDispatch(deps);
+
+    // Act
+    dispatch({ type: "openSubmit" });
+
+    // Assert
+    expect(deps.setMode).not.toHaveBeenCalled();
+  });
+});
+
+describe("share", () => {
+  test("dispatches to the controller's share", () => {
+    // Arrange
+    const deps = makeDeps();
+    const dispatch = createIntentDispatch(deps);
+
+    // Act
+    dispatch({ type: "share" });
+
+    // Assert
+    expect(deps.controller.share).toHaveBeenCalled();
+  });
+});
+
+describe("exit", () => {
+  test("calls the exit hook with 0", () => {
+    // Arrange
+    const deps = makeDeps();
+    const dispatch = createIntentDispatch(deps);
+
+    // Act
+    dispatch({ type: "exit" });
+
+    // Assert
+    expect(deps.onExit).toHaveBeenCalledWith(0);
+  });
+});

package/src/intent-dispatch.ts

@@ -0,0 +1,270 @@
+/**
+ * The intent reducer: one effectful handler per keymap Intent, lifted out of
+ * the App component so the 30-case grammar can be read and tested on its own.
+ * keymap.ts turns keys into Intents (pure); this turns an Intent into the
+ * matching controller call or view-state update. App builds the dependency
+ * bag once per render and hands it here; nothing in this module reaches back
+ * into React beyond the setters it is given.
+ */
+
+import type { Dispatch, MutableRefObject, RefObject, SetStateAction } from "react";
+import { isAddressed, isAgentNote, type ReviewSession, type VerdictKind } from "@cueloop/schema";
+import { displayText, spanKey, startSpan, type DisplayBlock, type SpanState } from "./view-plan";
+import type { DiffRow } from "./view-diff";
+import type { ReviewController } from "./session-controller";
+import type { Intent } from "./keymap";
+import type { PlanSheetHandle } from "./components/PlanSheet";
+import { VERDICTS } from "./components/ConfirmCard";
+import { REVIEW_RESIZE_STEP, cycleReviewPanelMode, resolveReviewWidth, type ReviewPanelMode } from "./review-panel";
+
+/** The one overlay/mode the TUI is in; every compose/submit/edit flow is a variant. */
+export type Mode =
+  | { type: "normal" }
+  | { type: "span"; span: SpanState }
+  | { type: "compose"; kind: "comment" | "suggestion"; displayIndex: number; start: number; end: number; text: string }
+  | { type: "railEdit"; id: string; text: string }
+  | { type: "submit"; verdict: VerdictKind; summary: string };
+
+/**
+ * Annotations that still count as feedback: agent notes never do, and an
+ * annotation a revision already addressed is settled - it neither blocks the
+ * verdict default nor re-enters the next feedback document.
+ */
+export function reviewerAnnotations(session: ReviewSession) {
+  return session.annotations.filter((annotation) => !isAgentNote(annotation) && !isAddressed(annotation));
+}
+
+export function defaultVerdict(session: ReviewSession): VerdictKind {
+  return reviewerAnnotations(session).length || session.workingCopy !== undefined ? "request_changes" : "approve";
+}
+
+/**
+ * Everything the reducer reads or writes, supplied fresh each render: the
+ * controller and exit hook, the derived reads (view rows, cursor, mode,
+ * session), the refs it pokes, the state setters, and the three App-owned
+ * selection helpers it composes.
+ */
+export interface IntentDispatchDeps {
+  controller: ReviewController;
+  onExit?: (code: number) => void;
+
+  isDiff: boolean;
+  display: DisplayBlock[];
+  rows: DiffRow[];
+  cursor: number;
+  inbox: ReviewSession[] | null;
+  inboxCursor: number;
+  mode: Mode;
+  session: ReviewSession | null;
+  reviewMode: ReviewPanelMode;
+  reviewWidth: number;
+  terminalWidth: number;
+  focusedAnnotationId: string | undefined;
+
+  liveInput: MutableRefObject<string>;
+  reviewWidthRef: MutableRefObject<number>;
+  planSheetRef: RefObject<PlanSheetHandle | null>;
+
+  setCursor: Dispatch<SetStateAction<number>>;
+  setInboxCursor: Dispatch<SetStateAction<number>>;
+  setMode: Dispatch<SetStateAction<Mode>>;
+  setReviewMode: Dispatch<SetStateAction<ReviewPanelMode>>;
+  setReviewWidth: Dispatch<SetStateAction<number>>;
+  setRailTab: Dispatch<SetStateAction<"review" | "agent">>;
+  setFocusedAnnotationId: Dispatch<SetStateAction<string | undefined>>;
+  setPulsedAnnotationId: Dispatch<SetStateAction<string | null>>;
+
+  selectCardFromDocument: (annotationId: string) => void;
+  runEditorHandOff: () => void;
+  openCardEdit: (annotationId: string) => void;
+}
+
+/** Build the intent handler for one render from its dependency bag. */
+export function createIntentDispatch(deps: IntentDispatchDeps): (intent: Intent) => void {
+  const {
+    controller,
+    onExit,
+    isDiff,
+    display,
+    rows,
+    cursor,
+    inbox,
+    inboxCursor,
+    mode,
+    session,
+    reviewMode,
+    reviewWidth,
+    terminalWidth,
+    focusedAnnotationId,
+    liveInput,
+    reviewWidthRef,
+    planSheetRef,
+    setCursor,
+    setInboxCursor,
+    setMode,
+    setReviewMode,
+    setReviewWidth,
+    setRailTab,
+    setFocusedAnnotationId,
+    setPulsedAnnotationId,
+    selectCardFromDocument,
+    runEditorHandOff,
+    openCardEdit,
+  } = deps;
+
+  return (intent: Intent): void => {
+    switch (intent.type) {
+      case "exit":
+        return void onExit?.(0);
+      case "status":
+        return controller.setStatus(intent.message);
+      case "move": {
+        const navigableCount = isDiff ? rows.length : display.length;
+        if (intent.to === "down") setCursor((current) => Math.min(navigableCount - 1, current + 1));
+        else if (intent.to === "up") setCursor((current) => Math.max(0, current - 1));
+        else if (intent.to === "top") setCursor(0);
+        else setCursor(navigableCount - 1);
+        return;
+      }
+      case "inboxMove": {
+        const navigableCount = inbox?.length ?? 0;
+        setInboxCursor((current) => (intent.to === "down" ? Math.min(navigableCount - 1, current + 1) : Math.max(0, current - 1)));
+        return;
+      }
+      case "openSession": {
+        const selected = inbox?.[inboxCursor];
+        if (selected) controller.open(selected.id);
+        return;
+      }
+      case "startSpan": {
+        const block = display[cursor];
+        if (!block?.work) return;
+        const span = startSpan(cursor, displayText(block));
+        if (span) setMode({ type: "span", span });
+        return;
+      }
+      case "spanKey":
+        if (mode.type === "span") {
+          const span = spanKey(mode.span, intent.name, displayText(display[mode.span.displayIndex]!));
+          setMode({ type: "span", span });
+        }
+        return;
+      case "openCompose": {
+        liveInput.current = "";
+        if (intent.from === "span" && mode.type === "span") {
+          setMode({
+            type: "compose",
+            kind: intent.kind,
+            displayIndex: mode.span.displayIndex,
+            start: mode.span.start,
+            end: mode.span.end,
+            text: "",
+          });
+        } else if (isDiff) {
+          const row = rows[cursor];
+          if (row) setMode({ type: "compose", kind: intent.kind, displayIndex: cursor, start: 0, end: row.text.length, text: "" });
+        } else {
+          // a mouse drag leaves a native selection; it wins over the cursor block
+          const native = planSheetRef.current?.readSelection() ?? null;
+          if (native) {
+            setMode({ type: "compose", kind: intent.kind, ...native, text: "" });
+          } else {
+            const block = display[cursor];
+            if (block) setMode({ type: "compose", kind: intent.kind, displayIndex: cursor, start: 0, end: displayText(block).length, text: "" });
+          }
+        }
+        return;
+      }
+      case "openSubmit":
+        if (!session) return;
+        liveInput.current = "";
+        // the confirm card lives in the expanded review rail; a compact or hidden
+        // panel would swallow the whole submit flow, so force the rail open (live
+        // only - the saved panel preference is left untouched)
+        setReviewMode("expanded");
+        setRailTab("review");
+        return void setMode({ type: "submit", verdict: defaultVerdict(session), summary: "" });
+      case "share":
+        return controller.share();
+      case "cut":
+        return controller.cut(cursor);
+      case "edit":
+        return runEditorHandOff();
+      case "editCard":
+        if (focusedAnnotationId) openCardEdit(focusedAnnotationId);
+        return;
+      case "nextAnnotation":
+      case "prevAnnotation": {
+        // cycle open cards only - addressed ones are out of the rail
+        const annotations = (session?.annotations ?? []).filter((annotation) => !isAddressed(annotation));
+        if (!annotations.length) return;
+        const focusedIndex = annotations.findIndex((annotation) => annotation.id === focusedAnnotationId);
+        const nextIndex =
+          focusedIndex === -1
+            ? 0
+            : (focusedIndex + (intent.type === "nextAnnotation" ? 1 : -1) + annotations.length) % annotations.length;
+        return void selectCardFromDocument(annotations[nextIndex]!.id);
+      }
+      case "walkStart":
+        return controller.walkStart();
+      case "walkForward":
+        return controller.walkForward();
+      case "walkBack":
+        return controller.walkBack();
+      case "walkLeave":
+        return controller.walkLeave();
+      case "removeAnnotation":
+        if (focusedAnnotationId) {
+          controller.removeAnnotation(focusedAnnotationId);
+          setFocusedAnnotationId(undefined);
+        }
+        return;
+      case "deselect":
+        planSheetRef.current?.clearSelection();
+        setFocusedAnnotationId(undefined);
+        setPulsedAnnotationId(null);
+        return;
+      case "closeOverlay":
+        return void setMode({ type: "normal" });
+      case "saveCompose": {
+        const body = liveInput.current.trim();
+        if (mode.type === "railEdit") {
+          if (session && body) controller.updateAnnotation(mode.id, body);
+          return void setMode({ type: "normal" });
+        }
+        if (mode.type !== "compose") return;
+        if (session && body) {
+          const annotationId = controller.annotate(mode.kind, mode.displayIndex, mode.start, mode.end, body);
+          if (annotationId) setFocusedAnnotationId(annotationId);
+        }
+        return void setMode({ type: "normal" });
+      }
+      case "submitVerdict":
+        if (mode.type === "submit") controller.submit(mode.verdict, liveInput.current);
+        return void setMode({ type: "normal" });
+      case "cycleVerdict": {
+        if (mode.type !== "submit") return;
+        const verdictIndex = (VERDICTS.indexOf(mode.verdict) + intent.direction + VERDICTS.length) % VERDICTS.length;
+        return void setMode({ ...mode, verdict: VERDICTS[verdictIndex]! });
+      }
+      case "finishReview":
+        return controller.finishReview();
+      case "optInAutoClose":
+        return controller.optInAutoClose();
+      case "dismissCompletion":
+        return controller.dismissCompletion();
+      case "cycleReviewPanel": {
+        const next = cycleReviewPanelMode(reviewMode);
+        setReviewMode(next);
+        return controller.saveReviewPanel({ mode: next });
+      }
+      case "resizeReviewPanel": {
+        if (reviewMode !== "expanded") return;
+        const next = resolveReviewWidth(reviewWidth + intent.direction * REVIEW_RESIZE_STEP, terminalWidth);
+        reviewWidthRef.current = next;
+        setReviewWidth(next);
+        return controller.saveReviewPanel({ width: next });
+      }
+    }
+  };
+}

package/src/key-bindings.test.ts

@@ -1,8 +1,4 @@
-/**
- * Binding resolution and hint generation over @opentui/keymap: config keys
- * resolve to action names per layer, and the status-line hints derive from
- * getActiveKeys() so rebinds surface in the hint text.
- */
+/** Config keys resolve to per-layer actions, and status hints derive from getActiveKeys() so rebinds surface. */
 
 import { describe, expect, test } from "bun:test";
 import { DEFAULT_KEYS } from "./config";
@@ -43,28 +39,40 @@ describe("grammar-layer resolution", () => {
 
 describe("mode layers own their keys", () => {
   test("span mode resolves the span verbs, not the grammar", () => {
+    // Arrange
     const resolver = bindings({ spanMode: true });
+
+    // Assert
     expect(resolver.resolveAction({ name: "l", shift: false })).toBe("span_grow");
     expect(resolver.resolveAction({ name: "c", shift: false })).toBe("span_comment");
     expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("span_cancel");
   });
 
   test("the compose overlay only knows save and cancel", () => {
+    // Arrange
     const resolver = bindings({ overlay: "compose" });
+
+    // Assert
     expect(resolver.resolveAction({ name: "return", shift: false })).toBe("save_compose");
     expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("cancel_overlay");
     expect(resolver.resolveAction({ name: "j", shift: false })).toBeUndefined();
   });
 
   test("the submit overlay adds the verdict arrows", () => {
+    // Arrange
     const resolver = bindings({ overlay: "submit" });
+
+    // Assert
     expect(resolver.resolveAction({ name: "left", shift: false })).toBe("cycle_verdict_left");
     expect(resolver.resolveAction({ name: "right", shift: false })).toBe("cycle_verdict_right");
     expect(resolver.resolveAction({ name: "return", shift: false })).toBe("submit_verdict");
   });
 
   test("the walk overlay owns the bracket stepping and leaves the grammar keys dead", () => {
+    // Arrange
     const resolver = bindings({ overlay: "walk" });
+
+    // Assert
     expect(resolver.resolveAction({ name: "]", shift: false })).toBe("walk_next");
     expect(resolver.resolveAction({ name: "[", shift: false })).toBe("walk_prev");
     expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("walk_leave");
@@ -110,9 +118,23 @@ describe("getActiveKeys-generated status hints", () => {
     expect(bindings().statusHint("read-only")).toBe("observer - read-only · j/k move · n/p annotations · q quit");
   });
 
+  test("collaborator hint annotates but shows no plan edit or submit", () => {
+    // Arrange / Act
+    const hint = bindings().statusHint("collaborator");
+
+    // Assert
+    expect(hint).toBe("j/k move · v span · drag selects · c comment · s suggest · n/p annotations · q quit");
+    expect(hint).not.toContain("cut");
+    expect(hint).not.toContain("edit");
+    expect(hint).not.toContain("submit");
+  });
+
   test("a rebound key shows its real binding in the hint", () => {
+    // Arrange
     const resolver = new KeyBindings({ ...DEFAULT_KEYS, comment: ["m"] });
     resolver.setContext({ overlay: "none", spanMode: false });
+
+    // Assert
     expect(resolver.resolveAction({ name: "m", shift: false })).toBe("comment");
     expect(resolver.resolveAction({ name: "c", shift: false })).toBeUndefined();
     expect(resolver.statusHint("normal")).toContain("m comment");

package/src/key-bindings.ts

@@ -24,7 +24,7 @@ export interface KeyLayerContext {
 }
 
 /** Hint templates keyed by the same view states the status line shows. */
-export type HintMode = "normal" | "card" | "span" | "compose" | "submit" | "walk" | "read-only";
+export type HintMode = "normal" | "collaborator" | "card" | "span" | "compose" | "submit" | "walk" | "read-only";
 
 type HintEntry =
   | { text: string }
@@ -43,6 +43,16 @@ const HINT_TEMPLATES: Record<HintMode, HintEntry[]> = {
     { commands: ["submit"], label: "submit" },
     { commands: ["quit"], label: "quit" },
   ],
+  // A share viewer: annotate and navigate, no plan edit / verdict submit.
+  collaborator: [
+    { commands: ["down", "up"], label: "move" },
+    { commands: ["span"], label: "span" },
+    { text: "drag selects" },
+    { commands: ["comment"], label: "comment" },
+    { commands: ["suggest"], label: "suggest" },
+    { commands: ["next_annotation", "prev_annotation"], label: "annotations" },
+    { commands: ["quit"], label: "quit" },
+  ],
   card: [
     { text: "card" },
     { commands: ["edit"], label: "edit" },