@explorer02/cfm-survey-sdk 0.1.4 → 0.1.6

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

@@ -0,0 +1,74 @@
+# 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/03-rating-scale.md

@@ -0,0 +1,91 @@
+# Rating Scale Component
+
+> **Component**: `RatingScale`
+> **Handles**: `type: 'rating'` | `type: 'rating_scale'`
+
+## Props Interface
+```typescript
+type RatingScaleProps = {
+  questionId: string;
+  options: SurveyOption[];
+  selectedValue?: string | number | null | any;
+  onSelect: (value: number) => void;
+  // Extracted from question object:
+  minLabel?: string;
+  midLabel?: string;
+  maxLabel?: string;
+  midLabelIndex?: number;
+};
+```
+
+## UI Styling & Interaction Rules (CRITICAL)
+
+The UI must exactly match these specifications:
+
+### 1. Square Rounded Buttons
+- Do **NOT** use circles for `rating` badges. Use squares with rounded corners.
+- Base classes: `flex h-10 w-10 sm:h-12 sm:w-12 items-center justify-center rounded-lg text-sm sm:text-base font-medium transition-all duration-200 cursor-pointer`.
+
+### 2. Colors & Hover States
+- `options` may contain a `color` property (NPS scale). Use it for the background.
+- If no color is provided, use a default gray background.
+- **Unselected State**: `opacity-30` (if any option is selected, dim the others), or just standard opacity with a subtle border.
+- **Hover State**: `hover:scale-105 hover:shadow-md hover:border-[#e20074] hover:border-2`.
+- **Selected State**: 
+  - Apply `opacity-100`.
+  - Apply a strong prominent border: `border-2 border-[#e20074] shadow-md`.
+
+### 3. Tooltips
+- Every button **MUST** have `title={option.label}` so users can see the exact semantic meaning (e.g., "Extremely Likely") when hovering over the number '10'.
+
+### 4. Label Positioning
+- Place `minLabel`, `midLabel`, and `maxLabel` underneath the button track.
+- Container for labels: `relative mt-3 h-8 w-full text-xs text-gray-500`.
+- Left label (`minLabel`): `absolute left-0`.
+- Right label (`maxLabel`): `absolute right-0`.
+- Middle label (`midLabel`): `absolute transform -translate-x-1/2` with `style={{ left: \`\${(midLabelIndex / (options.length - 1)) * 100}%\` }}`.
+
+## Implementation Snippet
+
+```tsx
+<div className="w-full">
+  <div className="flex w-full justify-between gap-1 sm:gap-2">
+    {options.map((option, i) => {
+      const isSelected = selectedValue === option.value;
+      const isAnySelected = selectedValue !== undefined && selectedValue !== null;
+      
+      return (
+        <button
+          key={option.id}
+          type="button"
+          onClick={() => onSelect(option.value as number)}
+          title={option.label} // Tooltip required
+          className={`
+            flex h-10 w-10 sm:h-12 sm:w-12 items-center justify-center rounded-lg font-semibold transition-all
+            ${isSelected ? 'border-2 border-[#e20074] scale-105 shadow-md opacity-100 z-10' : 'border border-transparent'}
+            ${!isSelected && isAnySelected ? 'opacity-40' : 'opacity-100'}
+            hover:border-[#e20074] hover:scale-105 hover:opacity-100
+          `}
+          style={{ backgroundColor: option.color || '#f3f4f6', color: '#000000' }}
+        >
+          {option.value}
+        </button>
+      );
+    })}
+  </div>
+  
+  {/* Label Positioning */}
+  <div className="relative mt-3 h-6 w-full text-xs font-medium text-gray-500">
+    {minLabel && <span className="absolute left-0">{minLabel}</span>}
+    {midLabel && (
+      <span 
+        className="absolute transform -translate-x-1/2 text-center"
+        style={{ left: `${(midLabelIndex! / (options.length - 1)) * 100}%` }}
+      >
+        {midLabel}
+      </span>
+    )}
+    {maxLabel && <span className="absolute right-0 text-right">{maxLabel}</span>}
+  </div>
+</div>
+```

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

@@ -0,0 +1,79 @@
+# CSAT Scale Component
+
+> **Component**: `CsatScale`
+> **Handles**: `type: 'csat'`
+
+## Props Interface
+```typescript
+type CsatScaleProps = {
+  question: SurveyQuestion & { type: 'csat' };
+  selectedValue?: string | number | null;
+  onSelect: (value: number | null) => void;
+};
+```
+
+## UI Styling & Interaction Rules (CRITICAL)
+
+The visual rendering heavily depends on `buttonType`. All variants MUST implement strict hover states, tooltips, and distinct active state bounding boxes.
+
+### 1. `buttonType === 'emoji'`
+- **Icons**: Use `getEmojiForIndex(index, total)` or map `CsatEmojiMapping`.
+- **Hover State**: `hover:scale-110 transition-transform cursor-pointer`.
+- **Active State Bounding Box**: 
+  - DO NOT just change the emoji color.
+  - The selected emoji MUST be wrapped in a prominent pink square box with rounded corners.
+  - Wrapper CSS: `border-2 border-[#e20074] rounded-lg p-2 bg-pink-50 shadow-sm scale-110`.
+  - Unselected CSS: `border-2 border-transparent p-2 opacity-50 hover:opacity-100`.
+- **Tooltips**: `title={option.label}` on every button.
+
+### 2. `buttonType === 'star'`
+- **Icons**: Use `CsatStarIcons.filled` and `CsatStarIcons.empty`.
+- **Active State Bounding Box**:
+  - The *last* selected star (the one matching the `selectedValue`) receives the pink bounding box: `border-2 border-[#e20074] rounded-lg p-2 bg-pink-50 scale-110`.
+  - Previous filled stars get `border-transparent p-2 text-[#e20074]`.
+  - Empty stars get `opacity-30`.
+
+### 3. `buttonType === 'numbered'`
+- Fallback to `RatingScale` style (Square badges).
+
+### 4. `buttonType === 'graphics'`
+- Render a single `<CustomSliderTrack>`.
+
+## N/A Option Handling
+If `question.hasNotApplicable` is true:
+- Render a distinct button or checkbox for N/A.
+- Selecting it passes `null` to `onSelect`.
+- Style it distinctly from the main scale (e.g., standard text button or checkbox).
+
+## Label Positioning
+- Place `minLabel` and `maxLabel` underneath the emoji/star track, just like RatingScale.
+- `relative mt-4 flex w-full justify-between text-xs text-gray-500 font-medium`.
+
+## Implementation Snippet (Emoji Variant)
+
+```tsx
+<div className="flex w-full justify-between items-center gap-2">
+  {options.map((option, i) => {
+    const isSelected = selectedValue === option.value;
+    
+    return (
+      <button
+        key={option.id}
+        onClick={() => onSelect(option.value as number)}
+        title={option.label} // Required Tooltip
+        className={`
+          flex items-center justify-center transition-all duration-200
+          ${isSelected 
+            ? 'border-2 border-[#e20074] rounded-lg p-1 sm:p-2 bg-pink-50 scale-110 shadow-sm z-10' 
+            : 'border-2 border-transparent p-1 sm:p-2 opacity-50 hover:opacity-100 hover:scale-105'
+          }
+        `}
+      >
+        <div className="w-8 h-8 sm:w-10 sm:h-10">
+          {getEmojiForIndex(i, options.length)}
+        </div>
+      </button>
+    );
+  })}
+</div>
+```

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

@@ -0,0 +1,77 @@
+# CSAT Matrix Scale Component
+
+> **Component**: `CsatMatrixScale`
+> **Handles**: `type: 'matrix'` (CSAT_MATRIX subType) | `type: 'rating_matrix'`
+
+## Props Interface
+```typescript
+type CsatMatrixScaleProps = {
+  question: SurveyQuestion & { type: 'matrix' | 'rating_matrix' };
+  selectedValue: MatrixAnswerMap;
+  onSelect: (value: MatrixAnswerMap) => void;
+};
+```
+
+## UI Structure & Hover Rules (CRITICAL)
+
+The matrix must be rendered as an HTML `<table>` with strict hover tracking and active selection bounding boxes.
+
+### 1. Table Layout
+- `w-full text-left border-collapse`.
+- **Headers (`<thead>`)**:
+  - `th` elements must be `p-4 text-sm font-semibold text-gray-600 text-center`.
+  - Leftmost header is empty.
+
+### 2. Row Hover Tracking
+- Matrix grids are hard to read. You **MUST** add `hover:bg-gray-50 transition-colors` to every `<tr>` in the `<tbody>`.
+- Cells: `td` elements must be `p-4 border-b border-gray-100 text-center`.
+- Leftmost cell (row text): `text-sm font-medium text-gray-800 text-left w-1/3`.
+
+### 3. Active State Bounding Boxes (Emojis & Stars)
+Just like `CsatScale`, when `buttonType === 'emoji'` or `'star'`, you cannot just swap the icon. The selected cell must highlight the selection prominently.
+
+- **Unselected Icon Wrapper**: `inline-flex p-1 border-2 border-transparent opacity-40 hover:opacity-100 hover:scale-110 transition-all cursor-pointer`.
+- **Selected Icon Wrapper**: `inline-flex p-1 border-2 border-[#e20074] rounded-md bg-pink-50 scale-110 shadow-sm opacity-100 cursor-pointer`.
+
+### 4. Tooltips
+- Every icon in every cell MUST have `title={col.label}` so the user knows what column they are clicking.
+
+## Implementation Snippet (Row Rendering)
+
+```tsx
+<tbody>
+  {question.rows.map((row) => (
+    <tr key={row.id} className="hover:bg-gray-50 transition-colors group">
+      <td className="p-4 border-b border-gray-100 text-sm font-medium text-gray-800 text-left w-1/3">
+        {row.text}
+      </td>
+      {question.columns.map((col, colIdx) => {
+        const isSelected = selectedValue[row.id] === col.value;
+        
+        return (
+          <td key={col.id} className="p-4 border-b border-gray-100 text-center">
+            <button
+              type="button"
+              onClick={() => onSelect({ ...selectedValue, [row.id]: col.value })}
+              title={col.label} // Tooltip required
+              className={`
+                inline-flex items-center justify-center transition-all duration-200
+                ${isSelected 
+                  ? 'border-2 border-[#e20074] rounded-md p-1.5 bg-pink-50 scale-110 shadow-sm' 
+                  : 'border-2 border-transparent p-1.5 opacity-40 group-hover:opacity-70 hover:opacity-100 hover:scale-110'
+                }
+              `}
+            >
+              <div className="w-6 h-6 sm:w-8 sm:h-8">
+                 {/* Render icon based on buttonType */}
+                 {question.buttonType === 'emoji' && getEmojiForIndex(colIdx, question.columns.length)}
+                 {question.buttonType === 'star' && (isSelected ? CsatStarIcons.filled : CsatStarIcons.empty)}
+              </div>
+            </button>
+          </td>
+        );
+      })}
+    </tr>
+  ))}
+</tbody>
+```

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

@@ -0,0 +1,43 @@
+# Likert Matrix Scale Component
+
+> **Component**: `LikertMatrixScale`
+> **Handles**: `type: 'matrix'` (CFM_MATRIX subType)
+
+## Props Interface
+```typescript
+type LikertMatrixScaleProps = {
+  question: SurveyQuestion & { type: 'matrix' };
+  selectedValue: MatrixAnswerMap;
+  onSelect: (value: MatrixAnswerMap) => void;
+};
+```
+
+## Matrix Configurations (CRITICAL)
+
+The SDK provides several boolean flags that alter the grid layout. You MUST implement logic for these:
+
+### 1. `question.transposeTable`
+If `true`, swap the axes:
+- The `columns` (labels like "Strongly Agree") become the left-hand row headers.
+- The `rows` (statements) become the top column headers.
+- Rendering logic must map over columns first, then rows.
+
+### 2. `question.repeatScale`
+If `true`, the `<thead>` (the column labels) should be injected periodically in the `<tbody>`.
+- Example: `if (rowIndex > 0 && rowIndex % 5 === 0) return <RepeatedHeaderRow />`
+- This helps users maintain context on very long grids.
+
+### 3. `question.matrixType === 'bipolar'`
+- The first cell contains `row.text`.
+- The last cell contains `row.rightText`.
+- The radio buttons span the cells in between.
+
+## UI Styling Rules
+
+- **Row Hovers**: Every `<tr>` must have `hover:bg-gray-50 transition-colors`.
+- **Radio Buttons**: 
+  - Do NOT use plain browser radios if possible. Use accent-colored styling:
+    `accent-[#e20074] w-5 h-5 cursor-pointer`.
+  - Alternatively, build custom CSS circles that fill with pink when selected.
+- **Labels**: Header labels (`th`) should be `text-xs font-semibold text-gray-500 uppercase tracking-wider text-center`.
+- **Tooltips**: Native `title` on every radio button mapping to the column label.

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

@@ -0,0 +1,93 @@
+# Slider Matrix Scale Component
+
+> **Component**: `SliderMatrixScale`
+> **Handles**: `type: 'slider_matrix'`
+
+## Props Interface
+```typescript
+type SliderMatrixScaleProps = {
+  question: SurveyQuestion & { type: 'slider_matrix' };
+  selectedValue: MatrixAnswerMap;
+  onSelect: (value: MatrixAnswerMap) => void;
+};
+```
+
+## UI Styling Rules (CRITICAL)
+
+Sliders must look substantial and modern. Native thin browser sliders are unacceptable.
+
+### 1. Thick Track Styling
+The slider track must be visually prominent:
+- Height: `h-2` or `h-3`.
+- Rounded corners: `rounded-full`.
+- **Dynamic Fill**: The track up to the thumb MUST be pink (`bg-[#e20074]`). The track after the thumb MUST be light gray (`bg-gray-200`).
+- You can achieve this using CSS linear-gradients tied to the value percentage, or by using a custom overlay div.
+
+### 2. Thumb Styling
+- Solid pink circle: `w-5 h-5 rounded-full bg-[#e20074] shadow-md border-2 border-white`.
+- Hover state: `hover:scale-125 transition-transform`.
+
+### 3. Value Display
+- The exact selected value (e.g., `7`) **MUST** be displayed visibly.
+- Typical layout: Place it at the far right of the slider track in a small bold badge.
+
+### 4. Ticks and Labels
+- `row.ticks`: If provided (e.g., `10`), render tiny tick marks beneath the track at intervals.
+- `row.minLabel` & `row.maxLabel`: Render underneath the far left and far right of the track.
+
+## Implementation Snippet (Custom Slider Row)
+
+```tsx
+{question.rows.map(row => {
+  const val = selectedValue[row.id] ?? row.min;
+  const percentage = ((val - row.min) / (row.max - row.min)) * 100;
+
+  return (
+    <div key={row.id} className="flex flex-col gap-4 py-6 border-b border-gray-100">
+      <p className="text-sm font-medium text-gray-800">{row.text}</p>
+      
+      <div className="flex items-center gap-4">
+        <div className="relative w-full flex items-center h-6">
+          {/* Track Background */}
+          <div className="absolute w-full h-2 bg-gray-200 rounded-full" />
+          
+          {/* Track Fill (Pink) */}
+          <div 
+            className="absolute h-2 bg-[#e20074] rounded-l-full" 
+            style={{ width: `${percentage}%` }}
+          />
+          
+          {/* Native Input (Invisible overlay for mechanics) */}
+          <input 
+            type="range"
+            min={row.min}
+            max={row.max}
+            step={row.step}
+            value={val}
+            onChange={e => onSelect({ ...selectedValue, [row.id]: Number(e.target.value) })}
+            className="absolute w-full h-full opacity-0 cursor-pointer z-10"
+            title={`Value: ${val}`}
+          />
+          
+          {/* Visual Thumb */}
+          <div 
+            className="absolute w-5 h-5 bg-[#e20074] border-2 border-white rounded-full shadow-md pointer-events-none transition-transform"
+            style={{ left: `calc(${percentage}% - 10px)` }}
+          />
+        </div>
+        
+        {/* Value Display Badge */}
+        <div className="shrink-0 w-8 text-center font-bold text-[#e20074]">
+          {val}
+        </div>
+      </div>
+      
+      {/* Min/Max Labels */}
+      <div className="flex justify-between text-xs text-gray-500 font-medium px-1">
+        <span>{row.minLabel}</span>
+        <span>{row.maxLabel}</span>
+      </div>
+    </div>
+  );
+})}
+```

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

@@ -0,0 +1,87 @@
+# File Upload Scale Component
+
+> **Component**: `FileUploadScale`
+> **Handles**: `type: 'file_upload'`
+
+## Props Interface
+```typescript
+type FileUploadScaleProps = {
+  question: SurveyQuestion & { type: 'file_upload' };
+  selectedValue?: any[]; // Expected to be UploadedFile[]
+  onSelect: (value: any[]) => void;
+};
+```
+
+## UI Styling Rules (CRITICAL)
+
+The file upload component must be highly polished, featuring a drag-and-drop zone and a discrete list of uploaded files.
+
+### 1. Dropzone Area
+- **Border**: Thick dashed border. `border-2 border-dashed border-gray-300 rounded-xl`.
+- **Background & Spacing**: `bg-gray-50 p-8 text-center cursor-pointer transition-colors`.
+- **Hover State**: `hover:border-[#e20074] hover:bg-pink-50 hover:shadow-sm`.
+- **Content**: 
+  - Render a large prominent cloud upload icon (e.g., from `react-icons`).
+  - Render the instruction text (`question.uploadMessage` or "Click or drag files here to upload").
+  - Render limits text below it in smaller font: `Max files: ${maxFileCount} | Limit: ${fileSizeLimit}MB | Formats: ${supportedFileFormats.join(', ')}`.
+
+### 2. Uploaded Files List
+When files are selected (`selectedValue.length > 0`), render them as a list of distinct cards below the dropzone:
+- **Card**: `flex items-center justify-between p-3 mt-3 border border-gray-200 rounded-lg bg-white shadow-sm`.
+- **File Info**: Display a small file icon, the file name (`truncate` class if long), and the file size.
+- **Remove Button**: A discrete trash can icon button. `text-red-500 hover:bg-red-50 rounded-md p-2 transition-colors`.
+
+## Implementation Snippet
+
+```tsx
+<div className="space-y-4">
+  {/* Hidden Input */}
+  <input 
+    type="file" 
+    ref={fileInputRef} 
+    className="hidden" 
+    multiple={question.maxFileCount > 1}
+    accept={question.supportedFileFormats?.map(f => `.${f.toLowerCase()}`).join(',')}
+    onChange={handleFileChange}
+  />
+
+  {/* Dropzone */}
+  <div 
+    onClick={() => fileInputRef.current?.click()}
+    className="border-2 border-dashed border-gray-300 rounded-xl bg-gray-50 hover:bg-pink-50 hover:border-[#e20074] transition-colors p-8 text-center cursor-pointer flex flex-col items-center justify-center gap-2 group"
+  >
+    <div className="w-12 h-12 rounded-full bg-white flex items-center justify-center text-gray-400 group-hover:text-[#e20074] shadow-sm mb-2">
+      {/* Insert SVG Cloud Icon Here */}
+      <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M15 13l-3-3m0 0l-3 3m3-3v12" /></svg>
+    </div>
+    <p className="text-sm font-semibold text-gray-700 group-hover:text-[#e20074]">
+      {question.uploadMessage || "Click or drag files here to upload"}
+    </p>
+    <p className="text-xs text-gray-500">
+      Supported formats: {question.supportedFileFormats?.join(', ')} (Max {question.fileSizeLimit}MB)
+    </p>
+  </div>
+
+  {/* Uploaded Files List */}
+  {selectedValue && selectedValue.length > 0 && (
+    <ul className="space-y-2 mt-4">
+      {selectedValue.map((file, i) => (
+        <li key={i} className="flex items-center justify-between p-3 border border-gray-200 rounded-lg bg-white shadow-sm">
+          <div className="flex items-center gap-3 overflow-hidden">
+            <span className="text-gray-400">📄</span>
+            <span className="text-sm font-medium text-gray-700 truncate">{file.name}</span>
+            {file.size && <span className="text-xs text-gray-400">({(file.size / 1024 / 1024).toFixed(2)} MB)</span>}
+          </div>
+          <button 
+            onClick={() => onSelect(selectedValue.filter((_, index) => index !== i))}
+            className="text-red-500 hover:bg-red-50 p-2 rounded-md transition-colors"
+            title="Remove file"
+          >
+            🗑️
+          </button>
+        </li>
+      ))}
+    </ul>
+  )}
+</div>
+```

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

@@ -0,0 +1,72 @@
+# 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 a standard branded thick track. 
+
+## Custom Graphics Variant (`sliderType === 'graphics'`)
+If the API specifies `graphics`, the slider thumb **MUST** dynamically display an emoji corresponding to the current value.
+- The thumb must be large enough to hold an emoji (`w-8 h-8` or `w-10 h-10`).
+- Use `getEmojiForIndex` from the SDK to map the current percentage/value to the correct sentiment face.
+- The thumb must have a shadow and white background to pop out from the track: `bg-white rounded-full shadow-md border border-gray-200 flex items-center justify-center text-xl`.
+
+## Track CSS Construction
+Native `<input type="range">` cannot reliably render an emoji inside the draggable thumb handle cross-browser. 
+
+You MUST use the "invisible overlay" trick:
+1. Render a visual background track `div` (the gray bar).
+2. Render a visual fill track `div` (the pink bar, width bound to `percentage`).
+3. Render a visual thumb `div` (the pink circle or the emoji, left bound to `percentage`).
+4. **Overlay** a completely invisible native `<input type="range" className="absolute opacity-0 w-full h-full cursor-pointer z-10" />`.
+
+## Implementation Snippet
+
+```tsx
+export default function CustomSliderTrack({ min, max, step, value, onChange, sliderType }) {
+  const percentage = ((value - min) / (max - min)) * 100;
+
+  // Determine emoji if graphics variant
+  const emoji = sliderType === 'graphics' 
+    ? getEmojiForIndex(value - min, (max - min) / step + 1)
+    : null;
+
+  return (
+    <div className="relative w-full flex items-center h-8">
+      {/* Background Track */}
+      <div className="absolute w-full h-2 bg-gray-200 rounded-full" />
+      
+      {/* Filled Track */}
+      <div 
+        className="absolute h-2 bg-[#e20074] rounded-l-full" 
+        style={{ width: `${percentage}%` }}
+      />
+      
+      {/* Invisible Native Input */}
+      <input 
+        type="range"
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        onChange={e => onChange(Number(e.target.value))}
+        className="absolute w-full h-full opacity-0 cursor-pointer z-10"
+        title={`Value: ${value}`}
+      />
+      
+      {/* Custom Thumb */}
+      <div 
+        className={`absolute pointer-events-none transition-transform flex items-center justify-center ${
+          sliderType === 'graphics' 
+            ? 'w-10 h-10 bg-white rounded-full shadow-md border border-gray-200 text-2xl -ml-5' 
+            : 'w-5 h-5 bg-[#e20074] border-2 border-white rounded-full shadow-md -ml-2.5 hover:scale-125'
+        }`}
+        style={{ left: `${percentage}%` }}
+      >
+        {sliderType === 'graphics' && emoji}
+      </div>
+    </div>
+  );
+}
+```

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.