@nestledjs/forms
Version:
A flexible React form library supporting both declarative and imperative usage patterns with TypeScript support
197 lines (196 loc) • 7.99 kB
TypeScript
import { BaseFieldOptions, ButtonOptions, CheckboxOptions, CheckboxGroupOptions, ContentOptions, CurrencyFieldOptions, CustomCheckboxOptions, CustomFieldOptions, DatePickerOptions, EmailFieldOptions, EnumSelectOptions, FormField, FormFieldType, InputFieldOptions, MarkdownEditorOptions, NumberFieldOptions, PasswordFieldOptions, PhoneFieldOptions, SearchSelectOptions, SearchSelectApolloOptions, SearchSelectMultiOptions, SelectOptions, SwitchOptions, TextAreaOptions, UrlFieldOptions } from './form-types';
/**
* Factory class for creating form field definitions.
* Provides a fluent API for building strongly-typed form fields.
*
* This is the main imperative API for creating form fields that can be used
* with both declarative (`fields` prop) and imperative (`children`) patterns.
*
* @example
* ```tsx
* // Basic field creation
* const usernameField = FormFieldClass.text('username', {
* label: 'Username',
* required: true,
* placeholder: 'Enter your username'
* })
*
* // Complex field with validation
* const emailField = FormFieldClass.email('email', {
* label: 'Email Address',
* required: true,
* validate: (value) => {
* if (!value.includes('@')) return 'Please enter a valid email'
* return true
* }
* })
*
* // Custom field with advanced options
* const phoneField = FormFieldClass.phone('phone', {
* label: 'Phone Number',
* helpText: 'Include country code',
* readOnly: false,
* readOnlyStyle: 'disabled'
* })
* ```
*/
export declare class FormFieldClass {
/**
* Creates a generic form field. Usually you'll want to use specific methods like text(), email(), etc.
*
* @param type - The field type from FormFieldType enum
* @param key - Unique identifier for the field (used as form field name)
* @param options - Configuration options for the field
* @returns A FormField object that can be used with Form component
*/
static field(type: FormFieldType, key: string, options?: BaseFieldOptions): FormField;
/**
* Creates a text input field.
*
* @param key - Unique identifier for the field
* @param options - Configuration options including label, placeholder, validation, etc.
* @returns A text field definition
*
* @example
* ```tsx
* FormFieldClass.text('firstName', {
* label: 'First Name',
* required: true,
* placeholder: 'Enter your first name'
* })
* ```
*/
static text(key: string, options?: InputFieldOptions): FormField;
/**
* Creates a textarea field for multi-line text input.
*
* @param key - Unique identifier for the field
* @param options - Configuration options including label, placeholder, rows, etc.
* @returns A textarea field definition
*
* @example
* ```tsx
* FormFieldClass.textArea('description', {
* label: 'Description',
* placeholder: 'Enter a detailed description',
* rows: 4
* })
* ```
*/
static textArea(key: string, options?: TextAreaOptions): FormField;
/**
* Creates a markdown editor field with rich text editing capabilities.
*
* @param key - Unique identifier for the field
* @param options - Configuration options including label, height, preview, toolbar, etc.
* @returns A markdown editor field definition
*
* @example
* ```tsx
* FormFieldClass.markdownEditor('content', {
* label: 'Content',
* height: 400,
* preview: true,
* toolbar: ['bold', 'italic', 'link', 'quote', 'code']
* })
* ```
*
* @example Dual format output
* ```tsx
* FormFieldClass.markdownEditor('content', {
* label: 'Content',
* outputFormat: 'both', // Outputs both markdown and HTML
* onHtmlChange: (html) => console.log('HTML:', html)
* })
* ```
*
* @example Modal-on-modal fix
* ```tsx
* FormFieldClass.markdownEditor('content', {
* label: 'Content',
* // Fix for when MarkdownEditor is inside a modal
* overlayContainer: document.getElementById('modal-container'),
* popupZIndex: 10000, // Higher than your modal's z-index
* })
* ```
*/
static markdownEditor(key: string, options?: Partial<MarkdownEditorOptions>): FormField;
/**
* Creates a Markdown editor field with image upload support
*/
static markdownEditorWithImages(key: string, imageUploadHandler: (file: File) => Promise<string>, options?: Partial<MarkdownEditorOptions>): FormField;
/**
* Creates an email input field with built-in email validation.
*
* @param key - Unique identifier for the field
* @param options - Configuration options including label, placeholder, validation, etc.
* @returns An email field definition
*
* @example
* ```tsx
* FormFieldClass.email('email', {
* label: 'Email Address',
* required: true,
* placeholder: 'user@example.com'
* })
* ```
*/
static email(key: string, options?: EmailFieldOptions): FormField;
/**
* Creates a password input field.
*
* @param key - Unique identifier for the field
* @param options - Configuration options including label, placeholder, validation, etc.
* @returns A password field definition
*
* @example
* ```tsx
* FormFieldClass.password('password', {
* label: 'Password',
* required: true,
* validate: (value) => value.length >= 8 || 'Password must be at least 8 characters'
* })
* ```
*/
static password(key: string, options?: PasswordFieldOptions): FormField;
static url(key: string, options?: UrlFieldOptions): FormField;
static phone(key: string, options?: PhoneFieldOptions): FormField;
static number(key: string, options?: NumberFieldOptions): FormField;
static currency(key: string, options?: CurrencyFieldOptions): FormField;
static checkbox(key: string, options?: CheckboxOptions): FormField;
/**
* Creates a checkbox group field with multiple selectable options.
*
* @param key - Unique identifier for the field
* @param options - Configuration options including checkboxOptions array, layout, etc.
* @returns A checkbox group field definition
*
* @example
* ```tsx
* FormFieldClass.checkboxGroup('interests', {
* label: 'Interests',
* checkboxOptions: [
* { key: 'sports', value: 'sports', label: 'Sports' },
* { key: 'music', value: 'music', label: 'Music' },
* { key: 'travel', value: 'travel', label: 'Travel' }
* ],
* checkboxDirection: 'column',
* defaultValue: 'sports,music' // comma-separated selected values
* })
* ```
*/
static checkboxGroup(key: string, options: CheckboxGroupOptions): FormField;
static customCheckbox(key: string, options?: CustomCheckboxOptions): FormField;
static switch(key: string, options?: SwitchOptions): FormField;
static button(key: string, options?: ButtonOptions): FormField;
static datePicker(key: string, options?: DatePickerOptions): FormField;
static dateTimePicker(key: string, options?: DatePickerOptions): FormField;
static select(key: string, options: SelectOptions): FormField;
static enumSelect(key: string, options: EnumSelectOptions): FormField;
static searchSelect(key: string, options: SearchSelectOptions): FormField;
static searchSelectApollo<TDataItem>(key: string, options: SearchSelectApolloOptions<TDataItem>): FormField;
static searchSelectMulti(key: string, options: SearchSelectMultiOptions): FormField;
static searchSelectMultiApollo<TDataItem>(key: string, options: SearchSelectApolloOptions<TDataItem>): FormField;
static content(key: string, options: ContentOptions): FormField;
static custom<T = unknown>(key: string, options: CustomFieldOptions<T>): FormField;
}