@ttoss/forms 0.41.2 → 0.43.0

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

package/dist/esm/{chunk-HN7QPZLJ.js → chunk-4YLT3VPV.js}

@@ -1,26 +1,139 @@
 /** 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";
-import * as React2 from "react";
+import { Box as Box2 } from "@ttoss/ui";
 import { FormProvider } from "react-hook-form";
-var Form = /* @__PURE__ */__name(({
+
+// src/FormActions.tsx
+import { Flex } from "@ttoss/ui";
+var alignMap = {
+  left: "flex-start",
+  center: "center",
+  right: "flex-end"
+};
+var FormActions = /* @__PURE__ */__name(({
+  align = "right",
+  children,
+  sticky = false,
+  sx,
+  ...flexProps
+}) => {
+  return /* @__PURE__ */React.createElement(Flex, {
+    ...flexProps,
+    sx: {
+      flexDirection: "row",
+      gap: "2",
+      justifyContent: alignMap[align],
+      ...(sticky && {
+        position: "sticky",
+        bottom: 0,
+        backgroundColor: "background",
+        paddingY: "3",
+        zIndex: "sticky"
+      }),
+      ...sx
+    }
+  }, children);
+}, "FormActions");
+
+// src/FormGroup.tsx
+import { Box, Flex as Flex2, Text } from "@ttoss/ui";
+import * as React2 from "react";
+var FormGroupContext = /* @__PURE__ */React2.createContext({});
+var useFormGroup = /* @__PURE__ */__name(() => {
+  const {
+    parentLevel
+  } = React2.useContext(FormGroupContext);
+  return {
+    level: parentLevel,
+    /**
+    * @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,
+  ...boxProps
+}) => {
+  const {
+    level
+  } = useFormGroup();
+  const childrenContainerSx = {
+    flexDirection: direction || "column",
+    gap: "4",
+    width: "100%"
+  };
+  return /* @__PURE__ */React2.createElement(Box, {
+    "data-level": level,
+    ...boxProps,
+    sx: {
+      marginTop: level === 0 ? "none" : "4",
+      ...boxProps.sx
+    }
+  }, (title || description) && /* @__PURE__ */React2.createElement(Box, {
+    sx: {
+      marginBottom: "2"
+    }
+  }, title && /* @__PURE__ */React2.createElement(Text, {
+    sx: {
+      fontSize: "2xl",
+      fontWeight: "bold"
+    }
+  }, title), description && /* @__PURE__ */React2.createElement(Text, {
+    sx: {
+      color: "text.secondary"
+    }
+  }, description)), /* @__PURE__ */React2.createElement(Flex2, {
+    sx: childrenContainerSx
+  }, children), name && /* @__PURE__ */React2.createElement(FormErrorMessage, {
+    name
+  }));
+}, "FormGroupWrapper");
+var FormGroup = /* @__PURE__ */__name(props => {
+  const {
+    level
+  } = useFormGroup();
+  const currentLevel = level === void 0 ? 0 : level + 1;
+  return /* @__PURE__ */React2.createElement(FormGroupContext.Provider, {
+    value: {
+      parentLevel: currentLevel
+    }
+  }, /* @__PURE__ */React2.createElement(FormGroupWrapper, props));
+}, "FormGroup");
+
+// src/Form.tsx
+var FormBase = /* @__PURE__ */__name(({
   children,
   onSubmit,
   sx,
   ...formMethods
 }) => {
-  return /* @__PURE__ */React2.createElement(FormProvider, formMethods, /* @__PURE__ */React2.createElement(Box, {
+  return /* @__PURE__ */React.createElement(FormProvider, formMethods, /* @__PURE__ */React.createElement(Box2, {
     as: "form",
     variant: "forms.form",
     onSubmit: formMethods.handleSubmit(data => {
       return onSubmit?.(data);
     }),
-    sx
+    sx: {
+      display: "flex",
+      flexDirection: "column",
+      gap: "4",
+      ...sx
+    }
   }, children));
-}, "Form");
+}, "FormBase");
+var Form = Object.assign(FormBase, {
+  Group: FormGroup,
+  Actions: FormActions
+});
 
 // src/FormFieldCheckbox.tsx
 import { Checkbox } from "@ttoss/ui";
@@ -363,7 +476,7 @@ var FormFieldPassword = /* @__PURE__ */__name(({
 }, "FormFieldPassword");
 
 // src/FormFieldRadio.tsx
-import { Flex, Label, Radio } from "@ttoss/ui";
+import { Flex as Flex3, Label, Radio } from "@ttoss/ui";
 var FormFieldRadio = /* @__PURE__ */__name(({
   disabled,
   options,
@@ -397,7 +510,7 @@ var FormFieldRadio = /* @__PURE__ */__name(({
     render: /* @__PURE__ */__name(({
       field
     }) => {
-      return /* @__PURE__ */React.createElement(Flex, {
+      return /* @__PURE__ */React.createElement(Flex3, {
         sx: {
           flexDirection: "column",
           gap: "1"
@@ -431,7 +544,7 @@ var FormFieldRadio = /* @__PURE__ */__name(({
 }, "FormFieldRadio");
 
 // src/FormFieldRadioCard.tsx
-import { Box as Box2, Flex as Flex2, Label as Label2, Radio as Radio2, Text } from "@ttoss/ui";
+import { Box as Box3, Flex as Flex4, Label as Label2, Radio as Radio2, Text as Text2 } from "@ttoss/ui";
 var FormFieldRadioCard = /* @__PURE__ */__name(({
   disabled,
   ...props
@@ -467,7 +580,7 @@ var FormFieldRadioCard = /* @__PURE__ */__name(({
     render: /* @__PURE__ */__name(({
       field
     }) => {
-      return /* @__PURE__ */React.createElement(Flex2, {
+      return /* @__PURE__ */React.createElement(Flex4, {
         sx: {
           flexDirection: direction,
           gap: "4"
@@ -475,7 +588,7 @@ var FormFieldRadioCard = /* @__PURE__ */__name(({
       }, options.map(option => {
         const key = `form-field-radio-${name}-${option.value}`;
         const isSelected = field.value === option.value;
-        return /* @__PURE__ */React.createElement(Box2, {
+        return /* @__PURE__ */React.createElement(Box3, {
           key,
           sx: {
             gap: "2",
@@ -506,12 +619,12 @@ var FormFieldRadioCard = /* @__PURE__ */__name(({
           checked: field.value === option.value,
           name,
           disabled: disabled ?? field.disabled
-        }), /* @__PURE__ */React.createElement(Flex2, {
+        }), /* @__PURE__ */React.createElement(Flex4, {
           sx: {
             flexDirection: "column",
             gap: "1"
           }
-        }, option.label && /* @__PURE__ */React.createElement(Text, null, option.label), option.description && /* @__PURE__ */React.createElement(Text, {
+        }, option.label && /* @__PURE__ */React.createElement(Text2, null, option.label), option.description && /* @__PURE__ */React.createElement(Text2, {
           sx: {
             fontSize: "sm"
           }
@@ -522,7 +635,7 @@ var FormFieldRadioCard = /* @__PURE__ */__name(({
 }, "FormFieldRadioCard");
 
 // src/FormFieldRadioCardIcony.tsx
-import { Box as Box3, Flex as Flex3, Tag, Text as Text2 } from "@ttoss/ui";
+import { Box as Box4, Flex as Flex5, Tag, Text as Text3 } from "@ttoss/ui";
 import * as React3 from "react";
 var FormFieldRadioCardIcony = /* @__PURE__ */__name(({
   disabled,
@@ -563,7 +676,7 @@ var FormFieldRadioCardIcony = /* @__PURE__ */__name(({
           field.onBlur();
         }
       }, "handleOptionClick");
-      return /* @__PURE__ */React3.createElement(Flex3, {
+      return /* @__PURE__ */React3.createElement(Flex5, {
         sx: {
           flexDirection: direction,
           gap: "4"
@@ -573,7 +686,7 @@ var FormFieldRadioCardIcony = /* @__PURE__ */__name(({
         const isSelected = field.value === option.value;
         const IconComponent = option.icon;
         const tag = option.tag;
-        return /* @__PURE__ */React3.createElement(Box3, {
+        return /* @__PURE__ */React3.createElement(Box4, {
           key,
           onClick: /* @__PURE__ */__name(() => {
             return handleOptionClick(option.value);
@@ -594,25 +707,25 @@ var FormFieldRadioCardIcony = /* @__PURE__ */__name(({
             opacity: isDisabled ? 0.5 : 1,
             transition: "all 0.2s ease-in-out"
           }
-        }, IconComponent && /* @__PURE__ */React3.createElement(Box3, {
+        }, IconComponent && /* @__PURE__ */React3.createElement(Box4, {
           sx: {
             marginBottom: "2",
             color: "text.primary"
           }
         }, /* @__PURE__ */React3.createElement(IconComponent, {
           size: 24
-        })), /* @__PURE__ */React3.createElement(Flex3, {
+        })), /* @__PURE__ */React3.createElement(Flex5, {
           sx: {
             flexDirection: "column",
             gap: "1"
           }
-        }, option.label && /* @__PURE__ */React3.createElement(Text2, {
+        }, option.label && /* @__PURE__ */React3.createElement(Text3, {
           sx: {
             fontSize: "lg",
             fontWeight: "semibold",
             color: "text.primary"
           }
-        }, option.label), option.description && /* @__PURE__ */React3.createElement(Text2, {
+        }, option.label), option.description && /* @__PURE__ */React3.createElement(Text3, {
           sx: {
             fontSize: "md",
             color: "text.secondary"
@@ -845,78 +958,6 @@ var FormFieldTextarea = /* @__PURE__ */__name(({
   });
 }, "FormFieldTextarea");
 
-// src/FormGroup.tsx
-import { Box as Box4, Flex as Flex4, Text as Text3 } from "@ttoss/ui";
-import * as React4 from "react";
-var FormGroupContext = /* @__PURE__ */React4.createContext({});
-var useFormGroup = /* @__PURE__ */__name(() => {
-  const {
-    parentLevel
-  } = React4.useContext(FormGroupContext);
-  return {
-    level: parentLevel,
-    /**
-    * @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,
-  ...boxProps
-}) => {
-  const {
-    level
-  } = useFormGroup();
-  const childrenContainerSx = {
-    flexDirection: direction || "column",
-    gap: "1",
-    width: "100%"
-  };
-  return /* @__PURE__ */React4.createElement(Box4, {
-    "data-level": level,
-    ...boxProps,
-    sx: {
-      marginTop: level === 0 ? "none" : "4",
-      marginBottom: "4",
-      ...boxProps.sx
-    }
-  }, (title || description) && /* @__PURE__ */React4.createElement(Box4, {
-    sx: {
-      marginBottom: "2"
-    }
-  }, title && /* @__PURE__ */React4.createElement(Text3, {
-    sx: {
-      fontSize: "2xl",
-      fontWeight: "bold"
-    }
-  }, title), description && /* @__PURE__ */React4.createElement(Text3, {
-    sx: {
-      color: "text.secondary"
-    }
-  }, description)), /* @__PURE__ */React4.createElement(Flex4, {
-    sx: childrenContainerSx
-  }, children), name && /* @__PURE__ */React4.createElement(FormErrorMessage, {
-    name
-  }));
-}, "FormGroupWrapper");
-var FormGroup = /* @__PURE__ */__name(props => {
-  const {
-    level
-  } = useFormGroup();
-  const currentLevel = level === void 0 ? 0 : level + 1;
-  return /* @__PURE__ */React4.createElement(FormGroupContext.Provider, {
-    value: {
-      parentLevel: currentLevel
-    }
-  }, /* @__PURE__ */React4.createElement(FormGroupWrapper, props));
-}, "FormGroup");
-
 // src/yup/i18n.ts
 import { defineMessage } from "@ttoss/react-i18n";
 import { setLocale } from "yup";
@@ -1083,4 +1124,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 { Form, FormFieldCheckbox, FormFieldCreditCardNumber, FormFieldNumericFormat, FormFieldCurrencyInput, FormFieldDatePicker, FormFieldInput, FormFieldPassword, FormFieldRadio, FormFieldRadioCard, FormFieldRadioCardIcony, FormFieldSegmentedControl, FormFieldSelect, FormFieldSwitch, FormFieldTextarea, useFormGroup, FormGroup, 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, FormFieldSelect, FormFieldSwitch, FormFieldTextarea, yup2 as yup, z3 as z, yupResolver, zodResolver, Controller, FormProvider2 as FormProvider, useController, useFieldArray, useForm, useFormContext, useFormState, useWatch };

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-HN7QPZLJ.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, 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-4YLT3VPV.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, 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

@@ -1,11 +1,11 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { BoxProps, CheckboxProps, InputProps, InputPasswordProps, RadioProps, ThemeUIStyleObject, SegmentedControlProps, SelectProps, SwitchProps, TextareaProps } from '@ttoss/ui';
+import { FlexProps, BoxProps, CheckboxProps, InputProps, InputPasswordProps, RadioProps, ThemeUIStyleObject, SegmentedControlProps, SelectProps, SwitchProps, TextareaProps } from '@ttoss/ui';
 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';
@@ -16,11 +16,141 @@ export { z };
 export { yupResolver } from '@hookform/resolvers/yup';
 export { zodResolver } from '@hookform/resolvers/zod';
 
-declare const Form: <TFieldValues extends FieldValues, TContext = any, TTransformedValues = TFieldValues>({ children, onSubmit, sx, ...formMethods }: {
+declare const alignMap: {
+    readonly left: "flex-start";
+    readonly center: "center";
+    readonly right: "flex-end";
+};
+/**
+ * Props for the FormActions component.
+ */
+type FormActionsProps = {
+    /** Action buttons (Submit, Cancel, Reset, etc.). */
+    children: React.ReactNode;
+    /**
+     * Horizontal alignment of the action buttons.
+     * @default 'right'
+     */
+    align?: keyof typeof alignMap;
+    /**
+     * When `true`, the action bar sticks to the bottom of the viewport so it
+     * remains visible while the user scrolls through a long form.
+     * @default false
+     */
+    sticky?: boolean;
+} & Omit<FlexProps, 'children'>;
+/**
+ * FormActions is a layout container for form action buttons such as Submit,
+ * Cancel, and Reset. It renders a flex row with consistent spacing.
+ *
+ * Use `align` to control horizontal button placement (`'left'`, `'center'`,
+ * or `'right'`). Use `sticky` to keep the action bar visible while the user
+ * scrolls through a long form.
+ *
+ * @example
+ * ```tsx
+ * <Form.Actions align="right" sticky>
+ *   <Button variant="secondary" onClick={onCancel}>Cancel</Button>
+ *   <Button type="submit">Save</Button>
+ * </Form.Actions>
+ * ```
+ */
+declare const FormActions: ({ align, children, sticky, sx, ...flexProps }: FormActionsProps) => react_jsx_runtime.JSX.Element;
+
+declare const useFormGroup: () => {
+    level: number | undefined;
+    /**
+     * @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;
+
+/**
+ * Form is the root component for all form compositions. It wraps
+ * `react-hook-form`'s `FormProvider` and an HTML `<form>` element,
+ * forwarding submission handling.
+ *
+ * Use the compound sub-components for structure:
+ * - `Form.Group` – groups related fields with optional title/description
+ * - `Form.Actions` – footer bar for Submit / Cancel / Reset buttons
+ *
+ * @example
+ * ```tsx
+ * const methods = useForm<FormValues>();
+ *
+ * <Form {...methods} onSubmit={handleSubmit}>
+ *   <Form.Group title="Personal details">
+ *     <FormFieldInput name="firstName" label="First name" />
+ *   </Form.Group>
+ *   <Form.Actions>
+ *     <Button variant="secondary" onClick={onCancel}>Cancel</Button>
+ *     <Button type="submit">Save</Button>
+ *   </Form.Actions>
+ * </Form>
+ * ```
+ */
+declare const Form: (<TFieldValues extends FieldValues, TContext = any, TTransformedValues = TFieldValues>({ children, onSubmit, sx, ...formMethods }: {
     children?: React.ReactNode;
     onSubmit?: (data: TTransformedValues) => Promise<void> | void;
     sx?: BoxProps["sx"];
-} & FormProviderProps<TFieldValues, TContext, TTransformedValues>) => react_jsx_runtime.JSX.Element;
+} & FormProviderProps<TFieldValues, TContext, TTransformedValues>) => react_jsx_runtime.JSX.Element) & {
+    Group: (props: FormGroupProps) => react_jsx_runtime.JSX.Element;
+    Actions: ({ align, children, sticky, sx, ...flexProps }: FormActionsProps) => react_jsx_runtime.JSX.Element;
+};
 
 declare const FormErrorMessage: <TFieldValues extends FieldValues = FieldValues>({ name, disabled, }: {
     name: FieldName<TFieldValues>;
@@ -112,66 +242,4 @@ declare const FormFieldSwitch: <TFieldValues extends FieldValues = FieldValues,
 type FormFieldTextareaProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = FormFieldProps<TFieldValues, TName> & Omit<TextareaProps, 'name'>;
 declare const FormFieldTextarea: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ defaultValue, disabled, ...props }: FormFieldTextareaProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
 
-declare const useFormGroup: () => {
-    level: number | undefined;
-    /**
-     * @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 };
+export { type DateRangePreset, Form, FormActions, type FormActionsProps, 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.2",
+  "version": "0.43.0",
   "license": "MIT",
   "author": "ttoss",
   "contributors": [
@@ -40,9 +40,9 @@
   },
   "peerDependencies": {
     "react": ">=16.8.0",
-    "@ttoss/ui": "^6.7.0",
-    "@ttoss/components": "^2.13.1",
-    "@ttoss/react-i18n": "^2.1.0"
+    "@ttoss/react-i18n": "^2.1.0",
+    "@ttoss/ui": "^6.8.0",
+    "@ttoss/components": "^2.13.2"
   },
   "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/components": "^2.13.1",
+    "@ttoss/components": "^2.13.2",
     "@ttoss/i18n-cli": "^0.7.39",
+    "@ttoss/react-i18n": "^2.1.0",
     "@ttoss/react-icons": "^0.6.0",
-    "@ttoss/config": "^1.36.0",
-    "@ttoss/ui": "^6.7.0",
     "@ttoss/test-utils": "^4.1.0",
-    "@ttoss/react-i18n": "^2.1.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 };