@vertesia/ui 0.24.0-dev.202601221707

package/src/core/components/popup/PopupController.ts

@@ -0,0 +1,182 @@
+import { computePosition, Constraints, Position } from "./position";
+import { computeVisibleClientRect, getScrollableParents } from "./utils";
+
+
+export interface PopupControllerOptions {
+    /**
+     * The element to use as the anchor for the popup.
+     */
+    anchor: HTMLElement;
+    closeOnClick?: boolean;
+    closeOnEsc?: boolean;
+    blockPageScroll?: boolean;
+    onClose?: (ctrl: PopupController) => void;
+    onOpen?: (ctrl: PopupController) => void;
+    root?: HTMLElement;
+}
+
+interface PopupControllerContext {
+    element: HTMLElement;
+    constraints: Constraints;
+    /**
+     * The computed position details
+     */
+    position?: Position;
+    cleanup: () => void;
+}
+
+export class PopupController {
+    root: HTMLElement;
+    scrollableParents: HTMLElement[];
+    visibleClientRect: DOMRect | null;
+    context?: PopupControllerContext;
+
+    constructor(public options: PopupControllerOptions) {
+        this.root = options.root || document.documentElement;
+        this.scrollableParents = getScrollableParents(this.anchor, this.root);
+        this.visibleClientRect = computeVisibleClientRect(this.scrollableParents);
+    }
+
+    get anchor() {
+        return this.options.anchor;
+    }
+
+    private registerListeners(element: HTMLElement) {
+        const parents = this.scrollableParents;
+        const updateHandler = () => {
+            this.update();
+        }
+        // add a window resize listener
+        window.addEventListener('resize', updateHandler);
+
+        //TODO do we add scroll listeners to the window?
+
+        // add scroll listeners to all scrollable parents
+        for (const parent of parents) {
+            parent.addEventListener('scroll', updateHandler);
+        }
+
+        let closeOnClick: ((ev: MouseEvent) => void) | undefined;
+        if (this.options.closeOnClick) {
+            closeOnClick = (ev: MouseEvent) => {
+                if (!element.contains(ev.target as HTMLElement)) {
+                    this.tryClose();
+                }
+            }
+            // register in the next event loop cycle since the current one
+            // is may be triggered by a click event
+            window.setTimeout(function () {
+                closeOnClick && document.addEventListener('click', closeOnClick);
+            }, 0);
+        }
+        let closeOnEsc: ((ev: KeyboardEvent) => void) | undefined;
+        if (this.options.closeOnEsc) {
+            closeOnEsc = (ev: KeyboardEvent) => {
+                if (ev.key === 'Escape') {
+                    this.tryClose();
+                }
+            }
+            window.setTimeout(function () {
+                closeOnEsc && document.addEventListener('keydown', closeOnEsc);
+            }, 0);
+        }
+        const blockPageScroll = this.options.blockPageScroll;
+        if (blockPageScroll) {
+            document.body.style.overflow = "hidden";
+            document.body.style.height = "100%";
+        }
+        return () => {
+            window.removeEventListener('resize', updateHandler);
+            for (const parent of parents) {
+                parent.removeEventListener('scroll', updateHandler);
+            }
+            closeOnClick && document.removeEventListener('click', closeOnClick);
+            closeOnEsc && document.removeEventListener('keydown', closeOnEsc);
+            if (blockPageScroll) {
+                document.body.style.overflow = "";
+                document.body.style.height = "";
+            }
+        }
+    }
+
+    open(element: HTMLElement, constraints: Constraints) {
+        if (this.context) {
+            throw new Error("The popup controller is already bound to an element");
+        }
+        this.tryOpen(element, constraints);
+    }
+    tryOpen(element: HTMLElement, constraints: Constraints) {
+        if (this.context) {
+            return; // do nothing if the popup is already open
+        }
+        this.context = {
+            element,
+            constraints,
+            cleanup: this.registerListeners(element)
+        }
+
+        element.style.display = "";
+        element.style.visibility = "hidden";
+        // update the popup position
+        this.update();
+        this.options.onOpen && this.options.onOpen(this);
+    }
+
+    close() {
+        if (!this.context) {
+            throw new Error("The popup controller is not bound to an element");
+        }
+        this.tryClose();
+    }
+    tryClose() {
+        if (!this.context) {
+            return; // do nothing if the popup is not open
+        }
+        this.options.onClose && this.options.onClose(this);
+        this.context.cleanup();
+        //TODO
+        this.context.element.style.display = "none";
+        this.context = undefined;
+    }
+
+    get isOpen() {
+        return !!this.context;
+    }
+
+    update() {
+        if (!this.context) return; // do nothing if the popup is not open
+        // update the position of the popup
+        const element = this.context.element;
+        const constraints = this.context.constraints;
+        const elemRect = element.getBoundingClientRect();
+        const anchorRect = this.anchor.getBoundingClientRect();
+        const clientRect = this.visibleClientRect;
+        if (!clientRect) {
+            // the popup is not visible
+            return;
+        }
+        const position = computePosition(constraints, elemRect, anchorRect, clientRect);
+        this.context.position = position || undefined;
+        if (position) {
+            if (position.constrainHeight) {
+                element.style.height = position.rect.height + 'px';
+            }
+            if (position.constrainWidth) {
+                element.style.width = position.rect.width + 'px';
+            }
+            element.style.left = position.rect.left + 'px';
+            element.style.top = position.rect.top + 'px';
+            element.style.visibility = "visible";
+        }
+    }
+
+    createPopupElement() {
+        const popup = document.createElement('div');
+        popup.style.margin = "0";
+        popup.style.padding = "0";
+        popup.style.border = "none";
+        popup.style.background = "transparent";
+        popup.className = "composable-Popup";
+        return popup;
+    }
+}

