@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

package/templates/docs/templates/RankOrderScale.tsx

@@ -0,0 +1,353 @@
+'use client';
+
+/**
+ * Portable RankOrderScale template — copy to src/components/RankOrderScale.tsx
+ * Import SDK from your package.json: @explorer02/cfm-survey-sdk or @repo/sdk
+ * Requires: @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+ * Next.js: add 'use client' (already present); optional dynamic(..., { ssr: false }) wrapper in Question.tsx
+ */
+
+import React, { useMemo } from 'react';
+import {
+  DndContext,
+  closestCenter,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+} from '@dnd-kit/core';
+import {
+  SortableContext,
+  arrayMove,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable';
+import { CSS } from '@dnd-kit/utilities';
+import type {
+  RankOrderAnswers,
+  RankOrderOption,
+  RankOrderOptionDisplay,
+  RankOrderQuestion,
+} from '@explorer02/cfm-survey-sdk';
+import {
+  assignRankWithoutDuplicates,
+  buildRankOrderFromOrderedOptionIds,
+  getOrderedOptionIdsFromRanks,
+  normalizeRankOrderAnswers,
+} from '@explorer02/cfm-survey-sdk';
+
+type RankOrderScaleProps = {
+  question: RankOrderQuestion;
+  selectedValue?: RankOrderAnswers;
+  onSelect: (value: RankOrderAnswers) => void;
+};
+
+type RankOrderOptionRowProps = {
+  option: RankOrderOption;
+  optionDisplay: RankOrderOptionDisplay;
+  rankSelect?: React.ReactNode;
+  trailingControls?: React.ReactNode;
+  dragHandle?: React.ReactNode;
+  rankBadge?: number;
+};
+
+function RankOrderOptionContent({
+  option,
+  optionDisplay,
+}: {
+  option: RankOrderOption;
+  optionDisplay: RankOrderOptionDisplay;
+}) {
+  const imageUrl = option.imageUrl || option.previewImageUrl;
+
+  if (optionDisplay === 'imageOnly') {
+    return (
+      <div className="flex flex-1 items-center">
+        {imageUrl ? (
+          <img
+            src={imageUrl}
+            alt={option.optionLabel || 'Option image'}
+            className="h-24 w-24 rounded-md object-cover"
+          />
+        ) : (
+          <div className="flex h-24 w-24 items-center justify-center rounded-md bg-gray-100 text-xs text-gray-400">
+            No image
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  if (optionDisplay === 'textOnly') {
+    return (
+      <span
+        className="flex-1 text-[15px] font-medium leading-tight text-gray-900"
+        dangerouslySetInnerHTML={{ __html: option.optionLabel }}
+      />
+    );
+  }
+
+  return (
+    <div className="flex flex-1 items-center gap-4">
+      {imageUrl ? (
+        <img
+          src={imageUrl}
+          alt={option.optionLabel || 'Option image'}
+          className="h-14 w-14 shrink-0 rounded-md object-cover"
+        />
+      ) : (
+        <div className="flex h-14 w-14 shrink-0 items-center justify-center rounded-md bg-gray-100 text-xs text-gray-400">
+          No image
+        </div>
+      )}
+      <span
+        className="text-[15px] font-medium leading-tight text-gray-900"
+        dangerouslySetInnerHTML={{ __html: option.optionLabel }}
+      />
+    </div>
+  );
+}
+
+function RankOrderOptionRow({
+  option,
+  optionDisplay,
+  rankSelect,
+  trailingControls,
+  dragHandle,
+  rankBadge,
+}: RankOrderOptionRowProps) {
+  return (
+    <div className="flex items-center gap-3 rounded-lg border border-[#e5e5e5] bg-white px-4 py-3 transition-colors hover:bg-gray-50/50">
+      {rankSelect}
+      {dragHandle}
+      {rankBadge !== undefined && (
+        <span className="flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-[#fdf2f8] text-sm font-semibold text-[#e20074]">
+          {rankBadge}
+        </span>
+      )}
+      <RankOrderOptionContent option={option} optionDisplay={optionDisplay} />
+      {trailingControls}
+    </div>
+  );
+}
+
+function DropdownRankLayout({
+  question,
+  selectedValue,
+  onSelect,
+}: RankOrderScaleProps) {
+  const rankAnswers = normalizeRankOrderAnswers(selectedValue);
+  const rankChoices = question.options.map((_, index) => index + 1);
+
+  const handleRankChange = (optionId: string, rawValue: string) => {
+    const nextRank = rawValue === '' ? undefined : Number(rawValue);
+    onSelect(assignRankWithoutDuplicates(rankAnswers, optionId, nextRank));
+  };
+
+  return (
+    <div className="space-y-3">
+      {question.options.map(option => {
+        const currentRank = rankAnswers[option.id];
+
+        return (
+          <RankOrderOptionRow
+            key={option.id}
+            option={option}
+            optionDisplay={question.optionDisplay}
+            rankSelect={
+              <select
+                aria-label={`Rank for ${option.optionLabel || option.id}`}
+                value={currentRank ?? ''}
+                onChange={event => handleRankChange(option.id, event.target.value)}
+                className="h-10 w-16 shrink-0 rounded border border-gray-300 bg-white px-2 text-sm outline-none focus:border-[#e20074] focus:ring-1 focus:ring-[#e20074]"
+              >
+                <option value="">-</option>
+                {rankChoices.map(rank => (
+                  <option key={rank} value={rank}>
+                    {rank}
+                  </option>
+                ))}
+              </select>
+            }
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+type SortableRankItemProps = {
+  option: RankOrderOption;
+  optionDisplay: RankOrderOptionDisplay;
+  rank: number;
+  onMoveUp: () => void;
+  onMoveDown: () => void;
+  isFirst: boolean;
+  isLast: boolean;
+};
+
+function SortableRankItem({
+  option,
+  optionDisplay,
+  rank,
+  onMoveUp,
+  onMoveDown,
+  isFirst,
+  isLast,
+}: SortableRankItemProps) {
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+    id: option.id,
+  });
+
+  const style = {
+    transform: CSS.Transform.toString(transform),
+    transition,
+    opacity: isDragging ? 0.85 : 1,
+    zIndex: isDragging ? 10 : undefined,
+  };
+
+  return (
+    <div ref={setNodeRef} style={style}>
+      <RankOrderOptionRow
+        option={option}
+        optionDisplay={optionDisplay}
+        rankBadge={rank}
+        dragHandle={
+          <button
+            type="button"
+            aria-label={`Drag to reorder ${option.optionLabel || option.id}`}
+            className="flex h-10 w-8 shrink-0 cursor-grab items-center justify-center rounded text-gray-500 hover:bg-gray-100 active:cursor-grabbing"
+            {...attributes}
+            {...listeners}
+          >
+            <svg viewBox="0 0 20 20" className="h-5 w-5" fill="currentColor" aria-hidden="true">
+              <circle cx="7" cy="6" r="1.5" />
+              <circle cx="13" cy="6" r="1.5" />
+              <circle cx="7" cy="10" r="1.5" />
+              <circle cx="13" cy="10" r="1.5" />
+              <circle cx="7" cy="14" r="1.5" />
+              <circle cx="13" cy="14" r="1.5" />
+            </svg>
+          </button>
+        }
+        trailingControls={
+          <div className="flex shrink-0 flex-col gap-1">
+            <button
+              type="button"
+              aria-label={`Move ${option.optionLabel || option.id} up`}
+              disabled={isFirst}
+              onClick={onMoveUp}
+              className="rounded border border-gray-300 px-2 py-1 text-xs text-gray-700 disabled:cursor-not-allowed disabled:opacity-40"
+            >
+              Up
+            </button>
+            <button
+              type="button"
+              aria-label={`Move ${option.optionLabel || option.id} down`}
+              disabled={isLast}
+              onClick={onMoveDown}
+              className="rounded border border-gray-300 px-2 py-1 text-xs text-gray-700 disabled:cursor-not-allowed disabled:opacity-40"
+            >
+              Down
+            </button>
+          </div>
+        }
+      />
+    </div>
+  );
+}
+
+function DragDropRankLayout({
+  question,
+  selectedValue,
+  onSelect,
+}: RankOrderScaleProps) {
+  const rankAnswers = normalizeRankOrderAnswers(selectedValue);
+  const optionIds = question.options.map(option => option.id);
+
+  const orderedOptionIds = useMemo(() => {
+    const rankedIds = getOrderedOptionIdsFromRanks(rankAnswers, optionIds);
+    const unrankedIds = optionIds.filter(optionId => !rankedIds.includes(optionId));
+    return rankedIds.length > 0 ? [...rankedIds, ...unrankedIds] : optionIds;
+  }, [rankAnswers, optionIds]);
+
+  const sensors = useSensors(
+    useSensor(PointerSensor),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+    })
+  );
+
+  const updateOrder = (nextOrder: string[]) => {
+    onSelect(buildRankOrderFromOrderedOptionIds(nextOrder));
+  };
+
+  const handleDragEnd = (event: DragEndEvent) => {
+    const { active, over } = event;
+    if (!over || active.id === over.id) {
+      return;
+    }
+
+    const oldIndex = orderedOptionIds.indexOf(String(active.id));
+    const newIndex = orderedOptionIds.indexOf(String(over.id));
+    if (oldIndex === -1 || newIndex === -1) {
+      return;
+    }
+
+    updateOrder(arrayMove(orderedOptionIds, oldIndex, newIndex));
+  };
+
+  const moveOption = (optionId: string, direction: 'up' | 'down') => {
+    const currentIndex = orderedOptionIds.indexOf(optionId);
+    if (currentIndex === -1) {
+      return;
+    }
+
+    const targetIndex = direction === 'up' ? currentIndex - 1 : currentIndex + 1;
+    if (targetIndex < 0 || targetIndex >= orderedOptionIds.length) {
+      return;
+    }
+
+    updateOrder(arrayMove(orderedOptionIds, currentIndex, targetIndex));
+  };
+
+  return (
+    <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
+      <SortableContext items={orderedOptionIds} strategy={verticalListSortingStrategy}>
+        <div className="space-y-3">
+          {orderedOptionIds.map((optionId, index) => {
+            const option = question.options.find(item => item.id === optionId);
+            if (!option) {
+              return null;
+            }
+
+            return (
+              <SortableRankItem
+                key={option.id}
+                option={option}
+                optionDisplay={question.optionDisplay}
+                rank={index + 1}
+                isFirst={index === 0}
+                isLast={index === orderedOptionIds.length - 1}
+                onMoveUp={() => moveOption(option.id, 'up')}
+                onMoveDown={() => moveOption(option.id, 'down')}
+              />
+            );
+          })}
+        </div>
+      </SortableContext>
+    </DndContext>
+  );
+}
+
+export function RankOrderScale({ question, selectedValue, onSelect }: RankOrderScaleProps) {
+  if (question.interactionMode === 'dragAndDrop') {
+    return (
+      <DragDropRankLayout question={question} selectedValue={selectedValue} onSelect={onSelect} />
+    );
+  }
+
+  return <DropdownRankLayout question={question} selectedValue={selectedValue} onSelect={onSelect} />;
+}

package/templates/docs/templates/deploy-to-aws.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Deploy static survey UI to AWS via EC2 middle API (S3 + CloudFront).
+# Prerequisites: CFM_INSTANCE_ID, CFM_DEPLOY_API_BASE, OUT_DIR set in environment.
+# Run from project root after a successful static build.
+set -euo pipefail
+
+: "${CFM_INSTANCE_ID:?Set CFM_INSTANCE_ID to the same JWT as SurveyPage SURVEY_INSTANCE_ID}"
+: "${CFM_DEPLOY_API_BASE:?Set CFM_DEPLOY_API_BASE (e.g. http://43.204.26.213:3000)}"
+: "${OUT_DIR:?Set OUT_DIR to absolute path of out/ (Next.js) or dist/ (Vite)}"
+
+if [ ! -f "$OUT_DIR/index.html" ]; then
+  echo "FAIL: $OUT_DIR/index.html not found — run build first"
+  exit 1
+fi
+
+FILE_COUNT=$(find "$OUT_DIR" -type f | wc -l | tr -d ' ')
+if [ "$FILE_COUNT" -gt 500 ]; then
+  echo "FAIL: $FILE_COUNT files exceeds API limit of 500"
+  exit 1
+fi
+
+echo "=== AWS Deploy ==="
+echo "API: $CFM_DEPLOY_API_BASE"
+echo "OUT: $OUT_DIR ($FILE_COUNT files)"
+echo
+
+HEALTH=$(curl -s "$CFM_DEPLOY_API_BASE/health")
+echo "Health: $HEALTH"
+echo
+
+python3 <<'PY' > /tmp/deploy-manifest.json
+import json, os, mimetypes
+from pathlib import Path
+out = Path(os.environ["OUT_DIR"])
+files = []
+for path in sorted(out.rglob("*")):
+    if not path.is_file():
+        continue
+    rel = path.relative_to(out).as_posix()
+    mime, _ = mimetypes.guess_type(rel)
+    files.append({
+        "path": rel,
+        "contentType": mime or "application/octet-stream",
+        "sizeBytes": path.stat().st_size,
+    })
+print(json.dumps({"files": files}))
+print(f"files: {len(files)}", file=__import__('sys').stderr)
+PY
+
+echo "Channel 1: deploy/start"
+curl -s -X POST "$CFM_DEPLOY_API_BASE/deploy/start" \
+  -H "Authorization: Bearer $CFM_INSTANCE_ID" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/deploy-manifest.json \
+  | tee /tmp/deploy-start.json
+echo
+
+if ! python3 -c "import json; json.load(open('/tmp/deploy-start.json'))['deployId']" 2>/dev/null; then
+  echo "FAIL: deploy/start did not return deployId"
+  exit 1
+fi
+
+echo "Channel 2: S3 uploads"
+python3 <<'PY'
+import json, os, subprocess
+from pathlib import Path
+
+out = Path(os.environ["OUT_DIR"])
+start = json.load(open("/tmp/deploy-start.json"))
+manifest = {f["path"]: f["contentType"] for f in json.load(open("/tmp/deploy-manifest.json"))["files"]}
+failed = []
+
+for item in start["uploads"]:
+    path = item["path"]
+    url = item["uploadUrl"]
+    mime = manifest.get(path, "application/octet-stream")
+    proc = subprocess.run(
+        ["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}",
+         "-X", "PUT", url, "-H", f"Content-Type: {mime}",
+         "--data-binary", f"@{out / path}"],
+        capture_output=True, text=True,
+    )
+    code = proc.stdout.strip()
+    mark = "OK" if code == "200" else "FAIL"
+    print(f"{mark} {code} {path}")
+    if code != "200":
+        failed.append(path)
+
+if failed:
+    print(f"\n{len(failed)} failed — rerun deploy (presigned URLs expire)")
+    raise SystemExit(1)
+print("\nAll uploads succeeded")
+PY
+
+echo
+echo "Channel 3: deploy/complete"
+DEPLOY_ID=$(python3 -c "import json; print(json.load(open('/tmp/deploy-start.json'))['deployId'])")
+curl -s -X POST "$CFM_DEPLOY_API_BASE/deploy/complete" \
+  -H "Authorization: Bearer $CFM_INSTANCE_ID" \
+  -H "Content-Type: application/json" \
+  -d "{\"deployId\":\"$DEPLOY_ID\"}" \
+  | tee /tmp/deploy-complete.json
+echo
+
+LIVE_URL=$(python3 -c "import json; print(json.load(open('/tmp/deploy-complete.json'))['url'])")
+echo "Live URL: $LIVE_URL"
+HTTP=$(curl -s -o /dev/null -w "%{http_code}" "$LIVE_URL")
+echo "Verify HTTP: $HTTP"
+if [ "$HTTP" != "200" ]; then
+  echo "WARN: index.html returned $HTTP — check CloudFront path or invalidation"
+  exit 1
+fi
+
+echo "=== Deploy complete ==="

package/templates/docs/templates/heatmapCoords.ts

@@ -0,0 +1,58 @@
+/**
+ * Portable heatmap coordinate helpers for agent projects.
+ *
+ * Copy to e.g. src/lib/heatmapCoords.ts — do not import from monorepo-only paths.
+ * See 01-components/17-heatmap-scale.md and question-type-sdk-matrix.md#heatmap.
+ */
+import type { MouseEvent } from 'react';
+import type { HeatmapClickPoint } from '@explorer02/cfm-survey-sdk';
+
+export const SPOT_HIT_RADIUS_PX = 14;
+
+export function roundCoordinate(value: number): number {
+  return Math.round(value * 100000) / 100000;
+}
+
+export function getNormalizedClickFromImage(
+  event: MouseEvent,
+  imageElement: HTMLImageElement
+): { x: number; y: number } {
+  const rect = imageElement.getBoundingClientRect();
+  if (rect.width === 0 || rect.height === 0) {
+    return { x: 0, y: 0 };
+  }
+
+  const x = (event.clientX - rect.left) / rect.width;
+  const y = (event.clientY - rect.top) / rect.height;
+
+  return {
+    x: roundCoordinate(Math.min(1, Math.max(0, x))),
+    y: roundCoordinate(Math.min(1, Math.max(0, y))),
+  };
+}
+
+export function findSpotNearClick(
+  clickX: number,
+  clickY: number,
+  spots: HeatmapClickPoint[],
+  imageRect: DOMRect
+): HeatmapClickPoint | undefined {
+  const clickPixelX = clickX * imageRect.width;
+  const clickPixelY = clickY * imageRect.height;
+
+  for (const spot of spots) {
+    const spotPixelX = spot.x * imageRect.width;
+    const spotPixelY = spot.y * imageRect.height;
+    const distance = Math.hypot(spotPixelX - clickPixelX, spotPixelY - clickPixelY);
+
+    if (distance <= SPOT_HIT_RADIUS_PX) {
+      return spot;
+    }
+  }
+
+  return undefined;
+}
+
+export function createNewSpot(x: number, y: number): HeatmapClickPoint {
+  return { id: crypto.randomUUID(), x, y };
+}