@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

package/templates/docs/03-ui-specs/00-question-shell.md

@@ -1,102 +1,33 @@
 # UI Spec: Question Shell (`Question.tsx`)
 
 > **Canonical template:** [`templates/Question.tsx`](../templates/Question.tsx) — copy this dispatcher verbatim
-> **Monorepo reference:** `apps/client/src/components/Question.tsx` (not available in npm installs — implement from this spec)
-> **SDK:** All types extend `QuestionBase` from `fetchSurvey/types/base.ts`
+> **SDK:** Each question type is standalone — see `fetchSurvey/types/*.ts`
 > **Component blueprint:** `01-components/02-question.md`
-> **Required files:** `00-integration/component-checklist.md`
 
-## Matrix subType Warning (CRITICAL)
+## Matrix routing (CRITICAL)
 
-Routing on `question.type === 'matrix'` **alone renders nothing**. You MUST branch on `subType`:
+Each matrix variant has its own `question.type` — **no `subType`**:
 
 - `CFM_MATRIX` → `LikertMatrixScale`
 - `CSAT_MATRIX` | `RATING_MATRIX` → `CsatMatrixScale`
+- `SLIDER_MATRIX` → `SliderMatrixScale`
 
-Never use a `default` fallback that shows `"not yet implemented"` — create the scale components listed in the checklist.
+Never use a `default` fallback that shows `"not yet implemented"`.
 