package/src/core/components/popup/index.ts

@@ -0,0 +1,3 @@
+export * from "./Popup";
+export * from "./PopupController"
+export * from "./position";

package/src/core/components/popup/position.ts

@@ -0,0 +1,277 @@
+
+export type PositionType = 'top' | 'right' | 'bottom' | 'left' | 'nw' | 'sw' | 'ne' | 'se';
+export type AlignType = 'start' | 'center' | 'end' | 'fill';
+export interface Constraints {
+    position: PositionType;
+    /**
+     * The alignment of the target element relative to the anchor element and the position constraint.
+     * The nw, ne, se, sw positions do not support any alignment. If any is given it will be ignored.
+     */
+    align?: AlignType;
+    /**
+     * A gap size between the anchor element and the target element.
+     */
+    gap?: number;
+    /**
+     * Whether the element should be displayed in a way that it covers the anchor element.
+     * This modifier change the interpretation of the position and alignment
+     */
+    cover?: boolean;
+    /**
+     * the minimum width in pixels accepted to display the target element.
+     * if the width contraint is not satisfied the element will be displayed in the opposite direction.
+     */
+    minWidth?: number;
+    /**
+     * the minimum height in pixels accepted to display the target element.
+     * if the height contraint is not satisfied the element will be displayed in the opposite direction
+     */
+    minHeight?: number;
+}
+
+export interface Position {
+    // the computer element rectangle
+    rect: DOMRect;
+    /**
+     * If true then the element must use the computed width, otherwise it should preserve his current width
+     */
+    constrainWidth: boolean;
+    /**
+     * If true then the element must use the computed height, otherwise it should preserve his current height
+     */
+    constrainHeight: boolean;
+    /**
+     * The position constraints used to compute the position
+     */
+    position: PositionType;
+    /**
+     * The alignment constraints used to compute the position
+     */
+    align?: AlignType;
+}
+
+function flipPos(position: PositionType) {
+    switch (position) {
+        case "top": return "bottom";
+        case "bottom": return "top";
+        case "left": return "right";
+        case "right": return "left";
+        case "ne": return "sw";
+        case "nw": return "se";
+        case "se": return "nw";
+        case "sw": return "ne";
+        default: return position;
+    }
+}
+
+function flipAlign(align: AlignType) {
+    switch (align) {
+        case "start": return "end";
+        case "end": return "start";
+        default: return align;
+    }
+}
+
+class PositionResolver {
+    /**
+     * The computed left coordinate (i.e. x)
+     */
+    left?: number;
+    /**
+     * The computed top coordinate (i.e. y)
+     */
+    top?: number;
+    /**
+     * The computed width constraint. If undefined it means that the width is not constrained.
+     */
+    width?: number;
+    /**
+     * The computed height constraint. If undefined it means that the height is not constrained.
+     */
+    height?: number;
+    /**
+     * Alignment axis. The axis is computed from the position constraints.
+     * If no axis is found - no alignment will be done
+     */
+    alignAxis?: 'x' | 'y';
+
+    /**
+     * A gap size between the anchor element and the target element.
+     */
+    gap: number;
+
+    constructor(gap: number = 0) {
+        this.gap = gap;
+    }
+
+    position(pos: PositionType, anchorRect: DOMRect, elemRect: DOMRect) {
+        switch (pos) {
+            case "top": {
+                this.top = anchorRect.top - elemRect.height - this.gap;
+                this.alignAxis = 'x';
+                break;
+            }
+            case "bottom": {
+                this.top = anchorRect.bottom + this.gap;
+                this.alignAxis = 'x';
+                break;
+            }
+            case "left": {
+                this.left = anchorRect.left - elemRect.width - this.gap;
+                this.alignAxis = 'y';
+                break;
+            }
+            case "right": {
+                this.left = anchorRect.right + this.gap;
+                this.alignAxis = 'y';
+                break;
+            }
+            case "ne": {
+                this.top = anchorRect.top - elemRect.height - this.gap;
+                this.left = anchorRect.right + this.gap;
+                break;
+            }
+            case "nw": {
+                this.top = anchorRect.top - elemRect.height - this.gap;
+                this.left = anchorRect.left - elemRect.width - this.gap;
+                break;
+            }
+            case "se": {
+                this.top = anchorRect.bottom + this.gap;
+                this.left = anchorRect.right + this.gap;
+                break;
+            }
+            case "sw": {
+                this.top = anchorRect.bottom + this.gap;
+                this.left = anchorRect.left - elemRect.width - this.gap;
+                break;
+            }
+        }
+    }
+
+    align(align: AlignType, anchorRect: DOMRect, elemRect: DOMRect) {
+        if (!this.alignAxis) return; // no alignment axis
+        switch (align) {
+            case 'start': {
+                if (this.alignAxis === 'x') {
+                    this.left = anchorRect.left;
+                } else {
+                    this.top = anchorRect.top;
+                }
+                break;
+            }
+            case 'end': {
+                if (this.alignAxis === 'x') {
+                    this.left = anchorRect.right - elemRect.width;
+                } else {
+                    this.top = anchorRect.bottom - elemRect.height;
+                }
+                break;
+            }
+            case 'center': {
+                // centering depend on the final value of the width / height
+                if (this.alignAxis === 'x') {
+                    this.left = anchorRect.left + anchorRect.width / 2 - elemRect.width / 2;
+                } else {
+                    this.top = anchorRect.top + anchorRect.height / 2 - elemRect.height / 2;
+                }
+                break;
+            }
+            case 'fill': {
+                if (this.alignAxis === 'x') {
+                    this.left = anchorRect.left;
+                    this.width = anchorRect.right - anchorRect.left;
+                } else {
+                    this.top = anchorRect.top;
+                    this.height = anchorRect.bottom - anchorRect.top;
+                }
+                break;
+            }
+        }
+    }
+
+    computePosition(constraints: Constraints, elemRect: DOMRect, anchorRect: DOMRect): Position {
+        this.position(constraints.position, anchorRect, elemRect);
+        constraints.align && this.align(constraints.align, anchorRect, elemRect);
+        if (!this.left && !this.top) {
+            throw new Error("Invalid position. Cannot compute x,y coordinates");
+        }
+        const constrainWidth = this.width != null;
+        const constrainHeight = this.height != null;
+        const width = constrainWidth ? this.width! : elemRect.width;
+        const height = constrainHeight ? this.height! : elemRect.height;
+        return {
+            rect: new DOMRect(this.left!, this.top!, width, height),
+            constrainWidth,
+            constrainHeight,
+            position: constraints.position,
+            align: constraints.align
+        }
+    }
+
+    flipAxis(constraints: Constraints, axis: 'x' | 'y'): Constraints | null {
+        if (this.alignAxis === axis) { // flip alignment
+            if (constraints.align) {
+                const newAlign = flipAlign(constraints.align);
+                if (newAlign !== constraints.align) {
+                    return { ...constraints, align: newAlign };
+                }
+            }
+        } else { // flip positioning
+            const newPos = flipPos(constraints.position);
+            if (newPos !== constraints.position) {
+                return { ...constraints, position: newPos };
+            }
+        }
+        return null; // nothing to do
+    }
+
+}
+function isElementVisible(elemRect: DOMRect, clientRect: DOMRect) {
+    return elemRect.left >= clientRect.left && elemRect.right <= clientRect.right
+        &&
+        elemRect.top >= clientRect.top && elemRect.bottom <= clientRect.bottom;
+}
+
+function isElementVisibleOnAxis(elemRect: DOMRect, clientRect: DOMRect, axis: 'x' | 'y') {
+    if (axis === 'x') {
+        return elemRect.left >= clientRect.left && elemRect.right <= clientRect.right;
+    } else {
+        return elemRect.top >= clientRect.top && elemRect.bottom <= clientRect.bottom;
+    }
+}
+
+
+/**
+ * Compute the position by trying to adjust the constraints until the computed position fits into the client area.
+ * Returns the best position that fits the constraints.
+ * @param constraints
+ * @param elemRect
+ * @param anchorRect
+ * @param clientRect
+ * @returns null if the element cannot be positioned otherwise returns a position object
+ */
+export function computePosition(constraints: Constraints, elemRect: DOMRect, anchorRect: DOMRect, clientRect: DOMRect): Position | null {
+    const resolver = new PositionResolver(constraints.gap);
+    let computedPos = resolver.computePosition(constraints, elemRect, anchorRect);
+    const isVisibleOnXAxis = isElementVisibleOnAxis(computedPos.rect, clientRect, 'x');
+    const isVisibleOnYAxis = isElementVisibleOnAxis(computedPos.rect, clientRect, 'y');
+    if (isVisibleOnXAxis && isVisibleOnYAxis) {
+        return computedPos; // the element is visible on both axis
+    }
+    let newConstraints: Constraints | null = null;
+    if (!isVisibleOnXAxis) {
+        newConstraints = resolver.flipAxis(constraints, 'x');
+    }
+    if (!isVisibleOnYAxis) {
+        newConstraints = resolver.flipAxis(newConstraints || constraints, 'y');
+    }
+    if (!newConstraints) {
+        return null; // cannot find a better position
+    }
+    computedPos = new PositionResolver(resolver.gap).computePosition(newConstraints, elemRect, anchorRect);
+    if (isElementVisible(computedPos.rect, clientRect)) {
+        return computedPos;
+    }
+    return null; // cannot find a better position
+}

