@explorer02/cfm-survey-sdk 0.2.1 → 0.2.2

package/templates/docs/00-integration/useSurveySDK.md

@@ -13,9 +13,7 @@ import {
   type UseSurveySDKReturn,
   type SurveyQuestion,
   type AnswerValue,
-  type MatrixAnswerMap,
-  CsatEmojiSet,
-  getEmojiForIndex,
+  type MatrixRowAnswers,
 } from '@explorer02/cfm-survey-sdk'; // or @repo/sdk in monorepo
 ```
 
@@ -28,12 +26,14 @@ Ask the client: *"Please provide your survey instance ID (JWT token)."*
 ## Hook Signature
 
 ```typescript
-const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
+const { surveyQueryResults, submitSurveyResults, partialSaveResults, state, onAction } = useSurveySDK({
   options: {
     instanceId: string,                    // JWT from client
     language: string | undefined,          // Active language code
     placeholders: Record<string, string>,  // Token replacements — MUST be stable ref
+    customFieldValues?: CustomFieldValueMap, // CRM/transaction custom field values — MUST be stable ref
     debug: boolean,                        // Console logging
+    savePartialResponse: boolean | { debounceMs?: number }, // Optional partial save (default 1500ms)
   },
 });
 ```
@@ -42,9 +42,52 @@ Define `placeholders` **outside** the component to avoid infinite re-fetch loops
 
 ```typescript
 const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'John' };
-// inside component: options: { placeholders: SURVEY_PLACEHOLDERS }
 ```
 
+Define `customFieldValues` **outside** the component (same stable-ref rule as `placeholders`):
+
+```typescript
+import type { CustomFieldValueMap } from '@explorer02/cfm-survey-sdk';
+
+const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {
+  '_c_6a436c1244764c9d4a6ce2fc': 'q5',           // TEXT — string
+  '_c_6a436c3644764c9d4a6ce3f5': 2,               // NUMBER — number or numeric string
+  '_c_6a436c9e44764c9d4a6ce717': 'option-id',   // PICKLIST — option id string
+  '_c_6a436cbb44764c9d4a6ce7e5': ['opt-a'],       // PICKLIST_MULTISELECT — option id array
+  '_c_6a4386dc44208eb8b08a9056': 1781029800000,  // DATETIME — epoch ms (recommended)
+};
+```
+
+Wrap hook options in `useMemo` inside the component:
+
+```typescript
+const surveyOptions = useMemo(
+  () => ({
+    instanceId,
+    language: selectedLanguage,
+    placeholders: SURVEY_PLACEHOLDERS,
+    customFieldValues: CUSTOM_FIELD_VALUES,
+  }),
+  [selectedLanguage]
+);
+
+useSurveySDK({ options: surveyOptions });
+```
+
+Keys are the `_c_…` custom field ids from survey logic rules (`conditionEntity.id` in skip/display/answer logic). The SDK evaluates skip, display, and answer logic against these values when passed via hook options.
+
+| Custom field type | Client value shape |
+|---|---|
+| TEXT / TEXT_MULTI / TEXTAREA | `string` |
+| NUMBER | `number` or numeric string (`0` is a valid value) |
+| PICKLIST | `string` (option id) |
+| PICKLIST_MULTISELECT | `string[]` (option ids) |
+| DATETIME | epoch ms (`number` or numeric string); ISO date strings also accepted |
+
+Missing ids in the map are treated as empty for logic evaluation.
+
+When the survey uses custom-field logic, also pass the same map into `Question.tsx` visibility helpers — see [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
+
 ## Return Shape
 
 | Namespace | Field | Type | Purpose |
@@ -55,42 +98,129 @@ const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'John' };
 | `submitSurveyResults` | `data` | `SubmitResult \| null` | Success payload |
 | | `error` | `Error \| null` | Submit failure |
 | | `isLoading` | `boolean` | Submit in progress |
-| `state` | `currentPageIndex` | `number` | 0-based page index |
-| | `currentQuestions` | `SurveyQuestion[]` | Questions on current page |
-| | `values` | `Record<string, AnswerValue>` | All answers so far |
+| `partialSaveResults` | `data` | `SubmitResult \| null` | Last partial save success payload (when enabled) |
+| | `error` | `Error \| null` | Partial save failure |
+| | `isLoading` | `boolean` | Partial save in progress |
+| `state` | `phase` | `SurveyPhase` | Survey flow phase (see below) |
+| | `currentPageIndex` | `number` | 0-based page index (when `phase.kind === 'content'`) |
+| | `currentQuestions` | `SurveyQuestion[]` | Questions on current page; `questionText` and `questionNumber` resolved by SDK |
+| | `answers` | `SurveyAnswers` | All answers so far |
 | | `validationErrors` | `Record<string, string>` | Per-question error messages |
-| | `progressPercentage` | `number` | 0–100 completion |
+| | `progressPercentage` | `number` | 0–100 path-scoped completion (see `progress.md`) |
+| | `totalQuestionsCount` | `number` | Answerable questions on active path (progress denominator) |
+| | `answeredQuestionsCount` | `number` | Earned credits on active path (progress numerator) |
+| | `canGoBack` | `boolean` | Show Back button |
+| | `primaryButtonType` | `'next' \| 'submit'` | Primary nav label; SDK maps `NEXT` → `SUBMIT` when `'submit'` |
+| | `specialPage` | `SpecialPage \| undefined` | Intro / end / paused page content when applicable |
 | `onAction` | — | `(action: SurveyAction) => void` | **Only** way to mutate state |
 
+### Survey phases (`state.phase.kind`)
+
+| Phase | When | UI |
+|-------|------|-----|
+| `intro` | Survey has intro page | Render intro; dispatch `START` |
+| `content` | Active questions | Question map + nav |
+| `end` | Successful submit | End/thank-you page from `specialPage` |
+| `paused` | Survey paused flag | Paused message (read-only) |
+| `submitted` | Already filled | Terminal message |
+| `expired` | Survey expired | Terminal message |
+| `quota_fulfilled` | Quota reached | Terminal message |
+
 ## Action Dispatching
 
 Never mutate `state` directly. Use `onAction`:
 
 ```typescript
 // Answer a question
