luna-components-library 1.1.40 → 1.1.42

package/README.md

@@ -125,28 +125,35 @@ const isValid = validators.isEmail('user@luna.com'); // true
 All components use TypeScript with specific types for better type safety and IntelliSense. The library follows a minimal documentation approach with descriptive type names instead of extensive JSDoc comments.
 
 ### Button
-A versatile button component with multiple variants and sizes.
+A versatile button component with multiple variants, sizes, icons, and rounded style.
 
 ```jsx
-<Button 
-  variant="primary" 
-  size="md"
-  onClick={handleClick}
-  disabled={false}
->
-  Button Text
-</Button>
+// Basic
+<Button variant="primary" size="md" onClick={handleClick}>Click Me</Button>
+
+// Rounded (pill)
+<Button variant="primary" rounded>Rounded</Button>
+
+// With icon
+<Button variant="primary" icon="🚀">Deploy</Button>
+<Button variant="outline" icon="→" iconPosition="right">Next</Button>
+
+// Icon only
+<Button variant="danger" rounded icon="✕" />
 ```
 
 **Props:**
-- `children`: React.ReactNode - Button content
+- `children?: React.ReactNode` - Button content (optional when using icon only)
 - `variant?: ButtonVariant` - Button style (default: 'primary')
-- `size?: ButtonSize` - Button size (default: 'md')
+- `size?: ButtonSize` - Button size (default: 'sm')
+- `rounded?: boolean` - Pill/circle shape (default: false)
+- `icon?: React.ReactNode` - Icon element, emoji, or any ReactNode
+- `iconPosition?: 'left' | 'right'` - Icon placement (default: 'left')
 - `onClick?: React.MouseEventHandler<HTMLButtonElement>` - Click handler
 - `disabled?: boolean` - Disable button (default: false)
 - `className?: string` - Additional CSS classes
 - `style?: React.CSSProperties` - Custom inline styles
-- `...props`: any - Additional HTML button attributes (spreads all native button props)
+- `...props`: any - Additional HTML button attributes
 
 **Types:**
 ```typescript
@@ -155,15 +162,15 @@ type ButtonSize = 'sm' | 'md' | 'lg';
 ```
 
 **Variants:**
-- `primary` - Blue background button
-- `secondary` - Gray background button  
+- `primary` - Blue background
+- `secondary` - Gray background
 - `outline` - Transparent with border
-- `success` - Green background button
-- `danger` - Red background button
-- `warning` - Yellow background button
-- `info` - Cyan background button
-- `dark` - Dark gray background button
-- `light` - Light gray background button
+- `success` - Green background
+- `danger` - Red background
+- `warning` - Yellow background
+- `info` - Cyan background
+- `dark` - Dark gray background
+- `light` - Light gray background
 - `link` - Blue text link with hover effects
 
 ### Card