package/src/core/components/popup/utils.ts

@@ -0,0 +1,82 @@
+
+/**
+ * Compute the intersection of the two given rects.
+ * @param rect1
+ * @param rect2
+ * @returns
+ */
+export function intersectRects(rect1: DOMRect, rect2: DOMRect): DOMRect | null {
+    const x1 = Math.max(rect1.left, rect2.left);
+    const y1 = Math.max(rect1.top, rect2.top);
+    const x2 = Math.min(rect1.right, rect2.right);
+    const y2 = Math.min(rect1.bottom, rect2.bottom);
+
+    if (x2 <= x1 || y2 <= y1) {
+        return null; // No intersection
+    }
+
+    return new DOMRect(x1, y1, x2 - x1, y2 - y1);
+}
+
+/**
+ * Compute the visible rectangle of the scrollable parents.
+ * @param scrollableParents
+ * @returns
+ */
+export function computeVisibleClientRect(scrollableParents: HTMLElement[]): DOMRect | null {
+    if (scrollableParents.length === 0) return null;
+    // Initialize the rect as the bounding rect of the first scrollable parent
+    let rect: DOMRect | null = scrollableParents[0].getBoundingClientRect();
+    // Iterate over the remaining scrollable parents to compute the intersection
+    for (let i = 1, l = scrollableParents.length; i < l; i++) {
+        const parentRect = scrollableParents[i].getBoundingClientRect();
+        rect = intersectRects(parentRect, rect);
+        // If there is no intersection, exit early
+        if (!rect) {
+            return null;
+        }
+    }
+    return rect;
+}
+
+/**
+ * Tests whether the given element is scrollable in any direction.
+ * @param element
+ * @returns
+ */
+export function isScrollable(element: HTMLElement): boolean {
+    const hasScrollY = element.scrollHeight > element.clientHeight;
+    const hasScrollX = element.scrollWidth > element.clientWidth;
+
+    if (hasScrollY || hasScrollX) {
+        const style = getComputedStyle(element);
+        if ((hasScrollY && style.overflowY !== 'visible') || (hasScrollX && style.overflowX !== 'visible')) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Get the list of scrollable parents of the given element. The list always include the root parent at the end.
+ * The root parent is either the document.documentElement or the given root element.
+ * To iterate the list from top to down you need to iterate from the end to the start of the list,
+ * since the root parent is always the last element and the nearest scrollable parent is the first element.
+ * @param element
+ * @param root
+ * @returns
+ */
+export function getScrollableParents(element: HTMLElement, root: HTMLElement = document.documentElement): HTMLElement[] {
+    const parents: HTMLElement[] = [];
+    let parent = element.parentElement;
+
+    while (parent && parent !== root) {
+        isScrollable(parent) && parents.push(parent);
+        parent = parent.parentElement;
+    }
+
+    // Always push the root element
+    parents.push(root);
+    return parents;
+}