@explorer02/cfm-survey-sdk 0.1.8 → 0.1.9

package/templates/docs/01-sdk-core/README.md

@@ -1,53 +0,0 @@
-# SDK Core Architecture
-
-> This folder documents the internal architecture of `@explorer02/cfm-survey-sdk`.
-> Read these files **in order** to understand how the SDK processes a survey from network fetch to user submission.
-
-## Pipeline Overview
-
-```
-┌─────────────┐     ┌──────────────┐     ┌──────────────────┐     ┌─────────────┐
-│  Fetch API  │ ──→ │  Map Survey  │ ──→ │  Map Questions   │ ──→ │  Paginate   │
-│  (network)  │     │  (language)  │     │  (per-type)      │     │  (pages)    │
-└─────────────┘     └──────────────┘     └──────────────────┘     └─────────────┘
-                                                                        │
-                                                                        ▼
-┌─────────────┐     ┌──────────────┐     ┌──────────────────┐     ┌─────────────┐
-│  Submit     │ ←── │  Format Body │ ←── │  Validate        │ ←── │  Render UI  │
-│  (network)  │     │  (payload)   │     │  (required)      │     │  (React)    │
-└─────────────┘     └──────────────┘     └──────────────────┘     └─────────────┘
-```
-
-## Files in This Folder
-
-| File | Topic | When to Read |
-|------|-------|-------------|
-| `01-fetch-survey.md` | Network fetching, API endpoint, instanceId | **Always** — first step |
-| `02-survey-mapper.md` | Raw API → Survey object transformation | **Always** — understand data shape |
-| `03-question-mappers.md` | Question type dispatch, normalizeType | **Always** — core routing logic |
-| `04-pagination.md` | Page navigation, currentPageIndex | **Always** — state management |
-| `05-validation.md` | Required field validation, scroll-to-error | **Always** — UX critical |
-| `06-submit-survey.md` | Response submission, payload formatting | **Always** — submission pipeline |
-| `07-language-handling.md` | Translations, placeholders, language switching | When survey is multi-language |
-| `08-icons-and-emojis.md` | CSAT emoji faces, star icons | When CSAT/rating_scale types present |
-
-## The Single Hook: `useSurveySDK()`
-
-The entire SDK is consumed through **one hook**:
-
-```typescript
-import { useSurveySDK } from '@explorer02/cfm-survey-sdk';
-
-const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
-  options: {
-    instanceId: string,                    // JWT token from client
-    language: string | undefined,          // Active language code
-    placeholders: Record<string, string>,  // Token replacements
-    debug: boolean,                        // Console logging
-  }
-});
-```
-
-This hook internally composes: `useFetchSurvey` → `useSurveyPagination` → `useSubmitResponse` → `useSurveyProgress`.
-
-The client component **never** needs to import or call these internal hooks directly.

package/templates/docs/02-question-types/02-radio.md

@@ -1,26 +0,0 @@
-# Radio Question (MCQ)
-
-> **Type**: `'radio'` | **API Source**: `MCQ` (and any unrecognised answerType)
-> **Mapper**: `radioMapper.ts` | **Component**: Inline in `Question.tsx`
-
-## TypeScript Type
-
-```typescript
-type RadioQuestion = QuestionBase & {
-  type: 'radio';
-  options: SurveyOption[];     // Answer choices
-  isMultiSelect?: boolean;     // If true, answer is (string|number)[]
-};
-```
-
-## Answer Shape: `string | number`
-Example: `"option_1"` or `3`
-If `isMultiSelect: true` → `(string | number)[]`
-
-## Rendering Guidance
-- Render as card-style option list with radio circles
-- Each option: border card with custom radio indicator + label
-- Selected state: brand-color border + light tint background + filled dot
-- Use `<input type="radio" className="sr-only">` for accessibility
-- Labels use `dangerouslySetInnerHTML` (may contain HTML)
-- `onChange={() => onSelect(option.value)}`

