vira 31.19.0 → 31.21.0

package/dist/elements/index.d.ts

@@ -23,3 +23,4 @@ export * from './vira-select.element.js';
 export * from './vira-tabs.element.js';
 export * from './vira-tag.element.js';
 export * from './vira-text-area.element.js';
+export * from './vira-theme-switcher.element.js';

package/dist/elements/index.js

@@ -23,3 +23,4 @@ export * from './vira-select.element.js';
 export * from './vira-tabs.element.js';
 export * from './vira-tag.element.js';
 export * from './vira-text-area.element.js';
+export * from './vira-theme-switcher.element.js';

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

@@ -17,10 +17,10 @@ export type ViraCheckboxInputs = {
 } & PartialWithUndefined<{
     stylePassthrough: Partial<Record<ViraCheckboxInnerElements, CSSResult>>;
     attributePassthrough: Partial<Record<ViraCheckboxInnerElements, AttributeValues>>;
-    disabled: boolean;
+    isDisabled: boolean;
     label: string;
     hasError: boolean;
-    horizontal: boolean;
+    useHorizontalLabel: boolean;
     /** The checkbox will be filled with a form selection color when it is checked. */
     fillWhenChecked: boolean;
     /** The checkbox will be filled with a form error color when it is unchecked. */

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

@@ -15,7 +15,7 @@ import { ViraIcon } from './vira-icon.element.js';
 export const ViraCheckbox = defineViraElement()({
     tagName: 'vira-checkbox',
     hostClasses: {
-        'vira-checkbox-horizontal': ({ inputs }) => !!inputs.horizontal,
+        'vira-checkbox-horizontal': ({ inputs }) => !!inputs.useHorizontalLabel,
         'vira-checkbox-filled-checked': ({ inputs }) => !!inputs.fillWhenChecked,
         'vira-checkbox-filled-unchecked': ({ inputs }) => !!inputs.fillWhenUnchecked,
     },
@@ -126,8 +126,8 @@ export const ViraCheckbox = defineViraElement()({
         }
 
         ${hostClasses['vira-checkbox-horizontal'].selector} label {
-            flex-direction: row-reverse;
-            align-items: flex-start;
+            flex-direction: row;
+            align-items: center;
             gap: 8px;
 
             & .label-text {
@@ -140,7 +140,7 @@ export const ViraCheckbox = defineViraElement()({
     },
     render({ inputs, dispatch, events }) {
         function updateValue() {
-            if (!inputs.disabled) {
+            if (!inputs.isDisabled) {
                 dispatch(new events.valueChange(!inputs.value));
             }
         }
@@ -158,7 +158,7 @@ export const ViraCheckbox = defineViraElement()({
         return html `
             <label
                 class=${classMap({
-            disabled: !!inputs.disabled,
+            disabled: !!inputs.isDisabled,
         })}
                 ${attributes(inputs.attributePassthrough?.label)}
                 style=${ifDefined(inputs.stylePassthrough?.label)}
@@ -168,14 +168,14 @@ export const ViraCheckbox = defineViraElement()({
                 <span
                     class="custom-checkbox ${classMap({
             checked: inputs.value,
-            disabled: !!inputs.disabled,
+            disabled: !!inputs.isDisabled,
             error: !!inputs.hasError,
         })}"
                     role="checkbox"
                     aria-label=${ifDefined(inputs.label || undefined)}
                     aria-checked=${inputs.value ? 'true' : 'false'}
-                    aria-disabled=${inputs.disabled ? 'true' : 'false'}
-                    tabindex=${inputs.disabled ? '-1' : '0'}
+                    aria-disabled=${inputs.isDisabled ? 'true' : 'false'}
+                    tabindex=${inputs.isDisabled ? '-1' : '0'}
                     ${attributes(inputs.attributePassthrough?.['custom-checkbox'])}
                     style=${ifDefined(inputs.stylePassthrough?.['custom-checkbox'])}
                     ${listenToActivate(updateValue)}

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

@@ -29,6 +29,21 @@ export declare const ViraForm: import("element-vir").DeclarativeElementDefinitio
      * @default false
      */
     horizontalCheckboxes: boolean;
+    /**
+     * When `true`, all form field labels render to the left of their inputs instead of above
+     * them.
+     *
+     * @default false
+     */
+    useHorizontalLabels: boolean;
+    /**
+     * When `true`, all fields in this form are prevented from user edits. Inputs, selects, and
+     * text areas render their current value as plain text; checkboxes render disabled since
+     * they have no native readonly mode.
+     *
+     * @default false
+     */
+    isReadonly: boolean;
 }>, {
     lastIsValid: boolean;
 }, {

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

@@ -1,5 +1,6 @@
 import { getObjectTypedEntries } from '@augment-vir/common';
-import { css, defineElementEvent, html, listen, nothing, testId } from 'element-vir';
+import { css, defineElementEvent, html, listen, nothing, testId, } from 'element-vir';
+import { viraFormCssVars } from '../styles/form-styles.js';
 import { defineViraElement } from '../util/define-vira-element.js';
 import { applyRequiredLabel, areFormFieldsValid, ViraFormFieldType, } from '../util/vira-form-fields.js';
 import { ViraCheckbox } from './vira-checkbox.element.js';
@@ -14,6 +15,11 @@ import { ViraTextArea } from './vira-text-area.element.js';
  */
 export const ViraForm = defineViraElement()({
     tagName: 'vira-form',
+    state() {
+        return {
+            lastIsValid: false,
+        };
+    },
     events: {
         valueChange: defineElementEvent(),
         validChange: defineElementEvent(),
@@ -34,12 +40,35 @@ export const ViraForm = defineViraElement()({
                 width: unset;
             }
         }
+
+        .horizontal-fields {
+            width: 100%;
+            border-collapse: separate;
+            border-spacing: 0 10px;
+
+            & th,
+            & td {
+                padding: 0;
+            }
+
+            & th {
+                padding: 0 8px;
+                vertical-align: middle;
+                white-space: nowrap;
+                font-weight: ${viraFormCssVars['vira-form-label-font-weight'].value};
+                text-align: right;
+            }
+
+            & td {
+                width: 100%;
+                vertical-align: top;
+
+                & > ${ViraCheckbox}, & > ${ViraInput}, & > ${ViraSelect}, & > ${ViraTextArea} {
+                    width: 100%;
+                }
+            }
+        }
     `,
-    state() {
-        return {
-            lastIsValid: false,
-        };
-    },
     render({ inputs, dispatch, events, state, updateState }) {
         const currentIsValid = areFormFieldsValid(inputs.fields);
         if (currentIsValid !== state.lastIsValid) {
@@ -50,168 +79,236 @@ export const ViraForm = defineViraElement()({
                 allFieldsAreValid: currentIsValid,
             }));
         }
+        function wrapFormField({ fieldTemplate, label, }) {
+            if (inputs.useHorizontalLabels) {
+                return html `
+                    <tr>
+                        <th scope="row">${label}</th>
+                        <td>${fieldTemplate}</td>
+                    </tr>
+                `;
+            }
+            else {
+                return fieldTemplate;
+            }
+        }
         const formFieldTemplates = getObjectTypedEntries(inputs.fields).map(([key, field,]) => {
+            const label = applyRequiredLabel(field.label, !!field.isRequired && !inputs.hideRequiredMarkers);
+            const isDisabled = !!(inputs.isDisabled || field.isDisabled);
+            const childLabel = inputs.useHorizontalLabels ? undefined : label;
+            const horizontalLabelAttributes = inputs.useHorizontalLabels && label
+                ? {
+                    'aria-label': label,
+                }
+                : {};
             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,
-                    horizontal: inputs.horizontalCheckboxes,
-                    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}>
-                    `;
+                return wrapFormField({
+                    label,
+                    fieldTemplate: html `
+                            <${ViraCheckbox.assign({
+                        value: field.value || false,
+                        isDisabled: !!(isDisabled || inputs.isReadonly),
+                        hasError: field.hasError,
+                        useHorizontalLabel: inputs.horizontalCheckboxes,
+                        fillWhenChecked: field.fillWhenChecked,
+                        fillWhenUnchecked: field.fillWhenUnchecked,
+                        label: childLabel,
+                        ...(inputs.useHorizontalLabels && label
+                            ? {
+                                attributePassthrough: {
+                                    'custom-checkbox': horizontalLabelAttributes,
+                                },
+                            }
+                            : {}),
+                    })}
+                                ${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}>
-                    `;
+                return wrapFormField({
+                    label,
+                    fieldTemplate: html `
+                            <${ViraSelect.assign({
+                        options: field.options,
+                        value: field.value,
+                        placeholder: field.placeholder,
+                        disabled: isDisabled,
+                        isReadonly: inputs.isReadonly,
+                        label: childLabel,
+                        hasError: field.hasError,
+                        icon: field.icon,
+                        ...(inputs.useHorizontalLabels && label
+                            ? {
+                                attributePassthrough: {
+                                    select: horizontalLabelAttributes,
+                                },
+                            }
+                            : {}),
+                    })}
+                                ${field.testId ? testId(field.testId) : nothing}
+                                ${listen(ViraSelect.events.valueChange, (event) => {
+                        dispatch(new events.valueChange({
+                            key,
+                            ...field,
+                            value: event.detail,
+                        }));
+                    })}
+                            ></${ViraSelect}>
+                        `,
+                });
             }
             else if (field.type === ViraFormFieldType.TextArea) {
-                return html `
-                        <${ViraTextArea.assign({
-                    value: field.value || '',
-                    disabled: inputs.isDisabled || field.isDisabled,
-                    hasError: field.hasError,
-                    label: applyRequiredLabel(field.label, !!field.isRequired && !inputs.hideRequiredMarkers),
-                    placeholder: field.placeholder,
-                    rows: field.rows,
-                    preventResize: field.preventResize,
-                })}
-                            ${field.testId ? testId(field.testId) : nothing}
-                            ${listen(ViraTextArea.events.valueChange, (event) => {
-                    dispatch(new events.valueChange({
-                        key,
-                        ...field,
-                        value: event.detail,
-                    }));
-                })}
-                        ></${ViraTextArea}>
-                    `;
+                return wrapFormField({
+                    label,
+                    fieldTemplate: html `
+                            <${ViraTextArea.assign({
+                        value: field.value || '',
+                        disabled: isDisabled,
+                        hasError: field.hasError,
+                        isReadonly: inputs.isReadonly,
+                        label: childLabel,
+                        placeholder: field.placeholder,
+                        rows: field.rows,
+                        preventResize: field.preventResize,
+                        attributePassthrough: horizontalLabelAttributes,
+                    })}
+                                ${field.testId ? testId(field.testId) : nothing}
+                                ${listen(ViraTextArea.events.valueChange, (event) => {
+                        dispatch(new events.valueChange({
+                            key,
+                            ...field,
+                            value: event.detail,
+                        }));
+                    })}
+                            ></${ViraTextArea}>
+                        `,
+                });
             }
             else if (field.type === ViraFormFieldType.Number) {
-                return html `
-                        <${ViraInput.assign({
-                    value: field.value?.toString() || '',
-                    disabled: inputs.isDisabled || field.isDisabled,
-                    allowedInputs: /\d/,
-                    hasError: field.hasError,
-                    icon: field.icon,
-                    label: applyRequiredLabel(field.label, !!field.isRequired && !inputs.hideRequiredMarkers),
-                    placeholder: field.placeholder,
-                    showClearButton: inputs.showClearButtons,
-                    type: ViraInputType.Number,
-                    attributePassthrough: {
-                        ...(field.min === undefined
-                            ? {}
-                            : {
-                                min: String(field.min),
-                            }),
-                        ...(field.max === undefined
-                            ? {}
-                            : {
-                                max: String(field.max),
-                            }),
-                        ...(field.step === undefined
-                            ? {}
-                            : {
-                                step: String(field.step),
-                            }),
-                    },
-                })}
-                            ${field.testId ? testId(field.testId) : nothing}
-                            ${listen(ViraInput.events.valueChange, (event) => {
-                    const numericValue = event.detail === '' ? undefined : Number(event.detail);
-                    dispatch(new events.valueChange({
-                        key,
-                        ...field,
-                        value: numericValue,
-                    }));
-                })}
-                        ></${ViraInput}>
-                    `;
+                return wrapFormField({
+                    label,
+                    fieldTemplate: html `
+                            <${ViraInput.assign({
+                        value: field.value?.toString() || '',
+                        disabled: isDisabled,
+                        allowedInputs: /\d/,
+                        hasError: field.hasError,
+                        icon: field.icon,
+                        isReadonly: inputs.isReadonly,
+                        label: childLabel,
+                        placeholder: field.placeholder,
+                        showClearButton: inputs.showClearButtons,
+                        type: ViraInputType.Number,
+                        attributePassthrough: {
+                            ...horizontalLabelAttributes,
+                            ...(field.min === undefined
+                                ? {}
+                                : {
+                                    min: String(field.min),
+                                }),
+                            ...(field.max === undefined
+                                ? {}
+                                : {
+                                    max: String(field.max),
+                                }),
+                            ...(field.step === undefined
+                                ? {}
+                                : {
+                                    step: String(field.step),
+                                }),
+                        },
+                    })}
+                                ${field.testId ? testId(field.testId) : nothing}
+                                ${listen(ViraInput.events.valueChange, (event) => {
+                        const numericValue = event.detail === '' ? undefined : Number(event.detail);
+                        dispatch(new events.valueChange({
+                            key,
+                            ...field,
+                            value: numericValue,
+                        }));
+                    })}
+                            ></${ViraInput}>
+                        `,
+                });
             }
             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
+                return wrapFormField({
+                    label,
+                    fieldTemplate: html `
+                            <${ViraInput.assign({
+                        value: field.value || '',
+                        disabled: isDisabled,
+                        hasError: field.hasError,
+                        icon: field.icon,
+                        isReadonly: inputs.isReadonly,
+                        label: childLabel,
+                        placeholder: field.placeholder,
+                        showClearButton: inputs.showClearButtons,
+                        attributePassthrough: {
+                            ...horizontalLabelAttributes,
+                            ...(field.isUsername
                                 ? {
-                                    autocomplete: 'password',
+                                    autocomplete: 'username',
                                 }
-                                : field.type === ViraFormFieldType.Email
+                                : field.type === ViraFormFieldType.NewPassword
                                     ? {
-                                        autocomplete: 'email',
+                                        autocomplete: 'new-password',
                                     }
-                                    : {},
-                    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}>
-                    `;
+                                    : 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}>
+                        `,
+                });
             }
         });
+        const formFieldsWrapper = inputs.useHorizontalLabels
+            ? html `
+                  <table class="horizontal-fields">
+                      <tbody>${formFieldTemplates}</tbody>
+                  </table>
+              `
+            : formFieldTemplates;
         return html `
             <form ${listen('submit', (event) => event.preventDefault())}>
-                ${formFieldTemplates}
+                ${formFieldsWrapper}
                 <slot></slot>
             </form>
         `;

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

@@ -35,6 +35,7 @@ export declare const ViraInput: import("element-vir").DeclarativeElementDefiniti
 } & PartialWithUndefined<{
     placeholder: string;
     disabled: boolean;
+    isReadonly: boolean;
     allowedInputs: string | RegExp;
     blockedInputs: string | RegExp;
     disableBrowserHelps: boolean;

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

@@ -156,6 +156,10 @@ export const ViraInput = defineViraElement()({
                 margin-right: calc(${cssVars['vira-input-padding-horizontal'].value} - 4px);
             }
 
+            .readonly-value {
+                overflow-wrap: anywhere;
+            }
+
             input {
                 ${noNativeFormStyles};
                 cursor: text;
@@ -293,6 +297,22 @@ export const ViraInput = defineViraElement()({
             allowed: inputs.allowedInputs,
             blocked: inputs.blockedInputs,
         });
+        if (inputs.isReadonly) {
+            const readonlyValueTemplate = html `
+                <span class="readonly-value">${filteredValue}</span>
+            `;
+            if (inputs.label) {
+                return html `
+                    <label>
+                        <span class="input-label">${inputs.label}</span>
+                        ${readonlyValueTemplate}
+                    </label>
+                `;
+            }
+            else {
+                return readonlyValueTemplate;
+            }
+        }
         const iconTemplate = inputs.icon
             ? html `
                   <${ViraIcon.assign({

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

@@ -290,7 +290,7 @@ export const ViraJsonForm = defineViraElement()({
                 return html `
                     <${ViraCheckbox.assign({
                     value: value === true,
-                    disabled: isDisabled,
+                    isDisabled,
                 })}
                         ${listen(ViraCheckbox.events.valueChange, (event) => {
                     emitReplaceAt(path, event.detail);

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

@@ -20,6 +20,11 @@ export declare const ViraSelect: import("element-vir").DeclarativeElementDefinit
     /** 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;

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

@@ -185,6 +185,10 @@ export const ViraSelect = defineViraElement()({
             }
         }
 
+        .readonly-value {
+            overflow-wrap: anywhere;
+        }
+
         ${hostClasses['vira-select-disabled'].selector} {
             cursor: not-allowed;
 
@@ -252,6 +256,27 @@ export const ViraSelect = defineViraElement()({
     },
     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 `
+                <span class="readonly-value">
+                    ${selectedOption?.label || inputs.placeholder || ''}
+                </span>
+            `;
+            if (inputs.label) {
+                return html `
+                    <label ${attributes(inputs.attributePassthrough?.label)}>
+                        <span class="select-label">${inputs.label}</span>
+                        ${readonlyValueTemplate}
+                    </label>
+                `;
+            }
+            else {
+                return readonlyValueTemplate;
+            }
+        }
         const placeholderOptionTemplate = inputs.placeholder || value == undefined
             ? html `
                       <option value="" disabled ?selected=${value == undefined}>

package/dist/elements/vira-text-area.element.d.ts

@@ -21,6 +21,7 @@ export declare const ViraTextArea: import("element-vir").DeclarativeElementDefin
 } & PartialWithUndefined<{
     placeholder: string;
     disabled: boolean;
+    isReadonly: boolean;
     allowedInputs: string | RegExp;
     blockedInputs: string | RegExp;
     disableBrowserHelps: boolean;

package/dist/elements/vira-text-area.element.js

@@ -97,6 +97,11 @@ export const ViraTextArea = defineViraElement()({
             pointer-events: none;
         }
 
+        .readonly-value {
+            white-space: pre-wrap;
+            overflow-wrap: anywhere;
+        }
+
         ${hostClasses['vira-text-area-prevent-resize'].selector} textarea {
             resize: none;
         }
@@ -154,6 +159,22 @@ export const ViraTextArea = defineViraElement()({
             allowed: inputs.allowedInputs,
             blocked: inputs.blockedInputs,
         });
+        if (inputs.isReadonly) {
+            const readonlyValueTemplate = html `
+                <span class="readonly-value">${filteredValue}</span>
+            `;
+            if (inputs.label) {
+                return html `
+                    <label>
+                        <span class="text-area-label">${inputs.label}</span>
+                        ${readonlyValueTemplate}
+                    </label>
+                `;
+            }
+            else {
+                return readonlyValueTemplate;
+            }
+        }
         const textAreaTemplate = html `
             <span class="text-area-wrapper">
                 <textarea

package/dist/elements/vira-theme-switcher.element.d.ts

@@ -0,0 +1,17 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { ViraThemeClient, ViraThemeSelection } from '../util/vira-theme-client.js';
+/**
+ * A row of buttons for selecting a {@link ViraThemeSelection} (light, dark, or auto). Fires a
+ * `themeSelect` event when the user picks an option; the consumer is responsible for applying the
+ * resulting theme.
+ *
+ * @category Elements
+ */
+export declare const ViraThemeSwitcher: import("element-vir").DeclarativeElementDefinition<"vira-theme-switcher", PartialWithUndefined<{
+    themeClient: Readonly<ViraThemeClient>;
+    /** Override the default English button titles (used as `title` attributes for tooltips). */
+    labels: Readonly<Record<ViraThemeSelection, string>>;
+}>, {
+    internalThemeClient: undefined | Readonly<ViraThemeClient>;
+    currentTheme: ViraThemeSelection;
+}, {}, "vira-theme-switcher-", "vira-theme-switcher-", readonly [], readonly []>;

package/dist/elements/vira-theme-switcher.element.js

@@ -0,0 +1,104 @@
+import { mapEnumToObject } from '@augment-vir/common';
+import { classMap, css, html, listen } from 'element-vir';
+import { AutoTheme24Icon, Moon24Icon, Sun24Icon } from '../icons/index.js';
+import { viraFormCssVars } from '../styles/form-styles.js';
+import { noNativeFormStyles, noNativeSpacing, viraTheme } from '../styles/index.js';
+import { defineViraElement } from '../util/define-vira-element.js';
+import { ViraThemeClient, ViraThemeSelection } from '../util/vira-theme-client.js';
+import { ViraIcon } from './vira-icon.element.js';
+const themeIcons = mapEnumToObject(ViraThemeSelection, (theme) => {
+    const map = {
+        [ViraThemeSelection.Light]: Sun24Icon,
+        [ViraThemeSelection.Dark]: Moon24Icon,
+        [ViraThemeSelection.Auto]: AutoTheme24Icon,
+    };
+    return map[theme];
+});
+const defaultThemeLabels = {
+    [ViraThemeSelection.Light]: 'Light',
+    [ViraThemeSelection.Dark]: 'Dark',
+    [ViraThemeSelection.Auto]: 'Auto',
+};
+/**
+ * A row of buttons for selecting a {@link ViraThemeSelection} (light, dark, or auto). Fires a
+ * `themeSelect` event when the user picks an option; the consumer is responsible for applying the
+ * resulting theme.
+ *
+ * @category Elements
+ */
+export const ViraThemeSwitcher = defineViraElement()({
+    tagName: 'vira-theme-switcher',
+    styles: css `
+        :host {
+            display: inline-flex;
+            align-items: center;
+            box-sizing: border-box;
+            gap: 4px;
+        }
+
+        button {
+            ${noNativeSpacing};
+            ${noNativeFormStyles};
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            border: 1px solid transparent;
+            border-radius: ${viraFormCssVars['vira-form-radius'].value};
+            padding: 2px;
+            cursor: pointer;
+            color: ${viraTheme.colors['vira-grey-foreground-placeholder'].foreground.value};
+
+            &:hover {
+                color: ${viraFormCssVars['vira-form-accent-primary-hover-color'].value};
+                border-color: currentColor;
+            }
+
+            &.selected {
+                pointer-events: none;
+                color: ${viraFormCssVars['vira-form-accent-primary-color'].value};
+                border-color: ${viraFormCssVars['vira-form-accent-primary-color'].value};
+            }
+        }
+
+        ${ViraIcon} {
+            width: 20px;
+            aspect-ratio: 1;
+        }
+    `,
+    state() {
+        return {
+            internalThemeClient: undefined,
+            currentTheme: ViraThemeSelection.Auto,
+        };
+    },
+    render({ inputs, state, updateState }) {
+        const themeClient = inputs.themeClient || state.internalThemeClient || new ViraThemeClient();
+        updateState({
+            internalThemeClient: themeClient,
+            currentTheme: themeClient.currentTheme,
+        });
+        const labels = inputs.labels || defaultThemeLabels;
+        return Object.values(ViraThemeSelection).map((theme) => {
+            return html `
+                <button
+                    class=${classMap({
+                selected: themeClient.currentTheme === theme,
+            })}
+                    title=${labels[theme]}
+                    ${listen('click', (event) => {
+                event.stopPropagation();
+                themeClient.setSelectedTheme(theme);
+                updateState({
+                    currentTheme: themeClient.currentTheme,
+                });
+            })}
+                >
+                    <${ViraIcon.assign({
+                icon: themeIcons[theme],
+                fitContainer: true,
+            })}></${ViraIcon}>
+                </button>
+            `;
+        });
+    },
+});

package/dist/util/index.d.ts

@@ -8,3 +8,4 @@ export * from './shared-text-input-logic.js';
 export * from './vira-form-fields.js';
 export * from './vira-json-schema.js';
 export * from './vira-select-option.js';
+export * from './vira-theme-client.js';

package/dist/util/index.js

@@ -8,3 +8,4 @@ export * from './shared-text-input-logic.js';
 export * from './vira-form-fields.js';
 export * from './vira-json-schema.js';
 export * from './vira-select-option.js';
+export * from './vira-theme-client.js';

package/dist/util/overflow-observer.d.ts

@@ -2,6 +2,7 @@
  * Creates an observer that monitors whether an element's content overflows its visible width. Uses
  * a ResizeObserver for size changes and a MutationObserver for DOM content changes.
  *
+ * @category Util
  * @returns A cleanup function that disconnects all observers.
  */
 export declare function createOverflowObserver({ element, widthElement, onChange, hysteresisPx, }: Readonly<{

package/dist/util/overflow-observer.js

@@ -2,6 +2,7 @@
  * Creates an observer that monitors whether an element's content overflows its visible width. Uses
  * a ResizeObserver for size changes and a MutationObserver for DOM content changes.
  *
+ * @category Util
  * @returns A cleanup function that disconnects all observers.
  */
 export function createOverflowObserver({ element, widthElement, onChange, hysteresisPx = 0, }) {

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

@@ -12,6 +12,7 @@ export type SharedTextInputElementInputs = {
     placeholder: string;
     /** Set to true to trigger disabled styles and to block all user input. */
     disabled: boolean;
+    isReadonly: boolean;
     /**
      * Only letters in the given string or matches to the given RegExp will be allowed.
      * blockedInputs takes precedence over this input.

package/dist/util/vira-form-fields.d.ts

@@ -77,7 +77,12 @@ export type ViraFormField = ({
 }> & CommonViraFormFields) | ({
     type: ViraFormFieldType.Checkbox;
     value: boolean | undefined;
-} & CommonViraFormFields) | ({
+} & PartialWithUndefined<{
+    /** The checkbox will be filled with a form selection color when it is checked. */
+    fillWhenChecked: boolean;
+    /** The checkbox will be filled with a form error color when it is unchecked. */
+    fillWhenUnchecked: boolean;
+}> & CommonViraFormFields) | ({
     type: ViraFormFieldType.Number;
     value: number | undefined;
 } & PartialWithUndefined<{

package/dist/util/vira-theme-client.d.ts

@@ -0,0 +1,83 @@
+import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { LocalStorageClient } from '@electrovir/local-storage-client';
+/**
+ * A user-facing selection of which theme to display. `Auto` follows the system color scheme; the
+ * other values force a specific theme regardless of system preference.
+ *
+ * @category Internal
+ */
+export declare enum ViraThemeSelection {
+    Light = "light",
+    Dark = "dark",
+    Auto = "auto"
+}
+/**
+ * Used by {@link ViraThemeClient} to apply themes. By default, vira themes will be applied (via
+ * {@link defaultApplyThemeCallback}).
+ *
+ * @category Internal
+ * @default `defaultApplyThemeCallback`
+ */
+export type ApplyThemeCallback = (params: Readonly<{
+    useDarkTheme: boolean;
+}>) => MaybePromise<void>;
+/**
+ * Default implementation of {@link ApplyThemeCallback}, which simply applies Vira themes.
+ *
+ * @category Internal
+ */
+export declare const defaultApplyThemeCallback: ApplyThemeCallback;
+/**
+ * Constructor params for {@link ViraThemeClient}.
+ *
+ * @category Internal
+ */
+export type ViraThemeClientParams = PartialWithUndefined<{
+    /**
+     * Called whenever the effective theme should change. If not provided, the default Vira themes
+     * will be used.
+     */
+    applyTheme: ApplyThemeCallback;
+    /**
+     * Override the LocalStorage store name used for theme persistence. Useful if a single page
+     * hosts multiple isolated theme clients.
+     *
+     * @default 'vira-theme'
+     */
+    storeName: string;
+}>;
+declare const themeStorageShapes: {
+    selectedTheme: import("object-shape-tester").Shape<{
+        theme: import("object-shape-tester").Shape<import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TLiteral<ViraThemeSelection.Light> | import("@sinclair/typebox").TLiteral<ViraThemeSelection.Dark> | import("@sinclair/typebox").TLiteral<ViraThemeSelection.Auto>)[]>>;
+    }>;
+};
+/**
+ * Tracks the user's {@link ViraThemeSelection} and bridges it to a consumer-supplied `applyTheme`
+ * callback. Persists the selection in LocalStorage via an internal `LocalStorageClient`, and
+ * listens for system color-scheme changes to re-apply the theme in auto mode without persisting.
+ *
+ * The initial theme is applied during construction.
+ *
+ * @category Util
+ */
+export declare class ViraThemeClient {
+    /** The callback that will be called to apply a new theme. */
+    protected readonly applyThemeCallback: ApplyThemeCallback;
+    /** Contains the user's last selected theme, saving and loading it to disk for persistence. */
+    protected readonly localStorageClient: LocalStorageClient<typeof themeStorageShapes>;
+    /** A callback to remove the global theme preference listener. */
+    protected readonly removeThemePreferenceListener: () => void;
+    constructor(params?: Readonly<ViraThemeClientParams>);
+    /**
+     * The currently selected theme. If you use multiple clients to set the same theme, this might
+     * get out of sync.
+     */
+    get currentTheme(): ViraThemeSelection;
+    /** Set the selected theme. */
+    setSelectedTheme(selection: ViraThemeSelection): void;
+    /** Cleanup internal state and listeners. */
+    destroy(): void;
+    /** Apply the currently selected theme. */
+    protected applySelection(selection: ViraThemeSelection): void;
+}
+export {};

package/dist/util/vira-theme-client.js

@@ -0,0 +1,93 @@
+import { assert } from '@augment-vir/assert';
+import { LocalStorageClient } from '@electrovir/local-storage-client';
+import { defineShape, enumShape } from 'object-shape-tester';
+import { applyColorThemeViaStyleElement } from 'theme-vir';
+import { listenTo } from 'typed-event-target';
+import { viraTheme, viraThemeDarkOverride } from '../styles/vira-color-theme.js';
+/**
+ * A user-facing selection of which theme to display. `Auto` follows the system color scheme; the
+ * other values force a specific theme regardless of system preference.
+ *
+ * @category Internal
+ */
+export var ViraThemeSelection;
+(function (ViraThemeSelection) {
+    ViraThemeSelection["Light"] = "light";
+    ViraThemeSelection["Dark"] = "dark";
+    ViraThemeSelection["Auto"] = "auto";
+})(ViraThemeSelection || (ViraThemeSelection = {}));
+/**
+ * Default implementation of {@link ApplyThemeCallback}, which simply applies Vira themes.
+ *
+ * @category Internal
+ */
+export const defaultApplyThemeCallback = ({ useDarkTheme }) => {
+    applyColorThemeViaStyleElement(viraTheme, useDarkTheme ? viraThemeDarkOverride : undefined);
+};
+const darkSchemeMediaQuery = '(prefers-color-scheme: dark)';
+const themeStorageShapes = {
+    selectedTheme: defineShape({
+        theme: enumShape(ViraThemeSelection),
+    }),
+};
+/**
+ * Tracks the user's {@link ViraThemeSelection} and bridges it to a consumer-supplied `applyTheme`
+ * callback. Persists the selection in LocalStorage via an internal `LocalStorageClient`, and
+ * listens for system color-scheme changes to re-apply the theme in auto mode without persisting.
+ *
+ * The initial theme is applied during construction.
+ *
+ * @category Util
+ */
+export class ViraThemeClient {
+    /** The callback that will be called to apply a new theme. */
+    applyThemeCallback = defaultApplyThemeCallback;
+    /** Contains the user's last selected theme, saving and loading it to disk for persistence. */
+    localStorageClient;
+    /** A callback to remove the global theme preference listener. */
+    removeThemePreferenceListener = listenTo(globalThis.matchMedia(darkSchemeMediaQuery), 'change', (event) => {
+        assert.instanceOf(event, MediaQueryListEvent);
+        if (this.currentTheme === ViraThemeSelection.Auto) {
+            void this.applyThemeCallback({
+                useDarkTheme: event.matches,
+            });
+        }
+    });
+    constructor(params = {}) {
+        if (params.applyTheme) {
+            this.applyThemeCallback = params.applyTheme;
+        }
+        this.localStorageClient = new LocalStorageClient(themeStorageShapes, {
+            storeName: params.storeName || 'vira-theme',
+        });
+        this.applySelection(this.currentTheme);
+    }
+    /**
+     * The currently selected theme. If you use multiple clients to set the same theme, this might
+     * get out of sync.
+     */
+    get currentTheme() {
+        return this.localStorageClient.get.selectedTheme()?.theme || ViraThemeSelection.Auto;
+    }
+    /** Set the selected theme. */
+    setSelectedTheme(selection) {
+        this.applySelection(selection);
+        this.localStorageClient.set.selectedTheme({
+            theme: selection,
+        });
+    }
+    /** Cleanup internal state and listeners. */
+    destroy() {
+        this.removeThemePreferenceListener();
+        this.localStorageClient.destroy();
+    }
+    /** Apply the currently selected theme. */
+    applySelection(selection) {
+        const useDarkTheme = selection === ViraThemeSelection.Dark ||
+            (selection === ViraThemeSelection.Auto &&
+                globalThis.matchMedia(darkSchemeMediaQuery).matches);
+        void this.applyThemeCallback({
+            useDarkTheme,
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vira",
-    "version": "31.19.0",
+    "version": "31.21.0",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",
@@ -42,10 +42,12 @@
         "@augment-vir/common": "^31.70.1",
         "@augment-vir/web": "^31.70.1",
         "@electrovir/color": "^1.7.9",
+        "@electrovir/local-storage-client": "^0.1.0",
         "date-vir": "^8.3.2",
         "device-navigation": "^4.5.5",
         "json-schema-to-ts": "^3.1.1",
         "lit-css-vars": "^3.6.2",
+        "object-shape-tester": "^6.13.0",
         "observavir": "^2.3.2",
         "page-active": "^1.0.3",
         "spa-router-vir": "^6.6.0",