vira 28.19.5 → 28.19.6

package/{dist/elements/pop-up/vira-pop-up-trigger.element.js → src/elements/pop-up/vira-pop-up-trigger.element.ts}

@@ -1,39 +1,94 @@
-import { assert } from '@augment-vir/assert';
-import { walkActiveElement } from '@augment-vir/web';
-import { NavController } from 'device-navigation';
-import { classMap, css, defineElementEvent, html, listen, renderIf } from 'element-vir';
-import { createFocusStyles } from '../../styles/focus.js';
-import { noNativeFormStyles, noUserSelect, viraDisabledStyles } from '../../styles/index.js';
-import { HidePopUpEvent, isInputLikeElement, NavSelectEvent, PopUpManager, } from '../../util/pop-up-manager.js';
-import { defineViraElement } from '../define-vira-element.js';
-import { triggerPopUpState } from './pop-up-helpers.js';
+import {assert} from '@augment-vir/assert';
+import {type PartialWithUndefined} from '@augment-vir/common';
+import {walkActiveElement} from '@augment-vir/web';
+import {NavController, type Coords} from 'device-navigation';
+import {classMap, css, defineElementEvent, html, listen, renderIf} from 'element-vir';
+import {createFocusStyles} from '../../styles/focus.js';
+import {noNativeFormStyles, noUserSelect, viraDisabledStyles} from '../../styles/index.js';
+import {
+    HidePopUpEvent,
+    isInputLikeElement,
+    NavSelectEvent,
+    PopUpManager,
+    type ShowPopUpResult,
+} from '../../util/pop-up-manager.js';
+import {defineViraElement} from '../define-vira-element.js';
+import {triggerPopUpState} from './pop-up-helpers.js';
+
+/**
+ * Offsets applied to any menu opened by {@link ViraPopUpTrigger}.
+ *
+ * @category Internal
+ */
+export type PopUpOffset = PartialWithUndefined<{
+    vertical: number;
+    right: number;
+    left: number;
+}>;
+
 /**
  * Anchor options for pop-ups.
  *
  * @category Internal
  */
-export var HorizontalAnchor;
-(function (HorizontalAnchor) {
+export enum HorizontalAnchor {
     /**
      * The left side of the pop-up will be anchored to the left side of the trigger, allowing the
      * pop-up to grow on the right side of the trigger.
      */
-    HorizontalAnchor["Left"] = "left";
+    Left = 'left',
     /**
      * The Right side of the pop-up will be anchored to the right side of the trigger, allowing the
      * pop-up to grow on the left side of the trigger.
      */
-    HorizontalAnchor["Right"] = "right";
+    Right = 'right',
     /** Restrict the pop-up on both sides. */
-    HorizontalAnchor["Both"] = "both";
+    Both = 'both',
     /**
      * Automatically choose left or right based on available space, defaulting to anchoring on the
      * left side.
      *
      * This is the default anchor for {@link ViraPopUpTrigger}.
      */
-    HorizontalAnchor["Auto"] = "auto";
-})(HorizontalAnchor || (HorizontalAnchor = {}));
+    Auto = 'auto',
+}
+
+/**
+ * Configs for {@link ViraPopUpTrigger} pop-up positioning and sizing.
+ *
+ * @category Internal
+ */
+export type PopUpTriggerPosition = {
+    /**
+     * - `HorizontalAnchor.Left`: pop-up is anchored to the left side of the trigger and the pop-up
+     *   can grow to the right.
+     * - `HorizontalAnchor.Right`: pop-up is anchored to the right side of the trigger and the pop-up
+     *   can grow to the left.
+     * - `HorizontalAnchor.Both`: pop-up is anchored on both sides of the trigger and cannot grow
+     *   beyond it.
+     * - `HorizontalAnchor.Auto`: automatically choose left or right anchor based on available space,
+     *   defaulting to left anchor. (This is the default experience.)
+     *
+     * Note that when `HorizontalAnchor.Both` is _not_ used, this anchor will cancel out any
+     * `popUpOffset` for the direction _opposite_ of the chosen anchor.
+     */
+    horizontalAnchor: HorizontalAnchor;
+    /**
+     * When `true`, the pop-up will not have its maximum width constrained to fit within the
+     * overflow container. The positioning logic (left/right) will still be applied.
+     *
+     * @default false
+     */
+    ignoreMaxWidth: boolean;
+    /**
+     * When `true`, the pop-up will not have its maximum height constrained to fit within the
+     * overflow container. The positioning logic (up/down) will still be applied.
+     *
+     * @default false
+     */
+    ignoreMaxHeight: boolean;
+};
+
 /**
  * An element with slots for a pop-up trigger and pop-up contents.
  *
@@ -41,13 +96,25 @@ export var HorizontalAnchor;
  * @category Elements
  * @see https://electrovir.github.io/vira/book/elements/vira-pop-up-trigger
  */
