@quietsapa/qsl 0.1.0

package/src/plugins/triggers.js

@@ -0,0 +1,247 @@
+/**
+ * Built-in trigger handlers.
+ *
+ * A trigger handler receives the raw trigger option and the flow/process it
+ * belongs to, and returns a function `(cb) => void` that invokes `cb` once the
+ * trigger fires. Returning `null` means "not my trigger" and lets the next
+ * registered handler try.
+ */
+
+/**
+ * Read the argument part of a prefixed trigger option.
+ *
+ * Uses `slice` rather than `split(':')` so that arguments containing colons
+ * (CSS pseudo-classes, media queries, URLs) survive intact.
+ *
+ * @param {string} opt - Full trigger option, e.g. `hover:.btn:first-child`.
+ * @param {string} prefix - Prefix including the colon, e.g. `hover:`.
+ * @returns {string} The argument, e.g. `.btn:first-child`.
+ */
+const arg = (opt, prefix) => opt.slice(prefix.length);
+
+/**
+ * Check whether an option is a string starting with the given prefix.
+ *
+ * @param {*} opt - Trigger option.
+ * @param {string} prefix - Prefix including the colon.
+ * @returns {boolean}
+ */
+const isPrefixed = (opt, prefix) => typeof opt === 'string' && opt.startsWith(prefix);
+
+/**
+ * Resolve an element now, or once it is inserted into the document.
+ *
+ * `appears:` and `visible:` may reference elements that are rendered later, so
+ * a plain `querySelector` at registration time is not enough.
+ *
+ * @param {string} selector - CSS selector.
+ * @param {Function} cb - Called with the element once it exists.
+ * @returns {void}
+ */
+const whenElement = (selector, cb) => {
+    let el = null;
+    try {
+        el = document.querySelector(selector);
+    } catch (e) {
+        /* Invalid selector: fail open so the flow is never stuck. */
+        cb(null);
+        return;
+    }
+
+    if (el) {
+        cb(el);
+        return;
+    }
+
+    if (typeof MutationObserver !== 'function') {
+        cb(null);
+        return;
+    }
+
+    const root = document.body || document.documentElement;
+    if (!root) {
+        cb(null);
+        return;
+    }
+
+    const observer = new MutationObserver(() => {
+        const found = document.querySelector(selector);
+        if (found) {
+            observer.disconnect();
+            cb(found);
+        }
+    });
+    observer.observe(root, { childList: true, subtree: true });
+};
+
+/**
+ * `load` - fires on the window load event.
+ * @param {Object} QSL
+ */
+export function loadTrigger(QSL) {
+    QSL.triggerHandlers.add(function (opt) {
+        if (opt !== 'load') return null;
+        return (cb) => {
+            if (document.readyState === 'complete') {
+                cb();
+            } else {
+                window.addEventListener('load', () => cb(), { once: true });
+            }
+        };
+    });
+}
+
+/**
+ * `idle` - fires when the browser is idle.
+ * @param {Object} QSL
+ */
+export function idleTrigger(QSL) {
+    QSL.triggerHandlers.add(function (opt) {
+        if (opt !== 'idle') return null;
+        return (cb) => {
+            if (typeof window.requestIdleCallback === 'function') {
+                window.requestIdleCallback(() => cb());
+            } else {
+                setTimeout(() => cb(), 200);
+            }
+        };
+    });
+}
+
+/**
+ * `domready` - fires on DOMContentLoaded.
+ *
+ * `interactive` means DOMContentLoaded has already fired, so a listener added
+ * at that point would never run.
+ *
+ * @param {Object} QSL
+ */
+export function domReadyTrigger(QSL) {
+    QSL.triggerHandlers.add(function (opt) {
+        if (opt !== 'domready') return null;
+        return (cb) => {
+            if (document.readyState === 'interactive' || document.readyState === 'complete') {
+                cb();
+            } else {
+                document.addEventListener('DOMContentLoaded', () => cb(), { once: true });
+            }
+        };
+    });
+}
+
+/**
+ * `delay:<ms>` - fires after a timeout.
+ * @param {Object} QSL
+ */
+export function delayTrigger(QSL) {
+    QSL.triggerHandlers.add(function (opt) {
+        if (!isPrefixed(opt, 'delay:')) return null;
+        const ms = parseInt(arg(opt, 'delay:'), 10);
+        return (cb) => setTimeout(cb, Number.isFinite(ms) && ms > 0 ? ms : 0);
+    });
+}
+
+/**
+ * `hover:<selector>` - fires when the pointer enters the element.
+ * @param {Object} QSL
+ */
+export function hoverTrigger(QSL) {
+    QSL.triggerHandlers.add(function (opt) {
+        if (!isPrefixed(opt, 'hover:')) return null;
+        const selector = arg(opt, 'hover:');
+        return (cb) => {
+            whenElement(selector, (el) => {
+                if (!el) {
+                    cb();
+                    return;
+                }
+                el.addEventListener('mouseenter', () => cb(), { once: true, passive: true });
+            });
+        };
+    });
+}
+
+/**
+ * `visible:<selector>` - fires when the element intersects the viewport.
+ * @param {Object} QSL
+ */
+export function visibleTrigger(QSL) {
+    QSL.triggerHandlers.add(function (opt) {
+        if (!isPrefixed(opt, 'visible:')) return null;
+        const selector = arg(opt, 'visible:');
+        return (cb) => {
+            whenElement(selector, (el) => {
+                if (!el || typeof IntersectionObserver !== 'function') {
+                    cb();
+                    return;
+                }
+                const observer = new IntersectionObserver((entries) => {
+                    for (const entry of entries) {
+                        if (entry.isIntersecting) {
+                            observer.disconnect();
+                            cb();
+                            return;
+                        }
+                    }
+                });
+                observer.observe(el);
+            });
+        };
+    });
+}
+
+/**
+ * `appears:<selector>` - fires when the element is inserted into the DOM.
+ * @param {Object} QSL
+ */
+export function appearsTrigger(QSL) {
+    QSL.triggerHandlers.add(function (opt) {
+        if (!isPrefixed(opt, 'appears:')) return null;
+        const selector = arg(opt, 'appears:');
+        return (cb) => whenElement(selector, () => cb());
+    });
+}
+
+/**
+ * `media:<query>` - fires when the media query matches, now or later.
+ * @param {Object} QSL
+ */
+export function mediaQueryTrigger(QSL) {
+    QSL.triggerHandlers.add(function (opt, o) {
+        if (!isPrefixed(opt, 'media:')) return null;
+        const query = arg(opt, 'media:');
+        return (cb) => {
+            if (!query.length || typeof window.matchMedia !== 'function') {
+                if (o) o.skipped = true;
+                cb();
+                return;
+            }
+            const mql = window.matchMedia(query);
+            if (mql.matches) {
+                cb();
+                return;
+            }
+            const handler = (e) => {
+                if (!e.matches) return;
+                mql.removeEventListener('change', handler);
+                cb();
+            };
+            mql.addEventListener('change', handler);
+        };
+    });
+}
+
+/**
+ * Register every built-in trigger handler.
+ * @param {Object} QSL
+ */
+export default function (QSL) {
+    loadTrigger(QSL);
+    idleTrigger(QSL);
+    domReadyTrigger(QSL);
+    delayTrigger(QSL);
+    hoverTrigger(QSL);
+    visibleTrigger(QSL);
+    appearsTrigger(QSL);
+    mediaQueryTrigger(QSL);
+}

