@explorer02/cfm-survey-sdk 0.2.2 → 0.2.4

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

@@ -1,40 +1,34 @@
 # Rating Scale Architectural Blueprint
 
 > **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`
+> **Portable template:** copy [`templates/RatingScale.tsx`](../templates/RatingScale.tsx) + [`surveyUiScaleUtils.ts`](../templates/surveyUiScaleUtils.ts) + [`surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx)
 > **Target Component**: `RatingScale`
 > **Handles**: `type: 'NPS_SCALE'` (via `QUESTION_TYPE.NPS_SCALE`)
 
 ## Core Responsibility
-Render a horizontal sequence of numbered badges. 
+
+Render a horizontal sequence of numbered badges with traffic-light colors (NPS 0–10).
 
 ## Configuration Matrix
-You MUST handle the following configurations dynamically:
 
 ### 1. Color Grading (NPS)
-- Check if `option.color` exists. If so, apply it to the badge background. This is crucial for NPS scales (Red 0-6, Yellow 7-8, Green 9-10).
+- Use `getAccentColor(value)` from `surveyUiScaleUtils.ts` for badge backgrounds
 
 ### 2. Label Positioning (`minLabel`, `midLabel`, `maxLabel`)
-- **Architectural Requirement**: Wrap the badge sequence and the labels in a relative container.
-- Place labels underneath the badges using absolute positioning.
-- **Mid Label Calculation**: You must calculate the exact center position: `style={{ left: \`\${(midLabelIndex / (options.length - 1)) * 100}%\` }}`.
+- Render in `Question.tsx` above `RatingScale` with absolute positioning
+- Mid label: `left: (midLabelIndex / (options.length - 1)) * 100%`
 
 ## UI/UX Rules (CRITICAL)
 
-The UI must exactly match enterprise standards:
-
-1. **Shape**: Badges MUST be square with rounded corners (`rounded-lg w-10 h-10 sm:w-12 sm:h-12`). Do NOT use full circles (`rounded-full`).
-2. **Unselected State**: If any item is selected, unselected items must dim (`opacity-30`).
-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').
+1. **Shape**: Square badges with rounded corners — not full circles
+2. **Unselected State**: Dim unselected when any item selected (`opacity-30`)
+3. **Selected State**: `border-2 border-[#e20074] shadow-md scale-105`
+4. **Tooltips**: `title={option.label}` on every badge
 
 ## SDK Integration Checklist (agent)
 
+- [ ] Copied portable `RatingScale.tsx`
 - [ ] 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)
+- [ ] minLabel/maxLabel rendered in Question.tsx when present

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

@@ -1,44 +1,36 @@
 # CSAT Matrix Architectural Blueprint
 
-> **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`
+> **UI spec (authoritative):** `03-ui-specs/04-csat.md` (CSAT) · `03-ui-specs/08-matrix-csat-rating.md` (RATING)
+> **Portable template:** copy [`templates/CsatMatrixScale.tsx`](../templates/CsatMatrixScale.tsx) + shared deps (see ui-spec)
 > **Target Component**: `CsatMatrixScale`
 > **Handles**: `type: 'CSAT_MATRIX'` and `type: 'RATING_MATRIX'`
 
 ## Core Responsibility
 
-Render a grid where columns represent satisfaction scales (Emojis, Stars, or Rating Badges).
+Render a matrix grid where rows are `statementRows` and columns are `scaleColumns`. Route on `displayStyle` and `gridLayout`.
 
-## Data Mapping & State Management
+## Statement & labels (CRITICAL)
 
-- `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`.
+Every grid row MUST show `statementRows[].statementText` in a **180px** left column.
 
-## Configuration Matrix
-
-You MUST handle:
-
-- **`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.
+Every grid MUST show either:
+- A **column header row** from `scaleColumns[].label`, OR
+- An **anchor label row** from `scaleAnchorLabels[]`
 
