@explorer02/cfm-survey-sdk 0.1.9 → 0.2.1

package/templates/docs/03-ui-specs/10-file-upload.md

@@ -0,0 +1,54 @@
+# UI Spec: File Upload (`type: 'file_upload'`)
+
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/FileUploadScale.tsx`
+> **SDK type:** `FileUploadQuestion` — `fetchSurvey/types/fileUpload.ts`
+> **Component blueprint:** `01-components/08-file-upload-scale.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `uploadMessage` | ✅ | HTML in dropzone (bold 16px) |
+| `supportedFileFormats` | ✅ | Validation + accept attribute |
+| `maxFileCount` | ✅ | Total file limit |
+| `fileSizeLimit` | ✅ | MB limit |
+| `fileSizeLimitType` | ✅ | `PER_FILE` or `IN_TOTAL` |
+
+## Layout Anatomy
+
+```
+[uploadMessage HTML in dashed dropzone]
+  File limit: N; File size limit: XMB/file|in total; Supports: ...
+[local error banner — red if validation fails]
+[file list cards: icon, name, size, remove ×]
+```
+
+## Interactive States
+
+| State | Border | Background |
+|-------|--------|------------|
+| Default | `#d1d5db` dashed | `#f9fafb` |
+| Hover | `#e20074` | `#fdf2f8` |
+| Drag active | `#e20074` | `#fdf2f8` |
+
+## Local Validation (before SDK)
+
+1. Max file count exceeded
+2. Unsupported extension
+3. PER_FILE size exceeded
+4. IN_TOTAL cumulative size exceeded
+
+Error banner: `#fee2e2` bg, `#b91c1c` text.
+
+## Answer Mutation
+
+```typescript
+onSelect(File[] | undefined) // undefined when all removed
+```
+
+## Agent Checklist
+
+- [ ] Hidden `<input type="file">` triggered by dropzone click
+- [ ] Drag enter/over/leave/drop handlers
+- [ ] Dynamic constraints line in dropzone
+- [ ] File list with remove button (hover red)

package/templates/docs/03-ui-specs/11-text-and-media.md

@@ -0,0 +1,49 @@
+# UI Spec: Text and Media (`type: 'text_and_media'`)
+
+> **Reference:** `apps/client/src/components/Question.tsx` (inline)
+> **SDK type:** `TextAndMediaQuestion` — `fetchSurvey/types/textAndMedia.ts`
+> **Component blueprint:** `01-components/02-question.md`
+
+## Config Inventory
+
+| Field | Implemented | UI impact |
+|-------|-------------|-----------|
+| `mediaUrl` | ✅ | Required to render media block |
+| `mediaMimeType` | ✅ | `video/` or `VIDEO` → `<video>`; else `<img>` |
+| `mediaTitle` | ✅ | Caption below media, centered gray text |
+| `mediaAlignment` | ✅ | Flex justify: CENTER / RIGHT / default left |
+| `mediaSize` | ✅ | Width `%` on media container; default 100% |
+
+No answer input — display-only question.
+
+## Layout Anatomy
+
+```
+[question title + description — standard shell]
+
+┌─ flex container (justify per mediaAlignment) ──────────────┐
+│  ┌─ media block (width: mediaSize%) ──────────────────┐   │
+│  │  <video controls> or <img>                          │   │
+│  │  [optional mediaTitle caption]                      │   │
+│  └─────────────────────────────────────────────────────┘   │
+└────────────────────────────────────────────────────────────┘
+```
+
+## Alignment Mapping
+
+| `mediaAlignment` | CSS |
+|------------------|-----|
+| `TOP_CENTER`, `BOTTOM_CENTER` | `justify-center` |
+| `TOP_RIGHT`, `BOTTOM_RIGHT` | `justify-end` |
+| default | `justify-start` |
+
+## Answer Mutation
+
+None — no `onSelect` payload for this type.
+
+## Agent Checklist
+
+- [ ] Render only when `mediaUrl` is present
+- [ ] Video vs image from mime type
+- [ ] `max-w-full rounded-md shadow-sm` on media element
+- [ ] Optional centered caption for `mediaTitle`

package/templates/docs/03-ui-specs/12-survey-chrome.md

