vira 28.19.6 → 28.20.0

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

@@ -0,0 +1,18 @@
+/**
+ * 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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,100 @@
+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

@@ -0,0 +1,60 @@
+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

@@ -0,0 +1,35 @@
+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 []>;

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

@@ -0,0 +1,151 @@
+import { getObjectTypedEntries } 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, 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()({
+    tagName: 'vira-form',
+    events: {
+        valueChange: defineElementEvent(),
+        validChange: defineElementEvent(),
+    },
+    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>
+        `;
+    },
+});

package/dist/elements/index.js

@@ -0,0 +1,25 @@
+export * from './define-vira-element.js';
+export * from './form/vira-form-fields.js';
+export * from './form/vira-form.element.js';
+export * from './pop-up/pop-up-helpers.js';
+export * from './pop-up/pop-up-menu-item.js';
+export * from './pop-up/vira-menu-item.element.js';
+export * from './pop-up/vira-menu-trigger.element.js';
+export * from './pop-up/vira-menu.element.js';
+export * from './pop-up/vira-pop-up-menu.element.js';
+export * from './pop-up/vira-pop-up-trigger.element.js';
+export * from './vira-bold-text.element.js';
+export * from './vira-button.element.js';
+export * from './vira-card.element.js';
+export * from './vira-checkbox.element.js';
+export * from './vira-collapsible-wrapper.element.js';
+export * from './vira-dropdown.element.js';
+export * from './vira-error.element.js';
+export * from './vira-icon.element.js';
+export * from './vira-image.element.js';
+export * from './vira-input.element.js';
+export * from './vira-link.element.js';
+export * from './vira-modal.element.js';
+export * from './vira-overflow-switch.element.js';
+export * from './vira-progress.element.js';
+export * from './vira-select.element.js';

package/dist/elements/pop-up/pop-up-helpers.d.ts

@@ -0,0 +1,33 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type PopUpManager, type PopUpManagerOptions, type ShowPopUpResult } from '../../util/pop-up-manager.js';
+import { type MenuItem } from './pop-up-menu-item.js';
+/**
+ * Verifies that all items have unique ids.
+ *
+ * @category Internal
+ */
+export declare function assertUniqueIdProps(items: ReadonlyArray<Readonly<{
+    id: PropertyKey;
+}>>): void;
+/**
+ * Creates a new array of selections based on the current selection and new selection id. This
+ * behaves differently when multi select is enabled, hence this function.
+ *
+ * @category Internal
+ */
+export declare function updateSelectedItems(
+/** The item that should be newly toggled. */
+newItem: Readonly<MenuItem>, currentSelection?: ReadonlyArray<PropertyKey>, isMultiSelect?: boolean): PropertyKey[];
+/**
+ * Handles toggling pop up state for `ViraDropdown`.
+ *
+ * @category Internal
+ */
+export declare function triggerPopUpState({ open, callback, popUpManager, host, options, }: Readonly<{
+    open: boolean;
+    popUpManager: PopUpManager;
+    host: HTMLElement;
+} & PartialWithUndefined<{
+    callback?: ((showPopUpResult: ShowPopUpResult | undefined) => void) | undefined;
+    options?: Partial<PopUpManagerOptions> | undefined;
+}>>): void;

package/dist/elements/pop-up/pop-up-helpers.js

@@ -0,0 +1,58 @@
+import { joinWithFinalConjunction } from '@augment-vir/common';
+/**
+ * Verifies that all items have unique ids.
+ *
+ * @category Internal
+ */
+export function assertUniqueIdProps(items) {
+    const usedIds = new Set();
+    const duplicateIds = [];
+    items.forEach((option) => {
+        if (usedIds.has(option.id)) {
+            duplicateIds.push(option.id);
+        }
+        else {
+            usedIds.add(option.id);
+        }
+    });
+    if (duplicateIds.length) {
+        throw new Error(`Duplicate option ids were given: ${joinWithFinalConjunction(duplicateIds)}`);
+    }
+}
+/**
+ * Creates a new array of selections based on the current selection and new selection id. This
+ * behaves differently when multi select is enabled, hence this function.
+ *
+ * @category Internal
+ */
+export function updateSelectedItems(
+/** The item that should be newly toggled. */
+newItem, currentSelection = [], isMultiSelect = false) {
+    if (isMultiSelect) {
+        return currentSelection.includes(newItem.id)
+            ? currentSelection.filter((entry) => entry !== newItem.id)
+            : [
+                ...currentSelection,
+                newItem.id,
+            ];
+    }
+    else {
+        /** In single select, only the toggled item is allowed. */
+        return [newItem.id];
+    }
+}
+/**
+ * Handles toggling pop up state for `ViraDropdown`.
+ *
+ * @category Internal
+ */
+export function triggerPopUpState({ open, callback, popUpManager, host, options, }) {
+    if (open) {
+        const showPopUpResult = popUpManager.showPopUp(host, options);
+        callback?.(showPopUpResult);
+    }
+    else {
+        popUpManager.removePopUp();
+        callback?.(undefined);
+    }
+}

package/{src/elements/pop-up/pop-up-menu-item.ts → dist/elements/pop-up/pop-up-menu-item.d.ts}