-## UI/UX Bounding Box Rules (CRITICAL)
+Never render a bare grid of inputs with no row/column labels.
 
-Matrices are difficult to read and click accurately. You MUST implement these strict UI rules:
-
-1. **Row Tracking**:
-   - Every data `<tr>` MUST have `hover:bg-gray-50 transition-colors duration-150`.
+## Configuration Matrix
 
-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.
+- **`displayStyle`**: emoji | star | numbered | graphics | standard — each has distinct UI (see ui-spec)
+- **`hasNotApplicableOption`**: 56px N/A column
+- **`reverseScaleOrder`**: flip column index before icon/badge lookup
+- **`gridLayout`**: standard | carousel | dropdown
 
 ## SDK Integration Checklist (agent)
 
+- [ ] Copied portable template + `surveyUiIcons.tsx` + `surveyUiScaleUtils.ts`
 - [ ] 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
+- [ ] Answer: `MatrixRowAnswers` via `matrixColumnStoredValue(col)`
+- [ ] Visibility: `getVisibleMatrixItemsForAnswers(..., customFieldValues?)`
+- [ ] Row labels + column/anchor labels visible
 - [ ] Matrix row: [`question-type-sdk-matrix.md`](../00-integration/question-type-sdk-matrix.md)

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

@@ -1,55 +1,36 @@
 # Likert Matrix Architectural Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/07-matrix-cfm.md`
-> **Reference implementation:** `apps/client/src/components/LikertMatrixScale.tsx`
+> **Portable template:** copy [`templates/LikertMatrixScale.tsx`](../templates/LikertMatrixScale.tsx) + [`MatrixDropdown.tsx`](../templates/MatrixDropdown.tsx)
 > **Target Component**: `LikertMatrixScale`
 > **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`: `MatrixRowAnswers` — store column **`id`** via `matrixColumnStoredValue(col)`
-- **Mutation**: When a cell is selected for `row.id`, dispatch `onSelect({ ...selectedValue, [row.id]: columnId })`
+Render CFM matrix grids with support for bipolar layout, transposed tables, multi-select checkboxes, and anchor labels.
 
-## Configuration Matrix (CRITICAL FOR PLANNING)
+## Statement & labels (CRITICAL)
 
-Your component architecture MUST account for the following boolean flags from `question`:
+| Mode | Left label | Right label | Column headers |
+|------|------------|-------------|----------------|
+| Likert | `statementText` (180px) | — | `scaleColumns[].label` when `showColumnHeaders` |
+| Bipolar | `statementText` (25%) | `oppositeStatementText` (25%) | anchor labels OR column headers |
+| Transposed | `scaleColumns[].label` as row | — | `statementRows[].statementText` as columns |
 
-### 1. `transposeTable`
-If `true`, the standard Row-by-Column matrix is inverted:
-- `question.columns` become the row labels on the left.
-- `question.rows` become the top column headers.
-- **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`.
+Use `dangerouslySetInnerHTML` for all statement/label HTML.
 
