vira 22.2.1 → 23.0.0

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

@@ -1,3 +1,24 @@
+/**
+ * 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}`;
-export declare const defineViraElement: <Inputs extends {}>() => <const TagName extends `vira-${string}`, StateInit extends {}, EventsInit extends {}, const HostClassKeys extends `${TagName}-${string}`, const CssVarKeys extends `${TagName}-${string}`, const SlotNames extends readonly string[]>(inputs: import("element-vir").VerifiedElementInit<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>) => import("element-vir").DeclarativeElementDefinition<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>, defineViraElementNoInputs: <const TagName_1 extends `vira-${string}`, Inputs_1 extends {}, StateInit_1 extends {}, EventsInit_1 extends {}, const HostClassKeys_1 extends `${TagName_1}-${string}`, const CssVarKeys_1 extends `${TagName_1}-${string}`, const SlotNames_1 extends readonly string[]>(inputs: import("element-vir").VerifiedElementNoInputsInit<TagName_1, Inputs_1, StateInit_1, EventsInit_1, HostClassKeys_1, CssVarKeys_1, SlotNames_1>) => import("element-vir").DeclarativeElementDefinition<TagName_1, Inputs_1, StateInit_1, EventsInit_1, HostClassKeys_1, CssVarKeys_1, SlotNames_1>;
+/**
+ * Define a vira element with custom requirements (like the `vira-` element tag prefix).
+ *
+ * @category Internal
+ */
+export declare const defineViraElement: <Inputs extends {}>() => <const TagName extends `vira-${string}`, StateInit extends {}, EventsInit extends {}, const HostClassKeys extends `${TagName}-${string}` = `${TagName}-`, const CssVarKeys extends `${TagName}-${string}` = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = readonly []>(inputs: import("element-vir").VerifiedElementInit<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>) => import("element-vir").DeclarativeElementDefinition<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+/**
+ * Define a vira element with custom requirements (like the `vira-` element tag prefix).
+ *
+ * @category Internal
+ */
+export declare const defineViraElementNoInputs: <const TagName extends `vira-${string}`, Inputs extends {}, StateInit extends {}, EventsInit extends {}, const HostClassKeys extends `${TagName}-${string}` = `${TagName}-`, const CssVarKeys extends `${TagName}-${string}` = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = readonly []>(inputs: import("element-vir").VerifiedElementNoInputsInit<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>) => import("element-vir").DeclarativeElementDefinition<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;

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

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

package/dist/elements/dropdown/dropdown-helpers.d.ts

@@ -1,14 +1,37 @@
-import { PopUpManager, ShowPopUpResult } from '../../util/pop-up-manager';
-import { ViraDropdownOption } from './vira-dropdown-item.element';
+import { PopUpManager, ShowPopUpResult } from '../../util/pop-up-manager.js';
+import { ViraDropdownOption } from './vira-dropdown-item.element.js';
+/**
+ * Filters an array of {@link ViraDropdownOption} based on the given selection.
+ *
+ * @category Internal
+ */
 export declare function filterToSelectedOptions({ selected, options, isMultiSelect, }: Readonly<{
     selected: ReadonlyArray<PropertyKey>;
     isMultiSelect?: boolean | undefined;
     options: ReadonlyArray<Readonly<ViraDropdownOption>>;
 }>): ViraDropdownOption[];
+/**
+ * Verifies that all options have unique ids.
+ *
+ * @category Internal
+ */
 export declare function assertUniqueIdProps(options: ReadonlyArray<Readonly<{
     id: PropertyKey;
 }>>): void;
