@cueloop/client 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/components/Tooltip.stories.tsx

@@ -0,0 +1,26 @@
+import React from "react";
+import { DARK } from "../theme";
+import type { Story, StoryMeta } from "./story";
+import { TooltipProvider } from "./Tooltip";
+import { IconButton } from "./primitives/IconButton";
+import { NERD } from "./primitives/icons";
+
+export const meta: StoryMeta = { title: "Layout/Tooltip" };
+
+// The tooltip surfaces only on hover, so a static story shows the provider wrapping a labelled control.
+export const HoverControl: Story = {
+  render: () => (
+    <TooltipProvider theme={DARK}>
+      <box style={{ flexDirection: "row", padding: 1, backgroundColor: DARK.panel }}>
+        <IconButton
+          glyph={NERD.sidebarRight}
+          tip="Toggle Right Sidebar"
+          onPress={() => {}}
+          theme={DARK}
+        />
+      </box>
+    </TooltipProvider>
+  ),
+  expectedColors: [DARK.textMuted],
+  size: { width: 40, height: 4 },
+};

package/src/components/Tooltip.tsx

@@ -0,0 +1,72 @@
+// Hover tooltips for the header controls. A tiny header cell clips its own children, so the label is
+// surfaced at the screen root instead: controls report the hovered label and cursor cell, and this layer
+// paints it one row below, nudged left when it would run past the right edge.
+
+import React, { createContext, useContext, useMemo, useState } from "react";
+import { useTerminalDimensions } from "@opentui/react";
+import { DARK, type Theme } from "../theme";
+
+interface TooltipTarget {
+  label: string;
+  x: number;
+  y: number;
+}
+
+interface TooltipApi {
+  showTooltip: (label: string, x: number, y: number) => void;
+  hideTooltip: () => void;
+}
+
+const TooltipContext = createContext<TooltipApi>({
+  showTooltip: () => {},
+  hideTooltip: () => {},
+});
+
+/** Report or clear the hovered control's tooltip; a no-op outside a TooltipProvider. */
+export function useTooltip(): TooltipApi {
+  return useContext(TooltipContext);
+}
+
+/** Wrap a shell so its header controls can surface hover tooltips at the screen root. */
+export function TooltipProvider({
+  theme,
+  children,
+}: {
+  theme?: Theme;
+  children: React.ReactNode;
+}): React.ReactNode {
+  const tokens = theme ?? DARK;
+  const { width, height } = useTerminalDimensions();
+  const [target, setTarget] = useState<TooltipTarget | null>(null);
+  const api = useMemo<TooltipApi>(
+    () => ({
+      showTooltip: (label, x, y) => setTarget({ label, x, y }),
+      hideTooltip: () => setTarget(null),
+    }),
+    [],
+  );
+
+  const boxWidth = target ? target.label.length + 2 : 0;
+  const left = target ? Math.max(0, Math.min(target.x, width - boxWidth)) : 0;
+  const top = target ? (target.y + 1 <= height - 1 ? target.y + 1 : Math.max(0, target.y - 1)) : 0;
+
+  return (
+    <TooltipContext.Provider value={api}>
+      {children}
+      {target ? (
+        <box
+          style={{
+            position: "absolute",
+            left,
+            top,
+            paddingLeft: 1,
+            paddingRight: 1,
+            backgroundColor: tokens.elevated,
+          }}
+        >
+          <text fg={tokens.text}>{target.label}</text>
+        </box>
+      ) : null}
+    </TooltipContext.Provider>
+  );
+}

package/src/components/TreePane.stories.tsx

@@ -0,0 +1,106 @@
+import React from "react";
+import { DARK } from "../theme";
+import type { Story, StoryMeta } from "./story";
+import { TreePane } from "./TreePane";
+import type { TreeRow } from "../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/components/TreePane.tsx

@@ -0,0 +1,157 @@
+/**
+ * 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 "./ScrollArea";
+import React, { useEffect, useRef } from "react";
+import { createTextAttributes, type ScrollBoxRenderable } from "@opentui/core";
+import type { Theme } from "../theme";
+import type { TreeRow } from "../tree-view";
+import { useComponentTheme } from "./theme-context";
+import { Button } from "./primitives/Button";
+import { Toolbar } from "./primitives/Toolbar";
+
+export interface TreePaneProps {
+  rows: TreeRow[];
+  selectedEntryId?: string;
+  /** The owner of an open review may move the tree; everyone else reads it. */
+  canMove: boolean;
+  /** The owner may fork, a resolved review included. */
+  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/components/WalkWizard.stories.tsx

