@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

package/templates/docs/00-integration/placeholders-and-tokens.md

@@ -0,0 +1,116 @@
+# Placeholders and Tokens
+
+> Covers `sdkFeatures.placeholderResolution` — how CRM and dynamic answer tokens resolve in question text.
+
+---
+
+## Token formats
+
+| Token pattern | Example | Resolved by |
+|---------------|---------|-------------|
+| CRM / static placeholder | `{{FIRST_NAME}}`, `{{COMPANY}}` | SDK at map time via `options.placeholders` |
+| Survey question answer | `{{SURVEY_QUESTION-:-questionId}}` | Client at render time via `resolveSurveyQuestionPlaceholders` |
+| Display variant text | Variant bodies may contain both | SDK resolves static tokens on variants; client resolves answer tokens |
+
+Question IDs in answer tokens match the fetched survey's `question.id` (not display order).
+
+---
+
+## Stable `placeholders` ref
+
+Define placeholders **outside** the React component (module scope or parent file):
+
+```typescript
+const SURVEY_PLACEHOLDERS = {
+  FIRST_NAME: 'Alex',
+  COMPANY: 'Acme Corp',
+} as const;
+```
+
+Wrap hook options in `useMemo` so the SDK does not re-fetch on every render:
+
+```typescript
+const surveyOptions = useMemo(
+  () => ({
+    instanceId: SURVEY_INSTANCE_ID,
+    language: selectedLanguage,
+    placeholders: SURVEY_PLACEHOLDERS,
+    customFieldValues: SURVEY_CUSTOM_FIELDS,
+  }),
+  [selectedLanguage]
+);
+```
+
+**Failure mode:** Inline `placeholders={{ FIRST_NAME: '...' }}` inside the component causes infinite fetch loops.
+
+---
+
+## Where SDK resolves vs client responsibility
+
+| Stage | What happens |
+|-------|--------------|
+| **Fetch / map time** | SDK applies language translation + static CRM placeholders to question text and display variants |
+| **`currentQuestions`** | Each question's `questionText` is already variant-resolved for the active path |
+| **Render time (client)** | `Question.tsx` calls `resolveSurveyQuestionPlaceholders(text, answers, questionsById)` for `{{SURVEY_QUESTION-:-id}}` tokens |
+
+Do **not** reimplement CRM token substitution in components — only answer-reference tokens need client resolution.
+
+---
+
+## `resolveSurveyQuestionPlaceholders`
+
+Import from package root:
+
+```typescript
+import { resolveSurveyQuestionPlaceholders } from '@explorer02/cfm-survey-sdk';
+```
+
+Typical usage in `Question.tsx`:
+
+```typescript
+const resolvedText = resolveSurveyQuestionPlaceholders(
+  question.questionText,
+  allAnswers,
+  questionsById
+);
+```
+
+Pass **all** answers and a `questionsById` map built from the full survey (not just `currentQuestions`) so cross-page answer tokens resolve.
+
+---
+
+## `formatAnswerForDisplay`
+
+When a token references another question's answer, the SDK formats the stored answer for human-readable display:
+
+```typescript
+import { formatAnswerForDisplay } from '@explorer02/cfm-survey-sdk';
+
+// Used internally by resolveSurveyQuestionPlaceholders; call directly only for custom UI
+const label = formatAnswerForDisplay(question, answerValue);
+```
+
+Matrix answers format as row/column labels; MCQ as option text; rank order as ordered list.
+
+---
+
+## Wiring checklist
+
+- [ ] `SURVEY_PLACEHOLDERS` defined at module scope (stable ref)
+- [ ] `surveyOptions` wrapped in `useMemo`
+- [ ] `Question` receives `allAnswers` + `allQuestions` (or `questionsById`)
+- [ ] Question shell renders `resolveSurveyQuestionPlaceholders` output, not raw `questionText` when answer tokens may appear
+- [ ] Display variants: trust SDK-resolved text on `currentQuestions`; still run answer-token pass at render
+
+---
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Token shows literally `{{FIRST_NAME}}` | Missing key in `placeholders` map | Add key matching token name (without braces) |
+| Answer token empty | Referenced question unanswered or hidden | Expected until answered; hidden answers sanitized on skip path change |
+| Infinite API requests | Unstable `placeholders` ref | Move outside component; `useMemo` on options |
+| Expired JWT / fetch error | Instance ID invalid | Refresh token; placeholders unrelated |
+
+See also [`question-display-variants.md`](question-display-variants.md) and [`client-integration-guide.md`](client-integration-guide.md).

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

