vira 28.19.5 → 28.19.6

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

@@ -0,0 +1,380 @@
+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)
+    );
+}
+
+/**
+ * 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 {
+    private listenTarget = new ListenTarget<PopUpManagerEvents>();
+    public options: PopUpManagerOptions = {
+        minDownSpace: 200,
+        minRightSpace: 400,
+        verticalDiffThreshold: 20,
+        horizontalDiffThreshold: 100,
+        supportNavigation: true,
+    };
+    private cleanupCallbacks: (() => void)[] = [];
+    private lastRootElement: HTMLElement | undefined;
+
+    constructor(
+        public readonly navController: NavController,
+        options?: Partial<PopUpManagerOptions> | undefined,
+    ) {
+        this.options = {...this.options, ...options};
+    }
+
+    private 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 (
+                        this.lastRootElement &&
+                        event.composedPath().includes(this.lastRootElement)
+                    ) {
+                        /** Ignore clicks that came from the pop up host itself. */
+                        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/dist/elements/define-vira-element.d.ts

@@ -1,18 +0,0 @@
-/**
- * Required prefix for all vira elements.
- *
- * @category Internal
- */
-export declare const ViraTagNamePrefix = "vira-";
-/**
- * Required tag name for all vira elements. This includes {@link ViraTagNamePrefix} in it.
- *
- * @category Internal
- */
-export type ViraTagName = `${typeof ViraTagNamePrefix}${string}`;
-/**
- * Define a vira element with custom requirements (like the `vira-` element tag prefix).
- *
- * @category Internal
- */
-export declare const defineViraElement: <Inputs extends {}>(...errorParams: import("element-vir").DeclarativeElementInputErrorParams<Inputs>) => <const TagName extends `vira-${string}`, State extends {}, EventsInit extends {}, const HostClassKeys extends `${TagName}-${string}` = `${TagName}-`, const CssVarKeys extends `${TagName}-${string}` = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = readonly [], const TestIds extends ReadonlyArray<string> = readonly []>(inputs: import("element-vir").DeclarativeElementInit<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames, TestIds>) => import("element-vir").DeclarativeElementDefinition<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames, TestIds>;

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

@@ -1,19 +0,0 @@
-import { wrapDefineElement } from 'element-vir';
-/**
- * Required prefix for all vira elements.
- *
- * @category Internal
- */
-export const ViraTagNamePrefix = `vira-`;
-/**
- * Define a vira element with custom requirements (like the `vira-` element tag prefix).
- *
- * @category Internal
- */
-export const defineViraElement = wrapDefineElement({
-    assertInputs: (inputs) => {
-        if (!inputs.tagName.startsWith(ViraTagNamePrefix)) {
-            throw new Error(`Tag name should start with '${ViraTagNamePrefix}' but got '${inputs.tagName}'`);
-        }
-    },
-});

package/dist/elements/form/vira-form-fields.d.ts

@@ -1,100 +0,0 @@
-import { type PartialWithUndefined } from '@augment-vir/common';
-import { type ViraIconSvg } from '../../icons/icon-svg.js';
-import { type ViraSelectOption } from '../vira-select.element.js';
-/**
- * Form field types for {@link ViraFormField}.
- *
- * @category Internal
- */
-export declare enum ViraFormFieldType {
-    Text = "text",
-    /** Allows auto complete for _existing_ passwords used on this website (for login). */
-    ExistingPassword = "existing-password",
-    /** Allows auto complete for _new_ passwords used on this website (for login). */
-    NewPassword = "new-password",
-    /** Uses a password input without any attributes applied for auto complete hints. */
-    PlainPassword = "plain-password",
-    Email = "email",
-    Select = "select",
-    Checkbox = "checkbox"
-}
-/**
- * {@link ViraFormField} properties that are shared between all field types.
- *
- * @category Internal
- */
-export type CommonViraFormFields = {
-    label: string;
-} & PartialWithUndefined<{
-    /** Applies a test id to the form field element. */
-    testId: string;
-    /**
-     * When `true`, visually indicates the form field as required and affects form validation.
-     *
-     * @default false
-     */
-    isRequired: boolean;
-    /**
-     * When `true`, marks this form field element with error styling.
-     *
-     * @default false
-     */
-    hasError: boolean;
-    /**
-     * When `true`, hides this form field entirely.
-     *
-     * @default false
-     */
-    isHidden: boolean;
-    /**
-     * When `true`, continues showing the form field but prevents edits.
-     *
-     * @default false
-     */
-    isDisabled: boolean;
-}>;
-/**
- * An individual form field for {@link ViraFormFields}.
- *
- * @category Internal
- */
-export type ViraFormField = ({
-    type: ViraFormFieldType.Text | ViraFormFieldType.ExistingPassword | ViraFormFieldType.NewPassword | ViraFormFieldType.PlainPassword | ViraFormFieldType.Email;
-    value: string | undefined;
-} & PartialWithUndefined<{
-    placeholder: string;
-    icon: ViraIconSvg;
-    isUsername: boolean;
-}> & CommonViraFormFields) | ({
-    type: ViraFormFieldType.Select;
-    value: string | undefined;
-    options: ReadonlyArray<Readonly<ViraSelectOption>>;
-} & PartialWithUndefined<{
-    placeholder: string;
-    icon: ViraIconSvg;
-}> & CommonViraFormFields) | ({
-    type: ViraFormFieldType.Checkbox;
-    value: boolean | undefined;
-} & CommonViraFormFields);
-/**
- * A collection of form fields for `ViraForm`.
- *
- * @category Internal
- */
-export type ViraFormFields = Record<string, ViraFormField>;
-/**
- * Appends a `'*'` to a label if it exist sand if it is required.
- *
- * @category Internal
- */
-export declare function applyRequiredLabel(label: string | undefined, isRequired: boolean): string | undefined;
-/**
- * Checks if all the {@link ViraFormField} entries in a given {@link ViraFormFields} are valid through
- * the following checks:
- *
- * - Checks that required fields are provided (not `undefined`)
- * - Ignores hidden fields
- *
- * @category Internal
- */
-export declare function areFormFieldsValid(formFields: Readonly<ViraFormFields>): boolean;