@@ -0,0 +1,60 @@
+# UI Spec: Survey Chrome
+
+> **Reference:** `SurveyPage.tsx`, `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `LanguageSelector.tsx`
+> **Component blueprints:** `01-components/01-survey-page.md`, `10-header-footer.md`, `11-progress-bar.md`, `12-language-selector.md`
+
+## SurveyPage — 5-State Machine
+
+| State | Condition | UI |
+|-------|-----------|-----|
+| Loading | `surveyQueryResults.isLoading` | Centered "Loading..." |
+| Error | `surveyQueryResults.error` | Red error message |
+| Empty | `!survey` | "No survey data" |
+| Submitted | `submitSurveyResults.data` | Thank you message |
+| Active | else | Questions + nav |
+
+## Active Layout
+
+```
+Header
+main (max-w-4xl)
+  ProgressBar(progressPercentage)
+  LanguageSelector (hidden if ≤1 language)
+  Questions (space-y-12)
+  Submit error (if any)
+  Nav: Back (if page > 0) + Next/Submit
+Footer
+```
+
+## Navigation Labels
+
+German when `survey.language.startsWith('de')`:
+
+| Action | EN | DE |
+|--------|----|----|
+| Back | Zurück | Back |
+| Next | Weiter | Next |
+| Submit | Absenden | Submit |
+| Submitting | Wird gesendet... | Submitting... |
+
+## Button Tokens
+
+- Back: `border-[#e20074] text-[#e20074] hover:bg-[#fdf2f8]`
+- Primary: `bg-[#e20074] text-white hover:opacity-90`
+
+## ProgressBar
+
+Pink fill bar, `300ms` width transition on `progressPercentage`.
+
+## LanguageSelector
+
+- Hidden when `languages.length <= 1`
+- Focus ring: `#2563eb`
+
+## Agent Checklist
+
+- [ ] All 5 states implemented
+- [ ] `onAction({ type: 'CHANGE' })` wired per question
+- [ ] PREVIOUS / NEXT actions on nav buttons
+- [ ] ProgressBar receives `state.progressPercentage`
+- [ ] Header/Footer on every state branch

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

@@ -0,0 +1,80 @@
+# 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/).
+> Read the spec for **each question type present** in the fetched survey before writing React code.
+
+## How to Read a UI Spec
+
+Each file in this folder follows the same structure:
+
+1. **Config inventory** — every SDK field, whether the reference client implements it
+2. **Layout anatomy** — structured ASCII diagram
+3. **Config decision tree** — matches `if/else` branches in reference code
+4. **Interactive states** — default, hover, selected, disabled, focus
+5. **Tooltips & labels** — positioning formulas
+6. **Color tokens** — exact hex values from reference client
+7. **Answer mutation** — `onSelect` / `onAction CHANGE` shape
+8. **Agent checklist**
+
+## Design Tokens (Reference Client)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| Primary | `#e20074` | Borders, rings, dots, slider fill, selected text |
+| Selected bg | `#fdf2f8` | Card options, CSAT buttons, matrix cells |
+| NPS track highlight | `#fbe8f3` | Selected radio cell in NPS track row |
+| NPS track bar | `#f2f2f2` | Gray bar behind NPS radios |
+| Validation border | `#333333` | Error banner |
+| Validation bg | `#d9d9d9` | Error banner |
+| Row band | `#f3f4f6` | Slider matrix row background |
+| Zebra row | `rgba(249,250,251,0.8)` | Matrix alternating rows |
+| Tooltip bg | `#1f2937` | Hover tooltips on emoji/slider |
+| Likert carousel dot (active) | `#2563eb` | LikertMatrix carousel only |
+| CSAT carousel dot (active) | `#e20074` | CsatMatrix carousel |
+
+## Reference Component Index
+
+| 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 |
+| [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` |
+| [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:
+
+| Value | Hex |
+|-------|-----|
+| 0 | `#e2001a` |
+| 1 | `#e4251b` |
+| 2 | `#ec610a` |
+| 3 | `#f18b00` |
+| 4 | `#f7b200` |
+| 5 | `#fcd900` |
+| 6 | `#fcd900` |
+| 7 | `#9fca00` |
+| 8 | `#6bb300` |
+| 9 | `#339a00` |
+| 10 | `#008000` |
+
+## When to Read
+
+After Phase 3 in [`index.md`](../index.md), for each question in `state.currentQuestions`:
+
+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`)
+3. Cross-check [`config-field-index.md`](../02-reference/config-field-index.md)

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

@@ -0,0 +1,52 @@
+# 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)
+
+## 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)
+```
+
+## Props
+
+| Prop | Role |
+|------|------|
+| `min`, `max`, `htmlStep` | Range input 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)
+```
+
+## Agent Checklist
+
+- [ ] 4-layer overlay with invisible range input
+- [ ] Tooltip on hover AND drag
+- [ ] Graphics mode emoji thumb
+- [ ] Transition disabled while dragging

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

@@ -0,0 +1,38 @@
+# UI Spec: Matrix Dropdown (shared primitive)
+
+> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/MatrixDropdown.tsx`
+> **Used by:** `LikertMatrixScale`, `CsatMatrixScale` vertical list
+
+## Modes
+
+| `multiple` | Trigger | Selection |
+|------------|---------|-----------|
+| `false` | Single line + chevron | One value; checkmark on selected option |
+| `true` | Tag chips with × | Toggle array; N/A mutex |
+
+## Interactive States
+
+| State | Trigger border | Shadow |
+|-------|----------------|--------|
+| Closed | `#d1d5db` | subtle |
+| Open | `#e20074` | `0 0 0 3px rgba(226,0,116,0.1)` |
+| Option hover | bg `#fdf2f8` | — |
+| Option selected | bg `#fdf2f8`, text `#e20074` | — |
+| N/A mutex (multi) | Other options opacity 0.5, disabled | — |
+
+## N/A Mutex (multi-select)
+
+```typescript
+if (val === null) {
+  if (multiValues.includes(null)) onChange([]);
+  else onChange([null]);
+}
+// When null selected, non-null options disabled
+```
+
+## Agent Checklist
+
+- [ ] Click-outside closes panel
+- [ ] HTML labels via dangerouslySetInnerHTML
+- [ ] Single: close on select
+- [ ] Multi: tag chips removable with ×

package/templates/docs/MANIFEST.json

@@ -33,6 +33,8 @@
       "id": 4,
       "name": "planAndIngest",
       "read": [
+        "00-integration/component-checklist.md",
+        "03-ui-specs/README.md",
         "01-components/README.md",
         "01-components/01-survey-page.md",
         "01-components/02-question.md",
@@ -49,6 +51,7 @@
         "01-components/13-matrix-dropdown.md"
       ],
       "template": "templates/implementation_plan.md",
+      "questionDispatcher": "templates/Question.tsx",
       "output": "implementation_plan.md"
     },
     {
@@ -63,6 +66,8 @@
       "read": ["00-integration/constraints.md"],
       "checklist": [
         "questionDispatcherCoversAll12Types",
+        "matrixRoutesBySubType",
+        "noStubPlaceholderText",
         "everyQuestionWrapperHasId",
         "noInternalSdkImports",
         "surveyPageFiveStates",
@@ -125,5 +130,26 @@
       "component": "01-components/02-question.md",
       "reference": "02-reference/question-types/README.md#text_and_media"
     }
-  }
+  },
+  "uiSpecs": {
+    "questionShell": "03-ui-specs/00-question-shell.md",
+    "rating": "03-ui-specs/01-rating.md",
+    "radio": "03-ui-specs/02-radio.md",
+    "text": "03-ui-specs/03-text.md",
+    "csat": "03-ui-specs/04-csat.md",
+    "rating_scale": "03-ui-specs/05-rating-scale.md",
+    "slider": "03-ui-specs/06-slider.md",
+    "matrix_CFM_MATRIX": "03-ui-specs/07-matrix-cfm.md",
+    "matrix_CSAT_MATRIX": "03-ui-specs/08-matrix-csat-rating.md",
+    "matrix_RATING_MATRIX": "03-ui-specs/08-matrix-csat-rating.md",
+    "slider_matrix": "03-ui-specs/09-slider-matrix.md",
+    "file_upload": "03-ui-specs/10-file-upload.md",
+    "text_and_media": "03-ui-specs/11-text-and-media.md",
+    "surveyChrome": "03-ui-specs/12-survey-chrome.md"
+  },
+  "sharedUiSpecs": {
+    "customSliderTrack": "03-ui-specs/shared/custom-slider-track.md",
+    "matrixDropdown": "03-ui-specs/shared/matrix-dropdown.md"
+  },
+  "configFieldIndex": "02-reference/config-field-index.md"
 }

package/templates/docs/index.md

@@ -11,10 +11,12 @@ docs/
 ├── index.md                 ← YOU ARE HERE
 ├── MANIFEST.json            ← Phase + question-type routing (for tooling)
 ├── 00-integration/          ← Setup, hook contract, constraints
-├── 01-components/           ← UI blueprints (read ALL before coding)
-├── 02-reference/            ← Routing table + question-type data (on demand)
+├── 01-components/           ← Wiring blueprints (read ALL before coding)
+├── 02-reference/            ← Routing table + config-field-index (on demand)
+├── 03-ui-specs/             ← Authoritative UI specs (reference-client driven)
 └── templates/
-    └── implementation_plan.md
+    ├── implementation_plan.md
+    └── Question.tsx           ← Canonical dispatcher (copy before building)
 ```
 
 **Import rule:** Use whatever package name appears in the project's `package.json` (`@explorer02/cfm-survey-sdk` or `@repo/sdk`).
@@ -63,17 +65,26 @@ Optional: read `02-reference/routing-table.md` for type overview.
 ### PHASE 4: PLAN + INGEST (CRITICAL)
 
 1. Read **every** file in `01-components/` (all 14 blueprints)
-2. Copy `docs/templates/implementation_plan.md` → `./implementation_plan.md`
-3. Fill every section — do **not** invent a different structure
-4. **Auto-proceed to Phase 5** — do not wait for approval
-
-For each question type in the fetched survey, also read matching docs from `02-reference/question-types/` (see `MANIFEST.json` or `02-reference/routing-table.md`).
+2. Read `00-integration/component-checklist.md` and `03-ui-specs/README.md`
+3. **Inventory** every `(type, subType)` in `survey.pages` after instanceId fetch
+4. For **each type in the survey**, read matching `03-ui-specs/` (use `MANIFEST.json` `uiSpecs`) and `02-reference/question-types/` — **blocking** for `matrix`, `slider_matrix`, `file_upload`
+5. Copy `docs/templates/implementation_plan.md` → `./implementation_plan.md` and fill every section
+6. Copy `docs/templates/Question.tsx` as the dispatcher starting point
+7. **Auto-proceed to Phase 5** — do not wait for approval
 
 ### PHASE 5: BUILD
 
-Read: `00-integration/constraints.md`
+Read: `00-integration/constraints.md`, `00-integration/component-checklist.md`
+
+Create all required scale component files **before** wiring `Question.tsx`. For each question in the survey:
+
+1. Read `02-reference/question-types/{type}.md` for data shape
+2. Read `03-ui-specs/{NN}-{type}.md` (use `MANIFEST.json` `uiSpecs`; split matrix by `subType`)
+3. If `matrixFormat`, `buttonType`, or `sliderType` is present → read `03-ui-specs/shared/` specs
+4. Cross-check `02-reference/config-field-index.md` for every non-default field
+5. Implement per ui-spec — monorepo devs may consult `apps/client/src/components/`; npm installs use ui-specs only
 
-Implement components per blueprints. Use exported types:
+Implement components per blueprints + UI specs. Use exported types:
 
 ```typescript
 import { useSurveySDK, ACTIONS, type SurveyAction } from '@explorer02/cfm-survey-sdk';
