@explorer02/cfm-survey-sdk 0.2.0 → 0.2.2

package/templates/docs/03-ui-specs/13-heatmap.md

@@ -0,0 +1,73 @@
+# UI Spec: Heatmap (`type: 'HEATMAP'`)
+
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/HeatmapScale.tsx`
+> **SDK type:** `HeatmapQuestion` — `fetchSurvey/types/heatmap.ts`
+> **Component blueprint:** `01-components/17-heatmap-scale.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `questionText` | ✅ (shell) | Bold title + required asterisk |
+| `questionDescription` | ✅ (shell) | Instruction text below title |
+| `required` | ✅ (shell + SDK) | Asterisk + validation on NEXT |
+| `imageUrl` | ✅ | Center-aligned interactive image |
+| `maxClicksAllowed` | ✅ | Footer hint count; blocks new clicks at limit |
+| `regions` | ❌ (respondent UI) | Logic only — not rendered on survey |
+
+## Layout Anatomy
+
+```
+[Question shell: title *, description]
+[Heatmap container — relative, inline-block, max-width 100%]
+  [<img> — object-contain, display block, crosshair cursor]
+  [Spot overlay — absolute inset-0, pointer-events-none]
+    [Orange circle markers at normalized x/y positions]
+[Footer hint — info icon + max spots text]
+[Validation error — from Question shell]
+```
+
+## Spot Marker Visual Spec
+
+| Property | Value |
+|----------|-------|
+| Shape | Circle |
+| Diameter | 16px |
+| Fill | `#F97316` |
+| Border | 2px solid `#FFFFFF` |
+| Shadow | `0 1px 3px rgba(0,0,0,0.25)` |
+| Position | `left: x * 100%`, `top: y * 100%`, `transform: translate(-50%, -50%)` |
+
+## Interactive States
+
+| State | Behavior |
+|-------|----------|
+| Image loading | Spinner overlay; clicks disabled |
+| Ready | `cursor: crosshair` on image |
+| At max clicks | Block new adds; allow remove |
+| Removing last spot | `onSelect(undefined)` |
+
+## Footer Hint Text
+
+```
+ⓘ You can select up to {maxClicksAllowed} spot(s). To change your selection, simply click on the same spot again to remove it.
+```
+
+Use singular "spot" when `maxClicksAllowed === 1`.
+
+## Answer Mutation
+
+```typescript
+onSelect(HeatmapAnswer | undefined)
+// HeatmapAnswer = Array<{ id: string; x: number; y: number }>
+// x, y normalized 0–1 relative to rendered image bounds
+```
+
+## Agent Checklist
+
+- [ ] Click handler on `<img>` element (not overlay) for precise coordinates
+- [ ] `inline-block` wrapper so spots align with image bounds
+- [ ] Toggle-remove within 14px hit radius
+- [ ] Wait for `onLoad` before accepting clicks
+- [ ] Percentage-positioned spots (survives resize)
+- [ ] Do NOT render region overlays on respondent UI

package/templates/docs/03-ui-specs/14-rank-order.md

