@stigmer/react 0.4.8 → 0.5.1

package/src/resource-creation/TemplateCard.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import { useCallback } from "react";
+import { cn } from "@stigmer/theme";
+import type { ResourceTemplate, TemplateCategory } from "./templates/types";
+import { TEMPLATE_CATEGORY_LABELS } from "./templates/types";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Props for {@link TemplateCard}. */
+export interface TemplateCardProps<TData> {
+  /** The template to display. */
+  readonly template: ResourceTemplate<TData>;
+  /** Called when the card is selected (click or Enter). */
+  readonly onSelect: (template: ResourceTemplate<TData>) => void;
+  /** Additional CSS classes for the card container. */
+  readonly className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Category badge colors
+// ---------------------------------------------------------------------------
+
+const CATEGORY_COLORS: Record<TemplateCategory, string> = {
+  "customer-support": "bg-blue-500/10 text-blue-700 dark:text-blue-400",
+  "code-review": "bg-violet-500/10 text-violet-700 dark:text-violet-400",
+  "data-analysis": "bg-amber-500/10 text-amber-700 dark:text-amber-400",
+  devops: "bg-emerald-500/10 text-emerald-700 dark:text-emerald-400",
+  content: "bg-pink-500/10 text-pink-700 dark:text-pink-400",
+  integration: "bg-cyan-500/10 text-cyan-700 dark:text-cyan-400",
+  general: "bg-muted text-muted-foreground",
+};
+
+// ---------------------------------------------------------------------------
+// Initial avatar colors (deterministic from template id)
+// ---------------------------------------------------------------------------
+
+const AVATAR_COLORS = [
+  "bg-blue-500/15 text-blue-700 dark:text-blue-400",
+  "bg-violet-500/15 text-violet-700 dark:text-violet-400",
+  "bg-emerald-500/15 text-emerald-700 dark:text-emerald-400",
+  "bg-amber-500/15 text-amber-700 dark:text-amber-400",
+  "bg-pink-500/15 text-pink-700 dark:text-pink-400",
+  "bg-cyan-500/15 text-cyan-700 dark:text-cyan-400",
+  "bg-rose-500/15 text-rose-700 dark:text-rose-400",
+] as const;
+
+function hashCode(str: string): number {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) - hash + str.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash);
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+/**
+ * A clickable card that displays a resource template's metadata.
+ *
+ * Renders the template's name, description, and category badge.
+ * Displays a colored initial avatar derived from the template name.
+ *
+ * Fully keyboard-accessible: focusable, activates on Enter/Space.
+ * Uses `--stgm-*` tokens for all structural styling; category badge
+ * colors use Tailwind's semantic palette with opacity for dark mode.
+ *
+ * @typeParam TData - The wizard data shape this template targets.
+ */
+export function TemplateCard<TData>({
+  template,
+  onSelect,
+  className,
+}: TemplateCardProps<TData>) {
+  const handleClick = useCallback(() => {
+    onSelect(template);
+  }, [onSelect, template]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        onSelect(template);
+      }
+    },
+    [onSelect, template],
+  );
+
+  const colorIndex = hashCode(template.id) % AVATAR_COLORS.length;
+  const avatarColor = AVATAR_COLORS[colorIndex]!;
+  const initial = template.name.charAt(0).toUpperCase();
+  const categoryLabel =
+    TEMPLATE_CATEGORY_LABELS[template.category] ?? template.category;
+
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      aria-label={`Use ${template.name} template`}
+      className={cn(
+        "group flex cursor-pointer flex-col gap-3 rounded-lg border border-border bg-card p-4",
+        "transition-colors hover:border-primary hover:bg-accent",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        className,
+      )}
+    >
+      <div className="flex items-start gap-3">
+        {/* Initial avatar */}
+        <span
+          className={cn(
+            "inline-flex size-9 shrink-0 items-center justify-center rounded-md text-sm font-semibold",
+            avatarColor,
+          )}
+          aria-hidden="true"
+        >
+          {initial}
+        </span>
+
+        <div className="min-w-0 flex-1">
+          <p className="text-sm font-medium text-foreground">{template.name}</p>
+          <span
+            className={cn(
+              "mt-1 inline-block rounded-full px-2 py-0.5 text-[10px] font-medium",
+              CATEGORY_COLORS[template.category] ?? CATEGORY_COLORS.general,
+            )}
+          >
+            {categoryLabel}
+          </span>
+        </div>
+      </div>
+
+      <p className="line-clamp-2 text-xs leading-relaxed text-muted-foreground">
+        {template.description}
+      </p>
+    </div>
+  );
+}

