vira 32.4.0 → 33.1.0

package/dist/util/popover-manager.d.ts

@@ -0,0 +1,123 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type AnyDuration } from 'date-vir';
+import { type Coords, type NavController } from 'device-navigation';
+/**
+ * Used to prevent popovers from closing when a text input is active.
+ *
+ * @category Internal
+ */
+export declare function isInputLikeElement(element: Element): boolean;
+/**
+ * Whether a keyboard click (a click with `detail` of `0`) came from pressing Enter in a text input,
+ * which browsers turn into a click on the form's first button.
+ *
+ * @category Internal
+ */
+export declare function isTextInputActive(): boolean;
+/**
+ * Determines if a mouse event landed on a scrollbar rather than on element content. Scrollbar
+ * interactions fire mouse events on the scrolling element itself (or on `<html>` for the page
+ * scrollbar), so an outside-click check would otherwise treat dragging a scrollbar as a click away
+ * from the popover and dismiss it mid-drag.
+ *
+ * @category Internal
+ */
+export declare function isMouseEventOnScrollbar(event: Readonly<MouseEvent>): boolean;
+/**
+ * The interaction on the anchor element that shows and hides a popover.
+ *
+ * @category Popover
+ */
+export declare enum PopoverTrigger {
+    /**
+     * Shows the popover shortly after the anchor is hovered or focused and hides it when the anchor
+     * is no longer hovered or focused.
+     */
+    Hover = "hover",
+    /** Toggles the popover when the anchor is clicked. An arrow key opens it. */
+    Click = "click",
+    /**
+     * Toggles the popover as soon as the mouse is pressed on the anchor, so it can be dragged over
+     * the popover's contents and released on one of them. Keyboard clicks and arrow keys also
+     * work.
+     */
+    Mousedown = "mousedown"
+}
+/**
+ * Options for {@link PopoverManager.update}, usually passed through the `popover` directive.
+ *
+ * @category Popover
+ */
+export type PopoverOptions = {
+    /** `true` or `false` force the popover open or closed, ignoring all interactions. */
+    trigger: boolean | PopoverTrigger;
+    /**
+     * Returns the `popover` element to open. Called each time the popover opens, so it may create
+     * the element.
+     */
+    getPopover: () => HTMLElement;
+} & PartialWithUndefined<{
+    /** Called when the user selects an item in the popover through the `NavController`. */
+    onNavSelect: (coords: Coords) => void;
+    /**
+     * How long to wait after the popover is triggered before opening it. Defaults to 300
+     * milliseconds for {@link PopoverTrigger.Hover} and no delay for everything else.
+     */
+    delay: AnyDuration;
+    /** Closes the popover once it has been open this long. By default it stays open. */
+    timeout: AnyDuration;
+}>;
+/**
+ * Opens and closes a single `popover` element that is anchored to another element: it opens the
+ * popover in response to the anchor's interactions (see {@link PopoverTrigger}) and closes it on
+ * Escape, an outside mousedown, or the page going inactive. Style the popover with
+ * `createAnchoredPopoverStyles`.
+ *
+ * @category Popover
+ */
+export declare class PopoverManager {
+    /**
+     * Enables arrow key navigation within the open popover. Omit this for popovers that have
+     * nothing to navigate, like tooltips.
+     */
+    readonly navController?: NavController | undefined;
+    protected anchor: HTMLElement | undefined;
+    protected options: Readonly<PopoverOptions> | undefined;
+    /** The most recently opened popover. */
+    protected popover: HTMLElement | undefined;
+    protected showTimeout: ReturnType<typeof setTimeout> | undefined;
+    /** Closes the popover after `options.timeout`. */
+    protected hideTimeout: ReturnType<typeof setTimeout> | undefined;
+    /** Removes the listeners for the current anchor and `trigger`. */
+    protected removeAnchorListeners: (() => void) | undefined;
+    /** Removes the global listeners attached while the popover is open. */
+    protected removeOpenListeners: (() => void) | undefined;
+    constructor(
+    /**
+     * Enables arrow key navigation within the open popover. Omit this for popovers that have
+     * nothing to navigate, like tooltips.
+     */
+    navController?: NavController | undefined);
+    /** Whether the popover is open. */
+    isOpen(): boolean;
+    /** Call this each time the anchor or options might have changed. The `popover` directive does. */
+    update(anchor: HTMLElement, options: Readonly<PopoverOptions>): void;
+    /** Opens or closes the popover when `trigger` is `true` or `false`. */
+    applyForcedState(): void;
+    /** Opens the popover right away. */
+    show(): void;
+    /** Closes the popover, unless `trigger` forces it open, and cancels a scheduled show. */
+    hide(): void;
+    /** Opens the popover after `options.delay`. */
+    scheduleShow(): void;
+    /** Opens the popover, or closes it (and cancels a delayed open). */
+    toggle(): void;
+    /** Opens a closed popover when an arrow key is pressed. */
+    openOnArrow(event: Readonly<KeyboardEvent>): void;
+    /** Closes the popover and removes all listeners. */
+    destroy(): void;
+    /** Closes the popover even when `trigger` forces it open. */
+    close(): void;
+    /** Attaches the global listeners that only matter while the popover is open. */
+    protected attachOpenListeners(): () => void;
+}

