@explorer02/cfm-survey-sdk 0.2.0 → 0.2.2

package/templates/docs/01-components/02-question.md

@@ -1,107 +1,95 @@
 # Question Dispatcher Architectural Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/00-question-shell.md`
-> **Reference implementation:** `apps/client/src/components/Question.tsx`
+> **Canonical template:** [`templates/Question.tsx`](../templates/Question.tsx) — copy verbatim, then create imported components
+> **Monorepo reference:** `apps/client/src/components/Question.tsx`
 > **Target Component**: `Question`
-> **Role**: Wrapper card component that routes to the correct scale component based on `question.type`.
 
-## Core Responsibility
-Render a visually separated container (card) for each question. Handle rich text parsing, required asterisks, description text, and error validation messages. Most importantly, it MUST act as an exhaustive switch statement dispatching to ALL supported question types.
+## Start Here (CRITICAL)
 
-## Exhaustive Dispatcher Logic (CRITICAL)
+1. Copy [`docs/templates/Question.tsx`](../templates/Question.tsx) into your project.
+2. Create every imported scale component — see [`component-checklist.md`](../00-integration/component-checklist.md).
+3. Read `03-ui-specs/` for each type in your fetched survey **before** editing the dispatcher.
 
-The agent MUST handle EVERY SINGLE ONE of these `question.type` values. Failure to handle them will result in blank UI or broken surveys.
+**Do NOT** write partial skeletons with `default` fallbacks or `"not yet implemented"` messages.
 
-1. **`rating`**: Renders `RatingScale`. This covers NPS, Stars, Emoji, and generic numeric scales.
-2. **`csat`**: Renders `CsatScale`. This covers CSAT specific faces/icons.
-3. **`radio`**: Renders inline MCQ radio buttons. (Can be implemented inside this file or separately).
-4. **`text`**: Renders an inline `<textarea>` or `<input>`.
-5. **`matrix`**: 
-   - If `subType === 'CFM_MATRIX'`, render `LikertMatrixScale`
-   - If `subType === 'CSAT_MATRIX'` or `'RATING_MATRIX'`, render `CsatMatrixScale`
-6. **`slider_matrix`**: Renders `SliderMatrixScale`
-7. **`file_upload`**: Renders `FileUploadScale`
-8. **`text_and_media`**: Renders inline `<video>` or `<img>` based on `question.mediaUrl`. 
-   - *Note: `text_and_media` questions may NOT have user input. Do not render a scale for them.*
+## Dispatcher (11 type literals)
 
-## Container UI Structure
-
-Every question MUST be wrapped in a standard HTML `<section>` to visually separate it.
+Use `QUESTION_TYPE` from the SDK:
 
-1. **Wrapper styling**: 
-   - Border: `border border-gray-200`
-   - Radius: `rounded-xl`
-   - Background: `bg-white`
-   - Padding: `p-6 md:p-8`
-   - Shadow & Hover: `shadow-sm transition-all hover:shadow-md`
-   - **Crucial**: ID must be set to `question.id` (`id={question.id}`) so scroll-to-error works!
+| `question.type` | Renders |
+|-----------------|---------|
+| `NPS_SCALE` | `RatingScale` (NPS) |
+| `MCQ` | Inline radio/checkbox |
+| `TEXTFIELD` | Inline textarea/input |
+| `CFM_MATRIX` | `LikertMatrixScale` |
+| `CSAT_MATRIX`, `RATING_MATRIX` | `CsatMatrixScale` |
+| `SLIDER_MATRIX` | `SliderMatrixScale` |
+| `FILE_UPLOAD` | `FileUploadScale` |
+| `TEXT_AND_MEDIA` | Media only (no answer) |
+| `HEATMAP` | `HeatmapScale` |
+| `RANK_ORDER` | `RankOrderScale` |
 
-2. **Heading (`question.text`)**:
-   - MUST use `dangerouslySetInnerHTML={{ __html: question.text }}` because text from Sprinklr contains rich HTML (bold, links, italics).
-   - If `question.required === true`, append a red asterisk `*`.
+**Never** branch on `subType`.
 
