@explorer02/cfm-survey-sdk 0.2.0 → 0.2.2

package/templates/docs/01-components/18-rank-order-scale.md

@@ -0,0 +1,100 @@
+# Rank Order Architectural Blueprint
+
+> **UI spec (authoritative):** `03-ui-specs/14-rank-order.md`
+> **Reference implementation:** `apps/client/src/components/RankOrderScale.tsx`
+> **Target Component:** `RankOrderScale`
+> **Handles:** `type: 'RANK_ORDER'`
+
+## Core Responsibility
+
+Render rankable options in either **dropdown** or **drag-and-drop** mode, support three option display variants (text only, image only, text and image), and bubble rank assignments via `onSelect`.
+
+## Props Contract
+
+```typescript
+type RankOrderScaleProps = {
+  question: RankOrderQuestion;
+  selectedValue?: RankOrderAnswers;
+  onSelect: (value: RankOrderAnswers) => void;
+};
+```
+
+## State Management
+
+- `selectedValue` from SDK is source of truth — do not duplicate answer state locally
+- Dropdown mode: use `assignRankWithoutDuplicates` from SDK when a rank changes
+- Drag-and-drop mode: use `buildRankOrderFromOrderedOptionIds` after reorder
+
+## Layout Orchestrator
+
+```tsx
+export function RankOrderScale({ question, selectedValue, onSelect }: RankOrderScaleProps) {
+  if (question.interactionMode === 'dragAndDrop') {
+    return <DragDropRankLayout ... />;
+  }
+  return <DropdownRankLayout ... />;
+}
+```
+
+## Dropdown Mode
+
+- One row per visible option
+- Left: rank `<select>` with `-` (unassigned) and `1..N`
+- Selecting rank `R` clears `R` from any other option (SDK helper)
+- Option content depends on `question.optionDisplay`
+- **Image URLs:** prefer `option.imageUrl` over `option.previewImageUrl` — preview `*_p.*` URLs often return 403 on CloudFront
+
+## Drag-and-Drop Mode
+
+- Use `@dnd-kit/core` + `@dnd-kit/sortable` for smooth reorder
+- List order maps to ranks: position 0 → rank 1
+- Show rank badge on each row
+- Provide Up/Down buttons for keyboard accessibility
+
+## Wiring in Question.tsx
+
+```typescript
+import {
+  QUESTION_TYPE,
+  getVisibleRankOrderOptionsForAnswers,
+} from '@explorer02/cfm-survey-sdk';
+
+const rankOrderQuestion = useMemo(() => {
+  if (question.type !== QUESTION_TYPE.RANK_ORDER) return null;
+  return {
+    ...question,
+    options: getVisibleRankOrderOptionsForAnswers(
+      question,
+      allAnswers,
+      allQuestions,
+      customFieldValues
+    ),
+  };
+}, [question, allAnswers, allQuestions, customFieldValues]);
+
+{question.type === QUESTION_TYPE.RANK_ORDER && rankOrderQuestion && (
+  <RankOrderScale
+    question={rankOrderQuestion}
+    selectedValue={...}
+    onSelect={onSelect}
+  />
+)}
+```
+
+## Dependencies
+
+Add to client `package.json`:
+
+- `@dnd-kit/core`
+- `@dnd-kit/sortable`
+- `@dnd-kit/utilities`
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.RANK_ORDER`
+- [ ] Answer stored as: `RankOrderAnswers`
+- [ ] onAction CHANGE: `{ questionId, answerValue: RankOrderAnswers }`
+- [ ] Visibility helper: `getVisibleRankOrderOptionsForAnswers(..., customFieldValues?)`
+- [ ] Rank utils: `assignRankWithoutDuplicates`, `buildRankOrderFromOrderedOptionIds`, `normalizeRankOrderAnswers`
+- [ ] Prefer `option.imageUrl` over `previewImageUrl`
+- [ ] Matrix row: [`question-type-sdk-matrix.md#rank_order`](../00-integration/question-type-sdk-matrix.md#rank_order)

package/templates/docs/01-components/README.md

@@ -1,48 +1,51 @@
 # Client Components Overview
 
