react-feedback-surveys 1.7.0 → 1.9.0

package/README.md

@@ -9,28 +9,36 @@
 
 > Lightweight, customizable survey widgets to collect user feedback in React apps.
 
+## Introduction
+
+react-feedback-surveys is a standalone, open-source (MIT) UI library — no backend, no hosting, no
+account required. Render the components, wire `onScoreSubmit`/`onFeedbackSubmit` to your own backend
+(or nowhere at all).
+
+Want AI-generated insights, a hosted dashboard, and response storage without building your own backend?
+Check out [feedback.tools](https://feedback.tools) — built by the same team.
+
 ## Table of Contents
 
+- [Introduction](#introduction)
 - [Features](#features)
 - [Survey Types](#survey-types)
 - [Installation](#installation)
     * [1. Install](#1-install)
     * [2. Styles](#2-styles)
-- [Survey Components](#survey-components)
-    * [CSAT5 (Customer Satisfaction Score, 5-Point Scale)](#csat5-customer-satisfaction-score-5-point-scale)
-    * [CSAT2 (Customer Satisfaction Score, 2-Point Scale)](#csat2-customer-satisfaction-score-2-point-scale)
-    * [NPS10 (Net Promoter Score, 0–10 Scale)](#nps10-net-promoter-score-010-scale)
-    * [CES7 (Customer Effort Score, 7-Point Scale)](#ces7-customer-effort-score-7-point-scale)
+- [Survey Component](#survey-component)
+    * [CSAT (Customer Satisfaction Score)](#csat-customer-satisfaction-score)
+    * [NPS (Net Promoter Score)](#nps-net-promoter-score)
+    * [CES (Customer Effort Score)](#ces-customer-effort-score)
 - [Layout Components](#layout-components)
     * [Popup](#popup)
     * [Surface](#surface)
 - [Props](#props)
     * [Shared Props](#shared-props)
+    * [Accessibility Labels](#accessibility-labels)
+    * [Attachments](#attachments)
+    * [Format Props](#format-props)
     * [Scale Style Options](#scale-style-options)
-        + [CSAT2Survey](#csat2survey)
-        + [CSAT5Survey](#csat5survey)
-        + [CES7Survey](#ces7survey)
-        + [NPS10Survey](#nps10survey)
 - [Styling](#styling)
     * [CSS Variables](#css-variables)
     * [Custom Classes](#custom-classes)
@@ -47,20 +55,25 @@
 
 ## Features
 
-- **Ready-to-use survey widgets** – CSAT (2 or 5 points), CES (7 points), NPS (0–10)
+- **A single `Survey` component** – the format (methodology, scale length, visual style) is configuration, not a different import
+- **Ready-to-use survey formats** – CSAT (2 or 5 points), CES (7 points), NPS (0–10)
 - **Multiple scale styles** – emoji, stars, numbers, thumbs
 - **Flexible placement** – embed inline or display as popup overlay
 - **Follow-up feedback** – optional text input or multiple choice responses
 - **Optional email collection** – close the loop by capturing a respondent's email when no user identity is known
+- **Optional screenshot attachments** – let respondents attach a screenshot, captured by a function you provide
 - **Fully customizable** – CSS variables and custom class names
 - **Zero dependencies**
 - **TypeScript support**
 
 ## Survey Types
 
-- **CSAT (Customer Satisfaction Score):** 2-point (`csat2`) or 5-point (`csat5`) scales
-- **NPS (Net Promoter Score):** 0–10 numeric scale (`nps10`)
-- **CES (Customer Effort Score):** 7-point numeric scale (`ces7`)
+`Survey` covers four feedback methodologies, selected with the `type` prop. `CSAT` is the only one with a variable scale length, set via `points`:
+
+- **CSAT (Customer Satisfaction Score):** `type="csat"`, 2-point or 5-point scale (`points={2}` or `points={5}`)
+- **NPS (Net Promoter Score):** `type="nps"`, fixed 0–10 scale
+- **CES (Customer Effort Score):** `type="ces"`, fixed 7-point scale
+- **General (text feedback only):** `type="general"`, no rating scale — see [General](#general-text-feedback-only)
 
 ## Installation
 
@@ -78,24 +91,28 @@ yarn add react-feedback-surveys
 import 'react-feedback-surveys/index.css';
 ```
 
-## Survey Components
+## Survey Component
+
+Every format is reached through the same `Survey` import — `type` and `points` pick the methodology and scale length, `scaleStyle` picks the visual style. See [Format Props](#format-props) for the full matrix of valid `type`/`points`/`scaleStyle` combinations.
 
-### CSAT5 (Customer Satisfaction Score, 5-Point Scale)
+### CSAT (Customer Satisfaction Score)
 
-Surveys to ask users about their overall satisfaction.
+Surveys to ask users about their overall satisfaction, or about a specific feature or flow.
 
 **Example questions:**
 - "How satisfied are you with our product?"
-- "How would you rate your overall experience?"
-- "How satisfied are you with our customer support?"
+- "Was this search helpful?"
+- "Are you satisfied with the checkout process?"
 
-<img alt="CSAT5" src="docs/assets/csat5.png" width="416" />
+<img alt="CSAT, 5-point scale" src="docs/assets/csat5.png" width="416" />
 
 ```tsx
-import { CSAT5Survey } from 'react-feedback-surveys';
+import { Survey } from 'react-feedback-surveys';
 import 'react-feedback-surveys/index.css';
 
-<CSAT5Survey
+<Survey
+  type="csat"
+  points={5}
   scaleStyle="emoji"
   question="How would you rate your satisfaction with our product?"
   minLabel="Very unsatisfied"
@@ -110,24 +127,12 @@ import 'react-feedback-surveys/index.css';
 />
 ```
 
-`scaleStyle`: `emoji` | `numbers` | `stars`.
-
-### CSAT2 (Customer Satisfaction Score, 2-Point Scale)
-
-Surveys to ask users about specific features or flows.
-
-**Example questions:**
-- "Was this search helpful?"
-- "Did you find what you were looking for?"
-- "Are you satisfied with the checkout process?"
-
-<img alt="CSAT2" src="docs/assets/csat2.png" width="386" />
+<img alt="CSAT, 2-point scale" src="docs/assets/csat2.png" width="386" />
 
 ```tsx
-import { CSAT2Survey } from 'react-feedback-surveys';
-import 'react-feedback-surveys/index.css';
-
-<CSAT2Survey
+<Survey
+  type="csat"
+  points={2}
   scaleStyle="thumbs"
   question="Are you satisfied with the result?"
   responseType="text"
@@ -140,26 +145,27 @@ import 'react-feedback-surveys/index.css';
 />
 ```
 
-`scaleStyle`: `emoji` | `thumbs`.
+`points={5}` → `scaleStyle`: `emoji` | `numbers` | `stars`. `points={2}` → `scaleStyle`: `emoji` | `thumbs`.
 
-### NPS10 (Net Promoter Score, 0–10 Scale)
+### NPS (Net Promoter Score)
 
-Surveys to ask users if they'd recommend your product.
+Surveys to ask users if they'd recommend your product. Fixed 0–10 scale — no `points` prop needed.
 
 **Example questions:**
 - "How likely are you to recommend us to a friend or colleague?"
 - "On a scale of 0-10, would you recommend our service?"
 - "How likely are you to recommend this product to others?"
 
-<img alt="NPS10" src="docs/assets/nps10.png" width="616" />
+<img alt="NPS" src="docs/assets/nps10.png" width="616" />
 
-<img alt="NPS10 mobile" src="docs/assets/nps10-mobile.png" width="340" />
+<img alt="NPS mobile" src="docs/assets/nps10-mobile.png" width="340" />
 
 ```tsx
-import { NPS10Survey } from 'react-feedback-surveys';
+import { Survey } from 'react-feedback-surveys';
 import 'react-feedback-surveys/index.css';
 
-<NPS10Survey
+<Survey
+  type="nps"
   scaleStyle="numbers"
   question="How likely are you to recommend our product/service to a friend or colleague?"
   minLabel="Very unlikely"
@@ -176,22 +182,23 @@ import 'react-feedback-surveys/index.css';
 
 `scaleStyle`: `numbers`.
 
-### CES7 (Customer Effort Score, 7-Point Scale)
+### CES (Customer Effort Score)
 
-Surveys to ask users how easy it is to use your product.
+Surveys to ask users how easy it is to use your product. Fixed 7-point scale — no `points` prop needed.
 
 **Example questions:**
 - "How easy was it to complete your task?"
 - "How much effort did it take to resolve your issue?"
 - "How easy was it to sign up for an account?"
 
-<img alt="CES7" src="docs/assets/ces7.png" width="436" />
+<img alt="CES" src="docs/assets/ces7.png" width="436" />
 
 ```tsx
-import { CES7Survey } from 'react-feedback-surveys';
+import { Survey } from 'react-feedback-surveys';
 import 'react-feedback-surveys/index.css';
 
-<CES7Survey
+<Survey
+  type="ces"
   scaleStyle="numbers"
   question="How easy was it to complete your task?"
   minLabel="Very difficult"
@@ -208,6 +215,31 @@ import 'react-feedback-surveys/index.css';
 
 `scaleStyle`: `numbers`.
 
+### General (text feedback only)
+
+No rating scale — just text feedback and an optional screenshot. The text feedback step is shown immediately and is the whole survey; there's no `points`/`scaleStyle`/`minLabel`/`maxLabel`/`question` to set.
+
+**Example use cases:**
+- A general "Send feedback" or "Report a problem" trigger with no methodology attached.
+- Contexts where a numeric rating doesn't make sense.
+
+<img alt="General" src="docs/assets/general.png" width="368" />
+
+```tsx
+import { Survey } from 'react-feedback-surveys';
+import 'react-feedback-surveys/index.css';
+
+<Survey
+  type="general"
+  textQuestion="Got feedback? We'd love to hear it"
+  textButtonSendLabel="Send"
+  thankYouMessage="Thank you for your feedback!"
+  onFeedbackSubmit={({ text }) => {/* ... */}}
+/>
+```
+
+`responseType` defaults to `'text'` (also accepts `'choices'`) — it can't be unset, since the text feedback step is the only content the survey has. The step is mandatory: there's no Skip button (`textButtonSkipLabel` is ignored for `type="general"`), and Submit stays disabled until there's something to send.
+
 ## Layout Components
 
 ### Popup
@@ -219,7 +251,7 @@ The `<Popup>` component wraps survey widgets in a fixed overlay that slides in f
 #### Usage
 
 ```tsx
-import { Popup, CSAT5Survey } from 'react-feedback-surveys';
+import { Popup, Survey } from 'react-feedback-surveys';
 import 'react-feedback-surveys/index.css';
 
 <Popup
@@ -232,7 +264,9 @@ import 'react-feedback-surveys/index.css';
   placement="bottomRight"
   onClose={() => console.log('Closed')}
 >
-  <CSAT5Survey
+  <Survey
+    type="csat"
+    points={5}
     scaleStyle="stars"
     question="How would you rate your satisfaction?"
     onScoreSubmit={({ value }) => {/* ... */}}
@@ -249,9 +283,13 @@ import 'react-feedback-surveys/index.css';
 | `className`  | `string`                                                   | -        | -               | Additional CSS class name for the popup container.                 |
 | `classNames` | `{ base?: string; content?: string; close?: string }`      | -        | -               | Optional class names for internal popup elements.                  |
 | `children`   | `React.ReactNode`                                          | -        | -               | Content to render inside the popup (typically a survey component). |
+| `closeLabel` | `string`                                                    | -        | `'Close survey'` | Close button label, used for both its `aria-label` and `title`.   |
 | `onClose`    | `() => void`                                               | -        | -               | Callback fired when the close button is clicked.                   |
 
-For more examples, check out the Storybook stories (e.g., `CSAT5Survey.stories.tsx`, `CSAT2Survey.stories.tsx`).
+For more examples, check out the Storybook stories under `widgets/Survey` (grouped by CSAT/NPS/CES in the sidebar).
+
+> **Note**
+> If the survey inside uses `dir="rtl"` on a page that's otherwise LTR (or vice versa), pass the same `dir` to `Popup` too — the close button's position resolves against the document direction, while the survey head's reserved offset resolves against the survey's own `dir`. Passing both keeps them aligned.
 
 ### Surface
 
@@ -265,11 +303,13 @@ The Surface component provides:
 #### Usage
 
 ```tsx
-import { Surface, CSAT5Survey } from 'react-feedback-surveys';
+import { Surface, Survey } from 'react-feedback-surveys';
 import 'react-feedback-surveys/index.css';
 
 <Surface className="custom-surface">
-  <CSAT5Survey
+  <Survey
+    type="csat"
+    points={5}
     scaleStyle="stars"
     question="How would you rate your satisfaction?"
     onScoreSubmit={({ value }) => {/* ... */}}
@@ -288,7 +328,7 @@ The Surface component uses the `--ft-surface-padding`, `--ft-surface-padding-mob
 
 ## Props
 
-Most props are shared across all survey widgets. Each widget differs only in its `scaleStyle` values.
+Most props are shared across every survey format. `type` (and `points`, for CSAT) select the format; `scaleStyle` picks its visual style — see [Format Props](#format-props).
 
 ### Shared Props
 
@@ -296,14 +336,17 @@ Most props are shared across all survey widgets. Each widget differs only in its
 |--------------------|-------------------------------|----------|------------------------------------------------------------------------------|
 | `classNames`       | `ClassNamesConfig` (see below)| -        | Optional class names to target internal parts.                               |
 | `dir`              | `'ltr' \| 'rtl' \| 'auto'`    | -        | Text direction for RTL/LTR language support.                                 |
-| `question`         | `string`                      | required | Main survey question displayed on the first screen.                          |
-| `minLabel`         | `string`                      | -        | Left label for the scale.                                                    |
-| `maxLabel`         | `string`                      | -        | Right label for the scale.                                                   |
-| `responseType`     | `null \| 'text' \| 'choices'` | -        | Enables optional follow-up feedback.                                         |
+| `strings`          | `SurveyStrings` (see below)   | -        | Overrides for the library's own aria-labels and other screen-reader-only text. See [Accessibility Labels](#accessibility-labels). |
+| `question`         | `string`                      | required (not used for `type="general"`) | Main survey question displayed on the first screen.       |
+| `minLabel`         | `string`                      | -        | Left label for the scale. Not used for `type="general"`.                     |
+| `maxLabel`         | `string`                      | -        | Right label for the scale. Not used for `type="general"`.                    |
+| `getScoreLabelSuffix` | `(label: string) => string` | -        | Builds the visible text appended after the first/last numbered scale button when it carries `minLabel`/`maxLabel`. Default `` (label) => ` - ${label}` ``. Applies to the `numbers` scale style (CSAT5, CES, NPS). |
+| `responseType`     | `null \| 'text' \| 'choices'` (`'text' \| 'choices'` for `type="general"`, defaults to `'text'`) | -        | Enables optional follow-up feedback.                     |
 | `textQuestion`     | `string`                      | -        | Follow-up question displayed when `responseType` is defined.                 |
 | `textButtonSendLabel`  | `string`                      | -        | Submit label for the feedback screen.                                        |
 | `textButtonSkipLabel`  | `string`                      | -        | Skip label for the feedback screen.                                          |
 | `choiceOptions`    | `string[] \| null`            | -        | Predefined choices (when `responseType === 'choices'`).                      |
+| `otherPlaceholder` | `string`                      | -        | Placeholder for the free-text input next to choice checkboxes. Default `'Other'`. |
 | `thankYouMessage`  | `string`                      | required | Message shown after submission.                                              |
 | `collectContact`     | `boolean`                     | -        | Enables an optional email collection step before the success screen.         |
 | `userId`           | `string`                      | -        | Existing user identity. When provided, the email collection step is skipped. |
@@ -311,6 +354,43 @@ Most props are shared across all survey widgets. Each widget differs only in its
 | `contactSubtext`   | `string`                      | -        | Descriptive text shown above the email input.                                |
 | `contactButtonSendLabel` | `string`                      | -        | Submit label for the email collection screen.                                |
 | `contactButtonSkipLabel`  | `string`                      | -        | Skip label for the email collection screen.                                  |
+| `onCaptureScreenshot` | `() => string \| Blob \| Promise<string \| Blob>` | -        | Enables an optional screenshot-attachment control on the feedback step. Hidden unless provided — see [Attachments](#attachments). |
+| `screenshotButtonLabel` | `string`                    | -        | Label for the screenshot-attachment control.                                 |
+| `screenshotErrorMessage` | `string`                  | -        | Shown to the respondent when `onCaptureScreenshot` fails. Default `'Failed to capture screenshot'`. |
+| `maxAttachments`   | `number`                      | -        | Maximum number of attachments a respondent may confirm. Default `1`. See [Attachments](#attachments). |
+| `attachmentCaption` | `string`                     | -        | Visible caption under an attachment thumbnail, also used as its image alt text. Default `'Screenshot'`. |
+
+### Accessibility Labels
+
+A handful of internal aria-labels ship with an English default. These are never visible UI copy (that's `question`, `thankYouMessage`, `otherPlaceholder`, `attachmentCaption`, etc., always authored by you, listed alongside the rest of the shared props above) — every key in `strings` is announced to assistive tech only, useful to override if you're localizing a survey for a non-English audience.
+
+Pass a `strings` object with only the keys you want to change — each one merges over its own English default, so there's no need to repeat the rest:
+
+```tsx
+<Survey
+  /* ... */
+  strings={{
+    emailLabel: 'Adresse e-mail',
+    getScoreLabel: (score) => `Score ${score}`
+  }}
+/>
+```
+
+#### SurveyStrings Type
+
+| Key | Type | Default |
+|-----|------|---------|
+| `feedbackFormLabel` | `string` | `'Feedback form'` |
+| `additionalFeedbackLabel` | `string` | `'Additional feedback'` |
+| `yourFeedbackLabel` | `string` | `'Your feedback'` |
+| `contactFormLabel` | `string` | `'Contact form'` |
+| `emailLabel` | `string` | `'Email address'` |
+| `attachmentOpenLabel` | `string` | `'Open screenshot in a new tab'` |
+| `attachmentRemoveLabel` | `string` | `'Remove screenshot'` |
+| `getScoreLabel` | `(score: number) => string` | `(score) => \`Score ${score}\`` |
+| `getStarsLabel` | `(score: number) => string` | `(score) => \`${score} ${score > 1 ? 'stars' : 'star'}\`` |
+
+`getScoreLabel` applies to the `numbers` scale style (CSAT5, CES, NPS); `getStarsLabel` applies to CSAT5's `stars` style. Both are callbacks rather than templates so you can apply correct pluralization for your target language. `Popup`'s close button label lives on `Popup` itself, not in `strings` — see its own `closeLabel` prop in [Popup Props](#props).
 
 #### ClassNamesConfig Type
 
@@ -350,10 +430,13 @@ interface ClassNamesConfig {
 
 ```typescript
 type ScorePayload = { value: number };
-type FeedbackPayload = { value: number; text?: string | string[] };
+type FeedbackPayload = { value?: number; text?: string | string[]; attachments?: Attachment[] };
 type ContactPayload = { value?: number; text?: string | string[]; email: string };
+type Attachment = { kind: 'screenshot'; data: string | Blob; name?: string; mimeType?: string; size?: number };
 ```
 
+> See [Attachments](#attachments).
+
 > **Event behavior**
 
 #### `onScoreSubmit`
@@ -372,13 +455,14 @@ The actual `value` returned depends on the survey type:
 Invoked when the user completes the follow-up step and submits their feedback (only applies when `responseType` is `text` or `choices`).  
 This callback provides both the original score and the user's input.
 
-The feedback step is always optional: respondents can submit feedback or skip it via the `textButtonSkipLabel` button (or by submitting with empty input), and either action advances to the next screen. `onFeedbackSubmit` only fires when feedback text or choices are actually submitted; it is **not** called when the step is skipped.
+For surveys with a rating step, the feedback step is optional: respondents can submit feedback or skip it via the `textButtonSkipLabel` button (or by submitting with empty input), and either action advances to the next screen. For `type="general"`, the feedback step **is** the survey, so there's no Skip button — Submit stays disabled until there's something to send. `onFeedbackSubmit` only fires when feedback text or choices are actually submitted; it is **not** called when a rating-survey's step is skipped.
 
 **Arguments:**
-- `value: number` — the same score previously passed to `onScoreSubmit`
+- `value?: number` — the same score previously passed to `onScoreSubmit`; `undefined` for `type="general"`, which has no rating step
 - `text: string | string[]` — depends on `responseType`:
-    - `text`: a single text comment
-    - `choices`: an array of selected options (may include a free-text comment if enabled)
+    - `text`: a single text feedback string
+    - `choices`: an array of selected options (may include free-text feedback if enabled)
+- `attachments?: Attachment[]` — present when the respondent confirmed a screenshot; see [Attachments](#attachments)
 
 > **Important**  
 You should listen to **both** `onScoreSubmit` and `onFeedbackSubmit`.  
@@ -399,7 +483,9 @@ When `collectContact` is `true` and no `userId` is provided, an optional email c
 - `email: string` — the email address entered by the respondent.
 
 ```tsx
-<CSAT5Survey
+<Survey
+  type="csat"
+  points={5}
   scaleStyle="numbers"
   question="How would you rate your satisfaction with our product?"
   responseType="text"
@@ -416,35 +502,73 @@ When `collectContact` is `true` and no `userId` is provided, an optional email c
 />
 ```
 
-### Scale Style Options
+### Attachments
 
-Each survey type supports specific scale styles for displaying the rating interface:
+Respondents can attach a screenshot to their feedback, surfaced on submit as `attachments?: Attachment[]` (see the event payload types above). Each attachment renders as a thumbnail in the feedback step, with a caption and size underneath, click to open it in a new tab, click the "x" to remove it. Submit is disabled for the brief moment a capture is still in flight, so it can't be confirmed before the attachment actually lands in the list.
 
-#### CSAT2Survey
+Once an attachment is confirmed, the Skip button is disabled — an attached screenshot is never silently discarded. Remove the attachment to re-enable Skip, or fill in feedback and submit to keep it. An attachment on its own is never sufficient to submit, either: for `responseType="text"`, submitting with an attachment but no text flags the textarea instead of sending; for `responseType="choices"`, Submit stays disabled until a choice is picked or text is entered.
 
-| Prop                     | Type                    | Required | Description                                                                       |
-|--------------------------|-------------------------|----------|-----------------------------------------------------------------------------------|
-| `scaleStyle` | `'emoji'` \| `'thumbs'` | required | Emoji mood scale style (happy/sad faces) or thumbs up/down emoji scale style. |
+By default a respondent can confirm a single attachment: once one is attached, the add control hides. Pass `maxAttachments` to raise (or lower) that cap. The add control stays visible (below the existing thumbnails) until the cap is reached:
 
-#### CSAT5Survey
+```tsx
+<Survey
+  /* ... */
+  onCaptureScreenshot={() => domToDataUrl(document.body)}
+  maxAttachments={3}
+/>
+```
 
-| Prop                     | Type                                  | Required | Description                                                                                                          |
-|--------------------------|---------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------|
-| `scaleStyle` | `'emoji'` \| `'numbers'` \| `'stars'` | required | Emoji scale style (5 emotion levels), numeric scale style (1–5), or star rating scale style (1–5 stars). |
+Pass `onCaptureScreenshot` to add an "Capture screenshot" control to the feedback step. Clicking it calls your function and attaches the result immediately. The control is off by default: it doesn't render at all unless `onCaptureScreenshot` is provided.
 
-#### CES7Survey
+Capturing a screenshot needs an actual DOM-to-image library (or a native bridge in a hybrid app) — real, non-trivial code that most consumers of this package won't want to pay for in bundle size if they don't use the feature. So react-feedback-surveys deliberately doesn't ship a capture implementation itself: bring your own function that returns the captured image (as a data URL string, a `Blob`, or a `Promise` of either). A drop-in recipe using [modern-screenshot](https://github.com/qq15725/modern-screenshot):
 
-| Prop                     | Type        | Required | Description                        |
-|--------------------------|-------------|----------|------------------------------------|
-| `scaleStyle` | `'numbers'` | required | Numeric scale style (1–7). |
+```shell
+npm i modern-screenshot
+```
 
-#### NPS10Survey
+```tsx
+import { Survey } from 'react-feedback-surveys';
+import { domToDataUrl } from 'modern-screenshot';
+import 'react-feedback-surveys/index.css';
 
-| Prop                     | Type        | Required | Description                         |
-|--------------------------|-------------|----------|-------------------------------------|
-| `scaleStyle` | `'numbers'` | required | Numeric scale style (0–10). |
+<Survey
+  type="csat"
+  points={5}
+  scaleStyle="numbers"
+  question="How would you rate your satisfaction with our product?"
+  responseType="text"
+  textQuestion="We'd love to hear your thoughts — what can we improve?"
+  thankYouMessage="Thanks for your feedback!"
+  onCaptureScreenshot={() => domToDataUrl(document.body)}
+  onScoreSubmit={({ value }) => {/* ... */}}
+  onFeedbackSubmit={({ value, text, attachments }) => {/* attachments?.[0]?.data holds the attached screenshot */}}
+/>
+```
+
+In a hybrid app, `onCaptureScreenshot` can just as well call into a native bridge (e.g. `WKWebView.takeSnapshot` on iOS) instead of a DOM-to-image library.
 
-Note: The numeric ranges are defined by the widget (e.g., CSAT5 uses a 1–5 scale, NPS10 uses 0–10).
+> **Note**  
+> DOM-to-image capture is best-effort — fonts, cross-origin images, and some CSS effects may not render identically on every browser (particularly Safari/iOS). The respondent can open the attached thumbnail in a new tab to check it, and remove it with one click if the capture came out wrong.
+
+### Format Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|--------------|
+| `type` | `'csat'` \| `'nps'` \| `'ces'` \| `'general'` | required | Survey methodology. Determines the scale range and which `scaleStyle`/`points` combinations are valid. `'general'` has no scale at all — see [General](#general-text-feedback-only). |
+| `points` | `2` \| `5` | required for `type="csat"`; not used otherwise | Number of points on the scale. `nps` is a fixed 0–10 scale and `ces` a fixed 1–7 scale, so neither takes `points`. |
+
+### Scale Style Options
+
+Valid `scaleStyle` values depend on `type` (and `points`, for CSAT):
+
+| `type` | `points` | Scale range | Valid `scaleStyle` |
+|--------|----------|-------------|---------------------|
+| `csat` | `5` | 1–5 | `'emoji'` (5 emotion levels) \| `'numbers'` \| `'stars'` (1–5 stars) |
+| `csat` | `2` | 0–1 | `'emoji'` (happy/sad faces) \| `'thumbs'` (thumbs up/down) |
+| `ces`  | — | 1–7 | `'numbers'` |
+| `nps`  | — | 0–10 | `'numbers'` |
+
+Invalid combinations (e.g. `type="ces"` with `scaleStyle="stars"`) are rejected at the type level.
 
 ## Styling
 
@@ -472,6 +596,9 @@ You can override colors and fonts via CSS variables:
   /* Error color for validation messages */
   --ft-color-error: 32 95% 44%;
 
+  /* Error text color (attachment capture errors) — darker than --ft-color-error, tuned for text contrast rather than borders/outlines */
+  --ft-color-error-text: 32 95% 32%;
+
   /* Border color for inputs and containers */
   --ft-color-border: 214 14% 83%;
 
@@ -493,7 +620,7 @@ You can override colors and fonts via CSS variables:
   --ft-popup-head-offset: 0;
 
   /* Padding for Surface component container (desktop) */
-  --ft-surface-padding: 24px;
+  --ft-surface-padding: 20px;
 
   /* Padding for Surface component container on mobile devices (max-width: 400px) */
   --ft-surface-padding-mobile: 20px;
@@ -523,6 +650,7 @@ Here's an example of dark theme colors that work well with the survey components
   --ft-color-bg: 220 13% 13%;
   --ft-color-muted: 214 10% 60%;
   --ft-color-error: 14 90% 62%;
+  --ft-color-error-text: 14 85% 72%;
   --ft-color-border: 217 10% 28%;
   --ft-color-outline: 216 12% 45%;
   --ft-color-shadow: 0 0% 0%;
@@ -549,7 +677,7 @@ Here's an example of dark theme colors that work well with the survey components
 **Implementation example with React:**
 
 ```tsx
-import { CSAT5Survey } from 'react-feedback-surveys';
+import { Survey } from 'react-feedback-surveys';
 import 'react-feedback-surveys/index.css';
 import { useEffect } from 'react';
 
@@ -573,7 +701,9 @@ function App() {
   }, []);
 
   return (
-    <CSAT5Survey
+    <Survey
+      type="csat"
+      points={5}
       scaleStyle="emoji"
       question="How satisfied are you with our product?"
       onScoreSubmit={({ value }) => console.log('Score:', value)}
@@ -608,7 +738,7 @@ For deeper customization strategies, see the section below.
 
 ### Custom Classes
 
-All widgets accept a `classNames` prop with two optional groups: `base` (outer shell) and `scale` (the interactive
+`Survey` accepts a `classNames` prop with two optional groups: `base` (outer shell) and `scale` (the interactive
 rating UI). Pass your own class names to override styles without relying on internal selectors.
 
 When is this useful?
@@ -637,13 +767,13 @@ Reference: available keys
 | `scale.score`   | Number inside a scale button (for numeric variants)          |
 | `scale.labels`  | Left/Right labels displayed under the scale                  |
 
-Example: customizing a CSAT5Survey widget
+Example: customizing a `Survey` widget
 
 ```tsx
-import { CSAT5Survey } from 'react-feedback-surveys';
+import { Survey } from 'react-feedback-surveys';
 import 'react-feedback-surveys/index.css';
 
-<CSAT5Survey
+<Survey
   classNames={{
     base: {
       base: 'my-survey-base',
@@ -659,6 +789,8 @@ import 'react-feedback-surveys/index.css';
       labels: 'my-scale-labels',
     }
   }}
+  type="csat"
+  points={5}
   scaleStyle="numbers"
   question="How would you rate your satisfaction with our product?"
   minLabel="Very unsatisfied"