vira 32.4.0 → 33.0.0

package/dist/elements/popover/vira-menu.element.js

@@ -0,0 +1,262 @@
+import { assertWrap } from '@augment-vir/assert';
+import { classMap, css, html, listen, onResize } from 'element-vir';
+import { ChevronUp16Icon } from '../../icons/index.js';
+import { viraFormCssVars } from '../../styles/form-styles.js';
+import { noUserSelect } from '../../styles/index.js';
+import { viraShadows } from '../../styles/shadows.js';
+import { defineViraElement } from '../../util/define-vira-element.js';
+import { ViraIcon } from '../vira-icon.element.js';
+/**
+ * Possible corner styles for {@link ViraMenu}.
+ *
+ * @category Internal
+ */
+export var ViraMenuCornerStyle;
+(function (ViraMenuCornerStyle) {
+    /** All of the menus corners should be rounded. */
+    ViraMenuCornerStyle["Round"] = "round";
+    /** None of the menus corners should be rounded. */
+    ViraMenuCornerStyle["Square"] = "square";
+})(ViraMenuCornerStyle || (ViraMenuCornerStyle = {}));
+var ScrollDirection;
+(function (ScrollDirection) {
+    ScrollDirection["Up"] = "up";
+    ScrollDirection["Down"] = "down";
+})(ScrollDirection || (ScrollDirection = {}));
+const defaultHoverScrollSpeed = 24;
+function canScroll(scrollArea, direction) {
+    const remainingScroll = {
+        [ScrollDirection.Up]: scrollArea.scrollTop,
+        [ScrollDirection.Down]: scrollArea.scrollHeight - scrollArea.clientHeight - scrollArea.scrollTop,
+    };
+    /** Scroll positions can be fractional, so less than a pixel left counts as the end. */
+    return remainingScroll[direction] >= 1;
+}
+/** Item positions relative to the top of `scrollArea`'s content. */
+function getItemBounds(scrollArea, items) {
+    const scrollAreaTop = scrollArea.getBoundingClientRect().top;
+    return items.map((item) => {
+        const rect = item.getBoundingClientRect();
+        const top = rect.top - scrollAreaTop + scrollArea.scrollTop;
+        return {
+            top,
+            bottom: top + rect.height,
+        };
+    });
+}
+/** Whether an item in `direction` is more than half scrolled out of view. */
+function hasHalfHiddenItem(scrollArea, items, direction) {
+    const itemBounds = getItemBounds(scrollArea, items);
+    const firstItem = itemBounds[0];
+    const lastItem = itemBounds.at(-1);
+    if (!firstItem || !lastItem) {
+        return canScroll(scrollArea, direction);
+    }
+    const isHalfHidden = {
+        [ScrollDirection.Up]() {
+            return (firstItem.top + firstItem.bottom) / 2 < scrollArea.scrollTop;
+        },
+        [ScrollDirection.Down]() {
+            return ((lastItem.top + lastItem.bottom) / 2 >
+                scrollArea.scrollTop + scrollArea.clientHeight);
+        },
+    };
+    return isHalfHidden[direction]();
+}
+/**
+ * Finds the `scrollTop` that fully reveals the next item that is cut off in `direction`, falling
+ * back to the end of the scroll area when no item is cut off.
+ */
+function findNextItemScrollTop(scrollArea, items, direction) {
+    const itemBounds = getItemBounds(scrollArea, items);
+    const maxScrollTop = scrollArea.scrollHeight - scrollArea.clientHeight;
+    const scrollTops = {
+        [ScrollDirection.Up]() {
+            const item = itemBounds.findLast((bounds) => bounds.top < scrollArea.scrollTop - 1);
+            return Math.max(0, item?.top ?? 0);
+        },
+        [ScrollDirection.Down]() {
+            const item = itemBounds.find((bounds) => bounds.bottom > scrollArea.scrollTop + scrollArea.clientHeight + 1);
+            return Math.min(maxScrollTop, (item?.bottom ?? Infinity) - scrollArea.clientHeight);
+        },
+    };
+    return scrollTops[direction]();
+}
+/**
+ * Scrolls `scrollArea` one item at a time until it reaches its end or the returned callback is
+ * called.
+ */
+function scrollByItems({ scrollArea, items, direction, itemsPerSecond, }) {
+    function scrollOneItem() {
+        scrollArea.scrollTop = findNextItemScrollTop(scrollArea, items, direction);
+        if (!canScroll(scrollArea, direction)) {
+            clearInterval(interval);
+        }
+    }
+    const interval = setInterval(scrollOneItem, 1000 / itemsPerSecond);
+    scrollOneItem();
+    return () => {
+        clearInterval(interval);
+    };
+}
+/**
+ * A simple default style wrapper for popover menus. Consider using `renderMenuItemEntries` to help
+ * rendering many menu items. Like a native `<select>` menu, a menu that scrolls shows an arrow at
+ * each end that has more items, and hovering an arrow scrolls towards that end.
+ *
+ * @category Popover
+ * @category Elements
+ */
+export const ViraMenu = defineViraElement()({
+    tagName: 'vira-menu',
+    state() {
+        return {
+            canScrollUp: false,
+            canScrollDown: false,
+            /** Stops the scrolling that hovering a scroll arrow started. */
+            stopScrolling: undefined,
+        };
+    },
+    cleanup({ state }) {
+        state.stopScrolling?.();
+    },
+    hostClasses: {
+        'vira-menu-square'({ inputs }) {
+            return inputs.cornerStyle === ViraMenuCornerStyle.Square;
+        },
+    },
+    styles({ hostClasses }) {
+        return css `
+            :host {
+                display: flex;
+                flex-direction: column;
+                max-width: 100%;
+                max-height: 100%;
+                overflow: hidden;
+                z-index: 99;
+                box-sizing: border-box;
+                border-radius: ${viraFormCssVars['vira-form-radius'].value};
+                background-color: ${viraFormCssVars['vira-form-background-color'].value};
+                border: 1px solid ${viraFormCssVars['vira-form-border-color'].value};
+                color: ${viraFormCssVars['vira-form-foreground-color'].value};
+                ${viraShadows.menuShadow}
+            }
+
+            ${hostClasses['vira-menu-square'].selector} {
+                border-radius: 0;
+            }
+
+            .scroll-area {
+                min-height: 0;
+                overflow-y: auto;
+                overscroll-behavior: contain;
+            }
+
+            .scroll-area-content {
+                display: flex;
+                flex-direction: column;
+            }
+
+            .scroll-arrow {
+                ${noUserSelect};
+                display: flex;
+                flex-shrink: 0;
+                justify-content: center;
+                padding: 2px 0;
+
+                &.hidden {
+                    display: none;
+                }
+
+                &.down ${ViraIcon} {
+                    transform: rotate(180deg);
+                }
+            }
+        `;
+    },
+    render({ inputs, state, updateState, host }) {
+        function getScrollArea() {
+            return assertWrap.instanceOf(host.shadowRoot.querySelector('.scroll-area'), HTMLElement);
+        }
+        function getItems() {
+            return assertWrap
+                .instanceOf(host.shadowRoot.querySelector('slot'), HTMLSlotElement)
+                .assignedElements({
+                flatten: true,
+            });
+        }
+        function updateScrollArrows() {
+            updateState({
+                canScrollUp: hasHalfHiddenItem(getScrollArea(), getItems(), ScrollDirection.Up),
+                canScrollDown: hasHalfHiddenItem(getScrollArea(), getItems(), ScrollDirection.Down),
+            });
+        }
+        function renderScrollArrow(direction, isShown) {
+            return html `
+                <div
+                    class=${classMap({
+                'scroll-arrow': true,
+                [direction]: true,
+                hidden: !isShown,
+            })}
+                    aria-hidden="true"
+                    ${listen('mouseenter', () => {
+                state.stopScrolling?.();
+                updateState({
+                    stopScrolling: scrollByItems({
+                        scrollArea: getScrollArea(),
+                        items: getItems(),
+                        direction,
+                        itemsPerSecond: inputs.hoverScrollSpeed ?? defaultHoverScrollSpeed,
+                    }),
+                });
+            })}
+                    ${listen('mouseleave', () => {
+                state.stopScrolling?.();
+                updateState({
+                    stopScrolling: undefined,
+                });
+            })}
+                    ${listen('mousedown', (event) => {
+                /** Keeps focus on the current menu item. */
+                event.preventDefault();
+            })}
+                    ${listen('click', (event) => {
+                /** Keeps `ViraPopoverTrigger` from closing the menu. */
+                event.stopPropagation();
+            })}
+                >
+                    <${ViraIcon.assign({
+                icon: ChevronUp16Icon,
+            })}></${ViraIcon}>
+                </div>
+            `;
+        }
+        return html `
+            ${renderScrollArrow(ScrollDirection.Up, state.canScrollUp)}
+            <div
+                class="scroll-area"
+                ${listen('scroll', () => {
+            updateScrollArrows();
+        })}
+                ${onResize(() => {
+            /**
+             * Showing or hiding an arrow resizes the scroll area, which inside a
+             * ResizeObserver callback causes a "ResizeObserver loop" error.
+             */
+            requestAnimationFrame(updateScrollArrows);
+        })}
+            >
+                <div
+                    class="scroll-area-content"
+                    ${onResize(() => {
+            requestAnimationFrame(updateScrollArrows);
+        })}
+                >
+                    <slot>&nbsp;</slot>
+                </div>
+            </div>
+            ${renderScrollArrow(ScrollDirection.Down, state.canScrollDown)}
+        `;
+    },
+});

