@explorer02/cfm-survey-sdk 0.1.3 → 0.1.5

package/templates/docs/01-sdk-core/08-icons-and-emojis.md

@@ -0,0 +1,88 @@
+# Icons & Emojis — CSAT Visual System
+
+> **Source**: `packages/sdk/src/ui/icons.tsx`
+> **Exports**: `CsatEmojiSet`, `CsatEmojiMapping`, `CsatStarIcons`, `getEmojiForIndex`
+
+## What It Provides
+
+Pre-built React elements for CSAT satisfaction faces and star rating icons. These are used by `CsatScale`, `CsatMatrixScale`, and `CustomSliderTrack` components.
+
+## Emoji Face System (11-Level)
+
+The SDK ships an 11-level sentiment face scale using `react-icons/fa6`:
+
+| Index | Face | Color | Icon |
+|-------|------|-------|------|
+| 1 | Very Angry | `#dc2626` | FaFaceAngry |
+| 2 | Sad | `#e04832` | FaFaceSadTear |
+| 3 | Frown | `#ea580c` | FaFaceFrown |
+| 4 | Open Frown | `#f59e0b` | FaFaceFrownOpen |
+| 5 | Meh | `#eab308` | FaFaceMeh |
+| 6 | Neutral | `#a3a323` | FaFaceMeh |
+| 7 | Smile | `#84cc16` | FaFaceSmile |
+| 8 | Beam | `#65a30d` | FaFaceSmileBeam |
+| 9 | Grin | `#22c55e` | FaFaceGrin |
+| 10 | Wide Grin | `#16a34a` | FaFaceGrinWide |
+| 11 | Star-Struck | `#059669` | FaFaceGrinStars |
+
+## `getEmojiForIndex(index, total)` — Adaptive Mapping
+
+Maps a 0-based column index within a scale of `total` items to the correct face from the 11-level set.
+
+**Curated subsets for common scale lengths:**
+- 3 options → indices [3, 6, 8] from the 11-set
+- 4 options → indices [3, 4, 7, 9]
+- 5 options → indices [3, 4, 6, 7, 9]
+- 6 options → indices [3, 4, 6, 7, 9, 11]
+
+**For other lengths:** Interpolates linearly across the 11-set:
+```typescript
+const percent = index / (total - 1);
+const key = Math.min(11, Math.max(1, Math.round(percent * 10) + 1));
+```
+
+## `CsatEmojiMapping` — Legacy 1–5 Mapping
+
+For standalone 5-point CSAT scales:
+```typescript
+{ 1: Face[1], 2: Face[4], 3: Face[6], 4: Face[8], 5: Face[11] }
+```
+
+## `CsatStarIcons` — Star Rating
+
+```typescript
+{
+  filled: <FaStar style={{ color: '#e20074', fontSize: '28px' }} />,
+  empty: <FaRegStar style={{ color: '#d1d5db', fontSize: '28px' }} />,
+}
+```
+
+## Usage in Components
+
+```tsx
+import { getEmojiForIndex, CsatStarIcons, CsatEmojiMapping } from '@explorer02/cfm-survey-sdk';
+
+// CSAT Matrix — dynamic emoji per column
+{columns.map((col, i) => getEmojiForIndex(i, columns.length))}
+
+// CSAT Scale — star rendering
+{options.map((opt, i) => (
+  i < selectedIndex ? CsatStarIcons.filled : CsatStarIcons.empty
+))}
+
+// Standalone CSAT — legacy 1-5 emoji
+{CsatEmojiMapping[optionValue]}
+```
+
+## Important: `buttonType` Determines Rendering
+
+The `CsatQuestion.buttonType` and `MatrixQuestion.buttonType` fields control which icon system to use:
+
+| `buttonType` | Render Style |
+|-------------|-------------|
+| `'emoji'` | Sentiment face icons from `getEmojiForIndex` |
+| `'star'` | Star icons from `CsatStarIcons` |
+| `'numbered'` | Numeric badge buttons (no icons) |
+| `'radio'` | Standard radio circles |
+| `'graphics'` | Continuous slider with emoji thumb |
+| `'dropdown'` | Collapsed select dropdown |

package/templates/docs/01-sdk-core/README.md

