@explorer02/cfm-survey-sdk 0.2.1 → 0.2.2

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

@@ -0,0 +1,174 @@
+# Custom Field Logic and Navigation
+
+> Integrator-facing contract for CRM/transaction custom fields used in skip, display, and answer logic. Evaluation runs inside the SDK — pass values via hook options; do not import internal `surveyLogic` paths.
+
+## When this applies
+
+Survey logic rules may reference **custom fields** instead of survey questions:
+
+```json
+{
+  "conditionEntity": {
+    "id": "_c_6a436c1244764c9d4a6ce2fc",
+    "entityType": "CUSTOM_FIELD",
+    "fieldType": "TEXT"
+  }
+}
+```
+
+Inspect fetched survey data: any `skipLogics`, `displayLogic`, or `answerLogic` with `entityType: 'CUSTOM_FIELD'` requires client-supplied values.
+
+---
+
+## Client value map
+
+Pass via `useSurveySDK({ options: { customFieldValues } })`. Keys are the `_c_…` ids from logic rules.
+
+```typescript
+import type { CustomFieldValueMap } from '@explorer02/cfm-survey-sdk';
+
+const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {
+  '_c_6a436c1244764c9d4a6ce2fc': 'q5',              // TEXT
+  '_c_6a436c3644764c9d4a6ce3f5': 2,                  // NUMBER
+  '_c_6a436c9e44764c9d4a6ce717': 'option-id-uuid',   // PICKLIST
+  '_c_6a436cbb44764c9d4a6ce7e5': ['opt-a', 'opt-b'], // PICKLIST_MULTISELECT
+  '_c_6a4386dc44208eb8b08a9056': 1781029800000,       // DATETIME (epoch ms)
+};
+```
+
+Define **outside** the component (stable ref — same rule as `placeholders`). Wrap hook `options` in `useMemo`.
+
+| Custom field type (`fieldType`) | Client value shape |
+|--------------------------------|-------------------|
+| TEXT / TEXT_MULTI / TEXTAREA | `string` |
+| NUMBER | `number` or numeric string (`0` is valid, not empty) |
+| PICKLIST | `string` (option id) |
+| PICKLIST_MULTISELECT | `string[]` (option ids) |
+| DATETIME | epoch ms (`number` or numeric string); ISO date strings also accepted |
+
+Missing keys in the map are treated as **empty** for logic evaluation.
+
+---
+
+## Operator contract
+
+| fieldType | Logic `field` | Operators |
+|-----------|---------------|-----------|
+| TEXT / TEXT_MULTI / TEXTAREA | `TEXT` or `CASE_SENSITIVE_TEXT` | EQUALS, NOT_EQUALS, CONTAINS, DOES_NOT_CONTAIN, MISSING, EXISTS |
+| NUMBER | `NUMBER` | LT, LTE, GT, GTE, EQUALS, NOT_EQUALS, MISSING, EXISTS |
+| PICKLIST / PICKLIST_MULTISELECT | `SELECTED_OPTIONS` | CONTAINS, DOES_NOT_CONTAIN, MISSING, EXISTS |
+| DATETIME | `SELECTED_DATETIME` | LT, LTE, GT, GTE, EQUALS, NOT_EQUALS |
+
+Filter `values` in API rules use strings (e.g. `'1781029800000'` for datetime). The SDK normalizes client datetime values to epoch ms for comparison.
+
+Datetime filters may include `valueAdditional.timezone` (e.g. `"Asia/Kolkata"`) — reserved for future timezone-aware parsing; comparisons currently use epoch ms numbers.
+
+---
+
+## Two wiring points (CRITICAL)
+
+Custom field values must reach **both** the hook and the question dispatcher:
+
+```mermaid
+flowchart LR
+  CRM["CRM / transaction payload"]
+  Map["CUSTOM_FIELD_VALUES map"]
+  Hook["useSurveySDK options"]
+  Question["Question.tsx"]
+  Nav["Skip / display / validation / progress"]
+  AnswerUI["Answer-logic option/row filtering"]
+
+  CRM --> Map
+  Map --> Hook --> Nav
+  Map --> Question --> AnswerUI
+```
+
+### 1. Hook options (navigation layer)
+
+```typescript
+useSurveySDK({
+  options: {
+    customFieldValues: CUSTOM_FIELD_VALUES,
+  },
+});
+```
+
+SDK uses this for:
+
+- Skip logic path simulation and jumps
+- Question-level display logic (`state.currentQuestions`)
+- Submit / Next validation on the active path
+- Progress bar denominator
+
+### 2. Question visibility helpers (answer-logic UI)
+
+When answer logic conditions reference custom fields, pass the **same map** to exported helpers:
+
+```typescript
+import {
+  getVisibleMcqOptionsForAnswers,
+  getVisibleMatrixItemsForAnswers,
+  getVisibleStatementRowsForAnswers,
+  getVisibleScaleColumnsForAnswers,
+} from '@explorer02/cfm-survey-sdk';
+
+getVisibleMcqOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues);
+getVisibleMatrixItemsForAnswers(question, allAnswers, allQuestions, customFieldValues);
+```
+
+Without the 4th argument, answer-logic UI defaults to an empty custom-field map — options/rows gated on CRM data may render incorrectly even though navigation logic works.
+
+**SurveyPage → Question prop threading:**
+
+```tsx
+<Question
+  customFieldValues={CUSTOM_FIELD_VALUES}
+  allAnswers={state.answers}
+  allQuestions={allQuestions}
+  // ...
+/>
+```
+
+---
+
+## Discovering field ids
+
+After fetching the survey with `instanceId`, search logic payloads for `_c_` ids:
+
+- `question.skipLogics[].condition.filters`
+- `question.displayLogic.condition.filters`
+- `question.options[].answerLogic` / matrix row `answerLogic` / column `answerLogic`
+
+Record each id in `implementation_plan.md` §3c and populate `CUSTOM_FIELD_VALUES` from your CRM/transaction API.
+
+---
+
+## Example — skip rule on custom field
+
+Rule: if TEXT custom field `_c_abc` equals `"premium"`, skip to Q6.
+
+```typescript
+const CUSTOM_FIELD_VALUES = { '_c_abc': 'premium' };
+
+useSurveySDK({ options: { instanceId, customFieldValues: CUSTOM_FIELD_VALUES } });
+```
+
+User clicks Next on page 1 → SDK evaluates condition → jumps to Q6's page. No extra client code per question.
+
+If the user later changes a CRM field value at runtime, update `customFieldValues` via a new stable map and remount or pass updated options through `useMemo` deps.
+
+---
+
+## Multiple skip logic blocks
+
+When a question has several `skipLogics[]` entries (including custom-field rules), the SDK evaluates them **top-to-bottom** and applies the **first match**. See [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md).
+
+---
+
+## Related docs
+
+- [`useSurveySDK.md`](useSurveySDK.md) — hook options and stable refs
+- [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md) — skip behavior with custom fields
+- [`display-logic-and-navigation.md`](display-logic-and-navigation.md) — question-level gating
+- [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md) — option/row/column gating + visibility helpers
+- [`client-integration-guide.md`](client-integration-guide.md) — full wiring map

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

