@explorer02/cfm-survey-sdk 0.1.1 → 0.1.3

package/templates/AGENT.md

@@ -72,9 +72,14 @@ npm install @explorer02/cfm-survey-sdk @tanstack/react-query
 >    ```
 > 3. Tell the client in chat: *"I am launching a premium interactive setup page in your browser. Please customize your survey preferences and logo there, then click Complete Setup."*
 > 4. The wizard will open in the browser. The client will answer the questions and upload their logo there. **You do not need to do anything while the wizard is running — just wait.**
-> 5. When `npx cfm-sdk init` exits (the terminal returns to a prompt), **immediately** read `./survey-config.json` and proceed to Phase 3.
-> 6. **Do NOT ask the client to invoke you again.** Continue automatically.
+> 5. When `npx cfm-sdk init` exits (the terminal returns to a prompt), **immediately** read `./survey-config.json` and proceed.
 
+### Phase 2b: Request Instance ID (STRICT REQUIREMENT)
+
+Before proceeding to Phase 3, you **MUST STRICTLY ASK THE CLIENT** for the Survey Instance ID input:
+*"Please provide the Instance ID (JWT Token) for your survey so I can configure the fetch logic."*
+
+**DO NOT proceed with code generation** or build the SurveyPage until the client provides this Instance ID in the chat!
 
 ### Phase 3: Configuration Setup
 
@@ -298,39 +303,213 @@ type Survey = {
 type SurveyPageData = {
   id: string;                    // Unique page identifier
   title?: string;                // Optional page title
-  questions: SurveyQuestion[];   // Questions on this page
+  questions: SurveyQuestion[];   // Questions on this page (discriminated union — see below)
 };
 
-// ── Question Structure ─────────────────────────────────
-type SurveyQuestion = {
+// ── Question Structure (Discriminated Union) ───────────
+// Use question.type as the discriminant to narrow to the correct variant.
+type SurveyQuestion =
+  | RatingQuestion
+  | RadioQuestion
+  | TextQuestion
+  | MatrixQuestion
+  | RatingMatrixQuestion
+  | SliderMatrixQuestion
+  | TextAndMediaQuestion
+  | CsatQuestion
+  | SliderQuestion
+  | RatingScaleQuestion
+  | FileUploadQuestion;
+
+// ── Base fields (present on ALL question variants) ─────
+type QuestionBase = {
   id: string;                    // ⚠️ CRITICAL: Must be used as HTML element ID for scroll navigation
   text: string;                  // Question text (may contain HTML — render with dangerouslySetInnerHTML)
-  type: 'rating' | 'radio' | 'text';  // Determines which input component to render
-
-  // Options (for 'rating' and 'radio' types)
-  options: SurveyOption[];
+  required?: boolean;            // Whether the question must be answered
+  requiredErrorMessage?: string; // Custom validation error message
+  questionNumber?: string;       // E.g. "Q1", "1." to display before the title
+  containerMediaUrl?: string;    // Media to display alongside the question block
+  containerMediaMimeType?: string;
+  containerMediaAlignment?: 'left' | 'right' | 'top' | 'bottom';
+  containerMediaSize?: 'small' | 'medium' | 'large' | 'full';
+};
 
-  // Rating scale labels (for 'rating' type only)
+// ── type: 'rating' (NPS scale / numeric rating) ────────
+type RatingQuestion = QuestionBase & {
+  type: 'rating';
+  options: SurveyOption[];       // Numeric badge options (0–10 for NPS)
   minLabel?: string;             // Label for the minimum end (e.g., "Not Likely")
   midLabel?: string;             // Label for the middle point
   maxLabel?: string;             // Label for the maximum end (e.g., "Extremely Likely")
-  midLabelIndex?: number;        // Position index for the mid label
+  midLabelIndex?: number;        // CSS position index for the mid label
+  reverseScaleOrder?: boolean;   // If true, render high to low
+  buttonVariant?: 'radio' | 'numbered' | 'emoji'; // Render style for rating options
+};
 
-  // Validation
-  required?: boolean;            // Whether the question must be answered
-  requiredErrorMessage?: string; // Custom validation error message
+// ── type: 'radio' (MCQ single-select or multi-select) ──
+type RadioQuestion = QuestionBase & {
+  type: 'radio';
+  options: SurveyOption[];       // Selectable answer choices
+  isMultiSelect?: boolean;       // If true, render checkboxes and map answer as an array
+};
 
-  // Text input specific
+// ── type: 'text' (short or long text field) ────────────
+type TextQuestion = QuestionBase & {
+  type: 'text';
   maxCharacterCount?: number;    // Character limit for text inputs
-  placeholder?: string;         // Placeholder text for text inputs
+  placeholder?: string;         // Placeholder hint for the input field
+};
+
+// ── type: 'csat' (CSAT 1-5 satisfaction) ───────────────
+type CsatQuestion = QuestionBase & {
+  type: 'csat';
+  options: SurveyOption[];
+  minLabel?: string;
+  maxLabel?: string;
+  buttonType?: SurveyButtonType; // 'emoji' | 'star' | 'radio' | etc.
+  hasNotApplicable?: boolean;    // If true, render N/A option
+  reverseScaleOrder?: boolean;
+  labelPosition?: 'top' | 'bottom' | 'hidden';
+};
+
+// ── type: 'slider' (Standalone Slider) ─────────────────
+type SliderQuestion = QuestionBase & {
+  type: 'slider';
+  min: number;
+  max: number;
+  step: number;
+  defaultValue?: number;
+  minLabel?: string;
+  maxLabel?: string;
+  enableInputBox?: boolean;      // If true, show numeric input alongside slider
+  tickValues?: TickValue[];      // Ticks/markers to display on the slider track
+  displayValues?: number[];      // Which tick values should have labels rendered
+};
+
+// ── type: 'rating_scale' (Stars / Emojis) ──────────────
+type RatingScaleQuestion = QuestionBase & {
+  type: 'rating_scale';
+  options: SurveyOption[];
+  minLabel?: string;
+  midLabel?: string;
+  maxLabel?: string;
+  midLabelIndex?: number;
+  scaleStyle?: 'star' | 'emoji'; // Icon style to render
+  reverseScaleOrder?: boolean;
+};
+
+// ── type: 'file_upload' (File attachments) ─────────────
+// Submit target is quesIdVsAttachmentDetails mapping instead of questionToAnswers
+type FileUploadQuestion = QuestionBase & {
+  type: 'file_upload';
+  uploadMessage?: string;        // Instructions above dropzone
+  supportedFileFormats?: string[]; // E.g. ['PNG', 'PDF', 'DOCX']
+  maxFileCount?: number;         // Max files allowed
+  fileSizeLimit?: number;        // Size limit in MB
+  fileSizeLimitType?: 'PER_FILE' | 'IN_TOTAL';
+};
+
+// ── type: 'matrix' (CFM_MATRIX / CSAT_MATRIX) ─────────
+// Grid of rows × columns; respondent selects one column per row.
+// CHANGE payload value: Record<rowId, columnValue>
+type MatrixQuestion = QuestionBase & {
+  type: 'matrix';
+  subType: 'CFM_MATRIX' | 'CSAT_MATRIX';
+  rows: MatrixRow[];             // Row sub-questions (one per grid row)
+  columns: MatrixColumn[];       // Column header options (shared across all rows)
+  buttonType?: SurveyButtonType; // For CSAT_MATRIX icon styling
+  hasNotApplicable?: boolean;
+  reverseScaleOrder?: boolean;
+  labels?: string[];             // General hints
+};
+
+// ── type: 'rating_matrix' (RATING_MATRIX) ─────────────
+// Grid of rows × rating-scale columns with optional NPS-style colors.
+// CHANGE payload value: Record<rowId, columnValue>
+type RatingMatrixQuestion = QuestionBase & {
+  type: 'rating_matrix';
+  rows: MatrixRow[];
+  columns: MatrixColumn[];       // Columns may carry color hints (like NPS)
+  minLabel?: string;
+  maxLabel?: string;
 };
 
+// ── type: 'slider_matrix' (SLIDER_MATRIX) ─────────────
+// Grid of rows, each with its own slider; respondent drags a handle per row.
+// CHANGE payload value: Record<rowId, numericValue>
+type SliderMatrixQuestion = QuestionBase & {
+  type: 'slider_matrix';
+  rows: SliderMatrixRow[];       // Each row carries its own min/max/step
+};
+
+// ── type: 'text_and_media' (TEXT_AND_MEDIA) ───────────
+// Display-only card. No answer recorded. Excluded from validation and progress %.
+// Do NOT dispatch a CHANGE action for this type.
+type TextAndMediaQuestion = QuestionBase & {
+  type: 'text_and_media';
+  mediaUrl?: string;             // Image or video URL to display
+  mediaMimeType?: string;        // e.g. 'image/png', 'video/mp4'
+  mediaTitle?: string;           // Optional media caption
+};
+
+// ── Primitive types ────────────────────────────────────
 type SurveyOption = {
+  id?: string;                   // Internal ID
   label: string;                 // Display text for the option
-  value: string | number;        // Actual value sent on submission
-  color?: string;                // Optional color (used for rating scale badges)
+  value: string | number | null; // Actual value sent on submission
+  color?: string;                // Optional color (NPS rating badges)
+};
+
+type MatrixRow = {
+  id: string;                    // Row sub-question ID (key in answer map)
+  text: string;                  // Display label for the row
+};
+
+type MatrixColumn = {
+  id: string;                    // Column identifier
+  label: string;                 // Display text for the column header
+  value: string | number | null; // Value recorded when this column is selected
+  color?: string;                // Optional color hint (rating_matrix)
 };
 
+type SliderMatrixRow = MatrixRow & {
+  min: number;                   // Slider minimum (default: 0)
+  max: number;                   // Slider maximum (default: 10)
+  step: number;                  // Slider step increment (default: 1)
+  defaultValue?: number;         // Optional initial slider position
+  enableInputBox?: boolean;      // If true, render numeric input next to slider
+  displayValues?: number[];      // Tick marks
+};
+
+type TickValue = {
+  value: number;
+  label?: string;
+};
+
+type UploadedFile = {
+  id: string;
+  name: string;
+  mediaUrl: string;
+  mimeType?: string;
+  size?: number;
+};
+
+type SurveyButtonType =
+  | 'radio'
+  | 'checkbox'
+  | 'numbered'
+  | 'emoji'
+  | 'star'
+  | 'graphics'
+  | 'dropdown'
+  | 'selectbox'
+  | 'matrix';
+
+// ── Answer value types ─────────────────────────────────
+// Used in state.values and onAction CHANGE payload.
+type MatrixAnswerMap = Record<string, string | number>;  // rowId → selectedValue
+type AnswerValue = string | number | (string | number)[] | MatrixAnswerMap | UploadedFile[];
+
 // ── Language Structure ─────────────────────────────────
 type SurveyLanguage = {
   code: string;                  // Language code (e.g., 'en', 'de')
@@ -338,6 +517,24 @@ type SurveyLanguage = {
 };
 ```
 