-onAction({ type: ACTIONS.CHANGE, payload: { questionId: 'q1', value: 4 } });
+onAction({ type: ACTIONS.CHANGE, payload: { questionId: 'q1', answerValue: 4 } });
 
 // Matrix answer
-onAction({ type: ACTIONS.CHANGE, payload: { questionId: 'q2', value: { row1: 5, row2: 2 } } });
+onAction({ type: ACTIONS.CHANGE, payload: { questionId: 'q2', answerValue: { row1: 5, row2: 2 } } });
+
+// Intro → content
+onAction({ type: ACTIONS.START });
 
 // Navigate
-onAction({ type: ACTIONS.NEXT });      // Validates current page; auto-SUBMIT on last page
-onAction({ type: ACTIONS.PREVIOUS });
-onAction({ type: ACTIONS.SUBMIT });    // Validates ALL pages, then submits
+onAction({ type: ACTIONS.NEXT });      // Validates current page; maps to SUBMIT when primaryButtonType is 'submit'
+onAction({ type: ACTIONS.PREVIOUS });    // Uses pageHistory (skip-aware Back)
+onAction({ type: ACTIONS.SUBMIT });    // Validates non-skipped pages, then submits
+
+// Lifecycle (client detects scroll / visibility, SDK handles API calls)
+onAction({ type: ACTIONS.SCROLL });    // First scroll — marks instance as started (once)
+onAction({
+  type: ACTIONS.RECORD_QUESTION_VIEW,
+  payload: { questionIds: ['q1'] },     // Question entered viewport
+});
 ```
 
-String literals also work: `'NEXT'`, `'PREVIOUS'`, `'SUBMIT'`, `'CHANGE'`.
+String literals also work: `'START'`, `'NEXT'`, `'PREVIOUS'`, `'SUBMIT'`, `'CHANGE'`, `'SCROLL'`, `'RECORD_QUESTION_VIEW'`.
 
 ## Validation
 
-- Required questions must be answered before `NEXT` or `SUBMIT`
+- Required questions must be answered before `NEXT` or `SUBMIT` on the **current page**
+- `NEXT` validates current page only; skip logic may bypass intermediate pages
+- `SUBMIT` validates **non-skipped pages** only (pages bypassed by skip logic are excluded)
 - `null` is a valid answer (N/A option)
-- `text_and_media` is display-only — always skipped
+- `TEXT_AND_MEDIA` is display-only — always skipped for validation
 - On failure, SDK scrolls to first error via `document.getElementById(questionId)` — **requires `id={question.id}` on question wrappers**
 
+See [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md) for skip, Back, and answer-sanitize behavior.
+
 ## Submission
 
-Triggered by `onAction({ type: ACTIONS.SUBMIT })` or `NEXT` on the last page. While submitting, `submitSurveyResults.isLoading` is `true`. On success, show thank-you UI when `submitSurveyResults.data` is set.
+Triggered by `onAction({ type: ACTIONS.SUBMIT })` or `NEXT` when `primaryButtonType === 'submit'`. While submitting, `submitSurveyResults.isLoading` is `true`. On success, render end UI when `state.phase.kind === 'end'` (and `state.specialPage` for content). `submitSurveyResults.data` confirms API success.
+
+## Mark as Started
+
+On the **first scroll or answer change**, the client should dispatch `onAction({ type: ACTIONS.SCROLL })` (once, on first scroll) and/or the SDK fires automatically on `CHANGE`. Both call a one-time GET to `markResponseInstanceAsStarted`. Fire-and-forget — errors do not block the UI.
+
+```typescript
+useEffect(() => {
+  const onScroll = () => onAction({ type: ACTIONS.SCROLL });
+  window.addEventListener('scroll', onScroll, { passive: true, once: true });
+  return () => window.removeEventListener('scroll', onScroll);
+}, [onAction]);
+```
+
+## Question Activity (VIEWED)
+
+When a question enters the viewport, dispatch `RECORD_QUESTION_VIEW` with its id(s). The SDK POSTs to `recordQuestionActivityV2` with deduplication (each question recorded once). Requires `id={question.id}` on question wrappers.
+
+```typescript
+useEffect(() => {
+  const observer = new IntersectionObserver(entries => {
+    for (const entry of entries) {
+      if (entry.isIntersecting && entry.target.id) {
+        onAction({
+          type: ACTIONS.RECORD_QUESTION_VIEW,
+          payload: { questionIds: [entry.target.id] },
+        });
+      }
+    }
+  }, { threshold: 0.5 });
+
+  state.currentQuestions.forEach(q => {
+    const el = document.getElementById(q.id);
+    if (el) observer.observe(el);
+  });
+
+  return () => observer.disconnect();
+}, [state.currentQuestions, onAction]);
+```
+
+## Partial Save
+
+When `savePartialResponse: true` (or `{ debounceMs: 1500 }`) is passed in options, the SDK debounces answer changes and POSTs partial responses with `surveySubmitted=false`. Partial saves begin only after the first user interaction (not MCQ default seeding). Monitor `partialSaveResults.isLoading` / `partialSaveResults.error` if you need UI feedback.
+
+```typescript
+useSurveySDK({
+  options: {
+    instanceId,
+    savePartialResponse: true,
+    // or: savePartialResponse: { debounceMs: 2000 },
+  },
+});
+```
 
 ## Language & Placeholders
 
@@ -98,10 +228,8 @@ Triggered by `onAction({ type: ACTIONS.SUBMIT })` or `NEXT` on the last page. Wh
 - `survey.languages` lists available languages for `LanguageSelector`
 - Placeholders replace `{{FIRST_NAME}}` tokens in question text at map time
 
-## CSAT Icons (from package)
+## CSAT / rating emoji UI (client-implemented)
 
-```typescript
-import { CsatEmojiSet, getEmojiForIndex, CsatStarIcons } from '@explorer02/cfm-survey-sdk';
-```
+CSAT emoji and star icons are **not** exported from the SDK. Implement client-side with `react-icons` (or your icon library). Map column index to sentiment icons proportionally for non-5-point scales.
 
-Use `getEmojiForIndex(index, totalOptions)` for proportional emoji mapping on non-5-point scales. Install `react-icons` in the client project.
+See `03-ui-specs/04-csat.md` and [`question-type-sdk-matrix.md#csat_matrix`](question-type-sdk-matrix.md#csat_matrix).

