@explorer02/cfm-survey-sdk 0.2.1 → 0.2.2

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,102 +1,33 @@
 # UI Spec: Question Shell (`Question.tsx`)
 
 > **Canonical template:** [`templates/Question.tsx`](../templates/Question.tsx) — copy this dispatcher verbatim
-> **Monorepo reference:** `apps/client/src/components/Question.tsx` (not available in npm installs — implement from this spec)
-> **SDK:** All types extend `QuestionBase` from `fetchSurvey/types/base.ts`
+> **SDK:** Each question type is standalone — see `fetchSurvey/types/*.ts`
 > **Component blueprint:** `01-components/02-question.md`
-> **Required files:** `00-integration/component-checklist.md`
 
-## Matrix subType Warning (CRITICAL)
+## Matrix routing (CRITICAL)
 
-Routing on `question.type === 'matrix'` **alone renders nothing**. You MUST branch on `subType`:
+Each matrix variant has its own `question.type` — **no `subType`**:
 
 - `CFM_MATRIX` → `LikertMatrixScale`
 - `CSAT_MATRIX` | `RATING_MATRIX` → `CsatMatrixScale`
+- `SLIDER_MATRIX` → `SliderMatrixScale`
 
-Never use a `default` fallback that shows `"not yet implemented"` — create the scale components listed in the checklist.
+Never use a `default` fallback that shows `"not yet implemented"`.
 
-## Config Inventory (QuestionBase)
+## Shell fields (duplicated on every question type)
 
 | 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
-```
-
-minLabel: `absolute left-0`, maxLabel: `absolute right-0`, container `relative h-6 text-xs font-semibold text-gray-500`.
-
-## Label Positioning (csat)
-
-minLabel / maxLabel: `flex justify-between text-xs font-semibold text-gray-500` above `CsatScale`.
-
-## 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
-- [ ] Copied from `templates/Question.tsx` — no stub/default fallback branches
-- [ ] Matrix routes by `subType`, not type alone
-- [ ] `slider_matrix` → `SliderMatrixScale`; `file_upload` → `FileUploadScale`
-- [ ] Validation error banner below scale
-- [ ] Rating/csat endpoint labels positioned per formulas above
+| `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

package/templates/docs/03-ui-specs/02-radio.md

@@ -1,7 +1,6 @@
-# UI Spec: Radio MCQ (`type: 'radio'`)
+# UI Spec: MCQ (`type: 'MCQ'`)
 
-> **Reference:** `apps/client/src/components/Question.tsx` (inline)
-> **SDK type:** `RadioQuestion` — `fetchSurvey/types/radio.ts`
+> **SDK type:** `McqQuestion` — `fetchSurvey/types/mcq.ts`
 > **Component blueprint:** `01-components/02-question.md`
 
 ## Config Inventory
@@ -9,43 +8,26 @@
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
 | `options[]` | ✅ | One card per option |
-| `options[].label` | ✅ | HTML via `dangerouslySetInnerHTML` |
-| `options[].value` | ✅ | Selection value; `null` → empty string on input |
-| `isMultiSelect` | ❌ | SDK supports; client is single-select only |
+| `options[].optionLabel` | ✅ | HTML via `dangerouslySetInnerHTML` |
+| `options[].id` | ✅ | **Submit value** — selected answer is `option.id` |
+| `isMultiSelect` | ⚠️ | SDK supports multi-select; implement checkbox cards when `true` |
 
-## Layout Anatomy
+## Multi-select note
 
-```
-┌─ label (full-width card) ─────────────────────────────────────┐
-│  (●)  Option label HTML                                      │  selected
-└───────────────────────────────────────────────────────────────┘
-┌─ label ───────────────────────────────────────────────────────┐
-│  (○)  Option label HTML                                      │  unselected
-└───────────────────────────────────────────────────────────────┘
-```
+When `question.isMultiSelect === true`:
 
