@explorer02/cfm-survey-sdk 0.1.7 → 0.1.9

package/templates/docs/index.md

@@ -1,149 +1,109 @@
 # CFM SURVEY SDK — AGENT DOCUMENTATION INDEX
 
-**@explorer02/cfm-survey-sdk**
+**@explorer02/cfm-survey-sdk** (npm) · **@repo/sdk** (monorepo)
 
-This file is the MASTER GUIDE for AI coding agents (Cursor, Copilot, etc.).
-It is a structured roadmap that tells the agent exactly which documentation files to read and in what order.
+Master guide for AI coding agents. Machine-readable index: `MANIFEST.json`.
 
-## ── HOW THIS DOCUMENTATION SYSTEM WORKS ──────────────────────────────────────
-
-The `docs/` folder mirrors the SDK's internal architecture:
+## Documentation Layout
 
 ```
 docs/
-├── index.md                    ← YOU ARE HERE — read this first
-├── 01-sdk-core/                ← SDK internals: fetch, map, paginate, validate, submit
-├── 02-question-types/          ← One doc per question type (12 types)
-├── 03-client-components/       ← One doc per UI component (13 components)
-└── 04-critical-rules/          ← Non-negotiable constraints, imports, troubleshooting
+├── index.md                 ← YOU ARE HERE
+├── MANIFEST.json            ← Phase + question-type routing (for tooling)
+├── 00-integration/          ← Setup, hook contract, constraints
+├── 01-components/           ← UI blueprints (read ALL before coding)
+├── 02-reference/            ← Routing table + question-type data (on demand)
+└── templates/
+    └── implementation_plan.md
 ```
 
