@explorer02/cfm-survey-sdk 0.2.0 → 0.2.2

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,242 @@
+# 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) |
+| **Known limitations** | Multi-select array shape is client responsibility; verify `selectionMode` from survey config |
+
+---
+
+## 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 `UploadedFile[]` |
+| **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: UploadedFile[] } }` after upload completes |
+| **Value derivation** | SDK submit maps file metadata to API |
+| **Performance notes** | Upload to presigned URL before CHANGE; show progress UI |
+| **Docs to read** | [`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** | Blocking question — validate file count/size client-side per config |
+
+---
+
+## 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 `HeatmapAnswer` (`{ clicks: HeatmapClickPoint[] }`) |
+| **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: HeatmapAnswer } }` 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 — drag-and-drop mode
+
+When the survey contains `RANK_ORDER` with `interactionMode: 'dragAndDrop'` (or you implement drag UI):
+
+```bash
+npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+```
+
+See [`18-rank-order-scale.md`](../01-components/18-rank-order-scale.md) and [`question-type-sdk-matrix.md#rank_order`](question-type-sdk-matrix.md#rank_order).
+
+### 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).

package/templates/docs/00-integration/skip-logic-and-navigation.md

@@ -0,0 +1,80 @@
+# Skip Logic and Navigation
+
+> Integrator-facing behavior contract. Skip evaluation is handled inside the SDK — do not import internal `surveyLogic` paths.
+
+## When skip rules run
+
+- Skip rules live on individual questions (`question.skipLogics`).
+- When a question has **multiple skip logic blocks**, the SDK evaluates them **top-to-bottom (API order)** and applies the **first** whose condition is true.
+- On **Next**, the SDK evaluates skip logic on the **last question of the current page** only.
+- Skip targets:
+  - `QUESTION` — jump forward to another question's page
+  - `END_OF_SURVEY` — trigger submit flow (validation bypass for skipped pages)
+
+**Forward-only:** backward skip targets are rejected. The respondent cannot skip to an earlier page via skip logic.
+
+## Multiselect MCQ — count of choice
+
+Multiselect MCQ skip rules may use `field: 'NUM_OF_SELECTED_OPTIONS'` (**Count of Choice** in the builder). The SDK compares the number of selected option ids with numeric operators (`EQUALS`, `NOT_EQUALS`, `GT`, `GTE`, `LT`, `LTE`). Zero selections is treated as missing for `MISSING` / `EXISTS`.
+
+## Custom field conditions
+
+Skip rules may reference **custom fields** (`conditionEntity.entityType: 'CUSTOM_FIELD'`). See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) for value shapes, operator contract, and the two wiring points (hook options + visibility helpers).
+
+## Simple example
+
+| Page | Question | Rule |
+|------|----------|------|
+| 1 | Q1 (NPS) | If score > 7 → skip to Q4 |
+| 2 | Q2 | (middle) |
+| 3 | Q3 | (middle) |
+| 4 | Q4 | destination |
+
+1. User sets Q1 = **5** → path is pages 1 → 2 → 3 → 4 (sequential).
+2. User sets Q1 = **9** → simulated path becomes pages **1 → 4** (pages 2–3 skipped).
+3. User clicks **Next** from page 1 → lands on page 4.
+
+## Answer changes (`onChange`)
+
+When the edited question has skip logic, the SDK compares the route **before** and **after** the edit.
+
+| Check | Meaning | SDK action |
+|-------|---------|------------|
+| **Path changed** | Page route reshaped (e.g. sequential → skip) | Clear answers on all pages after current page; reset skip/visit tracking ahead; refresh progress |
+| **Pruned only** | Route unchanged but progress credits were stale | Remove off-path earned credits; refresh progress; **keep answers** |
+
+**Example — path changed:** User walked page 2, answered Q2, then on page 1 changes Q1 from 5 → 9. Q2 answer is cleared because page 2 is no longer on the active path.
+
+**Example — pruned only:** User already on skip path; edits Q1 from 8 → 9 (still skips). Route unchanged; stale progress credits for pages visited earlier may be removed without clearing answers.
+
+## Back navigation
+
+- Back uses **`pageHistory`**, not `currentPageIndex - 1`.
+- After a skip jump (e.g. page 1 → page 4), Back returns to the **skip origin** (page 1), not the sequential previous page.
+- **Answers are preserved on Back** — the SDK does not sanitize answers when going back.
+- Skip/visit tracking for pages ahead of the back target is reset.
+
+## Forward navigation (`onNext`)
+
+- Validates **current page only** before moving.
+- On skip: marks intermediate pages in `skippedPageIndices`; may sanitize answers on skipped pages.
+- Sequential Next skips empty pages automatically.
+
+## Submit validation
+
+- Submit validates **non-skipped pages** only (pages marked skipped via skip logic are excluded).
+- End-of-survey skip triggers submit with `skipValidation: true` for remaining pages.
+
+## Optional question telemetry
+
+When the user leaves a page (Next or Submit), the SDK logs analytics for **optional questions left blank** on that page. This does not block navigation or affect answers.
+
+Event: `optional_question_skipped` with `questionId` and `pageIndex`.
+
+## Client responsibilities
+
+- Wire `onAction({ type: 'NEXT' })`, `onAction({ type: 'PREVIOUS' })`, and `onAction({ type: 'CHANGE', payload: { questionId, answerValue } })`.
+- Use `state.canGoBack` for the Back button (not `currentPageIndex === 0`).
+- Use `state.primaryButtonType` for Next vs Submit label; SDK maps `NEXT` → `SUBMIT` on the last page when appropriate.
+
+See also: [`progress.md`](progress.md), [`useSurveySDK.md`](useSurveySDK.md), [`display-logic-and-navigation.md`](display-logic-and-navigation.md), [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md).