@explorer02/cfm-survey-sdk 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -1,54 +1,614 @@
+import React from 'react';
+
+/**
+ * Visual display type for scale/rating input controls.
+ * Determines how individual answer options are rendered.
+ *
+ * - `'emoji'`     — Sentiment emoji faces (😞 → 😐 → 😊)
+ * - `'star'`      — Star icons (☆ → ★)
+ * - `'radio'`     — Standard radio-button circles
+ * - `'numbered'`  — Numeric badge buttons (1, 2, 3 …)
+ * - `'number'`    — Alias for `'numbered'` (legacy value from API)
+ * - `'dropdown'`  — Collapsed select dropdown
+ * - `'selectbox'` — Expanded list of selectable cards
+ * - `'graphics'`  — Continuous slider with emoji thumb
+ */
+type SurveyButtonType = 'emoji' | 'star' | 'radio' | 'numbered' | 'number' | 'dropdown' | 'selectbox' | 'graphics';
 /**
- * Types representing survey option selections (e.g., choice options in a question).
+ * A single selectable option used by rating, radio, CSAT, and matrix question types.
  */
 type SurveyOption = {
+    /**
+     * Unique identifier for this option, sourced from the API's `answerDetail.id`.
+     * Falls back to the option's index position as a string if the API omits it.
+     */
+    id: string;
+    /** The text label displayed to the respondent */
     label: string;
-    value: string | number;
+    /** The underlying value stored in the answer payload when this option is selected */
+    value: string | number | null;
+    /** Optional color hint (e.g. NPS traffic-light hex, or HSL scale color) */
     color?: string;
 };
 /**
- * Types representing a processed question from the survey.
+ * Fields present on every question variant.
+ *
+ * All question-specific types extend this via intersection (`&`).
  */
