@tangle-network/ui 1.0.0

package/src/files/file-tree.tsx

@@ -0,0 +1,258 @@
+/**
+ * FileTree — directory browser with file type icons.
+ *
+ * Renders a hierarchical file system view. Clicking a file
+ * triggers onSelect with the full path.
+ */
+
+import { useState, type ReactNode } from "react";
+import {
+  File,
+  FileText,
+  FileCode,
+  FileSpreadsheet,
+  FileImage,
+  Folder,
+  FolderOpen,
+  ChevronRight,
+  FileJson,
+} from "lucide-react";
+import { cn } from "../lib/utils";
+
+export interface FileNode {
+  name: string;
+  path: string;
+  type: "file" | "directory";
+  children?: FileNode[];
+  size?: number;
+  mimeType?: string;
+}
+
+export interface FileTreeProps {
+  root: FileNode;
+  selectedPath?: string;
+  onSelect?: (path: string, node: FileNode) => void;
+  className?: string;
+  defaultExpanded?: boolean;
+  visibility?: FileTreeVisibilityOptions;
+}
+
+export interface FileTreeVisibilityOptions {
+  hiddenPaths?: string[];
+  hiddenPathPrefixes?: string[];
+  isVisible?: (node: FileNode) => boolean;
+}
+
+function isNodeVisible(node: FileNode, visibility?: FileTreeVisibilityOptions) {
+  if (!visibility) return true;
+
+  if (visibility.hiddenPaths?.includes(node.path)) {
+    return false;
+  }
+
+  if (
+    visibility.hiddenPathPrefixes?.some(
+      (prefix) => node.path === prefix || node.path.startsWith(`${prefix}/`),
+    )
+  ) {
+    return false;
+  }
+
+  return visibility.isVisible ? visibility.isVisible(node) : true;
+}
+
+export function filterFileTree(root: FileNode, visibility?: FileTreeVisibilityOptions): FileNode | null {
+  if (!isNodeVisible(root, visibility)) {
+    return null;
+  }
+
+  if (root.type === "file") {
+    return root;
+  }
+
+  const children = (root.children ?? [])
+    .map((child) => filterFileTree(child, visibility))
+    .filter((child): child is FileNode => child !== null);
+
+  if (root.children && root.children.length > 0 && children.length === 0) {
+    return null;
+  }
+
+  return {
+    ...root,
+    children,
+  };
+}
+
+const FILE_ICONS: Record<string, typeof File> = {
+  pdf: FileText,
+  csv: FileSpreadsheet,
+  xlsx: FileSpreadsheet,
+  xls: FileSpreadsheet,
+  py: FileCode,
+  ts: FileCode,
+  js: FileCode,
+  json: FileJson,
+  yaml: FileCode,
+  yml: FileCode,
+  md: FileText,
+  txt: FileText,
+  png: FileImage,
+  jpg: FileImage,
+  jpeg: FileImage,
+  gif: FileImage,
+  svg: FileImage,
+};
+
+function getFileIcon(name: string): typeof File {
+  const ext = name.split(".").pop()?.toLowerCase() || "";
+  return FILE_ICONS[ext] || File;
+}
+
+function getFileColor(name: string): string {
+  const ext = name.split(".").pop()?.toLowerCase() || "";
+  switch (ext) {
+    case "pdf": return "text-red-400";
+    case "py": return "text-yellow-400";
+    case "ts":
+    case "js": return "text-blue-400";
+    case "json": return "text-green-400";
+    case "yaml":
+    case "yml": return "text-[var(--accent-text)]";
+    case "csv":
+    case "xlsx": return "text-emerald-400";
+    case "md": return "text-foreground";
+    default: return "text-muted-foreground";
+  }
+}
+
+interface TreeNodeProps {
+  node: FileNode;
+  depth: number;
+  selectedPath?: string;
+  onSelect?: (path: string, node: FileNode) => void;
+  defaultExpanded: boolean;
+}
+
+function TreeNode({ node, depth, selectedPath, onSelect, defaultExpanded }: TreeNodeProps) {
+  const [expanded, setExpanded] = useState(defaultExpanded);
+  const isSelected = node.path === selectedPath;
+  const isDir = node.type === "directory";
+
+  const handleClick = () => {
+    if (isDir) {
+      setExpanded(!expanded);
+    }
+    onSelect?.(node.path, node);
+  };
+
+  const Icon = isDir
+    ? (expanded ? FolderOpen : Folder)
+    : getFileIcon(node.name);
+
+  const iconColor = isDir ? "text-primary" : getFileColor(node.name);
+
+  return (
+    <div>
+      <button
+        type="button"
+        className={cn(
+          "flex items-center gap-1.5 w-full text-left px-2 py-[2px] cursor-pointer text-[13px] transition-colors",
+          "appearance-none bg-transparent border-none",
+          "hover:bg-accent",
+          isSelected ? "bg-primary/15 text-foreground" : "text-foreground",
+        )}
+        style={{ paddingLeft: `${depth * 16 + 8}px` }}
+        onClick={handleClick}
+        aria-expanded={isDir ? expanded : undefined}
+      >
+        {isDir && (
+          <ChevronRight
+            className={cn(
+              "h-3 w-3 shrink-0 text-muted-foreground transition-transform",
+              expanded && "rotate-90",
+            )}
+          />
+        )}
+        {!isDir && <span className="w-3" />}
+        <Icon className={cn("h-4 w-4 shrink-0", iconColor)} />
+        <span className="truncate">{node.name}</span>
+        {node.size !== undefined && !isDir && (
+          <span className="text-muted-foreground text-xs ml-auto tabular-nums">
+            {formatSize(node.size)}
+          </span>
+        )}
+      </button>
+      {isDir && expanded && node.children && (
+        <div>
+          {node.children
+            .sort((a, b) => {
+              if (a.type !== b.type) return a.type === "directory" ? -1 : 1;
+              return a.name.localeCompare(b.name);
+            })
+            .map((child) => (
+              <TreeNode
+                key={child.path}
+                node={child}
+                depth={depth + 1}
+                selectedPath={selectedPath}
+                onSelect={onSelect}
+                defaultExpanded={defaultExpanded}
+              />
+            ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)}K`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+}
+
+export function FileTree({
+  root,
+  selectedPath,
+  onSelect,
+  className,
+  defaultExpanded = true,
+  visibility,
+}: FileTreeProps) {
+  const visibleRoot = filterFileTree(root, visibility);
+
+  if (!visibleRoot) {
+    return null;
+  }
+
+  return (
+    <div className={cn("text-sm font-sans", className)}>
+      {visibleRoot.children ? (
+        visibleRoot.children
+          .sort((a, b) => {
+            if (a.type !== b.type) return a.type === "directory" ? -1 : 1;
+            return a.name.localeCompare(b.name);
+          })
+          .map((child) => (
+            <TreeNode
+              key={child.path}
+              node={child}
+              depth={0}
+              selectedPath={selectedPath}
+              onSelect={onSelect}
+              defaultExpanded={defaultExpanded}
+            />
+          ))
+      ) : (
+        <TreeNode
+          node={visibleRoot}
+          depth={0}
+          selectedPath={selectedPath}
+          onSelect={onSelect}
+          defaultExpanded={defaultExpanded}
+        />
+      )}
+    </div>
+  );
+}

package/src/files/index.ts

@@ -0,0 +1,17 @@
+export {
+  FileTree,
+  filterFileTree,
+  type FileTreeProps,
+  type FileNode,
+  type FileTreeVisibilityOptions,
+} from "./file-tree";
+export {
+  RichFileTree,
+  type RichFileTreeProps,
+  type RichFileTreeGitEntry,
+  type RichFileTreeGitStatus,
+  type RichFileTreeThemeVars,
+} from "./rich-file-tree";
+export { FilePreview, type FilePreviewProps } from "./file-preview";
+export { FileTabs, type FileTabsProps, type FileTabData } from "./file-tabs";
+export { FileArtifactPane, type FileArtifactPaneProps } from "./file-artifact-pane";

package/src/files/rich-file-tree.stories.tsx

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { RichFileTree, type RichFileTreeGitEntry } from "./rich-file-tree";
+import type { FileNode } from "./file-tree";
+
+const meta: Meta<typeof RichFileTree> = {
+  title: "Files/RichFileTree",
+  component: RichFileTree,
+  parameters: { layout: "padded", backgrounds: { default: "dark" } },
+  decorators: [
+    (Story) => (
+      <div className="w-[420px] h-[480px] rounded-xl border border-border bg-card overflow-hidden">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof RichFileTree>;
+
+const sampleRoot: FileNode = {
+  name: "vault",
+  path: "",
+  type: "directory",
+  children: [
+    {
+      name: "personas",
+      path: "personas",
+      type: "directory",
+      children: [
+        { name: "domain-saas-founder.md", path: "personas/domain-saas-founder.md", type: "file" },
+        { name: "regression-paranoid-shipper.md", path: "personas/regression-paranoid-shipper.md", type: "file" },
+        { name: "skeptical-agent-builder.md", path: "personas/skeptical-agent-builder.md", type: "file" },
+      ],
+    },
+    {
+      name: "signals",
+      path: "signals",
+      type: "directory",
+      children: [
+        {
+          name: "2026-04-28",
+          path: "signals/2026-04-28",
+          type: "directory",
+          children: [
+            { name: "router-pricing.md", path: "signals/2026-04-28/router-pricing.md", type: "file" },
+            { name: "competitor-launch.md", path: "signals/2026-04-28/competitor-launch.md", type: "file" },
+          ],
+        },
+      ],
+    },
+    { name: "brief.md", path: "brief.md", type: "file" },
+    { name: "README.md", path: "README.md", type: "file" },
+  ],
+};
+
+const flatPaths = [
+  "README.md",
+  "brief.md",
+  "personas/domain-saas-founder.md",
+  "personas/regression-paranoid-shipper.md",
+  "personas/skeptical-agent-builder.md",
+  "signals/2026-04-28/router-pricing.md",
+  "signals/2026-04-28/competitor-launch.md",
+]
+
+export const Default: Story = {
+  name: "Default (paths input)",
+  args: { paths: flatPaths, search: true },
+};
+
+export const FromTreeNode: Story = {
+  name: "From recursive FileNode",
+  args: { root: sampleRoot, search: true },
+};
+
+export const WithGitStatus: Story = {
+  name: "With git-status overlays",
+  args: {
+    paths: flatPaths,
+    gitStatus: [
+      { path: "brief.md", status: "modified" },
+      { path: "signals/2026-04-28/router-pricing.md", status: "added" },
+      { path: "personas/skeptical-agent-builder.md", status: "modified" },
+    ] as RichFileTreeGitEntry[],
+    search: true,
+  },
+};
+
+export const NoSearch: Story = {
+  name: "Without search input",
+  args: { paths: flatPaths, search: false },
+};
+
+export const HugeTree: Story = {
+  name: "Huge (5000 files — virtualization smoke test)",
+  args: {
+    paths: Array.from({ length: 5000 }, (_, i) => {
+      const dir = `dir-${Math.floor(i / 50)}`;
+      return `${dir}/file-${i}.md`;
+    }),
+    search: true,
+  },
+};

package/src/files/rich-file-tree.test.tsx

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest"
+import { render } from "@testing-library/react"
+import { RichFileTree } from "./rich-file-tree"
+
+describe("RichFileTree", () => {
+  it("renders without crashing given a flat path list", () => {
+    const { container } = render(
+      <RichFileTree paths={["README.md", "src/index.ts"]} />,
+    )
+    // Pierre renders into a custom element / shadow root; we can't peek
+    // inside shadow DOM from RTL, but we can confirm the host mounted.
+    expect(container.querySelectorAll("*").length).toBeGreaterThan(0)
+  })
+
+  it("flattens a recursive FileNode tree to paths", () => {
+    const { container } = render(
+      <RichFileTree
+        root={{
+          name: "root",
+          path: "",
+          type: "directory",
+          children: [
+            { name: "a.md", path: "a.md", type: "file" },
+            {
+              name: "b",
+              path: "b",
+              type: "directory",
+              children: [{ name: "c.md", path: "b/c.md", type: "file" }],
+            },
+          ],
+        }}
+      />,
+    )
+    expect(container.querySelectorAll("*").length).toBeGreaterThan(0)
+  })
+
+  it("throws when both root and paths are passed", () => {
+    expect(() =>
+      render(<RichFileTree root={{ name: "x", path: "x", type: "file" }} paths={["y"]} />),
+    ).toThrow(/root.*paths.*not both/i)
+  })
+})

package/src/files/rich-file-tree.tsx

@@ -0,0 +1,232 @@
+/**
+ * RichFileTree — feature-rich file browser built on @pierre/trees.
+ *
+ * Why this exists alongside the existing FileTree:
+ * - Built-in search (cmd-K-style fuzzy filter)
+ * - Virtualized rendering for vaults with thousands of files
+ * - Git-status overlays per row (modified / added / staged)
+ * - Right-click + button-lane context menus with custom item rendering
+ * - VS Code-style icons via @pierre/vscode-icons (optional)
+ *
+ * The existing FileTree stays as-is for simple cases. RichFileTree is the
+ * upgrade path when a consumer's vault grows past a few hundred files or
+ * needs richer affordances.
+ *
+ * Pierre renders inside a shadow DOM to keep its CSS isolated. We bridge
+ * the host theme via CSS variables on the host element below — the tree
+ * picks them up through `--trees-*-override` overrides.
+ */
+
+import {
+  FileTree as PierreFileTree,
+  useFileTree as usePierreFileTree,
+} from "@pierre/trees/react";
+import type {
+  ContextMenuItem,
+  ContextMenuOpenContext,
+  GitStatus,
+  GitStatusEntry,
+} from "@pierre/trees";
+import { useEffect, useMemo, type CSSProperties, type ReactNode } from "react";
+import type { FileNode } from "./file-tree";
+
+/**
+ * Re-export Pierre's git-status union under a stable name so consumers
+ * don't import directly from the dep. If we ever swap the underlying
+ * implementation, only this file changes.
+ */
+export type RichFileTreeGitStatus = GitStatus;
+export type RichFileTreeGitEntry = GitStatusEntry;
+
+export interface RichFileTreeProps {
+  /**
+   * Either a recursive `FileNode` tree (matches the existing FileTree
+   * input) or a flat list of canonical paths. Pass exactly one.
+   */
+  root?: FileNode;
+  paths?: ReadonlyArray<string>;
+
+  /** Currently-selected path. Pierre supports multi-select internally; the
+   * wrapper exposes a single string for parity with FileTree. */
+  selectedPath?: string;
+  /** Called whenever the selection changes (single-select fan-out). */
+  onSelect?: (path: string) => void;
+
+  /** Show the inline search input. Defaults to true. */
+  search?: boolean;
+  /** Open / closed initial expansion. Defaults to "open" — match FileTree. */
+  initialExpansion?: "open" | "closed";
+
+  /** Optional git-status decorations per path. */
+  gitStatus?: ReadonlyArray<RichFileTreeGitEntry>;
+
+  /**
+   * Right-click / button-lane menu content. Receives the row and the
+   * trigger context (which interaction opened the menu).
+   */
+  renderContextMenu?: (
+    item: ContextMenuItem,
+    context: ContextMenuOpenContext,
+  ) => ReactNode;
+
+  /** Optional header rendered above the tree rows. */
+  header?: ReactNode;
+
+  /**
+   * Theme override map for shadow-DOM CSS variables. Most consumers can
+   * leave this — defaults derive from the host element's computed
+   * tokens via `cssVarFromToken()`.
+   */
+  themeOverrides?: Partial<RichFileTreeThemeVars>;
+
+  className?: string;
+  style?: CSSProperties;
+  /** Inline height (or set via `style.height`). Defaults to 100% of parent. */
+  height?: number | string;
+}
+
+export interface RichFileTreeThemeVars {
+  /** Selected-row background. */
+  selectedBg: string;
+  /** Selected-row foreground. */
+  selectedFg: string;
+  /** Default row foreground. */
+  fg: string;
+  /** Hover background. */
+  hoverBg: string;
+  /** Border / divider color. */
+  border: string;
+  /** Muted (parent path, breadcrumb) foreground. */
+  mutedFg: string;
+}
+
+/**
+ * Map a sandbox-ui design token (e.g. `--accent-surface-soft`) to a CSS
+ * `var(--token)` reference. Pierre's CSS-variable surface accepts any
+ * valid CSS color expression, so passing `var(--token)` lets the host
+ * theme propagate through without us having to read computed styles.
+ */
+function cssVarFromToken(name: string): string {
+  return `var(${name})`;
+}
+
+const DEFAULT_THEME: RichFileTreeThemeVars = {
+  selectedBg: cssVarFromToken("--accent-surface-soft"),
+  selectedFg: cssVarFromToken("--accent-text"),
+  fg: cssVarFromToken("--foreground"),
+  hoverBg: cssVarFromToken("--muted"),
+  border: cssVarFromToken("--border"),
+  mutedFg: cssVarFromToken("--muted-foreground"),
+};
+
+/**
+ * Walk a recursive FileNode and return a flat list of canonical paths.
+ *
+ * Pierre infers directory structure from path segments — passing both
+ * `dir` and `dir/file.md` collides because `dir` looks like a file.
+ * We emit only files; pure-directory leaves get a trailing slash so
+ * Pierre keeps them as folders even when they have no children.
+ */
+function flattenFileNode(node: FileNode, out: string[] = []): string[] {
+  if (node.type === "file" && node.path) {
+    out.push(node.path);
+    return out;
+  }
+  if (node.type === "directory") {
+    if (node.children?.length) {
+      for (const child of node.children) {
+        flattenFileNode(child, out);
+      }
+      return out;
+    }
+    // Empty directory: trailing slash keeps Pierre treating it as a folder.
+    if (node.path) out.push(`${node.path}/`);
+  }
+  return out;
+}
+
+export function RichFileTree({
+  root,
+  paths,
+  selectedPath,
+  onSelect,
+  search = true,
+  initialExpansion = "open",
+  gitStatus,
+  renderContextMenu,
+  header,
+  themeOverrides,
+  className,
+  style,
+  height,
+}: RichFileTreeProps) {
+  if (root && paths) {
+    throw new Error("RichFileTree: pass `root` or `paths`, not both");
+  }
+
+  const flatPaths = useMemo<string[]>(() => {
+    if (paths) return Array.from(paths);
+    if (root) return flattenFileNode(root);
+    return [];
+  }, [paths, root]);
+
+  const { model } = usePierreFileTree({
+    paths: flatPaths,
+    search,
+    initialExpansion,
+    onSelectionChange: (selected) => {
+      const next = selected[0]
+      if (next && next !== selectedPath) onSelect?.(next)
+    },
+  });
+
+  // Push git status whenever it changes. The model's setter is the only
+  // way to update post-construction; useEffect keeps it in sync.
+  useEffect(() => {
+    if (!gitStatus) return;
+    model.setGitStatus(gitStatus);
+  }, [model, gitStatus]);
+
+  // Reset paths when the input changes after first render. resetPaths
+  // re-uses the model and preserves expansion / selection where it can.
+  useEffect(() => {
+    model.resetPaths(flatPaths);
+  }, [model, flatPaths]);
+
+  // Drive selection from props (controlled). Skip when already selected
+  // to avoid an emit loop with onSelectionChange.
+  useEffect(() => {
+    if (!selectedPath) return;
+    const current = model.getSelectedPaths();
+    if (current.length === 1 && current[0] === selectedPath) return;
+    // The public API exposes selection via `select` semantics through the
+    // controller — fall back to direct setter when present, no-op otherwise.
+    const m = model as unknown as { setSelectedPaths?: (paths: readonly string[]) => void };
+    m.setSelectedPaths?.([selectedPath]);
+  }, [model, selectedPath]);
+
+  const theme = { ...DEFAULT_THEME, ...themeOverrides };
+  const themeStyle = useMemo<CSSProperties>(
+    () => ({
+      ["--trees-selected-bg-override" as string]: theme.selectedBg,
+      ["--trees-selected-fg-override" as string]: theme.selectedFg,
+      ["--trees-fg-override" as string]: theme.fg,
+      ["--trees-hover-bg-override" as string]: theme.hoverBg,
+      ["--trees-border-color-override" as string]: theme.border,
+      ["--trees-muted-fg-override" as string]: theme.mutedFg,
+      height: height ?? "100%",
+      ...style,
+    }),
+    [theme, height, style],
+  );
+
+  return (
+    <PierreFileTree
+      model={model}
+      header={header}
+      renderContextMenu={renderContextMenu}
+      className={className}
+      style={themeStyle}
+    />
+  );
+}

package/src/hooks/index.ts

@@ -0,0 +1,10 @@
+export * from "./use-auto-scroll";
+export * from "./use-dropdown-menu";
+export * from "./use-live-time";
+export * from "./use-run-collapse-state";
+export * from "./use-run-groups";
+export * from "./use-tool-call-stream";
+export * from "./use-auth";
+export * from "./use-realtime-session";
+export * from "./use-sdk-session";
+export * from "./use-sse-stream";