@@ -0,0 +1,53 @@
+# SDK Core Architecture
+
+> This folder documents the internal architecture of `@explorer02/cfm-survey-sdk`.
+> Read these files **in order** to understand how the SDK processes a survey from network fetch to user submission.
+
+## Pipeline Overview
+
+```
+┌─────────────┐     ┌──────────────┐     ┌──────────────────┐     ┌─────────────┐
+│  Fetch API  │ ──→ │  Map Survey  │ ──→ │  Map Questions   │ ──→ │  Paginate   │
+│  (network)  │     │  (language)  │     │  (per-type)      │     │  (pages)    │
+└─────────────┘     └──────────────┘     └──────────────────┘     └─────────────┘
+                                                                        │
+                                                                        ▼
+┌─────────────┐     ┌──────────────┐     ┌──────────────────┐     ┌─────────────┐
+│  Submit     │ ←── │  Format Body │ ←── │  Validate        │ ←── │  Render UI  │
+│  (network)  │     │  (payload)   │     │  (required)      │     │  (React)    │
+└─────────────┘     └──────────────┘     └──────────────────┘     └─────────────┘
+```
+
+## Files in This Folder
+
+| File | Topic | When to Read |
+|------|-------|-------------|
+| `01-fetch-survey.md` | Network fetching, API endpoint, instanceId | **Always** — first step |
+| `02-survey-mapper.md` | Raw API → Survey object transformation | **Always** — understand data shape |
+| `03-question-mappers.md` | Question type dispatch, normalizeType | **Always** — core routing logic |
+| `04-pagination.md` | Page navigation, currentPageIndex | **Always** — state management |
+| `05-validation.md` | Required field validation, scroll-to-error | **Always** — UX critical |
+| `06-submit-survey.md` | Response submission, payload formatting | **Always** — submission pipeline |
+| `07-language-handling.md` | Translations, placeholders, language switching | When survey is multi-language |
+| `08-icons-and-emojis.md` | CSAT emoji faces, star icons | When CSAT/rating_scale types present |
+
+## The Single Hook: `useSurveySDK()`
+
+The entire SDK is consumed through **one hook**:
+
+```typescript
+import { useSurveySDK } from '@explorer02/cfm-survey-sdk';
+
+const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
+  options: {
+    instanceId: string,                    // JWT token from client
+    language: string | undefined,          // Active language code
+    placeholders: Record<string, string>,  // Token replacements
+    debug: boolean,                        // Console logging
+  }
+});
+```
+
+This hook internally composes: `useFetchSurvey` → `useSurveyPagination` → `useSubmitResponse` → `useSurveyProgress`.
+
+The client component **never** needs to import or call these internal hooks directly.

package/templates/docs/02-question-types/01-rating.md

@@ -0,0 +1,52 @@
+# Rating Question (NPS 0-10)
+
+> **Type**: `'rating'` | **API Source**: `SCALE` with `SCALE_TYPE=TEN_POINT` or `NPS_SCALE`
+> **Mapper**: `ratingMapper.ts` | **Component**: `RatingScale`
+
+## TypeScript Type
+
+```typescript
+type RatingQuestion = QuestionBase & {
+  type: 'rating';
+  options: SurveyOption[];       // 0-10 with NPS traffic-light colors
+  minLabel?: string;             // Left label (e.g. "Not Likely")
+  midLabel?: string;             // Middle label (e.g. "Neutral")
+  maxLabel?: string;             // Right label (e.g. "Extremely Likely")
+  midLabelIndex?: number;        // Fractional position for mid-label CSS
+  reverseScaleOrder?: boolean;   // Render high→low
+  buttonVariant?: 'radio' | 'numbered' | 'emoji';
+};
+```
+
+## Answer Shape: `number`
+Example: `7` (the selected badge value)
+
+## Options Auto-Generation
+If the API provides no explicit options, the SDK generates 0-10:
+```typescript
+Array.from({ length: 11 }, (_, i) => ({
+  id: String(i), label: String(i), value: i, color: getColor(i)
+}));
+```
+
+## NPS Traffic-Light Colors
+```
+0: #e2001a (red)     3: #f18b00 (orange)   6: #fcd900 (yellow)
+1: #e4251b           4: #f7b200            7: #9fca00 (lime)
+2: #ec610a           5: #fcd900            8: #6bb300 (green)
+                                            9: #339a00
+                                            10: #008000
+```
+
+## Mid-Label Positioning
+```typescript
+// CSS left percentage for mid-label
+const left = (midLabelIndex / (options.length - 1)) * 100;
+// For 11-point scale: midLabelIndex defaults to 7.5
+```
+
+## Rendering Guidance
+- Display as horizontal row of numbered badge buttons
+- Each badge uses `option.color` as background
+- Selected badge: emphasized border/scale, all others dimmed
+- Labels positioned: minLabel (left), midLabel (calculated %), maxLabel (right)

