@explorer02/cfm-survey-sdk 0.2.1 → 0.2.2

package/templates/docs/02-reference/question-types/05-rating-scale.md

@@ -1,26 +1,31 @@
-# Rating Scale Question (Stars/Emoji)
+# Star Rating Question (Stars/Emoji)
 
-> **Type**: `'rating_scale'` | **API Source**: `SCALE` with `SCALE_TYPE=STAR/EMOJI/FIVE_POINT`
-> **Mapper**: `ratingMapper.ts` (rating_scale branch) | **Component**: `RatingScale`
+> **Type**: `'star_rating'` | **API Source**: page `RATING`
+> **SDK type file**: `fetchSurvey/types/starRating.ts` | **Component**: `RatingScale`
 
 ## TypeScript Type
 
 ```typescript
-type RatingScaleQuestion = QuestionBase & {
-  type: 'rating_scale';
-  options: SurveyOption[];     // Typically 1-5 or 1-10 (no NPS colors)
+type StarRatingQuestion = {
+  type: 'star_rating';
+  id: string;
+  questionText: string;
+  options: StarRatingPoint[];
   minLabel?: string;
   midLabel?: string;
   maxLabel?: string;
   midLabelIndex?: number;
-  reverseScaleOrder?: boolean;
-  scaleStyle?: 'star' | 'emoji';
+  reverseScaleOrder: boolean;
+  scaleStyle: 'star' | 'emoji';
+  required: boolean;
+  // ... shell fields
 };
 ```
 
 ## Answer Shape: `number`
 
-## Key Difference from `'rating'`
+## Key Difference from `'nps'`
+
 - No NPS traffic-light colors on options
-- Rendered as stars, emojis, or plain icons — not numbered badges
-- Use `scaleStyle` to determine icon type
+- Rendered as stars or emojis per `scaleStyle`
+- See `03-ui-specs/05-rating-scale.md`

package/templates/docs/02-reference/question-types/06-slider.md

@@ -1,7 +1,7 @@
 # Slider Question (Single Range)
 
-> **Type**: `'slider'` | **API Source**: `SCALE` with `INPUT_TYPE=SLIDER`
-> **Mapper**: `ratingMapper.ts` (slider branch) | **Component**: `CustomSliderTrack` or native `<input type="range">`
+> **Type**: `'slider'` | **API Source**: page `SLIDER`
+> **Mapper**: `sliderMapper.ts` | **Component**: `CustomSliderTrack` or native `<input type="range">`
 
 ## TypeScript Type
 

package/templates/docs/02-reference/question-types/07-matrix-cfm.md

@@ -1,43 +1,57 @@
-# Matrix CFM Question (Likert Grid)
+# CFM Matrix Question (Likert Grid)
 
-> **Type**: `'matrix'` with `subType: 'CFM_MATRIX'` | **API Source**: `CFM_MATRIX`
-> **Mapper**: `cfmMatrixMapper.ts` | **Component**: `LikertMatrixScale`
+> **Type**: `'CFM_MATRIX'` | **API Source**: `CFM_MATRIX`
+> **SDK type file**: `fetchSurvey/types/cfmMatrix.ts` | **Component**: `LikertMatrixScale`
 
 ## TypeScript Type
 
 ```typescript
-type MatrixQuestion = QuestionBase & {
-  type: 'matrix';
-  subType: 'CFM_MATRIX';
-  rows: MatrixRow[];              // Statements to rate
-  columns: MatrixColumn[];        // Shared answer options per row
-  buttonType?: SurveyButtonType;
-  hasNotApplicable?: boolean;
-  reverseScaleOrder?: boolean;
-  labels?: string[];              // Anchor labels above columns
-  matrixFormat?: 'standard' | 'carousel' | 'dropdown';
-  matrixType?: 'likert' | 'bipolar';
-  answerType?: 'single' | 'multiple';
-  transposeTable?: boolean;
-  repeatScale?: boolean;
-  enableScale?: boolean;
+type CfmMatrixQuestion = {
+  type: 'CFM_MATRIX';
+  id: string;
+  questionText: string;
+  statementRows: CfmMatrixStatementRow[];
+  scaleColumns: CfmMatrixScaleColumn[];
+  statementLayout: 'likert' | 'bipolar';
+  selectionMode: 'single' | 'multiple';
+  gridLayout: 'standard' | 'carousel' | 'dropdown';
+  transposeTable: boolean;
+  repeatColumnHeaders: boolean;
+  hasNotApplicableOption: boolean;
+  showColumnHeaders: boolean;
+  scaleAnchorLabels?: string[];
+  required: boolean;
+  // ... shell fields
 };
 
-type MatrixRow = { id: string; text: string; rightText?: string; };
-type MatrixColumn = { id: string; label: string; value: string | number | null; color?: string; };
+type CfmMatrixStatementRow = {
+  id: string;
+  statementText: string;
+  oppositeStatementText?: string;
+};
 ```
 
