@explorer02/cfm-survey-sdk 0.1.4 → 0.1.6

package/templates/docs/03-client-components/11-progress-bar.md

@@ -0,0 +1,31 @@
+# Progress Bar
+
+> **Component**: `ProgressBar`
+> **Role**: Displays completion status at the top of the survey.
+
+## Props Interface
+```typescript
+type ProgressBarProps = {
+  progressPercentage: number; // 0 to 100
+};
+```
+
+## Implementation
+
+```tsx
+export default function ProgressBar({ progressPercentage }: ProgressBarProps) {
+  // Ensure it's bounded between 0 and 100
+  const width = Math.min(100, Math.max(0, progressPercentage));
+
+  return (
+    <div className="mb-8 h-2 w-full overflow-hidden rounded-full bg-gray-100">
+      <div
+        className="h-full bg-[#e20074] transition-all duration-500 ease-out"
+        style={{ width: `${width}%` }}
+      />
+    </div>
+  );
+}
+```
+
+The `progressPercentage` value is provided directly by `state.progressPercentage` from the `useSurveySDK` hook.

package/templates/docs/03-client-components/12-language-selector.md

@@ -0,0 +1,41 @@
+# Language Selector
+
+> **Component**: `LanguageSelector`
+> **Role**: Allows the user to switch the survey language.
+
+## Props Interface
+```typescript
+type LanguageSelectorProps = {
+  languages: SurveyLanguage[];
+  selectedLanguage: string;
+  onChange: (code: string) => void;
+};
+```
+
+## Implementation
+
+Only render the selector if there is more than 1 language available.
+
+```tsx
+export default function LanguageSelector({ languages, selectedLanguage, onChange }: LanguageSelectorProps) {
+  if (!languages || languages.length <= 1) return null;
+
+  return (
+    <div className="mb-6 flex justify-end">
+      <select
+        value={selectedLanguage}
+        onChange={e => onChange(e.target.value)}
+        className="rounded-md border border-gray-300 py-1.5 pl-3 pr-8 text-sm focus:border-[#e20074] focus:ring-1 focus:ring-[#e20074]"
+      >
+        {languages.map(lang => (
+          <option key={lang.code} value={lang.code}>
+            {lang.name}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+}
+```
+
+When `onChange` fires, it updates state in `SurveyPage.tsx`, which triggers the SDK to re-map the translations.

package/templates/docs/03-client-components/13-matrix-dropdown.md

@@ -0,0 +1,42 @@
+# Matrix Dropdown
+
+> **Component**: `MatrixDropdown`
+> **Used by**: `CsatMatrixScale`, `LikertMatrixScale`
+
+## Role
+Renders a dropdown selector for a single row in a matrix question. Used when `matrixFormat === 'dropdown'` or `buttonType === 'dropdown'`.
+
+## Props Interface
+```typescript
+type MatrixDropdownProps = {
+  columns: MatrixColumn[];
+  selectedValue: string | number | null | undefined;
+  onChange: (value: string | number | null) => void;
+  placeholder?: string;
+};
+```
+
+## Structure
+Renders a native HTML `<select>` element.
+
+```tsx
+<select
+  value={selectedValue === null ? '' : String(selectedValue ?? '')}
+  onChange={e => {
+    const val = e.target.value;
+    if (val === '') onChange(null); // Map empty string back to null for N/A
+    else {
+      // Find original option to keep type (number vs string) intact
+      const opt = columns.find(c => String(c.value) === val);
+      onChange(opt ? opt.value : val);
+    }
+  }}
+>
+  <option value="" disabled>Select an option...</option>
+  {columns.map(col => (
+    <option key={String(col.value)} value={String(col.value)}>
+      {col.label}
+    </option>
+  ))}
+</select>
+```

package/templates/docs/03-client-components/README.md