@@ -0,0 +1,61 @@
+# Progress Bar Calculation
+
+> The progress percentage reflects **questions on the active path**, not all questions in the survey.
+
+## Formula
+
+```
+active path     = pages the respondent will visit (given current answers + skip logic)
+total           = answerable questions on that path (excludes TEXT_AND_MEDIA)
+answered        = earned question credits that still lie on the path
+progress %      = round(answered / total × 100)
+```
+
+`state.progressPercentage` from `useSurveySDK` is already computed — bind it to your `ProgressBar`.
+
+The same active path also drives **question numbering** on `state.currentQuestions[].questionNumber`. See [`question-numbering.md`](question-numbering.md).
+
+Custom field values in `options.customFieldValues` affect the active path when skip or display logic references `CUSTOM_FIELD` entities — the denominator updates automatically. See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
+
+## How credits are earned
+
+| Question | When credited |
+|----------|---------------|
+| **Optional** | When the user **lands on** the page (`earnPageOnVisit`) |
+| **Required** | When validly answered (on change, or on visit if already filled) |
+
+Display-only `TEXT_AND_MEDIA` questions never count toward progress.
+
+## Skip logic changes the denominator
+
+If skip logic removes pages from the active path, the **total** shrinks automatically.
+
+**Example:** Survey has 10 pages; skip removes pages 3–6 → total might drop from 10 questions to 6 on the active path.
+
+## Path change vs prune (progress only)
+
+| Event | Progress effect |
+|-------|-----------------|
+| **Path changed** (answer edit reshapes route) | Future answers cleared; off-path credits removed; bar recalculates |
+| **Pruned only** (same route, stale credits) | Off-path credits removed; bar recalculates; answers kept |
+
+## Example timeline
+
+Survey: 4 questions on active path (Q1–Q4 sequential).
+
+| Step | Action | Progress |
+|------|--------|----------|
+| 1 | Land page 1 | Optional Q2 on page 2 not yet counted |
+| 2 | Answer required Q1 | 1/4 = 25% |
+| 3 | Next → page 2 | Optional Q2 credited on visit → 2/4 = 50% |
+| 4 | Change Q1 to trigger skip to Q4 | Path shrinks to 2 questions; stale credits pruned; sanitize clears middle answers |
+
+## UI wiring
+
+```tsx
+<ProgressBar progressPercentage={state.progressPercentage} />
+```
+
+See [`01-components/11-progress-bar.md`](../01-components/11-progress-bar.md) and [`03-ui-specs/12-survey-chrome.md`](../03-ui-specs/12-survey-chrome.md).
+
+See also: [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md).

package/templates/docs/00-integration/question-display-variants.md