-## ── CLIENT INTERACTION FLOW (3 INPUTS ONLY) ──────────────────────────────────
-
-The entire build process requires EXACTLY 3 inputs from the client:
-
-**INPUT 1: Client's initial prompt**
-→ "Build a survey like this image using @explorer02/cfm-survey-sdk"
-→ May include UI mockup screenshots, brand colors, or text description
-→ Agent begins project scaffolding and component architecture
-
-**INPUT 2: Instance ID (agent asks for it)**
-→ Agent asks: "Please provide your survey instance ID (JWT token)"
-→ Client pastes the instanceId string
-→ Agent wires it into SurveyPage.tsx and fetches the survey
-
-**INPUT 3: Deployment confirmation (agent asks at the end)**
-→ Agent asks: "Your survey is built and tested. Ready to deploy to Vercel?"
-→ Client confirms → Agent runs `npx vercel --prod --yes`
-
-## ── EXECUTION PIPELINE ───────────────────────────────────────────────────────
-
-Follow these phases IN ORDER. Each phase references specific doc files.
-
-### PHASE 1: PROJECT SCAFFOLDING
-Read: `04-critical-rules/01-import-rules.md`
-
-Actions:
-1. Create Next.js project:
-   `npx -y create-next-app@latest ./ --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm`
-2. Install SDK:
-   `npm install @explorer02/cfm-survey-sdk @tanstack/react-query`
-3. Configure `next.config.js`:
-   `transpilePackages: ["@explorer02/cfm-survey-sdk"]`
-
-### PHASE 2: ASK FOR INSTANCE ID (INPUT 2)
-Read: `01-sdk-core/01-fetch-survey.md`
-
-Ask the client in chat:
-"Please provide your survey instance ID (the JWT token string) so I can connect your survey."
-
-Wait for the client to paste the instanceId. Store it — you will wire it into SurveyPage.tsx in Phase 4.
-
-### PHASE 3: UNDERSTAND THE SDK PIPELINE
-Read these docs IN ORDER to understand how the SDK works:
-
-1. `01-sdk-core/01-fetch-survey.md`    — How survey data is fetched
-2. `01-sdk-core/02-survey-mapper.md`   — How raw API → Survey object
-3. `01-sdk-core/03-question-mappers.md` — How questions are typed/mapped
-4. `01-sdk-core/07-language-handling.md` — Translations & placeholders
-5. `01-sdk-core/04-pagination.md`      — Page navigation state
-6. `01-sdk-core/05-validation.md`      — Required field validation
-7. `01-sdk-core/06-submit-survey.md`   — Response submission format
-8. `01-sdk-core/08-icons-and-emojis.md` — CSAT emoji/star icon system
-
-Then understand what question types exist:
-9. `02-question-types/README.md`       — Overview of all 12 types
-
-*You do NOT need to read every question type doc upfront. Read them ON DEMAND when you encounter each type during component building.*
-
-### PHASE 4: UI ARCHITECTURE PLANNING (CRITICAL)
-Before writing any React code, you MUST enter Planning Mode and generate an `implementation_plan.md`.
-
-Read the component architectural blueprints IN ORDER:
-1. `03-client-components/README.md`        — File structure overview
-2. `03-client-components/01-survey-page.md` — MAIN orchestrator
-3. `03-client-components/02-question.md`    — Question dispatcher
-4. `03-client-components/10-header-footer.md` — CSS-built logo/branding/themes
-5. `03-client-components/11-progress-bar.md`  — Progress indicator
-6. `03-client-components/12-language-selector.md` — Language dropdown
-
-Then, for EACH question type present in the fetched survey, read its matching UI Blueprint:
-- **Rating**: `03-client-components/03-rating-scale.md`
-- **CSAT**: `03-client-components/04-csat-scale.md`
-- **CSAT Matrix**: `03-client-components/05-csat-matrix-scale.md`
-- **Likert Matrix**: `03-client-components/06-likert-matrix-scale.md`
-- **Slider Matrix**: `03-client-components/07-slider-matrix-scale.md`
-- **File Upload**: `03-client-components/08-file-upload-scale.md`
-- **Sliders**: `03-client-components/09-custom-slider-track.md`
-
-Your `implementation_plan.md` MUST be structured professionally and precisely cover:
-1. **Data Fetching & State**: How you will integrate `useSurveySDK(instanceId)` and handle loading/errors.
-2. **Pagination & Navigation**: How you will iterate through pages, manage `handleNext`, `handleBack`, `handleAction`, and progress tracking.
-3. **Question Dispatching**: How `Question.tsx` will route types and handle rich text rendering safely.
-4. **Question Architectures & Configs**: How you will implement complex UI exactly as prescribed (e.g., matrix transposition, slider invisible overlays, CSAT bounding boxes, file size constraints).
-5. **Theme & Logo Engineering**: How you will map the mockups to CSS-only logos and Tailwind themes.
-6. **Submission**: How you will trigger `submitSurvey` and route to the Thank You screen.
-
-**ACTION**: Generate the `implementation_plan.md`. Once the plan is written, **DO NOT WAIT FOR APPROVAL**. Automatically trigger Phase 5 and begin writing the React components immediately!
-
-Then for EACH question type present in the fetched survey, read the matching question-type doc AND component doc:
-
-| `question.type` | Question Doc | Component Doc |
-|---|---|---|
-| `'rating'` | `02-question-types/01-rating` | `03-components/03-rating` |
-| `'radio'` | `02-question-types/02-radio` | (inline in Question) |
-| `'text'` | `02-question-types/03-text` | (inline in Question) |
-| `'csat'` | `02-question-types/04-csat` | `03-components/04-csat` |
-| `'rating_scale'` | `02-question-types/05-rating-s` | `03-components/03-rating` |
-| `'slider'` | `02-question-types/06-slider` | `03-components/09-slider` |
-| `'matrix'` CFM | `02-question-types/07-matrix-c` | `03-components/06-likert` |
-| `'matrix'` CSAT | `02-question-types/08-matrix-c` | `03-components/05-csat-m` |
-| `'matrix'` RATING| `02-question-types/09-matrix-r` | `03-components/05-csat-m` |
-| `'slider_matrix'`| `02-question-types/10-slider-m` | `03-components/07-slider` |
-| `'file_upload'` | `02-question-types/11-file-up` | `03-components/08-file` |
-| `'text_and_media'`| `02-question-types/12-text-med` | (inline in Question) |
-
-Also read these shared component docs:
-- `03-client-components/09-custom-slider-track.md` (used by CSAT matrix, slider matrix when sliderType='graphics')
-- `03-client-components/13-matrix-dropdown.md` (used by matrix dropdown fmt)
-
-### PHASE 5: APPLY CRITICAL RULES
-Read ALL files in `04-critical-rules/`:
-1. `01-import-rules.md`       — Package imports, 'use client', Suspense
-2. `02-action-dispatching.md` — onAction pattern, placeholder constants
-3. `03-scroll-navigation.md`  — id={question.id} requirement
-4. `04-logo-branding.md`      — CSS-only logo, no external image needed
-5. `05-troubleshooting.md`    — Common build errors and fixes
-
-Verify your implementation against every rule before proceeding.
-
-### PHASE 6: BUILD VERIFICATION
-1. Run: `npm run build`
-2. If errors → fix automatically → re-run until clean
-3. Run: `npm run dev`
-4. Verify: survey loads, navigation works, validation fires, submit works
-
-### PHASE 7: DEPLOYMENT (INPUT 3)
-Ask the client: "Your survey is built and verified. Ready to deploy to Vercel?"
-If yes → run: `npx vercel --prod --yes`
-Report the final deployment URL to the client.
+**Import rule:** Use whatever package name appears in the project's `package.json` (`@explorer02/cfm-survey-sdk` or `@repo/sdk`).
+
+---
+
+## Client Inputs (3 only)
+
+1. **Initial prompt** — mockup, brand colors, layout preferences
+2. **Instance ID** — JWT token (agent asks in chat)
+3. **Deploy confirmation** — yes/no for production deploy
+
+**Branding comes from INPUT 1 only.** No setup wizard. No `survey-config.json`.
+
+---
+
+## Execution Pipeline
+
+### PHASE 0: ORIENT
+
+- Read this file and `AGENT.md`
+- Detect framework: read `package.json` — Next.js / Vite / CRA (see `00-integration/setup.md`)
+- Extract branding and layout from client prompt
+- For existing apps: read project structure; do not blindly scaffold
+
+### PHASE 1: SCAFFOLD
+
+Read: `00-integration/setup.md` (matching framework section)
+
+Install SDK + `@tanstack/react-query` + `react-icons`. Apply framework-specific config.
+
+### PHASE 2: INSTANCE ID (INPUT 2)
+
+Read: `00-integration/useSurveySDK.md`
+
+Ask: *"Please provide your survey instance ID (JWT token)."*
+
+### PHASE 3: SDK CONTRACT
+
+Read: `00-integration/useSurveySDK.md`
+
+Understand `useSurveySDK`, `onAction`, states. Do **not** read internal mapper/source paths.
+
+Optional: read `02-reference/routing-table.md` for type overview.
+
+### PHASE 4: PLAN + INGEST (CRITICAL)
+
+1. Read **every** file in `01-components/` (all 14 blueprints)
+2. Copy `docs/templates/implementation_plan.md` → `./implementation_plan.md`
+3. Fill every section — do **not** invent a different structure
+4. **Auto-proceed to Phase 5** — do not wait for approval
+
+For each question type in the fetched survey, also read matching docs from `02-reference/question-types/` (see `MANIFEST.json` or `02-reference/routing-table.md`).
+
+### PHASE 5: BUILD
+
+Read: `00-integration/constraints.md`
+
+Implement components per blueprints. Use exported types:
+
+```typescript
+import { useSurveySDK, ACTIONS, type SurveyAction } from '@explorer02/cfm-survey-sdk';
+```
+
+### PHASE 6: VERIFY
+
+Read: `00-integration/constraints.md` (troubleshooting)
+
+Checklist:
+
+- [ ] `Question.tsx` switch covers all 12 `question.type` values
+- [ ] Every question wrapper has `id={question.id}`
+- [ ] No imports from `@explorer02/cfm-survey-sdk/src/...`
+- [ ] `SurveyPage` handles loading / error / empty / submitted / active
+- [ ] `npm run build` exits 0
+
+### PHASE 7: DEPLOY (INPUT 3)
+
+Ask: *"Your survey is built and verified. Ready to deploy?"*
+
+If yes: `npx cfm-sdk deploy` (preferred) or `npx vercel --prod --yes`
+
+---
+
+## Progressive Reading Guide
+
+| When | Read |
+|------|------|
+| Always first | `index.md`, `00-integration/setup.md`, `00-integration/useSurveySDK.md`, `00-integration/constraints.md` |
+| Before any React code | All `01-components/*.md` |
+| On demand | `02-reference/question-types/<type>.md` for types in survey |
+| Tooling | `MANIFEST.json`, `templates/implementation_plan.md` |