-> Wiring blueprints for React components. **Authoritative UI details** are in [`03-ui-specs/`](../03-ui-specs/README.md) (reference-client driven).
-> This folder documents props, `onSelect` wiring, and dispatcher architecture.
+> Wiring blueprints for React components. **Authoritative UI details** are in [`03-ui-specs/`](../03-ui-specs/README.md).
+> **Required files gate:** [`component-checklist.md`](../00-integration/component-checklist.md)
+> **Dispatcher template:** [`templates/Question.tsx`](../templates/Question.tsx)
+> Read blueprints **per type** from `MANIFEST.json` after survey inventory — not all files are needed for every survey.
 
 ## Component Architecture
 
-The UI is driven by a single top-level `SurveyPage` component which iterates over the `currentQuestions` array and passes each `SurveyQuestion` object to the `Question` dispatcher component.
+The UI is driven by `SurveyPage`, which routes by `state.phase` and renders `Question` for each item in `currentQuestions`.
 
 ```
-SurveyPage (Top-level orchestrator)
+SurveyPage (phase router)
    │
-   ├── Header (Branding/Logo)
-   ├── ProgressBar
-   ├── LanguageSelector
-   ├── Footer
+   ├── IntroPage / PausedPage / EndPage (special phases)
    │
-   └── Question (Dispatcher, mapped over `currentQuestions`)
-         │
-         ├── RatingScale (handles 'rating' and 'rating_scale')
-         ├── CsatScale (handles 'csat')
-         ├── LikertMatrixScale (handles 'matrix' CFM_MATRIX)
-         ├── CsatMatrixScale (handles 'matrix' CSAT_MATRIX / 'rating_matrix')
-         ├── SliderMatrixScale (handles 'slider_matrix')
-         ├── FileUploadScale (handles 'file_upload')
-         │
-         ├── (Inline UI for 'radio', 'text', 'text_and_media')
-         │
-         └── Shared Sub-Components:
-               ├── CustomSliderTrack (used by csat/matrix sliders)
-               └── MatrixDropdown (used by matrix dropdowns)
+   └── SurveyContent (phase.kind === 'content')
+         ├── Header
+         ├── ProgressBar
+         ├── LanguageSelector
+         ├── Question × N (dispatcher)
+         ├── Back / Next|Submit nav
+         └── Footer
 ```
 
-## Styling Approach
+## Question dispatcher (11 types)
 
-- Built entirely with **Tailwind CSS**.
-- **No external UI libraries** (no Material UI, Chakra, etc.).
-- The default brand colour is Telekom Magenta: `#e20074`.
-- The UI follows a strict, clean, modern corporate aesthetic (card-based layout, subtle borders, pink accents on selection).
+`Question` switches on `question.type` / `QUESTION_TYPE` (no `subType`):
+
+| Type | Component |
+|------|-----------|
+| `NPS_SCALE` | `RatingScale` |
+| `MCQ`, `TEXTFIELD`, `TEXT_AND_MEDIA` | Inline in `Question` |
+| `CFM_MATRIX` | `LikertMatrixScale` |
+| `CSAT_MATRIX`, `RATING_MATRIX` | `CsatMatrixScale` |
+| `SLIDER_MATRIX` | `SliderMatrixScale` |
+| `FILE_UPLOAD` | `FileUploadScale` |
+| `HEATMAP` | `HeatmapScale` |
+| `RANK_ORDER` | `RankOrderScale` |
 
-## The `Question` Dispatcher
+Shared: `CustomSliderTrack`, `MatrixDropdown`
 
-The `Question` component is the heart of the rendering engine. It receives a `SurveyQuestion` union type and switches on `question.type` (and `question.subType` for matrices) to render the correct specialized scale component.
+## Styling Approach
 
-See `02-question.md` for details on the dispatcher logic.
+- Built entirely with **Tailwind CSS**.
+- **No external UI libraries** (no Material UI, Chakra, etc.).
+- Default brand colour: Telekom Magenta `#e20074`.
+- Card-based layout, subtle borders, pink accents on selection.
 
 ## Files in This Folder
 
@@ -50,14 +53,19 @@ See `02-question.md` for details on the dispatcher logic.
 |------|-----------|
 | `01-survey-page.md` | `SurveyPage` orchestrator |
 | `02-question.md` | `Question` dispatcher & inline types |
