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

package/src/workbench/components/ProjectTreeView.test.tsx

@@ -0,0 +1,236 @@
+/** The Project tree navigates by keyboard when focused: j/k move the cursor, Enter folds a folder or
+ * opens a file. */
+
+import { test, expect } from "bun:test";
+import React from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { ScrollBoxRenderable, type Renderable } from "@opentui/core";
+import { ProjectTreeView } from "./ProjectTreeView";
+import { locateText, settle, waitForText, waitForTextGone } from "../../testing/test-support";
+import { DARK } from "../../appearance/theme";
+
+function findById(node: Renderable, id: string): Renderable | undefined {
+  if (node.id === id) return node;
+  for (const child of node.getChildren()) {
+    const found = findById(child, id);
+
+    if (found) return found;
+  }
+
+  return undefined;
+}
+
+test("Enter expands a folder, then j moves down and Enter opens the file", async () => {
+  const opened: string[] = [];
+  const setup = await testRender(
+    <ProjectTreeView
+      loadFiles={async () => ["src/a.ts", "README.md"]}
+      onSelectFile={(path) => opened.push(path)}
+      focused
+      theme={DARK}
+    />,
+    { width: 40, height: 12 },
+  );
+
+  await settle(setup);
+  await waitForText(setup, "src");
+
+  // cursor starts on the "src" folder; Enter expands it
+  setup.mockInput.pressKey("RETURN");
+  await waitForText(setup, "a.ts");
+
+  // j moves onto the file, Enter opens it
+  setup.mockInput.pressKey("j");
+  await settle(setup);
+  setup.mockInput.pressKey("RETURN");
+  await settle(setup);
+
+  expect(opened).toEqual(["src/a.ts"]);
+
+  setup.renderer.destroy();
+});
+
+test("keyboard navigation reveals the selected project row", async () => {
+  const paths = Array.from(
+    { length: 35 },
+    (_, index) => `file-${String(index).padStart(2, "0")}.ts`,
+  );
+  const setup = await testRender(
+    <ProjectTreeView loadFiles={async () => paths} onSelectFile={() => {}} focused theme={DARK} />,
+    { width: 28, height: 8 },
+  );
+
+  await waitForText(setup, "file-00.ts");
+  const scrollbox = findById(setup.renderer.root, "tree-scroll");
+
+  if (!(scrollbox instanceof ScrollBoxRenderable)) throw new Error("tree scrollbox missing");
+  const scrollSteps: number[] = [];
+
+  for (const [index, key] of Array.from({ length: 15 }, () => "j").entries()) {
+    const before = scrollbox.scrollTop;
+
+    setup.mockInput.pressKey(key);
+    // eslint-disable-next-line no-await-in-loop
+    await settle(setup);
+    scrollSteps.push(scrollbox.scrollTop - before);
+    const row = scrollbox.content.findDescendantById(
+      `tree-row-file-${String(index + 1).padStart(2, "0")}.ts`,
+    );
+
+    expect(row?.y).toBeGreaterThanOrEqual(scrollbox.viewport.y);
+    expect(row?.y).toBeLessThan(scrollbox.viewport.y + scrollbox.viewport.height);
+  }
+
+  expect(scrollbox.scrollTop).toBeGreaterThan(0);
+  expect(Math.max(...scrollSteps)).toBe(1);
+  expect(setup.captureCharFrame()).toContain("file-15.ts");
+  setup.renderer.destroy();
+});
+
+test("project wheel scrolling accelerates during a gesture and resets after a pause", async () => {
+  const paths = Array.from(
+    { length: 35 },
+    (_, index) => `file-${String(index).padStart(2, "0")}.ts`,
+  );
+  const setup = await testRender(
+    <ProjectTreeView loadFiles={async () => paths} onSelectFile={() => {}} theme={DARK} />,
+    { width: 28, height: 8 },
+  );
+
+  await waitForText(setup, "file-00.ts");
+  const scrollbox = findById(setup.renderer.root, "tree-scroll");
+
+  if (!(scrollbox instanceof ScrollBoxRenderable)) throw new Error("tree scrollbox missing");
+  const acceleration = scrollbox.scrollAcceleration;
+  const first = acceleration.tick(1000);
+  const burst = Array.from({ length: 10 }, (_, index) => acceleration.tick(1016 + index * 16));
+  const tail = acceleration.tick(1400);
+
+  expect(first).toBe(1);
+  expect(Math.max(...burst)).toBeGreaterThan(first);
+  expect(tail).toBe(1);
+  acceleration.reset();
+  await setup.mockMouse.scroll(10, 4, "down");
+  await settle(setup);
+  expect(scrollbox.scrollTop).toBeGreaterThan(0);
+  setup.renderer.destroy();
+});
+
+test("long project filenames stay on one row without an ellipsis", async () => {
+  const path = "src/ChangesFileTree.test.tsx";
+  const setup = await testRender(
+    <ProjectTreeView loadFiles={async () => [path]} onSelectFile={() => {}} focused theme={DARK} />,
+    { width: 22, height: 8 },
+  );
+
+  await waitForText(setup, "src");
+  setup.mockInput.pressKey("RETURN");
+  await settle(setup);
+  const frame = setup.captureCharFrame();
+  const row = findById(setup.renderer.root, `tree-row-${path}`);
+
+  expect(row?.height).toBe(1);
+  expect(frame).not.toContain("…");
+  expect(frame).toContain("ChangesFile");
+  setup.renderer.destroy();
+});
+
+test("without focus the keyboard does nothing", async () => {
+  const opened: string[] = [];
+  const setup = await testRender(
+    <ProjectTreeView
+      loadFiles={async () => ["src/a.ts"]}
+      onSelectFile={(path) => opened.push(path)}
+      theme={DARK}
+    />,
+    { width: 40, height: 12 },
+  );
+
+  await settle(setup);
+  await waitForText(setup, "src");
+
+  setup.mockInput.pressKey("RETURN");
+  await settle(setup);
+  expect(setup.captureCharFrame()).not.toContain("a.ts");
+  expect(opened).toEqual([]);
+
+  setup.renderer.destroy();
+});
+
+test("the empty project hint stays centered in the panel", async () => {
+  const setup = await testRender(
+    <ProjectTreeView loadFiles={async () => []} onSelectFile={() => {}} theme={DARK} />,
+    { width: 40, height: 12 },
+  );
+
+  await waitForText(setup, "empty");
+  const position = locateText(setup, "empty");
+
+  expect(position.column).toBeGreaterThanOrEqual(17);
+  expect(position.column).toBeLessThanOrEqual(18);
+  expect(position.row).toBeGreaterThanOrEqual(5);
+  expect(position.row).toBeLessThanOrEqual(6);
+  setup.renderer.destroy();
+});
+
+test("the visible tree removes deleted files without remounting", async () => {
+  let files = ["README.md", "gone.ts"];
+  const setup = await testRender(
+    <ProjectTreeView loadFiles={async () => files} onSelectFile={() => {}} theme={DARK} />,
+    { width: 40, height: 12 },
+  );
+
+  await waitForText(setup, "gone.ts");
+  files = ["README.md"];
+  await waitForTextGone(setup, "gone.ts");
+  expect(setup.captureCharFrame()).toContain("README.md");
+  setup.renderer.destroy();
+});
+
+test("refresh keeps the selected file when an earlier file disappears", async () => {
+  let files = ["a.ts", "b.ts", "c.ts"];
+  const opened: string[] = [];
+  const setup = await testRender(
+    <ProjectTreeView
+      loadFiles={async () => files}
+      onSelectFile={(path) => opened.push(path)}
+      focused
+      theme={DARK}
+    />,
+    { width: 40, height: 12 },
+  );
+
+  await waitForText(setup, "b.ts");
+  setup.mockInput.pressKey("j");
+  await settle(setup);
+  files = ["b.ts", "c.ts"];
+  await waitForTextGone(setup, "a.ts");
+  setup.mockInput.pressKey("RETURN");
+  await settle(setup);
+
+  expect(opened).toEqual(["b.ts"]);
+  setup.renderer.destroy();
+});
+
+test("a double-click requests a persistent file tab", async () => {
+  const opened: { path: string; persistent: boolean }[] = [];
+  const setup = await testRender(
+    <ProjectTreeView
+      loadFiles={async () => ["README.md"]}
+      onSelectFile={(path, persistent) => opened.push({ path, persistent: persistent === true })}
+      theme={DARK}
+    />,
+    { width: 40, height: 12 },
+  );
+
+  await waitForText(setup, "README.md");
+  const file = locateText(setup, "README.md");
+
+  await setup.mockMouse.doubleClick(file.column, file.row);
+  expect(opened).toEqual([
+    { path: "README.md", persistent: false },
+    { path: "README.md", persistent: false },
+    { path: "README.md", persistent: true },
+  ]);
+  setup.renderer.destroy();
+});

