@explorer02/cfm-survey-sdk 0.2.5 → 0.2.7

package/templates/docs/00-integration/wizard-customization-catalog.md

@@ -0,0 +1,391 @@
+# Wizard Customization Catalog — All Steps, Types & Formats
+
+> **Phase 5 (BUILD) — read with [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md).** This is the authoritative map of every wizard control → config path → CSS variable → component.  
+> **After client saves:** [`wizard-post-customize-build.md`](wizard-post-customize-build.md) for apply + build gate.  
+> **Source of truth in code:** `survey-wizard/src/lib/cssVars.ts` (`configToCssVars`) + `TypePanel.tsx`.
+
+Agents wire components to this catalog **before** opening the wizard so live preview updates smoothly for every picker, toggle, and format tab.
+
+---
+
+## How live preview applies changes
+
+| Layer | Mechanism | Agent responsibility |
+|-------|-----------|---------------------|
+| **CSS variables** | Wizard sends `CFM_UI_CONFIG_SNAPSHOT` / `DELTA` with `--cfm-*` on `:root` | Components use `var(--cfm-*)` — no hardcoded brand hex for wizard tokens |
+| **Content patches** | Bridge sets text on `data-cfm-*` elements | Header, Footer, Intro, End, button labels |
+| **Layout flags** | Bridge shows/hides chrome | `SurveyPage` conditionals match `global.layout.*` |
+| **DOM attributes** | `data-cfm-mcq-style`, `data-cfm-nps-button-style`, `data-cfm-dropzone-style` | Read from `:root` or survey wrapper in CSS |
+| **Preview state** | Multi-statement rows, placeholder text, heatmap pin, rank variant | Matrix scales map all `statementRows`; rank branches on `interactionMode` |
+
+**Smooth preview rule:** If a wizard control does not update the iframe, find the missing row in this catalog and add the hook — do not change `Question.tsx` dispatch.
+
+---
+
+## Wizard steps — global controls
+
+### 1. Branding & Header (`branding` → preview `header`)
+
+| Wizard control | Config path | CSS variable / DOM | Wire in |
+|----------------|-------------|-------------------|---------|
+| Survey title | `global.surveyTitle` | `data-cfm-survey-title` | Intro / SurveyPage |
+| Company name | `global.companyName` | `data-cfm-company` | `Header.tsx` brand row after logo |
+| Browser tab title | `global.browserTabTitle` | `document.title` | `layout.tsx` metadata |
+| Thank-you message | `global.thankYouMessage` | `data-cfm-thank-you` | End page |
+| Logo upload | `global.logo.fileName`, `logo.url` (preview only) | `data-cfm-logo` src | `uiConfig.getLogoSrc()` → `./fileName` |
+| Logo width / height / padding | `global.header.logoBoxWidth` etc. | `--cfm-header-logo-width`, `--cfm-header-logo-height`, `--cfm-header-logo-padding` | Header img styles |
+| Header height, padding X | `global.header.height`, `contentPaddingX` | `--cfm-header-height`, `--cfm-header-padding-x` | `.cfm-header` |
+| Logo placement templates | `global.header.logoPlacement`, `companyNamePlacement` | `--cfm-header-logo-col`, `--cfm-header-company-col`, margin vars | `headerLayoutVars` in theme CSS |
+| Header background, border | `global.header.backgroundColor`, `borderBottomColor` | `--cfm-header-bg`, `--cfm-header-border` | Header |
+| Header shadow | `global.header.shadowEnabled` | `--cfm-header-shadow` | Header |
+| Show company name | `global.header.showCompanyName` | `--cfm-header-show-company` + bridge layout flag | Header visibility |
+| Company font size/weight/color | `global.header.companyNameFontSize` etc. | `--cfm-header-company-size`, `--cfm-header-company-weight`, `--cfm-header-company-color` | `data-cfm-company` |
+| Progress track height/color/fill | `global.theme.progressTrackHeight` etc. | `--cfm-progress-height`, `--cfm-progress-track`, `--cfm-progress-fill` | `data-cfm-progress` + `.cfm-progress` |
+
+### 2. Footer (`footer` → preview `footer`)
+
+| Wizard control | Config path | CSS variable / DOM |
+|----------------|-------------|-------------------|
+| Background, text, links | `global.footer.backgroundColor`, `textColor`, `linkColor`, `linkHoverColor` | `--cfm-footer-bg`, `--cfm-footer-text`, `--cfm-footer-link`, `--cfm-footer-link-hover` |
+| Copyright | `global.footer.copyrightText` | `data-cfm-copyright` |
+| Footer links | `global.footer.links[]` | `data-cfm-footer-links` |
+| Padding X/Y | `global.footer.paddingY`, `paddingX` | `--cfm-footer-padding-y`, `--cfm-footer-padding-x` |
+| Show footer logo | `global.footer.showLogo` | layout flag + footer logo slot |
+| Footer logo size | `global.footer.logoWidth`, `logoHeight` | `--cfm-footer-logo-width`, `--cfm-footer-logo-height` |
+
+### 3. Theme & Colors (`theme` → preview `survey_page`)
+
+| Section | Config paths | CSS variables |
+|---------|--------------|---------------|
+| Brand colors | `colorScheme.primary`, `buttonText`; `theme.pageBackground`; `colorScheme.text` | `--cfm-primary`, `--cfm-button-text`, `--cfm-background`, `--cfm-text` |
+| Header colors | `header.backgroundColor`, `borderBottomColor`, `companyNameColor` | `--cfm-header-*` |
+| Progress colors | `theme.progressTrackColor`, `progressFillColor`, `progressTrackHeight` | `--cfm-progress-*` |
+| Footer colors | `footer.backgroundColor`, `textColor`, `linkColor`, `linkHoverColor` | `--cfm-footer-*` |
+| Language selector | `theme.languageSelectorBackground`, `languageSelectorTextColor` | `--cfm-language-bg`, `--cfm-language-text`, `--cfm-language-border` |
+| **Question card** | `theme.cardBackground`, `cardBorderColor`, `cardPadding`, `cardShadowEnabled` | `--cfm-card-bg`, `--cfm-card-border-color`, `--cfm-card-padding`, `--cfm-card-shadow` |
+| **Cell selected** | `theme.cellSelectedColor` | `--cfm-matrix-selected`, `--cfm-mcq-selected-accent`, `--cfm-csat-ring-color` |
+| **Focus ring** | `theme.focusRingColor` | `--cfm-input-focus-ring` |
+| Selected background | `theme.selectedBackground` | `--cfm-selected-bg`, `--cfm-mcq-selected-bg` |
+| Zebra / row band | `theme.zebraRowColor`, `rowBandColor` | `--cfm-zebra-row`, `--cfm-row-band` |
+
+**Question card tokens drive selection UI on every scale type** — radio annulus, numbered badge fill, star/emoji ring, slider thumb, carousel dots.
+
+### 4. Layout & Chrome (`layout` → preview `survey_page`)
+
+| Wizard control | Config path | Apply in |
+|----------------|-------------|----------|
+| Width (narrow/standard/wide) | `global.layout.width` | `--cfm-max-width` |
+| Corners (sharp/rounded/pill) | `global.layout.borderStyle` | `--cfm-border-radius` |
+| Font family | `global.layout.fontStyle` | `--cfm-font-family` |
+| Show header / footer / progress | `global.layout.showHeader` etc. | `SurveyPage` conditionals + bridge `layoutFlags` |
+| Show language switcher | `global.layout.showLanguageSwitcher` | `LanguageSelector` |
+| Show next / back + labels | `global.layout.showNextButton`, `buttons.next` etc. | Nav buttons + `data-cfm-btn-next` |
+| Question numbers | `global.layout.showQuestionNumbers` | `data-cfm-question-number` |
+| Required asterisk | `global.layout.showRequiredAsterisk` | `data-cfm-required` |
+| Animations | `global.motion.enabled`, `durationMs` | `--cfm-motion-duration` |
+
+### 5. Testing & Tokens (`tokens` → preview `survey_page`)
+
+| Wizard control | Config path | Wire in |
+|----------------|-------------|---------|
+| Placeholders | `placeholders.*` | `useSurveySDK({ options: { placeholders } })` |
+| Custom fields | `customFields.*` | `customFieldValues.ts` + SurveyPage |
+| Debug mode | `debug.enabled` | hook `debug: true` |
+
+### 6. Deploy & Build (`deploy`)
+
+Informational — `deploy.target`, `deploy.autoDeploy`. Phase 7 routing only; no live preview tokens.
+
+---
+
+## Question Types step — format tabs & controls
+
+The wizard lists types from `surveyTypes[]` in `survey-ui-config.json`. **Seed all types present in the fetched survey** (plus any type you want the client to style) so every relevant tab appears.
+
+**Shared toggle (matrix types):** **Preview multiple statements** — harness injects 2nd `statementRow`; components must `map` all `statementRows`.
+
+**Shared selection (all scale formats):** Theme → Question card → cell selected + focus ring. Use [`selectionStyles.ts`](../templates/selectionStyles.ts).
+
+---
+
+### MCQ — `questionTypes.MCQ`
+
+| Format tab | Preview key | Controls in panel | Component |
+|------------|-------------|-------------------|-----------|
+| Single | `MCQ_single` | Option style, gap, radius, padding | `Question.tsx` MCQ + radio |
+| Multiple | `MCQ_multiple` | Same | Checkbox variant |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `optionStyle` | `data-cfm-mcq-style` (`outlined` / `filled` / `minimal`) |
+| `optionGap` | `--cfm-mcq-option-gap` |
+| `borderRadius` | `--cfm-mcq-border-radius` |
+| `optionPadding` | `--cfm-mcq-card-padding` |
+| `hoverBorderColor` | `--cfm-mcq-hover-border` |
+| Selection | `--cfm-input-focus-ring` (border + dot), `--cfm-matrix-selected` (annulus), `--cfm-mcq-selected-bg` |
+
+---
+
+### TEXTFIELD — `questionTypes.TEXTFIELD`
+
+| Format tab | Preview key | Controls | Component |
+|------------|-------------|----------|-----------|
+| Short | `TEXTFIELD_short` | Placeholder text, radius, border, placeholder color | `Question.tsx` + `data-cfm-textfield` |
+| Long | `TEXTFIELD_long` | Same | `textarea` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `defaultPlaceholder` | placeholder text (bridge `previewState.textfieldPlaceholder`) |
+| `inputRadius` | `--cfm-input-radius` |
+| `borderColor` | `--cfm-input-border` |
+| `inputPadding`, `inputHeight` | `--cfm-input-padding`, `--cfm-input-height` |
+| `placeholderColor` | `--cfm-input-placeholder` + `[data-cfm-textfield]::placeholder` rule |
+
+---
+
+### NPS_SCALE — `questionTypes.NPS_SCALE`
+
+| Format tab | Preview key | Controls | Component |
+|------------|-------------|----------|-----------|
+| NPS | `NPS_SCALE` | Button style, track colors, hint labels, number labels | `RatingScale.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `buttonStyle` | `data-cfm-nps-button-style` (`standard` / `numbered` / `pill`) |
+| `selectedFill`, `trackBarColor`, `trackHighlightColor` | `--cfm-nps-selected-fill`, `--cfm-nps-track-bar`, `--cfm-nps-track-highlight` |
+| `cellSize`, `cellGap` | `--cfm-nps-cell-size`, `--cfm-nps-cell-gap` |
+| `hintMinText`, `hintMaxText`, hint colors | `hintLabelStyle()` → `--cfm-hint-label-*` |
+| `numberLabelMode`, mono/individual colors | `--cfm-number-*`; unselected via `resolveNumberLabelColor()` |
+| Selection | `scaleRadioRingStyle`, `scaleRadioDotStyle` |
+
+---
+
+### CFM_MATRIX — `questionTypes.CFM_MATRIX`
+
+| Format tab | Preview key | Controls | Component |
+|------------|-------------|----------|-----------|
+| Likert | `CFM_likert` | Row width, bipolar %, label items | `LikertMatrixScale.tsx` |
+| Bipolar | `CFM_bipolar` | Same | Bipolar anchor column |
+| *(harness only)* Transpose | `CFM_transpose` | Same config block | Matrix transpose branch |
+| *(harness only)* Carousel | `CFM_carousel` | Same | Carousel dots = cell selected |
+| *(harness only)* Dropdown | `CFM_dropdown` | Same | `MatrixDropdown.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `rowLabelWidth` | `--cfm-matrix-row-width` |
+| `bipolarColumnWidthPercent` | `--cfm-matrix-bipolar-width` |
+| `cellPadding` | `--cfm-matrix-cell-padding` |
+| `columnLabelColor`, `columnLabelBgColor` | `matrixColumnLabelStyle()` |
+| Selection | `matrixRadioRingStyle`, `matrixRadioDotStyle` |
+
+**No** per-format accent overrides — Question card tokens only.
+
+---
+
+### CSAT_MATRIX — `questionTypes.CSAT_MATRIX`
+
+| Format tab | Preview key | Controls shown | Component |
+|------------|-------------|----------------|-----------|
+| Emoji | `CSAT_emoji` | Emoji size, unselected opacity, label items | `CsatMatrixScale.tsx` emoji |
+| Star | `CSAT_star` | Unselected opacity, label items | Star row |
+| Numbered | `CSAT_numbered` | Opacity, label items, **number labels** | Number badges |
+| Graphics | `CSAT_graphics` | Label items only | `CustomSliderTrack.tsx` per row |
+| Carousel | `CSAT_carousel` | Label items | Dot indicators |
+| Dropdown | `CSAT_dropdown` | Label items | `MatrixDropdown.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `emojiSize` | `--cfm-csat-emoji-size` |
+| `unselectedOpacity` | `--cfm-csat-unselected-opacity` |
+| `cellSize`, `tooltipBg`, `rowLabelWidth` | `--cfm-csat-cell-size`, `--cfm-csat-tooltip-bg`, `--cfm-matrix-row-width` |
+| Label items | `csatColumnLabelStyle()` → `--cfm-csat-column-label-*` |
+| Number labels (numbered tab) | `--cfm-number-*` |
+| Selection | theme cell selected + focus ring |
+
+---
+
+### RATING_MATRIX — `questionTypes.RATING_MATRIX`
+
+| Format tab | Preview key | Controls shown | Component |
+|------------|-------------|----------------|-----------|
+| Star | `RATING_star` | Unselected opacity, label items | `CsatMatrixScale.tsx` (shared) |
+| Numbered | `RATING_numbered` | Opacity, label items, number labels | Number badges |
+| Radio | `RATING_radio` | Opacity, label items | **Horizontal** radio grid |
+| Emoji | `RATING_emoji` | Emoji size, opacity, label items | Emoji cells |
+| Graphics | `RATING_graphics` | Opacity, label items | `CustomSliderTrack` |
+| Slider | `RATING_slider` | Label items | Slider thumb pattern |
+
+Uses `unselectedStarOpacity` in JSON (maps to `--cfm-csat-unselected-opacity`). Same label/number patterns as CSAT.
+
+---
+
+### SLIDER_MATRIX — `questionTypes.SLIDER_MATRIX`
+
+| Format tab | Preview key | Controls | Component |
+|------------|-------------|----------|-----------|
+| Slider | `SLIDER_matrix` | Track, thumb, tick, row width, tick label items, tick number labels | `SliderMatrixScale.tsx`, `CustomSliderTrack.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `trackColor`, `thumbColor`, `tickColor` | `--cfm-slider-track`, `--cfm-slider-thumb`, `--cfm-slider-tick` |
+| `rowLabelWidth` | `--cfm-matrix-row-width` |
+| `rowBandColor` | `--cfm-slider-row-band` |
+| `tickBadgeSize` | `--cfm-slider-tick-size` |
+| Tick label items | `sliderTickLabelStyle()` |
+| Tick number labels | `--cfm-number-*` |
+| Thumb selection | focus ring border + cell selected annulus + center dot |
+
+---
+
+### FILE_UPLOAD — `questionTypes.FILE_UPLOAD`
+
+| Format tab | Preview key | Controls | Component |
+|------------|-------------|----------|-----------|
+| Upload | `FILE_UPLOAD` | Border style, border color, fill, padding | `FileUploadScale.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `dropzoneStyle` | `data-cfm-dropzone-style` (`dashed` / `solid`) |
+| `borderColor` | `--cfm-upload-border-color` |
+| `dropzoneFillColor`, `dropzonePadding` | `--cfm-upload-fill`, `--cfm-upload-padding` |
+| Focus / drag-active | `--cfm-input-focus-ring`, `--cfm-mcq-selected-bg` |
+
+---
+
+### HEATMAP — `questionTypes.HEATMAP`
+
+| Format tab | Preview key | Controls | Component |
+|------------|-------------|----------|-----------|
+| Heatmap | `HEATMAP` | Pin color, border, size | `HeatmapScale.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `pinColor` | `--cfm-heatmap-pin` |
+| `pinBorderColor` | `--cfm-heatmap-pin-border` |
+| `pinSize` | `--cfm-heatmap-pin-size` |
+| `overlayOpacity` | `--cfm-heatmap-overlay-opacity` |
+
+Click preview image to place pin — bridge sends `heatmapPreviewPin`.
+
+---
+
+### RANK_ORDER — `questionTypes.RANK_ORDER`
+
+| Format tab | Preview key | Controls | Component |
+|------------|-------------|----------|-----------|
+| Drag | `RANK_drag` | Item bg, handle, badge | `RankOrderScale.tsx` + `@dnd-kit` |
+| Dropdown | `RANK_dropdown` | Item bg, select border, badge | Dropdown rank UI |
+
+| Config path | CSS var |
+|-------------|---------|
+| `drag.itemBg` / `dropdown.itemBg` | `--cfm-rank-item-bg` |
+| `drag.dragHandleColor` | `--cfm-rank-handle` |
+| `drag.rankBadgeColor` / `dropdown.rankBadgeColor` | `--cfm-rank-badge` |
+| `drag.itemPadding`, `itemGap` | `--cfm-rank-item-padding`, `--cfm-rank-item-gap` |
+| `dropdown.selectBorderColor` | `--cfm-rank-select-border` |
+
+Bridge sets `rankVariant` from active preview key — do not change answer shapes.
+
+---
+
+### TEXT_AND_MEDIA — `questionTypes.TEXT_AND_MEDIA`
+
+| Preview key | Wizard step | Tokens |
+|-------------|-------------|--------|
+| `TEXT_AND_MEDIA` | Theme (media section in defaults) | `--cfm-media-max-width`, `--cfm-media-radius`, `--cfm-media-caption-color`, `--cfm-media-caption-size` |
+
+No Question Types panel — wire in `Question.tsx` TEXT_AND_MEDIA branch.
+
+---
+
+## Complete preview key index (27 pages)
+
+| Preview key | Wizard step | Notes |
+|-------------|-------------|-------|
+| `header` | Branding | Logo + company |
+| `footer` | Footer | Links + copyright |
+| `survey_page` | Theme, Layout, Tokens | Full chrome |
+| `intro` | — | `data-cfm-survey-title` |
+| `end` | — | `data-cfm-thank-you` |
+| `MCQ_single` / `MCQ_multiple` | Question Types | MCQ |
+| `TEXTFIELD_short` / `TEXTFIELD_long` | Question Types | Text |
+| `NPS_SCALE` | Question Types | NPS |
+| `CFM_likert` / `CFM_bipolar` | Question Types | CFM wizard tabs |
+| `CFM_transpose` / `CFM_carousel` / `CFM_dropdown` | — | Harness; same `CFM_MATRIX` config |
+| `CSAT_emoji` … `CSAT_dropdown` | Question Types | 6 CSAT formats |
+| `RATING_star` … `RATING_slider` | Question Types | 6 Rating formats |
+| `SLIDER_matrix` | Question Types | Slider matrix |
+| `FILE_UPLOAD` | Question Types | Upload |
+| `HEATMAP` | Question Types | Heatmap |
+| `RANK_drag` / `RANK_dropdown` | Question Types | Rank |
+| `TEXT_AND_MEDIA` | Theme vars | Media block |
+
+---
+
+## Phase 5 — smooth wiring order
+
+Do this **once** before `npx cfm-sdk customize` so every catalog row works in live preview:
+
+```bash
+# 1. Chrome + bridge (wizard-chrome-contract.md)
+cp templates/docs/templates/Header.tsx Footer.tsx ProgressBar.tsx SurveyStickyChrome.tsx \
+   LanguageSelector.tsx PreviewBridgeInit.tsx uiConfig.ts → src/
+cp templates/previewBridge.ts src/lib/
+cp templates/survey-theme.css src/styles/
+
+# 2. Selection + label helpers
+cp templates/docs/templates/selectionStyles.ts labelStyles.ts → src/lib/surveyUi/
+
+# 3. Scale components per survey inventory (+ shared primitives)
+# RatingScale, LikertMatrixScale, CsatMatrixScale, SliderMatrixScale,
+# FileUploadScale, HeatmapScale, RankOrderScale, MatrixDropdown, CustomSliderTrack
+
+# 4. Seed config with all survey types
+# survey-ui-config.json → surveyTypes: [every type from fetched survey]
+
+# 5. Export previews from real components
+npx cfm-sdk export-previews
+
+# 6. Verify
+bash templates/verify-agent-build.sh
+```
+
+**Per-format checklist** while wiring each scale:
+
+1. Every wizard-exposed token uses `var(--cfm-*)` from this catalog
+2. Radio/scale cells use `selectionStyles.ts` (focus ring + cell selected)
+3. Matrix column headers use `labelStyles.ts` (label items — not hint labels on CFM)
+4. NPS/numbered unselected badges use `resolveNumberLabelColor()` only when unselected
+5. Question wrapper uses `var(--cfm-card-*)` on `.cfm-question-card`
+6. `data-cfm-question-number` + `data-cfm-required` on question shell
+
+---
+
+## Symptom → catalog lookup
+
+| Preview does not update when client changes… | Check catalog section |
+|---------------------------------------------|----------------------|
+| Logo / company | Branding & Header |
+| Progress bar (separate from header) | `data-cfm-progress` — not on sticky wrapper |
+| Question card padding/shadow | Theme → Question card + `.cfm-question-card` |
+| MCQ option spacing | MCQ → `--cfm-mcq-*` |
+| NPS number badge colors | NPS → `--cfm-number-*` + `resolveNumberLabelColor` |
+| Matrix 2nd row | CFM/CSAT/Rating/Slider + multi-statement toggle |
+| CSAT emoji size | CSAT emoji → `--cfm-csat-emoji-size` |
+| Slider thumb colors | SLIDER_MATRIX + `CustomSliderTrack` |
+| Dropzone border | FILE_UPLOAD → `--cfm-upload-border-color` |
+| Rank handle color | RANK drag → `--cfm-rank-handle` |
+
+Full symptom table: [`wizard-chrome-contract.md`](wizard-chrome-contract.md).
+
+---
+
+## Related
+
+| Doc | Role |
+|-----|------|
+| [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) | export-previews + bridge protocol |
+| [`wizard-question-type-styling.md`](wizard-question-type-styling.md) | Selection patterns + code snippets |
+| [`wizard-post-customize-build.md`](wizard-post-customize-build.md) | After save — apply + build |
+| [`apply-ui-config.md`](apply-ui-config.md) | Config path → CSS tables |
+| [`03-ui-specs/README.md`](../03-ui-specs/README.md) | Per-type layout anatomy |