@cueloop/client 0.1.0-alpha.65 → 0.1.0-alpha.67

package/src/components/session-tree.ts

@@ -0,0 +1,108 @@
+/**
+ * Groups the pending inbox into Projects and Threads for the sidebar. Threads
+ * whose workspace carries a rootCommit gather under their project (keyed by that
+ * commit, so moving or re-cloning the repo never forks it); the rest are
+ * standalone Threads. The flat `ordered` sequence is what the inbox cursor
+ * walks, so the keyboard grammar keeps a single index across the two groups.
+ */
+
+import type { ReviewSession, WorkspaceKey } from "@cueloop/schema";
+
+/** A repo's display name: the remote basename when present, else the working-tree folder name. */
+export function projectName(workspace: WorkspaceKey): string {
+  const { remote, repoRoot } = workspace;
+
+  if (remote !== undefined) {
+    const cleaned = remote.replace(/\.git$/, "").replace(/\/+$/, "");
+    const base = cleaned
+      .split(/[/:]/)
+      .filter((part) => part.length > 0)
+      .at(-1);
+    if (base !== undefined) return base;
+  }
+
+  const dir = repoRoot
+    .replace(/\/+$/, "")
+    .split("/")
+    .filter((part) => part.length > 0)
+    .at(-1);
+
+  return dir ?? repoRoot;
+}
+
+export type InboxRow =
+  | { kind: "section"; id: string; label: string }
+  | { kind: "project"; id: string; label: string }
+  | { kind: "thread"; id: string; session: ReviewSession; selectionIndex: number };
+
+export interface GroupedInbox {
+  rows: InboxRow[];
+  /** Threads in display order; the inbox cursor indexes this. */
+  ordered: ReviewSession[];
+}
+
+function threadTitle(session: ReviewSession): string {
+  return session.artifact.meta.title ?? session.id;
+}
+
+interface ProjectGroup {
+  name: string;
+  sessions: ReviewSession[];
+}
+
+/** Group pending sessions into Pinned, then Projects (by root commit), then standalone Threads. */
+export function groupInbox(
+  sessions: readonly ReviewSession[],
+  pinnedIds?: ReadonlySet<string>,
+): GroupedInbox {
+  const pinned: ReviewSession[] = [];
+  const projects = new Map<string, ProjectGroup>();
+  const standalone: ReviewSession[] = [];
+
+  for (const session of sessions) {
+    if (pinnedIds?.has(session.id) === true) {
+      pinned.push(session);
+      continue;
+    }
+
+    const key = session.workspace.rootCommit;
+    if (key === undefined) {
+      standalone.push(session);
+      continue;
+    }
+
+    const existing = projects.get(key);
+    if (existing !== undefined) existing.sessions.push(session);
+    else projects.set(key, { name: projectName(session.workspace), sessions: [session] });
+  }
+
+  const rows: InboxRow[] = [];
+  const ordered: ReviewSession[] = [];
+  const pushThread = (session: ReviewSession): void => {
+    rows.push({ kind: "thread", id: session.id, session, selectionIndex: ordered.length });
+    ordered.push(session);
+  };
+
+  if (pinned.length > 0) {
+    rows.push({ kind: "section", id: "section:pinned", label: "Pinned" });
+    for (const session of pinned) pushThread(session);
+  }
+
+  const projectEntries = [...projects.entries()].sort((a, b) => a[1].name.localeCompare(b[1].name));
+  if (projectEntries.length > 0) {
+    rows.push({ kind: "section", id: "section:projects", label: "Projects" });
+    for (const [key, project] of projectEntries) {
+      rows.push({ kind: "project", id: `project:${key}`, label: project.name });
+      for (const session of project.sessions) pushThread(session);
+    }
+  }
+
+  if (standalone.length > 0) {
+    rows.push({ kind: "section", id: "section:threads", label: "Threads" });
+    for (const session of standalone) pushThread(session);
+  }
+
+  return { rows, ordered };
+}
+
+export { threadTitle };

