@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

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)

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

@@ -1,26 +1,31 @@
-# Rating Scale Question (Stars/Emoji)
+# Star Rating Question (Stars/Emoji)
 
-> **Type**: `'rating_scale'` | **API Source**: `SCALE` with `SCALE_TYPE=STAR/EMOJI/FIVE_POINT`
-> **Mapper**: `ratingMapper.ts` (rating_scale branch) | **Component**: `RatingScale`
+> **Type**: `'star_rating'` | **API Source**: page `RATING`
+> **SDK type file**: `fetchSurvey/types/starRating.ts` | **Component**: `RatingScale`
 
 ## TypeScript Type
 
 ```typescript
-type RatingScaleQuestion = QuestionBase & {
-  type: 'rating_scale';
-  options: SurveyOption[];     // Typically 1-5 or 1-10 (no NPS colors)
+type StarRatingQuestion = {
+  type: 'star_rating';
+  id: string;
+  questionText: string;
+  options: StarRatingPoint[];
   minLabel?: string;
   midLabel?: string;
   maxLabel?: string;
   midLabelIndex?: number;
-  reverseScaleOrder?: boolean;
-  scaleStyle?: 'star' | 'emoji';
+  reverseScaleOrder: boolean;
+  scaleStyle: 'star' | 'emoji';
+  required: boolean;
+  // ... shell fields
 };
 ```
 
 ## Answer Shape: `number`
 
-## Key Difference from `'rating'`
+## Key Difference from `'nps'`
+
 - No NPS traffic-light colors on options
-- Rendered as stars, emojis, or plain icons — not numbered badges
-- Use `scaleStyle` to determine icon type
+- Rendered as stars or emojis per `scaleStyle`
+- See `03-ui-specs/05-rating-scale.md`

package/templates/docs/02-reference/question-types/06-slider.md

@@ -1,7 +1,7 @@
 # Slider Question (Single Range)
 
-> **Type**: `'slider'` | **API Source**: `SCALE` with `INPUT_TYPE=SLIDER`
-> **Mapper**: `ratingMapper.ts` (slider branch) | **Component**: `CustomSliderTrack` or native `<input type="range">`
+> **Type**: `'slider'` | **API Source**: page `SLIDER`
+> **Mapper**: `sliderMapper.ts` | **Component**: `CustomSliderTrack` or native `<input type="range">`
 
 ## TypeScript Type
 

package/templates/docs/02-reference/question-types/07-matrix-cfm.md

@@ -1,43 +1,57 @@
-# Matrix CFM Question (Likert Grid)
+# CFM Matrix Question (Likert Grid)
 
-> **Type**: `'matrix'` with `subType: 'CFM_MATRIX'` | **API Source**: `CFM_MATRIX`
-> **Mapper**: `cfmMatrixMapper.ts` | **Component**: `LikertMatrixScale`
+> **Type**: `'CFM_MATRIX'` | **API Source**: `CFM_MATRIX`
+> **SDK type file**: `fetchSurvey/types/cfmMatrix.ts` | **Component**: `LikertMatrixScale`
 
 ## TypeScript Type
 
 ```typescript
-type MatrixQuestion = QuestionBase & {
-  type: 'matrix';
-  subType: 'CFM_MATRIX';
-  rows: MatrixRow[];              // Statements to rate
-  columns: MatrixColumn[];        // Shared answer options per row
-  buttonType?: SurveyButtonType;
-  hasNotApplicable?: boolean;
-  reverseScaleOrder?: boolean;
-  labels?: string[];              // Anchor labels above columns
-  matrixFormat?: 'standard' | 'carousel' | 'dropdown';
-  matrixType?: 'likert' | 'bipolar';
-  answerType?: 'single' | 'multiple';
-  transposeTable?: boolean;
-  repeatScale?: boolean;
-  enableScale?: boolean;
+type CfmMatrixQuestion = {
+  type: 'CFM_MATRIX';
+  id: string;
+  questionText: string;
+  statementRows: CfmMatrixStatementRow[];
+  scaleColumns: CfmMatrixScaleColumn[];
+  statementLayout: 'likert' | 'bipolar';
+  selectionMode: 'single' | 'multiple';
+  gridLayout: 'standard' | 'carousel' | 'dropdown';
+  transposeTable: boolean;
+  repeatColumnHeaders: boolean;
+  hasNotApplicableOption: boolean;
+  showColumnHeaders: boolean;
+  scaleAnchorLabels?: string[];
+  required: boolean;
+  // ... shell fields
 };
 
-type MatrixRow = { id: string; text: string; rightText?: string; };
-type MatrixColumn = { id: string; label: string; value: string | number | null; color?: string; };
+type CfmMatrixStatementRow = {
+  id: string;
+  statementText: string;
+  oppositeStatementText?: string;
+};
 ```
 