-| `03-rating-scale.md` | `RatingScale` (NPS/Stars) |
-| `04-csat-scale.md` | `CsatScale` (Emoji/Star CSAT) |
-| `05-csat-matrix-scale.md` | `CsatMatrixScale` (Satisfaction Grid) |
-| `06-likert-matrix-scale.md` | `LikertMatrixScale` (Text Grid) |
-| `07-slider-matrix-scale.md` | `SliderMatrixScale` (Sliders Grid) |
+| `03-rating-scale.md` | `RatingScale` (NPS) |
+| `04-star-rating-scale.md` | Legacy star patterns (deprecated) |
+| `05-csat-matrix-scale.md` | `CsatMatrixScale` |
+| `06-likert-matrix-scale.md` | `LikertMatrixScale` |
+| `07-slider-matrix-scale.md` | `SliderMatrixScale` |
 | `08-file-upload-scale.md` | `FileUploadScale` |
-| `09-custom-slider-track.md` | `CustomSliderTrack` (Emoji thumbs) |
+| `09-custom-slider-track.md` | `CustomSliderTrack` |
 | `10-header-footer.md` | `Header` & `Footer` |
 | `11-progress-bar.md` | `ProgressBar` |
 | `12-language-selector.md` | `LanguageSelector` |
 | `13-matrix-dropdown.md` | `MatrixDropdown` |
+| `14-intro-page.md` | `IntroPage` |
+| `15-end-page.md` | `EndPage` |
+| `16-paused-page.md` | `PausedPage` |
+| `17-heatmap-scale.md` | `HeatmapScale` |
+| `18-rank-order-scale.md` | `RankOrderScale` |

package/templates/docs/02-reference/config-field-index.md

@@ -1,158 +1,160 @@
 # Config Field Index
 
-> Master map: every SDK config field → reference client file → implemented? → UI spec doc.
+> Master map: every SDK config field → UI spec doc.
 > Cross-check this when building any question with non-default config.
 
