vira 32.0.0-beta.0 → 32.0.0

package/dist/util/pop-up-manager.d.ts

@@ -0,0 +1,200 @@
+import { type MaybePromise } from '@augment-vir/common';
+import { type Coords, type NavController } from 'device-navigation';
+import { type ExtractEventByType, type ExtractEventTypes, type ListenOptions, ListenTarget, type RemoveListenerCallback } from 'typed-event-target';
+/**
+ * Used to prevent pop-ups from closing when a text input is active.
+ *
+ * @category Internal
+ */
+export declare function isInputLikeElement(element: Element): 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 pop-up and dismiss it mid-drag.
+ *
+ * @category Internal
+ */
+export declare function isMouseEventOnScrollbar(event: Readonly<MouseEvent>): boolean;
+/**
+ * A type used for representing a rectangle's position.
+ *
+ * @category Internal
+ */
+export type PositionRect = {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+};
+/**
+ * The default empty {@link PositionRect}, with all values set to 0.
+ *
+ * @category Internal
+ */
+export declare const emptyPositionRect: PositionRect;
+/**
+ * Options for {@link PopUpManager}.
+ *
+ * @category PopUp
+ */
+export type PopUpManagerOptions = {
+    /**
+     * 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 pop-up will be directed upwards.
+     *
+     * Equation:
+     *
+     *     const directUpwards =
+     *         downwardsSpace < minDownSpace &&
+     *         upwardsSpace > DownwardsSpace + verticalDiffThreshold;
+     *
+     * @default 200
+     */
+    minDownSpace: number;
+    /**
+     * The minimum number of pixels for allowing the pop-up to go rightwards. If the rightward
+     * available space is less than this, and if the leftwards available space is
+     * `horizontalDiffThreshold` more than the rightwards space, the pop-up will be directed
+     * leftwards.
+     *
+     * Equation:
+     *
+     *     const directLeftwards =
+     *         rightwardsSpace < minRightSpace &&
+     *         leftwardsSpace > rightwardsSpace + horizontalDiffThreshold;
+     *
+     * @default 400
+     */
+    minRightSpace: 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.
+     *
+     * Equation:
+     *
+     *     const directUpwards =
+     *         downwardsSpace < minDownSpace &&
+     *         upwardsSpace > DownwardsSpace + verticalDiffThreshold;
+     *
+     * @default 20
+     */
+    verticalDiffThreshold: number;
+    /**
+     * The number of pixels required for the leftwards available space to be bigger than the
+     * rightwards available space before directing the pop-up leftwards.
+     *
+     * Equation:
+     *
+     *     const directLeftwards =
+     *         rightwardsSpace < minRightSpace &&
+     *         leftwardsSpace > rightwardsSpace + horizontalDiffThreshold;
+     *
+     * @default 100
+     */
+    horizontalDiffThreshold: number;
+    /**
+     * Supports navigation of the pop up via the `device-navigation` package.
+     *
+     * @default true
+     */
+    supportNavigation: boolean;
+};
+/**
+ * Output type from `PopUpManager.showPopUp`
+ *
+ * @category PopUp
+ */
+export type ShowPopUpResult = {
+    /**
+     * 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 "pop up" should pop in the rightwards direction or not. If not, it should
+     * pop in the leftwards direction. This is determined by how much space is available on either
+     * side of the root element.
+     */
+    popRight: boolean;
+    positions: Record<'root' | 'container' | 'diff', PositionRect>;
+};
+declare const HidePopUpEvent_base: (new (eventInitDict?: EventInit) => Event & 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;
+}, "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE" | "prototype"> & Pick<import("typed-event-target").TypedEvent<"hide-pop-up">, "type">;
+/**
+ * An event fired from {@link PopUpManager} when the pop up should be hidden.
+ *
+ * @category PopUp
+ */
+export declare class HidePopUpEvent extends HidePopUpEvent_base {
+}
+declare const NavSelectEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: Coords;
+}) => import("typed-event-target").TypedCustomEvent<Coords, "nav-select">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE" | "prototype"> & 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.
+ *
+ * @category PopUp
+ */
+export declare class NavSelectEvent extends NavSelectEvent_base {
+}
+/**
+ * All events that can be emitted by {@link PopUpManager}.
+ *
+ * @category Internal
+ */
+export type PopUpManagerEvents = HidePopUpEvent | NavSelectEvent;
+/**
+ * A "pop up" manager for items that pop up from the HTML page, like dropdowns or menus.
+ *
+ * @category PopUp
+ */
+export declare class PopUpManager {
+    readonly navController: NavController;
+    protected listenTarget: ListenTarget<PopUpManagerEvents>;
+    options: PopUpManagerOptions;
+    /** Callbacks that remove the global listeners attached while a pop up is shown. */
+    protected cleanupCallbacks: (() => void)[];
+    protected lastRootElement: HTMLElement | undefined;
+    constructor(navController: NavController, options?: Partial<PopUpManagerOptions> | undefined);
+    /**
+     * Attaches the global listeners (page activation, navigation, mousedown, and keydown) that
+     * control the currently shown pop up.
+     */
+    protected attachGlobalListeners(): void;
+    /** Listen to events emitted from a {@link PopUpManager} 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;
+    /**
+     * Cleanup and destroy the {@link PopUpManager} instance. This:
+     *
+     * - Removes the existing pop up
+     * - Cleans up all internal and external listeners
+     */
+    destroy(): void;
+}
+export {};

