u2ui 1.0.1 → 1.4.5

package/js/SelectorObserver/SelectorObserver.js

@@ -1,201 +1,200 @@
-const observers = new Set();
-
-// global mutation observer
-const muObserver = new MutationObserver(checkMutations);
-muObserver.observe(document, {
-    childList: true,
-    subtree: true,
-    attributes: true
-});
-function addTree(el) {
-    for (const observer of observers) observer._addTree(el);
-}
-function removeTree(el) {
-    for (const observer of observers) observer._removeTree(el);
-}
-function treeModified(el) {
-    for (const observer of observers) observer._treeModified(el);
-}
-function checkMutations(mutations) {
-    for (const mutation of mutations) {
-        if (mutation.type==='childList') {
-            for (const target of mutation.addedNodes) {
-                target.nodeType === 1 && addTree(target);
-            }
-            for (const target of mutation.removedNodes) {
-                target.nodeType === 1 && removeTree(target);
-            }
-        }
-        if (mutation.type==='attributes') {
-            treeModified(mutation.target);
-        }
-    }
-}
-
-
-// animation observer (beta), todo:refine and performance tests, problem: can not set multiple animation per selector => can be overwritten
-/*
-let animationCounter = 0;
-let aObservers = new Set();
-class _animationObserver {
-    constructor(selector, on) {
-        this.on = on;
-        // todo?: reuse style element if selector already exists
-        // or better: use same style element for all selectors?
-        // this way we dont overwrite elements targeting by multiple observers,
-        // but we have to match the selector for every observer
-        this.style = document.createElement('style');
-        this.animationName = `u2-selObs-${animationCounter++}`;
-
-        this.style.innerHTML =
-            `@keyframes ${this.animationName}{}\n`+
-            `${selector}{animation:${this.animationName} .1ms}`+
-            `.u2sOTracked:not(${selector}){animation:${this.animationName} .1ms .1ms}`+
-            ``; // todo: :where() when supported
-        document.head.append(this.style);
-        aObservers.add(this);
-    }
-    disconnect(){
-        this.style.remove();
-        aObservers.delete(this);
-    }
-}
-document.addEventListener('animationstart', e => { // todo: remove/add listener by usage
-    for (const observer of aObservers) {
-        if (e.animationName === observer.animationName) {
-            observer.on(e.target);
-            e.target.classList.add('u2sOTracked'); // can be removed if none of the listeners tracking it
-        }
-    }
-});
-*/
-
-
-
-
-
-export class SelectorObserver {
-
-    /**
-     * @param {Object} options
-     * @param {Function} options.on
-     * @param {Function} options.off
-     */
-    constructor({on, off}) {
-        this.targets = new Set(); // was WeakSet, but we clean targets anyway. Better WeakRef-Set? // rename to targets?
-        this._on = on;
-        this._off = off;
-    }
-
-    /**
-     * @param {String} selector
-     */
-    observe(selector, options={}) {
-        this.selector = selector;
-        this.options = options;
-        const els = document.querySelectorAll(this.selector);
-        for (const el of els) this._add(el);
-
-        //if (options.checkMutations!==false) {
-            observers.add(this);
-        //}
-        /*
-        if (options && options.checkAnimation) {
-            this.aniObserver = new _animationObserver(this.selector, el=>{
-                el.matches(this.selector) ? this._add(el) : this._remove(el);
-            });
-        }
-        */
-    }
-
-
-    /**
-     * @description disconnects the observer
-     */
-    disconnect() {
-        this.targets.clear();
-        observers.delete(this);
-        //this.aniObserver && this.aniObserver.disconnect();
-    }
-
-    /**
-     * @private
-     */
-    _add(el) {
-        if (this.targets.has(el)) return;
-        this.targets.add(el);
-        this._on && this._on(el);
-    }
-
-    /**
-     * @private
-     */
-     _remove(el) {
-        if (!this.targets.has(el)) return;
-        this.targets.delete(el);
-        this._off && this._off(el);
-    }
-
-    /**
-     * @private
-     */
-     _addTree(target) {
-        target.matches(this.selector) && this._add(target);
-        if (document.readyState === 'complete') { // Before domready MutationObserver reports every node, ok?
-            for (const el of target.querySelectorAll(this.selector)) this._add(el);
-        }
-    }
-
-    /**
-     * @private
-     */
-     _removeTree(target) {
-        //if (!this._off) return; // performance
-        this._remove(target);
-        for (const el of target.querySelectorAll('*')) this._remove(el);
-    }
-
-    /**
-     * @private
-     */
-     _treeModified(target) {
-        target.matches(this.selector) ? this._add(target) : this._remove(target);
-        // for the moment subtree not checked
-        if (this.options.deep) {
-
-            for (const el of target.querySelectorAll('*')) { // expected to be expensiv
-                el.matches(this.selector) ? this._add(el) : this._remove(el);
-            }
-            //for (const el of this.targets) if (!el.matches(this.selector)) this._remove(el); // not iterable, use WeekRef if supported
-            //for (const el of target.querySelectorAll(this.selector)) this._add(el);
-        }
-    }
-}
-
-
-/* nice shorthands, todo:test *
-
-export function observe(selector, on, off) {
-    const observer = new SelectorObserver({on, off})
-    observer.observe(selector);
-    return observer;
-}
-
-export function on(selector, fn){
-    const observer = new SelectorObserver({on:fn});
-    observer.observe(selector);
-}
-
-export function off(selector, fn){
-    const observer = new SelectorObserver({off:fn});
-    observer.observe(selector);
-}
-
-export function one(selector, fn){
-    const observer = new SelectorObserver({on:el=>{
-        observer.disconnect();
-        fn(el);
-    }});
-    observer.observe(selector);
-}
+const observers = new Set();
+
+// one mutation observer per root (document or a ShadowRoot)
+const roots = new Map();
+function observeRoot(root) {
+    if (roots.has(root)) return;
+    const mo = new MutationObserver(m => checkMutations(m, root));
+    mo.observe(root, { childList: true, subtree: true, attributes: true });
+    roots.set(root, mo);
+}
+function forRoot(root, method, el) {
+    for (const observer of observers) observer.root === root && observer[method](el);
+}
+function checkMutations(mutations, root) {
+    for (const mutation of mutations) {
+        if (mutation.type==='childList') {
+            for (const target of mutation.addedNodes) {
+                target.nodeType === 1 && forRoot(root, '_addTree', target);
+            }
+            for (const target of mutation.removedNodes) {
+                target.nodeType === 1 && forRoot(root, '_removeTree', target);
+            }
+        }
+        if (mutation.type==='attributes') {
+            forRoot(root, '_treeModified', mutation.target);
+        }
+    }
+}
+
+
+// animation observer (beta), todo:refine and performance tests, problem: can not set multiple animation per selector => can be overwritten
+/*
+let animationCounter = 0;
+let aObservers = new Set();
+class _animationObserver {
+    constructor(selector, on) {
+        this.on = on;
+        // todo?: reuse style element if selector already exists
+        // or better: use same style element for all selectors?
+        // this way we dont overwrite elements targeting by multiple observers,
+        // but we have to match the selector for every observer
+        this.style = document.createElement('style');
+        this.animationName = `u2-selObs-${animationCounter++}`;
+
+        this.style.innerHTML =
+            `@keyframes ${this.animationName}{}\n`+
+            `${selector}{animation:${this.animationName} .1ms}`+
+            `.u2sOTracked:not(${selector}){animation:${this.animationName} .1ms .1ms}`+
+            ``; // todo: :where() when supported
+        document.head.append(this.style);
+        aObservers.add(this);
+    }
+    disconnect(){
+        this.style.remove();
+        aObservers.delete(this);
+    }
+}
+document.addEventListener('animationstart', e => { // todo: remove/add listener by usage
+    for (const observer of aObservers) {
+        if (e.animationName === observer.animationName) {
+            observer.on(e.target);
+            e.target.classList.add('u2sOTracked'); // can be removed if none of the listeners tracking it
+        }
+    }
+});
+*/
+
+
+
+
+
+export class SelectorObserver {
+
+    /**
+     * @param {Object} options
+     * @param {Function} options.on
+     * @param {Function} options.off
+     */
+    constructor({on, off}) {
+        this.targets = new Set(); // was WeakSet, but we clean targets anyway. Better WeakRef-Set? // rename to targets?
+        this._on = on;
+        this._off = off;
+    }
+
+    /**
+     * @param {String} selector
+     * @param {Object} [options]
+     * @param {Document|ShadowRoot} [options.root=document] - scope to observe (e.g. a shadow root)
+     */
+    observe(selector, options={}) {
+        this.selector = selector;
+        this.options = options;
+        const root = this.root = options.root ?? document;
+        observeRoot(root);
+        const els = root.querySelectorAll(this.selector);
+        for (const el of els) this._add(el);
+
+        //if (options.checkMutations!==false) {
+            observers.add(this);
+        //}
+        /*
+        if (options && options.checkAnimation) {
+            this.aniObserver = new _animationObserver(this.selector, el=>{
+                el.matches(this.selector) ? this._add(el) : this._remove(el);
+            });
+        }
+        */
+    }
+
+
+    /**
+     * @description disconnects the observer
+     */
+    disconnect() {
+        this.targets.clear();
+        observers.delete(this);
+        //this.aniObserver && this.aniObserver.disconnect();
+    }
+
+    /**
+     * @private
+     */
+    _add(el) {
+        if (this.targets.has(el)) return;
+        this.targets.add(el);
+        this._on && this._on(el);
+    }
+
+    /**
+     * @private
+     */
+     _remove(el) {
+        if (!this.targets.has(el)) return;
+        this.targets.delete(el);
+        this._off && this._off(el);
+    }
+
+    /**
+     * @private
+     */
+     _addTree(target) {
+        target.matches(this.selector) && this._add(target);
+        if (document.readyState === 'complete') { // Before domready MutationObserver reports every node, ok?
+            for (const el of target.querySelectorAll(this.selector)) this._add(el);
+        }
+    }
+
+    /**
+     * @private
+     */
+     _removeTree(target) {
+        //if (!this._off) return; // performance
+        this._remove(target);
+        for (const el of target.querySelectorAll('*')) this._remove(el);
+    }
+
+    /**
+     * @private
+     */
+     _treeModified(target) {
+        target.matches(this.selector) ? this._add(target) : this._remove(target);
+        // for the moment subtree not checked
+        if (this.options.deep) {
+
+            for (const el of target.querySelectorAll('*')) { // expected to be expensiv (why not target.querySelectorAll(this.selector)?)
+                el.matches(this.selector) ? this._add(el) : this._remove(el);
+            }
+            //for (const el of this.targets) if (!el.matches(this.selector)) this._remove(el); // not iterable, use WeekRef if supported
+            //for (const el of target.querySelectorAll(this.selector)) this._add(el);
+        }
+    }
+}
+
+
+/* nice shorthands, todo:test *
+
+export function observe(selector, on, off) {
+    const observer = new SelectorObserver({on, off})
+    observer.observe(selector);
+    return observer;
+}
+
+export function on(selector, fn){
+    const observer = new SelectorObserver({on:fn});
+    observer.observe(selector);
+}
+
+export function off(selector, fn){
+    const observer = new SelectorObserver({off:fn});
+    observer.observe(selector);
+}
+
+export function one(selector, fn){
+    const observer = new SelectorObserver({on:el=>{
+        observer.disconnect();
+        fn(el);
+    }});
+    observer.observe(selector);
+}
 /* */

