@explorer02/cfm-survey-sdk 0.2.1 → 0.2.3

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

@@ -0,0 +1,128 @@
+# Rank Order UI Spec (`RANK_ORDER`)
+
+> **Reference:** `02-reference/question-types/13-rank-order.md`
+> **Blueprint:** `01-components/18-rank-order-scale.md`
+> **Portable template:** copy [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx)
+
+## Config gate
+
+| Field | Values | UI branch |
+|-------|--------|-----------|
+| `interactionMode` | `'dropdown'` | Rank `<select>` per row |
+| `interactionMode` | `'dragAndDrop'` | `@dnd-kit` sortable list |
+| `optionDisplay` | `textOnly` / `imageOnly` / `textAndImage` | Option content layout |
+| `requireRankAll` | boolean | Validation (SDK) |
+| `shuffleOptions` | boolean | **SDK shuffles at fetch** — render `question.options` as-is; do not re-shuffle client-side |
+
+## Dependencies
+
+```bash
+npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+```
+
+Next.js: template includes `'use client'`. Optional in `Question.tsx`:
+
+```tsx
+const RankOrderScale = dynamic(() => import('./RankOrderScale').then(m => ({ default: m.RankOrderScale })), {
+  ssr: false,
+  loading: () => <p>Loading rank order…</p>,
+});
+```
+
+## SDK wiring
+
+```typescript
+import {
+  getVisibleRankOrderOptionsForAnswers,
+  normalizeRankOrderAnswers,
+  assignRankWithoutDuplicates,
+  buildRankOrderFromOrderedOptionIds,
+  getOrderedOptionIdsFromRanks,
+} from '@explorer02/cfm-survey-sdk';
+
+// Question.tsx — filter options + normalize answer
+const rankOrderQuestion = {
+  ...question,
+  options: getVisibleRankOrderOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues),
+};
+<RankOrderScale
+  question={rankOrderQuestion}
+  selectedValue={normalizeRankOrderAnswers(selectedValue)}
+  onSelect={onSelect}
+/>
+```
+
+Answer shape: `RankOrderAnswers` = `Record<optionId, rank>` (1-based).
+
+## Interaction modes
+
+### Dropdown (`interactionMode: 'dropdown'`)
+
+| Element | Behavior |
+|---------|----------|
+| Rank select | `-` (unassigned) or `1..N` per option row |
+| Duplicate ranks | `assignRankWithoutDuplicates` clears rank R from other options |
+| Layout | Rank select left, option content right |
+
+### Drag and drop (`interactionMode: 'dragAndDrop'`)
+
+| Element | Behavior |
+|---------|----------|
+| Drag handle | Six-dot grip; `PointerSensor` + `KeyboardSensor` |
+| Rank badge | Circular badge showing 1-based position |
+| Reorder | List order → `buildRankOrderFromOrderedOptionIds(orderedIds)` |
+| Up/Down | Keyboard fallback; disabled on first/last |
+
+## Implementation Recipe — dnd-kit
+
+```typescript
+const sensors = useSensors(
+  useSensor(PointerSensor),
+  useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates })
+);
+
+const handleDragEnd = (event: DragEndEvent) => {
+  const { active, over } = event;
+  if (!over || active.id === over.id) return;
+  const oldIndex = orderedOptionIds.indexOf(String(active.id));
+  const newIndex = orderedOptionIds.indexOf(String(over.id));
+  if (oldIndex === -1 || newIndex === -1) return;
+  onSelect(buildRankOrderFromOrderedOptionIds(arrayMove(orderedOptionIds, oldIndex, newIndex)));
+};
+```
+
+Wrap list in `<DndContext collisionDetection={closestCenter}>` + `<SortableContext strategy={verticalListSortingStrategy}>`.
+
+Copy full implementation from [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx).
+
+## Option display
+
+| `optionDisplay` | Render |
+|-----------------|--------|
+| `textOnly` | Label via `dangerouslySetInnerHTML` |
+| `imageOnly` | Square thumbnail; prefer `option.imageUrl` over `previewImageUrl` |
+| `textAndImage` | Thumbnail + label side by side |
+
+## Validation UX
+
+- Required + `requireRankAll`: every visible option unique rank 1..N
+- Required + not `requireRankAll`: at least one visible option ranked
+- Show `validationError` from question shell
+
+## Styling
+
+- Border `#e5e5e5`, optional `#e20074` when ranked
+- Rank badge: `#fdf2f8` bg, `#e20074` text
+
+## Logic
+
+RANK_ORDER operators (ranked as/above/below) — see [`logic-fields-catalog.md`](../00-integration/logic-fields-catalog.md).
+
+## Agent checklist
+
+- [ ] Copied `templates/RankOrderScale.tsx` (or equivalent dnd-kit + dropdown)
+- [ ] `@dnd-kit/*` in package.json when survey has RANK_ORDER
+- [ ] `getVisibleRankOrderOptionsForAnswers` + `normalizeRankOrderAnswers`
+- [ ] `option.imageUrl` before `previewImageUrl`
+- [ ] No client-side re-shuffle when `shuffleOptions` is true
+- [ ] No stub placeholder text

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

@@ -1,7 +1,7 @@
 # UI Specifications — Reference Implementation Guide
 