-export const ViraPopUpTrigger = defineViraElement()({
+export const ViraPopUpTrigger = defineViraElement<
+    PartialWithUndefined<
+        PopUpTriggerPosition & {
+            isDisabled: boolean;
+            /** For debugging purposes only. Very bad for actual production code use. */
+            z_debug_forceOpenState: boolean;
+            /** Set to `true` to keep the pop-up open if it is interacted with. */
+            keepOpenAfterInteraction: boolean;
+            /** All values in px. */
+            popUpOffset: PopUpOffset;
+        }
+    >
+>()({
     tagName: 'vira-pop-up-trigger',
-    state({ host }) {
+    state({host}) {
         return {
             /** `undefined` means the pop up is not currently showing. */
-            showPopUpResult: undefined,
-            popUpManager: new PopUpManager(new NavController(host, { activateOnMouseUp: true })),
+            showPopUpResult: undefined as ShowPopUpResult | undefined,
+            popUpManager: new PopUpManager(new NavController(host, {activateOnMouseUp: true})),
         };
     },
     slotNames: [
@@ -55,9 +122,9 @@ export const ViraPopUpTrigger = defineViraElement()({
         'popUp',
     ],
     hostClasses: {
-        'vira-pop-up-trigger-disabled': ({ inputs }) => !!inputs.isDisabled,
+        'vira-pop-up-trigger-disabled': ({inputs}) => !!inputs.isDisabled,
     },
-    styles: ({ hostClasses }) => css `
+    styles: ({hostClasses}) => css`
         :host {
             display: inline-flex;
             box-sizing: border-box;
@@ -75,8 +142,8 @@ export const ViraPopUpTrigger = defineViraElement()({
             box-sizing: border-box;
 
             ${createFocusStyles({
-        elementBorderSize: 1,
-    })}
+                elementBorderSize: 1,
+            })}
         }
 
         .dropdown-trigger {
@@ -119,26 +186,35 @@ export const ViraPopUpTrigger = defineViraElement()({
         }
     `,
     events: {
-        navSelect: defineElementEvent(),
+        navSelect: defineElementEvent<Coords>(),
         /**
          * - `undefined` indicates that the pop-up just closed.
          * - {@link ShowPopUpResult} indicates that the pop-up just opened.
          */
-        openChange: defineElementEvent(),
-        init: defineElementEvent(),
+        openChange: defineElementEvent<ShowPopUpResult | undefined>(),
+        init: defineElementEvent<{
+            navController: NavController;
+            popUpManager: PopUpManager;
+        }>(),
     },
-    cleanup({ state, updateState }) {
-        updateState({ showPopUpResult: undefined });
+    cleanup({state, updateState}) {
+        updateState({showPopUpResult: undefined});
         state.popUpManager.destroy();
     },
-    init({ state, updateState, host, inputs, dispatch, events }) {
+    init({state, updateState, host, inputs, dispatch, events}) {
         /** Refocus the trigger and set the result to `undefined` when the pop up closes. */
         state.popUpManager.listen(HidePopUpEvent, () => {
-            updateState({ showPopUpResult: undefined });
+            updateState({showPopUpResult: undefined});
             dispatch(new events.openChange(undefined));
             if (!inputs.isDisabled) {
                 const dropdownWrapper = host.shadowRoot.querySelector('.dropdown-wrapper');
-                assert.instanceOf(dropdownWrapper, HTMLButtonElement, 'failed to find dropdown wrapper child');
+
+                assert.instanceOf(
+                    dropdownWrapper,
+                    HTMLButtonElement,
+                    'failed to find dropdown wrapper child',
+                );
+
                 dropdownWrapper.focus();
             }
         });
@@ -157,13 +233,19 @@ export const ViraPopUpTrigger = defineViraElement()({
             }
             dispatch(new events.navSelect(event.detail));
         });
-        dispatch(new events.init({
-            navController: state.popUpManager.navController,
-            popUpManager: state.popUpManager,
-        }));
+
+        dispatch(
+            new events.init({
+                navController: state.popUpManager.navController,
+                popUpManager: state.popUpManager,
+            }),
+        );
     },
-    render({ dispatch, events, state, inputs, updateState, host, slotNames }) {
-        function triggerPopUp({ emitEvent, open }, event) {
+    render({dispatch, events, state, inputs, updateState, host, slotNames}) {
+        function triggerPopUp(
+            {emitEvent, open}: {emitEvent: boolean; open: boolean},
+            event: Event | undefined,
+        ) {
             if (state.showPopUpResult && inputs.keepOpenAfterInteraction && event) {
                 const dropdownTrigger = host.shadowRoot.querySelector('.dropdown-trigger');
                 if (dropdownTrigger && !event.composedPath().includes(dropdownTrigger)) {
@@ -177,7 +259,7 @@ export const ViraPopUpTrigger = defineViraElement()({
             triggerPopUpState({
                 open,
                 callback(showPopUpResult) {
-                    updateState({ showPopUpResult });
+                    updateState({showPopUpResult});
                     if (emitEvent) {
                         dispatch(new events.openChange(showPopUpResult));
                     }
@@ -186,53 +268,60 @@ export const ViraPopUpTrigger = defineViraElement()({
                 popUpManager: state.popUpManager,
             });
         }
+
         if (inputs.isDisabled) {
-            triggerPopUp({ open: false, emitEvent: false }, undefined);
-        }
-        else if (inputs.z_debug_forceOpenState != undefined) {
+            triggerPopUp({open: false, emitEvent: false}, undefined);
+        } else if (inputs.z_debug_forceOpenState != undefined) {
             if (!inputs.z_debug_forceOpenState && state.showPopUpResult) {
-                triggerPopUp({ emitEvent: false, open: false }, undefined);
-            }
-            else if (inputs.z_debug_forceOpenState && !state.showPopUpResult) {
-                triggerPopUp({ emitEvent: false, open: true }, undefined);
+                triggerPopUp({emitEvent: false, open: false}, undefined);
+            } else if (inputs.z_debug_forceOpenState && !state.showPopUpResult) {
+                triggerPopUp({emitEvent: false, open: true}, undefined);
             }
         }
+
         /**
          * Resolve the effective horizontal anchor. For Auto, use the popRight calculation from
          * showPopUpResult to determine whether to anchor left or right.
          */
-        const effectiveHorizontalAnchor = inputs.horizontalAnchor === HorizontalAnchor.Auto ||
+        const effectiveHorizontalAnchor: HorizontalAnchor =
+            inputs.horizontalAnchor === HorizontalAnchor.Auto ||
             inputs.horizontalAnchor === undefined
-            ? state.showPopUpResult?.popRight
-                ? HorizontalAnchor.Left
-                : HorizontalAnchor.Right
-            : inputs.horizontalAnchor;
-        const leftCss = effectiveHorizontalAnchor === HorizontalAnchor.Right && state.showPopUpResult
-            ? inputs.ignoreMaxWidth
-                ? css `
+                ? state.showPopUpResult?.popRight
+                    ? HorizontalAnchor.Left
+                    : HorizontalAnchor.Right
+                : inputs.horizontalAnchor;
+
+        const leftCss =
+            effectiveHorizontalAnchor === HorizontalAnchor.Right && state.showPopUpResult
+                ? inputs.ignoreMaxWidth
+                    ? css`
                           left: unset;
                       `
-                : css `
+                    : css`
                           left: -${state.showPopUpResult.positions.diff.left}px;
                       `
-            : css `
+                : css`
                       left: ${inputs.popUpOffset?.left || 0}px;
                   `;
-        const rightCss = state.showPopUpResult && effectiveHorizontalAnchor === HorizontalAnchor.Left
-            ? inputs.ignoreMaxWidth
-                ? css `
+
+        const rightCss =
+            state.showPopUpResult && effectiveHorizontalAnchor === HorizontalAnchor.Left
+                ? inputs.ignoreMaxWidth
+                    ? css`
                           right: unset;
                       `
-                : css `
+                    : css`
                           right: -${state.showPopUpResult.positions.diff.right}px;
                       `
-            : css `
+                : css`
                       right: ${inputs.popUpOffset?.right || 0}px;
                   `;
-        const horizontalPositionStyle = css `
+
+        const horizontalPositionStyle = css`
             ${leftCss}
             ${rightCss}
         `;
+
         /**
          * These styles do _not_ account for window resizing while the menu is open. I decided this
          * was not a major enough problem to tackle. If it becomes major enough in the future,
@@ -242,72 +331,75 @@ export const ViraPopUpTrigger = defineViraElement()({
         const positionerStyles = state.showPopUpResult
             ? state.showPopUpResult.popDown
                 ? /** Dropdown going down position. */
-                    inputs.ignoreMaxHeight
-                        ? css `
+                  inputs.ignoreMaxHeight
+                    ? css`
                           bottom: unset;
                           top: calc(100% + ${inputs.popUpOffset?.vertical || 0}px);
                           ${horizontalPositionStyle}
                       `
-                        : css `
+                    : css`
                           bottom: -${state.showPopUpResult.positions.diff.bottom}px;
                           top: calc(100% + ${inputs.popUpOffset?.vertical || 0}px);
                           ${horizontalPositionStyle}
                       `
                 : /** Dropdown going up position. */
-                    inputs.ignoreMaxHeight
-                        ? css `
+                  inputs.ignoreMaxHeight
+                  ? css`
                         top: unset;
                         bottom: calc(100% + ${inputs.popUpOffset?.vertical || 0}px);
                         ${horizontalPositionStyle}
                     `
-                        : css `
+                  : css`
                         top: -${state.showPopUpResult.positions.diff.top}px;
                         bottom: calc(100% + ${inputs.popUpOffset?.vertical || 0}px);
                         ${horizontalPositionStyle}
                     `
             : undefined;
-        function respondToClick(event) {
-            triggerPopUp({ emitEvent: true, open: !state.showPopUpResult }, event);
+
+        function respondToClick(event: Event) {
+            triggerPopUp({emitEvent: true, open: !state.showPopUpResult}, event);
         }
-        return html `
+
+        return html`
             <button
                 ?disabled=${!!inputs.isDisabled}
                 class="dropdown-wrapper ${classMap({
-            open: !!state.showPopUpResult,
-            'open-upwards': !state.showPopUpResult?.popDown,
-        })}"
+                    open: !!state.showPopUpResult,
+                    'open-upwards': !state.showPopUpResult?.popDown,
+                })}"
                 role="listbox"
                 aria-expanded=${!!state.showPopUpResult}
                 ${listen('keydown', (event) => {
-            if (!state.showPopUpResult && event.code.startsWith('Arrow')) {
-                triggerPopUp({ emitEvent: true, open: true }, event);
-            }
-        })}
-                ${listen('click', (event) => {
-            /** Detail is 0 if it was a keyboard key (like Enter) that triggered this click. */
-            if (event.detail === 0) {
-                let isTextActiveElement = false;
-                walkActiveElement(({ element }) => {
-                    if (isInputLikeElement(element)) {
-                        isTextActiveElement = true;
-                        return true;
+                    if (!state.showPopUpResult && event.code.startsWith('Arrow')) {
+                        triggerPopUp({emitEvent: true, open: true}, event);
                     }
-                    else {
-                        return false;
+                })}
+                ${listen('click', (event) => {
+                    /** Detail is 0 if it was a keyboard key (like Enter) that triggered this click. */
+                    if (event.detail === 0) {
+                        let isTextActiveElement = false as boolean;
+
+                        walkActiveElement(({element}) => {
+                            if (isInputLikeElement(element)) {
+                                isTextActiveElement = true;
+                                return true;
+                            } else {
+                                return false;
+                            }
+                        });
+                        if (isTextActiveElement) {
+                            return;
+                        }
+
+                        respondToClick(event);
                     }
-                });
-                if (isTextActiveElement) {
-                    return;
-                }
-                respondToClick(event);
-            }
-        })}
+                })}
                 ${listen('mousedown', (event) => {
-            /** Ignore any clicks that aren't the main button. */
-            if (event.button === 0) {
-                respondToClick(event);
-            }
-        })}
+                    /** Ignore any clicks that aren't the main button. */
+                    if (event.button === 0) {
+                        respondToClick(event);
+                    }
+                })}
             >
                 <div class="dropdown-trigger">
                     <slot name=${slotNames.trigger}></slot>