-## QuestionBase (all types)
-
-| Field | Types | Client file | Implemented? | Spec doc |
-|-------|-------|-------------|--------------|----------|
-| `id` | all | Question.tsx | ✅ | 00-question-shell |
-| `text` | all | Question.tsx | ✅ | 00-question-shell |
-| `description` | all | Question.tsx | ✅ | 00-question-shell |
-| `required` | all | Question.tsx | ✅ | 00-question-shell |
-| `requiredErrorMessage` | all | Question.tsx | ✅ | 00-question-shell |
-| `questionNumber` | all | — | ❌ | 00-question-shell |
-| `containerMediaUrl` | all | — | ❌ | 00-question-shell |
-| `containerMediaMimeType` | all | — | ❌ | 00-question-shell |
-| `containerMediaAlignment` | all | — | ❌ | 00-question-shell |
-| `containerMediaSize` | all | — | ❌ | 00-question-shell |
-
-## rating
-
-| Field | Values | Client file | Implemented? | Spec doc |
-|-------|--------|-------------|--------------|----------|
-| `options[]` | SurveyOption[] | RatingScale.tsx | ✅ | 01-rating |
-| `options[].color` | hex | RatingScale.tsx | ✅ | 01-rating |
-| `minLabel` | string | Question.tsx | ✅ | 01-rating |
-| `midLabel` | string | Question.tsx | ✅ | 01-rating |
-| `maxLabel` | string | Question.tsx | ✅ | 01-rating |
-| `midLabelIndex` | number | Question.tsx | ✅ | 01-rating |
-| `reverseScaleOrder` | boolean | — | ❌ | 01-rating |
-| `buttonVariant` | radio/numbered/emoji | — | ❌ | 01-rating |
-
-## radio
-
-| Field | Values | Client file | Implemented? | Spec doc |
-|-------|--------|-------------|--------------|----------|
-| `options[]` | SurveyOption[] | Question.tsx | ✅ | 02-radio |
-| `isMultiSelect` | boolean | — | ❌ | 02-radio |
-
-## text
-
-| Field | Values | Client file | Implemented? | Spec doc |
-|-------|--------|-------------|--------------|----------|
-| `placeholder` | string | Question.tsx | ✅ | 03-text |
-| `maxCharacterCount` | number | Question.tsx | ✅ | 03-text |
-| `inputVariant` | long/short | Question.tsx | partial | 03-text |
-
-## csat
-
-| Field | Values | Client file | Implemented? | Spec doc |
-|-------|--------|-------------|--------------|----------|
-| `options[]` | SurveyOption[] | CsatScale.tsx | ✅ | 04-csat |
-| `buttonType` | emoji/star/numbered/... | CsatScale.tsx | ✅ | 04-csat |
-| `labelPosition` | top/bottom/hidden | CsatScale.tsx | ✅ | 04-csat |
-| `minLabel` / `maxLabel` | string | Question.tsx | ✅ | 04-csat |
-| `hasNotApplicable` | boolean | — | ❌ | 04-csat |
-| `reverseScaleOrder` | boolean | — | ❌ | 04-csat |
-
-## rating_scale
-
-| Field | Values | Client file | Implemented? | Spec doc |
-|-------|--------|-------------|--------------|----------|
-| `options[]` | SurveyOption[] | — | ❌ | 05-rating-scale |
-| `scaleStyle` | star/emoji | — | ❌ | 05-rating-scale |
-| `minLabel` / `midLabel` / `maxLabel` | string | — | ❌ | 05-rating-scale |
-| `midLabelIndex` | number | — | ❌ | 05-rating-scale |
-| `reverseScaleOrder` | boolean | — | ❌ | 05-rating-scale |
+## Question shell (all types)
+
+| Field | Types | Spec doc |
+|-------|-------|----------|
+| `id` | all | 00-question-shell |
+| `questionText` | all | 00-question-shell |
+| `questionDescription` | all | 00-question-shell |
+| `questionHint` | all | 00-question-shell |
+| `required` | all | 00-question-shell |
+| `requiredErrorMessage` | all | 00-question-shell |
+| `questionNumber` | all | 00-question-shell |
+| `containerMedia` | ContainerMedia? | 00-question-shell |
+| `containerMedia.url` | string | 00-question-shell |
+| `containerMedia.mimeType` | string | 00-question-shell |
+| `containerMedia.alignment` | string | 00-question-shell |
+| `containerMedia.size` | number | 00-question-shell |
+
+## nps
+
+| Field | Values | Spec doc |
+|-------|--------|----------|
+| `options[]` | NpsScalePoint[] | 01-rating |
+| `minLabel` / `midLabel` / `maxLabel` | string | 01-rating |
+| `midLabelIndex` | number | 01-rating |
+| `reverseScaleOrder` | boolean | 01-rating |
+| `buttonStyle` | standard/numbered/emoji | 01-rating |
+
+## mcq
+
+| Field | Values | Spec doc |
+|-------|--------|----------|
+| `options[]` | McqOption[] | 02-radio |
+| `selectionMode` | single/multiple | 02-radio |
+| `displayFormat` | list/grid | 02-radio |
+| `shuffleOptions` | boolean | 02-radio |
+| `columnCount` | number | 02-radio |
+
+## text_input
+
+| Field | Values | Spec doc |
+|-------|--------|----------|
+| `placeholder` | string | 03-text |
+| `maxCharacterCount` | number | 03-text |
+| `inputVariant` | long/short | 03-text |
+
+## csat (matrix grid)
+
+| Field | Values | Spec doc |
+|-------|--------|----------|
+| `statementRows[]` | CsatStatementRow[] | 04-csat |
+| `scaleColumns[]` | CsatScaleColumn[] | 04-csat |
+| `displayStyle` | emoji/star/standard/numbered/dropdown/selectbox/graphics | 04-csat |
+| `gridLayout` | standard/carousel/dropdown | 04-csat |
+| `hasNotApplicableOption` | boolean | 04-csat |
+| `reverseScaleOrder` | boolean | 04-csat |
+| `scaleAnchorLabels[]` | string[] | 04-csat |
+
+## star_rating
+
+| Field | Values | Spec doc |
+|-------|--------|----------|
+| `options[]` | StarRatingPoint[] | 05-rating-scale |
+| `scaleStyle` | star/emoji | 05-rating-scale |
+| `minLabel` / `midLabel` / `maxLabel` | string | 05-rating-scale |
+| `midLabelIndex` | number | 05-rating-scale |
+| `reverseScaleOrder` | boolean | 05-rating-scale |
 
 ## slider
 