@@ -1,7 +1,6 @@
-import {type PartialWithUndefined} from '@augment-vir/common';
-import {type HTMLTemplateResult} from 'element-vir';
-import {type ViraLinkRoute} from '../vira-link.element.js';
-
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type HTMLTemplateResult } from 'element-vir';
+import { type ViraLinkRoute } from '../vira-link.element.js';
 /**
  * An individual menu item consumed partially by `ViraMenuItem` and used by `ViraMenu`.
  *

package/dist/elements/pop-up/pop-up-menu-item.js

@@ -0,0 +1 @@
+export {};

package/dist/elements/pop-up/vira-menu-item.element.d.ts

@@ -0,0 +1,19 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type MenuItem } from './pop-up-menu-item.js';
+/**
+ * An element for an individual menu item.
+ *
+ * @category PopUp
+ * @category Elements
+ */
+export declare const ViraMenuItem: import("element-vir").DeclarativeElementDefinition<"vira-menu-item", Readonly<{
+    selected: boolean;
+} & PartialWithUndefined<{
+    /**
+     * The text to show in the menu item. If this is not provided, it is expected that you
+     * will instead utilize this element's `<slot>`.
+     */
+    label: MenuItem["label"];
+    /** If `true`, does not render the selected check icon. */
+    hideCheckIcon: boolean;
+}>>, {}, {}, "vira-menu-item-selected", "vira-menu-item-", readonly [], readonly []>;

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

@@ -1,37 +1,20 @@
-import {type PartialWithUndefined} from '@augment-vir/common';
-import {css, html} from 'element-vir';
-import {Check24Icon} from '../../icons/icon-svgs/check-24.icon.js';
-import {noUserSelect} from '../../styles/index.js';
-import {defineViraElement} from '../define-vira-element.js';
-import {ViraIcon} from '../vira-icon.element.js';
-import {type MenuItem} from './pop-up-menu-item.js';
-
+import { css, html } from 'element-vir';
+import { Check24Icon } from '../../icons/icon-svgs/check-24.icon.js';
+import { noUserSelect } from '../../styles/index.js';
+import { defineViraElement } from '../define-vira-element.js';
+import { ViraIcon } from '../vira-icon.element.js';
 /**
  * An element for an individual menu item.
  *
  * @category PopUp
  * @category Elements
  */
-export const ViraMenuItem = defineViraElement<
-    Readonly<
-        {
-            selected: boolean;
-        } & PartialWithUndefined<{
-            /**
-             * The text to show in the menu item. If this is not provided, it is expected that you
-             * will instead utilize this element's `<slot>`.
-             */
-            label: MenuItem['label'];
-            /** If `true`, does not render the selected check icon. */
-            hideCheckIcon: boolean;
-        }>
-    >
->()({
+export const ViraMenuItem = defineViraElement()({
     tagName: 'vira-menu-item',
     hostClasses: {
-        'vira-menu-item-selected': ({inputs}) => !inputs.hideCheckIcon && inputs.selected,
+        'vira-menu-item-selected': ({ inputs }) => !inputs.hideCheckIcon && inputs.selected,
     },
-    styles: ({hostClasses}) => css`
+    styles: ({ hostClasses }) => css `
         :host {
             display: flex;
             ${noUserSelect};
@@ -70,10 +53,10 @@ export const ViraMenuItem = defineViraElement<
             visibility: hidden;
         }
     `,
-    render({inputs}) {
-        return html`
+    render({ inputs }) {
+        return html `
             <div class="item">
-                <${ViraIcon.assign({icon: Check24Icon})}></${ViraIcon}>
+                <${ViraIcon.assign({ icon: Check24Icon })}></${ViraIcon}>
                 <slot>${inputs.label}</slot>
             </div>
         `;

package/dist/elements/pop-up/vira-menu-trigger.element.d.ts

@@ -0,0 +1,41 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type NavController } from 'device-navigation';
+import { type PopUpManager, type ShowPopUpResult } from '../../util/pop-up-manager.js';
+import { type MenuItem } from './pop-up-menu-item.js';
+import { type PopUpMenuCornerStyle } from './vira-pop-up-menu.element.js';
+import { type PopUpOffset, type PopUpTriggerPosition } from './vira-pop-up-trigger.element.js';
+/**
+ * Test ids for {@link ViraMenuTrigger}.
+ *
+ * @category Internal
+ */
+export declare const viraMenuTriggerTestIds: {
+    menu: string;
+};
+/**
+ * A more specific wrapper of `ViraPopUpTrigger` that always opens a menu.
+ *
+ * @category PopUp
+ * @category Elements
+ */
+export declare const ViraMenuTrigger: import("element-vir").DeclarativeElementDefinition<"vira-menu-trigger", {
+    items: ReadonlyArray<Readonly<MenuItem>>;
+} & PartialWithUndefined<{
+    /** The selected item ids from the given `items` object. */
+    selected: ReadonlyArray<PropertyKey>;
+    isDisabled: boolean;
+    isMultiSelect: boolean;
+    z_debug_forceOpenState: boolean;
+    popUpOffset: PopUpOffset;
+    /** Hide menu item check mark icons. */
+    hideCheckIcons: boolean;
+    menuCornerStyle: PopUpMenuCornerStyle;
+} & PopUpTriggerPosition>, {
+    navController: undefined | NavController;
+    popUpManager: undefined | PopUpManager;
+    /** `undefined` means the pop up is not currently showing. */
+    showPopUpResult: ShowPopUpResult | undefined;
+}, {
+    itemActivate: import("element-vir").DefineEvent<PropertyKey[]>;
+    openChange: import("element-vir").DefineEvent<ShowPopUpResult | undefined>;
+}, "vira-menu-trigger-", "vira-menu-trigger-", readonly [], readonly []>;