@@ -315,13 +407,16 @@ export const ViraPopUpTrigger = defineViraElement()({
 
                 <div
                     class="pop-up-positioner ${classMap({
-            'right-aligned': effectiveHorizontalAnchor === HorizontalAnchor.Right,
-        })}"
+                        'right-aligned': effectiveHorizontalAnchor === HorizontalAnchor.Right,
+                    })}"
                     style=${positionerStyles}
                 >
-                    ${renderIf(!!state.showPopUpResult, html `
+                    ${renderIf(
+                        !!state.showPopUpResult,
+                        html`
                             <slot name=${slotNames.popUp}></slot>
-                        `)}
+                        `,
+                    )}
                 </div>
             </button>
         `;

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

@@ -0,0 +1,173 @@
+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;
+    /**
+     * 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;
+    }
+    if (input.length > 1) {
+        return input.split('').every((singleInput) => doesMatch({input: singleInput, matcher}));
+    }
+
+    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;
+    allowed: string | RegExp | undefined;
+    blocked: string | RegExp | undefined;
+};
+
+function isAllowed({value, allowed, blocked}: IsAllowedInputs) {
+    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;
+} {
+    if (!inputs.value) {
+        return {filtered: inputs.value, blocked: ''};
+    }
+    const {filtered, blocked} = inputs.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,
+    inputBlockedCallback,
+    newValueCallback,
+}: {
+    inputs: SharedTextInputElementInputs;
+    /** The value of the input element before this listener fired. */
+    previousValue: string;
+    event: Event;
+    inputBlockedCallback: (blockedInput: string) => void;
+    newValueCallback: (newValue: string) => void;
+}) {
+    const inputElement = extractEventTarget(event, 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);
+    }
+}

package/{dist/elements/vira-bold-text.element.js → src/elements/vira-bold-text.element.ts}

@@ -1,19 +1,20 @@
-import { css, html } from 'element-vir';
-import { defineViraElement } from './define-vira-element.js';
+import {css, html} from 'element-vir';
+import {defineViraElement} from './define-vira-element.js';
+
 /**
  * Use this element to reserve space for bolded text, even if it isn't bold yet.
  *
  * @category Elements
  */
-export const ViraBoldText = defineViraElement()({
+export const ViraBoldText = defineViraElement<{bold: boolean; text: string}>()({
     tagName: 'vira-bold',
     cssVars: {
         'vira-bold-bold-weight': 'bold',
     },
     hostClasses: {
-        'vira-bold-bold': ({ inputs }) => inputs.bold,
+        'vira-bold-bold': ({inputs}) => inputs.bold,
     },
-    styles: ({ hostClasses, cssVars }) => css `
+    styles: ({hostClasses, cssVars}) => css`
         span {
             text-decoration: inherit;
             white-space: inherit;
@@ -51,8 +52,8 @@ export const ViraBoldText = defineViraElement()({
             z-index: unset;
         }
     `,
-    render({ inputs }) {
-        return html `
+    render({inputs}) {
+        return html`
             <span class="everything-wrapper">
                 <span class="bold-wrapper">
                     <span class="bold">${inputs.text}</span>