@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

package/templates/docs/02-reference/question-types/11-file-upload.md

@@ -1,34 +1,60 @@
 # File Upload Question
 
-> **Type**: `'file_upload'` | **API Source**: `FILE_UPLOAD`
+> **Type**: `'FILE_UPLOAD'` | **API Source**: `FILE_UPLOAD`
 > **Mapper**: `fileUploadMapper.ts` | **Component**: `FileUploadScale`
+> **Upload flow**: [`00-integration/file-upload-aws.md`](../../00-integration/file-upload-aws.md)
 
 ## TypeScript Type
 
 ```typescript
 type FileUploadQuestion = QuestionBase & {
-  type: 'file_upload';
-  uploadMessage?: string;              // Instruction text (HTML)
-  supportedFileFormats?: string[];     // ['PDF', 'PNG', 'DOCX'] (uppercase, no dots)
-  maxFileCount?: number;               // Max files allowed
-  fileSizeLimit?: number;              // Max size in MB
+  type: 'FILE_UPLOAD';
+  uploadMessage?: string;
+  supportedFileFormats?: string[];
+  maxFileCount?: number;
+  fileSizeLimit?: number;
   fileSizeLimitType?: 'PER_FILE' | 'IN_TOTAL';
 };
 
-type UploadedFile = {
-  id: string; name: string; mediaUrl: string;
-  mimeType?: string; size?: number;
+/** Stored in state.answers — required for submit */
+type UploadedFileAnswer = {
+  id: string;
+  mediaUrl: string;
+  name?: string;
+  mimeType?: string;
+  size?: number;
 };
 ```
 
-## Answer Shape: `UploadedFile[]`
-Array of uploaded file descriptors. Submitted via `quesIdVsAttachmentDetails` (NOT `questionToAnswers`).
+## Answer Shape: `UploadedFileAnswer[]`
+
+Submitted via `quesIdVsAttachmentDetails` (NOT `questionToAnswers`). SDK submit formatter only accepts objects with `id` and `mediaUrl` — **raw browser `File[]` is dropped at submit**.
+
+## Two-phase client flow
+
+1. **Pick + validate locally** — extension, count, size (`PER_FILE` / `IN_TOTAL`)
+2. **Upload each file** — `POST /get-upload-url` → presigned PUT → collect `{ id, mediaUrl, name, mimeType, size }`
+3. **`onAction(CHANGE)`** — pass `UploadedFileAnswer[]` to SDK
+
+See [`file-upload-aws.md`](../../00-integration/file-upload-aws.md) for API contract.
 
 ## Rendering Guidance
-- Drag-and-drop zone + click-to-upload button
+
+- Drag-and-drop zone + click-to-upload
 - Show accepted formats from `supportedFileFormats`
-- Set `<input type="file" accept=".pdf,.png,.docx">`
-- Enforce `maxFileCount` in UI
-- Show file list with name, size, and remove button
-- Enforce `fileSizeLimit` with appropriate error messages
-- `onSelect` receives the full `UploadedFile[]` array
+- Set `<input type="file" accept=".pdf,.png,...">` from formats
+- Enforce `maxFileCount` and `fileSizeLimit` before upload
+- Show file list with name, size, remove button, uploading spinner per file
+- `onSelect(undefined)` when all files removed
+
+## Skip logic
+
+Presence-only (`EXISTS` / `MISSING`) — evaluated on page entry; no discrete value-change events required.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.FILE_UPLOAD`
+- [ ] Answer stored as: `UploadedFileAnswer[]` after upload completes
+- [ ] onAction CHANGE: `{ questionId, answerValue: UploadedFileAnswer[] }`
+- [ ] Do **not** store raw `File[]` as final answer
+- [ ] Matrix row: [`question-type-sdk-matrix.md#file_upload`](../../00-integration/question-type-sdk-matrix.md#file_upload)

package/templates/docs/02-reference/question-types/12-heatmap.md

