@explorer02/cfm-survey-sdk 0.1.3 → 0.1.5

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

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

@@ -0,0 +1,57 @@
+# 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
+
+Every question is wrapped in a standard HTML section:
+
+```tsx
+<section id={question.id} className="space-y-4 rounded-xl border border-gray-200 bg-white p-6 shadow-sm">
+  {/* 1. Question Text (with required asterisk) */}
+  <h2 className="text-lg font-medium leading-relaxed text-gray-900">
+    <span dangerouslySetInnerHTML={{ __html: question.text }} />
+    {question.required && <span className="text-red-500 ml-1">*</span>}
+  </h2>
+  
+  {/* 2. Question Description */}
+  {question.description && (
+    <div className="text-sm text-gray-600 mt-2 leading-relaxed" dangerouslySetInnerHTML={{ __html: question.description }} />
+  )}
+  
+  {/* 3. The Scale Component (Dispatcher switch statement) */}
+  {question.type === 'rating' && <RatingScale ... />}
+  {/* ... other types ... */}
+  
+  {/* 4. Validation Error Banner */}
+  {validationError && (
+    <div className="mt-4 rounded-[4px] border border-[#333333] bg-[#d9d9d9] py-3.5 px-4 text-left">
+      <p className="text-[13px] sm:text-sm font-bold text-gray-900 leading-tight">{validationError}</p>
+    </div>
+  )}
+</section>
+```
+
+**⚠️ CRITICAL**: The wrapper element **MUST** have `id={question.id}` for the scroll-to-error validation to work!
+
+## 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)**: Inline mapping of `<label>` and `<input type="radio">`
+2. **`text`**: Inline `<textarea>`
+3. **`text_and_media`**: Inline `<video>` or `<img>` tag
+
+(See the respective question type docs for the exact rendering guidance for these inline types).

package/templates/docs/03-client-components/03-rating-scale.md

@@ -0,0 +1,38 @@
+# Rating Scale Component
+
+> **Component**: `RatingScale`
+> **Handles**: `type: 'rating'` | `type: 'rating_scale'`
+
+## Role
+Renders numbered badge arrays (for NPS 0-10) or icon arrays (stars/emojis) for satisfaction scales.
+
+## Props Interface
+```typescript
+type RatingScaleProps = {
+  questionId: string;
+  options: SurveyOption[];
+  selectedValue?: string | number | null | any;
+  onSelect: (value: number) => void;
+};
+```
+
+## Sub-Variants
+
+### 1. Numbered Badges (NPS / 10-point)
+If `option.color` is present, it's an NPS scale.
+- Map over `options`
+- Render rounded `<button>` for each
+- Use `option.color` as the background color
+- If an option is selected (`selectedValue !== undefined`), apply full opacity to the selected button and dim the unselected ones (`opacity-30`).
+
+### 2. Star Scale (`question.scaleStyle === 'star'`)
+- Render generic star icons using `CsatStarIcons.filled` and `CsatStarIcons.empty`
+- Use logic: `i < selectedIndex ? filled : empty` (fill all stars up to the selected one).
+
+### 3. Emoji Scale (`question.scaleStyle === 'emoji'`)
+- Render emoji face icons
+- Since options length is variable, use `getEmojiForIndex(i, options.length)` to map the position to the correct sentiment face.
+
+## Layout
+- Usually rendered as a `flex` row, `justify-between` or `gap-2` depending on container width.
+- Needs to wrap cleanly on mobile viewports.

package/templates/docs/03-client-components/04-csat-scale.md

@@ -0,0 +1,40 @@
+# CSAT Scale Component
+
+> **Component**: `CsatScale`
+> **Handles**: `type: 'csat'`
+
+## Role
+Renders satisfaction scales (typically 1-5). Relies heavily on the `buttonType` property to determine the visual rendering style.
+
+## Props Interface
+```typescript
+type CsatScaleProps = {
+  question: SurveyQuestion & { type: 'csat' };
+  selectedValue?: string | number | null;
+  onSelect: (value: number | null) => void;
+};
+```
+
+## Rendering by `buttonType`
+
+1. **`buttonType === 'emoji'`**
+   - Map over options. Use `CsatEmojiMapping[option.value]` for standard 1-5 scales.
+   - Or use `getEmojiForIndex` if scale is variable length.
+   
+2. **`buttonType === 'star'`**
+   - Map options. Fill stars up to the selected index using `CsatStarIcons`.
+
+3. **`buttonType === 'numbered'`**
+   - Simple rounded `<button>` with the numeric value. No traffic-light colors.
+
+4. **`buttonType === 'radio'`**
+   - Standard radio list.
+
+5. **`buttonType === 'graphics'`**
+   - Renders a single continuous slider. Uses `<CustomSliderTrack>`.
+
+## N/A Option Handling
+If `question.hasNotApplicable` is true:
+- The options array contains an option with `value: null`.
+- Render a distinct button for N/A.
+- Selecting it passes `null` to `onSelect`.

