vira 27.0.0 → 28.1.0

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;

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

@@ -1,4 +1,6 @@
+import { assert } from '@augment-vir/assert';
 import { mapObjectValues } from '@augment-vir/common';
+import { findOverflowAncestor } from '@augment-vir/web';
 import { NavActivateEvent, NavDirection } from 'device-navigation';
 import { listenToPageActivation } from 'page-active';
 import { ListenTarget, defineTypedCustomEvent, defineTypedEvent, listenToGlobal, } from 'typed-event-target';
@@ -14,30 +16,30 @@ export const emptyPositionRect = {
     bottom: 0,
 };
 /**
- * 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 class HidePopoverEvent extends defineTypedEvent('hide-popover') {
+export class HidePopUpEvent extends defineTypedEvent('hide-pop-up') {
 }
 /**
- * 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 class NavSelectEvent extends defineTypedCustomEvent()('nav-select') {
 }
 /**
- * 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 class PopoverManager {
+export class PopUpManager {
     navController;
     listenTarget = new ListenTarget();
     options = {
-        minDownwardsSpace: 200,
+        minDownSpace: 200,
         verticalDiffThreshold: 20,
         supportNavigation: true,
     };
@@ -51,7 +53,7 @@ export class PopoverManager {
         let firstFired = false;
         const resizeObserver = new ResizeObserver(() => {
             if (firstFired) {
-                this.removePopover();
+                this.removePopUp();
             }
             else {
                 firstFired = true;
@@ -64,7 +66,7 @@ export class PopoverManager {
             },
             listenToPageActivation(false, (isPageActive) => {
                 if (!isPageActive) {
-                    this.removePopover();
+                    this.removePopUp();
                 }
             }),
             this.navController.listen(NavActivateEvent, (event) => {
@@ -78,15 +80,15 @@ export class PopoverManager {
             listenToGlobal('mousedown', (event) => {
                 if (this.lastRootElement &&
                     event.composedPath().includes(this.lastRootElement)) {
-                    /** Ignore clicks that came from the popover host itself. */
+                    /** Ignore clicks that came from the pop up host itself. */
                     return;
                 }
