@ttoss/forms 0.41.1 → 0.41.2

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/esm/MultistepForm/index.js

@@ -1,6 +1,6 @@
 /** 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 { Form, useForm, yupResolver } from "../chunk-HN7QPZLJ.js";
 import { __name } from "../chunk-BL55OAIO.js";
 
 // src/MultistepForm/MultistepForm.tsx

package/dist/esm/{chunk-6UQV3E5X.js → chunk-HN7QPZLJ.js}

@@ -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/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 { 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 };

package/dist/index.d.ts

@@ -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.41.2",
   "license": "MIT",
   "author": "ttoss",
   "contributors": [
@@ -40,8 +40,8 @@
   },
   "peerDependencies": {
     "react": ">=16.8.0",
-    "@ttoss/components": "^2.13.1",
     "@ttoss/ui": "^6.7.0",
+    "@ttoss/components": "^2.13.1",
     "@ttoss/react-i18n": "^2.1.0"
   },
   "devDependencies": {
@@ -52,13 +52,13 @@
     "react-error-boundary": "^6.1.0",
     "tsup": "^8.5.1",
     "yup": "^1.7.1",
-    "@ttoss/config": "^1.36.0",
-    "@ttoss/i18n-cli": "^0.7.39",
     "@ttoss/components": "^2.13.1",
+    "@ttoss/i18n-cli": "^0.7.39",
     "@ttoss/react-icons": "^0.6.0",
-    "@ttoss/react-i18n": "^2.1.0",
+    "@ttoss/config": "^1.36.0",
+    "@ttoss/ui": "^6.7.0",
     "@ttoss/test-utils": "^4.1.0",
-    "@ttoss/ui": "^6.7.0"
+    "@ttoss/react-i18n": "^2.1.0"
   },
   "publishConfig": {
     "access": "public",