@@ -0,0 +1,59 @@
+# Heatmap Question (`HEATMAP`)
+
+> **SDK type:** `HeatmapQuestion` in `fetchSurvey/types/heatmap.ts`
+> **UI spec:** `03-ui-specs/13-heatmap.md`
+
+## API Source
+
+- `answerType: "HEATMAP"`
+- `questionAssets[0]` → image URL
+- `surveyHeatmapMetadata` → regions, max clicks, canvas dimensions
+
+## Question Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `'HEATMAP'` | Dispatch literal |
+| `imageUrl` | `string` | Required image for click map |
+| `regions` | `HeatmapRegion[]` | Normalized 0–1 rects for logic |
+| `maxClicksAllowed` | `number` | 1–20, from `totalClickAllowed` |
+| `referenceWidth` | `number` | Canvas width used for region normalization |
+| `referenceHeight` | `number` | Canvas height used for region normalization |
+
+## Answer Shape
+
+```typescript
+type HeatmapClickPoint = { id: string; x: number; y: number };
+type HeatmapAnswer = HeatmapClickPoint[];
+```
+
+Stored in `state.answers[questionId]`. Submit serializes to:
+
+```typescript
+questionToAnswers[questionId] = [JSON.stringify(clicks)];
+```
+
+## Logic Fields
+
+| Field | Operators | Semantics |
+|-------|-----------|-----------|
+| `HEATMAP` | EXISTS / MISSING | Any click points present |
+| `HEATMAP_REGION` | CONTAINS / DOES_NOT_CONTAIN | Any listed region label has ≥1 click inside |
+
+Logic values use region **labels** (e.g. `"Region 1"`), not shape ids.
+
+## Component
+
+`HeatmapScale` — see `01-components/17-heatmap-scale.md`
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.HEATMAP`
+- [ ] Answer stored as: `HeatmapAnswer` (`HeatmapClickPoint[]`)
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: HeatmapClickPoint[] }` on click add/remove
+- [ ] Visibility helper: N/A
+- [ ] Custom fields: skip/display rules only
+- [ ] Logic features: skip ✓ display ✓ answer ✗ variants ✓ numbering ✓
+- [ ] Performance: normalize coords 0–1; copy [`templates/heatmapCoords.ts`](../../templates/heatmapCoords.ts)
+- [ ] Respect `maxClicksAllowed`; use `findSpotNearClick` for spot hit testing
+- [ ] Matrix row: [`question-type-sdk-matrix.md#heatmap`](../../00-integration/question-type-sdk-matrix.md#heatmap)

package/templates/docs/02-reference/question-types/13-rank-order.md

@@ -0,0 +1,101 @@
+# Rank Order Question (`RANK_ORDER`)
+
+> **SDK type:** `RankOrderQuestion` in `fetchSurvey/types/rankOrder.ts`
+> **UI spec:** `03-ui-specs/14-rank-order.md`
+
+## API Source
+
+- `answerType: "RANK_ORDER"`
+- `answerDetails[]` → options (text + optional `answerAsset`)
+- `questionConfigs`:
+  - `RANK_ORDER_ANSWER_TYPE` → `DROPDOWN` | `DRAG_AND_DROP`
+  - `OPTION_TYPE` → `TEXT_ONLY` | `IMAGE_ONLY` | `TEXT_AND_IMAGE`
+  - `REQUIRE_RANK_ALL` → boolean
+  - `SHUFFLE_ORDER` → boolean
+- `additionalInfo.hasOptionLevelAnswers: true` → submit uses `optionLevelAnswers`
+
+## Question Fields
+
+| Field | Type | API config |
+|-------|------|------------|
+| `type` | `'RANK_ORDER'` | `answerType` |
+| `options` | `RankOrderOption[]` | `answerDetails[]` |
+| `interactionMode` | `'dropdown' \| 'dragAndDrop'` | `RANK_ORDER_ANSWER_TYPE` |
+| `optionDisplay` | `'textOnly' \| 'imageOnly' \| 'textAndImage'` | `OPTION_TYPE` |
+| `requireRankAll` | `boolean` | `REQUIRE_RANK_ALL` |
+| `shuffleOptions` | `boolean` | `SHUFFLE_ORDER` |
+
+### RankOrderOption
+
+| Field | Source |
+|-------|--------|
+| `id` | `answerDetails[].id` |
+| `optionLabel` | `answerDetails[].answerText` |
+| `imageUrl` | `answerAsset.source` |
+| `previewImageUrl` | `answerAsset.previewImageUrl` |
+| `answerLogic` | option `controlConfig.displayLogic` |
+
+## Answer Shape
+
+```typescript
+/** optionId → 1-based rank. Partial map allowed when requireRankAll is false. */
+type RankOrderAnswers = Record<string, number>;
+```
+
+Stored in `state.answers[questionId]`.
+
+## Submit Shape
+
+Both fields are populated for rank-order questions:
+
+```typescript
+// Ordered option ids from rank 1 → N
+questionToAnswers[questionId] = ['optionIdRank1', 'optionIdRank2', ...];
+
+// Per-option rank (API key uses -:- separator)
+optionLevelAnswers[`${questionId}-:-${optionId}`] = [String(rank)];
+```
+
+## Logic Field: `RANK_ORDER`
+
+Conditions target a **specific option** via `details.subConditionEntity` (`entityType: 'OPTION'`).
+
+| UI label | API operator | Values | Semantics |
+|----------|--------------|--------|-----------|
+| Ranked as | `EQUALS` | rank number | Subject option rank equals value |
+| Ranked more than | `GT` | rank number | Subject rank > value |
+| Ranked less than | `LT` | rank number | Subject rank < value |
+| Ranked above | `BEFORE` | reference option id | Subject rank < reference rank |
+| Ranked below | `AFTER` | reference option id | Subject rank > reference rank |
+
+Also supports `EXISTS` / `MISSING` for the whole question answer.
+
+Works in skip, display, answer, question variant, and end-page logic via the shared `evaluateCondition` pipeline.
+
+## SDK Helpers (client-safe)
+
+```typescript
+import {
+  assignRankWithoutDuplicates,
+  buildRankOrderFromOrderedOptionIds,
+  getOrderedOptionIdsFromRanks,
+  getVisibleRankOrderOptionsForAnswers,
+  normalizeRankOrderAnswers,
+} from '@explorer02/cfm-survey-sdk';
+```
+
+## Component
+
+`RankOrderScale` — see `01-components/18-rank-order-scale.md`
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.RANK_ORDER`
+- [ ] Answer stored as: `RankOrderAnswers` (`Record<optionId, rank>`)
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: RankOrderAnswers }` after reorder
+- [ ] Visibility helper: `getVisibleRankOrderOptionsForAnswers(question, answers, allQuestions, customFieldValues?)`
+- [ ] Custom fields: 4th arg on rank visibility helper when logic references CRM fields
+- [ ] Logic features: skip ✓ display ✓ answer ✓ (options) variants ✓ numbering ✓
+- [ ] Performance: prefer `option.imageUrl` over `previewImageUrl`; install `@dnd-kit/*` for drag mode
+- [ ] Value utils: `assignRankWithoutDuplicates`, `buildRankOrderFromOrderedOptionIds`, `getOrderedOptionIdsFromRanks`, `normalizeRankOrderAnswers`
+- [ ] Matrix row: [`question-type-sdk-matrix.md#rank_order`](../../00-integration/question-type-sdk-matrix.md#rank_order)

package/templates/docs/02-reference/question-types/README.md

@@ -1,71 +1,120 @@
 # Question Types Reference
 
 > Read **on demand** — only for types present in the fetched survey.
-> UI implementation: `01-components/`. Routing table: `02-reference/routing-table.md`.
 
-## Discriminated Union
+## Discriminated Union (11 types)
 
 ```typescript
 type SurveyQuestion =
-  | RatingQuestion        // 'rating'
-  | RadioQuestion         // 'radio'
-  | TextQuestion          // 'text'
-  | CsatQuestion          // 'csat'
-  | RatingScaleQuestion   // 'rating_scale'
-  | SliderQuestion        // 'slider'
-  | MatrixQuestion        // 'matrix' (check subType)
-  | RatingMatrixQuestion  // 'rating_matrix'
-  | SliderMatrixQuestion  // 'slider_matrix'
-  | FileUploadQuestion    // 'file_upload'
-  | TextAndMediaQuestion; // 'text_and_media'
+  | McqQuestion           // 'MCQ'
+  | NpsQuestion           // 'NPS_SCALE'
+  | TextInputQuestion     // 'TEXTFIELD'
+  | CsatQuestion          // 'CSAT_MATRIX'
+  | CfmMatrixQuestion     // 'CFM_MATRIX'
+  | RatingMatrixQuestion  // 'RATING_MATRIX'
+  | SliderMatrixQuestion  // 'SLIDER_MATRIX'
+  | FileUploadQuestion    // 'FILE_UPLOAD'
+  | TextAndMediaQuestion  // 'TEXT_AND_MEDIA'
+  | HeatmapQuestion       // 'HEATMAP'
+  | RankOrderQuestion;    // 'RANK_ORDER'
 ```
 
-## Shared `QuestionBase` Properties
+Use `QUESTION_TYPE` from the SDK for dispatch comparisons.
 
-| Property | Type | Notes |
-|----------|------|-------|
-| `id` | `string` | **MUST** be DOM `id` on wrapper |
-| `text` | `string` | HTML — use `dangerouslySetInnerHTML` |
-| `description` | `string?` | HTML |
-| `required` | `boolean?` | |
-| `requiredErrorMessage` | `string?` | Custom validation message |
-| `questionNumber` | `number?` | 1-indexed |
+Each type is **standalone** — open its file in exported SDK types for the complete field list.
+
+> **Legacy:** `StarRatingQuestion` / `SliderQuestion` mapper types are not in the `SurveyQuestion` union. API RATING/SLIDER pages map into `NPS_SCALE`, matrix display styles, or `SLIDER_MATRIX`.
+
+## Shared field names (duplicated per type file)
+
+| Property | Meaning |
+|----------|---------|
+| `id` | DOM `id` on wrapper |
+| `questionText` | Main prompt (HTML) |
+| `questionDescription?` | Supplementary HTML |
+| `questionHint?` | Hint text |
+| `required` | Mandatory flag |
+| `requiredErrorMessage?` | Custom validation message |
+| `questionNumber?` | 1-indexed position |
+| `skipLogics?` | Forward skip rules evaluated on page leave |
+| `displayLogic?` | Question-level show/hide (dynamic or page-level) |
+| `displayVariants?` | Alternate `questionText` prompts selected by condition (SDK resolves on `currentQuestions`; see [`question-display-variants.md`](../../00-integration/question-display-variants.md)) |
+| `answerLogic?` | On `McqOption`, `StatementRow`, or `ScaleColumn` — sub-entity show/hide (see [`answer-logic-and-navigation.md`](../../00-integration/answer-logic-and-navigation.md)) |
 
 ---
 
-## radio {#radio}
+## MCQ {#mcq}
+
+- **Type:** `McqQuestion` — `type: 'MCQ'`
+- **Answer:** `string` or `string[]` (`option.id` values)
+- **Options:** `McqOption[]` with `id`, `optionLabel`
+
+| Field | Type | API source |
+|-------|------|------------|
+| `selectionMode` | `'single' \| 'multiple'` | multi-select config |
+| `defaultOptionIds?` | `string[]` | `DEFAULT_ANSWER` when enabled |
+| `minSelections?` | `number` | `ANSWER_CONDITION` / `MIN_ANSWER` |
+| `maxSelections?` | `number` | `ANSWER_CONDITION` / `MAX_ANSWER` |
+| `answerConditionErrorMessage?` | `string` | `ANSWER_CONDITION` error message |
+
+**Default answers:** On survey load, SDK `buildInitialAnswers` / `applyMcqDefaults` pre-populates `state.answers[questionId]` from `defaultOptionIds` (single: first id; multi: full array). Client binds UI checked state to `state.answers` — do not maintain separate default state. SDK re-applies defaults on validation/submit if answer is still empty.
 
-- **Type:** `RadioQuestion` — `type: 'radio'`
-- **Answer:** `string | number` (option id or value)
-- **UI:** Inline MCQ radio cards in `Question.tsx` — see `01-components/02-question.md`
-- **No separate reference doc needed**
+### SDK Integration Checklist (agent)
 
-## text {#text}
+- [ ] Type literal: `QUESTION_TYPE.MCQ`
+- [ ] Answer stored as: `option.id` (string/number) or array when `selectionMode === 'multiple'`
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: optionId | optionId[] }`
+- [ ] Visibility helper: `getVisibleMcqOptionsForAnswers(question, answers, allQuestions, customFieldValues?)`
+- [ ] Custom fields: 4th arg when logic references CRM fields
+- [ ] Logic features: skip ✓ display ✓ answer ✓ (options) variants ✓ numbering ✓
+- [ ] Performance: filter options via helper before render
+- [ ] Matrix row: [`question-type-sdk-matrix.md#mcq`](../../00-integration/question-type-sdk-matrix.md#mcq)
 
-- **Type:** `TextQuestion` — `type: 'text'`
+## TEXTFIELD {#textfield}
+
+- **Type:** `TextInputQuestion` — `type: 'TEXTFIELD'`
 - **Answer:** `string`
-- **UI:** Inline `<textarea>` or `<input>` in `Question.tsx`
-- **No separate reference doc needed**
 
-## text_and_media {#text_and_media}
+### SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.TEXTFIELD`
+- [ ] Answer stored as: `string`
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: string }`
+- [ ] Visibility helper: N/A
+- [ ] Custom fields: skip/display only
+- [ ] Logic features: skip ✓ display ✓ answer ✗ variants ✓ numbering ✓
+- [ ] Performance: debounce long textarea onChange if partial save enabled
+- [ ] Matrix row: [`question-type-sdk-matrix.md#textfield`](../../00-integration/question-type-sdk-matrix.md#textfield)
+
+## TEXT_AND_MEDIA {#text_and_media}
 
