@qaiddev/quests-embed 1.3.0 → 1.5.0

package/README.md

@@ -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:

package/dist/embed.d.ts

@@ -1,4 +1,4 @@
-import type { Answers, QuestsConfig } from "./types";
+import type { Answers, Questionnaire, QuestsConfig } from "./types";
 export declare class QaidQuests {
     private config;
     private questionnaire;
@@ -8,6 +8,8 @@ export declare class QaidQuests {
     private stepIndex;
     private visibleQuestions;
     private pendingGoToStep;
+    private pendingUpdate;
+    private suppressStepFocus;
     private hasRenderedStep;
     private answers;
     private responseId;
@@ -26,6 +28,8 @@ export declare class QaidQuests {
     private progressEl;
     private progressFillEl;
     private bodyEl;
+    private scrollCueEl;
+    private overflow;
     private footerEl;
     private savingEl;
     private backdropEl;
@@ -99,6 +103,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/overflow.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Keeping a step readable inside whatever box the host gives us.
+ *
+ * The card body is the scroll container. Two things were missing: it never
+ * adapted its own content to the height available (option tiles have width
+ * rules only, so a short container just clipped them), and when content did
+ * overflow there was no sign of it at all — the step simply looked cut off.
+ *
+ * This module owns both. It is DOM-only and free of embed state so it can be
+ * driven directly in tests.
+ */
+/** Where the scroll position currently sits. */
+export type ScrollEdge = "none" | "top" | "middle" | "bottom";
+/**
+ * Below this many pixels of available height, a step switches to its compact
+ * layout: smaller image tiles, tighter gaps. Chosen so the common 2-3 option
+ * step fits without scrolling in a ~360px tall container.
+ */
+export declare const COMPACT_HEIGHT = 360;
+/** Which edges of `el` have content beyond them. */
+export declare function scrollEdgeOf(el: {
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}): ScrollEdge;
+/**
+ * Reflect the scroll state onto the body as `data-qaid-scroll`, which the
+ * stylesheet turns into a fade mask, and onto the cue element's hidden state.
+ */
+export declare function applyScrollState(body: HTMLElement, cue: HTMLElement | null): ScrollEdge;
+/** Reflect the available height onto the card as `data-qaid-fit`. */
+export declare function applyFitState(card: HTMLElement, availableHeight: number): "compact" | "roomy";
+export interface OverflowWatcher {
+    /** Re-measure now — call after rendering a step. */
+    refresh(): void;
+    /** Detach every listener and observer. */
+    destroy(): void;
+}
+/**
+ * Watch `body` for scrolling and resizing, keeping the scroll and fit state
+ * attributes current.
+ *
+ * A ResizeObserver rather than a CSS container query on height: a container
+ * query needs `container-type: size`, which requires a definite height on both
+ * axes, and this card is deliberately content-sized when the host does not
+ * constrain it. Declaring it would collapse the body to nothing in exactly the
+ * inline case the embed supports.
+ */
+export declare function watchOverflow(body: HTMLElement, card: HTMLElement, cue: HTMLElement | null): OverflowWatcher;