@@ -0,0 +1,65 @@
+# Question Display Variants
+
+> Integrator-facing behavior contract. Variant evaluation is handled inside the SDK — the client renders `question.questionText` from `state.currentQuestions` with no variant-aware code.
+
+## What variants do
+
+A question may define alternate rich-text prompts under `questionDisplayVariants[]` in the API. Each variant has:
+
+- `questionText` / `questionRichText` (and optional `translations`)
+- `controlConfig.displayLogic.condition` — the same nested AND/OR filter tree used for skip, display, answer, and custom-field logic
+
+At runtime the SDK picks the **first variant whose condition evaluates true** and overrides `questionText` on `state.currentQuestions`. If no variant matches, the question's base shell text (root `questionRichText` / `questionText`) is used.
+
+Variants change **wording only** — they do not show/hide the question. Question-level show/hide remains `question.displayLogic` (see [`display-logic-and-navigation.md`](display-logic-and-navigation.md)).
+
+## Shared logic engine
+
+Variant conditions use the same evaluator as all other logic kinds:
+
+| Entity | Source |
+|--------|--------|
+| `QUESTION` | Prior answers in `state.answers` |
+| `CUSTOM_FIELD` | `options.customFieldValues` (`_c_…` ids) |
+
+See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) when variant rules reference CRM/transaction fields.
+
+## Client responsibilities
+
+**None beyond normal rendering.**
+
+- Use `state.currentQuestions` — `questionText` is already resolved for the current answers and custom field values.
+- Render with `dangerouslySetInnerHTML` as today.
+- Keep calling `resolveSurveyQuestionPlaceholders(question.questionText, allAnswers, allQuestions)` for `{{SURVEY_QUESTION-:-questionId}}` answer tokens (unchanged).
+- Do **not** read `question.displayVariants` or re-implement condition evaluation in the client.
+
+## Resolution order
+
+1. **Map time:** language translation + static CRM placeholders (`{{FIRST_NAME}}`) applied to each variant's text
+2. **Runtime (SDK):** first matching variant in API array order
+3. **Render time (client):** dynamic answer placeholders via `resolveSurveyQuestionPlaceholders`
+
+## Behavior summary
+
+| Scenario | Result |
+|----------|--------|
+| No `displayVariants` | Base `questionText` |
+| Variants present, none match | Base shell `questionText` |
+| Multiple variants match | First in API order wins |
+| Answers / custom fields change | `currentQuestions` updates on same page |
+| Question hidden by display logic | Not in `currentQuestions`; variants not evaluated |
+| Language switch | Re-fetch/remap applies translated variant text |
+
+## SDK exports (optional advanced use)
+
+```typescript
+import {
+  resolveQuestionDisplayText,
+  applyQuestionDisplayVariants,
+  type QuestionDisplayVariant,
+} from '@explorer02/cfm-survey-sdk';
+```
+
+Most integrators only need `state.currentQuestions`.
+
+See also: [`display-logic-and-navigation.md`](display-logic-and-navigation.md), [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md), [`useSurveySDK.md`](useSurveySDK.md).

package/templates/docs/00-integration/question-numbering.md

@@ -0,0 +1,51 @@
+# Question Numbering (Active Path)
+
+> Integrator-facing behavior contract. Question ordinals are computed inside the SDK — the client renders `question.questionNumber` from `state.currentQuestions` with no numbering logic.
+
+## What the SDK does
+
+The SDK assigns **1-indexed ordinals** to answerable questions on the respondent’s **active path** (same path used for the progress bar). The resolved value is written to `questionNumber` on each item in `state.currentQuestions`.
+
+| Rule | Behavior |
+|------|----------|
+| Path source | `simulateActivePath()` — skip + display + custom-field logic |
+| Which questions | Visible **answerable** questions (`getAnswerableQuestionsOnPage`) |
+| Excluded | `TEXT_AND_MEDIA` (display-only, same as progress) |
+| Order | Active-path page order, then question order within each page |
+| Updates | When answers, custom fields, or path shape change |
+
+Example: skip from Q3 to Q8 → path questions are numbered **1, 2, 3, 4…**, not builder indices.
+
+## Client responsibilities
+
+**Render only — no path simulation.**
+
+```tsx
+{question.questionNumber != null && (
+  <span>{question.questionNumber}.</span>
+)}
+```
+
+Use `state.currentQuestions` (not raw `survey.pages` questions). Optional chrome:
+
+```tsx
+state.totalQuestionsCount      // path denominator (same as progress)
+state.answeredQuestionsCount   // earned credits on path
+```
+
+## Relationship to progress
+
+Question numbering and `state.progressPercentage` share the same active-path denominator. See [`progress.md`](progress.md).
+
+## SDK exports (optional advanced use)
+
+```typescript
+import {
+  computeActivePathQuestionNumbers,
+  applyActivePathQuestionNumbers,
+} from '@explorer02/cfm-survey-sdk';
+```
+
+Most integrators only need `state.currentQuestions` and `state.totalQuestionsCount`.
+
+See also: [`question-display-variants.md`](question-display-variants.md), [`useSurveySDK.md`](useSurveySDK.md).