@@ -0,0 +1,49 @@
+# Display Logic and Navigation
+
+> Integrator-facing behavior contract. Display evaluation is handled inside the SDK — do not import internal `surveyLogic` paths directly unless using exported helpers.
+
+## Shared engine with skip logic
+
+Skip logic, display logic, and answer logic use the **same condition tree** (`LogicFilterGroup` with nested `AND` / `OR` groups) and the **same evaluator** (`evaluateCondition`). The SDK distinguishes them with `LOGIC_KIND`:
+
+| Kind | When true |
+|------|-----------|
+| `SKIP` | Navigate to skip target or end of survey |
+| `DISPLAY` | Show the gated **question** (whole question / page-level) |
+| `ANSWER` | Show a gated **option, statement row, or scale column** within a question |
+
+> **Note:** Statement-row and scale-column filtering is **answer logic**, not display logic. See [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md).
+
+## Dynamic vs non-dynamic
+
+| Mode | API flag | Behavior |
+|------|----------|----------|
+| **Dynamic** | `isDynamicAppearanceEnabled: true` | Gated question stays on the **same page** as trigger questions. Hidden until condition is true. Page stays on active path; hidden questions are excluded from progress denominator. |
+| **Non-dynamic** | `isDynamicAppearanceEnabled: false` | Gated question is on a **separate page**. When condition is false, that page is skipped in navigation and excluded from active path. |
+
+## Nested conditions
+
+Both skip and display support nested AND/OR groups from the API. Flat skip rows (`Q3 = 1 OR Q3 = 2 OR Q3 > 6`) and nested display condition groups map to the same recursive tree.
+
+## Client responsibilities
+
+- Use `state.currentQuestions` from `useSurveySDK` — the SDK filters hidden questions automatically.
+- Matrix UIs must filter statement rows with `getVisibleStatementRowsForAnswers(question, answers, allQuestions)` (or `getVisibleMatrixItemsForAnswers` for rows + scale columns).
+- Wire `onAction({ type: 'CHANGE' })` so display conditions re-evaluate when answers change.
+
+## Progress bar
+
+Progress counts **visible answerable questions on the active path**. When display logic hides a question:
+
+- **Dynamic:** page remains on path; hidden question excluded from total until visible.
+- **Non-dynamic:** gated page excluded from path until condition is true.
+
+## Custom field conditions
+
+Display logic may gate questions on **custom field** values (`conditionEntity.entityType: 'CUSTOM_FIELD'`). See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) for the full integration contract.
+
+## Question display variants (distinct from show/hide)
+
+Alternate question wording (`questionDisplayVariants`) uses the same condition engine but **does not hide** the question — the SDK resolves `questionText` on `state.currentQuestions`. See [`question-display-variants.md`](question-display-variants.md).
+
+See also: [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md), [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md), [`progress.md`](progress.md).