-## Answer Shape: `MatrixAnswerMap`
+## Answer Shape: `MatrixRowAnswers`
+
 ```typescript
-{ "row1_id": "column_value", "row2_id": "column_value", "row3_id": null }
-// null = N/A selected for that row
+{ "row1_id": columnValue, "row2_id": null }
 ```
 
 ## Rendering Guidance
-- **Standard format**: Grid table — rows on left, columns as headers
-- **Carousel format**: Show one row at a time with prev/next
-- **Dropdown format**: Each row has a dropdown selector for its column value
-- Likert: unipolar text labels (e.g. "Strongly Disagree" → "Strongly Agree")
-- Bipolar: `row.text` on left + `row.rightText` on right
-- If `hasNotApplicable` → add N/A column with `value: null`
-- `onSelect` receives the full `MatrixAnswerMap` object on each change
+
+- **standard**: Grid table — rows on left, columns as headers
+- **carousel**: One row at a time with prev/next
+- **dropdown**: Each row has a dropdown (`MatrixDropdown`)
+- **bipolar**: `statementText` left + `oppositeStatementText` right
+- `onSelect` receives the full `MatrixRowAnswers` object on each change
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.CFM_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` — column **`id`** via `matrixColumnStoredValue`
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] Visibility helper: `getVisibleMatrixItemsForAnswers(question, answers, allQuestions, customFieldValues?)`
+- [ ] Custom fields: 4th arg on matrix visibility helper when logic references CRM fields
+- [ ] Logic features: skip ✓ display ✓ answer ✓ (rows + columns) variants ✓ numbering ✓
+- [ ] Performance: filter rows/cols before render; lazy-load large matrices
+- [ ] Matrix row: [`question-type-sdk-matrix.md#cfm_matrix`](../../00-integration/question-type-sdk-matrix.md#cfm_matrix)

package/templates/docs/02-reference/question-types/08-matrix-csat.md

@@ -1,29 +1,7 @@
-# Matrix CSAT Question (Satisfaction Grid)
+# CSAT Matrix Question (legacy reference)
 
-> **Type**: `'matrix'` with `subType: 'CSAT_MATRIX'` | **API Source**: `CSAT_MATRIX`
-> **Mapper**: `csatMatrixMapper.ts` | **Component**: `CsatMatrixScale`
+> **Deprecated alias.** CSAT matrix grids use `type: 'CSAT_MATRIX'` — see [04-csat.md](04-csat.md).
 
-## TypeScript Type
-Same as `MatrixQuestion` (see `07-matrix-cfm.md`) but with `subType: 'CSAT_MATRIX'`.
+For rating-style matrix grids use `type: 'RATING_MATRIX'` — see [09-matrix-rating.md](09-matrix-rating.md).
 