-3. **Description (`question.description`)**:
-   - Render conditionally if `question.description` exists.
-   - MUST use `dangerouslySetInnerHTML`.
-   - Style with slightly smaller text, greyish color (e.g., `text-sm text-gray-600 mt-2`).
+```tsx
+import { QUESTION_TYPE } from '@explorer02/cfm-survey-sdk';
 
-4. **Validation Error Banner**:
-   - If `validationError` prop is passed, render a highly visible banner below the scale.
-   - Example: Red border-left, red background, bold text.
+{question.type === QUESTION_TYPE.CFM_MATRIX && <LikertMatrixScale ... />}
+```
 
-## Hover Tooltips & Micro-interactions
-- Focus states on text inputs MUST use the brand primary color (e.g., magenta `#e20074` for Telekom).
-- Radio button wrappers should have a subtle background hover effect (e.g., `hover:bg-pink-50`).
+## Placeholder resolution
 
-## Example Architectural Skeleton
+Pass `allAnswers` and `allQuestions` so question text can reference prior answers:
 
 ```tsx
-<section id={question.id} className="space-y-6 rounded-xl border border-gray-200 bg-white p-6 md:p-8 shadow-sm transition-all hover:shadow-md">
-  
-  {/* HEADING */}
-  <h2 className="text-lg md:text-xl font-semibold leading-relaxed text-gray-900 flex items-start gap-1">
-    <span dangerouslySetInnerHTML={{ __html: question.text }} className="prose prose-sm max-w-none" />
-    {question.required && <span className="text-[#e20074] shrink-0">*</span>}
-  </h2>
-  
-  {/* DESCRIPTION */}
-  {question.description && (
-    <div className="text-sm text-gray-600 mt-2 leading-relaxed prose prose-sm max-w-none" dangerouslySetInnerHTML={{ __html: question.description }} />
-  )}
-  
-  {/* DISPATCHER */}
-  <div className="pt-4">
-    {question.type === 'rating' && <RatingScale ... />}
-    {question.type === 'csat' && <CsatScale ... />}
-    {question.type === 'slider_matrix' && <SliderMatrixScale ... />}
-    {question.type === 'file_upload' && <FileUploadScale ... />}
-    {question.type === 'matrix' && question.subType === 'CFM_MATRIX' && <LikertMatrixScale ... />}
-    {question.type === 'matrix' && (question.subType === 'CSAT_MATRIX' || question.subType === 'RATING_MATRIX') && <CsatMatrixScale ... />}
-    
-    {question.type === 'radio' && (
-       // Inline Radio implementation
-       // Make sure to match brand hover colors!
-    )}
-    
-    {question.type === 'text' && (
-       // Inline Textarea implementation
-       // Handle character limit `question.maxCharacterCount`
-    )}
-
-    {question.type === 'text_and_media' && (
-       // Display media (image/video) based on question properties
-       // This handles CONTENT blocks.
-    )}
-  </div>
-
-  {/* ERROR BANNER */}
-  {validationError && (
-    <div className="mt-6 rounded-lg border-l-4 border-l-[#e20074] bg-red-50 p-4">
-      <p className="text-sm font-bold text-gray-900 leading-tight flex items-center gap-2">
-        <span className="text-[#e20074]">⚠</span> {validationError}
-      </p>
-    </div>
-  )}
-
-</section>
+resolveSurveyQuestionPlaceholders(question.questionText, allAnswers, questionsById)
+```
+
+## Props Contract
+
+```typescript
+type QuestionProps = {
+  question: SurveyQuestion;
+  selectedValue?: AnswerValue;
+  validationError?: string;
+  allAnswers: SurveyAnswers;
+  allQuestions: SurveyQuestion[];
+  onSelect: (answerValue: AnswerValue) => void;
+};
 ```
