luna-components-library 1.1.41 → 1.1.42

package/README.md

@@ -702,7 +702,79 @@ type InputType = 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'sea
 - `md` - Medium padding and text
 - `lg` - Large padding and text
 - `xl` - Extra large padding and text
-### DataTable
+### Form
+A form component with built-in state management, validation, and layout control. Works together with the `useForm` hook.
+
+```jsx
+import { Form, Input, Button, useForm } from 'luna-components-library';
+
+const MyForm = () => {
+  const form = useForm({
+    name:  { value: '', rules: [{ required: true, message: 'Name is required' }] },
+    email: { value: '', rules: [{ required: true }, { type: 'email', message: 'Invalid email' }] },
+    password: { value: '', rules: [
+      { required: true },
+      { minLength: 6, message: 'Min 6 characters' },
+      { validator: (v) => !validators.isStrongPassword(v) ? 'Must have letters and numbers' : undefined }
+    ]},
+    birthdate: { value: '', rules: [{ type: 'date' }, { maxDate: '2025-12-31' }] },
+    agree: { value: false, rules: [{ required: true, message: 'You must accept the terms' }] },
+  });
+
+  return (
+    <Form form={form} layout="vertical" onFinish={(values) => console.log(values)}>
+      <Form.Item name="name" label="Full Name" required>
+        <Input placeholder="John Doe" />
+      </Form.Item>
+      <Form.Item name="email" label="Email" required>
+        <Input type="email" placeholder="john@example.com" />
+      </Form.Item>
+      <Form.Item name="password" label="Password" required>
+        <Input type="password" placeholder="Min 6 chars" />
+      </Form.Item>
+      <Form.Item name="birthdate" label="Birth Date" required>
+        <Input type="date" />
+      </Form.Item>
+      <Form.Item name="agree">
+        <label>
+          <input type="checkbox" checked={form.values.agree} onChange={(e) => form.setValue('agree', e.target.checked)} />
+          I accept the terms
+        </label>
+      </Form.Item>
+      <Button type="submit">Submit</Button>
+      <Button type="button" variant="outline" onClick={form.reset}>Reset</Button>
+    </Form>
+  );
+};
+```
+
+**Form Props:**
+- `form: FormInstance` - Form instance from `useForm` hook
+- `onFinish?: (values) => void` - Called on valid submit
+- `onFinishFailed?: (errors) => void` - Called on invalid submit
+- `layout?: FormLayout` - Layout mode (default: `'vertical'`)
+- `children: React.ReactNode` - Form fields
+- `className?: string` - Additional CSS classes
+- `style?: React.CSSProperties` - Custom inline styles
+
+**Form.Item Props:**
+- `name?: string` - Field name, connects to form context
+- `label?: React.ReactNode` - Field label
+- `children: React.ReactElement` - Input component (auto-receives `value` and `onChange`)
+- `required?: boolean` - Shows `*` on label
+- `className?: string` - Additional CSS classes
+- `style?: React.CSSProperties` - Custom inline styles
+
+**Types:**
+```typescript
+type FormLayout = 'vertical' | 'horizontal' | 'inline';
+```
+
+**Behavior:**
+- `Form.Item` automatically injects `value`, `onChange`, and `variant="danger"` into the child when there's an error
+- Supports Luna `Input` and native HTML inputs (checkbox, etc.)
+- Error messages appear below the field in red
+
 A powerful and customizable data grid with support for filtering, sorting, pagination, selection, and search.
 
 ```jsx
@@ -833,15 +905,25 @@ const text = formatters.truncate('Long text here...', 10); // "Long text..."
 ```
 
 ### validators