package/templates/docs/00-integration/question-type-sdk-matrix.md

@@ -0,0 +1,244 @@
+# Question Type SDK Integration Matrix
+
+> **Authoritative master table** for all **11** `QUESTION_TYPE` literals. Read this after [`client-integration-guide.md`](client-integration-guide.md) and before building any question component.
+
+Each row uses the same columns so agents can inventory a fetched survey and wire every SDK feature without importing internal evaluators.
+
+---
+
+## Cross-type logic applicability
+
+| Feature | MCQ | TEXTFIELD | NPS | CFM | CSAT | RATING | SLIDER | FILE | T&M | HEATMAP | RANK |
+|---------|:---:|:---------:|:---:|:---:|:----:|:------:|:------:|:----:|:---:|:-------:|:----:|
+| Skip logic | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Display logic (question) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Answer logic (options/rows/cols) | opt | — | col | row+col | row+col | row | row | — | — | — | opt |
+| Display variants | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Question numbering | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Placeholders | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Partial save | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| Custom field logic | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+Legend: **opt** = option-level; **row+col** = statement rows and scale columns; **col** = scale columns only; **—** = no answer stored or no answer-logic targets.
+
+---
+
+## MCQ
+
+| Column | Value |
+|--------|-------|
+| **SDK type + answer shape** | `McqQuestion`; answer `string \| number` (option `id`) or `string[] \| number[]` when multi-select |
+| **Component file(s)** | Inline in `Question.tsx` or dedicated `McqQuestion.tsx` |
+| **Dispatcher branch** | `QUESTION_TYPE.MCQ` / `'MCQ'` |
+| **Visibility helper** | `getVisibleMcqOptionsForAnswers(question, answers, allQuestions, customFieldValues?)` |
+| **Answer logic scope** | Options |
+| **Skip / display / variants / numbering** | SDK handles skip path, `currentQuestions`, resolved `questionText`, `questionNumber` — client renders visible options only |
+| **Custom field logic** | Pass `customFieldValues` as 4th arg to visibility helper when rules reference CRM fields |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: optionId \| optionId[] } }` |
+| **Value derivation** | Store `option.id`; SDK maps to API value at submit |
+| **Performance notes** | Filter options once per render via helper; avoid re-fetch on option click |
+| **Docs to read** | [`02-question.md`](../01-components/02-question.md) · [`question-types/README.md#mcq`](../02-reference/question-types/README.md#mcq) · [`02-radio.md`](../03-ui-specs/02-radio.md) |
+| **Default answers** | SDK `applyMcqDefaults` seeds `state.answers` from `defaultOptionIds` on load — client binds `selectedValue` only |
+| **Answer conditions** | SDK validates `minSelections` / `maxSelections` on NEXT; client blocks add at max + shows `validationError` |
+| **Known limitations** | Multi-select stores `string[]`; use `selectionMode` not `isMultiSelect` |
+
+---
+
+## TEXTFIELD
+
+| Column | Value |
+|--------|-------|
+| **SDK type + answer shape** | `TextInputQuestion`; answer `string` |
+| **Component file(s)** | Inline in `Question.tsx` |
+| **Dispatcher branch** | `QUESTION_TYPE.TEXTFIELD` / `'TEXTFIELD'` |
+| **Visibility helper** | None |
+| **Answer logic scope** | None |
+| **Skip / display / variants / numbering** | SDK auto; client renders `inputVariant` (`short` vs `long`) from question config |
+| **Custom field logic** | Only in skip/display rules — no visibility helper |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: string } }` — debounce long text in UI if needed |
+| **Value derivation** | Raw string stored |
+| **Performance notes** | Debounce `onAction` for long textarea (300–500 ms) to reduce partial-save churn |
+| **Docs to read** | [`02-question.md`](../01-components/02-question.md) · [`03-text.md`](../03-ui-specs/03-text.md) |
+| **Known limitations** | `short` variant uses single-line input; no answer logic on field content |
+
+---
+
+## NPS_SCALE
+
+| Column | Value |
+|--------|-------|
+| **SDK type + answer shape** | `NpsQuestion`; answer `number` (0–10 index or stored scale value) |
+| **Component file(s)** | `RatingScale.tsx` (`variant="nps"`) |
+| **Dispatcher branch** | `QUESTION_TYPE.NPS_SCALE` / `'NPS_SCALE'` |
+| **Visibility helper** | `getVisibleScaleColumnsForAnswers` (when scale points have answer logic) |
+| **Answer logic scope** | Scale columns/points only |
+| **Skip / display / variants / numbering** | SDK auto; client renders NPS 0–10 row |
+| **Custom field logic** | 4th arg on scale visibility helper when needed |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: number } }` |
+| **Value derivation** | Numeric from selected scale point; use `optionLabel` or index per ui-spec |
+| **Performance notes** | Single row — no matrix overhead |
+| **Docs to read** | [`03-rating-scale.md`](../01-components/03-rating-scale.md) · [`01-rating.md`](../02-reference/question-types/01-rating.md) · [`01-rating.md`](../03-ui-specs/01-rating.md) |
+| **Known limitations** | Legacy `star_rating` maps here or to matrix display styles — not a separate literal |
+
+---
+
+## CFM_MATRIX
+
+| Column | Value |
+|--------|-------|
+| **SDK type + answer shape** | `CfmMatrixQuestion`; answer `MatrixRowAnswers` (`Record<rowId, columnStoredValue>`) |
+| **Component file(s)** | `LikertMatrixScale.tsx`, `MatrixDropdown.tsx` (when `gridLayout: dropdown`) |
+| **Dispatcher branch** | `QUESTION_TYPE.CFM_MATRIX` / `'CFM_MATRIX'` |
+| **Visibility helper** | `getVisibleMatrixItemsForAnswers` — filters rows **and** columns |
+| **Answer logic scope** | Statement rows + scale columns |
+| **Skip / display / variants / numbering** | SDK auto; client picks Likert vs dropdown from `gridLayout` |
+| **Custom field logic** | 4th arg on matrix visibility helper |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } }` — merge row updates |
+| **Value derivation** | **`matrixColumnStoredValue(column)`** for each cell — never store raw label |
+| **Performance notes** | Render only visible rows/cols; lazy-load large matrices |
+| **Docs to read** | [`06-likert-matrix-scale.md`](../01-components/06-likert-matrix-scale.md) · [`07-matrix-cfm.md`](../02-reference/question-types/07-matrix-cfm.md) · [`07-matrix-cfm.md`](../03-ui-specs/07-matrix-cfm.md) |
+| **Known limitations** | Bipolar layout is visual only — same answer shape |
+
+---
+
+## CSAT_MATRIX
+
+| Column | Value |
+|--------|-------|
+| **SDK type + answer shape** | `CsatQuestion`; answer `MatrixRowAnswers` |
+| **Component file(s)** | `CsatMatrixScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx` (graphics) |
+| **Dispatcher branch** | `QUESTION_TYPE.CSAT_MATRIX` / `'CSAT_MATRIX'` |
+| **Visibility helper** | `getVisibleMatrixItemsForAnswers` |
+| **Answer logic scope** | Statement rows + scale columns |
+| **Skip / display / variants / numbering** | SDK auto; emoji/star UI is **client-implemented** (`react-icons`) |
+| **Custom field logic** | 4th arg on matrix visibility helper |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } }` |
+| **Value derivation** | `matrixColumnStoredValue(column)` |
+| **Performance notes** | Graphics mode uses slider track per row; prefer memoized emoji maps |
+| **Docs to read** | [`05-csat-matrix-scale.md`](../01-components/05-csat-matrix-scale.md) · [`04-csat.md`](../02-reference/question-types/04-csat.md) · [`04-csat.md`](../03-ui-specs/04-csat.md) |
+| **Known limitations** | No SDK emoji exports — implement icons client-side |
+
+---
+
+## RATING_MATRIX
+
+| Column | Value |
+|--------|-------|
+| **SDK type + answer shape** | `RatingMatrixQuestion`; answer `MatrixRowAnswers` |
+| **Component file(s)** | Same as CSAT: `CsatMatrixScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx` |
+| **Dispatcher branch** | `QUESTION_TYPE.RATING_MATRIX` / `'RATING_MATRIX'` |
+| **Visibility helper** | `getVisibleMatrixItemsForAnswers` |
+| **Answer logic scope** | Statement rows; **column answer logic may be limited** — verify fetched survey |
+| **Skip / display / variants / numbering** | SDK auto; reuse CSAT matrix component with rating display style |
+| **Custom field logic** | 4th arg on matrix visibility helper |
+| **`onAction` pattern** | Same as CSAT matrix |
+| **Value derivation** | `matrixColumnStoredValue(column)` |
+| **Performance notes** | Same as CSAT matrix |
+| **Docs to read** | [`05-csat-matrix-scale.md`](../01-components/05-csat-matrix-scale.md) · [`09-matrix-rating.md`](../02-reference/question-types/09-matrix-rating.md) · [`08-matrix-csat-rating.md`](../03-ui-specs/08-matrix-csat-rating.md) |
+| **Known limitations** | Shares CSAT component; column-level answer logic gap documented in reference |
+
+---
+
+## SLIDER_MATRIX
+
+| Column | Value |
+|--------|-------|
+| **SDK type + answer shape** | `SliderMatrixQuestion`; answer `MatrixRowAnswers` |
+| **Component file(s)** | `SliderMatrixScale.tsx`, `CustomSliderTrack.tsx` |
+| **Dispatcher branch** | `QUESTION_TYPE.SLIDER_MATRIX` / `'SLIDER_MATRIX'` |
+| **Visibility helper** | `getVisibleStatementRowsForAnswers` (rows); columns from tick marks config |
+| **Answer logic scope** | Statement rows |
+| **Skip / display / variants / numbering** | SDK auto; tick marks from `tickMarks` array |
+| **Custom field logic** | 4th arg on statement-row helper |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } }` |
+| **Value derivation** | Stored value from tick mark / slider position per row |
+| **Performance notes** | One slider per visible row; debounce drag if partial save enabled |
+| **Docs to read** | [`07-slider-matrix-scale.md`](../01-components/07-slider-matrix-scale.md) · [`10-slider-matrix.md`](../02-reference/question-types/10-slider-matrix.md) · [`09-slider-matrix.md`](../03-ui-specs/09-slider-matrix.md) |
+| **Known limitations** | Legacy standalone `slider` type maps here — not a separate literal |
+
+---
+
+## FILE_UPLOAD
+
+| Column | Value |
+|--------|-------|
+| **SDK type + answer shape** | `FileUploadQuestion`; answer `UploadedFileAnswer[]` (`{ id, mediaUrl, name?, mimeType?, size? }`) |
+| **Component file(s)** | `FileUploadScale.tsx` |
+| **Dispatcher branch** | `QUESTION_TYPE.FILE_UPLOAD` / `'FILE_UPLOAD'` |
+| **Visibility helper** | None |
+| **Answer logic scope** | None |
+| **Skip / display / variants / numbering** | SDK auto |
+| **Custom field logic** | Skip/display only |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: UploadedFileAnswer[] } }` **after** presigned upload completes |
+| **Value derivation** | SDK submit maps to `quesIdVsAttachmentDetails` — raw `File[]` is **not submitted** |
+| **Performance notes** | Local validate → POST presigned URL → PUT file → then CHANGE; show progress UI |
+| **Docs to read** | [`file-upload-aws.md`](file-upload-aws.md) · [`08-file-upload-scale.md`](../01-components/08-file-upload-scale.md) · [`11-file-upload.md`](../02-reference/question-types/11-file-upload.md) · [`10-file-upload.md`](../03-ui-specs/10-file-upload.md) |
+| **Known limitations** | Must wire upload API; see [`file-upload-aws.md`](file-upload-aws.md) |
+
+---
+
+## TEXT_AND_MEDIA
+
+| Column | Value |
+|--------|-------|
+| **SDK type + answer shape** | `TextAndMediaQuestion`; **no answer** |
+| **Component file(s)** | Inline in `Question.tsx` |
+| **Dispatcher branch** | `QUESTION_TYPE.TEXT_AND_MEDIA` / `'TEXT_AND_MEDIA'` |
+| **Visibility helper** | None |
+| **Answer logic scope** | None |
+| **Skip / display / variants / numbering** | SDK auto; container media from survey shell |
+| **Custom field logic** | Skip/display only |
+| **`onAction` pattern** | No CHANGE — user advances with NEXT |
+| **Value derivation** | N/A |
+| **Performance notes** | Lazy-load media; respect alignment from ui-spec |
+| **Docs to read** | [`02-question.md`](../01-components/02-question.md) · [`11-text-and-media.md`](../03-ui-specs/11-text-and-media.md) |
+| **Known limitations** | Display-only; excluded from partial-save answer payload |
+
+---
+
+## HEATMAP
+
+| Column | Value |
+|--------|-------|
+| **SDK type + answer shape** | `HeatmapQuestion`; answer `HeatmapClickPoint[]` (array of `{ id, x, y }` normalized 0–1) |
+| **Component file(s)** | `HeatmapScale.tsx` + portable coord helper (see [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts)) |
+| **Dispatcher branch** | `QUESTION_TYPE.HEATMAP` / `'HEATMAP'` |
+| **Visibility helper** | None |
+| **Answer logic scope** | None |
+| **Skip / display / variants / numbering** | SDK auto |
+| **Custom field logic** | Skip/display only |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: HeatmapClickPoint[] \| undefined } }` on each click add/remove |
+| **Value derivation** | Normalized 0–1 coordinates; respect `maxClicksAllowed` |
+| **Performance notes** | Normalize coords on image load; use `findSpotNearClick` for hit testing |
+| **Docs to read** | [`17-heatmap-scale.md`](../01-components/17-heatmap-scale.md) · [`12-heatmap.md`](../02-reference/question-types/12-heatmap.md) · [`13-heatmap.md`](../03-ui-specs/13-heatmap.md) |
+| **Known limitations** | Coord helper is client code — copy template, not monorepo-only path |
+
+---
+
+## RANK_ORDER
+
+| Column | Value |
+|--------|-------|
+| **SDK type + answer shape** | `RankOrderQuestion`; answer `RankOrderAnswers` (`Record<optionId, rank>`) |
+| **Component file(s)** | `RankOrderScale.tsx` — requires `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities` |
+| **Dispatcher branch** | `QUESTION_TYPE.RANK_ORDER` / `'RANK_ORDER'` |
+| **Visibility helper** | `getVisibleRankOrderOptionsForAnswers` |
+| **Answer logic scope** | Options |
+| **Skip / display / variants / numbering** | SDK auto |
+| **Custom field logic** | 4th arg on rank visibility helper |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: RankOrderAnswers } }` after reorder |
+| **Value derivation** | Use `assignRankWithoutDuplicates`, `buildRankOrderFromOrderedOptionIds`, `getOrderedOptionIdsFromRanks`, `normalizeRankOrderAnswers` |
+| **Performance notes** | Prefer `option.imageUrl` over `previewImageUrl`; dnd-kit sensors for touch |
+| **Docs to read** | [`18-rank-order-scale.md`](../01-components/18-rank-order-scale.md) · [`13-rank-order.md`](../02-reference/question-types/13-rank-order.md) · [`14-rank-order.md`](../03-ui-specs/14-rank-order.md) |
+| **Known limitations** | Image preview URLs may 403 on static deploy — use full `imageUrl` |
+
+---
+
+## Agent workflow
+
+1. Inventory types from fetched survey → one row per type above.
+2. Fill [`implementation_plan.md`](../templates/implementation_plan.md) §3d from this matrix.
+3. For each type, read blueprint + reference + uiSpec from MANIFEST `questionTypes.{key}`.
+4. Wire lifecycle features per [`survey-lifecycle-analytics.md`](survey-lifecycle-analytics.md).
+5. Wire placeholders per [`placeholders-and-tokens.md`](placeholders-and-tokens.md).
+6. Enable partial save per [`partial-save-and-recovery.md`](partial-save-and-recovery.md) when required.

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