package/templates/docs/02-question-types/02-radio.md

@@ -0,0 +1,26 @@
+# Radio Question (MCQ)
+
+> **Type**: `'radio'` | **API Source**: `MCQ` (and any unrecognised answerType)
+> **Mapper**: `radioMapper.ts` | **Component**: Inline in `Question.tsx`
+
+## TypeScript Type
+
+```typescript
+type RadioQuestion = QuestionBase & {
+  type: 'radio';
+  options: SurveyOption[];     // Answer choices
+  isMultiSelect?: boolean;     // If true, answer is (string|number)[]
+};
+```
+
+## Answer Shape: `string | number`
+Example: `"option_1"` or `3`
+If `isMultiSelect: true` → `(string | number)[]`
+
+## Rendering Guidance
+- Render as card-style option list with radio circles
+- Each option: border card with custom radio indicator + label
+- Selected state: brand-color border + light tint background + filled dot
+- Use `<input type="radio" className="sr-only">` for accessibility
+- Labels use `dangerouslySetInnerHTML` (may contain HTML)
+- `onChange={() => onSelect(option.value)}`

package/templates/docs/02-question-types/03-text.md

@@ -0,0 +1,26 @@
+# Text Question (Free Text)
+
+> **Type**: `'text'` | **API Source**: `TEXTFIELD`
+> **Mapper**: `textMapper.ts` | **Component**: Inline in `Question.tsx`
+
+## TypeScript Type
+
+```typescript
+type TextQuestion = QuestionBase & {
+  type: 'text';
+  maxCharacterCount?: number;    // Character limit
+  placeholder?: string;         // Input placeholder text
+  inputVariant?: 'short' | 'long';  // Single-line vs textarea
+};
+```
+
+## Answer Shape: `string`
+Example: `"Great customer service, very satisfied"`
+
+## Rendering Guidance
+- `inputVariant === 'short'` → `<input type="text">`, `inputVariant === 'long'` → `<textarea rows={4}>`
+- Default to `<textarea>` if `inputVariant` is not specified
+- Show character counter: `maxCharacterCount - currentLength` remaining
+- `onChange={e => onSelect(e.target.value)}`
+- Use `question.placeholder` or fallback: `"Type your response here..."`
+- Focus state: brand-color border + ring

package/templates/docs/02-question-types/04-csat.md

@@ -0,0 +1,54 @@
+# CSAT Question (Satisfaction Scale)
+
+> **Type**: `'csat'` | **API Source**: `SCALE` with `SCALE_TYPE=CSAT` or ≤5 options
+> **Mapper**: `ratingMapper.ts` (CSAT branch) | **Component**: `CsatScale`
+
+## TypeScript Type
+
+```typescript
+type CsatQuestion = QuestionBase & {
+  type: 'csat';
+  options: SurveyOption[];          // Usually 1-5 satisfaction levels
+  minLabel?: string;                // "Very Dissatisfied"
+  maxLabel?: string;                // "Very Satisfied"
+  buttonType?: SurveyButtonType;    // 'emoji' | 'star' | 'numbered' | 'radio'
+  hasNotApplicable?: boolean;       // N/A option available
+  reverseScaleOrder?: boolean;      // Render high→low
+  labelPosition?: 'top' | 'bottom' | 'hidden';
+};
+```
+
+## Answer Shape: `number | null`
+Example: `4` or `null` (N/A selected)
+
+## Rendering by `buttonType`
+
+| `buttonType` | Render As |
+|-------------|-----------|
+| `'emoji'` | Sentiment face icons from `CsatEmojiMapping` |
+| `'star'` | Star icons from `CsatStarIcons` (filled/empty) |
+| `'numbered'` | Numeric badge buttons |
+| `'radio'` | Standard radio circles |
+| `'graphics'` | Emoji slider (use `CustomSliderTrack`) |
+
+## Star Rating Pattern
+```tsx
+{options.map((opt, i) => {
+  const numericValue = typeof opt.value === 'number' ? opt.value : i + 1;
+  const isActive = typeof selectedValue === 'number' && numericValue <= selectedValue;
+  return (
+    <button onClick={() => onSelect(opt.value)}>
+      {isActive ? CsatStarIcons.filled : CsatStarIcons.empty}
+    </button>
+  );
+})}
+```
+
+## Emoji Pattern
+```tsx
+{options.map((opt, i) => (
+  <button onClick={() => onSelect(opt.value)}>
+    {CsatEmojiMapping[typeof opt.value === 'number' ? opt.value : i + 1]}
+  </button>
+))}
+```

