vira 27.0.0 → 28.0.0

package/dist/elements/pop-up/vira-pop-up-trigger.element.js

@@ -0,0 +1,282 @@
+import { assert } from '@augment-vir/assert';
+import { NavController } from 'device-navigation';
+import { classMap, css, defineElementEvent, html, listen, renderIf } from 'element-vir';
+import { createFocusStyles } from '../../styles/focus.js';
+import { noNativeFormStyles, noUserSelect, viraDisabledStyles } from '../../styles/index.js';
+import { HidePopUpEvent, NavSelectEvent, PopUpManager, } from '../../util/pop-up-manager.js';
+import { defineViraElement } from '../define-vira-element.js';
+import { triggerPopUpState } from './pop-up-helpers.js';
+/**
+ * Anchor options for pop-ups.
+ *
+ * @category Internal
+ */
+export var HorizontalAnchor;
+(function (HorizontalAnchor) {
+    /**
+     * The left side of the pop-up will be anchored to the left side of the trigger, allowing the
+     * pop-up to grow on the right side of the trigger.
+     */
+    HorizontalAnchor["Left"] = "left";
+    /**
+     * The Right side of the pop-up will be anchored to the right side of the trigger, allowing the
+     * pop-up to grow on the left side of the trigger.
+     */
+    HorizontalAnchor["Right"] = "right";
+    /**
+     * Restrict the pop-up on both sides.
+     *
+     * This is the default anchor for {@link ViraPopUpTrigger}.
+     */
+    HorizontalAnchor["Both"] = "both";
+})(HorizontalAnchor || (HorizontalAnchor = {}));
+/**
+ * An element with slots for a pop-up trigger and pop-up contents.
+ *
+ * @category PopUp
+ * @category Elements
+ * @see https://electrovir.github.io/vira/book/elements/vira-pop-up-trigger
+ */
+export const ViraPopUpTrigger = defineViraElement()({
+    tagName: 'vira-pop-up-trigger',
+    state({ host }) {
+        return {
+            /** `undefined` means the pop up is not currently showing. */
+            showPopUpResult: undefined,
+            popUpManager: new PopUpManager(new NavController(host, { activateOnMouseUp: true })),
+        };
+    },
+    slotNames: [
+        'trigger',
+        'popUp',
+    ],
+    hostClasses: {
+        'vira-pop-up-trigger-disabled': ({ inputs }) => !!inputs.isDisabled,
+    },
+    styles: ({ hostClasses }) => 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;
+
+            ${createFocusStyles({
+        elementBorderSize: 1,
+    })}
+        }
+
+        .dropdown-trigger {
+            box-sizing: border-box;
+            ${noUserSelect};
+        }
+
+        ${hostClasses['vira-pop-up-trigger-disabled'].selector} {
+            ${viraDisabledStyles}
+            pointer-events: auto;
+        }
+
+        ${hostClasses['vira-pop-up-trigger-disabled'].selector} .dropdown-wrapper {
+            pointer-events: none;
+        }
+
+        .pop-up-positioner {
+            position: absolute;
+            pointer-events: none;
+            display: flex;
+            box-sizing: border-box;
+            flex-direction: column;
+            align-items: flex-start;
+
+            /* highest possible z-index */
+            z-index: 2147483647;
+
+            & > * {
+                pointer-events: auto;
+                max-width: 100%;
+            }
+
+            &.right-aligned {
+                align-items: flex-end;
+            }
+        }
+
+        .open-upwards .pop-up-positioner {
+            flex-direction: column-reverse;
+        }
+    `,
+    events: {
+        navSelect: defineElementEvent(),
+        /**
+         * - `undefined` indicates that the pop-up just closed.
+         * - {@link ShowPopUpResult} indicates that the pop-up just opened.
+         */
+        openChange: defineElementEvent(),
+        init: defineElementEvent(),
+    },
+    cleanup({ state, updateState }) {
+        updateState({ showPopUpResult: undefined });
+        state.popUpManager.destroy();
+    },
+    init({ state, updateState, host, inputs, dispatch, events }) {
+        /** Refocus the trigger and set the result to `undefined` when the pop up closes. */
+        state.popUpManager.listen(HidePopUpEvent, () => {
+            updateState({ showPopUpResult: undefined });
+            dispatch(new events.openChange(undefined));
+            if (!inputs.isDisabled) {
+                const dropdownWrapper = host.shadowRoot.querySelector('.dropdown-wrapper');
+                assert.instanceOf(dropdownWrapper, HTMLButtonElement, 'failed to find dropdown wrapper child');
+                dropdownWrapper.focus();
+            }
+        });
+        state.popUpManager.listen(NavSelectEvent, (event) => {
+            if (!inputs.keepOpenAfterInteraction) {
+                triggerPopUpState({
+                    open: false,
+                    callback(showPopUpResult) {
+                        updateState({
+                            showPopUpResult,
+                        });
+                    },
+                    host,
+                    popUpManager: state.popUpManager,
+                });
+            }
+            dispatch(new events.navSelect(event.detail));
+        });
+        dispatch(new events.init({
+            navController: state.popUpManager.navController,
+            popUpManager: state.popUpManager,
+        }));
+    },
+    render({ dispatch, events, state, inputs, updateState, host, slotNames }) {
+        function triggerPopUp({ emitEvent, open }, event) {
+            if (state.showPopUpResult && inputs.keepOpenAfterInteraction && event) {
+                const dropdownTrigger = host.shadowRoot.querySelector('.dropdown-trigger');
+                if (dropdownTrigger && !event.composedPath().includes(dropdownTrigger)) {
+                    /**
+                     * Prevent closing the pop-up when `keepOpenAfterInteraction` is turned on and
+                     * the pop-up was interacted with.
+                     */
+                    return;
+                }
+            }
+            triggerPopUpState({
+                open,
+                callback(showPopUpResult) {
+                    updateState({ showPopUpResult });
+                    if (emitEvent) {
+                        dispatch(new events.openChange(showPopUpResult));
+                    }
+                },
+                host,
+                popUpManager: state.popUpManager,
+            });
+        }
+        if (inputs.isDisabled) {
+            triggerPopUp({ open: false, emitEvent: false }, undefined);
+        }
+        else if (inputs.z_debug_forceOpenState != undefined) {
+            if (!inputs.z_debug_forceOpenState && state.showPopUpResult) {
+                triggerPopUp({ emitEvent: false, open: false }, undefined);
+            }
+            else if (inputs.z_debug_forceOpenState && !state.showPopUpResult) {
+                triggerPopUp({ emitEvent: false, open: true }, undefined);
+            }
+        }
+        const leftCss = inputs.horizontalAnchor === HorizontalAnchor.Right && state.showPopUpResult
+            ? css `
+                      left: -${state.showPopUpResult.positions.diff.left}px;
+                  `
+            : css `
+                      left: ${inputs.popUpOffset?.left || 0}px;
+                  `;
+        const rightCss = state.showPopUpResult && inputs.horizontalAnchor === HorizontalAnchor.Left
+            ? css `
+                      right: -${state.showPopUpResult.positions.diff.right}px;
+                  `
+            : css `
+                      right: ${inputs.popUpOffset?.right || 0}px;
+                  `;
+        const horizontalPositionStyle = css `
+            ${leftCss}
+            ${rightCss}
+        `;
+        /**
+         * These styles do _not_ account for window resizing while the menu is open. I decided this
+         * was not a major enough problem to tackle. If it becomes major enough in the future,
+         * you'll need to hook into a window _or_ container resize listener inside `PopUpManager`
+         * and emit a new `ShowPopUpResult` instance when it changes.
+         */
+        const positionerStyles = state.showPopUpResult
+            ? state.showPopUpResult.popDown
+                ? /** Dropdown going down position. */
+                    css `
+                      bottom: -${state.showPopUpResult.positions.diff.bottom}px;
+                      top: calc(100% + ${inputs.popUpOffset?.vertical || 0}px);
+                      ${horizontalPositionStyle}
+                  `
+                : /** Dropdown going up position. */
+                    css `
+                      top: -${state.showPopUpResult.positions.diff.top}px;
+                      bottom: calc(100% + ${inputs.popUpOffset?.vertical || 0}px);
+                      ${horizontalPositionStyle}
+                  `
+            : undefined;
+        function respondToClick(event) {
+            triggerPopUp({ emitEvent: true, open: !state.showPopUpResult }, event);
+        }
+        return html `
+            <button
+                ?disabled=${!!inputs.isDisabled}
+                class="dropdown-wrapper ${classMap({
+            open: !!state.showPopUpResult,
+            'open-upwards': !state.showPopUpResult?.popDown,
+        })}"
+                role="listbox"
+                aria-expanded=${!!state.showPopUpResult}
+                ${listen('keydown', (event) => {
+            if (!state.showPopUpResult && event.code.startsWith('Arrow')) {
+                triggerPopUp({ emitEvent: true, open: true }, event);
+            }
+        })}
+                ${listen('click', (event) => {
+            /** Detail is 0 if it was a keyboard key (like Enter) that triggered this click. */
+            if (event.detail === 0) {
+                respondToClick(event);
+            }
+        })}
+                ${listen('mousedown', (event) => {
+            /** Ignore any clicks that aren't the main button. */
+            if (event.button === 0) {
+                respondToClick(event);
+            }
+        })}
+            >
+                <div class="dropdown-trigger">
+                    <slot name=${slotNames.trigger}></slot>
+                </div>
+
+                <div
+                    class="pop-up-positioner ${classMap({
+            'right-aligned': inputs.horizontalAnchor === HorizontalAnchor.Right,
+        })}"
+                    style=${positionerStyles}
+                >
+                    ${renderIf(!!state.showPopUpResult, html `
+                            <slot name=${slotNames.popUp}></slot>
+                        `)}
+                </div>
+            </button>
+        `;
+    },
+});

package/dist/elements/vira-dropdown.element.d.ts

@@ -1,7 +1,8 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
 import { type ViraIconSvg } from '../icons/icon-svg.js';
-import { type ShowPopoverResult } from '../util/popover-manager.js';
-import { type MenuItem } from './popover/popover-menu-item.js';
+import { type ShowPopUpResult } from '../util/pop-up-manager.js';
+import { type MenuItem } from './pop-up/pop-up-menu-item.js';
+import { HorizontalAnchor } from './pop-up/vira-pop-up-trigger.element.js';
 /**
  * Test ids for {@link ViraDropdown}.
  *
@@ -13,7 +14,7 @@ export declare const viraDropdownTestIds: {
     prefix: string;
 };
 /**
- * A dropdown element that uses popover menus.
+ * A dropdown element that uses pop-up menus.
  *
  * @category Dropdown
  * @category Elements
@@ -36,10 +37,21 @@ export declare const ViraDropdown: import("element-vir").DeclarativeElementDefin
     isDisabled: boolean;
     /** For debugging purposes only. Very bad for actual production code use. */
     z_debug_forceOpenState: boolean;
+    /**
+     * - `HorizontalAnchor.Left`: dropdown is anchored to the left side of the trigger and the
+     *   dropdown can grow to the right.
+     * - `HorizontalAnchor.Right`: dropdown is anchored to the right side of the trigger and the
+     *   dropdown can grow to the left.
+     * - `HorizontalAnchor.Both`: dropdown is anchored on both sides of the trigger and cannot
+     *   grow beyond it. (This is the default experience.)
+     *
+     * @default HorizontalAnchor.Both
+     */
+    horizontalAnchor: HorizontalAnchor;
 }>, {
-    /** `undefined` means the popover is not currently showing. */
-    showPopoverResult: ShowPopoverResult | undefined;
+    /** `undefined` means the pop up is not currently showing. */
+    showPopUpResult: ShowPopUpResult | undefined;
 }, {
     selectedChange: import("element-vir").DefineEvent<PropertyKey[]>;
-    openChange: import("element-vir").DefineEvent<ShowPopoverResult | undefined>;
+    openChange: import("element-vir").DefineEvent<ShowPopUpResult | undefined>;
 }, "vira-dropdown-", "vira-dropdown-", readonly [], readonly []>;

package/dist/elements/vira-dropdown.element.js

@@ -6,7 +6,8 @@ import { viraBorders } from '../styles/border.js';
 import { viraFormCssVars } from '../styles/form-styles.js';
 import { noUserSelect, viraAnimationDurations } from '../styles/index.js';
 import { defineViraElement } from './define-vira-element.js';
-import { ViraMenuTrigger } from './popover/vira-menu-trigger.element.js';
+import { ViraMenuTrigger } from './pop-up/vira-menu-trigger.element.js';
+import { HorizontalAnchor } from './pop-up/vira-pop-up-trigger.element.js';
 import { ViraIcon } from './vira-icon.element.js';
 /**
  * Test ids for {@link ViraDropdown}.
@@ -19,7 +20,7 @@ export const viraDropdownTestIds = {
     prefix: 'dropdown-prefix',
 };
 /**
- * A dropdown element that uses popover menus.
+ * A dropdown element that uses pop-up menus.
  *
  * @category Dropdown
  * @category Elements
@@ -101,8 +102,8 @@ export const ViraDropdown = defineViraElement()({
     },
     state() {
         return {
-            /** `undefined` means the popover is not currently showing. */
-            showPopoverResult: undefined,
+            /** `undefined` means the pop up is not currently showing. */
+            showPopUpResult: undefined,
         };
     },
     render({ state, inputs, dispatch, events, updateState }) {
@@ -136,13 +137,14 @@ export const ViraDropdown = defineViraElement()({
             isDisabled: inputs.isDisabled,
             isMultiSelect: inputs.isMultiSelect,
             z_debug_forceOpenState: inputs.z_debug_forceOpenState,
-            popoverOffset: {
+            popUpOffset: {
                 vertical: -1,
                 right: 24,
             },
+            horizontalAnchor: inputs.horizontalAnchor || HorizontalAnchor.Both,
         })}
                 ${listen(ViraMenuTrigger.events.openChange, (event) => {
-            updateState({ showPopoverResult: event.detail });
+            updateState({ showPopUpResult: event.detail });
             dispatch(new events.openChange(event.detail));
         })}
                 ${listen(ViraMenuTrigger.events.itemActivate, (event) => {
@@ -151,8 +153,8 @@ export const ViraDropdown = defineViraElement()({
             >
                 <div
                     class="dropdown-trigger ${classMap({
-            open: !!state.showPopoverResult,
-            'open-upwards': !state.showPopoverResult?.popDown,
+            open: !!state.showPopUpResult,
+            'open-upwards': !state.showPopUpResult?.popDown,
         })}"
                     ${testId(viraDropdownTestIds.trigger)}
                 >

package/dist/util/index.d.ts

@@ -1,2 +1,2 @@
 export * from './define-table.js';
-export * from './popover-manager.js';
+export * from './pop-up-manager.js';

package/dist/util/index.js

@@ -1,2 +1,2 @@
 export * from './define-table.js';
-export * from './popover-manager.js';
+export * from './pop-up-manager.js';

package/dist/util/{popover-manager.d.ts → pop-up-manager.d.ts}

@@ -12,17 +12,6 @@ export type PositionRect = {
     right: number;
     bottom: number;
 };
-/**
- * Used to represent the diff between the root element and the viewport.
- *
- * @category Internal
- */
-export type DiffRect = PositionRect & {
-    rootLeftToContainerRight: number;
-    rootRightToContainerLeft: number;
-    rootTopToContainerBottom: number;
-    rootBottomToContainerTop: number;
-};
 /**
  * The default empty {@link PositionRect}, with all values set to 0.
  *
@@ -30,15 +19,15 @@ export type DiffRect = PositionRect & {
  */
 export declare const emptyPositionRect: PositionRect;
 /**
- * Options for {@link PopoverManager}.
+ * Options for {@link PopUpManager}.
  *
- * @category Popover
+ * @category PopUp
  */
-export type PopoverManagerOptions = {
+export type PopUpManagerOptions = {
     /**
-     * The minimum number of pixels for allowing the popover to go downwards. If the downward
+     * The minimum number of pixels for allowing the pop-up to go downwards. If the downward
      * available space is less than this, and if the upwards available space is
-     * `verticalDiffThreshold` more than the downwards space, the popover will be directed upwards.
+     * `verticalDiffThreshold` more than the downwards space, the pop-up will be directed upwards.
      *
      * Equation:
      *
@@ -48,10 +37,10 @@ export type PopoverManagerOptions = {
      *
      * @default 200
      */
-    minDownwardsSpace: number;
+    minDownSpace: number;
     /**
      * The number of pixels required for the upwards available space to be bigger than the downwards
-     * available space before directing the popover upwards.
+     * available space before directing the pop-up upwards.
      *
      * Equation:
      *
@@ -63,50 +52,40 @@ export type PopoverManagerOptions = {
      */
     verticalDiffThreshold: number;
     /**
-     * Supports navigation of the popover via the `device-navigation` package.
+     * Supports navigation of the pop up via the `device-navigation` package.
      *
      * @default true
      */
     supportNavigation: boolean;
 };
 /**
- * Output type from `PopoverManager.showPopover`
+ * Output type from `PopUpManager.showPopUp`
  *
- * @category Popover
+ * @category PopUp
  */
-export type ShowPopoverResult = {
+export type ShowPopUpResult = {
     /**
-     * Indicates if the popover should pop in the downwards direction or not. If not, it should pop
-     * in the upwards direction. This is determined by how much space is available on either
-     * vertical side of the root element.
+     * Indicates if the "pop up" should pop in the downwards direction or not. If not, it should pop
+     * in the upwards direction. This is determined by how much space is available on either side of
+     * the root element.
      */
     popDown: boolean;
-    /**
-     * Indicates if the popover should pop in the rightwards direction or not. If not, it should pop
-     * in the leftwards position. This is determined by how much space is available on either
-     * horizontal side of the root element.
-     */
-    popRight: boolean;
-    positions: {
-        root: PositionRect;
-        container: PositionRect;
-        diff: DiffRect;
-    };
+    positions: Record<'root' | 'container' | 'diff', PositionRect>;
 };
-declare const HidePopoverEvent_base: (new (eventInitDict?: EventInit) => import("typed-event-target").TypedEvent<"hide-popover">) & Pick<{
+declare const HidePopUpEvent_base: (new (eventInitDict?: EventInit) => import("typed-event-target").TypedEvent<"hide-pop-up">) & Pick<{
     new (type: string, eventInitDict?: EventInit): Event;
     prototype: Event;
     readonly NONE: 0;
     readonly CAPTURING_PHASE: 1;
     readonly AT_TARGET: 2;
     readonly BUBBLING_PHASE: 3;
-}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedEvent<"hide-popover">, "type">;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedEvent<"hide-pop-up">, "type">;
 /**
- * An event fired from {@link PopoverManager} when the popover should be hidden.
+ * An event fired from {@link PopUpManager} when the pop up should be hidden.
  *
- * @category Popover
+ * @category PopUp
  */
-export declare class HidePopoverEvent extends HidePopoverEvent_base {
+export declare class HidePopUpEvent extends HidePopUpEvent_base {
 }
 declare const NavSelectEvent_base: (new (eventInitDict: {
     bubbles?: boolean;
@@ -122,44 +101,44 @@ declare const NavSelectEvent_base: (new (eventInitDict: {
     readonly BUBBLING_PHASE: 3;
 }, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<Coords, "nav-select">, "type">;
 /**
- * An event fired from {@link PopoverManager} when an individual item in the popover has been
- * selected by the user.
+ * An event fired from {@link PopUpManager} when an individual item in the pop up has been selected
+ * by the user.
  *
- * @category Popover
+ * @category PopUp
  */
 export declare class NavSelectEvent extends NavSelectEvent_base {
 }
 /**
- * All events that can be emitted by {@link PopoverManager}.
+ * All events that can be emitted by {@link PopUpManager}.
  *
  * @category Internal
  */
-export type PopoverManagerEvents = HidePopoverEvent | NavSelectEvent;
+export type PopUpManagerEvents = HidePopUpEvent | NavSelectEvent;
 /**
- * A "popover" manager for items that popover from the HTML page, like dropdowns or menus.
+ * A "pop up" manager for items that pop up from the HTML page, like dropdowns or menus.
  *
- * @category Popover
+ * @category PopUp
  */
-export declare class PopoverManager {
+export declare class PopUpManager {
     readonly navController: NavController;
     private listenTarget;
-    options: PopoverManagerOptions;
+    options: PopUpManagerOptions;
     private cleanupCallbacks;
     private lastRootElement;
-    constructor(navController: NavController, options?: Partial<PopoverManagerOptions> | undefined);
+    constructor(navController: NavController, options?: Partial<PopUpManagerOptions> | undefined);
     private attachGlobalListeners;
-    /** Listen to events emitted from a {@link PopoverManager} instance. */
+    /** Listen to events emitted from a {@link PopUpManager} instance. */
     listen<const EventDefinition extends Readonly<{
-        type: ExtractEventTypes<PopoverManagerEvents>;
-    }>>(event: EventDefinition, listener: (event: ExtractEventByType<PopoverManagerEvents, EventDefinition['type']>) => MaybePromise<void>, options?: ListenOptions | undefined): RemoveListenerCallback;
-    /** Trigger removal or hiding of the popover. */
-    removePopover(): void;
-    /** Trigger showing the popover. */
-    showPopover(rootElement: HTMLElement, options?: Partial<PopoverManagerOptions> | undefined): ShowPopoverResult;
+        type: ExtractEventTypes<PopUpManagerEvents>;
+    }>>(event: EventDefinition, listener: (event: ExtractEventByType<PopUpManagerEvents, EventDefinition['type']>) => MaybePromise<void>, options?: ListenOptions | undefined): RemoveListenerCallback;
+    /** Trigger removal or hiding of the pop up. */
+    removePopUp(): void;
+    /** Trigger showing the pop up. */
+    showPopUp(rootElement: HTMLElement, options?: Partial<PopUpManagerOptions> | undefined): ShowPopUpResult;
     /**
-     * Cleanup and destroy the {@link PopoverManager} instance. This:
+     * Cleanup and destroy the {@link PopUpManager} instance. This:
      *
-     * - Removes the existing popover
+     * - Removes the existing pop up
      * - Cleans up all internal and external listeners
      */
     destroy(): void;