package/dist/util/popover-manager.js

@@ -0,0 +1,414 @@
+import { check } from '@augment-vir/assert';
+import { walkActiveElement } from '@augment-vir/web';
+import { convertDuration } from 'date-vir';
+import { NavActivateEvent, NavDirection } from 'device-navigation';
+import { listenToPageActivation } from 'page-active';
+import { listenTo, listenToGlobal } from 'typed-event-target';
+import { anchoredPopoverRetryClass } from './anchored-popover.js';
+/**
+ * Used to prevent popovers from closing when a text input is active.
+ *
+ * @category Internal
+ */
+export function isInputLikeElement(element) {
+    return ((element instanceof HTMLInputElement &&
+        (element.type === 'text' ||
+            element.type === 'search' ||
+            element.type === 'email' ||
+            element.type === 'url' ||
+            element.type === 'tel' ||
+            element.type === 'password' ||
+            element.type === 'number')) ||
+        element instanceof HTMLTextAreaElement ||
+        (element instanceof HTMLElement && element.isContentEditable));
+}
+/**
+ * Whether a keyboard click (a click with `detail` of `0`) came from pressing Enter in a text input,
+ * which browsers turn into a click on the form's first button.
+ *
+ * @category Internal
+ */
+export function isTextInputActive() {
+    let isActive = false;
+    walkActiveElement(({ element }) => {
+        isActive = isInputLikeElement(element);
+        return isActive;
+    });
+    return isActive;
+}
+/**
+ * Determines if a mouse event landed on a scrollbar rather than on element content. Scrollbar
+ * interactions fire mouse events on the scrolling element itself (or on `<html>` for the page
+ * scrollbar), so an outside-click check would otherwise treat dragging a scrollbar as a click away
+ * from the popover and dismiss it mid-drag.
+ *
+ * @category Internal
+ */
+export function isMouseEventOnScrollbar(event) {
+    const target = event.composedPath()[0];
+    if (!(target instanceof Element)) {
+        return false;
+    }
+    const rect = target.getBoundingClientRect();
+    /**
+     * `clientLeft` and `clientTop` are the border widths, which also include the scrollbar itself
+     * when it's rendered on the leading edge (RTL layouts).
+     */
+    const clientLeft = rect.left + target.clientLeft;
+    const clientTop = rect.top + target.clientTop;
+    const outsideHorizontally = event.clientX < clientLeft || event.clientX >= clientLeft + target.clientWidth;
+    const outsideVertically = event.clientY < clientTop || event.clientY >= clientTop + target.clientHeight;
+    return ((outsideHorizontally && target.scrollHeight > target.clientHeight) ||
+        (outsideVertically && target.scrollWidth > target.clientWidth));
+}
+/**
+ * The interaction on the anchor element that shows and hides a popover.
+ *
+ * @category Popover
+ */
+export var PopoverTrigger;
+(function (PopoverTrigger) {
+    /**
+     * Shows the popover shortly after the anchor is hovered or focused and hides it when the anchor
+     * is no longer hovered or focused.
+     */
+    PopoverTrigger["Hover"] = "hover";
+    /** Toggles the popover when the anchor is clicked. An arrow key opens it. */
+    PopoverTrigger["Click"] = "click";
+    /**
+     * Toggles the popover as soon as the mouse is pressed on the anchor, so it can be dragged over
+     * the popover's contents and released on one of them. Keyboard clicks and arrow keys also
+     * work.
+     */
+    PopoverTrigger["Mousedown"] = "mousedown";
+})(PopoverTrigger || (PopoverTrigger = {}));
+const defaultDelays = {
+    [PopoverTrigger.Hover]: {
+        milliseconds: 300,
+    },
+};
+function listenToAnchor(anchor, eventName, listener) {
+    return listenTo(anchor, eventName, (event) => {
+        listener(event);
+    });
+}
+const anchorListeners = {
+    [PopoverTrigger.Hover](popoverManager, anchor) {
+        return [
+            listenToAnchor(anchor, 'mouseenter', () => {
+                popoverManager.scheduleShow();
+            }),
+            listenToAnchor(anchor, 'focusin', () => {
+                popoverManager.scheduleShow();
+            }),
+            listenToAnchor(anchor, 'mouseleave', () => {
+                popoverManager.hide();
+            }),
+            listenToAnchor(anchor, 'focusout', () => {
+                popoverManager.hide();
+            }),
+        ];
+    },
+    [PopoverTrigger.Click](popoverManager, anchor) {
+        return [
+            listenToAnchor(anchor, 'click', (event) => {
+                if (event.detail !== 0 || !isTextInputActive()) {
+                    popoverManager.toggle();
+                }
+            }),
+            listenToAnchor(anchor, 'keydown', (event) => {
+                popoverManager.openOnArrow(event);
+            }),
+        ];
+    },
+    [PopoverTrigger.Mousedown](popoverManager, anchor) {
+        return [
+            listenToAnchor(anchor, 'mousedown', (event) => {
+                if (event.button === 0 && !isMouseEventOnScrollbar(event)) {
+                    const target = event.composedPath()[0];
+                    if (!(target instanceof Element && isInputLikeElement(target))) {
+                        /**
+                         * Without this, WebKit scrolls the anchor's scroll containers when the
+                         * pointer is dragged past their edges on the way to a popover item.
+                         */
+                        event.preventDefault();
+                        /** Preventing the default also prevents the focus that mousedown gives. */
+                        event
+                            .composedPath()
+                            .find((eventTarget) => {
+                            return (eventTarget instanceof HTMLElement && eventTarget.tabIndex >= 0);
+                        })
+                            ?.focus({
+                            preventScroll: true,
+                            /** Otherwise a mouse click shows the keyboard focus ring. */
+                            focusVisible: false,
+                        });
+                    }
+                    popoverManager.toggle();
+                }
+            }),
+            listenToAnchor(anchor, 'click', (event) => {
+                /** Mouse clicks were already handled by the mousedown. */
+                if (event.detail === 0 && !isTextInputActive()) {
+                    popoverManager.toggle();
+                }
+            }),
+            listenToAnchor(anchor, 'keydown', (event) => {
+                popoverManager.openOnArrow(event);
+            }),
+        ];
+    },
+};
+/**
+ * Opens and closes a single `popover` element that is anchored to another element: it opens the
+ * popover in response to the anchor's interactions (see {@link PopoverTrigger}) and closes it on
+ * Escape, an outside mousedown, or the page going inactive. Style the popover with
+ * `createAnchoredPopoverStyles`.
+ *
+ * @category Popover
+ */
+export class PopoverManager {
+    navController;
+    anchor;
+    options;
+    /** The most recently opened popover. */
+    popover;
+    showTimeout;
+    /** Closes the popover after `options.timeout`. */
+    hideTimeout;
+    /** Removes the listeners for the current anchor and `trigger`. */
+    removeAnchorListeners;
+    /** Removes the global listeners attached while the popover is open. */
+    removeOpenListeners;
+    constructor(
+    /**
+     * Enables arrow key navigation within the open popover. Omit this for popovers that have
+     * nothing to navigate, like tooltips.
+     */
+    navController) {
+        this.navController = navController;
+    }
+    /** Whether the popover is open. */
+    isOpen() {
+        return !!this.popover?.matches(':popover-open');
+    }
+    /** Call this each time the anchor or options might have changed. The `popover` directive does. */
+    update(anchor, options) {
+        const previousTrigger = this.options?.trigger;
+        this.options = options;
+        if (anchor === this.anchor && options.trigger === previousTrigger) {
+            return;
+        }
+        this.removeAnchorListeners?.();
+        this.anchor = anchor;
+        const removeListeners = check.isBoolean(options.trigger)
+            ? []
+            : anchorListeners[options.trigger](this, anchor);
+        this.removeAnchorListeners = () => {
+            removeListeners.forEach((removeListener) => removeListener());
+        };
+        this.applyForcedState();
+    }
+    /** Opens or closes the popover when `trigger` is `true` or `false`. */
+    applyForcedState() {
+        if (this.options?.trigger === true) {
+            /**
+             * Deferred because on first render lit updates directives before inserting the template
+             * into the document, and a disconnected popover cannot open.
+             */
+            queueMicrotask(() => {
+                if (this.options?.trigger === true) {
+                    this.scheduleShow();
+                }
+            });
+        }
+        else if (this.options?.trigger === false) {
+            this.close();
+        }
+    }
+    /** Opens the popover right away. */
+    show() {
+        clearTimeout(this.showTimeout);
+        this.showTimeout = undefined;
+        if (!this.anchor || !this.options || this.isOpen()) {
+            return;
+        }
+        this.popover = this.options.getPopover();
+        this.popover.showPopover({
+            source: this.anchor,
+        });
+        this.removeOpenListeners = this.attachOpenListeners();
+        if (this.options.timeout) {
+            this.hideTimeout = setTimeout(() => {
+                this.hide();
+            }, convertDuration(this.options.timeout, {
+                milliseconds: true,
+            }).milliseconds);
+        }
+    }
+    /** Closes the popover, unless `trigger` forces it open, and cancels a scheduled show. */
+    hide() {
+        if (this.options?.trigger !== true) {
+            this.close();
+        }
+    }
+    /** Opens the popover after `options.delay`. */
+    scheduleShow() {
+        if (this.showTimeout || this.isOpen() || !this.options) {
+            return;
+        }
+        const rawDelay = this.options.delay ||
+            (check.isBoolean(this.options.trigger) ? {} : defaultDelays[this.options.trigger]);
+        const delay = rawDelay &&
+            convertDuration(rawDelay, {
+                milliseconds: true,
+            });
+        if (delay && delay.milliseconds > 0) {
+            this.showTimeout = setTimeout(() => {
+                this.show();
+            }, delay.milliseconds);
+        }
+        else {
+            this.show();
+        }
+    }
+    /** Opens the popover, or closes it (and cancels a delayed open). */
+    toggle() {
+        if (this.isOpen() || this.showTimeout) {
+            this.hide();
+        }
+        else {
+            this.scheduleShow();
+        }
+    }
+    /** Opens a closed popover when an arrow key is pressed. */
+    openOnArrow(event) {
+        if (event.code.startsWith('Arrow')) {
+            this.scheduleShow();
+        }
+    }
+    /** Closes the popover and removes all listeners. */
+    destroy() {
+        this.removeAnchorListeners?.();
+        this.removeAnchorListeners = undefined;
+        this.anchor = undefined;
+        this.close();
+    }
+    /** Closes the popover even when `trigger` forces it open. */
+    close() {
+        clearTimeout(this.showTimeout);
+        this.showTimeout = undefined;
+        clearTimeout(this.hideTimeout);
+        this.hideTimeout = undefined;
+        this.removeOpenListeners?.();
+        this.removeOpenListeners = undefined;
+        if (this.isOpen()) {
+            this.popover?.hidePopover();
+        }
+    }
+    /** Attaches the global listeners that only matter while the popover is open. */
+    attachOpenListeners() {
+        const navController = this.navController;
+        const removeListeners = [
+            listenToGlobal('resize', () => {
+                this.popover?.classList.toggle(anchoredPopoverRetryClass);
+                /** `nearest` does not scroll at all when the anchor is already fully visible. */
+                this.anchor?.scrollIntoView({
+                    block: 'nearest',
+                    inline: 'nearest',
+                });
+            }, {
+                passive: true,
+            }),
+            listenToGlobal('scroll', () => {
+                this.popover?.classList.toggle(anchoredPopoverRetryClass);
+            }, {
+                /** Scroll events do not bubble, so this catches scrolling in any element. */
+                capture: true,
+                passive: true,
+            }),
+            listenToPageActivation(false, (isPageActive) => {
+                if (!isPageActive) {
+                    this.hide();
+                }
+            }),
+            navController?.listen(NavActivateEvent, (event) => {
+                const target = event.composedPath()[0];
+                if (target instanceof Element && isInputLikeElement(target)) {
+                    return;
+                }
+                if (event.detail.success) {
+                    this.options?.onNavSelect?.(event.detail.coords);
+                    navController.currentNavEntry?.entry.focus(true);
+                    event.stopImmediatePropagation();
+                    event.preventDefault();
+                }
+            }),
+            listenToGlobal('mousedown', (event) => {
+                const path = event.composedPath();
+                if ((this.anchor && path.includes(this.anchor)) ||
+                    (this.popover && path.includes(this.popover)) ||
+                    isMouseEventOnScrollbar(event)) {
+                    return;
+                }
+                this.hide();
+            }, {
+                passive: true,
+            }),
+            listenToGlobal('keydown', (event) => {
+                const keyCode = event.code;
+                if (keyCode === 'Escape') {
+                    this.hide();
+                }
+                else if (navController) {
+                    const target = event.composedPath()[0];
+                    if (target instanceof Element && isInputLikeElement(target)) {
+                        return;
+                    }
+                    if (keyCode === 'ArrowDown') {
+                        event.stopImmediatePropagation();
+                        event.preventDefault();
+                        navController.navigate({
+                            direction: NavDirection.Down,
+                            allowWrapping: false,
+                        });
+                    }
+                    else if (keyCode === 'ArrowUp') {
+                        event.stopImmediatePropagation();
+                        event.preventDefault();
+                        navController.navigate({
+                            direction: NavDirection.Up,
+                            allowWrapping: false,
+                        });
+                    }
+                    else if (keyCode === 'ArrowLeft') {
+                        event.stopImmediatePropagation();
+                        event.preventDefault();
+                        navController.navigate({
+                            direction: NavDirection.Left,
+                            allowWrapping: false,
+                        });
+                    }
+                    else if (keyCode === 'ArrowRight') {
+                        event.stopImmediatePropagation();
+                        event.preventDefault();
+                        navController.navigate({
+                            direction: NavDirection.Right,
+                            allowWrapping: false,
+                        });
+                    }
+                    else if ((keyCode === 'Enter' || keyCode === 'Return' || keyCode === 'Space') &&
+                        navController.enterInto({
+                            fallbackToActivate: true,
+                        }).success) {
+                        event.stopImmediatePropagation();
+                        event.preventDefault();
+                    }
+                }
+            }),
+        ].filter(check.isDefined);
+        return () => {
+            removeListeners.forEach((removeListener) => removeListener());
+        };
+    }
+}