package/dist/elements/form/vira-form-fields.js

@@ -1,60 +0,0 @@
-import { check } from '@augment-vir/assert';
-import { addSuffix, getObjectTypedValues } from '@augment-vir/common';
-/**
- * Form field types for {@link ViraFormField}.
- *
- * @category Internal
- */
-export var ViraFormFieldType;
-(function (ViraFormFieldType) {
-    ViraFormFieldType["Text"] = "text";
-    /** Allows auto complete for _existing_ passwords used on this website (for login). */
-    ViraFormFieldType["ExistingPassword"] = "existing-password";
-    /** Allows auto complete for _new_ passwords used on this website (for login). */
-    ViraFormFieldType["NewPassword"] = "new-password";
-    /** Uses a password input without any attributes applied for auto complete hints. */
-    ViraFormFieldType["PlainPassword"] = "plain-password";
-    ViraFormFieldType["Email"] = "email";
-    ViraFormFieldType["Select"] = "select";
-    ViraFormFieldType["Checkbox"] = "checkbox";
-})(ViraFormFieldType || (ViraFormFieldType = {}));
-/**
- * Appends a `'*'` to a label if it exist sand if it is required.
- *
- * @category Internal
- */
-export function applyRequiredLabel(label, isRequired) {
-    if (label) {
-        if (isRequired) {
-            return addSuffix({ value: label, suffix: '*' });
-        }
-        else {
-            return label;
-        }
-    }
-    else {
-        return undefined;
-    }
-}
-/**
- * Checks if all the {@link ViraFormField} entries in a given {@link ViraFormFields} are valid through
- * the following checks:
- *
- * - Checks that required fields are provided (not `undefined`)
- * - Ignores hidden fields
- *
- * @category Internal
- */
-export function areFormFieldsValid(formFields) {
-    return getObjectTypedValues(formFields).every((formField) => {
-        if (formField.isHidden || !formField.isRequired) {
-            return true;
-        }
-        else if (check.isString(formField.value)) {
-            return !!formField.value;
-        }
-        else {
-            return formField.value != undefined;
-        }
-    });
-}

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

@@ -1,35 +0,0 @@
-import { type PartialWithUndefined } from '@augment-vir/common';
-import { type ViraFormField, type ViraFormFields } from './vira-form-fields.js';
-/**
- * A form element.
- *
- * @category Elements
- * @see https://electrovir.github.io/vira/book/elements/vira-form
- */
-export declare const ViraForm: import("element-vir").DeclarativeElementDefinition<"vira-form", Readonly<{
-    fields: Readonly<ViraFormFields>;
-} & PartialWithUndefined<{
-    showClearButtons: boolean;
-    /**
-     * When `true`, all fields in this form are disabled. Note that this will not (and can
-     * not) disable any child elements you've inserted via <slot>.
-     *
-     * @default false
-     */
-    isDisabled: boolean;
-    /**
-     * If true, no `'*'` is appended to required form field labels.
-     *
-     * @default false
-     */
-    hideRequiredMarkers: boolean;
-}>>, {
-    lastIsValid: boolean;
-}, {
-    valueChange: import("element-vir").DefineEvent<{
-        key: string;
-    } & ViraFormField>;
-    validChange: import("element-vir").DefineEvent<{
-        allFieldsAreValid: boolean;
-    }>;
-}, "vira-form-", "vira-form-", readonly [], readonly []>;