js-kompo-utils 1.0.0

package/tutorials/utils/selectors.js

@@ -0,0 +1,225 @@
+/**
+ * Selector utility functions.
+ * Pure helpers for resolving element references, computing element positions,
+ * and generating unique CSS selectors for DOM elements.
+ */
+
+/**
+ * Resolve a reference selector like "highlight:N" or "hover:N" into an actual
+ * CSS selector using the step's highlight/hover configuration.
+ *
+ * - "highlight:N" resolves to the Nth element across all highlight groups
+ * - "hover:N" resolves to the Nth hover selector
+ * - All other strings are returned as-is
+ *
+ * @param {string} selector - A CSS selector, "screen:x,y", "highlight:N", or "hover:N"
+ * @param {Object} [step] - Current step object for resolving references
+ * @returns {string} Resolved CSS selector (or the original string if no match)
+ */
+export function resolveRef(selector, step) {
+    if (!step || typeof selector !== 'string') return selector;
+
+    // highlight:N -- resolve to the Nth element across highlight groups
+    const hlMatch = selector.match(/^highlight:(\d+)$/);
+    if (hlMatch && step.highlight?.groups) {
+        const hlIdx = parseInt(hlMatch[1], 10);
+        const allSelectors = [];
+        for (const g of step.highlight.groups) {
+            const elems = g.elements || g;
+            if (Array.isArray(elems)) {
+                allSelectors.push(...elems);
+            }
+        }
+        if (allSelectors[hlIdx]) return allSelectors[hlIdx];
+        console.warn(
+            `TutorialEngine: highlight:${hlIdx} not found, ${allSelectors.length} elements available`
+        );
+        return selector;
+    }
+
+    // hover:N -- resolve to the Nth hover selector
+    const hvMatch = selector.match(/^hover:(\d+)$/);
+    if (hvMatch && step.hover) {
+        const hvIdx = parseInt(hvMatch[1], 10);
+        const hoverList = Array.isArray(step.hover) ? step.hover : [step.hover];
+        if (hoverList[hvIdx]) return hoverList[hvIdx];
+        console.warn(
+            `TutorialEngine: hover:${hvIdx} not found, ${hoverList.length} elements available`
+        );
+        return selector;
+    }
+
+    return selector;
+}
+
+/**
+ * Resolve an element's position from a selector string.
+ *
+ * Supports two formats:
+ * - "screen:x,y" for absolute screen coordinates (returned directly)
+ * - Any CSS selector, which is queried and its bounding rect used
+ *
+ * The `anchor` parameter controls where within the element's bounding box
+ * the point is taken (0,0 = top-left, 1,1 = bottom-right, default 0.5,0.5 = center).
+ * The result is clamped to the viewport.
+ *
+ * Reference selectors ("highlight:N", "hover:N") are resolved via `resolveRef`
+ * before querying.
+ *
+ * @param {string} selector - CSS selector or "screen:x,y"
+ * @param {{x: number, y: number}} [anchor] - Anchor ratios (0-1), defaults to center (0.5, 0.5)
+ * @param {Object} [step] - Current step object for resolving references
+ * @returns {{x: number, y: number}|null} Position in pixels, or null if element not found
+ */
+export function resolveElementCenter(selector, anchor, step) {
+    // Resolve highlight:N / hover:N references first
+    const resolved = resolveRef(selector, step);
+
+    // "screen:x,y" -- direct absolute coordinates
+    if (typeof resolved === 'string' && resolved.startsWith('screen:')) {
+        const parts = resolved.replace('screen:', '').split(',');
+        return { x: parseFloat(parts[0]), y: parseFloat(parts[1]) };
+    }
+
+    const el = document.querySelector(resolved);
+    if (!el) {
+        console.warn('TutorialEngine.resolveElementCenter: element not found for selector', resolved);
+        return null;
+    }
+
+    const rect = el.getBoundingClientRect();
+    const ax = anchor?.x ?? 0.5;
+    const ay = anchor?.y ?? 0.5;
+
+    return {
+        x: Math.max(0, Math.min(window.innerWidth, rect.left + rect.width * ax)),
+        y: Math.max(0, Math.min(window.innerHeight, rect.top + rect.height * ay)),
+    };
+}
+
+/**
+ * Generate the best unique CSS selector for a given DOM element.
+ *
+ * Tries strategies in order of preference:
+ * 1. Element ID (#id)
+ * 2. Unique single class (.class)
+ * 3. Tag + class (tag.class)
+ * 4. Unique data attribute ([data-foo="bar"])
+ * 5. Ancestor with ID + relative child path (#ancestor > tag.class > ...)
+ * 6. Fallback: nth-child path from body (tag:nth-child(n) > ...)
+ *
+ * Classes containing special characters (colons, percent signs, brackets, slashes)
+ * are filtered out to avoid issues with Tailwind-style utility classes.
+ *
+ * @param {HTMLElement} el - Target DOM element
+ * @returns {string} A CSS selector that uniquely identifies the element
+ */
+export function bestSelector(el) {
+    if (!el || el === document.body || el === document.documentElement) return 'body';
+    if (el.id) return `#${el.id}`;
+
+    /**
+     * Safely count how many elements match a selector.
+     * Returns -1 if the selector is invalid.
+     */
+    const safeQSA = (s) => {
+        try {
+            return document.querySelectorAll(s).length;
+        } catch {
+            return -1;
+        }
+    };
+
+    /**
+     * Filter out classes with special characters that break selectors
+     * (Tailwind hover:, focus:, brackets, etc.)
+     */
+    const safeClasses = (classList) =>
+        Array.from(classList).filter((c) => !/[:%\[\]\/]/.test(c));
+
+    // Strategy 1: unique single class
+    const classes = safeClasses(el.classList);
+    const tag = el.tagName.toLowerCase();
+
+    if (classes.length) {
+        for (const cls of classes) {
+            const sel = `.${cls}`;
+            if (safeQSA(sel) === 1) return sel;
+        }
+        // Strategy 2: tag + single class
+        for (const cls of classes) {
+            const sel = `${tag}.${cls}`;
+            if (safeQSA(sel) === 1) return sel;
+        }
+    }
+
+    // Strategy 3: unique data attribute
+    for (const attr of el.attributes) {
+        if (attr.name.startsWith('data-')) {
+            const escapedVal = attr.value.replace(/"/g, '\\"');
+            const sel = `[${attr.name}="${escapedVal}"]`;
+            if (safeQSA(sel) === 1) return sel;
+        }
+    }
+
+    // Strategy 4: ancestor with ID + relative child path
+    let ancestor = el.parentElement;
+    while (ancestor && ancestor !== document.body) {
+        if (ancestor.id) {
+            const relPath = [];
+            let cur = el;
+
+            while (cur && cur !== ancestor) {
+                const parent = cur.parentElement;
+                if (!parent) break;
+
+                const siblings = Array.from(parent.children);
+                const idx = siblings.indexOf(cur) + 1;
+                const curTag = cur.tagName.toLowerCase();
+
+                // Try class-based segment first for readability
+                const curClasses = safeClasses(cur.classList);
+                let found = false;
+
+                for (const cls of curClasses) {
+                    const segment = `${curTag}.${cls}`;
+                    const full = `#${ancestor.id} > ${[segment, ...relPath].join(' > ')}`;
+                    if (safeQSA(full) === 1) {
+                        relPath.unshift(segment);
+                        found = true;
+                        break;
+                    }
+                }
+
+                if (!found) {
+                    relPath.unshift(`${curTag}:nth-child(${idx})`);
+                }
+
+                cur = parent;
+            }
+
+            const sel = `#${ancestor.id} > ${relPath.join(' > ')}`;
+            if (safeQSA(sel) === 1) return sel;
+        }
+        ancestor = ancestor.parentElement;
+    }
+
+    // Strategy 5 (fallback): nth-child path from body
+    const path = [];
+    let current = el;
+    while (current && current !== document.body) {
+        const parent = current.parentElement;
+        if (!parent) break;
+
+        const children = Array.from(parent.children);
+        const index = children.indexOf(current) + 1;
+        const currentTag = current.tagName.toLowerCase();
+        path.unshift(`${currentTag}:nth-child(${index})`);
+        current = parent;
+
+        const sel = path.join(' > ');
+        if (safeQSA(sel) === 1) return sel;
+    }
+
+    return path.join(' > ');
+}

package/tutorials/utils/stability.js

@@ -0,0 +1,76 @@
+/**
+ * DOM stability utility.
+ * Polls element positions/sizes until they stop changing,
+ * useful for waiting out CSS transitions before measuring layout.
+ */
+
+/**
+ * Wait for all highlight target elements to be stable (position/size not changing)
+ * before calling the callback.
+ *
+ * "Stable" means the bounding rects of all target elements have not changed
+ * for 3 consecutive checks (150ms). Gives up after 30 attempts (1.5s).
+ *
+ * @param {Object} config - Highlight configuration object
+ * @param {Array} config.groups - Array of group objects, each with an `elements`
+ *   array of CSS selector strings (or the group itself may be a selector array)
+ * @param {Function} callback - Called once all elements are stable (or timeout is reached)
+ * @returns {Function} cancel - Call to stop polling early
+ */
+export function waitForStableHighlight(config, callback) {
+    // Collect all CSS selectors from the highlight groups
+    const allSelectors = [];
+    for (const g of config.groups || []) {
+        const elems = g.elements || g;
+        if (Array.isArray(elems)) {
+            allSelectors.push(...elems);
+        }
+    }
+
+    let lastRects = null;
+    let stableCount = 0;
+    const maxAttempts = 30; // 30 * 50ms = 1.5s max
+    let attempts = 0;
+    let cancelled = false;
+    let timerId = null;
+
+    /** Take a snapshot of all elements' bounding rects as a comparable string. */
+    const snapshot = () =>
+        allSelectors
+            .map((sel) => {
+                const el = document.querySelector(sel);
+                if (!el) return '0,0,0,0';
+                const r = el.getBoundingClientRect();
+                return `${Math.round(r.left)},${Math.round(r.top)},${Math.round(r.width)},${Math.round(r.height)}`;
+            })
+            .join('|');
+
+    /** Check if rects are stable; if not, schedule another check. */
+    const check = () => {
+        if (cancelled) return;
+        attempts++;
+        const current = snapshot();
+
+        if (current === lastRects) {
+            stableCount++;
+        } else {
+            stableCount = 0;
+        }
+        lastRects = current;
+
+        // Stable for 3 consecutive checks (150ms) or max attempts reached
+        if (stableCount >= 3 || attempts >= maxAttempts) {
+            callback();
+        } else {
+            timerId = setTimeout(check, 50);
+        }
+    };
+
+    // Start after a minimum initial delay for CSS transitions to begin
+    timerId = setTimeout(check, 50);
+
+    return function cancel() {
+        cancelled = true;
+        if (timerId) clearTimeout(timerId);
+    };
+}

package/tutorials/utils/svg.js

@@ -0,0 +1,46 @@
+/**
+ * SVG utility functions.
+ * Pure helpers for creating SVG elements and transforming SVG paths.
+ */
+
+/**
+ * Create an SVG element with the given tag and attributes.
+ * @param {string} tag - SVG element tag name (e.g. 'rect', 'path', 'circle')
+ * @param {Object} [attrs={}] - Key-value pairs to set as attributes
+ * @returns {SVGElement}
+ */
+export function createSvgEl(tag, attrs = {}) {
+    const el = document.createElementNS('http://www.w3.org/2000/svg', tag);
+    for (const [key, value] of Object.entries(attrs)) {
+        el.setAttribute(key, value);
+    }
+    return el;
+}
+
+/**
+ * Convert a normalized SVG path (0-1 range) to absolute pixel coordinates.
+ *
+ * Coordinate pairs in the path string are interpreted as normalized values
+ * within the bounding box defined by `from` and `to`. Each pair (nx, ny) is
+ * mapped to (from.x + nx * dx, from.y + ny * dy).
+ *
+ * @param {string} svgPath - SVG path string with normalized coordinate pairs
+ * @param {{x: number, y: number}} from - Start position in pixels
+ * @param {{x: number, y: number}} to - End position in pixels
+ * @returns {string} SVG path with absolute pixel coordinates
+ */
+export function denormalizeSvgPath(svgPath, from, to) {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+
+    return svgPath.replace(
+        /([-]?[0-9]*\.?[0-9]+)\s*,\s*([-]?[0-9]*\.?[0-9]+)/g,
+        (_, xStr, yStr) => {
+            const nx = parseFloat(xStr);
+            const ny = parseFloat(yStr);
+            const px = from.x + nx * dx;
+            const py = from.y + ny * dy;
+            return `${px.toFixed(1)},${py.toFixed(1)}`;
+        }
+    );
+}