-| Field | Values | Client file | Implemented? | Spec doc |
-|-------|--------|-------------|--------------|----------|
-| `min` / `max` / `step` | number | — | ❌ | 06-slider |
-| `defaultValue` | number | — | ❌ | 06-slider |
-| `minLabel` / `maxLabel` | string | — | ❌ | 06-slider |
-| `enableInputBox` | boolean | SliderMatrixScale.tsx | partial | 06-slider |
-| `displayValues` | boolean | CustomSliderTrack.tsx | partial | 06-slider, shared/custom-slider-track |
-
-## matrix (shared)
-
-| Field | Values | Client file | Implemented? | Spec doc |
-|-------|--------|-------------|--------------|----------|
-| `subType` | CFM/CSAT/RATING | Question.tsx | ✅ | 07, 08 |
-| `rows[]` | MatrixRow[] | Likert/CsatMatrix | ✅ | 07, 08 |
-| `columns[]` | MatrixColumn[] | Likert/CsatMatrix | ✅ | 07, 08 |
-| `matrixFormat` | standard/carousel/dropdown | Likert/CsatMatrix | ✅ | 07, 08 |
-| `hasNotApplicable` | boolean | Likert/CsatMatrix | ✅ | 07, 08 |
-| `reverseScaleOrder` | boolean | CsatMatrixScale | ✅ | 08 |
-| `labels[]` | string[] | Likert/CsatMatrix | ✅ | 07, 08 |
-| `buttonType` | SurveyButtonType | CsatMatrixScale | ✅ | 08 |
-
-## matrix — CFM only
-
-| Field | Values | Client file | Implemented? | Spec doc |
-|-------|--------|-------------|--------------|----------|
-| `matrixType` | likert/bipolar | LikertMatrixScale | ✅ | 07-matrix-cfm |
-| `answerType` | single/multiple | LikertMatrixScale | ✅ | 07-matrix-cfm |
-| `transposeTable` | boolean | LikertMatrixScale | ✅ | 07-matrix-cfm |
-| `repeatScale` | boolean | LikertMatrixScale | ✅ | 07-matrix-cfm |
-| `enableScale` | boolean | LikertMatrixScale | ✅ | 07-matrix-cfm |
+| Field | Values | Spec doc |
+|-------|--------|----------|
+| `min` / `max` / `step` | number | 06-slider |
+| `defaultValue` | number | 06-slider |
+| `minLabel` / `maxLabel` | string | 06-slider |
+| `enableInputBox` | boolean | 06-slider |
+| `displayValues` | boolean | 06-slider, shared/custom-slider-track |
+
+## cfm_matrix
+
+| Field | Values | Spec doc |
+|-------|--------|----------|
+| `statementRows[]` | CfmMatrixStatementRow[] | 07-matrix-cfm |
+| `scaleColumns[]` | CfmMatrixScaleColumn[] | 07-matrix-cfm |
+| `statementLayout` | likert/bipolar | 07-matrix-cfm |
+| `selectionMode` | single/multiple | 07-matrix-cfm |
+| `gridLayout` | standard/carousel/dropdown | 07-matrix-cfm |
+| `transposeTable` | boolean | 07-matrix-cfm |
+| `repeatColumnHeaders` | boolean | 07-matrix-cfm |
+| `showColumnHeaders` | boolean | 07-matrix-cfm |
+| `hasNotApplicableOption` | boolean | 07-matrix-cfm |
+| `scaleAnchorLabels[]` | string[] | 07-matrix-cfm |
+
+## rating_matrix
+
+| Field | Values | Spec doc |
+|-------|--------|----------|
+| Same matrix fields as `csat` | — | 08-matrix-csat-rating |
+| `minLabel` / `maxLabel` | string | 08-matrix-csat-rating |
 
 ## slider_matrix
 
-| Field | Values | Client file | Implemented? | Spec doc |
-|-------|--------|-------------|--------------|----------|
-| `rows[].min/max/step` | number | SliderMatrixScale | ✅ | 09-slider-matrix |
-| `labels[]` | string[] | SliderMatrixScale | ✅ | 09-slider-matrix |
-| `ticks` | number | SliderMatrixScale | ✅ | 09-slider-matrix |
-| `tickValues[]` | TickValue[] | SliderMatrixScale | ✅ | 09-slider-matrix |
-| `enableInputBox` | boolean | SliderMatrixScale | ✅ | 09-slider-matrix |
-| `displayValues` | boolean | CustomSliderTrack | ✅ | 09-slider-matrix |
-| `enableNotApplicable` | boolean | SliderMatrixScale | ✅ | 09-slider-matrix |
-| `sliderType` | graphics | SliderMatrixScale | ✅ | 09-slider-matrix |
+| Field | Values | Spec doc |
+|-------|--------|----------|
+| `statementRows[].min/max/step` | number | 09-slider-matrix |
+| `scaleAnchorLabels[]` | string[] | 09-slider-matrix |
+| `tickMarks` | number | 09-slider-matrix |
+| `enableInputBox` | boolean | 09-slider-matrix |
+| `displayValues` | boolean | 09-slider-matrix |
+| `hasNotApplicableOption` | boolean | 09-slider-matrix |
+| `sliderStyle` | graphics | 09-slider-matrix |
 
 ## file_upload
 