-Common validation rules.
+Common validation functions, shared internally with `useForm`.
 
 ```javascript
 import { validators } from 'luna-components-library';
 
-validators.isEmail('test@example.com'); // true
-validators.isEmpty('   '); // true
-validators.isStrongPassword('Pass1234'); // true
-validators.isPhone('88888888', 'es-CR'); // true
+validators.isEmail('test@example.com');        // true
+validators.isUrl('https://example.com');       // true
+validators.isEmpty('   ');                     // true
+validators.isEmpty(null);                      // true
+validators.isEmpty(false);                     // true
+validators.isNumber('42');                     // true
+validators.isStrongPassword('Pass1234');       // true (8+ chars, letter + number)
+validators.isPhone('88888888', 'es-CR');       // true
+validators.minLength('hello', 3);             // true
+validators.maxLength('hello', 10);            // true
+validators.matchesPattern('ABC123', /^[A-Z]{3}\d{3}$/); // true
+validators.isDate('2025-01-15');              // true
+validators.isDateBefore('2024-01-01', '2025-01-01'); // true
+validators.isDateAfter('2025-01-01', '2024-01-01');  // true
 ```
 
 ### logger
@@ -882,7 +964,80 @@ function UserList() {
 }
 ```
 
-### useLocalStorage
+### useForm
+Manages form state and validation. Returns a `FormInstance` used by the `Form` component.
+
+```javascript
+import { useForm } from 'luna-components-library';
+
+const form = useForm({
+  email: {
+    value: '',
+    rules: [
+      { required: true, message: 'Email is required' },
+      { type: 'email', message: 'Invalid email' },
+    ]
+  },
+  age: {
+    value: '',
+    rules: [
+      { type: 'number', message: 'Must be a number' },
+    ]
+  },
+  website: {
+    value: '',
+    rules: [{ type: 'url', message: 'Invalid URL' }]
+  },
+  birthdate: {
+    value: '',
+    rules: [
+      { type: 'date', message: 'Invalid date' },
+      { minDate: '1900-01-01', message: 'Too old' },
+      { maxDate: '2025-12-31', message: 'Cannot be in the future' },
+    ]
+  },
+  bio: {
+    value: '',
+    rules: [
+      { minLength: 10, message: 'Min 10 characters' },
+      { maxLength: 200, message: 'Max 200 characters' },
+    ]
+  },
+  code: {
+    value: '',
+    rules: [{ pattern: /^[A-Z]{3}\d{3}$/, message: 'Format: ABC123' }]
+  },
+  custom: {
+    value: '',
+    rules: [{ validator: (v) => v !== 'forbidden' ? undefined : 'This value is not allowed' }]
+  },
+});
+
+// FormInstance API
+form.values;                    // { email: '', age: '', ... }
+form.errors;                    // { email: 'Email is required', ... }
+form.setValue('email', 'a@b.c'); // update + validate field
+form.validate();                 // validate all, returns boolean
+form.reset();                    // restore initial values
+form.setError('email', 'Taken'); // set error manually
+form.clearError('email');        // clear error manually
+```
+
+**FieldRule options:**
+```typescript
+type FieldRule = {
+  required?: boolean;       // field must not be empty
+  message?: string;         // custom error message
+  type?: 'email' | 'url' | 'number' | 'date'; // format validation
+  minLength?: number;       // minimum string length
+  maxLength?: number;       // maximum string length
+  minDate?: string;         // minimum date (ISO string)
+  maxDate?: string;         // maximum date (ISO string)
+  pattern?: RegExp;         // regex pattern
+  validator?: (value: any) => string | undefined; // custom validator
+};
+```
+
 Syncs state with `localStorage` automatically.
 
 ```javascript

package/dist/luna-components-library.js

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 //#endregion
@@ -2478,6 +2478,115 @@ var QRCode = ({ value, size = 160, color = "000000", bgColor = "ffffff", bordere
 	});
 };
 //#endregion
