@stigmer/react 0.4.8 → 0.5.1

package/src/version-history/DiffViewer.tsx

@@ -0,0 +1,163 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { DiffHunk, DiffLine } from "./types";
+
+/** Props for {@link DiffViewer}. */
+export interface DiffViewerProps {
+  /** Hunks to render — output of `computeDiff()`. */
+  readonly hunks: readonly DiffHunk[];
+  /** File path displayed in the header. */
+  readonly filePath?: string;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Generic unified diff renderer for a single file.
+ *
+ * Renders a unified diff with line numbers, `+`/`-` prefix indicators,
+ * and hunk separator headers. Uses `--stgm-diff-*` design tokens for
+ * all colors — respects light/dark mode and preset overrides.
+ *
+ * Accessibility: uses a `<table>` with proper column headers, `+`/`-`
+ * text indicators alongside color (color is never the sole channel),
+ * and ARIA labels on change lines for screen readers.
+ *
+ * Zero Console dependencies — safe for platform builder embedding.
+ *
+ * @example
+ * ```tsx
+ * const hunks = computeDiff(oldText, newText);
+ * <DiffViewer hunks={hunks} filePath="SKILL.md" />
+ * ```
+ */
+export function DiffViewer({ hunks, filePath, className }: DiffViewerProps) {
+  if (hunks.length === 0) {
+    return (
+      <div
+        role="status"
+        className={cn(
+          "flex items-center justify-center py-8 text-sm text-muted-foreground",
+          className,
+        )}
+      >
+        No changes
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cn(
+        "overflow-auto rounded-lg border border-border font-mono text-[13px] leading-[1.6]",
+        className,
+      )}
+    >
+      {filePath && (
+        <div className="sticky top-0 z-10 border-b border-border bg-muted px-3 py-1.5 text-xs font-medium text-muted-foreground">
+          {filePath}
+        </div>
+      )}
+
+      <table className="w-full border-collapse" role="table">
+        <thead className="sr-only">
+          <tr>
+            <th scope="col">Old line</th>
+            <th scope="col">New line</th>
+            <th scope="col">Change</th>
+            <th scope="col">Content</th>
+          </tr>
+        </thead>
+        <tbody>
+          {hunks.map((hunk, hunkIdx) => (
+            <HunkRows key={hunkIdx} hunk={hunk} isFirst={hunkIdx === 0} />
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Hunk rendering
+// ---------------------------------------------------------------------------
+
+function HunkRows({
+  hunk,
+  isFirst,
+}: {
+  readonly hunk: DiffHunk;
+  readonly isFirst: boolean;
+}) {
+  const header = `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`;
+
+  return (
+    <>
+      {!isFirst && (
+        <tr>
+          <td
+            colSpan={4}
+            className="select-none bg-diff-hunk-header-bg px-3 py-1 text-[11px] text-diff-hunk-header-fg"
+            aria-label={`Hunk: ${header}`}
+          >
+            {header}
+          </td>
+        </tr>
+      )}
+      {hunk.lines.map((line, lineIdx) => (
+        <DiffLineRow key={lineIdx} line={line} />
+      ))}
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Line rendering
+// ---------------------------------------------------------------------------
+
+const LINE_NUM_CLASSES =
+  "w-[1px] min-w-10 select-none whitespace-nowrap px-2 text-right text-[11px] text-muted-foreground-faint";
+const MARKER_CLASSES = "w-[1px] select-none px-1 text-center";
+
+function DiffLineRow({ line }: { readonly line: DiffLine }) {
+  const marker = line.type === "added" ? "+" : line.type === "removed" ? "-" : " ";
+
+  const rowClass =
+    line.type === "added"
+      ? "bg-diff-added-bg"
+      : line.type === "removed"
+        ? "bg-diff-removed-bg"
+        : "";
+
+  const markerColor =
+    line.type === "added"
+      ? "text-diff-added-fg"
+      : line.type === "removed"
+        ? "text-diff-removed-fg"
+        : "text-muted-foreground-faint";
+
+  const ariaLabel =
+    line.type === "added"
+      ? `Added line ${line.newLineNumber}: ${line.content}`
+      : line.type === "removed"
+        ? `Removed line ${line.oldLineNumber}: ${line.content}`
+        : undefined;
+
+  return (
+    <tr className={rowClass} aria-label={ariaLabel}>
+      <td className={LINE_NUM_CLASSES}>
+        {line.oldLineNumber ?? ""}
+      </td>
+      <td className={LINE_NUM_CLASSES}>
+        {line.newLineNumber ?? ""}
+      </td>
+      <td className={cn(MARKER_CLASSES, markerColor)} aria-hidden="true">
+        {marker}
+      </td>
+      <td className="whitespace-pre-wrap break-all px-2">
+        {line.content}
+      </td>
+    </tr>
+  );
+}

package/src/version-history/MultiFileDiffView.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { cn } from "@stigmer/theme";
+import type { MultiFileDiffResult } from "./types";
+import { DiffViewer } from "./DiffViewer";
+import { DiffFileList } from "./DiffFileList";
+import { DiffSummary } from "./DiffSummary";
+
+/** Props for {@link MultiFileDiffView}. */
+export interface MultiFileDiffViewProps {
+  /** Multi-file diff result from `computeMultiFileDiff()`. */
+  readonly diff: MultiFileDiffResult;
+  /**
+   * Initially selected file path. When omitted, defaults to the first
+   * changed file (SKILL.md if present, per the sort order).
+   */
+  readonly initialSelectedPath?: string;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Composed multi-file diff view with file list and per-file unified diff.
+ *
+ * Layout: summary bar at top, file list as a horizontal scrollable bar,
+ * and the full unified diff for the selected file below. Designed to
+ * work within a dialog or a detail page panel.
+ *
+ * Zero Console dependencies — safe for platform builder embedding.
+ *
+ * @example
+ * ```tsx
+ * const diff = computeMultiFileDiff(oldFiles, newFiles);
+ * <MultiFileDiffView diff={diff} />
+ * ```
+ */
+export function MultiFileDiffView({
+  diff,
+  initialSelectedPath,
+  className,
+}: MultiFileDiffViewProps) {
+  const [selectedPath, setSelectedPath] = useState<string | null>(
+    initialSelectedPath ?? diff.files[0]?.path ?? null,
+  );
+
+  const handleSelect = useCallback((path: string) => {
+    setSelectedPath(path);
+  }, []);
+
+  const hunks = selectedPath ? diff.getDiff(selectedPath) : [];
+
+  if (diff.files.length === 0) {
+    return (
+      <div
+        role="status"
+        className={cn(
+          "flex flex-col items-center gap-2 py-12 text-center",
+          className,
+        )}
+      >
+        <NoDiffIcon className="size-8 text-muted-foreground-faint" />
+        <p className="text-sm text-muted-foreground">No differences found</p>
+        <p className="text-xs text-muted-foreground-subtle">
+          These two versions have identical content.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("flex flex-col gap-3", className)}>
+      <DiffSummary
+        fileCount={diff.files.length}
+        additions={diff.totalAdditions}
+        deletions={diff.totalDeletions}
+      />
+
+      {diff.files.length > 1 && (
+        <div className="overflow-hidden rounded-lg border border-border">
+          <DiffFileList
+            files={diff.files}
+            selectedPath={selectedPath}
+            onSelect={handleSelect}
+          />
+        </div>
+      )}
+
+      <DiffViewer hunks={hunks} filePath={selectedPath ?? undefined} />
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+
+function NoDiffIcon({ 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"
+    >
+      <path d="M8 3v10M3 8h10" />
+      <circle cx="8" cy="8" r="7" />
+    </svg>
+  );
+}

package/src/version-history/VersionTimeline.tsx

@@ -0,0 +1,232 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { cn } from "@stigmer/theme";
+import type { VersionTimelineProps } from "./types";
+import { VersionTimelineEntry } from "./VersionTimelineEntry";
+
+/**
+ * Accessible vertical timeline for version history.
+ *
+ * Renders a chronologically-ordered list of version entries with a
+ * connecting line, selection state, and optional compare mode. Designed
+ * as a generic SDK primitive usable for any versioned resource (skills,
+ * and in future, agents, MCP servers).
+ *
+ * Supports two interaction modes:
+ * - **Select mode** (default): single-click selects an entry, fires `onEntrySelect`
+ * - **Compare mode** (when `onCompare` is provided): selecting two entries fires
+ *   `onCompare(fromId, toId)` — designed for T05-D diff viewer integration
+ *
+ * All visual properties flow through `--stgm-*` design tokens.
+ * Zero Console dependencies — safe for platform builder embedding.
+ *
+ * @example
+ * ```tsx
+ * const { versions } = useSkillVersions(org, slug);
+ *
+ * <VersionTimeline
+ *   entries={versions}
+ *   onEntrySelect={(id) => console.log("Selected:", id)}
+ * />
+ * ```
+ */
+export function VersionTimeline({
+  entries,
+  onEntrySelect,
+  onCompare,
+  selectedId,
+  isLoading,
+  emptyMessage = "No version history available",
+  className,
+}: VersionTimelineProps) {
+  const [compareSelection, setCompareSelection] = useState<string | null>(null);
+
+  const handleSelect = useCallback(
+    (id: string) => {
+      if (onCompare) {
+        if (compareSelection === null) {
+          setCompareSelection(id);
+        } else if (compareSelection === id) {
+          setCompareSelection(null);
+        } else {
+          onCompare(compareSelection, id);
+          setCompareSelection(null);
+        }
+      }
+
+      onEntrySelect?.(id);
+    },
+    [onCompare, onEntrySelect, compareSelection],
+  );
+
+  const cancelCompare = useCallback(() => {
+    setCompareSelection(null);
+  }, []);
+
+  if (isLoading) {
+    return <TimelineSkeleton className={className} />;
+  }
+
+  if (entries.length === 0) {
+    return <EmptyState message={emptyMessage} className={className} />;
+  }
+
+  const compareLabel = compareSelection
+    ? entries.find((e) => e.id === compareSelection)?.label ?? compareSelection.slice(0, 12)
+    : null;
+
+  return (
+    <div className={cn("flex flex-col pt-2", className)}>
+      {compareSelection && (
+        <CompareInfoBar
+          selectedLabel={compareLabel!}
+          onCancel={cancelCompare}
+        />
+      )}
+
+      <div role="list" aria-label="Version history">
+        {entries.map((entry, index) => (
+          <VersionTimelineEntry
+            key={entry.id}
+            entry={entry}
+            isSelected={entry.id === selectedId}
+            isCompareSource={entry.id === compareSelection}
+            isLast={index === entries.length - 1}
+            onSelect={() => handleSelect(entry.id)}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Compare-mode info bar
+// ---------------------------------------------------------------------------
+
+function CompareInfoBar({
+  selectedLabel,
+  onCancel,
+}: {
+  readonly selectedLabel: string;
+  readonly onCancel: () => void;
+}) {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="mb-3 flex items-center gap-2 rounded-md border border-dashed border-primary bg-primary-subtle px-3 py-2 text-xs"
+    >
+      <CompareIcon className="size-3.5 shrink-0 text-primary" />
+      <span className="flex-1 text-foreground">
+        Select another version to compare with{" "}
+        <code className="rounded bg-muted px-1 py-0.5 font-mono text-[10px] font-medium">
+          {selectedLabel}
+        </code>
+      </span>
+      <button
+        type="button"
+        onClick={onCancel}
+        className={cn(
+          "rounded px-2 py-0.5 text-[10px] font-medium text-muted-foreground transition-colors",
+          "hover:bg-accent-hover hover:text-foreground",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        )}
+      >
+        Cancel
+      </button>
+    </div>
+  );
+}
+
+function CompareIcon({ 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"
+    >
+      <path d="M5 12V4M5 4l-3 3M11 4v8M11 12l3-3" />
+    </svg>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Non-happy states
+// ---------------------------------------------------------------------------
+
+function TimelineSkeleton({ className }: { readonly className?: string }) {
+  return (
+    <div
+      className={cn("flex flex-col gap-4 pt-2", className)}
+      aria-busy="true"
+      aria-label="Loading version history"
+    >
+      {[1, 2, 3].map((i) => (
+        <div key={i} className="flex gap-3">
+          <div className="flex flex-col items-center">
+            <div className="size-2.5 animate-pulse rounded-full bg-muted" />
+            {i < 3 && <div className="mt-1 w-px flex-1 bg-border" />}
+          </div>
+          <div className="mb-4 flex-1 space-y-2 px-2.5 py-2">
+            <div className="flex gap-2">
+              <div className="h-4 w-20 animate-pulse rounded bg-muted" />
+              <div className="h-4 w-12 animate-pulse rounded-full bg-muted" />
+            </div>
+            <div className="h-3 w-32 animate-pulse rounded bg-muted" />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function EmptyState({
+  message,
+  className,
+}: {
+  readonly message: string;
+  readonly className?: string;
+}) {
+  return (
+    <div
+      role="status"
+      className={cn(
+        "flex flex-col items-center gap-2 py-8 text-center",
+        className,
+      )}
+    >
+      <HistoryIcon className="size-8 text-muted-foreground-faint" />
+      <p className="text-sm text-muted-foreground">{message}</p>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+
+function HistoryIcon({ 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"
+    >
+      <path d="M8 4v4l2.5 1.5" />
+      <circle cx="8" cy="8" r="6" />
+      <path d="M2 8a6 6 0 0 1 6-6" />
+    </svg>
+  );
+}