@explorer02/cfm-survey-sdk 0.2.2 → 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/implementation_plan.md

@@ -121,8 +121,28 @@ Fill from `00-integration/question-type-sdk-matrix.md`:
 | FileUploadScale | | `08-file-upload-scale.md` |
 | Header / Footer / ProgressBar / LanguageSelector | | `10`–`12` |
 
+## 3e. Interaction dependencies (from survey inventory)
+
+| Package | Install when |
+|---------|--------------|
+| `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities` | Survey contains `RANK_ORDER` |
+| `react-icons` | Always (shared setup) + CSAT emoji/star matrix |
+
+Copy portable templates from `docs/templates/` — see `component-checklist.md`.
+
 ## 4b. Per-Question Config & UI Coverage
 
+Inventory required config fields per type:
+
+| type | must inventory |
+|------|----------------|
+| MCQ | `selectionMode`, `minSelections`, `maxSelections`, `defaultOptionIds`, answer-logic on options |
+| RANK_ORDER | `interactionMode`, `optionDisplay`, `requireRankAll`, `shuffleOptions` |
+| CFM/CSAT/RATING | `gridLayout`, `displayStyle`, `selectionMode`, `hasNotApplicableOption`, `statementLayout` |
+| SLIDER_MATRIX | `enableInputBox`, `enableNotApplicable`, `sliderStyle` |
+| FILE_UPLOAD | `maxFileCount`, `fileSizeLimit`, `fileSizeLimitType`, upload API configured? |
+| HEATMAP | `maxClicksAllowed`, image URL |
+
 | questionId | type | configs detected | uiSpec read | component files | branches implemented |
 |------------|------|------------------|-------------|-----------------|---------------------|
 | | | | | | |

package/templates/docs/templates/survey-inventory.schema.json