package/templates/docs/templates/implementation_plan.md

@@ -0,0 +1,78 @@
+# Survey UI Implementation Plan
+
+> Copy this file to `./implementation_plan.md` in the project root. Fill every section before writing React code.
+
+## 0. Project Context
+
+- **Framework:** [ ] Next.js App Router  [ ] Vite  [ ] CRA  [ ] Existing app
+- **Package import name:** (from `package.json` — `@explorer02/cfm-survey-sdk` or `@repo/sdk`)
+- **instanceId:** (JWT — wired in SurveyPage)
+- **Branding source:** (client prompt / mockup description — no wizard)
+
+## 1. Data Fetching & State
+
+- [ ] `useSurveySDK` options: instanceId, language, placeholders, debug
+- [ ] `SurveyPage` 5-state machine: loading / error / empty / submitted / active
+- [ ] `surveyQueryResults.isLoading`, `.error`, `.data` handling
+- [ ] `submitSurveyResults.isLoading`, `.error`, `.data` handling
+
+## 2. Pagination, Actions & Flow
+
+- [ ] `onAction` NEXT / PREVIOUS / SUBMIT wiring
+- [ ] `ProgressBar` bound to `state.progressPercentage`
+- [ ] Back/Next button visibility per layout config
+- [ ] Last-page NEXT → auto SUBMIT behavior
+
+## 3. Question Dispatching (`Question.tsx`)
+
+Exhaustive switch — check each:
+
+- [ ] `rating` → `RatingScale`
+- [ ] `csat` → `CsatScale`
+- [ ] `radio` → inline MCQ
+- [ ] `text` → inline textarea/input
+- [ ] `rating_scale` → `RatingScale` (star/emoji)
+- [ ] `slider` → `CustomSliderTrack`
+- [ ] `matrix` + `CFM_MATRIX` → `LikertMatrixScale`
+- [ ] `matrix` + `CSAT_MATRIX` / `RATING_MATRIX` → `CsatMatrixScale`
+- [ ] `rating_matrix` → `CsatMatrixScale`
+- [ ] `slider_matrix` → `SliderMatrixScale`
+- [ ] `file_upload` → `FileUploadScale`
+- [ ] `text_and_media` → inline media (no scale)
+- [ ] `dangerouslySetInnerHTML` for `question.text` / `description`
+- [ ] `validationError` banner per question
+- [ ] `id={question.id}` on every question wrapper
+
+## 4. Component Architecture Checklist
+
+| Component | In survey? | Blueprint doc | Key constraints verified |
+|-----------|------------|---------------|--------------------------|
+| RatingScale | | `01-components/03-rating-scale.md` | |
+| CsatScale | | `01-components/04-csat-scale.md` | |
+| CsatMatrixScale | | `01-components/05-csat-matrix-scale.md` | |
+| LikertMatrixScale | | `01-components/06-likert-matrix-scale.md` | |
+| SliderMatrixScale | | `01-components/07-slider-matrix-scale.md` | |
+| FileUploadScale | | `01-components/08-file-upload-scale.md` | |
+| CustomSliderTrack | | `01-components/09-custom-slider-track.md` | |
+| Header / Footer | | `01-components/10-header-footer.md` | |
+| ProgressBar | | `01-components/11-progress-bar.md` | |
+| LanguageSelector | | `01-components/12-language-selector.md` | |
+| MatrixDropdown | | `01-components/13-matrix-dropdown.md` | |
+
+## 5. Theme, Brand & Logo
+
+- [ ] CSS-only logo (no `<img>`, no `public/` uploads)
+- [ ] Primary / hover colors from client prompt
+- [ ] Header / Footer / ProgressBar / LanguageSelector per layout
+
+## 6. Submit & Thank You
+
+- [ ] `onAction({ type: 'SUBMIT' })` on final page
+- [ ] Thank-you screen when `submitSurveyResults.data` is set
+- [ ] Custom thank-you message from client prompt if provided
+
+## 7. Pre-Build Verification
+
+- [ ] No imports from `.../src/` internal paths
+- [ ] All mutations via `onAction` — no direct state mutation
+- [ ] `npm run build` passes