package/dist/util/vira-dropdown-option.d.ts

@@ -0,0 +1,30 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+/**
+ * Options for `ViraDropdown`.
+ *
+ * @category Dropdown
+ * @category Elements
+ */
+export type ViraDropdownOption = {
+    /** A value or id, used to keep track of which option is selected. */
+    value: string;
+    label: string;
+} & PartialWithUndefined<{
+    disabled: boolean;
+}>;
+/**
+ * A group of options for `ViraDropdown`, rendered under a group label.
+ *
+ * @category Dropdown
+ * @category Elements
+ */
+export type ViraDropdownOptionGroup = {
+    groupName: string;
+    options: ReadonlyArray<Readonly<ViraDropdownOption>>;
+};
+/**
+ * Type guard to determine if a `ViraDropdown` options entry is a group.
+ *
+ * @category Internal
+ */
+export declare function isViraDropdownOptionGroup(entry: Readonly<ViraDropdownOption> | Readonly<ViraDropdownOptionGroup>): entry is Readonly<ViraDropdownOptionGroup>;

package/dist/util/vira-dropdown-option.js

@@ -0,0 +1,8 @@
+/**
+ * Type guard to determine if a `ViraDropdown` options entry is a group.
+ *
+ * @category Internal
+ */
+export function isViraDropdownOptionGroup(entry) {
+    return 'groupName' in entry;
+}