-- **Type:** `TextAndMediaQuestion` — `type: 'text_and_media'`
-- **Answer:** none — display-only, skipped in validation and submission
-- **UI:** Inline `<video>` or `<img>` from `question.mediaUrl` — no scale component
-- **No separate reference doc needed**
+- **Type:** `TextAndMediaQuestion` — `type: 'TEXT_AND_MEDIA'`
+- **Answer:** none — display-only
+
+### SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.TEXT_AND_MEDIA`
+- [ ] Answer stored as: none — no CHANGE action
+- [ ] onAction: user advances with NEXT only
+- [ ] Visibility helper: N/A
+- [ ] Custom fields: skip/display only
+- [ ] Logic features: skip ✓ display ✓ answer ✗ variants ✓ numbering ✓
+- [ ] Performance: lazy-load media; respect `media.alignment`
+- [ ] Matrix row: [`question-type-sdk-matrix.md#text_and_media`](../../00-integration/question-type-sdk-matrix.md#text_and_media)
 
 ---
 
 ## Detailed Reference Docs
 
-| File | Type | When to read |
-|------|------|--------------|
-| `01-rating.md` | `rating` | NPS / numeric scales |
-| `04-csat.md` | `csat` | CSAT emoji/star (≤5 options) |
-| `05-rating-scale.md` | `rating_scale` | Star/emoji rating |
-| `06-slider.md` | `slider` | Single range slider |
-| `07-matrix-cfm.md` | `matrix` + `CFM_MATRIX` | Likert text grid |
-| `08-matrix-csat.md` | `matrix` + CSAT/RATING | Satisfaction grid |
-| `09-matrix-rating.md` | `rating_matrix` | NPS-style grid |
-| `10-slider-matrix.md` | `slider_matrix` | Slider grid |
-| `11-file-upload.md` | `file_upload` | File attachments |
+| File | Type literal | When to read |
+|------|--------------|--------------|
+| `01-rating.md` | `NPS_SCALE` | NPS 0–10 scales |
+| `04-csat.md` | `CSAT_MATRIX` | CSAT matrix grid |
+| `07-matrix-cfm.md` | `CFM_MATRIX` | CFM matrix grid |
+| `09-matrix-rating.md` | `RATING_MATRIX` | NPS-style rating matrix |
+| `10-slider-matrix.md` | `SLIDER_MATRIX` | Slider grid |
+| `11-file-upload.md` | `FILE_UPLOAD` | File attachments |
+| `12-heatmap.md` | `HEATMAP` | Click-map heatmap |
+| `13-rank-order.md` | `RANK_ORDER` | Rank order options |
+
+Legacy docs (deprecated API mappings): `05-rating-scale.md`, `06-slider.md`

package/templates/docs/02-reference/routing-table.md

@@ -1,35 +1,50 @@
 # Question Type → Component Routing
 
-> Canonical mapping. For **UI implementation** (config branches, tokens, states), read `03-ui-specs/`. For wiring, read `01-components/`. For data shapes, read `02-reference/question-types/`. For field audit, read `config-field-index.md`.
-
-| `question.type` | `question.subType` | Component | Answer Shape | Reference Doc | UI Spec |
-|-----------------|-------------------|-----------|--------------|---------------|---------|
-| `'rating'` | — | `RatingScale` | `number` | `question-types/01-rating.md` | `03-ui-specs/01-rating.md` |
-| `'radio'` | — | Inline in `Question` | `string \| number` | `question-types/README.md#radio` | `03-ui-specs/02-radio.md` |
-| `'text'` | — | Inline in `Question` | `string` | `question-types/README.md#text` | `03-ui-specs/03-text.md` |
-| `'csat'` | — | `CsatScale` | `number \| null` | `question-types/04-csat.md` | `03-ui-specs/04-csat.md` |
-| `'rating_scale'` | — | `RatingScale` | `number` | `question-types/05-rating-scale.md` | `03-ui-specs/05-rating-scale.md` |
-| `'slider'` | — | `CustomSliderTrack` | `number` | `question-types/06-slider.md` | `03-ui-specs/06-slider.md` |
-| `'matrix'` | `'CFM_MATRIX'` | `LikertMatrixScale` | `MatrixAnswerMap` | `question-types/07-matrix-cfm.md` | `03-ui-specs/07-matrix-cfm.md` |
-| `'matrix'` | `'CSAT_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/08-matrix-csat.md` | `03-ui-specs/08-matrix-csat-rating.md` |
-| `'matrix'` | `'RATING_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/08-matrix-csat.md` | `03-ui-specs/08-matrix-csat-rating.md` |
-| `'rating_matrix'` | — | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/09-matrix-rating.md` | `03-ui-specs/08-matrix-csat-rating.md` |
-| `'slider_matrix'` | — | `SliderMatrixScale` | `MatrixAnswerMap` | `question-types/10-slider-matrix.md` | `03-ui-specs/09-slider-matrix.md` |
-| `'file_upload'` | — | `FileUploadScale` | `UploadedFile[]` | `question-types/11-file-upload.md` | `03-ui-specs/10-file-upload.md` |
-| `'text_and_media'` | — | Inline in `Question` | (no answer) | `question-types/README.md#text_and_media` | `03-ui-specs/11-text-and-media.md` |
+> Canonical mapping. Dispatch on `question.type` only — each matrix variant is its own type (no `subType`).
+
+| `question.type` | SDK Type | Component | Answer Shape | Reference Doc | UI Spec |
+|-----------------|----------|-----------|--------------|---------------|---------|
+| `MCQ` | `McqQuestion` | Inline in `Question` | `string \| string[]` | `question-types/README.md#mcq` | `03-ui-specs/02-radio.md` |
+| `TEXTFIELD` | `TextInputQuestion` | Inline in `Question` | `string` | `question-types/README.md#textfield` | `03-ui-specs/03-text.md` |
+| `NPS_SCALE` | `NpsQuestion` | `RatingScale` | `number` | `question-types/01-rating.md` | `03-ui-specs/01-rating.md` |
+| `CFM_MATRIX` | `CfmMatrixQuestion` | `LikertMatrixScale` | `MatrixRowAnswers` | `question-types/07-matrix-cfm.md` | `03-ui-specs/07-matrix-cfm.md` |
+| `CSAT_MATRIX` | `CsatQuestion` | `CsatMatrixScale` | `MatrixRowAnswers` | `question-types/04-csat.md` | `03-ui-specs/04-csat.md` |
+| `RATING_MATRIX` | `RatingMatrixQuestion` | `CsatMatrixScale` | `MatrixRowAnswers` | `question-types/09-matrix-rating.md` | `03-ui-specs/08-matrix-csat-rating.md` |
+| `SLIDER_MATRIX` | `SliderMatrixQuestion` | `SliderMatrixScale` | `MatrixRowAnswers` | `question-types/10-slider-matrix.md` | `03-ui-specs/09-slider-matrix.md` |
+| `FILE_UPLOAD` | `FileUploadQuestion` | `FileUploadScale` | `UploadedFileAnswer[]` | `question-types/11-file-upload.md` | `03-ui-specs/10-file-upload.md` |
+| `TEXT_AND_MEDIA` | `TextAndMediaQuestion` | Inline in `Question` | (no answer) | `question-types/README.md#text_and_media` | `03-ui-specs/11-text-and-media.md` |
+| `HEATMAP` | `HeatmapQuestion` | `HeatmapScale` | `HeatmapAnswer` | `question-types/12-heatmap.md` | `03-ui-specs/13-heatmap.md` |
+| `RANK_ORDER` | `RankOrderQuestion` | `RankOrderScale` | `RankOrderAnswers` | `question-types/13-rank-order.md` | `03-ui-specs/14-rank-order.md` |
+
+Use `QUESTION_TYPE` from the SDK for dispatch:
+
+```typescript
+import { QUESTION_TYPE } from '@explorer02/cfm-survey-sdk';
+
+{question.type === QUESTION_TYPE.NPS_SCALE && <RatingScale ... />}
+```
+
+> **Legacy note:** API RATING/SLIDER page types are mapped into `NPS_SCALE`, matrix display styles, or `SLIDER_MATRIX` — not separate `question.type` values.
+
+## SDK hook contract
+
+- Read answers from `state.answers` (`SurveyAnswers`)
+- Dispatch `{ type: 'CHANGE', payload: { questionId, answerValue } }`
+- Pass `allAnswers` and `allQuestions` to `Question` for placeholder resolution
 
 ## Component Blueprint Docs
 
 | Component | Blueprint |
 |-----------|-----------|
 | `SurveyPage` | `01-components/01-survey-page.md` |
+| `IntroPage` / `EndPage` / `PausedPage` | `01-components/14-intro-page.md`, `15-end-page.md`, `16-paused-page.md` |
 | `Question` | `01-components/02-question.md` |
 | `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` |
+| `HeatmapScale` | `01-components/17-heatmap-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` |

package/templates/docs/02-reference/value-derivation.md

@@ -0,0 +1,63 @@
+# Client-Side Value Derivation
+
+> SDK types expose **display** fields only for scale options and matrix columns. Submit values are derived at submit/partial-save time.
+
+## Matrix columns (`ScaleColumn`)
+
+**Import from SDK** (preferred):
+
+```typescript
+import { matrixColumnStoredValue } from '@explorer02/cfm-survey-sdk';
+// monorepo: import { matrixColumnStoredValue } from '@repo/sdk';
+```
+
+```typescript
+type ScaleColumn = { id: string; label: string };
+
+// matrixColumnStoredValue(column) → column.id, except N/A → null
+```
+
+- **Stored matrix answers** use `matrixColumnStoredValue(col)` → always the column **`id`** (string), except N/A → `null`
+- Matrix answers: `MatrixRowAnswers = Record<statementRowId, columnId | columnId[] | null>`
+- **Submit / partial save**: SDK `resolveSubmitValues` maps stored column ids → API label or numeric string (id-only lookup)
+- N/A column: SDK adds `{ id: 'na', label: 'N/A' }` when `hasNotApplicableOption` is true
+- Filter N/A from scale pickers: `scaleColumns.filter(col => col.id !== 'na')`
+- Slider matrix rows still store numeric slider positions (unchanged)
+
+Monorepo client mirror: `apps/client/src/lib/surveyUi/scaleValues.ts` exports the same helper for matrix UI components.
+
+## NPS / star rating options
+
+Options are `{ id: string; optionLabel: string }` — no `optionValue` on the type.
+
+```typescript
+function npsValueFromOption(option: NpsScalePoint, index: number): number {
+  const numeric = Number(option.optionLabel);
+  return Number.isFinite(numeric) && option.optionLabel.trim() !== '' ? numeric : index;
+}
+```
+
+NPS questions use `question.type === 'NPS_SCALE'`. Store a **number** in `SurveyAnswers`. Badge colors: traffic-light table keyed by numeric value (0–10).
+
+## MCQ
+
+- Selected answer: **`option.id`** (string), not a separate `optionValue` field
+
+## Rank order
+
+- Stored answer: **`RankOrderAnswers`** — `Record<optionId, rankNumber>` (1-based)
+- Dropdown: use `assignRankWithoutDuplicates(current, optionId, rank)` before `onSelect`
+- Drag-and-drop: use `buildRankOrderFromOrderedOptionIds(orderedOptionIds)` after reorder
+- Submit / partial save:
+  - `questionToAnswers[questionId]` → ordered **option id** array (rank 1 → N)
+  - `optionLevelAnswers[`${questionId}-:-${optionId}`]` → `[String(rank)]`
+- Filter visible options: `getVisibleRankOrderOptionsForAnswers(question, answers, allQuestions, customFieldValues?)`
+
+## Media
+
+- Shell side media: `question.containerMedia?.url`, `containerMedia?.mimeType`, etc.
+- Text & media block: `question.media?.url`, `question.media?.title`, etc.
+
+## Shared types (exported)
+
+`StatementRow`, `ScaleColumn`, `ContainerMedia`, `QuestionMedia`, `SurveyAnswers`, `matrixColumnStoredValue` — see [`exports.md`](exports.md).