vira 28.19.6 → 28.20.0

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

@@ -0,0 +1,214 @@
+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));
+}
+/**
+ * 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,
+    };
+    cleanupCallbacks = [];
+    lastRootElement;
+    constructor(navController, options) {
+        this.navController = navController;
+        this.options = { ...this.options, ...options };
+    }
+    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. */
+    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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vira",
-    "version": "28.19.6",
+    "version": "28.20.0",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",
@@ -27,9 +27,9 @@
     },
     "sideEffects": false,
     "type": "module",
-    "main": "src/index.ts",
-    "module": "src/index.ts",
-    "types": "src/index.ts",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
     "scripts": {
         "build": "npm run docs",
         "compile": "virmator compile",
@@ -44,7 +44,7 @@
         "colorjs.io": "^0.6.1",
         "date-vir": "^8.1.0",
         "device-navigation": "^4.5.5",
-        "lit-css-vars": "^3.1.1",
+        "lit-css-vars": "^3.2.2",
         "observavir": "^2.3.1",
         "page-active": "^1.0.3",
         "spa-router-vir": "^6.4.1",
@@ -61,7 +61,7 @@
         "esbuild": "^0.27.2",
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
-        "theme-vir": "^28.18.2",
+        "theme-vir": "^28.18.3",
         "typedoc": "^0.28.16",
         "typescript": "5.9.3",
         "vite": "^7.3.1",

package/src/elements/define-vira-element.ts

@@ -1,29 +0,0 @@
-import {wrapDefineElement} from 'element-vir';
-
-/**
- * Required prefix for all vira elements.
- *
- * @category Internal
- */
-export 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 const defineViraElement = wrapDefineElement<ViraTagName>({
-    assertInputs: (inputs) => {
-        if (!inputs.tagName.startsWith(ViraTagNamePrefix)) {
-            throw new Error(
-                `Tag name should start with '${ViraTagNamePrefix}' but got '${inputs.tagName}'`,
-            );
-        }
-    },
-});

package/src/elements/form/vira-form-fields.ts

@@ -1,140 +0,0 @@
-import {check} from '@augment-vir/assert';
-import {addSuffix, getObjectTypedValues, 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 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 function applyRequiredLabel(
-    label: string | undefined,
-    isRequired: boolean,
-): string | undefined {
-    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: Readonly<ViraFormFields>) {
-    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/src/elements/form/vira-form.element.ts

@@ -1,204 +0,0 @@
-import {getObjectTypedEntries, type PartialWithUndefined} from '@augment-vir/common';
-import {css, defineElementEvent, html, listen, nothing, testId} from 'element-vir';
-import {defineViraElement} from '../define-vira-element.js';
-import {ViraCheckbox} from '../vira-checkbox.element.js';
-import {ViraInput, ViraInputType} from '../vira-input.element.js';
-import {ViraSelect} from '../vira-select.element.js';
-import {
-    applyRequiredLabel,
-    areFormFieldsValid,
-    type ViraFormField,
-    type ViraFormFields,
-    ViraFormFieldType,
-} from './vira-form-fields.js';
-
-/**
- * A form element.
- *
- * @category Elements
- * @see https://electrovir.github.io/vira/book/elements/vira-form
- */
-export const ViraForm = defineViraElement<
-    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;
-        }>
-    >
->()({
-    tagName: 'vira-form',
-    events: {
-        valueChange: defineElementEvent<
-            {
-                key: string;
-            } & ViraFormField
-        >(),
-        validChange: defineElementEvent<{
-            allFieldsAreValid: boolean;
-        }>(),
-    },
-    styles: css`
-        :host {
-            display: flex;
-        }
-
-        form {
-            display: flex;
-            flex-grow: 1;
-            flex-direction: column;
-            align-items: stretch;
-            gap: 10px;
-
-            > * {
-                width: unset;
-            }
-        }
-    `,
-    state() {
-        return {
-            lastIsValid: false,
-        };
-    },
-    render({inputs, dispatch, events, state, updateState}) {
-        const currentIsValid = areFormFieldsValid(inputs.fields);
-        if (currentIsValid !== state.lastIsValid) {
-            updateState({
-                lastIsValid: currentIsValid,
-            });
-            dispatch(new events.validChange({allFieldsAreValid: currentIsValid}));
-        }
-
-        const formFieldTemplates = getObjectTypedEntries(inputs.fields).map(
-            ([
-                key,
-                field,
-            ]) => {
-                if (field.isHidden) {
-                    return nothing;
-                } else if (field.type === ViraFormFieldType.Checkbox) {
-                    return html`
-                        <${ViraCheckbox.assign({
-                            value: field.value || false,
-                            disabled: inputs.isDisabled || field.isDisabled,
-                            hasError: field.hasError,
-                            label: applyRequiredLabel(
-                                field.label,
-                                !!field.isRequired && !inputs.hideRequiredMarkers,
-                            ),
-                        })}
-                            ${field.testId ? testId(field.testId) : nothing}
-                            ${listen(ViraCheckbox.events.valueChange, (event) => {
-                                dispatch(
-                                    new events.valueChange({
-                                        key,
-                                        ...field,
-                                        value: event.detail,
-                                    }),
-                                );
-                            })}
-                        ></${ViraCheckbox}>
-                    `;
-                } else if (field.type === ViraFormFieldType.Select) {
-                    return html`
-                        <${ViraSelect.assign({
-                            options: field.options,
-                            value: field.value,
-                            placeholder: field.placeholder,
-                            disabled: inputs.isDisabled || field.isDisabled,
-                            label: applyRequiredLabel(
-                                field.label,
-                                !!field.isRequired && !inputs.hideRequiredMarkers,
-                            ),
-                            hasError: field.hasError,
-                            icon: field.icon,
-                        })}
-                            ${field.testId ? testId(field.testId) : nothing}
-                            ${listen(ViraSelect.events.valueChange, (event) => {
-                                dispatch(
-                                    new events.valueChange({
-                                        key,
-                                        ...field,
-                                        value: event.detail,
-                                    }),
-                                );
-                            })}
-                        ></${ViraSelect}>
-                    `;
-                } else {
-                    return html`
-                        <${ViraInput.assign({
-                            value: field.value || '',
-                            disabled: inputs.isDisabled || field.isDisabled,
-                            hasError: field.hasError,
-                            icon: field.icon,
-                            label: applyRequiredLabel(
-                                field.label,
-                                !!field.isRequired && !inputs.hideRequiredMarkers,
-                            ),
-                            placeholder: field.placeholder,
-                            showClearButton: inputs.showClearButtons,
-                            attributePassthrough: field.isUsername
-                                ? {
-                                      autocomplete: 'username',
-                                  }
-                                : field.type === ViraFormFieldType.NewPassword
-                                  ? {
-                                        autocomplete: 'new-password',
-                                    }
-                                  : field.type === ViraFormFieldType.ExistingPassword
-                                    ? {
-                                          autocomplete: 'password',
-                                      }
-                                    : field.type === ViraFormFieldType.Email
-                                      ? {
-                                            autocomplete: 'email',
-                                        }
-                                      : {},
-                            type: [
-                                ViraFormFieldType.NewPassword,
-                                ViraFormFieldType.ExistingPassword,
-                                ViraFormFieldType.PlainPassword,
-                            ].includes(field.type)
-                                ? ViraInputType.Password
-                                : field.type === ViraFormFieldType.Email
-                                  ? ViraInputType.Email
-                                  : ViraInputType.Default,
-                        })}
-                            ${field.testId ? testId(field.testId) : nothing}
-                            ${listen(ViraInput.events.valueChange, (event) => {
-                                dispatch(
-                                    new events.valueChange({
-                                        key,
-                                        ...field,
-                                        value: event.detail,
-                                    }),
-                                );
-                            })}
-                        ></${ViraInput}>
-                    `;
-                }
-            },
-        );
-
-        return html`
-            <form ${listen('submit', (event) => event.preventDefault())}>
-                ${formFieldTemplates}
-                <slot></slot>
-            </form>
-        `;
-    },
-});