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

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 { AppShell } from "./AppShell";
+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()}
+      <AppShell
+        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/diff-hunk-curate.ts

@@ -13,16 +13,12 @@
  * the stored git patch and the model split hunks differently.
  */
 
-import { parseDiffFromFile, diffAcceptRejectHunk, type FileDiffMetadata } from "@pierre/diffs";
-import { unifiedDiffText, type DiffFileContents, type DiffFileStatus } from "@cueloop/schema";
+import type { FileDiffMetadata } from "@pierre/diffs";
+import type { HunkRejection } from "@cueloop/schema";
 import type { DiffRow } from "./view-diff";
 
-/** One reject decision; `changeIndex` absent rejects the whole hunk. */
-export interface HunkRejection {
-  path: string;
-  hunkIndex: number;
-  changeIndex?: number;
-}
+export { curateDiff, parseFileDiff } from "@cueloop/daemon/curate";
+export type { HunkRejection } from "@cueloop/schema";
 
 /** Which side of the diff a line number addresses. */
 type DiffSide = "addition" | "deletion";
@@ -34,24 +30,6 @@ export interface LocatedLine {
   changeIndex?: number;
 }
 
-/**
- * Context lines around each change. Matching git's default (3) makes the model
- * split hunks like the rendered working-tree patch does; git's coalescing can
- * still merge adjacent hunks differently, but the row is mapped by absolute line
- * number (not by counting hunks), so a whole-hunk reject can only ever span the
- * model hunk it lands in - never the wrong file or a crash.
- */
-const DIFF_CONTEXT = 3;
-
-/** Parse one file's full contents into a non-partial diff model. */
-export function parseFileDiff(file: DiffFileContents): FileDiffMetadata {
-  return parseDiffFromFile(
-    { name: file.path, contents: file.oldContents },
-    { name: file.path, contents: file.newContents },
-    { context: DIFF_CONTEXT },
-  );
-}
-
 /**
  * Resolve a 1-based file line on one side to its hunk and, when the line is
  * part of a change block, that block's `hunkContent` index.
@@ -173,81 +151,3 @@ export function isRowRejected(
       (rejection.changeIndex === undefined || rejection.changeIndex === located.changeIndex),
   );
 }
-
-/**
- * Apply one file's rejections and return its curated patch, or null when the
- * curated content equals the old content (every change rejected - no patch).
- * Whole-hunk rejections supersede change-level ones for the same hunk. Because
- * `diffAcceptRejectHunk` returns a model with the same hunk/content shape, the
- * indices stay valid across calls; they are applied high-to-low regardless, so
- * the order is deterministic.
- */
-function curateFilePatch(file: DiffFileContents, rejections: HunkRejection[]): string | null {
-  let model = parseFileDiff(file);
-  const wholeHunks = new Set(
-    rejections
-      .filter((rejection) => rejection.changeIndex === undefined)
-      .map((rejection) => rejection.hunkIndex),
-  );
-
-  for (const hunkIndex of [...wholeHunks].sort((a, b) => b - a)) {
-    model = diffAcceptRejectHunk(model, hunkIndex, "reject");
-  }
-  const changeRejections = rejections
-    .filter(
-      (rejection) => rejection.changeIndex !== undefined && !wholeHunks.has(rejection.hunkIndex),
-    )
-    .sort((a, b) => b.hunkIndex - a.hunkIndex || b.changeIndex! - a.changeIndex!);
-
-  for (const rejection of changeRejections) {
-    model = diffAcceptRejectHunk(model, rejection.hunkIndex, {
-      type: "reject",
-      changeIndex: rejection.changeIndex!,
-    });
-  }
-  const curatedNew = model.additionLines.join("");
-
-  if (curatedNew === file.oldContents) return null;
-  const patch = unifiedDiffText(file.oldContents, curatedNew, file.path);
-
-  if (patch === null) return null;
-
-  return withFileStateHeaders(patch, file.path, file.status, curatedNew);
-}
-
-/**
- * Point the diff headers at /dev/null for a created or fully-deleted file so the
- * curated patch applies. git's status - not empty contents - decides existence,
- * so editing an existing empty file stays a modify; a deletion whose removals
- * were partly restored also falls back to a modify.
- */
-function withFileStateHeaders(
-  patch: string,
-  path: string,
-  status: DiffFileStatus,
-  curatedNew: string,
-): string {
-  if (status === "added") return patch.replace(`--- a/${path}`, "--- /dev/null");
-  if (status === "deleted" && curatedNew === "") {
-    return patch.replace(`+++ b/${path}`, "+++ /dev/null");
-  }
-
-  return patch;
-}
-
-/**
- * The curated unified-diff patch of the accepted changes across every file.
- * Files with no net change (unchanged, or with all changes rejected) drop out.
- */
-export function curateDiff(files: DiffFileContents[], rejections: HunkRejection[]): string {
-  const parts: string[] = [];
-
-  for (const file of files) {
-    const fileRejections = rejections.filter((rejection) => rejection.path === file.path);
-    const patch = curateFilePatch(file, fileRejections);
-
-    if (patch) parts.push(patch);
-  }
-
-  return parts.join("\n");
-}

package/src/index.ts

@@ -3,6 +3,7 @@ export { serveClient, type ServeHandle, type ServeOptions } from "./serve";
 export { App, type AppProps } from "./App";
 export {
   collaboratorAnnotations,
+  mergeFromShare,
   publishShare,
   pullShare,
   pushShare,