package/dist/util/pop-up-manager.js

@@ -0,0 +1,258 @@
+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';
+/**
+ * Used to prevent pop-ups 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));
+}
+/**
+ * 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 pop-up 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 default empty {@link PositionRect}, with all values set to 0.
+ *
+ * @category Internal
+ */
+export const emptyPositionRect = {
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+};
+/**
+ * An event fired from {@link PopUpManager} when the pop up should be hidden.
+ *
+ * @category PopUp
+ */
+export class HidePopUpEvent extends defineTypedEvent('hide-pop-up') {
+}
+/**
+ * An event fired from {@link PopUpManager} when an individual item in the pop up has been selected
+ * by the user.
+ *
+ * @category PopUp
+ */
+export class NavSelectEvent extends defineTypedCustomEvent()('nav-select') {
+}
+/**
+ * A "pop up" manager for items that pop up from the HTML page, like dropdowns or menus.
+ *
+ * @category PopUp
+ */
+export class PopUpManager {
+    navController;
+    listenTarget = new ListenTarget();
+    options = {
+        minDownSpace: 200,
+        minRightSpace: 400,
+        verticalDiffThreshold: 20,
+        horizontalDiffThreshold: 100,
+        supportNavigation: true,
+    };
+    /** Callbacks that remove the global listeners attached while a pop up is shown. */
+    cleanupCallbacks = [];
+    lastRootElement;
+    constructor(navController, options) {
+        this.navController = navController;
+        this.options = {
+            ...this.options,
+            ...options,
+        };
+    }
+    /**
+     * Attaches the global listeners (page activation, navigation, mousedown, and keydown) that
+     * control the currently shown pop up.
+     */
+    attachGlobalListeners() {
+        this.cleanupCallbacks = [
+            listenToPageActivation(false, (isPageActive) => {
+                if (!isPageActive) {
+                    this.removePopUp();
+                }
+            }),
+            this.navController.listen(NavActivateEvent, (event) => {
+                const target = event.composedPath()[0];
+                if (target instanceof Element && isInputLikeElement(target)) {
+                    return;
+                }
+                if (event.detail.success) {
+                    this.listenTarget.dispatch(new NavSelectEvent({
+                        detail: event.detail.coords,
+                    }));
+                    this.navController.currentNavEntry?.entry.focus(true);
+                    event.stopImmediatePropagation();
+                    event.preventDefault();
+                }
+            }),
+            listenToGlobal('mousedown', (event) => {
+                if (
+                /** Ignore clicks that came from the pop up host itself. */
+                (this.lastRootElement &&
+                    event.composedPath().includes(this.lastRootElement)) ||
+                    isMouseEventOnScrollbar(event)) {
+                    return;
+                }
+                this.removePopUp();
+            }, {
+                passive: true,
+            }),
+            listenToGlobal('keydown', (event) => {
+                const keyCode = event.code;
+                if (keyCode === 'Escape') {
+                    this.removePopUp();
+                }
+                else if (this.options.supportNavigation) {
+                    const target = event.composedPath()[0];
+                    if (target instanceof Element && isInputLikeElement(target)) {
+                        return;
+                    }
+                    if (keyCode === 'ArrowDown') {
+                        event.stopImmediatePropagation();
+                        event.preventDefault();
+                        this.navController.navigate({
+                            direction: NavDirection.Down,
+                            allowWrapping: false,
+                        });
+                    }
+                    else if (keyCode === 'ArrowUp') {
+                        event.stopImmediatePropagation();
+                        event.preventDefault();
+                        this.navController.navigate({
+                            direction: NavDirection.Up,
+                            allowWrapping: false,
+                        });
+                    }
+                    else if (keyCode === 'ArrowLeft') {
+                        event.stopImmediatePropagation();
+                        event.preventDefault();
+                        this.navController.navigate({
+                            direction: NavDirection.Left,
+                            allowWrapping: false,
+                        });
+                    }
+                    else if (keyCode === 'ArrowRight') {
+                        event.stopImmediatePropagation();
+                        event.preventDefault();
+                        this.navController.navigate({
+                            direction: NavDirection.Right,
+                            allowWrapping: false,
+                        });
+                    }
+                    else if ((keyCode === 'Enter' || keyCode === 'Return' || keyCode === 'Space') &&
+                        this.navController.enterInto({
+                            fallbackToActivate: true,
+                        }).success) {
+                        event.stopImmediatePropagation();
+                        event.preventDefault();
+                    }
+                }
+            }),
+        ];
+    }
+    /** 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 pop up. */
+    removePopUp() {
+        this.cleanupCallbacks.forEach((callback) => callback());
+        this.listenTarget.dispatch(new HidePopUpEvent());
+    }
+    /** Trigger showing the pop up. */
+    showPopUp(rootElement, options) {
+        this.lastRootElement = rootElement;
+        const currentOptions = {
+            ...this.options,
+            ...options,
+        };
+        const container = findOverflowAncestor(rootElement);
+        assert.instanceOf(container, HTMLElement);
+        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 rootPosition = mapObjectValues(emptyPositionRect, (key) => {
+            return rootRect[key];
+        });
+        const diff = mapObjectValues(emptyPositionRect, (key) => {
+            const containerDimension = containerPosition[key];
+            const hostDimension = rootPosition[key];
+            return Math.abs(containerDimension - hostDimension);
+        });
+        const useUp = diff.top > diff.bottom + currentOptions.verticalDiffThreshold &&
+            diff.bottom < currentOptions.minDownSpace;
+        const useLeft = diff.left > diff.right + currentOptions.horizontalDiffThreshold &&
+            diff.right < currentOptions.minRightSpace;
+        this.attachGlobalListeners();
+        return {
+            popDown: !useUp,
+            popRight: !useLeft,
+            positions: {
+                container: containerPosition,
+                root: rootPosition,
+                diff,
+            },
+        };
+    }
+    /**
+     * Cleanup and destroy the {@link PopUpManager} instance. This:
+     *
+     * - Removes the existing pop up
+     * - Cleans up all internal and external listeners
+     */
+    destroy() {
+        this.removePopUp();
+        this.listenTarget.destroy();
+    }
+}

