@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

package/templates/docs/templates/implementation_plan.md

@@ -12,107 +12,166 @@
 ## 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
 
+## 3a. Value Derivation (client-side)
+
+Read `02-reference/value-derivation.md`:
+
+- [ ] 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` — every file below that applies to your survey **must exist** before Phase 5:
+Fill from `00-integration/component-checklist.md`:
 
 | Component file | Required if survey contains | Created? |
 |----------------|----------------------------|----------|
-| `LikertMatrixScale.tsx` | `matrix` + `CFM_MATRIX` | |
-| `CsatMatrixScale.tsx` | `matrix` + `CSAT_MATRIX` or `RATING_MATRIX` | |
-| `SliderMatrixScale.tsx` | `slider_matrix` | **blocking** |
-| `FileUploadScale.tsx` | `file_upload` | **blocking** |
-| `MatrixDropdown.tsx` | matrix with dropdown/selectbox modes | |
-| `CustomSliderTrack.tsx` | `slider_matrix` or CSAT matrix `graphics` | |
+| `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:
+
+| questionId | skipLogics | displayLogic | answerLogic (options/rows/cols) | customField refs (`_c_…`) |
+|------------|------------|--------------|----------------------------------|---------------------------|
+| | | | | |
+
+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 | 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` | |
+| 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` |
+
+## 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
 
-Fill one row per question in the fetched survey:
+Inventory required config fields per type:
 
-| questionId | type | subType | configs detected | uiSpec read | ref component | branches implemented |
-|------------|------|---------|------------------|-------------|---------------|---------------------|
-| | | | | | | |
+| 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 |
 
-- **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:** monorepo: `apps/client/src/components/{Component}.tsx`; npm: implement from ui-spec only
-- **branches implemented:** list decision-tree branches from the ui-spec (e.g. dropdown vs grid vs carousel)
-- **blocking types:** `matrix`, `slider_matrix`, `file_upload` must show interactive UI, not placeholder text
+| 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
-
-## 7b. Stub-Free Verification
-
-Per question type in the fetched survey, confirm interactive UI renders (not grey placeholder text):
-
-| type | subType | Renders real component? | No "not yet implemented" text? |
-|------|---------|---------------------------|--------------------------------|
-| | | | |
-
-- [ ] `grep -r "not yet implemented" src/ components/ app/` returns **zero matches**
-- [ ] Matrix questions route by `subType` in `Question.tsx`
-- [ ] `slider_matrix` shows sliders; `file_upload` shows dropzone
+- [ ] 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,77 @@
+{
+  "$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" },
+    "interactionDependencies": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "npm packages e.g. @dnd-kit/core, react-icons"
+    },
+    "uniqueTypes": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "MCQ",
+          "TEXTFIELD",
+          "NPS_SCALE",
+          "CFM_MATRIX",
+          "CSAT_MATRIX",
+          "RATING_MATRIX",
+          "SLIDER_MATRIX",
+          "FILE_UPLOAD",
+          "TEXT_AND_MEDIA",
+          "HEATMAP",
+          "RANK_ORDER"
+        ]
+      },
+      "uniqueItems": true
+    },
+    "questions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "type", "uiSpecRead", "implemented"],
+        "properties": {
+          "id": { "type": "string" },
+          "type": {
+            "type": "string",
+            "enum": [
+              "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": "e.g. interactionMode:dragAndDrop, gridLayout:carousel, selectionMode:multiple, defaultOptionIds"
+          },
+          "uiSpecRead": { "type": "string" },
+          "componentFiles": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "branchesImplemented": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "implemented": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,85 @@
+#!/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"
+
+  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..."
+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)