vira 26.13.1 → 27.0.0

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

@@ -12,6 +12,17 @@ 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.
  *
@@ -19,15 +30,15 @@ export type PositionRect = {
  */
 export declare const emptyPositionRect: PositionRect;
 /**
- * Options for {@link PopUpManager}.
+ * Options for {@link PopoverManager}.
  *
- * @category PopUp
+ * @category Popover
  */
-export type PopUpManagerOptions = {
+export type PopoverManagerOptions = {
     /**
-     * The minimum number of pixels for allowing the pop-up to go downwards. If the downward
+     * The minimum number of pixels for allowing the popover 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 pop-up will be directed upwards.
+     * `verticalDiffThreshold` more than the downwards space, the popover will be directed upwards.
      *
      * Equation:
      *
@@ -37,10 +48,10 @@ export type PopUpManagerOptions = {
      *
      * @default 200
      */
-    minDownSpace: number;
+    minDownwardsSpace: number;
     /**
      * The number of pixels required for the upwards available space to be bigger than the downwards
-     * available space before directing the pop-up upwards.
+     * available space before directing the popover upwards.
      *
      * Equation:
      *
@@ -52,40 +63,50 @@ export type PopUpManagerOptions = {
      */
     verticalDiffThreshold: number;
     /**
-     * Supports navigation of the pop up via the `device-navigation` package.
+     * Supports navigation of the popover via the `device-navigation` package.
      *
      * @default true
      */
     supportNavigation: boolean;
 };
 /**
- * Output type from `PopUpManager.showPopUp`
+ * Output type from `PopoverManager.showPopover`
  *
- * @category PopUp
+ * @category Popover
  */
-export type ShowPopUpResult = {
+export type ShowPopoverResult = {
     /**
-     * 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.
+     * 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.
      */
     popDown: boolean;
-    positions: Record<'root' | 'container' | 'diff', PositionRect>;
+    /**
+     * 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;
+    };
 };
-declare const HidePopUpEvent_base: (new (eventInitDict?: EventInit) => import("typed-event-target").TypedEvent<"hide-pop-up">) & Pick<{
+declare const HidePopoverEvent_base: (new (eventInitDict?: EventInit) => import("typed-event-target").TypedEvent<"hide-popover">) & 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-pop-up">, "type">;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedEvent<"hide-popover">, "type">;
 /**
- * An event fired from {@link PopUpManager} when the pop up should be hidden.
+ * An event fired from {@link PopoverManager} when the popover should be hidden.
  *
- * @category PopUp
+ * @category Popover
  */
-export declare class HidePopUpEvent extends HidePopUpEvent_base {
+export declare class HidePopoverEvent extends HidePopoverEvent_base {
 }
 declare const NavSelectEvent_base: (new (eventInitDict: {
     bubbles?: boolean;
@@ -101,44 +122,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 PopUpManager} when an individual item in the pop up has been selected
- * by the user.
+ * An event fired from {@link PopoverManager} when an individual item in the popover has been
+ * selected by the user.
  *
- * @category PopUp
+ * @category Popover
  */
 export declare class NavSelectEvent extends NavSelectEvent_base {
 }
 /**
- * All events that can be emitted by {@link PopUpManager}.
+ * All events that can be emitted by {@link PopoverManager}.
  *
  * @category Internal
  */
-export type PopUpManagerEvents = HidePopUpEvent | NavSelectEvent;
+export type PopoverManagerEvents = HidePopoverEvent | NavSelectEvent;
 /**
- * A "pop up" manager for items that pop up from the HTML page, like dropdowns or menus.
+ * A "popover" manager for items that popover from the HTML page, like dropdowns or menus.
  *
- * @category PopUp
+ * @category Popover
  */
-export declare class PopUpManager {
+export declare class PopoverManager {
     readonly navController: NavController;
     private listenTarget;
-    options: PopUpManagerOptions;
+    options: PopoverManagerOptions;
     private cleanupCallbacks;
     private lastRootElement;
-    constructor(navController: NavController, options?: Partial<PopUpManagerOptions> | undefined);
+    constructor(navController: NavController, options?: Partial<PopoverManagerOptions> | undefined);
     private attachGlobalListeners;
-    /** Listen to events emitted from a {@link PopUpManager} instance. */
+    /** Listen to events emitted from a {@link PopoverManager} instance. */
     listen<const EventDefinition extends Readonly<{
-        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;
+        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;
     /**
-     * Cleanup and destroy the {@link PopUpManager} instance. This:
+     * Cleanup and destroy the {@link PopoverManager} instance. This:
      *
-     * - Removes the existing pop up
+     * - Removes the existing popover
      * - Cleans up all internal and external listeners
      */
     destroy(): void;

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

@@ -1,6 +1,4 @@
-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';
@@ -16,30 +14,30 @@ export const emptyPositionRect = {
     bottom: 0,
 };
 /**
- * An event fired from {@link PopUpManager} when the pop up should be hidden.
+ * An event fired from {@link PopoverManager} when the popover should be hidden.
  *
- * @category PopUp
+ * @category Popover
  */
-export class HidePopUpEvent extends defineTypedEvent('hide-pop-up') {
+export class HidePopoverEvent extends defineTypedEvent('hide-popover') {
 }
 /**
- * An event fired from {@link PopUpManager} when an individual item in the pop up has been selected
- * by the user.
+ * An event fired from {@link PopoverManager} when an individual item in the popover has been
+ * selected by the user.
  *
- * @category PopUp
+ * @category Popover
  */
 export class NavSelectEvent extends defineTypedCustomEvent()('nav-select') {
 }
 /**
- * A "pop up" manager for items that pop up from the HTML page, like dropdowns or menus.
+ * A "popover" manager for items that popover from the HTML page, like dropdowns or menus.
  *
- * @category PopUp
+ * @category Popover
  */
-export class PopUpManager {
+export class PopoverManager {
     navController;
     listenTarget = new ListenTarget();
     options = {
-        minDownSpace: 200,
+        minDownwardsSpace: 200,
         verticalDiffThreshold: 20,
         supportNavigation: true,
     };
@@ -53,7 +51,7 @@ export class PopUpManager {
         let firstFired = false;
         const resizeObserver = new ResizeObserver(() => {
             if (firstFired) {
-                this.removePopUp();
+                this.removePopover();
             }
             else {
                 firstFired = true;
@@ -66,7 +64,7 @@ export class PopUpManager {
             },
             listenToPageActivation(false, (isPageActive) => {
                 if (!isPageActive) {
-                    this.removePopUp();
+                    this.removePopover();
                 }
             }),
             this.navController.listen(NavActivateEvent, (event) => {
@@ -80,15 +78,15 @@ export class PopUpManager {
             listenToGlobal('mousedown', (event) => {
                 if (this.lastRootElement &&
                     event.composedPath().includes(this.lastRootElement)) {
-                    /** Ignore clicks that came from the pop up host itself. */
+                    /** Ignore clicks that came from the popover host itself. */
                     return;
                 }
-                this.removePopUp();
+                this.removePopover();
             }, { passive: true }),
             listenToGlobal('keydown', (event) => {
                 const keyCode = event.code;
                 if (keyCode === 'Escape') {
-                    this.removePopUp();
+                    this.removePopover();
                 }
                 else if (this.options.supportNavigation) {
                     if (keyCode === 'ArrowDown') {
@@ -132,51 +130,50 @@ export class PopUpManager {
             }),
         ];
     }
-    /** Listen to events emitted from a {@link PopUpManager} instance. */
+    /** Listen to events emitted from a {@link PopoverManager} instance. */
     listen(event, listener, options) {
         return this.listenTarget.listen(event, listener, options);
     }
-    /** Trigger removal or hiding of the pop up. */
-    removePopUp() {
+    /** Trigger removal or hiding of the popover. */
+    removePopover() {
         this.cleanupCallbacks.forEach((callback) => callback());
-        this.listenTarget.dispatch(new HidePopUpEvent());
+        this.listenTarget.dispatch(new HidePopoverEvent());
     }
-    /** Trigger showing the pop up. */
-    showPopUp(rootElement, options) {
+    /** Trigger showing the popover. */
+    showPopover(rootElement, options) {
         this.lastRootElement = rootElement;
         const currentOptions = { ...this.options, ...options };
-        const container = findOverflowAncestor(rootElement);
-        assert.instanceOf(container, HTMLElement);
+        const container = window.document.body;
         const rootRect = rootElement.getBoundingClientRect();
         const containerRect = container.getBoundingClientRect();
-        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 containerPosition = {
+            top: 0,
+            left: 0,
+            right: containerRect.width,
+            bottom: containerRect.height,
+        };
         const rootPosition = mapObjectValues(emptyPositionRect, (key) => {
             return rootRect[key];
         });
-        const diff = mapObjectValues(emptyPositionRect, (key) => {
+        const diffPositions = 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.minDownSpace;
+            diff.bottom < currentOptions.minDownwardsSpace;
         this.attachGlobalListeners(container);
+        const useLeft = diff.rootLeftToContainerRight + 100 < diff.rootRightToContainerLeft;
         return {
             popDown: !useUp,
+            popRight: !useLeft,
             positions: {
                 container: containerPosition,
                 root: rootPosition,
@@ -185,13 +182,13 @@ export class PopUpManager {
         };
     }
     /**
-     * Cleanup and destroy the {@link PopUpManager} instance. This:
+     * Cleanup and destroy the {@link PopoverManager} instance. This:
      *
-     * - Removes the existing pop up
+     * - Removes the existing popover
      * - Cleans up all internal and external listeners
      */
     destroy() {
-        this.removePopUp();
+        this.removePopover();
         this.listenTarget.destroy();
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vira",
-    "version": "26.13.1",
+    "version": "27.0.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.40.0",
-        "@augment-vir/common": "^31.40.0",
-        "@augment-vir/web": "^31.40.0",
+        "@augment-vir/assert": "^31.41.0",
+        "@augment-vir/common": "^31.41.0",
+        "@augment-vir/web": "^31.41.0",
         "colorjs.io": "^0.5.2",
         "date-vir": "^8.0.0",
         "device-navigation": "^4.5.5",
@@ -52,7 +52,7 @@
         "typed-event-target": "^4.1.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.40.0",
+        "@augment-vir/test": "^31.41.0",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",
@@ -63,7 +63,7 @@
         "markdown-code-example-inserter": "^3.0.3",
         "typedoc": "^0.28.14",
         "typescript": "5.9.3",
-        "vite": "^7.1.9",
+        "vite": "^7.1.10",
         "vite-tsconfig-paths": "^5.1.4"
     },
     "peerDependencies": {

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

@@ -1,55 +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 MenuItem } from './pop-up-menu-item.js';
-import { type PopUpMenuCornerStyle } from './vira-pop-up-menu.element.js';
-import { HorizontalAnchor, type PopUpOffset } 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-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;
-    popUpOffset: PopUpOffset;
-    /** Hide menu item check mark icons. */
-    hideCheckIcons: boolean;
-    menuCornerStyle: PopUpMenuCornerStyle;
-    /**
-     * - `HorizontalAnchor.Left`: pop-up is anchored to the left side of the trigger and the
-     *   pop-up can grow to the right.
-     * - `HorizontalAnchor.Right`: pop-up is anchored to the right side of the trigger and the
-     *   pop-up can grow to the left.
-     * - `HorizontalAnchor.Both`: pop-up is anchored on both sides of the trigger and cannot grow
-     *   beyond it.
-     *
-     * Note that when `HorizontalAnchor.Both` is _not_ used, this anchor will cancel out any
-     * `popUpOffset` for the direction _opposite_ of the chosen anchor.
-     *
-     * @default HorizontalAnchor.Left
-     */
-    horizontalAnchor: HorizontalAnchor;
-}>, {
-    navController: undefined | NavController;
-    popUpManager: undefined | PopUpManager;
-    /** `undefined` means the pop up is not currently showing. */
-    showPopUpResult: ShowPopUpResult | undefined;
-}, {
-    itemActivate: import("element-vir").DefineEvent<PropertyKey[]>;
-    openChange: import("element-vir").DefineEvent<ShowPopUpResult | undefined>;
-}, "vira-menu-trigger-", "vira-menu-trigger-", readonly []>;

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

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

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

@@ -1,81 +0,0 @@
-import { type PartialWithUndefined } from '@augment-vir/common';
-import { NavController, type Coords } from 'device-navigation';
-import { PopUpManager, type ShowPopUpResult } from '../../util/pop-up-manager.js';
-/**
- * Offsets applied to any menu opened by {@link ViraPopUpTrigger}.
- *
- * @category Internal
- */
-export type PopUpOffset = PartialWithUndefined<{
-    vertical: number;
-    right: number;
-    left: number;
-}>;
-/**
- * Anchor options for pop-ups.
- *
- * @category Internal
- */
-export declare enum 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.
-     */
-    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.
-     */
-    Right = "right",
-    /**
-     * Restrict the pop-up on both sides.
-     *
-     * This is the default anchor for {@link ViraPopUpTrigger}.
-     */
-    Both = "both"
-}
-/**
- * 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 declare const ViraPopUpTrigger: import("element-vir").DeclarativeElementDefinition<"vira-pop-up-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 pop-up open if it is interacted with. */
-    keepOpenAfterInteraction: boolean;
-    /** All values in px. */
-    popUpOffset?: PopUpOffset;
-    /**
-     * - `HorizontalAnchor.Left`: pop-up is anchored to the left side of the trigger and the
-     *   pop-up can grow to the right.
-     * - `HorizontalAnchor.Right`: pop-up is anchored to the right side of the trigger and the
-     *   pop-up can grow to the left.
-     * - `HorizontalAnchor.Both`: pop-up is anchored on both sides of the trigger and cannot grow
-     *   beyond it. (This is the default experience.)
-     *
-     * Note that when `HorizontalAnchor.Both` is _not_ used, this anchor will cancel out any
-     * `popUpOffset` for the direction _opposite_ of the chosen anchor.
-     *
-     * @default HorizontalAnchor.Both
-     */
-    horizontalAnchor?: HorizontalAnchor;
-}>, {
-    /** `undefined` means the pop up is not currently showing. */
-    showPopUpResult: ShowPopUpResult | undefined;
-    popUpManager: PopUpManager;
-}, {
-    navSelect: import("element-vir").DefineEvent<Coords>;
-    /**
-     * - `undefined` indicates that the pop-up just closed.
-     * - {@link ShowPopUpResult} indicates that the pop-up just opened.
-     */
-    openChange: import("element-vir").DefineEvent<ShowPopUpResult | undefined>;
-    init: import("element-vir").DefineEvent<{
-        navController: NavController;
-        popUpManager: PopUpManager;
-    }>;
-}, "vira-pop-up-trigger-disabled", "vira-pop-up-trigger-", readonly ["trigger", "popUp"]>;