@stigmer/react 1.0.4 → 2.0.0

package/src/file-reference/FileReferenceChipList.tsx

@@ -0,0 +1,148 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link FileReferenceChipList}. */
+export interface FileReferenceChipListProps {
+  /** Workspace-relative file paths to display as reference chips. */
+  readonly refs: readonly string[];
+  /** Called when the user removes a file reference. */
+  readonly onRemove: (path: string) => void;
+  /** Disables the remove action on all chips. */
+  readonly disabled?: boolean;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Renders a horizontal list of workspace file-reference chips.
+ *
+ * Each chip shows the workspace-relative path (truncated) with a remove
+ * button. Unlike attachment chips, file references have no upload
+ * lifecycle — they are instant, lightweight "attention" signals.
+ *
+ * Designed to sit alongside {@link AttachmentChipList} in the composer's
+ * attachments zone. Usable standalone by platform builders who compose
+ * their own file-reference UI (headless-first, DD-003).
+ *
+ * All visual properties flow through `--stgm-*` tokens (DD-005).
+ *
+ * @example
+ * ```tsx
+ * function CustomComposer() {
+ *   const fileRefs = useFileReferences();
+ *
+ *   return (
+ *     <FileReferenceChipList
+ *       refs={fileRefs.refs}
+ *       onRemove={fileRefs.remove}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function FileReferenceChipList({
+  refs,
+  onRemove,
+  disabled,
+  className,
+}: FileReferenceChipListProps) {
+  if (refs.length === 0) return null;
+
+  return (
+    <div
+      className={cn("flex flex-wrap gap-1.5", className)}
+      role="list"
+      aria-label="Referenced workspace files"
+    >
+      {refs.map((path) => (
+        <FileReferenceChip
+          key={path}
+          path={path}
+          onRemove={() => onRemove(path)}
+          disabled={disabled}
+        />
+      ))}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Individual chip
+// ---------------------------------------------------------------------------
+
+function FileReferenceChip({
+  path,
+  onRemove,
+  disabled,
+}: {
+  readonly path: string;
+  readonly onRemove: () => void;
+  readonly disabled?: boolean;
+}) {
+  const filename = path.split("/").pop() ?? path;
+
+  return (
+    <span
+      role="listitem"
+      aria-label={`Referenced file: ${path}`}
+      title={path}
+      className="inline-flex max-w-[200px] items-center gap-1 rounded-md bg-muted-subtle px-2 py-0.5 text-xs text-foreground"
+    >
+      <FileRefIcon />
+      <span className="truncate">{filename}</span>
+      <button
+        type="button"
+        onClick={onRemove}
+        disabled={disabled}
+        className="ml-0.5 shrink-0 text-muted-foreground hover:text-destructive disabled:pointer-events-none"
+        aria-label={`Remove reference to ${path}`}
+      >
+        <XIcon />
+      </button>
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Inline SVG icons
+// ---------------------------------------------------------------------------
+
+function FileRefIcon() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0 text-accent-foreground"
+      aria-hidden="true"
+    >
+      <path d="M8 1H4C3.45 1 3 1.45 3 2V12C3 12.55 3.45 13 4 13H10C10.55 13 11 12.55 11 12V4L8 1Z" />
+      <path d="M8 1V4H11" />
+      <path d="M5 8H9M5 10H8" />
+    </svg>
+  );
+}
+
+function XIcon() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M4 4L10 10M10 4L4 10" />
+    </svg>
+  );
+}

package/src/file-reference/__tests__/FileReferenceChipList.test.tsx

@@ -0,0 +1,94 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import { FileReferenceChipList } from "../FileReferenceChipList";
+
+afterEach(cleanup);
+
+describe("FileReferenceChipList", () => {
+  it("returns null when refs array is empty", () => {
+    const { container } = render(
+      <FileReferenceChipList refs={[]} onRemove={vi.fn()} />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("renders a chip for each ref path", () => {
+    render(
+      <FileReferenceChipList
+        refs={["src/config.yaml", "docs/spec.md"]}
+        onRemove={vi.fn()}
+      />,
+    );
+
+    const items = screen.getAllByRole("listitem");
+    expect(items).toHaveLength(2);
+    expect(items[0].getAttribute("aria-label")).toBe("Referenced file: src/config.yaml");
+    expect(items[1].getAttribute("aria-label")).toBe("Referenced file: docs/spec.md");
+  });
+
+  it("displays the filename (last path segment) as visible text", () => {
+    render(
+      <FileReferenceChipList
+        refs={["src/deeply/nested/file.ts"]}
+        onRemove={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByText("file.ts")).toBeTruthy();
+  });
+
+  it("calls onRemove with the correct path when remove button is clicked", () => {
+    const onRemove = vi.fn();
+    render(
+      <FileReferenceChipList
+        refs={["a.ts", "b.ts"]}
+        onRemove={onRemove}
+      />,
+    );
+
+    const items = screen.getAllByRole("listitem");
+    const firstRemoveBtn = items[0].querySelector("button")!;
+    fireEvent.click(firstRemoveBtn);
+
+    expect(onRemove).toHaveBeenCalledWith("a.ts");
+    expect(onRemove).toHaveBeenCalledTimes(1);
+  });
+
+  it("disables remove buttons when disabled prop is true", () => {
+    render(
+      <FileReferenceChipList
+        refs={["a.ts"]}
+        onRemove={vi.fn()}
+        disabled
+      />,
+    );
+
+    const item = screen.getByRole("listitem");
+    const removeButton = item.querySelector("button")!;
+    expect(removeButton.hasAttribute("disabled")).toBe(true);
+  });
+
+  it("renders with role=list and correct aria-label", () => {
+    render(
+      <FileReferenceChipList
+        refs={["a.ts"]}
+        onRemove={vi.fn()}
+      />,
+    );
+
+    const list = screen.getByRole("list");
+    expect(list.getAttribute("aria-label")).toBe("Referenced workspace files");
+  });
+
+  it("sets title attribute on chip for full path tooltip", () => {
+    render(
+      <FileReferenceChipList
+        refs={["src/deeply/nested/file.ts"]}
+        onRemove={vi.fn()}
+      />,
+    );
+
+    const item = screen.getByRole("listitem");
+    expect(item.getAttribute("title")).toBe("src/deeply/nested/file.ts");
+  });
+});

package/src/file-reference/__tests__/useFileReferences.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useFileReferences } from "../useFileReferences";
+
+describe("useFileReferences", () => {
+  it("starts with empty refs and hasRefs false", () => {
+    const { result } = renderHook(() => useFileReferences());
+
+    expect(result.current.refs).toEqual([]);
+    expect(result.current.hasRefs).toBe(false);
+  });
+
+  it("add() appends a path and sets hasRefs true", () => {
+    const { result } = renderHook(() => useFileReferences());
+
+    act(() => {
+      result.current.add("src/config.yaml");
+    });
+
+    expect(result.current.refs).toEqual(["src/config.yaml"]);
+    expect(result.current.hasRefs).toBe(true);
+  });
+
+  it("add() deduplicates — same path added twice results in one entry", () => {
+    const { result } = renderHook(() => useFileReferences());
+
+    act(() => {
+      result.current.add("src/config.yaml");
+      result.current.add("src/config.yaml");
+    });
+
+    expect(result.current.refs).toEqual(["src/config.yaml"]);
+  });
+
+  it("add() preserves insertion order", () => {
+    const { result } = renderHook(() => useFileReferences());
+
+    act(() => {
+      result.current.add("a.ts");
+      result.current.add("b.ts");
+      result.current.add("c.ts");
+    });
+
+    expect(result.current.refs).toEqual(["a.ts", "b.ts", "c.ts"]);
+  });
+
+  it("remove() removes an existing path", () => {
+    const { result } = renderHook(() => useFileReferences());
+
+    act(() => {
+      result.current.add("a.ts");
+      result.current.add("b.ts");
+    });
+
+    act(() => {
+      result.current.remove("a.ts");
+    });
+
+    expect(result.current.refs).toEqual(["b.ts"]);
+    expect(result.current.hasRefs).toBe(true);
+  });
+
+  it("remove() is a no-op for non-existent paths (referential stability)", () => {
+    const { result } = renderHook(() => useFileReferences());
+
+    act(() => {
+      result.current.add("a.ts");
+    });
+
+    const refsBefore = result.current.refs;
+
+    act(() => {
+      result.current.remove("nonexistent.ts");
+    });
+
+    expect(result.current.refs).toBe(refsBefore);
+  });
+
+  it("clear() removes all refs", () => {
+    const { result } = renderHook(() => useFileReferences());
+
+    act(() => {
+      result.current.add("a.ts");
+      result.current.add("b.ts");
+    });
+
+    act(() => {
+      result.current.clear();
+    });
+
+    expect(result.current.refs).toEqual([]);
+    expect(result.current.hasRefs).toBe(false);
+  });
+
+  it("clear() on empty state preserves reference (no unnecessary re-render)", () => {
+    const { result } = renderHook(() => useFileReferences());
+
+    const refsBefore = result.current.refs;
+
+    act(() => {
+      result.current.clear();
+    });
+
+    expect(result.current.refs).toBe(refsBefore);
+  });
+
+  it("return value is referentially stable across renders when refs unchanged", () => {
+    const { result, rerender } = renderHook(() => useFileReferences());
+
+    act(() => {
+      result.current.add("a.ts");
+    });
+
+    const returnBefore = result.current;
+    rerender();
+
+    expect(result.current.add).toBe(returnBefore.add);
+    expect(result.current.remove).toBe(returnBefore.remove);
+    expect(result.current.clear).toBe(returnBefore.clear);
+  });
+});

package/src/file-reference/index.ts

@@ -0,0 +1,2 @@
+export { useFileReferences, type UseFileReferencesReturn } from "./useFileReferences";
+export { FileReferenceChipList, type FileReferenceChipListProps } from "./FileReferenceChipList";

package/src/file-reference/useFileReferences.ts

@@ -0,0 +1,55 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+
+export interface UseFileReferencesReturn {
+  /** Current workspace-relative file paths. */
+  readonly refs: readonly string[];
+  /** Whether any file references are present. */
+  readonly hasRefs: boolean;
+  /** Add a workspace-relative path. No-op if already present. */
+  add(path: string): void;
+  /** Remove a specific path. */
+  remove(path: string): void;
+  /** Remove all file references. */
+  clear(): void;
+}
+
+/**
+ * Behavior hook managing workspace file references for the composer.
+ *
+ * File references are lightweight "attention" signals — workspace-relative
+ * paths the user wants the agent to focus on. Unlike attachments, they
+ * require no upload; the agent reads them directly from the workspace
+ * filesystem post-provisioning.
+ *
+ * This hook is independently importable by platform builders who want
+ * to manage file references with their own UI (headless-first, DD-003).
+ */
+export function useFileReferences(): UseFileReferencesReturn {
+  const [refs, setRefs] = useState<string[]>([]);
+
+  const add = useCallback((path: string) => {
+    setRefs((prev) => {
+      if (prev.includes(path)) return prev;
+      return [...prev, path];
+    });
+  }, []);
+
+  const remove = useCallback((path: string) => {
+    setRefs((prev) => {
+      const next = prev.filter((p) => p !== path);
+      if (next.length === prev.length) return prev;
+      return next;
+    });
+  }, []);
+
+  const clear = useCallback(() => {
+    setRefs((prev) => (prev.length === 0 ? prev : []));
+  }, []);
+
+  return useMemo(
+    () => ({ refs, hasRefs: refs.length > 0, add, remove, clear }),
+    [refs, add, remove, clear],
+  );
+}

package/src/github/__tests__/parseGitUrl.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import { parseGitUrl } from "../parseGitUrl";
+
+describe("parseGitUrl", () => {
+  it("parses a standard HTTPS GitHub URL", () => {
+    expect(parseGitUrl("https://github.com/acme/api")).toEqual({
+      owner: "acme",
+      repo: "api",
+    });
+  });
+
+  it("parses an HTTPS URL with .git suffix", () => {
+    expect(parseGitUrl("https://github.com/acme/api.git")).toEqual({
+      owner: "acme",
+      repo: "api",
+    });
+  });
+
+  it("parses an SSH-style URL", () => {
+    expect(parseGitUrl("git@github.com:acme/api.git")).toEqual({
+      owner: "acme",
+      repo: "api",
+    });
+  });
+
+  it("parses a URL with a trailing slash stripped", () => {
+    expect(parseGitUrl("https://github.com/org/repo")).toEqual({
+      owner: "org",
+      repo: "repo",
+    });
+  });
+
+  it("returns null for non-GitHub URLs", () => {
+    expect(parseGitUrl("https://gitlab.com/acme/api")).toBeNull();
+    expect(parseGitUrl("https://bitbucket.org/acme/api")).toBeNull();
+  });
+
+  it("returns null for empty string", () => {
+    expect(parseGitUrl("")).toBeNull();
+  });
+
+  it("returns null for malformed URLs", () => {
+    expect(parseGitUrl("not-a-url")).toBeNull();
+    expect(parseGitUrl("https://github.com/")).toBeNull();
+    expect(parseGitUrl("https://github.com/acme")).toBeNull();
+  });
+
+  it("handles owner/repo with hyphens and underscores", () => {
+    expect(parseGitUrl("https://github.com/my-org/my_repo.git")).toEqual({
+      owner: "my-org",
+      repo: "my_repo",
+    });
+  });
+});

package/src/github/__tests__/useGitHubTreeLister.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useGitHubTreeLister } from "../useGitHubTreeLister";
+import type { WorkspaceEntry } from "../../workspace/useWorkspaceEntries";
+
+function gitEntry(overrides?: Partial<WorkspaceEntry>): WorkspaceEntry {
+  return {
+    id: "ws-1",
+    name: "acme/api",
+    type: "git",
+    gitUrl: "https://github.com/acme/api",
+    gitBranch: "main",
+    ...overrides,
+  };
+}
+
+function localEntry(): WorkspaceEntry {
+  return {
+    id: "ws-2",
+    name: "/Users/dev/project",
+    type: "local",
+    localPath: "/Users/dev/project",
+  };
+}
+
+const SAMPLE_TREE_RESPONSE = {
+  sha: "abc123",
+  url: "https://api.github.com/repos/acme/api/git/trees/abc123",
+  truncated: false,
+  tree: [
+    { path: "src", mode: "040000", type: "tree", sha: "a1", url: "" },
+    { path: "src/index.ts", mode: "100644", type: "blob", sha: "a2", size: 42, url: "" },
+    { path: "README.md", mode: "100644", type: "blob", sha: "a3", size: 100, url: "" },
+    { path: ".gitmodules", mode: "160000", type: "commit", sha: "a4", url: "" },
+  ],
+};
+
+describe("useGitHubTreeLister", () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    globalThis.fetch = vi.fn();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("returns undefined when token is null", () => {
+    const { result } = renderHook(() => useGitHubTreeLister(null));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("returns a lister function when token is provided", () => {
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    expect(typeof result.current).toBe("function");
+  });
+
+  it("returns null for non-git entries", async () => {
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    const files = await result.current!(localEntry());
+    expect(files).toBeNull();
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+  });
+
+  it("returns null for entries without gitUrl", async () => {
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    const files = await result.current!(gitEntry({ gitUrl: undefined }));
+    expect(files).toBeNull();
+  });
+
+  it("returns null for non-GitHub git URLs", async () => {
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    const files = await result.current!(
+      gitEntry({ gitUrl: "https://gitlab.com/acme/api" }),
+    );
+    expect(files).toBeNull();
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+  });
+
+  it("fetches tree and maps blob/tree entries", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      new Response(JSON.stringify(SAMPLE_TREE_RESPONSE), { status: 200 }),
+    );
+
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    const files = await result.current!(gitEntry());
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      "https://api.github.com/repos/acme/api/git/trees/main?recursive=1",
+      { headers: { Authorization: "Bearer ghp_abc" } },
+    );
+
+    expect(files).toEqual([
+      { path: "src", isDirectory: true },
+      { path: "src/index.ts", isDirectory: false },
+      { path: "README.md", isDirectory: false },
+    ]);
+  });
+
+  it("filters out commit entries (submodules)", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      new Response(JSON.stringify(SAMPLE_TREE_RESPONSE), { status: 200 }),
+    );
+
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    const files = await result.current!(gitEntry());
+
+    const paths = files!.map((f) => f.path);
+    expect(paths).not.toContain(".gitmodules");
+  });
+
+  it("appends a truncation marker when API indicates truncation", async () => {
+    const truncated = { ...SAMPLE_TREE_RESPONSE, truncated: true };
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      new Response(JSON.stringify(truncated), { status: 200 }),
+    );
+
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    const files = await result.current!(gitEntry());
+
+    const last = files![files!.length - 1];
+    expect(last.path).toContain("truncated");
+    expect(last.isDirectory).toBe(false);
+  });
+
+  it("returns null on non-OK response", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      new Response("Not Found", { status: 404 }),
+    );
+
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    const files = await result.current!(gitEntry());
+    expect(files).toBeNull();
+  });
+
+  it("defaults to 'main' branch when gitBranch is undefined", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      new Response(JSON.stringify(SAMPLE_TREE_RESPONSE), { status: 200 }),
+    );
+
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    await result.current!(gitEntry({ gitBranch: undefined }));
+
+    expect(vi.mocked(globalThis.fetch)).toHaveBeenCalledWith(
+      expect.stringContaining("/git/trees/main?"),
+      expect.anything(),
+    );
+  });
+
+  it("encodes branch names with special characters", async () => {
+    vi.mocked(globalThis.fetch).mockResolvedValue(
+      new Response(JSON.stringify(SAMPLE_TREE_RESPONSE), { status: 200 }),
+    );
+
+    const { result } = renderHook(() => useGitHubTreeLister("ghp_abc"));
+    await result.current!(gitEntry({ gitBranch: "feat/my branch" }));
+
+    expect(vi.mocked(globalThis.fetch)).toHaveBeenCalledWith(
+      expect.stringContaining("/git/trees/feat%2Fmy%20branch?"),
+      expect.anything(),
+    );
+  });
+});

package/src/github/index.ts

@@ -23,3 +23,6 @@ export {
   GitHubRepoPicker,
   type GitHubRepoPickerProps,
 } from "./GitHubRepoPicker";
+
+export { useGitHubTreeLister } from "./useGitHubTreeLister";
+export { parseGitUrl, type ParsedGitRepo } from "./parseGitUrl";

package/src/github/parseGitUrl.ts

@@ -0,0 +1,28 @@
+/**
+ * Parsed owner and repository name from a GitHub URL.
+ *
+ * Returned by {@link parseGitUrl} when the URL is a valid GitHub
+ * repository reference.
+ */
+export interface ParsedGitRepo {
+  readonly owner: string;
+  readonly repo: string;
+}
+
+const GITHUB_URL_RE = /github\.com[/:]([^/]+)\/([^/.]+?)(?:\.git)?$/;
+
+/**
+ * Extract the owner and repository name from a GitHub URL.
+ *
+ * Supports both HTTPS and SSH-style URLs:
+ * - `https://github.com/acme/api`
+ * - `https://github.com/acme/api.git`
+ * - `git@github.com:acme/api.git`
+ *
+ * Returns `null` for non-GitHub or unparseable URLs.
+ */
+export function parseGitUrl(url: string): ParsedGitRepo | null {
+  const match = url.match(GITHUB_URL_RE);
+  if (!match) return null;
+  return { owner: match[1], repo: match[2] };
+}