package/dist/util/vira-form-fields.d.ts

@@ -2,7 +2,7 @@ import { type PartialWithUndefined } from '@augment-vir/common';
 import { type FullDate, type Timezone } from 'date-vir';
 import { type HtmlInterpolation } from 'element-vir';
 import { type ViraIconSvg } from '../icons/icon-svg.js';
-import { type ViraSelectOption } from './vira-select-option.js';
+import { type ViraDropdownOption } from './vira-dropdown-option.js';
 /**
  * Form field types for {@link ViraFormField}.
  *
@@ -73,7 +73,7 @@ export type ViraFormField = ({
 }> & CommonViraFormFields) | ({
     type: ViraFormFieldType.Select;
     value: string | undefined;
-    options: ReadonlyArray<Readonly<ViraSelectOption>>;
+    options: ReadonlyArray<Readonly<ViraDropdownOption>>;
 } & PartialWithUndefined<{
     placeholder: string;
     icon: ViraIconSvg;

package/dist/util/vira-theme-client.d.ts

@@ -72,7 +72,7 @@ export declare class ViraThemeClient {
      * The currently selected theme. If you use multiple clients to set the same theme, this might
      * get out of sync.
      */
-    get currentTheme(): ViraThemeSelection;
+    getCurrentTheme(): ViraThemeSelection;
     /** Set the selected theme. */
     setSelectedTheme(selection: ViraThemeSelection): void;
     /** Cleanup internal state and listeners. */

