vira 32.0.0-beta.0 → 32.1.0

package/src/util/pop-up-manager.ts

@@ -1,434 +0,0 @@
-import {assert} from '@augment-vir/assert';
-import {type MaybePromise, mapObjectValues} from '@augment-vir/common';
-import {findOverflowAncestor} from '@augment-vir/web';
-import {type Coords, NavActivateEvent, type NavController, NavDirection} from 'device-navigation';
-import {listenToPageActivation} from 'page-active';
-import {
-    type ExtractEventByType,
-    type ExtractEventTypes,
-    type ListenOptions,
-    ListenTarget,
-    type RemoveListenerCallback,
-    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: Element): boolean {
-    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: Readonly<MouseEvent>): boolean {
-    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)
-    );
-}
-
-/**
- * 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 const emptyPositionRect: PositionRect = {
-    top: 0,
-    left: 0,
-    right: 0,
-    bottom: 0,
-};
-
-/**
- * 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>;
-};
-
-/**
- * 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<Coords>()('nav-select') {}
-
-/**
- * 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 class PopUpManager {
-    protected listenTarget = new ListenTarget<PopUpManagerEvents>();
-    public options: PopUpManagerOptions = {
-        minDownSpace: 200,
-        minRightSpace: 400,
-        verticalDiffThreshold: 20,
-        horizontalDiffThreshold: 100,
-        supportNavigation: true,
-    };
-    /** Callbacks that remove the global listeners attached while a pop up is shown. */
-    protected cleanupCallbacks: (() => void)[] = [];
-    protected lastRootElement: HTMLElement | undefined;
-
-    constructor(
-        public readonly navController: NavController,
-        options?: Partial<PopUpManagerOptions> | undefined,
-    ) {
-        this.options = {
-            ...this.options,
-            ...options,
-        };
-    }
-
-    /**
-     * Attaches the global listeners (page activation, navigation, mousedown, and keydown) that
-     * control the currently shown pop up.
-     */
-    protected 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. */
-    public listen<
-        const EventDefinition extends Readonly<{
-            type: ExtractEventTypes<PopUpManagerEvents>;
-        }>,
-    >(
-        event: EventDefinition,
-        listener: (
-            event: ExtractEventByType<PopUpManagerEvents, EventDefinition['type']>,
-        ) => MaybePromise<void>,
-        options?: ListenOptions | undefined,
-    ): RemoveListenerCallback {
-        return this.listenTarget.listen(event, listener, options);
-    }
-
-    /** Trigger removal or hiding of the pop up. */
-    public removePopUp() {
-        this.cleanupCallbacks.forEach((callback) => callback());
-        this.listenTarget.dispatch(new HidePopUpEvent());
-    }
-
-    /** Trigger showing the pop up. */
-    public showPopUp(
-        rootElement: HTMLElement,
-        options?: Partial<PopUpManagerOptions> | undefined,
-    ): ShowPopUpResult {
-        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: PositionRect =
-            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: PositionRect = mapObjectValues(emptyPositionRect, (key) => {
-            return rootRect[key];
-        });
-        const diff: PositionRect = 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
-     */
-    public destroy() {
-        this.removePopUp();
-        this.listenTarget.destroy();
-    }
-}

package/src/util/shared-text-input-logic.ts

@@ -1,192 +0,0 @@
-import {check, checkWrap} from '@augment-vir/assert';
-import {type PartialWithUndefined} from '@augment-vir/common';
-import {extractEventTarget} from '@augment-vir/web';
-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;
-}>;
-
-function doesMatch({input, matcher}: {input: string; matcher: string | RegExp}): boolean {
-    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);
-    }
-}
-
-/**
- * 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;
-};
-
-function isAllowed({value: rawValue, allowed, blocked}: IsAllowedInputs) {
-    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: IsAllowedInputs): {
-    filtered: string;
-    blocked: string;
-} {
-    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: [] as string[],
-            blocked: [] as string[],
-        },
-    );
-
-    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,
-}: {
-    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;
-}) {
-    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: string =
-        (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);
-    }
-}