hazo_ui 2.1.2 → 2.2.1

package/README.md

@@ -12,25 +12,27 @@ npm install hazo_ui
 
 ### Component Overview
 
-- **[MultiFilterDialog](#multifilterdialog)** - A powerful dialog component for multi-field filtering with support for text, number, combobox, boolean, and date fields. Includes operator support, validation, and visual feedback.
+- **[HazoUiMultiFilterDialog](#hazouimultifilterdialog)** - A powerful dialog component for multi-field filtering with support for text, number, combobox, boolean, and date fields. Includes operator support, validation, and visual feedback.
 
-- **[MultiSortDialog](#multisortdialog)** - A flexible dialog component for multi-field sorting with drag-and-drop reordering. Allows users to set sort priority and direction (ascending/descending) for multiple fields.
+- **[HazoUiMultiSortDialog](#hazouimultisortdialog)** - A flexible dialog component for multi-field sorting with drag-and-drop reordering. Allows users to set sort priority and direction (ascending/descending) for multiple fields.
 
-- **[MultiStateRadio](#multistateradio)** - A flexible radio button/icon selection component with support for single and multi-selection modes, customizable layouts, and react-icons integration. Perfect for settings panels, preference selection, and option groups.
+- **[HazoUiFlexRadio](#hazouiflexradio)** - A flexible radio button/icon selection component with support for single and multi-selection modes, customizable layouts, and react-icons integration. Perfect for settings panels, preference selection, and option groups.
+
+- **[HazoUiFlexInput](#hazouiflexinput)** - An enhanced input component with type validation, character restrictions, and error messaging. Supports numeric, alpha, email, and mixed input types with built-in validation and formatting guides.
 
 ---
 
-## MultiFilterDialog
+## HazoUiMultiFilterDialog
 
 A powerful, flexible dialog component for multi-field filtering with support for various input types. Perfect for table headers, grid views, or any interface where users need to apply multiple filters simultaneously.
 
-![MultiFilterDialog - Filter Button with Active Filters Tooltip](https://github.com/pub12/hazo_ui/raw/main/docs/multifilterdialog/filter-button-tooltip.png)
+![HazoUiMultiFilterDialog - Filter Button with Active Filters Tooltip](https://github.com/pub12/hazo_ui/raw/main/docs/multifilterdialog/filter-button-tooltip.png)
 
-![MultiFilterDialog - Dialog with Multiple Filters](https://github.com/pub12/hazo_ui/raw/main/docs/multifilterdialog/filter-dialog.png)
+![HazoUiMultiFilterDialog - Dialog with Multiple Filters](https://github.com/pub12/hazo_ui/raw/main/docs/multifilterdialog/filter-dialog.png)
 
-![MultiFilterDialog - Calendar Date Picker](https://github.com/pub12/hazo_ui/raw/main/docs/multifilterdialog/filter-dialog-calendar.png)
+![HazoUiMultiFilterDialog - Calendar Date Picker](https://github.com/pub12/hazo_ui/raw/main/docs/multifilterdialog/filter-dialog-calendar.png)
 
-![MultiFilterDialog - Filter Output Example](https://github.com/pub12/hazo_ui/raw/main/docs/multifilterdialog/filter-output.png)
+![HazoUiMultiFilterDialog - Filter Output Example](https://github.com/pub12/hazo_ui/raw/main/docs/multifilterdialog/filter-output.png)
 
 #### Features
 
@@ -71,7 +73,7 @@ A powerful, flexible dialog component for multi-field filtering with support for
 #### Usage
 
 ```tsx
-import { MultiFilterDialog, type FilterField, type FilterConfig } from 'hazo_ui';
+import { HazoUiMultiFilterDialog, type FilterField, type FilterConfig } from 'hazo_ui';
 import { useState } from 'react';
 
 function DataTable() {
@@ -145,7 +147,7 @@ function DataTable() {
 
   return (
     <div>
-      <MultiFilterDialog
+      <HazoUiMultiFilterDialog
         availableFields={availableFields}
         onFilterChange={handleFilterChange}
         initialFilters={filters}
@@ -239,17 +241,17 @@ When users apply filters, the `onFilterChange` callback receives an array of `Fi
 
 ---
 
-## MultiSortDialog
+## HazoUiMultiSortDialog
 
 A powerful dialog component for multi-field sorting with drag-and-drop reordering. Allows users to select multiple fields for sorting, reorder them by priority, and set ascending/descending direction for each field.
 
-![MultiSortDialog - Sort Button with Active Sorts Tooltip](https://github.com/pub12/hazo_ui/raw/main/docs/multisortdialog/sort-button-tooltip.png)
+![HazoUiMultiSortDialog - Sort Button with Active Sorts Tooltip](https://github.com/pub12/hazo_ui/raw/main/docs/multisortdialog/sort-button-tooltip.png)
 
-![MultiSortDialog - Dialog with Multiple Sort Fields](https://github.com/pub12/hazo_ui/raw/main/docs/multisortdialog/sort-dialog.png)
+![HazoUiMultiSortDialog - Dialog with Multiple Sort Fields](https://github.com/pub12/hazo_ui/raw/main/docs/multisortdialog/sort-dialog.png)
 
-![MultiSortDialog - Drag and Drop Reordering](https://github.com/pub12/hazo_ui/raw/main/docs/multisortdialog/sort-drag-drop.png)
+![HazoUiMultiSortDialog - Drag and Drop Reordering](https://github.com/pub12/hazo_ui/raw/main/docs/multisortdialog/sort-drag-drop.png)
 
-![MultiSortDialog - Sort Output Example](https://github.com/pub12/hazo_ui/raw/main/docs/multisortdialog/sort-output.png)
+![HazoUiMultiSortDialog - Sort Output Example](https://github.com/pub12/hazo_ui/raw/main/docs/multisortdialog/sort-output.png)
 
 #### Features
 
@@ -278,7 +280,7 @@ The component returns an array of sort configurations in priority order, where t
 #### Usage
 
 ```tsx
-import { MultiSortDialog, type SortField, type SortConfig } from 'hazo_ui';
+import { HazoUiMultiSortDialog, type SortField, type SortConfig } from 'hazo_ui';
 import { useState } from 'react';
 
 function DataTable() {
@@ -319,7 +321,7 @@ function DataTable() {
 
   return (
     <div>
-      <MultiSortDialog
+      <HazoUiMultiSortDialog
         availableFields={availableFields}
         onSortChange={handleSortChange}
         initialSortFields={sorts}
@@ -446,7 +448,7 @@ const sortedData = applySorts(originalData, sorts);
 
 ---
 
-## MultiStateRadio
+## HazoUiFlexRadio
 
 A flexible radio button/icon selection component with support for single and multi-selection modes, customizable layouts, and react-icons integration. Perfect for settings panels, preference selection, and option groups.
 
@@ -466,19 +468,19 @@ A flexible radio button/icon selection component with support for single and mul
 #### Props
 
 ```typescript
-interface MultiStateRadioItem {
+interface HazoUiFlexRadioItem {
   label: string;                    // Display label for the option
   value: string;                    // Unique value identifier
   icon_selected?: string;           // Icon name when selected (e.g., "FaHome")
   icon_unselected?: string;         // Icon name when unselected (e.g., "FaRegHome")
 }
 
-interface MultiStateRadioProps {
+interface HazoUiFlexRadioProps {
   layout?: 'horizontal' | 'vertical';  // Layout direction (default: 'horizontal')
   style?: 'radio' | 'icons';           // Display style (default: 'radio')
   display_label?: boolean;              // Show/hide labels (default: true)
   icon_set?: string;                    // Icon set package name (e.g., 'fa', 'md')
-  data: MultiStateRadioItem[];          // Array of options
+  data: HazoUiFlexRadioItem[];          // Array of options
   selection: 'single' | 'multi';       // Selection mode
   value: string | string[];             // Controlled value (string for single, array for multi)
   onChange: (value: string | string[]) => void;  // Change handler
@@ -491,13 +493,13 @@ interface MultiStateRadioProps {
 **Basic Single Selection (Radio Style)**
 
 ```tsx
-import { MultiStateRadio, type MultiStateRadioItem } from 'hazo_ui';
+import { HazoUiFlexRadio, type HazoUiFlexRadioItem } from 'hazo_ui';
 import { useState } from 'react';
 
 function SettingsPanel() {
   const [selectedOption, setSelectedOption] = useState<string>('option1');
 
-  const options: MultiStateRadioItem[] = [
+  const options: HazoUiFlexRadioItem[] = [
     { label: 'Option 1', value: 'option1' },
     { label: 'Option 2', value: 'option2' },
     { label: 'Option 3', value: 'option3' },
@@ -505,7 +507,7 @@ function SettingsPanel() {
   ];
 
   return (
-    <MultiStateRadio
+    <HazoUiFlexRadio
       data={options}
       value={selectedOption}
       onChange={setSelectedOption}
@@ -521,13 +523,13 @@ function SettingsPanel() {
 **Icon Style with React Icons**
 
 ```tsx
-import { MultiStateRadio, type MultiStateRadioItem } from 'hazo_ui';
+import { HazoUiFlexRadio, type HazoUiFlexRadioItem } from 'hazo_ui';
 import { useState } from 'react';
 
 function IconSelector() {
   const [selectedIcon, setSelectedIcon] = useState<string>('home');
 
-  const iconOptions: MultiStateRadioItem[] = [
+  const iconOptions: HazoUiFlexRadioItem[] = [
     {
       label: 'Home',
       value: 'home',
@@ -549,7 +551,7 @@ function IconSelector() {
   ];
 
   return (
-    <MultiStateRadio
+    <HazoUiFlexRadio
       data={iconOptions}
       value={selectedIcon}
       onChange={setSelectedIcon}
@@ -566,13 +568,13 @@ function IconSelector() {
 **Multi-Selection Mode**
 
 ```tsx
-import { MultiStateRadio, type MultiStateRadioItem } from 'hazo_ui';
+import { HazoUiFlexRadio, type HazoUiFlexRadioItem } from 'hazo_ui';
 import { useState } from 'react';
 
 function MultiSelectExample() {
   const [selectedOptions, setSelectedOptions] = useState<string[]>(['option1', 'option3']);
 
-  const options: MultiStateRadioItem[] = [
+  const options: HazoUiFlexRadioItem[] = [
     { label: 'Option 1', value: 'option1' },
     { label: 'Option 2', value: 'option2' },
     { label: 'Option 3', value: 'option3' },
@@ -580,7 +582,7 @@ function MultiSelectExample() {
   ];
 
   return (
-    <MultiStateRadio
+    <HazoUiFlexRadio
       data={options}
       value={selectedOptions}
       onChange={setSelectedOptions}
@@ -596,13 +598,13 @@ function MultiSelectExample() {
 **Vertical Layout with Icons Only (No Labels)**
 
 ```tsx
-import { MultiStateRadio, type MultiStateRadioItem } from 'hazo_ui';
+import { HazoUiFlexRadio, type HazoUiFlexRadioItem } from 'hazo_ui';
 import { useState } from 'react';
 
 function VerticalIconSelector() {
   const [selected, setSelected] = useState<string>('favorite');
 
-  const options: MultiStateRadioItem[] = [
+  const options: HazoUiFlexRadioItem[] = [
     {
       label: 'Favorite',
       value: 'favorite',
@@ -618,7 +620,7 @@ function VerticalIconSelector() {
   ];
 
   return (
-    <MultiStateRadio
+    <HazoUiFlexRadio
       data={options}
       value={selected}
       onChange={setSelected}
@@ -667,6 +669,257 @@ The component supports the following react-icons packages:
 
 ---
 
+## HazoUiFlexInput
+
+An enhanced input component with type validation, character restrictions, and error messaging. Extends shadcn Input component with additional validation props for numeric, alpha, email, and mixed input types.
+
+#### Features
+
+- **Multiple Input Types**: Supports mixed (text), numeric, alpha (letters only), and email input types
+- **Real-time Character Filtering**: Automatically prevents invalid characters from being entered (e.g., numbers in alpha fields)
+- **Validation on Blur**: Validates input when the field loses focus and displays error messages
+- **Numeric Constraints**: Min/max value validation and decimal precision control
+- **Length Constraints**: Configurable minimum and maximum character lengths
+- **Regex Validation**: Custom regex pattern support for complex validation rules
+- **Format Guide**: Optional helper text displayed below the input
+- **Error Messaging**: Clear error messages displayed when validation fails
+- **Controlled & Uncontrolled**: Supports both controlled and uncontrolled usage patterns
+- **TypeScript Support**: Fully typed with TypeScript interfaces
+- **Accessible**: Built with accessibility in mind using shadcn/ui components
+
+#### Input Types
+
+1. **Mixed (text)**
+   - Allows any characters
+   - Supports length constraints (min/max)
+   - Supports regex validation
+
+2. **Numeric**
+   - Only allows numbers, decimal point, and minus sign
+   - Supports min/max value constraints
+   - Configurable decimal precision (including integers with 0 decimals)
+   - Automatically filters out non-numeric characters
+
+3. **Alpha**
+   - Only allows letters and spaces
+   - Automatically filters out numbers and special characters
+   - Supports length constraints
+
+4. **Email**
+   - Validates email format on blur
+   - Uses standard email regex pattern
+
+#### Props
+
+```typescript
+interface HazoUiFlexInputProps extends Omit<InputProps, "type"> {
+  input_type?: "mixed" | "numeric" | "email" | "alpha";  // Input type (default: "mixed")
+  text_len_min?: number;                                  // Minimum character length
+  text_len_max?: number;                                  // Maximum character length
+  num_min?: number;                                       // Minimum numeric value
+  num_max?: number;                                       // Maximum numeric value
+  regex?: string | RegExp;                                // Custom regex pattern
+  num_decimals?: number;                                  // Number of decimal places allowed
+  format_guide?: string;                                  // Helper text displayed below input
+  format_guide_info?: boolean;                            // Show format guide (default: false)
+}
+```
+
+#### Usage
+
+**Basic Mixed Input**
+
+```tsx
+import { HazoUiFlexInput } from 'hazo_ui';
+import { useState } from 'react';
+
+function BasicForm() {
+  const [value, setValue] = useState<string>("");
+
+  return (
+    <HazoUiFlexInput
+      input_type="mixed"
+      placeholder="Enter text..."
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+}
+```
+
+**Numeric Input with Constraints**
+
+```tsx
+import { HazoUiFlexInput } from 'hazo_ui';
+import { useState } from 'react';
+
+function PriceInput() {
+  const [price, setPrice] = useState<string>("");
+
+  return (
+    <HazoUiFlexInput
+      input_type="numeric"
+      placeholder="Enter price (0-100)..."
+      num_min={0}
+      num_max={100}
+      num_decimals={2}
+      format_guide="Enter a number between 0 and 100 with up to 2 decimal places"
+      format_guide_info={true}
+      value={price}
+      onChange={(e) => setPrice(e.target.value)}
+    />
+  );
+}
+```
+
+**Integer Input (No Decimals)**
+
+```tsx
+import { HazoUiFlexInput } from 'hazo_ui';
+import { useState } from 'react';
+
+function AgeInput() {
+  const [age, setAge] = useState<string>("");
+
+  return (
+    <HazoUiFlexInput
+      input_type="numeric"
+      placeholder="Enter age (1-120)..."
+      num_min={1}
+      num_max={120}
+      num_decimals={0}
+      format_guide="Enter a whole number between 1 and 120"
+      format_guide_info={true}
+      value={age}
+      onChange={(e) => setAge(e.target.value)}
+    />
+  );
+}
+```
+
+**Alpha Input (Letters Only)**
+
+```tsx
+import { HazoUiFlexInput } from 'hazo_ui';
+import { useState } from 'react';
+
+function NameInput() {
+  const [name, setName] = useState<string>("");
+
+  return (
+    <HazoUiFlexInput
+      input_type="alpha"
+      placeholder="Enter name (letters only)..."
+      format_guide="Only letters and spaces are allowed"
+      format_guide_info={true}
+      value={name}
+      onChange={(e) => setName(e.target.value)}
+    />
+  );
+}
+```
+
+**Email Input with Validation**
+
+```tsx
+import { HazoUiFlexInput } from 'hazo_ui';
+import { useState } from 'react';
+
+function EmailForm() {
+  const [email, setEmail] = useState<string>("");
+
+  return (
+    <HazoUiFlexInput
+      input_type="email"
+      placeholder="Enter email address..."
+      format_guide="Enter a valid email address (e.g., user@example.com)"
+      format_guide_info={true}
+      value={email}
+      onChange={(e) => setEmail(e.target.value)}
+    />
+  );
+}
+```
+
+**Mixed Input with Length Constraints**
+
+```tsx
+import { HazoUiFlexInput } from 'hazo_ui';
+import { useState } from 'react';
+
+function UsernameInput() {
+  const [username, setUsername] = useState<string>("");
+
+  return (
+    <HazoUiFlexInput
+      input_type="mixed"
+      placeholder="Enter username (5-20 characters)..."
+      text_len_min={5}
+      text_len_max={20}
+      format_guide="Must be between 5 and 20 characters"
+      format_guide_info={true}
+      value={username}
+      onChange={(e) => setUsername(e.target.value)}
+    />
+  );
+}
+```
+
+**Input with Regex Validation**
+
+```tsx
+import { HazoUiFlexInput } from 'hazo_ui';
+import { useState } from 'react';
+
+function PhoneInput() {
+  const [phone, setPhone] = useState<string>("");
+
+  return (
+    <HazoUiFlexInput
+      input_type="mixed"
+      placeholder="Enter phone number (XXX-XXX-XXXX)..."
+      regex={/^\d{3}-\d{3}-\d{4}$/}
+      format_guide="Format: XXX-XXX-XXXX (e.g., 123-456-7890)"
+      format_guide_info={true}
+      value={phone}
+      onChange={(e) => setPhone(e.target.value)}
+    />
+  );
+}
+```
+
+#### Validation Behavior
+
+- **Character Filtering**: For `numeric` and `alpha` types, invalid characters are automatically filtered out as the user types
+- **Validation Timing**: Validation occurs when the input loses focus (onBlur event)
+- **Error Display**: Error messages appear below the input in red text when validation fails
+- **Format Guide**: Optional helper text can be displayed below the input (set `format_guide_info={true}`)
+- **Error Priority**: If both an error message and format guide are present, only the error message is shown
+
+#### Expected Output
+
+The component behaves like a standard input element:
+
+```typescript
+// onChange receives a standard React.ChangeEvent<HTMLInputElement>
+onChange={(e) => {
+  const value = e.target.value;  // Current input value as string
+  // Handle value change
+}}
+```
+
+#### Error Messages
+
+The component provides default error messages for common validation failures:
+
+- **Numeric**: "Must be a valid number", "Must be at least X", "Must be at most X", "Maximum X decimal places allowed"
+- **Alpha**: "Only letters are allowed"
+- **Email**: "Must be a valid email address"
+- **Mixed**: "Must be at least X characters", "Must be at most X characters"
+- **Regex**: "Invalid format" (or custom message via `format_guide`)
+
+---
+
 ## Styling
 
 Both components use Tailwind CSS and follow shadcn/ui design patterns. Make sure your project has Tailwind CSS configured with the following CSS variables: