@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

package/templates/docs/01-components/16-paused-page.md

@@ -0,0 +1,27 @@
+# Paused Page
+
+> **UI spec:** `03-ui-specs/12-survey-chrome.md`
+> **Reference:** `apps/client/src/components/PausedPage.tsx`
+
+## When to render
+
+`state.phase.kind === 'paused'` when survey `phaseFlags.paused` is true.
+
+## Props
+
+```typescript
+type PausedPageProps = {
+  page: SpecialPage;
+};
+```
+
+## Wiring
+
+```tsx
+<PausedPage page={state.specialPage} />
+```
+
+## Content
+
+- Read-only message from `page.header` / `page.description`
+- No start or navigation actions

package/templates/docs/01-components/17-heatmap-scale.md

@@ -0,0 +1,75 @@
+# Heatmap Architectural Blueprint
+
+> **UI spec (authoritative):** `03-ui-specs/13-heatmap.md`
+> **Reference implementation:** `apps/client/src/components/HeatmapScale.tsx`
+> **Portable coord helper:** copy [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts)
+> **Target Component**: `HeatmapScale`
+> **Handles**: `type: 'HEATMAP'`
+
+## Core Responsibility
+
+Render the heatmap image, capture click spots in normalized 0–1 coordinates, toggle spots on repeat click, enforce `maxClicksAllowed` client-side, and bubble answers via `onSelect`.
+
+## Props Contract
+
+```typescript
+type HeatmapScaleProps = {
+  question: HeatmapQuestion;
+  selectedValue?: HeatmapClickPoint[];
+  onSelect: (answer: HeatmapClickPoint[] | undefined) => void;
+};
+```
+
+## State Management
+
+- `selectedValue` from SDK is source of truth — do not duplicate answer state
+- Local UI state: `isImageReady` only
+
+## Click Interaction
+
+1. User clicks image → compute normalized `{ x, y }` from `getBoundingClientRect()`
+2. If click within 14px of existing spot → remove that spot
+3. Else if under `maxClicksAllowed` → append `{ id: crypto.randomUUID(), x, y }`
+4. Else → no-op
+
+## Coordinate Helpers
+
+Copy [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts):
+
+- `getNormalizedClickFromImage(event, imageElement)`
+- `findSpotNearClick(clickX, clickY, spots, imageRect)`
+- `createNewSpot(x, y)`
+
+## DOM Structure
+
+```tsx
+<div className="relative inline-block max-w-full">
+  <img onClick={handleImageClick} ... />
+  <div className="absolute inset-0 pointer-events-none">
+    {spots.map(spot => <Spot />)}
+  </div>
+</div>
+```
+
+## Wiring in Question.tsx
+
+```typescript
+{question.type === QUESTION_TYPE.HEATMAP && (
+  <HeatmapScale
+    question={question as HeatmapQuestion}
+    selectedValue={Array.isArray(selectedValue) ? selectedValue : undefined}
+    onSelect={onSelect}
+  />
+)}
+```
+
+Question shell (title, description, validation) stays in `Question.tsx`.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Type literal: `QUESTION_TYPE.HEATMAP`
+- [ ] Answer stored as: `HeatmapClickPoint[]`
+- [ ] onAction CHANGE: `{ questionId, answerValue: HeatmapClickPoint[] }`
+- [ ] Copy coord helper from [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts)
+- [ ] Respect `maxClicksAllowed`; normalize coords 0–1
+- [ ] Matrix row: [`question-type-sdk-matrix.md#heatmap`](../00-integration/question-type-sdk-matrix.md#heatmap)

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

@@ -0,0 +1,93 @@
+# Rank Order Architectural Blueprint
+
+> **UI spec (authoritative):** `03-ui-specs/14-rank-order.md`
+> **Portable template:** copy [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx)
+> **Target Component:** `RankOrderScale`
+> **Handles:** `type: 'RANK_ORDER'`
+
+## Core Responsibility
+
+Render rankable options in **dropdown** or **drag-and-drop** mode, three option display variants, bubble ranks via `onSelect`.
+
+## Props Contract
+
+```typescript
+type RankOrderScaleProps = {
+  question: RankOrderQuestion;
+  selectedValue?: RankOrderAnswers;
+  onSelect: (value: RankOrderAnswers) => void;
+};
+```
+
+## State Management
+
+- `selectedValue` from SDK is source of truth — no duplicate local answer state
+- Dropdown: `assignRankWithoutDuplicates` on rank change
+- Drag-and-drop: `buildRankOrderFromOrderedOptionIds` after reorder; `getOrderedOptionIdsFromRanks` for display order
+
+## Layout Orchestrator
+
+```tsx
+export function RankOrderScale({ question, selectedValue, onSelect }: RankOrderScaleProps) {
+  if (question.interactionMode === 'dragAndDrop') {
+    return <DragDropRankLayout ... />;
+  }
+  return <DropdownRankLayout ... />;
+}
+```
+
+## shuffleOptions
+
+When API `SHUFFLE_ORDER` is true, SDK shuffles options at map time. **Do not re-shuffle in the client** — logic and option ids must stay aligned with fetched order.
+
+## Wiring in Question.tsx
+
+```typescript
+import {
+  QUESTION_TYPE,
+  getVisibleRankOrderOptionsForAnswers,
+  normalizeRankOrderAnswers,
+} 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={normalizeRankOrderAnswers(
+      typeof selectedValue === 'object' && selectedValue !== null && !Array.isArray(selectedValue)
+        ? selectedValue
+        : undefined
+    )}
+    onSelect={onSelect}
+  />
+)}
+```
+
+## Dependencies
+
+```bash
+npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+```
+
+## Next.js SSR
+
+Template uses `'use client'`. For drag-and-drop, optional `dynamic(..., { ssr: false })` in Question.tsx if hydration warnings occur.
+
+## SDK Integration Checklist (agent)
+
+- [ ] Copy [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx)
+- [ ] Type literal: `QUESTION_TYPE.RANK_ORDER`
+- [ ] Answer: `RankOrderAnswers`
+- [ ] Visibility: `getVisibleRankOrderOptionsForAnswers(..., customFieldValues?)`
+- [ ] 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,50 +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).
+> 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)
-> This folder documents props, `onSelect` wiring, and dispatcher architecture.
+> 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
 
@@ -52,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` |