package/templates/docs/00-integration/end-page-logic.md

@@ -0,0 +1,64 @@
+# End Page Logic
+
+> Integrator-facing contract for surveys with **multiple end pages**. Selection runs inside the SDK at submit time — do not import internal `surveyLogic` paths.
+
+## When it runs
+
+After a **successful submit**, the SDK evaluates each end page's `displayLogic` (mapped from API `controlConfig.displayLogic`) and sets `state.phase` to `{ kind: 'end', endPageId }`. The client renders `state.specialPage` — no extra wiring.
+
+## Selection rules
+
+End pages are evaluated in **API order**:
+
+1. **Conditional pages** — pages with `displayLogic`: return the **first** whose condition is true (same evaluator as question display logic: nested AND/OR, question answers, custom fields).
+2. **Default page** — if no conditional page matches, use the **first page without** `displayLogic`.
+3. **Safety fallback** — if every page has logic and none match, use `endPages[0]`.
+
+`isDynamicAppearanceEnabled` on end pages is ignored (evaluation happens once at submit).
+
+## Default vs conditional pages
+
+Typical builder setup:
+
+| End page | `displayLogic` | Role |
+|----------|----------------|------|
+| End Page | none | Default thank-you screen |
+| End Page 2 | OR/AND conditions | Shown when rules match |
+
+Example: show **End Page 2** when multiselect MCQ **contains** Option 1 **and** Option 3 (both must be selected). Otherwise show the default end page.
+
+For `SELECTED_OPTIONS` / `CONTAINS`, multiple values in the rule mean **all** listed options must be selected (Sprinklr multiselect semantics). A single listed option still matches when only that option is selected.
+
+## Custom fields
+
+When end-page rules reference `conditionEntity.entityType: 'CUSTOM_FIELD'`, pass the same `options.customFieldValues` map used for skip/display logic:
+
+```typescript
+useSurveySDK(instanceId, {
+  customFieldValues: {
+    '_c_6a436c1244764c9d4a6ce2fc': 'end2',
+    '_c_6a436c3644764c9d4a6ce3f5': 2,
+  },
+});
+```
+
+Without this map, custom-field branches evaluate as empty/missing.
+
+### OR branches and static mock values
+
+Conditional end pages often use **OR** groups (any branch true → show that page). If `customFieldValues` includes a value that satisfies one branch unconditionally—e.g. number field `= 2` while the survey has `NUMBER EQUALS 2` in an OR branch—that end page will **always** win at submit, even when MCQ/NPS answers would otherwise show the default page.
+
+When testing answer-driven branches, omit unrelated custom-field keys or set them to values that do not match other OR branches.
+
+## Client responsibilities
+
+- Render `<EndPage page={state.specialPage} />` when `state.phase.kind === 'end'`.
+- Use `state.phase.endPageId` (and `options.debug`) during development to verify selection when headers match.
+- Pass `customFieldValues` via hook options when the survey's end pages reference custom fields.
+- No logic evaluation in the client — the SDK resolves `endPageId` before setting phase.
+
+## Supported condition fields
+
+Same as skip/display logic: `SELECTED_OPTIONS`, `NUM_OF_SELECTED_OPTIONS`, `TEN_POINT_SCALE`, `TEXT`, `CASE_SENSITIVE_TEXT`, custom-field `NUMBER`, `PICKLIST`, `DATETIME`, etc.
+
+See also: [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md), [`display-logic-and-navigation.md`](display-logic-and-navigation.md), [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md), [`01-components/15-end-page.md`](../01-components/15-end-page.md).