+
+Wire `onSelect` → `onAction({ type: 'CHANGE', payload: { questionId, answerValue } })`.
+
+## Container UI Structure
+
+- Wrapper: `<section id={question.id} ...>` — **required** for scroll-to-error
+- `questionText` / `questionDescription`: `dangerouslySetInnerHTML`
+- Required asterisk when `question.required`
+- Validation error banner when `validationError` is set
+
+## Matrix value storage
+
+Store matrix cell values as column **`id`** via `matrixColumnStoredValue(col)` — see [`value-derivation.md`](../02-reference/value-derivation.md).
+
+## SDK Integration Checklist — inline types (agent)
+
+### MCQ (`QUESTION_TYPE.MCQ`)
+
+- [ ] Filter options with `getVisibleMcqOptionsForAnswers` before render
+- [ ] Store `option.id`; support `isMultiSelect` array shape when configured
+- [ ] onAction CHANGE: `{ questionId, answerValue: optionId | optionId[] }`
+
+### TEXTFIELD (`QUESTION_TYPE.TEXTFIELD`)
+
+- [ ] Render `inputVariant` (`short` single-line vs `long` textarea)
+- [ ] onAction CHANGE: `{ questionId, answerValue: string }`
+- [ ] Debounce long text if partial save enabled
+
+### TEXT_AND_MEDIA (`QUESTION_TYPE.TEXT_AND_MEDIA`)
+
+- [ ] No answer input — no CHANGE action
+- [ ] Render media block when `question.media?.url` present
+- [ ] User advances with NEXT
+
+See [`question-type-sdk-matrix.md`](../00-integration/question-type-sdk-matrix.md) for all 11 types.

package/templates/docs/01-components/03-rating-scale.md

@@ -3,7 +3,7 @@
 > **UI spec (authoritative):** `03-ui-specs/01-rating.md` (NPS) · `03-ui-specs/05-rating-scale.md` (star/emoji gap)
 > **Reference implementation:** `apps/client/src/components/RatingScale.tsx`
 > **Target Component**: `RatingScale`
-> **Handles**: `type: 'rating'`, `type: 'rating_scale'`
+> **Handles**: `type: 'NPS_SCALE'` (via `QUESTION_TYPE.NPS_SCALE`)
 
 ## Core Responsibility
 Render a horizontal sequence of numbered badges. 