@@ -626,74 +633,148 @@ const MyComponent = () => {
 ```
 
 ### Input
-A versatile input component with multiple variants, sizes, masks, currency formatting, and types.
+A versatile input component with multiple variants, sizes, masks, currency formatting, icons, and required indicator.
 
 ```jsx
-<Input 
-  inputSize="md"
-  variant="primary"
-  type="text"
-  placeholder="Enter your text here"
-  value={inputValue}
-  onChange={(value) => setInputValue(value)}
-  className="custom-class"
-  id="my-input"
->
-  Input Label
-</Input>
+// Basic
+<Input variant="primary" placeholder="Enter text">Label</Input>
+
+// With icon
+<Input icon="🔍" placeholder="Search...">Search</Input>
+<Input icon="🔒" iconPosition="right" variant="danger" placeholder="Password">Password</Input>
+
+// Required indicator
+<Input isRequired variant="primary" placeholder="Email">Email</Input>
+
+// Currency
+<Input useCurrency currency="USD" locale="en-US" placeholder="$0.00">Price</Input>
+
+// Mask
+<Input mask="(999) 999-9999" placeholder="(555) 000-0000">Phone</Input>
 ```
 
 **Props:**
-- `children?: React.ReactNode` - Label content for the input
-- `variant?: InputVariant` - Input style variant (default: 'none')
+- `children?: React.ReactNode` - Label content
+- `variant?: InputVariant` - Border color variant (default: 'none')
 - `inputSize?: InputSize` - Input size (default: 'md')
 - `type?: InputType` - HTML input type (default: 'text')
 - `placeholder?: string` - Placeholder text
-- `value?: string` - Input value
+- `value?: string` - Controlled value
 - `onChange?: (value: string) => void` - Change handler
 - `onFocus?: () => void` - Focus handler
 - `onBlur?: () => void` - Blur handler
 - `disabled?: boolean` - Disable input (default: false)
-- `required?: boolean` - Required field (default: false)
+- `required?: boolean` - HTML required attribute (default: false)
+- `isRequired?: boolean` - Shows a red `*` next to the label (default: false)
 - `readOnly?: boolean` - Read-only input (default: false)
+- `icon?: React.ReactNode` - Icon inside the input (emoji, SVG, component)
+- `iconPosition?: 'left' | 'right'` - Icon placement (default: 'left')
 - `className?: string` - Additional CSS classes
 - `style?: React.CSSProperties` - Custom inline styles
-- `id?: string` - HTML id attribute for label association
+- `id?: string` - HTML id for label association
 - `name?: string` - HTML name attribute
-- `classNames?: InputClassNames` - Custom class names for sub-elements
-- `styles?: InputStyles` - Custom inline styles per element
-- `mask?: string` - Input mask pattern (e.g. "(999) 999-9999")
-- `maskChar?: string` - Mask placeholder character (default: '_')
+- `classNames?: InputClassNames` - Custom class names per sub-element
+- `styles?: InputStyles` - Custom inline styles per sub-element
+- `mask?: string` - Input mask pattern (e.g. `"(999) 999-9999"`)
+- `maskChar?: string` - Mask placeholder character (default: `'_'`)
 - `useCurrency?: boolean` - Enable currency formatting
-- `currency?: string` - Currency code (e.g. "USD", "CRC")
-- `locale?: string` - Locale for formatting (e.g. "en-US", "es-CR")
+- `currency?: string` - Currency code (e.g. `"USD"`, `"CRC"`)
+- `locale?: string` - Locale for formatting (e.g. `"en-US"`, `"es-CR"`)
 - `minFractionDigits?: number` - Minimum fraction digits (default: 0)
 - `maxFractionDigits?: number` - Maximum fraction digits (default: 2)
-- `aria-label?: string` - ARIA label for accessibility
+- `aria-label?: string` - ARIA label
 - `aria-labelledby?: string` - ARIA labelledby
 - `...props`: any - Additional HTML input attributes
 
 **Types:**
 ```typescript
-type InputVariant = 'none' | 'primary' | 'secondary' | 'outline' | 'danger' | 'success';
+type InputVariant = 'none' | 'primary' | 'secondary' | 'outline' | 'danger' | 'success' | 'warning' | 'info' | 'dark' | 'light' | 'link';
 type InputSize = 'sm' | 'md' | 'lg' | 'xl';
 type InputType = 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 'date' | 'time' | 'datetime-local' | 'month' | 'week' | 'color' | 'file' | 'hidden' | 'image' | 'range' | 'reset' | 'submit';
 ```
 
-**Variants:**
-- `none` - Default styling with border
-- `primary` - Blue focus ring
-- `secondary` - Gray focus ring
-- `outline` - Border only
-- `danger` - Red focus ring
-- `success` - Green focus ring
+**Focus behavior:** Border increases from `1px` to `2px` on focus, using the variant color. On blur it returns to `1px` with the same variant color.
+
+**Variants:** Each variant applies a distinct border color — `primary` (blue), `secondary` (gray), `danger` (red), `success` (green), `warning` (yellow), `info` (cyan), `dark`, `light`, `outline` (default gray), `none` (default gray).
 
 **Size Options:**
 - `sm` - Small padding and text
 - `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
@@ -824,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
@@ -873,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