@@ -85,7 +96,10 @@ Read: `00-integration/constraints.md` (troubleshooting)
 
 Checklist:
 
-- [ ] `Question.tsx` switch covers all 12 `question.type` values
+- [ ] `Question.tsx` copied from `docs/templates/Question.tsx` — covers all 12 `question.type` values
+- [ ] Matrix routes by `subType` (`CFM_MATRIX` vs `CSAT_MATRIX` / `RATING_MATRIX`)
+- [ ] All scale components from `component-checklist.md` exist for types in survey
+- [ ] **Zero stub text:** `grep -r "not yet implemented" src/ components/ app/` returns no matches
 - [ ] Every question wrapper has `id={question.id}`
 - [ ] No imports from `@explorer02/cfm-survey-sdk/src/...`
 - [ ] `SurveyPage` handles loading / error / empty / submitted / active
@@ -104,6 +118,7 @@ If yes: `npx cfm-sdk deploy` (preferred) or `npx vercel --prod --yes`
 | When | Read |
 |------|------|
 | Always first | `index.md`, `00-integration/setup.md`, `00-integration/useSurveySDK.md`, `00-integration/constraints.md` |
-| Before any React code | All `01-components/*.md` |
-| On demand | `02-reference/question-types/<type>.md` for types in survey |
+| Before any React code | All `01-components/*.md`, `00-integration/component-checklist.md`, `templates/Question.tsx` |
+| After instanceId fetch | `03-ui-specs/` per type in survey (blocking for matrix / slider_matrix / file_upload) |
+| Config audit | `02-reference/config-field-index.md` |
 | Tooling | `MANIFEST.json`, `templates/implementation_plan.md` |