package/dist/util/shared-text-input-logic.d.ts

@@ -0,0 +1,69 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type AttributeValues } from 'element-vir';
+/**
+ * Inputs shared between the multiple input elements.
+ *
+ * @category Internal
+ */
+export type SharedTextInputElementInputs = {
+    value: string;
+} & PartialWithUndefined<{
+    /** Shown when no other text is present. Input restrictions do not apply to this property. */
+    placeholder: string;
+    /** Set to true to trigger disabled styles and to block all user input. */
+    disabled: boolean;
+    isReadonly: boolean;
+    /**
+     * Only letters in the given string or matches to the given RegExp will be allowed.
+     * blockedInputs takes precedence over this input.
+     *
+     * For example: if allowedInputs is set to "abcd" and blockedInputs is set to "d", only "a",
+     * "b", or "c" letters will be allowed.
+     */
+    allowedInputs: string | RegExp;
+    /** Any letters in the given string or matches to the given RegExp will be blocked. */
+    blockedInputs: string | RegExp;
+    /** Disable all browser helps like spellchecking, autocomplete, etc. */
+    disableBrowserHelps: boolean;
+    /** Set this to true to make the whole element size to only fit the input text. */
+    fitText: boolean;
+    /** A set of attributes that will be applied to the inner native text element. */
+    attributePassthrough: AttributeValues;
+}>;
+/**
+ * Inputs used to check if the current input element value is allowed.
+ *
+ * @category Internal
+ */
+export type IsAllowedInputs = {
+    value: string | number;
+    allowed: string | RegExp | undefined;
+    blocked: string | RegExp | undefined;
+};
+/**
+ * Filters out blocked text from an input element's value.
+ *
+ * @category Internal
+ */
+export declare function filterTextInputValue(inputs: IsAllowedInputs): {
+    filtered: string;
+    blocked: string;
+};
+/**
+ * A function to be called when an input element's value changes.
+ *
+ * @category Internal
+ */
+export declare function textInputListener({ inputs, previousValue, event, elementConstructor, inputBlockedCallback, newValueCallback, }: {
+    inputs: SharedTextInputElementInputs;
+    /** The value of the input element before this listener fired. */
+    previousValue: string;
+    event: Event;
+    /**
+     * The constructor for the underlying native element. Defaults to `HTMLInputElement`, but can be
+     * set to `HTMLTextAreaElement` for textarea-based elements.
+     */
+    elementConstructor?: typeof HTMLInputElement | typeof HTMLTextAreaElement | undefined;
+    inputBlockedCallback: (blockedInput: string) => void;
+    newValueCallback: (newValue: string) => void;
+}): void;

