@cube-dev/ui-kit 0.0.0-canary-d688797 → 0.0.0-canary-bdfccbd

package/docs/components/form/Form.md

@@ -1,9 +1,9 @@
 # Form
 
-<Badge variant="accent">Form component</Badge>
-
 Forms allow users to enter data that can be submitted while providing alignment and styling for form fields. The Form component provides structure, validation, and state management for user input through a collection of input components with built-in field support.
 
+The form system is inspired by AntD Forms and [rc-field-form](https://field-form-react-component.vercel.app/) with a similar API.
+
 ## When to Use
 
 - When collecting user information or input data
@@ -15,78 +15,64 @@ Forms allow users to enter data that can be submitted while providing alignment
 
 ## Properties
 
-### Base Properties
+### Form-specific Properties
 
-Supports [Base properties](../../tasty/tasty.md)
+- **`name`** `string` — Form name attribute
+- **`defaultValues`** `Partial<T>` — Default field values
+- **`onValuesChange`** `(data: T) => void` — Triggered when any field value changes
+- **`onSubmit`** `(data: T) => void | Promise<void>` — Triggered on successful form submission. When returning a promise, the form and submit button show loading state until resolved
+- **`onSubmitFailed`** `(error: any) => void` — Triggered when form submission fails
+- **`form`** `CubeFormInstance<T>` — Form instance created by `Form.useForm()`
+- **`labelWidth`** `Styles['width']` — Width of label area for side-positioned labels
+- **`orientation`** `'vertical' | 'horizontal'` (default: `vertical`) — Form layout orientation
 
-### Styling Properties
+### Inherited Form Properties
 
-#### styles
+These properties are inherited by all input components within the form:
 
-Customizes the root form element.
+- **`labelPosition`** `'top' | 'side' | 'split'` (default: `top`) — Where to place labels relative to inputs. `'top'` places labels above inputs, `'side'` places labels beside inputs with fixed width, `'split'` places labels and inputs on opposite sides without fixed label width
+- **`labelStyles`** `Styles` — Styles applied to field labels
+- **`requiredMark`** `boolean` (default: `true`) — Whether to show required field indicators
+- **`necessityIndicator`** `'icon' | 'label'` (default: `icon`) — Type of necessity indicator
+- **`isReadOnly`** `boolean` (default: `false`) — Whether fields are read-only by default
+- **`validationState`** `'valid' | 'invalid'` — Validation state for all fields
+- **`validateTrigger`** `'onBlur' | 'onChange' | 'onSubmit'` (default: `onBlur`) — When to trigger validation
+- **`showValid`** `boolean` (default: `false`) — Whether to show valid state indicators
 
-The Form component does not expose styled sub-elements via the `styles` prop. It uses a simple container layout that can be customized through the main styles property.
+### HTML Form Properties
 
-### Style Properties
+- **`action`** `string` — Form action URL (for server submission)
+- **`autoComplete`** `string` — Browser autocomplete behavior
+- **`encType`** `string` — Form encoding type
+- **`method`** `'get' | 'post'` — HTTP method for form submission
+- **`target`** `string` — Target for form submission
 
-These properties allow direct style application without using the `styles` prop: `display`, `flow`, `gap`, `placeItems`, `width`, `height`, `padding`, `margin`.
+### Base Properties
 
-### Form-specific Properties
+Supports [Base properties](../../BaseProperties.md)
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | Form name attribute |
-| `defaultValues` | `Partial<T>` | Default field values |
-| `onValuesChange` | `(data: T) => void` | Triggered when any field value changes |
-| `onSubmit` | `(data: T) => void \| Promise<void>` | Triggered on successful form submission |
-| `onSubmitFailed` | `(error: any) => void` | Triggered when form submission fails |
-| `form` | `CubeFormInstance<T>` | Form instance created by `useForm` |
-| `labelWidth` | `Styles['width']` | Width of label area for side-positioned labels |
-| `orientation` | `'vertical' \| 'horizontal'` | Form layout orientation |
+### Styling Properties
 
-### Inherited Form Properties
+#### styles
 
-These properties are inherited by all input components within the form:
+Customizes the root form element.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `labelPosition` | `'top' \| 'side' \| 'split'` | Where to place labels relative to inputs. `'top'` places labels above inputs, `'side'` places labels beside inputs with fixed width, `'split'` places labels and inputs on opposite sides without fixed label width |
-| `requiredMark` | `boolean` | Whether to show required field indicators |
-| `isRequired` | `boolean` | Whether fields are required by default |
-| `necessityIndicator` | `'icon' \| 'label'` | Type of necessity indicator |
-| `isReadOnly` | `boolean` | Whether fields are read-only by default |
-| `validationState` | `'valid' \| 'invalid'` | Validation state for all fields |
-| `validateTrigger` | `'onBlur' \| 'onChange' \| 'onSubmit'` | When to trigger validation |
-| `showValid` | `boolean` | Whether to show valid state indicators |
+The Form component does not expose styled sub-elements via the `styles` prop. It uses a simple container layout that can be customized through the main styles property.
 
-### HTML Form Properties
+### Style Properties
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `action` | `string` | Form action URL (for server submission) |
-| `autoComplete` | `string` | Browser autocomplete behavior |
-| `encType` | `string` | Form encoding type |
-| `method` | `'get' \| 'post'` | HTTP method for form submission |
-| `target` | `string` | Target for form submission |
+These properties allow direct style application without using the `styles` prop: `display`, `flow`, `gap`, `placeItems`, `width`, `height`, `padding`, `margin`.
 
 ### Modifiers
 
 The `mods` property accepts the following modifiers:
 
-| Modifier | Type | Description |
-|----------|------|-------------|
-| `has-sider` | `boolean` | Applied when `labelPosition="side"` |
-| `has-split` | `boolean` | Applied when `labelPosition="split"` |
-| `horizontal` | `boolean` | Applied when `orientation="horizontal"` |
-
-## Variants
-
-The Form component does not have built-in variants. Styling is controlled through the `styles` prop and layout properties.
+- **`has-sider`** `boolean` — Applied when `labelPosition="side"`
+- **`has-split`** `boolean` — Applied when `labelPosition="split"`
+- **`horizontal`** `boolean` — Applied when `orientation="horizontal"`
 
 ## Static Methods
 
-The Form component provides several static methods for form functionality:
-
 ### Form.useForm
 
 ```jsx
@@ -95,13 +81,26 @@ const [form] = Form.useForm();
 
 Creates a form instance for programmatic control. See [FormInstance documentation](./FormInstance.md) for detailed API.
 
+You can also pass options:
+
+```jsx
+const [form] = Form.useForm(undefined, undefined, {
+  onSubmit: async (data) => {
+    await apiCall(data);
+  },
+  onValuesChange: (data) => {
+    console.log('Changed:', data);
+  },
+});
+```
+
 ### Form.Submit (SubmitButton)
 
 ```jsx
 <Form.Submit>Submit</Form.Submit>
 ```
 
-Specialized button that automatically handles form submission and loading states.
+Specialized button that automatically handles form submission and loading states. When `onSubmit` returns a promise, the button shows a loading spinner until the promise resolves.
 
 ### Form.Reset (ResetButton)
 
@@ -127,16 +126,16 @@ Component that displays submission errors returned from the `onSubmit` handler.
 </Form.Item>
 ```
 
-**⚠️ Deprecated**: The Field wrapper is deprecated and not recommended for regular use. Input components now have built-in field support, so you can pass field properties directly to them.
+**Deprecated**: The Field wrapper is not recommended for regular use. Input components now have built-in field support, so you can pass field properties directly to them.
 
-The Field component should only be used when wrapping read-only content to make it appear as a form field.
+The Field component should only be used when wrapping read-only content or custom components without built-in field support.
 
 ## Built-in Field Support
 
 **All input components have built-in field support**, meaning you can pass field properties directly to them without needing a wrapper:
 
 ```jsx
-// ✅ Recommended - Direct field properties
+// Recommended — direct field properties
 <Input.Text
   name="email"
   label="Email"
@@ -144,7 +143,7 @@ The Field component should only be used when wrapping read-only content to make
   placeholder="Enter your email"
 />
 
-// ❌ Deprecated - Field wrapper (still works but not recommended)
+// Deprecated — Field wrapper (still works but not recommended)
 <Field name="email" label="Email" rules={[{ required: true, type: 'email' }]}>
   <Input.Text placeholder="Enter your email" />
 </Field>
@@ -154,17 +153,92 @@ The Field component should only be used when wrapping read-only content to make
 
 All input components within a Form accept these field-related properties:
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | Field name for form data |
-| `label` | `ReactNode` | Field label text |
-| `rules` | `ValidationRule[]` | Validation rules array |
-| `required` | `boolean` | Whether the field is required |
-| `help` | `ReactNode` | Help text displayed below the field |
-| `extra` | `ReactNode` | Additional information displayed below help text |
-| `tooltip` | `ReactNode` | Tooltip content for the field label |
-| `dependencies` | `string[]` | Other field names this field depends on |
-| `shouldUpdate` | `boolean \| (prevValues, curValues) => boolean` | When to re-render this field |
+- **`name`** `string` — Field name for form data. Supports dot notation for nested objects (e.g. `"user.email"`)
+- **`label`** `ReactNode` — Field label text
+- **`description`** `ReactNode` — Help text displayed below the field
+- **`errorMessage`** `ReactNode` — Error message displayed when validation fails
+- **`rules`** `ValidationRule[]` — Validation rules array (see [Validation Rules](#validation-rules))
+- **`isRequired`** `boolean` — Whether the field is required
+- **`extra`** `ReactNode` — Additional content displayed next to the label
+- **`tooltip`** `ReactNode` — Tooltip content for the field label
+- **`labelSuffix`** `ReactNode` — Content appended after the label
+- **`isHidden`** `boolean` — Hides the field
+- **`validateTrigger`** `'onBlur' | 'onChange' | 'onSubmit'` — When to validate (overrides form-level setting)
+
+## Validation Rules
+
+The form uses an async rule-based validation system. Each rule is an object with one or more validators:
+
+### Built-in Validators
+
+- **`required`** `boolean` — Field must have a non-empty value
+- **`type`** `string` — Validates data type: `'string'`, `'number'`, `'boolean'`, `'email'`, `'url'`, `'integer'`, `'array'`, `'object'`, `'date'`, `'hex'`, `'regexp'`
+- **`pattern`** `RegExp` — Value must match the regex pattern
+- **`min`** `number` — Minimum length (for strings/arrays) or minimum value (for numbers)
+- **`max`** `number` — Maximum length (for strings/arrays) or maximum value (for numbers)
+- **`len`** `number` — Exact length (for strings/arrays) or exact value (for numbers)
+- **`enum`** `any[]` — Value must be one of the allowed values
+- **`whitespace`** `boolean` — String must not be only whitespace
+- **`validator`** `(rule, value) => Promise<void>` — Custom async validation function. Throw an `Error` to fail validation
+- **`transform`** `(value) => value` — Transform the value before validation
+- **`message`** `string` — Error message displayed when the rule fails
+
+### Rules Example
+
+```jsx
+<Input.Text
+  name="email"
+  label="Email"
+  rules={[
+    { required: true, message: 'Email is required' },
+    { type: 'email', message: 'Please enter a valid email' },
+  ]}
+/>
+
+<Input.Text
+  name="username"
+  label="Username"
+  rules={[
+    { required: true, message: 'Username is required' },
+    { min: 3, message: 'Must be at least 3 characters' },
+    { max: 20, message: 'Must be at most 20 characters' },
+    { pattern: /^[a-zA-Z0-9_]+$/, message: 'Only letters, numbers, and underscores' },
+  ]}
+/>
+
+<Input.Text
+  name="invite"
+  label="Invite Code"
+  rules={[
+    {
+      async validator(rule, value) {
+        const isValid = await checkInviteCode(value);
+        if (!isValid) {
+          throw new Error('Invalid invite code');
+        }
+      },
+    },
+  ]}
+/>
+```
+
+Rules can also be functions that receive the form instance, useful for cross-field validation:
+
+```jsx
+<Input.Password
+  name="confirmPassword"
+  label="Confirm Password"
+  rules={[
+    (form) => ({
+      async validator(rule, value) {
+        if (value !== form.getFieldValue('password')) {
+          throw new Error('Passwords do not match');
+        }
+      },
+    }),
+  ]}
+/>
+```
 
 ## Examples
 
@@ -186,7 +260,7 @@ function BasicForm() {
         type="email"
         rules={[
           { required: true, message: 'Email is required' },
-          { type: 'email', message: 'Please enter a valid email' }
+          { type: 'email', message: 'Please enter a valid email' },
         ]}
         placeholder="Enter your email"
       />
@@ -196,11 +270,51 @@ function BasicForm() {
         label="Password"
         rules={[
           { required: true, message: 'Password is required' },
-          { min: 6, message: 'Password must be at least 6 characters' }
+          { min: 6, message: 'Password must be at least 6 characters' },
         ]}
         placeholder="Enter your password"
       />
 
+      <Form.SubmitError />
+      <SubmitButton>Submit</SubmitButton>
+    </Form>
+  );
+}
+```
+
+### Login Form
+
+An example with async submission that shows loading state:
+
+```jsx
+import { Form, Field, SubmitButton, Input, SubmitError } from '@cube-dev/ui-kit';
+
+export function LoginForm() {
+  async function onSubmit(data) {
+    await Auth.login(data); // { email, password }
+  }
+
+  return (
+    <Form onSubmit={onSubmit} requiredMark={false}>
+      <Input.Text
+        name="email"
+        label="Email"
+        description="Your email"
+        type="email"
+        autoFocus
+        rules={[
+          { required: true, message: 'E-mail required' },
+          { type: 'email', message: 'Please enter a valid e-mail' },
+        ]}
+      />
+
+      <Input.Password
+        name="password"
+        label="Password"
+        rules={[{ required: true, message: 'Password required' }]}
+      />
+
+      <Form.SubmitError />
       <SubmitButton>Submit</SubmitButton>
     </Form>
   );
@@ -236,7 +350,7 @@ function BasicForm() {
 <Form
   defaultValues={{
     email: 'user@example.com',
-    name: 'John Doe'
+    name: 'John Doe',
   }}
   onSubmit={handleSubmit}
 >
@@ -272,7 +386,7 @@ function BasicForm() {
     options={[
       { value: 'us', label: 'United States' },
       { value: 'uk', label: 'United Kingdom' },
-      { value: 'ca', label: 'Canada' }
+      { value: 'ca', label: 'Canada' },
     ]}
   />
 
@@ -286,27 +400,137 @@ function BasicForm() {
 </Form>
 ```
 
+### Nested Field Names
+
+Use dot notation in field names to create nested data structures:
+
+```jsx
+<Form onSubmit={(data) => console.log(data)}>
+  <Input.Text name="user.firstName" label="First Name" />
+  <Input.Text name="user.lastName" label="Last Name" />
+  <Input.Text name="user.address.city" label="City" />
+
+  {/* Submits: { user: { firstName: '...', lastName: '...', address: { city: '...' } } } */}
+  <SubmitButton>Submit</SubmitButton>
+</Form>
+```
+
+### Programmatic Form Control
+
+```jsx
+function ControlledForm() {
+  const [form] = Form.useForm();
+
+  const handleReset = () => {
+    form.resetFields();
+  };
+
+  const handleFillDemo = () => {
+    form.setFieldsValue({
+      email: 'demo@example.com',
+      name: 'Demo User',
+    });
+  };
+
+  return (
+    <Form form={form} onSubmit={handleSubmit}>
+      <Input.Text name="email" label="Email" type="email" />
+      <Input.Text name="name" label="Name" />
+
+      <Space>
+        <SubmitButton>Submit</SubmitButton>
+        <Button onPress={handleReset}>Reset</Button>
+        <Button onPress={handleFillDemo}>Fill Demo Data</Button>
+      </Space>
+    </Form>
+  );
+}
+```
+
 ### When to Use Field Component
 
 The Field component should **only** be used when wrapping read-only content or custom components that don't have built-in field support:
 
 ```jsx
 <Form onSubmit={handleSubmit}>
-  {/* Regular inputs - use built-in field support */}
+  {/* Regular inputs — use built-in field support */}
   <Input.Text name="name" label="Name" rules={[{ required: true }]} />
 
-  {/* Read-only content - use Field wrapper */}
+  {/* Read-only content — use Field wrapper */}
   <Field name="readonly" label="Read-only Information">
     <div>This is some read-only content that should look like a field</div>
   </Field>
 
-  {/* Custom component without field support - use Field wrapper */}
+  {/* Custom component without field support — use Field wrapper */}
   <Field name="custom" label="Custom Component" rules={[{ required: true }]}>
     <CustomComponent />
   </Field>
 </Form>
 ```
 
+### Dialog Form
+
+It's possible to create forms inside dialogs. The `DialogForm` contains all props of `Form` and `Dialog` components. When `onSubmit` returns a promise, the dialog stays open with a loading state until the promise resolves.
+
+```jsx
+import {
+  DialogForm,
+  Field,
+  Paragraph,
+  Input,
+  Text,
+} from '@cube-dev/ui-kit';
+
+export function ConfirmDeletionDialogForm({ name, onSubmit, onDismiss }) {
+  return (
+    <DialogForm
+      title="Delete Deployment"
+      onSubmit={onSubmit}
+      onDismiss={onDismiss}
+      submitProps={{
+        label: 'Delete',
+        theme: 'danger',
+      }}
+      cancelProps={{
+        label: 'I changed my mind',
+      }}
+    >
+      <Paragraph>
+        To delete the instance, please enter its full name:{' '}
+        <Text.Strong>{name}</Text.Strong>
+      </Paragraph>
+
+      <Input.Text
+        name="name"
+        rules={[
+          { required: true, message: 'This field is required' },
+          {
+            async validator(rule, value) {
+              if (value !== name) {
+                throw new Error('Incorrect name');
+              }
+            },
+          },
+        ]}
+        placeholder="Enter the name of the instance"
+      />
+    </DialogForm>
+  );
+}
+```
+
+## Known Differences with AntD Forms
+
+- `onSubmit` instead of `onSuccess`
+- `onSubmitFailed` instead of `onFailed`
+- `defaultValues` instead of `initialValues`
+- `onSubmit` can return a promise — the form and submit button show loading state until the promise resolves
+- Arrays inside form data are not supported
+- `preserve` property is not yet implemented
+- The `Field` component is a virtual wrapper (does not render a DOM element)
+- Nested properties are handled via field names with `.` dot notation
+- Does not support `validating` state (but validation rules can be async)
+
 ## Accessibility
 
 ### Keyboard Navigation
@@ -336,10 +560,10 @@ The Field component should **only** be used when wrapping read-only content or c
 
 1. **Use direct field properties**: Pass field properties directly to input components instead of using Field wrapper
    ```jsx
-   // ✅ Recommended
+   // Recommended
    <Input.Text name="email" label="Email" type="email" rules={[{ required: true }]} />
 
-   // ❌ Deprecated
+   // Deprecated
    <Field name="email" label="Email" rules={[{ required: true }]}>
      <Input.Text type="email" />
    </Field>
@@ -350,7 +574,7 @@ The Field component should **only** be used when wrapping read-only content or c
    <Input.Text name="email" label="Email Address" type="email" />
    ```
 
-3. **Use appropriate validation**: Implement both client-side and server-side validation
+3. **Use appropriate validation**: Combine built-in validators for common cases and custom validators for complex logic
    ```jsx
    <Input.Text
      name="email"
@@ -358,7 +582,7 @@ The Field component should **only** be used when wrapping read-only content or c
      type="email"
      rules={[
        { required: true, message: 'Email is required' },
-       { type: 'email', message: 'Please enter a valid email' }
+       { type: 'email', message: 'Please enter a valid email' },
      ]}
    />
    ```
@@ -384,40 +608,6 @@ The Field component should **only** be used when wrapping read-only content or c
    <Form labelPosition="side">     {/* for wide layouts */}
    ```
 
-## Form Management
-
-Forms can be controlled programmatically using the form instance:
-
-```jsx
-function ControlledForm() {
-  const [form] = Form.useForm();
-
-  const handleReset = () => {
-    form.resetFields();
-  };
-
-  const handleFillDemo = () => {
-    form.setFieldsValue({
-      email: 'demo@example.com',
-      name: 'Demo User'
-    });
-  };
-
-  return (
-    <Form form={form} onSubmit={handleSubmit}>
-      <Input.Text name="email" label="Email" type="email" />
-      <Input.Text name="name" label="Name" />
-
-      <Space>
-        <SubmitButton>Submit</SubmitButton>
-        <Button onPress={handleReset}>Reset</Button>
-        <Button onPress={handleFillDemo}>Fill Demo Data</Button>
-      </Space>
-    </Form>
-  );
-}
-```
-
 ## Integration with Input Components
 
 All input components automatically register with the parent Form and inherit form-level properties:
@@ -437,7 +627,6 @@ Field properties can be passed directly to any input component:
   <Select name="select" label="Select" options={[]} />
   <Checkbox name="checkbox" label="Checkbox" />
   <RadioGroup name="radio" label="Radio Group" options={[]} />
-  <TextArea name="textarea" label="Text Area" />
   <DatePicker name="date" label="Date Picker" />
   <Slider name="slider" label="Slider" />
   <Switch name="switch" label="Switch" />
@@ -447,9 +636,9 @@ Field properties can be passed directly to any input component:
 ## Related Components
 
 - [FormInstance](./FormInstance.md) - Programmatic form control API
+- [Field](./Field.md) - Field wrapper (deprecated for regular use)
 - [Input.Text](../fields/TextInput.md) - Text input field
 - [Input.Password](../fields/PasswordInput.md) - Password input field
 - [Select](../fields/Select.md) - Dropdown selection field
 - [Checkbox](../fields/Checkbox.md) - Checkbox input field
-- [Field](./Field.md) - Field wrapper (deprecated for regular use)
 - [DialogForm](../overlays/DialogForm.md) - Form within a dialog