@@ -41,6 +41,41 @@ import { useSurveySDK } from '@explorer02/cfm-survey-sdk';
 
 ---
 
+## Next.js static export for AWS deploy {#nextjs-aws-static-export}
+
+Required when deploying to **Sprinklr AWS** (S3 + CloudFront via EC2 middle API). See [`aws-deploy.md`](aws-deploy.md) for the full deploy procedure.
+
+**`next.config.js`** — add static export settings alongside `transpilePackages`:
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  transpilePackages: ['@explorer02/cfm-survey-sdk'], // or '@repo/sdk'
+  output: 'export',
+  assetPrefix: './',
+  images: { unoptimized: true },
+};
+module.exports = nextConfig;
+```
+
+**`package.json`** — copy RSC payload so `index.html` URLs work on CloudFront:
+
+```json
+"build": "next build && cp out/index.txt out/index.html.txt"
+```
+
+| Setting | Why |
+|---------|-----|
+| `output: 'export'` | Produces uploadable `out/` folder |
+| `assetPrefix: './'` | Assets work under nested `/sites/{surveyId}/{deployId}/` path |
+| `images.unoptimized` | No server for Next Image Optimization |
+| `index.html.txt` copy | Fixes 403 on `index.html.txt?_rsc` requests |
+
+**Vite:** set `OUT_DIR` to `dist/` at deploy time. Use `base: './'` in `vite.config.ts` if built HTML uses absolute `/` asset paths.
+
+---
+
 ## Vite + React {#vite}
 
 ```bash