package/templates/docs/01-sdk-core/01-fetch-survey.md

@@ -1,68 +0,0 @@
-# Fetch Survey — `useFetchSurvey`
-
-> **Source**: `packages/sdk/src/fetchSurvey/useFetchSurvey.ts`
-> **Called by**: `useSurveySDK()` internally — the client never calls this directly.
-
-## What It Does
-
-1. Builds the API URL from the client's `instanceId` (JWT token)
-2. Makes a `GET` request to the Sprinklr CFM API endpoint
-3. Caches the raw response using `@tanstack/react-query` (singleton QueryClient — no provider needed)
-4. Re-maps the cached response whenever the target language changes (client-side, no re-fetch)
-
-## API Endpoint
-
-```
-https://custom-p0.feedbook.me/api/feedback/survey/cfm?instanceId={JWT_TOKEN}
-```
-
-The URL is constructed by `buildSurveyUrl()` in `fetchSurvey/utils/url.ts`.
-
-## Instance ID
-
-The `instanceId` is a **JWT token** string that encodes:
-- `surveyId` — Which survey to load
-- `distributionEntityId` — Which distribution channel
-- `surveyLanguage` — Default language (e.g. `'de'`)
-- `partnerId` — Tenant identifier
-
-**⚠️ CRITICAL**: The instanceId comes from the **client's chat prompt**. The agent must ask the client for it before building the survey. Without it, `useFetchSurvey` returns `null` and the survey cannot load.
-
-## Return Shape
-
-```typescript
-{
-  survey: Survey | null,       // Fully mapped survey object (see 02-survey-mapper.md)
-  session: SurveySession | null, // { instanceId, language } — passed to submit hook
-  fetching: boolean,           // True while network request is in flight
-  fetchError: Error | null,    // Network/API error
-}
-```
-
-## Caching Behaviour
-
-- Keyed by `['survey', url]` — fetched **once** per instanceId
-- Language changes do NOT re-fetch — they re-map the cached raw response via `useMemo`
-- Uses `cache: 'force-cache'` on the fetch request for browser-level HTTP caching
-
-## QueryClient
-
-The SDK creates its own internal singleton `QueryClient` in `src/queryClient.ts`.
-The client app does **NOT** need to wrap anything in `<QueryClientProvider>`.
-
-## Logging & Telemetry
-
-The fetch lifecycle emits structured logs (when `debug: true`):
-- `logFetchStart(url)` — before the request
-- `logFetchPerfSuccess(durationMs, status, url, payloadSize)` — on success
-- `logFetchPerfFailure(durationMs, status, url)` — on failure
-- `trackFetchLatency(...)` — performance telemetry
-
-## Error Handling
-
-| Scenario | Behaviour |
-|----------|-----------|
-| Network offline | `fetchError` populated, `survey` is `null` |
-| HTTP 4xx/5xx | `fetchError` populated with status message |
-| Invalid instanceId | API returns empty/malformed → `survey` maps to `null` |
-| Successful but empty | `survey` is `null`, no error |