package/templates/docs/02-question-types/03-text.md

@@ -1,26 +0,0 @@
-# Text Question (Free Text)
-
-> **Type**: `'text'` | **API Source**: `TEXTFIELD`
-> **Mapper**: `textMapper.ts` | **Component**: Inline in `Question.tsx`
-
-## TypeScript Type
-
-```typescript
-type TextQuestion = QuestionBase & {
-  type: 'text';
-  maxCharacterCount?: number;    // Character limit
-  placeholder?: string;         // Input placeholder text
-  inputVariant?: 'short' | 'long';  // Single-line vs textarea
-};
-```
-
-## Answer Shape: `string`
-Example: `"Great customer service, very satisfied"`
-
-## Rendering Guidance
-- `inputVariant === 'short'` → `<input type="text">`, `inputVariant === 'long'` → `<textarea rows={4}>`
-- Default to `<textarea>` if `inputVariant` is not specified
-- Show character counter: `maxCharacterCount - currentLength` remaining
-- `onChange={e => onSelect(e.target.value)}`
-- Use `question.placeholder` or fallback: `"Type your response here..."`
-- Focus state: brand-color border + ring

package/templates/docs/02-question-types/12-text-and-media.md

@@ -1,35 +0,0 @@
-# Text and Media Question (Display-Only)
-
-> **Type**: `'text_and_media'` | **API Source**: `TEXT_AND_MEDIA`
-> **Mapper**: `textAndMediaMapper.ts` | **Component**: Inline in `Question.tsx`
-
-## TypeScript Type
-
-```typescript
-type TextAndMediaQuestion = QuestionBase & {
-  type: 'text_and_media';
-  mediaUrl?: string;             // Image or video URL
-  mediaMimeType?: string;        // 'image/*' or 'video/*'
-  mediaTitle?: string;           // Caption/alt text
-  mediaAlignment?: string;       // Layout position
-  mediaSize?: number;            // Width percentage
-};
-```
-
-## Answer Shape: NONE
-This is **display-only** — no answer is collected.
-
-## ⚠️ Critical Rules
-- **DO NOT** dispatch a `CHANGE` action for this question type
-- **Excluded** from validation (always passes)
-- **Excluded** from progress percentage counting
-- **Skipped** in `buildSubmitRequestBody()` — nothing is submitted
-
-## Rendering Guidance
-- Show `question.text` as the heading
-- If `mediaUrl` exists:
-  - `mediaMimeType` starts with `'video/'` → `<video controls src={mediaUrl}>`
-  - Otherwise → `<img src={mediaUrl} alt={mediaTitle}>`
-- Position media according to `mediaAlignment`
-- Size media according to `mediaSize` percentage
-- Show `mediaTitle` as caption below media

package/templates/docs/02-question-types/README.md

