@qaiddev/quests-embed 1.5.0 → 1.6.0

package/README.md

@@ -78,8 +78,8 @@ For complex configurations or inline questionnaires, use a separate JSON config
 2. A response record is created on your server (`POST` to `endpoint`)
 3. Questions render one at a time with a progress bar and Back/Next navigation
 4. Answers autosave as the user moves between steps (`PATCH` per question). Text and currency fields debounce by `saveDebounceMs` (default 500ms)
-5. On the final step, all answers are submitted in a single batch (`POST` to `{endpoint}/{id}/submit`)
-6. A "thank you" screen appears when finished
+5. On the final step, the answers to the questions still visible are submitted in a single batch (`POST` to `{endpoint}/{id}/submit`). An answer to a question that `visibleIf` has since hidden is left out, and cleared on the server with a `PATCH` of `null`
+6. A "thank you" screen appears once the server accepts the submit. If the create or the submit fails (a network error or a non-2xx reply), the embed shows "Couldn't send your answers" with a **Try again** button instead; the answers are kept, and Try again re-creates the response first if it has to
 
 If `container` is set, the form renders inline inside that element. If not, it opens as a centered modal with a backdrop.
 
@@ -242,18 +242,18 @@ We offer a Free Plan that hosts both the endpoint and a dashboard for managing y
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `autoAdvance` | `boolean` | `false` | Advance automatically on selection for single-choice multiple-choice and range questions |
+| `autoAdvance` | `boolean` | `false` | Advance automatically when an option is picked on a single-choice multiple-choice question. No other type auto-advances (multi-select, text, currency, range and date wait for Next / Enter) |
 | `saveDebounceMs` | `number` | `500` | Debounce in ms for autosave on text/currency/range |
 | `autoFocus` | `boolean` | `true` | Auto-focus the input on each step. Set `false` in preview/embedded contexts that shouldn't steal focus |
 
 ### Host integration
 
-For programmatic embedding — e.g. launching a quest from another widget — these hooks let the host pass correlation data in and react to the quest's lifecycle. They're only useful when you construct `QaidQuests` yourself (not via the auto-init `<script>` tag).
+For programmatic embedding — e.g. launching a quest from another widget — these hooks let the host pass correlation data in and react to the quest's lifecycle. `metadata` can also be set on the `<script>` tag as `data-metadata`; the two callbacks are functions, so they need you to construct `QaidQuests` yourself.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `metadata` | `Record<string, unknown>` | — | Extra key/value pairs sent verbatim in the create-response `POST` body. The server decides which keys it persists; unknown keys are ignored. Used, for example, by `@qaiddev/thumbs-embed` to pass `{ feedbackId }` so the QAid backend joins the quest answers to the feedback record. |
-| `onComplete` | `(answers) => void` | — | Called once when the quest is completed and submitted (just after the thank-you screen renders), with a copy of the collected answers. Fires in both modal and inline modes. |
+| `onComplete` | `(answers) => void` | — | Called once when the quest is completed and the server accepted the submit (just after the thank-you screen renders), with a copy of the submitted answers — answers to questions hidden by `visibleIf` are left out. Not called while the submit is failing. Fires in both modal and inline modes. |
 | `onClose` | `() => void` | — | Called once when the embed is torn down — visitor close, host `destroy()`, or teardown after completion. Lets a host that launched the quest drop its reference. |
 
 ```typescript
@@ -297,25 +297,45 @@ Colors accept hex (`#ABC`, `#AABBCC`) or `rgb(r, g, b)` format. The text color u
 
 ## Script Tag Data Attributes
 
-When using the script tag method, all config options are available as `data-*` attributes:
+Every config option except the two callbacks (`onComplete`, `onClose`) has a `data-*` attribute, so the script tag alone can set anything else. If a JSON config block is also on the page, the block wins and the attributes are not read.
+
+Object options take JSON. In HTML, wrap the value in single quotes so the JSON's double quotes survive: `data-metadata='{"feedbackId":"clx1"}'`.
 
 | Attribute | Maps To |
 |-----------|---------|
-| `data-endpoint` | `endpoint` |
-| `data-config-url` | `configUrl` |
+| `data-endpoint` | `endpoint` (required) |
 | `data-api-key` | `apiKey` |
+| `data-questionnaire` | `questionnaire`: the questionnaire as JSON, with a `questions` array. Starts the quest without `data-config-url` |
+| `data-config-url` | `configUrl` |
 | `data-container` | `container` |
 | `data-zindex` | `zIndex` |
-| `data-positive-color` | `colors.positive` |
-| `data-negative-color` | `colors.negative` |
-| `data-marker-color` | `colors.marker` |
+| `data-accent-color` | `colors.accent` |
+| `data-error-color` | `colors.error` |
+| `data-focus-color` | `colors.focus` |
+| `data-positive-color` | `colors.positive` (deprecated alias for `colors.accent`) |
+| `data-negative-color` | `colors.negative` (deprecated alias for `colors.error`) |
+| `data-marker-color` | `colors.marker` (deprecated alias for `colors.focus`) |
 | `data-modal-width` | `modalWidth` |
 | `data-backdrop-opacity` | `backdropOpacity` |
 | `data-font-family` | `fontFamily` |
 | `data-font-size` | `fontSize` |