package/dist/elements/popover/vira-popover-trigger.element.d.ts

@@ -0,0 +1,49 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { NavController, type Coords } from 'device-navigation';
+import { PopoverManager, PopoverTrigger } from '../../util/popover-manager.js';
+/**
+ * Offsets applied to any menu opened by {@link ViraPopoverTrigger}.
+ *
+ * @category Internal
+ */
+export type PopoverOffset = PartialWithUndefined<{
+    vertical: number;
+    /** Moves the popover rightwards when it opens from the trigger's left edge. */
+    left: number;
+    /** Only shrinks the popover's minimum width (the trigger's width). This never moves the popover. */
+    right: number;
+}>;
+/**
+ * An element with slots for a popover trigger and popover contents.
+ *
+ * @category Popover
+ * @category Elements
+ * @see https://electrovir.github.io/vira/book/elements/vira-popover-trigger
+ */
+export declare const ViraPopoverTrigger: import("element-vir").DeclarativeElementDefinition<`vira-${string}`, PartialWithUndefined<{
+    isDisabled: boolean;
+    /**
+     * Defaults to {@link PopoverTrigger.Mousedown}. `true` or `false` force the popover open or
+     * closed.
+     */
+    trigger: boolean | PopoverTrigger;
+    /** Set to `true` to keep the popover open if it is interacted with. */
+    keepOpenAfterInteraction: boolean;
+    /** All values in px. */
+    popoverOffset: PopoverOffset;
+    /** If true, the focus outline is moved inside the element. */
+    useInsideFocus: boolean;
+    /** When `true`, the trigger will focus itself when the popover closes. */
+    focusOnClose: boolean;
+}>, {
+    isOpen: boolean;
+    navController: NavController;
+    popoverManager: PopoverManager;
+}, {
+    navSelect: import("element-vir").DefineElementEvent<Coords>;
+    /** `true` when the popover just opened, `false` when it just closed. */
+    openChange: import("element-vir").DefineElementEvent<boolean>;
+    init: import("element-vir").DefineElementEvent<{
+        navController: NavController;
+    }>;
+}, "vira-popover-trigger-disabled" | "vira-popover-trigger-inside-focus" | "vira-popover-trigger-outside-focus", "vira-popover-trigger-offset-vertical" | "vira-popover-trigger-offset-left" | "vira-popover-trigger-offset-right", readonly ["vira-popover-trigger-trigger", "vira-popover-trigger-popover"], readonly []>;

package/dist/elements/popover/vira-popover-trigger.element.js

@@ -0,0 +1,301 @@
+import { assertWrap } from '@augment-vir/assert';
+import { NavController } from 'device-navigation';
+import { classMap, css, defineElementEvent, html, listen, renderIf } from 'element-vir';
+import { listenTo } from 'typed-event-target';
+import { popover } from '../../directives/popover.directive.js';
+import { createFocusStyles } from '../../styles/focus.js';
+import { noNativeFormStyles, noUserSelect, viraDisabledStyles } from '../../styles/index.js';
+import { createAnchoredPopoverStyles } from '../../util/anchored-popover.js';
+import { defineViraElement } from '../../util/define-vira-element.js';
+import { isMouseEventOnScrollbar, isTextInputActive, PopoverManager, PopoverTrigger, } from '../../util/popover-manager.js';
+import { ViraMenuItem } from './vira-menu-item.element.js';
+/**
+ * An element with slots for a popover trigger and popover contents.
+ *
+ * @category Popover
+ * @category Elements
+ * @see https://electrovir.github.io/vira/book/elements/vira-popover-trigger
+ */
+export const ViraPopoverTrigger = defineViraElement()({
+    tagName: 'vira-popover-trigger',
+    state({ host }) {
+        const navController = new NavController(host, {
+            activateOnMouseUp: true,
+        });
+        return {
+            isOpen: false,
+            navController,
+            popoverManager: new PopoverManager(navController),
+        };
+    },
+    slotNames: [
+        'vira-popover-trigger-trigger',
+        'vira-popover-trigger-popover',
+    ],
+    hostClasses: {
+        'vira-popover-trigger-disabled'({ inputs }) {
+            return !!inputs.isDisabled;
+        },
+        'vira-popover-trigger-inside-focus'({ inputs }) {
+            return !!inputs.useInsideFocus;
+        },
+        'vira-popover-trigger-outside-focus'({ inputs }) {
+            return !inputs.useInsideFocus;
+        },
+    },
+    cssVars: {
+        'vira-popover-trigger-offset-vertical': '0px',
+        'vira-popover-trigger-offset-left': '0px',
+        'vira-popover-trigger-offset-right': '0px',
+    },
+    styles({ hostClasses, cssVars }) {
+        return css `
+            :host {
+                display: inline-flex;
+                box-sizing: border-box;
+                vertical-align: middle;
+                position: relative;
+                max-width: 100%;
+            }
+
+            .dropdown-wrapper {
+                ${noNativeFormStyles};
+                cursor: pointer;
+                max-width: 100%;
+                position: relative;
+                flex-grow: 1;
+                box-sizing: border-box;
+            }
+
+            ${hostClasses['vira-popover-trigger-inside-focus'].selector} .dropdown-wrapper {
+                ${createFocusStyles({
+            renderInside: true,
+        })}
+            }
+            ${hostClasses['vira-popover-trigger-outside-focus'].selector} .dropdown-wrapper {
+                ${createFocusStyles()}
+            }
+
+            .dropdown-trigger {
+                box-sizing: border-box;
+                ${noUserSelect};
+            }
+
+            ${hostClasses['vira-popover-trigger-disabled'].selector} {
+                ${viraDisabledStyles}
+                pointer-events: auto;
+            }
+
+            ${hostClasses['vira-popover-trigger-disabled'].selector} .dropdown-wrapper {
+                pointer-events: none;
+            }
+
+            ${createAnchoredPopoverStyles({
+            selector: css `.popover-positioner`,
+            /**
+             * Each fallback has an upwards copy because a position-try-fallbacks entry can only
+             * reference one @position-try rule. Every downwards entry comes before any upwards
+             * entry. The last entry always fits because, when no entry fits, browsers use the
+             * first one and shift it over the trigger.
+             */
+            fallbacks: [
+                {
+                    /**
+                     * Used instead of flip-inline, which would move the left offset to the
+                     * right side.
+                     */
+                    name: 'vira-popover-leftwards',
+                    styles: css `
+                            position-area: block-end span-inline-start;
+                            margin-left: 0;
+                        `,
+                },
+                {
+                    /**
+                     * For a popover that fits on neither side of the trigger. 100% instead of
+                     * 100vw so that this always fits, even next to a scrollbar.
+                     */
+                    name: 'vira-popover-viewport-right',
+                    styles: css `
+                            position-area: block-end span-all;
+                            justify-self: end;
+                            margin-left: 0;
+                            max-width: min(500px, 100%);
+                        `,
+                },
+                {
+                    name: 'vira-popover-upwards',
+                    styles: css `
+                            min-height: 0;
+                        `,
+                    flipBlock: true,
+                },
+                {
+                    name: 'vira-popover-leftwards-upwards',
+                    styles: css `
+                            position-area: block-end span-inline-start;
+                            margin-left: 0;
+                            min-height: 0;
+                        `,
+                    flipBlock: true,
+                },
+                {
+                    name: 'vira-popover-viewport-right-upwards',
+                    styles: css `
+                            position-area: block-end span-all;
+                            justify-self: end;
+                            margin-left: 0;
+                            max-width: min(500px, 100%);
+                            min-height: 0;
+                        `,
+                    flipBlock: true,
+                },
+            ],
+        })}
+
+            .popover-positioner {
+                pointer-events: none;
+                box-sizing: border-box;
+                flex-direction: column;
+                align-items: stretch;
+
+                margin-top: ${cssVars['vira-popover-trigger-offset-vertical'].value};
+                /*
+                    The positioner is invisible outside of its content, so this minimum only makes
+                    it flip upwards when there is not much room below the trigger.
+                */
+                min-height: 200px;
+                /* Margins are not included in the percentage. */
+                max-height: calc(100% - ${cssVars['vira-popover-trigger-offset-vertical'].value});
+                width: max-content;
+                min-width: calc(
+                    anchor-size(width) - ${cssVars['vira-popover-trigger-offset-left'].value} -
+                        ${cssVars['vira-popover-trigger-offset-right'].value}
+                );
+                /*
+                    Not limited to the room beside the trigger, so a popover that does not fit there
+                    overflows it and moves on to the next position-try-fallbacks entry.
+                */
+                max-width: min(500px, 100vw);
+                position-area: block-end span-inline-end;
+                margin-left: ${cssVars['vira-popover-trigger-offset-left'].value};
+
+                &:popover-open {
+                    display: flex;
+                }
+
+                & > * {
+                    pointer-events: auto;
+                    max-width: 100%;
+                }
+            }
+        `;
+    },
+    events: {
+        navSelect: defineElementEvent(),
+        /** `true` when the popover just opened, `false` when it just closed. */
+        openChange: defineElementEvent(),
+        init: defineElementEvent(),
+    },
+    cleanup({ state, updateState }) {
+        updateState({
+            isOpen: false,
+        });
+        state.popoverManager.destroy();
+    },
+    init({ state, inputs, dispatch, events, host }) {
+        /**
+         * Listens on the host rather than the popover because a drag from the trigger that is
+         * released in the popover fires its click on the closest element containing both.
+         */
+        listenTo(host, 'click', (event) => {
+            const anchor = host.shadowRoot.querySelector('.dropdown-wrapper');
+            if (inputs.keepOpenAfterInteraction ||
+                (anchor && event.composedPath().includes(anchor)) ||
+                (event instanceof MouseEvent && event.detail === 0
+                    ? isTextInputActive()
+                    : !(event instanceof MouseEvent) ||
+                        event.button !== 0 ||
+                        isMouseEventOnScrollbar(event))) {
+                return;
+            }
+            /** Close the popover when something in it (like a menu item) is clicked. */
+            state.popoverManager.hide();
+        });
+        dispatch(new events.init({
+            detail: {
+                navController: state.navController,
+            },
+        }));
+    },
+    render({ dispatch, events, state, inputs, updateState, host, slotNames, cssVars }) {
+        return html `
+            <button
+                ?disabled=${!!inputs.isDisabled}
+                class="dropdown-wrapper ${classMap({
+            open: state.isOpen,
+        })}"
+                role="listbox"
+                aria-expanded=${state.isOpen}
+                ${popover(state.popoverManager, {
+            trigger: inputs.isDisabled
+                ? false
+                : (inputs.trigger ?? PopoverTrigger.Mousedown),
+            getPopover() {
+                return assertWrap.instanceOf(host.shadowRoot.querySelector('.popover-positioner'), HTMLElement);
+            },
+            onNavSelect(coords) {
+                if (!inputs.keepOpenAfterInteraction) {
+                    state.popoverManager.hide();
+                }
+                dispatch(new events.navSelect({
+                    detail: coords,
+                }));
+            },
+        })}
+            >
+                <div class="dropdown-trigger">
+                    <slot name=${slotNames['vira-popover-trigger-trigger']}></slot>
+                </div>
+            </button>
+            <div
+                class="popover-positioner"
+                popover="manual"
+                style=${css `
+                    ${cssVars['vira-popover-trigger-offset-vertical'].name}: ${inputs.popoverOffset
+            ?.vertical || 0}px;
+                    ${cssVars['vira-popover-trigger-offset-left'].name}: ${inputs.popoverOffset
+            ?.left || 0}px;
+                    ${cssVars['vira-popover-trigger-offset-right'].name}: ${inputs.popoverOffset
+            ?.right || 0}px;
+                `}
+                ${listen('toggle', () => {
+            const isOpen = state.popoverManager.isOpen();
+            if (isOpen === state.isOpen) {
+                return;
+            }
+            updateState({
+                isOpen,
+            });
+            dispatch(new events.openChange({
+                detail: isOpen,
+            }));
+            if (!isOpen && inputs.focusOnClose && !inputs.isDisabled) {
+                assertWrap
+                    .instanceOf(host.shadowRoot.querySelector('.dropdown-wrapper'), HTMLButtonElement)
+                    .focus();
+            }
+        })}
+                ${listen(ViraMenuItem.events.activate, () => {
+            if (!inputs.keepOpenAfterInteraction) {
+                state.popoverManager.hide();
+            }
+        })}
+            >
+                ${renderIf(state.isOpen, html `
+                        <slot name=${slotNames['vira-popover-trigger-popover']}></slot>
+                    `)}
+            </div>
+        `;
+    },
+});

package/dist/elements/popover/vira-tooltip.element.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The popover rendered by the `tooltip` directive. The element itself is the popover, centered
+ * above `anchor` when there's room. Its children are the tooltip contents.
+ *
+ * @category Popover
+ * @category Elements
+ */
+export declare const ViraTooltip: import("element-vir").DeclarativeElementDefinition<"vira-tooltip", {
+    anchor: HTMLElement;
+}, {}, {}, "vira-tooltip-", "vira-tooltip-", readonly [], readonly []>;