-## Config Inventory (QuestionBase)
+## Shell fields (duplicated on every question type)
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `id` | ✅ | `section id={question.id}` — required for scroll-to-error |
-| `text` | ✅ | Heading via `dangerouslySetInnerHTML` |
-| `description` | ✅ | Optional HTML block below title |
-| `required` | ✅ | Red `*` after title (`text-red-500`) |
-| `requiredErrorMessage` | ✅ | Shown via SDK validation in error banner |
-| `questionNumber` | ❌ | Not rendered in reference client |
-| `containerMediaUrl` | ❌ | Not rendered on generic questions |
-
-## Layout Anatomy
-
-```
-┌─ section (rounded-xl border border-gray-200 bg-white p-6 shadow-sm) ─────┐
-│  h2: question.text (HTML) + red * if required                           │
-│  [optional description HTML]                                            │
-│  ┌─ type-specific scale (see per-type specs) ─────────────────────┐   │
-│  └─────────────────────────────────────────────────────────────────┘   │
-│  [validation error banner if validationError prop]                      │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
-## Dispatcher Routing
-
-| `question.type` | Condition | Component |
-|-----------------|-----------|-----------|
-| `rating` | — | `RatingScale` + label row in Question |
-| `radio` | — | Inline card radios in Question |
-| `text` | — | Inline textarea in Question |
-| `csat` | — | `CsatScale` + min/max labels in Question |
-| `matrix` | `CSAT_MATRIX` \| `RATING_MATRIX` | `CsatMatrixScale` |
-| `matrix` | `CFM_MATRIX` | `LikertMatrixScale` |
-| `slider_matrix` | — | `SliderMatrixScale` |
-| `file_upload` | — | `FileUploadScale` |
-| `text_and_media` | `mediaUrl` present | Inline media in Question |
-| `slider` | — | ❌ Not routed — see `06-slider.md` |
-| `rating_scale` | — | ❌ Not routed — see `05-rating-scale.md` |
-
-## Label Positioning (rating)
-
-Rendered in Question before `RatingScale`:
-
-```tsx
-// midLabel CSS left:
-left: `${(midLabelIndex / (options.length - 1)) * 100}%`
-// with -translate-x-1/2 for centering
-```
-
-minLabel: `absolute left-0`, maxLabel: `absolute right-0`, container `relative h-6 text-xs font-semibold text-gray-500`.
-
-## Label Positioning (csat)
-
-minLabel / maxLabel: `flex justify-between text-xs font-semibold text-gray-500` above `CsatScale`.
-
-## Validation Error Banner
-
-```tsx
-className="mt-4 rounded-[4px] border border-[#333333] bg-[#d9d9d9] py-3.5 px-4"
-// text: text-[13px] font-bold text-gray-900
-```
-
-## Props Contract
-
-```typescript
-type QuestionProps = {
-  question: SurveyQuestion;
-  selectedValue?: AnswerValue;
-  validationError?: string;
-  onSelect: (value: AnswerValue) => void;
-};
-```
-
-Wire `onSelect` → `onAction({ type: 'CHANGE', payload: { questionId, value } })`.
-
-## Agent Checklist
-
-- [ ] `id={question.id}` on outermost `<section>`
-- [ ] HTML rendering for text and description
-- [ ] Copied from `templates/Question.tsx` — no stub/default fallback branches
-- [ ] Matrix routes by `subType`, not type alone
-- [ ] `slider_matrix` → `SliderMatrixScale`; `file_upload` → `FileUploadScale`
-- [ ] Validation error banner below scale
-- [ ] Rating/csat endpoint labels positioned per formulas above
+| `id` | ✅ | `section id={question.id}` — scroll-to-error |
+| `questionText` | ✅ | Heading via `dangerouslySetInnerHTML`; when the survey defines `displayVariants`, the SDK resolves the active variant text on `state.currentQuestions` before render |
+| `questionDescription` | ✅ | Optional HTML below title |
+| `questionHint` | ❌ | Optional hint below description |
+| `required` | ✅ | Red `*` after title |
+| `requiredErrorMessage` | ✅ | Validation error banner |
+| `questionNumber` | ✅ | Prefix before title (e.g. `3.`); SDK resolves active-path ordinals on `state.currentQuestions` (see [`question-numbering.md`](../../00-integration/question-numbering.md)) |
+| `containerMedia` | ❌ | Side media — `containerMedia?.url` etc.; not in reference client |
+
+## SDK hook
+
+- Answers: `state.answers` (not `state.values`)
+- Change action: `{ type: 'CHANGE', payload: { questionId, answerValue } }`

package/templates/docs/03-ui-specs/01-rating.md

@@ -1,80 +1,46 @@
-# UI Spec: NPS Rating (`type: 'rating'`)
+# UI Spec: NPS Rating (`type: 'NPS_SCALE'`)
 
-> **Reference:** `apps/client/src/components/RatingScale.tsx` + label row in `Question.tsx`
-> **SDK type:** `RatingQuestion` — `fetchSurvey/types/rating.ts`
+> **SDK type:** `NpsQuestion` — `fetchSurvey/types/nps.ts`
 > **Component blueprint:** `01-components/03-rating-scale.md`
+> **Value derivation:** `02-reference/value-derivation.md`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
 | `options[]` | ✅ | Badge row + radio row (dual layer) |
-| `options[].color` | ✅ | Badge background; fallback `#e20074` |
-| `options[].label` | ✅ | Displayed in badge |
-| `options[].value` | ✅ | Selection value |
+| `options[].optionLabel` | ✅ | Displayed in badge |
+| `options[].id` | ✅ | Stable option id (display only) |
+| Submit value | ✅ derived | Parse `optionLabel` as number or use index — see value-derivation |
+| Badge color | ✅ derived | Traffic-light table from numeric value |
 | `minLabel` | ✅ | Rendered in Question.tsx above scale |
 | `midLabel` | ✅ | Absolute positioned in Question.tsx |
 | `maxLabel` | ✅ | Absolute positioned in Question.tsx |
 | `midLabelIndex` | ✅ | Mid label `left` percentage |
-| `reverseScaleOrder` | ❌ | Document for agents when SDK sends true |
-| `buttonVariant` | ❌ | Client always uses dual-layer radio layout |
+| `reverseScaleOrder` | ✅ | Reverse option index before selection/color lookup |
+| `buttonVariant` | ❌ | Client uses dual-layer radio layout |
 
-## Layout Anatomy
+## Answer logic on scale points
 