package/src/workbench/components/ProjectTreeView.tsx

@@ -0,0 +1,151 @@
+// The Project pane in tree mode: the workspace's tracked files as a collapsible directory tree.
+// Folders start collapsed and expand on click; a file click opens it as a tab. The caller keys this
+// on the session id so switching sessions remounts it and never shows the previous repository's paths.
+
+import { ScrollArea } from "../../ui/components/ScrollArea";
+import React, { useEffect, useEffectEvent, useMemo, useState } from "react";
+import { useKeyboard } from "@opentui/react";
+import type { Theme } from "../../appearance/theme";
+import { useComponentTheme } from "../../appearance/components/theme-context";
+import { Tree } from "../../ui/components/primitives/Tree";
+import { flattenTree } from "../../ui/components/primitives/tree-model";
+import { buildPathTree } from "./file-tree";
+
+const PROJECT_FILES_REFRESH_MS = 2000;
+
+export interface ProjectTreeViewProps {
+  loadFiles: () => Promise<string[]>;
+  onSelectFile: (path: string, persistent?: boolean) => void;
+  focused?: boolean;
+  theme?: Theme;
+}
+
+export function ProjectTreeView({
+  loadFiles,
+  onSelectFile,
+  focused = false,
+  theme,
+}: ProjectTreeViewProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const [paths, setPaths] = useState<readonly string[] | null>(null);
+  const [expandedIds, setExpandedIds] = useState<ReadonlySet<string>>(new Set());
+  const [cursorId, setCursorId] = useState<string | null>(null);
+  const nodes = useMemo(() => (paths ? buildPathTree(paths) : []), [paths]);
+  const rows = useMemo(() => flattenTree(nodes, { expandedIds }), [nodes, expandedIds]);
+  const cursorIndex = Math.max(
+    0,
+    rows.findIndex((row) => row.id === cursorId),
+  );
+  const loadLatestFiles = useEffectEvent(loadFiles);
+
+  const toggle = (id: string): void =>
+    setExpandedIds((current) => {
+      const next = new Set(current);
+
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+
+      return next;
+    });
+
+  useKeyboard((key) => {
+    if (!focused || rows.length === 0) return;
+    if (key.name === "j" || key.name === "down")
+      return setCursorId(rows[Math.min(cursorIndex + 1, rows.length - 1)]!.id);
+    if (key.name === "k" || key.name === "up")
+      return setCursorId(rows[Math.max(cursorIndex - 1, 0)]!.id);
+    const row = rows[cursorIndex];
+
+    if (!row) return;
+    if (key.name === "return" || key.name === "enter")
+      return row.isFolder ? toggle(row.id) : onSelectFile(row.id, true);
+    if (key.name === "l" && row.isFolder && !expandedIds.has(row.id)) return toggle(row.id);
+    if (key.name === "h" && row.isFolder && expandedIds.has(row.id)) return toggle(row.id);
+  });
+
+  useEffect(() => {
+    let cancelled = false;
+    let requestInFlight = false;
+
+    const refreshFiles = async (): Promise<void> => {
+      if (requestInFlight) return;
+      requestInFlight = true;
+
+      try {
+        const files = await loadLatestFiles();
+
+        if (!cancelled) {
+          setPaths((previous) =>
+            previous?.length === files.length &&
+            previous.every((path, index) => path === files[index])
+              ? previous
+              : files,
+          );
+        }
+      } catch {
+        if (!cancelled) setPaths((previous) => previous ?? []);
+      } finally {
+        requestInFlight = false;
+      }
+    };
+
+    void refreshFiles();
+    const timer = setInterval(() => void refreshFiles(), PROJECT_FILES_REFRESH_MS);
+
+    return () => {
+      cancelled = true;
+      clearInterval(timer);
+    };
+  }, []);
+
+  if (paths === null) {
+    return (
+      <box
+        style={{
+          flexGrow: 1,
+          flexDirection: "column",
+          alignItems: "center",
+          justifyContent: "center",
+        }}
+      >
+        <text fg={tokens.textDim}>loading...</text>
+      </box>
+    );
+  }
+  if (paths.length === 0) {
+    return (
+      <box
+        style={{
+          flexGrow: 1,
+          flexDirection: "column",
+          alignItems: "center",
+          justifyContent: "center",
+        }}
+      >
+        <text fg={tokens.textDim}>empty</text>
+      </box>
+    );
+  }
+
+  return (
+    <ScrollArea
+      id="tree-scroll"
+      revealId={focused ? rows[cursorIndex]?.id : undefined}
+      gestureWheel
+    >
+      <Tree
+        nodes={nodes}
+        expandedIds={expandedIds}
+        selectedId={focused ? rows[cursorIndex]?.id : undefined}
+        singleLine
+        onSelect={(id) => {
+          setCursorId(id);
+          onSelectFile(id);
+        }}
+        onDoubleSelect={(id) => onSelectFile(id, true)}
+        onToggle={toggle}
+        theme={theme}
+      />
+    </ScrollArea>
+  );
+}