@@ -0,0 +1,59 @@
+# Rank Order UI Spec (`RANK_ORDER`)
+
+> **Reference:** `02-reference/question-types/13-rank-order.md`
+> **Blueprint:** `01-components/18-rank-order-scale.md`
+
+## Interaction Modes
+
+### Dropdown (`interactionMode: 'dropdown'`)
+
+| Element | Behavior |
+|---------|----------|
+| Rank select | `-` (unassigned) or `1..N` per option row |
+| Duplicate ranks | Selecting rank R on option A clears R from any other option |
+| Layout | Rank select on left, option content on right |
+
+### Drag and Drop (`interactionMode: 'dragAndDrop'`)
+
+| Element | Behavior |
+|---------|----------|
+| Drag handle | Six-dot grip on left; pointer + keyboard sensors |
+| Rank badge | Circular badge showing 1-based position |
+| Reorder | List order determines rank; smooth transform during drag |
+| Up/Down buttons | Keyboard fallback on right side of each row |
+
+## Option Display Variants
+
+| `optionDisplay` | Render |
+|-----------------|--------|
+| `textOnly` | Full-width text label only |
+| `imageOnly` | Large square thumbnail only (no label) |
+| `textAndImage` | Thumbnail + text label side by side |
+
+Use `dangerouslySetInnerHTML` for option labels (HTML from builder).
+
+## Validation UX
+
+- Required + `requireRankAll`: every visible option must have a unique rank from 1..N
+- Required + not `requireRankAll`: at least one visible option ranked
+- SDK surfaces `validationError` on the question shell — show the standard error banner
+
+## Styling
+
+Match MCQ card styling:
+
+- Border: `#e5e5e5` default, `#e20074` when actively ranked (optional highlight)
+- Background hover: `hover:bg-gray-50/50`
+- Rank badge: `#fdf2f8` background, `#e20074` text
+
+## Accessibility
+
+- Each rank select: `aria-label="Rank for {option label}"`
+- Drag handle: `aria-label="Drag to reorder {option label}"`
+- Up/Down: disabled on first/last item
+
+## Do Not
+
+- Store ranks in local component state without syncing to `onSelect`
+- Submit option labels — submit rank numbers via SDK formatter only
+- Hardcode logic operators in the client — all conditions are SDK-evaluated

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

@@ -1,7 +1,8 @@
 # UI Specifications — Reference Implementation Guide
 
-> **Authoritative source:** [`apps/client/src/components/`](../../../../../../apps/client/src/components/) in the monorepo.
-> Agents must reproduce this UI when building survey apps. Read the spec for each question type present in the fetched survey.
+> **For npm installs:** implement from these specs + [`templates/Question.tsx`](../templates/Question.tsx).
+> **For monorepo devs:** Reference client at `apps/client/src/components/` aligns with SDK types — trust `03-ui-specs/`, `templates/Question.tsx`, and exported types.
+> Read the spec for **each question type present** in the fetched survey before writing React code.
 
 ## How to Read a UI Spec
 
@@ -37,14 +38,14 @@ Each file in this folder follows the same structure:
 | Spec file | Reference component | `question.type` |
 |-----------|---------------------|-----------------|
 | [00-question-shell.md](00-question-shell.md) | `Question.tsx` | All (wrapper) |
-| [01-rating.md](01-rating.md) | `RatingScale.tsx` | `rating` |
-| [02-radio.md](02-radio.md) | `Question.tsx` inline | `radio` |
-| [03-text.md](03-text.md) | `Question.tsx` inline | `text` |
-| [04-csat.md](04-csat.md) | `CsatScale.tsx` | `csat` |
-| [05-rating-scale.md](05-rating-scale.md) | *(gap — reuse CsatScale patterns)* | `rating_scale` |
-| [06-slider.md](06-slider.md) | *(gap — reuse CustomSliderTrack)* | `slider` |
-| [07-matrix-cfm.md](07-matrix-cfm.md) | `LikertMatrixScale.tsx` | `matrix` + CFM |
-| [08-matrix-csat-rating.md](08-matrix-csat-rating.md) | `CsatMatrixScale.tsx` | CSAT/RATING matrix |
+| [01-rating.md](01-rating.md) | `RatingScale.tsx` | `nps` |
+| [02-radio.md](02-radio.md) | `Question.tsx` inline | `mcq` |
+| [03-text.md](03-text.md) | `Question.tsx` inline | `text_input` |
+| [04-csat.md](04-csat.md) | `CsatMatrixScale.tsx` | `csat` |
+| [05-rating-scale.md](05-rating-scale.md) | `RatingScale.tsx` | `star_rating` |
+| [06-slider.md](06-slider.md) | `CustomSliderTrack.tsx` | `slider` |
+| [07-matrix-cfm.md](07-matrix-cfm.md) | `LikertMatrixScale.tsx` | `cfm_matrix` |
+| [08-matrix-csat-rating.md](08-matrix-csat-rating.md) | `CsatMatrixScale.tsx` | `rating_matrix` |
 | [09-slider-matrix.md](09-slider-matrix.md) | `SliderMatrixScale.tsx` | `slider_matrix` |
 | [10-file-upload.md](10-file-upload.md) | `FileUploadScale.tsx` | `file_upload` |
 | [11-text-and-media.md](11-text-and-media.md) | `Question.tsx` inline | `text_and_media` |
