@ttoss/forms 0.41.1 → 0.42.0

package/README.md

@@ -619,25 +619,50 @@ Brazilian phone number input with formatting.
 
 ## FormGroup
 
-Groups related fields with optional label and layout direction.
+Groups related fields with an optional title, description, and layout direction.
 
 ```tsx
-<FormGroup label="Personal Information" direction="row">
+<FormGroup title="Personal Information" direction="row">
   <FormFieldInput name="firstName" label="First Name" />
   <FormFieldInput name="lastName" label="Last Name" />
 </FormGroup>
 
-<FormGroup label="Address">
+<FormGroup title="Address" description="Where we'll send your order">
   <FormFieldInput name="street" label="Street" />
   <FormFieldInput name="city" label="City" />
 </FormGroup>
 ```
 
+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:**
 
-- `label`: Group label
-- `direction`: Layout direction (`'row'` | `'column'`)
-- `name`: Group name for error messages
+- `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
 
 ## Multistep Forms
 

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 } from '../FormFieldPatternFormat-kaO0pl1R.js';
+import { a as FormFieldPatternFormatProps, F as FormFieldProps, d as FormFieldPhoneProps$1 } from '../FormFieldPhone-BKeOS0i6.js';
 import { PatternFormatProps, NumberFormatBaseProps } from 'react-number-format';
 import '@ttoss/ui';
 import 'react';
@@ -19,7 +19,18 @@ declare const FormFieldCPF: <TFieldValues extends FieldValues = FieldValues, TNa
 type FormFieldCPFOrCNPJProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = FormFieldProps<TFieldValues, TName> & Omit<NumberFormatBaseProps, 'name' | 'format'>;
 declare const FormFieldCPFOrCNPJ: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ disabled, ...props }: FormFieldCPFOrCNPJProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
 
-type FormFieldPhoneProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = FormFieldProps<TFieldValues, TName> & Omit<PatternFormatProps, 'name' | 'format'>;
-declare const FormFieldPhone: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ disabled, ...props }: FormFieldPhoneProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
+type FormFieldPhoneProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = Omit<FormFieldPhoneProps$1<TFieldValues, TName>, 'countryCode' | 'format'>;
+/**
+ * Brazilian phone number form field.
+ *
+ * Wraps the generic `FormFieldPhone` with the Brazil country code (`+55`)
+ * and the appropriate local number format pre-configured.
+ *
+ * @example
+ * ```tsx
+ * <FormFieldPhone name="phone" label="Phone" />
+ * ```
+ */
+declare const FormFieldPhone: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ placeholder, countryCodeOptions, ...props }: FormFieldPhoneProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
 
 export { FormFieldCEP, FormFieldCNPJ, FormFieldCPF, FormFieldCPFOrCNPJ, FormFieldPhone, isCnpjValid, isCpfValid };

package/dist/FormFieldPhone-BKeOS0i6.d.ts

@@ -0,0 +1,217 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { TooltipProps, SxProp, InputProps } from '@ttoss/ui';
+import { FieldValues, FieldPath, RegisterOptions, FieldPathValue, UseControllerReturn } from 'react-hook-form';
+import { PatternFormatProps } from 'react-number-format';
+import * as React from 'react';
+
+type AuxiliaryCheckboxRules<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = Omit<RegisterOptions<TFieldValues, TName>, 'valueAsNumber' | 'valueAsDate' | 'setValueAs' | 'disabled'>;
+/**
+ * Props for the AuxiliaryCheckbox component.
+ */
+type AuxiliaryCheckboxProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = {
+    /**
+     * The label to display next to the checkbox.
+     */
+    label: React.ReactNode;
+    /**
+     * The name of the checkbox field in the form.
+     */
+    name: TName;
+    /**
+     * The default value of the checkbox.
+     * @default false
+     */
+    defaultValue?: boolean;
+    /**
+     * Validation rules for the checkbox field.
+     */
+    rules?: AuxiliaryCheckboxRules<TFieldValues, TName>;
+    /**
+     * Whether the checkbox is disabled.
+     */
+    disabled?: boolean;
+};
+
+type Rules<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = Omit<RegisterOptions<TFieldValues, TName>, 'valueAsNumber' | 'valueAsDate' | 'setValueAs' | 'disabled'>;
+type FormFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = {
+    label?: React.ReactNode;
+    id?: string;
+    name: TName;
+    defaultValue?: FieldPathValue<TFieldValues, TName>;
+    disabled?: boolean;
+    labelTooltip?: TooltipProps;
+    warning?: string | React.ReactNode;
+    rules?: Rules<TFieldValues, TName>;
+    /**
+     * Optional auxiliary checkbox to render between the field and error message.
+     * Useful for input confirmation or conditional display of other fields.
+     */
+    auxiliaryCheckbox?: AuxiliaryCheckboxProps<TFieldValues, FieldPath<TFieldValues>>;
+} & SxProp;
+type FormFieldCompleteProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = {
+    render: (props: UseControllerReturn<TFieldValues, TName>) => React.ReactElement;
+} & FormFieldProps<TFieldValues, TName>;
+declare const FormField: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ label, id: idProp, name, defaultValue, disabled: propsDisabled, labelTooltip, sx, css, render, warning, rules, auxiliaryCheckbox, }: FormFieldCompleteProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
+
+type FormFieldPatternFormatProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = FormFieldProps<TFieldValues, TName> & Omit<PatternFormatProps, 'name'> & Pick<InputProps, 'leadingIcon' | 'trailingIcon'>;
+declare const FormFieldPatternFormat: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ disabled, ...props }: FormFieldPatternFormatProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
+
+/**
+ * A curated list of the most common country calling codes paired with their
+ * typical local phone number format patterns (using `#` as digit placeholders).
+ *
+ * Import this constant and pass it to the `countryCodeOptions` prop of
+ * `FormFieldPhone` to give users a ready-made country-code picker that also
+ * automatically updates the number format when they switch countries.
+ *
+ * @example
+ * ```tsx
+ * import { FormFieldPhone } from '@ttoss/forms';
+ *
+ * // COMMON_PHONE_COUNTRY_CODES is the default — no need to pass it explicitly.
+ * // Index 0 is the "Manual" entry; index 1 is US (+1).
+ * const [countryCode, setCountryCode] = React.useState(
+ *   COMMON_PHONE_COUNTRY_CODES[1].value // '+1'
+ * );
+ *
+ * <FormFieldPhone
+ *   name="phone"
+ *   label="Phone"
+ *   countryCode={countryCode}
+ *   onCountryCodeChange={setCountryCode}
+ * />
+ * ```
+ */
+type CountryCodeOption = {
+    /** Label displayed in the dropdown (e.g. 'US +1'). */
+    label: string;
+    /** The calling-code value (e.g. '+1'). */
+    value: string;
+    /**
+     * Optional phone number format for the local part specific to this country
+     * (e.g. '(###) ###-####'). When the user selects this option the format
+     * is used automatically, overriding the `format` prop of `FormFieldPhone`.
+     */
+    format?: string | ((value: string) => string);
+};
+/**
+ * Sentinel value used as `countryCode` to indicate that the user wants to
+ * type the entire phone number manually (no pattern mask is applied).
+ * A `+` prefix is displayed before the input.
+ */
+declare const MANUAL_PHONE_COUNTRY_CODE = "manual";
+/**
+ * Common country calling codes sorted by numeric dial-code order.
+ * The "Manual" option is listed first, allowing users to type the full
+ * international number freely without any mask.
+ */
+declare const COMMON_PHONE_COUNTRY_CODES: CountryCodeOption[];
+
+type FormFieldPhoneProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = FormFieldProps<TFieldValues, TName> & Omit<PatternFormatProps, 'name' | 'format'> & {
+    /**
+     * The country calling code to display as a literal prefix in the input.
+     * For example, '+55' for Brazil or '+1' for the United States.
+     * Defaults to the first entry in `countryCodeOptions` when not provided.
+     */
+    countryCode?: string;
+    /**
+     * The pattern format for the local part of the phone number.
+     * Accepts either a static string (e.g., '(##) #####-####') or a function
+     * that receives the current raw value and returns the format string,
+     * which is useful for dynamic formats (e.g., different lengths).
+     *
+     * When the selected entry in countryCodeOptions includes its own
+     * format, that value takes precedence over this prop.
+     *
+     * Defaults to '(###) ###-####' when neither this prop nor the selected
+     * country option supplies a format.
+     *
+     * Ignored when `countryCode` is `MANUAL_PHONE_COUNTRY_CODE`.
+     */
+    format?: string | ((value: string) => string);
+    /**
+     * List of country calling code options to display in the dropdown.
+     * Defaults to `COMMON_PHONE_COUNTRY_CODES` (15 common countries + Manual).
+     * Pass an empty array to hide the dropdown and show a plain phone input.
+     */
+    countryCodeOptions?: CountryCodeOption[];
+    /**
+     * Called with the newly selected country code value when the user changes
+     * the country code via the dropdown. Only relevant when
+     * countryCodeOptions is non-empty.
+     */
+    onCountryCodeChange?: (countryCode: string) => void;
+};
+/**
+ * Generic phone number form field that supports an optional country code prefix.
+ *
+ * By default, a country-code dropdown is rendered using `COMMON_PHONE_COUNTRY_CODES`
+ * (15 common countries + a Manual entry; Manual is the first entry at index 0).
+ * Pass `countryCodeOptions={[]}` to disable the dropdown and show a plain phone input.
+ *
+ * The format prop defines the pattern for the local phone number (using #
+ * as digit placeholders). When a countryCode is provided it is prepended to
+ * the format and rendered as a read-only literal inside the input.
+ *
+ * When the user selects the "Manual" option (`MANUAL_PHONE_COUNTRY_CODE`),
+ * the pattern mask is disabled and a plain text input is shown so the user
+ * can type the full international number freely.
+ *
+ * When a country code is provided, the stored value is the country code
+ * concatenated directly with the raw local digits (e.g., `"+15555555555"`
+ * for country code `"+1"` and local digits `"5555555555"`). When no country
+ * code is set, only the raw local digits are stored.
+ *
+ * Changing the country code via the dropdown automatically resets the phone
+ * number field to an empty string, so a new number can be entered in the
+ * correct format for the selected country.
+ *
+ * @example
+ * ```tsx
+ * // Default: dropdown with COMMON_PHONE_COUNTRY_CODES, US (+1) pre-selected
+ * <FormFieldPhone name="phone" label="Phone" countryCode="+1" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled country code — submitted value includes the prefix
+ * // e.g. { phone: '+15555555555' }
+ * const [countryCode, setCountryCode] = React.useState('+1');
+ * <FormFieldPhone
+ *   name="phone"
+ *   label="Phone"
+ *   countryCode={countryCode}
+ *   onCountryCodeChange={setCountryCode}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // No dropdown — plain phone input; value includes the prefix
+ * // e.g. { phone: '+15555555555' }
+ * <FormFieldPhone
+ *   name="phone"
+ *   label="Phone"
+ *   countryCode="+1"
+ *   format="(###) ###-####"
+ *   countryCodeOptions={[]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Dynamic format (e.g. Brazilian numbers with 8 or 9 local digits)
+ * <FormFieldPhone
+ *   name="phone"
+ *   label="Phone"
+ *   countryCode="+55"
+ *   format={(value) =>
+ *     value.length > 10 ? '(##) #####-####' : '(##) ####-#####'
+ *   }
+ *   countryCodeOptions={[]}
+ * />
+ * ```
+ */
+declare const FormFieldPhone: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ disabled, countryCode: countryCodeProp, format, countryCodeOptions, onCountryCodeChange, ...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, __name, isCnpjValid, isCpfValid } from "../chunk-BL55OAIO.js";
+import { FormField, FormFieldCNPJ, FormFieldCPF, FormFieldPatternFormat, FormFieldPhone, __name, isCnpjValid, isCpfValid } from "../chunk-ZORKZWD7.js";
 
 // src/Brazil/FormFieldCEP.tsx
 var FormFieldCEP = /* @__PURE__ */__name(({
@@ -73,56 +73,21 @@ var FormFieldCPFOrCNPJ = /* @__PURE__ */__name(({
 }, "FormFieldCPFOrCNPJ");
 
 // src/Brazil/FormFieldPhone.tsx
-import { Input as Input2 } from "@ttoss/ui";
-import { PatternFormat } from "react-number-format";
-var FormFieldPhone = /* @__PURE__ */__name(({
-  disabled,
+var BRAZIL_COUNTRY_CODE = "+55";
+var getBrazilPhoneFormat = /* @__PURE__ */__name(value => {
+  return value.length > 10 ? "(##) #####-####" : "(##) ####-#####";
+}, "getBrazilPhoneFormat");
+var FormFieldPhone2 = /* @__PURE__ */__name(({
+  placeholder = "(11) 91234-1234",
+  countryCodeOptions = [],
   ...props
 }) => {
-  const {
-    label,
-    name,
-    labelTooltip,
-    warning,
-    sx,
-    css,
-    rules,
-    id,
-    defaultValue,
-    placeholder = "(11) 91234-1234",
-    auxiliaryCheckbox,
-    ...patternFormatProps
-  } = props;
-  return /* @__PURE__ */React.createElement(FormField, {
-    id,
-    label,
-    name,
-    labelTooltip,
-    warning,
-    sx,
-    css,
-    defaultValue,
-    rules,
-    disabled,
-    auxiliaryCheckbox,
-    render: /* @__PURE__ */__name(({
-      field
-    }) => {
-      const format = field.value?.length > 10 ? "(##) #####-####" : "(##) ####-#####";
-      return /* @__PURE__ */React.createElement(PatternFormat, {
-        ...patternFormatProps,
-        name: field.name,
-        value: field.value,
-        onBlur: field.onBlur,
-        onValueChange: /* @__PURE__ */__name(values => {
-          field.onChange(values.value);
-        }, "onValueChange"),
-        format,
-        customInput: Input2,
-        placeholder,
-        disabled: disabled ?? field.disabled
-      });
-    }, "render")
+  return /* @__PURE__ */React.createElement(FormFieldPhone, {
+    ...props,
+    countryCode: BRAZIL_COUNTRY_CODE,
+    format: getBrazilPhoneFormat,
+    placeholder,
+    countryCodeOptions
   });
 }, "FormFieldPhone");
-export { FormFieldCEP, FormFieldCNPJ, FormFieldCPF, FormFieldCPFOrCNPJ, FormFieldPhone, isCnpjValid, isCpfValid };
+export { FormFieldCEP, FormFieldCNPJ, FormFieldCPF, FormFieldCPFOrCNPJ, FormFieldPhone2 as FormFieldPhone, isCnpjValid, isCpfValid };

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-6UQV3E5X.js";
-import { __name } from "../chunk-BL55OAIO.js";
+import { Form, useForm, yupResolver } from "../chunk-YCW3GPTZ.js";
+import { __name } from "../chunk-ZORKZWD7.js";
 
 // src/MultistepForm/MultistepForm.tsx
 import { Flex as Flex6 } from "@ttoss/ui";

package/dist/esm/{chunk-6UQV3E5X.js → chunk-YCW3GPTZ.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-BL55OAIO.js";
+import { FormErrorMessage, FormField, FormFieldPatternFormat, __name, isCnpjValid, isCpfValid } from "./chunk-ZORKZWD7.js";
 
 // src/Form.tsx
 import { Box } from "@ttoss/ui";
@@ -848,43 +848,23 @@ var FormFieldTextarea = /* @__PURE__ */__name(({
 // src/FormGroup.tsx
 import { Box as Box4, Flex as Flex4, Text as Text3 } from "@ttoss/ui";
 import * as React4 from "react";
-var FormGroupLevelsManagerContext = /* @__PURE__ */React4.createContext({
-  levelsLength: 1,
-  registerChild: /* @__PURE__ */__name(() => {
-    return null;
-  }, "registerChild")
-});
-var FormGroupLevelsManager = /* @__PURE__ */__name(({
-  children
-}) => {
-  const [levelsLength, setLevelsLength] = React4.useState(0);
-  const registerChild = React4.useCallback(level => {
-    if (level + 1 > levelsLength) {
-      setLevelsLength(level + 1);
-    }
-  }, [levelsLength]);
-  return /* @__PURE__ */React4.createElement(FormGroupLevelsManagerContext.Provider, {
-    value: {
-      levelsLength,
-      registerChild
-    }
-  }, children);
-}, "FormGroupLevelsManager");
 var FormGroupContext = /* @__PURE__ */React4.createContext({});
 var useFormGroup = /* @__PURE__ */__name(() => {
   const {
     parentLevel
   } = React4.useContext(FormGroupContext);
-  const {
-    levelsLength
-  } = React4.useContext(FormGroupLevelsManagerContext);
   return {
     level: parentLevel,
-    levelsLength
+    /**
+    * @deprecated `levelsLength` has been removed from `FormGroup` internals.
+    * This field always returns `undefined`. Use `level` to determine nesting depth.
+    */
+    levelsLength: void 0
   };
 }, "useFormGroup");
 var FormGroupWrapper = /* @__PURE__ */__name(({
   title,
+  description,
   direction,
   children,
   name,
@@ -893,37 +873,33 @@ var FormGroupWrapper = /* @__PURE__ */__name(({
   const {
     level
   } = useFormGroup();
-  const {
-    registerChild
-  } = React4.useContext(FormGroupLevelsManagerContext);
-  React4.useEffect(() => {
-    if (typeof level === "number") {
-      registerChild(level);
-    }
-  }, [level, registerChild]);
   const childrenContainerSx = {
     flexDirection: direction || "column",
     gap: "1",
     width: "100%"
   };
   return /* @__PURE__ */React4.createElement(Box4, {
-    "aria-level": level,
+    "data-level": level,
     ...boxProps,
     sx: {
       marginTop: level === 0 ? "none" : "4",
       marginBottom: "4",
       ...boxProps.sx
     }
-  }, title && /* @__PURE__ */React4.createElement(Box4, {
+  }, (title || description) && /* @__PURE__ */React4.createElement(Box4, {
     sx: {
       marginBottom: "2"
     }
-  }, /* @__PURE__ */React4.createElement(Text3, {
+  }, title && /* @__PURE__ */React4.createElement(Text3, {
     sx: {
       fontSize: "2xl",
       fontWeight: "bold"
     }
-  }, title)), /* @__PURE__ */React4.createElement(Flex4, {
+  }, title), description && /* @__PURE__ */React4.createElement(Text3, {
+    sx: {
+      color: "text.secondary"
+    }
+  }, description)), /* @__PURE__ */React4.createElement(Flex4, {
     sx: childrenContainerSx
   }, children), name && /* @__PURE__ */React4.createElement(FormErrorMessage, {
     name
@@ -938,7 +914,7 @@ var FormGroup = /* @__PURE__ */__name(props => {
     value: {
       parentLevel: currentLevel
     }
-  }, currentLevel === 0 ? /* @__PURE__ */React4.createElement(FormGroupLevelsManager, null, /* @__PURE__ */React4.createElement(FormGroupWrapper, props)) : /* @__PURE__ */React4.createElement(FormGroupWrapper, props));
+  }, /* @__PURE__ */React4.createElement(FormGroupWrapper, props));
 }, "FormGroup");
 
 // src/yup/i18n.ts

package/dist/esm/{chunk-BL55OAIO.js → chunk-ZORKZWD7.js}

@@ -268,9 +268,223 @@ var FormFieldPatternFormat = /* @__PURE__ */__name(({
   });
 }, "FormFieldPatternFormat");
 
+// src/phoneCountryCodes.ts
+var MANUAL_PHONE_COUNTRY_CODE = "manual";
+var COMMON_PHONE_COUNTRY_CODES = [{
+  label: "Manual",
+  value: MANUAL_PHONE_COUNTRY_CODE
+}, {
+  label: "\u{1F1FA}\u{1F1F8} +1 (US/Canada)",
+  value: "+1",
+  format: "(###) ###-####"
+}, {
+  label: "\u{1F1FF}\u{1F1E6} +27 (South Africa)",
+  value: "+27",
+  format: "## ### ####"
+}, {
+  label: "\u{1F1EB}\u{1F1F7} +33 (France)",
+  value: "+33",
+  format: "# ## ## ## ##"
+}, {
+  label: "\u{1F1EA}\u{1F1F8} +34 (Spain)",
+  value: "+34",
+  format: "### ### ###"
+}, {
+  label: "\u{1F1EE}\u{1F1F9} +39 (Italy)",
+  value: "+39",
+  format: "### ### ####"
+}, {
+  label: "\u{1F1EC}\u{1F1E7} +44 (UK)",
+  value: "+44",
+  format: "#### ### ####"
+}, {
+  label: "\u{1F1E9}\u{1F1EA} +49 (Germany)",
+  value: "+49",
+  format: "### ########"
+}, {
+  label: "\u{1F1F2}\u{1F1FD} +52 (Mexico)",
+  value: "+52",
+  format: "## ########"
+}, {
+  label: "\u{1F1E6}\u{1F1F7} +54 (Argentina)",
+  value: "+54",
+  format: "## ########"
+}, {
+  label: "\u{1F1E7}\u{1F1F7} +55 (Brazil)",
+  value: "+55",
+  format: "(##) #####-####"
+}, {
+  label: "\u{1F1E6}\u{1F1FA} +61 (Australia)",
+  value: "+61",
+  format: "#### ### ###"
+}, {
+  label: "\u{1F1EF}\u{1F1F5} +81 (Japan)",
+  value: "+81",
+  format: "##-####-####"
+}, {
+  label: "\u{1F1E8}\u{1F1F3} +86 (China)",
+  value: "+86",
+  format: "###-####-####"
+}, {
+  label: "\u{1F1EE}\u{1F1F3} +91 (India)",
+  value: "+91",
+  format: "#####-#####"
+}, {
+  label: "\u{1F1F5}\u{1F1F9} +351 (Portugal)",
+  value: "+351",
+  format: "### ### ###"
+}];
+
+// src/FormFieldPhone.tsx
+import { Box, Flex as Flex3, Input as Input2, Select } from "@ttoss/ui";
+import * as React4 from "react";
+import { NumericFormat, PatternFormat as PatternFormat2 } from "react-number-format";
+var PhoneDropdownWrapper = /* @__PURE__ */__name(({
+  id,
+  countryCode,
+  countryCodeOptions,
+  disabled,
+  onCountryCodeChange,
+  onPhoneReset,
+  inputNode
+}) => {
+  return /* @__PURE__ */React4.createElement(Flex3, {
+    sx: {
+      gap: "2",
+      alignItems: "stretch"
+    }
+  }, /* @__PURE__ */React4.createElement(Box, {
+    sx: {
+      minWidth: "180px"
+    }
+  }, /* @__PURE__ */React4.createElement(Select, {
+    options: countryCodeOptions,
+    value: countryCode,
+    disabled,
+    onChange: /* @__PURE__ */__name(value => {
+      if (value !== void 0) {
+        onPhoneReset?.();
+        onCountryCodeChange?.(String(value));
+      }
+    }, "onChange")
+  })), /* @__PURE__ */React4.createElement(Box, {
+    sx: {
+      flex: 1
+    }
+  }, /* @__PURE__ */React4.cloneElement(inputNode, {
+    id
+  })));
+}, "PhoneDropdownWrapper");
+var FormFieldPhone = /* @__PURE__ */__name(({
+  disabled,
+  countryCode: countryCodeProp,
+  format,
+  countryCodeOptions = COMMON_PHONE_COUNTRY_CODES,
+  onCountryCodeChange,
+  ...props
+}) => {
+  const {
+    label,
+    name,
+    labelTooltip,
+    warning,
+    sx,
+    css,
+    rules,
+    id,
+    defaultValue,
+    auxiliaryCheckbox,
+    onBlur,
+    onValueChange,
+    placeholder,
+    ...patternFormatProps
+  } = props;
+  const countryCode = countryCodeProp ?? countryCodeOptions[0]?.value ?? void 0;
+  const isManual = countryCode === MANUAL_PHONE_COUNTRY_CODE;
+  const getFormat = /* @__PURE__ */__name(value => {
+    const selectedOption = countryCodeOptions.find(opt => {
+      return opt.value === countryCode;
+    });
+    const resolvedFormat = selectedOption?.format ?? format ?? "(###) ###-####";
+    const baseFormat = typeof resolvedFormat === "function" ? resolvedFormat(value) : resolvedFormat;
+    return countryCode && !isManual ? `${countryCode} ${baseFormat}` : baseFormat;
+  }, "getFormat");
+  const showDropdown = countryCodeOptions.length > 0;
+  return /* @__PURE__ */React4.createElement(FormField, {
+    id,
+    label,
+    name,
+    labelTooltip,
+    warning,
+    sx,
+    css,
+    defaultValue,
+    rules,
+    disabled,
+    auxiliaryCheckbox,
+    render: /* @__PURE__ */__name(({
+      field,
+      fieldState
+    }) => {
+      const localPhoneValue = !isManual && countryCode && field.value?.startsWith(countryCode) ? field.value.slice(countryCode.length) : field.value;
+      const inputNode = isManual ? /* @__PURE__ */React4.createElement(NumericFormat, {
+        name: field.name,
+        value: field.value ?? "",
+        placeholder,
+        prefix: "+",
+        allowLeadingZeros: true,
+        decimalScale: 0,
+        thousandSeparator: false,
+        onBlur: /* @__PURE__ */__name(e => {
+          field.onBlur();
+          onBlur?.(e);
+        }, "onBlur"),
+        onValueChange: /* @__PURE__ */__name((values, sourceInfo) => {
+          field.onChange(values.formattedValue);
+          onValueChange?.(values, sourceInfo);
+        }, "onValueChange"),
+        customInput: Input2,
+        disabled: disabled ?? field.disabled,
+        "aria-invalid": fieldState.error ? "true" : void 0
+      }) : /* @__PURE__ */React4.createElement(PatternFormat2, {
+        ...patternFormatProps,
+        name: field.name,
+        value: localPhoneValue,
+        placeholder,
+        onBlur: /* @__PURE__ */__name(e => {
+          field.onBlur();
+          onBlur?.(e);
+        }, "onBlur"),
+        onValueChange: /* @__PURE__ */__name((values, sourceInfo) => {
+          const fullValue = countryCode && values.value ? countryCode + values.value : values.value;
+          field.onChange(fullValue);
+          onValueChange?.(values, sourceInfo);
+        }, "onValueChange"),
+        format: getFormat(localPhoneValue ?? ""),
+        customInput: Input2,
+        disabled: disabled ?? field.disabled,
+        "aria-invalid": fieldState.error ? "true" : void 0
+      });
+      if (!showDropdown) {
+        return inputNode;
+      }
+      return /* @__PURE__ */React4.createElement(PhoneDropdownWrapper, {
+        countryCode,
+        countryCodeOptions,
+        disabled: disabled ?? field.disabled,
+        onCountryCodeChange,
+        onPhoneReset: /* @__PURE__ */__name(() => {
+          return field.onChange("");
+        }, "onPhoneReset"),
+        inputNode
+      });
+    }, "render")
+  });
+}, "FormFieldPhone");
+
 // src/Brazil/FormFieldCNPJ.tsx
-import { Input as Input2 } from "@ttoss/ui";
-import { PatternFormat as PatternFormat2 } from "react-number-format";
+import { Input as Input3 } from "@ttoss/ui";
+import { PatternFormat as PatternFormat3 } from "react-number-format";
 var isCnpjValid = /* @__PURE__ */__name(cnpj => {
   if (cnpj?.length != 14) {
     return false;
@@ -342,7 +556,7 @@ var FormFieldCNPJ = /* @__PURE__ */__name(({
     render: /* @__PURE__ */__name(({
       field
     }) => {
-      return /* @__PURE__ */React.createElement(PatternFormat2, {
+      return /* @__PURE__ */React.createElement(PatternFormat3, {
         ...patternFormatProps,
         name: field.name,
         value: field.value,
@@ -351,7 +565,7 @@ var FormFieldCNPJ = /* @__PURE__ */__name(({
           field.onChange(values.value);
         }, "onValueChange"),
         format: "##.###.###/####-##",
-        customInput: Input2,
+        customInput: Input3,
         placeholder,
         disabled: disabled ?? field.disabled
       });
@@ -360,8 +574,8 @@ var FormFieldCNPJ = /* @__PURE__ */__name(({
 }, "FormFieldCNPJ");
 
 // src/Brazil/FormFieldCPF.tsx
-import { Input as Input3 } from "@ttoss/ui";
-import { PatternFormat as PatternFormat3 } from "react-number-format";
+import { Input as Input4 } from "@ttoss/ui";
+import { PatternFormat as PatternFormat4 } from "react-number-format";
 var isCpfValid = /* @__PURE__ */__name(cpf => {
   if (cpf?.length != 11) {
     return false;
@@ -424,7 +638,7 @@ var FormFieldCPF = /* @__PURE__ */__name(({
     render: /* @__PURE__ */__name(({
       field
     }) => {
-      return /* @__PURE__ */React.createElement(PatternFormat3, {
+      return /* @__PURE__ */React.createElement(PatternFormat4, {
         ...patternFormatProps,
         name: field.name,
         value: field.value,
@@ -433,11 +647,11 @@ var FormFieldCPF = /* @__PURE__ */__name(({
           field.onChange(values.value);
         }, "onValueChange"),
         format: "###.###.###-##",
-        customInput: Input3,
+        customInput: Input4,
         placeholder,
         disabled: disabled ?? field.disabled
       });
     }, "render")
   });
 }, "FormFieldCPF");
-export { __name, FormErrorMessage, FormField, FormFieldPatternFormat, isCnpjValid, FormFieldCNPJ, isCpfValid, FormFieldCPF };
+export { __name, FormErrorMessage, FormField, FormFieldPatternFormat, MANUAL_PHONE_COUNTRY_CODE, COMMON_PHONE_COUNTRY_CODES, FormFieldPhone, isCnpjValid, FormFieldCNPJ, isCpfValid, FormFieldCPF };

package/dist/esm/index.js

@@ -1,4 +1,4 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { Controller, Form, 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-6UQV3E5X.js";
-import { FormErrorMessage, FormField, FormFieldPatternFormat } from "./chunk-BL55OAIO.js";
-export { Controller, Form, FormErrorMessage, FormField, FormFieldCheckbox, FormFieldCreditCardNumber, FormFieldCurrencyInput, FormFieldDatePicker, FormFieldInput, FormFieldNumericFormat, FormFieldPassword, FormFieldPatternFormat, FormFieldRadio, FormFieldRadioCard, FormFieldRadioCardIcony, FormFieldSegmentedControl, FormFieldSelect, FormFieldSwitch, FormFieldTextarea, FormGroup, FormProvider, useController, useFieldArray, useForm, useFormContext, useFormGroup, useFormState, useWatch, yup, yupResolver, z, zodResolver };
+import { Controller, Form, 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-YCW3GPTZ.js";
+import { COMMON_PHONE_COUNTRY_CODES, FormErrorMessage, FormField, FormFieldPatternFormat, FormFieldPhone, MANUAL_PHONE_COUNTRY_CODE } from "./chunk-ZORKZWD7.js";
+export { COMMON_PHONE_COUNTRY_CODES, Controller, Form, 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 './FormFieldPatternFormat-kaO0pl1R.js';
-export { b as FormField, c as FormFieldPatternFormat } from './FormFieldPatternFormat-kaO0pl1R.js';
+import { F as FormFieldProps, a as FormFieldPatternFormatProps } from './FormFieldPhone-BKeOS0i6.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-BKeOS0i6.js';
 import { NumericFormatProps } from 'react-number-format';
 import { DateRange } from '@ttoss/components/DatePicker';
 import './typings.d-BzNUo1mD.js';
@@ -114,13 +114,64 @@ declare const FormFieldTextarea: <TFieldValues extends FieldValues = FieldValues
 
 declare const useFormGroup: () => {
     level: number | undefined;
-    levelsLength: number;
+    /**
+     * @deprecated `levelsLength` has been removed from `FormGroup` internals.
+     * This field always returns `undefined`. Use `level` to determine nesting depth.
+     */
+    levelsLength: number | undefined;
 };
+/**
+ * Props for the FormGroup component.
+ */
 type FormGroupProps = {
+    /**
+     * The field name used to display a validation error message below the group.
+     * Useful when the group maps to an array or object field in the form schema.
+     */
     name?: string;
+    /**
+     * Optional heading displayed above the group's children.
+     */
     title?: string;
+    /**
+     * Optional description displayed below the title.
+     */
+    description?: string;
+    /**
+     * Layout direction for the group's children.
+     * @default 'column'
+     */
     direction?: 'column' | 'row';
 } & BoxProps;
+/**
+ * FormGroup is a layout container that organises form fields into labelled,
+ * optionally nested sections. Each nested `FormGroup` increments an internal
+ * `level` counter exposed via `useFormGroup`, which drives a `data-level`
+ * attribute and top-margin spacing so deeper groups are visually indented.
+ *
+ * @example
+ * ```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>
+ * ```
+ *
+ * @example
+ * // Show a group-level validation error (e.g. for an array field)
+ * ```tsx
+ * <FormGroup name="items" title="Items">
+ *   {fields.map((field, i) => (
+ *     <FormFieldInput key={field.id} name={`items[${i}].value`} label="Value" />
+ *   ))}
+ * </FormGroup>
+ * ```
+ */
 declare const FormGroup: (props: FormGroupProps) => react_jsx_runtime.JSX.Element;
 
 export { type DateRangePreset, Form, FormErrorMessage, FormFieldCheckbox, FormFieldCreditCardNumber, FormFieldCurrencyInput, FormFieldDatePicker, FormFieldInput, FormFieldNumericFormat, FormFieldPassword, FormFieldProps, FormFieldRadio, FormFieldRadioCard, FormFieldRadioCardIcony, FormFieldSegmentedControl, FormFieldSelect, FormFieldSwitch, FormFieldTextarea, FormGroup, type FormRadioOption, useFormGroup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/forms",
-  "version": "0.41.1",
+  "version": "0.42.0",
   "license": "MIT",
   "author": "ttoss",
   "contributors": [
@@ -40,9 +40,9 @@
   },
   "peerDependencies": {
     "react": ">=16.8.0",
-    "@ttoss/components": "^2.13.1",
-    "@ttoss/ui": "^6.7.0",
-    "@ttoss/react-i18n": "^2.1.0"
+    "@ttoss/components": "^2.13.2",
+    "@ttoss/react-i18n": "^2.1.0",
+    "@ttoss/ui": "^6.8.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
@@ -52,13 +52,13 @@
     "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/components": "^2.13.1",
-    "@ttoss/react-icons": "^0.6.0",
     "@ttoss/react-i18n": "^2.1.0",
+    "@ttoss/react-icons": "^0.6.0",
     "@ttoss/test-utils": "^4.1.0",
-    "@ttoss/ui": "^6.7.0"
+    "@ttoss/ui": "^6.8.0",
+    "@ttoss/config": "^1.36.0"
   },
   "publishConfig": {
     "access": "public",

package/dist/FormFieldPatternFormat-kaO0pl1R.d.ts

@@ -1,59 +0,0 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { TooltipProps, SxProp, InputProps } from '@ttoss/ui';
-import { FieldValues, FieldPath, RegisterOptions, FieldPathValue, UseControllerReturn } from 'react-hook-form';
-import { PatternFormatProps } from 'react-number-format';
-import * as React from 'react';
-
-type AuxiliaryCheckboxRules<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = Omit<RegisterOptions<TFieldValues, TName>, 'valueAsNumber' | 'valueAsDate' | 'setValueAs' | 'disabled'>;
-/**
- * Props for the AuxiliaryCheckbox component.
- */
-type AuxiliaryCheckboxProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = {
-    /**
-     * The label to display next to the checkbox.
-     */
-    label: React.ReactNode;
-    /**
-     * The name of the checkbox field in the form.
-     */
-    name: TName;
-    /**
-     * The default value of the checkbox.
-     * @default false
-     */
-    defaultValue?: boolean;
-    /**
-     * Validation rules for the checkbox field.
-     */
-    rules?: AuxiliaryCheckboxRules<TFieldValues, TName>;
-    /**
-     * Whether the checkbox is disabled.
-     */
-    disabled?: boolean;
-};
-
-type Rules<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = Omit<RegisterOptions<TFieldValues, TName>, 'valueAsNumber' | 'valueAsDate' | 'setValueAs' | 'disabled'>;
-type FormFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = {
-    label?: React.ReactNode;
-    id?: string;
-    name: TName;
-    defaultValue?: FieldPathValue<TFieldValues, TName>;
-    disabled?: boolean;
-    labelTooltip?: TooltipProps;
-    warning?: string | React.ReactNode;
-    rules?: Rules<TFieldValues, TName>;
-    /**
-     * Optional auxiliary checkbox to render between the field and error message.
-     * Useful for input confirmation or conditional display of other fields.
-     */
-    auxiliaryCheckbox?: AuxiliaryCheckboxProps<TFieldValues, FieldPath<TFieldValues>>;
-} & SxProp;
-type FormFieldCompleteProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = {
-    render: (props: UseControllerReturn<TFieldValues, TName>) => React.ReactElement;
-} & FormFieldProps<TFieldValues, TName>;
-declare const FormField: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ label, id: idProp, name, defaultValue, disabled: propsDisabled, labelTooltip, sx, css, render, warning, rules, auxiliaryCheckbox, }: FormFieldCompleteProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
-
-type FormFieldPatternFormatProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = FormFieldProps<TFieldValues, TName> & Omit<PatternFormatProps, 'name'> & Pick<InputProps, 'leadingIcon' | 'trailingIcon'>;
-declare const FormFieldPatternFormat: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ disabled, ...props }: FormFieldPatternFormatProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
-
-export { type FormFieldProps as F, type FormFieldPatternFormatProps as a, FormField as b, FormFieldPatternFormat as c };