@explorer02/cfm-survey-sdk 0.2.0 → 0.2.2

package/templates/docs/templates/implementation_plan.md

@@ -12,80 +12,146 @@
 ## 1. Data Fetching & State
 
 - [ ] `useSurveySDK` options: instanceId, language, placeholders, debug
-- [ ] `SurveyPage` 5-state machine: loading / error / empty / submitted / active
+- [ ] `surveyOptions` wrapped in `useMemo` (stable refs for placeholders / customFieldValues)
+- [ ] `customFieldValues` map when survey logic references `CUSTOM_FIELD` entities (see `custom-field-logic-and-navigation.md`)
+- [ ] `savePartialResponse` enabled if required (`true` or `{ debounceMs }`)
+- [ ] Monorepo: `packages/sdk` built (`npm run build`) before client dev
+- [ ] `SurveyPage` phase router: loading / error / empty / intro / paused / end / terminal / content
 - [ ] `surveyQueryResults.isLoading`, `.error`, `.data` handling
 - [ ] `submitSurveyResults.isLoading`, `.error`, `.data` handling
+- [ ] Answers read from `state.answers` (`SurveyAnswers`); changes via `payload.answerValue`
 
 ## 2. Pagination, Actions & Flow
 
-- [ ] `onAction` NEXT / PREVIOUS / SUBMIT wiring
-- [ ] `ProgressBar` bound to `state.progressPercentage`
-- [ ] Back/Next button visibility per layout config
-- [ ] Last-page NEXT → auto SUBMIT behavior
+- [ ] `onAction` START / NEXT / PREVIOUS / SUBMIT wiring
+- [ ] `onAction(SCROLL)` once on first scroll (mark as started)
+- [ ] `onAction(RECORD_QUESTION_VIEW)` via IntersectionObserver on question wrappers
+- [ ] `ProgressBar` bound to `state.progressPercentage` (path-scoped — see `00-integration/progress.md`)
+- [ ] Back via `state.canGoBack`; primary label via `state.primaryButtonType`
+- [ ] Read `00-integration/skip-logic-and-navigation.md` for skip/Back behavior
+- [ ] Read `00-integration/client-integration-guide.md` for full wiring map
+
+## 1b. Lifecycle & Analytics
+
+- [ ] `onAction(SCROLL)` once on first scroll (see `survey-lifecycle-analytics.md`)
+- [ ] First `CHANGE` auto mark-as-started (SDK — no extra client call)
+- [ ] `onAction(RECORD_QUESTION_VIEW)` via IntersectionObserver on `#question-{id}` wrappers
+- [ ] Effect re-runs when `currentQuestions` changes (multi-page / display logic)
+- [ ] Partial save: `savePartialResponse` + monitor `partialSaveResults` if enabled (see `partial-save-and-recovery.md`)
+- [ ] Placeholders: stable `SURVEY_PLACEHOLDERS` ref + `useMemo` on hook options (see `placeholders-and-tokens.md`)
 
 ## 3. Question Dispatching (`Question.tsx`)
 
-Exhaustive switch — check each:
-
-- [ ] `rating` → `RatingScale`
-- [ ] `csat` → `CsatScale`
-- [ ] `radio` → inline MCQ
-- [ ] `text` → inline textarea/input
-- [ ] `rating_scale` → `RatingScale` (star/emoji)
-- [ ] `slider` → `CustomSliderTrack`
-- [ ] `matrix` + `CFM_MATRIX` → `LikertMatrixScale`
-- [ ] `matrix` + `CSAT_MATRIX` / `RATING_MATRIX` → `CsatMatrixScale`
-- [ ] `rating_matrix` → `CsatMatrixScale`
-- [ ] `slider_matrix` → `SliderMatrixScale`
-- [ ] `file_upload` → `FileUploadScale`
-- [ ] `text_and_media` → inline media (no scale)
-- [ ] `dangerouslySetInnerHTML` for `question.text` / `description`
+Exhaustive switch — check each (**11** `QUESTION_TYPE` literals):
+
+- [ ] `NPS_SCALE` → `RatingScale`
+- [ ] `MCQ` → inline MCQ
+- [ ] `TEXTFIELD` → inline textarea/input
+- [ ] `CFM_MATRIX` → `LikertMatrixScale`
+- [ ] `CSAT_MATRIX`, `RATING_MATRIX` → `CsatMatrixScale`
+- [ ] `SLIDER_MATRIX` → `SliderMatrixScale`
+- [ ] `FILE_UPLOAD` → `FileUploadScale`
+- [ ] `TEXT_AND_MEDIA` → inline media (no scale)
+- [ ] `HEATMAP` → `HeatmapScale`
+- [ ] `RANK_ORDER` → `RankOrderScale`
+- [ ] `allAnswers` + `allQuestions` passed for placeholder resolution
+- [ ] `customFieldValues` passed from SurveyPage when survey uses custom-field or answer logic on CRM data
+- [ ] Answer logic: `getVisibleMcqOptionsForAnswers` / `getVisibleMatrixItemsForAnswers` with `customFieldValues` 4th arg
+- [ ] `dangerouslySetInnerHTML` for `question.questionText` / `questionDescription`
 - [ ] `validationError` banner per question
 - [ ] `id={question.id}` on every question wrapper