-```
-[minLabel]              [midLabel @ %]              [maxLabel]
-┌──┬──┬──┬── ... ──┬──┐  ← Row 1: colored badges (NOT clickable)
-│0 │1 │2 │3 │ ...  │10│     grid repeat(options.length), h-5 w-5 sm:h-6 w-6
-└──┴──┴──┴── ... ──┴──┘     rounded-[3px], white bold text, option.color bg
-┌──────────────────────────────────────────────┐
-│  ○  ○  ●  ○  ...  ○                          │  ← Row 2: gray track bg-[#f2f2f2]
-└──────────────────────────────────────────────┘     h-11 sm:h-12, rounded-md
-         ↑ selected cell: inner bg-[#fbe8f3]
-           radio: border-[4px] border-[#e20074] bg-white
-```
-
-## Config Decision Tree
-
-```
-rating
-└── RatingScale (always dual-layer in reference client)
-    ├── Row 1: display-only colored badges
-    └── Row 2: sr-only radio + custom circle per cell
-```
+When scale points have answer logic, filter with `getVisibleScaleColumnsForAnswers(question, answers, allQuestions, customFieldValues?)` before render.
 
-If `buttonVariant === 'numbered'` (SDK gap): badges become clickable buttons instead — not in reference client.
+## Implementation Recipe — reverseScaleOrder
 
-If `reverseScaleOrder`: reverse `options` array before mapping both rows.
-
-## Interactive States
-
-| State | Badge row | Track cell | Radio circle |
-|-------|-----------|------------|--------------|
-| Default | Full color | Transparent inner | `border-2 border-gray-300` |
-| Hover | — | `hover:bg-gray-200/40` | — |
-| Selected | Unchanged | `bg-[#fbe8f3]` | `border-[4px] border-[#e20074]` |
-
-## Tooltips
-
-Recommended: `title={option.label}` on each track `<label>`. Not in reference client yet.
+When `reverseScaleOrder === true`, map visual index `i` to stored index `options.length - 1 - i` before deriving submit value and badge color.
 
 ## Answer Mutation
 
 ```typescript
-onSelect(option.value) // number
-// → onAction CHANGE { questionId, value: number }
+const value = npsValueFromOption(option, index);
+onSelect(value) // number
+// → onAction CHANGE { questionId, answerValue: number }
 ```
 
-## Accessibility
-
-- `role="radiogroup"` on wrapper
-- Native `<input type="radio" className="sr-only">` per cell
-- `name={questionId}` groups radios
+See [`02-reference/value-derivation.md`](../02-reference/value-derivation.md).
 
 ## Agent Checklist
 
+- [ ] Derive submit value and badge color in UI — types omit `optionValue` / `accentColor`
 - [ ] Two-row grid with `gridTemplateColumns: repeat(options.length, 1fr)`
-- [ ] Badges use `option.color`, not hardcoded NPS colors unless option lacks color
 - [ ] Only track row is clickable
 - [ ] min/mid/max labels in Question wrapper with midLabelIndex formula
-- [ ] Selected state: pink inner track + thick magenta radio ring

package/templates/docs/03-ui-specs/02-radio.md

@@ -1,57 +1,100 @@
-# UI Spec: Radio MCQ (`type: 'radio'`)
+# UI Spec: MCQ (`type: 'MCQ'`)
 
-> **Reference:** `apps/client/src/components/Question.tsx` (inline)
-> **SDK type:** `RadioQuestion` — `fetchSurvey/types/radio.ts`
+> **SDK type:** `McqQuestion` — `fetchSurvey/types/mcq.ts`
 > **Component blueprint:** `01-components/02-question.md`
+> **Dispatcher:** inline in `Question.tsx` (see [`templates/Question.tsx`](../templates/Question.tsx))
 
 ## Config Inventory
 
-| Field | Implemented | UI impact |
-|-------|-------------|-----------|
-| `options[]` | ✅ | One card per option |
-| `options[].label` | ✅ | HTML via `dangerouslySetInnerHTML` |
-| `options[].value` | ✅ | Selection value; `null` → empty string on input |
-| `isMultiSelect` | ❌ | SDK supports; client is single-select only |
+| Field | UI impact |
+|-------|-----------|
+| `options[]` | One card per visible option |
+| `options[].optionLabel` | HTML via `dangerouslySetInnerHTML` |
+| `options[].id` | **Submit value** — answer is `option.id` |
+| `selectionMode` | `'single'` → radio cards; `'multiple'` → checkbox cards + `string[]` answer |
+| `defaultOptionIds?` | Pre-selected on load (SDK seeds `state.answers`) |
+| `minSelections?` / `maxSelections?` | Answer-condition count (SDK validates on NEXT) |
+| `answerConditionErrorMessage?` | Custom validation banner text |
+| `requiredErrorMessage?` | Required-field error text |
 