package/src/presets/default.js

@@ -0,0 +1,7 @@
+import core from '../core.js';
+
+import { Script } from '../types.js';
+
+core
+    .registerTypes([Script])
+    .init();

package/src/presets/full.js

@@ -0,0 +1,34 @@
+import core from '../core.js';
+
+import { Script, InlineScript, InlineStyle, Stylesheet, Pixel, Shadow, HTML } from '../types.js';
+
+import { mediaQueryCondition, languageCondition, timezoneCondition, urlCondition, userAgentCondition } from '../plugins/conditions.js';
+import { loadTrigger, idleTrigger, domReadyTrigger, delayTrigger, hoverTrigger, visibleTrigger, appearsTrigger, mediaQueryTrigger } from '../plugins/triggers.js';
+
+import logger from '../plugins/logger.js';
+import events from '../plugins/events.js';
+import circ from '../plugins/circ.js';
+
+core
+    .registerTypes([Script, InlineScript, InlineStyle, Stylesheet, Pixel, Shadow, HTML])
+
+    .use(logger)
+    .use(events)
+    .use(circ)
+
+    .use(mediaQueryCondition)
+    .use(languageCondition)
+    .use(timezoneCondition)
+    .use(urlCondition)
+    .use(userAgentCondition)
+
+    .use(loadTrigger)
+    .use(idleTrigger)
+    .use(domReadyTrigger)
+    .use(delayTrigger)
+    .use(hoverTrigger)
+    .use(visibleTrigger)
+    .use(appearsTrigger)
+    .use(mediaQueryTrigger)
+
+    .init();