package/templates/docs/01-components/01-survey-page.md

@@ -3,91 +3,113 @@
 > **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
 > **Reference implementation:** `apps/client/src/components/SurveyPage.tsx`
 > **Target Component**: `SurveyPage`
-> **Role**: The main entry point that wires the UI to the `useSurveySDK` hook, manages loading/error states, orchestrates pagination, and controls submission.
+> **Role**: Wires `useSurveySDK` to the UI — loading/error states, phase routing, pagination, submission.
 
 ## Core Responsibility
-This component MUST act as the state machine for the entire survey flow. It should never render questions directly—it delegates that to `Question.tsx`.
 
-## Setup & Wiring (CRITICAL)
+Act as the **phase state machine** for the survey. Never render questions directly — delegate to `Question.tsx`.
 
-The component MUST invoke `useSurveySDK`, passing the **instanceId** from the client prompt.
+## Setup & Wiring (CRITICAL)
 
 ```tsx
+import type { CustomFieldValueMap } from '@explorer02/cfm-survey-sdk';
+
 const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'Customer' }; // Must be outside component!
+const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {}; // Populate when survey uses custom-field logic
 
 export default function SurveyPage() {
-  const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>("");
+  const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>();
 
-  const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
-    options: {
-      instanceId: 'YOUR_INSTANCE_ID_HERE', // From client prompt
+  const surveyOptions = useMemo(
+    () => ({
+      instanceId: 'YOUR_INSTANCE_ID_HERE',
       language: selectedLanguage,
       placeholders: SURVEY_PLACEHOLDERS,
+      customFieldValues: CUSTOM_FIELD_VALUES,
       debug: true,
-    }
+    }),
+    [selectedLanguage]
+  );
+
+  const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
+    options: surveyOptions,
   });
-  
+
   const survey = surveyQueryResults.data;
-  
-  // ... state machine rendering
+  const allQuestions = useMemo(
+    () => survey?.pages.flatMap(page => page.questions) ?? [],
+    [survey]
+  );
+  // ... phase routing below
 }
 ```
 
