@stigmer/react 3.1.1 → 3.1.3

package/src/internal/__tests__/useRevealLine.test.tsx

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { useRevealLine, type RevealTarget } from "../useRevealLine";
+import { prefersReducedMotion } from "../motion-preference";
+
+// Mock the motion utility directly: it caches at module scope, so driving it
+// through `matchMedia` would leak state across cases. Mocking gives each test a
+// deterministic reduced-motion answer.
+vi.mock("../motion-preference", () => ({
+  prefersReducedMotion: vi.fn(() => false),
+}));
+
+// A tiny harness that renders addressable line rows and drives the hook, so we
+// exercise the real `[data-line]` query + scroll effect against a real DOM.
+function LineView({
+  reveal,
+  lineCount = 5,
+}: {
+  readonly reveal: RevealTarget | undefined;
+  readonly lineCount?: number;
+}) {
+  const { containerRef, isRevealed } = useRevealLine<HTMLDivElement>(reveal);
+  return (
+    <div ref={containerRef}>
+      {Array.from({ length: lineCount }, (_, i) => {
+        const line = i + 1;
+        return (
+          <span key={line} data-line={line} data-revealed={isRevealed(line)}>
+            line {line}
+          </span>
+        );
+      })}
+    </div>
+  );
+}
+
+describe("useRevealLine", () => {
+  let scrollSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.mocked(prefersReducedMotion).mockReturnValue(false);
+    // happy-dom has no real scrollIntoView — stub it to assert calls + options.
+    scrollSpy = vi.fn();
+    Element.prototype.scrollIntoView =
+      scrollSpy as unknown as typeof Element.prototype.scrollIntoView;
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("scrolls the target line into view on mount", () => {
+    render(<LineView reveal={{ line: 3, nonce: 1 }} />);
+    expect(scrollSpy).toHaveBeenCalledTimes(1);
+    expect(scrollSpy).toHaveBeenCalledWith({ block: "center", behavior: "smooth" });
+  });
+
+  it("re-scrolls when the nonce changes, even for the same line", () => {
+    const { rerender } = render(<LineView reveal={{ line: 3, nonce: 1 }} />);
+    expect(scrollSpy).toHaveBeenCalledTimes(1);
+
+    rerender(<LineView reveal={{ line: 3, nonce: 2 }} />);
+    expect(scrollSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not re-scroll when the nonce is unchanged", () => {
+    const { rerender } = render(<LineView reveal={{ line: 3, nonce: 7 }} />);
+    expect(scrollSpy).toHaveBeenCalledTimes(1);
+
+    // Same nonce, different (irrelevant) prop → no additional scroll.
+    rerender(<LineView reveal={{ line: 3, nonce: 7 }} lineCount={6} />);
+    expect(scrollSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("is a no-op when the target line is out of range", () => {
+    render(<LineView reveal={{ line: 99, nonce: 1 }} lineCount={5} />);
+    expect(scrollSpy).not.toHaveBeenCalled();
+  });
+
+  it("is a no-op when there is no reveal target", () => {
+    render(<LineView reveal={undefined} />);
+    expect(scrollSpy).not.toHaveBeenCalled();
+  });
+
+  it("uses instant scroll under prefers-reduced-motion", () => {
+    vi.mocked(prefersReducedMotion).mockReturnValue(true);
+    render(<LineView reveal={{ line: 2, nonce: 1 }} />);
+    expect(scrollSpy).toHaveBeenCalledWith({ block: "center", behavior: "auto" });
+  });
+
+  it("reports the revealed line via isRevealed", () => {
+    const { container } = render(<LineView reveal={{ line: 4, nonce: 1 }} />);
+    const revealed = container.querySelector('[data-revealed="true"]');
+    expect(revealed?.getAttribute("data-line")).toBe("4");
+    expect(container.querySelectorAll('[data-revealed="true"]')).toHaveLength(1);
+  });
+});

package/src/internal/file-icons/__tests__/file-icons.test.tsx

@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest";
+import { fileIconCategory } from "../index";
+
+describe("fileIconCategory", () => {
+  it("classifies common code extensions", () => {
+    for (const name of ["a.ts", "b.tsx", "c.js", "m.py", "s.go", "r.rs"]) {
+      expect(fileIconCategory(name)).toBe("code");
+    }
+  });
+
+  it("classifies markup, style, data, markdown, image", () => {
+    expect(fileIconCategory("index.html")).toBe("markup");
+    expect(fileIconCategory("app.css")).toBe("style");
+    expect(fileIconCategory("tsconfig.json")).toBe("data");
+    expect(fileIconCategory("config.yaml")).toBe("data");
+    expect(fileIconCategory("README.md")).toBe("markdown");
+    expect(fileIconCategory("logo.png")).toBe("image");
+  });
+
+  it("is case-insensitive on the extension", () => {
+    expect(fileIconCategory("Main.TS")).toBe("code");
+    expect(fileIconCategory("PHOTO.PNG")).toBe("image");
+  });
+
+  it("falls back to generic for unknown or extension-less names", () => {
+    expect(fileIconCategory("Makefile")).toBe("generic");
+    expect(fileIconCategory("data.unknownext")).toBe("generic");
+    expect(fileIconCategory("trailingdot.")).toBe("generic");
+  });
+
+  it("uses the last dotted segment for multi-dot names", () => {
+    expect(fileIconCategory("app.test.ts")).toBe("code");
+    expect(fileIconCategory("archive.tar.gz")).toBe("generic");
+  });
+});

package/src/internal/file-icons/index.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+// Monochrome, shape-differentiated file icons. Deliberately NOT colored with
+// language brand colors: DD-005 forbids hardcoded colors, and every glyph must
+// tint from `currentColor` so it inherits the row's `--stgm-*` token in every
+// preset and color mode (like VS Code's "Minimal" icon theme). Recognition
+// comes from distinct shapes per broad category, not from color.
+
+/** Broad file categories, chosen so one glyph serves many related extensions. */
+export type FileIconCategory =
+  | "code"
+  | "markup"
+  | "style"
+  | "data"
+  | "markdown"
+  | "image"
+  | "generic";
+
+/**
+ * Extension → category. Kept intentionally coarse: adding a language usually
+ * means adding one entry here, not a new glyph. Unknown extensions fall back to
+ * the generic document icon.
+ */
+const EXTENSION_CATEGORY: Readonly<Record<string, FileIconCategory>> = {
+  // code
+  js: "code", jsx: "code", mjs: "code", cjs: "code",
+  ts: "code", tsx: "code",
+  py: "code", rb: "code", go: "code", rs: "code",
+  java: "code", kt: "code", c: "code", h: "code",
+  cpp: "code", cc: "code", hpp: "code", cs: "code",
+  php: "code", swift: "code", sh: "code", bash: "code", zsh: "code",
+  lua: "code", dart: "code", scala: "code", proto: "code",
+  // markup
+  html: "markup", htm: "markup", xml: "markup", vue: "markup", svelte: "markup",
+  // style
+  css: "style", scss: "style", sass: "style", less: "style",
+  // data / config
+  json: "data", jsonc: "data", yaml: "data", yml: "data",
+  toml: "data", ini: "data", env: "data", csv: "data", tsv: "data",
+  // markdown
+  md: "markdown", mdx: "markdown", markdown: "markdown",
+  // image
+  png: "image", jpg: "image", jpeg: "image", gif: "image",
+  webp: "image", svg: "image", ico: "image", bmp: "image",
+};
+
+/** Classify a file name into a {@link FileIconCategory} by its extension. */
+export function fileIconCategory(fileName: string): FileIconCategory {
+  const dot = fileName.lastIndexOf(".");
+  if (dot < 0 || dot === fileName.length - 1) return "generic";
+  const ext = fileName.slice(dot + 1).toLowerCase();
+  return EXTENSION_CATEGORY[ext] ?? "generic";
+}
+
+/**
+ * A monochrome icon for a file, chosen by extension category. Tints from
+ * `currentColor`; size via the surrounding font/box.
+ */
+export function FileTypeIcon({ fileName }: { readonly fileName: string }): ReactNode {
+  const category = fileIconCategory(fileName);
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.3"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0"
+      aria-hidden="true"
+    >
+      {/* Every category shares a document outline for a consistent silhouette. */}
+      <path d="M9.5 1.5H4.5C3.95 1.5 3.5 1.95 3.5 2.5V13.5C3.5 14.05 3.95 14.5 4.5 14.5H11.5C12.05 14.5 12.5 14.05 12.5 13.5V4.5L9.5 1.5Z" />
+      <path d="M9.3 1.7V4.5H12.3" />
+      {CATEGORY_GLYPH[category]}
+    </svg>
+  );
+}
+
+/** The inner glyph that distinguishes each category, drawn in the doc body. */
+const CATEGORY_GLYPH: Readonly<Record<FileIconCategory, ReactNode>> = {
+  code: (
+    <>
+      <path d="M7 8.5L5.75 9.75L7 11" />
+      <path d="M9 8.5L10.25 9.75L9 11" />
+    </>
+  ),
+  markup: (
+    <>
+      <path d="M6.5 8.5L5.5 9.9L6.5 11.3" />
+      <path d="M9.5 8.5L10.5 9.9L9.5 11.3" />
+    </>
+  ),
+  style: <path d="M5.5 9.3H10.5M5.5 11.1H8.5" />,
+  data: (
+    <>
+      <path d="M7 8.4C6.2 8.4 6.2 9.3 6.2 9.9C6.2 10.5 6.2 11.4 5.4 11.4" />
+      <path d="M9 8.4C9.8 8.4 9.8 9.3 9.8 9.9C9.8 10.5 9.8 11.4 10.6 11.4" />
+    </>
+  ),
+  markdown: <path d="M5.4 11.3V8.6L6.9 10.1L8.4 8.6V11.3M10.4 8.7V11.1M9.5 10.2L10.4 11.2L11.3 10.2" />,
+  image: (
+    <>
+      <circle cx="6.4" cy="9" r="0.7" />
+      <path d="M5.2 11.4L7.3 9.9L10.6 11.6" />
+    </>
+  ),
+  generic: <path d="M5.5 9.3H10.5M5.5 11.1H10.5" />,
+};
+
+/** A folder icon; `open` swaps to the opened-folder silhouette. */
+export function FolderTypeIcon({ open = false }: { readonly open?: boolean }): ReactNode {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.3"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0"
+      aria-hidden="true"
+    >
+      {open ? (
+        <path d="M1.8 5.5V12A1 1 0 002.8 13H12.6L14.5 7.5H4.2L2.8 11" />
+      ) : (
+        <path d="M1.8 4.5A1 1 0 012.8 3.5H6L7.3 5H13.2A1 1 0 0114.2 6V12A1 1 0 0113.2 13H2.8A1 1 0 011.8 12V4.5Z" />
+      )}
+    </svg>
+  );
+}

package/src/internal/file-tree/FileTreeNode.tsx

@@ -2,6 +2,7 @@
 
 import { useCallback, useState, type DragEvent } from "react";
 import { cn } from "@stigmer/theme";
+import { FileTypeIcon, FolderTypeIcon } from "../file-icons/index.js";
 import type { TreeNode } from "./tree-node.js";
 
 /**
@@ -15,6 +16,12 @@ export interface FileTreeNodeProps {
   readonly node: TreeNode;
   readonly selectedPath: string;
   readonly onSelect: (path: string) => void;
+  /**
+   * Optional double-click handler for file nodes. When set, a double-click on a
+   * file calls `onActivate(path)` (used by the workspace surface to pin a
+   * previewed tab); the single click still fires `onSelect`. Folders ignore it.
+   */
+  readonly onActivate?: (path: string) => void;
   readonly depth: number;
   /**
    * When `true`, file nodes (not folders) become draggable and emit
@@ -24,6 +31,17 @@ export interface FileTreeNodeProps {
    * where file referencing is not applicable (e.g., SkillFileBrowser).
    */
   readonly enableDrag?: boolean;
+  /**
+   * When `true`, render monochrome file-type / folder icons before each name
+   * (VS Code explorer feel). Opt-in so drag/skill contexts stay icon-free.
+   */
+  readonly showIcons?: boolean;
+  /**
+   * When `true`, draw vertical indent guides down each nested group and indent
+   * via nested margins rather than per-row left padding. Opt-in; the default
+   * padding-based indentation is preserved for existing consumers.
+   */
+  readonly indentGuides?: boolean;
   /**
    * Maximum depth at which folders start collapsed instead of expanded.
    * Folders at depth >= maxInitialDepth render collapsed by default,
@@ -49,8 +67,11 @@ export function FileTreeNode({
   node,
   selectedPath,
   onSelect,
+  onActivate,
   depth,
   enableDrag = false,
+  showIcons = false,
+  indentGuides = false,
   maxInitialDepth,
 }: FileTreeNodeProps) {
   const [expanded, setExpanded] = useState(
@@ -68,6 +89,10 @@ export function FileTreeNode({
     }
   }, [isFolder, node.path, onSelect]);
 
+  const handleDoubleClick = useCallback(() => {
+    if (!isFolder) onActivate?.(node.path);
+  }, [isFolder, node.path, onActivate]);
+
   const handleDragStart = useCallback(
     (e: DragEvent) => {
       e.dataTransfer.setData(FILE_REF_MIME, JSON.stringify({ path: node.path }));
@@ -77,42 +102,68 @@ export function FileTreeNode({
   );
 
   return (
-    <li role="treeitem" aria-expanded={isFolder ? expanded : undefined}>
+    <li
+      role="treeitem"
+      // Depth conveys tree nesting to assistive tech (indentation is visual
+      // only). aria-level is 1-based; `depth` is 0-based. aria-expanded stays on
+      // the treeitem (the <li>) — its child group is nested here, so this is the
+      // element a tree-aware screen reader reads expandability from.
+      aria-level={depth + 1}
+      aria-expanded={isFolder ? expanded : undefined}
+    >
       <button
         type="button"
         onClick={handleClick}
+        onDoubleClick={onActivate ? handleDoubleClick : undefined}
         draggable={isDraggable}
         onDragStart={isDraggable ? handleDragStart : undefined}
         className={cn(
-          "flex w-full items-center gap-1.5 px-3 py-1 text-left text-xs transition-colors",
+          "flex w-full items-center gap-1.5 py-1 text-left text-xs transition-colors",
           "hover:bg-muted",
           "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
           isSelected && !isFolder && "bg-muted text-foreground font-medium",
           !isSelected && "text-muted-foreground",
           isDraggable && "cursor-grab active:cursor-grabbing",
         )}
-        style={{ paddingLeft: `${12 + depth * 12}px` }}
+        // Indent-guide mode indents via the nested group's margin, so rows need
+        // only a small constant inset; padding mode keeps the per-depth inset.
+        style={{ paddingLeft: indentGuides ? "8px" : `${12 + depth * 12}px`, paddingRight: "8px" }}
         aria-current={isSelected ? "true" : undefined}
       >
         {isFolder && (
-          <span className="text-[10px] text-muted-foreground-subtle">
+          <span
+            aria-hidden="true"
+            className="text-[10px] text-muted-foreground-subtle"
+          >
             {expanded ? "▼" : "▶"}
           </span>
         )}
+        {showIcons &&
+          (isFolder ? (
+            <FolderTypeIcon open={expanded} />
+          ) : (
+            <FileTypeIcon fileName={node.name} />
+          ))}
         <span className={cn("truncate", isFolder && "font-medium text-foreground")}>
           {node.name}
         </span>
       </button>
       {isFolder && expanded && node.children && (
-        <ul role="group">
+        <ul
+          role="group"
+          className={cn(indentGuides && "ml-3 border-l border-border")}
+        >
           {node.children.map((child) => (
             <FileTreeNode
               key={child.path}
               node={child}
               selectedPath={selectedPath}
               onSelect={onSelect}
+              onActivate={onActivate}
               depth={depth + 1}
               enableDrag={enableDrag}
+              showIcons={showIcons}
+              indentGuides={indentGuides}
               maxInitialDepth={maxInitialDepth}
             />
           ))}

package/src/internal/file-tree/__tests__/FileTreeNode-explorer.test.tsx

@@ -0,0 +1,86 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import { FileTreeNode } from "../FileTreeNode";
+import type { TreeNode } from "../tree-node";
+
+afterEach(cleanup);
+
+const fileNode: TreeNode = { name: "a.ts", path: "src/a.ts" };
+const folderNode: TreeNode = {
+  name: "src",
+  path: "src/",
+  children: [fileNode],
+};
+
+describe("FileTreeNode — explorer props", () => {
+  it("renders an icon before the name when showIcons is set", () => {
+    render(
+      <ul>
+        <FileTreeNode node={fileNode} selectedPath="" onSelect={vi.fn()} depth={0} showIcons />
+      </ul>,
+    );
+    const button = screen.getByText("a.ts").closest("button")!;
+    expect(button.querySelector("svg")).toBeTruthy();
+  });
+
+  it("renders no icon by default (unchanged for existing consumers)", () => {
+    render(
+      <ul>
+        <FileTreeNode node={fileNode} selectedPath="" onSelect={vi.fn()} depth={0} />
+      </ul>,
+    );
+    const button = screen.getByText("a.ts").closest("button")!;
+    expect(button.querySelector("svg")).toBeNull();
+  });
+
+  it("calls onActivate on double-click of a file", () => {
+    const onActivate = vi.fn();
+    render(
+      <ul>
+        <FileTreeNode
+          node={fileNode}
+          selectedPath=""
+          onSelect={vi.fn()}
+          onActivate={onActivate}
+          depth={0}
+        />
+      </ul>,
+    );
+    fireEvent.doubleClick(screen.getByText("a.ts"));
+    expect(onActivate).toHaveBeenCalledWith("src/a.ts");
+  });
+
+  it("does not call onActivate on a folder double-click", () => {
+    const onActivate = vi.fn();
+    render(
+      <ul>
+        <FileTreeNode
+          node={folderNode}
+          selectedPath=""
+          onSelect={vi.fn()}
+          onActivate={onActivate}
+          depth={0}
+        />
+      </ul>,
+    );
+    fireEvent.doubleClick(screen.getByText("src"));
+    expect(onActivate).not.toHaveBeenCalled();
+  });
+
+  it("draws an indent guide on nested groups when indentGuides is set", () => {
+    const { container } = render(
+      <ul>
+        <FileTreeNode
+          node={folderNode}
+          selectedPath=""
+          onSelect={vi.fn()}
+          depth={0}
+          indentGuides
+        />
+      </ul>,
+    );
+    // The nested group carries the guide border class.
+    const group = container.querySelector('ul[role="group"]');
+    expect(group?.className).toContain("border-l");
+  });
+});