docs: update participant trialCount documentation; fix participants view & experiments router diagnostics; add StepPreview placeholder and block-converter smoke test

src/components/experiments/designer/StepPreview.tsx

@@ -0,0 +1,195 @@
+import { memo } from "react";
+import { Badge } from "~/components/ui/badge";
+import { Card, CardContent, CardHeader, CardTitle } from "~/components/ui/card";
+
+/**
+ * Lightweight, dependency‑minimal placeholder for step preview rendering in the
+ * experiment designer. This was added to satisfy references expecting the file
+ * to exist (diagnostics previously reported it missing).
+ *
+ * Replace / extend this component when richer preview logic (block graphs,
+ * parameter summaries, validation states, drift indicators) is implemented.
+ *
+ * Design Goals:
+ * - Zero external (designer-internal) imports to avoid circular dependencies
+ * - Strict typing without leaking un-finalized internal step model types
+ * - Safe rendering even with partial or incomplete data
+ * - Pure presentational; no side-effects or client hooks required
+ */
+
+export interface StepPreviewAction {
+  id?: string;
+  name: string;
+  description?: string | null;
+  type?: string | null;
+  pluginId?: string | null;
+  pluginVersion?: string | null;
+  category?: string | null;
+}
+
+export interface StepPreviewProps {
+  id?: string;
+  name: string;
+  description?: string | null;
+  type?: string | null;
+  orderIndex?: number;
+  required?: boolean;
+  durationEstimateSeconds?: number;
+  actions?: StepPreviewAction[];
+  conditions?: unknown;
+  validationIssues?: readonly string[];
+  integrityHashFragment?: string | null;
+  /**
+   * When true, shows a subtle placeholder treatment (e.g. while constructing
+   * from a transient visual design mutation).
+   */
+  transient?: boolean;
+}
+
+/**
+ * Stateless pure component – safe to use in server or client trees.
+ */
+export const StepPreview = memo(function StepPreview({
+  name,
+  description,
+  type,
+  orderIndex,
+  required,
+  durationEstimateSeconds,
+  actions = [],
+  conditions,
+  validationIssues,
+  integrityHashFragment,
+  transient,
+}: StepPreviewProps) {
+  const hasIssues = (validationIssues?.length ?? 0) > 0;
+
+  return (
+    <Card
+      data-transient={transient ? "true" : "false"}
+      className={[
+        "relative overflow-hidden border",
+        transient ? "opacity-70" : "",
+        hasIssues ? "border-red-300 dark:border-red-500" : "",
+      ]
+        .filter(Boolean)
+        .join(" ")}
+    >
+      <CardHeader className="pb-3">
+        <div className="flex items-start justify-between gap-2">
+          <div>
+            <CardTitle className="text-sm font-semibold">
+              {orderIndex !== undefined && (
+                <span className="text-muted-foreground mr-2 text-xs">
+                  #{orderIndex + 1}
+                </span>
+              )}
+              {name || "(Untitled Step)"}
+            </CardTitle>
+            {description && (
+              <p className="text-muted-foreground mt-1 line-clamp-2 text-xs">
+                {description}
+              </p>
+            )}
+          </div>
+          <div className="flex shrink-0 flex-col items-end gap-1">
+            {type && (
+              <Badge variant="outline" className="text-[10px] uppercase">
+                {type}
+              </Badge>
+            )}
+            {required && (
+              <Badge
+                variant="secondary"
+                className="border border-blue-200 bg-blue-50 text-[10px] font-medium text-blue-700 dark:border-blue-400/40 dark:bg-blue-400/10 dark:text-blue-300"
+              >
+                Required
+              </Badge>
+            )}
+            {hasIssues && (
+              <Badge
+                variant="destructive"
+                className="text-[10px] font-medium tracking-wide"
+              >
+                {validationIssues?.length} Issue
+                {validationIssues && validationIssues.length > 1 ? "s" : ""}
+              </Badge>
+            )}
+          </div>
+        </div>
+      </CardHeader>
+      <CardContent className="pt-0">
+        <div className="flex flex-col gap-3">
+          <div className="text-muted-foreground flex flex-wrap items-center gap-2 text-xs">
+            {durationEstimateSeconds !== undefined && (
+              <span>≈ {Math.max(1, Math.round(durationEstimateSeconds))}s</span>
+            )}
+            {actions.length > 0 && (
+              <span>
+                {actions.length} action{actions.length > 1 ? "s" : ""}
+              </span>
+            )}
+            {conditions !== undefined && conditions !== null && (
+              <span>Conditional</span>
+            )}
+            {integrityHashFragment && (
+              <span className="truncate font-mono text-[10px] opacity-70">
+                hash:{integrityHashFragment.slice(0, 8)}
+              </span>
+            )}
+            {transient && <span className="italic">transient</span>}
+          </div>
+
+          {/* Action summary */}
+          {actions.length > 0 && (
+            <ol className="space-y-1">
+              {actions.slice(0, 5).map((a, idx) => (
+                <li
+                  key={a.id ?? `${a.name}-${idx}`}
+                  className="bg-muted/30 flex items-center gap-2 rounded border px-2 py-1 text-xs"
+                >
+                  <span className="font-medium">{a.name}</span>
+                  {a.type && (
+                    <span className="bg-background text-muted-foreground rounded px-1 py-0.5 text-[10px] uppercase">
+                      {a.type}
+                    </span>
+                  )}
+                  {a.pluginId && (
+                    <span className="text-muted-foreground truncate text-[10px]">
+                      {a.pluginId}
+                      {a.pluginVersion && (
+                        <span className="opacity-60">@{a.pluginVersion}</span>
+                      )}
+                    </span>
+                  )}
+                </li>
+              ))}
+              {actions.length > 5 && (
+                <li className="text-muted-foreground text-[10px] italic">
+                  + {actions.length - 5} more…
+                </li>
+              )}
+            </ol>
+          )}
+
+          {hasIssues && validationIssues && (
+            <ul className="space-y-1 rounded border border-red-300/50 bg-red-50/60 p-2 text-[11px] text-red-700 dark:border-red-500/40 dark:bg-red-950/30 dark:text-red-300">
+              {validationIssues.slice(0, 3).map((issue, i) => (
+                <li key={i} className="leading-snug">
+                  • {issue}
+                </li>
+              ))}
+              {validationIssues.length > 3 && (
+                <li className="opacity-70">
+                  + {validationIssues.length - 3} more…
+                </li>
+              )}
+            </ul>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  );
+});
+
+export default StepPreview;

src/components/participants/ParticipantsView.tsx

@@ -2,10 +2,20 @@
 
 import { format, formatDistanceToNow } from "date-fns";
 import {
-    AlertCircle,
-    CheckCircle,
-    Clock, Download, Eye, MoreHorizontal, Plus,
-    Search, Shield, Target, Trash2, Upload, Users, UserX
+  AlertCircle,
+  CheckCircle,
+  Clock,
+  Download,
+  Eye,
+  MoreHorizontal,
+  Plus,
+  Search,
+  Shield,
+  Target,
+  Trash2,
+  Upload,
+  Users,
+  UserX,
 } from "lucide-react";
 import { useRouter } from "next/navigation";
 import { useCallback, useState } from "react";
@@ -14,37 +24,37 @@ import { Badge } from "~/components/ui/badge";
 import { Button } from "~/components/ui/button";
 import { Card, CardContent, CardHeader, CardTitle } from "~/components/ui/card";
 import {
-    Dialog,
-    DialogContent,
-    DialogDescription,
-    DialogFooter,
-    DialogHeader,
-    DialogTitle
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
 } from "~/components/ui/dialog";
 import {
-    DropdownMenu,
-    DropdownMenuContent,
-    DropdownMenuItem,
-    DropdownMenuLabel,
-    DropdownMenuSeparator,
-    DropdownMenuTrigger
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
 } from "~/components/ui/dropdown-menu";
 import { Input } from "~/components/ui/input";
 import { Label } from "~/components/ui/label";
 import {
-    Select,
-    SelectContent,
-    SelectItem,
-    SelectTrigger,
-    SelectValue
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
 } from "~/components/ui/select";
 import {
-    Table,
-    TableBody,
-    TableCell,
-    TableHead,
-    TableHeader,
-    TableRow
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
 } from "~/components/ui/table";
 import { Textarea } from "~/components/ui/textarea";
 import { api } from "~/trpc/react";
@@ -54,13 +64,14 @@ interface Participant {
   participantCode: string;
   email: string | null;
   name: string | null;
-  demographics: any;
+  demographics: Record<string, unknown>;
   consentGiven: boolean;
   consentDate: Date | null;
   notes: string | null;
   createdAt: Date;
   updatedAt: Date;
   studyId: string;
+  trialCount: number;
   _count?: {
     trials: number;
   };
@@ -78,7 +89,14 @@ export function ParticipantsView() {
   const [showConsentDialog, setShowConsentDialog] = useState(false);
   const [selectedParticipant, setSelectedParticipant] =
     useState<Participant | null>(null);
-  const [newParticipant, setNewParticipant] = useState({
+  const [newParticipant, setNewParticipant] = useState<{
+    participantCode: string;
+    email: string;
+    name: string;
+    studyId: string;
+    demographics: Record<string, unknown>;
+    notes: string;
+  }>({
     participantCode: "",
     email: "",
     name: "",
@@ -102,12 +120,10 @@ export function ParticipantsView() {
     {
       studyId:
         studyFilter === "all"
-          ? userStudies?.studies?.[0]?.id || ""
+          ? (userStudies?.studies?.[0]?.id ?? "")
           : studyFilter,
-      search: searchQuery || undefined,
+      search: searchQuery ?? undefined,
       limit: 100,
-
-
     },
     {
       enabled: !!userStudies?.studies?.length,
@@ -117,7 +133,7 @@ export function ParticipantsView() {
   // Mutations
   const createParticipantMutation = api.participants.create.useMutation({
     onSuccess: () => {
-      refetch();
+      void refetch();
       setShowNewParticipantDialog(false);
       resetNewParticipantForm();
     },
@@ -125,7 +141,7 @@ export function ParticipantsView() {
 
   const updateConsentMutation = api.participants.update.useMutation({
     onSuccess: () => {
-      refetch();
+      void refetch();
       setShowConsentDialog(false);
       setSelectedParticipant(null);
     },
@@ -133,7 +149,7 @@ export function ParticipantsView() {
 
   const deleteParticipantMutation = api.participants.delete.useMutation({
     onSuccess: () => {
-      refetch();
+      void refetch();
     },
   });
 
@@ -155,31 +171,25 @@ export function ParticipantsView() {
       await createParticipantMutation.mutateAsync({
         participantCode: newParticipant.participantCode,
         studyId: newParticipant.studyId,
-        email: newParticipant.email || undefined,
-        name: newParticipant.name || undefined,
+        email: newParticipant.email ? newParticipant.email : undefined,
+        name: newParticipant.name ? newParticipant.name : undefined,
         demographics: newParticipant.demographics,
-
       });
     } catch (_error) {
       console.error("Failed to create participant:", _error);
     }
-  }, [newParticipant, createParticipantMutation]);
+  }, [createParticipantMutation, newParticipant]);
 
-  const handleUpdateConsent = useCallback(
-    async (consentGiven: boolean) => {
-      if (!selectedParticipant) return;
-
-      try {
-        await updateConsentMutation.mutateAsync({
-          id: selectedParticipant.id,
-
-        });
-      } catch (_error) {
-        console.error("Failed to update consent:", _error);
-      }
-    },
-    [selectedParticipant, updateConsentMutation],
-  );
+  const handleUpdateConsent = useCallback(async () => {
+    if (!selectedParticipant) return;
+    try {
+      await updateConsentMutation.mutateAsync({
+        id: selectedParticipant.id,
+      });
+    } catch (_error) {
+      console.error("Failed to update consent:", _error);
+    }
+  }, [selectedParticipant, updateConsentMutation]);
 
   const handleDeleteParticipant = useCallback(
     async (participantId: string) => {
@@ -230,13 +240,16 @@ export function ParticipantsView() {
     }
   };
 
-  const filteredParticipants =
-    participantsData?.participants?.filter((participant) => {
-      if (consentFilter === "consented" && !participant.consentGiven)
+  const filteredParticipants: Participant[] =
+    (participantsData?.participants?.filter((participant) => {
+      if (consentFilter === "consented" && !participant.consentGiven) {
         return false;
-      if (consentFilter === "pending" && participant.consentGiven) return false;
+      }
+      if (consentFilter === "pending" && participant.consentGiven) {
+        return false;
+      }
       return true;
-    }) || [];
+    }) as Participant[] | undefined) ?? [];
 
   return (
     <div className="space-y-6">
@@ -296,7 +309,7 @@ export function ParticipantsView() {
               </SelectTrigger>
               <SelectContent>
                 <SelectItem value="all">All Studies</SelectItem>
-                {userStudies?.studies?.map((study: any) => (
+                {userStudies?.studies?.map((study) => (
                   <SelectItem key={study.id} value={study.id}>
                     {study.name}
                   </SelectItem>
@@ -317,7 +330,7 @@ export function ParticipantsView() {
               value={`${sortBy}-${sortOrder}`}
               onValueChange={(value) => {
                 const [field, order] = value.split("-");
-                setSortBy(field || "createdAt");
+                setSortBy(field ?? "createdAt");
                 setSortOrder(order as "asc" | "desc");
               }}
             >
@@ -345,7 +358,7 @@ export function ParticipantsView() {
               <Users className="h-8 w-8 text-blue-600" />
               <div>
                 <p className="text-2xl font-bold">
-                  {participantsData?.pagination?.total || 0}
+                  {participantsData?.pagination?.total ?? 0}
                 </p>
                 <p className="text-xs text-slate-600">Total Participants</p>
               </div>
@@ -358,7 +371,11 @@ export function ParticipantsView() {
               <CheckCircle className="h-8 w-8 text-green-600" />
               <div>
                 <p className="text-2xl font-bold">
-                  {filteredParticipants.filter((p) => p.consentGiven).length}
+                  {
+                    filteredParticipants.filter(
+                      (p: Participant) => p.consentGiven,
+                    ).length
+                  }
                 </p>
                 <p className="text-xs text-slate-600">Consented</p>
               </div>
@@ -371,7 +388,11 @@ export function ParticipantsView() {
               <Clock className="h-8 w-8 text-yellow-600" />
               <div>
                 <p className="text-2xl font-bold">
-                  {filteredParticipants.filter((p) => !p.consentGiven).length}
+                  {
+                    filteredParticipants.filter(
+                      (p: Participant) => !p.consentGiven,
+                    ).length
+                  }
                 </p>
                 <p className="text-xs text-slate-600">Pending Consent</p>
               </div>
@@ -385,7 +406,7 @@ export function ParticipantsView() {
               <div>
                 <p className="text-2xl font-bold">
                   {filteredParticipants.reduce(
-                    (sum, p) => sum + (p.trialCount || 0),
+                    (sum: number, p: Participant) => sum + (p.trialCount ?? 0),
                     0,
                   )}
                 </p>
@@ -469,11 +490,11 @@ export function ParticipantsView() {
                       <div className="text-sm">
                         {userStudies?.studies?.find(
                           (s) => s.id === participant.studyId,
-                        )?.name || "Unknown Study"}
+                        )?.name ?? "Unknown Study"}
                       </div>
                     </TableCell>
                     <TableCell>
-                      {getConsentStatusBadge({...participant, demographics: null, notes: null})}
+                      {getConsentStatusBadge(participant)}
                       {participant.consentDate && (
                         <p className="mt-1 text-xs text-slate-500">
                           {format(
@@ -484,7 +505,7 @@ export function ParticipantsView() {
                       )}
                     </TableCell>
                     <TableCell>
-                      {getTrialsBadge(participant.trialCount || 0)}
+                      {getTrialsBadge(participant.trialCount ?? 0)}
                     </TableCell>
                     <TableCell>
                       <div className="text-sm text-slate-600">
@@ -512,7 +533,7 @@ export function ParticipantsView() {
                           </DropdownMenuItem>
                           <DropdownMenuItem
                             onClick={() => {
-                              setSelectedParticipant({...participant, demographics: null, notes: null});
+                              setSelectedParticipant(participant);
                               setShowConsentDialog(true);
                             }}
                           >
@@ -696,7 +717,7 @@ export function ParticipantsView() {
 
               <div className="flex space-x-2">
                 <Button
-                  onClick={() => handleUpdateConsent(true)}
+                  onClick={() => void handleUpdateConsent()}
                   disabled={
                     selectedParticipant.consentGiven ||
                     updateConsentMutation.isPending
@@ -708,7 +729,7 @@ export function ParticipantsView() {
                 </Button>
                 <Button
                   variant="outline"
-                  onClick={() => handleUpdateConsent(false)}
+                  onClick={() => void handleUpdateConsent()}
                   disabled={
                     !selectedParticipant.consentGiven ||
                     updateConsentMutation.isPending