-## The 5 State Machine Renders (MANDATORY)
+See [`client-integration-guide.md`](../00-integration/client-integration-guide.md) for lifecycle effects (`SCROLL`, `RECORD_QUESTION_VIEW`).
 
-You MUST structure your render logic to strictly handle these 5 states in order to avoid UI crashes when data is not yet available.
+## Render Order (MANDATORY)
 
-### 1. Loading State
-If `surveyQueryResults.isLoading` is true, render a Skeleton or Spinner.
-*Include your CSS-only Header and Footer around the spinner.*
+Handle in this order:
 
-### 2. Error State
-If `surveyQueryResults.error` is true, render a red Error banner containing `surveyQueryResults.error.message`.
+### 1. Loading / Error / Empty
 
-### 3. Empty State
-If `!survey`, render a generic "Survey not found" message.
+| Condition | UI |
+|-----------|-----|
+| `surveyQueryResults.isLoading` | Spinner + Header/Footer |
+| `surveyQueryResults.error` | Error message |
+| `!survey` | "No survey data" |
 
-### 4. Submitted State
-If `submitSurveyResults.data` exists, the survey is complete.
-*Render the Thank You Screen (e.g., "Thank you for your feedback!"). Do not render the question list.*
+### 2. Special phases (`state.phase`)
 
