@stigmer/react 0.4.8 → 0.5.1

package/src/skill/useSkillVersions.ts

@@ -0,0 +1,165 @@
+"use client";
+
+import { useCallback, useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { StigmerError } from "@stigmer/sdk";
+import {
+  ListSkillVersionsInputSchema,
+  type SkillVersionEntry as ProtoSkillVersionEntry,
+} from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+import type { VersionEntry } from "../version-history/types";
+
+// gRPC/Connect Code.Unimplemented = 12
+const CODE_UNIMPLEMENTED = 12;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Return value of {@link useSkillVersions}. */
+export interface UseSkillVersionsReturn {
+  /** Version entries mapped to the generic timeline format (newest first). */
+  readonly versions: readonly VersionEntry[];
+  /** `true` when no versions are available (RPC unimplemented or empty response). */
+  readonly isEmpty: boolean;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request (excludes UNIMPLEMENTED), or `null`. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+  /**
+   * Look up the artifact storage key for a version by its hash.
+   * Used by diff flows to fetch historical artifacts via `getArtifact()`.
+   * Returns `null` if the version hash is not found or has no artifact key.
+   */
+  readonly getArtifactKey: (versionHash: string) => string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Hook implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Data hook that fetches version history for a skill.
+ *
+ * Calls the `listVersions` RPC via the SDK client and maps the response
+ * to generic {@link VersionEntry} objects for the `VersionTimeline`
+ * component.
+ *
+ * **Graceful degradation**: If the backend returns UNIMPLEMENTED (the
+ * RPC handler hasn't been deployed yet), the hook treats it as an empty
+ * response — `versions` is `[]` and `isEmpty` is `true`. No error is
+ * surfaced to the consumer. This enables the frontend to ship ahead of
+ * the backend without visual breakage.
+ *
+ * Pass `null` for `org` or `slug` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { versions, isEmpty, isLoading } = useSkillVersions("acme", "code-style-guide");
+ *
+ * if (!isEmpty) {
+ *   return <VersionTimeline entries={versions} />;
+ * }
+ * ```
+ */
+export function useSkillVersions(
+  org: string | null,
+  slug: string | null,
+): UseSkillVersionsReturn {
+  const stigmer = useStigmer();
+
+  const {
+    data: rawVersions,
+    isLoading,
+    error,
+    refetch,
+  } = useFetch(
+    org && slug
+      ? async () => {
+          try {
+            const request = create(ListSkillVersionsInputSchema, {
+              org,
+              slug,
+            });
+            const response = await stigmer.skill.listVersions(request);
+            return response.versions;
+          } catch (err) {
+            if (isUnimplemented(err)) return [];
+            throw err;
+          }
+        }
+      : null,
+    [org, slug, stigmer],
+    [] as ProtoSkillVersionEntry[],
+  );
+
+  const versions = useMemo(
+    () => rawVersions.map(mapProtoToVersionEntry),
+    [rawVersions],
+  );
+
+  const artifactKeyMap = useMemo(() => {
+    const map = new Map<string, string>();
+    for (const entry of rawVersions) {
+      if (entry.versionHash && entry.artifactStorageKey) {
+        map.set(entry.versionHash, entry.artifactStorageKey);
+      }
+    }
+    return map;
+  }, [rawVersions]);
+
+  const getArtifactKey = useCallback(
+    (versionHash: string): string | null =>
+      artifactKeyMap.get(versionHash) ?? null,
+    [artifactKeyMap],
+  );
+
+  const isEmpty = versions.length === 0;
+
+  return useMemo(
+    () => ({ versions, isEmpty, isLoading, error, refetch, getArtifactKey }),
+    [versions, isEmpty, isLoading, error, refetch, getArtifactKey],
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Proto → generic mapping
+// ---------------------------------------------------------------------------
+
+function mapProtoToVersionEntry(proto: ProtoSkillVersionEntry): VersionEntry {
+  return {
+    id: proto.versionHash,
+    timestamp: proto.pushedAt ? timestampDate(proto.pushedAt) : new Date(0),
+    actor: proto.pushedBy
+      ? {
+          id: proto.pushedBy.id,
+          avatar: proto.pushedBy.avatar || undefined,
+          displayName: undefined,
+        }
+      : undefined,
+    label: proto.versionHash.slice(0, 12),
+    sublabel: proto.message || undefined,
+    isCurrent: proto.isCurrent,
+    tag: proto.tag || undefined,
+    gitProvenance: proto.gitProvenance
+      ? {
+          remoteUrl: proto.gitProvenance.remoteUrl,
+          ref: proto.gitProvenance.ref,
+          commit: proto.gitProvenance.commit,
+        }
+      : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Error detection
+// ---------------------------------------------------------------------------
+
+function isUnimplemented(err: unknown): boolean {
+  return err instanceof StigmerError && err.connectCode === CODE_UNIMPLEMENTED;
+}

package/src/styles.css

@@ -38,6 +38,7 @@
   --color-info-foreground: var(--stgm-info-foreground);
   --color-border: var(--stgm-border);
   --color-input: var(--stgm-input);
+  --color-input-bg: var(--stgm-input-bg);
   --color-ring: var(--stgm-ring);
   --color-chart-1: var(--stgm-chart-1);
   --color-chart-2: var(--stgm-chart-2);
@@ -70,6 +71,33 @@
   --color-sidebar-accent-foreground: var(--stgm-sidebar-accent-foreground);
   --color-sidebar-border: var(--stgm-sidebar-border);
   --color-sidebar-ring: var(--stgm-sidebar-ring);
+  --color-status-ready: var(--stgm-status-ready);
+  --color-status-ready-foreground: var(--stgm-status-ready-foreground);
+  --color-status-ready-subtle: var(--stgm-status-ready-subtle);
+  --color-status-running: var(--stgm-status-running);
+  --color-status-running-foreground: var(--stgm-status-running-foreground);
+  --color-status-running-subtle: var(--stgm-status-running-subtle);
+  --color-status-pending: var(--stgm-status-pending);
+  --color-status-pending-foreground: var(--stgm-status-pending-foreground);
+  --color-status-pending-subtle: var(--stgm-status-pending-subtle);
+  --color-status-degraded: var(--stgm-status-degraded);
+  --color-status-degraded-foreground: var(--stgm-status-degraded-foreground);
+  --color-status-degraded-subtle: var(--stgm-status-degraded-subtle);
+  --color-status-failed: var(--stgm-status-failed);
+  --color-status-failed-foreground: var(--stgm-status-failed-foreground);
+  --color-status-failed-subtle: var(--stgm-status-failed-subtle);
+  --color-status-disabled: var(--stgm-status-disabled);
+  --color-status-disabled-foreground: var(--stgm-status-disabled-foreground);
+  --color-status-disabled-subtle: var(--stgm-status-disabled-subtle);
+  --color-status-draft: var(--stgm-status-draft);
+  --color-status-draft-foreground: var(--stgm-status-draft-foreground);
+  --color-status-draft-subtle: var(--stgm-status-draft-subtle);
+  --color-diff-added-bg: var(--stgm-diff-added-bg);
+  --color-diff-added-fg: var(--stgm-diff-added-fg);
+  --color-diff-removed-bg: var(--stgm-diff-removed-bg);
+  --color-diff-removed-fg: var(--stgm-diff-removed-fg);
+  --color-diff-hunk-header-bg: var(--stgm-diff-hunk-header-bg);
+  --color-diff-hunk-header-fg: var(--stgm-diff-hunk-header-fg);
   --shadow-sm: var(--stgm-shadow-sm);
   --shadow-md: var(--stgm-shadow-md);
   --shadow-lg: var(--stgm-shadow-lg);

package/src/tabs/Tabs.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import { useCallback, useId, useRef, type KeyboardEvent, type ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+
+export interface TabItem {
+  /** Unique identifier for the tab, used as the `activeTab` value. */
+  readonly id: string;
+  /** Display label shown in the tab trigger. */
+  readonly label: string;
+  /** Optional numeric badge rendered next to the label (e.g. item count). */
+  readonly badge?: number;
+  /** Optional icon rendered before the label. */
+  readonly icon?: ReactNode;
+}
+
+export interface TabsProps {
+  /** Ordered list of tabs to render. Tabs with no matching content are still clickable. */
+  readonly tabs: readonly TabItem[];
+  /** The `id` of the currently active tab. */
+  readonly activeTab: string;
+  /** Called when the user selects a different tab. */
+  readonly onTabChange: (tabId: string) => void;
+  /**
+   * Content to render in the active tab panel.
+   * Typically a switch/map over `activeTab`.
+   */
+  readonly children: ReactNode;
+  /** Accessible label for the tab list (e.g. "Agent detail sections"). */
+  readonly "aria-label"?: string;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Accessible tabbed panel with badge and icon support.
+ *
+ * Implements the WAI-ARIA Tabs pattern:
+ * - `role="tablist"` / `role="tab"` / `role="tabpanel"`
+ * - Arrow-key navigation (Left/Right), Home/End to jump
+ * - `aria-selected`, `aria-controls`, `aria-labelledby` wiring
+ *
+ * All visual properties flow through `--stgm-*` design tokens.
+ * No external dependencies — safe for platform builder embedding.
+ *
+ * @example
+ * ```tsx
+ * const [tab, setTab] = useState("overview");
+ *
+ * <Tabs
+ *   tabs={[
+ *     { id: "overview", label: "Overview" },
+ *     { id: "activity", label: "Activity", badge: 3 },
+ *   ]}
+ *   activeTab={tab}
+ *   onTabChange={setTab}
+ *   aria-label="Agent sections"
+ * >
+ *   {tab === "overview" ? <Overview /> : <Activity />}
+ * </Tabs>
+ * ```
+ */
+export function Tabs({
+  tabs,
+  activeTab,
+  onTabChange,
+  children,
+  "aria-label": ariaLabel,
+  className,
+}: TabsProps) {
+  const instanceId = useId();
+  const tabRefsMap = useRef<Map<string, HTMLButtonElement>>(new Map());
+
+  const tabId = (id: string) => `${instanceId}-tab-${id}`;
+  const panelId = (id: string) => `${instanceId}-panel-${id}`;
+
+  const focusTab = useCallback(
+    (id: string) => {
+      tabRefsMap.current.get(id)?.focus();
+      onTabChange(id);
+    },
+    [onTabChange],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      const currentIndex = tabs.findIndex((t) => t.id === activeTab);
+      if (currentIndex === -1) return;
+
+      let nextIndex: number | null = null;
+
+      switch (e.key) {
+        case "ArrowRight":
+          nextIndex = (currentIndex + 1) % tabs.length;
+          break;
+        case "ArrowLeft":
+          nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
+          break;
+        case "Home":
+          nextIndex = 0;
+          break;
+        case "End":
+          nextIndex = tabs.length - 1;
+          break;
+        default:
+          return;
+      }
+
+      e.preventDefault();
+      focusTab(tabs[nextIndex].id);
+    },
+    [tabs, activeTab, focusTab],
+  );
+
+  return (
+    <div className={cn("flex flex-col", className)}>
+      <div
+        role="tablist"
+        aria-label={ariaLabel}
+        onKeyDown={handleKeyDown}
+        className="flex border-b border-border"
+      >
+        {tabs.map((tab) => {
+          const isActive = tab.id === activeTab;
+          return (
+            <button
+              key={tab.id}
+              ref={(el) => {
+                if (el) tabRefsMap.current.set(tab.id, el);
+                else tabRefsMap.current.delete(tab.id);
+              }}
+              id={tabId(tab.id)}
+              role="tab"
+              type="button"
+              aria-selected={isActive}
+              aria-controls={panelId(tab.id)}
+              tabIndex={isActive ? 0 : -1}
+              onClick={() => onTabChange(tab.id)}
+              data-cursor-target={`tab-${tab.id}`}
+              className={cn(
+                "relative inline-flex items-center gap-1.5 px-3 py-2 text-xs font-medium transition-colors",
+                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
+                isActive
+                  ? "text-foreground"
+                  : "text-muted-foreground hover:text-foreground",
+              )}
+            >
+              {tab.icon}
+              {tab.label}
+              {tab.badge != null && tab.badge > 0 && (
+                <span
+                  className={cn(
+                    "inline-flex min-w-[1.25rem] items-center justify-center rounded-full px-1 py-px text-[10px] font-medium leading-none",
+                    isActive
+                      ? "bg-primary-subtle text-primary"
+                      : "bg-muted text-muted-foreground",
+                  )}
+                >
+                  {tab.badge}
+                </span>
+              )}
+              {isActive && (
+                <span
+                  className="absolute inset-x-0 -bottom-px h-0.5 bg-primary"
+                  aria-hidden="true"
+                />
+              )}
+            </button>
+          );
+        })}
+      </div>
+
+      <div
+        id={panelId(activeTab)}
+        role="tabpanel"
+        aria-labelledby={tabId(activeTab)}
+        tabIndex={0}
+        className="pt-4 focus-visible:outline-none"
+      >
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/tabs/index.ts

@@ -0,0 +1,2 @@
+export { Tabs } from "./Tabs";
+export type { TabsProps, TabItem } from "./Tabs";

package/src/version-history/DiffFileList.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { FileDiffEntry } from "./types";
+
+/** Props for {@link DiffFileList}. */
+export interface DiffFileListProps {
+  /** Changed files to display. */
+  readonly files: readonly FileDiffEntry[];
+  /** Currently selected file path. */
+  readonly selectedPath: string | null;
+  /** Called when a file is clicked. */
+  readonly onSelect: (path: string) => void;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * File list with change-type indicators for a multi-file diff.
+ *
+ * Each file shows its path, change type badge (M/A/D), and a compact
+ * `+N -N` additions/deletions count. Files are keyboard-navigable.
+ *
+ * Zero Console dependencies — safe for platform builder embedding.
+ */
+export function DiffFileList({
+  files,
+  selectedPath,
+  onSelect,
+  className,
+}: DiffFileListProps) {
+  if (files.length === 0) return null;
+
+  return (
+    <nav
+      aria-label="Changed files"
+      className={cn("flex flex-col overflow-auto", className)}
+    >
+      {files.map((file) => (
+        <button
+          key={file.path}
+          type="button"
+          onClick={() => onSelect(file.path)}
+          aria-current={file.path === selectedPath ? "true" : undefined}
+          className={cn(
+            "flex items-center gap-2 px-3 py-1.5 text-left text-xs transition-colors",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+            file.path === selectedPath
+              ? "bg-accent-hover text-foreground"
+              : "text-muted-foreground hover:bg-accent-hover hover:text-foreground",
+          )}
+        >
+          <ChangeTypeBadge changeType={file.changeType} />
+          <span className="min-w-0 flex-1 truncate font-mono">{file.path}</span>
+          <DeltaCount additions={file.additions} deletions={file.deletions} />
+        </button>
+      ))}
+    </nav>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Change type badge (M / A / D)
+// ---------------------------------------------------------------------------
+
+function ChangeTypeBadge({
+  changeType,
+}: {
+  readonly changeType: FileDiffEntry["changeType"];
+}) {
+  const letter = changeType === "modified" ? "M" : changeType === "added" ? "A" : "D";
+  const color =
+    changeType === "modified"
+      ? "text-diff-hunk-header-fg"
+      : changeType === "added"
+        ? "text-diff-added-fg"
+        : "text-diff-removed-fg";
+
+  return (
+    <span
+      className={cn("shrink-0 font-mono text-[10px] font-bold", color)}
+      aria-label={changeType}
+    >
+      {letter}
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// +N -N delta count
+// ---------------------------------------------------------------------------
+
+function DeltaCount({
+  additions,
+  deletions,
+}: {
+  readonly additions: number;
+  readonly deletions: number;
+}) {
+  return (
+    <span className="shrink-0 font-mono text-[10px]">
+      {additions > 0 && (
+        <span className="text-diff-added-fg">+{additions}</span>
+      )}
+      {additions > 0 && deletions > 0 && " "}
+      {deletions > 0 && (
+        <span className="text-diff-removed-fg">-{deletions}</span>
+      )}
+    </span>
+  );
+}

package/src/version-history/DiffSummary.tsx

@@ -0,0 +1,61 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link DiffSummary}. */
+export interface DiffSummaryProps {
+  /** Number of files with changes. */
+  readonly fileCount: number;
+  /** Total added lines across all files. */
+  readonly additions: number;
+  /** Total removed lines across all files. */
+  readonly deletions: number;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Summary bar showing aggregate diff statistics.
+ *
+ * Renders "N files changed, +X additions, -Y deletions" in a compact
+ * single-line format. Uses diff-specific design tokens for coloring.
+ *
+ * Zero Console dependencies — safe for platform builder embedding.
+ */
+export function DiffSummary({
+  fileCount,
+  additions,
+  deletions,
+  className,
+}: DiffSummaryProps) {
+  const fileLabel = fileCount === 1 ? "1 file changed" : `${fileCount} files changed`;
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className={cn(
+        "flex items-center gap-2 text-xs text-muted-foreground",
+        className,
+      )}
+    >
+      <span>{fileLabel}</span>
+      {additions > 0 && (
+        <>
+          <span aria-hidden="true">&middot;</span>
+          <span className="font-mono text-diff-added-fg">
+            +{additions} {additions === 1 ? "addition" : "additions"}
+          </span>
+        </>
+      )}
+      {deletions > 0 && (
+        <>
+          <span aria-hidden="true">&middot;</span>
+          <span className="font-mono text-diff-removed-fg">
+            -{deletions} {deletions === 1 ? "deletion" : "deletions"}
+          </span>
+        </>
+      )}
+    </div>
+  );
+}