@explorer02/cfm-survey-sdk 0.2.1 → 0.2.2

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)

package/templates/docs/02-reference/question-types/01-rating.md

@@ -1,52 +1,51 @@
-# Rating Question (NPS 0-10)
+# NPS Question (0–10)
 
-> **Type**: `'rating'` | **API Source**: `SCALE` with `SCALE_TYPE=TEN_POINT` or `NPS_SCALE`
-> **Mapper**: `ratingMapper.ts` | **Component**: `RatingScale`
+> **Type**: `'NPS_SCALE'` | **API Source**: `SCALE` / `NPS_SCALE`
+> **SDK type file**: `fetchSurvey/types/nps.ts` | **Component**: `RatingScale`
 
 ## TypeScript Type
 
 ```typescript
-type RatingQuestion = QuestionBase & {
-  type: 'rating';
-  options: SurveyOption[];       // 0-10 with NPS traffic-light colors
-  minLabel?: string;             // Left label (e.g. "Not Likely")
-  midLabel?: string;             // Middle label (e.g. "Neutral")
-  maxLabel?: string;             // Right label (e.g. "Extremely Likely")
-  midLabelIndex?: number;        // Fractional position for mid-label CSS
-  reverseScaleOrder?: boolean;   // Render high→low
-  buttonVariant?: 'radio' | 'numbered' | 'emoji';
+type NpsQuestion = {
+  type: 'NPS_SCALE';
+  id: string;
+  questionText: string;
+  questionDescription?: string;
+  options: NpsScalePoint[];
+  minLabel?: string;
+  midLabel?: string;
+  maxLabel?: string;
+  midLabelIndex?: number;
+  reverseScaleOrder: boolean;
+  buttonStyle: 'standard' | 'numbered' | 'emoji';
+  required: boolean;
+  // ... shell fields
 };
 ```
 
 ## Answer Shape: `number`
-Example: `7` (the selected badge value)
-
-## Options Auto-Generation
-If the API provides no explicit options, the SDK generates 0-10:
-```typescript
-Array.from({ length: 11 }, (_, i) => ({
-  id: String(i), label: String(i), value: i, color: getColor(i)
-}));
-```
 
-## NPS Traffic-Light Colors
-```
-0: #e2001a (red)     3: #f18b00 (orange)   6: #fcd900 (yellow)
-1: #e4251b           4: #f7b200            7: #9fca00 (lime)
-2: #ec610a           5: #fcd900            8: #6bb300 (green)
-                                            9: #339a00
-                                            10: #008000
-```
+Example: `7` (the selected badge value)
 
 ## Mid-Label Positioning
+
 ```typescript
-// CSS left percentage for mid-label
 const left = (midLabelIndex / (options.length - 1)) * 100;
-// For 11-point scale: midLabelIndex defaults to 7.5
 ```
 
 ## Rendering Guidance
+
 - Display as horizontal row of numbered badge buttons