@@ -0,0 +1,100 @@
+import React from "react";
+import { DARK } from "../theme";
+import type { WalkFile } from "../walk";
+import type { Story, StoryMeta } from "./story";
+import { WalkWizard } from "./WalkWizard";
+
+export const meta: StoryMeta = { title: "Overlays/WalkWizard" };
+
+const FILES: WalkFile[] = [
+  {
+    path: "packages/daemon/src/store.ts",
+    added: 12,
+    removed: 3,
+    preview: [
+      { sign: "+", text: "const viewed = new Set<string>();" },
+      { sign: "+", text: "record.viewedPaths = [...viewed];" },
+      { sign: "-", text: "// viewed tracking lives in the client only" },
+    ],
+  },
+  {
+    path: "packages/client/src/walk.ts",
+    added: 48,
+    removed: 0,
+    preview: [{ sign: "+", text: "export function firstUnviewedIndex(files, viewed) {" }],
+  },
+  {
+    path: "packages/schema/src/types.ts",
+    added: 3,
+    removed: 0,
+    preview: [{ sign: "+", text: "viewedPaths?: string[];" }],
+  },
+];
+
+const noop = (): void => {};
+
+export const FirstFile: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={0}
+      viewedPaths={new Set()}
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  // the main card wears the accent border; stats carry the +/- colors
+  expectedColors: [
+    DARK.accent,
+    DARK.green,
+    DARK.red,
+    DARK.insertedForeground,
+    DARK.deletedForeground,
+  ],
+};
+
+export const WithAgentNote: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={1}
+      viewedPaths={new Set(["packages/daemon/src/store.ts"])}
+      note="New module: pure helpers that pick the next unviewed file. No IO, unit tested."
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  // the agent-note block wears the plain gray border token, not the accent
+  expectedColors: [DARK.accent, DARK.border, DARK.textMuted],
+};
+
+export const EndCard: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={3}
+      viewedPaths={new Set(FILES.map((file) => file.path))}
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  // the end card wears the green border and the solid submit button
+  expectedColors: [DARK.green, DARK.accent, DARK.accentInk],
+};
+
+export const EndCardPartialPass: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={3}
+      viewedPaths={new Set(["packages/daemon/src/store.ts"])}
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  expectedColors: [DARK.green],
+};

package/src/components/WalkWizard.tsx