@@ -67,6 +102,24 @@ If you hit ESM resolution errors, migrate to Vite or use CRACO to transpile `nod
 
 ---
 
+## Monorepo (`@repo/sdk`) {#monorepo}
+
+When the client app lives in the same monorepo as the SDK:
+
+1. Ensure `package.json` depends on `@repo/sdk` (workspace link).
+2. **Build the SDK before running the client dev server:**
+
+```bash
+cd packages/sdk && npm run build
+```
+
+3. Use `@repo/sdk` in imports and set `transpilePackages: ['@repo/sdk']` in Next.js config.
+4. Rebuild the SDK after any change to `packages/sdk/src/**` — the client reads from `packages/sdk/dist/`.
+
+Missing `dist/index.mjs` causes runtime module-not-found errors. See [`constraints.md`](constraints.md) troubleshooting.
+
+---
+
 ## Framework Detection (for agents)
 
 ```
@@ -78,3 +131,34 @@ else                           → ask client which React setup to use
 ```
 
 For **existing apps**, read `package.json` and project structure — do not scaffold from scratch unless the client asks.
+
+---
+
+## Survey-type conditional dependencies
+
+After fetching the survey, install extra packages only when those types appear:
+
+### RANK_ORDER — dnd-kit (required when survey contains RANK_ORDER)
+
+Install whenever the survey inventory includes **`RANK_ORDER`** — the portable template supports both dropdown and drag-and-drop modes:
+
+```bash
+npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+```
+
+Copy [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx) before building. See [`18-rank-order-scale.md`](../01-components/18-rank-order-scale.md).
+
+### HEATMAP — coordinate normalization
+
+When the survey contains `HEATMAP`, copy the portable coord helper into your project:
+
+```bash
+# Example destination — adjust to your src layout
+cp node_modules/@explorer02/cfm-survey-sdk/templates/docs/templates/heatmapCoords.ts src/lib/heatmapCoords.ts
+```
+
+Monorepo agents: copy from `packages/sdk/templates/docs/templates/heatmapCoords.ts`.
+
+Import `getNormalizedClickFromImage`, `findSpotNearClick`, and `createNewSpot` in `HeatmapScale.tsx`. Do **not** reference monorepo-only paths like `apps/client/src/lib/...` in shipped agent docs.
+
+See [`17-heatmap-scale.md`](../01-components/17-heatmap-scale.md) and [`question-type-sdk-matrix.md#heatmap`](question-type-sdk-matrix.md#heatmap).