import type { CustomElement } from '../CustomElement';
/**
 * ICustomFormElement - The interface contract for form-associated custom elements.
 *
 * @description
 * ICustomFormElement defines the type contract for custom elements that participate in HTML forms.
 * It extends CustomElement with the Form-Associated Custom Elements API, providing properties and
 * methods for form integration, validation state, and lifecycle callbacks. This interface ensures
 * that form components implement the standard form element contract, including constraint validation,
 * form association, and state restoration capabilities. It mirrors the native HTMLInputElement API
 * for common form-related properties while adding custom element-specific lifecycle hooks.
 *
 * @remarks
 * This interface combines properties from HTMLInputElement with custom lifecycle callbacks defined
 * in the Form-Associated Custom Elements specification. Components implementing this interface can
 * be used seamlessly within HTML forms, supporting features like form submission, validation,
 * reset, and browser autofill.
 *
 * @see https://web.dev/more-capable-form-controls/#lifecycle-callbacks
 * @see https://web.dev/more-capable-form-controls/#defining-a-form-associated-custom-element
 *
 * @example
 * Implementing ICustomFormElement:
 * ```typescript
 * export class TextInputElement extends CustomFormElement implements ICustomFormElement {
 *   public name: string = '';
 *   public value: string = '';
 *   public required: boolean = false;
 *
 *   public formResetCallback(): void {
 *     this.value = this.defaultValue || '';
 *   }
 *
 *   public formDisabledCallback(disabled: boolean): void {
 *     this.disabled = disabled;
 *   }
 * }
 * ```
 *
 * @example
 * Using form lifecycle callbacks:
 * ```typescript
 * public formStateRestoreCallback(state: string | null, reason: 'restore' | 'autocomplete'): void {
 *   if (reason === 'autocomplete') {
 *     this.value = state ?? '';
 *     this.dispatchEvent(new Event('input', { bubbles: true }));
 *   }
 * }
 * ```
 *
 * @example
 * Implementing form validation:
 * ```typescript
 * public override checkValidity(): boolean {
 *   const isValid = this.required ? this.value.trim() !== '' : true;
 *   if (!isValid) {
 *     this.internals.setValidity({ valueMissing: true }, 'Please fill out this field.');
 *   }
 *   return isValid;
 * }
 * ```
 *
 * @public
 */
export interface ICustomFormElement extends CustomElement, Partial<Pick<HTMLInputElement, 'name' | 'defaultValue' | 'value' | 'required' | 'disabled'>>, Pick<HTMLInputElement, 'form' | 'validity' | 'validationMessage' | 'willValidate' | 'checkValidity' | 'reportValidity'> {
    /**
     * Called when the browser associates the element with a form element,
     * or disassociates the element from a form element.
     */
    formAssociatedCallback?(form: HTMLFormElement | null): void;
    /**
     * Called after the disabled state of the element changes,
     * either because the disabled attribute of this element was added or removed;
     * or because the disabled state changed on a `<fieldset>` that's an ancestor of this element.
     *
     * @param disabled This parameter represents the new disabled state of the element.
     */
    formDisabledCallback?(disabled: boolean): void;
    /**
     * Called after the form is reset.
     * The element should reset itself to some kind of default state.
     */
    formResetCallback?(): void;
    /**
     * Called in one of two circumstances:
     *   - When the browser restores the state of the element (for example, after a navigation, or when the browser restarts). The `mode` argument is `"restore"` in this case.
     *   - When the browser's input-assist features such as form autofilling sets a value. The `mode` argument is `"autocomplete"` in this case.
     *
     * @param state The type of this argument depends on how the `this.internals.setFormValue()` method was called.
     * @param reason
     */
    formStateRestoreCallback?(state: string | File | Array<[string, FormDataEntryValue]> | null, reason: 'restore' | 'autocomplete'): void;
}
//# sourceMappingURL=ICustomFormElement.d.ts.map