+- [ ] Copied from `docs/templates/Question.tsx` — no stub/default fallback branches
 
-## 4. Component Architecture Checklist
+## 3a. Value Derivation (client-side)
 
-| Component | In survey? | Blueprint doc | Key constraints verified |
-|-----------|------------|---------------|--------------------------|
-| RatingScale | | `01-components/03-rating-scale.md` | |
-| CsatScale | | `01-components/04-csat-scale.md` | |
-| CsatMatrixScale | | `01-components/05-csat-matrix-scale.md` | |
-| LikertMatrixScale | | `01-components/06-likert-matrix-scale.md` | |
-| SliderMatrixScale | | `01-components/07-slider-matrix-scale.md` | |
-| FileUploadScale | | `01-components/08-file-upload-scale.md` | |
-| CustomSliderTrack | | `01-components/09-custom-slider-track.md` | |
-| Header / Footer | | `01-components/10-header-footer.md` | |
-| ProgressBar | | `01-components/11-progress-bar.md` | |
-| LanguageSelector | | `01-components/12-language-selector.md` | |
-| MatrixDropdown | | `01-components/13-matrix-dropdown.md` | |
+Read `02-reference/value-derivation.md`:
 
-## 4b. Per-Question Config & UI Coverage
+- [ ] Import `matrixColumnStoredValue` from SDK for matrix cells
+- [ ] Matrix keys = `statementRows[].id`; values = column **`id`** or `null`
+- [ ] NPS: derive numeric value from `optionLabel` or index
+- [ ] MCQ: store `option.id`
+
+## 3b. Required Component Files (from fetched survey)
+
+Fill from `00-integration/component-checklist.md`:
+
+| Component file | Required if survey contains | Created? |
+|----------------|----------------------------|----------|
+| `IntroPage.tsx` | intro page | |
+| `EndPage.tsx` | end pages | |
+| `PausedPage.tsx` | paused flag | |
+| `LikertMatrixScale.tsx` | `CFM_MATRIX` | |
+| `CsatMatrixScale.tsx` | `CSAT_MATRIX` or `RATING_MATRIX` | |
+| `SliderMatrixScale.tsx` | `SLIDER_MATRIX` | **blocking** |
+| `FileUploadScale.tsx` | `FILE_UPLOAD` | **blocking** |
+| `MatrixDropdown.tsx` | matrix dropdown/selectbox | |
+| `CustomSliderTrack.tsx` | `SLIDER_MATRIX` or matrix graphics | |
+| `RatingScale.tsx` | `NPS_SCALE` | |
+| `HeatmapScale.tsx` | `HEATMAP` | |
+| `RankOrderScale.tsx` | `RANK_ORDER` | |
+| `lib/heatmapCoords.ts` | `HEATMAP` | copy from `templates/heatmapCoords.ts` |
+
+## 3c. Logic inventory (from fetched survey)
+
+Scan `survey.pages` for logic flags. Fill after fetch:
 