-> **For npm installs:** implement from these specs + [`templates/Question.tsx`](../templates/Question.tsx). The monorepo path `apps/client/src/components/` is **not** available in client projects.
-> **For monorepo devs:** cross-check against [`apps/client/src/components/`](../../../../../../apps/client/src/components/).
+> **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
@@ -38,24 +38,26 @@ 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_SCALE` |
+| [02-radio.md](02-radio.md) | `Question.tsx` inline | `MCQ` |
+| [03-text.md](03-text.md) | `Question.tsx` inline | `TEXTFIELD` |
+| [04-csat.md](04-csat.md) | `CsatMatrixScale.tsx` | `CSAT_MATRIX` |
+| [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` |
+| [11-text-and-media.md](11-text-and-media.md) | `Question.tsx` inline | `TEXT_AND_MEDIA` |
+| [13-heatmap.md](13-heatmap.md) | `HeatmapScale.tsx` | `HEATMAP` |
+| [14-rank-order.md](14-rank-order.md) | `RankOrderScale.tsx` | `RANK_ORDER` |
 | [12-survey-chrome.md](12-survey-chrome.md) | `SurveyPage.tsx` + chrome | Shell |
 | [shared/custom-slider-track.md](shared/custom-slider-track.md) | `CustomSliderTrack.tsx` | Primitive |
 | [shared/matrix-dropdown.md](shared/matrix-dropdown.md) | `MatrixDropdown.tsx` | Primitive |
 
 ## 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 |
 |-------|-----|
@@ -73,8 +75,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,52 +1,45 @@
 # UI Spec: Custom Slider Track (shared primitive)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CustomSliderTrack.tsx`
-> **Used by:** `SliderMatrixScale.tsx`, `CsatMatrixScale` (graphics), standalone `slider` (gap)
+> **Portable template:** copy [`templates/CustomSliderTrack.tsx`](../templates/CustomSliderTrack.tsx) + [`templates/surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx)
+> **Used by:** `SliderMatrixScale`, `CsatMatrixScale` (graphics), matrix `displayStyle: graphics`
+
+## Scale column labels (Day 19 — CRITICAL)
+
+Matrix rows must pass **`tickLabels` from `scaleColumns[].label`** (filtered to visible columns):
+
+```typescript
+const tickLabels = visibleScaleColumns.map(col => col.label);
+<CustomSliderTrack tickLabels={tickLabels} ticks={tickLabels.length} ... />
+```
+
+Tooltip shows stripped HTML from `tickLabels[tickIndex]`; without labels, tooltips fall back to numeric value only.
 
 ## Layer Architecture
 
 ```
-1. Gray inactive track (#e5e7eb, 4px height)
-2. Magenta fill bar (width = percentage%, #e20074 or #9ca3af if disabled)
-3. Tick marks (1px × 8px at ticks positions)
-4. Invisible <input type="range"> overlay (opacity 0, full hit area)
-5. Visual thumb: circle OR emoji (sliderType === 'graphics')
-6. Tooltip bubble on hover/drag (#1f2937 bg, rounded value)
+1. Gray inactive track (#e5e7eb, 4px)
+2. Magenta fill bar (percentage%, #e20074 or #9ca3af if disabled)
+3. Tick marks at column positions
+4. Invisible <input type="range"> overlay
+5. Thumb: circle OR emoji (sliderType === 'graphics')
+6. Tooltip on hover/drag (#1f2937)
 ```
 
 ## Props
 
 | Prop | Role |
 |------|------|
-| `min`, `max`, `htmlStep` | Range input bounds |
+| `min`, `max`, `htmlStep` | Range bounds |
 | `value` | Current position |
-| `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` |
-| `ticks` | Discrete tick count + emoji index scale |
-| `reverseScaleOrder` | Flip emoji index calculation |
-
-## Interactive States
-
-| State | Thumb | Tooltip |
-|-------|-------|---------|
-| Default | White circle, 2.5px magenta border | Hidden |
-| Hover/drag | Pink glow ring `rgba(226,0,116,0.2)` | Dark bubble with `Math.round(value)` |
-| Disabled | Gray border, opacity 0.5 | Hidden |
-| Graphics | Emoji at percentage position | Same tooltip |
-
-## Emoji Index Formula
-
-```typescript
-const idx = Math.round(((value - min) / (max - min)) * ((ticks || 10) - 1));
-const displayIdx = reverseScaleOrder ? (ticks || 10) - 1 - idx : idx;
-getEmojiForIndex(displayIdx, ticks || 10)
-```
+| `disabled` | Gray theme, opacity 0.5 |
+| `sliderType: 'graphics'` | Emoji thumb via `surveyUiIcons.getEmojiForIndex` |
+| `ticks` | Discrete tick count |
+| **`tickLabels`** | **Column labels for tooltip + graphics index** |
+| `reverseScaleOrder` | Flip emoji index |
 
 ## Agent Checklist
 
-- [ ] 4-layer overlay with invisible range input
+- [ ] Copy portable template or match layer stack
+- [ ] Always pass `tickLabels` from matrix `scaleColumns` when available
 - [ ] Tooltip on hover AND drag
-- [ ] Graphics mode emoji thumb
-- [ ] Transition disabled while dragging
+- [ ] Graphics emoji thumb with `reverseScaleOrder` support

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

@@ -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