@ttoss/forms 0.32.0 → 0.32.1

package/README.md

@@ -1,10 +1,6 @@
 # @ttoss/forms
 
-**@ttoss/forms** is a library of React form components for building form components. It is built on top of [React Hook Form](https://react-hook-form.com/) and [Yup](https://github.com/jquense/yup).
-
-## ESM Only
-
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+**@ttoss/forms** provides React form components built on [React Hook Form](https://react-hook-form.com/) and [Yup](https://github.com/jquense/yup), with integrated i18n support and theme styling.
 
 ## Installation
 
@@ -13,13 +9,20 @@ pnpm i @ttoss/forms @ttoss/react-i18n @ttoss/ui @emotion/react
 pnpm i --save-dev @ttoss/i18n-cli
 ```
 
-Check the [@ttoss/react-i18n](https://ttoss.dev/docs/modules/packages/react-i18n/) docs to see how to configure the i18n.
+**Note:** This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). I18n configuration is required—see [@ttoss/react-i18n](https://ttoss.dev/docs/modules/packages/react-i18n/) for setup details.
 
-## Quickstart
+## Quick Start
 
 ```tsx
 import { Button } from '@ttoss/ui';
-import { Form, FormField, yupResolver, useForm, yup } from '@ttoss/forms';
+import {
+  Form,
+  FormFieldCheckbox,
+  FormFieldInput,
+  useForm,
+  yup,
+  yupResolver,
+} from '@ttoss/forms';
 import { I18nProvider } from '@ttoss/react-i18n';
 
 const schema = yup.object({
@@ -34,12 +37,16 @@ export const FormComponent = () => {
     resolver: yupResolver(schema),
   });
 
+  const onSubmit = (data) => {
+    console.log(data);
+  };
+
   return (
     <I18nProvider>
-      <Form {...formMethods} onSubmit={action('onSubmit')}>
-        <FormField.Input name="firstName" label="First Name" />
-        <FormField.Input name="age" label="Age" />
-        <FormField.Checkbox name="receiveEmails" label="Receive Emails" />
+      <Form {...formMethods} onSubmit={onSubmit}>
+        <FormFieldInput name="firstName" label="First Name" />
+        <FormFieldInput name="age" label="Age" type="number" />
+        <FormFieldCheckbox name="receiveEmails" label="Receive Emails" />
         <Button type="submit">Submit</Button>
       </Form>
     </I18nProvider>
@@ -47,240 +54,434 @@ export const FormComponent = () => {
 };
 ```
 
-**WARNING:** I18n is necessary as `Forms` module has some integrations with it.
+## React Hook Form Integration
 
-## React Hook Form
-
-It exposes all the API from react-hook-form, so you can use all the methods and properties from it. Check the [React Hook Form](https://react-hook-form.com/docs) documentation for more details.
+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.
 
 ## Yup Validation
 
-You can also use yup and all of API from react-hook-form importing `import { yup, useForm } from @ttoss/forms`
+Import `yup` and `yupResolver` directly from `@ttoss/forms`:
 
 ```tsx
-const FirstNameForm = () => {
-  const schema = yup.object({
-    firstName: yup.string().required(),
-  });
+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={onSubmit}>
-      <FormField
-        name="firstName"
-        label="First Name"
-        defaultValue={''}
-        render={({ field }) => {
-          return <Input {...field} />;
-        }}
-      />
+    <Form {...formMethods} onSubmit={(data) => console.log(data)}>
+      <FormFieldInput name="firstName" label="First Name" defaultValue="" />
       <Button type="submit">Submit</Button>
     </Form>
   );
 };
 ```
 
-When field is invalid according with schema requirements, it gonna return the default. In this example, for required fields, it gonna be `Field is required`.
+### Validation Messages
 
-You can translate the message or change the generic message by configuring the messages in the json i18n definition. To use this, please, refer to the docs on [React-i18n](https://ttoss.dev/docs/modules/packages/react-i18n/) and [i18n-CLI](https://ttoss.dev/docs/modules/packages/i18n-cli/).
+Invalid fields display default error messages like "Field is required". Customize these messages via i18n configuration—see [React-i18n](https://ttoss.dev/docs/modules/packages/react-i18n/) and [i18n-CLI](https://ttoss.dev/docs/modules/packages/i18n-cli/).
 
-### Custom Error messages
+### Custom Error Messages
 
-You can, also, pass custom error messages to the validation constraints in schema. It's really recommended that you use i18n pattern to create your custom message.
+Provide custom error messages using i18n patterns:
 
 ```tsx
-const ComponentForm = () => {
+import { useI18n } from '@ttoss/react-i18n';
+import { useMemo } from 'react';
+
+const MyForm = () => {
   const {
     intl: { formatMessage },
   } = useI18n();
 
-  const schema = useMemo(() => {
-    return yup.object({
-      name: yup.string().required(
-        formatMessage({
-          defaultMessage: 'Name must be not null',
-          description: 'Name required constraint',
-        })
-      ),
-      age: yup.number().min(
-        18,
-        formatMessage(
-          {
-            defaultMessage: 'You should be {age} years old or more',
-            description: 'Min Age Constriant message',
-          },
-          { age: 18 }
-        )
-      ),
-    });
-  }, [formatMessage]);
-
-  // ...
+  const schema = useMemo(
+    () =>
+      yup.object({
+        name: yup.string().required(
+          formatMessage({
+            defaultMessage: 'Name must not be null',
+            description: 'Name required constraint',
+          })
+        ),
+        age: yup.number().min(
+          18,
+          formatMessage(
+            {
+              defaultMessage: 'You must be {age} years old or more',
+              description: 'Min age constraint message',
+            },
+            { age: 18 }
+          )
+        ),
+      }),
+    [formatMessage]
+  );
+
+  // ... rest of form implementation
 };
 ```
 
-## Components
+## Validation Approaches
 
-### FormFieldSelect
+There are two ways to validate form fields in `@ttoss/forms`: schema-based validation using Yup schemas with `yupResolver`, 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
 
-#### FormFieldSelect support for Default Value
+**When to use `rules`:**
 
-`FormFieldSelect` has support for default values, by assigning the first option defined or the value passed to it in the parameter `defaultValue`.
+- Simple, field-specific validations
+- Dynamic validation based on component state
+- Quick prototyping
+- Single-field conditional logic
+
+### 1. Schema-based Validation (Recommended)
+
+Use Yup schemas with `yupResolver` for complex validation logic:
 
 ```tsx
-const RADIO_OPTIONS = [
-  { value: 'Ferrari', label: 'Ferrari' },
-  { value: 'Mercedes', label: 'Mercedes' },
-  { value: 'BMW', label: 'BMW' },
+const schema = yup.object({
+  email: yup.string().email().required(),
+  age: yup.number().min(18).max(100).required(),
+});
+
+const formMethods = useForm({
+  resolver: yupResolver(schema),
+});
+```
+
+**Advantages:**
+
+- Centralized validation logic
+- Type-safe with TypeScript
+- Reusable schemas
+- Complex validation patterns
+- Schema composition
+
+### 2. Field-level Validation
+
+Use the `rules` prop on individual form fields for simpler validations:
+
+```tsx
+<FormFieldInput
+  name="username"
+  label="Username"
+  rules={{
+    required: 'Username is required',
+    minLength: {
+      value: 3,
+      message: 'Username must be at least 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';
+    },
+  }}
+/>
+```
+
+**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
+
+## Form Field Components
+
+All form field components share common props:
+
+- `name` (required): Field name in the form
+- `label`: Field label text
+- `disabled`: Disables the field
+- `defaultValue`: Initial field value
+- `tooltip`: Label tooltip configuration
+- `inputTooltip`: Input field tooltip configuration
+- `warning`: Warning message displayed below the field
+- `sx`: Theme-UI styling object
+
+### 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' },
 ];
 
-// RenderForm gonna use "Ferrari" as defaultValue
-const RenderForm = () => {
-  const formMethods = useForm();
+<FormFieldRadio name="choice" label="Choose one" options={options} />;
+```
 
-  return (
-    <Form {...formMethods} onSubmit={onSubmit}>
-      <FormFieldSelect name="car" label="Cars" options={RADIO_OPTIONS} />
-      <Button type="submit">Submit</Button>
-    </Form>
-  );
-};
+### FormFieldRadioCard
 
-// RenderForm gonna use "Mercedes" as defaultValue
-const RenderForm = () => {
-  const formMethods = useForm();
+Radio buttons styled as cards.
 
-  return (
-    <Form {...formMethods} onSubmit={onSubmit}>
-      <FormFieldSelect
-        name="car"
-        label="Cars"
-        options={RADIO_OPTIONS}
-        defaultValue="Mercedes"
-      />
-      <Button type="submit">Submit</Button>
-    </Form>
-  );
-};
+```tsx
+<FormFieldRadioCard name="plan" label="Select Plan" options={options} />
 ```
 
-When a placeholder is set, if in the options don't have an empty value, automatically an empty value gonna be injected.
+### FormFieldRadioCardIcony
+
+Radio cards with icon support.
 
 ```tsx
-const RenderForm = () => {
-  const formMethods = useForm();
+const options = [
+  { value: 'card', label: 'Credit Card', icon: 'credit-card' },
+  { value: 'bank', label: 'Bank Transfer', icon: 'bank' },
+];
 
-  // automatically injects an empty value on the "RADIO_OPTIONS"
-  return (
-    <Form {...formMethods} onSubmit={onSubmit}>
-      <FormFieldSelect
-        name="car"
-        label="Cars"
-        options={RADIO_OPTIONS}
-        placeholder="Select a car"
-      />
-      <Button type="submit">Submit</Button>
-    </Form>
-  );
-};
+<FormFieldRadioCardIcony
+  name="payment"
+  label="Payment Method"
+  options={options}
+/>;
 ```
 
-**Note that a placeholder cannot be set when an defaultValue is set and vice-versa**
+### FormFieldSelect
+
+Dropdown select field.
 
 ```tsx
-// type error!!
-return (
-  <Form {...formMethods} onSubmit={onSubmit}>
-    <FormFieldSelect
-      name="car"
-      label="Cars"
-      options={RADIO_OPTIONS}
-      placeholder="Select a car"
-      defaultValue="Ferrari"
-    />
-    <Button type="submit">Submit</Button>
-  </Form>
-);
+const options = [
+  { value: 'ferrari', label: 'Ferrari' },
+  { value: 'mercedes', label: 'Mercedes' },
+  { value: 'bmw', label: 'BMW' },
+];
+
+<FormFieldSelect name="car" label="Choose a car" options={options} />;
 ```
 
-When your Select options depends on fetched values, the manual defaultValue setting is required.
+#### FormFieldSelect Default Values
+
+`FormFieldSelect` defaults to the first option or a specified `defaultValue`:
 
 ```tsx
-const RenderForm = () => {
-  const formMethods = useForm();
-  const { resetField } = formMethods;
-  const [formOptions, setFormOptions] = useState<
-    {
-      value: string;
-      label: string;
-    }[]
-  >([]);
+// Defaults to "Ferrari"
+<FormFieldSelect name="car" label="Cars" options={options} />
+
+// Defaults to "Mercedes"
+<FormFieldSelect
+  name="car"
+  label="Cars"
+  options={options}
+  defaultValue="Mercedes"
+/>
+```
 
-  useEffect(() => {
-    // some fetch operation here
+When using a `placeholder`, an empty option is automatically added if not present:
 
-    setFormOptions(RADIO_OPTIONS);
+```tsx
+<FormFieldSelect
+  name="car"
+  label="Cars"
+  options={options}
+  placeholder="Select a car"
+/>
+```
 
-    // fetch are side effects, so, if the options depends on fetch and have a default value, the field should be reseted in the effect
-    resetField('car', { defaultValue: 'Ferrari' });
-  }, []);
+**Note:** `placeholder` and `defaultValue` cannot be used together.
 
-  return (
-    <Form {...formMethods} onSubmit={onSubmit}>
-      <FormFieldSelect name="car" label="Cars" options={formOptions} />
-      <Button type="submit">Submit</Button>
-    </Form>
-  );
-};
+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' });
+}, []);
 ```
 
-### FormGroup
+### FormFieldNumericFormat
 
-`FormGroup` is a component that groups fields together. It's useful when you need to group fields that are related to each other.
+Numeric input with formatting support (decimals, thousands separators).
 
 ```tsx
-const RenderForm = () => {
-  const formMethods = useForm();
+<FormFieldNumericFormat
+  name="price"
+  label="Price"
+  thousandSeparator=","
+  decimalScale={2}
+/>
+```
 
-  return (
-    <Form {...formMethods} onSubmit={onSubmit}>
-      <FormGroup label="Personal Information" direction="row">
-        <FormField.Input name="firstName" label="First Name" />
-        <FormField.Input name="lastName" label="Last Name" />
-      </FormGroup>
-      <FormGroup label="Address">
-        <FormField.Input name="street" label="Street" />
-        <FormField.Input name="city" label="City" />
-      </FormGroup>
-      <Button type="submit">Submit</Button>
-    </Form>
-  );
-};
+### FormFieldCurrencyInput
+
+Currency input with locale-based formatting.
+
+```tsx
+<FormFieldCurrencyInput
+  name="amount"
+  label="Amount"
+  prefix="$"
+  decimalsLimit={2}
+/>
+```
+
+### FormFieldPatternFormat
+
+Input with custom format patterns.
+
+```tsx
+<FormFieldPatternFormat
+  name="phone"
+  label="Phone"
+  format="+1 (###) ###-####"
+  mask="_"
+/>
 ```
 
-#### Props
+### FormFieldCreditCardNumber
 
-- `title`: The label of the group.
-- `direction`: The direction of the group. It can be `row` or `column`.
-- `name`: The name of the group. It is used to render the group error message.
+Credit card input with automatic formatting.
 
-## @ttoss/forms/multistep-form
+```tsx
+<FormFieldCreditCardNumber name="cardNumber" label="Card Number" />
+```
+
+### Brazil-Specific Fields
 
-The `@ttoss/forms/multistep-form` module from the **@ttoss/forms** library provides an efficient and flexible way to create multistep forms in React. This component is ideal for scenarios where filling out a lengthy form needs to be divided into several smaller steps, improving user experience. With support for integrated validations and style customizations, this tool offers everything you need to implement robust multistep forms in your React applications.
+Import from `@ttoss/forms/brazil`:
+
+```tsx
+import {
+  FormFieldCEP,
+  FormFieldCNPJ,
+  FormFieldPhone,
+} from '@ttoss/forms/brazil';
+```
 
-### How to Use
+#### FormFieldCEP
 
-To use the `MultistepForm`, you first need to define the steps of the form, each with its own fields, validations, and messages. Here's a basic example of assembling a multistep form:
+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 formatting.
+
+```tsx
+<FormFieldPhone name="phone" label="Phone" />
+```
+
+## FormGroup
+
+Groups related fields with optional label and layout direction.
+
+```tsx
+<FormGroup label="Personal Information" direction="row">
+  <FormFieldInput name="firstName" label="First Name" />
+  <FormFieldInput name="lastName" label="Last Name" />
+</FormGroup>
+
+<FormGroup label="Address">
+  <FormFieldInput name="street" label="Street" />
+  <FormFieldInput name="city" label="City" />
+</FormGroup>
+```
+
+**Props:**
+
+- `label`: Group label
+- `direction`: Layout direction (`'row'` | `'column'`)
+- `name`: Group name for error messages
+
+## Multistep Forms
+
+Import from `@ttoss/forms/multistep-form`:
 
 ```tsx
-import * as React from 'react';
-import { FormFieldInput, yup } from '@ttoss/forms';
 import { MultistepForm } from '@ttoss/forms/multistep-form';
+import { FormFieldInput, yup } from '@ttoss/forms';
 
-// Define your steps
 const steps = [
   {
     label: 'Step 1',
@@ -294,83 +495,70 @@ const steps = [
     label: 'Step 2',
     question: 'How old are you?',
     fields: <FormFieldInput type="number" name="age" label="Age" />,
-    defaultValues: {
-      age: 18,
-    },
+    defaultValues: { age: 18 },
     schema: yup.object({
       age: yup
         .number()
-        .min(18, 'Min required age is 18')
+        .min(18, 'Must be at least 18')
         .required('Age is required'),
     }),
   },
-  // Add more steps as needed
 ];
 
-const MyMultistepForm = () => {
+const MyForm = () => {
   return (
     <MultistepForm
-      // ...other props
       steps={steps}
-      // submit the full form on submit
       onSubmit={(data) => console.log(data)}
+      footer="© 2024 Company"
+      header={{
+        variant: 'logo',
+        src: '/logo.png',
+        onClose: () => console.log('closed'),
+      }}
     />
   );
 };
 ```
 
-#### Props
-
-The `MultistepForm` component accepts the following props:
-
-- `steps`: An array of objects representing each step of the form.
-- `onSubmit`: A function that is called when the form is completely filled and submitted.
-- `footer`: An string with the text to show on form's footer.
-- `header`: [Header Props](#header-props)
+### MultistepForm Props
 
-Each step can have the following properties:
+- `steps`: Array of step configurations
+- `onSubmit`: Handler called with complete form data
+- `footer`: Footer text
+- `header`: Header configuration (see below)
 
-- `label`: The label of the step (used for navigation).
-- `question`: The question or instruction presented to the user at this step.
-- `fields`: The form fields for this step.
-- `schema`: A `yup` schema for validating the fields at this step.
-- `defaultValues`: An optional object with default values to this step.
+### Step Configuration
 
-#### Header-Props
+Each step object contains:
 
-- **For Logo Header (`MultistepFormHeaderLogoProps`):**
+- `label`: Step label for navigation
+- `question`: Question or instruction text
+- `fields`: React element(s) containing form fields
+- `schema`: Yup validation schema
+- `defaultValues`: Optional default values for step fields
 
-  - `variant`: Set to `'logo'`.
-  - `src`: The source URL for the logo image.
-  - `onClose`: A function to handle the close button click event.
+### Header Types
 
-- **For Titled Header (`MultistepFormTitledProps`):**
-  - `variant`: Set to `'titled'`.
-  - `title`: The title text.
-  - `leftIcon` and `rightIcon`: Icon types for left and right icons.
-  - `onLeftIconClick` and `onRightIconClick`: Functions to handle clicks on left and right icons.
-
-#### Customizing Headers
-
-1. **Logo Header:**
+**Logo Header:**
 
 ```tsx
-const logoHeaderProps = {
+{
   variant: 'logo',
-  src: 'path-to-your-logo-image',
-  onClose: () => console.log('Close button clicked'),
-};
+  src: '/path/to/logo.png',
+  onClose: () => console.log('Close clicked')
+}
 ```
 
-2. **Titled Header:**
+**Titled Header:**
 
 ```tsx
-const titledHeaderProps = {
+{
   variant: 'titled',
-  title: 'Your Title',
-  leftIcon: 'icon-type',
-  rightIcon: 'icon-type',
-  onLeftIconClick: () => console.log('Left icon clicked'),
-  onRightIconClick: () => console.log('Right icon clicked'),
-};
+  title: 'Form Title',
+  leftIcon: 'arrow-left',
+  rightIcon: 'close',
+  onLeftIconClick: () => console.log('Back'),
+  onRightIconClick: () => console.log('Close')
+}
 ```