@stigmer/react 0.4.8 → 0.5.0

package/src/version-history/VersionTimelineEntry.tsx

@@ -0,0 +1,254 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { VersionTimelineEntryProps } from "./types";
+
+/**
+ * A single row in a version timeline.
+ *
+ * Renders a version entry with: truncated hash badge, relative timestamp,
+ * actor info, tag badge, "current" indicator, and git provenance link.
+ * Supports keyboard activation and focus management.
+ *
+ * All visual properties flow through `--stgm-*` design tokens.
+ * Zero Console dependencies — safe for platform builder embedding.
+ *
+ * @example
+ * ```tsx
+ * <VersionTimelineEntry
+ *   entry={version}
+ *   isSelected={selectedId === version.id}
+ *   onSelect={() => setSelectedId(version.id)}
+ * />
+ * ```
+ */
+export function VersionTimelineEntry({
+  entry,
+  isSelected,
+  isCompareSource,
+  isLast,
+  onSelect,
+  trailing,
+}: VersionTimelineEntryProps) {
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      onSelect?.();
+    }
+  };
+
+  return (
+    <div
+      role="listitem"
+      aria-current={entry.isCurrent ? "true" : undefined}
+      className="relative flex gap-3"
+    >
+      {/* Timeline connector */}
+      <div className="flex flex-col items-center pt-1">
+        <div
+          className={cn(
+            "size-2.5 shrink-0 rounded-full border-2",
+            entry.isCurrent
+              ? "border-primary bg-primary"
+              : isCompareSource
+                ? "border-primary border-dashed bg-background"
+                : isSelected
+                  ? "border-primary bg-background"
+                  : "border-border bg-background",
+          )}
+          aria-hidden="true"
+        />
+        {!isLast && (
+          <div className="mt-1 w-px flex-1 bg-border" aria-hidden="true" />
+        )}
+      </div>
+
+      {/* Entry content */}
+      <button
+        type="button"
+        onClick={onSelect}
+        onKeyDown={handleKeyDown}
+        tabIndex={0}
+        aria-selected={isSelected}
+        className={cn(
+          "mb-4 flex min-w-0 flex-1 flex-col gap-1 rounded-md px-2.5 py-2 text-left transition-colors",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          isCompareSource
+            ? "border border-dashed border-primary bg-primary-subtle"
+            : isSelected
+              ? "bg-accent-hover"
+              : "hover:bg-accent-hover",
+        )}
+      >
+        {/* Top line: hash + tag + current badge */}
+        <div className="flex items-center gap-2">
+          <code
+            className="shrink-0 rounded bg-muted px-1.5 py-0.5 font-mono text-[11px] font-medium text-foreground"
+            title={entry.id}
+          >
+            {entry.label}
+          </code>
+
+          {isCompareSource && (
+            <span className="shrink-0 rounded-full bg-primary px-1.5 py-0.5 text-[10px] font-medium text-primary-foreground">
+              A
+            </span>
+          )}
+
+          {entry.tag && (
+            <span className="shrink-0 rounded-full bg-primary-subtle px-1.5 py-0.5 text-[10px] font-medium text-primary">
+              {entry.tag}
+            </span>
+          )}
+
+          {entry.isCurrent && (
+            <span className="shrink-0 rounded-full bg-status-ready-subtle px-1.5 py-0.5 text-[10px] font-medium text-status-ready">
+              current
+            </span>
+          )}
+
+          {trailing && (
+            <div className="ml-auto shrink-0">{trailing}</div>
+          )}
+        </div>
+
+        {/* Second line: timestamp + actor */}
+        <div className="flex items-center gap-2 text-xs text-muted-foreground">
+          <time
+            dateTime={entry.timestamp.toISOString()}
+            title={entry.timestamp.toLocaleString()}
+          >
+            {formatRelativeTime(entry.timestamp)}
+          </time>
+
+          {entry.actor && (
+            <>
+              <span aria-hidden="true">&middot;</span>
+              <span className="flex items-center gap-1">
+                {entry.actor.avatar && (
+                  <img
+                    src={entry.actor.avatar}
+                    alt=""
+                    className="size-3.5 rounded-full"
+                  />
+                )}
+                <span>{entry.actor.displayName || entry.actor.id}</span>
+              </span>
+            </>
+          )}
+        </div>
+
+        {/* Optional sublabel (commit message) */}
+        {entry.sublabel && (
+          <p className="text-xs text-muted-foreground">
+            {entry.sublabel}
+          </p>
+        )}
+
+        {/* Git provenance */}
+        {entry.gitProvenance && (
+          <GitProvenanceRow provenance={entry.gitProvenance} />
+        )}
+      </button>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Git provenance inline display
+// ---------------------------------------------------------------------------
+
+function GitProvenanceRow({
+  provenance,
+}: {
+  readonly provenance: NonNullable<VersionTimelineEntryProps["entry"]["gitProvenance"]>;
+}) {
+  const repoUrl = normalizeGitUrl(provenance.remoteUrl);
+  const truncatedCommit = provenance.commit.slice(0, 7);
+  const commitUrl = repoUrl
+    ? `${repoUrl}/commit/${provenance.commit}`
+    : null;
+
+  return (
+    <div className="flex items-center gap-1.5 text-[11px] text-muted-foreground">
+      <GitIcon className="size-3 shrink-0" />
+      {provenance.ref && (
+        <span className="font-medium">{provenance.ref}</span>
+      )}
+      {commitUrl ? (
+        <a
+          href={commitUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="font-mono text-primary underline-offset-2 hover:underline"
+          onClick={(e) => e.stopPropagation()}
+        >
+          {truncatedCommit}
+        </a>
+      ) : (
+        <code className="font-mono">{truncatedCommit}</code>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function formatRelativeTime(date: Date): string {
+  const now = Date.now();
+  const diffMs = now - date.getTime();
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+  const diffHr = Math.floor(diffMin / 60);
+  const diffDays = Math.floor(diffHr / 24);
+
+  if (diffSec < 60) return "just now";
+  if (diffMin < 60) return `${diffMin}m ago`;
+  if (diffHr < 24) return `${diffHr}h ago`;
+  if (diffDays < 7) return `${diffDays}d ago`;
+  if (diffDays < 30) return `${Math.floor(diffDays / 7)}w ago`;
+
+  return date.toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+    year: date.getFullYear() !== new Date().getFullYear() ? "numeric" : undefined,
+  });
+}
+
+function normalizeGitUrl(url: string): string | null {
+  if (!url) return null;
+  const cleaned = url.replace(/\.git$/, "");
+  if (cleaned.startsWith("https://") || cleaned.startsWith("http://")) {
+    return cleaned;
+  }
+  const sshMatch = cleaned.match(/^(?:git@|ssh:\/\/)([^:/]+)[:/](.+)$/);
+  if (sshMatch) {
+    return `https://${sshMatch[1]}/${sshMatch[2]}`;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+
+function GitIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx="8" cy="4" r="2" />
+      <circle cx="8" cy="12" r="2" />
+      <path d="M8 6v4" />
+    </svg>
+  );
+}

package/src/version-history/computeDiff.ts

@@ -0,0 +1,61 @@
+import { structuredPatch } from "diff";
+import type { DiffHunk, DiffLine } from "./types";
+
+/**
+ * Compute a unified diff between two text strings.
+ *
+ * Returns an array of {@link DiffHunk} objects, each containing the
+ * changed and context lines with line numbers. Uses the `diff` library's
+ * Myers algorithm internally.
+ *
+ * Pure function — no side effects, safe to call outside React.
+ *
+ * @param oldText - The "before" text content.
+ * @param newText - The "after" text content.
+ * @param contextLines - Number of unchanged context lines around changes (default: 3).
+ */
+export function computeDiff(
+  oldText: string,
+  newText: string,
+  contextLines = 3,
+): readonly DiffHunk[] {
+  const patch = structuredPatch("a", "b", oldText, newText, "", "", {
+    context: contextLines,
+  });
+
+  return patch.hunks.map((hunk) => {
+    const lines: DiffLine[] = [];
+    let oldLine = hunk.oldStart;
+    let newLine = hunk.newStart;
+
+    for (const raw of hunk.lines) {
+      const prefix = raw[0];
+      const content = raw.slice(1);
+
+      if (prefix === "+") {
+        lines.push({ type: "added", content, newLineNumber: newLine });
+        newLine++;
+      } else if (prefix === "-") {
+        lines.push({ type: "removed", content, oldLineNumber: oldLine });
+        oldLine++;
+      } else {
+        lines.push({
+          type: "context",
+          content,
+          oldLineNumber: oldLine,
+          newLineNumber: newLine,
+        });
+        oldLine++;
+        newLine++;
+      }
+    }
+
+    return {
+      oldStart: hunk.oldStart,
+      oldLines: hunk.oldLines,
+      newStart: hunk.newStart,
+      newLines: hunk.newLines,
+      lines,
+    };
+  });
+}

package/src/version-history/computeMultiFileDiff.ts

@@ -0,0 +1,97 @@
+import type { DiffHunk, FileDiffEntry, MultiFileDiffResult } from "./types";
+import { computeDiff } from "./computeDiff";
+
+/**
+ * Compute a multi-file diff between two snapshots of a file tree.
+ *
+ * Each snapshot is a `Map<path, textContent>`. The function categorises
+ * every path as `added`, `removed`, or `modified`, computes per-file
+ * unified diffs for modified files, and returns an aggregate result.
+ *
+ * Pure function — no side effects, safe to call outside React.
+ *
+ * @param oldFiles - File map for the "before" version.
+ * @param newFiles - File map for the "after" version.
+ */
+export function computeMultiFileDiff(
+  oldFiles: ReadonlyMap<string, string>,
+  newFiles: ReadonlyMap<string, string>,
+): MultiFileDiffResult {
+  const diffCache = new Map<string, readonly DiffHunk[]>();
+  const files: FileDiffEntry[] = [];
+  let totalAdditions = 0;
+  let totalDeletions = 0;
+
+  const allPaths = new Set([...oldFiles.keys(), ...newFiles.keys()]);
+
+  for (const path of allPaths) {
+    const oldContent = oldFiles.get(path);
+    const newContent = newFiles.get(path);
+
+    if (oldContent === undefined && newContent !== undefined) {
+      const lineCount = countLines(newContent);
+      files.push({ path, changeType: "added", additions: lineCount, deletions: 0 });
+      totalAdditions += lineCount;
+
+      const hunks = computeDiff("", newContent);
+      diffCache.set(path, hunks);
+    } else if (oldContent !== undefined && newContent === undefined) {
+      const lineCount = countLines(oldContent);
+      files.push({ path, changeType: "removed", additions: 0, deletions: lineCount });
+      totalDeletions += lineCount;
+
+      const hunks = computeDiff(oldContent, "");
+      diffCache.set(path, hunks);
+    } else if (oldContent !== undefined && newContent !== undefined && oldContent !== newContent) {
+      const hunks = computeDiff(oldContent, newContent);
+      const additions = hunks.reduce(
+        (sum, h) => sum + h.lines.filter((l) => l.type === "added").length,
+        0,
+      );
+      const deletions = hunks.reduce(
+        (sum, h) => sum + h.lines.filter((l) => l.type === "removed").length,
+        0,
+      );
+      files.push({ path, changeType: "modified", additions, deletions });
+      totalAdditions += additions;
+      totalDeletions += deletions;
+      diffCache.set(path, hunks);
+    }
+  }
+
+  files.sort(fileSortComparator);
+
+  return {
+    files,
+    totalAdditions,
+    totalDeletions,
+    getDiff: (path: string) => diffCache.get(path) ?? [],
+  };
+}
+
+function countLines(text: string): number {
+  if (text.length === 0) return 0;
+  let count = 1;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "\n") count++;
+  }
+  return count;
+}
+
+/**
+ * Sort changed files: SKILL.md first (primary file), then alphabetically.
+ * Modified files before added, added before removed — mirrors GitHub's
+ * convention of showing the most actionable changes first.
+ */
+function fileSortComparator(a: FileDiffEntry, b: FileDiffEntry): number {
+  const aIsSkillMd = a.path === "SKILL.md" || a.path === "skill.md";
+  const bIsSkillMd = b.path === "SKILL.md" || b.path === "skill.md";
+  if (aIsSkillMd && !bIsSkillMd) return -1;
+  if (!aIsSkillMd && bIsSkillMd) return 1;
+
+  const order: Record<string, number> = { modified: 0, added: 1, removed: 2 };
+  const typeSort = (order[a.changeType] ?? 3) - (order[b.changeType] ?? 3);
+  if (typeSort !== 0) return typeSort;
+
+  return a.path.localeCompare(b.path);
+}

package/src/version-history/index.ts

@@ -0,0 +1,22 @@
+export { VersionTimeline } from "./VersionTimeline";
+export { VersionTimelineEntry } from "./VersionTimelineEntry";
+export { DiffViewer } from "./DiffViewer";
+export type { DiffViewerProps } from "./DiffViewer";
+export { DiffFileList } from "./DiffFileList";
+export type { DiffFileListProps } from "./DiffFileList";
+export { DiffSummary } from "./DiffSummary";
+export type { DiffSummaryProps } from "./DiffSummary";
+export { MultiFileDiffView } from "./MultiFileDiffView";
+export type { MultiFileDiffViewProps } from "./MultiFileDiffView";
+export { computeDiff } from "./computeDiff";
+export { computeMultiFileDiff } from "./computeMultiFileDiff";
+export type {
+  VersionEntry,
+  VersionTimelineProps,
+  VersionTimelineEntryProps,
+  DiffLine,
+  DiffHunk,
+  FileDiffEntry,
+  MultiFileDiffResult,
+  DiffViewMode,
+} from "./types";

package/src/version-history/types.ts

@@ -0,0 +1,129 @@
+import type { ReactNode } from "react";
+
+// ---------------------------------------------------------------------------
+// Diff types — generic text diff primitives for any versioned resource
+// ---------------------------------------------------------------------------
+
+/** A single line within a diff hunk. */
+export interface DiffLine {
+  readonly type: "added" | "removed" | "context";
+  readonly content: string;
+  readonly oldLineNumber?: number;
+  readonly newLineNumber?: number;
+}
+
+/** A contiguous group of changed/context lines in a unified diff. */
+export interface DiffHunk {
+  readonly oldStart: number;
+  readonly oldLines: number;
+  readonly newStart: number;
+  readonly newLines: number;
+  readonly lines: readonly DiffLine[];
+}
+
+/** Summary of changes to a single file between two versions. */
+export interface FileDiffEntry {
+  readonly path: string;
+  readonly changeType: "added" | "removed" | "modified";
+  readonly additions: number;
+  readonly deletions: number;
+}
+
+/** Aggregated diff result across all files in two version snapshots. */
+export interface MultiFileDiffResult {
+  readonly files: readonly FileDiffEntry[];
+  readonly totalAdditions: number;
+  readonly totalDeletions: number;
+  /** Retrieve the hunk-level diff for a specific file path. */
+  readonly getDiff: (path: string) => readonly DiffHunk[];
+}
+
+/** Display mode for the diff viewer. */
+export type DiffViewMode = "unified";
+
+// ---------------------------------------------------------------------------
+// Generic version entry — presentation-layer type for the timeline component
+// ---------------------------------------------------------------------------
+
+/**
+ * A single entry in a version timeline.
+ *
+ * This is a generic presentation type — not tied to any specific resource.
+ * Resource-specific hooks (e.g., `useSkillVersions`) map from proto types
+ * to this shape, enabling the `VersionTimeline` component to render version
+ * history for any resource type.
+ */
+export interface VersionEntry {
+  /** Unique identifier for this version (e.g., content hash). */
+  readonly id: string;
+  /** When this version was created/pushed. */
+  readonly timestamp: Date;
+  /** Actor who created this version. */
+  readonly actor?: {
+    readonly id: string;
+    readonly avatar?: string;
+    readonly displayName?: string;
+  };
+  /** Primary display text (e.g., truncated content hash). */
+  readonly label: string;
+  /** Secondary text (e.g., commit message or version description). */
+  readonly sublabel?: string;
+  /** Whether this is the currently active version. */
+  readonly isCurrent?: boolean;
+  /** Version tag (e.g., "stable", "v1.0"). */
+  readonly tag?: string;
+  /** Git provenance for traceability. */
+  readonly gitProvenance?: {
+    readonly remoteUrl: string;
+    readonly ref: string;
+    readonly commit: string;
+  };
+  /** Extensible key-value metadata for display. */
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// VersionTimeline props
+// ---------------------------------------------------------------------------
+
+/** Props for {@link VersionTimeline}. */
+export interface VersionTimelineProps {
+  /** Ordered list of version entries (newest first). */
+  readonly entries: readonly VersionEntry[];
+  /** Called when a single entry is selected (clicked). */
+  readonly onEntrySelect?: (id: string) => void;
+  /**
+   * Called when two entries are selected for comparison.
+   * The component manages compare-mode selection internally when this
+   * callback is provided — enabling T05-D integration.
+   */
+  readonly onCompare?: (fromId: string, toId: string) => void;
+  /** Currently selected entry ID (controlled selection). */
+  readonly selectedId?: string;
+  /** `true` while version data is being fetched. */
+  readonly isLoading?: boolean;
+  /** Message shown when `entries` is empty and not loading. */
+  readonly emptyMessage?: string;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// VersionTimelineEntry props
+// ---------------------------------------------------------------------------
+
+/** Props for {@link VersionTimelineEntry}. */
+export interface VersionTimelineEntryProps {
+  /** The version entry data to render. */
+  readonly entry: VersionEntry;
+  /** Whether this entry is currently selected. */
+  readonly isSelected?: boolean;
+  /** Whether this entry is the first pick in compare mode (dashed border, "A" badge). */
+  readonly isCompareSource?: boolean;
+  /** Whether this is the last entry in the timeline (no connecting line below). */
+  readonly isLast?: boolean;
+  /** Called when this entry is clicked. */
+  readonly onSelect?: () => void;
+  /** Optional trailing content (e.g., action buttons). */
+  readonly trailing?: ReactNode;
+}