@qaiddev/quests-embed 1.4.0 → 1.5.3

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,7 +242,7 @@ 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 |
 
@@ -253,7 +253,7 @@ For programmatic embedding — e.g. launching a quest from another widget — th
 | 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
@@ -348,8 +348,52 @@ const quests = new QaidQuests(config: QuestsConfig);
 | Method | Description |
 |--------|-------------|
 | `getAnswers()` | Read-only snapshot of the answers collected so far, keyed by question id |
+| `getCurrentQuestionId()` | Id of the question on screen, or `null` if the embed isn't on one (loading, finished, or unmounted) |
+| `goToStep(questionId)` | Jump to a visible question. Returns `false` if it's unknown or hidden by an unmet `visibleIf`. Latched if the embed is still initializing |
+| `update(questionnaire)` | Swap in a new questionnaire without re-mounting. Returns whether it was applied — see below |
 | `destroy()` | Remove all DOM elements, event listeners, and injected styles. Safe to call multiple times |
 
+#### `update(questionnaire)`
+
+For hosts that render a questionnaire while it is being authored — a live
+preview in an editor, say. Rebuilding the embed on every edit re-mounts the
+shadow root, repaints the loading state, and re-runs both the theme fetch and
+the create call; because that path awaits the network it always paints a blank
+frame first, which is what makes a live preview flicker as the author types.
+
+`update()` re-renders the header and the current step, synchronously. The
+shadow root, the resolved theme, the response id and the answers so far all
+survive, and focus is left wherever the host put it — it does not pull focus
+into the form the way stepping through it does.
+
+Answers are kept for questions that still exist and dropped for ones that
+don't, so `getAnswers()` never reports an id the questionnaire has no question
+for. The reader's place is kept the same way: if the question on screen is
+still present and visible, the embed stays on it; otherwise the step index is
+clamped into range.
+
+It returns `false`, leaving the embed exactly as it was, when:
+
+- the questionnaire has no questions,
+- every question is gated off behind an unmet `visibleIf`, so there would be
+  nothing to render,
+- or the reader has already completed the form — resuming a submitted response
+  isn't something the embed can decide for you, so rebuild if you want the new
+  form there.
+
+Called before the embed has finished initializing, the update is latched and
+applied as soon as it is ready (and reported as applied), the same way
+`goToStep` is.
+
+```js
+const quests = new QaidQuests({ endpoint, questionnaire, container: "#preview" });
+
+// later, as the author edits — no teardown, no refetch, no flicker
+if (!quests.update(nextQuestionnaire)) {
+  // refused: rebuild if you need the new questionnaire on screen
+}
+```
+
 ### Server Protocol
 
 The embed talks to your endpoint in three steps:
@@ -378,8 +422,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/embed.d.ts

@@ -1,4 +1,14 @@
-import type { Answers, QuestsConfig } from "./types";
+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;
@@ -8,10 +18,16 @@ export declare class QaidQuests {
     private stepIndex;
     private visibleQuestions;
     private pendingGoToStep;
+    private pendingUpdate;
+    private suppressStepFocus;
     private hasRenderedStep;
     private answers;
     private responseId;
     private visitorId;
+    private createPromise;
+    private createPending;
+    private droppedSaves;
+    private submitting;
     private pendingSaveTimer;
     private pendingSaveQuestionId;
     private pendingSaveValue;
@@ -70,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;
@@ -77,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;
@@ -101,6 +127,33 @@ export declare class QaidQuests {
      * user's place after a forced re-mount.
      */
     getCurrentQuestionId(): string | null;
+    /**
+     * Swap in a new questionnaire without tearing the embed down.
+     *
+     * Built for editor previews, where the alternative — `destroy()` plus a
+     * fresh construction on every edit — re-mounts the shadow root, repaints
+     * the loading state, and re-runs both the theme fetch and the create
+     * call. Because that path awaits the network it always paints a blank
+     * frame first, which is what makes a live preview strobe while the author
+     * types. This re-renders the header and the current step and nothing
+     * else, synchronously: the shadow root, the resolved theme, the response
+     * id and the answers so far all survive.
+     *
+     * Answers are kept for questions that still exist and dropped for ones
+     * that don't, so `getAnswers()` never reports an id the questionnaire has
+     * no question for. The reader's place is kept the same way: if the
+     * question on screen is still present and visible, the embed stays on it,
+     * otherwise the step index is clamped into range.
+     *
+     * Returns whether the update was applied. It is refused, leaving the
+     * embed exactly as it was, when the questionnaire has no questions, or
+     * once the reader has completed the form — resuming a submitted response
+     * is not something this can decide on the host's behalf, so a host that
+     * wants the new form there should rebuild. Called before the embed has
+     * finished initializing, the update is latched and applied as soon as it
+     * is ready (and reported as applied), the same way `goToStep` is.
+     */
+    update(questionnaire: Questionnaire): boolean;
     /**
      * Jump to the visible question with the given id. Returns true if
      * the question is currently visible (and the embed navigated to

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";