-## Answer Shape: `MatrixAnswerMap`
+## Answer Shape: `MatrixRowAnswers`
+
 ```typescript
-{ "row1_id": "column_value", "row2_id": "column_value", "row3_id": null }
-// null = N/A selected for that row
+{ "row1_id": columnValue, "row2_id": null }
 ```
 
 ## Rendering Guidance
-- **Standard format**: Grid table — rows on left, columns as headers
-- **Carousel format**: Show one row at a time with prev/next
-- **Dropdown format**: Each row has a dropdown selector for its column value
-- Likert: unipolar text labels (e.g. "Strongly Disagree" → "Strongly Agree")
-- Bipolar: `row.text` on left + `row.rightText` on right
-- If `hasNotApplicable` → add N/A column with `value: null`
-- `onSelect` receives the full `MatrixAnswerMap` object on each change
+
+- **standard**: Grid table — rows on left, columns as headers
+- **carousel**: One row at a time with prev/next
+- **dropdown**: Each row has a dropdown (`MatrixDropdown`)
+- **bipolar**: `statementText` left + `oppositeStatementText` right
+- `onSelect` receives the full `MatrixRowAnswers` object on each change
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.CFM_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` — column **`id`** via `matrixColumnStoredValue`
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] 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: filter rows/cols before render; lazy-load large matrices
+- [ ] Matrix row: [`question-type-sdk-matrix.md#cfm_matrix`](../../00-integration/question-type-sdk-matrix.md#cfm_matrix)

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

@@ -1,29 +1,7 @@
-# Matrix CSAT Question (Satisfaction Grid)
+# CSAT Matrix Question (legacy reference)
 
-> **Type**: `'matrix'` with `subType: 'CSAT_MATRIX'` | **API Source**: `CSAT_MATRIX`
-> **Mapper**: `csatMatrixMapper.ts` | **Component**: `CsatMatrixScale`
+> **Deprecated alias.** CSAT matrix grids use `type: 'CSAT_MATRIX'` — see [04-csat.md](04-csat.md).
 
-## TypeScript Type
-Same as `MatrixQuestion` (see `07-matrix-cfm.md`) but with `subType: 'CSAT_MATRIX'`.
+For rating-style matrix grids use `type: 'RATING_MATRIX'` — see [09-matrix-rating.md](09-matrix-rating.md).
 
-## Key Difference from CFM_MATRIX
-- Columns represent satisfaction levels (not text labels)
-- Uses `buttonType` to determine visual: emoji faces, stars, numbered, etc.
-- Uses `getEmojiForIndex(colIndex, totalCols)` for emoji rendering per cell
-
-## Rendering by `buttonType`
-
-| `buttonType` | Cell Rendering |
-|-------------|---------------|
-| `'emoji'` | Sentiment face icons via `getEmojiForIndex` |
-| `'star'` | Star icons via `CsatStarIcons` |
-| `'numbered'` | Numeric badge buttons |
-| `'radio'` | Standard radio circles |
-| `'dropdown'` | Dropdown per row (uses `MatrixDropdown`) |
-| `'graphics'` | Emoji slider per row (uses `CustomSliderTrack`) |
-
-## Answer Shape: `MatrixAnswerMap`
-Same as CFM_MATRIX — `{ "row_id": column_value | null }`
-
-## N/A Column
-If `hasNotApplicable` is true, the last column has `value: null`. Selecting it records `null` for that row, which is a valid answer (passes validation).
+There is no `subType` field. Each matrix variant is a flat `question.type` literal.

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

@@ -1,28 +1,44 @@
 # Rating Matrix Question
 