+//#region src/components/Form.tsx
+var FormContext = createContext(null);
+var useFormContext = () => useContext(FormContext);
+/**
+* Form.Item component that represents an individual form field. It accepts a name prop to connect to the form context, a label for display, and children which should be a form input component. It automatically handles value changes and displays validation errors based on the form context. The required prop adds an asterisk to the label and indicates that the field is required.
+* @param name The name of the form field, used to connect to the form context for value and error handling.
+* @param label The label to display for the form field.
+* @param children The form input component (e.g., Input, Checkbox) that will be rendered and connected to the form context.
+* @param required If true, indicates that the field is required and adds an asterisk to the label.
+* @param className Optional additional class name for styling.
+* @param style Optional additional styles for the form item container. 
+* @returns A Form.Item component that displays a label, the input field, and any validation error messages based on the form context.
+* @description Form.Item component that represents an individual form field. It accepts a name prop to connect to the form context, a label for display, and children which should be a form input component. It automatically handles value changes and displays validation errors based on the form context. The required prop adds an asterisk to the label and indicates that the field is required.
+* 
+*/
+var FormItem = ({ name, label, children, required, className, style }) => {
+	const ctx = useFormContext();
+	const error = name && ctx ? ctx.errors[name] : void 0;
+	const value = name && ctx ? ctx.values[name] : void 0;
+	const child = name && ctx ? React.createElement(children.type, {
+		...children.props,
+		value: value ?? "",
+		onChange: (val) => {
+			if (val && typeof val === "object" && val.target) ctx.setValue(name, val.target.type === "checkbox" ? val.target.checked : val.target.value);
+			else ctx.setValue(name, val);
+		},
+		variant: error ? "danger" : children.props.variant ?? void 0
+	}) : children;
+	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
+		className,
+		style: {
+			marginBottom: "1.25rem",
+			display: ctx?.layout === "horizontal" ? "flex" : "block",
+			alignItems: ctx?.layout === "horizontal" ? "flex-start" : void 0,
+			gap: ctx?.layout === "horizontal" ? "1rem" : void 0,
+			...style
+		},
+		children: [label && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("label", {
+			style: {
+				display: "block",
+				fontSize: fontSizes.sm,
+				fontWeight: fontWeights.medium,
+				color: colors.text,
+				marginBottom: ctx?.layout === "horizontal" ? 0 : "0.25rem",
+				minWidth: ctx?.layout === "horizontal" ? "120px" : void 0,
+				paddingTop: ctx?.layout === "horizontal" ? "0.5rem" : void 0
+			},
+			children: [required && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", {
+				style: {
+					color: colors.danger,
+					marginRight: "0.25rem"
+				},
+				children: "*"
+			}), label]
+		}), /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
+			style: { flex: 1 },
+			children: [child, error && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", {
+				style: {
+					display: "block",
+					marginTop: "0.25rem",
+					fontSize: fontSizes.xs,
+					color: colors.danger
+				},
+				children: error
+			})]
+		})]
+	});
+};
+/**
+* 
+* @param form The form instance created by the useForm hook, which manages form state and validation.
+* @param onFinish Callback function that is called when the form is successfully submitted and passes validation. It receives the form values as an argument.
+* @param onFinishFailed Callback function that is called when the form submission fails validation. It receives the form errors as an argument.
+* @param layout The layout of the form, which can be 'vertical', 'horizontal', or 'inline'. This affects how the form items are displayed.
+* @param children The form fields (Form.Item components) that will be rendered inside the form.  
+* @param className Optional additional class name for styling the form.
+* @param style Optional additional styles for the form container.
+* 
+* @returns A Form component that provides context for managing form state and validation. It includes a nested Form.Item component for individual form fields, which automatically connects to the form context for value and error handling. The Form component handles form submission and validation, while Form.Item displays labels, inputs, and error messages based on the provided rules.
+* @description Form component that provides context for managing form state and validation. It includes a nested Form.Item component for individual form fields, which automatically connects to the form context for value and error handling. The Form component handles form submission and validation, while Form.Item displays labels, inputs, and error messages based on the provided rules. 
+*/
+var Form = ({ form, onFinish, onFinishFailed, layout = "vertical", children, className, style }) => {
+	const handleSubmit = (e) => {
+		e.preventDefault();
+		if (form.validate()) onFinish?.(form.values);
+		else onFinishFailed?.(form.errors);
+	};
+	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FormContext.Provider, {
+		value: {
+			...form,
+			layout
+		},
+		children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("form", {
+			onSubmit: handleSubmit,
+			className,
+			style: {
+				display: layout === "inline" ? "flex" : "block",
+				flexWrap: layout === "inline" ? "wrap" : void 0,
+				gap: layout === "inline" ? "1rem" : void 0,
+				alignItems: layout === "inline" ? "flex-end" : void 0,
+				...style
+			},
+			noValidate: true,
+			children
+		})
+	});
+};
+Form.Item = FormItem;
+//#endregion
 //#region src/utilities/apiFetch.util.ts
 /**
 * A generic wrapper for the fetch API with error handling and response parsing.
@@ -2646,46 +2755,33 @@ var formatters = {
 	}
 };
 //#endregion
+//#region src/types.ts
+var EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var URL_REGEX = /^https?:\/\/.+/;
+//#endregion
 //#region src/utilities/validators.util.ts
-/**
-* Utility functions for common validations.
-*/
 var validators = {
-	/**
-	* Checks if a string is a valid email.
-	*/
-	isEmail: (email) => {
-		return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
-	},
-	/**
-	* Checks if a string is empty or only whitespace.
-	*/
-	isEmpty: (str) => {
-		return !str || str.trim().length === 0;
-	},
-	/**
-	* Checks if a value is a number.
-	*/
-	isNumber: (value) => {
-		return !isNaN(parseFloat(value)) && isFinite(value);
-	},
-	/**
-	* Validates if a password meets minimum complexity.
-	* (At least 8 chars, 1 letter, 1 number)
-	*/
-	isStrongPassword: (password) => {
-		return password.length >= 8 && /[A-Za-z]/.test(password) && /[0-9]/.test(password);
-	},
-	/**
-	* Validates a phone number.
-	* @param phone - Phone number string
-	* @param locale - Optional locale (default: 'generic')
-	*/
+	isEmail: (value) => EMAIL_REGEX.test(value),
+	isUrl: (value) => URL_REGEX.test(value),
+	isEmpty: (value) => value === void 0 || value === null || value === false || String(value).trim().length === 0,
+	isNumber: (value) => !isNaN(parseFloat(value)) && isFinite(value),
+	/** A strong password is defined as including both letters and numbers. */
+	isStrongPassword: (password, minLength) => password.length >= minLength && /[A-Za-z]/.test(password) && /[0-9]/.test(password),
 	isPhone: (phone, locale = "generic") => {
-		const cleanPhone = phone.replace(/\s|-/g, "");
-		if (locale === "es-CR") return /^[245678]\d{7}$/.test(cleanPhone);
-		return /^\+?[\d\s-]{7,}$/.test(cleanPhone);
-	}
+		const clean = phone.replace(/\s|-/g, "");
+		if (locale === "es-CR") return /^[245678]\d{7}$/.test(clean);
+		return /^\+?[\d\s-]{7,}$/.test(clean);
+	},
+	minLength: (value, min) => min === void 0 || value.length >= min,
+	maxLength: (value, max) => max === void 0 || value.length <= max,
+	matchesPattern: (value, pattern) => pattern.test(value),
+	isDate: (value) => {
+		if (!value) return false;
+		const d = new Date(value);
+		return !isNaN(d.getTime());
+	},
+	isDateBefore: (value, max) => new Date(value) < new Date(max),
+	isDateAfter: (value, min) => new Date(value) > new Date(min)
 };
 //#endregion
 //#region src/utilities/logger.util.ts
