@qaiddev/quests-embed 1.2.0 → 1.4.0

package/README.md

@@ -246,6 +246,27 @@ We offer a Free Plan that hosts both the endpoint and a dashboard for managing y
 | `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).
+
+| 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. |
+| `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
+const quest = new QaidQuests({
+  endpoint: 'https://qaid.dev/api/quests/responses',
+  configUrl: 'https://qaid.dev/api/quests/<questId>/definition',
+  apiKey: 'YOUR_API_KEY',
+  metadata: { feedbackId: 'clx…' },       // correlate this response server-side
+  onComplete: (answers) => console.log('done', answers),
+  onClose: () => { /* drop your reference */ },
+});
+```
+
 ### Appearance
 
 | Option | Type | Default | Description |

package/dist/embed.d.ts

@@ -26,6 +26,8 @@ export declare class QaidQuests {
     private progressEl;
     private progressFillEl;
     private bodyEl;
+    private scrollCueEl;
+    private overflow;
     private footerEl;
     private savingEl;
     private backdropEl;
@@ -40,6 +42,10 @@ export declare class QaidQuests {
     private themeUrl;
     private themeDocument;
     private hostCss;
+    private metadata;
+    private onCompleteCb;
+    private onCloseCb;
+    private closed;
     constructor(config: QuestsConfig);
     private init;
     private loadTheme;

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;