+
+#### CHANGE action value by question type
+
+| `question.type` | `value` in `onAction({ type: 'CHANGE', payload: { questionId, value } })` | Notes |
+|---|---|---|
+| `'rating'` | `number` | NPS 0–10 badge selection |
+| `'radio'` | `string \| number \| (string \| number)[]` | option's `.value`, or array of values if `isMultiSelect` |
+| `'text'` | `string` | typed text |
+| `'csat'` | `number \| string \| null` | selected satisfaction value or `null` if N/A |
+| `'slider'` | `number` | slider handle position |
+| `'rating_scale'` | `number` | selected star/icon value |
+| `'file_upload'` | `UploadedFile[]` | array of successfully uploaded file descriptors |
+| `'matrix'` | `Record<rowId, columnValue>` | full map of all row answers |
+| `'rating_matrix'` | `Record<rowId, columnValue>` | full map of all row answers |
+| `'slider_matrix'` | `Record<rowId, numericValue>` | full map of all slider positions |
+| `'text_and_media'` | ❌ **Do not dispatch CHANGE** | display-only, no answer |
+
+
 ### 3e. How the SDK Works Internally (Context for the Agent)
 
 1. **Data Fetching**: The SDK uses `@tanstack/react-query` with an internal singleton `QueryClient`. The client does NOT need to wrap their app in a `QueryClientProvider` — the SDK manages this automatically.