-Fill one row per question in the fetched survey:
+| questionId | skipLogics | displayLogic | answerLogic (options/rows/cols) | customField refs (`_c_…`) |
+|------------|------------|--------------|----------------------------------|---------------------------|
+| | | | | |
 
-| questionId | type | subType | configs detected | uiSpec read | ref component | branches implemented |
-|------------|------|---------|------------------|-------------|---------------|---------------------|
-| | | | | | | |
+Custom field ids found → populate `CUSTOM_FIELD_VALUES` map. See `00-integration/custom-field-logic-and-navigation.md`.
+
+## 3d. Per-Type SDK Integration (from fetched survey)
+
+Fill from `00-integration/question-type-sdk-matrix.md`:
+
+| questionId | type | answer shape | visibility helper | customField refs | component files |
+|------------|------|--------------|-------------------|------------------|-----------------|
+| | | | | | |
+
+## 4. Component Architecture Checklist
+
+| Component | In survey? | Blueprint doc |
+|-----------|------------|---------------|
+| IntroPage / EndPage / PausedPage | | `14` / `15` / `16` |
+| RatingScale | | `03-rating-scale.md` |
+| CsatMatrixScale | | `05-csat-matrix-scale.md` |
+| LikertMatrixScale | | `06-likert-matrix-scale.md` |
+| SliderMatrixScale | | `07-slider-matrix-scale.md` |
+| FileUploadScale | | `08-file-upload-scale.md` |
+| Header / Footer / ProgressBar / LanguageSelector | | `10`–`12` |
+
+## 4b. Per-Question Config & UI Coverage
 
-- **configs detected:** non-default fields from `02-reference/config-field-index.md` (e.g. `matrixFormat: carousel`, `buttonType: emoji`)
-- **uiSpec read:** path from `MANIFEST.json` `uiSpecs` (matrix: use `matrix_{subType}`)
-- **ref component:** `apps/client/src/components/{Component}.tsx`
-- **branches implemented:** list decision-tree branches from the ui-spec (e.g. dropdown vs grid vs carousel)
+| questionId | type | configs detected | uiSpec read | component files | branches implemented |
+|------------|------|------------------|-------------|-----------------|---------------------|
+| | | | | | |
 
 ## 5. Theme, Brand & Logo
 
 - [ ] CSS-only logo (no `<img>`, no `public/` uploads)
 - [ ] Primary / hover colors from client prompt
-- [ ] Header / Footer / ProgressBar / LanguageSelector per layout
 
 ## 6. Submit & Thank You
 
-- [ ] `onAction({ type: 'SUBMIT' })` on final page
-- [ ] Thank-you screen when `submitSurveyResults.data` is set
-- [ ] Custom thank-you message from client prompt if provided
+- [ ] `onAction({ type: 'NEXT' })` when `primaryButtonType === 'submit'`
+- [ ] End UI when `state.phase.kind === 'end'` with `EndPage`
 
 ## 7. Pre-Build Verification
 
 - [ ] No imports from `.../src/` internal paths