@@ -2803,6 +2899,99 @@ function useDebounce(value, delay = 500) {
 	return debouncedValue;
 }
 //#endregion
-export { Accordion, Anchor, Button, Card, DataTable, DropDown, Input, Modal, MultiSelect, Popconfirm, Preloader, ProgressBar, QRCode, ScrollTop, Spinner, Toast, Typed, WhatsApp, apiFetch, del, formatters, get, httpClient, logger, post, put, storage, useDebounce, useFetch, useLocalStorage, validators };
+//#region src/hooks/useForm.hook.ts
+/**
+* Validates a field value against its rules.
+* @param value 
+* @param rules 
+* @returns 
+* Checks the provided value against an array of validation rules. It returns an error message if any rule fails, or undefined if the value is valid. The function supports various types of validation, including required fields, email and URL formats, number checks, length constraints, date validations, custom patterns, and custom validator functions.
+*/
+var validateField = (value, rules = []) => {
+	for (const rule of rules) {
+		if (rule.validator) {
+			const msg = rule.validator(value);
+			if (msg) return msg;
+		}
+		if (rule.required && validators.isEmpty(value)) return rule.message ?? "This field is required";
+		if (rule.type === "email" && value && !validators.isEmail(value)) return rule.message ?? "Invalid email address";
+		if (rule.type === "url" && value && !validators.isUrl(value)) return rule.message ?? "Invalid URL";
+		if (rule.type === "number" && value && !validators.isNumber(value)) return rule.message ?? "Must be a number";
+		if (rule.minLength && value && !validators.minLength(value, rule.minLength)) return rule.message ?? `Minimum ${rule.minLength} characters`;
+		if (rule.maxLength && value && !validators.maxLength(value, rule.maxLength)) return rule.message ?? `Maximum ${rule.maxLength} characters`;
+		if (rule.type === "date" && value && !validators.isDate(value)) return rule.message ?? "Invalid date";
+		if (rule.minDate && value && !validators.isDateAfter(value, rule.minDate)) return rule.message ?? `Date must be after ${rule.minDate}`;
+		if (rule.maxDate && value && !validators.isDateBefore(value, rule.maxDate)) return rule.message ?? `Date must be before ${rule.maxDate}`;
+		if (rule.pattern && value && !validators.matchesPattern(value, rule.pattern)) return rule.message ?? "Invalid format";
+	}
+};
+/**
+* Hook for managing form state and validation.
+* @param fields 
+* @returns 
+* Provides form state management and validation based on a configuration object. Each field can have its own validation rules, and the hook returns current values, errors, and helper functions to manage the form.
+* The `useForm` hook initializes form values and errors based on the provided field configurations. It offers a `setValue` function to update field values and perform validation, a `validate` function to check all fields against their rules, a `reset` function to restore initial values, and functions to set or clear specific error messages. This hook abstracts away the complexities of form handling, making it easier to implement forms in React components.
+*/
+var useForm = (fields) => {
+	const initialValues = Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, v.value]));
+	const [values, setValues] = useState(initialValues);
+	const [errors, setErrors] = useState({});
+	const setValue = (name, value) => {
+		setValues((prev) => ({
+			...prev,
+			[name]: value
+		}));
+		const error = validateField(value, fields[name]?.rules);
+		setErrors((prev) => ({
+			...prev,
+			[name]: error
+		}));
+	};
+	const validate = () => {
+		const newErrors = {};
+		let valid = true;
+		for (const [name, config] of Object.entries(fields)) {
+			const error = validateField(values[name], config.rules);
+			if (error) {
+				newErrors[name] = error;
+				valid = false;
+			}
+		}
+		setErrors(newErrors);
+		return valid;
+	};
+	const reset = () => {
+		setValues(initialValues);
+		setErrors({});
+	};
+	const setError = (name, message) => {
+		setErrors((prev) => ({
+			...prev,
+			[name]: message
+		}));
+	};
+	const clearError = (name) => {
+		setErrors((prev) => ({
+			...prev,
+			[name]: void 0
+		}));
+	};
+	/**
+	* Returns the form instance with all its methods and state.
+	* This includes the current values of the form fields, any validation errors, and functions to update field values, validate the form, reset it, and manage errors. The hook abstracts away the complexity of form state management and validation, providing a simple interface for use in components.
+	* @returns {FormInstance} The form instance containing values, errors, and helper functions.
+	*/
+	return {
+		values,
+		errors,
+		setValue,
+		validate,
+		reset,
+		setError,
+		clearError
+	};
+};
+//#endregion
+export { Accordion, Anchor, Button, Card, DataTable, DropDown, Form, Input, Modal, MultiSelect, Popconfirm, Preloader, ProgressBar, QRCode, ScrollTop, Spinner, Toast, Typed, WhatsApp, apiFetch, del, formatters, get, httpClient, logger, post, put, storage, useDebounce, useFetch, useForm, useLocalStorage, validators };
 
 //# sourceMappingURL=luna-components-library.js.map