vira 32.0.0-beta.0 → 32.0.0

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

@@ -1,9 +1,8 @@
-import {clamp, type PartialWithUndefined} from '@augment-vir/common';
-import {applyAttributes} from 'device-navigation';
-import {css, html} from 'element-vir';
-import {viraFormCssVars} from '../styles/form-styles.js';
-import {defineViraElement} from '../util/define-vira-element.js';
-
+import { clamp } from '@augment-vir/common';
+import { applyAttributes } from 'device-navigation';
+import { css, html } from 'element-vir';
+import { viraFormCssVars } from '../styles/form-styles.js';
+import { defineViraElement } from '../util/define-vira-element.js';
 /**
  * A [`<progress>`](https://developer.mozilla.org/docs/Web/HTML/Reference/Elements/progress)
  * alternative that supports custom styling in _all_ browsers via CSS vars _and_ prevents background
@@ -13,16 +12,7 @@ import {defineViraElement} from '../util/define-vira-element.js';
  * @category Elements
  * @see https://electrovir.github.io/vira/book/elements/vira-progress
  */
-export const ViraProgress = defineViraElement<
-    {
-        value: number;
-    } & PartialWithUndefined<{
-        /** @default 0 */
-        min: number;
-        /** @default 100 */
-        max: number;
-    }>
->()({
+export const ViraProgress = defineViraElement()({
     tagName: 'vira-progress',
     cssVars: {
         /**
@@ -32,8 +22,8 @@ export const ViraProgress = defineViraElement<
         'vira-progress-border-radius': '99999999px',
         'vira-progress-height': '8px',
     },
-    styles: ({cssVars}) => {
-        return css`
+    styles({ cssVars }) {
+        return css `
             :host {
                 /* Default width that can easily be overridden because it's applied on the host. */
                 width: 100px;
@@ -57,32 +47,29 @@ export const ViraProgress = defineViraElement<
             }
         `;
     },
-    render({inputs, host}) {
+    render({ inputs, host }) {
         const min = inputs.min || 0;
         const max = inputs.max || 100;
         const totalRange = max - min;
         const value = inputs.value - min;
-
         const percentFull = clamp(Math.round((value / totalRange) * 100), {
             min: 0,
             max: 100,
         });
-
         applyAttributes(host, {
             'aria-valuemin': inputs.min,
             'aria-valuemax': inputs.max,
             'aria-valuenow': inputs.value,
             'aria-role': 'progressbar',
         });
-
-        return html`
+        return html `
             <div
                 class="progress-bar"
                 style=${percentFull
-                    ? css`
+            ? css `
                           width: ${percentFull}%;
                       `
-                    : css`
+            : css `
                           display: none;
                       `}
             ></div>

package/dist/elements/vira-relative-time.element.d.ts

@@ -0,0 +1,42 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type AtLeastOneDuration, type FullDate, type Timezone } from 'date-vir';
+/**
+ * Displays a date/time as a live, relative timestamp (for example `5 minutes ago`). The relative
+ * string automatically updates over time. Optionally renders the absolute timestamp beneath the
+ * relative string.
+ *
+ * @category Time
+ * @category Elements
+ * @see https://electrovir.github.io/vira/book/elements/vira-relative-time
+ */
+export declare const ViraRelativeTime: import("element-vir").DeclarativeElementDefinition<"vira-relative-time", {
+    time: Readonly<FullDate>;
+} & PartialWithUndefined<{
+    /** When true, the absolute timestamp is rendered beneath the relative string. */
+    showAbsoluteTime: boolean;
+    /**
+     * How long before the relative time updates.
+     *
+     * @default {seconds: 5}
+     */
+    updateInterval: Readonly<AtLeastOneDuration>;
+    /**
+     * Timezone the absolute time is displayed in. Defaults to the user's timezone. Set this for
+     * values that are conceptually anchored to a specific timezone (e.g. a date-only value
+     * stored at midnight UTC), where converting to the user's timezone would shift the
+     * displayed date/time.
+     */
+    timezone: Timezone;
+}>, {
+    now: {
+        hour: import("date-vir").Hour;
+        minute: import("date-vir").Minute;
+        millisecond: number;
+        year: number;
+        month: import("date-vir").MonthNumber;
+        day: import("date-vir").DayOfMonth;
+        second: import("date-vir").Second;
+        timezone: "UTC";
+    };
+    timeoutId: undefined | ReturnType<typeof globalThis.setTimeout>;
+}, {}, "vira-relative-time-", "vira-relative-time-", readonly [], readonly []>;

package/dist/elements/vira-relative-time.element.js

@@ -0,0 +1,96 @@
+import { convertDuration, getNowInUtcTimezone, toRelativeString, } from 'date-vir';
+import { css, html, nothing } from 'element-vir';
+import { viraTheme } from '../styles/vira-color-theme.js';
+import { defineViraElement } from '../util/define-vira-element.js';
+import { formatAbsoluteTime, ViraAbsoluteTime } from './vira-absolute-time.element.js';
+/**
+ * Displays a date/time as a live, relative timestamp (for example `5 minutes ago`). The relative
+ * string automatically updates over time. Optionally renders the absolute timestamp beneath the
+ * relative string.
+ *
+ * @category Time
+ * @category Elements
+ * @see https://electrovir.github.io/vira/book/elements/vira-relative-time
+ */
+export const ViraRelativeTime = defineViraElement()({
+    tagName: 'vira-relative-time',
+    styles: css `
+        :host {
+            display: inline-flex;
+            flex-direction: column;
+            white-space: nowrap;
+        }
+
+        ${ViraAbsoluteTime} {
+            font-size: 12px;
+            color: ${viraTheme.colors['vira-grey-foreground-non-body'].foreground.value};
+        }
+    `,
+    state() {
+        return {
+            now: getNowInUtcTimezone(),
+            timeoutId: undefined,
+        };
+    },
+    init({ inputs, updateState }) {
+        /**
+         * Reschedule with a fresh timeout after each update so the delay always reflects the
+         * current `updateInterval` input.
+         */
+        function scheduleNextUpdate() {
+            const updateInterval = inputs.updateInterval || {
+                seconds: 5,
+            };
+            updateState({
+                timeoutId: globalThis.setTimeout(() => {
+                    updateState({
+                        now: getNowInUtcTimezone(),
+                    });
+                    scheduleNextUpdate();
+                }, convertDuration(updateInterval, {
+                    milliseconds: true,
+                }).milliseconds),
+            });
+        }
+        scheduleNextUpdate();
+    },
+    cleanup({ state, updateState }) {
+        globalThis.clearTimeout(state.timeoutId);
+        updateState({
+            timeoutId: undefined,
+        });
+    },
+    render({ state, inputs }) {
+        const relativeTime = toRelativeString({
+            start: state.now,
+            end: inputs.time,
+        }, {
+            years: true,
+            months: true,
+            days: true,
+            hours: true,
+            minutes: true,
+            seconds: true,
+        }, {
+            useOnlyLargestUnit: true,
+            decimalCount: 0,
+        });
+        return html `
+            <span
+                title=${formatAbsoluteTime(inputs.time, {
+            timezone: inputs.timezone,
+        })}
+            >
+                ${relativeTime}
+            </span>
+            ${inputs.showAbsoluteTime
+            ? html `
+                      <${ViraAbsoluteTime.assign({
+                time: inputs.time,
+                timezone: inputs.timezone,
+            })}></${ViraAbsoluteTime}>
+                  `
+            : nothing}
+        `;
+    },
+});

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

@@ -0,0 +1,44 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type AttributeValues } from 'element-vir';
+import { type ViraIconSvg } from '../icons/index.js';
+import { type ViraSelectOption, type ViraSelectOptionGroup } from '../util/vira-select-option.js';
+/**
+ * Similar to {@link ViraDropdown} but is, instead, simply a wrapper for `<select>` and nothing more.
+ *
+ * @category Dropdown
+ * @category Elements
+ * @see https://electrovir.github.io/vira/book/elements/vira-select
+ */
+export declare const ViraSelect: import("element-vir").DeclarativeElementDefinition<"vira-select", {
+    options: ReadonlyArray<Readonly<ViraSelectOption> | Readonly<ViraSelectOptionGroup>>;
+    /** The currently selected option value. */
+    value: undefined | string;
+} & PartialWithUndefined<{
+    icon: Readonly<ViraIconSvg>;
+    placeholder: string;
+    label: string;
+    /** If set to `true`, only minimal styles are applied. */
+    rawSelect: boolean;
+    disabled: boolean;
+    /**
+     * When `true`, the currently selected option's label is rendered as plain text with no
+     * wrapper, border, or focus styles.
+     */
+    isReadonly: boolean;
+    attributePassthrough: Readonly<PartialWithUndefined<{
+        label: AttributeValues;
+        select: AttributeValues;
+        option: AttributeValues;
+    }>>;
+    hasError: boolean;
+}>, {
+    /**
+     * Used to couple the label and select together. This is not applied if no label is
+     * provided.
+     */
+    randomId: string;
+    /** Removes event listeners registered during init. */
+    cleanupListeners: undefined | (() => void);
+}, {
+    valueChange: import("element-vir").DefineElementEvent<string>;
+}, "vira-select-disabled" | "vira-select-error" | "vira-select-has-label" | "vira-select-not-raw" | "vira-select-readonly", "vira-select-padding-horizontal" | "vira-select-padding-vertical" | "vira-select-icon-padding", readonly [], readonly []>;

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

@@ -1,35 +1,19 @@
-import {assertWrap} from '@augment-vir/assert';
-import {randomString, type PartialWithUndefined} from '@augment-vir/common';
-import {extractEventTarget} from '@augment-vir/web';
-import {
-    attributes,
-    classMap,
-    css,
-    defineElementEvent,
-    html,
-    ifDefined,
-    listen,
-    nothing,
-    type AttributeValues,
-} from 'element-vir';
-import {listenTo} from 'typed-event-target';
-import {ChevronUp16Icon, type ViraIconSvg} from '../icons/index.js';
-import {viraDisabledStyles} from '../styles/disabled.js';
-import {createFocusStyles} from '../styles/focus.js';
-import {viraFormCssVars} from '../styles/form-styles.js';
-import {viraAnimationDurations} from '../styles/index.js';
-import {noNativeFormStyles} from '../styles/native-styles.js';
-import {defineViraElement} from '../util/define-vira-element.js';
-import {
-    isViraSelectOptionGroup,
-    type ViraSelectOption,
-    type ViraSelectOptionGroup,
-} from '../util/vira-select-option.js';
-import {ViraDropdown} from './vira-dropdown.element.js';
-import {ViraIcon} from './vira-icon.element.js';
-
-function renderSelectOption(option: Readonly<ViraSelectOption>, value: string | undefined) {
-    return html`
+import { assertWrap } from '@augment-vir/assert';
+import { randomString } from '@augment-vir/common';
+import { extractEventTarget } from '@augment-vir/web';
+import { attributes, classMap, css, defineElementEvent, html, ifDefined, listen, nothing, } from 'element-vir';
+import { listenTo } from 'typed-event-target';
+import { ChevronUp16Icon } from '../icons/index.js';
+import { viraDisabledStyles } from '../styles/disabled.js';
+import { createFocusStyles } from '../styles/focus.js';
+import { viraFormCssVars } from '../styles/form-styles.js';
+import { viraAnimationDurations } from '../styles/index.js';
+import { noNativeFormStyles } from '../styles/native-styles.js';
+import { defineViraElement } from '../util/define-vira-element.js';
+import { isViraSelectOptionGroup, } from '../util/vira-select-option.js';
+import { ViraIcon } from './vira-icon.element.js';
+function renderSelectOption(option, value) {
+    return html `
         <option
             ?selected=${option.value === value}
             aria-label=${option.label}
@@ -40,7 +24,6 @@ function renderSelectOption(option: Readonly<ViraSelectOption>, value: string |
         </option>
     `;
 }
-
 /**
  * Similar to {@link ViraDropdown} but is, instead, simply a wrapper for `<select>` and nothing more.
  *
@@ -48,33 +31,7 @@ function renderSelectOption(option: Readonly<ViraSelectOption>, value: string |
  * @category Elements
  * @see https://electrovir.github.io/vira/book/elements/vira-select
  */
-export const ViraSelect = defineViraElement<
-    {
-        options: ReadonlyArray<Readonly<ViraSelectOption> | Readonly<ViraSelectOptionGroup>>;
-        /** The currently selected option value. */
-        value: undefined | string;
-    } & PartialWithUndefined<{
-        icon: Readonly<ViraIconSvg>;
-        placeholder: string;
-        label: string;
-        /** If set to `true`, only minimal styles are applied. */
-        rawSelect: boolean;
-        disabled: boolean;
-        /**
-         * When `true`, the currently selected option's label is rendered as plain text with no
-         * wrapper, border, or focus styles.
-         */
-        isReadonly: boolean;
-        attributePassthrough: Readonly<
-            PartialWithUndefined<{
-                label: AttributeValues;
-                select: AttributeValues;
-                option: AttributeValues;
-            }>
-        >;
-        hasError: boolean;
-    }>
->()({
+export const ViraSelect = defineViraElement()({
     tagName: 'vira-select',
     state() {
         return {
@@ -84,11 +41,11 @@ export const ViraSelect = defineViraElement<
              */
             randomId: randomString(32),
             /** Removes event listeners registered during init. */
-            cleanupListeners: undefined as undefined | (() => void),
+            cleanupListeners: undefined,
         };
     },
     events: {
-        valueChange: defineElementEvent<string>(),
+        valueChange: defineElementEvent(),
     },
     cssVars: {
         'vira-select-padding-horizontal': '12px',
@@ -96,14 +53,24 @@ export const ViraSelect = defineViraElement<
         'vira-select-icon-padding': '44px',
     },
     hostClasses: {
-        'vira-select-disabled': ({inputs}) => !!inputs.disabled,
-        'vira-select-error': ({inputs}) => !!inputs.hasError,
-        'vira-select-has-label': ({inputs}) => !!inputs.label,
-        'vira-select-not-raw': ({inputs}) => !inputs.rawSelect,
-        'vira-select-readonly': ({inputs}) => !!inputs.isReadonly,
+        'vira-select-disabled'({ inputs }) {
+            return !!inputs.disabled;
+        },
+        'vira-select-error'({ inputs }) {
+            return !!inputs.hasError;
+        },
+        'vira-select-has-label'({ inputs }) {
+            return !!inputs.label;
+        },
+        'vira-select-not-raw'({ inputs }) {
+            return !inputs.rawSelect;
+        },
+        'vira-select-readonly'({ inputs }) {
+            return !!inputs.isReadonly;
+        },
     },
-    styles: ({hostClasses, cssVars}) => {
-        return css`
+    styles({ hostClasses, cssVars }) {
+        return css `
             :host {
                 position: relative;
                 display: inline-flex;
@@ -205,9 +172,9 @@ export const ViraSelect = defineViraElement<
 
                         &:focus:focus-visible:not([aria-disabled='true']) ~ .focus-border {
                             ${createFocusStyles({
-                                elementBorderSize: '1px',
-                                noNesting: true,
-                            })}
+            elementBorderSize: '1px',
+            noNesting: true,
+        })}
                         }
                     }
 
@@ -273,31 +240,24 @@ export const ViraSelect = defineViraElement<
 
             :host(
                     .${hostClasses['vira-select-not-raw'].name}.${hostClasses['vira-select-error']
-                            .name}
+            .name}
                 )
                 .wrapper-border {
                 border-color: ${viraFormCssVars['vira-form-error-color'].value};
             }
         `;
     },
-    init({state, updateState, host}) {
+    init({ state, updateState, host }) {
         state.cleanupListeners?.();
-
         function getSelectElement() {
-            return assertWrap.instanceOf(
-                host.shadowRoot.querySelector('select'),
-                HTMLSelectElement,
-            );
+            return assertWrap.instanceOf(host.shadowRoot.querySelector('select'), HTMLSelectElement);
         }
-
         const listenerRemovers = [
             listenTo(host, 'mousedown', (event) => {
                 const selectElement = getSelectElement();
-
                 if (event.composedPath().includes(selectElement)) {
                     return;
                 }
-
                 event.preventDefault();
                 event.stopPropagation();
                 /** `showPicker` is not in Safari. */
@@ -305,7 +265,8 @@ export const ViraSelect = defineViraElement<
                 if (selectElement.showPicker) {
                     try {
                         selectElement.showPicker();
-                    } catch {
+                    }
+                    catch {
                         /**
                          * Chromium throws `NotAllowedError` when `showPicker` runs without
                          * transient user activation; the picker just won't open.
@@ -315,11 +276,9 @@ export const ViraSelect = defineViraElement<
             }),
             listenTo(host, 'click', (event) => {
                 const selectElement = getSelectElement();
-
                 if (event.composedPath().includes(selectElement)) {
                     return;
                 }
-
                 event.preventDefault();
                 event.stopPropagation();
                 /** `showPicker` is not in Safari. */
@@ -327,7 +286,8 @@ export const ViraSelect = defineViraElement<
                 if (selectElement.showPicker) {
                     try {
                         selectElement.showPicker();
-                    } catch {
+                    }
+                    catch {
                         /**
                          * Chromium throws `NotAllowedError` when `showPicker` runs without
                          * transient user activation; the picker just won't open.
@@ -336,100 +296,91 @@ export const ViraSelect = defineViraElement<
                 }
             }),
         ];
-
         updateState({
-            cleanupListeners: () => {
+            cleanupListeners() {
                 listenerRemovers.forEach((remover) => remover());
             },
         });
     },
-    cleanup({state, updateState}) {
+    cleanup({ state, updateState }) {
         state.cleanupListeners?.();
         updateState({
             cleanupListeners: undefined,
         });
     },
-    render({inputs, state, dispatch, events}) {
+    render({ inputs, state, dispatch, events }) {
         const value = inputs.value || undefined;
-
         if (inputs.isReadonly) {
             const selectedOption = inputs.options
                 .flatMap((entry) => (isViraSelectOptionGroup(entry) ? [...entry.options] : [entry]))
                 .find((option) => option.value === value);
-            const readonlyValueTemplate = html`
+            const readonlyValueTemplate = html `
                 <span class="readonly-value">
                     ${selectedOption?.label || inputs.placeholder || ''}
                 </span>
             `;
-
             if (inputs.label) {
-                return html`
+                return html `
                     <label ${attributes(inputs.attributePassthrough?.label)}>
                         <span class="select-label">${inputs.label}</span>
                         ${readonlyValueTemplate}
                     </label>
                 `;
-            } else {
+            }
+            else {
                 return readonlyValueTemplate;
             }
         }
-
-        const placeholderOptionTemplate =
-            inputs.placeholder || value == undefined
-                ? html`
+        const placeholderOptionTemplate = inputs.placeholder || value == undefined
+            ? html `
                       <option value="" disabled ?selected=${value == undefined}>
                           ${inputs.placeholder}
                       </option>
                   `
-                : nothing;
-
-        const selectTemplate = html`
+            : nothing;
+        const selectTemplate = html `
             <span class="select-wrapper">
                 <select
                     .value=${ifDefined(value)}
                     class=${classMap({
-                        placeholder: !value && !!inputs.placeholder,
-                        'with-icon': !!inputs.icon,
-                    })}
+            placeholder: !value && !!inputs.placeholder,
+            'with-icon': !!inputs.icon,
+        })}
                     tabindex=${inputs.disabled ? -1 : 0}
                     id=${ifDefined(inputs.label ? state.randomId : undefined)}
                     aria-label=${ifDefined(inputs.label || undefined)}
                     aria-disabled=${ifDefined(inputs.disabled ? 'true' : undefined)}
                     ${listen('input', (event) => {
-                        const selectElement = extractEventTarget(event, HTMLSelectElement);
-                        const newValue = selectElement.value;
-
-                        if (selectElement.value !== value) {
-                            selectElement.selectedIndex = inputs.options
-                                .flatMap((entry) => {
-                                    return isViraSelectOptionGroup(entry)
-                                        ? [...entry.options]
-                                        : [entry];
-                                })
-                                .findIndex((option) => option.value === value);
-                        }
-
-                        dispatch(
-                            new events.valueChange({
-                                detail: newValue,
-                            }),
-                        );
-                    })}
+            const selectElement = extractEventTarget(event, HTMLSelectElement);
+            const newValue = selectElement.value;
+            if (selectElement.value !== value) {
+                selectElement.selectedIndex = inputs.options
+                    .flatMap((entry) => {
+                    return isViraSelectOptionGroup(entry)
+                        ? [...entry.options]
+                        : [entry];
+                })
+                    .findIndex((option) => option.value === value);
+            }
+            dispatch(new events.valueChange({
+                detail: newValue,
+            }));
+        })}
                     ${attributes(inputs.attributePassthrough?.select)}
                 >
                     ${placeholderOptionTemplate}
                     ${inputs.options.map((entry) => {
-                        if (isViraSelectOptionGroup(entry)) {
-                            return html`
+            if (isViraSelectOptionGroup(entry)) {
+                return html `
                                 <optgroup label=${entry.groupName}>
                                     ${entry.options.map((option) => {
-                                        return renderSelectOption(option, value);
-                                    })}
+                    return renderSelectOption(option, value);
+                })}
                                 </optgroup>
                             `;
-                        }
-                        return renderSelectOption(entry, value);
-                    })}
+            }
+            return renderSelectOption(entry, value);
+        })}
                 </select>
                 <!--
                     These separate style elements are necessary so that we can select them as
@@ -441,26 +392,26 @@ export const ViraSelect = defineViraElement<
                 <div class="border-style wrapper-border"></div>
 
                 <${ViraIcon.assign({
-                    icon: inputs.icon,
-                })}
+            icon: inputs.icon,
+        })}
                     class="input-icon"
                 ></${ViraIcon}>
                 <${ViraIcon.assign({
-                    icon: ChevronUp16Icon,
-                })}
+            icon: ChevronUp16Icon,
+        })}
                     class="trigger-icon"
                 ></${ViraIcon}>
             </span>
         `;
-
         if (inputs.label) {
-            return html`
+            return html `
                 <label for=${state.randomId} ${attributes(inputs.attributePassthrough?.label)}>
                     <span class="select-label">${inputs.label}</span>
                     ${selectTemplate}
                 </label>
             `;
-        } else {
+        }
+        else {
             return selectTemplate;
         }
     },