+| `data-css` | `css` (wins over `data-css-selector`) |
+| `data-css-selector` | `css`, taken from the `textContent` of the element this selector matches |
 | `data-auto-advance` | `autoAdvance` (`"true"` to enable) |
 | `data-save-debounce-ms` | `saveDebounceMs` |
-| `data-css-selector` | CSS selector for an element whose `textContent` is used as `css` |
+| `data-auto-focus` | `autoFocus` (`"true"` or `"false"`) |
+| `data-animate` | `animate` (`"true"` or `"false"`) |
+| `data-progress-position` | `progressPosition` (`"top"` or `"bottom"`) |
+| `data-theme` | `theme` (`"light"`, `"dark"` or `"auto"`) |
+| `data-unstyled` | `unstyled` (`"true"` to enable) |
+| `data-preset` | `preset` (`"default"`, `"minimal"`, `"pill"` or `"dense"`) |
+| `data-theme-url` | `themeUrl` |
+| `data-theme-document` | `themeDocument`, as a JSON object |
+| `data-metadata` | `metadata`, as a JSON object |
+
+`onComplete` and `onClose` are functions, so they can only be passed from code (`new QaidQuests({ ... })`).
+
+A value the embed can't use (malformed JSON, a questionnaire with no `questions` array, `data-auto-focus="yes"`, an unknown `data-progress-position`) is ignored with one `console.warn` naming the attribute, and the default stays.
 
 ## Modal vs. Inline
 
@@ -422,8 +442,14 @@ Your endpoint should return `{ "id": "..." }` (string or number). The form is us
 ```
 
 `value` is `string | number | string[] | null` depending on the question type.
-
-**3. Submit** — `POST {endpoint}/{id}/submit`:
+Just before submitting, the embed sends `"value": null` for every answered
+question that `visibleIf` has since hidden, so a server that stores answers
+from these PATCHes drops them too.
+
+**3. Submit** — `POST {endpoint}/{id}/submit`. `answers` holds only the
+questions visible at submit time. Reply with a 2xx; anything else (or a
+network error) shows the visitor a retry screen instead of the thank-you
+screen:
 
 ```json
 {

package/dist/bootstrap.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Reading config from the page for the script-tag install: the JSON config
+ * block and the embed's own `data-*` attributes.
+ *
+ * Kept out of `index.ts` so it can be tested: `index.ts` runs auto-init as a
+ * side effect of being imported and is excluded from coverage. Not re-exported
+ * from `index.ts`, so none of this is public API.
+ */
+import type { QuestsConfig } from "./types";
+/**
+ * Config from `<script type="application/json" data-quests-config>`.
+ * When present and valid it wins outright; the attributes are not read.
+ */
+export declare function parseJsonConfig(): Partial<QuestsConfig> | null;
+/**
+ * Config from the embed's own `data-*` attributes. Every option that can be
+ * written as text has one; only the `onComplete` / `onClose` callbacks need
+ * code.
+ */
+export declare function parseDataAttributes(script: HTMLScriptElement): Partial<QuestsConfig> | null;

package/dist/embed.d.ts

@@ -1,4 +1,14 @@
 import type { Answers, Questionnaire, QuestsConfig } from "./types";
+/**
+ * A random v4 UUID.
+ *
+ * `crypto.randomUUID` exists only in secure contexts (HTTPS and localhost). On
+ * a plain http:// page it is undefined, and calling it threw while mounting, so
+ * the quest never appeared. `crypto.getRandomValues` has no such restriction;
+ * `Math.random` covers a runtime with no `crypto` at all. The id only groups
+ * one browser's responses, so it needs to be unique, not secret.
+ */
+export declare function randomId(): string;
 export declare class QaidQuests {
     private config;
     private questionnaire;
@@ -14,6 +24,10 @@ export declare class QaidQuests {
     private answers;
     private responseId;
     private visitorId;
+    private createPromise;
+    private createPending;
+    private droppedSaves;
+    private submitting;
     private pendingSaveTimer;
     private pendingSaveQuestionId;
     private pendingSaveValue;
@@ -72,6 +86,13 @@ export declare class QaidQuests {
     private renderHeader;
     private renderStep;
     private renderDone;
+    /**
+     * Shown instead of the thank-you screen when the response could not be
+     * created or the submit was refused. The answers stay in memory, so
+     * "Try again" re-runs the whole submit (re-creating the response first
+     * if needed) without the visitor re-entering anything.
+     */
+    private renderSubmitError;
     private advance;
     private back;
     private recomputeVisible;
@@ -79,8 +100,11 @@ export declare class QaidQuests {
     private flushPendingSave;
     private saveAnswer;
     private doSave;
+    private patchAnswer;
+    private startCreate;
     private createResponse;
     private submit;
+    private trySubmit;
     private jsonHeaders;
     private showSaving;
     private handleKeyDown;

package/dist/index.d.ts

@@ -32,5 +32,5 @@
  */
 import { QaidQuests } from "./embed";
 export { QaidQuests };
-export { getVisibleQuestions, evaluateRule } from "./visibility";
+export { getVisibleQuestions, getVisibleAnswers, evaluateRule, } from "./visibility";
 export type { QuestsConfig, ResolvedQuestsConfig, Questionnaire, Question, TextQuestion, CurrencyQuestion, RangeQuestion, DateQuestion, MultipleChoiceQuestion, MultipleChoiceOption, Answers, AnswerValue, VisibilityRule, CreateResponsePayload, CreateResponseResult, UpdateAnswerPayload, SubmitPayload, } from "./types";