@qaiddev/quests-embed 1.9.0 → 1.10.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -10
- package/dist/embed-loader.d.ts +5 -0
- package/dist/embed.js +1 -1
- package/dist/embed.js.map +1 -1
- package/dist/prefetch.d.ts +13 -0
- package/dist/qaid-quests.js +131 -131
- package/dist/qaid-quests.js.map +1 -1
- package/dist/qaid-quests.umd.cjs +3 -3
- package/dist/qaid-quests.umd.cjs.map +1 -1
- package/dist/types.d.ts +6 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -5,6 +5,10 @@
|
|
|
5
5
|
|
|
6
6
|
A zero-dependency, lightweight questionnaire embed that renders step-by-step forms from a JSON definition. Drop it inline on a page or open it as a modal — answers are autosaved as the user types and submitted to your API endpoint or the [QAid.dev hosted dashboard](https://qaid.dev).
|
|
7
7
|
|
|
8
|
+
It needs 16.8 KB (gzipped) to show a quest: a 0.8 KB tag, then the quest code once the quest is near the screen. See [What loads when](#what-loads-when).
|
|
9
|
+
|
|
10
|
+

|
|
11
|
+
|
|
8
12
|
## Install
|
|
9
13
|
|
|
10
14
|
### npm
|
|
@@ -41,7 +45,20 @@ new QaidQuests({
|
|
|
41
45
|
|
|
42
46
|
The embed auto-initializes when it detects a `data-endpoint` attribute on its script tag and either `data-config-url` or an inline JSON config.
|
|
43
47
|
|
|
44
|
-
`dist/embed.js` is a 0.
|
|
48
|
+
`dist/embed.js` is a 0.8 KB loader (gzipped). It loads the quest code (about 16 KB) when the container comes within a screen's height of the viewport, or once the page has loaded and the browser is idle, whichever is first. Without a `data-container` it loads at once. It starts fetching the questions (`data-config-url`) and theme (`data-theme-url`) at the same moment as the quest code, so they arrive together. A questionnaire may also carry its theme as `themeDocument`, so one request brings both; a `themeUrl` or `themeDocument` set on the tag still wins. Pointing the tag straight at `dist/qaid-quests.umd.cjs` still works and loads everything up front.
|
|
49
|
+
|
|
50
|
+
### What loads when
|
|
51
|
+
|
|
52
|
+
Sizes are gzipped, for 1.10. Times are rough estimates for a first visit on a typical 4G phone (100 ms round trip, 9 Mbps).
|
|
53
|
+
|
|
54
|
+
| When | Size | What it brings | About |
|
|
55
|
+
|------|------|----------------|-------|
|
|
56
|
+
| Before paint | 0 KB | nothing; the tag waits (`defer`) | 0 s |
|
|
57
|
+
| After paint | 0.8 KB | the tag (`embed.js`) | 0.5 s |
|
|
58
|
+
| Quest near the screen, or browser idle | 16 KB | the quest code | 0.1 s |
|
|
59
|
+
| Same moment | +1 KB | the questions and theme, in one request | 0.3 s |
|
|
60
|
+
|
|
61
|
+
The quest is ready about 0.9 s after paint. The questions come from your server on a new connection, so they finish a little after the code even though they start together.
|
|
45
62
|
|
|
46
63
|
### JSON Config (Script Tag)
|
|
47
64
|
|
|
@@ -86,6 +103,8 @@ For complex configurations or inline questionnaires, use a separate JSON config
|
|
|
86
103
|
|
|
87
104
|
If `container` is set, the form renders inline inside that element. If not, it opens as a centered modal with a backdrop.
|
|
88
105
|
|
|
106
|
+

|
|
107
|
+
|
|
89
108
|
## Questionnaire Definition
|
|
90
109
|
|
|
91
110
|
A `Questionnaire` is the JSON document that describes the form. It can be loaded inline via the `questionnaire` config option, or fetched from a URL via `configUrl`.
|
|
@@ -513,6 +532,10 @@ The embed renders inside a Shadow DOM, so your page's CSS can't leak in. To them
|
|
|
513
532
|
|
|
514
533
|
The variable names are shared with `@qaiddev/thumbs-embed`, so a single theme can drive both embeds.
|
|
515
534
|
|
|
535
|
+
For a quick change, the tag takes a preset, a light or dark theme and an accent color. This is `data-preset="pill" data-theme="dark" data-accent-color="#d97706"`:
|
|
536
|
+
|
|
537
|
+

|
|
538
|
+
|
|
516
539
|
## Hosted Dashboard
|
|
517
540
|
|
|
518
541
|
[Qaid](https://qaid.dev) provides a hosted dashboard for managing responses collected by this embed:
|
|
@@ -525,15 +548,7 @@ The variable names are shared with `@qaiddev/thumbs-embed`, so a single theme ca
|
|
|
525
548
|
|
|
526
549
|
### Plans
|
|
527
550
|
|
|
528
|
-
|
|
529
|
-
|---|---|---|---|
|
|
530
|
-
| Projects | 1 | Unlimited | Unlimited |
|
|
531
|
-
| Responses | 100/mo | Unlimited | Unlimited |
|
|
532
|
-
| Data retention | 7 days | 1 year | Unlimited |
|
|
533
|
-
| Notifications | - | Email/Text | Email/Text |
|
|
534
|
-
| Integrations | - | GitHub + more | Custom |
|
|
535
|
-
|
|
536
|
-
Sign up at [qaid.dev](https://qaid.dev). You can also self-host — the embed works with any endpoint that accepts the protocol described above.
|
|
551
|
+
There is a free Cadet plan, a Commander plan at $9 per seat per month, and an Admiral plan for larger teams. See [qaid.dev/pricing](https://qaid.dev/pricing) for what each includes. Sign up at [qaid.dev](https://qaid.dev). You can also self-host — the embed works with any endpoint that accepts the protocol described above.
|
|
537
552
|
|
|
538
553
|
## Self-Hosting
|
|
539
554
|
|
package/dist/embed-loader.d.ts
CHANGED
|
@@ -12,6 +12,11 @@
|
|
|
12
12
|
* - right away, when there is no container to watch (the modal install) or
|
|
13
13
|
* the browser has no IntersectionObserver.
|
|
14
14
|
*
|
|
15
|
+
* When it injects the bundle it also starts fetching the quest's questions
|
|
16
|
+
* (`data-config-url`) and theme (`data-theme-url`), so they download beside
|
|
17
|
+
* the code instead of after it. The bundle picks the requests up from
|
|
18
|
+
* `window.__qaidQuestsPrefetch` (see prefetch.ts).
|
|
19
|
+
*
|
|
15
20
|
* The injected bundle initializes itself from the `data-*` attributes copied
|
|
16
21
|
* across from this tag (or from a `<script type="application/json">` config
|
|
17
22
|
* block already on the page), exactly as if the page had loaded it directly.
|
package/dist/embed.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
(function(){"use strict";(function(){if(typeof document=="undefined")return;function
|
|
1
|
+
(function(){"use strict";(function(){if(typeof document=="undefined")return;function f(){var e=document.currentScript;if(e&&e.src)return e;for(var t=document.getElementsByTagName("script"),n=t.length-1;n>=0;n--){var r=t[n].src||"";if(r.indexOf("quests-embed")!==-1&&/\/embed(\.min)?\.js(\?|#|$)/.test(r))return t[n]}return null}var c=f();if(!c||!c.src)return;var a=c,l=a.src.substring(0,a.src.lastIndexOf("/")+1),u=!1;function i(){if(!u){u=!0;for(var e=document.createElement("script"),t=a.attributes,n=0;n<t.length;n++){var r=t[n];r.name.indexOf("data-")===0&&e.setAttribute(r.name,r.value)}e.src=l+"qaid-quests.umd.cjs",(document.head||document.documentElement).appendChild(e),d(a.getAttribute("data-config-url")),d(a.getAttribute("data-theme-url"))}}function d(e){if(!(!e||typeof fetch!="function")){var t=window,n=t.__qaidQuestsPrefetch||(t.__qaidQuestsPrefetch={});if(!n[e]){var r=fetch(e,{headers:{Accept:"application/json"}});r.catch(function(){}),n[e]=r}}}function v(){function e(){var t=window;typeof t.requestIdleCallback=="function"?t.requestIdleCallback(i,{timeout:3e3}):setTimeout(i,200)}document.readyState==="complete"?e():window.addEventListener("load",e)}function s(){var e=a.getAttribute("data-container"),t=e?document.querySelector(e):null;if(!t||typeof IntersectionObserver=="undefined"){i();return}var n=new IntersectionObserver(function(r){for(var o=0;o<r.length;o++)if(r[o].isIntersecting){n.disconnect(),i();return}},{rootMargin:"100% 0px"});n.observe(t),v()}document.readyState==="loading"?document.addEventListener("DOMContentLoaded",s):s()})()})();
|
|
2
2
|
//# sourceMappingURL=embed.js.map
|
package/dist/embed.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"embed.js","sources":["../src/embed-loader.ts"],"sourcesContent":["/**\n * Single-tag embed loader (`dist/embed.js`).\n *\n * A tiny classic `<script>` that holds back the quest code (the UMD bundle,\n * `qaid-quests.umd.cjs`) until it is needed, so a quest further down the page\n * costs the page nothing while it loads. The bundle is injected when the first\n * of these happens:\n *\n * - the quest's container comes within a screen's height of the viewport;\n * - the page has finished loading and the browser is idle, so the quest is\n * ready before the visitor scrolls to it;\n * - right away, when there is no container to watch (the modal install) or\n * the browser has no IntersectionObserver.\n *\n * The injected bundle initializes itself from the `data-*` attributes copied\n * across from this tag (or from a `<script type=\"application/json\">` config\n * block already on the page), exactly as if the page had loaded it directly.\n *\n * Usage:\n * <div id=\"quest-mount\"></div>\n * <script src=\"https://unpkg.com/@qaiddev/quests-embed/dist/embed.js\" defer\n * data-endpoint=\"/api/responses\" data-config-url=\"/forms/intake.json\"\n * data-container=\"#quest-mount\"></script>\n *\n * IMPORTANT: this file must stay ES5-clean and dependency-free, like the\n * thumbs-embed loader it mirrors: it is the first thing to run on every\n * browser. Written with var/function on purpose.\n */\n\n(function () {\n if (typeof document === \"undefined\") return;\n\n // Locate this script tag: prefer document.currentScript (valid for a plain\n // classic script), else find the last <script> whose src looks like embed.js.\n function findSelf(): HTMLScriptElement | null {\n var cur = document.currentScript as HTMLScriptElement | null;\n if (cur && cur.src) return cur;\n var scripts = document.getElementsByTagName(\"script\");\n for (var i = scripts.length - 1; i >= 0; i--) {\n var src = scripts[i].src || \"\";\n if (src.indexOf(\"quests-embed\") !== -1 && /\\/embed(\\.min)?\\.js(\\?|#|$)/.test(src)) {\n return scripts[i];\n }\n }\n return null;\n }\n\n var self = findSelf();\n if (!self || !self.src) return;\n var tag = self;\n\n // Base = the directory that holds embed.js, e.g.\n // \"https://unpkg.com/@qaiddev/quests-embed@1.9.0/dist/\", so the bundle comes\n // from the same (CDN-versioned) place.\n var base = tag.src.substring(0, tag.src.lastIndexOf(\"/\") + 1);\n\n var loaded = false;\n function load(): void {\n if (loaded) return;\n loaded = true;\n var entry = document.createElement(\"script\");\n // Carry the config across so the bundle's auto-init sees it.\n var attrs = tag.attributes;\n for (var j = 0; j < attrs.length; j++) {\n var a = attrs[j];\n if (a.name.indexOf(\"data-\") === 0) entry.setAttribute(a.name, a.value);\n }\n entry.src = base + \"qaid-quests.umd.cjs\";\n (document.head || document.documentElement).appendChild(entry);\n }\n\n function whenIdleAfterLoad(): void {\n function idle(): void {\n var w = window as Window & {\n requestIdleCallback?: (cb: () => void, opts?: { timeout: number }) => number;\n };\n if (typeof w.requestIdleCallback === \"function\") w.requestIdleCallback(load, { timeout: 3000 });\n else setTimeout(load, 200);\n }\n if (document.readyState === \"complete\") idle();\n else window.addEventListener(\"load\", idle);\n }\n\n function start(): void {\n var selector = tag.getAttribute(\"data-container\");\n var container = selector ? document.querySelector(selector) : null;\n if (!container || typeof IntersectionObserver === \"undefined\") {\n load();\n return;\n }\n var observer = new IntersectionObserver(\n function (entries) {\n for (var k = 0; k < entries.length; k++) {\n if (entries[k].isIntersecting) {\n observer.disconnect();\n load();\n return;\n }\n }\n },\n { rootMargin: \"100% 0px\" },\n );\n observer.observe(container);\n whenIdleAfterLoad();\n }\n\n // The container may come after the tag in the page, so look once it's parsed.\n if (document.readyState === \"loading\") document.addEventListener(\"DOMContentLoaded\", start);\n else start();\n})();\n"],"names":["findSelf","cur","scripts","i","src","self","tag","base","loaded","load","entry","attrs","j","a","
|
|
1
|
+
{"version":3,"file":"embed.js","sources":["../src/embed-loader.ts"],"sourcesContent":["/**\n * Single-tag embed loader (`dist/embed.js`).\n *\n * A tiny classic `<script>` that holds back the quest code (the UMD bundle,\n * `qaid-quests.umd.cjs`) until it is needed, so a quest further down the page\n * costs the page nothing while it loads. The bundle is injected when the first\n * of these happens:\n *\n * - the quest's container comes within a screen's height of the viewport;\n * - the page has finished loading and the browser is idle, so the quest is\n * ready before the visitor scrolls to it;\n * - right away, when there is no container to watch (the modal install) or\n * the browser has no IntersectionObserver.\n *\n * When it injects the bundle it also starts fetching the quest's questions\n * (`data-config-url`) and theme (`data-theme-url`), so they download beside\n * the code instead of after it. The bundle picks the requests up from\n * `window.__qaidQuestsPrefetch` (see prefetch.ts).\n *\n * The injected bundle initializes itself from the `data-*` attributes copied\n * across from this tag (or from a `<script type=\"application/json\">` config\n * block already on the page), exactly as if the page had loaded it directly.\n *\n * Usage:\n * <div id=\"quest-mount\"></div>\n * <script src=\"https://unpkg.com/@qaiddev/quests-embed/dist/embed.js\" defer\n * data-endpoint=\"/api/responses\" data-config-url=\"/forms/intake.json\"\n * data-container=\"#quest-mount\"></script>\n *\n * IMPORTANT: this file must stay ES5-clean and dependency-free, like the\n * thumbs-embed loader it mirrors: it is the first thing to run on every\n * browser. Written with var/function on purpose.\n */\n\n(function () {\n if (typeof document === \"undefined\") return;\n\n // Locate this script tag: prefer document.currentScript (valid for a plain\n // classic script), else find the last <script> whose src looks like embed.js.\n function findSelf(): HTMLScriptElement | null {\n var cur = document.currentScript as HTMLScriptElement | null;\n if (cur && cur.src) return cur;\n var scripts = document.getElementsByTagName(\"script\");\n for (var i = scripts.length - 1; i >= 0; i--) {\n var src = scripts[i].src || \"\";\n if (src.indexOf(\"quests-embed\") !== -1 && /\\/embed(\\.min)?\\.js(\\?|#|$)/.test(src)) {\n return scripts[i];\n }\n }\n return null;\n }\n\n var self = findSelf();\n if (!self || !self.src) return;\n var tag = self;\n\n // Base = the directory that holds embed.js, e.g.\n // \"https://unpkg.com/@qaiddev/quests-embed@1.9.0/dist/\", so the bundle comes\n // from the same (CDN-versioned) place.\n var base = tag.src.substring(0, tag.src.lastIndexOf(\"/\") + 1);\n\n var loaded = false;\n function load(): void {\n if (loaded) return;\n loaded = true;\n var entry = document.createElement(\"script\");\n // Carry the config across so the bundle's auto-init sees it.\n var attrs = tag.attributes;\n for (var j = 0; j < attrs.length; j++) {\n var a = attrs[j];\n if (a.name.indexOf(\"data-\") === 0) entry.setAttribute(a.name, a.value);\n }\n entry.src = base + \"qaid-quests.umd.cjs\";\n (document.head || document.documentElement).appendChild(entry);\n prefetch(tag.getAttribute(\"data-config-url\"));\n prefetch(tag.getAttribute(\"data-theme-url\"));\n }\n\n // Must match PREFETCH_KEY and the request in prefetch.ts.\n function prefetch(url: string | null): void {\n if (!url || typeof fetch !== \"function\") return;\n var w = window as unknown as Record<string, Record<string, Promise<Response> | undefined> | undefined>;\n var store = w.__qaidQuestsPrefetch || (w.__qaidQuestsPrefetch = {});\n if (store[url]) return;\n var request = fetch(url, { headers: { Accept: \"application/json\" } });\n // The embed handles a failure (it retries); this only stops a request\n // nobody picks up from reporting an unhandled rejection.\n request.catch(function () {});\n store[url] = request;\n }\n\n function whenIdleAfterLoad(): void {\n function idle(): void {\n var w = window as Window & {\n requestIdleCallback?: (cb: () => void, opts?: { timeout: number }) => number;\n };\n if (typeof w.requestIdleCallback === \"function\") w.requestIdleCallback(load, { timeout: 3000 });\n else setTimeout(load, 200);\n }\n if (document.readyState === \"complete\") idle();\n else window.addEventListener(\"load\", idle);\n }\n\n function start(): void {\n var selector = tag.getAttribute(\"data-container\");\n var container = selector ? document.querySelector(selector) : null;\n if (!container || typeof IntersectionObserver === \"undefined\") {\n load();\n return;\n }\n var observer = new IntersectionObserver(\n function (entries) {\n for (var k = 0; k < entries.length; k++) {\n if (entries[k].isIntersecting) {\n observer.disconnect();\n load();\n return;\n }\n }\n },\n { rootMargin: \"100% 0px\" },\n );\n observer.observe(container);\n whenIdleAfterLoad();\n }\n\n // The container may come after the tag in the page, so look once it's parsed.\n if (document.readyState === \"loading\") document.addEventListener(\"DOMContentLoaded\", start);\n else start();\n})();\n"],"names":["findSelf","cur","scripts","i","src","self","tag","base","loaded","load","entry","attrs","j","a","prefetch","url","w","store","request","whenIdleAfterLoad","idle","start","selector","container","observer","entries","k"],"mappings":"0BAkCC,UAAY,CACX,GAAI,OAAO,UAAa,YAAa,OAIrC,SAASA,GAAqC,CAC5C,IAAIC,EAAM,SAAS,cACnB,GAAIA,GAAOA,EAAI,IAAK,OAAOA,EAE3B,QADIC,EAAU,SAAS,qBAAqB,QAAQ,EAC3CC,EAAID,EAAQ,OAAS,EAAGC,GAAK,EAAGA,IAAK,CAC5C,IAAIC,EAAMF,EAAQC,CAAC,EAAE,KAAO,GAC5B,GAAIC,EAAI,QAAQ,cAAc,IAAM,IAAM,8BAA8B,KAAKA,CAAG,EAC9E,OAAOF,EAAQC,CAAC,CAEpB,CACA,OAAO,IACT,CAEA,IAAIE,EAAOL,EAAA,EACX,GAAI,CAACK,GAAQ,CAACA,EAAK,IAAK,OACxB,IAAIC,EAAMD,EAKNE,EAAOD,EAAI,IAAI,UAAU,EAAGA,EAAI,IAAI,YAAY,GAAG,EAAI,CAAC,EAExDE,EAAS,GACb,SAASC,GAAa,CACpB,GAAI,CAAAD,EACJ,CAAAA,EAAS,GAIT,QAHIE,EAAQ,SAAS,cAAc,QAAQ,EAEvCC,EAAQL,EAAI,WACPM,EAAI,EAAGA,EAAID,EAAM,OAAQC,IAAK,CACrC,IAAIC,EAAIF,EAAMC,CAAC,EACXC,EAAE,KAAK,QAAQ,OAAO,IAAM,GAAGH,EAAM,aAAaG,EAAE,KAAMA,EAAE,KAAK,CACvE,CACAH,EAAM,IAAMH,EAAO,uBAClB,SAAS,MAAQ,SAAS,iBAAiB,YAAYG,CAAK,EAC7DI,EAASR,EAAI,aAAa,iBAAiB,CAAC,EAC5CQ,EAASR,EAAI,aAAa,gBAAgB,CAAC,EAC7C,CAGA,SAASQ,EAASC,EAA0B,CAC1C,GAAI,GAACA,GAAO,OAAO,OAAU,YAC7B,KAAIC,EAAI,OACJC,EAAQD,EAAE,uBAAyBA,EAAE,qBAAuB,CAAA,GAChE,GAAI,CAAAC,EAAMF,CAAG,EACb,KAAIG,EAAU,MAAMH,EAAK,CAAE,QAAS,CAAE,OAAQ,kBAAA,EAAsB,EAGpEG,EAAQ,MAAM,UAAY,CAAC,CAAC,EAC5BD,EAAMF,CAAG,EAAIG,GACf,CAEA,SAASC,GAA0B,CACjC,SAASC,GAAa,CACpB,IAAIJ,EAAI,OAGJ,OAAOA,EAAE,qBAAwB,WAAYA,EAAE,oBAAoBP,EAAM,CAAE,QAAS,IAAM,EACzF,WAAWA,EAAM,GAAG,CAC3B,CACI,SAAS,aAAe,WAAYW,EAAA,EACnC,OAAO,iBAAiB,OAAQA,CAAI,CAC3C,CAEA,SAASC,GAAc,CACrB,IAAIC,EAAWhB,EAAI,aAAa,gBAAgB,EAC5CiB,EAAYD,EAAW,SAAS,cAAcA,CAAQ,EAAI,KAC9D,GAAI,CAACC,GAAa,OAAO,sBAAyB,YAAa,CAC7Dd,EAAA,EACA,MACF,CACA,IAAIe,EAAW,IAAI,qBACjB,SAAUC,EAAS,CACjB,QAASC,EAAI,EAAGA,EAAID,EAAQ,OAAQC,IAClC,GAAID,EAAQC,CAAC,EAAE,eAAgB,CAC7BF,EAAS,WAAA,EACTf,EAAA,EACA,MACF,CAEJ,EACA,CAAE,WAAY,UAAA,CAAW,EAE3Be,EAAS,QAAQD,CAAS,EAC1BJ,EAAA,CACF,CAGI,SAAS,aAAe,UAAW,SAAS,iBAAiB,mBAAoBE,CAAK,EACrFA,EAAA,CACP,GAAA"}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Requests the script-tag loader (`embed-loader.ts`) starts while the quest
|
|
3
|
+
* code is still downloading, so the questions and theme are on their way, or
|
|
4
|
+
* already here, by the time the code asks for them.
|
|
5
|
+
*
|
|
6
|
+
* The loader keeps them on `window`, keyed by the exact URL from the tag's
|
|
7
|
+
* `data-config-url` / `data-theme-url`, which is the same string the embed
|
|
8
|
+
* fetches. Each is taken once: a response body can only be read once.
|
|
9
|
+
*/
|
|
10
|
+
/** The window property the loader writes and the embed reads. */
|
|
11
|
+
export declare const PREFETCH_KEY = "__qaidQuestsPrefetch";
|
|
12
|
+
/** Fetch `url` as the embed would, or take the loader's request for it. */
|
|
13
|
+
export declare function fetchJson(url: string): Promise<Response>;
|