@stigmer/react 0.4.8 → 0.5.0

package/src/resource-creation/CreationPicker.tsx

@@ -0,0 +1,292 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { cn } from "@stigmer/theme";
+import type { ResourceTemplate } from "./templates/types";
+import { TemplateGallery } from "./TemplateGallery";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * The creation path the user selected on the picker screen.
+ *
+ * - `"scratch"` — start the wizard with empty fields
+ * - `"template"` — start the wizard with template-provided data
+ * - `"import"` — open the import dialog (handled by the consumer)
+ */
+export type CreationPath =
+  | { readonly kind: "scratch" }
+  | { readonly kind: "template"; readonly data: Partial<unknown> }
+  | { readonly kind: "import" };
+
+/** Props for {@link CreationPicker}. */
+export interface CreationPickerProps<TData> {
+  /** Label for the resource type (e.g. "agent", "MCP server"). Used in headings. */
+  readonly resourceLabel: string;
+  /** Available templates for the gallery view. */
+  readonly templates: readonly ResourceTemplate<TData>[];
+  /** Called when the user selects a creation path. */
+  readonly onSelect: (path: CreationPath) => void;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+type PickerView = "options" | "gallery";
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+/**
+ * "Step 0" landing screen for resource creation flows.
+ *
+ * Presents three creation entry points as large option cards:
+ * 1. **Start from scratch** — blank wizard
+ * 2. **Browse templates** — opens the template gallery inline
+ * 3. **Import from file** — triggers the import dialog
+ *
+ * When the user clicks "Browse templates", the picker transitions
+ * to show the `TemplateGallery` inline with a back button. Selecting
+ * a template emits `onSelect({ kind: "template", data })`.
+ *
+ * This component is SDK-first with zero Console dependencies. The
+ * consumer (e.g. `AgentNewPage`) handles routing, the import dialog,
+ * and mounting the wizard.
+ *
+ * @typeParam TData - The wizard data shape (e.g. `AgentWizardData`).
+ *
+ * @example
+ * ```tsx
+ * <CreationPicker
+ *   resourceLabel="agent"
+ *   templates={AGENT_TEMPLATES}
+ *   onSelect={(path) => {
+ *     if (path.kind === "scratch") startWizard();
+ *     if (path.kind === "template") startWizard(path.data);
+ *     if (path.kind === "import") openImportDialog();
+ *   }}
+ * />
+ * ```
+ */
+export function CreationPicker<TData>({
+  resourceLabel,
+  templates,
+  onSelect,
+  className,
+}: CreationPickerProps<TData>) {
+  const [view, setView] = useState<PickerView>("options");
+
+  const handleTemplateSelect = useCallback(
+    (template: ResourceTemplate<TData>) => {
+      onSelect({ kind: "template", data: template.data });
+    },
+    [onSelect],
+  );
+
+  const handleBackToOptions = useCallback(() => {
+    setView("options");
+  }, []);
+
+  if (view === "gallery") {
+    return (
+      <div className={cn("flex flex-col gap-4", className)}>
+        <div className="flex items-center gap-2">
+          <button
+            type="button"
+            onClick={handleBackToOptions}
+            aria-label="Back to creation options"
+            className={cn(
+              "inline-flex items-center justify-center rounded-md p-1.5",
+              "text-muted-foreground transition-colors",
+              "hover:bg-accent hover:text-accent-foreground",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            )}
+          >
+            <BackArrowIcon />
+          </button>
+          <h2 className="text-base font-semibold text-foreground">
+            Choose a template
+          </h2>
+        </div>
+        <TemplateGallery
+          templates={templates}
+          onSelect={handleTemplateSelect}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("flex flex-col gap-6", className)}>
+      <div>
+        <h2 className="text-lg font-semibold text-foreground">
+          Create a new {resourceLabel}
+        </h2>
+        <p className="mt-1 text-sm text-muted-foreground">
+          Choose how you'd like to get started.
+        </p>
+      </div>
+
+      <div className="grid grid-cols-1 gap-3 sm:grid-cols-3">
+        {/* Start from scratch */}
+        <OptionCard
+          title="Start from scratch"
+          description={`Create a blank ${resourceLabel} and configure it step by step.`}
+          icon={<BlankPageIcon />}
+          onClick={() => onSelect({ kind: "scratch" })}
+        />
+
+        {/* Browse templates */}
+        {templates.length > 0 && (
+          <OptionCard
+            title="Browse templates"
+            description={`Start with a pre-built ${resourceLabel} configuration.`}
+            icon={<GridIcon />}
+            onClick={() => setView("gallery")}
+            badge={`${templates.length} available`}
+          />
+        )}
+
+        {/* Import from file */}
+        <OptionCard
+          title="Import from file"
+          description="Upload a YAML or JSON configuration file."
+          icon={<UploadIcon />}
+          onClick={() => onSelect({ kind: "import" })}
+        />
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Internal components
+// ---------------------------------------------------------------------------
+
+function OptionCard({
+  title,
+  description,
+  icon,
+  onClick,
+  badge,
+}: {
+  readonly title: string;
+  readonly description: string;
+  readonly icon: React.ReactNode;
+  readonly onClick: () => void;
+  readonly badge?: string;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={cn(
+        "group flex flex-col items-center gap-3 rounded-lg border border-border bg-card p-6 text-center",
+        "transition-colors hover:border-primary hover:bg-accent",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+      )}
+    >
+      <span className="text-muted-foreground transition-colors group-hover:text-foreground">
+        {icon}
+      </span>
+      <div className="flex flex-col gap-1">
+        <span className="text-sm font-medium text-foreground">{title}</span>
+        <span className="text-xs text-muted-foreground">{description}</span>
+      </div>
+      {badge && (
+        <span className="rounded-full bg-muted px-2 py-0.5 text-[10px] font-medium text-muted-foreground">
+          {badge}
+        </span>
+      )}
+    </button>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons (inline SVGs — no external dependency)
+// ---------------------------------------------------------------------------
+
+function BlankPageIcon() {
+  return (
+    <svg
+      className="size-8"
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M14.5 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7.5L14.5 2z" />
+      <polyline points="14 2 14 8 20 8" />
+    </svg>
+  );
+}
+
+function GridIcon() {
+  return (
+    <svg
+      className="size-8"
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect width="7" height="7" x="3" y="3" rx="1" />
+      <rect width="7" height="7" x="14" y="3" rx="1" />
+      <rect width="7" height="7" x="14" y="14" rx="1" />
+      <rect width="7" height="7" x="3" y="14" rx="1" />
+    </svg>
+  );
+}
+
+function UploadIcon() {
+  return (
+    <svg
+      className="size-8"
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+      <polyline points="17 8 12 3 7 8" />
+      <line x1="12" x2="12" y1="3" y2="15" />
+    </svg>
+  );
+}
+
+function BackArrowIcon() {
+  return (
+    <svg
+      className="size-4"
+      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"
+    >
+      <path d="m12 19-7-7 7-7" />
+      <path d="M19 12H5" />
+    </svg>
+  );
+}

package/src/resource-creation/StepIndicator.tsx

@@ -0,0 +1,156 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link StepIndicator}. */
+export interface StepIndicatorProps {
+  /** Step definitions to render (only `id` and `label` are used for rendering). */
+  readonly steps: readonly { readonly id: string; readonly label: string }[];
+  /** Zero-based index of the currently active step. */
+  readonly currentStepIndex: number;
+  /** Called when a completed step is clicked (backward navigation). */
+  readonly onStepClick?: (index: number) => void;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Vertical step progress indicator for multi-step wizards.
+ *
+ * Renders each step as a numbered circle with label. Steps are
+ * color-coded by state: completed (filled), active (ring), pending
+ * (muted). Completed steps are clickable for backward navigation.
+ *
+ * Responsive: collapses to a compact horizontal layout on narrow
+ * viewports via CSS container queries.
+ *
+ * Uses `--stgm-*` tokens exclusively. Zero Console dependencies.
+ */
+export function StepIndicator({
+  steps,
+  currentStepIndex,
+  onStepClick,
+  className,
+}: StepIndicatorProps) {
+  return (
+    <nav
+      aria-label="Wizard progress"
+      className={cn("flex flex-col gap-1", className)}
+    >
+      <ol className="flex flex-col gap-1" role="list">
+        {steps.map((step, index) => {
+          const state = getStepState(index, currentStepIndex);
+          const isClickable = state === "completed" && onStepClick != null;
+
+          const content = (
+            <div className="flex items-center gap-3">
+              <StepCircle index={index} state={state} />
+              <span
+                className={cn(
+                  "text-sm font-medium transition-colors",
+                  state === "active" && "text-foreground",
+                  state === "completed" && "text-foreground",
+                  state === "pending" && "text-muted-foreground",
+                )}
+              >
+                {step.label}
+              </span>
+            </div>
+          );
+
+          return (
+            <li key={step.id}>
+              {isClickable ? (
+                <button
+                  type="button"
+                  onClick={() => onStepClick(index)}
+                  className={cn(
+                    "w-full rounded-md px-2 py-2 text-left transition-colors",
+                    "hover:bg-accent-hover",
+                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
+                  )}
+                  aria-label={`Go back to step ${index + 1}: ${step.label}`}
+                  aria-current={undefined}
+                >
+                  {content}
+                </button>
+              ) : (
+                <div
+                  className="px-2 py-2"
+                  aria-current={state === "active" ? "step" : undefined}
+                >
+                  {content}
+                </div>
+              )}
+              {index < steps.length - 1 && (
+                <div
+                  className="ml-[18px] h-4 w-px bg-border"
+                  aria-hidden="true"
+                />
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Step circle — the numbered indicator
+// ---------------------------------------------------------------------------
+
+type StepState = "completed" | "active" | "pending";
+
+function getStepState(index: number, currentIndex: number): StepState {
+  if (index < currentIndex) return "completed";
+  if (index === currentIndex) return "active";
+  return "pending";
+}
+
+function StepCircle({
+  index,
+  state,
+}: {
+  readonly index: number;
+  readonly state: StepState;
+}) {
+  return (
+    <div
+      className={cn(
+        "flex size-7 shrink-0 items-center justify-center rounded-full text-xs font-medium transition-colors",
+        state === "completed" && "bg-primary text-primary-foreground",
+        state === "active" && "border-2 border-primary text-primary",
+        state === "pending" && "border border-border text-muted-foreground",
+      )}
+      aria-hidden="true"
+    >
+      {state === "completed" ? (
+        <CheckIcon className="size-3.5" />
+      ) : (
+        <span>{index + 1}</span>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+
+function CheckIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="m3 8.5 3.5 3.5 6.5-8" />
+    </svg>
+  );
+}

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>
+  );
+}