package/templates/docs/02-question-types/05-rating-scale.md

@@ -0,0 +1,26 @@
+# Rating Scale Question (Stars/Emoji)
+
+> **Type**: `'rating_scale'` | **API Source**: `SCALE` with `SCALE_TYPE=STAR/EMOJI/FIVE_POINT`
+> **Mapper**: `ratingMapper.ts` (rating_scale branch) | **Component**: `RatingScale`
+
+## TypeScript Type
+
+```typescript
+type RatingScaleQuestion = QuestionBase & {
+  type: 'rating_scale';
+  options: SurveyOption[];     // Typically 1-5 or 1-10 (no NPS colors)
+  minLabel?: string;
+  midLabel?: string;
+  maxLabel?: string;
+  midLabelIndex?: number;
+  reverseScaleOrder?: boolean;
+  scaleStyle?: 'star' | 'emoji';
+};
+```
+
+## Answer Shape: `number`
+
+## Key Difference from `'rating'`
+- No NPS traffic-light colors on options
+- Rendered as stars, emojis, or plain icons — not numbered badges
+- Use `scaleStyle` to determine icon type

package/templates/docs/02-question-types/06-slider.md

@@ -0,0 +1,30 @@
+# Slider Question (Single Range)
+
+> **Type**: `'slider'` | **API Source**: `SCALE` with `INPUT_TYPE=SLIDER`
+> **Mapper**: `ratingMapper.ts` (slider branch) | **Component**: `CustomSliderTrack` or native `<input type="range">`
+
+## TypeScript Type
+
+```typescript
+type SliderQuestion = QuestionBase & {
+  type: 'slider';
+  min: number;              // Left end value
+  max: number;              // Right end value
+  step: number;             // Increment between positions
+  defaultValue?: number;    // Initial handle position
+  minLabel?: string;        // Left label
+  maxLabel?: string;        // Right label
+  enableInputBox?: boolean; // Show numeric input alongside
+  displayValues?: boolean;  // Show value tooltip on thumb
+};
+```
+
+## Answer Shape: `number`
+Example: `65`
+
+## Rendering Guidance
+- Use `<input type="range" min={min} max={max} step={step}>`
+- Or use the `CustomSliderTrack` component for emoji-thumb variant
+- Show labels at min/max ends
+- If `enableInputBox` → show numeric `<input type="number">` alongside
+- If `displayValues` → show floating tooltip showing current value

package/templates/docs/02-question-types/07-matrix-cfm.md

@@ -0,0 +1,43 @@
+# Matrix CFM Question (Likert Grid)
+
+> **Type**: `'matrix'` with `subType: 'CFM_MATRIX'` | **API Source**: `CFM_MATRIX`
+> **Mapper**: `cfmMatrixMapper.ts` | **Component**: `LikertMatrixScale`
+
+## TypeScript Type
+
+```typescript
+type MatrixQuestion = QuestionBase & {
+  type: 'matrix';
+  subType: 'CFM_MATRIX';
+  rows: MatrixRow[];              // Statements to rate
+  columns: MatrixColumn[];        // Shared answer options per row
+  buttonType?: SurveyButtonType;
+  hasNotApplicable?: boolean;
+  reverseScaleOrder?: boolean;
+  labels?: string[];              // Anchor labels above columns
+  matrixFormat?: 'standard' | 'carousel' | 'dropdown';
+  matrixType?: 'likert' | 'bipolar';
+  answerType?: 'single' | 'multiple';
+  transposeTable?: boolean;
+  repeatScale?: boolean;
+  enableScale?: boolean;
+};
+
+type MatrixRow = { id: string; text: string; rightText?: string; };
+type MatrixColumn = { id: string; label: string; value: string | number | null; color?: string; };
+```
+
+## Answer Shape: `MatrixAnswerMap`
+```typescript
+{ "row1_id": "column_value", "row2_id": "column_value", "row3_id": null }
+// null = N/A selected for that row
+```
+
+## Rendering Guidance
+- **Standard format**: Grid table — rows on left, columns as headers
+- **Carousel format**: Show one row at a time with prev/next
+- **Dropdown format**: Each row has a dropdown selector for its column value
+- Likert: unipolar text labels (e.g. "Strongly Disagree" → "Strongly Agree")
+- Bipolar: `row.text` on left + `row.rightText` on right
+- If `hasNotApplicable` → add N/A column with `value: null`
+- `onSelect` receives the full `MatrixAnswerMap` object on each change