@@ -7,22 +7,27 @@
   "required": ["questions", "uniqueTypes"],
   "properties": {
     "instanceId": { "type": "string", "description": "JWT used to fetch survey" },
+    "interactionDependencies": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "npm packages e.g. @dnd-kit/core, react-icons"
+    },
     "uniqueTypes": {
       "type": "array",
       "items": {
         "type": "string",
         "enum": [
-          "nps",
-          "mcq",
-          "text_input",
-          "csat",
-          "star_rating",
-          "slider",
-          "cfm_matrix",
-          "rating_matrix",
-          "slider_matrix",
-          "file_upload",
-          "text_and_media"
+          "MCQ",
+          "TEXTFIELD",
+          "NPS_SCALE",
+          "CFM_MATRIX",
+          "CSAT_MATRIX",
+          "RATING_MATRIX",
+          "SLIDER_MATRIX",
+          "FILE_UPLOAD",
+          "TEXT_AND_MEDIA",
+          "HEATMAP",
+          "RANK_ORDER"
         ]
       },
       "uniqueItems": true
@@ -37,23 +42,23 @@
           "type": {
             "type": "string",
             "enum": [
-              "nps",
-              "mcq",
-              "text_input",
-              "csat",
-              "star_rating",
-              "slider",
-              "cfm_matrix",
-              "rating_matrix",
-              "slider_matrix",
-              "file_upload",
-              "text_and_media"
+              "MCQ",
+              "TEXTFIELD",
+              "NPS_SCALE",
+              "CFM_MATRIX",
+              "CSAT_MATRIX",
+              "RATING_MATRIX",
+              "SLIDER_MATRIX",
+              "FILE_UPLOAD",
+              "TEXT_AND_MEDIA",
+              "HEATMAP",
+              "RANK_ORDER"
             ]
           },
           "configFlags": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "Non-default config, e.g. gridLayout:carousel"
+            "description": "e.g. interactionMode:dragAndDrop, gridLayout:carousel, selectionMode:multiple, defaultOptionIds"
           },
           "uiSpecRead": { "type": "string" },
           "componentFiles": {

package/templates/docs/templates/surveyUiIcons.tsx

@@ -0,0 +1,52 @@
+'use client';
+
+import React from 'react';
+import {
+  FaFaceAngry,
+  FaFaceSadTear,
+  FaFaceFrown,
+  FaFaceFrownOpen,
+  FaFaceMeh,
+  FaFaceSmile,
+  FaFaceSmileBeam,
+  FaFaceGrin,
+  FaFaceGrinWide,
+  FaFaceGrinStars,
+} from 'react-icons/fa6';
+
+const EMOJI_COLORS = [
+  '#dc2626', '#e04832', '#ea580c', '#f59e0b', '#eab308',
+  '#a3a323', '#84cc16', '#65a30d', '#22c55e', '#16a34a', '#059669',
+] as const;
+
+const FACE_ICONS = [
+  FaFaceAngry, FaFaceSadTear, FaFaceFrown, FaFaceFrownOpen, FaFaceMeh, FaFaceMeh,
+  FaFaceSmile, FaFaceSmileBeam, FaFaceGrin, FaFaceGrinWide, FaFaceGrinStars,
+] as const;
+
+const CsatEmojiSet: Record<number, React.ReactNode> = {};
+for (let i = 0; i < 11; i++) {
+  const Icon = FACE_ICONS[i];
+  CsatEmojiSet[i + 1] = React.createElement(Icon as React.ElementType, {
+    className: 'transition-transform',
+    style: { color: EMOJI_COLORS[i], fontSize: '28px' },
+  });
+}
+
+const EMOJI_SCALES: Record<number, number[]> = {
+  3: [3, 6, 8],
+  4: [3, 4, 7, 9],
+  5: [3, 4, 6, 7, 9],
+  6: [3, 4, 6, 7, 9, 11],
+};
+
+export function getEmojiForIndex(index: number, total: number): React.ReactNode {
+  if (total <= 1) return CsatEmojiSet[6];
+  if (EMOJI_SCALES[total]) {
+    const key = EMOJI_SCALES[total][index];
+    if (key) return CsatEmojiSet[key];
+  }
+  const percent = index / (total - 1);
+  const key = Math.min(11, Math.max(1, Math.round(percent * 10) + 1));
+  return CsatEmojiSet[key];
+}

package/templates/docs/templates/verify-agent-build.sh

@@ -46,6 +46,38 @@ else
     exit 1
   fi
   echo "OK: All 11 question.type branches present"
+
+  if grep -q "RANK_ORDER" "$QUESTION_FILE" || grep -q "RankOrderScale" "$QUESTION_FILE"; then
+    RANK_FILE=""
+    for candidate in src/components/RankOrderScale.tsx components/RankOrderScale.tsx app/components/RankOrderScale.tsx; do
+      if [ -f "$candidate" ]; then RANK_FILE="$candidate"; break; fi
+    done
+    if [ -z "$RANK_FILE" ]; then
+      echo "FAIL: RankOrderScale.tsx required when RANK_ORDER is wired in Question.tsx"
+      exit 1
+    fi
+    echo "OK: RankOrderScale.tsx exists ($RANK_FILE)"
+    if ! grep -q "@dnd-kit/core" package.json 2>/dev/null; then
+      echo "FAIL: @dnd-kit/core missing from package.json (required for RANK_ORDER)"
+      exit 1
+    fi
+    echo "OK: @dnd-kit in package.json"
+    if ! grep -q "getVisibleRankOrderOptionsForAnswers" "$QUESTION_FILE"; then
+      echo "WARN: getVisibleRankOrderOptionsForAnswers not found in Question.tsx"
+    fi
+  fi
+
+  if grep -q "FILE_UPLOAD" "$QUESTION_FILE" || grep -q "FileUploadScale" "$QUESTION_FILE"; then
+    UPLOAD_FILE=""
+    for candidate in src/components/FileUploadScale.tsx components/FileUploadScale.tsx app/components/FileUploadScale.tsx; do
+      if [ -f "$candidate" ]; then UPLOAD_FILE="$candidate"; break; fi
+    done
+    if [ -z "$UPLOAD_FILE" ]; then
+      echo "FAIL: FileUploadScale.tsx required when FILE_UPLOAD is wired"
+      exit 1
+    fi
+    echo "OK: FileUploadScale.tsx exists ($UPLOAD_FILE)"
+  fi
 fi
 
 echo "Running npm run build..."