package/dist/util/vira-theme-client.js

@@ -47,7 +47,7 @@ export class ViraThemeClient {
     /** A callback to remove the global theme preference listener. */
     removeThemePreferenceListener = listenTo(globalThis.matchMedia(darkSchemeMediaQuery), 'change', (event) => {
         assert.instanceOf(event, MediaQueryListEvent);
-        if (this.currentTheme === ViraThemeSelection.Auto) {
+        if (this.getCurrentTheme() === ViraThemeSelection.Auto) {
             void this.applyThemeCallback({
                 useDarkTheme: event.matches,
             });
@@ -60,13 +60,13 @@ export class ViraThemeClient {
         this.localStorageClient = new LocalStorageClient(themeStorageShapes, {
             storeName: params.storeName || 'vira-theme',
         });
-        this.applySelection(this.currentTheme);
+        this.applySelection(this.getCurrentTheme());
     }
     /**
      * The currently selected theme. If you use multiple clients to set the same theme, this might
      * get out of sync.
      */
-    get currentTheme() {
+    getCurrentTheme() {
         return this.localStorageClient.get.selectedTheme()?.theme || ViraThemeSelection.Auto;
     }
     /** Set the selected theme. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vira",
-    "version": "32.4.0",
+    "version": "33.1.0",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",
@@ -46,6 +46,7 @@
         "date-vir": "^9.1.1",
         "device-navigation": "^5.0.0",
         "json-schema-to-ts": "^3.1.1",
+        "lit": "^3.3.3",
         "lit-css-vars": "^3.6.3",
         "object-shape-tester": "^6.15.0",
         "observavir": "^2.3.3",