package/templates/docs/02-question-types/08-matrix-csat.md

@@ -0,0 +1,29 @@
+# Matrix CSAT Question (Satisfaction Grid)
+
+> **Type**: `'matrix'` with `subType: 'CSAT_MATRIX'` | **API Source**: `CSAT_MATRIX`
+> **Mapper**: `csatMatrixMapper.ts` | **Component**: `CsatMatrixScale`
+
+## TypeScript Type
+Same as `MatrixQuestion` (see `07-matrix-cfm.md`) but with `subType: 'CSAT_MATRIX'`.
+
+## Key Difference from CFM_MATRIX
+- Columns represent satisfaction levels (not text labels)
+- Uses `buttonType` to determine visual: emoji faces, stars, numbered, etc.
+- Uses `getEmojiForIndex(colIndex, totalCols)` for emoji rendering per cell
+
+## Rendering by `buttonType`
+
+| `buttonType` | Cell Rendering |
+|-------------|---------------|
+| `'emoji'` | Sentiment face icons via `getEmojiForIndex` |
+| `'star'` | Star icons via `CsatStarIcons` |
+| `'numbered'` | Numeric badge buttons |
+| `'radio'` | Standard radio circles |
+| `'dropdown'` | Dropdown per row (uses `MatrixDropdown`) |
+| `'graphics'` | Emoji slider per row (uses `CustomSliderTrack`) |
+
+## Answer Shape: `MatrixAnswerMap`
+Same as CFM_MATRIX — `{ "row_id": column_value | null }`
+
+## N/A Column
+If `hasNotApplicable` is true, the last column has `value: null`. Selecting it records `null` for that row, which is a valid answer (passes validation).

package/templates/docs/02-question-types/09-matrix-rating.md

@@ -0,0 +1,28 @@
+# Rating Matrix Question
+
+> **Type**: `'rating_matrix'` | **API Source**: `RATING_MATRIX`
+> **Mapper**: `ratingMatrixMapper.ts` → routed to `mapMatrixQuestion` | **Component**: `CsatMatrixScale`
+
+## TypeScript Type
+
+```typescript
+type RatingMatrixQuestion = QuestionBase & {
+  type: 'rating_matrix';
+  rows: MatrixRow[];
+  columns: MatrixColumn[];       // Rating columns with NPS-style colors
+  minLabel?: string;
+  maxLabel?: string;
+  buttonType?: SurveyButtonType;
+  hasNotApplicable?: boolean;
+  reverseScaleOrder?: boolean;
+  labels?: string[];
+};
+```
+
+## Key Difference from CSAT_MATRIX
+- Columns carry traffic-light `color` values (like NPS rating)
+- Has `minLabel`/`maxLabel` endpoint labels
+- Rendered by the same `CsatMatrixScale` component
+
+## Answer Shape: `MatrixAnswerMap`
+Same pattern: `{ "row_id": column_value | null }`

package/templates/docs/02-question-types/10-slider-matrix.md