@@ -1,74 +0,0 @@
-# Question Types Overview
-
-> This folder contains one detailed doc per question type. Each doc covers: TypeScript type, mapper logic, answer shape, properties, and rendering guidance.
-
-## The `SurveyQuestion` Discriminated Union
-
-The SDK maps API questions into a **discriminated union** using the `type` field:
-
-```typescript
-type SurveyQuestion =
-  | RatingQuestion        // type: 'rating'       — NPS 0-10 numeric scale
-  | RadioQuestion         // type: 'radio'        — MCQ single/multi select
-  | TextQuestion          // type: 'text'         — Free text input
-  | CsatQuestion          // type: 'csat'         — 1-5 satisfaction (emoji/star)
-  | RatingScaleQuestion   // type: 'rating_scale' — Star/emoji rating (1-5/1-10)
-  | SliderQuestion        // type: 'slider'       — Single range slider
-  | MatrixQuestion        // type: 'matrix'       — Grid (CFM/CSAT/RATING subTypes)
-  | RatingMatrixQuestion  // type: 'rating_matrix' — NPS-style rating grid
-  | SliderMatrixQuestion  // type: 'slider_matrix' — Grid of range sliders
-  | FileUploadQuestion    // type: 'file_upload'  — File attachment
-  | TextAndMediaQuestion; // type: 'text_and_media' — Display-only media card
-```
-
-## Question → Component Routing Table
-
-| `question.type` | `question.subType` | Client Component | Answer Shape |
-|-----------------|-------------------|-----------------|-------------|
-| `'rating'` | — | `RatingScale` | `number` |
-| `'radio'` | — | Inline radio cards | `string \| number` |
-| `'text'` | — | Inline textarea | `string` |
-| `'csat'` | — | `CsatScale` | `number \| null` |
-| `'rating_scale'` | — | `RatingScale` (star/emoji variant) | `number` |
-| `'slider'` | — | `CustomSliderTrack` | `number` |
-| `'matrix'` | `'CFM_MATRIX'` | `LikertMatrixScale` | `MatrixAnswerMap` |
-| `'matrix'` | `'CSAT_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` |
-| `'matrix'` | `'RATING_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` |
-| `'rating_matrix'` | — | `CsatMatrixScale` | `MatrixAnswerMap` |
-| `'slider_matrix'` | — | `SliderMatrixScale` | `MatrixAnswerMap` |
-| `'file_upload'` | — | `FileUploadScale` | `UploadedFile[]` |
-| `'text_and_media'` | — | Inline media card | (no answer) |
-
-## Shared Base Properties
-
-All question types extend `QuestionBase`:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `id` | `string` | ⚠️ MUST be DOM element id |
-| `text` | `string` | Question text (may contain HTML) |
-| `description` | `string?` | Supplementary instruction (HTML) |
-| `required` | `boolean?` | Mandatory answer flag |
-| `requiredErrorMessage` | `string?` | Custom validation error |
-| `questionNumber` | `number?` | 1-indexed ordinal |
-| `containerMediaUrl` | `string?` | Image/video alongside question |
-| `containerMediaMimeType` | `string?` | MIME type for container media |
-| `containerMediaAlignment` | `string?` | Media layout position |
-| `containerMediaSize` | `number?` | Media width percentage |
-
-## Files in This Folder
-
-| File | Question Type | API Source |
-|------|-------------|-----------|
-| `01-rating.md` | `RatingQuestion` | `SCALE` (NPS/TEN_POINT) |
-| `02-radio.md` | `RadioQuestion` | `MCQ` |
-| `03-text.md` | `TextQuestion` | `TEXTFIELD` |
-| `04-csat.md` | `CsatQuestion` | `SCALE` (CSAT, ≤5 options) |
-| `05-rating-scale.md` | `RatingScaleQuestion` | `SCALE` (STAR/EMOJI) |
-| `06-slider.md` | `SliderQuestion` | `SCALE` (INPUT_TYPE=SLIDER) |
-| `07-matrix-cfm.md` | `MatrixQuestion` CFM | `CFM_MATRIX` |
-| `08-matrix-csat.md` | `MatrixQuestion` CSAT | `CSAT_MATRIX` |
-| `09-matrix-rating.md` | `RatingMatrixQuestion` | `RATING_MATRIX` |
-| `10-slider-matrix.md` | `SliderMatrixQuestion` | `SLIDER_MATRIX` |
-| `11-file-upload.md` | `FileUploadQuestion` | `FILE_UPLOAD` |
-| `12-text-and-media.md` | `TextAndMediaQuestion` | `TEXT_AND_MEDIA` |

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

@@ -1,51 +0,0 @@
-# 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

@@ -1,56 +0,0 @@
-# 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

@@ -1,37 +0,0 @@
-# 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

@@ -1,42 +0,0 @@
-# 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

@@ -1,46 +0,0 @@
-# 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

@@ -1,29 +0,0 @@
-# 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';
-```