-## Layout Anatomy
+## Selection mode (not `isMultiSelect`)
 
-```
-┌─ label (full-width card) ─────────────────────────────────────┐
-│  (●)  Option label HTML                                      │  selected
-└───────────────────────────────────────────────────────────────┘
-┌─ label ───────────────────────────────────────────────────────┐
-│  (○)  Option label HTML                                      │  unselected
-└───────────────────────────────────────────────────────────────┘
+Use `question.selectionMode` from the SDK — **never** `isMultiSelect`.
+
+| `selectionMode` | UI | Answer shape |
+|-----------------|-----|--------------|
+| `'single'` (default) | Radio cards; one selected | `string` (option `id`) |
+| `'multiple'` | Checkbox cards; toggle on click | `string[]` of option ids |
+
+Multi-select toggle pattern:
+
+```typescript
+const handleToggle = (optionId: string) => {
+  const next = selectedIds.includes(optionId)
+    ? selectedIds.filter(id => id !== optionId)
+    : question.maxSelections && selectedIds.length >= question.maxSelections
+      ? selectedIds  // block add at max
+      : [...selectedIds, optionId];
+  onSelect(next);
+};
 ```
 
-## Interactive States
+Filter options before render: `getVisibleMcqOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues?)`.
 
-| State | Border | Background | Radio |
-|-------|--------|------------|-------|
-| Unselected | `#e5e5e5` | `white` | `border-gray-400`, empty |
-| Unselected hover | `#e5e5e5` | `hover:bg-gray-50/50` | — |
-| Selected | `#e20074` | `#fdf2f8` | `border-2 border-[#e20074]` + inner dot `h-2.5 w-2.5 bg-[#e20074]` |
+---
 
-## Structure
+## Implementation Recipe — Default answers
 
-```tsx
-<label className="flex items-center gap-4 rounded-lg border py-4 px-5 cursor-pointer">
-  <input type="radio" name={question.id} className="sr-only" />
-  <div className="h-5 w-5 rounded-full border ..."> {/* custom radio */} </div>
-  <span dangerouslySetInnerHTML={{ __html: option.label }} />
-</label>
-```
+| Concern | SDK behavior | Client UI contract |
+|---------|--------------|-------------------|
+| **Config** | API `DEFAULT_ANSWER` → `question.defaultOptionIds?: string[]` | Inventory in implementation plan §4b |
+| **Initial load** | `buildInitialAnswers` / `applyMcqDefaults` writes into `state.answers` | Bind checked state to `selectedValue` (`state.answers[question.id]`) |
+| **Single-select** | Default = `defaultOptionIds[0]` | Pre-selected radio when present in `state.answers` |
+| **Multi-select** | Default = full `defaultOptionIds` array | Pre-checked boxes for each id |
+| **User override** | `applyMcqDefaults` never overwrites user selection | Toggle via `onAction(CHANGE)` |
+| **Validation / submit** | SDK re-applies defaults in `validateCurrentPage` and submit if empty | Client does **not** re-apply defaults at NEXT/SUBMIT |
+| **Answer logic** | Hidden defaults may exist in `state.answers` until SDK sanitizes | Show checked state only for **visible** options |
+| **Template fallback** | `Question.tsx` uses `selectedValue ?? defaultOptionIds` defensively | Prefer `state.answers`; fallback is display-only |
+
+---
+
+## Implementation Recipe — Answer conditions
+
+When API `ANSWER_CONDITION` is enabled, SDK maps:
+
+- `minSelections` — minimum selected count (multi-select)
+- `maxSelections` — maximum selected count (multi-select)
+- `answerConditionErrorMessage` — shown in `state.validationErrors[questionId]`
+
+**Client must:**
+
+1. Render `validationError` banner when SDK sets an error (do not duplicate count validation).
+2. Block adding options when `selectedIds.length >= maxSelections` in multi-select UI.
+3. Pass through `onAction(CHANGE)` with updated array — SDK validates on NEXT.
+
+Skip logic may use `NUM_OF_SELECTED_OPTIONS` — see [`logic-fields-catalog.md`](../00-integration/logic-fields-catalog.md).
+
+---
 
 ## Answer Mutation
 
 ```typescript
-onSelect(option.value) // string | number
+// Single-select
+onSelect(option.id)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: string } })
+
+// Multi-select
+onSelect(selectedIds)  // string[]
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: string[] } })
 ```
 
 ## Agent Checklist
 