-type SurveyQuestion = {
+type QuestionBase = {
+    /**
+     * Unique identifier for this question.
+     *
+     * ⚠️ CRITICAL: Set this as the `id` attribute on the outermost DOM element
+     * so the SDK's scroll-to-error logic can find it via `document.getElementById`.
+     */
     id: string;
+    /**
+     * Question text — may contain HTML markup.
+     * Always render with `dangerouslySetInnerHTML` or an HTML-safe renderer.
+     */
     text: string;
-    type: 'rating' | 'radio' | 'text';
+    /**
+     * Optional description / supplementary instruction text — may contain HTML markup.
+     * Rendered below the main question text.
+     */
+    description?: string;
+    /** Whether the respondent must answer this question before proceeding */
+    required?: boolean;
+    /** Localised error message shown when a required question is left unanswered */
+    requiredErrorMessage?: string;
+    /**
+     * Ordinal position of this question in the survey (1-indexed).
+     * Useful for displaying question numbers in the UI.
+     */
+    questionNumber?: number;
+    /**
+     * URL of a media asset displayed alongside the question (container image/video).
+     * This field is present on ANY question type that has an attached container asset —
+     * not just TEXT_AND_MEDIA questions.
+     */
+    containerMediaUrl?: string;
+    /**
+     * MIME type of the container asset.
+     * Use this to decide between `<img>` and `<video>` rendering.
+     */
+    containerMediaMimeType?: string;
+    /**
+     * Layout alignment of the container media relative to the question text.
+     * Sourced from the `QUESTION_CONTAINER_MEDIA_ALIGNMENT` question config.
+     * Common values: `'LEFT_CENTER'`, `'RIGHT_CENTER'`, `'TOP'`, `'BOTTOM'`
+     */
+    containerMediaAlignment?: string;
+    /**
+     * Width of the container media as a percentage of the question card width.
+     * Sourced from the `TEXT_AND_MEDIA_SIZE` question config.
+     * e.g. `50` means the media takes up 50% of the width.
+     */
+    containerMediaSize?: number;
+};
+
+/**
+ * NPS Rating question — a 0-to-10 numeric badge scale.
+ *
+ * API source: `SCALE` answerType with `SCALE_TYPE=TEN_POINT` config (or `NPS_SCALE`).
+ * Answer shape: `number` — the selected badge value (e.g. `7`).
+ *
+ * The `options` array is auto-generated (0–10) if the API omits it;
+ * each option carries a color from the NPS traffic-light palette
+ * (red for 0–6, amber for 7–8, green for 9–10).
+ */
+type RatingQuestion = QuestionBase & {
+    type: 'rating';
+    /** Selectable rating options (0–10), each with an NPS traffic-light color */
     options: SurveyOption[];
+    /** Label shown at the left/low end of the scale (e.g. "Not Likely") */
     minLabel?: string;
+    /** Label shown at the middle of the scale (e.g. "Neutral") */
     midLabel?: string;
+    /** Label shown at the right/high end of the scale (e.g. "Extremely Likely") */
     maxLabel?: string;
+    /**
+     * Fractional position index for the mid label within the option list.
+     * Used to compute the CSS `left` percentage offset of the mid-label element.
+     * Formula: `(midLabelIndex / (options.length - 1)) * 100`%
+     */
     midLabelIndex?: number;
+    /** Whether the scale options should be rendered in reverse order (high → low) */
+    reverseScaleOrder?: boolean;
+    /** Visual style for each option button */
+    buttonVariant?: 'radio' | 'numbered' | 'emoji';
+};
+
+/**
+ * Multiple Choice Question (MCQ) — a single-select radio list.
+ *
+ * API source: `MCQ` answerType (and any unrecognised answerType as a safe fallback).
+ * Answer shape: `string | number` — the `.value` of the selected option.
+ */
+type RadioQuestion = QuestionBase & {
+    type: 'radio';
+    /** Selectable answer choices rendered as radio buttons or option cards */
+    options: SurveyOption[];
+    /**
+     * Whether the respondent can select more than one option.
+     * When `true`, the answer shape becomes `(string | number)[]`.
+     */
+    isMultiSelect?: boolean;
+};
+
+/**
+ * Text Field question — short or long free-text input.
+ *
+ * API source: `TEXTFIELD` answerType.
+ * Answer shape: `string` — the raw text typed by the respondent.
+ *
+ * Both "Short Text Field" and "Long Text Field" from the survey builder
+ * map to this type. UI components use `maxCharacterCount` to decide
+ * between a single-line `<input>` and a multi-line `<textarea>`.
+ */
+type TextQuestion = QuestionBase & {
+    type: 'text';
+    /** Maximum number of characters allowed; should be enforced client-side */
     maxCharacterCount?: number;
-    required?: boolean;
-    requiredErrorMessage?: string;
+    /** Placeholder hint shown inside the empty input field */
     placeholder?: string;
+    /**
+     * Text input variant.
+     * - `'short'` — Rendered as a single-line text input.
+     * - `'long'`  — Rendered as a multi-line textarea.
+     */
+    inputVariant?: 'short' | 'long';
+};
+
+/**
+ * A single row (sub-question) in a matrix question.
+ * Each row represents an independent statement the respondent rates
+ * by selecting one of the shared column options.
+ */
+type MatrixRow = {
+    /** Unique row ID — used as the key in the `Record<rowId, value>` answer map */
+    id: string;
+    /** Primary statement text shown at the start of the row. May contain HTML. */
+    text: string;
+    /** Right-side statement for bipolar scales (e.g. "Agree" ↔ "Disagree") */
+    rightText?: string;
+};
+/**
+ * A single column header in a matrix question.
+ * Columns are shared across all rows; selecting a cell in a column records
+ * that column's `value` for the corresponding row.
+ */
+type MatrixColumn = {
+    /** Unique column identifier */
+    id: string;
+    /** Display label shown in the column header (e.g. "Strongly Agree") */
+    label: string;
+    /** Value recorded in the payload when this column is selected for any given row */
+    value: string | number | null;
+    /** Optional color hint — used by RATING_MATRIX scale columns (HSL or hex) */
+    color?: string;
+};
+/**
+ * CFM_MATRIX / CSAT_MATRIX — a grid of rows × columns where the respondent
+ * selects exactly one column per row (or N/A).
+ *
+ * API sources: `CFM_MATRIX`, `CSAT_MATRIX` answerType.
+ * Answer shape: `Record<rowId, columnValue | null>` — one entry per row.
+ *   - `null` means the respondent selected the N/A option for that row.
+ *
+ * Use `subType` to distinguish visual styling:
+ * - `'CSAT_MATRIX'` → rendered with emoji/star/numbered buttons per cell.
+ * - `'CFM_MATRIX'`  → rendered as a Likert-style text-label grid.
+ * - `'RATING_MATRIX'` → rendered with color-coded NPS-style rating buttons.
+ */
+type MatrixQuestion = QuestionBase & {
+    type: 'matrix';
+    /** Original API sub-type — use this to apply the correct visual variant */
+    subType: 'CFM_MATRIX' | 'CSAT_MATRIX' | 'RATING_MATRIX';
+    /** Ordered list of row sub-questions (statements to rate) */
+    rows: MatrixRow[];
+    /**
+     * Shared column header options (same columns appear for every row).
+     * Columns with `value === null` represent the N/A column.
+     */
+    columns: MatrixColumn[];
+    /** Visual display type for cell input controls (only applies to CSAT_MATRIX) */
+    buttonType?: SurveyButtonType;
+    /** Whether the last column is a Not Applicable (N/A) option */
+    hasNotApplicable?: boolean;
+    /** Whether the scale columns should be displayed in reverse order (high → low) */
+    reverseScaleOrder?: boolean;
+    /**
+     * Anchor labels displayed above the scale columns at evenly distributed positions.
+     * (e.g. `['Strongly Disagree', 'Neutral', 'Strongly Agree']`)
+     */
+    labels?: string[];
+    /**
+     * Layout format for the matrix.
+     * - `'standard'`  — All rows displayed as a grid at once.
+     * - `'carousel'`  — One row shown at a time with prev/next navigation.
+     * - `'dropdown'`  — Each row's answer is selected via a dropdown menu.
+     */
+    matrixFormat?: 'standard' | 'carousel' | 'dropdown';
+    /**
+     * Scale polarity for CFM_MATRIX.
+     * - `'likert'`  — Standard unipolar scale (e.g. Strongly Agree → Strongly Disagree).
+     * - `'bipolar'` — Two-sided scale with opposite statements at each end.
+     */
+    matrixType?: 'likert' | 'bipolar';
+    /**
+     * Answer selection mode for CFM_MATRIX.
+     * - `'single'`   — One selection per row.
+     * - `'multiple'` — Multiple selections allowed per row.
+     */
+    answerType?: 'single' | 'multiple';
+    /** Whether to transpose the table (rows become columns and vice versa) */
+    transposeTable?: boolean;
+    /** Whether to repeat the column header row at regular intervals */
+    repeatScale?: boolean;
+    /** Whether to show the scale header row at all */
+    enableScale?: boolean;
 };
+
 /**
- * Type representing a survey page.
+ * RATING_MATRIX — a grid of rows × NPS-style rating columns.
+ * Visually similar to `MatrixQuestion` (CSAT_MATRIX), but specifically
+ * for rating scales where columns carry traffic-light colors and endpoint labels.
+ *
+ * API source: `RATING_MATRIX` answerType.
+ * Answer shape: `Record<rowId, columnValue | null>` — one entry per row.
+ *   - `null` means the respondent selected the N/A option for that row.
+ */
+type RatingMatrixQuestion = QuestionBase & {
+    type: 'rating_matrix';
+    /** Ordered list of row sub-questions (statements to rate) */
+    rows: MatrixRow[];
+    /**
+     * Rating-scale column options — each may carry a `color` for visual emphasis.
+     * Columns with `value === null` represent the N/A column.
+     */
+    columns: MatrixColumn[];
+    /** Label for the lowest end of the rating scale (e.g. "Poor") */
+    minLabel?: string;
+    /** Label for the highest end of the rating scale (e.g. "Excellent") */
+    maxLabel?: string;
+    /** Visual display type for each cell's input control */
+    buttonType?: SurveyButtonType;
+    /** Whether the last column is a Not Applicable (N/A) option */
+    hasNotApplicable?: boolean;
+    /** Whether the scale columns should be displayed in reverse order (high → low) */
+    reverseScaleOrder?: boolean;
+    /**
+     * Anchor labels displayed above the scale columns at evenly distributed positions.
+     * (e.g. `['Strongly Disagree', 'Neutral', 'Strongly Agree']`)
+     */
+    labels?: string[];
+};
+
+/**
+ * A single row in a SLIDER_MATRIX question.
+ * Each row carries its own independent slider range configuration.
+ */
+type SliderMatrixRow = MatrixRow & {
+    /** Minimum value of this row's slider track */
+    min: number;
+    /** Maximum value of this row's slider track */
+    max: number;
+    /** Step increment between selectable values (e.g. `1` for integers) */
+    step: number;
+    /** Optional initial position of the slider handle before interaction */
+    defaultValue?: number;
+};
+/**
+ * A discrete tick mark on a slider track, carrying a display label and color.
+ * Used by `SliderMatrixQuestion.tickValues` for rich visual scales.
+ */
+type TickValue = {
+    /** Numeric position on the slider track */
+    value: number;
+    /** Display label shown at this tick (e.g. `"0"`, `"Neutral"`) */
+    label: string;
+    /** HSL or hex color for the tick / emoji at this position */
+    color: string;
+};
+/**
+ * SLIDER_MATRIX — a grid of rows where each row has an independent range slider.
+ * The respondent drags a handle to set a numeric position per row.
+ *
+ * API source: `SLIDER_MATRIX` answerType.
+ * Answer shape: `Record<rowId, number | null>` — one numeric value per row,
+ *   or `null` when the respondent selects the N/A option for that row.
+ */
+type SliderMatrixQuestion = QuestionBase & {
+    type: 'slider_matrix';
+    /** Rows — each row carries its own min/max/step slider configuration */
+    rows: SliderMatrixRow[];
+    /**
+     * Anchor text labels displayed above the slider tracks at evenly distributed positions.
+     * (e.g. `['Label 1', 'Label 3', 'Label 5']`)
+     */
+    labels?: string[];
+    /**
+     * Number of discrete tick marks rendered on the slider track.
+     * Defaults to `10` if not set by the survey configuration.
+     */
+    ticks?: number;
+    /**
+     * Pre-calculated tick values with display labels and HSL color mapping.
+     * The colors transition Red → Amber → Green from index 0 to the last tick.
+     */
+    tickValues?: TickValue[];
+    /** Whether to show a numeric text input box alongside the slider handle */
+    enableInputBox?: boolean;
+    /** Whether to display the current value as a tooltip on the slider thumb */
+    displayValues?: boolean;
+    /** Whether to include a Not Applicable (N/A) option per row */
+    enableNotApplicable?: boolean;
+    /**
+     * Whether this is a Graphics Slider (renders an emoji thumb instead of a plain handle).
+     * When `'graphics'`, the slider thumb shows a sentiment emoji that changes with the value.
+     */
+    sliderType?: 'graphics';
+};
+
+/**
+ * Text and Media — a display-only informational card.
+ * No answer is recorded for this type — it is purely presentational.
+ *
+ * API source: `TEXT_AND_MEDIA` answerType.
+ * ⚠️ Do NOT dispatch a CHANGE action for this question type.
+ * ⚠️ This type is excluded from validation and response progress counting.
+ *
+ * The heading text is sourced from `answerDetails` where
+ * `additional.textAndMediaFieldType === 'HEADER'`, not from `questionText`.
+ */
+type TextAndMediaQuestion = QuestionBase & {
+    type: 'text_and_media';
+    /**
+     * Public URL of the image or video asset to display.
+     * Sourced from `questionContainerAssets[0].source`.
+     */
+    mediaUrl?: string;
+    /**
+     * MIME type of the media asset.
+     * - `'image/*'` for photos.
+     * - `'video/*'` for video clips.
+     * Use this to decide between `<img>` and `<video>` rendering.
+     */
+    mediaMimeType?: 'image/*' | 'video/*' | string;
+    /** Optional caption or alt text rendered beneath the media asset */
+    mediaTitle?: string;
+    /**
+     * Layout position of the media relative to the text content.
+     * Sourced from the `TEXT_AND_MEDIA_ALIGNMENT` question config.
+     * (e.g. `'BOTTOM_LEFT'`, `'TOP_CENTER'`, `'LEFT_CENTER'`)
+     */
+    mediaAlignment?: string;
+    /**
+     * Width of the media container as a percentage of the card width.
+     * Sourced from the `TEXT_AND_MEDIA_SIZE` question config.
+     * (e.g. `50` means the image takes up 50% of the width)
+     */
+    mediaSize?: number;
+};
+
+/**
+ * CSAT Rating — a short customer satisfaction scale, typically 1–5.
+ * Usually rendered with emoji face icons (😞 → 😐 → 😊).
+ *
+ * API source: `SCALE` answerType with `SCALE_TYPE=CSAT` config,
+ * or heuristically detected when the option count is ≤ 5.
+ * Answer shape: `string | number | null` — the selected satisfaction value,
+ * or `null` when the respondent selects the N/A option.
+ */
+type CsatQuestion = QuestionBase & {
+    type: 'csat';
+    /**
+     * Selectable satisfaction options — usually 1 to 5.
+     * The UI should render these as emoji/face icons rather than numeric badges.
+     */
+    options: SurveyOption[];
+    /** Label for the lowest satisfaction level (e.g. "Very Dissatisfied") */
+    minLabel?: string;
+    /** Label for the highest satisfaction level (e.g. "Very Satisfied") */
+    maxLabel?: string;
+    /** Visual display type for the scale options */
+    buttonType?: SurveyButtonType;
+    /** Whether the user can select an N/A (Not Applicable) option */
+    hasNotApplicable?: boolean;
+    /** Whether the options should be displayed in reverse order (high → low) */
+    reverseScaleOrder?: boolean;
+    /**
+     * Where the min/max labels are positioned relative to the scale buttons.
+     * - `'top'`    — Labels appear above the scale
+     * - `'bottom'` — Labels appear below the scale
+     * - `'hidden'` — Labels are not shown
+     */
+    labelPosition?: 'top' | 'bottom' | 'hidden';
+};
+
+/**
+ * Standalone Slider — a single continuous range input.
+ * The respondent drags a handle to set a numeric value along a track.
+ *
+ * API source: `SCALE` answerType with `INPUT_TYPE=SLIDER` questionConfig.
+ * Answer shape: `number` — the position of the slider handle on the track.
+ */
+type SliderQuestion = QuestionBase & {
+    type: 'slider';
+    /** Minimum value at the left end of the slider track */
+    min: number;
+    /** Maximum value at the right end of the slider track */
+    max: number;
+    /** Step increment between selectable positions (e.g. `1` for whole numbers) */
+    step: number;
+    /** Optional initial position of the slider handle before interaction */
+    defaultValue?: number;
+    /** Label displayed at the minimum (left) end of the track */
+    minLabel?: string;
+    /** Label displayed at the maximum (right) end of the track */
+    maxLabel?: string;
+    /** Whether to show a numeric text input box alongside the slider handle */
+    enableInputBox?: boolean;
+    /** Whether to display the current value as a floating tooltip on the thumb */
+    displayValues?: boolean;
+};
+
+/**
+ * Rating Scale — a star, emoji, or icon-based rating question (e.g. 1–5 stars).
+ *
+ * Unlike the NPS `'rating'` type, this does NOT apply traffic-light colors to options
+ * and is visually rendered as stars, emojis, thumbs, or similar icons.
+ *
+ * API source: `SCALE` answerType with `SCALE_TYPE=STAR`, `SCALE_TYPE=EMOJI`,
+ * or `SCALE_TYPE=FIVE_POINT` config.
+ * Answer shape: `number` — the selected star/icon value.
+ */
+type RatingScaleQuestion = QuestionBase & {
+    type: 'rating_scale';
+    /**
+     * Selectable rating options (typically 1–5 or 1–10).
+     * These carry no NPS colors — the UI should render them as stars or custom icons.
+     */
+    options: SurveyOption[];
+    /** Label for the lowest rating end (e.g. "Poor") */
+    minLabel?: string;
+    /** Label for the midpoint of the scale (e.g. "Average") */
+    midLabel?: string;
+    /** Label for the highest rating end (e.g. "Excellent") */
+    maxLabel?: string;
+    /**
+     * Fractional position index for the mid label within the option list.
+     * Used to compute the CSS `left` percentage offset of the mid-label element.
+     * Formula: `(midLabelIndex / (options.length - 1)) * 100`%
+     */
+    midLabelIndex?: number;
+    /** Whether the scale options should be displayed in reverse order (high → low) */
+    reverseScaleOrder?: boolean;
+    /**
+     * The specific icon style used for this scale.
+     * - `'star'`  — Classic star icons
+     * - `'emoji'` — Sentiment emoji faces
+     */
+    scaleStyle?: 'star' | 'emoji';
+};
+
+/**
+ * A file uploaded by the respondent in response to a `FILE_UPLOAD` question.
+ * This is the shape that should be passed to `onSelect` after a successful upload.
+ *
+ * @example
+ * ```ts
+ * const handleUpload = (file: File) => {
+ *   uploadToServer(file).then((result) => {
+ *     onSelect([{ id: result.id, name: file.name, mediaUrl: result.url }]);
+ *   });
+ * };
+ * ```
+ */
+type UploadedFile = {
+    /** Unique asset ID returned by the upload server */
+    id: string;
+    /** Original filename of the uploaded file */
+    name: string;
+    /** Public URL to access the uploaded file */
+    mediaUrl: string;
+    /** MIME type of the uploaded file (e.g. `'image/png'`, `'application/pdf'`) */
+    mimeType?: string;
+    /** File size in bytes */
+    size?: number;
+};
+/**
+ * File Upload question — prompts the respondent to attach one or more files.
+ *
+ * API source: `FILE_UPLOAD` answerType.
+ * Answer shape: `UploadedFile[]` — an array of successfully uploaded file descriptors.
+ * Submit target: `quesIdVsAttachmentDetails[questionId]` (NOT `questionToAnswers`).
+ */
+type FileUploadQuestion = QuestionBase & {
+    type: 'file_upload';
+    /**
+     * Custom instruction text displayed above the upload area.
+     * May contain HTML markup; render with `dangerouslySetInnerHTML`.
+     */
+    uploadMessage?: string;
+    /**
+     * List of accepted file extensions in uppercase without dots (e.g. `['PDF', 'PNG', 'DOCX']`).
+     * Use these to set the `accept` attribute on the `<input type="file">` element.
+     */
+    supportedFileFormats?: string[];
+    /**
+     * Maximum number of files the respondent can attach to this question.
+     * If `undefined`, no limit is enforced by the SDK.
+     */
+    maxFileCount?: number;
+    /**
+     * Maximum file size in megabytes (MB).
+     * Applies either per-file or in total, depending on `fileSizeLimitType`.
+     */
+    fileSizeLimit?: number;
+    /**
+     * Determines how `fileSizeLimit` is applied.
+     * - `'PER_FILE'` — Each individual file must not exceed `fileSizeLimit` MB.
+     * - `'IN_TOTAL'` — The combined size of all uploads must not exceed `fileSizeLimit` MB.
+     */
+    fileSizeLimitType?: 'PER_FILE' | 'IN_TOTAL';
+};
+
+/**
+ * Discriminated union of all question types surfaced by the SDK.
+ */
+type SurveyQuestion = RatingQuestion | RadioQuestion | TextQuestion | MatrixQuestion | RatingMatrixQuestion | SliderMatrixQuestion | TextAndMediaQuestion | CsatQuestion | SliderQuestion | RatingScaleQuestion | FileUploadQuestion;
+/**
+ * A single survey page containing an ordered list of questions.
  */
 type SurveyPageData = {
+    /** Unique page identifier */
     id: string;
+    /** Optional page title displayed as a section header */
     title?: string;
+    /** Ordered list of questions on this page */
     questions: SurveyQuestion[];
 };
+/**
+ * A language option available for this survey.
+ */
 type SurveyLanguage = {
+    /** BCP-47 language code (e.g. `'en'`, `'de'`, `'fr'`) */
     code: string;
+    /** Human-readable language name (e.g. `'English'`, `'Deutsch'`) */
     name: string;
 };
 /**
- * Type representing the fully parsed and normalized Survey structure.
+ * The fully parsed and normalised survey structure returned by the SDK.
  */
 type Survey = {
+    /** Unique survey identifier */
     id: string;
+    /** Active language code for this response session */
     language: string;
+    /** All languages configured for this survey */
     languages: SurveyLanguage[];
+    /** Ordered list of pages that make up the survey flow */
     pages: SurveyPageData[];
 };
 
 /**
- * Key-value mapping of question IDs to their selected answer values (string or number).
+ * Answer value for matrix questions (CFM_MATRIX, CSAT_MATRIX, RATING_MATRIX, SLIDER_MATRIX).
+ * Maps each row sub-question ID to the selected column value or slider position.
+ * For multi-select grids, the value can be an array of selected column values.
+ */
+type MatrixAnswerMap = Record<string, string | number | null | Array<string | number | null>>;
+/**
+ * Union of all possible answer value types across all question variants.
+ * - `string | number | null` — standard single-value questions (rating, radio, text, csat N/A)
+ * - `MatrixAnswerMap`  — grid questions (matrix, rating_matrix, slider_matrix)
+ */
+type AnswerValue = string | number | null | MatrixAnswerMap | any[];
+/**
+ * Key-value mapping of question IDs to their answer values.
  */
-type SubmitAnswers = Record<string, string | number>;
+type SubmitAnswers = Record<string, AnswerValue>;
 /**
  * The final output result resolved after a successful submit response.
  */
@@ -80,7 +640,7 @@ type SurveyAction = {
     type: ACTIONS.CHANGE | 'CHANGE';
     payload: {
         questionId: string;
-        value: string | number;
+        value: AnswerValue;
     };
 };
 /**
@@ -124,4 +684,23 @@ declare function useSurveySDK({ options }?: UseSurveySDKProps): {
     onAction: (action: SurveyAction) => void;
 };
 
-export { type SurveyLanguage, type SurveyQuestion, useSurveySDK };
+/**
+ * Extended 11-level CSAT emoji set.
+ * Each entry is a pre-built React element with colour and sizing.
+ */
+declare const CsatEmojiSet: Record<number, React.ReactNode>;
+/**
+ * Maps a 0-based column index within a scale of `total` items
+ * to the correct professional face icon from the 11-level set.
+ *
+ * Works for any scale length. Uses specific curated subsets for 3-6 lengths.
+ */
+declare function getEmojiForIndex(index: number, total: number): React.ReactNode;
+/** Legacy 1–5 mapping kept for backward compatibility with CsatScale (standalone) */
+declare const CsatEmojiMapping: Record<number, React.ReactNode>;
+declare const CsatStarIcons: {
+    filled: React.ReactNode;
+    empty: React.ReactNode;
+};
+
+export { type AnswerValue, CsatEmojiMapping, CsatEmojiSet, type CsatQuestion, CsatStarIcons, type FileUploadQuestion, type MatrixAnswerMap, type MatrixColumn, type MatrixQuestion, type MatrixRow, type QuestionBase, type RadioQuestion, type RatingMatrixQuestion, type RatingQuestion, type RatingScaleQuestion, type SliderMatrixQuestion, type SliderMatrixRow, type SliderQuestion, type SurveyButtonType, type SurveyLanguage, type SurveyOption, type SurveyQuestion, type TextAndMediaQuestion, type TextQuestion, type TickValue, type UploadedFile, getEmojiForIndex, useSurveySDK };