@@ -28,3 +28,13 @@ The UI must exactly match enterprise standards:
 3. **Selected State**: The selected badge MUST pop out prominently: `border-2 border-[#e20074] shadow-md scale-105 opacity-100 font-bold`.
 4. **Hover State**: `hover:scale-105 hover:border-[#e20074] transition-all cursor-pointer`.
 5. **Tooltips**: Every badge MUST have `title={option.label}` applied for accessibility and semantic context (e.g. hovering '10' shows 'Extremely Likely').
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.NPS_SCALE`
+- [ ] Answer stored as: `number`
+- [ ] onAction CHANGE: `{ questionId, answerValue: number }`
+- [ ] Visibility helper: `getVisibleScaleColumnsForAnswers` when scale points have answer logic
+- [ ] Custom fields: 4th arg on scale visibility helper when needed
+- [ ] Logic features: skip ✓ display ✓ answer ✓ variants ✓ numbering ✓
+- [ ] Matrix row: [`question-type-sdk-matrix.md`](../00-integration/question-type-sdk-matrix.md#nps_scale)

package/templates/docs/01-components/04-star-rating-scale.md

@@ -0,0 +1,45 @@
+# Star Rating Scale Architectural Blueprint
+
+> **DEPRECATED:** API RATING pages map to `NPS_SCALE` or matrix display styles — not a separate `question.type`. Keep for historical reference only.
+>
+> **UI spec (authoritative):** `03-ui-specs/05-rating-scale.md`
+> **SDK type:** `StarRatingQuestion` — `type: 'star_rating'`
+> **Target Component**: `RatingScale` (star/emoji variant)
+> **Handles**: `type: 'star_rating'` only — not `CSAT_MATRIX` (that is a matrix grid)
+
+## Core Responsibility
+
+Render star or emoji rating scales ensuring that active selections are unmistakably highlighted using bounding boxes or strong border accents, NEVER just by changing the SVG fill color.
+
+## State Management & Mapping
+
+- **Emojis**: `scaleStyle === 'emoji'`
+  - Map values using client-side emoji icons (react-icons) proportional to scale length.
+- **Stars**: `scaleStyle === 'star'`
+  - Active stars (index <= selectedValue) use filled star icons from react-icons.
+- **Numbers**: Derive display/submit value from `optionLabel` (see `02-reference/value-derivation.md`).
+
+## UX Bounding Box Rules (CRITICAL)
+
+### For Emojis & Stars:
+
+- **Unselected**: `inline-flex p-2 border-2 border-transparent opacity-40 hover:opacity-100 hover:scale-110 transition-all cursor-pointer`.
+- **Selected**: The specific selected icon MUST be wrapped in a prominent square box with rounded corners.
+  - **CSS**: `border-2 border-[#e20074] rounded-lg p-2 bg-pink-50 shadow-sm scale-110 opacity-100`.
+
+### For Numbered Badges:
+
+- **Shape**: MUST be square with rounded corners (`rounded-lg w-12 h-12`). Do not use full circles.
+- **Selected**: `border-2 border-[#e20074] opacity-100 font-bold scale-105 shadow-md`.
+- **Unselected**: `opacity-30 border-transparent`.
+
+## Bounding Boxes inside Matrices
+
+When emojis or stars are rendered inside `CsatMatrixScale`, the exact same bounding box logic applies. See `05-csat-matrix-scale.md`.
+
+## Tooltips & Label Positions
+
+- **Tooltips**: Every emoji, star, and badge MUST have `title={optionLabel}` on hover.
+- **Labels (`minLabel`, `midLabel`, `maxLabel`)**:
+  - Render in `Question.tsx` above the scale (same pattern as `nps`).
+  - `midLabel` position: `style={{ left: \`\${(midLabelIndex / (options.length - 1)) * 100}%\` }}`.

package/templates/docs/01-components/05-csat-matrix-scale.md

@@ -1,22 +1,27 @@
 # CSAT Matrix Architectural Blueprint
 
-> **UI spec (authoritative):** `03-ui-specs/08-matrix-csat-rating.md`
+> **UI spec (authoritative):** `03-ui-specs/04-csat.md` (for `CSAT_MATRIX`) and `03-ui-specs/08-matrix-csat-rating.md` (for `RATING_MATRIX`)
 > **Reference implementation:** `apps/client/src/components/CsatMatrixScale.tsx`
 > **Target Component**: `CsatMatrixScale`
-> **Handles**: `type: 'matrix'` (CSAT_MATRIX and RATING_MATRIX subTypes)
+> **Handles**: `type: 'CSAT_MATRIX'` and `type: 'RATING_MATRIX'`
 
 ## Core Responsibility
+
 Render a grid where columns represent satisfaction scales (Emojis, Stars, or Rating Badges).
 
 ## Data Mapping & State Management
-- `selectedValue`: Expects `MatrixAnswerMap` shape.
-- Iterate over `question.rows`. Within each row, iterate over `question.columns`.
-- Render the correct icon/badge in the `<td>` based on `question.buttonType`.
+
+- `selectedValue`: `MatrixRowAnswers` — keys are `statementRows[].id`, values are column **`id`** (via `matrixColumnStoredValue`)
+- Iterate over `question.statementRows`. Within each row, iterate over `question.scaleColumns`.
+- Render the correct icon/badge in the `<td>` based on `question.displayStyle`.
 
 ## Configuration Matrix
+
 You MUST handle:
-- **`hasNotApplicable`**: If true, the last column might be `null`. Render a distinct UI (e.g., standard radio or gray badge) for the N/A column.
-- **`reverseScaleOrder`**: Ensure your column mapping respects this logic if implemented in the UI.
+
+- **`hasNotApplicableOption`**: If true, the last column might be `null`. Render a distinct UI for the N/A column.
+- **`reverseScaleOrder`**: Reverse column order before render when true.
+- **`gridLayout`**: `'standard'`, `'carousel'`, or `'dropdown'` — see ui-spec decision tree.
 
 ## UI/UX Bounding Box Rules (CRITICAL)
 
@@ -28,8 +33,12 @@ Matrices are difficult to read and click accurately. You MUST implement these st
 2. **The "Active Bounding Box"**:
    - For Emojis and Stars inside the matrix, do NOT just change the SVG fill.
    - The interactive wrapper inside the `<td>` MUST toggle a pink bounding box.
-   - **Selected Cell**: `border-2 border-[#e20074] rounded-lg p-2 bg-pink-50 shadow-sm scale-110 opacity-100 cursor-pointer`.
-   - **Unselected Cell**: `border-2 border-transparent p-2 opacity-40 hover:opacity-100 hover:scale-110 cursor-pointer`.
 
-3. **Tooltips**:
-   - Every single interactive cell MUST have `title={col.label}` so the user sees exactly what column they are in without scrolling up to the table header.
+## SDK Integration Checklist (agent)
+
+- [ ] Type literals: `QUESTION_TYPE.CSAT_MATRIX` and `QUESTION_TYPE.RATING_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` via `matrixColumnStoredValue`
+- [ ] onAction CHANGE: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] Visibility helper: `getVisibleMatrixItemsForAnswers(..., customFieldValues?)`
+- [ ] Emoji/star UI: client-side `react-icons` — not SDK exports
+- [ ] Matrix row: [`question-type-sdk-matrix.md`](../00-integration/question-type-sdk-matrix.md)

