vira 32.3.0 → 33.0.0

package/dist/util/popover-manager.js

@@ -0,0 +1,412 @@
+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,
+                        });
+                    }
+                    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}.
  *
@@ -29,7 +29,7 @@ export declare enum ViraFormFieldType {
  * @category Internal
  */
 export type CommonViraFormFields = {
-    label: string;
+    label: string | HtmlInterpolation;
 } & PartialWithUndefined<{
     /** Applies a test id to the form field element. */
     testId: string;
@@ -73,24 +73,19 @@ export type ViraFormField = ({
 }> & CommonViraFormFields) | ({
     type: ViraFormFieldType.Select;
     value: string | undefined;
-    options: ReadonlyArray<Readonly<ViraSelectOption>>;
+    options: ReadonlyArray<Readonly<ViraDropdownOption>>;
 } & PartialWithUndefined<{
     placeholder: string;
     icon: ViraIconSvg;
 }> & CommonViraFormFields) | ({
     type: ViraFormFieldType.Checkbox;
     value: boolean | undefined;
-    /**
-     * Label for the checkbox. Unlike other field types, this accepts arbitrary HTML so the
-     * checkbox's label slot can be filled with rich content.
-     */
-    label: HtmlInterpolation;
 } & PartialWithUndefined<{
     /** The checkbox will be filled with a form selection color when it is checked. */
     fillWhenChecked: boolean;
     /** The checkbox will be filled with a form error color when it is unchecked. */
     fillWhenUnchecked: boolean;
-}> & Omit<CommonViraFormFields, 'label'>) | ({
+}> & CommonViraFormFields) | ({
     type: ViraFormFieldType.Number;
     value: number | undefined;
 } & PartialWithUndefined<{
@@ -132,7 +127,7 @@ export type ViraFormFields = Record<string, ViraFormField>;
  *
  * @category Internal
  */
-export declare function applyRequiredLabel(label: string | undefined, isRequired: boolean): string | undefined;
+export declare function applyRequiredLabel(label: string | HtmlInterpolation | undefined, isRequired: boolean): string | HtmlInterpolation | undefined;
 /**
  * Checks if all the {@link ViraFormField} entries in a given {@link ViraFormFields} are valid through
  * the following checks:

package/dist/util/vira-form-fields.js

@@ -1,5 +1,6 @@
 import { check } from '@augment-vir/assert';
 import { addSuffix, getObjectTypedValues } from '@augment-vir/common';
+import { html } from 'element-vir';
 /**
  * Form field types for {@link ViraFormField}.
  *
@@ -27,19 +28,22 @@ export var ViraFormFieldType;
  * @category Internal
  */
 export function applyRequiredLabel(label, isRequired) {
-    if (label) {
-        if (isRequired) {
-            return addSuffix({
-                value: label,
-                suffix: '*',
-            });
-        }
-        else {
-            return label;
-        }
+    if (!label) {
+        return undefined;
+    }
+    else if (!isRequired) {
+        return label;
+    }
+    else if (check.isString(label)) {
+        return addSuffix({
+            value: label,
+            suffix: '*',
+        });
     }
     else {
-        return undefined;
+        return html `
+            ${label}*
+        `;
     }
 }
 /**

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.3.0",
+    "version": "33.0.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",

package/dist/elements/pop-up/vira-menu-trigger.element.d.ts

@@ -1,45 +0,0 @@
-import { type PartialWithUndefined } from '@augment-vir/common';
-import { type NavController } from 'device-navigation';
-import { type PopUpManager, type ShowPopUpResult } from '../../util/pop-up-manager.js';
-import { type ViraMenuCornerStyle } from './vira-menu.element.js';
-import { type PopUpOffset, type PopUpTriggerPosition } from './vira-pop-up-trigger.element.js';
-/**
- * Test ids for {@link ViraMenuTrigger}.
- *
- * @category Internal
- */
-export declare const viraMenuTriggerTestIds: {
-    menu: string;
-};
-/**
- * A more specific wrapper of `ViraPopUpTrigger` that always opens a menu.
- *
- * @category PopUp
- * @category Elements
- */
-export declare const ViraMenuTrigger: import("element-vir").DeclarativeElementDefinition<`vira-${string}`, PartialWithUndefined<{
-    isDisabled: boolean;
-    z_debug_forceOpenState: boolean;
-    popUpOffset: PopUpOffset;
-    keepOpenAfterInteraction: boolean;
-    menuCornerStyle: ViraMenuCornerStyle;
-    /**
-     * If true, the focus outline is moved inside the element.
-     *
-     * @default false
-     */
-    useInsideFocus: boolean;
-    /**
-     * When `true`, the trigger will focus itself when the pop-up closes.
-     *
-     * @default false
-     */
-    focusOnClose: boolean;
-} & PopUpTriggerPosition>, {
-    navController: undefined | NavController;
-    popUpManager: undefined | PopUpManager;
-    /** `undefined` means the pop up is not currently showing. */
-    showPopUpResult: ShowPopUpResult | undefined;
-}, {
-    openChange: import("element-vir").DefineElementEvent<ShowPopUpResult | undefined>;
-}, `vira-${string}-`, `vira-${string}-`, readonly ["vira-menu-trigger-trigger"], readonly []>;

package/dist/elements/pop-up/vira-menu.element.d.ts

@@ -1,36 +0,0 @@
-import { type PartialWithUndefined } from '@augment-vir/common';
-/**
- * Possible corner styles for {@link ViraMenu}.
- *
- * @category Internal
- */
-export declare enum ViraMenuCornerStyle {
-    /** Rounding of corners depends on the open direction of the menu. */
-    Directional = "directional",
-    /** All of the menus corners should be rounded. */
-    AllRounded = "all-rounded",
-    /** None of the menus corners should be rounded. */
-    AllSquare = "all-square"
-}
-/**
- * Menu pop-up directions available for {@link ViraMenu}.
- *
- * @category Internal
- */
-export declare enum ViraMenuPopUpDirection {
-    Downwards = "downwards",
-    Upwards = "upwards"
-}
-/**
- * A simple default style wrapper for pop-up menus. Consider using `renderMenuItemEntries` to help
- * rendering many menu items.
- *
- * @category PopUp
- * @category Elements
- */
-export declare const ViraMenu: import("element-vir").DeclarativeElementDefinition<"vira-menu", PartialWithUndefined<{
-    /** @default PopUpMenuDirection.Downwards */
-    direction: ViraMenuPopUpDirection;
-    /** @default PopUpMenuCornerStyle.Directional */
-    cornerStyle: ViraMenuCornerStyle;
-}>, {}, {}, "vira-menu-open-upwards" | "vira-menu-rounded" | "vira-menu-square", "vira-menu-", readonly [], readonly []>;