@explorer02/cfm-survey-sdk 0.2.0 → 0.2.2

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`

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).

package/templates/docs/03-ui-specs/00-question-shell.md

@@ -1,89 +1,33 @@
 # UI Spec: Question Shell (`Question.tsx`)
 
-> **Reference:** `apps/client/src/components/Question.tsx`
-> **SDK:** All types extend `QuestionBase` from `fetchSurvey/types/base.ts`
+> **Canonical template:** [`templates/Question.tsx`](../templates/Question.tsx) — copy this dispatcher verbatim
+> **SDK:** Each question type is standalone — see `fetchSurvey/types/*.ts`
 > **Component blueprint:** `01-components/02-question.md`
 
-## Config Inventory (QuestionBase)
+## Matrix routing (CRITICAL)
 
-| Field | Implemented | UI impact |
-|-------|-------------|-----------|
-| `id` | ✅ | `section id={question.id}` — required for scroll-to-error |
-| `text` | ✅ | Heading via `dangerouslySetInnerHTML` |
-| `description` | ✅ | Optional HTML block below title |
-| `required` | ✅ | Red `*` after title (`text-red-500`) |
-| `requiredErrorMessage` | ✅ | Shown via SDK validation in error banner |
-| `questionNumber` | ❌ | Not rendered in reference client |
-| `containerMediaUrl` | ❌ | Not rendered on generic questions |
-
-## Layout Anatomy
-
-```
-┌─ section (rounded-xl border border-gray-200 bg-white p-6 shadow-sm) ─────┐
-│  h2: question.text (HTML) + red * if required                           │
-│  [optional description HTML]                                            │
-│  ┌─ type-specific scale (see per-type specs) ─────────────────────┐   │
-│  └─────────────────────────────────────────────────────────────────┘   │
-│  [validation error banner if validationError prop]                      │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
-## Dispatcher Routing
-
-| `question.type` | Condition | Component |
-|-----------------|-----------|-----------|
-| `rating` | — | `RatingScale` + label row in Question |
-| `radio` | — | Inline card radios in Question |
-| `text` | — | Inline textarea in Question |
-| `csat` | — | `CsatScale` + min/max labels in Question |
-| `matrix` | `CSAT_MATRIX` \| `RATING_MATRIX` | `CsatMatrixScale` |
-| `matrix` | `CFM_MATRIX` | `LikertMatrixScale` |
-| `slider_matrix` | — | `SliderMatrixScale` |
-| `file_upload` | — | `FileUploadScale` |
-| `text_and_media` | `mediaUrl` present | Inline media in Question |
-| `slider` | — | ❌ Not routed — see `06-slider.md` |
-| `rating_scale` | — | ❌ Not routed — see `05-rating-scale.md` |
-
-## Label Positioning (rating)
-
-Rendered in Question before `RatingScale`:
-
-```tsx
-// midLabel CSS left:
-left: `${(midLabelIndex / (options.length - 1)) * 100}%`
-// with -translate-x-1/2 for centering
-```
+Each matrix variant has its own `question.type` — **no `subType`**:
 
-minLabel: `absolute left-0`, maxLabel: `absolute right-0`, container `relative h-6 text-xs font-semibold text-gray-500`.
+- `CFM_MATRIX` → `LikertMatrixScale`
+- `CSAT_MATRIX` | `RATING_MATRIX` → `CsatMatrixScale`
+- `SLIDER_MATRIX` → `SliderMatrixScale`
 
-## Label Positioning (csat)
+Never use a `default` fallback that shows `"not yet implemented"`.
 
-minLabel / maxLabel: `flex justify-between text-xs font-semibold text-gray-500` above `CsatScale`.
+## Shell fields (duplicated on every question type)
 
-## Validation Error Banner
-
-```tsx
-className="mt-4 rounded-[4px] border border-[#333333] bg-[#d9d9d9] py-3.5 px-4"
-// text: text-[13px] font-bold text-gray-900
-```
-
-## Props Contract
-
-```typescript
-type QuestionProps = {
-  question: SurveyQuestion;
-  selectedValue?: AnswerValue;
-  validationError?: string;
-  onSelect: (value: AnswerValue) => void;
-};
-```
-
-Wire `onSelect` → `onAction({ type: 'CHANGE', payload: { questionId, value } })`.
-
-## Agent Checklist
-
-- [ ] `id={question.id}` on outermost `<section>`
-- [ ] HTML rendering for text and description
-- [ ] Exhaustive type switch — all 12 types handled or explicitly noted as gap
-- [ ] Validation error banner below scale
-- [ ] Rating/csat endpoint labels positioned per formulas above
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `id` | ✅ | `section id={question.id}` — scroll-to-error |
+| `questionText` | ✅ | Heading via `dangerouslySetInnerHTML`; when the survey defines `displayVariants`, the SDK resolves the active variant text on `state.currentQuestions` before render |
+| `questionDescription` | ✅ | Optional HTML below title |
+| `questionHint` | ❌ | Optional hint below description |
+| `required` | ✅ | Red `*` after title |
+| `requiredErrorMessage` | ✅ | Validation error banner |
+| `questionNumber` | ✅ | Prefix before title (e.g. `3.`); SDK resolves active-path ordinals on `state.currentQuestions` (see [`question-numbering.md`](../../00-integration/question-numbering.md)) |
+| `containerMedia` | ❌ | Side media — `containerMedia?.url` etc.; not in reference client |
+
+## SDK hook
+
+- Answers: `state.answers` (not `state.values`)
+- Change action: `{ type: 'CHANGE', payload: { questionId, answerValue } }`

package/templates/docs/03-ui-specs/01-rating.md

@@ -1,17 +1,18 @@
-# UI Spec: NPS Rating (`type: 'rating'`)
+# UI Spec: NPS Rating (`type: 'NPS_SCALE'`)
 
-> **Reference:** `apps/client/src/components/RatingScale.tsx` + label row in `Question.tsx`
-> **SDK type:** `RatingQuestion` — `fetchSurvey/types/rating.ts`
+> **SDK type:** `NpsQuestion` — `fetchSurvey/types/nps.ts`
 > **Component blueprint:** `01-components/03-rating-scale.md`
+> **Value derivation:** `02-reference/value-derivation.md`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
 | `options[]` | ✅ | Badge row + radio row (dual layer) |
-| `options[].color` | ✅ | Badge background; fallback `#e20074` |
-| `options[].label` | ✅ | Displayed in badge |
-| `options[].value` | ✅ | Selection value |
+| `options[].optionLabel` | ✅ | Displayed in badge |
+| `options[].id` | ✅ | Stable option id (display only) |
+| Submit value | ✅ derived | Parse `optionLabel` as number or use index — see value-derivation |
+| Badge color | ✅ derived | Traffic-light table from numeric value |
 | `minLabel` | ✅ | Rendered in Question.tsx above scale |
 | `midLabel` | ✅ | Absolute positioned in Question.tsx |
 | `maxLabel` | ✅ | Absolute positioned in Question.tsx |
@@ -19,62 +20,19 @@
 | `reverseScaleOrder` | ❌ | Document for agents when SDK sends true |
 | `buttonVariant` | ❌ | Client always uses dual-layer radio layout |
 
-## Layout Anatomy
-
-```
-[minLabel]              [midLabel @ %]              [maxLabel]
-┌──┬──┬──┬── ... ──┬──┐  ← Row 1: colored badges (NOT clickable)
-│0 │1 │2 │3 │ ...  │10│     grid repeat(options.length), h-5 w-5 sm:h-6 w-6
-└──┴──┴──┴── ... ──┴──┘     rounded-[3px], white bold text, option.color bg
-┌──────────────────────────────────────────────┐
-│  ○  ○  ●  ○  ...  ○                          │  ← Row 2: gray track bg-[#f2f2f2]
-└──────────────────────────────────────────────┘     h-11 sm:h-12, rounded-md
-         ↑ selected cell: inner bg-[#fbe8f3]
-           radio: border-[4px] border-[#e20074] bg-white
-```
-
-## Config Decision Tree
-
-```
-rating
-└── RatingScale (always dual-layer in reference client)
-    ├── Row 1: display-only colored badges
-    └── Row 2: sr-only radio + custom circle per cell
-```
-
-If `buttonVariant === 'numbered'` (SDK gap): badges become clickable buttons instead — not in reference client.
-
-If `reverseScaleOrder`: reverse `options` array before mapping both rows.
-
-## Interactive States
-
-| State | Badge row | Track cell | Radio circle |
-|-------|-----------|------------|--------------|
-| Default | Full color | Transparent inner | `border-2 border-gray-300` |
-| Hover | — | `hover:bg-gray-200/40` | — |
-| Selected | Unchanged | `bg-[#fbe8f3]` | `border-[4px] border-[#e20074]` |
-
-## Tooltips
-
-Recommended: `title={option.label}` on each track `<label>`. Not in reference client yet.
-
 ## Answer Mutation
 
 ```typescript
-onSelect(option.value) // number
-// → onAction CHANGE { questionId, value: number }
+const value = npsValueFromOption(option, index);
+onSelect(value) // number
+// → onAction CHANGE { questionId, answerValue: number }
 ```
 
-## Accessibility
-
-- `role="radiogroup"` on wrapper
-- Native `<input type="radio" className="sr-only">` per cell
-- `name={questionId}` groups radios
+See [`02-reference/value-derivation.md`](../02-reference/value-derivation.md).
 
 ## Agent Checklist
 
+- [ ] Derive submit value and badge color in UI — types omit `optionValue` / `accentColor`
 - [ ] Two-row grid with `gridTemplateColumns: repeat(options.length, 1fr)`
-- [ ] Badges use `option.color`, not hardcoded NPS colors unless option lacks color
 - [ ] Only track row is clickable
 - [ ] min/mid/max labels in Question wrapper with midLabelIndex formula
-- [ ] Selected state: pink inner track + thick magenta radio ring