vira 32.3.0 → 33.0.0

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

@@ -3,7 +3,7 @@ import { type FullSpaRoute, type GenericTreePaths, type SpaRouter } from 'spa-ro
 import { type ViraIconSvg } from '../icons/icon-svg.js';
 import { ViraColorVariant } from '../styles/form-variants.js';
 import { ViraThemeColorName } from '../styles/vira-color-theme-object.js';
-import { type HorizontalAnchor, type PopUpOffset } from './pop-up/vira-pop-up-trigger.element.js';
+import { type PopoverOffset } from './popover/vira-popover-trigger.element.js';
 /**
  * Controls which edge of the tab the selection indicator bar appears on.
  *
@@ -93,16 +93,10 @@ export declare const ViraTabs: import("element-vir").DeclarativeElementDefinitio
      * @default ViraTabsIconLayout.Vertical
      */
     iconLayout: ViraTabsIconLayout;
-    /**
-     * Horizontal anchor for the dropdown menu. Only used when tabs overflow into a dropdown.
-     *
-     * @default HorizontalAnchor.Left
-     */
-    menuHorizontalAnchor: HorizontalAnchor;
     /** Whether the dropdown trigger is disabled. Only used when tabs overflow into a dropdown. */
     menuIsDisabled: boolean;
-    /** Offset for the dropdown pop-up. Only used when tabs overflow into a dropdown. */
-    menuPopUpOffset: Readonly<PopUpOffset>;
+    /** Offset for the dropdown popover. Only used when tabs overflow into a dropdown. */
+    menuPopoverOffset: Readonly<PopoverOffset>;
     /**
      * Text shown on the overflow "more" trigger when the selected tab is _not_ collapsed into
      * the menu. When the selected tab _is_ collapsed, the trigger shows that tab's label (with

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

@@ -13,9 +13,9 @@ import { standaloneThemeColorNames, ViraColorVariant, viraColorVariantToHostClas
 import { noNativeFormStyles, noUserSelect, viraDisabledStyles, viraTheme } from '../styles/index.js';
 import { viraThemeByKeys, ViraThemeColorName } from '../styles/vira-color-theme-object.js';
 import { defineViraElement } from '../util/define-vira-element.js';
-import { renderMenuItemEntries } from '../util/pop-up-helpers.js';
-import { ViraMenuTrigger } from './pop-up/vira-menu-trigger.element.js';
-import { ViraMenuCornerStyle } from './pop-up/vira-menu.element.js';
+import { renderMenuItemEntries } from '../util/menu-helpers.js';
+import { ViraMenuTrigger } from './popover/vira-menu-trigger.element.js';
+import { ViraMenuCornerStyle } from './popover/vira-menu.element.js';
 import { ViraBoldText } from './vira-bold-text.element.js';
 import { ViraButton } from './vira-button.element.js';
 import { ViraIcon } from './vira-icon.element.js';
@@ -786,10 +786,9 @@ export const ViraTabs = defineViraElement()({
             ? html `
                   <div class="tab-more">
                       <${ViraMenuTrigger.assign({
-                horizontalAnchor: inputs.menuHorizontalAnchor,
                 isDisabled: inputs.menuIsDisabled,
-                popUpOffset: inputs.menuPopUpOffset,
-                menuCornerStyle: ViraMenuCornerStyle.AllRounded,
+                popoverOffset: inputs.menuPopoverOffset,
+                menuCornerStyle: ViraMenuCornerStyle.Round,
             })}>
                           <${ViraButton.assign({
                 text: selectedIsCollapsed ? selectedTab?.label : overflowLabel,

package/dist/elements/vira-text-area.element.d.ts

@@ -1,4 +1,5 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
+import { type HtmlInterpolation } from 'element-vir';
 /**
  * A multi-line text area element with all listeners properly attached. Mirrors the look and feel of
  * {@link ViraInput} but for multi-line text input.
@@ -9,7 +10,7 @@ import { type PartialWithUndefined } from '@augment-vir/common';
  */
 export declare const ViraTextArea: import("element-vir").DeclarativeElementDefinition<"vira-text-area", PartialWithUndefined<{
     /** A label that is shown above the text area, if provided. */
-    label: string;
+    label: string | HtmlInterpolation;
     /** If true, applies error styling. */
     hasError: boolean;
     /** Number of visible text rows. Defaults to 4. */

package/dist/elements/vira-text-area.element.js

@@ -1,5 +1,6 @@
+import { check } from '@augment-vir/assert';
 import { randomString } from '@augment-vir/common';
-import { attributes, css, defineElementEvent, html, ifDefined, listen } from 'element-vir';
+import { attributes, css, defineElementEvent, html, ifDefined, listen, } from 'element-vir';
 import { createFocusStyles } from '../styles/focus.js';
 import { viraFormCssVars } from '../styles/form-styles.js';
 import { viraDisabledStyles } from '../styles/index.js';
@@ -187,7 +188,7 @@ export const ViraTextArea = defineViraElement()({
             <span class="text-area-wrapper">
                 <textarea
                     id=${ifDefined(inputs.label ? state.randomId : undefined)}
-                    aria-label=${ifDefined(inputs.label || undefined)}
+                    aria-label=${ifDefined((check.isString(inputs.label) && inputs.label) || undefined)}
                     rows=${inputs.rows ?? 4}
                     ?disabled=${inputs.disabled}
                     autocomplete=${ifDefined(inputs.disableBrowserHelps ? 'off' : undefined)}

package/dist/elements/vira-theme-switcher.element.js

@@ -75,21 +75,21 @@ export const ViraThemeSwitcher = defineViraElement()({
         const themeClient = inputs.themeClient || state.internalThemeClient || new ViraThemeClient();
         updateState({
             internalThemeClient: themeClient,
-            currentTheme: themeClient.currentTheme,
+            currentTheme: themeClient.getCurrentTheme(),
         });
         const labels = inputs.labels || defaultThemeLabels;
         return Object.values(ViraThemeSelection).map((theme) => {
             return html `
                 <button
                     class=${classMap({
-                selected: themeClient.currentTheme === theme,
+                selected: themeClient.getCurrentTheme() === theme,
             })}
                     title=${labels[theme]}
                     ${listen('click', (event) => {
                 event.stopPropagation();
                 themeClient.setSelectedTheme(theme);
                 updateState({
-                    currentTheme: themeClient.currentTheme,
+                    currentTheme: themeClient.getCurrentTheme(),
                 });
             })}
                 >

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './directives/index.js';
 export * from './elements/index.js';
 export * from './icons/index.js';
 export * from './styles/index.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from './directives/index.js';
 export * from './elements/index.js';
 export * from './icons/index.js';
 export * from './styles/index.js';

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

@@ -0,0 +1,40 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type CSSResult } from 'element-vir';
+/**
+ * The class that `PopoverManager` toggles on a popover to make the browser re-run its
+ * `position-try-fallbacks` from the first entry.
+ *
+ * @category Internal
+ */
+export declare const anchoredPopoverRetryClass = "retry-position";
+/**
+ * A single `position-try-fallbacks` entry for {@link createAnchoredPopoverStyles}.
+ *
+ * @category Popover
+ */
+export type AnchoredPopoverFallback = {
+    /**
+     * The `@position-try` rule name, without the leading `--`. Only needs to be unique within the
+     * shadow root that the styles are used in.
+     */
+    name: string;
+    /** Only the properties that `@position-try` rules accept have any effect here. */
+    styles: CSSResult;
+} & PartialWithUndefined<{
+    /** Adds `flip-block` to this entry, which mirrors it (and its block margins) vertically. */
+    flipBlock: boolean;
+}>;
+/**
+ * Creates the shared styles for a `popover` element that is positioned with CSS anchor positioning
+ * and opened through `PopoverManager`. Put the popover's default position (such as `position-area`)
+ * in a rule _after_ these styles. `fallbacks` are tried in order whenever the default position
+ * overflows the viewport.
+ *
+ * @category Popover
+ */
+export declare function createAnchoredPopoverStyles({ selector, fallbacks, }: Readonly<{
+    fallbacks: ReadonlyArray<Readonly<AnchoredPopoverFallback>>;
+} & PartialWithUndefined<{
+    /** Selects the popover element. Omit this when the host element itself is the popover. */
+    selector: CSSResult | string;
+}>>): CSSResult;

package/dist/util/anchored-popover.js

@@ -0,0 +1,70 @@
+import { css, unsafeCSS } from 'element-vir';
+/**
+ * The class that `PopoverManager` toggles on a popover to make the browser re-run its
+ * `position-try-fallbacks` from the first entry.
+ *
+ * @category Internal
+ */
+export const anchoredPopoverRetryClass = 'retry-position';
+function createFallbackEntry({ name, flipBlock }) {
+    return flipBlock ? `--${name} flip-block` : `--${name}`;
+}
+/**
+ * Creates the shared styles for a `popover` element that is positioned with CSS anchor positioning
+ * and opened through `PopoverManager`. Put the popover's default position (such as `position-area`)
+ * in a rule _after_ these styles. `fallbacks` are tried in order whenever the default position
+ * overflows the viewport.
+ *
+ * @category Popover
+ */
+export function createAnchoredPopoverStyles({ selector, fallbacks, }) {
+    const fallbackEntries = fallbacks.map((fallback) => createFallbackEntry(fallback));
+    const retryClass = unsafeCSS(anchoredPopoverRetryClass);
+    return css `
+        /*
+            Anchored through showPopover({source}).
+        */
+        ${selector ? unsafeCSS(selector) : unsafeCSS(':host')} {
+            /*
+                position-anchor is set explicitly because its initial value differs between browsers.
+            */
+            position-anchor: auto;
+            /* Override the browser's default popover styles. */
+            position: fixed;
+            inset: auto;
+            margin: 0;
+            padding: 0;
+            border: none;
+            height: auto;
+            overflow: visible;
+            background: none;
+            color: inherit;
+
+            position-try-fallbacks: ${unsafeCSS(fallbackEntries.join(', ') || 'none')};
+        }
+
+        /*
+            Browsers keep using the last position-try-fallbacks entry that fit until it no longer
+            fits, even when an earlier entry fits again, so without this the popover would not return
+            to its default position after a resize or scroll. Changing the computed
+            position-try-fallbacks value is what makes browsers start over from the first entry, so
+            this repeats an entry, which does not change the result.
+        */
+        ${selector
+        ? css `
+                  ${unsafeCSS(selector)}.${retryClass}
+              `
+        : unsafeCSS(`:host(.${anchoredPopoverRetryClass})`)} {
+            position-try-fallbacks: ${unsafeCSS([
+        ...fallbackEntries,
+        ...fallbackEntries.slice(-1),
+    ].join(', ') || 'none')};
+        }
+
+        ${unsafeCSS(fallbacks
+        .map(({ name, styles }) => {
+        return `@position-try --${name} {${styles.cssText}}`;
+    })
+        .join('\n'))}
+    `;
+}

package/dist/util/index.d.ts

@@ -1,11 +1,12 @@
+export * from './anchored-popover.js';
 export * from './define-table.js';
 export * from './define-vira-element.js';
 export * from './dynamic-element.js';
+export * from './menu-helpers.js';
 export * from './overflow-observer.js';
-export * from './pop-up-helpers.js';
-export * from './pop-up-manager.js';
+export * from './popover-manager.js';
 export * from './shared-text-input-logic.js';
+export * from './vira-dropdown-option.js';
 export * from './vira-form-fields.js';
 export * from './vira-json-schema.js';
-export * from './vira-select-option.js';
 export * from './vira-theme-client.js';

package/dist/util/index.js

@@ -1,11 +1,12 @@
+export * from './anchored-popover.js';
 export * from './define-table.js';
 export * from './define-vira-element.js';
 export * from './dynamic-element.js';
+export * from './menu-helpers.js';
 export * from './overflow-observer.js';
-export * from './pop-up-helpers.js';
-export * from './pop-up-manager.js';
+export * from './popover-manager.js';
 export * from './shared-text-input-logic.js';
+export * from './vira-dropdown-option.js';
 export * from './vira-form-fields.js';
 export * from './vira-json-schema.js';
-export * from './vira-select-option.js';
 export * from './vira-theme-client.js';

package/dist/util/{pop-up-helpers.d.ts → menu-helpers.d.ts}

@@ -1,7 +1,6 @@
 import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
 import { type HtmlInterpolation } from 'element-vir';
-import { ViraMenuItem } from '../elements/pop-up/vira-menu-item.element.js';
-import { type PopUpManager, type PopUpManagerOptions, type ShowPopUpResult } from './pop-up-manager.js';
+import { ViraMenuItem } from '../elements/popover/vira-menu-item.element.js';
 /**
  * Verifies that all items have unique ids.
  *
@@ -10,23 +9,10 @@ import { type PopUpManager, type PopUpManagerOptions, type ShowPopUpResult } fro
 export declare function assertUniqueIdProps(items: ReadonlyArray<Readonly<{
     id: PropertyKey;
 }>>): void;
-/**
- * Handles toggling pop up state for `ViraDropdown`.
- *
- * @category Internal
- */
-export declare function triggerPopUpState({ open, callback, popUpManager, host, options, }: Readonly<{
-    open: boolean;
-    popUpManager: PopUpManager;
-    host: HTMLElement;
-} & PartialWithUndefined<{
-    callback?: ((showPopUpResult: ShowPopUpResult | undefined) => void) | undefined;
-    options?: Partial<PopUpManagerOptions> | undefined;
-}>>): void;
 /**
  * A helper type to be used with {@link renderMenuItemEntries}.
  *
- * @category PopUp
+ * @category Popover
  */
 export type ViraMenuItemEntry = {
     content: HtmlInterpolation;
@@ -44,7 +30,7 @@ export type ViraMenuItemEntry = {
 /**
  * A callback for menu items getting activated, to be used with {@link renderMenuItemEntries}.
  *
- * @category PopUp
+ * @category Popover
  */
 export type MenuItemClickCallback = (params: Readonly<{
     /** The menu item's index in the array. */
@@ -54,6 +40,6 @@ export type MenuItemClickCallback = (params: Readonly<{
 /**
  * A helper for rendering a bunch of menu items.
  *
- * @category PopUp
+ * @category Popover
  */
 export declare function renderMenuItemEntries(items: ReadonlyArray<Readonly<ViraMenuItemEntry>>): import("lit-html").HTMLTemplateResult[];

package/dist/util/{pop-up-helpers.js → menu-helpers.js}

@@ -1,6 +1,6 @@
 import { filterMap, joinWithFinalConjunction, } from '@augment-vir/common';
 import { html, listen } from 'element-vir';
-import { ViraMenuItem } from '../elements/pop-up/vira-menu-item.element.js';
+import { ViraMenuItem } from '../elements/popover/vira-menu-item.element.js';
 /**
  * Verifies that all items have unique ids.
  *
@@ -21,25 +21,10 @@ export function assertUniqueIdProps(items) {
         throw new Error(`Duplicate option ids were given: ${joinWithFinalConjunction(duplicateIds)}`);
     }
 }
-/**
- * Handles toggling pop up state for `ViraDropdown`.
- *
- * @category Internal
- */
-export function triggerPopUpState({ open, callback, popUpManager, host, options, }) {
-    if (open) {
-        const showPopUpResult = popUpManager.showPopUp(host, options);
-        callback?.(showPopUpResult);
-    }
-    else {
-        popUpManager.removePopUp();
-        callback?.(undefined);
-    }
-}
 /**
  * A helper for rendering a bunch of menu items.
  *
- * @category PopUp
+ * @category Popover
  */
 export function renderMenuItemEntries(items) {
     return filterMap(items, (item, index) => {

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

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