package/templates/docs/00-integration/partial-save-and-recovery.md

@@ -0,0 +1,74 @@
+# Partial Save and Recovery
+
+> Covers `sdkFeatures.partialSave` — debounced autosave of in-progress responses.
+
+---
+
+## When to enable
+
+Pass in `useSurveySDK` options:
+
+```typescript
+useSurveySDK({
+  ...surveyOptions,
+  savePartialResponse: true,           // default debounce
+  // or
+  savePartialResponse: { debounceMs: 1500 },
+});
+```
+
+Enable when the survey config or client prompt requires resume/recovery UX. If not requested, omit the option.
+
+---
+
+## `partialSaveResults` shape
+
+Same surface as submit results (type inferred from hook return):
+
+| Field | Meaning |
+|-------|---------|
+| `partialSaveResults.data` | Last successful partial save payload (`SubmitResult \| null`) |
+| `partialSaveResults.isLoading` | POST in flight |
+| `partialSaveResults.error` | Last failure |
+
+Monitor these for optional "Saving…" / error toasts. Do **not** reimplement the POST endpoint logic client-side.
+
+---
+
+## Interaction with skip / display logic
+
+When skip or display logic hides a question, the SDK **sanitizes** answers for questions no longer on the active path before partial save. Client components should not manually delete hidden answers — the SDK handles consistency on path changes.
+
+After a partial save succeeds, reloading the survey instance may restore prior answers depending on backend behavior (outside SDK scope).
+
+---
+
+## When partial save starts
+
+Partial saves begin only after the **first user interaction** (a real `CHANGE` action). MCQ default seeding or programmatic answer init does not trigger an immediate save.
+
+Each subsequent debounced answer change triggers another partial save with `surveySubmitted: false`.
+
+---
+
+## Error UX patterns
+
+| Scenario | Recommended UX |
+|----------|----------------|
+| Transient network error | Silent retry on next debounced change; optional subtle indicator |
+| Persistent error | Non-blocking banner: "Unable to save progress" |
+| Success | Usually no UI — optional checkmark on footer |
+
+Do not block navigation (NEXT/PREVIOUS) on partial save failure unless product explicitly requires it.
+
+---
+
+## Verify checklist
+
+- [ ] `savePartialResponse` only set when required
+- [ ] No duplicate fetch/submit logic outside SDK
+- [ ] `TEXT_AND_MEDIA` questions produce no CHANGE (correct — no answer to save)
+- [ ] Hidden-path answers not manually managed in client state
+- [ ] Optional UI wired to `partialSaveResults.isLoading` / `.error`
+
+See [`useSurveySDK.md`](useSurveySDK.md) for hook signature and [`client-integration-guide.md`](client-integration-guide.md) for full wiring map.

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).