package/templates/docs/01-sdk-core/02-survey-mapper.md

@@ -1,85 +0,0 @@
-# Survey Mapper — `mapSurvey`
-
-> **Source**: `packages/sdk/src/fetchSurvey/utils/mappers/surveyMapper.ts`
-> **Called by**: `useFetchSurvey()` inside `useMemo` — re-runs when language changes.
-
-## What It Does
-
-Transforms the raw API response (`ApiResponse`) into a clean, typed `Survey` object:
-
-```
-ApiResponse (raw network JSON)
-    │
-    ├── extractQuestions()      → Flat list of ApiQuestion[]
-    ├── resolveSurveyLanguage() → Determine active language code
-    ├── extractSurveyLanguages()→ Build SurveyLanguage[] for language switcher
-    └── mapSurveyPages()        → Pages → Questions → per-type mappers
-            │
-            └── mapQuestion() per question (see 03-question-mappers.md)
-```
-
-## Output: `Survey` Type
-
-```typescript
-type Survey = {
-  id: string;                    // Survey identifier
-  language: string;              // Active language code (e.g. 'en', 'de')
-  languages: SurveyLanguage[];   // All available languages for the switcher
-  pages: SurveyPageData[];       // Ordered list of pages
-};
-
-type SurveyPageData = {
-  id: string;                    // Page identifier
-  title?: string;                // Optional page heading
-  questions: SurveyQuestion[];   // Questions on this page
-};
-
-type SurveyLanguage = {
-  code: string;                  // BCP-47 code (e.g. 'de')
-  name: string;                  // Display name (e.g. 'Deutsch')
-};
-```
-
-## Key Functions
-
-### `extractQuestions(api)`
-Traverses `api.cfmSurveyDTO.surveyPages[].questionHolders[].question` to produce a flat array of raw API questions.
-
-### `resolveSurveyLanguage(api, language?)`
-Priority: `language` parameter → `api.surveyLanguage` → `api.cfmSurveyDTO.baseLanguage` → `'en'`
-
-### `extractSession(api)`
-Returns `{ instanceId, language }` or `null` if no valid instanceId exists. This session object is passed to the submit hook.
-
-### `mapSurveyPages(api, language, placeholders)`
-Iterates over `api.cfmSurveyDTO.surveyPages`, calling `mapQuestion()` for each question within each page's `questionHolders`. Returns `SurveyPageData[]`.
-
-## API Response Structure (Simplified)
-
-```typescript
-type ApiResponse = {
-  instanceId: string;
-  surveyLanguage: string;
-  cfmSurveyDTO: {
-    id: string;
-    baseLanguage: string;
-    surveyPages: Array<{
-      id: string;
-      pageTitle?: string;
-      questionHolders: Array<{
-        question: ApiQuestion;
-      }>;
-    }>;
-  };
-};
-```
-
-## Language Re-mapping
-
-When the user switches language via the `LanguageSelector`:
-1. `selectedLanguage` state changes in `SurveyPage.tsx`
-2. This flows into `useSurveySDK({ options: { language: selectedLanguage } })`
-3. `useFetchSurvey` does **NOT re-fetch** — the raw `ApiResponse` is cached
-4. `useMemo` re-runs `mapSurvey(apiResponse, newLanguage, placeholders)`
-5. Each question's text, options, and labels are resolved from `translations[language]`
-6. The entire UI re-renders with translated content