package/src/types.js

@@ -0,0 +1,318 @@
+/**
+ * Get cache-bypass suffix for a URL.
+ */
+const bypassSuffix = (source, bypassCache) =>{
+    return bypassCache ? ( ( source.includes('?') ? '&' : '?') + Date.now() ) : '';
+}
+
+/**
+ * Log a message.
+ */
+const log = (detail) => {
+    window.dispatchEvent(new CustomEvent('QSL:log', { detail }));
+}
+
+/**
+ * Log an error.
+ */
+const error = (detail) => {
+    window.dispatchEvent(new CustomEvent('QSL:error', { detail }));
+}
+
+/**
+ * Render an element.
+ */
+const render = (config, callbacks = {}) => {
+    return new Promise(async (resolve) => {
+        const { flowId, tag, id, delay, data, onBeforeStart, onComplete, onError, footer, dom, onElement, onCustomResolve } = config;
+        if (!flowId || !tag || !id) {
+            resolve();
+            return;
+        }
+        try {
+            if (onBeforeStart) await onBeforeStart(config);
+            log({ tag, type: 'PROCESS_STARTED', config });
+            if (delay) await new Promise(res => setTimeout(res, delay));
+            let el = document.createElement(tag);
+            onElement?.(el, config);
+
+            callbacks.registerProcessElement?.(el, config);
+
+            if (data && typeof data === 'object') {
+                for (const [key, value] of Object.entries(data)) {
+                    el.setAttribute(`data-${key.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/[^a-z0-9_-]/g, '').replace(/^-/, '')}`, String(value));
+                }
+            }
+
+            if (!onCustomResolve) {
+                el.onload = () => {
+                    log({ tag, type: 'PROCESS_COMPLETED', config });
+                    onComplete?.();
+                    resolve();
+                };
+            }
+            el.onerror = (e) => {
+                error({ tag, type: 'PROCESS_FAILED', config });
+                onError?.(e);
+                resolve(e);
+            };
+            if (dom) {
+                (footer ? document.body : document.head).appendChild(el);
+            }
+            onCustomResolve?.({ el, config, resolve });
+        } catch (e) {
+            error({ tag, type: 'PROCESS_FAILED', config, error: e });
+            onError?.(e);
+            resolve(e);
+        }
+    });
+}
+
+/**
+ * Render an inline script.
+ */
+const InlineScript = {
+    type: 'inline-script',
+    handler: (config, callbacks) => {      
+        let storedResolve = null;
+        let alreadyFired = false;
+        const eventName = `QSL:inline-script:completed:${config.id}`;
+        const resolveProcess = () => {
+            log({ tag: 'inline-script', type: 'INLINE_SCRIPT_SUCCESS', config });
+            log({ tag: 'inline-script', type: 'PROCESS_COMPLETED', config });
+            config?.onComplete?.();
+            storedResolve?.();
+        };
+        const normalizedConfig = {
+            ...config,
+            code: config.code?.replace(/<script.*?>|<\/script>/gi, '')
+        };
+        return render({
+            ...normalizedConfig,
+            tag: 'script',
+            dom: true,
+            onElement: (el, config) => {
+                const { code, module, id, flowId } = config;
+                if (code) el.textContent = code;
+                if (module) {
+                    el.type = 'module';
+                    const originalCode = el.textContent;
+                    const fid = JSON.stringify(String(flowId));
+                    const pid = JSON.stringify(String(id));
+                    const evt = JSON.stringify(String(eventName));
+                    const wrappedCode = `(function(){window.__QSL__.currentProcessPerFlow.set(${fid},${pid});try{${originalCode}}finally{window.__QSL__.currentProcessPerFlow.delete(${fid});window.dispatchEvent(new Event(${evt}));}})();`;
+                    el.textContent = wrappedCode;
+                    const handler = () => {
+                        window.removeEventListener(eventName, handler);
+                        if (storedResolve) {
+                            resolveProcess();
+                        } else { 
+                            alreadyFired = true;
+                        }
+                    };
+                    window.addEventListener(eventName, handler);
+                }
+            },
+            onCustomResolve: ({ el, config, resolve }) => {
+                const { module } = config;
+                storedResolve = resolve;
+                if (module && alreadyFired) {
+                    resolveProcess();
+                } else if (!module) {
+                    queueMicrotask(() => {
+                        if (storedResolve === resolve) resolveProcess();
+                    });
+                }
+            }
+        }, callbacks);
+    }
+};
+
+/**
+ * Render a script element.
+ */
+const Script = {
+    type: 'script',
+    handler: (config, callbacks) => {     
+        return render({
+            ...config,
+            tag: 'script',
+            dom: true,
+            onElement: (el, { src, module, async, defer, crossOrigin, integrity, bypassCache }) => {
+                if (module) el.type = 'module';
+                if (async) el.async = async;
+                if (defer) el.defer = defer;
+                if (crossOrigin) el.crossOrigin = crossOrigin;
+                if (integrity) el.integrity = integrity;
+                if (src) el.src = src + bypassSuffix(src, bypassCache);
+            }
+        }, callbacks);
+    }
+};
+
+/**
+ * Render an inline style.
+ */
+const InlineStyle = {
+    type: 'style',
+    handler: (config, callbacks) => {
+        const normalizedConfig = {
+            ...config,
+            code: config.code?.replace(/<style.*?>|<\/style>/gi, '')
+        };
+        return render({
+            ...normalizedConfig,
+            tag: 'style',
+            dom: true,
+            onElement: (el, { code }) => {
+                if (code) el.textContent = code;
+            },
+            onCustomResolve: ({ el, config, resolve }) => {
+                const { tag, onComplete } = config;
+                log({ tag, type: 'INLINE_STYLE_SUCCESS', config });
+                log({ tag, type: 'PROCESS_COMPLETED', config });
+                onComplete?.();
+                resolve();
+            }
+        }, callbacks);
+    }
+};
+
+/**
+ * Render a stylesheet.
+ */
+const Stylesheet = {
+    type: 'stylesheet',
+    handler: (config, callbacks) => {
+        return render({
+            ...config,
+            tag: 'link',
+            dom: true,
+            onElement: (el, { href, crossOrigin, bypassCache }) => {
+                el.rel = 'stylesheet';
+                if (crossOrigin) el.crossOrigin = crossOrigin;
+                el.href = href + bypassSuffix(href, bypassCache);
+            }
+        }, callbacks);
+    }
+};
+
+/**
+ * Render a pixel.
+ */
+const Pixel = {
+    type: 'pixel',
+    handler: (config, callbacks) => {
+        return render({
+            ...config,
+            tag: 'img',
+            dom: true,
+            onElement: (el, { style = { display: 'none' }, dom, src, bypassCache }) => {
+                if ( ! dom ) el = new window.Image();
+                el.src = src + bypassSuffix(src, bypassCache);
+                el.width = 1;
+                el.height = 1;
+                if ( style && typeof style === 'object' ) {
+                    for (const [key, value] of Object.entries(style)) {
+                        el.style.setProperty(key, value);
+                    }
+                }
+            },
+            onCustomResolve: ({ el, config, resolve }) => {
+                const { tag, dom, onComplete } = config;
+                const resolver = () => {
+                    log({ tag, type: 'IMAGE_LOADED', config });
+                    log({ tag, type: 'PROCESS_COMPLETED', config });
+                    onComplete?.();
+                    resolve();
+                };
+                ! dom ? resolver() : el.onload = () => resolver();
+            }
+        }, callbacks);
+    }
+};
+
+/**
+ * Render a custom element.
+ */
+const Shadow = {
+    type: 'shadow',
+    handler: (config, callbacks) => {
+        return render({
+            ...config,
+            onBeforeStart: async ({ tag }) => await window.customElements.whenDefined(tag),
+            onElement: (el, { shadowData }) => {
+                el.data = shadowData || {};
+                if (shadowData?.hidden) el.setAttribute('hidden', '');    
+            },
+            onCustomResolve: ({ el, config, resolve }) => {
+                const { tag, shadowData, onComplete, onError } = config;
+                const resolver = () => {
+                    const selector = shadowData?.container;
+                    let container = null;
+                    if (selector === 'body') {
+                        container = document.body;
+                    } else if (typeof selector === 'string' && selector) {
+                        try {
+                            container = document.querySelector(selector);
+                        } catch (e) {
+                            container = null;
+                        }
+                    }
+                    if (!container) {
+                        const err = new Error(`Container not found: ${selector}`);
+                        error({ tag, type: 'SHADOW_FAILED', config, error: err });
+                        onError?.(err);
+                        resolve(err);
+                        return;
+                    }
+                    shadowData?.position === 'top' ? container.insertBefore(el, container.firstChild) : container.appendChild(el);
+                    log({ tag, type: 'SHADOW_SUCCESS', config });
+                    log({ tag, type: 'PROCESS_COMPLETED', config });
+                    onComplete?.();
+                    resolve();
+                };
+                if (document.readyState === 'interactive' || document.readyState === 'complete') {
+                    resolver();
+                } else {
+                    document.addEventListener('DOMContentLoaded', resolver, { once: true });
+                }
+            }
+        }, callbacks);
+    }
+}
+
+/**
+ * Render an HTML element.
+ */
+const HTML = {
+    type: 'html',
+    handler: (config, callbacks) => {
+        return render({
+            ...config,
+            dom: true,
+            onElement: (el, { html = '', id = '', className = '', style = {} }) => {
+                if (html) el.innerHTML = html;
+                if (id) el.id = id;
+                if (className) el.className = Array.isArray(className) ? className.join(' ') : className;
+                if ( style && typeof style === 'object' ) {
+                    for (const [key, value] of Object.entries(style)) {
+                        el.style.setProperty(key, value);
+                    }
+                }
+            },
+            onCustomResolve: ({ el, config, resolve }) => {
+                const { tag, onComplete } = config;
+                log({ tag, type: 'HTML_SUCCESS', config });
+                log({ tag, type: 'PROCESS_COMPLETED', config });
+                onComplete?.();
+                resolve();
+            }
+        }, callbacks);
+    }
+};
+
+/**
+ * Default types for QSL.
+ */
+export { Script, Stylesheet, InlineScript, InlineStyle, Pixel, Shadow, HTML };