@stigmer/react 0.0.36

package/src/catalog/components/ResourceSearchCard.tsx

@@ -0,0 +1,137 @@
+import type { ReactNode } from "react";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { Bot, FileCode2, Server, Globe, Box } from "lucide-react";
+
+import { cn } from "@stigmer/theme";
+
+import { Badge } from "../../internal/badge";
+import { formatRelativeTime, toDate } from "../internal/time";
+
+const KIND_ICON: Record<number, ReactNode> = {
+  [ApiResourceKind.agent]: <Bot className="text-muted-foreground size-4" />,
+  [ApiResourceKind.skill]: <FileCode2 className="text-muted-foreground size-4" />,
+  [ApiResourceKind.mcp_server]: <Server className="text-muted-foreground size-4" />,
+};
+
+const FALLBACK_ICON = <Box className="text-muted-foreground size-4" />;
+
+export interface ResourceSearchCardProps {
+  /** The search result to display. */
+  result: SearchResult;
+  /** When provided, the card renders as an `<a>` element with this URL. */
+  href?: string;
+  /** Click handler for SPA navigation or custom actions. */
+  onClick?: () => void;
+  /** Override the auto-detected icon derived from `result.kind`. */
+  icon?: ReactNode;
+  /** Additional CSS class names on the root element. */
+  className?: string;
+}
+
+/**
+ * A card component for displaying any Stigmer resource search result
+ * (agent, skill, MCP server) in a grid catalog layout.
+ *
+ * Auto-selects the icon based on `result.kind`. Renders as an `<a>` tag
+ * when `href` is provided, otherwise as a `<div>`.
+ */
+export function ResourceSearchCard({
+  result,
+  href,
+  onClick,
+  icon,
+  className,
+}: ResourceSearchCardProps) {
+  const isPublic =
+    result.visibility === ApiResourceVisibility.visibility_public;
+
+  const resolvedIcon = icon ?? KIND_ICON[result.kind] ?? FALLBACK_ICON;
+
+  const Tag = href ? "a" : "div";
+  const interactive = !!(onClick || href);
+
+  return (
+    <Tag
+      href={href}
+      onClick={onClick}
+      role={interactive ? "button" : undefined}
+      tabIndex={interactive ? 0 : undefined}
+      onKeyDown={
+        interactive
+          ? (e: React.KeyboardEvent) => {
+              if (onClick && (e.key === "Enter" || e.key === " ")) {
+                e.preventDefault();
+                onClick();
+              }
+            }
+          : undefined
+      }
+      className={cn(
+        "bg-card text-card-foreground flex flex-col rounded-xl border p-4",
+        interactive &&
+          "hover:bg-accent/50 focus-visible:ring-ring cursor-pointer transition-colors focus-visible:ring-2 focus-visible:outline-none",
+        className,
+      )}
+    >
+      {/* Header: icon + name + visibility */}
+      <div className="flex items-start gap-3">
+        <div className="bg-muted flex size-9 shrink-0 items-center justify-center rounded-lg">
+          {resolvedIcon}
+        </div>
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-2">
+            <span className="truncate text-sm font-semibold">
+              {result.name}
+            </span>
+            {isPublic && (
+              <Badge variant="outline" className="shrink-0 text-[10px]">
+                <Globe className="size-2.5" />
+                Public
+              </Badge>
+            )}
+          </div>
+          <p className="text-muted-foreground truncate font-mono text-[11px]">
+            {result.qualifiedSlug}
+          </p>
+        </div>
+      </div>
+
+      {/* Description */}
+      {result.description && (
+        <p className="text-muted-foreground mt-2 line-clamp-2 text-xs leading-relaxed">
+          {result.description}
+        </p>
+      )}
+
+      {/* Footer: tags + timestamp */}
+      <div className="mt-3 flex items-end justify-between gap-2">
+        {result.tags.length > 0 ? (
+          <div className="flex min-w-0 flex-wrap gap-1">
+            {result.tags.slice(0, 3).map((tag) => (
+              <Badge key={tag} variant="secondary" className="text-[10px]">
+                {tag}
+              </Badge>
+            ))}
+            {result.tags.length > 3 && (
+              <span className="text-muted-foreground self-center text-[10px]">
+                +{result.tags.length - 3}
+              </span>
+            )}
+          </div>
+        ) : (
+          <div />
+        )}
+        {result.createdAt && (
+          <time
+            dateTime={toDate(result.createdAt)?.toISOString() ?? ""}
+            className="text-muted-foreground shrink-0 text-[10px]"
+          >
+            {formatRelativeTime(result.createdAt)}
+          </time>
+        )}
+      </div>
+    </Tag>
+  );
+}