package/templates/docs/03-client-components/05-csat-matrix-scale.md

@@ -0,0 +1,43 @@
+# CSAT Matrix Scale Component
+
+> **Component**: `CsatMatrixScale`
+> **Handles**: `type: 'matrix'` (CSAT_MATRIX subType) | `type: 'rating_matrix'`
+
+## Role
+Renders a grid where rows are statements and columns are rating/satisfaction levels.
+
+## Props Interface
+```typescript
+type CsatMatrixScaleProps = {
+  question: SurveyQuestion & { type: 'matrix' | 'rating_matrix' };
+  selectedValue: MatrixAnswerMap;
+  onSelect: (value: MatrixAnswerMap) => void;
+};
+```
+
+## Structure
+- Renders an HTML `<table>`.
+- **`<thead>`**:
+  - Empty top-left cell.
+  - Column headers mapped from `question.columns`. Use `col.label`.
+- **`<tbody>`**:
+  - Map over `question.rows`.
+  - First cell is the row text.
+  - Subsequent cells are the input controls mapped from `question.columns`.
+
+## Input Control Selection
+Within each table cell, the control rendered depends on `question.buttonType` (similar to CsatScale):
+
+- `'emoji'`: Use `getEmojiForIndex(colIndex, cols.length)`
+- `'star'`: Use `CsatStarIcons`
+- `'radio'`: `<input type="radio">` + custom CSS dot
+- `'numbered'`: Badge button (if `rating_matrix`, apply `col.color`)
+
+If `buttonType === 'dropdown'`, the table structure is **abandoned**. Instead, it renders a list of rows, each containing a `<MatrixDropdown>` component.
+
+## `MatrixAnswerMap` Updates
+When a cell is clicked:
+```tsx
+const newValue = { ...selectedValue, [row.id]: col.value };
+onSelect(newValue);
+```

package/templates/docs/03-client-components/06-likert-matrix-scale.md

@@ -0,0 +1,38 @@
+# Likert Matrix Scale Component
+
+> **Component**: `LikertMatrixScale`
+> **Handles**: `type: 'matrix'` (CFM_MATRIX subType)
+
+## Role
+Renders a grid with text-label columns (Likert scale).
+
+## Props Interface
+```typescript
+type LikertMatrixScaleProps = {
+  question: SurveyQuestion & { type: 'matrix' };
+  selectedValue: MatrixAnswerMap;
+  onSelect: (value: MatrixAnswerMap) => void;
+};
+```
+
+## Structure & Formats
+
+The visual representation changes drastically based on `question.matrixFormat`:
+
+### 1. `matrixFormat === 'standard'` (Default)
+- Table grid.
+- Columns are simple radio buttons (`<input type="radio">`).
+- **No emojis or stars** — standard Likert matrices are purely structural text.
+- If `matrixType === 'bipolar'`, the first cell has `row.text` and the last cell has `row.rightText` added.
+
+### 2. `matrixFormat === 'carousel'`
+- Shows one row at a time.
+- Renders `row.text` prominently.
+- Renders a standard MCQ-style list of options (`columns`) below it.
+- Has internal state for `currentRowIndex`.
+- Next/Prev buttons step through the rows.
+
+### 3. `matrixFormat === 'dropdown'`
+- Renders a list of rows.
+- Each row contains a `<select>` dropdown populated with `question.columns`.
+- Or uses a custom `<MatrixDropdown>` component for better styling.

package/templates/docs/03-client-components/07-slider-matrix-scale.md

@@ -0,0 +1,44 @@
+# Slider Matrix Scale Component
+
+> **Component**: `SliderMatrixScale`
+> **Handles**: `type: 'slider_matrix'`
+
+## Role
+Renders a list of rows, where each row contains an independent range slider.
+
+## Props Interface
+```typescript
+type SliderMatrixScaleProps = {
+  question: SurveyQuestion & { type: 'slider_matrix' };
+  selectedValue: MatrixAnswerMap;
+  onSelect: (value: MatrixAnswerMap) => void;
+};
+```
+
+## Structure
+- Not a `<table>`. Rendered as a flex/grid list.
+- Map over `question.rows`.
+- Each row uses the row's specific `min`, `max`, and `step` values.
+- The slider is bound to `selectedValue[row.id]`.
+
+## Rendering the Slider
+
+```tsx
+<input 
+  type="range"
+  min={row.min}
+  max={row.max}
+  step={row.step}
+  value={selectedValue[row.id] ?? row.min}
+  onChange={e => onSelect({ ...selectedValue, [row.id]: Number(e.target.value) })}
+/>
+```
+
+If `question.sliderType === 'graphics'`, delegate to `<CustomSliderTrack>` instead of native `<input>`.
+
+If `question.enableNotApplicable` is true, render a checkbox next to each slider:
+```tsx
+<input type="checkbox" onChange={e => {
+  onSelect({ ...selectedValue, [row.id]: e.target.checked ? null : row.min })
+}} />
+```

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