@@ -435,12 +632,17 @@ const SURVEY_PLACEHOLDERS = {
 export default function SurveyPage() {
   const [selectedLanguage, setSelectedLanguage] = useState<string | undefined>("");
 
+  // ⚠️ MANDATORY: Pass the exact Instance ID that the client provided to you in the chat!
+  // The SDK will only fetch the survey data once this valid instance ID is passed.
+  const INPUT_OPTIONS = {
+    instanceId: '<<REPLACE_WITH_CLIENT_PROVIDED_INSTANCE_ID>>',
+    language: selectedLanguage,
+    debug: false,
+    placeholders: SURVEY_PLACEHOLDERS,
+  };
+
   const { surveyQueryResults, submitSurveyResults, state, onAction } = useSurveySDK({
-    options: {
-      language: selectedLanguage,
-      debug: false,
-      placeholders: SURVEY_PLACEHOLDERS,
-    },
+    options: INPUT_OPTIONS
   });
 
   const survey = surveyQueryResults.data;
@@ -587,14 +789,19 @@ export default function SurveyPage() {
 **⚠️ CRITICAL**: The outermost element MUST have `id={question.id}`. This enables the SDK's scroll-to-error and page-transition scroll features.
 
 ```tsx
-import type { SurveyQuestion } from '@explorer02/cfm-survey-sdk';
+import type { SurveyQuestion, AnswerValue, MatrixAnswerMap } from '@explorer02/cfm-survey-sdk';
 import RatingScale from './RatingScale';
+import CsatScale from './CsatScale';
+import LikertMatrixScale from './LikertMatrixScale';
+import CsatMatrixScale from './CsatMatrixScale';
+import SliderMatrixScale from './SliderMatrixScale';
+import FileUploadScale from './FileUploadScale';
 
 type QuestionProps = {
   question: SurveyQuestion;
-  selectedValue?: string | number;
+  selectedValue?: AnswerValue;
   validationError?: string;
-  onSelect: (value: string | number) => void;
+  onSelect: (value: AnswerValue) => void;
 };
 
 export default function Question({ question, selectedValue, validationError, onSelect }: QuestionProps) {
@@ -603,15 +810,17 @@ export default function Question({ question, selectedValue, validationError, onS
     // Do NOT modify, prefix, or omit this ID.
     <section id={question.id}>
 
-      {/* Question Title
+      {/* Question Title — skip for text_and_media (may be display-only card)
           ⚠️ MANDATORY: Use dangerouslySetInnerHTML — question.text may contain HTML markup. */}
-      <h2>
-        <span dangerouslySetInnerHTML={{ __html: question.text }} />
-        {question.required && (
-          /* STYLE: Design a required indicator (e.g., red asterisk, "(required)" label) */
-          <span>*</span>
-        )}
-      </h2>
+      {question.type !== 'text_and_media' && (
+        <h2>
+          <span dangerouslySetInnerHTML={{ __html: question.text }} />
+          {question.required && (
+            /* STYLE: Design a required indicator (e.g., red asterisk, "(required)" label) */
+            <span>*</span>
+          )}
+        </h2>
+      )}
 
       {/* ── RATING TYPE ─────────────────────────────────── */}
       {question.type === 'rating' && (
@@ -642,7 +851,7 @@ export default function Question({ question, selectedValue, validationError, onS
           <RatingScale
             questionId={question.id}
             options={question.options}
-            selectedValue={selectedValue}
+            selectedValue={typeof selectedValue === 'number' || typeof selectedValue === 'string' ? selectedValue : undefined}
             onSelect={onSelect}
           />
         </div>
@@ -679,12 +888,32 @@ export default function Question({ question, selectedValue, validationError, onS
         </div>
       )}
 
+      {/* ── CSAT TYPE ────────────────────────────────────── */}
+      {question.type === 'csat' && (
+        <div>
+          {/* Scale Endpoint Labels */}
+          {(question.minLabel || question.maxLabel) && (
+            <div>
+              {question.minLabel && <span dangerouslySetInnerHTML={{ __html: question.minLabel }} />}
+              {question.maxLabel && <span dangerouslySetInnerHTML={{ __html: question.maxLabel }} />}
+            </div>
+          )}
+
+          {/* CsatScale Component is imported from @repo/sdk! */}
+          <CsatScale
+            question={question}
+            selectedValue={selectedValue as string | number | null}
+            onSelect={onSelect}
+          />
+        </div>
+      )}
+
       {/* ── TEXT TYPE ────────────────────────────────────── */}
       {question.type === 'text' && (
         <div>
           <textarea
             rows={4}
-            value={selectedValue ?? ''}
+            value={typeof selectedValue === 'string' ? selectedValue : ''}
             onChange={e => onSelect(e.target.value)}
             placeholder={question.placeholder || 'Type your response here...'}
             /* STYLE: Design the textarea to match the mockup.
@@ -705,6 +934,73 @@ export default function Question({ question, selectedValue, validationError, onS
         </div>
       )}
 
+      {/* ── MATRIX TYPE (CFM_MATRIX / CSAT_MATRIX) ──────── */}
+      {question.type === 'matrix' && (
+        <CsatMatrixScale
+          question={question}
+          selectedValue={selectedValue as MatrixAnswerMap}
+          onSelect={onSelect}
+        />
+      )}
+
+      {/* ── RATING MATRIX TYPE ───────────────────────────── */}
+      {question.type === 'rating_matrix' && (
+        <LikertMatrixScale
+          question={question}
+          selectedValue={selectedValue as MatrixAnswerMap}
+          onSelect={onSelect}
+        />
+      )}
+
+      {/* ── SLIDER MATRIX TYPE ───────────────────────────── */}
+      {question.type === 'slider_matrix' && (
+        <SliderMatrixScale
+          question={question}
+          selectedValue={selectedValue as MatrixAnswerMap}
+          onSelect={onSelect}
+        />
+      )}
+
+      {/* ── FILE UPLOAD TYPE ─────────────────────────────── */}
+      {question.type === 'file_upload' && (
+        <FileUploadScale
+          question={question}
+          selectedValue={selectedValue}
+          onSelect={onSelect}
+        />
+      )}
+
+      {/* ── TEXT AND MEDIA TYPE ──────────────────────────── */}
+      {question.type === 'text_and_media' && (
+        <div>
+          {/* Question text (informational content) */}
+          {question.text && (
+            <div dangerouslySetInnerHTML={{ __html: question.text }} />
+          )}
+
+          {/* Media — render image or video based on mediaMimeType */}
+          {question.mediaUrl && (
+            question.mediaMimeType?.startsWith('video') ? (
+              <video
+                src={question.mediaUrl}
+                controls
+                /* STYLE: Constrain max width, add rounded corners, etc. */
+              />
+            ) : (
+              <img
+                src={question.mediaUrl}
+                alt={question.mediaTitle ?? ''}
+                /* STYLE: Responsive image sizing */
+              />
+            )
+          )}
+
+          {/* Optional caption */}
+          {question.mediaTitle && <p>{question.mediaTitle}</p>}
+          {/* NOTE: No onSelect call — this is display-only. The SDK skips this in validation. */}
+        </div>
+      )}
+
       {/* Validation Error — display when the SDK flags a required question as unanswered */}
       {validationError && (
         /* STYLE: Design a visible error message.
@@ -719,6 +1015,8 @@ export default function Question({ question, selectedValue, validationError, onS
 }
 ```
 
+
+
 ---
 
 ### Logic Skeleton: `RatingScale.tsx` — Rating Input
@@ -759,6 +1057,339 @@ export default function RatingScale({ questionId, options, selectedValue, onSele
 
 ---
 
+### Logic Skeleton: `CsatScale.tsx` — CSAT Satisfaction Input
+
+```tsx
+import type { CsatQuestion } from '@explorer02/cfm-survey-sdk';
+import { getEmojiForIndex, CsatStarIcons } from '@explorer02/cfm-survey-sdk';
+
+type CsatScaleProps = {
+  question: CsatQuestion;
+  selectedValue: string | number | null;
+  onSelect: (value: string | number | null) => void;
+};
+
+export default function CsatScale({ question, selectedValue, onSelect }: CsatScaleProps) {
+  const { options, buttonType, hasNotApplicable, reverseScaleOrder } = question;
+
+  return (
+    <div>
+      {/* STYLE: Design a horizontal layout for CSAT options. */}
+      <div>
+        {options.map((option, index) => {
+          const isSelected = selectedValue === option.value;
+          
+          return (
+            <button
+              key={option.value}
+              type="button"
+              onClick={() => onSelect(option.value)}
+              /* STYLE: Style selected vs unselected states */
+            >
+              {buttonType === 'emoji' && (
+                 /* ⚠️ SDK provides getEmojiForIndex helper! */
+                 <span dangerouslySetInnerHTML={{ __html: getEmojiForIndex(index, options.length, reverseScaleOrder) }} />
+              )}
+              {buttonType === 'star' && (
+                 <span dangerouslySetInnerHTML={{ __html: CsatStarIcons[isSelected ? 'filled' : 'empty'] }} />
+              )}
+              {/* Default fallback for other buttonTypes */}
+              {buttonType !== 'emoji' && buttonType !== 'star' && (
+                <span>{option.label}</span>
+              )}
+            </button>
+          );
+        })}
+      </div>
+
+      {hasNotApplicable && (
+        <label>
+          <input 
+            type="checkbox" 
+            checked={selectedValue === null} 
+            onChange={() => onSelect(selectedValue === null ? undefined : null)} 
+          />
+          <span>Not Applicable</span>
+        </label>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+### Logic Skeleton: `CsatMatrixScale.tsx` — Responsive Grid
+
+```tsx
+import type { MatrixQuestion, MatrixAnswerMap } from '@explorer02/cfm-survey-sdk';
+
+type CsatMatrixScaleProps = {
+  question: MatrixQuestion;
+  selectedValue?: MatrixAnswerMap;
+  onSelect: (value: MatrixAnswerMap) => void;
+};
+
+export default function CsatMatrixScale({ question, selectedValue = {}, onSelect }: CsatMatrixScaleProps) {
+  const { rows, columns, hasNotApplicable } = question;
+
+  const handleCellSelect = (rowId: string, colValue: any) => {
+    onSelect({ ...selectedValue, [rowId]: colValue });
+  };
+
+  return (
+    <div>
+      {/* STYLE: Create a responsive layout.
+          On desktop, show a standard table/grid.
+          On mobile, stack the rows vertically and use a dropdown or list. */}
+          
+      {rows.map(row => (
+        <div key={row.id}>
+          <h3 dangerouslySetInnerHTML={{ __html: row.text }} />
+          
+          {/* Mobile view example: Dropdown */}
+          <div className="md:hidden">
+            <select
+              value={selectedValue[row.id] ?? ''}
+              onChange={(e) => handleCellSelect(row.id, e.target.value)}
+            >
+               <option value="" disabled>Select...</option>
+               {columns.map(col => (
+                 <option key={col.id} value={col.value}>{col.label}</option>
+               ))}
+            </select>
+          </div>
+
+          {/* Desktop view example: Row of buttons */}
+          <div className="hidden md:flex">
+            {columns.map(col => (
+               <button 
+                 key={col.id}
+                 type="button"
+                 onClick={() => handleCellSelect(row.id, col.value)}
+               >
+                 {col.label}
+               </button>
+            ))}
+          </div>
+
+          {hasNotApplicable && (
+            <label>
+              <input 
+                type="checkbox" 
+                checked={selectedValue[row.id] === null}
+                onChange={() => handleCellSelect(row.id, selectedValue[row.id] === null ? undefined : null)} 
+              />
+              N/A
+            </label>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+### Logic Skeleton: `LikertMatrixScale.tsx`
+
+```tsx
+import type { MatrixQuestion, MatrixAnswerMap } from '@explorer02/cfm-survey-sdk';
+
+type LikertMatrixScaleProps = {
+  question: MatrixQuestion;
+  selectedValue?: MatrixAnswerMap;
+  onSelect: (value: MatrixAnswerMap) => void;
+};
+
+export default function LikertMatrixScale({ question, selectedValue = {}, onSelect }: LikertMatrixScaleProps) {
+  const { rows, columns } = question;
+
+  const handleCellSelect = (rowId: string, colValue: any) => {
+    onSelect({ ...selectedValue, [rowId]: colValue });
+  };
+
+  return (
+    <table>
+      <thead>
+        <tr>
+          <th />
+          {columns.map(col => (
+             <th key={col.id} style={{ color: col.color }}>{col.label}</th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map(row => (
+          <tr key={row.id}>
+            <td><span dangerouslySetInnerHTML={{ __html: row.text }} /></td>
+            {columns.map(col => (
+              <td key={col.id}>
+                <button
+                  type="button"
+                  onClick={() => handleCellSelect(row.id, col.value)}
+                  style={{ backgroundColor: selectedValue[row.id] === col.value ? col.color : undefined }}
+                >
+                  {col.label}
+                </button>
+              </td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+```
+
+---
+
+### Logic Skeleton: `SliderMatrixScale.tsx`
+
+```tsx
+import type { SliderMatrixQuestion, MatrixAnswerMap } from '@explorer02/cfm-survey-sdk';
+
+type SliderMatrixScaleProps = {
+  question: SliderMatrixQuestion;
+  selectedValue?: MatrixAnswerMap;
+  onSelect: (value: MatrixAnswerMap) => void;
+};
+
+export default function SliderMatrixScale({ question, selectedValue = {}, onSelect }: SliderMatrixScaleProps) {
+  const handleSliderChange = (rowId: string, val: number) => {
+    onSelect({ ...selectedValue, [rowId]: val });
+  };
+
+  return (
+    <div>
+      {question.rows.map(row => {
+        const currentVal = typeof selectedValue[row.id] === 'number' 
+          ? selectedValue[row.id] as number 
+          : row.defaultValue ?? row.min;
+          
+        return (
+          <div key={row.id}>
+            <div dangerouslySetInnerHTML={{ __html: row.text }} />
+            
+            {/* Custom Slider logic: Calculate percentage fill */}
+            <div style={{ position: 'relative' }}>
+              <input
+                 type="range"
+                 min={row.min} max={row.max} step={row.step}
+                 value={currentVal}
+                 onChange={(e) => handleSliderChange(row.id, Number(e.target.value))}
+                 style={{ zIndex: 10, width: '100%', position: 'absolute', opacity: 0 }}
+                 /* STYLE: Make the native input invisible but keep it on top for interaction */
+              />
+              {/* STYLE: Build a custom visible track and thumb behind the transparent native input */}
+              <div style={{ width: '100%', height: '8px', backgroundColor: '#e5e7eb' }}>
+                <div style={{ width: `${((currentVal - row.min) / (row.max - row.min)) * 100}%`, height: '100%', backgroundColor: 'var(--brand-color)' }} />
+              </div>
+            </div>
+            
+            {row.enableInputBox && (
+              <input 
+                type="number" 
+                value={currentVal} 
+                onChange={(e) => handleSliderChange(row.id, Number(e.target.value))} 
+              />
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+```
+
+---
+
+### Logic Skeleton: `FileUploadScale.tsx`
+
+```tsx
+import { useState, useRef } from 'react';
+import type { FileUploadQuestion } from '@explorer02/cfm-survey-sdk';
+
+export default function FileUploadScale({ question, selectedValue, onSelect }: { question: FileUploadQuestion, selectedValue: any, onSelect: any }) {
+  const { maxFileCount = 1, fileSizeLimit = 10, fileSizeLimitType, supportedFileFormats = [], uploadMessage } = question;
+  const [isDragActive, setIsDragActive] = useState(false);
+  const [error, setError] = useState('');
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  const currentFiles: File[] = Array.isArray(selectedValue) ? selectedValue : [];
+
+  const handleFiles = (files: FileList) => {
+    setError('');
+    const newFiles = Array.from(files);
+    
+    // Validate count
+    if (currentFiles.length + newFiles.length > maxFileCount) {
+      setError(`Maximum ${maxFileCount} files allowed.`);
+      return;
+    }
+    
+    // Validate extensions & size
+    for (const file of newFiles) {
+      const ext = file.name.split('.').pop()?.toUpperCase() || '';
+      if (supportedFileFormats.length > 0 && !supportedFileFormats.includes(ext)) {
+        setError(`File type .${ext} not supported.`);
+        return;
+      }
+      if (fileSizeLimitType === 'PER_FILE' && file.size > fileSizeLimit * 1024 * 1024) {
+        setError(`File exceeds limit of ${fileSizeLimit}MB.`);
+        return;
+      }
+    }
+    
+    onSelect([...currentFiles, ...newFiles]);
+  };
+
+  const handleDrop = (e: React.DragEvent) => {
+    e.preventDefault(); setIsDragActive(false);
+    if (e.dataTransfer.files) handleFiles(e.dataTransfer.files);
+  };
+
+  const handleDragOver = (e: React.DragEvent) => {
+    e.preventDefault(); setIsDragActive(true);
+  };
+
+  return (
+    <div>
+       <input 
+         type="file" 
+         hidden ref={fileInputRef} 
+         onChange={(e) => e.target.files && handleFiles(e.target.files)}
+         multiple={maxFileCount > 1}
+       />
+       
+       <div 
+         onDrop={handleDrop} 
+         onDragOver={handleDragOver} 
+         onDragLeave={() => setIsDragActive(false)}
+         onClick={() => fileInputRef.current?.click()}
+         /* STYLE: Apply dashed border, drag active state styles */
+       >
+         <span dangerouslySetInnerHTML={{ __html: uploadMessage || 'Drag and drop files here' }} />
+       </div>
+       
+       {error && <div /* STYLE: Error message styling */>{error}</div>}
+       
+       <div>
+         {currentFiles.map((f, i) => (
+           <div key={i}>
+             {f.name} ({(f.size / 1024 / 1024).toFixed(2)} MB)
+             <button type="button" onClick={() => onSelect(currentFiles.filter((_, idx) => idx !== i))}>Remove</button>
+           </div>
+         ))}
+       </div>
+    </div>
+  );
+}
+```
+
+---
+
 ### Logic Skeleton: `LanguageSelector.tsx`
 
 ```tsx