@explorer02/cfm-survey-sdk 0.1.6 → 0.1.8

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

@@ -1,11 +1,14 @@
-# Survey Page Orchestrator
+# Survey Page Orchestrator Architectural Blueprint
 
-> **Source**: `apps/client/src/components/SurveyPage.tsx`
-> **Role**: The main entry point that wires the UI to the `useSurveySDK` hook.
+> **Target Component**: `SurveyPage`
+> **Role**: The main entry point that wires the UI to the `useSurveySDK` hook, manages loading/error states, orchestrates pagination, and controls submission.
 
-## Setup & Wiring
+## Core Responsibility
+This component MUST act as the state machine for the entire survey flow. It should never render questions directly—it delegates that to `Question.tsx`.
 
-The component must pass the `options` to `useSurveySDK`, including the **instanceId** provided by the client prompt.
+## Setup & Wiring (CRITICAL)
+
+The component MUST invoke `useSurveySDK`, passing the **instanceId** from the client prompt.
 
 ```tsx
 const SURVEY_PLACEHOLDERS = { FIRST_NAME: 'Customer' }; // Must be outside component!
@@ -24,52 +27,40 @@ export default function SurveyPage() {
   
   const survey = surveyQueryResults.data;
   
-  // ... render states
+  // ... state machine rendering
 }
 ```
 
-## The 5 Render States
+## The 5 State Machine Renders (MANDATORY)
 
-A complete `SurveyPage` must handle 5 distinct rendering states in this exact order:
+You MUST structure your render logic to strictly handle these 5 states in order to avoid UI crashes when data is not yet available.
 
 ### 1. Loading State
-```tsx
-if (surveyQueryResults.isLoading) {
-  return <LoadingView /> // Header, Footer, and a "Loading..." message
-}
-```
+If `surveyQueryResults.isLoading` is true, render a Skeleton or Spinner.
+*Include your CSS-only Header and Footer around the spinner.*
 
 ### 2. Error State
-```tsx
-if (surveyQueryResults.error) {
-  return <ErrorView error={surveyQueryResults.error.message} /> 
-}
-```
+If `surveyQueryResults.error` is true, render a red Error banner containing `surveyQueryResults.error.message`.
 
 ### 3. Empty State
-```tsx
-if (!survey) {
-  return <EmptyView /> // Header, Footer, and a "No survey data" message
-}
-```
+If `!survey`, render a generic "Survey not found" message.
 
 ### 4. Submitted State
-```tsx
-if (submitSurveyResults.data) {
-  return <SubmitSummaryView /> // Header, Footer, and a "Thank you" message
-}
-```
+If `submitSurveyResults.data` exists, the survey is complete.
+*Render the Thank You Screen (e.g., "Thank you for your feedback!"). Do not render the question list.*
 
 ### 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
+If the above 4 conditions are met, render the active survey page:
+1. `Header` (Logo)
+2. `ProgressBar` (Pass `state.progressPercentage`)
+3. `LanguageSelector` (Pass `survey.languages`, `survey.language`, `setSelectedLanguage`)
+4. **The Question Map** (See below)
+5. **Navigation Buttons** (See below)
 6. `Footer`
 
-## Question Mapping Pattern
+## The Question Map
+
+You MUST iterate over `state.currentQuestions` and dispatch to `Question.tsx`.
 
 ```tsx
 <div className="space-y-12">
@@ -88,26 +79,13 @@ The main render path. Must include:
 </div>
 ```
 
-## Navigation Buttons Pattern
+## Navigation Buttons Logic
 
-```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>
-```
+You MUST conditionally render "Back" and "Next/Submit" buttons. 
+
+- **Back Button**: Hide if `state.currentPageIndex === 0`.
+  - `onClick={() => onAction({ type: 'PREVIOUS' })}`
+- **Next/Submit Button**:
+  - `disabled={submitSurveyResults.isLoading}`
+  - If `state.currentPageIndex < survey.pages.length - 1`, label is "Next", action is `type: 'NEXT'`.
+  - If on the last page, label is "Submit", action is `type: 'NEXT'` (the SDK intercepts NEXT on the last page to trigger submission automatically!).

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

@@ -1,50 +1,98 @@
-# Question Dispatcher
+# Question Dispatcher Architectural Blueprint
 