-                this.removePopover();
+                this.removePopUp();
             }, { passive: true }),
             listenToGlobal('keydown', (event) => {
                 const keyCode = event.code;
                 if (keyCode === 'Escape') {
-                    this.removePopover();
+                    this.removePopUp();
                 }
                 else if (this.options.supportNavigation) {
                     if (keyCode === 'ArrowDown') {
@@ -130,50 +132,51 @@ export class PopoverManager {
             }),
         ];
     }
-    /** Listen to events emitted from a {@link PopoverManager} instance. */
+    /** Listen to events emitted from a {@link PopUpManager} instance. */
     listen(event, listener, options) {
         return this.listenTarget.listen(event, listener, options);
     }
-    /** Trigger removal or hiding of the popover. */
-    removePopover() {
+    /** Trigger removal or hiding of the pop up. */
+    removePopUp() {
         this.cleanupCallbacks.forEach((callback) => callback());
-        this.listenTarget.dispatch(new HidePopoverEvent());
+        this.listenTarget.dispatch(new HidePopUpEvent());
     }
-    /** Trigger showing the popover. */
-    showPopover(rootElement, options) {
+    /** Trigger showing the pop up. */
+    showPopUp(rootElement, options) {
         this.lastRootElement = rootElement;
         const currentOptions = { ...this.options, ...options };
-        const container = window.document.body;
+        const container = findOverflowAncestor(rootElement);
+        assert.instanceOf(container, HTMLElement);
         const rootRect = rootElement.getBoundingClientRect();
         const containerRect = container.getBoundingClientRect();
-        const containerPosition = {
-            top: 0,
-            left: 0,
-            right: containerRect.width,
-            bottom: containerRect.height,
-        };
+        const containerScrollbarWidth = container.offsetWidth - container.clientWidth;
+        const containerScrollbarHeight = container.offsetHeight - container.clientHeight;
+        const containerPosition = container === document.body
+            ? {
+                top: 0,
+                left: 0,
+                right: containerRect.width,
+                bottom: containerRect.height,
+            }
+            : {
+                top: containerRect.top,
+                left: containerRect.left,
+                right: containerRect.right - containerScrollbarWidth,
+                bottom: containerRect.bottom - containerScrollbarHeight,
+            };
         const rootPosition = mapObjectValues(emptyPositionRect, (key) => {
             return rootRect[key];
         });
-        const diffPositions = mapObjectValues(emptyPositionRect, (key) => {
+        const diff = mapObjectValues(emptyPositionRect, (key) => {
             const containerDimension = containerPosition[key];
             const hostDimension = rootPosition[key];
             return Math.abs(containerDimension - hostDimension);
         });
-        const diff = {
-            ...diffPositions,
-            rootLeftToContainerRight: containerPosition.right - diffPositions.left,
-            rootRightToContainerLeft: containerPosition.right - diffPositions.right,
-            rootTopToContainerBottom: containerPosition.bottom - diffPositions.top,
-            rootBottomToContainerTop: containerPosition.bottom - diffPositions.bottom,
-        };
         const useUp = diff.top > diff.bottom + currentOptions.verticalDiffThreshold &&
-            diff.bottom < currentOptions.minDownwardsSpace;
+            diff.bottom < currentOptions.minDownSpace;
         this.attachGlobalListeners(container);
-        const useLeft = diff.rootLeftToContainerRight + 100 < diff.rootRightToContainerLeft;
         return {
             popDown: !useUp,
-            popRight: !useLeft,
             positions: {
                 container: containerPosition,
                 root: rootPosition,
@@ -182,13 +185,13 @@ export class PopoverManager {
         };
     }
     /**
-     * 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() {
-        this.removePopover();
+        this.removePopUp();
         this.listenTarget.destroy();
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vira",
-    "version": "27.0.0",
+    "version": "28.1.0",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",
@@ -38,9 +38,9 @@
         "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.41.0",
-        "@augment-vir/common": "^31.41.0",
-        "@augment-vir/web": "^31.41.0",
+        "@augment-vir/assert": "^31.45.0",
+        "@augment-vir/common": "^31.45.0",
+        "@augment-vir/web": "^31.45.0",
         "colorjs.io": "^0.5.2",
         "date-vir": "^8.0.0",
         "device-navigation": "^4.5.5",
@@ -52,18 +52,18 @@
         "typed-event-target": "^4.1.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.41.0",
+        "@augment-vir/test": "^31.45.0",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.1",
         "@web/test-runner-visual-regression": "^0.10.0",
-        "esbuild": "^0.25.10",
+        "esbuild": "^0.25.11",
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
         "typedoc": "^0.28.14",
         "typescript": "5.9.3",
-        "vite": "^7.1.10",
+        "vite": "^7.1.12",
         "vite-tsconfig-paths": "^5.1.4"
     },
     "peerDependencies": {

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

@@ -1,41 +0,0 @@
-import { type PartialWithUndefined } from '@augment-vir/common';
-import { type NavController } from 'device-navigation';
-import { type PopoverManager, type ShowPopoverResult } from '../../util/popover-manager.js';
-import { type MenuItem } from './popover-menu-item.js';
-import { type PopoverMenuCornerStyle } from './vira-popover-menu.element.js';
-import { type PopoverOffset } from './vira-popover-trigger.element.js';
-/**
- * Test ids for {@link ViraMenuTrigger}.
- *
- * @category Internal
- */
-export declare const viraMenuTriggerTestIds: {
-    menu: string;
-};
-/**
- * A more specific wrapper of `ViraPopoverTrigger` that always opens a menu.
- *
- * @category Popover
- * @category Elements
- */
-export declare const ViraMenuTrigger: import("element-vir").DeclarativeElementDefinition<"vira-menu-trigger", {
-    items: ReadonlyArray<Readonly<MenuItem>>;
-} & PartialWithUndefined<{
-    /** The selected item ids from the given `items` object. */
-    selected: ReadonlyArray<PropertyKey>;
-    isDisabled: boolean;
-    isMultiSelect: boolean;
-    z_debug_forceOpenState: boolean;
-    popoverOffset: PopoverOffset;
-    /** Hide menu item check mark icons. */
-    hideCheckIcons: boolean;
-    menuCornerStyle: PopoverMenuCornerStyle;
-}>, {
-    navController: undefined | NavController;
-    popoverManager: undefined | PopoverManager;
-    /** `undefined` means the popover is not currently showing. */
-    showPopoverResult: ShowPopoverResult | undefined;
-}, {
-    itemActivate: import("element-vir").DefineEvent<PropertyKey[]>;
-    openChange: import("element-vir").DefineEvent<ShowPopoverResult | undefined>;
-}, "vira-menu-trigger-", "vira-menu-trigger-", readonly [], readonly []>;

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

@@ -1,35 +0,0 @@
-import { type PartialWithUndefined } from '@augment-vir/common';
-/**
- * Possible corner styles for {@link ViraPopoverMenu}.
- *
- * @category Internal
- */
-export declare enum PopoverMenuCornerStyle {
-    /** 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 popover directions available for {@link ViraPopoverMenu}.
- *
- * @category Internal
- */
-export declare enum PopoverMenuDirection {
-    Downwards = "downwards",
-    Upwards = "upwards"
-}
-/**
- * A simple default style wrapper for popover menus.
- *
- * @category Popover
- * @category Elements
- */
-export declare const ViraPopoverMenu: import("element-vir").DeclarativeElementDefinition<"vira-popover-menu", PartialWithUndefined<{
-    /** @default PopoverMenuDirection.Downwards */
-    direction: PopoverMenuDirection;
-    /** @default PopoverMenuCornerStyle.Directional */
-    cornerStyle: PopoverMenuCornerStyle;
-}>, {}, {}, "vira-popover-menu-open-upwards" | "vira-popover-menu-rounded" | "vira-popover-menu-square", "vira-popover-menu-", readonly [], readonly []>;

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

@@ -1,67 +0,0 @@
-import { type PartialWithUndefined } from '@augment-vir/common';
-import { NavController, type Coords } from 'device-navigation';
-import { PopoverManager, type ShowPopoverResult } from '../../util/popover-manager.js';
-/**
- * Offsets applied to any menu opened by {@link ViraPopoverTrigger}.
- *
- * @category Internal
- */
-export type PopoverOffset = PartialWithUndefined<{
-    vertical: number;
-    right: number;
-    left: number;
-}>;
-/**
- * Anchor options for popovers.
- *
- * @category Internal
- */
-export declare enum HorizontalAnchor {
-    /**
-     * The left side of the popover will be anchored to the left side of the trigger, allowing the
-     * popover to grow on the right side of the trigger.
-     */
-    Left = "left",
-    /**
-     * The Right side of the popover will be anchored to the right side of the trigger, allowing the
-     * popover to grow on the left side of the trigger.
-     */
-    Right = "right",
-    /**
-     * Restrict the popover on both sides.
-     *
-     * This is the default anchor for {@link ViraPopoverTrigger}.
-     */
-    Both = "both"
-}
-/**
- * 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-popover-trigger", PartialWithUndefined<{
-    isDisabled: boolean;
-    /** For debugging purposes only. Very bad for actual production code use. */
-    z_debug_forceOpenState: boolean;
-    /** Set to `true` to keep the popover open if it is interacted with. */
-    keepOpenAfterInteraction: boolean;
-    /** All values in px. */
-    popoverOffset?: PopoverOffset;
-}>, {
-    /** `undefined` means the popover is not currently showing. */
-    showPopoverResult: ShowPopoverResult | undefined;
-    popoverManager: PopoverManager;
-}, {
-    navSelect: import("element-vir").DefineEvent<Coords>;
-    /**
-     * - `undefined` indicates that the popover just closed.
-     * - {@link ShowPopoverResult} indicates that the popover just opened.
-     */
-    openChange: import("element-vir").DefineEvent<ShowPopoverResult | undefined>;
-    init: import("element-vir").DefineEvent<{
-        navController: NavController;
-        popoverManager: PopoverManager;
-    }>;
-}, "vira-popover-trigger-disabled", "vira-popover-trigger-", readonly ["trigger", "popover"], readonly []>;