@@ -0,0 +1,63 @@
+# Client Components Overview
+
+> This folder documents the React client components that render the survey UI.
+> It explains the architecture, the dispatcher (`Question.tsx`), and all 11 individual question scale components.
+
+## Component Architecture
+
+The UI is driven by a single top-level `SurveyPage` component which iterates over the `currentQuestions` array and passes each `SurveyQuestion` object to the `Question` dispatcher component.
+
+```
+SurveyPage (Top-level orchestrator)
+   │
+   ├── Header (Branding/Logo)
+   ├── ProgressBar
+   ├── LanguageSelector
+   ├── Footer
+   │
+   └── Question (Dispatcher, mapped over `currentQuestions`)
+         │
+         ├── RatingScale (handles 'rating' and 'rating_scale')
+         ├── CsatScale (handles 'csat')
+         ├── LikertMatrixScale (handles 'matrix' CFM_MATRIX)
+         ├── CsatMatrixScale (handles 'matrix' CSAT_MATRIX / 'rating_matrix')
+         ├── SliderMatrixScale (handles 'slider_matrix')
+         ├── FileUploadScale (handles 'file_upload')
+         │
+         ├── (Inline UI for 'radio', 'text', 'text_and_media')
+         │
+         └── Shared Sub-Components:
+               ├── CustomSliderTrack (used by csat/matrix sliders)
+               └── MatrixDropdown (used by matrix dropdowns)
+```
+
+## Styling Approach
+
+- Built entirely with **Tailwind CSS**.
+- **No external UI libraries** (no Material UI, Chakra, etc.).
+- The default brand colour is Telekom Magenta: `#e20074`.
+- The UI follows a strict, clean, modern corporate aesthetic (card-based layout, subtle borders, pink accents on selection).
+
+## The `Question` Dispatcher
+
+The `Question` component (`apps/client/src/components/Question.tsx`) is the heart of the rendering engine. It receives a `SurveyQuestion` union type and switches on `question.type` (and `question.subType` for matrices) to render the correct specialized scale component.
+
+See `02-question.md` for details on the dispatcher logic.
+
+## Files in This Folder
+
+| File | Component |
+|------|-----------|
+| `01-survey-page.md` | `SurveyPage` orchestrator |
+| `02-question.md` | `Question` dispatcher & inline types |
+| `03-rating-scale.md` | `RatingScale` (NPS/Stars) |
+| `04-csat-scale.md` | `CsatScale` (Emoji/Star CSAT) |
+| `05-csat-matrix-scale.md` | `CsatMatrixScale` (Satisfaction Grid) |
+| `06-likert-matrix-scale.md` | `LikertMatrixScale` (Text Grid) |
+| `07-slider-matrix-scale.md` | `SliderMatrixScale` (Sliders Grid) |
+| `08-file-upload-scale.md` | `FileUploadScale` |
+| `09-custom-slider-track.md` | `CustomSliderTrack` (Emoji thumbs) |
+| `10-header-footer.md` | `Header` & `Footer` |
+| `11-progress-bar.md` | `ProgressBar` |
+| `12-language-selector.md` | `LanguageSelector` |
+| `13-matrix-dropdown.md` | `MatrixDropdown` |

package/templates/docs/04-critical-rules/01-import-rules.md