package/src/catalog/index.ts

@@ -0,0 +1,6 @@
+// Components
+export { ResourceSearchCard } from "./components/ResourceSearchCard";
+export type { ResourceSearchCardProps } from "./components/ResourceSearchCard";
+
+// Utilities
+export { formatRelativeTime, toDate } from "./internal/time";

package/src/catalog/internal/time.ts

@@ -0,0 +1,40 @@
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+
+/**
+ * Convert a protobuf Timestamp to a JS Date.
+ * Returns null if the timestamp is undefined or has no seconds.
+ */
+export function toDate(ts: Timestamp | undefined): Date | null {
+  if (!ts) return null;
+  const seconds = Number(ts.seconds);
+  if (!seconds && seconds !== 0) return null;
+  return new Date(seconds * 1000 + Math.floor(ts.nanos / 1_000_000));
+}
+
+/**
+ * Format a protobuf Timestamp as a human-readable relative time string.
+ *
+ * Examples: "just now", "2m ago", "3h ago", "yesterday", "Mar 12"
+ */
+export function formatRelativeTime(ts: Timestamp | undefined): string {
+  const date = toDate(ts);
+  if (!date) return "";
+
+  const now = Date.now();
+  const diffMs = now - date.getTime();
+
+  if (diffMs < 0) return "just now";
+  if (diffMs < 60_000) return "just now";
+
+  const minutes = Math.floor(diffMs / 60_000);
+  if (minutes < 60) return `${minutes}m ago`;
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+
+  const days = Math.floor(hours / 24);
+  if (days === 1) return "yesterday";
+  if (days < 7) return `${days}d ago`;
+
+  return date.toLocaleDateString(undefined, { month: "short", day: "numeric" });
+}

package/src/context.ts

@@ -0,0 +1,15 @@
+"use client";
+
+import { createContext } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+
+/**
+ * React context for the Stigmer SDK client instance.
+ *
+ * Separated from the provider component to prevent circular imports:
+ * both the provider and consumer hooks import from this file.
+ *
+ * The context value is `null` when no provider is mounted. Consumer hooks
+ * throw in this case to surface wiring mistakes during development.
+ */
+export const StigmerContext = createContext<Stigmer | null>(null);

package/src/hooks.ts