@@ -54,7 +55,7 @@ Each file in this folder follows the same structure:
 
 ## NPS Traffic-Light Colors
 
-Use `option.color` from SDK — never invent colors:
+Use accent colors from SDK options — never invent colors for NPS:
 
 | Value | Hex |
 |-------|-----|
@@ -72,8 +73,8 @@ Use `option.color` from SDK — never invent colors:
 
 ## When to Read
 
-After Phase 3 in [`index.md`](../index.md), for each question in `state.currentQuestions`:
+After Phase 3 in [`index.md`](../index.md), for each question in the fetched survey:
 
 1. Read [`02-reference/question-types/`](../02-reference/question-types/) for data shape
-2. Read matching spec from this folder (see [`MANIFEST.json`](../MANIFEST.json) `uiSpecs`)
+2. Read matching spec from this folder (see [`MANIFEST.json`](../MANIFEST.json) `questionTypes.{type}.uiSpec`)
 3. Cross-check [`config-field-index.md`](../02-reference/config-field-index.md)

package/templates/docs/03-ui-specs/shared/custom-slider-track.md

@@ -1,6 +1,6 @@
 # UI Spec: Custom Slider Track (shared primitive)
 
-> **Reference:** `apps/client/src/components/CustomSliderTrack.tsx`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CustomSliderTrack.tsx`
 > **Used by:** `SliderMatrixScale.tsx`, `CsatMatrixScale` (graphics), standalone `slider` (gap)
 
 ## Layer Architecture
@@ -23,7 +23,7 @@
 | `disabled` | Gray theme, opacity 0.5, no interaction |
 | `displayValues` | Reserved — tooltip always shows on hover/drag in client |
 | `hasSelectedValue` | Reserved |
-| `sliderType: 'graphics'` | Emoji thumb via `getEmojiForIndex` |
+| `sliderType: 'graphics'` | Emoji thumb via client-side react-icons |
 | `ticks` | Discrete tick count + emoji index scale |
 | `reverseScaleOrder` | Flip emoji index calculation |
 
@@ -41,7 +41,7 @@
 ```typescript
 const idx = Math.round(((value - min) / (max - min)) * ((ticks || 10) - 1));
 const displayIdx = reverseScaleOrder ? (ticks || 10) - 1 - idx : idx;
-getEmojiForIndex(displayIdx, ticks || 10)
+// Map displayIdx to react-icons emoji — proportional mapping is client-implemented (not an SDK export)
 ```
 
 ## Agent Checklist

package/templates/docs/03-ui-specs/shared/matrix-dropdown.md

@@ -1,6 +1,6 @@
 # UI Spec: Matrix Dropdown (shared primitive)
 
-> **Reference:** `apps/client/src/components/MatrixDropdown.tsx`
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/MatrixDropdown.tsx`
 > **Used by:** `LikertMatrixScale`, `CsatMatrixScale` vertical list
 
 ## Modes
@@ -30,6 +30,11 @@ if (val === null) {
 // When null selected, non-null options disabled
 ```
 
+## Props
+
+- `options: ScaleColumn[]` — matrix scale columns (`id`, `label`)
+- `value` / `onChange` — stored values use `matrixColumnStoredValue(col)` → column **`id`**
+
 ## Agent Checklist
 
 - [ ] Click-outside closes panel