Form

Import and live example#

One host-owned form containing a required filter and submit button.

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 form = createCatalogElement<AeliqoFormElement>("aeliqo-form", root);
		form.label = "Report filters";
		const field = document.createElement("aeliqo-text-field") as AeliqoTextFieldElement;
		field.label = "Required filter";
		field.name = "filter";
		field.required = true;
		const submit = document.createElement("button");
		submit.type = "submit";
		submit.textContent = "Apply";
		form.append(field, submit);
	}))(root);

Purpose#

A native form boundary around slotted controls that emits a submit proposal after constraint validation. Invalid submits focus an error summary; a rerender never submits.

When to use it#

• Several controls submit together under one action.
• Native constraint validation should run before the submit proposal.
• Invalid submission should move focus to an error summary.
• The host performs the action and decides whether a reset is accepted.

When to use a different component#

• Use FieldGroup when controls need grouping but no submission.
• Use FormFlow when the task spans multiple steps before commit.

Properties and defaults#

The form coordinates validation and emits a submit proposal; persistence and navigation remain with the host.

Events#

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

Listen for aeliqo-form-submit

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

Listen for aeliqo-form-reset

const element = document.querySelector('aeliqo-form');</p>
<p>element?.addEventListener('aeliqo-form-reset', (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-form');</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 form reports validity and emits a cancellable submit/reset request without executing business effects.

Form data and constraint validation follow native disabled-fieldset rules. Controls in the first legend of a disabled fieldset remain enabled unless another disabled state applies; controls in later legends or the fieldset body are excluded. A valid, enabled DateRange contributes both named endpoints to the form data.

Keyboard, focus, and accessibility#

Keyboard behavior:

• Tab follows form order
• Enter submits when valid
• Escape preserves draft

An invalid submit focuses the rendered error summary after a slotted submit button click, Enter in a field, or requestSubmit().

Exposed semantics:

• form
• li
• role
• ul

Responsive behavior#

Stack fields and submit actions on narrow screens. Preserve DOM order and keep validation messages beside their fields.

Style hooks#

• Shadow parts: error-summary, form
• Varendo design tokens referenced: --aeliqo-color-border, --aeliqo-color-danger, --aeliqo-color-surface, --aeliqo-color-text, --aeliqo-control-border-width, --aeliqo-control-inline-padding, --aeliqo-control-min-target, --aeliqo-space-12, --aeliqo-space-8

Related components#

• FieldGroup
• FormFlow

Generated TypeScript declaration#

export declare class AeliqoFormElement extends AeliqoFoundationElement {
    static readonly properties: {
        label: {
            type: StringConstructor;
        };
        noValidate: {
            attribute: string;
            type: BooleanConstructor;
        };
    };
    label: string;
    noValidate: boolean;
    private summary;
    connectedCallback(): void;
    disconnectedCallback(): void;
    /** Request native constraint validation and dispatch the typed host event. */
    requestSubmit(submitter?: HTMLElement): void;
    reset(): void;
    checkValidity(): boolean;
    reportValidity(): boolean;
    formData(): FormData | undefined;
    private appendSlottedNativeValues;
    private isSuccessfulNativeControl;
    private isCheckedInput;
    private isSubmitOnlyControl;
    private appendSlottedFieldValues;
    private fieldName;
    protected render(): import("lit").TemplateResult<1>;
    private readonly handleSubmit;
    private emitSubmit;
    private readonly handleSlottedClick;
    private readonly handleSlottedKeyDown;
    private isSlottedEnter;
    private nativeControlOwnsEnter;
    private submitSlotted;
    private focusSummary;
    private defaultSlottedSubmitter;
    private submitterSkipsValidation;
    private readonly handleReset;
    private collectErrors;
    private formControlErrors;
    private formControlError;
    private unownedNativeControlErrors;
    private slottedFieldErrors;
    private fieldLabel;
    private slottedFields;
    private slottedNativeControls;
    private nativeControlFromEvent;
    private eventFormOwner;
    private ownsEvent;
    private resetSlottedNativeControls;
    private resetNativeControl;
    private resetNativeInput;
    private resetNativeSelect;
    private appendNativeControlValue;
    private nativeControlError;
    private nativeForm;
    static readonly styles: import("lit").CSSResult[];
}

Version#

This page documents the Varendo 0.6 component contract.