@explorer02/cfm-survey-sdk 0.1.7 → 0.1.9

package/templates/docs/03-client-components/01-survey-page.md

@@ -1,113 +0,0 @@
-# Survey Page Orchestrator
-
-> **Source**: `apps/client/src/components/SurveyPage.tsx`
-> **Role**: The main entry point that wires the UI to the `useSurveySDK` hook.
-
-## Setup & Wiring
-
-The component must pass the `options` to `useSurveySDK`, including the **instanceId** provided by the client prompt.
-
-```tsx
-const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'Customer' }; // Must be outside component!
-
-export default function SurveyPage() {
-  const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>("");
-
-  const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
-    options: {
-      instanceId: 'YOUR_INSTANCE_ID_HERE', // From client prompt
-      language: selectedLanguage,
-      placeholders: SURVEY_PLACEHOLDERS,
-      debug: true,
-    }
-  });
-  
-  const survey = surveyQueryResults.data;
-  
-  // ... render states
-}
-```
-
-## The 5 Render States
-
-A complete `SurveyPage` must handle 5 distinct rendering states in this exact order:
-
-### 1. Loading State
-```tsx
-if (surveyQueryResults.isLoading) {
-  return <LoadingView /> // Header, Footer, and a "Loading..." message
-}
-```
-
-### 2. Error State
-```tsx
-if (surveyQueryResults.error) {
-  return <ErrorView error={surveyQueryResults.error.message} /> 
-}
-```
-
-### 3. Empty State
-```tsx
-if (!survey) {
-  return <EmptyView /> // Header, Footer, and a "No survey data" message
-}
-```
-
-### 4. Submitted State
-```tsx
-if (submitSurveyResults.data) {
-  return <SubmitSummaryView /> // Header, Footer, and a "Thank you" message
-}
-```
-
-### 5. Active Survey State
-The main render path. Must include:
-1. `Header`
-2. `ProgressBar` (passing `state.progressPercentage`)
-3. `LanguageSelector` (passing `survey.languages`, `survey.language`, `setSelectedLanguage`)
-4. The question list mapping over `state.currentQuestions`
-5. Back / Next buttons
-6. `Footer`
-
-## Question Mapping Pattern
-
-```tsx
-<div className="space-y-12">
-  {state.currentQuestions.map(question => (
-    <Question
-      key={question.id}
-      question={question}
-      selectedValue={state.values[question.id]}
-      validationError={state.validationErrors[question.id]}
-      onSelect={value => onAction({ 
-        type: 'CHANGE', 
-        payload: { questionId: question.id, value } 
-      })}
-    />
-  ))}
-</div>
-```
-
-## Navigation Buttons Pattern
-
-```tsx
-{/* Back Button (hide on first page) */}
-{state.currentPageIndex > 0 && (
-  <button onClick={() => onAction({ type: 'PREVIOUS' })}>
-    {survey.language?.startsWith('de') ? 'Zurück' : 'Back'}
-  </button>
-)}
-
-{/* Next/Submit Button */}
-<button 
-  onClick={() => onAction({ type: 'NEXT' })}
-  disabled={submitSurveyResults.isLoading}
->
-  {submitSurveyResults.isLoading
-    ? (survey.language?.startsWith('de') ? 'Wird gesendet...' : 'Submitting...')
-    : state.currentPageIndex < survey.pages.length - 1
-      ? (survey.language?.startsWith('de') ? 'Weiter' : 'Next')
-      : (survey.language?.startsWith('de') ? 'Absenden' : 'Submit')
-  }
-</button>
-```

package/templates/docs/03-client-components/02-question.md