@@ -0,0 +1,32 @@
+"use client";
+
+import { useContext } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "./context";
+
+/**
+ * Access the {@link Stigmer} SDK client from the nearest
+ * {@link StigmerProvider}.
+ *
+ * Throws if called outside a provider — this surfaces wiring mistakes
+ * immediately during development rather than producing silent `null`
+ * failures at runtime.
+ *
+ * @example
+ * ```tsx
+ * function AgentDetail({ id }: { id: string }) {
+ *   const stigmer = useStigmer();
+ *   const agent = await stigmer.agent.get(id);
+ * }
+ * ```
+ */
+export function useStigmer(): Stigmer {
+  const client = useContext(StigmerContext);
+  if (!client) {
+    throw new Error(
+      "useStigmer must be used within <StigmerProvider>. " +
+        "Wrap your component tree with <StigmerProvider client={stigmerClient}>.",
+    );
+  }
+  return client;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// Provider and context
+export { StigmerProvider, type StigmerProviderProps } from "./provider";
+export { StigmerContext } from "./context";
+
+// Hooks
+export { useStigmer } from "./hooks";

package/src/internal/badge.tsx

@@ -0,0 +1,52 @@
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@stigmer/theme";
+
+const badgeVariants = cva(
+  "group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-4xl border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-all focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3!",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground [a]:hover:bg-primary/80",
+        secondary:
+          "bg-secondary text-secondary-foreground [a]:hover:bg-secondary/80",
+        destructive:
+          "bg-destructive/10 text-destructive focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:focus-visible:ring-destructive/40 [a]:hover:bg-destructive/20",
+        outline:
+          "border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground",
+        ghost:
+          "hover:bg-muted hover:text-muted-foreground dark:hover:bg-muted/50",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+function Badge({
+  className,
+  variant = "default",
+  render,
+  ...props
+}: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>) {
+  return useRender({
+    defaultTagName: "span",
+    props: mergeProps<"span">(
+      {
+        className: cn(badgeVariants({ variant }), className),
+      },
+      props,
+    ),
+    render,
+    state: {
+      slot: "badge",
+      variant,
+    },
+  });
+}
+
+export { Badge, badgeVariants };

package/src/internal/button.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { Button as ButtonPrimitive } from "@base-ui/react/button";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@stigmer/theme";
+
+const buttonVariants = cva(
+  "group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground [a]:hover:bg-primary/80",
+        outline:
+          "border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80 aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
+        ghost:
+          "hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
+        destructive:
+          "bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default:
+          "h-8 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
+        sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+        lg: "h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3",
+        icon: "size-8",
+        "icon-xs":
+          "size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+        "icon-sm":
+          "size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg",
+        "icon-lg": "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+function Button({
+  className,
+  variant = "default",
+  size = "default",
+  ...props
+}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>) {
+  return (
+    <ButtonPrimitive
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+}
+
+export { Button, buttonVariants };

package/src/internal/collapsible.tsx

@@ -0,0 +1,21 @@
+"use client";
+
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+
+function Collapsible({ ...props }: CollapsiblePrimitive.Root.Props) {
+  return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />;
+}
+
+function CollapsibleTrigger({ ...props }: CollapsiblePrimitive.Trigger.Props) {
+  return (
+    <CollapsiblePrimitive.Trigger data-slot="collapsible-trigger" {...props} />
+  );
+}
+
+function CollapsibleContent({ ...props }: CollapsiblePrimitive.Panel.Props) {
+  return (
+    <CollapsiblePrimitive.Panel data-slot="collapsible-content" {...props} />
+  );
+}
+
+export { Collapsible, CollapsibleTrigger, CollapsibleContent };

package/src/internal/section.tsx

@@ -0,0 +1,18 @@
+interface SectionProps {
+  title: string;
+  children: React.ReactNode;
+}
+
+function Section({ title, children }: SectionProps) {
+  return (
+    <section>
+      <h3 className="text-muted-foreground mb-3 text-sm font-semibold tracking-wider uppercase">
+        {title}
+      </h3>
+      {children}
+    </section>
+  );
+}
+
+export { Section };
+export type { SectionProps };

package/src/internal/textarea.tsx

@@ -0,0 +1,23 @@
+import * as React from "react";
+
+import { cn } from "@stigmer/theme";
+
+const Textarea = React.forwardRef<
+  HTMLTextAreaElement,
+  React.ComponentProps<"textarea">
+>(({ className, ...props }, ref) => {
+  return (
+    <textarea
+      ref={ref}
+      data-slot="textarea"
+      className={cn(
+        "border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 disabled:bg-input/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 flex field-sizing-content min-h-16 w-full rounded-lg border bg-transparent px-2.5 py-2 text-base transition-colors outline-none focus-visible:ring-3 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:ring-3 md:text-sm",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+Textarea.displayName = "Textarea";
+
+export { Textarea };

package/src/mcp-server/hooks/useMcpServerSearch.ts

@@ -0,0 +1,79 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { useStigmer } from "../../hooks";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+
+const DEBOUNCE_MS = 300;
+const DEFAULT_PAGE_SIZE = 20;
+
+export interface UseMcpServerSearchOptions {
+  org: string;
+  debounceMs?: number;
+  pageSize?: number;
+}
+
+export interface UseMcpServerSearchReturn {
+  query: string;
+  setQuery: (query: string) => void;
+  results: SearchResult[];
+  isLoading: boolean;
+  error: string | null;
+}
+
+/**
+ * Debounced MCP server search scoped to a specific organization.
+ *
+ * On mount fetches all accessible MCP servers (empty query). Typing fires at
+ * most one request per debounce interval. Stale responses from out-of-order
+ * requests are discarded.
+ *
+ * Returns full {@link SearchResult} objects suitable for use with
+ * `ResourceSearchCard`.
+ */
+export function useMcpServerSearch(options: UseMcpServerSearchOptions): UseMcpServerSearchReturn {
+  const { org, debounceMs = DEBOUNCE_MS, pageSize = DEFAULT_PAGE_SIZE } = options;
+  const stigmer = useStigmer();
+
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState<SearchResult[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const latestRequestId = useRef(0);
+  const debouncedQuery = useDebouncedValue(query, debounceMs);
+
+  useEffect(() => {
+    const requestId = ++latestRequestId.current;
+    setIsLoading(true);
+    setError(null);
+
+    stigmer.mcpServer
+      .list({ query: debouncedQuery, org, page: { num: 1, size: pageSize } })
+      .then((response) => {
+        if (requestId !== latestRequestId.current) return;
+        setResults(response.entries);
+      })
+      .catch((err: unknown) => {
+        if (requestId !== latestRequestId.current) return;
+        setError(err instanceof Error ? err.message : "Search failed");
+      })
+      .finally(() => {
+        if (requestId !== latestRequestId.current) return;
+        setIsLoading(false);
+      });
+  }, [debouncedQuery, org, pageSize, stigmer]);
+
+  return { query, setQuery, results, isLoading, error };
+}
+
+function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+
+  return debounced;
+}

package/src/mcp-server/index.ts

@@ -0,0 +1,6 @@
+// Hooks
+export { useMcpServerSearch } from "./hooks/useMcpServerSearch";
+export type {
+  UseMcpServerSearchOptions,
+  UseMcpServerSearchReturn,
+} from "./hooks/useMcpServerSearch";

package/src/provider.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { cn, resolvePresetClass } from "@stigmer/theme";
+import type { ThemePresetId } from "@stigmer/theme";
+import { StigmerContext } from "./context";
+
+export interface StigmerProviderProps {
+  /** A configured {@link Stigmer} client instance. */
+  readonly client: Stigmer;
+  readonly children: ReactNode;
+  /**
+   * Built-in theme preset to apply.
+   *
+   * Maps to a CSS class on the scoping container so the preset's
+   * design tokens take effect for all descendant Stigmer components.
+   * Omit (or pass `"default"`) to use the base Stigmer palette.
+   *
+   * @example
+   * ```tsx
+   * <StigmerProvider client={client} preset="corporate">
+   *   <ChatWidget />
+   * </StigmerProvider>
+   * ```
+   */
+  readonly preset?: ThemePresetId;
+  /**
+   * Additional CSS class names applied to the scoping container element.
+   * The container always includes the `stgm` class for style isolation.
+   */
+  readonly className?: string;
+}
+
+/**
+ * React provider that distributes a {@link Stigmer} SDK client to
+ * descendant components via {@link StigmerContext}.
+ *
+ * Renders a `<div class="stgm">` container that scopes Stigmer's
+ * CSS reset and design tokens. External consumers importing
+ * `@stigmer/react/styles.css` get isolated styles that do not
+ * leak into the host application.
+ *
+ * Pass {@link StigmerProviderProps.preset | preset} to apply a
+ * built-in theme, or use {@link StigmerProviderProps.className | className}
+ * for custom styling.
+ *
+ * @example
+ * ```tsx
+ * const client = useMemo(
+ *   () => new Stigmer({ baseUrl, getAccessToken }),
+ *   [getAccessToken],
+ * );
+ *
+ * <StigmerProvider client={client} preset="fintech">
+ *   <App />
+ * </StigmerProvider>
+ * ```
+ */
+export function StigmerProvider({
+  client,
+  children,
+  preset,
+  className,
+}: StigmerProviderProps) {
+  const presetClass = preset ? resolvePresetClass(preset) : "";
+
+  return (
+    <StigmerContext.Provider value={client}>
+      <div className={cn("stgm", presetClass, className)}>{children}</div>
+    </StigmerContext.Provider>
+  );
+}