DateRange

Import and live example#

One inclusive September reporting range in the calendar timezone.

import {registerAeliqoElements} from "@varendo/web";
import {
  AeliqoCheckboxElement,
  AeliqoComboboxElement,
  AeliqoDateFieldElement,
  AeliqoDateRangeElement,
  AeliqoFieldGroupElement,
  AeliqoFileInputElement,
  AeliqoFormElement,
  AeliqoNumberFieldElement,
  AeliqoRadioGroupElement,
  AeliqoSearchFieldElement,
  AeliqoSelectElement,
  AeliqoSliderElement,
  AeliqoSwitchElement,
  AeliqoTextAreaElement,
  AeliqoTextFieldElement,
  type AeliqoOption,
} from "@varendo/web/inputs";

const options: readonly AeliqoOption[] = [
  {value: "ada", label: "Ada Lovelace", description: "Research"},
  {value: "grace", label: "Grace Hopper", description: "Product"},
  {value: "lin", label: "Lin Chen", disabled: true},
];

registerAeliqoElements();

const host = document.querySelector<HTMLElement>("#aeliqo-example") ?? (() => {
  const created = document.createElement("div");
  created.id = "aeliqo-example";
  (document.body ?? document.documentElement).append(created);
  return created;
})();

function createCatalogRoot(container: HTMLElement): HTMLElement {
  const root = document.createElement("div");
  root.dataset.catalogSourceRoot = "true";
  root.style.display = "grid";
  root.style.gap = "12px";
  container.append(root);
  return root;
}

function createCatalogElement<T extends HTMLElement>(tagName: string, container: HTMLElement): T {
  const element = document.createElement(tagName) as T;
  element.setAttribute("data-aeliqo-theme", "light");
  container.append(element);
  return element;
}

function appendSlottedText(root: HTMLElement, slot: string, textContent: string): void {
  const content = document.createElement("span");
  content.slot = slot;
  content.textContent = textContent;
  root.append(content);
}

const root = createCatalogRoot(host);
(((root) => {
		const element = createCatalogElement<AeliqoDateRangeElement>("aeliqo-date-range", root);
		element.label = "Reporting period";
		element.name = "period";
		element.start = "2026-09-01";
		element.end = "2026-09-30";
		element.boundary = "inclusive";
		element.timezone = "calendar";
	}))(root);

Purpose#

A pair of date fields whose start and end properties the host can set. User edits update those local properties and emit both dates with boundary and calendar meaning as one range value; the host decides what to persist.

When to use it#

• You need a start and end date that stay consistent together.
• The range must declare whether its endpoints are inclusive or exclusive.
• Timezone and calendar policy must travel with the submitted value.

When to use a different component#

• Use DateField when only one calendar date is needed.
• Use Form when the range submits alongside related fields.

Properties and defaults#

Start and end are explicit values; boundary and timezone are part of the meaning, not display decoration.

Events#

Events cross the component boundary as user proposals. Validate their detail and current authority before applying a business effect.

Listen for aeliqo-input-change

const element = document.querySelector('aeliqo-date-range');<p>element?.addEventListener('aeliqo-input-change', (event) => {
  const proposal = (event as CustomEvent<unknown>).detail;
  // Validate the proposal, update host state, then assign controlled properties.
  applyProposal(proposal);
});

Listen for aeliqo-input-commit

const element = document.querySelector('aeliqo-date-range');</p>
<p>element?.addEventListener('aeliqo-input-commit', (event) => {
  const proposal = (event as CustomEvent<unknown>).detail;
  // Validate the proposal, update host state, then assign controlled properties.
  applyProposal(proposal);
});

Listen for aeliqo-validation

const element = document.querySelector('aeliqo-date-range');</p>
<p>element?.addEventListener('aeliqo-validation', (event) => {
  const proposal = (event as CustomEvent<unknown>).detail;
  // Validate the proposal, update host state, then assign controlled properties.
  applyProposal(proposal);
});

States and failure handling#

Relevant states:

• ready
• disabled
• invalid
• pending

Expected result: The range preserves ordering and boundary semantics while emitting a typed range proposal.

Changing the range or its boundary policy or replacing validator cancels validation for the previous value and clears its validator-owned error. An independently supplied host error survives the change. Late results after a reset or disconnect are ignored.

The range is invalid when a required endpoint is missing or the endpoints are out of order. Inclusive ranges allow equal endpoints; exclusive ranges require the start to precede the end. The event detail includes both dates, the boundary policy, timezone: 'calendar', calendar: 'gregory', and validity. An ordinary native form and Form both contribute ${name}[start] and ${name}[end] when the named pair is valid and enabled. Host updates and reset update both endpoints together; an invalid or disabled pair contributes neither endpoint. The host carries the boundary and calendar policy into any query or action.

Keyboard, focus, and accessibility#

Keyboard behavior:

• Tab
• Arrow keys
• Enter
• IME composition

Exposed semantics:

• aria-describedby
• aria-hidden
• aria-invalid
• aria-readonly
• input
• role

Responsive behavior#

Stack start and end fields in a narrow form. Keep each label and the range boundary meaning next to its value.

Style hooks#

• Shadow parts: description, end, end-label, error, field, input, label, pending, policy, start, start-label
• Varendo design tokens referenced: --aeliqo-color-muted, --aeliqo-space-4, --aeliqo-space-8, --aeliqo-typography-font-weight-semibold

Related components#

• DateField
• Form

Generated TypeScript declaration#

export declare class AeliqoDateRangeElement extends AeliqoFieldElement<AeliqoDateRangeValue> {
    static readonly properties: {
        label: {
            type: StringConstructor;
        };
        description: {
            type: StringConstructor;
        };
        error: {
            type: StringConstructor;
        };
        required: {
            type: BooleanConstructor;
            reflect: boolean;
        };
        disabled: {
            type: BooleanConstructor;
            reflect: boolean;
        };
        readOnly: {
            attribute: string;
            type: BooleanConstructor;
            reflect: boolean;
        };
        name: {
            type: StringConstructor;
            reflect: boolean;
        };
        autocomplete: {
            type: StringConstructor;
        };
        locale: {
            type: StringConstructor;
        };
        validationState: {
            attribute: string;
            type: StringConstructor;
            reflect: boolean;
        };
        validator: {
            attribute: boolean;
        };
        start: {
            type: StringConstructor;
            reflect: boolean;
        };
        end: {
            type: StringConstructor;
            reflect: boolean;
        };
        defaultStart: {
            attribute: string;
            type: StringConstructor;
        };
        defaultEnd: {
            attribute: string;
            type: StringConstructor;
        };
        boundary: {
            type: StringConstructor;
        };
        timezone: {
            type: StringConstructor;
        };
        calendar: {
            type: StringConstructor;
        };
    };
    start: string;
    end: string;
    defaultStart: string;
    defaultEnd: string;
    boundary: AeliqoRangeBoundary;
    timezone: 'calendar';
    calendar: 'gregory';
    connectedCallback(): void;
    protected updated(): void;
    protected isCurrentValidationValue(value: AeliqoDateRangeValue): boolean;
    protected resetField(): void;
    protected render(): import("lit").TemplateResult<1>;
    focus(options?: FocusOptions): void;
    private readonly handleStart;
    private readonly handleEnd;
    private readonly handleCommit;
    private emitChange;
    private rangeValue;
    private isValid;
    private valueMissingMessage;
    private syncNative;
    private syncFormValue;
    private syncAriaInvalid;
    private syncValidity;
    private nativeStart;
    static readonly styles: import("lit").CSSResult[];
}

Version#

This page documents the Varendo 0.6 component contract.