package/js/Tour/README.md

@@ -0,0 +1,56 @@
+# Tour.js
+Simple guided tours for existing interfaces.
+Targets are highlighted without modifying them.
+The mask is isolated, while the info and buttons inherit the website's styles.
+
+Style `.u2TourInfo`, `.u2TourContent`, `.u2TourButtons`, `.u2TourBack`,
+`.u2TourNext` and `.u2TourClose` as part of the website.
+
+## Usage
+
+```html
+<button id=start onclick="(new u2_Tour.Tour([{target:'#title', content:'This is the title.'}, {target:'#text', content:'And this is the description.'}]).start())">Start tour</button>
+<h1 id=title>Simple Tour</h1>
+<p id=text>A tour highlights existing elements.</p>
+```
+
+## API
+
+```js
+tour.start();
+tour.show(1);
+tour.next();
+tour.back();
+tour.stop();
+
+tour.addEventListener('step', e => console.log(e.detail));
+tour.addEventListener('complete', () => console.log('completed'));
+tour.addEventListener('close', () => console.log('closed'));
+```
+
+`target` may be an element, selector, or function returning an element or
+promise. Target functions run when their step is shown and may prepare it.
+`content` may also be a promise.
+
+The tour buttons support horizontal arrow-key navigation using
+[`u2-focusgroup`](../../attr/focusgroup/README.md).
+
+The info uses a non-modal dialog role, announces changed steps, closes with
+Escape and restores focus to the element active before the tour.
+
+## Install
+
+```js
+import * as module from "https://cdn.jsdelivr.net/gh/u2ui/u2@main/js/Tour/Tour.js"
+```
+
+## Demos
+
+[minimal.html](http://gcdn.li/u2ui/u2@main/js/Tour/tests/minimal.html)  
+[demo.html](http://gcdn.li/u2ui/u2@main/js/Tour/tests/demo.html)  
+
+## About
+
+- MIT License, Copyright (c) 2022 <u2> (like all repositories in this organization) <br>
+- Suggestions, ideas, finding bugs and making pull requests make us very happy. ♥
+

package/js/Tour/Tour.js

@@ -0,0 +1,156 @@
+import { Placer } from '../Placer/Placer.js';
+
+export class Tour extends EventTarget {
+    constructor(steps) {
+        super();
+        this.steps = steps;
+    }
+
+    start() { return this.show(0); }
+
+    async show(index) {
+        const step = this.steps[index];
+        if (!step) return;
+
+        const pending = this.pending = {};
+        const target = typeof step.target === 'function' ? await step.target(this) : typeof step.target === 'string' ? document.querySelector(step.target) : step.target;
+        if (this.pending !== pending) return;
+        if (!target) throw new Error(`Tour target not found: ${step.target}`);
+        const content = await step.content;
+        if (this.pending !== pending) return;
+        this.target = target;
+        const opened = !this.info;
+        if (opened) this.#create();
+
+        this.current = index;
+        this.content.replaceChildren(content instanceof Node ? content.cloneNode(true) : content);
+        this.info.ariaLabel = `Tour step ${index + 1} of ${this.steps.length}`;
+        this.backButton.disabled = index === 0;
+        this.nextButton.textContent = index === this.steps.length - 1 ? 'Done' : 'Next';
+        this.target.scrollIntoView({block:'nearest', inline:'nearest'});
+        this.placer.followElement(this.target);
+        this.#draw();
+        if (opened) this.nextButton.focus();
+        this.dispatchEvent(new CustomEvent('step', {detail:{step, index}}));
+    }
+
+    next() { return this.current === this.steps.length - 1 ? this.stop('complete') : this.show(this.current + 1); }
+    back() { return this.show(this.current - 1); }
+
+    stop(event = 'close') {
+        this.placer?.unfollow();
+        this.host?.remove();
+        document.removeEventListener('scroll', this.#scheduleDraw, true);
+        globalThis.removeEventListener('resize', this.#scheduleDraw);
+        clearInterval(this.drawInterval);
+        cancelAnimationFrame(this.drawFrame);
+        this.drawFrame = 0;
+        this.pending = null;
+        this.host = this.info = this.target = null;
+        if (this.returnFocus?.isConnected) this.returnFocus.focus();
+        this.returnFocus = null;
+        this.dispatchEvent(new Event(event));
+    }
+
+    #create() {
+        import('../../attr/focusgroup/focusgroup.js');
+        this.returnFocus = document.activeElement;
+        const host = this.host = document.createElement('div');
+        document.documentElement.append(host);
+        host.popover = 'manual';
+        host.style.cssText = `
+            xposition: fixed !important;
+            xinset: 0 !important;
+            pointer-events: none !important;
+            border:0; padding:0; margin:0;
+        `;
+
+        const root = host.attachShadow({mode:'closed'});
+        root.innerHTML = `
+            <style>
+                svg {
+                    position: fixed;
+                    inset: 0;
+                    width: 120%;
+                    height: 120%;
+                }
+                .hole { transition: all .15s; filter:blur(4px); }
+                slot { pointer-events: none; }
+            </style>
+            <svg aria-hidden=true focusable=false>
+                <defs>
+                    <mask id=spotlight>
+                        <rect width="100%" height="100%" fill="white"/>
+                        <rect class=hole rx=8 fill="black"/>
+                    </mask>
+                </defs>
+                <rect width="100%" height="100%" fill="#000a" mask="url(#spotlight)"/>
+            </svg>
+            <slot></slot>
+        `;
+        host.showPopover();
+
+        this.hole = root.querySelector('.hole');
+        document.addEventListener('scroll', this.#scheduleDraw, {passive:true, capture:true});
+        globalThis.addEventListener('resize', this.#scheduleDraw, {passive:true});
+        this.drawInterval = setInterval(this.#scheduleDraw, 200);
+
+        const info = this.info = document.createElement('dialog');
+        info.className = 'u2TourInfo';
+        info.open = true;
+        info.style.cssText = `
+            position: fixed !important;
+            pointer-events: auto;
+            margin: 0;
+            margin-left:3px;
+        `;
+        info.innerHTML = `
+            <div style="margin-bottom:1em;">
+                <button class="u2-unstyle u2TourClose" aria-label="Close tour" style="float:right;">
+                    <u2-ico icon=close>&times;</u2-ico>
+                </button>
+                <div aria-live=polite aria-atomic=true class=u2TourContent></div>
+            </div>
+            <footer class=u2-flex u2-focusgroup style="justify-content:space-between;">
+                <button class=u2TourBack>Back</button>
+                <button class=u2TourNext>Next</button>
+            </footer>
+        `;
+        info.onkeydown = e => {
+            e.stopPropagation();
+            if (e.key !== 'Escape') return;
+            e.preventDefault();
+            this.stop();
+        };
+        for (const event of ['pointerdown', 'mousedown', 'touchstart', 'click', 'dblclick', 'contextmenu']) {
+            info.addEventListener(event, e => e.stopPropagation());
+        }
+        host.append(info);
+        this.content = info.querySelector('.u2TourContent');
+        [this.closeButton, this.backButton, this.nextButton] = info.querySelectorAll('button');
+        this.backButton.onclick = () => this.back();
+        this.nextButton.onclick = () => this.next();
+        this.closeButton.onclick = () => this.stop();
+        this.placer = new Placer(info, {margin:15});
+    }
+
+    #draw() {
+        if (!this.target) return;
+        const {left, top, width, height} = this.target.getBoundingClientRect();
+        const margin = 7;
+        Object.assign(this.hole.style, {
+            x: `${left - margin}px`,
+            y: `${top - margin}px`,
+            width: `${width + margin * 2}px`,
+            height: `${height + margin * 2}px`,
+        });
+    }
+
+    #scheduleDraw = () => {
+        if (this.drawFrame) return;
+        this.drawFrame = requestAnimationFrame(() => {
+            this.drawFrame = 0;
+            this.#draw();
+        });
+    };
+}