@nuraly/lumenui 0.1.0

package/dist/src/components/form/form.component.d.ts

@@ -0,0 +1,279 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+import { LitElement, type PropertyValues } from 'lit';
+import { FormConfig, FormValidationState, FormSubmissionState } from './form.types.js';
+declare const NrFormElement_base: (new (...args: any[]) => import("@nuralyui/common/mixins").DependencyAware) & (new (...args: any[]) => import("@nuralyui/common/mixins").ThemeAware) & (new (...args: any[]) => import("@nuralyui/common/mixins").EventHandlerCapable) & typeof LitElement;
+/**
+ * Comprehensive form component with field management and validation API
+ *
+ * Key Features:
+ * - Coordinates validation across all form fields (does NOT validate itself)
+ * - Handles form submission with built-in validation checks
+ * - Provides form state management and events
+ * - Integrates with existing component validation controllers
+ * - Supports both programmatic and user-driven interactions
+ * - Comprehensive API for field manipulation and validation
+ *
+ * @example Basic Usage
+ * ```html
+ * <nr-form @nr-form-submit-success="${handleSuccess}" validate-on-change>
+ *   <nr-input name="username" required></nr-input>
+ *   <nr-input name="email" type="email" required></nr-input>
+ *   <nr-button type="submit">Submit</nr-button>
+ * </nr-form>
+ * ```
+ *
+ * @example Programmatic Usage
+ * ```typescript
+ * const form = document.querySelector('nr-form');
+ *
+ * // Set field values
+ * form.setFieldsValue({ username: 'john', email: 'john@example.com' });
+ *
+ * // Get field values
+ * const values = form.getFieldsValue();
+ *
+ * // Validate and submit
+ * try {
+ *   const values = await form.finish();
+ *   console.log('Form submitted:', values);
+ * } catch (errors) {
+ *   console.log('Validation failed:', errors);
+ * }
+ *
+ * // Reset specific fields
+ * form.resetFields(['username']);
+ * ```
+ *
+ * @fires nr-form-validation-changed - Validation state changes
+ * @fires nr-form-field-changed - Individual field changes
+ * @fires nr-form-submit-attempt - Form submission attempted
+ * @fires nr-form-submit-success - Form submitted successfully
+ * @fires nr-form-submit-error - Form submission failed
+ * @fires nr-form-reset - Form was reset
+ *
+ * @slot default - Form content (inputs, buttons, etc.)
+ */
+export declare class NrFormElement extends NrFormElement_base {
+    static styles: import("lit").CSSResult;
+    /** Form configuration */
+    config: FormConfig;
+    /** Enable real-time validation on field changes */
+    validateOnChange: boolean;
+    /** Enable validation on field blur */
+    validateOnBlur: boolean;
+    /** Prevent form submission if validation fails */
+    preventInvalidSubmission: boolean;
+    /** Reset form after successful submission */
+    resetOnSuccess: boolean;
+    /** Form action URL for native submission */
+    action?: string;
+    /** Form method for native submission */
+    method: 'GET' | 'POST';
+    /** Form encoding type */
+    enctype: string;
+    /** Target for form submission */
+    target?: string;
+    /** Disable the entire form */
+    disabled: boolean;
+    /** Form validation state */
+    private _validationState;
+    /** Form submission state */
+    private _submissionState;
+    /** Validation controller */
+    private validationController;
+    /** Submission controller */
+    private submissionController;
+    /** Get current validation state */
+    get validationState(): FormValidationState;
+    /** Get current submission state */
+    get submissionState(): FormSubmissionState;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(changedProperties: PropertyValues): void;
+    firstUpdated(): void;
+    /**
+     * Setup mutation observer to detect new form fields
+     */
+    private setupFormObserver;
+    /**
+     * Cleanup mutation observer
+     */
+    private cleanupFormObserver;
+    /**
+     * Register existing form fields
+     */
+    private registerExistingFields;
+    /**
+     * Register form fields in an element
+     */
+    private registerFieldsInElement;
+    /**
+     * Setup form events
+     */
+    private setupFormEvents;
+    /**
+     * Handle form submission
+     */
+    private handleFormSubmit;
+    /**
+     * Handle form reset
+     */
+    private handleFormReset;
+    /**
+     * Handle validation state changes
+     */
+    private handleValidationChanged;
+    /**
+     * Perform native form submission
+     */
+    private performNativeSubmission;
+    /**
+     * Validate the form
+     */
+    validate(): Promise<boolean>;
+    /**
+     * Submit the form programmatically
+     */
+    submit(customData?: Record<string, any>): Promise<void>;
+    /**
+     * Reset the form
+     */
+    reset(): void;
+    /**
+     * Check if form is valid
+     */
+    get isValid(): boolean;
+    /**
+     * Check if form is submitting
+     */
+    get isSubmitting(): boolean;
+    /**
+     * Get form data
+     */
+    getFormData(): import("./form.types.js").FormSubmissionData;
+    /**
+     * Get invalid fields
+     */
+    getInvalidFields(): import("./form.types.js").FormField[];
+    /**
+     * Get values of all fields
+     * @returns Object containing all field values
+     */
+    getFieldsValue(nameList?: string[]): Record<string, any>;
+    /**
+     * Get value of specific field
+     * @param name Field name
+     * @returns Field value
+     */
+    getFieldValue(name: string): any;
+    /**
+     * Set values of fields
+     * @param values Object containing field values to set
+     */
+    setFieldsValue(values: Record<string, any>): void;
+    /**
+     * Set value of specific field
+     * @param name Field name
+     * @param value Field value
+     */
+    setFieldValue(name: string, value: any): void;
+    /**
+     * Validate specific fields
+     * @param nameList Array of field names to validate, if empty validates all
+     * @returns Promise with validation result
+     */
+    validateFields(nameList?: string[]): Promise<Record<string, any>>;
+    /**
+     * Reset specific fields
+     * @param nameList Array of field names to reset, if empty resets all
+     */
+    resetFields(nameList?: string[]): void;
+    /**
+     * Get field error
+     * @param name Field name
+     * @returns Field error message or null
+     */
+    getFieldError(name: string): string | null;
+    /**
+     * Get all field errors
+     * @param nameList Array of field names, if empty returns all
+     * @returns Object containing field errors
+     */
+    getFieldsError(nameList?: string[]): Record<string, string | null>;
+    /**
+     * Check if field has been touched
+     * @param name Field name
+     * @returns Whether field has been touched
+     */
+    isFieldTouched(name: string): boolean;
+    /**
+     * Check if any fields have been touched
+     * @param nameList Array of field names, if empty checks all
+     * @returns Whether any of the specified fields have been touched
+     */
+    isFieldsTouched(nameList?: string[]): boolean;
+    /**
+     * Check if field value has been modified
+     * @param name Field name
+     * @returns Whether field has been modified
+     */
+    isFieldDirty(name: string): boolean;
+    /**
+     * Check if any fields have been modified
+     * @param nameList Array of field names, if empty checks all
+     * @returns Whether any of the specified fields have been modified
+     */
+    isFieldsDirty(nameList?: string[]): boolean;
+    /**
+     * Get field instance
+     * @param name Field name
+     * @returns Field element or null
+     */
+    getFieldInstance(name: string): HTMLElement | null;
+    /**
+     * Scroll to first error field
+     * @returns Whether scrolled to a field
+     */
+    scrollToField(name?: string): boolean;
+    /**
+     * Submit form and validate
+     * @returns Promise with form values
+     */
+    finish(): Promise<Record<string, any>>;
+    /**
+     * Get field names that have validation errors
+     * @returns Array of field names with errors
+     */
+    getFieldsWithErrors(): string[];
+    /**
+     * Check if form has any validation errors
+     * @returns Whether form has errors
+     */
+    hasErrors(): boolean;
+    /**
+     * Get summary of form state
+     * @returns Object with form state information
+     */
+    getFormState(): {
+        isValid: boolean;
+        isSubmitting: boolean;
+        hasErrors: boolean;
+        errorCount: number;
+        fieldCount: number;
+        touchedFields: string[];
+        dirtyFields: string[];
+        invalidFields: string[];
+    };
+    /**
+     * Set form loading state (useful for async operations)
+     * @param loading Whether form is in loading state
+     */
+    setLoading(loading: boolean): void;
+    render(): import("lit-html").TemplateResult<1>;
+}
+export {};
+//# sourceMappingURL=form.component.d.ts.map