@@ -0,0 +1,33 @@
+# File Upload Scale Component
+
+> **Component**: `FileUploadScale`
+> **Handles**: `type: 'file_upload'`
+
+## Role
+Provides a UI for selecting files, enforcing limits, and displaying the selected list.
+
+## Props Interface
+```typescript
+type FileUploadScaleProps = {
+  question: SurveyQuestion & { type: 'file_upload' };
+  selectedValue?: any[]; // Expected to be UploadedFile[]
+  onSelect: (value: any[]) => void;
+};
+```
+
+## Structure
+1. **Dropzone / Browse Button**
+   - `<input type="file" multiple={maxFileCount > 1} className="hidden">`
+   - Visible button triggers `.click()` on hidden input.
+2. **File List**
+   - Map over `selectedValue || []`.
+   - Show file name and remove button.
+3. **Error Text**
+   - Local state for size limit or format errors.
+
+## Limit Enforcement
+- `question.maxFileCount`
+- `question.supportedFileFormats` (e.g. `['PDF', 'PNG']`)
+- `question.fileSizeLimit` (MB)
+
+When files are selected, validate before adding to `selectedValue`.

package/templates/docs/03-client-components/09-custom-slider-track.md

@@ -0,0 +1,27 @@
+# Custom Slider Track
+
+> **Component**: `CustomSliderTrack`
+> **Used by**: `SliderMatrixScale`, `CsatMatrixScale`, `CsatScale`
+
+## Role
+A shared presentation component that overrides native browser range slider styling to provide an emoji-thumb or branded track.
+
+## Why it exists
+Native `<input type="range">` cannot reliably render an emoji inside the draggable thumb handle cross-browser. This component uses CSS tricks (often a transparent native range input layered over a custom styled `div` track) to achieve the design.
+
+## Props Interface
+```typescript
+type CustomSliderTrackProps = {
+  min: number;
+  max: number;
+  step: number;
+  value: number;
+  onChange: (val: number) => void;
+  sliderType?: 'graphics' | 'standard';
+  // Additional props for tick marks, colors
+};
+```
+
+## Emoji Thumb Logic
+If `sliderType === 'graphics'`, the thumb handle should dynamically display an emoji corresponding to the current value.
+It uses `getEmojiForIndex` from `icons.tsx`.

package/templates/docs/03-client-components/10-header-footer.md

@@ -0,0 +1,46 @@
+# Header, Footer & Branding
+
+> **Components**: `Header`, `Footer`
+> **Role**: Branding shells around the survey content.
+
+## Strict Logo Requirement
+
+**⚠️ CRITICAL RULE**: You must NOT use `<img>` tags pointing to external Telekom or Sprinklr URLs. You must NOT download static images into the `public/` folder.
+
+All logos must be constructed **purely using Tailwind CSS** geometric shapes.
+
+## The Header (Abstract Brand)
+
+```tsx
+export default function Header() {
+  return (
+    <header className="flex h-16 items-center justify-between border-b px-6">
+      {/* CSS-only Abstract Logo */}
+      <div className="flex items-center gap-2">
+        <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-[#e20074]">
+          <div className="h-4 w-4 rounded-full bg-white" />
+        </div>
+        <span className="text-xl font-bold tracking-tight text-gray-900">
+          YourBrand
+        </span>
+      </div>
+    </header>
+  );
+}
+```
+
+## The Footer
+
+```tsx
+export default function Footer() {
+  return (
+    <footer className="border-t py-6 text-center text-sm text-gray-500">
+      <p>Powered by Sprinklr CFM SDK</p>
+    </footer>
+  );
+}
+```
+
+## Customization
+
+The client may provide a prompt asking for specific colors ("make it dark mode", "use blue"). Update the CSS classes in `SurveyPage`, `Header`, and `Footer` to match their request. Do not try to reverse-engineer their brand logo exactly — stick to clean abstract CSS geometry unless you have an explicit SVG path.

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