-> **Type**: `'rating_matrix'` | **API Source**: `RATING_MATRIX`
-> **Mapper**: `ratingMatrixMapper.ts` → routed to `mapMatrixQuestion` | **Component**: `CsatMatrixScale`
+> **Type**: `'RATING_MATRIX'` | **API Source**: `RATING_MATRIX`
+> **Component**: `CsatMatrixScale`
 
 ## TypeScript Type
 
 ```typescript
-type RatingMatrixQuestion = QuestionBase & {
-  type: 'rating_matrix';
-  rows: MatrixRow[];
-  columns: MatrixColumn[];       // Rating columns with NPS-style colors
+type RatingMatrixQuestion = {
+  type: 'RATING_MATRIX';
+  statementRows: StatementRow[];
+  scaleColumns: ScaleColumn[];
   minLabel?: string;
   maxLabel?: string;
-  buttonType?: SurveyButtonType;
-  hasNotApplicable?: boolean;
-  reverseScaleOrder?: boolean;
-  labels?: string[];
+  displayStyle: CsatQuestion['displayStyle'];
+  gridLayout: 'standard' | 'carousel' | 'dropdown';
+  hasNotApplicableOption: boolean;
+  reverseScaleOrder: boolean;
+  scaleAnchorLabels?: string[];
+  // + shell fields (id, questionText, required, containerMedia?, etc.)
 };
 ```
 
 ## Key Difference from CSAT_MATRIX
-- Columns carry traffic-light `color` values (like NPS rating)
+
 - Has `minLabel`/`maxLabel` endpoint labels
+- Column badge colors derived client-side via `columnAccentColor(col)` — see `02-reference/value-derivation.md`
 - Rendered by the same `CsatMatrixScale` component
 
-## Answer Shape: `MatrixAnswerMap`
-Same pattern: `{ "row_id": column_value | null }`
+## Answer Shape: `MatrixRowAnswers`
+
+`Record<statementRows[].id, matrixColumnStoredValue(col) | null>` — stored value is always the column **`id`**; submit maps id → label/number via `resolveSubmitValues`.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.RATING_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` — column **`id`** via `matrixColumnStoredValue`
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] 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; column logic may be limited) variants ✓ numbering ✓
+- [ ] Performance: reuse `CsatMatrixScale`; render only visible rows/cols
+- [ ] Known limitation: column-level answer logic gap — verify fetched survey rules
+- [ ] Matrix row: [`question-type-sdk-matrix.md#rating_matrix`](../../00-integration/question-type-sdk-matrix.md#rating_matrix)

package/templates/docs/02-reference/question-types/10-slider-matrix.md

@@ -1,13 +1,13 @@
 # Slider Matrix Question
 
-> **Type**: `'slider_matrix'` | **API Source**: `SLIDER_MATRIX`
+> **Type**: `'SLIDER_MATRIX'` | **API Source**: `SLIDER_MATRIX`
 > **Mapper**: `sliderMatrixMapper.ts` | **Component**: `SliderMatrixScale`
 
 ## TypeScript Type
 
 ```typescript
 type SliderMatrixQuestion = QuestionBase & {
-  type: 'slider_matrix';
+  type: 'SLIDER_MATRIX';
   rows: SliderMatrixRow[];       // Each row has independent slider config
   labels?: string[];             // Anchor labels above track
   ticks?: number;                // Number of tick marks (default 10)
@@ -25,7 +25,7 @@ type SliderMatrixRow = MatrixRow & {
 type TickValue = { value: number; label: string; color: string; };
 ```
 
-## Answer Shape: `MatrixAnswerMap`
+## Answer Shape: `MatrixRowAnswers`
 ```typescript
 { "row1_id": 75, "row2_id": 30, "row3_id": null }
 // number = slider position, null = N/A
@@ -37,4 +37,15 @@ type TickValue = { value: number; label: string; color: string; };
 - If `tickValues` available → render tick marks with labels and colors
 - If `enableInputBox` → show numeric input alongside slider
 - If `enableNotApplicable` → add N/A checkbox per row
-- `onSelect` receives the full `MatrixAnswerMap` with all row values
+- `onSelect` receives the full `MatrixRowAnswers` with all row values
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.SLIDER_MATRIX`
+- [ ] Answer stored as: `MatrixRowAnswers` — numeric slider value or `null` for N/A per row
+- [ ] onAction CHANGE payload: `{ questionId, answerValue: MatrixRowAnswers }`
+- [ ] Visibility helper: `getVisibleStatementRowsForAnswers(question, answers, allQuestions, customFieldValues?)`
+- [ ] Custom fields: 4th arg on statement-row helper when logic references CRM fields
+- [ ] Logic features: skip ✓ display ✓ answer ✓ (rows) variants ✓ numbering ✓
+- [ ] Performance: debounce drag events if partial save enabled; one slider per visible row
+- [ ] Matrix row: [`question-type-sdk-matrix.md#slider_matrix`](../../00-integration/question-type-sdk-matrix.md#slider_matrix)