-> **Source**: `apps/client/src/components/Question.tsx`
-> **Role**: Wrapper card component that routes to the correct scale component based on question type.
+> **Target Component**: `Question`
+> **Role**: Wrapper card component that routes to the correct scale component based on `question.type`.
 
-## Props Interface
+## Core Responsibility
+Render a visually separated container (card) for each question. Handle rich text parsing, required asterisks, description text, and error validation messages. Most importantly, it MUST act as an exhaustive switch statement dispatching to ALL supported question types.
 
-```typescript
-type QuestionProps = {
-  question: SurveyQuestion;
-  selectedValue?: AnswerValue;
-  validationError?: string;
-  onSelect: (value: AnswerValue) => void;
-};
-```
+## Exhaustive Dispatcher Logic (CRITICAL)
+
+The agent MUST handle EVERY SINGLE ONE of these `question.type` values. Failure to handle them will result in blank UI or broken surveys.
+
+1. **`rating`**: Renders `RatingScale`. This covers NPS, Stars, Emoji, and generic numeric scales.
+2. **`csat`**: Renders `CsatScale`. This covers CSAT specific faces/icons.
+3. **`radio`**: Renders inline MCQ radio buttons. (Can be implemented inside this file or separately).
+4. **`text`**: Renders an inline `<textarea>` or `<input>`.
+5. **`matrix`**: 
+   - If `subType === 'CFM_MATRIX'`, render `LikertMatrixScale`
+   - If `subType === 'CSAT_MATRIX'` or `'RATING_MATRIX'`, render `CsatMatrixScale`
+6. **`slider_matrix`**: Renders `SliderMatrixScale`
+7. **`file_upload`**: Renders `FileUploadScale`
+8. **`text_and_media`**: Renders inline `<video>` or `<img>` based on `question.mediaUrl`. 
+   - *Note: `text_and_media` questions may NOT have user input. Do not render a scale for them.*
+
+## Container UI Structure
+
+Every question MUST be wrapped in a standard HTML `<section>` to visually separate it.
+
+1. **Wrapper styling**: 
+   - Border: `border border-gray-200`
+   - Radius: `rounded-xl`
+   - Background: `bg-white`
+   - Padding: `p-6 md:p-8`
+   - Shadow & Hover: `shadow-sm transition-all hover:shadow-md`
+   - **Crucial**: ID must be set to `question.id` (`id={question.id}`) so scroll-to-error works!
+
+2. **Heading (`question.text`)**:
+   - MUST use `dangerouslySetInnerHTML={{ __html: question.text }}` because text from Sprinklr contains rich HTML (bold, links, italics).
+   - If `question.required === true`, append a red asterisk `*`.
+
+3. **Description (`question.description`)**:
+   - Render conditionally if `question.description` exists.
+   - MUST use `dangerouslySetInnerHTML`.
+   - Style with slightly smaller text, greyish color (e.g., `text-sm text-gray-600 mt-2`).
+
+4. **Validation Error Banner**:
+   - If `validationError` prop is passed, render a highly visible banner below the scale.
+   - Example: Red border-left, red background, bold text.
 
-## Structure & Styling Rules (CRITICAL)
+## Hover Tooltips & Micro-interactions
+- Focus states on text inputs MUST use the brand primary color (e.g., magenta `#e20074` for Telekom).
+- Radio button wrappers should have a subtle background hover effect (e.g., `hover:bg-pink-50`).
 
-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.
+## Example Architectural Skeleton
 
 ```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) */}
+<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">
+  
+  {/* HEADING */}
   <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) */}
+  {/* DESCRIPTION */}
   {question.description && (
-    <div 
-      className="text-sm text-gray-600 mt-2 leading-relaxed prose prose-sm max-w-none" 
-      dangerouslySetInnerHTML={{ __html: 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) */}
+  {/* DISPATCHER */}
   <div className="pt-4">
     {question.type === 'rating' && <RatingScale ... />}
-    {/* ... other types ... */}
+    {question.type === 'csat' && <CsatScale ... />}
+    {question.type === 'slider_matrix' && <SliderMatrixScale ... />}
+    {question.type === 'file_upload' && <FileUploadScale ... />}
+    {question.type === 'matrix' && question.subType === 'CFM_MATRIX' && <LikertMatrixScale ... />}
+    {question.type === 'matrix' && (question.subType === 'CSAT_MATRIX' || question.subType === 'RATING_MATRIX') && <CsatMatrixScale ... />}
+    
+    {question.type === 'radio' && (
+       // Inline Radio implementation
+       // Make sure to match brand hover colors!
+    )}
+    
+    {question.type === 'text' && (
+       // Inline Textarea implementation
+       // Handle character limit `question.maxCharacterCount`
+    )}
+
+    {question.type === 'text_and_media' && (
+       // Display media (image/video) based on question properties
+       // This handles CONTENT blocks.
+    )}
   </div>
-  
-  {/* 4. Validation Error Banner */}
+
+  {/* 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">
@@ -52,23 +100,6 @@ Every question is wrapped in a standard HTML section. It **MUST** have a border
       </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

@@ -1,91 +1,28 @@
-# Rating Scale Component
+# Rating Scale Architectural Blueprint
 
-> **Component**: `RatingScale`
-> **Handles**: `type: 'rating'` | `type: 'rating_scale'`
+> **Target 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;
-};
-```
+## Core Responsibility
+Render a horizontal sequence of numbered badges. 
 