-### 2. `repeatScale`
-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>`.
+## Configuration Matrix
 
-### 3. `matrixType === 'bipolar'`
-Standard matrices (`'likert'`) only show statement text on the left. Bipolar scales show text on BOTH sides of the radio buttons.
-- **Implementation Strategy**: Render an extra `<td>` at the end of the row containing `row.rightText`.
-
-## UI/UX & Styling Constraints
-
-To match enterprise standards, implement the following UI strictly:
-
-1. **Row Tracking (Hover Effects)**:
-   - Every data `<tr>` MUST have `hover:bg-gray-50 transition-colors duration-150 group`. This is mandatory for UX on wide matrices.
-2. **Radio Buttons**:
-   - Use `accent-[#e20074] w-5 h-5 cursor-pointer` or build custom CSS circles that fill with the brand color.
-   - Do NOT use standard unstyled blue browser radios.
-3. **Tooltips (Accessibility)**:
-   - 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`.
+- **`transposeTable`**: swaps which array becomes grid rows vs columns
+- **`selectionMode: 'multiple'`**: checkboxes; answers are `string[]` per row
+- **`statementLayout: 'bipolar'`**: 25% | scale | 25% layout
+- **`scaleAnchorLabels`**: positioned above scale when bipolar or likert
 
 ## SDK Integration Checklist (agent)
 
+- [ ] Copied portable template
 - [ ] 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)
+- [ ] Answer: `MatrixRowAnswers` via `matrixColumnStoredValue(col)`
+- [ ] Visibility: `getVisibleMatrixItemsForAnswers(..., customFieldValues?)`
+- [ ] All row labels and header labels visible per ui-spec
+- [ ] Matrix row: [`question-type-sdk-matrix.md`](../00-integration/question-type-sdk-matrix.md)

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

@@ -1,56 +1,71 @@
 # Slider Matrix Architectural Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/09-slider-matrix.md`
-> **Reference implementation:** `apps/client/src/components/SliderMatrixScale.tsx`
+> **Portable template:** copy [`templates/SliderMatrixScale.tsx`](../templates/SliderMatrixScale.tsx) + [`CustomSliderTrack.tsx`](../templates/CustomSliderTrack.tsx) + [`surveyUiScaleUtils.ts`](../templates/surveyUiScaleUtils.ts)
 > **Target Component**: `SliderMatrixScale`
 > **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 `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`.
+Render one `CustomSliderTrack` per `statementRows[]` entry, with a shared header row of colored tick badges and optional anchor labels.
 
-## The "Thick Slider" UX Implementation (CRITICAL)
+## CRITICAL — Do NOT improvise
 
-Native `<input type="range">` elements are notoriously difficult to style consistently across browsers. You MUST implement the "Invisible Overlay" pattern to achieve the expected thick-track UI.
+- **Do NOT** build custom “thick slider” / invisible overlay range inputs
+- **Do NOT** use legacy field names (`rows`, `labels`, `tickValues`, `enableNotApplicable`, `sliderType`)
+- **Copy the portable template first**, then customize branding colors only
 
-### The Invisible Overlay Pattern
-For every slider row, build a relative container:
-1. **Base Track**: `absolute w-full h-2 bg-gray-200 rounded-full`.
-2. **Dynamic Fill Track**: `absolute h-2 bg-[#e20074] rounded-l-full`.
-   - Calculate width dynamically: `((value - min) / (max - min)) * 100 + '%'`.
-3. **The Thumb**: `absolute w-5 h-5 bg-[#e20074] border-2 border-white rounded-full shadow-md pointer-events-none transition-transform group-hover:scale-125`.
-   - Position it dynamically: `left: calc(${percentage}% - 10px)`.
-4. **The Input Control**: Layer a native input on top, completely invisible but clickable:
-   - `<input type="range" className="absolute w-full h-full opacity-0 cursor-pointer z-10" />`
+## SDK Fields (authoritative)
 
-## Configuration Matrix (CRITICAL FOR PLANNING)
+From `fetchSurvey/types/sliderMatrix.ts`:
 
-Your component must account for:
+| Field | UI role |
+|-------|---------|
+| `statementRows[]` | Row labels + per-row min/max/step |
+| `ticks.count` + `ticks.marks[]` | Header colored badges (`tickPosition`, `tickLabel`) |
+| `scaleAnchorLabels?` | Optional text labels above tick row |
+| `enableInputBox` | 80px numeric input + steppers |
+| `displayValues` | Pass to `CustomSliderTrack` |
+| `hasNotApplicableOption` | N/A checkbox column; answer value **`'N/A'`** string |
+| `sliderStyle?: 'graphics'` | Plain text ticks + emoji thumb via `CustomSliderTrack` |
 
-### 1. Exact Value Display
-- Users must see the exact number they are selecting.
-- Render a badge at the far right of the slider track: `shrink-0 w-8 text-center font-bold text-[#e20074]`.
+## Layout (matches reference)
 
-### 2. `row.ticks` & `tickValues`
-- If `question.ticks` or `row.tickValues` exists, you must render tiny vertical tick marks below the track at appropriate percentage intervals to guide the user.
+```
+[25% spacer] [scaleAnchorLabels?] [colored tick badges 0–10] [input spacer?] [N/A header?]
+┌─ gray row band #f3f4f6 ─────────────────────────────────────────────────────────────┐
+│ 25% statementText │ CustomSliderTrack │ 80px input? │ N/A checkbox? │
+└─────────────────────────────────────────────────────────────────────────────────────┘
+```
 
-### 3. Label Positioning
-- `row.minLabel` and `row.maxLabel` must be displayed directly underneath the far-left and far-right of the slider track using flexbox `justify-between text-xs text-gray-500`.
+## Statement text visibility
 
-### 4. `enableNotApplicable`
-- 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.
+- Render `row.statementText` with `dangerouslySetInnerHTML` in the **25% left column**
+- Skip rendering when text is empty or literal `"Question"` (placeholder from API)
+- **Never** omit the statement column — agents that put statement text in the question title only will fail multi-row surveys
+
+## Header tick badges
+
+```typescript
+const tickValues = ticks.marks.map((mark, index) => ({
+  value: mark.tickPosition,
+  label: mark.tickLabel,
+  color: tickColorFromIndex(index, ticks.count),
+}));
+const htmlStep = ticks.count > 1 ? (max - min) / (ticks.count - 1) : row.step;
+```
+
+## N/A behavior
+
+- Checked → store `'N/A'` string (not `null`)
+- Unchecked → reset to `row.defaultValue ?? row.min`
 
 ## SDK Integration Checklist (agent)
 
+- [ ] Copied `SliderMatrixScale.tsx`, `CustomSliderTrack.tsx`, `surveyUiScaleUtils.ts`
 - [ ] Type literal: `QUESTION_TYPE.SLIDER_MATRIX`
-- [ ] Answer stored as: `MatrixRowAnswers` — number or `null` per row
+- [ ] Answer: `MatrixRowAnswers` — `{ [rowId]: number | 'N/A' }`
 - [ ] onAction CHANGE: `{ questionId, answerValue: MatrixRowAnswers }`
-- [ ] Visibility helper: `getVisibleStatementRowsForAnswers(..., customFieldValues?)`
-- [ ] Use `CustomSliderTrack` when `sliderType === 'graphics'`
+- [ ] Visibility: `getVisibleStatementRowsForAnswers(..., customFieldValues?)`
+- [ ] Header row renders even for single-row questions
 - [ ] 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,67 +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.
 
-## 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.
+Render drag-and-drop zone, validate files locally, **upload via presigned URL**, then bubble `UploadedFileAnswer[]` via `onSelect`.
 
-### 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").
+## State Management
 
-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.
+- `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)`
 
-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.
+## Local validation (before upload)
 
-## Hidden Input
-- Include a hidden `<input type="file" multiple={question.maxFileCount > 1} accept={...} />` that is triggered via a `useRef` when the dropzone is clicked.
+Same as ui-spec: `supportedFileFormats`, `maxFileCount`, `fileSizeLimit` + `fileSizeLimitType`.
 
 ## 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
+- [ ] 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

@@ -1,38 +1,28 @@
 # Custom Slider Track Architectural Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/shared/custom-slider-track.md`
-> **Reference implementation:** `apps/client/src/components/CustomSliderTrack.tsx`
+> **Portable template:** copy [`templates/CustomSliderTrack.tsx`](../templates/CustomSliderTrack.tsx) + [`surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx)
 > **Target Component**: `CustomSliderTrack`
-> **Used By**: `SliderMatrixScale`, `CsatMatrixScale`, standalone `slider`
+> **Used By**: `SliderMatrixScale`, `CsatMatrixScale` (`displayStyle: graphics`)
 
 ## 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.
 
-## The Invisible Overlay Architecture (CRITICAL)
+Provide a styled range slider with optional emoji thumb (`sliderType: 'graphics'`). Used **inside** `SliderMatrixScale` and matrix graphics rows — not as a standalone question type.
 
-Instead of trying to style the `::-webkit-slider-thumb` pseudo-elements, you MUST build the slider using layered DOM elements.
+## CRITICAL — Copy template
 
-### Layer 1: The Background Track
-A static `<div>` representing the entire length of the slider.
-- CSS: `absolute w-full h-2 bg-gray-200 rounded-full`.
+Do not reimplement from this blueprint alone. Copy `templates/CustomSliderTrack.tsx` which implements the layered track + invisible range input pattern.
 
-### Layer 2: The Active Fill
-A dynamic `<div>` representing the portion of the slider up to the current value.
-- CSS: `absolute h-2 bg-[#e20074] rounded-l-full`.
-- Inline Style: `style={{ width: \`\${percentage}%\` }}`.
+## Pass tickLabels for matrix graphics
 
-### 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 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}%\` }}`.
+```typescript
+tickLabels={scaleColumns.map(col => col.label)}
+```
 
-### Layer 4: The Native Input (The Engine)
-An invisible native input overlaid exactly on top to capture all mouse/touch events automatically without needing manual math for drag interactions.
-- CSS: `<input type="range" className="absolute w-full h-full opacity-0 cursor-pointer z-10" />`.
-- This ensures perfect accessibility, keyboard navigation, and mobile touch support.
+Required for correct tooltip text on graphics sliders (RATING_MATRIX Page 11 fixture).
 
-## Configuration Logic
-- Calculate percentage carefully: `((value - min) / (max - min)) * 100`.
-- Ensure the custom thumb is negatively margined (e.g. `-ml-2.5` or `-ml-5`) so that its *center* aligns with the percentage point, not its left edge.
-- If `question.ticks` is provided, map out small `w-0.5 h-3 bg-gray-300` vertical lines below the track at the correct percentage intervals.
+## SDK Integration Checklist
+
+- [ ] Copied portable `CustomSliderTrack.tsx`
+- [ ] Used by `SliderMatrixScale` or `CsatMatrixScale` — not wired directly in `Question.tsx` for SLIDER_MATRIX
+- [ ] `hasSelectedValue`, `disabled`, `htmlStep` props wired correctly

package/templates/docs/01-components/10-header-footer.md

@@ -1,17 +1,36 @@
 # Theme & Logo Engineering Blueprint
 
 > **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
-> **Reference implementation:** `apps/client/src/components/Header.tsx`, `Footer.tsx`
+> **Wizard contract:** [`wizard-preview-build-guide.md`](../00-integration/wizard-preview-build-guide.md) — `data-cfm-*` + `var(--cfm-*)`
+> **Monorepo snapshot (do not copy):** `apps/client/src/components/Header.tsx`, `Footer.tsx`
 > **Target Components**: `Header`, `Footer`
 > **Handles**: Branding, Mockup Replication
 
 ## Core Responsibility
 When building the survey layout, the client will provide a text prompt or an image mockup. You MUST dynamically build the Theme and Logo using purely CSS and Tailwind to match the requested brand.
 
+## Sticky content chrome
+
+On the **content** phase, render `Header` inside `SurveyStickyChrome` with `embedded` so the wrapper owns the shadow:
+
+```tsx
+<Header embedded />
+```
+
+Use standalone `Header` (default, with shadow) on intro, end, paused, loading, and terminal pages. See `19-survey-sticky-chrome.md`.
+
 ## Logo Engineering Rules (CRITICAL)
-- **NO EXTERNAL IMAGES**: You are strictly forbidden from writing `<img src="url" />` for logos, because you do not have a CDN to host them.
-- **CSS-Only Logos**: You MUST construct the company logo using HTML and CSS primitives. 
-- Example: If the prompt shows the Telekom logo (a white 'T' inside a pink square, or distinct abstract shapes), you must build it using Flexbox, CSS shapes (`rounded-full`, `rounded-tr-3xl`, absolute positioning), and the exact brand colors (`bg-[#e20074] text-white`).
+
+Agents must implement **one** of these wizard-compatible patterns in `Header.tsx`:
+
+| Mode | When | Required markup |
+|------|------|-----------------|
+| **Image** | Brand asset in `public/` | `<img data-cfm-logo src="/exact-file.svg" />` plus hidden `<span data-cfm-logo-text>` fallback |
+| **Text** | CSS-only logo from prompt (no image file) | `<span data-cfm-logo-text>Company</span>` in logo slot — no `data-cfm-logo` img |
+
+- **NO EXTERNAL URLS** for logos (`https://…`).
+- **CSS-only logos** use `data-cfm-logo-text` (and optional CSS shapes) — wizard shows text until client uploads an image.
+- After wizard upload, saved `global.logo.fileName` is used on subsequent sessions — see `wizard-preview-build-guide.md`.
 
 ## Theme Engineering
 - Map the primary brand color to the accent and border colors across the entire survey.

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

@@ -20,20 +20,28 @@ export default function ProgressBar({ progressPercentage }: ProgressBarProps) {
   const width = Math.min(100, Math.max(0, progressPercentage));
 
   return (
-    <div className="mb-8 h-2 w-full overflow-hidden rounded-full bg-gray-100">
-      <div
-        className="h-full bg-[#e20074] transition-all duration-500 ease-out"
-        style={{ width: `${width}%` }}
-      />
+    <div className="w-full">
+      <div className="h-3 w-full rounded-full bg-gray-100">
+        <div
+          className="h-3 rounded-full bg-[#e20074] transition-all duration-300 ease-out"
+          style={{ width: `${width}%` }}
+        />
+      </div>
     </div>
   );
 }
 ```
 
+Vertical spacing (`pt-4` above, `pb-5` below) lives on the **`SurveyStickyChrome`** wrapper — not on `ProgressBar` itself.
+
 ## Wiring
 
+Place inside **`SurveyStickyChrome`** on the content phase (see `19-survey-sticky-chrome.md`):
+
 ```tsx
-<ProgressBar progressPercentage={state.progressPercentage} />
+<SurveyStickyChrome progressPercentage={state.progressPercentage} />
 ```
 
+Do not duplicate `ProgressBar` inside scrollable `<main>`.
+
 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,46 +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 `gridLayout === 'dropdown'` or `displayStyle === 'dropdown'`.
 
-Accepts `ScaleColumn[]`; emits stored column ids via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+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)
 
-## Props Interface
 ```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/17-heatmap-scale.md

@@ -2,7 +2,7 @@
 
 > **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`
+> **Portable coord helper:** copy [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts)
 > **Target Component**: `HeatmapScale`
 > **Handles**: `type: 'HEATMAP'`
 
@@ -15,8 +15,8 @@ Render the heatmap image, capture click spots in normalized 0–1 coordinates, t
 ```typescript
 type HeatmapScaleProps = {
   question: HeatmapQuestion;
-  selectedValue?: HeatmapAnswer;
-  onSelect: (answer: HeatmapAnswer | undefined) => void;
+  selectedValue?: HeatmapClickPoint[];
+  onSelect: (answer: HeatmapClickPoint[] | undefined) => void;
 };
 ```
 
@@ -34,7 +34,7 @@ type HeatmapScaleProps = {
 
 ## Coordinate Helpers
 
-Use `apps/client/src/lib/surveyUi/heatmapCoords.ts`:
+Copy [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts):
 
 - `getNormalizedClickFromImage(event, imageElement)`
 - `findSpotNearClick(clickX, clickY, spots, imageRect)`