@qaiddev/quests-embed 1.1.1 → 1.3.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/a11y.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared accessibility primitives for the qaid embeds.
+ *
+ * These helpers are intentionally framework-free and self-contained (no CSS
+ * dependency) so they can be dropped into any open shadow root. They cover the
+ * cross-cutting WCAG 2.2 AA infrastructure called for in the embed
+ * accessibility plan: live-region announcements, focus management (trap,
+ * save/restore), dialog semantics, and background isolation.
+ *
+ * The API is deliberately identical to @qaiddev/thumbs-embed's a11y module so
+ * both embeds consume one shared surface. In quests-embed specifically:
+ *   - {@link announce} is a GENERAL-PURPOSE announcer for step-change,
+ *     loading, and thank-you messages. It is separate from the pre-existing
+ *     per-step `.qaid-q-error` region (aria-live="polite") in embed.ts — that
+ *     region stays the owner of field-validation errors. Callers should route
+ *     step/status text through announce()'s polite region and only use the
+ *     assertive region for load failures, so the two never clobber each other.
+ */
+/** Host for the live regions: either a shadow root or a plain element. */
+export type AnnounceRoot = ShadowRoot | HTMLElement;
+/** Options accepted by {@link announce}. */
+export interface AnnounceOptions {
+    /** Route the message through the assertive (role="alert") region. */
+    assertive?: boolean;
+}
+/** Options accepted by {@link applyDialog}. */
+export interface ApplyDialogOptions {
+    /** id of the element that labels the dialog (wired via aria-labelledby). */
+    labelledbyId?: string;
+    /** id of the element that describes the dialog (wired via aria-describedby). */
+    describedbyId?: string;
+    /** Fallback accessible name when no labelling element exists. */
+    label?: string;
+}
+/** Handle returned by {@link createFocusTrap}. */
+export interface FocusTrap {
+    /** Remove the trap's key handler and clean up any tabindex it added. */
+    release(): void;
+}
+/**
+ * Announce a message to assistive technology via a visually-hidden live region
+ * mounted inside `root`. The two regions (polite role="status" and assertive
+ * role="alert") are created lazily on first use and reused thereafter.
+ *
+ * The target region is cleared before the new text is written so that repeated
+ * identical messages are re-announced rather than coalesced.
+ */
+export declare function announce(root: AnnounceRoot, message: string, opts?: AnnounceOptions): void;
+/**
+ * Collect the focusable descendants of `container` in DOM order, excluding
+ * disabled controls, elements opted out with tabindex="-1", and elements that
+ * are hidden (via the hidden attribute or an inline display/visibility rule on
+ * themselves or an ancestor up to the document root).
+ */
+export declare function getFocusable(container: HTMLElement): HTMLElement[];
+/**
+ * Trap keyboard focus inside `container`: Tab / Shift+Tab cycle between the
+ * first and last focusable descendants and can never leave the container. On
+ * creation focus moves to the first focusable element, or to the container
+ * itself (made programmatically focusable) when it has no focusable children.
+ *
+ * Call {@link FocusTrap.release} to remove the handler; pair it with
+ * {@link restoreFocus} to return focus to the invoking control.
+ */
+export declare function createFocusTrap(container: HTMLElement): FocusTrap;
+/**
+ * Capture the currently focused element (drilling through shadow roots) so it
+ * can be restored later with {@link restoreFocus}. Returns null when focus is
+ * on nothing focusable.
+ */
+export declare function saveFocus(): HTMLElement | null;
+/**
+ * Restore focus to a previously saved element. Safe to call with null or an
+ * element that has since been detached (a missing/throwing focus is ignored).
+ */
+export declare function restoreFocus(el: HTMLElement | null): void;
+/**
+ * Apply dialog semantics to `el`: role="dialog", aria-modal="true", and the
+ * naming/description wiring described by `opts`. Prefer aria-labelledby /
+ * aria-describedby pointing at visible title/subtitle elements; fall back to
+ * aria-label when no visible label element exists.
+ */
+export declare function applyDialog(el: HTMLElement, opts?: ApplyDialogOptions): void;
+/**
+ * Isolate the background from assistive technology while a dialog is open by
+ * marking every top-level sibling of the dialog inert (with an aria-hidden
+ * fallback). `except` is the open dialog (or any element inside it); the
+ * top-level element that contains it is left interactive.
+ *
+ * Returns a restore function that reverts every attribute this call changed,
+ * leaving elements that were already inert/hidden untouched.
+ */
+export declare function setBackgroundInert(except: HTMLElement): () => void;

package/dist/embed.d.ts

@@ -31,12 +31,19 @@ export declare class QaidQuests {
     private backdropEl;
     private currentInput;
     private boundKeyDown;
+    private savedOpener;
+    private focusTrap;
+    private inertRestore;
     private cssVars;
     private hostThemeOverrides;
     private hostInlineVars;
     private themeUrl;
     private themeDocument;
     private hostCss;
+    private metadata;
+    private onCompleteCb;
+    private onCloseCb;
+    private closed;
     constructor(config: QuestsConfig);
     private init;
     private loadTheme;
@@ -73,6 +80,13 @@ export declare class QaidQuests {
     private jsonHeaders;
     private showSaving;
     private handleKeyDown;
+    /**
+     * Modal mode only: trap Tab within the card and mark the rest of the
+     * page inert while the dialog is open. Runs once (guarded) after the
+     * first step renders. Inline mode keeps normal page tab flow and is
+     * never trapped or isolated.
+     */
+    private setupModalA11y;
     private close;
     /** Destroy the embed and clean up all resources */
     destroy(): void;

package/dist/inputs.d.ts

@@ -15,6 +15,15 @@ export interface QuestionInput {
     focus(): void;
     getValue(): AnswerValue;
     isValid(): boolean;
+    /**
+     * Mark the control invalid: sets aria-invalid="true" and links the
+     * error text (identified by `errorId`) via aria-describedby so a
+     * screen reader reads the error as the field's description. Do not
+     * rely on colour alone (WCAG 3.3.1 / 1.3.1 / 4.1.2).
+     */
+    setInvalid(errorId: string): void;
+    /** Clear aria-invalid and unlink the error text once the field is corrected. */
+    clearInvalid(): void;
 }
 export interface QuestionInputOptions {
     question: Question;