package/src/workbench/components/TreePane.stories.tsx

@@ -0,0 +1,106 @@
+import React from "react";
+import { DARK } from "../../appearance/theme";
+import type { Story, StoryMeta } from "../../stories/story";
+import { TreePane } from "./TreePane";
+import type { TreeRow } from "../../thread/tree-view";
+
+export const meta: StoryMeta = { title: "Surfaces/TreePane" };
+
+const callbacks = {
+  onSelect: () => {},
+  onGo: () => {},
+  onBranch: () => {},
+  onLabel: () => {},
+  onFork: () => {},
+  onForkAndShare: () => {},
+};
+
+/** rev1 -> comment (labelled, a branch hangs off it) -> the branch's comment -> rev2 as main's tip. */
+const ROWS: TreeRow[] = [
+  {
+    entryId: "e1",
+    depth: 0,
+    glyph: "◉",
+    text: "revision 1",
+    onPath: true,
+    tips: [],
+    isCurrentTip: false,
+  },
+  {
+    entryId: "e2",
+    depth: 0,
+    glyph: "·",
+    text: "comment",
+    onPath: true,
+    tips: [],
+    isCurrentTip: false,
+    label: "start",
+  },
+  {
+    entryId: "e3",
+    depth: 1,
+    glyph: "·",
+    text: "comment",
+    onPath: false,
+    tips: ["alt"],
+    isCurrentTip: false,
+  },
+  {
+    entryId: "e4",
+    depth: 0,
+    glyph: "◉",
+    text: "revision 2",
+    onPath: true,
+    tips: ["main"],
+    isCurrentTip: true,
+  },
+];
+
+/** The rail expects a height-constrained parent, like the app's main row. */
+function PaneFrame({ children }: { children: React.ReactNode }): React.ReactNode {
+  return (
+    <box
+      style={{ flexDirection: "column", width: 40, height: "100%", backgroundColor: DARK.panel }}
+    >
+      {children}
+    </box>
+  );
+}
+
+export const OwnerWithBranch: Story = {
+  render: () => (
+    <PaneFrame>
+      <TreePane rows={ROWS} selectedEntryId="e2" canMove canFork {...callbacks} />
+    </PaneFrame>
+  ),
+  expectedColors: [DARK.accent],
+  size: { width: 40, height: 16 },
+};
+
+export const CollaboratorReadsOnly: Story = {
+  render: () => (
+    <PaneFrame>
+      <TreePane rows={ROWS} canMove={false} canFork={false} {...callbacks} />
+    </PaneFrame>
+  ),
+  size: { width: 40, height: 16 },
+};
+
+/** A resolved review: the owner can still fork, not move. */
+export const ResolvedForkOnly: Story = {
+  render: () => (
+    <PaneFrame>
+      <TreePane rows={ROWS} canMove={false} canFork {...callbacks} />
+    </PaneFrame>
+  ),
+  size: { width: 40, height: 16 },
+};
+
+export const NoHistory: Story = {
+  render: () => (
+    <PaneFrame>
+      <TreePane rows={[]} canMove canFork {...callbacks} />
+    </PaneFrame>
+  ),
+  size: { width: 40, height: 8 },
+};