-## Key Difference from CFM_MATRIX
-- Columns represent satisfaction levels (not text labels)
-- Uses `buttonType` to determine visual: emoji faces, stars, numbered, etc.
-- Uses `getEmojiForIndex(colIndex, totalCols)` for emoji rendering per cell
-
-## Rendering by `buttonType`
-
-| `buttonType` | Cell Rendering |
-|-------------|---------------|
-| `'emoji'` | Sentiment face icons via `getEmojiForIndex` |
-| `'star'` | Star icons via `CsatStarIcons` |
-| `'numbered'` | Numeric badge buttons |
-| `'radio'` | Standard radio circles |
-| `'dropdown'` | Dropdown per row (uses `MatrixDropdown`) |
-| `'graphics'` | Emoji slider per row (uses `CustomSliderTrack`) |
-
-## Answer Shape: `MatrixAnswerMap`
-Same as CFM_MATRIX — `{ "row_id": column_value | null }`
-
-## N/A Column
-If `hasNotApplicable` is true, the last column has `value: null`. Selecting it records `null` for that row, which is a valid answer (passes validation).
+There is no `subType` field. Each matrix variant is a flat `question.type` literal.

package/templates/docs/02-reference/question-types/09-matrix-rating.md

@@ -1,28 +1,44 @@
 # Rating Matrix Question
 
-> **Type**: `'rating_matrix'` | **API Source**: `RATING_MATRIX`
-> **Mapper**: `ratingMatrixMapper.ts` → routed to `mapMatrixQuestion` | **Component**: `CsatMatrixScale`
+> **Type**: `'RATING_MATRIX'` | **API Source**: `RATING_MATRIX`
+> **Component**: `CsatMatrixScale`
 
 ## TypeScript Type
 
 ```typescript
-type RatingMatrixQuestion = QuestionBase & {
-  type: 'rating_matrix';
-  rows: MatrixRow[];
-  columns: MatrixColumn[];       // Rating columns with NPS-style colors
+type RatingMatrixQuestion = {
+  type: 'RATING_MATRIX';
+  statementRows: StatementRow[];
+  scaleColumns: ScaleColumn[];
   minLabel?: string;
   maxLabel?: string;
-  buttonType?: SurveyButtonType;
-  hasNotApplicable?: boolean;
-  reverseScaleOrder?: boolean;
-  labels?: string[];
+  displayStyle: CsatQuestion['displayStyle'];
+  gridLayout: 'standard' | 'carousel' | 'dropdown';
+  hasNotApplicableOption: boolean;
+  reverseScaleOrder: boolean;
+  scaleAnchorLabels?: string[];
+  // + shell fields (id, questionText, required, containerMedia?, etc.)
 };
 ```
 
 ## Key Difference from CSAT_MATRIX
-- Columns carry traffic-light `color` values (like NPS rating)
+
 - Has `minLabel`/`maxLabel` endpoint labels
+- Column badge colors derived client-side via `columnAccentColor(col)` — see `02-reference/value-derivation.md`
 - Rendered by the same `CsatMatrixScale` component
 
-## Answer Shape: `MatrixAnswerMap`
-Same pattern: `{ "row_id": column_value | null }`
+## Answer Shape: `MatrixRowAnswers`
+
+`Record<statementRows[].id, matrixColumnStoredValue(col) | null>` — stored value is always the column **`id`**; submit maps id → label/number via `resolveSubmitValues`.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.RATING_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` — column **`id`** via `matrixColumnStoredValue`
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] Visibility helper: `getVisibleMatrixItemsForAnswers(question, answers, allQuestions, customFieldValues?)`
+- [ ] Custom fields: 4th arg on matrix visibility helper when logic references CRM fields
+- [ ] Logic features: skip ✓ display ✓ answer ✓ (rows; column logic may be limited) variants ✓ numbering ✓
+- [ ] Performance: reuse `CsatMatrixScale`; render only visible rows/cols
+- [ ] Known limitation: column-level answer logic gap — verify fetched survey rules
+- [ ] Matrix row: [`question-type-sdk-matrix.md#rating_matrix`](../../00-integration/question-type-sdk-matrix.md#rating_matrix)

package/templates/docs/02-reference/question-types/10-slider-matrix.md

@@ -1,13 +1,13 @@
 # Slider Matrix Question
 