package/templates/docs/01-sdk-core/03-question-mappers.md

@@ -1,114 +0,0 @@
-# Question Mappers — `mapQuestion`
-
-> **Source**: `packages/sdk/src/fetchSurvey/utils/mappers/questionMappers/index.ts`
-> **Called by**: `mapSurveyPages()` for each question in each page.
-
-## What It Does
-
-Takes a raw `ApiQuestion` and produces a fully typed `SurveyQuestion` variant. This is the core routing logic that determines what question type the client component will render.
-
-## Dispatch Pipeline
-
-```
-ApiQuestion
-    │
-    ├── resolveBase(raw, configs, language, placeholders)
-    │   → { id, text, description, required, requiredErrorMessage, containerMedia* }
-    │
-    ├── normalizeType(raw.answerType)
-    │   → 'rating' | 'text' | 'matrix' | 'rating_matrix' | 'slider_matrix'
-    │     | 'text_and_media' | 'file_upload' | 'radio' (default)
-    │
-    └── switch(type) → per-type mapper
-        ├── 'rating'         → mapRatingQuestion()   [handles NPS, CSAT, Slider, RatingScale]
-        ├── 'text'           → mapTextQuestion()
-        ├── 'matrix'         → mapMatrixQuestion()   [handles CFM, CSAT, RATING matrix]
-        ├── 'rating_matrix'  → mapMatrixQuestion()   [same handler, different subType]
-        ├── 'slider_matrix'  → mapSliderMatrixQuestion()
-        ├── 'text_and_media' → mapTextAndMediaQuestion()
-        ├── 'file_upload'    → mapFileUploadQuestion()
-        └── default          → mapRadioQuestion()    [MCQ and any unrecognised type]
-```
-
-## `normalizeType(answerType)` — Type Resolution
-
-| API `answerType` | Normalized Type | Notes |
-|-----------------|----------------|-------|
-| `'SCALE'` | `'rating'` | Further sub-typed inside ratingMapper |
-| `'RATING'` | `'rating'` | Legacy alias |
-| `'RATING_MATRIX'` | `'rating_matrix'` | Grid with NPS-style columns |
-| `'TEXTFIELD'` | `'text'` | Short or long text input |
-| `'MCQ'` | `'radio'` | Multiple choice (single select) |
-| `'CFM_MATRIX'` | `'matrix'` | Likert-style grid |
-| `'CSAT_MATRIX'` | `'matrix'` | Satisfaction grid with emoji/star |
-| `'SLIDER_MATRIX'` | `'slider_matrix'` | Grid of range sliders |
-| `'TEXT_AND_MEDIA'` | `'text_and_media'` | Display-only media card |
-| `'FILE_UPLOAD'` | `'file_upload'` | File attachment question |
-| Any other | `'radio'` | Safe fallback |
-
-## `resolveBase()` — Shared Fields
-
-Every question variant inherits these base fields:
-
-```typescript
-type QuestionBase = {
-  id: string;                      // ⚠️ MUST be used as DOM element id
-  text: string;                    // May contain HTML — use dangerouslySetInnerHTML
-  description?: string;            // Supplementary instruction text (HTML)
-  required?: boolean;              // Whether answer is mandatory
-  requiredErrorMessage?: string;   // Custom validation error text
-  questionNumber?: number;         // 1-indexed ordinal position
-  containerMediaUrl?: string;      // Image/video shown alongside question
-  containerMediaMimeType?: string; // MIME type for container media
-  containerMediaAlignment?: string;// Layout position of container media
-  containerMediaSize?: number;     // Width percentage of container media
-};
-```
-
-### Text Resolution Priority
-```
-language translation (richText) → language translation (plainText)
-  → default richText → default plainText → ''
-```
-
-### Placeholder Replacement
-The `resolveBase` function replaces `{{TOKEN}}` patterns in question text and description:
-```typescript
-text.replace(/\{\{(\w+)\}\}/g, (match, key) =>
-  placeholders[key] !== undefined ? placeholders[key] : match
-);
-```
-
-## Rating Mapper Sub-Dispatch
-
-The `mapRatingQuestion()` handler further sub-types based on `questionConfigs`:
-
-```
-SCALE answerType
-    │
-    ├── SCALE_TYPE=CSAT (or ≤5 options) → type: 'csat'
-    ├── SCALE_TYPE=STAR/EMOJI/FIVE_POINT → type: 'rating_scale'
-    ├── INPUT_TYPE=SLIDER → type: 'slider'
-    └── default (NPS/TEN_POINT) → type: 'rating'
-```
-
-This means the client component's `Question.tsx` needs to handle **all these refined types**, not just the raw `'rating'` type.
-
-## Final Output: `SurveyQuestion` Union
-
-```typescript
-type SurveyQuestion =
-  | RatingQuestion        // type: 'rating'
-  | RadioQuestion         // type: 'radio'
-  | TextQuestion          // type: 'text'
-  | MatrixQuestion        // type: 'matrix'
-  | RatingMatrixQuestion  // type: 'rating_matrix'
-  | SliderMatrixQuestion  // type: 'slider_matrix'
-  | TextAndMediaQuestion  // type: 'text_and_media'
-  | CsatQuestion          // type: 'csat'
-  | SliderQuestion        // type: 'slider'
-  | RatingScaleQuestion   // type: 'rating_scale'
-  | FileUploadQuestion;   // type: 'file_upload'
-```
-
-Each type is documented in detail in `02-question-types/`.