-## Interactive States
+- Answer shape is `string[]` (or `number[]`) of selected `option.id` values
+- Toggle options on click; do not replace the entire array with a single id
+- onAction CHANGE: `{ questionId, answerValue: selectedIds[] }`
+- Still filter via `getVisibleMcqOptionsForAnswers` before render
 
-| State | Border | Background | Radio |
-|-------|--------|------------|-------|
-| Unselected | `#e5e5e5` | `white` | `border-gray-400`, empty |
-| Unselected hover | `#e5e5e5` | `hover:bg-gray-50/50` | — |
-| Selected | `#e20074` | `#fdf2f8` | `border-2 border-[#e20074]` + inner dot `h-2.5 w-2.5 bg-[#e20074]` |
-
-## Structure
-
-```tsx
-<label className="flex items-center gap-4 rounded-lg border py-4 px-5 cursor-pointer">
-  <input type="radio" name={question.id} className="sr-only" />
-  <div className="h-5 w-5 rounded-full border ..."> {/* custom radio */} </div>
-  <span dangerouslySetInnerHTML={{ __html: option.label }} />
-</label>
-```
+When `false` (default), single-select radio behavior applies.
 
 ## Answer Mutation
 
 ```typescript
-onSelect(option.value) // string | number
+onSelect(option.id) // string
+// → onAction CHANGE { questionId, answerValue: string }
 ```
 
 ## Agent Checklist
@@ -54,4 +36,10 @@ onSelect(option.value) // string | number
 - [ ] Custom circular radio indicator (not browser default)
 - [ ] Selected: magenta border + pink background
 - [ ] HTML labels