-### 5. Active Survey State
-If the above 4 conditions are met, render the active survey page:
-1. `Header` (Logo)
-2. `ProgressBar` (Pass `state.progressPercentage`)
-3. `LanguageSelector` (Pass `survey.languages`, `survey.language`, `setSelectedLanguage`)
-4. **The Question Map** (See below)
-5. **Navigation Buttons** (See below)
+| `phase.kind` | Component | Action |
+|--------------|-----------|--------|
+| `intro` | `IntroPage` | `onAction({ type: 'START' })` |
+| `paused` | `PausedPage` | Read-only |
+| `end` | `EndPage` | Thank-you from `state.specialPage` |
+| `submitted` | Terminal message | Already filled |
+| `expired` | Terminal message | Survey expired |
+| `quota_fulfilled` | Terminal message | Quota reached |
+
+See `14-intro-page.md`, `15-end-page.md`, `16-paused-page.md`.
+
+### 3. Active content (`phase.kind === 'content'`)
+
+1. `Header`
+2. `ProgressBar` (`state.progressPercentage`) — see `00-integration/progress.md`
+3. `LanguageSelector`
+4. Question map (below)
+5. Navigation buttons (below)
 6. `Footer`
 
 ## The Question Map
 
-You MUST iterate over `state.currentQuestions` and dispatch to `Question.tsx`.
+Pass **all answers and questions** for placeholder resolution (`{{SURVEY_QUESTION-:-qId}}`):
 
 ```tsx
-<div className="space-y-12">
-  {state.currentQuestions.map(question => (
-    <Question
-      key={question.id}
-      question={question}
-      selectedValue={state.values[question.id]}
-      validationError={state.validationErrors[question.id]}
-      onSelect={value => onAction({ 
-        type: 'CHANGE', 
-        payload: { questionId: question.id, value } 
-      })}
-    />
-  ))}
-</div>
+{state.currentQuestions.map(question => (
+  <Question
+    key={question.id}
+    question={question}
+    selectedValue={state.answers[question.id]}
+    validationError={state.validationErrors[question.id]}
+    allAnswers={state.answers}
+    allQuestions={allQuestions}
+    customFieldValues={CUSTOM_FIELD_VALUES}
+    onSelect={answerValue =>
+      onAction({ type: 'CHANGE', payload: { questionId: question.id, answerValue } })
+    }
+  />
+))}
 ```
 
-## Navigation Buttons Logic
+## Navigation Buttons
 
-You MUST conditionally render "Back" and "Next/Submit" buttons. 
-
-- **Back Button**: Hide if `state.currentPageIndex === 0`.
-  - `onClick={() => onAction({ type: 'PREVIOUS' })}`
-- **Next/Submit Button**:
+- **Back:** Render when `state.canGoBack` — `onAction({ type: 'PREVIOUS' })`
+- **Primary:** Label from `state.primaryButtonType` (`'next'` | `'submit'`)
+  - Always dispatch `onAction({ type: 'NEXT' })` — SDK maps to submit when `primaryButtonType === 'submit'`
   - `disabled={submitSurveyResults.isLoading}`
-  - If `state.currentPageIndex < survey.pages.length - 1`, label is "Next", action is `type: 'NEXT'`.
-  - If on the last page, label is "Submit", action is `type: 'NEXT'` (the SDK intercepts NEXT on the last page to trigger submission automatically!).
+
+Do **not** use `currentPageIndex === 0` alone to hide Back — intro page and skip-aware history use `canGoBack`.
+
+## Scroll & question activity
+
+Wire `SCROLL` (once) and `RECORD_QUESTION_VIEW` as documented in `useSurveySDK.md`.

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}%\` }}`.