vira 28.19.4 → 28.19.6

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vira",
-    "version": "28.19.4",
+    "version": "28.19.6",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",
@@ -27,9 +27,9 @@
     },
     "sideEffects": false,
     "type": "module",
-    "main": "dist/index.js",
-    "module": "dist/index.js",
-    "types": "dist/index.d.ts",
+    "main": "src/index.ts",
+    "module": "src/index.ts",
+    "types": "src/index.ts",
     "scripts": {
         "build": "npm run docs",
         "compile": "virmator compile",
@@ -38,21 +38,21 @@
         "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.57.5",
-        "@augment-vir/common": "^31.57.5",
-        "@augment-vir/web": "^31.57.5",
-        "colorjs.io": "^0.6.0",
+        "@augment-vir/assert": "^31.59.0",
+        "@augment-vir/common": "^31.59.0",
+        "@augment-vir/web": "^31.59.0",
+        "colorjs.io": "^0.6.1",
         "date-vir": "^8.1.0",
         "device-navigation": "^4.5.5",
-        "lit-css-vars": "^3.0.11",
+        "lit-css-vars": "^3.1.1",
         "observavir": "^2.3.1",
         "page-active": "^1.0.3",
         "spa-router-vir": "^6.4.1",
-        "type-fest": "^5.3.1",
+        "type-fest": "^5.4.1",
         "typed-event-target": "^4.1.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.57.5",
+        "@augment-vir/test": "^31.59.0",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",
@@ -61,8 +61,8 @@
         "esbuild": "^0.27.2",
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
-        "theme-vir": "^28.17.0",
-        "typedoc": "^0.28.15",
+        "theme-vir": "^28.18.2",
+        "typedoc": "^0.28.16",
         "typescript": "5.9.3",
         "vite": "^7.3.1",
         "vite-tsconfig-paths": "^6.0.4"

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

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

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

@@ -0,0 +1,204 @@
+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>
+        `;
+    },
+});

package/src/elements/pop-up/pop-up-helpers.ts

@@ -0,0 +1,85 @@
+import {joinWithFinalConjunction, 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 function assertUniqueIdProps(items: ReadonlyArray<Readonly<{id: PropertyKey}>>) {
+    const usedIds = new Set<PropertyKey>();
+    const duplicateIds: PropertyKey[] = [];
+    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: Readonly<MenuItem>,
+    currentSelection: ReadonlyArray<PropertyKey> = [],
+    isMultiSelect: boolean = false,
+): PropertyKey[] {
+    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,
+}: Readonly<
+    {
+        open: boolean;
+        popUpManager: PopUpManager;
+        host: HTMLElement;
+    } & PartialWithUndefined<{
+        callback?: ((showPopUpResult: ShowPopUpResult | undefined) => void) | undefined;
+        options?: Partial<PopUpManagerOptions> | undefined;
+    }>
+>) {
+    if (open) {
+        const showPopUpResult = popUpManager.showPopUp(host, options);
+        callback?.(showPopUpResult);
+    } else {
+        popUpManager.removePopUp();
+        callback?.(undefined);
+    }
+}

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

@@ -1,6 +1,7 @@
-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/vira-menu-item.element.js → src/elements/pop-up/vira-menu-item.element.ts}

@@ -1,20 +1,37 @@
-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 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';
+
 /**
  * An element for an individual menu item.
  *
  * @category PopUp
  * @category Elements
  */
-export const ViraMenuItem = defineViraElement()({
+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;
+        }>
+    >
+>()({
     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};
@@ -53,10 +70,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>
         `;