-export declare function createNewSelection(id: PropertyKey, currentSelection: ReadonlyArray<PropertyKey>, isMultiSelect: boolean): PropertyKey[];
+/**
+ * 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 createNewSelection(
+/** The id of the option that should be newly selected. */
+id: PropertyKey, currentSelection: ReadonlyArray<PropertyKey>, isMultiSelect: boolean): PropertyKey[];
+/**
+ * Handles toggles pop up state for `ViraDropdown`.
+ *
+ * @category Internal
+ */
 export declare function triggerPopUpState({ open, emitEvent }: {
     open: boolean;
     emitEvent: boolean;

package/dist/elements/dropdown/dropdown-helpers.js

@@ -1,10 +1,14 @@
 import { joinWithFinalConjunction } from '@augment-vir/common';
-import { ViraDropdown } from './vira-dropdown.element';
+/**
+ * Filters an array of {@link ViraDropdownOption} based on the given selection.
+ *
+ * @category Internal
+ */
 export function filterToSelectedOptions({ selected, options, isMultiSelect, }) {
     if (selected.length && options.length) {
         const selectedOptions = options.filter((option) => selected.includes(option.id));
         if (selectedOptions.length > 1 && !isMultiSelect) {
-            console.error(`${ViraDropdown.tagName} has multiple selections but \`isMultiSelect\` is not \`true\`. Truncating to the first selection.`);
+            console.error(`vira-dropdown has multiple selections but \`isMultiSelect\` is not \`true\`. Truncating to the first selection.`);
             return selectedOptions.slice(0, 1);
         }
         else {
@@ -15,6 +19,11 @@ export function filterToSelectedOptions({ selected, options, isMultiSelect, }) {
         return [];
     }
 }
+/**
+ * Verifies that all options have unique ids.
+ *
+ * @category Internal
+ */
 export function assertUniqueIdProps(options) {
     const usedIds = new Set();
     const duplicateIds = [];
@@ -30,7 +39,16 @@ export function assertUniqueIdProps(options) {
         throw new Error(`Duplicate option ids were given to ViraDropdown: ${joinWithFinalConjunction(duplicateIds)}`);
     }
 }
-export function createNewSelection(id, currentSelection, isMultiSelect) {
+/**
+ * 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 createNewSelection(
+/** The id of the option that should be newly selected. */
+id, currentSelection, isMultiSelect) {
+    // eslint-disable-next-line sonarjs/no-selector-parameter
     if (isMultiSelect) {
         return currentSelection.includes(id)
             ? currentSelection.filter((entry) => entry !== id)
@@ -43,6 +61,11 @@ export function createNewSelection(id, currentSelection, isMultiSelect) {
         return [id];
     }
 }
+/**
+ * Handles toggles pop up state for `ViraDropdown`.
+ *
+ * @category Internal
+ */
 export function triggerPopUpState({ open, emitEvent }, { updateState, popUpManager, dispatch, host, }) {
     if (open) {
         updateState({ showPopUpResult: popUpManager.showPopUp(host) });

package/dist/elements/dropdown/vira-dropdown-item.element.d.ts

@@ -1,16 +1,27 @@
-import { PartialAndUndefined } from '@augment-vir/common';
+import { PartialWithUndefined } from '@augment-vir/common';
 import { HTMLTemplateResult } from 'element-vir';
+/**
+ * An individual option for ViraDropdown.
+ *
+ * @category Dropdown
+ */
 export type ViraDropdownOption = {
     /** Each `id` must be unique across all options. */
     id: PropertyKey;
     label: string;
-} & PartialAndUndefined<{
-    disabled?: boolean | undefined;
-    hoverText?: string | undefined;
+} & PartialWithUndefined<{
+    disabled: boolean;
+    hoverText: string;
     /** An optional custom template for this option. */
-    template?: HTMLTemplateResult | undefined;
+    template: HTMLTemplateResult;
 }>;
+/**
+ * An element for an individual item in the ViraDropdown menu.
+ *
+ * @category Dropdown
+ * @category Elements
+ */
 export declare const ViraDropdownItem: import("element-vir").DeclarativeElementDefinition<"vira-dropdown-item", {
     label: string;
     selected: boolean;
-}, {}, {}, "vira-dropdown-item-selected", `vira-dropdown-item-${string}`, readonly string[]>;
+}, {}, {}, "vira-dropdown-item-selected", "vira-dropdown-item-", readonly []>;

package/dist/elements/dropdown/vira-dropdown-item.element.js

@@ -1,9 +1,15 @@
 import { css, html } from 'element-vir';
-import { Check24Icon } from '../../icons/icon-svgs/check-24.icon';
-import { noUserSelect, viraAnimationDurations } from '../../styles';
-import { viraBorders } from '../../styles/border';
-import { defineViraElement } from '../define-vira-element';
-import { ViraIcon } from '../vira-icon.element';
+import { Check24Icon } from '../../icons/icon-svgs/check-24.icon.js';
+import { viraBorders } from '../../styles/border.js';
+import { noUserSelect, viraAnimationDurations } from '../../styles/index.js';
+import { defineViraElement } from '../define-vira-element.js';
+import { ViraIcon } from '../vira-icon.element.js';
+/**
+ * An element for an individual item in the ViraDropdown menu.
+ *
+ * @category Dropdown
+ * @category Elements
+ */
 export const ViraDropdownItem = defineViraElement()({
     tagName: 'vira-dropdown-item',
     hostClasses: {
@@ -52,7 +58,7 @@ export const ViraDropdownItem = defineViraElement()({
                 ${viraBorders['vira-form-input-radius'].value} 0 0;
         }
     `,
-    renderCallback({ inputs }) {
+    render({ inputs }) {
         return html `
             <div class="option">
                 <${ViraIcon.assign({ icon: Check24Icon })}></${ViraIcon}>

package/dist/elements/dropdown/vira-dropdown-options.element.d.ts

@@ -1,7 +1,18 @@
-import { ViraDropdownOption } from './vira-dropdown-item.element';
+import { ViraDropdownOption } from './vira-dropdown-item.element.js';
+/**
+ * Test ids for {@link ViraDropdownOptions}.
+ *
+ * @category Internal
+ */
 export declare const viraDropdownOptionsTestIds: {
     option: string;
 };
+/**
+ * The dropdown menu portion of `ViraDropdown`.
+ *
+ * @category Dropdown
+ * @category Elements
+ */
 export declare const ViraDropdownOptions: import("element-vir").DeclarativeElementDefinition<"vira-dropdown-options", Readonly<{
     /** All dropdown options to show to the user. */
     options: ReadonlyArray<Readonly<ViraDropdownOption>>;
@@ -12,5 +23,5 @@ export declare const ViraDropdownOptions: import("element-vir").DeclarativeEleme
      */
     selectedOptions: ReadonlyArray<Readonly<ViraDropdownOption>>;
 }>, {}, {
-    selectionChange: import("element-vir").DefinedTypedEventNameDefinition<Readonly<ViraDropdownOption>>;
-}, `vira-dropdown-options-${string}`, `vira-dropdown-options-${string}`, readonly string[]>;
+    selectionChange: import("element-vir").DefineEvent<Readonly<ViraDropdownOption>>;
+}, "vira-dropdown-options-", "vira-dropdown-options-", readonly []>;

package/dist/elements/dropdown/vira-dropdown-options.element.js

@@ -1,14 +1,25 @@
 import { nav, navSelector } from 'device-navigation';
 import { classMap, css, defineElementEvent, html, ifDefined, listen, nothing, testId, } from 'element-vir';
-import { viraDisabledStyles } from '../../styles';
-import { viraBorders } from '../../styles/border';
-import { viraFormCssVars } from '../../styles/form-themes';
-import { viraShadows } from '../../styles/shadows';
-import { defineViraElement } from '../define-vira-element';
-import { ViraDropdownItem } from './vira-dropdown-item.element';
+import { viraBorders } from '../../styles/border.js';
+import { viraFormCssVars } from '../../styles/form-themes.js';
+import { viraDisabledStyles } from '../../styles/index.js';
+import { viraShadows } from '../../styles/shadows.js';
+import { defineViraElement } from '../define-vira-element.js';
+import { ViraDropdownItem } from './vira-dropdown-item.element.js';
+/**
+ * Test ids for {@link ViraDropdownOptions}.
+ *
+ * @category Internal
+ */
 export const viraDropdownOptionsTestIds = {
     option: 'dropdown-option',
 };
+/**
+ * The dropdown menu portion of `ViraDropdown`.
+ *
+ * @category Dropdown
+ * @category Elements
+ */
 export const ViraDropdownOptions = defineViraElement()({
     tagName: 'vira-dropdown-options',
     events: {
@@ -53,7 +64,7 @@ export const ViraDropdownOptions = defineViraElement()({
             pointer-events: auto;
         }
     `,
-    renderCallback({ inputs, dispatch, events }) {
+    render({ inputs, dispatch, events }) {
         const optionTemplates = inputs.options.map((option) => {
             const innerTemplate = option.template ||
                 html `

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

@@ -1,19 +1,31 @@
-import { PartialAndUndefined } from '@augment-vir/common';
+import { PartialWithUndefined } from '@augment-vir/common';
 import { NavController } from 'device-navigation';
-import { ViraIconSvg } from '../../icons/icon-svg';
-import { PopUpManager, ShowPopUpResult } from '../../util/pop-up-manager';
-import { ViraDropdownOption } from './vira-dropdown-item.element';
+import { ViraIconSvg } from '../../icons/icon-svg.js';
+import { PopUpManager, ShowPopUpResult } from '../../util/pop-up-manager.js';
+import { ViraDropdownOption } from './vira-dropdown-item.element.js';
+/**
+ * Test ids for {@link ViraDropdown}.
+ *
+ * @category Internal
+ */
 export declare const viraDropdownTestIds: {
     trigger: string;
     icon: string;
     prefix: string;
     options: string;
 };
+/**
+ * The main dropdown element that should be use directly.
+ *
+ * @category Dropdown
+ * @category Elements
+ * @see https://electrovir.github.io/element-vir/vira/book/elements/dropdown/vira-dropdown
+ */
 export declare const ViraDropdown: import("element-vir").DeclarativeElementDefinition<"vira-dropdown", {
     options: ReadonlyArray<Readonly<ViraDropdownOption>>;
     /** The selected id from the given options. */
     selected: ReadonlyArray<PropertyKey>;
-} & PartialAndUndefined<{
+} & PartialWithUndefined<{
     /** Text to show if nothing is selected. */
     placeholder: string;
     /**
@@ -32,6 +44,6 @@ export declare const ViraDropdown: import("element-vir").DeclarativeElementDefin
     popUpManager: PopUpManager;
     navController: NavController | undefined;
 }, {
-    selectedChange: import("element-vir").DefinedTypedEventNameDefinition<PropertyKey[]>;
-    openChange: import("element-vir").DefinedTypedEventNameDefinition<boolean>;
-}, "vira-dropdown-disabled", `vira-dropdown-${string}`, readonly string[]>;
+    selectedChange: import("element-vir").DefineEvent<PropertyKey[]>;
+    openChange: import("element-vir").DefineEvent<boolean>;
+}, "vira-dropdown-disabled", "vira-dropdown-", readonly []>;

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

@@ -1,23 +1,35 @@
+import { assert } from '@augment-vir/assert';
 import { NavController } from 'device-navigation';
 import { classMap, css, defineElementEvent, html, ifDefined, listen, perInstance, renderIf, testId, } from 'element-vir';
-import { assertInstanceOf } from 'run-time-assertions';
-import { ChevronUp24Icon } from '../../icons/index';
-import { noNativeFormStyles, noUserSelect, viraAnimationDurations, viraDisabledStyles, } from '../../styles';
-import { viraBorders } from '../../styles/border';
-import { createFocusStyles, viraFocusCssVars } from '../../styles/focus';
-import { viraFormCssVars } from '../../styles/form-themes';
-import { viraShadows } from '../../styles/shadows';
-import { HidePopUpEvent, NavSelectEvent, PopUpManager, } from '../../util/pop-up-manager';
-import { defineViraElement } from '../define-vira-element';
-import { ViraIcon } from '../vira-icon.element';
-import { assertUniqueIdProps, createNewSelection, filterToSelectedOptions, triggerPopUpState, } from './dropdown-helpers';
-import { ViraDropdownOptions } from './vira-dropdown-options.element';
+import { ChevronUp24Icon } from '../../icons/index.js';
+import { viraBorders } from '../../styles/border.js';
+import { createFocusStyles, viraFocusCssVars } from '../../styles/focus.js';
+import { viraFormCssVars } from '../../styles/form-themes.js';
+import { noNativeFormStyles, noUserSelect, viraAnimationDurations, viraDisabledStyles, } from '../../styles/index.js';
+import { viraShadows } from '../../styles/shadows.js';
+import { HidePopUpEvent, NavSelectEvent, PopUpManager, } from '../../util/pop-up-manager.js';
+import { defineViraElement } from '../define-vira-element.js';
+import { ViraIcon } from '../vira-icon.element.js';
+import { assertUniqueIdProps, createNewSelection, filterToSelectedOptions, triggerPopUpState, } from './dropdown-helpers.js';
+import { ViraDropdownOptions } from './vira-dropdown-options.element.js';
+/**
+ * Test ids for {@link ViraDropdown}.
+ *
+ * @category Internal
+ */
 export const viraDropdownTestIds = {
     trigger: 'dropdown-trigger',
     icon: 'dropdown-icon',
     prefix: 'dropdown-prefix',
     options: 'dropdown-options',
 };
+/**
+ * The main dropdown element that should be use directly.
+ *
+ * @category Dropdown
+ * @category Elements
+ * @see https://electrovir.github.io/element-vir/vira/book/elements/dropdown/vira-dropdown
+ */
 export const ViraDropdown = defineViraElement()({
     tagName: 'vira-dropdown',
     hostClasses: {
@@ -148,16 +160,16 @@ export const ViraDropdown = defineViraElement()({
         popUpManager: perInstance(() => new PopUpManager()),
         navController: undefined,
     },
-    cleanupCallback({ state, updateState }) {
+    cleanup({ state, updateState }) {
         updateState({ showPopUpResult: undefined });
         state.popUpManager.destroy();
     },
-    initCallback({ state, updateState, host, inputs, dispatch, events }) {
+    init({ state, updateState, host, inputs, dispatch, events }) {
         state.popUpManager.listen(HidePopUpEvent, () => {
             updateState({ showPopUpResult: undefined });
             if (!inputs.isDisabled) {
                 const dropdownWrapper = host.shadowRoot.querySelector('.dropdown-wrapper');
-                assertInstanceOf(dropdownWrapper, HTMLButtonElement, 'failed to find dropdown wrapper child');
+                assert.instanceOf(dropdownWrapper, HTMLButtonElement, 'failed to find dropdown wrapper child');
                 dropdownWrapper.focus();
             }
         });
@@ -182,7 +194,7 @@ export const ViraDropdown = defineViraElement()({
         });
         updateState({ navController: new NavController(host) });
     },
-    renderCallback({ dispatch, events, state, inputs, updateState, host }) {
+    render({ dispatch, events, state, inputs, updateState, host }) {
         assertUniqueIdProps(inputs.options);
         function triggerPopUp(param) {
             triggerPopUpState(param, {

package/dist/elements/index.d.ts

@@ -1,11 +1,11 @@
 /** This file is automatically updated by update-index-exports.ts */
-export * from './define-vira-element';
-export * from './dropdown/vira-dropdown-item.element';
-export * from './dropdown/vira-dropdown-options.element';
-export * from './dropdown/vira-dropdown.element';
-export * from './vira-button.element';
-export * from './vira-collapsible-wrapper.element';
-export * from './vira-icon.element';
-export * from './vira-image.element';
-export * from './vira-input.element';
-export * from './vira-link.element';
+export * from './define-vira-element.js';
+export * from './dropdown/vira-dropdown-item.element.js';
+export * from './dropdown/vira-dropdown-options.element.js';
+export * from './dropdown/vira-dropdown.element.js';
+export * from './vira-button.element.js';
+export * from './vira-collapsible-wrapper.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';

package/dist/elements/index.js

@@ -1,11 +1,11 @@
 /** This file is automatically updated by update-index-exports.ts */
-export * from './define-vira-element';
-export * from './dropdown/vira-dropdown-item.element';
-export * from './dropdown/vira-dropdown-options.element';
-export * from './dropdown/vira-dropdown.element';
-export * from './vira-button.element';
-export * from './vira-collapsible-wrapper.element';
-export * from './vira-icon.element';
-export * from './vira-image.element';
-export * from './vira-input.element';
-export * from './vira-link.element';
+export * from './define-vira-element.js';
+export * from './dropdown/vira-dropdown-item.element.js';
+export * from './dropdown/vira-dropdown-options.element.js';
+export * from './dropdown/vira-dropdown.element.js';
+export * from './vira-button.element.js';
+export * from './vira-collapsible-wrapper.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';

package/dist/elements/shared-text-input-logic.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Inputs shared between the multiple input elements.
+ *
+ * @category Internal
+ */
 export type SharedTextInputElementInputs = {
     value: string;
     /** Shown when no other text is present. Input restrictions do not apply to this property. */
@@ -19,15 +24,30 @@ export type SharedTextInputElementInputs = {
     /** Set this to true to make the whole element size to only fit the input text. */
     fitText?: boolean;
 };
+/**
+ * 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;
 };
+/**
+ * Filters out blocked text from an input element's value.
+ *
+ * @category Internal
+ */
 export declare function filterTextInputValue(inputs: IsAllowedInputs): {
     filtered: string;
     blocked: string;
 };
+/**
+ * A function to be called when an input element's value changes.
+ *
+ * @category Internal
+ */
 export declare function textInputListener({ inputs, filteredValue, event, inputBlockedCallback, newValueCallback, }: {
     inputs: SharedTextInputElementInputs;
     filteredValue: string;

package/dist/elements/shared-text-input-logic.js

@@ -1,4 +1,4 @@
-import { extractEventTarget } from '@augment-vir/browser';
+import { extractEventTarget } from '@augment-vir/web';
 function doesMatch({ input, matcher }) {
     if (!input || !matcher) {
         return true;
@@ -28,6 +28,11 @@ function isAllowed({ value, allowed, blocked }) {
         : false;
     return isAllowedCharacter && !isBlockedCharacter;
 }
+/**
+ * Filters out blocked text from an input element's value.
+ *
+ * @category Internal
+ */
 export function filterTextInputValue(inputs) {
     if (!inputs.value) {
         return { filtered: inputs.value, blocked: '' };
@@ -50,9 +55,14 @@ export function filterTextInputValue(inputs) {
         blocked: blocked.join(''),
     };
 }
+/**
+ * A function to be called when an input element's value changes.
+ *
+ * @category Internal
+ */
 export function textInputListener({ inputs, filteredValue, event, inputBlockedCallback, newValueCallback, }) {
     if (!(event instanceof InputEvent)) {
-        throw new Error('Text input event was not an InputEvent.');
+        throw new TypeError('Text input event was not an InputEvent.');
     }
     const inputElement = extractEventTarget(event, HTMLInputElement);
     /**
@@ -62,7 +72,7 @@ export function textInputListener({ inputs, filteredValue, event, inputBlockedCa
     const changedText = event.data;
     const beforeChangeText = filteredValue;
     // this will be overwritten below if blocked characters are encountered
-    let finalText = inputElement.value ?? '';
+    let finalText = inputElement.value;
     /**
      * When changedText is falsy, that means an operation other than inserting characters happened.
      * Such as: deleting, cutting the text, etc.

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

@@ -1,11 +1,23 @@
-import { ViraIconSvg } from '../icons';
-export declare enum ViraButtonStyleEnum {
+import { ViraIconSvg } from '../icons/index.js';
+/**
+ * Button styles available for {@link ViraButton}.
+ *
+ * @category Button
+ */
+export declare enum ViraButtonStyle {
     Default = "vira-button-default",
     Outline = "vira-button-outline"
 }
+/**
+ * A custom button with default styling.
+ *
+ * @category Button
+ * @category Elements
+ * @see https://electrovir.github.io/element-vir/vira/book/elements/vira-button
+ */
 export declare const ViraButton: import("element-vir").DeclarativeElementDefinition<"vira-button", {
     text?: string;
-    icon?: undefined | Pick<ViraIconSvg, 'svgTemplate'>;
+    icon?: undefined | Pick<ViraIconSvg, "svgTemplate">;
     disabled?: boolean | undefined;
-    buttonStyle?: ViraButtonStyleEnum | undefined;
-}, {}, {}, "vira-button-outline-style" | "vira-button-disabled", "vira-button-primary-color" | "vira-button-primary-hover-color" | "vira-button-primary-active-color" | "vira-button-secondary-color" | "vira-button-padding" | "vira-button-internal-foreground-color" | "vira-button-internal-background-color", readonly string[]>;
+    buttonStyle?: ViraButtonStyle | undefined;
+}, {}, {}, "vira-button-outline-style" | "vira-button-disabled", "vira-button-primary-color" | "vira-button-primary-hover-color" | "vira-button-primary-active-color" | "vira-button-secondary-color" | "vira-button-padding" | "vira-button-internal-foreground-color" | "vira-button-internal-background-color", readonly []>;

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

@@ -1,21 +1,33 @@
 import { css, html } from 'element-vir';
-import { noUserSelect } from '../styles';
-import { viraBorders } from '../styles/border';
-import { viraDisabledStyles } from '../styles/disabled';
-import { viraAnimationDurations } from '../styles/durations';
-import { createFocusStyles, viraFocusCssVars } from '../styles/focus';
-import { noNativeFormStyles } from '../styles/native-styles';
-import { defineViraElement } from './define-vira-element';
-import { ViraIcon } from './vira-icon.element';
-export var ViraButtonStyleEnum;
-(function (ViraButtonStyleEnum) {
-    ViraButtonStyleEnum["Default"] = "vira-button-default";
-    ViraButtonStyleEnum["Outline"] = "vira-button-outline";
-})(ViraButtonStyleEnum || (ViraButtonStyleEnum = {}));
+import { viraBorders } from '../styles/border.js';
+import { viraDisabledStyles } from '../styles/disabled.js';
+import { viraAnimationDurations } from '../styles/durations.js';
+import { createFocusStyles, viraFocusCssVars } from '../styles/focus.js';
+import { noUserSelect } from '../styles/index.js';
+import { noNativeFormStyles } from '../styles/native-styles.js';
+import { defineViraElement } from './define-vira-element.js';
+import { ViraIcon } from './vira-icon.element.js';
+/**
+ * Button styles available for {@link ViraButton}.
+ *
+ * @category Button
+ */
+export var ViraButtonStyle;
+(function (ViraButtonStyle) {
+    ViraButtonStyle["Default"] = "vira-button-default";
+    ViraButtonStyle["Outline"] = "vira-button-outline";
+})(ViraButtonStyle || (ViraButtonStyle = {}));
+/**
+ * A custom button with default styling.
+ *
+ * @category Button
+ * @category Elements
+ * @see https://electrovir.github.io/element-vir/vira/book/elements/vira-button
+ */
 export const ViraButton = defineViraElement()({
     tagName: 'vira-button',
     hostClasses: {
-        'vira-button-outline-style': ({ inputs }) => inputs.buttonStyle === ViraButtonStyleEnum.Outline,
+        'vira-button-outline-style': ({ inputs }) => inputs.buttonStyle === ViraButtonStyle.Outline,
         'vira-button-disabled': ({ inputs }) => !!inputs.disabled,
     },
     cssVars: {
@@ -95,7 +107,7 @@ export const ViraButton = defineViraElement()({
             margin-left: 8px;
         }
     `,
-    renderCallback: ({ inputs }) => {
+    render: ({ inputs }) => {
         const iconTemplate = inputs.icon
             ? html `
                   <${ViraIcon.assign({