cotomy 0.3.14 → 0.3.16

package/README.md

@@ -87,11 +87,15 @@ The View layer provides thin wrappers around DOM elements and window events.
   - `innerWidth: number` / `innerHeight: number`
   - `outerWidth: number` / `outerHeight: number` — Includes margins
   - `scrollWidth: number` / `scrollHeight: number` / `scrollTop: number`
+  - `scrollIn(options?: CotomyScrollOptions | Partial<CotomyScrollOptions>): this` — Scrolls the nearest scrollable container (or window) to reveal the element
+  - `scrollTo(target, options?: CotomyScrollOptions | Partial<CotomyScrollOptions>): this` — Convenience wrapper; if `target` is a selector it searches descendants then calls `scrollIn()`
   - `position(): { top, left }` — Relative to viewport
   - `absolutePosition(): { top, left }` — Viewport + page scroll offset
   - `screenPosition(): { top, left }`
   - `rect(): { top, left, width, height }`
   - `innerRect()` — Subtracts padding
+  - `overlaps(target: CotomyElement): boolean` — True if the two elements' `rect` values overlap (AABB)
+  - `overlapElements: CotomyElement[]` — Returns other CotomyElements (by `data-cotomy-instance`) that overlap this element
 - Events
   - Generic: `on(eventOrEvents, handler, options?)`, `off(eventOrEvents, handler?, options?)`, `once(eventOrEvents, handler, options?)`, `trigger(event[, Event])` — `eventOrEvents` accepts either a single event name or an array for batch registration/removal. `trigger` emits bubbling events by default and can be customized by passing an `Event`.
   - Delegation: `onSubTree(eventOrEvents, selector, handler, options?)` — `eventOrEvents` can also be an array for listening to multiple delegated events at once.
@@ -151,6 +155,7 @@ The first command ensures `[scope]` expands to `[data-cotomy-scopeid="..."]` in
 - DOM helpers
   - `body: CotomyElement`
   - `append(element: CotomyElement): this`
+  - `scrollTo(target, options?: CotomyScrollOptions | Partial<CotomyScrollOptions>): this` — Scrolls to reveal a target (`selector | CotomyElement | HTMLElement`)
   - `moveNext(focused: CotomyElement, shift = false)` — Move focus to next/previous focusable
 - Window events
   - `on(eventOrEvents, handler): this` / `off(eventOrEvents, handler?): this` / `trigger(event[, Event]): this` — `eventOrEvents` accepts a single event name or an array. CotomyWindow’s `trigger` also bubbles by default and accepts an `Event` to override the behavior.

package/dist/browser/cotomy.js

@@ -841,6 +841,30 @@ class EventRegistry {
         this._registry.delete(target.scopeId);
     }
 }