@@ -0,0 +1,40 @@
+# Slider Matrix Question
+
+> **Type**: `'slider_matrix'` | **API Source**: `SLIDER_MATRIX`
+> **Mapper**: `sliderMatrixMapper.ts` | **Component**: `SliderMatrixScale`
+
+## TypeScript Type
+
+```typescript
+type SliderMatrixQuestion = QuestionBase & {
+  type: 'slider_matrix';
+  rows: SliderMatrixRow[];       // Each row has independent slider config
+  labels?: string[];             // Anchor labels above track
+  ticks?: number;                // Number of tick marks (default 10)
+  tickValues?: TickValue[];      // Pre-calculated tick values with colors
+  enableInputBox?: boolean;
+  displayValues?: boolean;
+  enableNotApplicable?: boolean;
+  sliderType?: 'graphics';       // Emoji thumb slider
+};
+
+type SliderMatrixRow = MatrixRow & {
+  min: number; max: number; step: number; defaultValue?: number;
+};
+
+type TickValue = { value: number; label: string; color: string; };
+```
+
+## Answer Shape: `MatrixAnswerMap`
+```typescript
+{ "row1_id": 75, "row2_id": 30, "row3_id": null }
+// number = slider position, null = N/A
+```
+
+## Rendering Guidance
+- Each row: row label + independent range slider
+- If `sliderType === 'graphics'` → use `CustomSliderTrack` (emoji thumb)
+- If `tickValues` available → render tick marks with labels and colors
+- If `enableInputBox` → show numeric input alongside slider
+- If `enableNotApplicable` → add N/A checkbox per row
+- `onSelect` receives the full `MatrixAnswerMap` with all row values

package/templates/docs/02-question-types/11-file-upload.md

@@ -0,0 +1,34 @@
+# File Upload Question
+
+> **Type**: `'file_upload'` | **API Source**: `FILE_UPLOAD`
+> **Mapper**: `fileUploadMapper.ts` | **Component**: `FileUploadScale`
+
+## TypeScript Type
+
+```typescript
+type FileUploadQuestion = QuestionBase & {
+  type: 'file_upload';
+  uploadMessage?: string;              // Instruction text (HTML)
+  supportedFileFormats?: string[];     // ['PDF', 'PNG', 'DOCX'] (uppercase, no dots)
+  maxFileCount?: number;               // Max files allowed
+  fileSizeLimit?: number;              // Max size in MB
+  fileSizeLimitType?: 'PER_FILE' | 'IN_TOTAL';
+};
+
+type UploadedFile = {
+  id: string; name: string; mediaUrl: string;
+  mimeType?: string; size?: number;
+};
+```
+
+## Answer Shape: `UploadedFile[]`
+Array of uploaded file descriptors. Submitted via `quesIdVsAttachmentDetails` (NOT `questionToAnswers`).
+
+## Rendering Guidance
+- Drag-and-drop zone + click-to-upload button
+- Show accepted formats from `supportedFileFormats`
+- Set `<input type="file" accept=".pdf,.png,.docx">`
+- Enforce `maxFileCount` in UI
+- Show file list with name, size, and remove button
+- Enforce `fileSizeLimit` with appropriate error messages
+- `onSelect` receives the full `UploadedFile[]` array

package/templates/docs/02-question-types/12-text-and-media.md

@@ -0,0 +1,35 @@
+# Text and Media Question (Display-Only)
+
+> **Type**: `'text_and_media'` | **API Source**: `TEXT_AND_MEDIA`
+> **Mapper**: `textAndMediaMapper.ts` | **Component**: Inline in `Question.tsx`
+
+## TypeScript Type
+
+```typescript
+type TextAndMediaQuestion = QuestionBase & {
+  type: 'text_and_media';
+  mediaUrl?: string;             // Image or video URL
+  mediaMimeType?: string;        // 'image/*' or 'video/*'
+  mediaTitle?: string;           // Caption/alt text
+  mediaAlignment?: string;       // Layout position
+  mediaSize?: number;            // Width percentage
+};
+```
+
+## Answer Shape: NONE
+This is **display-only** — no answer is collected.
+
+## ⚠️ Critical Rules
+- **DO NOT** dispatch a `CHANGE` action for this question type
+- **Excluded** from validation (always passes)
+- **Excluded** from progress percentage counting
+- **Skipped** in `buildSubmitRequestBody()` — nothing is submitted
+
+## Rendering Guidance
+- Show `question.text` as the heading
+- If `mediaUrl` exists:
+  - `mediaMimeType` starts with `'video/'` → `<video controls src={mediaUrl}>`
+  - Otherwise → `<img src={mediaUrl} alt={mediaTitle}>`
+- Position media according to `mediaAlignment`
+- Size media according to `mediaSize` percentage
+- Show `mediaTitle` as caption below media

package/templates/docs/02-question-types/README.md