package/templates/docs/01-components/06-likert-matrix-scale.md

@@ -3,14 +3,14 @@
 > **UI spec (authoritative):** `03-ui-specs/07-matrix-cfm.md`
 > **Reference implementation:** `apps/client/src/components/LikertMatrixScale.tsx`
 > **Target Component**: `LikertMatrixScale`
-> **Handles**: `type: 'matrix'` (CFM_MATRIX subType)
+> **Handles**: `type: 'CFM_MATRIX'`
 
 ## Core Responsibility
 Render a grid with text-label columns. However, this component must be highly dynamic to support complex layouts, transpositions, and long-form matrix readability.
 
 ## Data Mapping & State Management
-- `selectedValue`: Expects `MatrixAnswerMap` shape (`Record<string, string | number | null>`).
-- **Mutation**: When radio button is clicked for `row.id` and `col.value`, dispatch `onSelect({ ...selectedValue, [row.id]: col.value })`.
+- `selectedValue`: `MatrixRowAnswers` — store column **`id`** via `matrixColumnStoredValue(col)`
+- **Mutation**: When a cell is selected for `row.id`, dispatch `onSelect({ ...selectedValue, [row.id]: columnId })`
 
 ## Configuration Matrix (CRITICAL FOR PLANNING)
 
@@ -44,3 +44,12 @@ To match enterprise standards, implement the following UI strictly:
    - Every input MUST have `title={col.label}` so the user sees the semantic meaning when hovering the radio button.
 4. **Header Typography**:
    - `th` tags should be `text-xs font-semibold text-gray-500 uppercase tracking-wider p-4 border-b`.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.CFM_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` via `matrixColumnStoredValue`
+- [ ] onAction CHANGE: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] Visibility helper: `getVisibleMatrixItemsForAnswers(..., customFieldValues?)`
+- [ ] Handle `gridLayout`: standard / carousel / dropdown
+- [ ] Matrix row: [`question-type-sdk-matrix.md#cfm_matrix`](../00-integration/question-type-sdk-matrix.md#cfm_matrix)

package/templates/docs/01-components/07-slider-matrix-scale.md

@@ -3,13 +3,13 @@
 > **UI spec (authoritative):** `03-ui-specs/09-slider-matrix.md`
 > **Reference implementation:** `apps/client/src/components/SliderMatrixScale.tsx`
 > **Target Component**: `SliderMatrixScale`
-> **Handles**: `type: 'slider_matrix'`
+> **Handles**: `type: 'SLIDER_MATRIX'`
 
 ## Core Responsibility
 Render an independent range slider for every row in the matrix. Sliders must be highly visible, utilizing a "thick track" UI, dynamic fill based on the current value, and exact value badges.
 
 ## State Management
-- `selectedValue`: Expects `MatrixAnswerMap` shape.
+- `selectedValue`: Expects `MatrixRowAnswers` shape.
 - `row.min`, `row.max`, and `row.step` must dictate the boundaries of the slider logic.
 - **Mutation**: `onChange` of the input must parse the value as a Number before dispatching `onSelect`.
 
@@ -45,3 +45,12 @@ Your component must account for:
 - If `true`, render a checkbox at the end of the row.
 - Checking it sets the value in the map to `null`.
 - When `value === null`, gray out the slider track and disable the input.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.SLIDER_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` — number or `null` per row
+- [ ] onAction CHANGE: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] Visibility helper: `getVisibleStatementRowsForAnswers(..., customFieldValues?)`
+- [ ] Use `CustomSliderTrack` when `sliderType === 'graphics'`
+- [ ] Matrix row: [`question-type-sdk-matrix.md#slider_matrix`](../00-integration/question-type-sdk-matrix.md#slider_matrix)

package/templates/docs/01-components/08-file-upload-scale.md

@@ -3,7 +3,7 @@
 > **UI spec (authoritative):** `03-ui-specs/10-file-upload.md`
 > **Reference implementation:** `apps/client/src/components/FileUploadScale.tsx`
 > **Target Component**: `FileUploadScale`
-> **Handles**: `type: 'file_upload'`
+> **Handles**: `type: 'FILE_UPLOAD'`
 
 ## Core Responsibility
 Render a robust drag-and-drop zone and enforce complex file size, type limits, and maximum file count constraints BEFORE updating the state.
@@ -56,3 +56,12 @@ Before calling `onSelect`, your component MUST validate against these properties
 
 ## Hidden Input
 - Include a hidden `<input type="file" multiple={question.maxFileCount > 1} accept={...} />` that is triggered via a `useRef` when the dropzone is clicked.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.FILE_UPLOAD`
+- [ ] Answer stored as: `UploadedFile[]`
+- [ ] onAction CHANGE: `{ questionId, answerValue: UploadedFile[] }` after upload
+- [ ] Visibility helper: N/A
+- [ ] Enforce `maxFileCount` and `fileSizeLimit` client-side
+- [ ] Matrix row: [`question-type-sdk-matrix.md#file_upload`](../00-integration/question-type-sdk-matrix.md#file_upload)

package/templates/docs/01-components/09-custom-slider-track.md

@@ -3,7 +3,7 @@
 > **UI spec (authoritative):** `03-ui-specs/shared/custom-slider-track.md`
 > **Reference implementation:** `apps/client/src/components/CustomSliderTrack.tsx`
 > **Target Component**: `CustomSliderTrack`
-> **Used By**: `SliderMatrixScale`, `CsatMatrixScale`, `CsatScale`
+> **Used By**: `SliderMatrixScale`, `CsatMatrixScale`, standalone `slider`
 
 ## Core Responsibility
 Native browser `<input type="range">` elements are impossible to style consistently across browsers, especially when trying to render dynamic emoji handles. This component MUST implement an invisible overlay architecture to provide total CSS control over the slider's appearance.
@@ -24,7 +24,7 @@ A dynamic `<div>` representing the portion of the slider up to the current value
 ### Layer 3: The Custom Thumb
 A visual element that floats along the track.
 - **For Standard Sliders**: A pink circle. `w-5 h-5 bg-[#e20074] border-2 border-white rounded-full shadow-md pointer-events-none`.
-- **For Graphics Sliders (`sliderType === 'graphics'`)**: A larger white circle containing an emoji mapped to the current value using `getEmojiForIndex`. `w-10 h-10 bg-white shadow-md border flex items-center justify-center text-2xl`.
+- **For Graphics Sliders (`sliderType === 'graphics'`)**: A larger white circle containing an emoji mapped to the current value using client-side react-icons. `w-10 h-10 bg-white shadow-md border flex items-center justify-center text-2xl`.
 - Inline Style: `style={{ left: \`\${percentage}%\` }}`.
 
 ### Layer 4: The Native Input (The Engine)

package/templates/docs/01-components/11-progress-bar.md

@@ -1,14 +1,15 @@
 # Progress Bar
 
 > **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
+> **Progress calculation:** `00-integration/progress.md`
 > **Reference implementation:** `apps/client/src/components/ProgressBar.tsx`
 > **Component**: `ProgressBar`
-> **Role**: Displays completion status at the top of the survey.
 
 ## Props Interface
+
 ```typescript
 type ProgressBarProps = {
-  progressPercentage: number; // 0 to 100
+  progressPercentage: number; // 0 to 100, path-scoped
 };
 ```
 
@@ -16,7 +17,6 @@ type ProgressBarProps = {
 
 ```tsx
 export default function ProgressBar({ progressPercentage }: ProgressBarProps) {
-  // Ensure it's bounded between 0 and 100
   const width = Math.min(100, Math.max(0, progressPercentage));
 
   return (
@@ -30,4 +30,10 @@ export default function ProgressBar({ progressPercentage }: ProgressBarProps) {
 }
 ```
 
-The `progressPercentage` value is provided directly by `state.progressPercentage` from the `useSurveySDK` hook.
+## Wiring
+
+```tsx
+<ProgressBar progressPercentage={state.progressPercentage} />
+```
+
+The SDK computes percentage from **questions on the active skip path**, not total survey pages. Skip logic and answer changes update the bar automatically.

package/templates/docs/01-components/13-matrix-dropdown.md

@@ -6,7 +6,9 @@
 > **Used by**: `CsatMatrixScale`, `LikertMatrixScale`
 
 ## Role
-Renders a dropdown selector for a single row in a matrix question. Used when `matrixFormat === 'dropdown'` or `buttonType === 'dropdown'`.
+Renders a dropdown selector for a single row in a matrix question. Used when `gridLayout === 'dropdown'` or `displayStyle === 'dropdown'`.
+
+Accepts `ScaleColumn[]`; emits stored column ids via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
 
 ## Props Interface
 ```typescript

package/templates/docs/01-components/14-intro-page.md

@@ -0,0 +1,34 @@
+# Intro Page
+
+> **UI spec:** `03-ui-specs/12-survey-chrome.md`
+> **Reference:** `apps/client/src/components/IntroPage.tsx`
+
+## When to render
+
+`state.phase.kind === 'intro'` and `state.specialPage` is set.
+
+## Props
+
+```typescript
+type IntroPageProps = {
+  page: SpecialPage;
+  language?: string;
+  onStart: () => void;
+};
+```
+
+## Wiring
+
+```tsx
+<IntroPage
+  page={state.specialPage}
+  language={survey.language}
+  onStart={() => onAction({ type: 'START' })}
+/>
+```
+
+## Content
+
+- Render `page.header` and optional `page.description` as HTML
+- CTA label: `page.ctaLabel` or default "Start Survey"
+- Header + Footer chrome on full-page layout

package/templates/docs/01-components/15-end-page.md

@@ -0,0 +1,31 @@
+# End Page
+
+> **UI spec:** `03-ui-specs/12-survey-chrome.md`
+> **Reference:** `apps/client/src/components/EndPage.tsx`
+> **Logic:** `00-integration/end-page-logic.md`
+
+## When to render
+
+`state.phase.kind === 'end'` after successful submit, with `state.specialPage` from `survey.endPages`.
+
+When the survey has **multiple end pages**, the SDK picks the page at submit using display logic (see [`end-page-logic.md`](../00-integration/end-page-logic.md)). The client only renders the resolved `state.specialPage`.
+
+## Props
+
+```typescript
+type EndPageProps = {
+  page: SpecialPage;
+};
+```
+
+## Wiring
+
+```tsx
+<EndPage page={state.specialPage} />
+```
+
+## Content
+
+- Render `page.header` and optional `page.description` as HTML
+- No navigation buttons — terminal thank-you screen
+- Header + Footer chrome

package/templates/docs/01-components/16-paused-page.md

@@ -0,0 +1,27 @@
+# Paused Page
+
+> **UI spec:** `03-ui-specs/12-survey-chrome.md`
+> **Reference:** `apps/client/src/components/PausedPage.tsx`
+
+## When to render
+
+`state.phase.kind === 'paused'` when survey `phaseFlags.paused` is true.
+
+## Props
+
+```typescript
+type PausedPageProps = {
+  page: SpecialPage;
+};
+```
+
+## Wiring
+
+```tsx
+<PausedPage page={state.specialPage} />
+```
+
+## Content
+
+- Read-only message from `page.header` / `page.description`
+- No start or navigation actions

package/templates/docs/01-components/17-heatmap-scale.md

@@ -0,0 +1,75 @@
+# Heatmap Architectural Blueprint
+
+> **UI spec (authoritative):** `03-ui-specs/13-heatmap.md`
+> **Reference implementation:** `apps/client/src/components/HeatmapScale.tsx`
+> **Coordinate helpers:** `apps/client/src/lib/surveyUi/heatmapCoords.ts`
+> **Target Component**: `HeatmapScale`
+> **Handles**: `type: 'HEATMAP'`
+
+## Core Responsibility
+
+Render the heatmap image, capture click spots in normalized 0–1 coordinates, toggle spots on repeat click, enforce `maxClicksAllowed` client-side, and bubble answers via `onSelect`.
+
+## Props Contract
+
+```typescript
+type HeatmapScaleProps = {
+  question: HeatmapQuestion;
+  selectedValue?: HeatmapAnswer;
+  onSelect: (answer: HeatmapAnswer | undefined) => void;
+};
+```
+
+## State Management
+
+- `selectedValue` from SDK is source of truth — do not duplicate answer state
+- Local UI state: `isImageReady` only
+
+## Click Interaction
+
+1. User clicks image → compute normalized `{ x, y }` from `getBoundingClientRect()`
+2. If click within 14px of existing spot → remove that spot
+3. Else if under `maxClicksAllowed` → append `{ id: crypto.randomUUID(), x, y }`
+4. Else → no-op
+
+## Coordinate Helpers
+
+Use `apps/client/src/lib/surveyUi/heatmapCoords.ts`:
+
+- `getNormalizedClickFromImage(event, imageElement)`
+- `findSpotNearClick(clickX, clickY, spots, imageRect)`
+- `createNewSpot(x, y)`
+
+## DOM Structure
+
+```tsx
+<div className="relative inline-block max-w-full">
+  <img onClick={handleImageClick} ... />
+  <div className="absolute inset-0 pointer-events-none">
+    {spots.map(spot => <Spot />)}
+  </div>
+</div>
+```
+
+## Wiring in Question.tsx
+
+```typescript
+{question.type === QUESTION_TYPE.HEATMAP && (
+  <HeatmapScale
+    question={question as HeatmapQuestion}
+    selectedValue={Array.isArray(selectedValue) ? selectedValue : undefined}
+    onSelect={onSelect}
+  />
+)}
+```
+
+Question shell (title, description, validation) stays in `Question.tsx`.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.HEATMAP`
+- [ ] Answer stored as: `HeatmapClickPoint[]`
+- [ ] onAction CHANGE: `{ questionId, answerValue: HeatmapClickPoint[] }`
+- [ ] Copy coord helper from [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts)
+- [ ] Respect `maxClicksAllowed`; normalize coords 0–1
+- [ ] Matrix row: [`question-type-sdk-matrix.md#heatmap`](../00-integration/question-type-sdk-matrix.md#heatmap)