@esri/calcite-components/dist/utils/form.d.ts

Web Components for Esri's Calcite Design System.

import { Writable } from 'type-fest';
import { TemplateResult } from 'lit-html';
import { IconNameOrString } from '../components/calcite-icon/interfaces';
import { Status } from '../components/interfaces';
/** Any form <Component> with a `calcite<Component>Input` event needs to be included in this array. */
export declare const componentsWithInputEvent: string[];
/**
 * Get the event name to listen for that, when emitted, will clear the
 * validation message that displays after form submission. Only validation
 * messages that are set by the browser will be cleared. If a user sets
 * validationMessage to a custom value, they are responsible for clearing it.
 *
 * Exported for testing purposes.
 *
 * @param componentTag the tag of the component, e.g. "calcite-input"
 * @returns the event name
 */
export declare function getClearValidationEventName(componentTag: string): string;
export type MutableValidityState = Writable<ValidityState>;
/** Exported for testing purposes. */
export declare const hiddenFormInputSlotName = "hidden-form-input";
/**
 * Defines interface for form owning components.
 *
 * Allows calling submit/reset methods on the form.
 */
export interface FormOwner {
    /** The host element. */
    readonly el: HTMLElement;
    /**
     * The ID of the form to associate with the component.
     *
     * When not set, the component will be associated with its ancestor form element, if any.
     *
     * Note that this prop should use the `@Prop` decorator.
     */
    form: string;
    /**
     * The form this component is associated with.
     *
     * @private
     */
    formEl: HTMLFormElement;
}
/**
 * Defines interface for form-associated components.
 *
 * Along with the interface, use the matching form utils to help set up the component behavior.
 */
export interface FormComponent<T = any> extends FormOwner {
    /** When true, this component's value will not be submitted in the form. */
    disabled: boolean;
    /**
     * When true, form submit requests will enforce field requirement.
     *
     * @todo remove optional in follow-up PR
     */
    required?: boolean;
    /**
     * The name used to submit the value to the associated form.
     *
     * Note that this prop should use the `@Prop` decorator.
     */
    name: string;
    /**
     * This form component's value.
     *
     * Note that this prop should use the `@Prop` decorator.
     */
    value: T;
    /**
     * The initial value for this form component.
     *
     * When the form is reset, the value will be set to this property.
     */
    defaultValue: T;
    /** The validation icon to display. */
    validationIcon?: string | boolean;
    /** The validation message to display. */
    validationMessage?: string;
    /** The validity state of the form component. */
    validity?: MutableValidityState;
    /** Hook for components to provide custom form reset behavior. */
    onFormReset?: () => void;
    /**
     * Hook for components to sync _extra_ props on the hidden input form element used for form-submitting.
     *
     * Note: The following props are set by default: disabled, hidden, name, required, value.
     */
    syncHiddenFormInput?: (input: HTMLInputElement) => void;
}
/**
 * Defines interface for checkable form-associated components.
 *
 * Along with the interface, use the matching form utils to help set up the component behavior.
 */
export interface CheckableFormComponent<T = any> extends FormComponent<T> {
    /** For boolean-valued components, this property defines whether the associated value is submitted to the form or not. */
    checked: boolean;
    /**
     * The initial checked value for this form component.
     *
     * When the form is reset, the checked property will be set to this value.
     */
    defaultChecked: boolean;
}
export interface ValidationProps {
    status: Status;
    message: string;
    icon: IconNameOrString | boolean | "";
}
/**
 * Helper to submit a form.
 *
 * @param component
 * @returns true if its associated form was submitted, false otherwise.
 */
export declare function submitForm(component: FormOwner): boolean;
/**
 * Helper to reset a form.
 *
 * @param component
 */
export declare function resetForm(component: FormOwner): void;
/**
 * Helper to set up form interactions on connectedCallback.
 *
 * @param component
 */
export declare function connectForm<T>(component: FormComponent<T>): void;
/**
 * Utility method to find a form-component's associated form element.
 *
 * @param component
 */
export declare function findAssociatedForm(component: FormOwner): HTMLFormElement | null;
/**
 * Helper to tear down form interactions on disconnectedCallback.
 *
 * @param component
 */
export declare function disconnectForm<T>(component: FormComponent<T>): void;
/**
 * Helper for setting the default value on initialization after connectedCallback.
 *
 * Note that this is only needed if the default value cannot be determined on connectedCallback.
 *
 * @param component
 * @param value
 */
export declare function afterConnectDefaultValueSet<T>(component: FormComponent<T>, value: any): void;
export declare const internalHiddenInputInputEvent = "calciteInternalHiddenInputInput";
interface HiddenFormInputSlotProps {
    component: FormComponent;
}
/**
 * Helper to render the slot for form-associated component's hidden input.
 *
 * If the component has a default slot, this must be placed at the bottom of the component's root container to ensure it is the last child.
 *
 * render(): VNode {
 *   <Host>
 *     <div class={CSS.container}>
 *     // ...
 *     <HiddenFormInputSlot component={this} />
 *     </div>
 *   </Host>
 * }
 *
 * Note that the hidden-form-input Sass mixin must be added to the component's style to apply specific styles.
 *
 * @param root0
 * @param root0.component
 */
export declare const HiddenFormInputSlot: ({ component }: HiddenFormInputSlotProps) => TemplateResult;
export {};