bonsaif-ui 0.1.19 → 0.1.20

package/README.md

@@ -32,12 +32,110 @@ The package includes reusable components migrated from `prime-auth` and new shar
 
 ### Forms
 
-- `InputField`, `TextInput`, `Textarea`: text inputs with Bonsaif styling.
+- `InputField`, `EmailField`, `PhoneField`, `NumberField`, `TextInput`, `Textarea`: inputs with Bonsaif styling and inline validation for email and phone values.
 - `SearchableSelect`, `CompactFilterSelect`, `CompactSearchInput`: select and filter controls.
 - `CalendarPicker`, `DateRangePicker`: single-date and range selection.
 - `Checkbox`, `RadioGroup`, `Toggle`: boolean and option controls.
 - `FormField`: label, helper, error, and required wrapper for custom controls.
 
+#### Form Validation
+
+Use `validateForm` with reusable validators to validate complete forms before saving. Validators run in order and return the first error per field. Add `noValidate` to the form to avoid native browser validation, then pass each error to the field with `errorDisplay="tooltip"` when the message should appear in the compact validation tooltip.
+
+```tsx
+import { useMemo, useState, type FormEvent } from "react";
+import {
+  EmailField,
+  PhoneField,
+  emailFormat,
+  maxValue,
+  minLength,
+  minValue,
+  phoneFormat,
+  required,
+  validateForm,
+  type ValidationSchema,
+} from "bonsaif-ui";
+
+type AccountForm = {
+  contactName: string;
+  contactEmail: string;
+  contactCountryCode: string;
+  contactPhone: string;
+  seats: string;
+  discountCode: string;
+};
+
+const schema = {
+  contactName: [required("Escribe el nombre."), minLength(3)],
+  contactEmail: [required(), emailFormat()],
+  contactCountryCode: [required()],
+  contactPhone: (value, values) =>
+    phoneFormat()(`${values.contactCountryCode} ${value}`),
+  seats: [required(), minValue(1), maxValue(500)],
+  discountCode: (value, values) =>
+    Number(values.seats) > 100 && String(value).trim() === ""
+      ? "Solicita un codigo para cuentas de mas de 100 usuarios."
+      : undefined,
+} satisfies ValidationSchema<AccountForm>;
+
+function AccountFormExample() {
+  const [form, setForm] = useState<AccountForm>({
+    contactName: "",
+    contactEmail: "",
+    contactCountryCode: "+1",
+    contactPhone: "",
+    seats: "",
+    discountCode: "",
+  });
+  const validationResult = useMemo(
+    () => validateForm(form, schema),
+    [form],
+  );
+  const errors = validationResult.errors;
+
+  function submitForm(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (!validationResult.valid) return;
+
+    saveAccount(form);
+  }
+
+  return (
+    <form noValidate onSubmit={submitForm}>
+      <EmailField
+        label="Correo"
+        value={form.contactEmail}
+        error={errors.contactEmail}
+        validate={false}
+        errorDisplay="tooltip"
+      />
+      <PhoneField
+        label="Telefono"
+        countryCode={form.contactCountryCode}
+        onCountryCodeChange={(countryCode) =>
+          setForm((current) => ({ ...current, contactCountryCode: countryCode }))
+        }
+        allowedCountryCodes={["+1", "+34", "+52", "+57", "+58"]}
+        value={form.contactPhone}
+        onChange={(event) =>
+          setForm((current) => ({
+            ...current,
+            contactPhone: event.currentTarget.value,
+          }))
+        }
+        error={errors.contactPhone}
+        validate={false}
+        errorDisplay="tooltip"
+      />
+      <button type="submit" disabled={!validationResult.valid}>
+        Guardar
+      </button>
+    </form>
+  );
+}
+```
+
 ### Actions And Overlays
 
 - `Button`, `BonsaifButton`: action buttons.