@ttoss/forms 0.43.1 → 0.43.8

package/README.md

@@ -39,13 +39,9 @@ export const FormComponent = () => {
     resolver: zodResolver(schema),
   });
 
-  const onSubmit = (data) => {
-    console.log(data);
-  };
-
   return (
     <I18nProvider>
-      <Form {...formMethods} onSubmit={onSubmit}>
+      <Form {...formMethods} onSubmit={(data) => console.log(data)}>
         <FormFieldInput name="firstName" label="First Name" />
         <FormFieldInput name="age" label="Age" type="number" />
         <FormFieldCheckbox name="receiveEmails" label="Receive Emails" />
@@ -56,169 +52,40 @@ export const FormComponent = () => {
 };
 ```
 
-## React Hook Form Integration
-
-All React Hook Form APIs are re-exported from `@ttoss/forms`, including hooks like `useForm`, `useController`, `useFieldArray`, and `useFormContext`. See the [React Hook Form documentation](https://react-hook-form.com/docs) for complete API details.
+All React Hook Form APIs (`useForm`, `useController`, `useFieldArray`, `useFormContext`, etc.) are re-exported from `@ttoss/forms`. See the [React Hook Form documentation](https://react-hook-form.com/docs) for details.
 
 ## Zod Validation (Recommended)
 
-Import `z` and `zodResolver` directly from `@ttoss/forms` for schema validation using [Zod](https://zod.dev/):
-
-```tsx
-import { Form, FormFieldInput, useForm, z, zodResolver } from '@ttoss/forms';
-
-const schema = z.object({
-  firstName: z.string().min(1, 'First name is required'),
-});
-
-const MyForm = () => {
-  const formMethods = useForm({
-    resolver: zodResolver(schema),
-  });
-
-  return (
-    <Form {...formMethods} onSubmit={(data) => console.log(data)}>
-      <FormFieldInput name="firstName" label="First Name" defaultValue="" />
-      <Button type="submit">Submit</Button>
-    </Form>
-  );
-};
-```
-
-### Validation Messages
-
-Invalid fields display default error messages like "Field is required". These messages are defined using i18n and can be customized for each locale.
-
-#### Default Zod Messages
-
-The package provides internationalized default messages for common Zod validation errors. These are automatically extracted when you run `pnpm run i18n`:
-
-- **Required field**: `"Field is required"`
-- **Type mismatch**: `"Invalid Value for Field of type {expected}"`
-- **Minimum length**: `"Field must be at least {min} characters"`
-
-To customize these messages for your locale, extract the i18n messages and translate them in your application's i18n files (e.g., `i18n/compiled/pt-BR.json`). See the [i18n-CLI documentation](https://ttoss.dev/docs/modules/packages/i18n-cli/) for more details.
+Import `z` and `zodResolver` directly from `@ttoss/forms`. Invalid fields display i18n-backed default messages (`"Field is required"`, `"Invalid Value for Field of type {expected}"`, `"Field must be at least {min} characters"`). Run `pnpm run i18n` to extract them and translate per locale in your app's i18n files. See the [i18n-CLI documentation](https://ttoss.dev/docs/modules/packages/i18n-cli/) for details.
 
 ### Custom Validations
 
-The package extends Zod with custom validation methods for Brazilian documents:
-
-#### CPF Validation
+The package extends Zod with custom validation methods:
 
 ```tsx
-import { z } from '@ttoss/forms';
+import { z, passwordSchema } from '@ttoss/forms';
 
 const schema = z.object({
-  cpf: z.string().cpf(), // Uses default message: "Invalid CPF"
-  // Or with custom message:
-  cpfCustom: z.string().cpf('CPF inválido'),
+  cpf: z.string().cpf(), // "Invalid CPF"
+  cnpj: z.string().cnpj('Invalid CNPJ'), // custom message
+  password: passwordSchema({ required: true }), // min 8 chars
+  optionalPassword: passwordSchema(), // empty or min 8 chars
 });
 ```
 
-#### CNPJ Validation
-
-````
-
-```tsx
-import { z } from '@ttoss/forms';
-
-const schema = z.object({
-  cnpj: z.string().cnpj(), // Uses default message: "Invalid CNPJ"
-  // Or with custom message:
-  cnpjCustom: z.string().cnpj('CNPJ inválido'),
-});
-````
-
-#### Password Validation
-
-```tsx
-import { passwordSchema } from '@ttoss/forms';
-import { z } from '@ttoss/forms';
-
-const schema = z.object({
-  // Required password (minimum 8 characters)
-  password: passwordSchema({ required: true }),
-
-  // Optional password (accepts empty string or minimum 8 characters)
-  optionalPassword: passwordSchema(),
-});
-```
+Also exports `isCnpjValid(cnpj: string)` for standalone validation.
 
 ## Yup Validation (Deprecated)
 
-> **DEPRECATION WARNING:** Yup support is deprecated and will be removed in a future major version. Please migrate to Zod for new projects. Existing Yup schemas will continue to work, but we recommend planning your migration to Zod.
-
-For legacy projects still using Yup, you can import `yup` and `yupResolver` from `@ttoss/forms`:
-
-```tsx
-import { Form, FormFieldInput, useForm, yup, yupResolver } from '@ttoss/forms';
-
-const schema = yup.object({
-  firstName: yup.string().required(),
-});
-
-const MyForm = () => {
-  const formMethods = useForm({
-    resolver: yupResolver(schema),
-  });
-
-  return (
-    <Form {...formMethods} onSubmit={(data) => console.log(data)}>
-      <FormFieldInput name="firstName" label="First Name" />
-      <Button type="submit">Submit</Button>
-    </Form>
-  );
-};
-```
+> **DEPRECATION WARNING:** Yup support will be removed in a future major version. `yup` and `yupResolver` are still exported from `@ttoss/forms` for legacy projects, but new projects should use Zod.
 
 ## Validation Approaches
 
-There are two ways to validate form fields in `@ttoss/forms`: schema-based validation using Zod schemas with `zodResolver`, and field-level validation using the `rules` prop on individual form fields.
-
-**IMPORTANT:** You cannot mix both validation methods for the same field—choose either schema-based or field-level validation per field.
-
-**When to use schema validation:**
-
-- Cross-field validation
-- Complex business logic
-- Reusable validation patterns
-- Type-safe validation with TypeScript
-
-**When to use `rules`:**
-
-- Simple, field-specific validations
-- Dynamic validation based on component state
-- Quick prototyping
-- Single-field conditional logic
-
-### 1. Schema-based Validation (Recommended)
-
-Use Zod schemas with `zodResolver` for complex validation logic:
-
-```tsx
-import { z, zodResolver } from '@ttoss/forms';
-
-const schema = z.object({
-  email: z.string().email(),
-  age: z.number().min(18).max(100),
-});
-
-const formMethods = useForm({
-  resolver: zodResolver(schema),
-});
-```
-
-**Advantages:**
+There are two ways to validate form fields — choose one per field, they cannot be mixed.
 
-- Centralized validation logic
-- Type-safe with TypeScript
-- Reusable schemas
-- Complex validation patterns
-- Schema composition
+**Schema-based validation** (`zodResolver`) is recommended for cross-field validation, complex business logic, and reusable/type-safe schemas.
 
-### 2. Field-level Validation
-
-Use the `rules` prop on individual form fields for simpler validations:
+**Field-level validation** (`rules` prop) suits simple, field-specific cases:
 
 ```tsx
 <FormFieldInput
@@ -226,398 +93,78 @@ Use the `rules` prop on individual form fields for simpler validations:
   label="Username"
   rules={{
     required: 'Username is required',
-    minLength: {
-      value: 3,
-      message: 'Username must be at least 3 characters',
-    },
+    minLength: { value: 3, message: 'Min 3 characters' },
     pattern: {
       value: /^[a-zA-Z0-9_]+$/,
-      message: 'Only letters, numbers, and underscores allowed',
-    },
-  }}
-/>
-
-<FormFieldInput
-  name="email"
-  label="Email"
-  rules={{
-    required: 'Email is required',
-    validate: (value) => {
-      return value.includes('@') || 'Invalid email format';
+      message: 'Letters, numbers, underscores only',
     },
   }}
 />
 ```
 
-**Available validation rules:**
-
-- `required`: Field is required (string message or boolean)
-- `min`: Minimum value (for numbers)
-- `max`: Maximum value (for numbers)
-- `minLength`: Minimum string length
-- `maxLength`: Maximum string length
-- `pattern`: RegExp pattern
-- `validate`: Custom validation function or object of functions
+Available `rules` keys: `required`, `min`, `max`, `minLength`, `maxLength`, `pattern`, `validate`.
 
 ## Form Field Components
 
-All form field components share common props:
+> **Interactive examples for every component are available at [storybook.ttoss.dev](https://storybook.ttoss.dev/) under the Forms section.**
+
+All form field components share these common props:
 
 - `name` (required): Field name in the form
 - `label`: Field label text
-- `disabled`: Disables the field
+- `disabled`: Disables the field (field-level overrides form-level `disabled`)
 - `defaultValue`: Initial field value
 - `tooltip`: Label tooltip configuration
 - `warning`: Warning message displayed below the field
-- `auxiliaryCheckbox`: Optional auxiliary checkbox configuration
+- `auxiliaryCheckbox`: Optional checkbox rendered between the field and error message — useful for confirmation or terms acceptance. Props: `name`, `label`, `disabled`, `defaultValue`.
 - `sx`: Theme-UI styling object
 
-### Disabling Form Fields
-
-You can disable form fields in two ways:
-
-**1. Disable the entire form:**
-
-Set `disabled: true` in `useForm` to disable all fields at once:
-
-```tsx
-const formMethods = useForm({
-  disabled: true, // Disables all fields
-});
-```
-
-This is particularly useful for preventing user interaction during asynchronous operations:
+To disable all fields at once, pass `disabled` to `useForm`:
 
 ```tsx
-const [isSubmitting, setIsSubmitting] = useState(false);
-
-const formMethods = useForm({
-  disabled: isSubmitting, // Disable form during submission
-});
-
-const onSubmit = async (data) => {
-  setIsSubmitting(true);
-  await saveData(data);
-  setIsSubmitting(false);
-};
+const formMethods = useForm({ disabled: isSubmitting });
 ```
 
-**2. Disable individual fields:**
+### Available Components
 
-Use the `disabled` prop on specific form field components:
+| Component                   | Description                                                                                         |
+| --------------------------- | --------------------------------------------------------------------------------------------------- |
+| `FormFieldInput`            | Text input — supports all HTML input types                                                          |
+| `FormFieldPassword`         | Password input with show/hide toggle                                                                |
+| `FormFieldTextarea`         | Multi-line text input                                                                               |
+| `FormFieldCheckbox`         | Single checkbox                                                                                     |
+| `FormFieldSwitch`           | Toggle switch                                                                                       |
+| `FormFieldRadio`            | Radio button group                                                                                  |
+| `FormFieldRadioCard`        | Radio buttons styled as cards                                                                       |
+| `FormFieldRadioCardIcony`   | Radio cards with icon support                                                                       |
+| `FormFieldSelect`           | Dropdown — defaults to first option; `placeholder` and `defaultValue` cannot be used together       |
+| `FormFieldSegmentedControl` | Segmented buttons wrapping `SegmentedControl` from `@ttoss/ui`; `variant` defaults to `"secondary"` |
+| `FormFieldNumericFormat`    | Numeric input with decimals/thousands formatting                                                    |
+| `FormFieldCurrencyInput`    | Currency input with locale-based separators (see below)                                             |
+| `FormFieldPatternFormat`    | Input with custom format patterns                                                                   |
+| `FormFieldPhone`            | Phone input with optional country-code dropdown (see below)                                         |
+| `FormFieldCreditCardNumber` | Credit card input with automatic formatting                                                         |
 
-```tsx
-<FormFieldInput name="email" label="Email" disabled />
-```
+### FormFieldCurrencyInput — Locale Separators
 
-Field-level `disabled` props override the form-level setting:
-
-```tsx
-const formMethods = useForm({
-  disabled: false,
-});
-
-// This field will be disabled even though the form is enabled
-<FormFieldInput name="id" label="ID" disabled />;
-```
-
-### Auxiliary Checkbox
-
-Form fields can include an optional auxiliary checkbox rendered between the field and error message. This is useful for input confirmation, terms acceptance, or conditional display of other fields.
-
-```tsx
-<FormFieldInput
-  name="email"
-  label="Email"
-  auxiliaryCheckbox={{
-    name: 'confirmEmail',
-    label: 'Send me promotional emails',
-  }}
-/>
-```
-
-The auxiliary checkbox can be disabled independently of the main field:
-
-```tsx
-<FormFieldInput
-  name="email"
-  label="Email"
-  auxiliaryCheckbox={{
-    name: 'confirmEmail',
-    label: 'Send me promotional emails',
-    disabled: true, // Checkbox is disabled, but email field is enabled
-  }}
-/>
-```
-
-**Props for `auxiliaryCheckbox`:**
-
-- `name` (required): Field name for the checkbox
-- `label` (required): Checkbox label text
-- `disabled`: Disables the checkbox (independent of field disabled state)
-- `defaultValue`: Initial checkbox value
-
-The auxiliary checkbox's disabled state is the logical OR of its own `disabled` prop and the field's disabled state.
-
-### FormFieldInput
-
-Text input field supporting all HTML input types.
-
-```tsx
-<FormFieldInput
-  name="email"
-  label="Email"
-  type="email"
-  placeholder="Enter your email"
-/>
-```
-
-### FormFieldPassword
-
-Password input with show/hide toggle.
-
-```tsx
-<FormFieldPassword name="password" label="Password" />
-```
-
-### FormFieldTextarea
-
-Multi-line text input.
-
-```tsx
-<FormFieldTextarea name="description" label="Description" rows={4} />
-```
-
-### FormFieldCheckbox
-
-Single checkbox or checkbox group.
-
-```tsx
-<FormFieldCheckbox name="terms" label="I accept the terms" />
-```
-
-### FormFieldSwitch
-
-Toggle switch component.
-
-```tsx
-<FormFieldSwitch name="notifications" label="Enable notifications" />
-```
-
-### FormFieldRadio
-
-Radio button group.
-
-```tsx
-const options = [
-  { value: 'option1', label: 'Option 1' },
-  { value: 'option2', label: 'Option 2' },
-];
-
-<FormFieldRadio name="choice" label="Choose one" options={options} />;
-```
-
-### FormFieldRadioCard
-
-Radio buttons styled as cards.
-
-```tsx
-<FormFieldRadioCard name="plan" label="Select Plan" options={options} />
-```
-
-### FormFieldRadioCardIcony
-
-Radio cards with icon support.
-
-```tsx
-const options = [
-  { value: 'card', label: 'Credit Card', icon: 'credit-card' },
-  { value: 'bank', label: 'Bank Transfer', icon: 'bank' },
-];
-
-<FormFieldRadioCardIcony
-  name="payment"
-  label="Payment Method"
-  options={options}
-/>;
-```
-
-### FormFieldSelect
-
-Dropdown select field.
-
-```tsx
-const options = [
-  { value: 'ferrari', label: 'Ferrari' },
-  { value: 'mercedes', label: 'Mercedes' },
-  { value: 'bmw', label: 'BMW' },
-];
-
-<FormFieldSelect name="car" label="Choose a car" options={options} />;
-```
-
-#### FormFieldSelect Default Values
-
-`FormFieldSelect` defaults to the first option or a specified `defaultValue`:
-
-```tsx
-// Defaults to "Ferrari"
-<FormFieldSelect name="car" label="Cars" options={options} />
-
-// Defaults to "Mercedes"
-<FormFieldSelect
-  name="car"
-  label="Cars"
-  options={options}
-  defaultValue="Mercedes"
-/>
-```
-
-### FormFieldSegmentedControl
-
-Segmented control field wrapping the `SegmentedControl` from `@ttoss/ui`. Use this field when you want a compact set of mutually-exclusive options presented as segmented buttons.
-
-Props are the common form field props plus any `SegmentedControl` props (except `value` and `className`). Notably, the `variant` prop is supported and defaults to `"secondary"` if not provided.
-
-```tsx
-<FormFieldSegmentedControl
-  name="viewMode"
-  label="View"
-  options={[
-    { value: 'list', label: 'List' },
-    { value: 'grid', label: 'Grid' },
-  ]}
-  variant="primary" // optional, defaults to "secondary"
-  defaultValue="list"
-/>
-```
-
-When using a `placeholder`, an empty option is automatically added if not present:
-
-```tsx
-<FormFieldSelect
-  name="car"
-  label="Cars"
-  options={options}
-  placeholder="Select a car"
-/>
-```
-
-**Note:** `placeholder` and `defaultValue` cannot be used together.
-
-For dynamic options from async data, reset the field after loading:
-
-```tsx
-const { resetField } = useForm();
-const [options, setOptions] = useState([]);
-
-useEffect(() => {
-  // Fetch options
-  const fetchedOptions = await fetchData();
-  setOptions(fetchedOptions);
-  resetField('car', { defaultValue: 'Ferrari' });
-}, []);
-```
-
-### FormFieldNumericFormat
-
-Numeric input with formatting support (decimals, thousands separators).
-
-```tsx
-<FormFieldNumericFormat
-  name="price"
-  label="Price"
-  thousandSeparator=","
-  decimalScale={2}
-/>
-```
-
-### FormFieldCurrencyInput
-
-Currency input with locale-based formatting. The decimal and thousand separators are automatically determined by the locale set in the `I18nProvider`.
-
-```tsx
-<FormFieldCurrencyInput name="amount" label="Amount" prefix="$" />
-```
-
-#### Customizing Separators per Locale
-
-The component uses i18n messages to determine the decimal and thousand separators based on the current locale. You can customize these for each locale in your application:
-
-1. First, extract the i18n messages by running `pnpm run i18n` in your package
-2. In your application's i18n files (e.g., `i18n/compiled/pt-BR.json`), add the custom separators:
+The decimal and thousand separators are driven by i18n. To customize per locale, add to your app's i18n file (e.g., `i18n/compiled/pt-BR.json`):
 
 ```json
 {
-  "JnCaDG": ",", // Decimal separator (default: ".")
-  "0+4wTp": "." // Thousand separator (default: ",")
+  "JnCaDG": ",",
+  "0+4wTp": "."
 }
 ```
 
-This approach allows each locale to define its own number formatting rules, which will be automatically applied to all currency inputs.
-
-For more information about the i18n workflow, see the [i18n-CLI documentation](https://ttoss.dev/docs/modules/packages/i18n-cli/).
+### FormFieldPhone — Key Props
 
-### FormFieldPatternFormat
-
-Input with custom format patterns.
-
-```tsx
-<FormFieldPatternFormat
-  name="phone"
-  label="Phone"
-  format="+1 (###) ###-####"
-  mask="_"
-/>
-```
-
-### FormFieldPhone
-
-Generic phone number field with an optional country-code dropdown. By default it renders a dropdown populated with `COMMON_PHONE_COUNTRY_CODES` (15 common countries + a Manual entry). The component manages the selected country code internally — no external state is needed.
-
-```tsx
-import { FormFieldPhone, COMMON_PHONE_COUNTRY_CODES } from '@ttoss/forms';
-
-// Minimal — dropdown defaults to COMMON_PHONE_COUNTRY_CODES, starts in Manual mode
-<FormFieldPhone name="phone" label="Phone" />
-
-// Set an initial country code (US +1)
-<FormFieldPhone name="phone" label="Phone" defaultCountryCode="+1" />
-
-// React to country-code changes without managing state
-<FormFieldPhone
-  name="phone"
-  label="Phone"
-  defaultCountryCode="+1"
-  onCountryCodeChange={(code) => console.log('selected', code)}
-/>
-
-// No dropdown — plain masked input with a fixed country code
-<FormFieldPhone
-  name="phone"
-  label="Phone"
-  defaultCountryCode="+1"
-  format="(###) ###-####"
-  countryCodeOptions={[]}
-/>
-```
-
-The submitted value always includes the country code prefix (e.g. `{ phone: '+15555555555' }`). When the user selects the **Manual** entry, the mask is removed and the user can type any international number freely (the value is stored with a `+` prefix).
-
-**Key props:**
+The submitted value always includes the country code prefix (e.g. `{ phone: '+15555555555' }`). When the user selects the **Manual** entry, the mask is removed and any international number can be typed freely.
 
 - `defaultCountryCode`: Initial calling code (e.g. `'+1'`). Defaults to the first entry in `countryCodeOptions`.
-- `format`: Pattern string or function for the local number part (e.g. `'(###) ###-####'`).
-- `countryCodeOptions`: List of `CountryCodeOption` objects. Defaults to `COMMON_PHONE_COUNTRY_CODES`. Pass `[]` to hide the dropdown.
-- `onCountryCodeChange`: Optional callback fired when the user picks a different country code.
-
-### FormFieldCreditCardNumber
-
-Credit card input with automatic formatting.
-
-```tsx
-<FormFieldCreditCardNumber name="cardNumber" label="Card Number" />
-```
+- `format`: Pattern string for the local number part (e.g. `'(###) ###-####'`).
+- `countryCodeOptions`: Defaults to `COMMON_PHONE_COUNTRY_CODES`. Pass `[]` to hide the dropdown.
+- `onCountryCodeChange`: Callback fired when the user picks a different country code.
+- `countryCodeName`: Stores the selected country code as a separate form field (e.g. `{ phone: '+15555555555', countryCode: '+1' }`).
 
 ### Brazil-Specific Fields
 
@@ -631,161 +178,30 @@ import {
 } from '@ttoss/forms/brazil';
 ```
 
-#### FormFieldCEP
-
-Brazilian postal code (CEP) input with automatic formatting.
-
-```tsx
-<FormFieldCEP name="cep" label="CEP" />
-```
-
-#### FormFieldCNPJ
-
-Brazilian tax ID (CNPJ) input with validation and formatting.
-
-```tsx
-<FormFieldCNPJ name="cnpj" label="CNPJ" />
-```
-
-The package also exports `isCnpjValid(cnpj: string)` for standalone validation.
-
-#### FormFieldPhone
-
-Brazilian phone number input with automatic formatting and the `+55` country code pre-set.
-
-```tsx
-<FormFieldPhone name="phone" label="Phone" />
-```
+- `FormFieldCEP` — postal code with automatic formatting
+- `FormFieldCNPJ` — tax ID with validation and formatting
+- `FormFieldPhone` — phone with `+55` country code pre-set
 
 ## FormGroup
 
-Groups related fields with an optional title, description, and layout direction.
+Groups related fields with an optional title, description, and layout direction. Pass `name` to display a group-level validation error (e.g. for array fields).
 
-```tsx
-<FormGroup title="Personal Information" direction="row">
-  <FormFieldInput name="firstName" label="First Name" />
-  <FormFieldInput name="lastName" label="Last Name" />
-</FormGroup>
-
-<FormGroup title="Address" description="Where we'll send your order">
-  <FormFieldInput name="street" label="Street" />
-  <FormFieldInput name="city" label="City" />
-</FormGroup>
-```
+**Props:** `title`, `description`, `direction` (`'row'` | `'column'`, default `'column'`), `name`.
 
-Nest `FormGroup` components to create hierarchical sections:
-
-```tsx
-<FormGroup title="Personal details">
-  <FormFieldInput name="firstName" label="First name" />
-  <FormFieldInput name="lastName" label="Last name" />
-
-  <FormGroup title="Address" direction="row">
-    <FormFieldInput name="city" label="City" />
-    <FormFieldInput name="zip" label="ZIP" />
-  </FormGroup>
-</FormGroup>
-```
-
-To display a group-level validation error (e.g. for an array field), pass the `name` prop:
-
-```tsx
-<FormGroup name="items" title="Items">
-  {fields.map((field, i) => (
-    <FormFieldInput key={field.id} name={`items[${i}].value`} label="Value" />
-  ))}
-</FormGroup>
-```
-
-**Props:**
-
-- `title`: Optional heading displayed above the group's children
-- `description`: Optional description displayed below the title
-- `direction`: Layout direction (`'row'` | `'column'`, default: `'column'`)
-- `name`: Field name used to display a group-level validation error message
+See [Storybook](https://storybook.ttoss.dev/?path=/story/forms-formgroup) for nested group examples.
 
 ## Multistep Forms
 
-Import from `@ttoss/forms/multistep-form`:
+Import from `@ttoss/forms/multistep-form`. Each step provides its own `schema` (Zod) and `fields` (React elements); data is accumulated and passed to `onSubmit` on the final step.
 
 ```tsx
 import { MultistepForm } from '@ttoss/forms/multistep-form';
-import { FormFieldInput, z } from '@ttoss/forms';
-
-const steps = [
-  {
-    label: 'Step 1',
-    question: 'What is your name?',
-    fields: <FormFieldInput name="name" label="Name" />,
-    schema: z.object({
-      name: z.string().min(1, 'Name is required'),
-    }),
-  },
-  {
-    label: 'Step 2',
-    question: 'How old are you?',
-    fields: <FormFieldInput type="number" name="age" label="Age" />,
-    defaultValues: { age: 18 },
-    schema: z.object({
-      age: z.number().min(18, 'Must be at least 18'),
-    }),
-  },
-];
-
-const MyForm = () => {
-  return (
-    <MultistepForm
-      steps={steps}
-      onSubmit={(data) => console.log(data)}
-      footer="© 2024 Company"
-      header={{
-        variant: 'logo',
-        src: '/logo.png',
-        onClose: () => console.log('closed'),
-      }}
-    />
-  );
-};
 ```
 
-### MultistepForm Props
-
-- `steps`: Array of step configurations
-- `onSubmit`: Handler called with complete form data
-- `footer`: Footer text
-- `header`: Header configuration (see below)
-
-### Step Configuration
-
-Each step object contains:
-
-- `label`: Step label for navigation
-- `question`: Question or instruction text
-- `fields`: React element(s) containing form fields
-- `schema`: Zod validation schema
-- `defaultValues`: Optional default values for step fields
-
-### Header Types
-
-**Logo Header:**
+**`MultistepForm` props:** `steps`, `onSubmit`, `footer`, `header`.
 
-```tsx
-{
-  variant: 'logo',
-  src: '/path/to/logo.png',
-  onClose: () => console.log('Close clicked')
-}
-```
+**Step object:** `label`, `question`, `fields`, `schema`, `defaultValues`.
 
-**Titled Header:**
+**`header` variants:** `{ variant: 'logo', src, onClose }` or `{ variant: 'titled', title, leftIcon, rightIcon, onLeftIconClick, onRightIconClick }`.
 
-```tsx
-{
-  variant: 'titled',
-  title: 'Form Title',
-  leftIcon: 'arrow-left',
-  rightIcon: 'close',
-  onLeftIconClick: () => console.log('Back'),
-  onRightIconClick: () => console.log('Close')
-}
-```
+See [Storybook](https://storybook.ttoss.dev/?path=/story/forms-multistepform) for an interactive example.

package/dist/Brazil/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { FieldValues, FieldPath } from 'react-hook-form';
-import { a as FormFieldPatternFormatProps, F as FormFieldProps, d as FormFieldPhoneProps$1 } from '../FormFieldPhone--tC0Hlcf.js';
+import { a as FormFieldPatternFormatProps, F as FormFieldProps, d as FormFieldPhoneProps$1 } from '../FormFieldPhone-Dp3kaJbz.js';
 import { PatternFormatProps, NumberFormatBaseProps } from 'react-number-format';
 import '@ttoss/ui';
 import 'react';

package/dist/{FormFieldPhone--tC0Hlcf.d.ts → FormFieldPhone-Dp3kaJbz.d.ts}

@@ -143,6 +143,19 @@ type FormFieldPhoneProps<TFieldValues extends FieldValues = FieldValues, TName e
      * caller wants to react to country-code changes.
      */
     onCountryCodeChange?: (countryCode: string) => void;
+    /**
+     * When provided, the selected country code is stored as a separate field
+     * in the form under this name (e.g. `'countryCode'`). This allows the
+     * submitted form data to include both the full phone value and the
+     * selected calling code independently.
+     *
+     * @example
+     * ```tsx
+     * // Form data: { phone: '+15555555555', countryCode: '+1' }
+     * <FormFieldPhone name="phone" label="Phone" countryCodeName="countryCode" />
+     * ```
+     */
+    countryCodeName?: string;
 };
 /**
  * Generic phone number form field that supports an optional country code prefix.
@@ -217,7 +230,18 @@ type FormFieldPhoneProps<TFieldValues extends FieldValues = FieldValues, TName e
  *   countryCodeOptions={[]}
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Store the selected country code as a separate form field.
+ * // Submitted data: { phone: '+15555555555', countryCode: '+1' }
+ * <FormFieldPhone
+ *   name="phone"
+ *   label="Phone"
+ *   countryCodeName="countryCode"
+ * />
+ * ```
  */
-declare const FormFieldPhone: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ disabled, defaultCountryCode: countryCodeProp, format, countryCodeOptions, onCountryCodeChange, ...props }: FormFieldPhoneProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
+declare const FormFieldPhone: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ disabled, defaultCountryCode: countryCodeProp, format, countryCodeOptions, onCountryCodeChange, countryCodeName, ...props }: FormFieldPhoneProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
 
 export { type CountryCodeOption as C, type FormFieldProps as F, MANUAL_PHONE_COUNTRY_CODE as M, type FormFieldPatternFormatProps as a, FormField as b, FormFieldPatternFormat as c, type FormFieldPhoneProps as d, FormFieldPhone as e, COMMON_PHONE_COUNTRY_CODES as f };

package/dist/esm/Brazil/index.js

@@ -1,6 +1,6 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 import * as React from 'react';
-import { FormField, FormFieldCNPJ, FormFieldCPF, FormFieldPatternFormat, FormFieldPhone, __name, isCnpjValid, isCpfValid } from "../chunk-U7QBQHMU.js";
+import { FormField, FormFieldCNPJ, FormFieldCPF, FormFieldPatternFormat, FormFieldPhone, __name, isCnpjValid, isCpfValid } from "../chunk-NEIQETLB.js";
 
 // src/Brazil/FormFieldCEP.tsx
 var FormFieldCEP = /* @__PURE__ */__name(({

package/dist/esm/MultistepForm/index.js

@@ -1,7 +1,7 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 import * as React from 'react';
-import { Form, useForm, yupResolver } from "../chunk-3M2OR5NH.js";
-import { __name } from "../chunk-U7QBQHMU.js";
+import { Form, useForm, yupResolver } from "../chunk-UT6OKRDR.js";
+import { __name } from "../chunk-NEIQETLB.js";
 
 // src/MultistepForm/MultistepForm.tsx
 import { Flex as Flex6 } from "@ttoss/ui";

package/dist/esm/{chunk-U7QBQHMU.js → chunk-NEIQETLB.js}

@@ -268,6 +268,59 @@ var FormFieldPatternFormat = /* @__PURE__ */__name(({
   });
 }, "FormFieldPatternFormat");
 
+// src/FormFieldSelect.tsx
+import { Select } from "@ttoss/ui";
+var FormFieldSelect = /* @__PURE__ */__name(({
+  disabled,
+  ...props
+}) => {
+  const {
+    label,
+    name,
+    labelTooltip,
+    warning,
+    sx,
+    css,
+    rules,
+    id,
+    defaultValue,
+    onBlur,
+    onChange,
+    ...selectProps
+  } = props;
+  return /* @__PURE__ */React.createElement(FormField, {
+    id,
+    label,
+    name,
+    labelTooltip,
+    warning,
+    sx,
+    css,
+    defaultValue,
+    rules,
+    disabled,
+    render: /* @__PURE__ */__name(({
+      field,
+      fieldState
+    }) => {
+      return /* @__PURE__ */React.createElement(Select, {
+        ...selectProps,
+        ...field,
+        onBlur: /* @__PURE__ */__name(e => {
+          field.onBlur();
+          onBlur?.(e);
+        }, "onBlur"),
+        onChange: /* @__PURE__ */__name(newValue => {
+          field.onChange(newValue);
+          onChange?.(newValue);
+        }, "onChange"),
+        isDisabled: disabled ?? field.disabled,
+        "aria-invalid": fieldState.error ? "true" : void 0
+      });
+    }, "render")
+  });
+}, "FormFieldSelect");
+
 // src/phoneCountryCodes.ts
 var MANUAL_PHONE_COUNTRY_CODE = "manual";
 var COMMON_PHONE_COUNTRY_CODES = [{
@@ -336,12 +389,14 @@ var COMMON_PHONE_COUNTRY_CODES = [{
 }];
 
 // src/FormFieldPhone.tsx
-import { Box, Flex as Flex3, Input as Input2, Select } from "@ttoss/ui";
+import { Box, Flex as Flex3, Input as Input2 } from "@ttoss/ui";
 import * as React4 from "react";
+import { useFormContext as useFormContext3 } from "react-hook-form";
 import { NumericFormat, PatternFormat as PatternFormat2 } from "react-number-format";
 var PhoneDropdownWrapper = /* @__PURE__ */__name(({
   id,
-  countryCode,
+  countryCodeFieldName,
+  defaultCountryCode,
   countryCodeOptions,
   disabled,
   onCountryCodeChange,
@@ -357,9 +412,10 @@ var PhoneDropdownWrapper = /* @__PURE__ */__name(({
     sx: {
       minWidth: "180px"
     }
-  }, /* @__PURE__ */React4.createElement(Select, {
+  }, /* @__PURE__ */React4.createElement(FormFieldSelect, {
+    name: countryCodeFieldName,
+    defaultValue: defaultCountryCode,
     options: countryCodeOptions,
-    value: countryCode,
     disabled,
     onChange: /* @__PURE__ */__name(value => {
       if (value !== void 0) {
@@ -381,6 +437,7 @@ var FormFieldPhone = /* @__PURE__ */__name(({
   format,
   countryCodeOptions = COMMON_PHONE_COUNTRY_CODES,
   onCountryCodeChange,
+  countryCodeName,
   ...props
 }) => {
   const {
@@ -399,9 +456,13 @@ var FormFieldPhone = /* @__PURE__ */__name(({
     placeholder,
     ...patternFormatProps
   } = props;
-  const [countryCode, setCountryCode] = React4.useState(countryCodeProp ?? countryCodeOptions[0]?.value ?? void 0);
+  const {
+    watch
+  } = useFormContext3();
+  const countryCodeFieldName = countryCodeName ?? `${String(name)}CountryCode`;
+  const defaultCountryCode = countryCodeProp ?? countryCodeOptions[0]?.value ?? void 0;
+  const countryCode = watch(countryCodeFieldName) ?? defaultCountryCode;
   const handleCountryCodeChange = /* @__PURE__ */__name(code => {
-    setCountryCode(code);
     onCountryCodeChange?.(code);
   }, "handleCountryCodeChange");
   const isManual = countryCode === MANUAL_PHONE_COUNTRY_CODE;
@@ -414,7 +475,16 @@ var FormFieldPhone = /* @__PURE__ */__name(({
     return countryCode && !isManual ? `${countryCode} ${baseFormat}` : baseFormat;
   }, "getFormat");
   const showDropdown = countryCodeOptions.length > 0;
-  return /* @__PURE__ */React4.createElement(FormField, {
+  const hiddenCountryCodeSelect = !showDropdown && countryCodeName ? /* @__PURE__ */React4.createElement(Box, {
+    sx: {
+      display: "none"
+    }
+  }, /* @__PURE__ */React4.createElement(FormFieldSelect, {
+    name: countryCodeName,
+    defaultValue: defaultCountryCode,
+    options: []
+  })) : null;
+  return /* @__PURE__ */React4.createElement(React4.Fragment, null, hiddenCountryCodeSelect, /* @__PURE__ */React4.createElement(FormField, {
     id,
     label,
     name,
@@ -473,7 +543,8 @@ var FormFieldPhone = /* @__PURE__ */__name(({
         return inputNode;
       }
       return /* @__PURE__ */React4.createElement(PhoneDropdownWrapper, {
-        countryCode,
+        countryCodeFieldName,
+        defaultCountryCode,
         countryCodeOptions,
         disabled: disabled ?? field.disabled,
         onCountryCodeChange: handleCountryCodeChange,
@@ -483,7 +554,7 @@ var FormFieldPhone = /* @__PURE__ */__name(({
         inputNode
       });
     }, "render")
-  });
+  }));
 }, "FormFieldPhone");
 
 // src/Brazil/FormFieldCNPJ.tsx
@@ -658,4 +729,4 @@ var FormFieldCPF = /* @__PURE__ */__name(({
     }, "render")
   });
 }, "FormFieldCPF");
-export { __name, FormErrorMessage, FormField, FormFieldPatternFormat, MANUAL_PHONE_COUNTRY_CODE, COMMON_PHONE_COUNTRY_CODES, FormFieldPhone, isCnpjValid, FormFieldCNPJ, isCpfValid, FormFieldCPF };
+export { __name, FormErrorMessage, FormField, FormFieldPatternFormat, FormFieldSelect, MANUAL_PHONE_COUNTRY_CODE, COMMON_PHONE_COUNTRY_CODES, FormFieldPhone, isCnpjValid, FormFieldCNPJ, isCpfValid, FormFieldCPF };

package/dist/esm/{chunk-3M2OR5NH.js → chunk-UT6OKRDR.js}

@@ -1,6 +1,6 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
 import * as React from 'react';
-import { FormErrorMessage, FormField, FormFieldPatternFormat, __name, isCnpjValid, isCpfValid } from "./chunk-U7QBQHMU.js";
+import { FormErrorMessage, FormField, FormFieldPatternFormat, __name, isCnpjValid, isCpfValid } from "./chunk-NEIQETLB.js";
 
 // src/Form.tsx
 import { Box as Box2 } from "@ttoss/ui";
@@ -797,59 +797,6 @@ var FormFieldSegmentedControl = /* @__PURE__ */__name(({
   });
 }, "FormFieldSegmentedControl");
 
-// src/FormFieldSelect.tsx
-import { Select } from "@ttoss/ui";
-var FormFieldSelect = /* @__PURE__ */__name(({
-  disabled,
-  ...props
-}) => {
-  const {
-    label,
-    name,
-    labelTooltip,
-    warning,
-    sx,
-    css,
-    rules,
-    id,
-    defaultValue,
-    onBlur,
-    onChange,
-    ...selectProps
-  } = props;
-  return /* @__PURE__ */React.createElement(FormField, {
-    id,
-    label,
-    name,
-    labelTooltip,
-    warning,
-    sx,
-    css,
-    defaultValue,
-    rules,
-    disabled,
-    render: /* @__PURE__ */__name(({
-      field,
-      fieldState
-    }) => {
-      return /* @__PURE__ */React.createElement(Select, {
-        ...selectProps,
-        ...field,
-        onBlur: /* @__PURE__ */__name(e => {
-          field.onBlur();
-          onBlur?.(e);
-        }, "onBlur"),
-        onChange: /* @__PURE__ */__name(newValue => {
-          field.onChange(newValue);
-          onChange?.(newValue);
-        }, "onChange"),
-        isDisabled: disabled ?? field.disabled,
-        "aria-invalid": fieldState.error ? "true" : void 0
-      });
-    }, "render")
-  });
-}, "FormFieldSelect");
-
 // src/FormFieldSwitch.tsx
 import { Switch } from "@ttoss/ui";
 var FormFieldSwitch = /* @__PURE__ */__name(({
@@ -1124,4 +1071,4 @@ import { yupResolver } from "@hookform/resolvers/yup";
 import { zodResolver } from "@hookform/resolvers/zod";
 import { Controller, FormProvider as FormProvider2, useController, useFieldArray, useForm, useFormContext, useFormState, useWatch } from "react-hook-form";
 export * from "react-hook-form";
-export { FormActions, useFormGroup, FormGroup, Form, FormFieldCheckbox, FormFieldCreditCardNumber, FormFieldNumericFormat, FormFieldCurrencyInput, FormFieldDatePicker, FormFieldInput, FormFieldPassword, FormFieldRadio, FormFieldRadioCard, FormFieldRadioCardIcony, FormFieldSegmentedControl, FormFieldSelect, FormFieldSwitch, FormFieldTextarea, yup2 as yup, z3 as z, yupResolver, zodResolver, Controller, FormProvider2 as FormProvider, useController, useFieldArray, useForm, useFormContext, useFormState, useWatch };
+export { FormActions, useFormGroup, FormGroup, Form, FormFieldCheckbox, FormFieldCreditCardNumber, FormFieldNumericFormat, FormFieldCurrencyInput, FormFieldDatePicker, FormFieldInput, FormFieldPassword, FormFieldRadio, FormFieldRadioCard, FormFieldRadioCardIcony, FormFieldSegmentedControl, FormFieldSwitch, FormFieldTextarea, yup2 as yup, z3 as z, yupResolver, zodResolver, Controller, FormProvider2 as FormProvider, useController, useFieldArray, useForm, useFormContext, useFormState, useWatch };

package/dist/esm/index.js

@@ -1,4 +1,4 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { Controller, Form, FormActions, FormFieldCheckbox, FormFieldCreditCardNumber, FormFieldCurrencyInput, FormFieldDatePicker, FormFieldInput, FormFieldNumericFormat, FormFieldPassword, FormFieldRadio, FormFieldRadioCard, FormFieldRadioCardIcony, FormFieldSegmentedControl, FormFieldSelect, FormFieldSwitch, FormFieldTextarea, FormGroup, FormProvider, useController, useFieldArray, useForm, useFormContext, useFormGroup, useFormState, useWatch, yup, yupResolver, z, zodResolver } from "./chunk-3M2OR5NH.js";
-import { COMMON_PHONE_COUNTRY_CODES, FormErrorMessage, FormField, FormFieldPatternFormat, FormFieldPhone, MANUAL_PHONE_COUNTRY_CODE } from "./chunk-U7QBQHMU.js";
+import { Controller, Form, FormActions, FormFieldCheckbox, FormFieldCreditCardNumber, FormFieldCurrencyInput, FormFieldDatePicker, FormFieldInput, FormFieldNumericFormat, FormFieldPassword, FormFieldRadio, FormFieldRadioCard, FormFieldRadioCardIcony, FormFieldSegmentedControl, FormFieldSwitch, FormFieldTextarea, FormGroup, FormProvider, useController, useFieldArray, useForm, useFormContext, useFormGroup, useFormState, useWatch, yup, yupResolver, z, zodResolver } from "./chunk-UT6OKRDR.js";
+import { COMMON_PHONE_COUNTRY_CODES, FormErrorMessage, FormField, FormFieldPatternFormat, FormFieldPhone, FormFieldSelect, MANUAL_PHONE_COUNTRY_CODE } from "./chunk-NEIQETLB.js";
 export { COMMON_PHONE_COUNTRY_CODES, Controller, Form, FormActions, FormErrorMessage, FormField, FormFieldCheckbox, FormFieldCreditCardNumber, FormFieldCurrencyInput, FormFieldDatePicker, FormFieldInput, FormFieldNumericFormat, FormFieldPassword, FormFieldPatternFormat, FormFieldPhone, FormFieldRadio, FormFieldRadioCard, FormFieldRadioCardIcony, FormFieldSegmentedControl, FormFieldSelect, FormFieldSwitch, FormFieldTextarea, FormGroup, FormProvider, MANUAL_PHONE_COUNTRY_CODE, useController, useFieldArray, useForm, useFormContext, useFormGroup, useFormState, useWatch, yup, yupResolver, z, zodResolver };

package/dist/index.d.ts

@@ -4,8 +4,8 @@ import * as React from 'react';
 import { FieldValues, FormProviderProps, FieldName, FieldPath } from 'react-hook-form';
 export * from 'react-hook-form';
 export { Controller, FormProvider, useController, useFieldArray, useForm, useFormContext, useFormState, useWatch } from 'react-hook-form';
-import { F as FormFieldProps, a as FormFieldPatternFormatProps } from './FormFieldPhone--tC0Hlcf.js';
-export { f as COMMON_PHONE_COUNTRY_CODES, C as CountryCodeOption, b as FormField, c as FormFieldPatternFormat, e as FormFieldPhone, d as FormFieldPhoneProps, M as MANUAL_PHONE_COUNTRY_CODE } from './FormFieldPhone--tC0Hlcf.js';
+import { F as FormFieldProps, a as FormFieldPatternFormatProps } from './FormFieldPhone-Dp3kaJbz.js';
+export { f as COMMON_PHONE_COUNTRY_CODES, C as CountryCodeOption, b as FormField, c as FormFieldPatternFormat, e as FormFieldPhone, d as FormFieldPhoneProps, M as MANUAL_PHONE_COUNTRY_CODE } from './FormFieldPhone-Dp3kaJbz.js';
 import { NumericFormatProps } from 'react-number-format';
 import { DateRange } from '@ttoss/components/DatePicker';
 import './typings.d-BzNUo1mD.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/forms",
-  "version": "0.43.1",
+  "version": "0.43.8",
   "license": "MIT",
   "author": "ttoss",
   "contributors": [
@@ -40,25 +40,25 @@
   },
   "peerDependencies": {
     "react": ">=16.8.0",
-    "@ttoss/components": "^2.13.2",
-    "@ttoss/react-i18n": "^2.1.0",
-    "@ttoss/ui": "^6.8.0"
+    "@ttoss/components": "^2.14.5",
+    "@ttoss/ui": "^6.9.5",
+    "@ttoss/react-i18n": "^2.2.5"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/react": "^19.2.14",
-    "jest": "^30.2.0",
+    "jest": "^30.3.0",
     "react": "^19.2.4",
     "react-error-boundary": "^6.1.0",
     "tsup": "^8.5.1",
     "yup": "^1.7.1",
-    "@ttoss/config": "^1.36.0",
-    "@ttoss/components": "^2.13.2",
-    "@ttoss/i18n-cli": "^0.7.39",
-    "@ttoss/react-icons": "^0.6.0",
-    "@ttoss/test-utils": "^4.1.0",
-    "@ttoss/react-i18n": "^2.1.0",
-    "@ttoss/ui": "^6.8.0"
+    "@ttoss/components": "^2.14.5",
+    "@ttoss/i18n-cli": "^0.8.5",
+    "@ttoss/config": "^1.37.5",
+    "@ttoss/react-icons": "^0.7.5",
+    "@ttoss/test-utils": "^4.2.5",
+    "@ttoss/react-i18n": "^2.2.5",
+    "@ttoss/ui": "^6.9.5"
   },
   "publishConfig": {
     "access": "public",