-## UI Styling & Interaction Rules (CRITICAL)
+## Configuration Matrix
+You MUST handle the following configurations dynamically:
 
-The UI must exactly match these specifications:
+### 1. Color Grading (NPS)
+- Check if `option.color` exists. If so, apply it to the badge background. This is crucial for NPS scales (Red 0-6, Yellow 7-8, Green 9-10).
 
-### 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. Label Positioning (`minLabel`, `midLabel`, `maxLabel`)
+- **Architectural Requirement**: Wrap the badge sequence and the labels in a relative container.
+- Place labels underneath the badges using absolute positioning.
+- **Mid Label Calculation**: You must calculate the exact center position: `style={{ left: \`\${(midLabelIndex / (options.length - 1)) * 100}%\` }}`.
 
-### 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`.
+## UI/UX Rules (CRITICAL)
 
-### 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'.
+The UI must exactly match enterprise standards:
 
-### 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>
-```
+1. **Shape**: Badges MUST be square with rounded corners (`rounded-lg w-10 h-10 sm:w-12 sm:h-12`). Do NOT use full circles (`rounded-full`).
+2. **Unselected State**: If any item is selected, unselected items must dim (`opacity-30`).
+3. **Selected State**: The selected badge MUST pop out prominently: `border-2 border-[#e20074] shadow-md scale-105 opacity-100 font-bold`.
+4. **Hover State**: `hover:scale-105 hover:border-[#e20074] transition-all cursor-pointer`.
+5. **Tooltips**: Every badge MUST have `title={option.label}` applied for accessibility and semantic context (e.g. hovering '10' shows 'Extremely Likely').

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

@@ -1,79 +1,38 @@
-# CSAT Scale Component
+# CSAT & Rating Architectural Blueprints
 
-> **Component**: `CsatScale`
-> **Handles**: `type: 'csat'`
+> **Target Components**: `CsatScale`, `RatingScale`, `CsatMatrixScale`
+> **Handles**: `type: 'csat'`, `'rating'`, `'rating_scale'`, CSAT matrices.
 
-## Props Interface
-```typescript
-type CsatScaleProps = {
-  question: SurveyQuestion & { type: 'csat' };
-  selectedValue?: string | number | null;
-  onSelect: (value: number | null) => void;
-};
-```
+## Core Responsibility
+Render sentiment arrays (Faces, Stars, Numbers) ensuring that active selections are unmistakably highlighted using bounding boxes or strong border accents, NEVER just by changing the SVG fill color.
 
-## UI Styling & Interaction Rules (CRITICAL)
+## State Management & Mapping
+- **Emojis**: `buttonType === 'emoji'`
+  - Map values using `getEmojiForIndex(index, totalLength)` from your icons utility.
+- **Stars**: `buttonType === 'star'`
+  - Active stars (index <= selectedValue) get `CsatStarIcons.filled`.
+- **Numbers**: Default for rating scales.
+  - Apply `option.color` to the background if provided by the SDK (NPS tracking).
 
-The visual rendering heavily depends on `buttonType`. All variants MUST implement strict hover states, tooltips, and distinct active state bounding boxes.
+## UX Bounding Box Rules (CRITICAL)
 
-### 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.
+The UI must exactly match the "Active Box" standard.
 
-### 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`.
+### For Emojis & Stars:
+- **Unselected**: `inline-flex p-2 border-2 border-transparent opacity-40 hover:opacity-100 hover:scale-110 transition-all cursor-pointer`.
+- **Selected**: The specific selected icon MUST be wrapped in a prominent square box with rounded corners.
+  - **CSS**: `border-2 border-[#e20074] rounded-lg p-2 bg-pink-50 shadow-sm scale-110 opacity-100`.
 
-### 3. `buttonType === 'numbered'`
-- Fallback to `RatingScale` style (Square badges).
+### For Numbered Badges (Rating):
+- **Shape**: MUST be square with rounded corners (`rounded-lg w-12 h-12`). Do not use full circles.
+- **Selected**: `border-2 border-[#e20074] opacity-100 font-bold scale-105 shadow-md`.
+- **Unselected**: `opacity-30 border-transparent`.
 
-### 4. `buttonType === 'graphics'`
-- Render a single `<CustomSliderTrack>`.
+## Bounding Boxes inside Matrices
+When emojis or stars are rendered inside `CsatMatrixScale`, the exact same bounding box logic applies. The table cell `<td>` should center the icon, and the icon wrapper `<div>` or `<button>` should toggle between `border-transparent` and `border-[#e20074]` based on the active state.
 
-## 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>
-```
+## Tooltips & Label Positions
+- **Tooltips**: Every single emoji, star, and badge MUST have `title={label}` applied so the user sees the semantic text string on hover.
+- **Labels (`minLabel`, `midLabel`, `maxLabel`)**:
+  - Must be rendered absolutely below the track.
+  - `midLabel` must use inline styles to calculate its exact centered position: `style={{ left: \`\${(midLabelIndex / (options.length - 1)) * 100}%\` }}`.

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

@@ -1,77 +1,33 @@
-# CSAT Matrix Scale Component
+# CSAT Matrix Architectural Blueprint
 
-> **Component**: `CsatMatrixScale`
-> **Handles**: `type: 'matrix'` (CSAT_MATRIX subType) | `type: 'rating_matrix'`
+> **Target Component**: `CsatMatrixScale`
+> **Handles**: `type: 'matrix'` (CSAT_MATRIX and RATING_MATRIX subTypes)
 
-## Props Interface
-```typescript
-type CsatMatrixScaleProps = {
-  question: SurveyQuestion & { type: 'matrix' | 'rating_matrix' };
-  selectedValue: MatrixAnswerMap;
-  onSelect: (value: MatrixAnswerMap) => void;
-};
-```
+## Core Responsibility
+Render a grid where columns represent satisfaction scales (Emojis, Stars, or Rating Badges).
 
-## UI Structure & Hover Rules (CRITICAL)
+## Data Mapping & State Management
+- `selectedValue`: Expects `MatrixAnswerMap` shape.
+- Iterate over `question.rows`. Within each row, iterate over `question.columns`.
+- Render the correct icon/badge in the `<td>` based on `question.buttonType`.
 
-The matrix must be rendered as an HTML `<table>` with strict hover tracking and active selection bounding boxes.
+## Configuration Matrix
+You MUST handle:
+- **`hasNotApplicable`**: If true, the last column might be `null`. Render a distinct UI (e.g., standard radio or gray badge) for the N/A column.
+- **`reverseScaleOrder`**: Ensure your column mapping respects this logic if implemented in the UI.
 
-### 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.
+## UI/UX Bounding Box Rules (CRITICAL)
 
-### 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`.
+Matrices are difficult to read and click accurately. You MUST implement these strict UI rules:
 
-### 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.
+1. **Row Tracking**:
+   - Every data `<tr>` MUST have `hover:bg-gray-50 transition-colors duration-150`.
 
-- **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`.
+2. **The "Active Bounding Box"**:
+   - For Emojis and Stars inside the matrix, do NOT just change the SVG fill.
+   - The interactive wrapper inside the `<td>` MUST toggle a pink bounding box.
+   - **Selected Cell**: `border-2 border-[#e20074] rounded-lg p-2 bg-pink-50 shadow-sm scale-110 opacity-100 cursor-pointer`.
+   - **Unselected Cell**: `border-2 border-transparent p-2 opacity-40 hover:opacity-100 hover:scale-110 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>
-```
+3. **Tooltips**:
+   - Every single interactive cell MUST have `title={col.label}` so the user sees exactly what column they are in without scrolling up to the table header.