package/src/workbench/components/TreePane.tsx

@@ -0,0 +1,155 @@
+/**
+ * The rail's Tree tab: the session's history as one row per entry. The active
+ * path reads bright, everything else dim; a branch tip carries its name, the
+ * current tip a marker, a checkpoint its label. Clicking a row selects it,
+ * clicking the selected row goes there; the buttons underneath are the mouse
+ * path to the same primitives the option chords reach.
+ */
+
+import { ScrollArea } from "../../ui/components/ScrollArea";
+import React, { useEffect, useRef } from "react";
+import { createTextAttributes, type ScrollBoxRenderable } from "@opentui/core";
+import type { Theme } from "../../appearance/theme";
+import type { TreeRow } from "../../thread/tree-view";
+import { useComponentTheme } from "../../appearance/components/theme-context";
+import { Button } from "../../ui/components/primitives/Button";
+import { Toolbar } from "../../ui/components/primitives/Toolbar";
+
+export interface TreePaneProps {
+  rows: TreeRow[];
+  selectedEntryId?: string;
+  canMove: boolean;
+  canFork: boolean;
+  onSelect: (entryId: string) => void;
+  onGo: (entryId: string) => void;
+  onBranch: () => void;
+  onLabel: () => void;
+  onFork: () => void;
+  onForkAndShare: () => void;
+  theme?: Theme;
+}
+
+const DIM = createTextAttributes({ dim: true });
+const BOLD = createTextAttributes({ bold: true });
+
+/** The marker column: the current tip stands out, every other row keeps its kind's glyph. */
+function markerFor(row: TreeRow): string {
+  return row.isCurrentTip ? "●" : row.glyph;
+}
+
+/** What follows the entry's name: the branches whose tip it is, and its checkpoint. */
+function trailerFor(row: TreeRow): string {
+  const parts: string[] = [];
+
+  if (row.tips.length) parts.push(`← ${row.tips.join(", ")}`);
+  if (row.label !== undefined) parts.push(`⚑ ${row.label}`);
+
+  return parts.length ? `  ${parts.join("  ")}` : "";
+}
+
+export function TreePane({
+  rows,
+  selectedEntryId,
+  canMove,
+  canFork,
+  onSelect,
+  onGo,
+  onBranch,
+  onLabel,
+  onFork,
+  onForkAndShare,
+  theme,
+}: TreePaneProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const scrollRef = useRef<ScrollBoxRenderable | null>(null);
+  const revealId = selectedEntryId ?? rows.find((row) => row.isCurrentTip)?.entryId;
+
+  // the trunk draws last, so a long history opens with its tip below the fold: keep the row in view
+  useEffect(() => {
+    if (revealId === undefined) return;
+    try {
+      scrollRef.current?.scrollChildIntoView(`tree-row-${revealId}`);
+    } catch {
+      // reveal is best-effort; the selection is already correct
+    }
+  }, [revealId]);
+
+  if (rows.length === 0)
+    return (
+      <box style={{ flexGrow: 1, alignItems: "center", justifyContent: "center" }}>
+        <text fg={tokens.textDim}>no history yet</text>
+      </box>
+    );
+
+  return (
+    <box style={{ flexGrow: 1, flexDirection: "column" }}>
+      <ScrollArea scrollRef={scrollRef}>
+        {rows.map((row) => {
+          const selected = row.entryId === selectedEntryId;
+          const foreground = row.onPath ? tokens.text : tokens.textDim;
+
+          return (
+            <box
+              key={row.entryId}
+              id={`tree-row-${row.entryId}`}
+              style={{
+                flexDirection: "row",
+                paddingLeft: 1 + row.depth * 2,
+                backgroundColor: selected ? tokens.elevated : undefined,
+              }}
+              onMouseUp={() => (selected && canMove ? onGo(row.entryId) : onSelect(row.entryId))}
+            >
+              <text
+                fg={row.isCurrentTip ? tokens.accent : foreground}
+                attributes={row.onPath ? undefined : DIM}
+              >
+                {markerFor(row)} {row.text}
+              </text>
+              <text fg={tokens.textMuted} attributes={row.label === undefined ? undefined : BOLD}>
+                {trailerFor(row)}
+              </text>
+            </box>
+          );
+        })}
+      </ScrollArea>
+      {canMove || canFork ? (
+        <box style={{ paddingLeft: 1 }}>
+          <Toolbar>
+            {canMove ? (
+              <Button
+                onPress={() => {
+                  if (selectedEntryId !== undefined) onGo(selectedEntryId);
+                }}
+                isDisabled={selectedEntryId === undefined}
+                marginRight={1}
+                theme={theme}
+              >
+                Go
+              </Button>
+            ) : null}
+            {canMove ? (
+              <Button onPress={onBranch} marginRight={1} theme={theme}>
+                Branch
+              </Button>
+            ) : null}
+            {canMove ? (
+              <Button onPress={onLabel} marginRight={1} theme={theme}>
+                Label
+              </Button>
+            ) : null}
+            {canFork ? (
+              <Button onPress={onFork} marginRight={1} theme={theme}>
+                Fork
+              </Button>
+            ) : null}
+            {canFork ? (
+              <Button onPress={onForkAndShare} theme={theme}>
+                Fork+share
+              </Button>
+            ) : null}
+          </Toolbar>
+        </box>
+      ) : null}
+    </box>
+  );
+}

package/src/workbench/components/WelcomePlayground.stories.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import { DARK } from "../../appearance/theme";
+import type { Story, StoryMeta } from "../../stories/story";
+import { WelcomePlayground } from "./WelcomePlayground";
+
+export const meta: StoryMeta = { title: "Surfaces/WelcomePlayground" };
+
+export const Welcome: Story = {
+  render: () => <WelcomePlayground quickActions={[]} theme={DARK} />,
+  expectedColors: [DARK.textDim],
+  size: { width: 72, height: 20 },
+};