@@ -0,0 +1,51 @@
+# Import Rules & Setup
+
+> Non-negotiable constraints for setting up Next.js with `@explorer02/cfm-survey-sdk`.
+
+## 1. Top-Level Imports ONLY
+
+You must import from the root package name.
+
+```tsx
+// ✅ REQUIRED
+import { useSurveySDK, getEmojiForIndex } from '@explorer02/cfm-survey-sdk';
+
+// ❌ FORBIDDEN (Will fail Next.js build)
+import { useSurveySDK } from '@explorer02/cfm-survey-sdk/src/fetchSurvey/useFetchSurvey';
+```
+
+## 2. Peer Dependencies
+
+The SDK requires `@tanstack/react-query` to be installed in the client project:
+
+```bash
+npm install @explorer02/cfm-survey-sdk @tanstack/react-query
+```
+
+## 3. Client Components Only
+
+Because the SDK uses React state, `useQuery`, and DOM interactions, the `SurveyPage` must be a client component.
+
+```tsx
+'use client';
+
+import { useSurveySDK } from '@explorer02/cfm-survey-sdk';
+```
+
+## 4. Next.js Configuration
+
+**CRITICAL**: You must configure `next.config.js` to transpile the SDK, because the SDK exports modern ES modules and uses CSS that Next.js needs to process.
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['@explorer02/cfm-survey-sdk'],
+};
+
+module.exports = nextConfig;
+```
+If you forget this, you will get `"SyntaxError: Cannot use import statement outside a module"`.
+
+## 5. React 18 / StrictMode
+
+Next.js `reactStrictMode: true` causes effects to fire twice in development. The SDK is built to handle this safely (e.g., query caching), but be aware of double-logging if `debug: true` is enabled.

package/templates/docs/04-critical-rules/02-action-dispatching.md

@@ -0,0 +1,56 @@
+# Action Dispatching Rule
+
+> The single flow of data mutation in the SDK.
+
+## The Rule
+
+You must NEVER try to update the `state` object directly. The `state` returned by `useSurveySDK` is deeply immutable.
+
+All state mutations (answering a question, navigating pages, submitting) must be done through the `onAction` dispatcher function provided by the hook.
+
+## The `onAction` Function
+
+```typescript
+const { onAction } = useSurveySDK({ ... });
+```
+
+### Action Types
+
+#### 1. Answering a Question
+```tsx
+// Standard (number/string)
+onAction({ 
+  type: 'CHANGE', 
+  payload: { questionId: 'q123', value: 4 } 
+});
+
+// Matrix (MatrixAnswerMap)
+onAction({ 
+  type: 'CHANGE', 
+  payload: { questionId: 'q456', value: { row1: 5, row2: 2 } } 
+});
+```
+
+#### 2. Next Page
+```tsx
+// Automatically triggers validation. If on the last page, auto-converts to SUBMIT.
+onAction({ type: 'NEXT' });
+```
+
+#### 3. Previous Page
+```tsx
+onAction({ type: 'PREVIOUS' });
+```
+
+#### 4. Force Submit
+```tsx
+// Validates ALL pages, then triggers API request.
+onAction({ type: 'SUBMIT' });
+```
+
+## Why This Matters
+The `onAction` dispatcher internally handles:
+- Clearing validation errors the moment a user answers
+- Tracking analytics (timestamps, backtrack counts)
+- Preserving scroll position
+- Triggering cross-question logic

package/templates/docs/04-critical-rules/03-scroll-navigation.md

@@ -0,0 +1,37 @@
+# Scroll Navigation Rule
+
+> The DOM requirement for validation error scrolling to function.
+
+## The Rule
+
+When rendering the wrapper for ANY question, the outermost DOM element (usually a `<section>` or `<div>`) **MUST** have its `id` attribute set to `question.id`.
+
+```tsx
+// ✅ REQUIRED
+export default function Question({ question, ... }) {
+  return (
+    <section id={question.id} className="p-6 bg-white rounded-xl">
+      <h2>{question.text}</h2>
+      {/* ... */}
+    </section>
+  );
+}
+
+// ❌ FORBIDDEN
+export default function Question({ question, ... }) {
+  return (
+    <section className="p-6 bg-white rounded-xl">
+      <h2 id={question.id}>{question.text}</h2>  {/* Wrong element */}
+      {/* ... */}
+    </section>
+  );
+}
+```
+
+## Why This Matters
+
+When the user clicks "Next" or "Submit", the SDK validates the fields. If it finds a required field is empty, it does two things:
+1. Sets `validationErrors[questionId]`
+2. Calls `document.getElementById(questionId).scrollIntoView()`
+
+If the ID is missing from the DOM, the error message will appear, but the page will not scroll to the error, resulting in a broken User Experience (especially on long pages).

package/templates/docs/04-critical-rules/04-logo-branding.md

@@ -0,0 +1,42 @@
+# Logo and Branding Rule
+
+> How to handle logos and branding without breaking the build or deployment.
+
+## The Rule
+
+You must **NEVER** use `<img>` tags pointing to external URLs (e.g., Telekom or Sprinklr servers) for the main brand logo.
+
+You must **NEVER** attempt to download image files, save them to the `public/` folder, and reference them.
+
+You MUST construct the logo purely using **Tailwind CSS**.
+
+## Example: Telekom "T" Logo (Abstracted)
+
+Instead of finding the exact Telekom logo, build a clean, recognizable abstract representation using geometric divs:
+
+```tsx
+{/* Abstract Magenta "T" equivalent */}
+<div className="flex items-center gap-2">
+  <div className="flex h-8 w-8 items-center justify-center rounded-sm bg-[#e20074]">
+    <div className="flex flex-col items-center">
+      <div className="h-1 w-4 bg-white" />
+      <div className="h-3 w-1 bg-white" />
+    </div>
+  </div>
+  <span className="font-bold text-gray-900 tracking-tight">Telekom</span>
+</div>
+```
+
+## Example: Generic Circular Logo
+
+```tsx
+<div className="flex items-center gap-3">
+  <div className="h-8 w-8 rounded-full bg-gradient-to-tr from-blue-600 to-indigo-500" />
+  <span className="text-xl font-bold tracking-tight text-gray-900">BrandName</span>
+</div>
+```
+
+## Why This Matters
+1. **Broken Links**: External image URLs often change, expire, or return 403 Forbidden when accessed from a Vercel deployment domain.
+2. **File System Issues**: Downloading assets to `public/` during an automated AI build process often fails due to permissions, path resolution, or missing dependencies.
+3. **Performance**: CSS-only logos render instantly and scale perfectly without network requests.

package/templates/docs/04-critical-rules/05-troubleshooting.md

@@ -0,0 +1,46 @@
+# Troubleshooting & Common Errors
+
+> Solutions for common issues encountered while building with the SDK.
+
+## 1. "Cannot use import statement outside a module"
+**Symptom**: Next.js build fails immediately on start.
+**Cause**: Next.js is not transpiling the SDK package.
+**Fix**: Add the package to `transpilePackages` in `next.config.js`:
+```javascript
+const nextConfig = {
+  transpilePackages: ['@explorer02/cfm-survey-sdk'],
+};
+```
+
+## 2. Infinite Re-renders / Re-fetching
+**Symptom**: The browser freezes or the network tab shows hundreds of API requests to the survey endpoint.
+**Cause**: Passing a new object reference to `options.placeholders` on every render.
+**Fix**: Extract the placeholders object outside the component:
+```tsx
+// OUTSIDE the component
+const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'John' };
+
+export default function SurveyPage() {
+  const { ... } = useSurveySDK({ options: { placeholders: SURVEY_PLACEHOLDERS } });
+}
+```
+
+## 3. "window is not defined" or "document is not defined"
+**Symptom**: Next.js SSR crashes with DOM errors.
+**Cause**: A component using the SDK is missing the `'use client'` directive. The SDK relies on browser APIs.
+**Fix**: Add `'use client';` to the very top of `SurveyPage.tsx` and any file importing the SDK.
+
+## 4. Clicking "Next" shows errors but doesn't scroll
+**Symptom**: Required field validation fails, text appears, but the viewport doesn't move.
+**Cause**: The DOM wrapper for the question is missing the `id` attribute.
+**Fix**: Ensure `<section id={question.id}>` is present on the outermost element of every question card.
+
+## 5. Survey renders completely empty
+**Symptom**: `surveyQueryResults.data` is `null`, but there's no error.
+**Cause**: The provided `instanceId` is empty, malformed, or has expired/been deleted on the server.
+**Fix**: Verify the `instanceId` JWT token. Ask the client to provide a fresh one.
+
+## 6. Icons/Emojis are missing or look broken
+**Symptom**: CSAT scales show empty boxes instead of faces.
+**Cause**: Missing peer dependencies.
+**Fix**: Ensure `react-icons` is installed in the client project: `npm install react-icons`.

package/templates/docs/04-critical-rules/README.md

@@ -0,0 +1,29 @@
+# Critical Operating Rules
+
+> This folder contains the absolute, non-negotiable constraints you MUST follow when building a survey using `@explorer02/cfm-survey-sdk`.
+
+## Files in This Folder
+
+| File | Topic | Importance |
+|------|-------|------------|
+| `01-import-rules.md` | Imports and Next.js setup | **CRITICAL** (Build breaks without it) |
+| `02-action-dispatching.md` | `onAction` pattern | **CRITICAL** (State breaks without it) |
+| `03-scroll-navigation.md` | `id={question.id}` rule | **CRITICAL** (Validation UX breaks) |
+| `04-logo-branding.md` | CSS-only logo mandate | **CRITICAL** (Deployment breaks) |
+| `05-troubleshooting.md` | Common errors & fixes | Useful reference |
+
+## The Golden Rule
+
+**You are building a client application using a pre-compiled npm package.**
+
+You are STRICTLY PROHIBITED from trying to modify, monkey-patch, or import internal files from inside `node_modules/@explorer02/cfm-survey-sdk`. 
+
+Everything you need is exported from the top-level barrel file.
+
+```typescript
+// ✅ CORRECT
+import { useSurveySDK, type SurveyQuestion } from '@explorer02/cfm-survey-sdk';
+
+// ❌ WRONG — Build will fail immediately
+import { mapQuestion } from '@explorer02/cfm-survey-sdk/src/fetchSurvey/utils';
+```

package/templates/docs/index.md

@@ -0,0 +1,129 @@
+# CFM SURVEY SDK — AGENT DOCUMENTATION INDEX
+
+**@explorer02/cfm-survey-sdk**
+
+This file is the MASTER GUIDE for AI coding agents (Cursor, Copilot, etc.).
+It is a structured roadmap that tells the agent exactly which documentation files to read and in what order.
+
+## ── HOW THIS DOCUMENTATION SYSTEM WORKS ──────────────────────────────────────
+
+The `docs/` folder mirrors the SDK's internal architecture:
+
+```
+docs/
+├── index.md                    ← YOU ARE HERE — read this first
+├── 01-sdk-core/                ← SDK internals: fetch, map, paginate, validate, submit
+├── 02-question-types/          ← One doc per question type (12 types)
+├── 03-client-components/       ← One doc per UI component (13 components)
+└── 04-critical-rules/          ← Non-negotiable constraints, imports, troubleshooting
+```
+
+## ── CLIENT INTERACTION FLOW (3 INPUTS ONLY) ──────────────────────────────────
+
+The entire build process requires EXACTLY 3 inputs from the client:
+
+**INPUT 1: Client's initial prompt**
+→ "Build a survey like this image using @explorer02/cfm-survey-sdk"
+→ May include UI mockup screenshots, brand colors, or text description
+→ Agent begins project scaffolding and component architecture
+
+**INPUT 2: Instance ID (agent asks for it)**
+→ Agent asks: "Please provide your survey instance ID (JWT token)"
+→ Client pastes the instanceId string
+→ Agent wires it into SurveyPage.tsx and fetches the survey
+
+**INPUT 3: Deployment confirmation (agent asks at the end)**
+→ Agent asks: "Your survey is built and tested. Ready to deploy to Vercel?"
+→ Client confirms → Agent runs `npx vercel --prod --yes`
+
+## ── EXECUTION PIPELINE ───────────────────────────────────────────────────────
+
+Follow these phases IN ORDER. Each phase references specific doc files.
+
+### PHASE 1: PROJECT SCAFFOLDING
+Read: `04-critical-rules/01-import-rules.md`
+
+Actions:
+1. Create Next.js project:
+   `npx -y create-next-app@latest ./ --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm`
+2. Install SDK:
+   `npm install @explorer02/cfm-survey-sdk @tanstack/react-query`
+3. Configure `next.config.js`:
+   `transpilePackages: ["@explorer02/cfm-survey-sdk"]`
+
+### PHASE 2: ASK FOR INSTANCE ID (INPUT 2)
+Read: `01-sdk-core/01-fetch-survey.md`
+
+Ask the client in chat:
+"Please provide your survey instance ID (the JWT token string) so I can connect your survey."
+
+Wait for the client to paste the instanceId. Store it — you will wire it into SurveyPage.tsx in Phase 4.
+
+### PHASE 3: UNDERSTAND THE SDK PIPELINE
+Read these docs IN ORDER to understand how the SDK works:
+
+1. `01-sdk-core/01-fetch-survey.md`    — How survey data is fetched
+2. `01-sdk-core/02-survey-mapper.md`   — How raw API → Survey object
+3. `01-sdk-core/03-question-mappers.md` — How questions are typed/mapped
+4. `01-sdk-core/07-language-handling.md` — Translations & placeholders
+5. `01-sdk-core/04-pagination.md`      — Page navigation state
+6. `01-sdk-core/05-validation.md`      — Required field validation
+7. `01-sdk-core/06-submit-survey.md`   — Response submission format
+8. `01-sdk-core/08-icons-and-emojis.md` — CSAT emoji/star icon system
+
+Then understand what question types exist:
+9. `02-question-types/README.md`       — Overview of all 12 types
+
+*You do NOT need to read every question type doc upfront. Read them ON DEMAND when you encounter each type during component building.*
+
+### PHASE 4: BUILD THE SURVEY UI
+Read these component docs IN ORDER:
+
+1. `03-client-components/README.md`        — File structure overview
+2. `03-client-components/01-survey-page.md` — MAIN orchestrator (REQUIRED)
+3. `03-client-components/02-question.md`    — Question dispatcher (REQUIRED)
+4. `03-client-components/10-header-footer.md` — CSS-built logo/branding
+5. `03-client-components/11-progress-bar.md`  — Progress indicator
+6. `03-client-components/12-language-selector.md` — Language dropdown
+
+Then for EACH question type present in the fetched survey, read the matching question-type doc AND component doc:
+
+| `question.type` | Question Doc | Component Doc |
+|---|---|---|
+| `'rating'` | `02-question-types/01-rating` | `03-components/03-rating` |
+| `'radio'` | `02-question-types/02-radio` | (inline in Question) |
+| `'text'` | `02-question-types/03-text` | (inline in Question) |
+| `'csat'` | `02-question-types/04-csat` | `03-components/04-csat` |
+| `'rating_scale'` | `02-question-types/05-rating-s` | `03-components/03-rating` |
+| `'slider'` | `02-question-types/06-slider` | `03-components/09-slider` |
+| `'matrix'` CFM | `02-question-types/07-matrix-c` | `03-components/06-likert` |
+| `'matrix'` CSAT | `02-question-types/08-matrix-c` | `03-components/05-csat-m` |
+| `'matrix'` RATING| `02-question-types/09-matrix-r` | `03-components/05-csat-m` |
+| `'slider_matrix'`| `02-question-types/10-slider-m` | `03-components/07-slider` |
+| `'file_upload'` | `02-question-types/11-file-up` | `03-components/08-file` |
+| `'text_and_media'`| `02-question-types/12-text-med` | (inline in Question) |
+
+Also read these shared component docs:
+- `03-client-components/09-custom-slider-track.md` (used by CSAT matrix, slider matrix when sliderType='graphics')
+- `03-client-components/13-matrix-dropdown.md` (used by matrix dropdown fmt)
+
+### PHASE 5: APPLY CRITICAL RULES
+Read ALL files in `04-critical-rules/`:
+1. `01-import-rules.md`       — Package imports, 'use client', Suspense
+2. `02-action-dispatching.md` — onAction pattern, placeholder constants
+3. `03-scroll-navigation.md`  — id={question.id} requirement
+4. `04-logo-branding.md`      — CSS-only logo, no external image needed
+5. `05-troubleshooting.md`    — Common build errors and fixes
+
+Verify your implementation against every rule before proceeding.
+
+### PHASE 6: BUILD VERIFICATION
+1. Run: `npm run build`
+2. If errors → fix automatically → re-run until clean
+3. Run: `npm run dev`
+4. Verify: survey loads, navigation works, validation fires, submit works
+
+### PHASE 7: DEPLOYMENT (INPUT 3)
+Ask the client: "Your survey is built and verified. Ready to deploy to Vercel?"
+If yes → run: `npx vercel --prod --yes`
+Report the final deployment URL to the client.