-- [ ] If `isMultiSelect`: implement checkbox cards (SDK gap in reference)
+- [ ] If `isMultiSelect`: implement checkbox cards with array answer shape
+
+## SDK Integration Checklist (agent)
+
+- [ ] Visibility helper: `getVisibleMcqOptionsForAnswers`
+- [ ] Store `option.id` — never option label text
+- [ ] Matrix row: [`question-type-sdk-matrix.md#mcq`](../00-integration/question-type-sdk-matrix.md#mcq)

package/templates/docs/03-ui-specs/03-text.md

@@ -1,7 +1,7 @@
-# UI Spec: Text Field (`type: 'text'`)
+# UI Spec: Text Field (`type: 'TEXTFIELD'`)
 
 > **Reference:** `apps/client/src/components/Question.tsx` (inline)
-> **SDK type:** `TextQuestion` — `fetchSurvey/types/text.ts`
+> **SDK type:** `TextInputQuestion` — `fetchSurvey/types/text.ts`
 
 ## Config Inventory
 

package/templates/docs/03-ui-specs/04-csat.md

@@ -1,57 +1,62 @@
-# UI Spec: CSAT (`type: 'csat'`)
+# UI Spec: CSAT Matrix Grid (`type: 'CSAT_MATRIX'`)
 
-> **Reference:** `apps/client/src/components/CsatScale.tsx`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CsatMatrixScale.tsx`
 > **SDK type:** `CsatQuestion` — `fetchSurvey/types/csat.ts`
-> **Component blueprint:** `01-components/04-csat-scale.md`
+> **Component blueprint:** `01-components/05-csat-matrix-scale.md`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `options[]` | ✅ | Scale buttons or dropdown options |
-| `buttonType` | ✅ partial | Branches below |
-| `labelPosition` | ✅ | `'top'` → flex-col-reverse; `'hidden'` → no label |
-| `minLabel` / `maxLabel` | ✅ | Rendered in Question.tsx above scale |
-| `hasNotApplicable` | ❌ | N/A option in options array still renders |
-| `reverseScaleOrder` | ❌ | Document: reverse options before map |
+| `statementRows[]`, `scaleColumns[]` | ✅ | Grid / carousel / dropdown data |
+| `displayStyle` | ✅ | Grid vs vertical list routing |
+| `gridLayout` | ✅ | carousel vs standard vs dropdown |
+| `hasNotApplicableOption` | ✅ | Checkbox below row (vertical) or N/A column (grid) |
+| `reverseScaleOrder` | ✅ | Flip emoji/star/number index |
+| `scaleAnchorLabels[]` | ✅ | Anchor row above columns |
 
 ## Config Decision Tree
 
 ```
-csat
-├── buttonType === 'dropdown'
-│   └── Native <select>, placeholder "Select an option"
-│       └── Parse value 'null' → null
-└── else (emoji | star | numbered | number | default)
-    └── flex flex-wrap gap-3 buttons
-        ├── emoji → getEmojiForIndex(index, scaleLength)
-        ├── star → CsatStarIcons filled/empty; labels hidden
-        ├── numbered/number → mono font value
-        └── default → bold value or 'N/A' if null
+CSAT_MATRIX
+├── gridLayout === 'carousel' → CsatMatrixCarousel
+├── displayStyle in (dropdown, selectbox) → CsatMatrixVerticalList
+│   ├── dropdown → MatrixDropdown placeholder "Select..."
+│   ├── selectbox → full-width cards #fdf2f8 selected
+│   └── else → card radio list
+└── else → CsatMatrixGrid
+    ├── displayStyle === 'emoji' → client-side emoji icons (react-icons) + hover scale + ring when selected
+    ├── displayStyle === 'star' → opacity 0.5 unselected; filled/empty icons
+    ├── displayStyle === 'numbered' → 40×40 badge; selected magenta fill
+    └── displayStyle === 'graphics' → CustomSliderTrack per row (carousel)
 ```
 
-## Interactive States
+## Grid Structure
 
-| State | Border | Background | Transform |
-|-------|--------|------------|-----------|
-| Default | `border-gray-200` | `white` | scale-100 |
-| Hover | `border-gray-300` | `hover:bg-gray-50` | — |
-| Selected | `border-[#e20074]` | `#fdf2f8` | `scale-110` |
-| Star mode | transparent | transparent | no border/bg on button |
+- Row label: `180px` fixed column
+- N/A column: `56px` when `hasNotApplicableOption`
+- Alternating row backgrounds
+- Column headers OR `scaleAnchorLabels[]` anchor row with percentage positioning
 
-## Tooltips
+## Carousel
 
-Recommended: `title={option.label}` on each button. Not in reference client.
+- Pink active dot expands: `20px × 8px` vs `8px` inactive
+- Column labels below cells
+- Emoji tooltip via hover state
+- Graphics mode: slider maps column index
 
 ## Answer Mutation
 
+Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+
 ```typescript
-onSelect(string | number | null)
+onSelect(MatrixRowAnswers)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } })
 ```
 
 ## Agent Checklist
 
-- [ ] Dropdown branch with magenta focus ring
-- [ ] Emoji/star/numbered branches per decision tree
-- [ ] `labelPosition` controls label above/below/hidden
-- [ ] Implement `reverseScaleOrder` and standalone `hasNotApplicable` (SDK gaps)
+- [ ] All displayStyle × gridLayout branches
+- [ ] reverseScaleOrder on emoji/star/numbered
+- [ ] Carousel pink dot indicators
+- [ ] Vertical selectbox cards match MCQ card styling

package/templates/docs/03-ui-specs/05-rating-scale.md

@@ -1,49 +1,52 @@
-# UI Spec: Rating Scale (`type: 'rating_scale'`)
+# UI Spec: Star Rating (`type: 'star_rating'`)
 
-> **Reference:** ❌ Not routed in `Question.tsx` — reuse `CsatScale.tsx` patterns
-> **SDK type:** `RatingScaleQuestion` — `fetchSurvey/types/ratingScale.ts`
-> **Component blueprint:** `01-components/03-rating-scale.md`
+> **DEPRECATED:** Not in the current `SurveyQuestion` union. API RATING pages map to `NPS_SCALE` or CSAT/RATING matrix display styles. See `01-rating.md` and matrix specs instead.
+>
+> **SDK type:** `StarRatingQuestion` — `fetchSurvey/types/starRating.ts`
+> **Component blueprint:** `01-components/04-star-rating-scale.md`
+> **Routed in template:** `Question.tsx` → `RatingScale` for `star_rating`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `options[]` | ❌ gap | Star/emoji buttons (no NPS colors) |
-| `scaleStyle` | ❌ gap | `'star'` or `'emoji'` |
-| `minLabel` / `midLabel` / `maxLabel` | ❌ gap | Same formulas as NPS in Question shell |
-| `midLabelIndex` | ❌ gap | `(midLabelIndex / (options.length - 1)) * 100`% |
-| `reverseScaleOrder` | ❌ gap | Reverse options before render |
+| `options[]` | ✅ | Star/emoji buttons (no NPS traffic-light colors) |
+| `scaleStyle` | ✅ | `'star'` or `'emoji'` |
+| `minLabel` / `midLabel` / `maxLabel` | ✅ | Same formulas as NPS in Question shell |
+| `midLabelIndex` | ✅ | `(midLabelIndex / (options.length - 1)) * 100`% |
+| `reverseScaleOrder` | partial | Reverse options before render |
 
-## Expected UI (from CsatScale + rating labels)
+## Expected UI
 
 ```
 [minLabel]     [midLabel @ %]     [maxLabel]
 ┌────┬────┬────┬────┬────┐
 │ ★  │ ★  │ ★  │ ★  │ ★  │  scaleStyle: 'star'
 └────┴────┴────┴────┴────┘
-  OR emoji row from getEmojiForIndex when scaleStyle: 'emoji'
+  OR emoji row from client-side react-icons when scaleStyle: 'emoji'
 ```
 
-Reuse CsatScale selected styling: `border-[#e20074] bg-[#fdf2f8] scale-110`.
+Selected styling: `border-[#e20074] bg-[#fdf2f8] scale-110`.
 
 ## Config Decision Tree
 
 ```
-rating_scale
-├── scaleStyle === 'star' → CsatStarIcons per option
-├── scaleStyle === 'emoji' → getEmojiForIndex
-└── else → numbered badges (no option.color)
+star_rating
+├── scaleStyle === 'star' → client-side star icons (react-icons) per option
+├── scaleStyle === 'emoji' → client-side emoji icons (react-icons)
+└── else → numbered badges (no accentColor)
 ```
 
 ## Answer Mutation
 
 ```typescript
 onSelect(number)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: number } })
 ```
 
 ## Agent Checklist
 
-- [ ] Add dispatcher branch in Question for `rating_scale`
+- [ ] Dispatcher branch for `star_rating` in Question.tsx
 - [ ] No traffic-light NPS colors on options
 - [ ] min/mid/max labels with midLabelIndex formula
-- [ ] Match CsatScale interactive states
+- [ ] Match star/emoji bounding box rules from `04-star-rating-scale.md`

package/templates/docs/03-ui-specs/06-slider.md

@@ -1,6 +1,8 @@
 # UI Spec: Standalone Slider (`type: 'slider'`)
 
-> **Reference:** ❌ Not routed in `Question.tsx` — reuse `CustomSliderTrack.tsx`
+> **DEPRECATED:** Not in the current `SurveyQuestion` union. API SLIDER pages map to `SLIDER_MATRIX` or matrix `displayStyle: 'graphics'`. See `10-slider-matrix.md` and `CustomSliderTrack` specs.
+>
+> **Reference:** Standalone slider is not routed in current `Question.tsx`
 > **SDK type:** `SliderQuestion` — `fetchSurvey/types/slider.ts`
 > **Component blueprint:** `01-components/09-custom-slider-track.md`