package/src/components/stories-app.tsx

@@ -1,109 +1,169 @@
 /**
- * The interactive stories catalog (`bun run stories`): a left list of
- * component modules (j/k), h/l cycling through the module's stories, and the
+ * The interactive stories catalog (`bun run stories`): a nested tree of
+ * component modules on the left (j/k to move, h/l to fold or open) and the
  * selected story rendered live in the preview pane. The same story objects
  * back the snapshot harness - what this TUI shows is what the tests assert.
  */
 
-import React, { useMemo, useState } from "react";
-import { createCliRenderer } from "@opentui/core";
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { createCliRenderer, type ScrollBoxRenderable } from "@opentui/core";
 import { createRoot, useKeyboard } from "@opentui/react";
 import { DARK } from "../theme";
 import { ThemeProvider } from "./theme-context";
-import { loadStories, type LoadedStory } from "./story";
-import { FRAME_BORDER_STYLE } from "./primitives/frame";
+import { buildStoryTree, loadStories, type LoadedStory } from "./story";
+import { PaneGrid } from "./PaneGrid";
+import { ShellHeader } from "./ShellHeader";
+import { Tree } from "./primitives/Tree";
+import { NERD } from "./primitives/icons";
+import { allFolderIds, flattenTree } from "./primitives/tree-model";
 