-- Each badge uses `option.color` as background
 - Selected badge: emphasized border/scale, all others dimmed
 - Labels positioned: minLabel (left), midLabel (calculated %), maxLabel (right)
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.NPS_SCALE`
+- [ ] Answer stored as: `number` (selected scale point value)
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: number }`
+- [ ] Visibility helper: `getVisibleScaleColumnsForAnswers` when scale points have answer logic
+- [ ] Custom fields: pass `customFieldValues` as 4th arg to scale visibility helper when rules reference CRM fields
+- [ ] Logic features: skip ✓ display ✓ answer ✓ (columns) variants ✓ numbering ✓
+- [ ] Performance: single horizontal row — no matrix filtering overhead
+- [ ] Matrix row: [`question-type-sdk-matrix.md#nps_scale`](../../00-integration/question-type-sdk-matrix.md#nps_scale)

package/templates/docs/02-reference/question-types/04-csat.md

@@ -1,54 +1,63 @@
-# CSAT Question (Satisfaction Scale)
+# CSAT Matrix Question (Satisfaction Grid)
 
-> **Type**: `'csat'` | **API Source**: `SCALE` with `SCALE_TYPE=CSAT` or ≤5 options
-> **Mapper**: `ratingMapper.ts` (CSAT branch) | **Component**: `CsatScale`
+> **Type**: `'CSAT_MATRIX'` | **API Source**: `CSAT_MATRIX`
+> **SDK type**: `CsatQuestion` | **Component**: `CsatMatrixScale`
 
 ## TypeScript Type
 
 ```typescript
-type CsatQuestion = QuestionBase & {
-  type: 'csat';
-  options: SurveyOption[];          // Usually 1-5 satisfaction levels
-  minLabel?: string;                // "Very Dissatisfied"
-  maxLabel?: string;                // "Very Satisfied"
-  buttonType?: SurveyButtonType;    // 'emoji' | 'star' | 'numbered' | 'radio'
-  hasNotApplicable?: boolean;       // N/A option available
-  reverseScaleOrder?: boolean;      // Render high→low
-  labelPosition?: 'top' | 'bottom' | 'hidden';
+type CsatQuestion = {
+  type: 'CSAT_MATRIX';
+  id: string;
+  statementRows: CsatStatementRow[];
+  scaleColumns: CsatScaleColumn[];
+  displayStyle: 'emoji' | 'star' | 'standard' | 'numbered' | 'dropdown' | 'selectbox' | 'graphics';
+  gridLayout: 'standard' | 'carousel' | 'dropdown';
+  hasNotApplicableOption: boolean;
+  reverseScaleOrder: boolean;
+  // ... shell fields, skipLogics?, displayLogic?
 };
+
+type CsatStatementRow = { id: string; statementText: string; answerLogic?: AnswerLogic };
+type CsatScaleColumn = { id: string; label: string; answerLogic?: AnswerLogic };
 ```
 
-## Answer Shape: `number | null`
-Example: `4` or `null` (N/A selected)
+Filter visible rows/columns with `getVisibleMatrixItemsForAnswers` before rendering (see [`answer-logic-and-navigation.md`](../../00-integration/answer-logic-and-navigation.md)).
 
-## Rendering by `buttonType`
+## Answer Shape: `MatrixRowAnswers`
 
-| `buttonType` | Render As |
-|-------------|-----------|
-| `'emoji'` | Sentiment face icons from `CsatEmojiMapping` |
-| `'star'` | Star icons from `CsatStarIcons` (filled/empty) |
-| `'numbered'` | Numeric badge buttons |
-| `'radio'` | Standard radio circles |
-| `'graphics'` | Emoji slider (use `CustomSliderTrack`) |
-
-## Star Rating Pattern
-```tsx
-{options.map((opt, i) => {
-  const numericValue = typeof opt.value === 'number' ? opt.value : i + 1;
-  const isActive = typeof selectedValue === 'number' && numericValue <= selectedValue;
-  return (
-    <button onClick={() => onSelect(opt.value)}>
-      {isActive ? CsatStarIcons.filled : CsatStarIcons.empty}
-    </button>
-  );
-})}
-```
+Store column **`id`** per row (not label text):
 
-## Emoji Pattern
-```tsx
-{options.map((opt, i) => (
-  <button onClick={() => onSelect(opt.value)}>
-    {CsatEmojiMapping[typeof opt.value === 'number' ? opt.value : i + 1]}
-  </button>
-))}
+```typescript
+import { matrixColumnStoredValue } from '@explorer02/cfm-survey-sdk';
+
+// { [rowId]: columnId | columnId[] | null }
+{ "row_1": "col_5", "row_2": null }
 ```
+
+Submit maps ids → API label/number via SDK `resolveSubmitValues`.
+
+## Rendering by `displayStyle`
+
+| `displayStyle` | Cell Rendering |
+|----------------|----------------|
+| `'emoji'` | Sentiment faces — implement client-side with `react-icons` (not SDK exports) |
+| `'star'` | Star icons — implement client-side with `react-icons` |
+| `'numbered'` | Numeric badge buttons |
+| `'dropdown'` | Dropdown per row (`MatrixDropdown`) |
+| `'graphics'` | Emoji slider per row (`CustomSliderTrack`) |
+
+## N/A Column
+
+When `hasNotApplicableOption` is true, selecting N/A stores `null` for that row — a valid answer.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.CSAT_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` — column **`id`** per row via `matrixColumnStoredValue`
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: MatrixRowAnswers }` (merge row updates)
+- [ ] Visibility helper: `getVisibleMatrixItemsForAnswers(question, answers, allQuestions, customFieldValues?)`
+- [ ] Custom fields: 4th arg on matrix visibility helper when logic references CRM fields
+- [ ] Logic features: skip ✓ display ✓ answer ✓ (rows + columns) variants ✓ numbering ✓
+- [ ] Performance: render only visible rows/cols; memoize emoji/star maps for graphics mode
+- [ ] Matrix row: [`question-type-sdk-matrix.md#csat_matrix`](../../00-integration/question-type-sdk-matrix.md#csat_matrix)