-| Field | Values | Client file | Implemented? | Spec doc |
-|-------|--------|-------------|--------------|----------|
-| `uploadMessage` | HTML string | FileUploadScale | ✅ | 10-file-upload |
-| `supportedFileFormats` | string[] | FileUploadScale | ✅ | 10-file-upload |
-| `maxFileCount` | number | FileUploadScale | ✅ | 10-file-upload |
-| `fileSizeLimit` | number (MB) | FileUploadScale | ✅ | 10-file-upload |
-| `fileSizeLimitType` | PER_FILE/IN_TOTAL | FileUploadScale | ✅ | 10-file-upload |
+| Field | Values | Spec doc |
+|-------|--------|----------|
+| `uploadMessage` | HTML string | 10-file-upload |
+| `supportedFileFormats` | string[] | 10-file-upload |
+| `maxFileCount` | number | 10-file-upload |
+| `fileSizeLimit` | number (MB) | 10-file-upload |
+| `fileSizeLimitType` | PER_FILE/IN_TOTAL | 10-file-upload |
 
 ## text_and_media
 
-| Field | Values | Client file | Implemented? | Spec doc |
-|-------|--------|-------------|--------------|----------|
-| `mediaUrl` | string | Question.tsx | ✅ | 11-text-and-media |
-| `mediaMimeType` | string | Question.tsx | ✅ | 11-text-and-media |
-| `mediaTitle` | string | Question.tsx | ✅ | 11-text-and-media |
-| `mediaAlignment` | string | Question.tsx | ✅ | 11-text-and-media |
-| `mediaSize` | number (%) | Question.tsx | ✅ | 11-text-and-media |
-
-## Implementation Gaps (no client branch yet)
-
-| Gap | SDK type/field | Extend from |
-|-----|----------------|-------------|
-| `rating_scale` dispatcher | `type: 'rating_scale'` | CsatScale star/emoji patterns |
-| `slider` dispatcher | `type: 'slider'` | CustomSliderTrack + SliderMatrixScale row |
-| `radio.isMultiSelect` | checkbox cards | 02-radio card styling |
-| `text.inputVariant: 'short'` | single-line input | 03-text focus tokens |
-| `rating.reverseScaleOrder` | reverse options array | 01-rating |
-| `rating.buttonVariant` | numbered clickable badges | 01-rating |
-| `csat.hasNotApplicable` / `reverseScaleOrder` | standalone CSAT | 04-csat, 08-matrix N/A |
-| `containerMedia*` on any type | container asset | 11-text-and-media media block |
-
-## buttonType × matrixFormat Quick Reference
-
-| buttonType | matrixFormat | Layout component | Spec |
-|------------|--------------|------------------|------|
+| Field | Values | Spec doc |
+|-------|--------|----------|
+| `media` | QuestionMedia? | 11-text-and-media |
+| `media.url` | string | 11-text-and-media |
+| `media.mimeType` | string | 11-text-and-media |
+| `media.title` | string | 11-text-and-media |
+| `media.alignment` | string | 11-text-and-media |
+| `media.size` | number | 11-text-and-media |
+| `mediaTitle` | string | 11-text-and-media |
+| `mediaAlignment` | string | 11-text-and-media |
+| `mediaSize` | number (%) | 11-text-and-media |
+
+## displayStyle × gridLayout Quick Reference
+
+| displayStyle | gridLayout | Layout component | Spec |
+|--------------|------------|------------------|------|
 | (CFM default) | standard | LikertMatrixGrid | 07 |
 | (CFM default) | carousel | LikertMatrixCarousel | 07 |
 | (CFM default) | dropdown | LikertMatrixDropdown | 07 |