@@ -1,74 +0,0 @@
-# Question Dispatcher
-
-> **Source**: `apps/client/src/components/Question.tsx`
-> **Role**: Wrapper card component that routes to the correct scale component based on question type.
-
-## Props Interface
-
-```typescript
-type QuestionProps = {
-  question: SurveyQuestion;
-  selectedValue?: AnswerValue;
-  validationError?: string;
-  onSelect: (value: AnswerValue) => void;
-};
-```
-
-## Structure & Styling Rules (CRITICAL)
-
-Every question is wrapped in a standard HTML section. It **MUST** have a border around the entire question block to separate them visually, and it **MUST** handle rich text (HTML) provided by the SDK safely.
-
-```tsx
-<section 
-  id={question.id} 
-  className="space-y-6 rounded-xl border border-gray-200 bg-white p-6 md:p-8 shadow-sm transition-all hover:shadow-md"
->
-  {/* 1. Question Text (Rich Text with required asterisk) */}
-  <h2 className="text-lg md:text-xl font-semibold leading-relaxed text-gray-900 flex items-start gap-1">
-    {/* dangerouslySetInnerHTML handles strong, em, and link tags from the SDK */}
-    <span dangerouslySetInnerHTML={{ __html: question.text }} className="prose prose-sm max-w-none" />
-    {question.required && <span className="text-[#e20074] shrink-0">*</span>}
-  </h2>
-  
-  {/* 2. Question Description (Rich Text) */}
-  {question.description && (
-    <div 
-      className="text-sm text-gray-600 mt-2 leading-relaxed prose prose-sm max-w-none" 
-      dangerouslySetInnerHTML={{ __html: question.description }} 
-    />
-  )}
-  
-  {/* 3. The Scale Component (Dispatcher switch statement) */}
-  <div className="pt-4">
-    {question.type === 'rating' && <RatingScale ... />}
-    {/* ... other types ... */}
-  </div>
-  
-  {/* 4. Validation Error Banner */}
-  {validationError && (
-    <div className="mt-6 rounded-lg border-l-4 border-l-[#e20074] bg-red-50 p-4">
-      <p className="text-sm font-bold text-gray-900 leading-tight flex items-center gap-2">
-        <span className="text-[#e20074]">⚠</span> {validationError}
-      </p>
-    </div>
-  )}
-</section>
-```
-
-**⚠️ CRITICAL RULES**:
-1. **DOM ID**: The wrapper element **MUST** have `id={question.id}` for the scroll-to-error validation to work!
-2. **Borders**: The wrapper **MUST** have `border border-gray-200 rounded-xl`.
-3. **Rich Text**: `question.text` and `question.description` MUST be rendered using `dangerouslySetInnerHTML` because the SDK sends formatted HTML. Do not render them as raw strings.
-4. **Spacing**: Use `space-y-6` and `p-6 md:p-8` for generous internal padding.
-
-## Inline vs Dedicated Components
-
-While complex scales (like Matrix, Slider, FileUpload) get their own dedicated files (e.g. `CsatMatrixScale.tsx`), some simpler types are handled directly inline within `Question.tsx` to reduce boilerplate:
-
-1. **`radio` (MCQ)**: 
-   - Each option is a card: `border rounded-lg p-4 flex items-center gap-3 cursor-pointer transition-colors`.
-   - Hover state: `hover:border-[#e20074] hover:bg-pink-50`.
-   - Selected state: `border-[#e20074] bg-pink-50`.
-   - Custom radio dot: `<div className={`h-5 w-5 rounded-full border-2 ${isSelected ? 'border-[#e20074]' : 'border-gray-300'} flex items-center justify-center`}><div className={`h-2.5 w-2.5 rounded-full bg-[#e20074] ${isSelected ? 'block' : 'hidden'}`} /></div>`
-2. **`text`**: Inline `<textarea>` or `<input type="text">` with `border-gray-300 focus:border-[#e20074] focus:ring-[#e20074] rounded-lg w-full`.
-3. **`text_and_media`**: Inline `<video>` or `<img>` tag with `rounded-lg`.

package/templates/docs/03-client-components/08-file-upload-scale.md

@@ -1,37 +0,0 @@
-# File Upload Architectural Blueprint
-
-> **Target Component**: `FileUploadScale`
-> **Handles**: `type: 'file_upload'`
-
-## Core Responsibility
-Provide a robust drag-and-drop zone and enforce complex file size and type limits before updating state.
-
-## State Management
-- `selectedValue`: Expects `UploadedFile[]` (array of objects with `name`, `size`, `type`).
-- **Mutation**: Since we aren't uploading to a real server in the UI stub, you must read the `File` from the hidden `<input>`, create a mock `UploadedFile` object with a fake `mediaUrl` and `id`, and dispatch it via `onSelect`.
-
-## Configuration Matrix (CRITICAL FOR PLANNING)
-
-Before calling `onSelect`, your component MUST validate against these properties:
-
-### 1. `supportedFileFormats`
-- Build the `accept` attribute string for the hidden input: `question.supportedFileFormats?.map(f => \`.\${f.toLowerCase()}\`).join(',')`.
-
-### 2. `maxFileCount`
-- If `selectedValue.length >= maxFileCount`, prevent further additions and show an error state.
-
-### 3. `fileSizeLimit` & `fileSizeLimitType`
-- If `fileSizeLimitType === 'PER_FILE'`, validate that the incoming file's `size` (in MB) is `<= fileSizeLimit`.
-- If `fileSizeLimitType === 'IN_TOTAL'`, calculate the sum of all existing `selectedValue` sizes plus the incoming file size, and validate against `fileSizeLimit`.
-
-## UI/UX Specifications
-
-1. **Dropzone**:
-   - `border-2 border-dashed border-gray-300 rounded-xl bg-gray-50 p-8 text-center cursor-pointer transition-colors hover:border-[#e20074] hover:bg-pink-50`.
-   - Render a Cloud SVG icon.
-   - Display the instruction text (`question.uploadMessage`) and the dynamic limits text cleanly.
-
-2. **File List**:
-   - Render existing files as distinct cards underneath the dropzone.
-   - `flex items-center justify-between p-3 mt-3 border border-gray-200 rounded-lg bg-white shadow-sm`.
-   - Include a distinct red Trash/Remove button.

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';
-```