-- [ ] All mutations via `onAction` — no direct state mutation
-- [ ] `npm run build` passes
+- [ ] All mutations via `onAction`
+- [ ] Stable `customFieldValues` ref; passed to hook and Question visibility helpers
+- [ ] `bash templates/verify-agent-build.sh` passes
+- [ ] `grep -r "not yet implemented"` → zero matches
+
+## 8. AWS Deploy Readiness (fill if client prompt mentions AWS / CloudFront / S3 / EC2 / Sprinklr)
+
+- [ ] Next.js `output: "export"` + `assetPrefix: "./"` configured (see `setup.md#nextjs-aws-static-export`)
+- [ ] `images.unoptimized: true` in `next.config.js`
+- [ ] Build produces `out/index.html` (+ `index.html.txt` copy step in build script)
+- [ ] `SURVEY_INSTANCE_ID` matches deploy JWT (`CFM_INSTANCE_ID`)
+- [ ] Logo/media paths are relative (no leading `/`)
+- [ ] Rank-order uses `option.imageUrl` before `option.previewImageUrl`
+- [ ] `CFM_DEPLOY_API_BASE=http://43.204.26.213:3000` noted in plan
+- [ ] Static file count ≤ 500 (`find out -type f | wc -l`)

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

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://cfm-survey-sdk/templates/survey-inventory.schema.json",
+  "title": "Survey Question Inventory",
+  "description": "Post-fetch inventory agents fill before Phase 5 BUILD",
+  "type": "object",
+  "required": ["questions", "uniqueTypes"],
+  "properties": {
+    "instanceId": { "type": "string", "description": "JWT used to fetch survey" },
+    "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"
+        ]
+      },
+      "uniqueItems": true
+    },
+    "questions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "type", "uiSpecRead", "implemented"],
+        "properties": {
+          "id": { "type": "string" },
+          "type": {
+            "type": "string",
+            "enum": [
+              "nps",
+              "mcq",
+              "text_input",
+              "csat",
+              "star_rating",
+              "slider",
+              "cfm_matrix",
+              "rating_matrix",
+              "slider_matrix",
+              "file_upload",
+              "text_and_media"
+            ]
+          },
+          "configFlags": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Non-default config, e.g. gridLayout:carousel"
+          },
+          "uiSpecRead": { "type": "string" },
+          "componentFiles": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "branchesImplemented": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "implemented": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Agent build verification — run from project root after Phase 5 BUILD
+set -euo pipefail
+
+echo "=== CFM Survey SDK — Agent Build Verification ==="
+
+STUB_MATCHES=$(grep -r "not yet implemented" src/ components/ app/ 2>/dev/null || true)
+if [ -n "$STUB_MATCHES" ]; then
+  echo "FAIL: Stub placeholder text found:"
+  echo "$STUB_MATCHES"
+  exit 1
+fi
+echo "OK: No stub placeholder text"
+
+INTERNAL_IMPORTS=$(grep -rE "@explorer02/cfm-survey-sdk/src|@repo/sdk/src" src/ components/ app/ 2>/dev/null || true)
+if [ -n "$INTERNAL_IMPORTS" ]; then
+  echo "FAIL: Internal SDK imports found:"
+  echo "$INTERNAL_IMPORTS"
+  exit 1
+fi
+echo "OK: No internal SDK imports"
+
+REQUIRED_TYPES=(MCQ TEXTFIELD NPS_SCALE CFM_MATRIX CSAT_MATRIX RATING_MATRIX SLIDER_MATRIX FILE_UPLOAD TEXT_AND_MEDIA HEATMAP RANK_ORDER)
+QUESTION_FILE=""
+for candidate in src/components/Question.tsx components/Question.tsx app/components/Question.tsx; do
+  if [ -f "$candidate" ]; then
+    QUESTION_FILE="$candidate"
+    break
+  fi
+done
+
+if [ -z "$QUESTION_FILE" ]; then
+  echo "WARN: Question.tsx not found in expected paths — skip type coverage check"
+else
+  echo "Checking dispatcher types in $QUESTION_FILE"
+  for t in "${REQUIRED_TYPES[@]}"; do
+    if ! grep -q "QUESTION_TYPE.${t}" "$QUESTION_FILE" && \
+       ! grep -q "type === '${t}'" "$QUESTION_FILE" && \
+       ! grep -q "type === \"${t}\"" "$QUESTION_FILE"; then
+      echo "FAIL: Missing dispatcher branch for type: ${t}"
+      exit 1
+    fi
+  done
+  if grep -q "subType" "$QUESTION_FILE"; then
+    echo "FAIL: Legacy subType routing found in Question.tsx — use flat question.type literals"
+    exit 1
+  fi
+  echo "OK: All 11 question.type branches present"
+fi
+
+echo "Running npm run build..."
+npm run build
+echo "=== All checks passed ==="

package/templates/docs/01-components/04-csat-scale.md