@@ -0,0 +1,74 @@
+# Question Types Overview
+
+> This folder contains one detailed doc per question type. Each doc covers: TypeScript type, mapper logic, answer shape, properties, and rendering guidance.
+
+## The `SurveyQuestion` Discriminated Union
+
+The SDK maps API questions into a **discriminated union** using the `type` field:
+
+```typescript
+type SurveyQuestion =
+  | RatingQuestion        // type: 'rating'       — NPS 0-10 numeric scale
+  | RadioQuestion         // type: 'radio'        — MCQ single/multi select
+  | TextQuestion          // type: 'text'         — Free text input
+  | CsatQuestion          // type: 'csat'         — 1-5 satisfaction (emoji/star)
+  | RatingScaleQuestion   // type: 'rating_scale' — Star/emoji rating (1-5/1-10)
+  | SliderQuestion        // type: 'slider'       — Single range slider
+  | MatrixQuestion        // type: 'matrix'       — Grid (CFM/CSAT/RATING subTypes)
+  | RatingMatrixQuestion  // type: 'rating_matrix' — NPS-style rating grid
+  | SliderMatrixQuestion  // type: 'slider_matrix' — Grid of range sliders
+  | FileUploadQuestion    // type: 'file_upload'  — File attachment
+  | TextAndMediaQuestion; // type: 'text_and_media' — Display-only media card
+```
+
+## Question → Component Routing Table
+
+| `question.type` | `question.subType` | Client Component | Answer Shape |
+|-----------------|-------------------|-----------------|-------------|
+| `'rating'` | — | `RatingScale` | `number` |
+| `'radio'` | — | Inline radio cards | `string \| number` |
+| `'text'` | — | Inline textarea | `string` |
+| `'csat'` | — | `CsatScale` | `number \| null` |
+| `'rating_scale'` | — | `RatingScale` (star/emoji variant) | `number` |
+| `'slider'` | — | `CustomSliderTrack` | `number` |
+| `'matrix'` | `'CFM_MATRIX'` | `LikertMatrixScale` | `MatrixAnswerMap` |
+| `'matrix'` | `'CSAT_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` |
+| `'matrix'` | `'RATING_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` |
+| `'rating_matrix'` | — | `CsatMatrixScale` | `MatrixAnswerMap` |
+| `'slider_matrix'` | — | `SliderMatrixScale` | `MatrixAnswerMap` |
+| `'file_upload'` | — | `FileUploadScale` | `UploadedFile[]` |
+| `'text_and_media'` | — | Inline media card | (no answer) |
+
+## Shared Base Properties
+
+All question types extend `QuestionBase`:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | ⚠️ MUST be DOM element id |
+| `text` | `string` | Question text (may contain HTML) |
+| `description` | `string?` | Supplementary instruction (HTML) |
+| `required` | `boolean?` | Mandatory answer flag |
+| `requiredErrorMessage` | `string?` | Custom validation error |
+| `questionNumber` | `number?` | 1-indexed ordinal |
+| `containerMediaUrl` | `string?` | Image/video alongside question |
+| `containerMediaMimeType` | `string?` | MIME type for container media |
+| `containerMediaAlignment` | `string?` | Media layout position |
+| `containerMediaSize` | `number?` | Media width percentage |
+
+## Files in This Folder
+
+| File | Question Type | API Source |
+|------|-------------|-----------|
+| `01-rating.md` | `RatingQuestion` | `SCALE` (NPS/TEN_POINT) |
+| `02-radio.md` | `RadioQuestion` | `MCQ` |
+| `03-text.md` | `TextQuestion` | `TEXTFIELD` |
+| `04-csat.md` | `CsatQuestion` | `SCALE` (CSAT, ≤5 options) |
+| `05-rating-scale.md` | `RatingScaleQuestion` | `SCALE` (STAR/EMOJI) |
+| `06-slider.md` | `SliderQuestion` | `SCALE` (INPUT_TYPE=SLIDER) |
+| `07-matrix-cfm.md` | `MatrixQuestion` CFM | `CFM_MATRIX` |
+| `08-matrix-csat.md` | `MatrixQuestion` CSAT | `CSAT_MATRIX` |
+| `09-matrix-rating.md` | `RatingMatrixQuestion` | `RATING_MATRIX` |
+| `10-slider-matrix.md` | `SliderMatrixQuestion` | `SLIDER_MATRIX` |
+| `11-file-upload.md` | `FileUploadQuestion` | `FILE_UPLOAD` |
+| `12-text-and-media.md` | `TextAndMediaQuestion` | `TEXT_AND_MEDIA` |