+class CotomyScrollOptions {
+    constructor(init = {}) {
+        this.behavior = "smooth";
+        this.onlyIfNeeded = true;
+        this.block = "nearest";
+        this.inline = "nearest";
+        if (init.behavior !== undefined)
+            this.behavior = init.behavior;
+        if (init.onlyIfNeeded !== undefined)
+            this.onlyIfNeeded = init.onlyIfNeeded;
+        if (init.block !== undefined)
+            this.block = init.block;
+        if (init.inline !== undefined)
+            this.inline = init.inline;
+    }
+    resolveBehavior() {
+        return this.behavior;
+    }
+    static from(options) {
+        if (options instanceof CotomyScrollOptions)
+            return options;
+        return new CotomyScrollOptions(options ?? {});
+    }
+}
 class CotomyElement {
     static encodeHtml(text) {
         const div = document.createElement("div");
@@ -1254,6 +1278,36 @@ class CotomyElement {
             height: rect.height + margin.top + margin.bottom
         };
     }
+    static overlapsRect(left, right) {
+        if (left.width <= 0 || left.height <= 0 || right.width <= 0 || right.height <= 0) {
+            return false;
+        }
+        const leftRight = left.left + left.width;
+        const leftBottom = left.top + left.height;
+        const rightRight = right.left + right.width;
+        const rightBottom = right.top + right.height;
+        return left.left < rightRight
+            && leftRight > right.left
+            && left.top < rightBottom
+            && leftBottom > right.top;
+    }
+    overlaps(target) {
+        if (!this.attached || !target.attached) {
+            return false;
+        }
+        if (this.element === target.element) {
+            return false;
+        }
+        return CotomyElement.overlapsRect(this.rect, target.rect);
+    }
+    get overlapElements() {
+        if (!this.attached) {
+            return [];
+        }
+        return CotomyElement.find("[data-cotomy-instance]")
+            .filter(e => e.element !== this.element)
+            .filter(e => this.overlaps(e));
+    }
     get padding() {
         const style = this.getComputedStyle();
         return {
@@ -1288,6 +1342,107 @@ class CotomyElement {
     get isRightViewport() {
         return this.element.getBoundingClientRect().left > window.innerWidth;
     }
+    static isScrollableOverflow(value) {
+        const overflow = (value ?? "").toLowerCase();
+        return overflow === "auto" || overflow === "scroll";
+    }
+    static findNearestScrollableAncestor(element) {
+        let current = element.parentElement;
+        while (current) {
+            if (current === document.body || current === document.documentElement) {
+                return null;
+            }
+            const style = window.getComputedStyle(current);
+            const overflowY = style.overflowY;
+            const overflowX = style.overflowX;
+            const canScrollY = CotomyElement.isScrollableOverflow(overflowY) && current.scrollHeight > current.clientHeight;
+            const canScrollX = CotomyElement.isScrollableOverflow(overflowX) && current.scrollWidth > current.clientWidth;
+            if (canScrollY || canScrollX) {
+                return current;
+            }
+            current = current.parentElement;
+        }
+        return null;
+    }
+    static computeAlignedScroll(viewStart, viewSize, elementStart, elementEnd, align, onlyIfNeeded) {
+        const viewEnd = viewStart + viewSize;
+        if (onlyIfNeeded && elementStart >= viewStart && elementEnd <= viewEnd) {
+            return null;
+        }
+        if (align === "start") {
+            return elementStart;
+        }
+        if (align === "end") {
+            return elementEnd - viewSize;
+        }
+        if (align === "center") {
+            const elementSize = elementEnd - elementStart;
+            return elementStart - (viewSize - elementSize) / 2;
+        }
+        if (elementStart < viewStart) {
+            return elementStart;
+        }
+        if (elementEnd > viewEnd) {
+            return elementEnd - viewSize;
+        }
+        return null;
+    }
+    scrollIn(options = {}) {
+        if (!this.attached)
+            return this;
+        const resolved = CotomyScrollOptions.from(options);
+        const behavior = resolved.resolveBehavior();
+        const onlyIfNeeded = resolved.onlyIfNeeded;
+        const block = resolved.block;
+        const inline = resolved.inline;
+        const scrollable = CotomyElement.findNearestScrollableAncestor(this.element);
+        if (scrollable) {
+            const elementRect = this.element.getBoundingClientRect();
+            const containerRect = scrollable.getBoundingClientRect();
+            const elementTopInContainer = elementRect.top - containerRect.top + scrollable.scrollTop;
+            const elementBottomInContainer = elementRect.bottom - containerRect.top + scrollable.scrollTop;
+            const elementLeftInContainer = elementRect.left - containerRect.left + scrollable.scrollLeft;
+            const elementRightInContainer = elementRect.right - containerRect.left + scrollable.scrollLeft;
+            const targetTop = CotomyElement.computeAlignedScroll(scrollable.scrollTop, scrollable.clientHeight, elementTopInContainer, elementBottomInContainer, block, onlyIfNeeded);
+            const targetLeft = CotomyElement.computeAlignedScroll(scrollable.scrollLeft, scrollable.clientWidth, elementLeftInContainer, elementRightInContainer, inline, onlyIfNeeded);
+            if (!onlyIfNeeded || targetTop !== null || targetLeft !== null) {
+                const nextTop = targetTop ?? scrollable.scrollTop;
+                const nextLeft = targetLeft ?? scrollable.scrollLeft;
+                scrollable.scrollTo?.({ top: nextTop, left: nextLeft, behavior });
+                if (!scrollable.scrollTo) {
+                    scrollable.scrollTop = nextTop;
+                    scrollable.scrollLeft = nextLeft;
+                }
+            }
+            return this;
+        }
+        const rect = this.element.getBoundingClientRect();
+        const currentTop = window.scrollY || document.documentElement.scrollTop;
+        const currentLeft = window.scrollX || document.documentElement.scrollLeft;
+        const elementTop = currentTop + rect.top;
+        const elementBottom = currentTop + rect.bottom;
+        const elementLeft = currentLeft + rect.left;
+        const elementRight = currentLeft + rect.right;
+        const targetTop = CotomyElement.computeAlignedScroll(currentTop, window.innerHeight, elementTop, elementBottom, block, onlyIfNeeded);
+        const targetLeft = CotomyElement.computeAlignedScroll(currentLeft, window.innerWidth, elementLeft, elementRight, inline, onlyIfNeeded);
+        if (!onlyIfNeeded || targetTop !== null || targetLeft !== null) {
+            window.scrollTo({ top: targetTop ?? currentTop, left: targetLeft ?? currentLeft, behavior });
+        }
+        return this;
+    }
+    scrollTo(target, options = {}) {
+        if (typeof target === "string") {
+            const element = this.first(target);
+            element?.scrollIn(options);
+            return this;
+        }
+        if (target instanceof CotomyElement) {
+            target.scrollIn(options);
+            return this;
+        }
+        new CotomyElement(target).scrollIn(options);
+        return this;
+    }
     comesBefore(target) {
         const pos = this.element.compareDocumentPosition(target.element);
         if (pos & Node.DOCUMENT_POSITION_DISCONNECTED)
@@ -1993,6 +2148,19 @@ class CotomyWindow {
             return this.trigger("scroll");
         }
     }
+    scrollTo(target, options = {}) {
+        if (typeof target === "string") {
+            const element = CotomyElement.first(target);
+            element?.scrollIn(options);
+            return this;
+        }
+        if (target instanceof CotomyElement) {
+            target.scrollIn(options);
+            return this;
+        }
+        new CotomyElement(target).scrollIn(options);
+        return this;
+    }
     changeLayout(handle) {
         if (handle) {
             return this.on("cotomy:changelayout", handle);