-> **Type**: `'slider_matrix'` | **API Source**: `SLIDER_MATRIX`
+> **Type**: `'SLIDER_MATRIX'` | **API Source**: `SLIDER_MATRIX`
 > **Mapper**: `sliderMatrixMapper.ts` | **Component**: `SliderMatrixScale`
 
 ## TypeScript Type
 
 ```typescript
 type SliderMatrixQuestion = QuestionBase & {
-  type: 'slider_matrix';
+  type: 'SLIDER_MATRIX';
   rows: SliderMatrixRow[];       // Each row has independent slider config
   labels?: string[];             // Anchor labels above track
   ticks?: number;                // Number of tick marks (default 10)
@@ -25,7 +25,7 @@ type SliderMatrixRow = MatrixRow & {
 type TickValue = { value: number; label: string; color: string; };
 ```
 
-## Answer Shape: `MatrixAnswerMap`
+## Answer Shape: `MatrixRowAnswers`
 ```typescript
 { "row1_id": 75, "row2_id": 30, "row3_id": null }
 // number = slider position, null = N/A
@@ -37,4 +37,15 @@ type TickValue = { value: number; label: string; color: string; };
 - If `tickValues` available → render tick marks with labels and colors
 - If `enableInputBox` → show numeric input alongside slider
 - If `enableNotApplicable` → add N/A checkbox per row
-- `onSelect` receives the full `MatrixAnswerMap` with all row values
+- `onSelect` receives the full `MatrixRowAnswers` with all row values
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.SLIDER_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` — numeric slider value or `null` for N/A per row
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] Visibility helper: `getVisibleStatementRowsForAnswers(question, answers, allQuestions, customFieldValues?)`
+- [ ] Custom fields: 4th arg on statement-row helper when logic references CRM fields
+- [ ] Logic features: skip ✓ display ✓ answer ✓ (rows) variants ✓ numbering ✓
+- [ ] Performance: debounce drag events if partial save enabled; one slider per visible row
+- [ ] Matrix row: [`question-type-sdk-matrix.md#slider_matrix`](../../00-integration/question-type-sdk-matrix.md#slider_matrix)

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

@@ -1,13 +1,13 @@
 # File Upload Question
 
-> **Type**: `'file_upload'` | **API Source**: `FILE_UPLOAD`
+> **Type**: `'FILE_UPLOAD'` | **API Source**: `FILE_UPLOAD`
 > **Mapper**: `fileUploadMapper.ts` | **Component**: `FileUploadScale`
 
 ## TypeScript Type
 
 ```typescript
 type FileUploadQuestion = QuestionBase & {
-  type: 'file_upload';
+  type: 'FILE_UPLOAD';
   uploadMessage?: string;              // Instruction text (HTML)
   supportedFileFormats?: string[];     // ['PDF', 'PNG', 'DOCX'] (uppercase, no dots)
   maxFileCount?: number;               // Max files allowed
@@ -32,3 +32,14 @@ Array of uploaded file descriptors. Submitted via `quesIdVsAttachmentDetails` (N
 - Show file list with name, size, and remove button
 - Enforce `fileSizeLimit` with appropriate error messages
 - `onSelect` receives the full `UploadedFile[]` array
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.FILE_UPLOAD`
+- [ ] Answer stored as: `UploadedFile[]`
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: UploadedFile[] }` after upload completes
+- [ ] Visibility helper: N/A
+- [ ] Custom fields: skip/display rules only — no visibility helper
+- [ ] Logic features: skip ✓ display ✓ answer ✗ variants ✓ numbering ✓
+- [ ] Performance: upload to presigned URL before CHANGE; show progress UI
+- [ ] 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,110 @@
 # 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`
+
+### SDK Integration Checklist (agent)
 
-- **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**
+- [ ] Type literal: `QUESTION_TYPE.MCQ`
+- [ ] Answer stored as: `option.id` (string/number) or array when multi-select
+- [ ] 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)
 
-## text {#text}
+## TEXTFIELD {#textfield}
 
-- **Type:** `TextQuestion` — `type: 'text'`
+- **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:** `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 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
+
+### 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`