@@ -1,40 +0,0 @@
-# CSAT & Rating Architectural Blueprints
-
-> **UI spec (authoritative):** `03-ui-specs/04-csat.md`
-> **Reference implementation:** `apps/client/src/components/CsatScale.tsx`
-> **Target Components**: `CsatScale`
-> **Handles**: `type: 'csat'`, `'rating'`, `'rating_scale'`, CSAT matrices.
-
-## Core Responsibility
-Render sentiment arrays (Faces, Stars, Numbers) ensuring that active selections are unmistakably highlighted using bounding boxes or strong border accents, NEVER just by changing the SVG fill color.
-
-## State Management & Mapping
-- **Emojis**: `buttonType === 'emoji'`
-  - Map values using `getEmojiForIndex(index, totalLength)` from your icons utility.
-- **Stars**: `buttonType === 'star'`
-  - Active stars (index <= selectedValue) get `CsatStarIcons.filled`.
-- **Numbers**: Default for rating scales.
-  - Apply `option.color` to the background if provided by the SDK (NPS tracking).
-
-## UX Bounding Box Rules (CRITICAL)
-
-The UI must exactly match the "Active Box" standard.
-
-### For Emojis & Stars:
-- **Unselected**: `inline-flex p-2 border-2 border-transparent opacity-40 hover:opacity-100 hover:scale-110 transition-all cursor-pointer`.
-- **Selected**: The specific selected icon MUST be wrapped in a prominent square box with rounded corners.
-  - **CSS**: `border-2 border-[#e20074] rounded-lg p-2 bg-pink-50 shadow-sm scale-110 opacity-100`.
-
-### For Numbered Badges (Rating):
-- **Shape**: MUST be square with rounded corners (`rounded-lg w-12 h-12`). Do not use full circles.
-- **Selected**: `border-2 border-[#e20074] opacity-100 font-bold scale-105 shadow-md`.
-- **Unselected**: `opacity-30 border-transparent`.
-
-## Bounding Boxes inside Matrices
-When emojis or stars are rendered inside `CsatMatrixScale`, the exact same bounding box logic applies. The table cell `<td>` should center the icon, and the icon wrapper `<div>` or `<button>` should toggle between `border-transparent` and `border-[#e20074]` based on the active state.
-
-## Tooltips & Label Positions
-- **Tooltips**: Every single emoji, star, and badge MUST have `title={label}` applied so the user sees the semantic text string on hover.
-- **Labels (`minLabel`, `midLabel`, `maxLabel`)**:
-  - Must be rendered absolutely below the track.
-  - `midLabel` must use inline styles to calculate its exact centered position: `style={{ left: \`\${(midLabelIndex / (options.length - 1)) * 100}%\` }}`.

package/templates/docs/02-question-types/01-rating.md

@@ -1,44 +0,0 @@
-# Rating Question (NPS 0-10)
-
-> **Type**: `'rating'` | **API Source**: `SCALE` with `SCALE_TYPE=TEN_POINT` or `NPS_SCALE`
-> **Mapper**: `ratingMapper.ts` | **Component**: `RatingScale`
-
-## TypeScript Type
-
-```typescript
-type RatingQuestion = QuestionBase & {
-  type: 'rating';
-  options: SurveyOption[];       // 0-10 with NPS traffic-light colors
-  minLabel?: string;             // Left label (e.g. "Not Likely")
-  midLabel?: string;             // Middle label (e.g. "Neutral")
-  maxLabel?: string;             // Right label (e.g. "Extremely Likely")
-  midLabelIndex?: number;        // Fractional position for mid-label CSS
-  reverseScaleOrder?: boolean;   // Render high→low
-  buttonVariant?: 'radio' | 'numbered' | 'emoji';
-};
-```
-
-## Answer Shape: `number`
-Example: `7` (the selected badge value)
-
-## NPS Traffic-Light Colors
-```
-0: #e2001a (red)     3: #f18b00 (orange)   6: #fcd900 (yellow)
-1: #e4251b           4: #f7b200            7: #9fca00 (lime)
-2: #ec610a           5: #fcd900            8: #6bb300 (green)
-                                            9: #339a00
-                                            10: #008000
-```
-
-## Mid-Label Positioning
-```typescript
-// CSS left percentage for mid-label
-const left = (midLabelIndex / (options.length - 1)) * 100;
-// For 11-point scale: midLabelIndex defaults to 7.5
-```
-
-## Rendering Guidance
-- Display as horizontal row of numbered badge buttons
-- Each badge uses `option.color` as background
-- Selected badge: emphasized border/scale, all others dimmed
-- Labels positioned: minLabel (left), midLabel (calculated %), maxLabel (right)