package/dist/util/shared-text-input-logic.js

@@ -0,0 +1,114 @@
+import { check, checkWrap } from '@augment-vir/assert';
+import { extractEventTarget } from '@augment-vir/web';
+function doesMatch({ input, matcher }) {
+    if (!input || !matcher) {
+        return true;
+    }
+    else if (input.length > 1) {
+        return input.split('').every((singleInput) => {
+            return doesMatch({
+                input: singleInput,
+                matcher,
+            });
+        });
+    }
+    else if (matcher instanceof RegExp) {
+        return !!input.match(matcher);
+    }
+    else {
+        return matcher.includes(input);
+    }
+}
+function isAllowed({ value: rawValue, allowed, blocked }) {
+    const value = String(rawValue);
+    const isAllowedCharacter = allowed
+        ? doesMatch({
+            input: value,
+            matcher: allowed,
+        })
+        : true;
+    const isBlockedCharacter = blocked
+        ? doesMatch({
+            input: value,
+            matcher: blocked,
+        })
+        : false;
+    return isAllowedCharacter && !isBlockedCharacter;
+}
+/**
+ * Filters out blocked text from an input element's value.
+ *
+ * @category Internal
+ */
+export function filterTextInputValue(inputs) {
+    const value = String(inputs.value);
+    if (!inputs.value) {
+        return {
+            filtered: value,
+            blocked: '',
+        };
+    }
+    const { filtered, blocked } = value.split('').reduce((accum, letter) => {
+        const allowed = isAllowed({
+            ...inputs,
+            value: letter,
+        });
+        if (allowed) {
+            accum.filtered.push(letter);
+        }
+        else {
+            accum.blocked.push(letter);
+        }
+        return accum;
+    }, {
+        filtered: [],
+        blocked: [],
+    });
+    return {
+        filtered: filtered.join(''),
+        blocked: blocked.join(''),
+    };
+}
+/**
+ * A function to be called when an input element's value changes.
+ *
+ * @category Internal
+ */
+export function textInputListener({ inputs, previousValue, event, elementConstructor, inputBlockedCallback, newValueCallback, }) {
+    const inputElement = extractEventTarget(event, elementConstructor || HTMLInputElement);
+    /**
+     * This is usually a single character, but can be a bunch of characters in some circumstances.
+     * For example, when a bunch of characters are pasted, this will be the entire pasted contents.
+     *
+     * When a password manager auto fills the password, at least for Safari + iCloud Keychain, it'll
+     * fire a `CustomEvent` (rather than the typical `InputEvent`) and `event.data` won't be
+     * populated.
+     */
+    const changedText = (check.hasKey(event, 'data') && checkWrap.isString(event.data)) || '';
+    /**
+     * When changedText is falsy, that means an operation other than inserting characters happened.
+     * Such as: deleting, cutting the text, etc.
+     */
+    if (changedText) {
+        const { blocked } = filterTextInputValue({
+            value: changedText,
+            allowed: inputs.allowedInputs,
+            blocked: inputs.blockedInputs,
+        });
+        if (blocked.length) {
+            inputBlockedCallback(blocked);
+        }
+    }
+    const finalValue = filterTextInputValue({
+        value: inputElement.value,
+        allowed: inputs.allowedInputs,
+        blocked: inputs.blockedInputs,
+    }).filtered;
+    if (inputElement.value !== finalValue) {
+        // this prevents blocked inputs by simply overwriting them
+        inputElement.value = finalValue;
+    }
+    if (previousValue !== finalValue) {
+        newValueCallback(finalValue);
+    }
+}