-| emoji/star/numbered | standard | CsatMatrixGrid | 08 |
-| emoji/star/numbered/graphics | carousel | CsatMatrixCarousel | 08 |
-| dropdown/selectbox/radio | any | CsatMatrixVerticalList | 08 |
+| emoji/star/numbered | standard | CsatMatrixGrid | 04 |
+| emoji/star/numbered/graphics | carousel | CsatMatrixCarousel | 04 |
+| dropdown/selectbox | any | CsatMatrixVerticalList | 04 |
+
+## Shared spec triggers
+
+When these config values appear, also read `03-ui-specs/shared/`:
+
+| Config | Read |
+|--------|------|
+| `gridLayout: dropdown` | `matrix-dropdown.md` |
+| `displayStyle: dropdown` or `selectbox` | `matrix-dropdown.md` |
+| `displayStyle: graphics` or `sliderStyle: graphics` | `custom-slider-track.md` |

package/templates/docs/02-reference/exports.md

@@ -0,0 +1,149 @@
+# SDK Public Exports
+
+> Import **only** from the package root. Never from `/src/` paths.
+
+```typescript
+import {
+  useSurveySDK,
+  ACTIONS,
+  QUESTION_TYPE,
+  type SurveyAction,
+  type UseSurveySDKProps,
+  type UseSurveySDKReturn,
+  type Survey,
+  type SurveyQuestion,
+  type SurveyPage,
+  type SurveyLanguage,
+  type SurveyPhase,
+  type SpecialPage,
+  type SkipLogic,
+  type DisplayLogic,
+  type AnswerLogic,
+  type QuestionDisplayVariant,
+  type CustomFieldType,
+  type CustomFieldValue,
+  type CustomFieldValueMap,
+  type LogicConditionEntity,
+  type McqQuestion,
+  type McqOption,
+  type NpsQuestion,
+  type NpsScalePoint,
+  type CsatQuestion,
+  type CsatStatementRow,
+  type CsatScaleColumn,
+  type TextInputQuestion,
+  type CfmMatrixQuestion,
+  type CfmMatrixStatementRow,
+  type CfmMatrixScaleColumn,
+  type RatingMatrixQuestion,
+  type RatingMatrixStatementRow,
+  type RatingMatrixScaleColumn,
+  type SliderMatrixQuestion,
+  type SliderMatrixStatementRow,
+  type SliderMatrixTickMark,
+  type FileUploadQuestion,
+  type UploadedFile,
+  type TextAndMediaQuestion,
+  type HeatmapQuestion,
+  type HeatmapRegion,
+  type HeatmapClickPoint,
+  type HeatmapAnswer,
+  type RankOrderQuestion,
+  type RankOrderOption,
+  type RankOrderAnswers,
+  type AnswerValue,
+  type MatrixRowAnswers,
+  type SurveyAnswers,
+  type UploadedFileAnswer,
+  type StatementRow,
+  type ScaleColumn,
+  type ContainerMedia,
+  type QuestionMedia,
+  matrixColumnStoredValue,
+  resolveSurveyQuestionPlaceholders,
+  formatAnswerForDisplay,
+  resolveQuestionDisplayText,
+  applyQuestionDisplayVariants,
+  computeActivePathQuestionNumbers,
+  applyActivePathQuestionNumbers,
+  getVisibleStatementRowsForAnswers,
+  getVisibleMcqOptionsForAnswers,
+  getVisibleScaleColumnsForAnswers,
+  getVisibleMatrixItemsForAnswers,
+  getVisibleRankOrderOptionsForAnswers,
+  assignRankWithoutDuplicates,
+  buildRankOrderFromOrderedOptionIds,
+  getOrderedOptionIdsFromRanks,
+  normalizeRankOrderAnswers,
+} from '@explorer02/cfm-survey-sdk'; // or @repo/sdk
+```
+
+> **CSAT emoji UI** is **not** exported from the SDK. Implement emoji/star icons client-side (typically `react-icons`). See `03-ui-specs/04-csat.md`.
+
+## Hook contract (authoritative)
+
+| Item | Value |
+|------|-------|
+| Answers field | `state.answers` (`SurveyAnswers`) |
+| Custom fields | `options.customFieldValues` (`CustomFieldValueMap`) — stable ref; see [`custom-field-logic-and-navigation.md`](../00-integration/custom-field-logic-and-navigation.md) |
+| Change action | `{ type: 'CHANGE', payload: { questionId, answerValue } }` |
+| Navigation | `'START'`, `'NEXT'`, `'PREVIOUS'`, `'SUBMIT'` |
+| Phase | `state.phase`, `state.specialPage`, `state.canGoBack`, `state.primaryButtonType` |
+
+See `MANIFEST.json` `hookContract` and `00-integration/useSurveySDK.md`.
+
+## Question type literals
+
+All **11** values of `question.type` (from `QUESTION_TYPE`):
+
+`MCQ` · `TEXTFIELD` · `NPS_SCALE` · `CFM_MATRIX` · `CSAT_MATRIX` · `RATING_MATRIX` · `SLIDER_MATRIX` · `FILE_UPLOAD` · `TEXT_AND_MEDIA` · `HEATMAP` · `RANK_ORDER`
+
+Dispatch with `question.type === QUESTION_TYPE.CSAT_MATRIX` (or string literal `'CSAT_MATRIX'`).
+
+> **Note:** Legacy mapper types `star_rating` / `slider` are not in the `SurveyQuestion` union. API RATING/SLIDER pages map into `NPS_SCALE`, matrix display styles, or `SLIDER_MATRIX`.
+
+See `MANIFEST.json` `typeLiterals` and [`question-type-sdk-matrix.md`](../00-integration/question-type-sdk-matrix.md) for routing to docs and components.
+
+## Value derivation
+
+- Matrix storage: import `matrixColumnStoredValue` from the package root (do not reimplement).
+- Rank order: `assignRankWithoutDuplicates`, `buildRankOrderFromOrderedOptionIds`, `getOrderedOptionIdsFromRanks`, `normalizeRankOrderAnswers`.
+- Submit mapping: SDK derives API strings at submit/partial-save time — see [`value-derivation.md`](value-derivation.md).
+
+## Visibility helpers (answer logic UI)
+
+Pass `customFieldValues` as the optional 4th argument when logic rules reference `CUSTOM_FIELD` entities:
+
+```typescript
+getVisibleMcqOptionsForAnswers(question, answers, allQuestions, customFieldValues?);
+getVisibleMatrixItemsForAnswers(question, answers, allQuestions, customFieldValues?);
+getVisibleStatementRowsForAnswers(question, answers, allQuestions, customFieldValues?);
+getVisibleScaleColumnsForAnswers(question, answers, allQuestions, customFieldValues?);
+getVisibleRankOrderOptionsForAnswers(question, answers, allQuestions, customFieldValues?);
+```
+
+See [`answer-logic-and-navigation.md`](../00-integration/answer-logic-and-navigation.md) and [`custom-field-logic-and-navigation.md`](../00-integration/custom-field-logic-and-navigation.md).
+
+## Question display variants
+
+The SDK resolves conditional question text on `state.currentQuestions`. Clients render `question.questionText` as-is — no variant checks required. See [`question-display-variants.md`](../00-integration/question-display-variants.md).
+
+Optional helpers: `resolveQuestionDisplayText`, `applyQuestionDisplayVariants`, type `QuestionDisplayVariant`.
+
+## Question numbering
+
+Active-path ordinals are on `state.currentQuestions[].questionNumber`. Optional: `computeActivePathQuestionNumbers`, `applyActivePathQuestionNumbers`. See [`question-numbering.md`](../00-integration/question-numbering.md).
+
+## Related integration docs
+
+- [`client-integration-guide.md`](../00-integration/client-integration-guide.md)
+- [`question-type-sdk-matrix.md`](../00-integration/question-type-sdk-matrix.md)
+- [`placeholders-and-tokens.md`](../00-integration/placeholders-and-tokens.md)
+- [`partial-save-and-recovery.md`](../00-integration/partial-save-and-recovery.md)
+- [`survey-lifecycle-analytics.md`](../00-integration/survey-lifecycle-analytics.md)
+- [`skip-logic-and-navigation.md`](../00-integration/skip-logic-and-navigation.md)
+- [`display-logic-and-navigation.md`](../00-integration/display-logic-and-navigation.md)
+- [`question-display-variants.md`](../00-integration/question-display-variants.md)
+- [`question-numbering.md`](../00-integration/question-numbering.md)
+- [`answer-logic-and-navigation.md`](../00-integration/answer-logic-and-navigation.md)
+- [`progress.md`](../00-integration/progress.md)