-- [ ] Full-width card options with gap-3 vertical stack
-- [ ] Custom circular radio indicator (not browser default)
-- [ ] Selected: magenta border + pink background
-- [ ] HTML labels
-- [ ] If `isMultiSelect`: implement checkbox cards (SDK gap in reference)
+- [ ] Use `selectionMode`, not `isMultiSelect`
+- [ ] Full-width card options; custom circular radio / checkbox indicators
+- [ ] Selected: magenta border `#e20074` + pink bg `#fdf2f8`
+- [ ] Multi-select: `string[]` answer; block at `maxSelections`
+- [ ] Defaults: bind to `state.answers`; pre-selected visual on load when `defaultOptionIds` set
+- [ ] `getVisibleMcqOptionsForAnswers` with optional `customFieldValues` 4th arg
+- [ ] Store `option.id` — never label text
+- [ ] Matrix row: [`question-type-sdk-matrix.md#mcq`](../00-integration/question-type-sdk-matrix.md#mcq)

package/templates/docs/03-ui-specs/03-text.md

@@ -1,7 +1,7 @@
-# UI Spec: Text Field (`type: 'text'`)
+# UI Spec: Text Field (`type: 'TEXTFIELD'`)
 
 > **Reference:** `apps/client/src/components/Question.tsx` (inline)
-> **SDK type:** `TextQuestion` — `fetchSurvey/types/text.ts`
+> **SDK type:** `TextInputQuestion` — `fetchSurvey/types/text.ts`
 
 ## Config Inventory
 

package/templates/docs/03-ui-specs/04-csat.md

@@ -1,57 +1,92 @@
-# UI Spec: CSAT (`type: 'csat'`)
+# UI Spec: CSAT Matrix Grid (`type: 'CSAT_MATRIX'`)
 
-> **Reference:** `apps/client/src/components/CsatScale.tsx`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CsatMatrixScale.tsx`
 > **SDK type:** `CsatQuestion` — `fetchSurvey/types/csat.ts`
-> **Component blueprint:** `01-components/04-csat-scale.md`
+> **Component blueprint:** `01-components/05-csat-matrix-scale.md`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `options[]` | ✅ | Scale buttons or dropdown options |
-| `buttonType` | ✅ partial | Branches below |
-| `labelPosition` | ✅ | `'top'` → flex-col-reverse; `'hidden'` → no label |
-| `minLabel` / `maxLabel` | ✅ | Rendered in Question.tsx above scale |
-| `hasNotApplicable` | ❌ | N/A option in options array still renders |
-| `reverseScaleOrder` | ❌ | Document: reverse options before map |
+| `statementRows[]`, `scaleColumns[]` | ✅ | Grid / carousel / dropdown data |
+| `displayStyle` | ✅ | Grid vs vertical list routing |
+| `gridLayout` | ✅ | carousel vs standard vs dropdown |
+| `hasNotApplicableOption` | ✅ | Checkbox below row (vertical) or N/A column (grid) |
+| `reverseScaleOrder` | ✅ | Flip emoji/star/number index |
+| `scaleAnchorLabels[]` | ✅ | Anchor row above columns |
 
 ## Config Decision Tree
 
 ```
-csat
-├── buttonType === 'dropdown'
-│   └── Native <select>, placeholder "Select an option"
-│       └── Parse value 'null' → null
-└── else (emoji | star | numbered | number | default)
-    └── flex flex-wrap gap-3 buttons
-        ├── emoji → getEmojiForIndex(index, scaleLength)
-        ├── star → CsatStarIcons filled/empty; labels hidden
-        ├── numbered/number → mono font value
-        └── default → bold value or 'N/A' if null
+CSAT_MATRIX
+├── gridLayout === 'carousel' → CsatMatrixCarousel
+├── displayStyle in (dropdown, selectbox) → CsatMatrixVerticalList
+│   ├── dropdown → MatrixDropdown placeholder "Select..."
+│   ├── selectbox → full-width cards #fdf2f8 selected
+│   └── else → card radio list
+└── else → CsatMatrixGrid
+    ├── displayStyle === 'emoji' → client-side emoji icons (react-icons) + hover scale + ring when selected
+    ├── displayStyle === 'star' → opacity 0.5 unselected; filled/empty icons
+    ├── displayStyle === 'numbered' → 40×40 badge; selected magenta fill
+    └── displayStyle === 'graphics' → CustomSliderTrack per row (carousel)
 ```
 
-## Interactive States
+## Grid Structure
 
-| State | Border | Background | Transform |
-|-------|--------|------------|-----------|
-| Default | `border-gray-200` | `white` | scale-100 |
-| Hover | `border-gray-300` | `hover:bg-gray-50` | — |
-| Selected | `border-[#e20074]` | `#fdf2f8` | `scale-110` |
-| Star mode | transparent | transparent | no border/bg on button |
+- Row label: `180px` fixed column
+- N/A column: `56px` when `hasNotApplicableOption`
+- Alternating row backgrounds
+- Column headers OR `scaleAnchorLabels[]` anchor row with percentage positioning
 
-## Tooltips
+## Carousel — Implementation Recipe
 
-Recommended: `title={option.label}` on each button. Not in reference client.
+Same rules as CFM carousel (prev/next disabled at bounds, dot click jumps row, no auto-advance). CSAT uses **pink** active dot `#e20074` (not Likert blue).
+
+## N/A mutex
+
+| Layout | Behavior |
+|--------|----------|
+| Grid N/A column | Selecting N/A clears row; selecting column clears N/A |
+| Vertical checkbox | `hasNotApplicableOption` checkbox below row sets `null` |
+
+## Emoji / star / numbered — react-icons mapping
+
+Copy [`templates/surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx) or implement `getEmojiForIndex(index, totalColumns)`.
+
+**5-point CSAT emoji index → icon key:**
+
+| Column index (0-based) | Sentiment | Maps to 11-point scale key |
+|--------------------------|-----------|----------------------------|
+| 0 | Very negative | 3 |
+| 1 | Negative | 4 |
+| 2 | Neutral | 6 |
+| 3 | Positive | 7 |
+| 4 | Very positive | 9 |
+
+**Star mode:** filled `FaStar` `#e20074` when selected; `FaRegStar` `#d1d5db` opacity 0.5 when unselected; hover ring `ring-2 ring-[#e20074] ring-offset-2`.
+
+**Numbered mode:** 40×40 badge; selected = magenta fill `#e20074` white text; unselected = gray border.
+
+**Graphics mode:** `CustomSliderTrack` per row with `ticks={scaleColumns.length}`, `tickLabels={scaleColumns.map(c => c.label)}`, `sliderType="graphics"`.
+
+Apply `reverseScaleOrder` by flipping column index before icon lookup.
+
+## Scale column labels on slider (Day 19)
+
+Pass `tickLabels={visibleScaleColumns.map(col => col.label)}` to `CustomSliderTrack` so tooltips and graphics thumb show mapped labels, not raw numeric indices.
 
 ## Answer Mutation
 
+Store **`column.id`** via `matrixColumnStoredValue(col)` — see `02-reference/value-derivation.md`.
+
 ```typescript
-onSelect(string | number | null)
+onSelect(MatrixRowAnswers)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } })
 ```
 
 ## Agent Checklist
 
-- [ ] Dropdown branch with magenta focus ring
-- [ ] Emoji/star/numbered branches per decision tree
-- [ ] `labelPosition` controls label above/below/hidden
-- [ ] Implement `reverseScaleOrder` and standalone `hasNotApplicable` (SDK gaps)
+- [ ] All displayStyle × gridLayout branches
+- [ ] reverseScaleOrder on emoji/star/numbered
+- [ ] Carousel pink dot indicators
+- [ ] Vertical selectbox cards match MCQ card styling

package/templates/docs/03-ui-specs/05-rating-scale.md

@@ -1,49 +1,52 @@
-# UI Spec: Rating Scale (`type: 'rating_scale'`)
+# UI Spec: Star Rating (`type: 'star_rating'`)
 
-> **Reference:** ❌ Not routed in `Question.tsx` — reuse `CsatScale.tsx` patterns
-> **SDK type:** `RatingScaleQuestion` — `fetchSurvey/types/ratingScale.ts`
-> **Component blueprint:** `01-components/03-rating-scale.md`
+> **DEPRECATED:** Not in the current `SurveyQuestion` union. API RATING pages map to `NPS_SCALE` or CSAT/RATING matrix display styles. See `01-rating.md` and matrix specs instead.
+>
+> **SDK type:** `StarRatingQuestion` — `fetchSurvey/types/starRating.ts`
+> **Component blueprint:** `01-components/04-star-rating-scale.md`
+> **Routed in template:** `Question.tsx` → `RatingScale` for `star_rating`
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `options[]` | ❌ gap | Star/emoji buttons (no NPS colors) |
-| `scaleStyle` | ❌ gap | `'star'` or `'emoji'` |
-| `minLabel` / `midLabel` / `maxLabel` | ❌ gap | Same formulas as NPS in Question shell |
-| `midLabelIndex` | ❌ gap | `(midLabelIndex / (options.length - 1)) * 100`% |
-| `reverseScaleOrder` | ❌ gap | Reverse options before render |
+| `options[]` | ✅ | Star/emoji buttons (no NPS traffic-light colors) |
+| `scaleStyle` | ✅ | `'star'` or `'emoji'` |
+| `minLabel` / `midLabel` / `maxLabel` | ✅ | Same formulas as NPS in Question shell |
+| `midLabelIndex` | ✅ | `(midLabelIndex / (options.length - 1)) * 100`% |
+| `reverseScaleOrder` | partial | Reverse options before render |
 
-## Expected UI (from CsatScale + rating labels)
+## Expected UI
 
 ```
 [minLabel]     [midLabel @ %]     [maxLabel]
 ┌────┬────┬────┬────┬────┐
 │ ★  │ ★  │ ★  │ ★  │ ★  │  scaleStyle: 'star'
 └────┴────┴────┴────┴────┘
-  OR emoji row from getEmojiForIndex when scaleStyle: 'emoji'
+  OR emoji row from client-side react-icons when scaleStyle: 'emoji'
 ```
 
-Reuse CsatScale selected styling: `border-[#e20074] bg-[#fdf2f8] scale-110`.
+Selected styling: `border-[#e20074] bg-[#fdf2f8] scale-110`.
 
 ## Config Decision Tree
 
 ```
-rating_scale
-├── scaleStyle === 'star' → CsatStarIcons per option
-├── scaleStyle === 'emoji' → getEmojiForIndex
-└── else → numbered badges (no option.color)
+star_rating
+├── scaleStyle === 'star' → client-side star icons (react-icons) per option
+├── scaleStyle === 'emoji' → client-side emoji icons (react-icons)
+└── else → numbered badges (no accentColor)
 ```
 
 ## Answer Mutation
 
 ```typescript
 onSelect(number)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: number } })
 ```
 
 ## Agent Checklist
 
-- [ ] Add dispatcher branch in Question for `rating_scale`
+- [ ] Dispatcher branch for `star_rating` in Question.tsx
 - [ ] No traffic-light NPS colors on options
 - [ ] min/mid/max labels with midLabelIndex formula
-- [ ] Match CsatScale interactive states
+- [ ] Match star/emoji bounding box rules from `04-star-rating-scale.md`

package/templates/docs/03-ui-specs/06-slider.md

@@ -1,6 +1,8 @@
 # UI Spec: Standalone Slider (`type: 'slider'`)
 
-> **Reference:** ❌ Not routed in `Question.tsx` — reuse `CustomSliderTrack.tsx`
+> **DEPRECATED:** Not in the current `SurveyQuestion` union. API SLIDER pages map to `SLIDER_MATRIX` or matrix `displayStyle: 'graphics'`. See `10-slider-matrix.md` and `CustomSliderTrack` specs.
+>
+> **Reference:** Standalone slider is not routed in current `Question.tsx`
 > **SDK type:** `SliderQuestion` — `fetchSurvey/types/slider.ts`
 > **Component blueprint:** `01-components/09-custom-slider-track.md`