package/src/resource-creation/TemplateGallery.tsx

@@ -0,0 +1,222 @@
+"use client";
+
+import { useCallback, useRef, type ReactNode } from "react";
+import { cn } from "@stigmer/theme";
+import type { ResourceTemplate, TemplateCategory } from "./templates/types";
+import { TEMPLATE_CATEGORY_LABELS } from "./templates/types";
+import { useTemplateFilter } from "./useTemplateFilter";
+import { TemplateCard } from "./TemplateCard";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Props for {@link TemplateGallery}. */
+export interface TemplateGalleryProps<TData> {
+  /** Templates to display in the gallery. */
+  readonly templates: readonly ResourceTemplate<TData>[];
+  /** Called when the user selects a template. */
+  readonly onSelect: (template: ResourceTemplate<TData>) => void;
+  /**
+   * Content to render when no templates match the search/filter.
+   * Falls back to a built-in empty message if not provided.
+   */
+  readonly emptyContent?: ReactNode;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+/**
+ * A searchable, filterable gallery of resource templates.
+ *
+ * Renders category tabs, a search input, and a responsive card grid.
+ * Uses the headless `useTemplateFilter` hook for state — platform
+ * builders who want custom rendering can use the hook directly.
+ *
+ * Keyboard navigation:
+ * - Tab moves focus between the search input, category tabs, and cards
+ * - Arrow keys (Left/Right) navigate between category tabs
+ * - Enter/Space activates the focused tab or card
+ *
+ * All structural styling via `--stgm-*` tokens. Zero Console or
+ * framework dependencies.
+ *
+ * @typeParam TData - The wizard data shape (e.g. `AgentWizardData`).
+ *
+ * @example
+ * ```tsx
+ * <TemplateGallery
+ *   templates={AGENT_TEMPLATES}
+ *   onSelect={(template) => startWizardWithTemplate(template)}
+ * />
+ * ```
+ */
+export function TemplateGallery<TData>({
+  templates,
+  onSelect,
+  emptyContent,
+  className,
+}: TemplateGalleryProps<TData>) {
+  const {
+    filtered,
+    query,
+    setQuery,
+    activeCategory,
+    setActiveCategory,
+    availableCategories,
+  } = useTemplateFilter({ templates });
+
+  const tabListRef = useRef<HTMLDivElement>(null);
+
+  const handleTabKeyDown = useCallback((e: React.KeyboardEvent) => {
+    const tabs =
+      tabListRef.current?.querySelectorAll<HTMLButtonElement>('[role="tab"]');
+    if (!tabs?.length) return;
+
+    const currentIndex = Array.from(tabs).findIndex(
+      (t) => t === document.activeElement,
+    );
+    if (currentIndex === -1) return;
+
+    let nextIndex: number | null = null;
+
+    if (e.key === "ArrowRight") {
+      nextIndex = (currentIndex + 1) % tabs.length;
+    } else if (e.key === "ArrowLeft") {
+      nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
+    } else if (e.key === "Home") {
+      nextIndex = 0;
+    } else if (e.key === "End") {
+      nextIndex = tabs.length - 1;
+    }
+
+    if (nextIndex !== null) {
+      e.preventDefault();
+      tabs[nextIndex]!.focus();
+      tabs[nextIndex]!.click();
+    }
+  }, []);
+
+  return (
+    <div className={cn("flex flex-col gap-4", className)}>
+      {/* Search input */}
+      <div className="relative">
+        <SearchIcon />
+        <input
+          type="search"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          placeholder="Search templates…"
+          aria-label="Search templates"
+          className={cn(
+            "w-full rounded-md border border-input bg-input-bg py-2 pl-9 pr-3 text-sm text-foreground",
+            "placeholder:text-muted-foreground",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          )}
+        />
+      </div>
+
+      {/* Category tabs */}
+      {availableCategories.length > 1 && (
+        <div
+          ref={tabListRef}
+          role="tablist"
+          aria-label="Template categories"
+          onKeyDown={handleTabKeyDown}
+          className="flex flex-wrap gap-1"
+        >
+          <CategoryTab
+            label="All"
+            isActive={activeCategory === null}
+            onClick={() => setActiveCategory(null)}
+          />
+          {availableCategories.map((cat) => (
+            <CategoryTab
+              key={cat}
+              label={TEMPLATE_CATEGORY_LABELS[cat] ?? cat}
+              isActive={activeCategory === cat}
+              onClick={() => setActiveCategory(cat)}
+            />
+          ))}
+        </div>
+      )}
+
+      {/* Card grid or empty state */}
+      {filtered.length > 0 ? (
+        <div
+          role="list"
+          aria-label="Templates"
+          className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3"
+        >
+          {filtered.map((template) => (
+            <div key={template.id} role="listitem">
+              <TemplateCard template={template} onSelect={onSelect} />
+            </div>
+          ))}
+        </div>
+      ) : (
+        (emptyContent ?? (
+          <div className="py-8 text-center text-sm text-muted-foreground">
+            No templates match your search.
+          </div>
+        ))
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Internal components
+// ---------------------------------------------------------------------------
+
+function CategoryTab({
+  label,
+  isActive,
+  onClick,
+}: {
+  readonly label: string;
+  readonly isActive: boolean;
+  readonly onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      role="tab"
+      aria-selected={isActive}
+      tabIndex={isActive ? 0 : -1}
+      onClick={onClick}
+      className={cn(
+        "rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        isActive
+          ? "bg-primary text-primary-foreground"
+          : "bg-muted text-muted-foreground hover:bg-accent hover:text-accent-foreground",
+      )}
+    >
+      {label}
+    </button>
+  );
+}
+
+function SearchIcon() {
+  return (
+    <svg
+      className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground"
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx={11} cy={11} r={8} />
+      <path d="m21 21-4.3-4.3" />
+    </svg>
+  );
+}

package/src/resource-creation/WizardNav.tsx

@@ -0,0 +1,163 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link WizardNav}. */
+export interface WizardNavProps {
+  /** Whether the Back button should be displayed. */
+  readonly showBack: boolean;
+  /** Label for the primary action button. */
+  readonly nextLabel: string;
+  /** Whether the primary action is disabled. */
+  readonly nextDisabled?: boolean;
+  /** Whether the primary action is in a loading state. */
+  readonly isSubmitting?: boolean;
+  /** Called when Back is clicked. */
+  readonly onBack: () => void;
+  /** Called when Next/Submit is clicked. */
+  readonly onNext: () => void;
+  /** Called when Cancel is clicked. */
+  readonly onCancel?: () => void;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Navigation footer for the wizard shell.
+ *
+ * Renders Back / Next|Submit buttons in a standardized layout.
+ * The primary (right-side) button adapts its label and loading
+ * state based on whether it's the final step.
+ *
+ * Keyboard: Enter triggers the primary action when focused within
+ * the wizard content (not within text areas or other multi-line inputs).
+ */
+export function WizardNav({
+  showBack,
+  nextLabel,
+  nextDisabled,
+  isSubmitting,
+  onBack,
+  onNext,
+  onCancel,
+  className,
+}: WizardNavProps) {
+  return (
+    <div
+      className={cn(
+        "flex items-center justify-between border-t border-border px-6 py-4",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-2">
+        {onCancel && (
+          <button
+            type="button"
+            onClick={onCancel}
+            disabled={isSubmitting}
+            className={cn(
+              "rounded-md px-3 py-1.5 text-sm",
+              "text-muted-foreground transition-colors",
+              "hover:text-foreground hover:bg-accent-hover",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+              "disabled:pointer-events-none disabled:opacity-50",
+            )}
+          >
+            Cancel
+          </button>
+        )}
+      </div>
+
+      <div className="flex items-center gap-2">
+        {showBack && (
+          <button
+            type="button"
+            onClick={onBack}
+            disabled={isSubmitting}
+            className={cn(
+              "inline-flex items-center gap-1.5 rounded-md border border-input bg-background px-3 py-1.5 text-sm font-medium text-foreground transition-colors",
+              "hover:bg-accent-hover",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+              "disabled:pointer-events-none disabled:opacity-50",
+            )}
+          >
+            <ArrowLeftIcon className="size-3.5" />
+            Back
+          </button>
+        )}
+
+        <button
+          type="button"
+          onClick={onNext}
+          disabled={nextDisabled || isSubmitting}
+          className={cn(
+            "inline-flex items-center gap-1.5 rounded-md bg-primary px-4 py-1.5 text-sm font-medium text-primary-foreground transition-colors",
+            "hover:bg-primary-hover",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            "disabled:pointer-events-none disabled:opacity-40",
+          )}
+        >
+          {isSubmitting && <SpinnerIcon />}
+          {nextLabel}
+          {!isSubmitting && <ArrowRightIcon className="size-3.5" />}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+
+function ArrowLeftIcon({ 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="M10 3 5 8l5 5" />
+    </svg>
+  );
+}
+
+function ArrowRightIcon({ 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="m6 3 5 5-5 5" />
+    </svg>
+  );
+}
+
+function SpinnerIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      className="animate-spin"
+      aria-hidden="true"
+    >
+      <path d="M8 2a6 6 0 1 0 6 6" />
+    </svg>
+  );
+}

package/src/resource-creation/WizardShell.tsx

@@ -0,0 +1,124 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { WizardShellProps } from "./types";
+import { StepIndicator } from "./StepIndicator";
+import { WizardNav } from "./WizardNav";
+
+/**
+ * Reusable multi-step wizard layout for resource creation flows.
+ *
+ * Renders three zones:
+ * 1. **Step indicator sidebar** — vertical progress showing all steps
+ * 2. **Content area** — the active step's form content (via `children`)
+ * 3. **Navigation footer** — Back / Next / Create buttons
+ *
+ * This component is resource-agnostic. It accepts step definitions for
+ * the indicator, delegates content rendering to the consumer, and
+ * emits navigation events. The consumer (e.g., `AgentCreationWizard`)
+ * manages form state via `useWizardState` and renders the appropriate
+ * step component as `children`.
+ *
+ * Layout:
+ * - **Desktop** (>= 640px): Sidebar (200px) + content (flex-1) side by side
+ * - **Mobile** (< 640px): Step indicator as compact top bar, content below
+ *
+ * All visual properties via `--stgm-*` tokens. Zero Console or
+ * framework dependencies — works in any React host.
+ *
+ * @example
+ * ```tsx
+ * <WizardShell
+ *   steps={steps}
+ *   currentStepIndex={wizard.currentStepIndex}
+ *   submitLabel="Create agent"
+ *   isSubmitting={isCreating}
+ *   canGoNext={wizard.canGoNext}
+ *   canGoBack={wizard.canGoBack}
+ *   onNext={wizard.goNext}
+ *   onBack={wizard.goBack}
+ *   onCancel={handleCancel}
+ * >
+ *   {renderCurrentStep()}
+ * </WizardShell>
+ * ```
+ */
+export function WizardShell({
+  steps,
+  currentStepIndex,
+  children,
+  submitLabel,
+  isSubmitting,
+  canGoNext = true,
+  canGoBack = false,
+  onNext,
+  onBack,
+  onGoToStep,
+  onCancel,
+  className,
+}: WizardShellProps) {
+  const isLastStep = currentStepIndex === steps.length - 1;
+  const nextLabel = isLastStep ? submitLabel : "Next";
+
+  return (
+    <div
+      className={cn(
+        "flex min-h-0 flex-col overflow-hidden rounded-lg border border-border bg-background",
+        className,
+      )}
+    >
+      {/* Mobile step indicator (visible < sm) */}
+      <div className="flex items-center gap-2 border-b border-border px-4 py-3 sm:hidden">
+        <MobileProgress current={currentStepIndex + 1} total={steps.length} />
+        <span className="text-sm font-medium text-foreground">
+          {steps[currentStepIndex]?.label}
+        </span>
+      </div>
+
+      <div className="flex min-h-0 flex-1">
+        {/* Step indicator sidebar (visible >= sm) */}
+        <aside className="hidden w-52 shrink-0 border-r border-border bg-muted-faint px-3 py-6 sm:block">
+          <StepIndicator
+            steps={steps}
+            currentStepIndex={currentStepIndex}
+            onStepClick={onGoToStep}
+          />
+        </aside>
+
+        {/* Content area */}
+        <main className="flex-1 overflow-y-auto px-6 py-6 sm:px-8">
+          {children}
+        </main>
+      </div>
+
+      {/* Navigation footer */}
+      <WizardNav
+        showBack={canGoBack}
+        nextLabel={nextLabel}
+        nextDisabled={!canGoNext}
+        isSubmitting={isSubmitting}
+        onBack={onBack}
+        onNext={onNext}
+        onCancel={onCancel}
+      />
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Mobile progress (compact step display)
+// ---------------------------------------------------------------------------
+
+function MobileProgress({
+  current,
+  total,
+}: {
+  readonly current: number;
+  readonly total: number;
+}) {
+  return (
+    <span className="inline-flex items-center justify-center rounded-full bg-primary px-2 py-0.5 text-[10px] font-semibold text-primary-foreground">
+      {current}/{total}
+    </span>
+  );
+}

package/src/resource-creation/index.ts

@@ -0,0 +1,45 @@
+// Types
+export type {
+  EnvVarEntry,
+  KeyValueEntry,
+  WizardStepDef,
+  WizardState,
+  WizardShellProps,
+} from "./types";
+
+// Template types and data
+export type { ResourceTemplate, TemplateCategory } from "./templates/types";
+export { TEMPLATE_CATEGORY_LABELS } from "./templates/types";
+export { AGENT_TEMPLATES } from "./templates/agent-templates";
+export { MCP_SERVER_TEMPLATES } from "./templates/mcp-server-templates";
+
+// Hooks
+export { useWizardState } from "./useWizardState";
+export type {
+  UseWizardStateOptions,
+  UseWizardStateReturn,
+} from "./useWizardState";
+
+export { useTemplateFilter } from "./useTemplateFilter";
+export type {
+  UseTemplateFilterOptions,
+  UseTemplateFilterReturn,
+} from "./useTemplateFilter";
+
+// Components
+export { WizardShell } from "./WizardShell";
+
+export { WizardNav } from "./WizardNav";
+export type { WizardNavProps } from "./WizardNav";
+
+export { StepIndicator } from "./StepIndicator";
+export type { StepIndicatorProps } from "./StepIndicator";
+
+export { TemplateCard } from "./TemplateCard";
+export type { TemplateCardProps } from "./TemplateCard";
+
+export { TemplateGallery } from "./TemplateGallery";
+export type { TemplateGalleryProps } from "./TemplateGallery";
+
+export { CreationPicker } from "./CreationPicker";
+export type { CreationPickerProps, CreationPath } from "./CreationPicker";