-function StoriesApp({
-  stories,
-  onExit,
-}: {
+interface StoriesAppProps {
   stories: LoadedStory[];
   onExit: () => void;
-}): React.ReactNode {
-  const moduleTitles = useMemo(
-    () => [...new Set(stories.map((story) => story.moduleTitle))],
+}
+
+function StoriesApp({ stories, onExit }: StoriesAppProps): React.ReactNode {
+  const treeNodes = useMemo(() => buildStoryTree(stories), [stories]);
+  const storiesById = useMemo(
+    () => new Map(stories.map((story) => [`${story.moduleTitle}/${story.storyName}`, story])),
     [stories],
   );
-  const [moduleIndex, setModuleIndex] = useState(0);
-  const [storyIndex, setStoryIndex] = useState(0);
-  const moduleTitle = moduleTitles[moduleIndex]!;
-  const moduleStories = stories.filter((story) => story.moduleTitle === moduleTitle);
-  const current = moduleStories[Math.min(storyIndex, moduleStories.length - 1)]!;
+  const firstStoryId = `${stories[0]!.moduleTitle}/${stories[0]!.storyName}`;
+
+  const [expandedIds, setExpandedIds] = useState<ReadonlySet<string>>(() =>
+    allFolderIds(treeNodes),
+  );
+  const [selectedId, setSelectedId] = useState(firstStoryId);
+  const [openedId, setOpenedId] = useState(firstStoryId);
+  const [treeOpen, setTreeOpen] = useState(true);
+
+  const rows = flattenTree(treeNodes, { expandedIds });
+  const selectedRow = rows.find((row) => row.id === selectedId) ?? rows[0];
+  const opened = storiesById.get(openedId);
+  const sidebarScroll = useRef<ScrollBoxRenderable | null>(null);
+
+  // keep the moving selection inside the scrolled viewport
+  useEffect(() => {
+    try {
+      sidebarScroll.current?.scrollChildIntoView(`tree-row-${selectedId}`);
+    } catch {
+      // reveal is best-effort; the selection state is already correct
+    }
+  }, [selectedId]);
+
+  const openStory = (id: string): void => {
+    if (storiesById.has(id)) setOpenedId(id);
+  };
+
+  const toggleFolder = (id: string): void => {
+    setExpandedIds((current) => {
+      const next = new Set(current);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+
+      return next;
+    });
+  };
+
+  const expandFolder = (id: string): void => {
+    setExpandedIds((current) => new Set(current).add(id));
+  };
+
+  const collapseFolder = (id: string): void => {
+    setExpandedIds((current) => {
+      const next = new Set(current);
+      next.delete(id);
+
+      return next;
+    });
+  };
+
+  const moveSelection = (delta: number): void => {
+    const index = rows.findIndex((row) => row.id === selectedId);
+    const nextIndex = Math.max(0, Math.min(rows.length - 1, index + delta));
+    const nextRow = rows[nextIndex];
+    if (nextRow !== undefined) setSelectedId(nextRow.id);
+  };
 
   useKeyboard((key) => {
     if (key.name === "q") onExit();
-    else if (key.name === "j" || key.name === "down") {
-      setModuleIndex((index) => Math.min(moduleTitles.length - 1, index + 1));
-      setStoryIndex(0);
-    } else if (key.name === "k" || key.name === "up") {
-      setModuleIndex((index) => Math.max(0, index - 1));
-      setStoryIndex(0);
-    } else if (key.name === "l" || key.name === "right") {
-      setStoryIndex((index) => (index + 1) % moduleStories.length);
+    else if (key.name === "j" || key.name === "down") moveSelection(1);
+    else if (key.name === "k" || key.name === "up") moveSelection(-1);
+    else if (selectedRow === undefined) return;
+    else if (key.name === "l" || key.name === "right") {
+      if (selectedRow.isFolder) expandFolder(selectedRow.id);
+      else openStory(selectedRow.id);
     } else if (key.name === "h" || key.name === "left") {
-      setStoryIndex((index) => (index - 1 + moduleStories.length) % moduleStories.length);
+      if (selectedRow.isFolder) collapseFolder(selectedRow.id);
+    } else if (key.name === "return" || key.name === "space") {
+      if (selectedRow.isFolder) toggleFolder(selectedRow.id);
+      else openStory(selectedRow.id);
     }
   });
 
   return (
     <ThemeProvider theme={DARK}>
-      <box
-        style={{
-          flexDirection: "column",
-          width: "100%",
-          height: "100%",
-          backgroundColor: DARK.background,
-        }}
-      >
-        <box style={{ height: 1, backgroundColor: DARK.panel, paddingLeft: 1 }}>
-          <text fg={DARK.text}>
-            <span fg={DARK.accent}>cueloop stories</span>
-            <span fg={DARK.textDim}>
-              {" "}
-              · {moduleTitle} / {current.storyName}
-            </span>
-          </text>
-        </box>
-        <box style={{ flexDirection: "row", flexGrow: 1 }}>
-          <box
-            style={{
-              width: 28,
-              backgroundColor: DARK.panel,
-              flexDirection: "column",
-              paddingLeft: 1,
-              paddingTop: 1,
-            }}
-          >
-            {moduleTitles.map((title, index) => (
-              <text key={title} fg={index === moduleIndex ? DARK.accent : DARK.textMuted}>
-                {index === moduleIndex ? "▸ " : "  "}
-                {title}
-              </text>
-            ))}
-          </box>
-          <box
-            style={{
-              flexGrow: 1,
-              flexDirection: "column",
-              border: true,
-              borderStyle: FRAME_BORDER_STYLE,
-              borderColor: DARK.border,
-            }}
-            title={` ${current.storyName} (${moduleStories.indexOf(current) + 1}/${moduleStories.length}) `}
-          >
-            {/* remount per story so component-local state never leaks across */}
-            <box
-              key={`${moduleTitle}/${current.storyName}`}
-              style={{ flexGrow: 1, flexDirection: "column" }}
-            >
-              {current.story.render()}
+      <PaneGrid
+        theme={DARK}
+        mainHeader={
+          <ShellHeader
+            theme={DARK}
+            leftIcons={[{ glyph: NERD.settings }]}
+            leftLabel="cueloop storybook"
+            inspectorOpen={treeOpen}
+            onToggleInspector={treeOpen ? undefined : () => setTreeOpen(true)}
+          />
+        }
+        inspectorHeader={
+          <ShellHeader
+            theme={DARK}
+            inspectorOpen={treeOpen}
+            onToggleInspector={() => setTreeOpen(false)}
+          />
+        }
+        main={
+          opened !== undefined ? (
+            <scrollbox style={{ flexGrow: 1, paddingLeft: 1, paddingTop: 1 }} focused={false}>
+              {/* remount per story so component-local state never leaks across */}
+              <box key={openedId} style={{ flexDirection: "column" }}>
+                {opened.story.render()}
+              </box>
+            </scrollbox>
+          ) : (
+            <box style={{ flexGrow: 1, paddingLeft: 1, paddingTop: 1 }}>
+              <text fg={DARK.textDim}>Select a story</text>
+            </box>
+          )
+        }
+        inspectorWidth={34}
+        inspector={
+          treeOpen ? (
+            <box style={{ flexDirection: "column", flexGrow: 1, paddingTop: 1 }}>
+              <scrollbox ref={sidebarScroll} style={{ flexGrow: 1 }} focused={false}>
+                <Tree
+                  nodes={treeNodes}
+                  expandedIds={expandedIds}
+                  selectedId={selectedId}
+                  theme={DARK}
+                  onSelect={(id) => {
+                    setSelectedId(id);
+                    openStory(id);
+                  }}
+                  onToggle={(id) => {
+                    setSelectedId(id);
+                    toggleFolder(id);
+                  }}
+                />
+              </scrollbox>
             </box>
+          ) : undefined
+        }
+        footer={
+          <box style={{ height: 1, paddingLeft: 1 }}>
+            <text fg={DARK.textDim}>j/k move · h/l fold or open · enter open · q quit</text>
           </box>
-        </box>
-        <box style={{ height: 1, backgroundColor: DARK.panel, paddingLeft: 1 }}>
-          <text fg={DARK.textDim}>j/k component · h/l story · q quit</text>
-        </box>
-      </box>
+        }
+      />
     </ThemeProvider>
   );
 }

package/src/components/story-tree.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+import { buildStoryTree, type LoadedStory } from "./story";
+import type { TreeNode } from "./primitives/tree-model";
+
+/** A story object whose render is never invoked in these structural tests. */
+const STUB = { render: () => null };
+
+function story(moduleTitle: string, storyName: string): LoadedStory {
+  return { moduleTitle, storyName, story: STUB };
+}
+
+function childLabels(node: TreeNode): string[] {
+  return (node.children ?? []).map((child) => child.label);
+}
+
+describe("buildStoryTree", () => {
+  test("splits moduleTitle on / into nested folders keyed by their path", () => {
+    // Arrange
+    const stories = [story("Primitives/Tree", "Default"), story("Layout/AppShell", "Default")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+
+    // Assert
+    expect(tree.map((node) => [node.id, node.label])).toEqual([
+      ["Primitives", "Primitives"],
+      ["Layout", "Layout"],
+    ]);
+    expect(tree[0]!.children!.map((node) => node.id)).toEqual(["Primitives/Tree"]);
+  });
+
+  test("groups sibling components under one shared parent folder", () => {
+    // Arrange
+    const stories = [story("Primitives/Tree", "Default"), story("Primitives/Card", "Default")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+
+    // Assert
+    expect(tree).toHaveLength(1);
+    expect(childLabels(tree[0]!)).toEqual(["Tree", "Card"]);
+  });
+
+  test("nests to the full depth of the moduleTitle path", () => {
+    // Arrange
+    const stories = [story("A/B/C", "Only")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const a = tree[0]!;
+    const b = a.children![0]!;
+
+    // Assert
+    expect([a.id, b.id]).toEqual(["A", "A/B"]);
+    expect(b.children![0]!.id).toBe("A/B/C");
+  });
+
+  test("adds each story as a leaf keyed `${moduleTitle}/${storyName}` under its component", () => {
+    // Arrange
+    const stories = [story("Primitives/Tree", "Empty"), story("Primitives/Tree", "Deep")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const component = tree[0]!.children![0]!;
+
+    // Assert
+    expect(component.id).toBe("Primitives/Tree");
+    expect(component.children!.map((leaf) => [leaf.id, leaf.label])).toEqual([
+      ["Primitives/Tree/Empty", "Empty"],
+      ["Primitives/Tree/Deep", "Deep"],
+    ]);
+  });
+
+  test("hoists a component with a single story of its own name into one leaf row", () => {
+    // Arrange
+    const stories = [story("Primitives/Card", "Card")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const hoisted = tree[0]!.children![0]!;
+
+    // Assert
+    expect(hoisted.children).toBeUndefined();
+    expect(hoisted.id).toBe("Primitives/Card/Card");
+    expect(hoisted.label).toBe("Card");
+  });
+
+  test("keeps the folder when its single story differs from the component name", () => {
+    // Arrange
+    const stories = [story("Primitives/Card", "Default")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const component = tree[0]!.children![0]!;
+
+    // Assert
+    expect(component.id).toBe("Primitives/Card");
+    expect(component.children!.map((leaf) => leaf.id)).toEqual(["Primitives/Card/Default"]);
+  });
+});

package/src/components/story.ts

@@ -7,6 +7,7 @@
  */
 
 import type React from "react";
+import type { TreeNode } from "./primitives/tree-model";
 
 export interface StoryMeta {
   /** Catalog path, e.g. "primitives/Card". */
@@ -68,6 +69,60 @@ export async function loadStories(): Promise<LoadedStory[]> {
   return loaded;
 }
 
+/** A folder node keeps its children array live so the builder can append to it. */
+interface StoryTreeFolder extends TreeNode {
+  children: TreeNode[];
+}
+
+// A component folder holding one story of its own name reads as one row, not a folder wrapping a single leaf.
+function hoistSingleStoryFolders(nodes: TreeNode[]): TreeNode[] {
+  return nodes.map((node) => {
+    if (node.children === undefined) return node;
+    const children = hoistSingleStoryFolders(node.children);
+    const onlyChild = children.length === 1 ? children[0] : undefined;
+    if (
+      onlyChild !== undefined &&
+      onlyChild.children === undefined &&
+      onlyChild.label === node.label
+    ) {
+      return onlyChild;
+    }
+
+    return { ...node, children };
+  });
+}
+
+/**
+ * Nest the flat catalog into folder/component groups by splitting each
+ * moduleTitle on "/". Each story becomes a leaf keyed `${moduleTitle}/${storyName}`
+ * under its component node; a component holding a single story of its own name
+ * collapses so its row IS that story leaf.
+ */
+export function buildStoryTree(stories: LoadedStory[]): TreeNode[] {
+  const roots: TreeNode[] = [];
+  const foldersByPath = new Map<string, StoryTreeFolder>();
+
+  for (const { moduleTitle, storyName } of stories) {
+    let siblings = roots;
+    let path = "";
+
+    for (const segment of moduleTitle.split("/")) {
+      path = path === "" ? segment : `${path}/${segment}`;
+      let folder = foldersByPath.get(path);
+      if (folder === undefined) {
+        folder = { id: path, label: segment, children: [] };
+        foldersByPath.set(path, folder);
+        siblings.push(folder);
+      }
+      siblings = folder.children;
+    }
+
+    siblings.push({ id: `${moduleTitle}/${storyName}`, label: storyName });
+  }
+
+  return hoistSingleStoryFolders(roots);
+}
+
 /** Component files that must carry stories: every .tsx that is not a story/test/prototype. */
 export function componentFilesMissingStories(): string[] {
   const componentGlob = new Bun.Glob("**/*.tsx");

package/src/components/theme-context.stories.tsx

@@ -4,7 +4,7 @@ import type { Story, StoryMeta } from "./story";
 import { ThemeProvider } from "./theme-context";
 import { Card } from "./primitives/Card";
 
-export const meta: StoryMeta = { title: "theme-context" };
+export const meta: StoryMeta = { title: "Foundations/Theme" };
 
 /** A high-contrast variant to prove tokens flow through the provider. */
 const HIGH_CONTRAST: Theme = { ...DARK, accent: "#00ffff", elevated: "#000000", border: "#ffffff" };

package/src/config.test.ts

@@ -8,14 +8,12 @@ import {
   actionFor,
   loadConfig,
   persistAuthorName,
-  persistReviewState,
   persistActions,
-  persistReviewWidth,
+  persistPins,
   persistTheme,
   quickActionBody,
   resolveQuickAction,
 } from "./config";
-import { REVIEW_DEFAULT_WIDTH, REVIEW_MAX_WIDTH } from "./review-panel";
 import { DARK } from "./theme";
 import { themeForName } from "./theme-presets";
 
@@ -128,48 +126,19 @@ describe("loadConfig", () => {
     }
   });
 
-  test("[ui] review panel defaults to an expanded rail at the default width", () => {
-    // Act
-    const config = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
-
-    // Assert
-    expect(config.ui.reviewState).toBe("expanded");
-    expect(config.ui.reviewWidth).toBe(REVIEW_DEFAULT_WIDTH);
-  });
-
-  test("[ui] parses review_width (clamped) and review_state", () => {
-    // Arrange
-    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg6-"));
-    const path = join(dir, "config.toml");
-
-    writeFileSync(path, `[ui]\nreview_width = 999\nreview_state = "compact"\n`);
-
-    try {
-      // Act
-      const config = loadConfig({ userConfigPath: path });
-
-      // Assert
-      expect(config.ui.reviewWidth).toBe(REVIEW_MAX_WIDTH); // out-of-range width clamps
-      expect(config.ui.reviewState).toBe("compact");
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  test("[ui] ignores an unknown review_state and a non-numeric width", () => {
+  test("[ui] diff_view defaults to unified and parses split", () => {
     // Arrange
-    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg7-"));
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg-diff-"));
     const path = join(dir, "config.toml");
 
-    writeFileSync(path, `[ui]\nreview_width = "wide"\nreview_state = "sideways"\n`);
+    writeFileSync(path, `[ui]\ndiff_view = "split"\n`);
 
     try {
-      // Act
-      const config = loadConfig({ userConfigPath: path });
-
       // Assert
-      expect(config.ui.reviewWidth).toBe(REVIEW_DEFAULT_WIDTH);
-      expect(config.ui.reviewState).toBe("expanded");
+      expect(loadConfig({ userConfigPath: "/nonexistent/config.toml" }).ui.diffView).toBe(
+        "unified",
+      );
+      expect(loadConfig({ userConfigPath: path }).ui.diffView).toBe("split");
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -288,28 +257,30 @@ describe("loadConfig", () => {
     }
   });
 
-  test("persistReviewWidth and persistReviewState round-trip through the config file", () => {
+  test("persistPins round-trips the pinned-thread ids through the config file", () => {
     // Arrange
-    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg8-"));
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg-pins-"));
     const path = join(dir, "config.toml");
 
     try {
       // Act
-      persistReviewWidth(42, path);
-      persistReviewState("hidden", path);
+      persistPins(["s_one", "s_two"], path);
 
       // Assert
-      const config = loadConfig({ userConfigPath: path });
+      expect(loadConfig({ userConfigPath: path }).ui.pins).toEqual(["s_one", "s_two"]);
 
-      expect(config.ui.reviewWidth).toBe(42);
-      expect(config.ui.reviewState).toBe("hidden");
+      // unpinning rewrites the list in place, including down to empty
+      // Act
+      persistPins(["s_two"], path);
+
+      // Assert
+      expect(loadConfig({ userConfigPath: path }).ui.pins).toEqual(["s_two"]);
 
-      // a second write replaces the key in place rather than appending a duplicate
       // Act
-      persistReviewWidth(30, path);
+      persistPins([], path);
 
       // Assert
-      expect(loadConfig({ userConfigPath: path }).ui.reviewWidth).toBe(30);
+      expect(loadConfig({ userConfigPath: path }).ui.pins).toEqual([]);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }