@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

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

@@ -2,9 +2,8 @@
 
 > **UI spec (authoritative):** `03-ui-specs/00-question-shell.md`
 > **Canonical template:** [`templates/Question.tsx`](../templates/Question.tsx) — copy verbatim, then create imported components
-> **Monorepo reference:** `apps/client/src/components/Question.tsx` (not available in npm installs)
+> **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`.
 
 ## Start Here (CRITICAL)
 
@@ -12,71 +11,40 @@
 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.
 
-**Do NOT** write a partial skeleton with `default` fallbacks or `"not yet implemented"` messages.
+**Do NOT** write partial skeletons with `default` fallbacks or `"not yet implemented"` messages.
 
-## 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.
+## Dispatcher (11 type literals)
 
-## Exhaustive Dispatcher Logic (CRITICAL)
+Use `QUESTION_TYPE` from the SDK:
 
-The agent MUST handle EVERY SINGLE ONE of these `question.type` values. Failure to handle them will result in blank UI or broken surveys.
+| `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` |
 
-1. **`rating`**: Renders `RatingScale`. This covers NPS scales.
-2. **`csat`**: Renders `CsatScale`. This covers CSAT specific faces/icons.
-3. **`radio`**: Renders inline MCQ radio buttons.
-4. **`text`**: Renders an inline `<textarea>` or `<input>`.
-5. **`matrix`** — **requires `subType`**:
-   - If `subType === 'CFM_MATRIX'`, render `LikertMatrixScale`
-   - If `subType === 'CSAT_MATRIX'` or `'RATING_MATRIX'`, render `CsatMatrixScale`
-   - Routing on `type === 'matrix'` alone renders **nothing**
-6. **`slider_matrix`**: Renders `SliderMatrixScale`
-7. **`file_upload`**: Renders `FileUploadScale`
-8. **`text_and_media`**: Renders inline `<video>` or `<img>` based on `question.mediaUrl`. No answer input.
-9. **`rating_scale`**: Star/emoji scale — see `03-ui-specs/05-rating-scale.md`
-10. **`slider`**: Standalone slider — see `03-ui-specs/06-slider.md`
-
-## Forbidden Anti-Patterns
+**Never** branch on `subType`.
 
 ```tsx
-// ❌ FORBIDDEN — never ship this
-default:
-  return <p>Question type "{question.type}" is not yet implemented in this client.</p>;
-
-// ❌ FORBIDDEN — matrix without subType
-{question.type === 'matrix' && <SomeMatrix />}
+import { QUESTION_TYPE } from '@explorer02/cfm-survey-sdk';
 
-// ✅ REQUIRED — matrix with subType
-{question.type === 'matrix' && question.subType === 'CFM_MATRIX' && <LikertMatrixScale ... />}
-{question.type === 'matrix' && (question.subType === 'CSAT_MATRIX' || question.subType === 'RATING_MATRIX') && <CsatMatrixScale ... />}
+{question.type === QUESTION_TYPE.CFM_MATRIX && <LikertMatrixScale ... />}
 ```
 
-## Container UI Structure
-
-Every question MUST be wrapped in a standard HTML `<section>` to visually separate it.
-
-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!
-
-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 `*`.
+## Placeholder resolution
 
-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`).
+Pass `allAnswers` and `allQuestions` so question text can reference prior answers:
 
-4. **Validation Error Banner**:
-   - If `validationError` prop is passed, render a highly visible banner below the scale.
-
-## 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`).
+```tsx
+resolveSurveyQuestionPlaceholders(question.questionText, allAnswers, questionsById)
+```
 
 ## Props Contract
 
@@ -85,8 +53,43 @@ type QuestionProps = {
   question: SurveyQuestion;
   selectedValue?: AnswerValue;
   validationError?: string;
-  onSelect: (value: AnswerValue) => void;
+  allAnswers: SurveyAnswers;
+  allQuestions: SurveyQuestion[];
+  onSelect: (answerValue: AnswerValue) => void;
 };
 ```
 
-Wire `onSelect` → `onAction({ type: 'CHANGE', payload: { questionId, value } })`.
+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)
 
@@ -23,9 +23,10 @@ If `true`, the standard Row-by-Column matrix is inverted:
 - **Architectural Requirement**: Your `<tbody>` map must iterate over `question.columns` first, and render `<td>` cells mapped from `question.rows`.
 - Ensure `onSelect` still correctly pairs the original `row.id` with the original `col.value`.
 
-### 2. `repeatScale`
+### 2. `repeatColumnHeaders`
 If `true`, the `<thead>` containing column labels must be re-injected periodically to prevent users from losing track of columns on long matrices.
 - **Implementation Strategy**: In your row `map()`, if `index > 0 && index % 5 === 0`, return a React Fragment containing a cloned `<tr>` header row followed by the actual data `<tr>`.
+- **Note:** API/config field is `repeatColumnHeaders` (not `repeatScale`).
 
 ### 3. `matrixType === 'bipolar'`
 Standard matrices (`'likert'`) only show statement text on the left. Bipolar scales show text on BOTH sides of the radio buttons.
@@ -44,3 +45,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

@@ -1,58 +1,30 @@
 # File Upload Architectural Blueprint
 
 > **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'`
+> **Upload API:** [`00-integration/file-upload-aws.md`](../00-integration/file-upload-aws.md)
+> **Portable template:** implement per ui-spec (upload wiring is project-specific)
+> **Target Component:** `FileUploadScale`
+> **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.
+
+Render drag-and-drop zone, validate files locally, **upload via presigned URL**, then bubble `UploadedFileAnswer[]` via `onSelect`.
 
 ## State Management
-- `selectedValue`: Expects an array of native `File` objects (or serialized equivalents).
-- **Mutation Pattern**: 
-  1. The user selects files.
-  2. The component intercepts the files.
-  3. The component validates them against ALL limits.
-  4. If valid, append the new files to `selectedValue` (handling it as an array).
-  5. Call `onSelect(updatedFilesArray)`.
-
-## Configuration Matrix (CRITICAL FOR PLANNING)
-
-Before calling `onSelect`, your component MUST validate against these properties:
-
-### 1. `supportedFileFormats`
-- Extracted from `question.supportedFileFormats` (e.g. `['PDF', 'PNG', 'JPG']`).
-- Use this to build the `accept` attribute string for the hidden input: `question.supportedFileFormats?.map(f => \`.\${f.toLowerCase()}\`).join(',')`.
-- You MUST reject files with extensions that are not in this list.
-
-### 2. `maxFileCount`
-- Prevent uploads if `currentFiles.length + newFiles.length > maxFileCount`.
-- Provide a clear local error message indicating the max limit.
-
-### 3. `fileSizeLimit` & `fileSizeLimitType`
-- `fileSizeLimit` is a number representing megabytes (MB).
-- If `fileSizeLimitType === 'PER_FILE'`, validate that EVERY incoming file's `size` (in bytes) is `<= fileSizeLimit * 1024 * 1024`.
-- If `fileSizeLimitType === 'IN_TOTAL'`, validate that the combined sum of all existing `selectedValue` sizes plus the incoming files' sizes is `<= fileSizeLimit * 1024 * 1024`.
-
-## UI/UX Specifications
-
-1. **Dropzone**:
-   - Wrap the main area with `onDragEnter`, `onDragOver`, `onDragLeave`, `onDrop`.
-   - **Inactive State**: `border-2 border-dashed border-gray-300 rounded-xl bg-gray-50 p-8 text-center cursor-pointer transition-all`.
-   - **Drag/Hover State**: `border-[#e20074] bg-[#fdf2f8]` (Using the brand primary color).
-   - Display a Cloud SVG icon (use gray, switch to magenta on hover).
-   - Render `question.uploadMessage` (which can contain HTML, so use `dangerouslySetInnerHTML`).
-   - Dynamically render the limits text (e.g., "Max 3 files, 10MB per file").
-
-2. **File List**:
-   - Render existing files as distinct cards underneath the dropzone.
-   - Styling: `flex items-center justify-between p-3 mt-3 border border-gray-200 rounded-lg bg-white shadow-sm`.
-   - Display the filename (truncated if long) and the formatted file size (e.g., "1.2 MB").
-   - Include a distinct, circular Trash/Remove button that removes the file from the state and calls `onSelect` with the updated array.
-
-3. **Validation Errors**:
-   - Local validation errors (e.g. "File too large") must be displayed in a highly visible red banner (`bg-red-50 text-red-700 p-3 rounded-md`) right below the dropzone.
-
-## Hidden Input
-- Include a hidden `<input type="file" multiple={question.maxFileCount > 1} accept={...} />` that is triggered via a `useRef` when the dropzone is clicked.
+
+- `selectedValue`: `UploadedFileAnswer[] | undefined` — **not** raw `File[]` after upload completes
+- **Mutation pattern:**
+  1. User selects files → local validation
+  2. For each file: request presigned URL → PUT to S3 → append `{ id, mediaUrl, name, mimeType, size }`
+  3. `onSelect(uploadedAnswers)` → `onAction(CHANGE)`
+
+## Local validation (before upload)
+
+Same as ui-spec: `supportedFileFormats`, `maxFileCount`, `fileSizeLimit` + `fileSizeLimitType`.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.FILE_UPLOAD`
+- [ ] Final answer: `UploadedFileAnswer[]` with `id` + `mediaUrl`
+- [ ] Wire upload API per [`file-upload-aws.md`](../00-integration/file-upload-aws.md)
+- [ ] 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

@@ -1,44 +1,41 @@
 # Matrix Dropdown
 
-> **UI spec (authoritative):** `03-ui-specs/shared/matrix-dropdown.md`
-> **Reference implementation:** `apps/client/src/components/MatrixDropdown.tsx`
-> **Component**: `MatrixDropdown`
-> **Used by**: `CsatMatrixScale`, `LikertMatrixScale`
+> **UI spec (authoritative):** [`03-ui-specs/shared/matrix-dropdown.md`](../03-ui-specs/shared/matrix-dropdown.md) — implement the **custom panel** (not a native `<select>`).
+> **Portable template:** copy [`templates/MatrixDropdown.tsx`](../templates/MatrixDropdown.tsx) when available.
+> **Component:** `MatrixDropdown`
+> **Used by:** `CsatMatrixScale`, `LikertMatrixScale`
 
 ## Role
-Renders a dropdown selector for a single row in a matrix question. Used when `matrixFormat === 'dropdown'` or `buttonType === 'dropdown'`.
 
-## Props Interface
+Renders a custom dropdown selector for a single matrix row. Used when `gridLayout === 'dropdown'` or `displayStyle` is `'dropdown'` / `'selectbox'`.
+
+Emits stored column **`id`** values via `matrixColumnStoredValue(col)` — see [`02-reference/value-derivation.md`](../02-reference/value-derivation.md).
+
+## Props (wiring only)
+
 ```typescript
 type MatrixDropdownProps = {
-  columns: MatrixColumn[];
-  selectedValue: string | number | null | undefined;
+  options: ScaleColumn[];           // visible columns for this row
+  value: string | number | null | undefined;
   onChange: (value: string | number | null) => void;
+  multiple?: boolean;
   placeholder?: string;
 };
 ```
 
-## Structure
-Renders a native HTML `<select>` element.
-
-```tsx
-<select
-  value={selectedValue === null ? '' : String(selectedValue ?? '')}
-  onChange={e => {
-    const val = e.target.value;
-    if (val === '') onChange(null); // Map empty string back to null for N/A
-    else {
-      // Find original option to keep type (number vs string) intact
-      const opt = columns.find(c => String(c.value) === val);
-      onChange(opt ? opt.value : val);
-    }
-  }}
->
-  <option value="" disabled>Select an option...</option>
-  {columns.map(col => (
-    <option key={String(col.value)} value={String(col.value)}>
-      {col.label}
-    </option>
-  ))}
-</select>
-```
+## Implementation
+
+Do **not** use a native `<select>`. Follow the shared ui-spec for:
+
+- Click-to-open panel with click-outside dismiss
+- Single-select: one choice; multi-select: tag chips + toggle
+- N/A mutual exclusion when `hasNotApplicableOption` applies
+- Placeholder text: `"Select..."` (dropdown) or full-width cards (selectbox)
+
+See [`03-ui-specs/shared/matrix-dropdown.md`](../03-ui-specs/shared/matrix-dropdown.md) for layout, states, and agent checklist.
+
+## SDK Integration Checklist
+
+- [ ] Copy `templates/MatrixDropdown.tsx` or implement per shared ui-spec
+- [ ] `onChange` stores column **`id`** via `matrixColumnStoredValue(col)`
+- [ ] Filter columns with `getVisibleMatrixItemsForAnswers` before passing to dropdown

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