@@ -0,0 +1,152 @@
+/**
+ * The guided walk's focused card wizard: one card per changed file
+ * floating over the dimmed diff, with a plain step count in the title - no
+ * progress bar. Below the main card a separate gray-bordered block carries
+ * the submitting agent's note for the file, when one exists. Past the last
+ * file the end card offers the submit action directly with honest counts.
+ * The keys live in the keymap's walk overlay; this component only renders.
+ */
+
+import React from "react";
+import type { Theme } from "../theme";
+import { useComponentTheme } from "./theme-context";
+import type { WalkFile } from "../walk";
+import { viewedCount } from "../walk";
+import { Card } from "./primitives/Card";
+import { Button } from "./primitives/Button";
+import { Toolbar } from "./primitives/Toolbar";
+
+export interface WalkWizardProps {
+  files: WalkFile[];
+  /** The wizard step; index === files.length renders the end card. */
+  index: number;
+  viewedPaths: ReadonlySet<string>;
+  /** The agent's note for the current file; the gray block renders only when set. */
+  note?: string;
+  /** Terminal width bounds the card width. */
+  terminalWidth: number;
+  /** End-card submit: leaves the walk and opens the rail confirm. */
+  onSubmitRequest: () => void;
+  onBack: () => void;
+  theme?: Theme;
+}
+
+/** The card never crowds the terminal edge nor stretches past reading width. */
+function wizardWidth(terminalWidth: number): number {
+  return Math.min(72, Math.max(24, terminalWidth - 8));
+}
+
+/** Note rows from a crude wrap estimate, capped so the block stays a block. */
+function noteRows(note: string, innerWidth: number): number {
+  return Math.min(3, Math.max(1, Math.ceil(note.length / Math.max(1, innerWidth))));
+}
+
+export function WalkWizard({
+  files,
+  index,
+  viewedPaths,
+  note,
+  terminalWidth,
+  onSubmitRequest,
+  onBack,
+  theme,
+}: WalkWizardProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const width = wizardWidth(terminalWidth);
+  const viewed = viewedCount(files, viewedPaths);
+  const atEnd = index >= files.length;
+  const currentFile = files[index];
+
+  return (
+    <box
+      style={{
+        position: "absolute",
+        left: 0,
+        top: 0,
+        width: "100%",
+        height: "100%",
+        alignItems: "center",
+        justifyContent: "center",
+        flexDirection: "column",
+      }}
+    >
+      <box style={{ width, flexDirection: "column" }}>
+        {atEnd || !currentFile ? (
+          <Card
+            title=" walk complete "
+            contentRows={3}
+            borderColor={tokens.green}
+            backgroundColor={tokens.elevated}
+            theme={theme}
+          >
+            <text fg={tokens.text}>
+              {viewed === files.length
+                ? `every file viewed (${viewed}/${files.length})`
+                : `${viewed} of ${files.length} files viewed`}
+            </text>
+            <box style={{ height: 1 }} />
+            <Toolbar>
+              <Button variant="solid" marginRight={2} onPress={onSubmitRequest} theme={theme}>
+                {" Submit review "}
+              </Button>
+              <Button onPress={onBack} theme={theme}>
+                {" [ back "}
+              </Button>
+            </Toolbar>
+          </Card>
+        ) : (
+          <>
+            <Card
+              title={` file ${index + 1} of ${files.length} · ${viewed} viewed `}
+              contentRows={3 + Math.max(1, currentFile.preview.length)}
+              borderColor={tokens.accent}
+              backgroundColor={tokens.elevated}
+              theme={theme}
+            >
+              <text fg={tokens.text}>{currentFile.path}</text>
+              <text>
+                <span fg={tokens.green}>{`+${currentFile.added}`}</span>
+                <span fg={tokens.textDim}> </span>
+                <span fg={tokens.red}>{`-${currentFile.removed}`}</span>
+                <span fg={tokens.textDim}>
+                  {viewedPaths.has(currentFile.path) ? " · viewed" : ""}
+                </span>
+              </text>
+              <box style={{ height: 1 }} />
+              {currentFile.preview.length === 0 ? (
+                <text fg={tokens.textDim}>(no changed lines)</text>
+              ) : (
+                currentFile.preview.map((previewLine, previewIndex) => (
+                  <text
+                    key={previewIndex}
+                    style={{ wrapMode: "none" }}
+                    fg={
+                      previewLine.sign === "+"
+                        ? tokens.insertedForeground
+                        : tokens.deletedForeground
+                    }
+                  >
+                    {previewLine.sign + previewLine.text}
+                  </text>
+                ))
+              )}
+            </Card>
+            {note !== undefined ? (
+              <box style={{ marginTop: 1, flexDirection: "column" }}>
+                <Card
+                  title=" agent note "
+                  contentRows={noteRows(note, width - 4)}
+                  borderColor={tokens.border}
+                  backgroundColor={tokens.elevated}
+                  theme={theme}
+                >
+                  <text fg={tokens.textMuted}>{note}</text>
+                </Card>
+              </box>
+            ) : null}
+          </>
+        )}
+      </box>
+    </box>
+  );
+}

package/src/components/WelcomePlayground.stories.tsx

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

package/src/components/WelcomePlayground.test.tsx

@@ -0,0 +1,47 @@
+/**
+ * The welcome page is a real annotation surface, but ephemeral: selecting its copy and typing leaves
+ * a comment that shows inline, exactly as a file does, and it lives only in the component - there is
+ * no controller or daemon behind it, so nothing is persisted. The copy prompts the two first gestures.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { testRender } from "@opentui/react/test-utils";
+import React from "react";
+import { WelcomePlayground } from "./WelcomePlayground";
+import { DARK } from "../theme";
+import { dragText, typeText, pressKey, waitForText } from "../test-support";
+
+describe("WelcomePlayground", () => {
+  test("the copy prompts the select-and-type and the slash gestures", async () => {
+    const setup = await testRender(
+      <WelcomePlayground version="1.2.3" quickActions={[]} theme={DARK} />,
+      { width: 80, height: 24 },
+    );
+
+    await waitForText(setup, "Getting started");
+    const frame = setup.captureCharFrame();
+
+    expect(frame).toContain("start typing to leave your first comment");
+    expect(frame).toContain('type "/"');
+
+    setup.renderer.destroy();
+  });
+
+  test("selecting the copy and typing leaves a comment inline, exactly like a file", async () => {
+    const setup = await testRender(
+      <WelcomePlayground version="1.2.3" quickActions={[]} theme={DARK} />,
+      { width: 80, height: 24 },
+    );
+
+    // Act - select the practice line, type a comment, send it
+    await waitForText(setup, "quick brown fox");
+    await dragText(setup, "quick brown fox", "quick brown fox", "quick brown fox".length);
+    await typeText(setup, "my first note");
+    await pressKey(setup, "RETURN", { meta: true });
+
+    // Assert - the note renders on the surface, no controller or daemon involved
+    await waitForText(setup, "my first note");
+
+    setup.renderer.destroy();
+  });
+});