@gnwebsoft/ui 4.0.2 → 4.0.4

package/README.md

@@ -40,7 +40,7 @@ npm install react react-dom @mui/material @mui/icons-material @emotion/react @em
 ```json
 {
   "@emotion/cache": "^11.14.0",
-  "@emotion/react": "^11.14.0", 
+  "@emotion/react": "^11.14.0",
   "@emotion/styled": "^11.14.0",
   "@hookform/resolvers": "^5.2.1",
   "@mui/icons-material": "^7.3.1",
@@ -61,6 +61,7 @@ npm install react react-dom @mui/material @mui/icons-material @emotion/react @em
   "zustand": "^5.0.2"
 }
 ```
+
 </details>
 
 ## Quick Start
@@ -77,8 +78,8 @@ function App() {
     <ThemeProvider theme={theme}>
       <div>
         <LabelText>Welcome to @gnwebsoft/ui</LabelText>
-        <SimpleButton 
-          variant="contained" 
+        <SimpleButton
+          variant="contained"
           color="primary"
           onClick={() => alert('Hello World!')}
         >
@@ -110,19 +111,20 @@ import { SimpleButton, TextFieldElement } from '@gnwebsoft/ui';
 
 ### Available Modules
 
-| Module | Description | Import Path |
-|--------|-------------|-------------|
-| **Components** | UI components | `@gnwebsoft/ui/components` |
-| **Wrappers** | Form element wrappers | `@gnwebsoft/ui/wrappers` |
-| **Hooks** | Custom React hooks | `@gnwebsoft/ui/hooks` |
-| **Types** | TypeScript definitions | `@gnwebsoft/ui/types` |
-| **Utils** | Utility functions | `@gnwebsoft/ui/utils` |
+| Module         | Description            | Import Path                |
+| -------------- | ---------------------- | -------------------------- |
+| **Components** | UI components          | `@gnwebsoft/ui/components` |
+| **Wrappers**   | Form element wrappers  | `@gnwebsoft/ui/wrappers`   |
+| **Hooks**      | Custom React hooks     | `@gnwebsoft/ui/hooks`      |
+| **Types**      | TypeScript definitions | `@gnwebsoft/ui/types`      |
+| **Utils**      | Utility functions      | `@gnwebsoft/ui/utils`      |
 
 ## Components
 
 ### Basic Components
 
 #### SimpleButton
+
 Enhanced MUI Button with loading states and conditional rendering.
 
 ```tsx
@@ -136,10 +138,11 @@ import { SimpleButton } from '@gnwebsoft/ui/components';
   onClick={handleSubmit}
 >
   Save Changes
-</SimpleButton>
+</SimpleButton>;
 ```
 
 **Features:**
+
 - Loading state with spinner
 - Conditional rendering
 - Automatic disabling during loading
@@ -147,22 +150,24 @@ import { SimpleButton } from '@gnwebsoft/ui/components';
 - Full TypeScript support
 
 #### LabelText
+
 Responsive label-value display component with grid layout and hover effects.
 
 ```tsx
 import { LabelText } from '@gnwebsoft/ui/components';
 
-<LabelText 
-  label="Full Name" 
+<LabelText
+  label="Full Name"
   value="John Doe"
   gridSize={{
     labelSize: { xs: 12, sm: 4, md: 3 },
-    valueSize: { xs: 12, sm: 8, md: 9 }
+    valueSize: { xs: 12, sm: 8, md: 9 },
   }}
-/>
+/>;
 ```
 
 **Features:**
+
 - Responsive grid layout
 - Hover effects with background color change
 - Text overflow handling with ellipsis
@@ -170,6 +175,7 @@ import { LabelText } from '@gnwebsoft/ui/components';
 - Customizable spacing and styling
 
 #### AuthorizedView
+
 Simple conditional rendering component based on a boolean show prop.
 
 ```tsx
@@ -177,32 +183,34 @@ import { AuthorizedView } from '@gnwebsoft/ui/components';
 
 <AuthorizedView show={user.hasAdminRole}>
   <AdminPanel />
-</AuthorizedView>
+</AuthorizedView>;
 ```
 
 **Features:**
+
 - Minimal overhead conditional rendering
 - Returns empty fragment when hidden
 - TypeScript support
 
 #### ClearButton, CancelButton, FilterButton
+
 Standardized button components for common form actions.
 
 ```tsx
 import { ClearButton, CancelButton, FilterButton } from '@gnwebsoft/ui/components';
 
-<ClearButton 
+<ClearButton
   isSubmitting={isLoading}
   handleClear={() => reset()}
   storeKey="userFormData" // Optional localStorage cleanup
 />
 
-<CancelButton 
+<CancelButton
   isSubmitting={isLoading}
   handleCancel={() => navigate('/dashboard')}
 />
 
-<FilterButton 
+<FilterButton
   isSubmitting={isFiltering}
   show={hasFilters}
   title="Apply Filters"
@@ -213,12 +221,13 @@ import { ClearButton, CancelButton, FilterButton } from '@gnwebsoft/ui/component
 ### Layout Components
 
 #### FormWrapper
+
 Card-based container for forms with header, title, and action buttons.
 
 ```tsx
 import { FormWrapper } from '@gnwebsoft/ui/components';
 
-<FormWrapper 
+<FormWrapper
   title="User Profile"
   icon={<PersonIcon />}
   actionButton={
@@ -229,16 +238,18 @@ import { FormWrapper } from '@gnwebsoft/ui/components';
 >
   <TextFieldElement name="firstName" label="First Name" />
   <TextFieldElement name="lastName" label="Last Name" />
-</FormWrapper>
+</FormWrapper>;
 ```
 
 **Features:**
+
 - Card-based layout with header and content areas
 - Divider between header and content
 - Flexible action button placement
 - Grid container for content with spacing
 
 #### FilterWrapper, ListWrapper, SimpleToolbar
+
 Specialized container components for different UI patterns.
 
 ```tsx
@@ -272,7 +283,7 @@ import {
   TextFieldElement,
   SelectElement,
   DatePickerElement,
-  CheckboxElement
+  CheckboxElement,
 } from '@gnwebsoft/ui/wrappers';
 
 const schema = z.object({
@@ -280,14 +291,14 @@ const schema = z.object({
   email: z.string().email('Invalid email'),
   category: z.string(),
   birthDate: z.date(),
-  subscribe: z.boolean()
+  subscribe: z.boolean(),
 });
 
 type FormData = z.infer<typeof schema>;
 
 function ContactForm() {
   const { control, handleSubmit } = useForm<FormData>({
-    resolver: zodResolver(schema)
+    resolver: zodResolver(schema),
   });
 
   return (
@@ -298,7 +309,7 @@ function ContactForm() {
         label="Full Name"
         required
       />
-      
+
       <TextFieldElement
         control={control}
         name="email"
@@ -306,29 +317,29 @@ function ContactForm() {
         type="email"
         required
       />
-      
+
       <SelectElement
         control={control}
         name="category"
         label="Category"
         options={[
           { value: 'general', label: 'General Inquiry' },
-          { value: 'support', label: 'Support' }
+          { value: 'support', label: 'Support' },
         ]}
       />
-      
+
       <DatePickerElement
         control={control}
         name="birthDate"
         label="Birth Date"
       />
-      
+
       <CheckboxElement
         control={control}
         name="subscribe"
         label="Subscribe to newsletter"
       />
-      
+
       <SimpleButton type="submit" variant="contained">
         Submit
       </SimpleButton>
@@ -339,24 +350,25 @@ function ContactForm() {
 
 ### Available Form Wrappers
 
-| Component | Description | Use Case | Features |
-|-----------|-------------|----------|----------|
-| `TextFieldElement` | Text input wrapper | Single-line text, email, password | Value transformation, grid layout, auto-validation |
-| `PasswordElement` | Password input with visibility toggle | Secure password entry | Eye icon toggle, all TextFieldElement features |
-| `SelectElement` | Single selection dropdown | Categories, statuses | Auto-select single option, custom label/value keys |
-| `SelectMultiElement` | Multiple selection dropdown | Tags, permissions | Chip display, select all/none functionality |
-| `SelectCascadeElement` | Dependent dropdown selections | Country → State → City | Hierarchical options, parent-child relationships |
-| `AsyncSelect` | Async searchable dropdown | User search, API data | Debounced search, loading states, no options handling |
-| `AsyncMultiSelect` | Async multiple selection | Multiple user selection | Async loading with multi-select capabilities |
-| `DatePickerElement` | Date selection | Birth dates, deadlines | MUI date picker integration, keyboard input |
-| `TimePickerElement` | Time selection | Appointments, schedules | MUI time picker integration, 12/24 hour format |
-| `CheckboxElement` | Single checkbox | Agreements, preferences | Boolean value handling, label integration |
-| `CheckboxGroup` | Multiple checkboxes | Multiple selections | Array value handling, group validation |
-| `RadioButtonGroup` | Radio button group | Exclusive selections | Single selection from multiple options |
+| Component              | Description                           | Use Case                          | Features                                              |
+| ---------------------- | ------------------------------------- | --------------------------------- | ----------------------------------------------------- |
+| `TextFieldElement`     | Text input wrapper                    | Single-line text, email, password | Value transformation, grid layout, auto-validation    |
+| `PasswordElement`      | Password input with visibility toggle | Secure password entry             | Eye icon toggle, all TextFieldElement features        |
+| `SelectElement`        | Single selection dropdown             | Categories, statuses              | Auto-select single option, custom label/value keys    |
+| `SelectMultiElement`   | Multiple selection dropdown           | Tags, permissions                 | Chip display, select all/none functionality           |
+| `SelectCascadeElement` | Dependent dropdown selections         | Country → State → City            | Hierarchical options, parent-child relationships      |
+| `AsyncSelect`          | Async searchable dropdown             | User search, API data             | Debounced search, loading states, no options handling |
+| `AsyncMultiSelect`     | Async multiple selection              | Multiple user selection           | Async loading with multi-select capabilities          |
+| `DatePickerElement`    | Date selection                        | Birth dates, deadlines            | MUI date picker integration, keyboard input           |
+| `TimePickerElement`    | Time selection                        | Appointments, schedules           | MUI time picker integration, 12/24 hour format        |
+| `CheckboxElement`      | Single checkbox                       | Agreements, preferences           | Boolean value handling, label integration             |
+| `CheckboxGroup`        | Multiple checkboxes                   | Multiple selections               | Array value handling, group validation                |
+| `RadioButtonGroup`     | Radio button group                    | Exclusive selections              | Single selection from multiple options                |
 
 ## Hooks
 
 ### useTransform
+
 Transform values with memoization and change handling for form components.
 
 ```tsx
@@ -366,13 +378,14 @@ const { value, onChange } = useTransform({
   value: formValue,
   onChange: field.onChange,
   transform: {
-    input: (value) => value?.toString() || '',
-    output: (event) => parseInt(event.target.value) || null
-  }
+    input: value => value?.toString() || '',
+    output: event => parseInt(event.target.value) || null,
+  },
 });
 ```
 
 **Features:**
+
 - Memoized transformations for performance
 - Input/output transformation support
 - Change event handling
@@ -380,6 +393,7 @@ const { value, onChange } = useTransform({
 - Integration with form components
 
 **Common Use Cases:**
+
 - Number input formatting
 - Date formatting
 - Currency formatting
@@ -390,32 +404,34 @@ const { value, onChange } = useTransform({
 Comprehensive TypeScript interfaces for API integration and form handling:
 
 ```tsx
-import type { 
-  ApiResponse, 
-  OperationResponse, 
+import type {
+  ApiResponse,
+  OperationResponse,
   ValidationErrors,
   OptionItem,
   PostModel,
-  ListResponse
+  ListResponse,
 } from '@gnwebsoft/ui/types';
 
 // API response structure
 const response: ApiResponse<User[]> = {
   status: 200,
-  apiData: users,
-  traceId: 'abc123'
+  data: users,
+  traceId: 'abc123',
 };
 
 // Form options
 const options: OptionItem[] = [
   { Label: 'Option 1', Value: '1' },
-  { Label: 'Option 2', Value: '2' }
+  { Label: 'Option 2', Value: '2' },
 ];
 
 // Paginated list response
 const listResponse: ListResponse<User> = {
-  Data: [/* users */],
-  Total: 150
+  Data: [
+    /* users */
+  ],
+  Total: 150,
 };
 
 // Filter/search request
@@ -424,11 +440,12 @@ const filterRequest: PostModel<UserFilter> = {
   pageOffset: 0,
   pageSize: 20,
   sortField: 'name',
-  sortOrder: 'asc'
+  sortOrder: 'asc',
 };
 ```
 
 **Available Types:**
+
 - `ApiResponse<T>` - Standard API response structure
 - `ValidationErrors` - Form validation errors
 - `OptionItem` / `OptionItem2` - Select options
@@ -446,7 +463,10 @@ import { api, handleServerErrors } from '@gnwebsoft/ui/utils';
 // API calls with automatic authentication
 const users = await api.get<User[]>('/users');
 const newUser = await api.post<User>('/users', userData);
-const filteredUsers = await api.filter<User, UserFilter>('/users/search', filterModel);
+const filteredUsers = await api.filter<User, UserFilter>(
+  '/users/search',
+  filterModel
+);
 
 // File upload
 const uploadResult = await api.upload<UploadResponse>('/upload', formData);
@@ -457,7 +477,7 @@ try {
 } catch (error) {
   handleServerErrors({
     errors: error.response.data.errors,
-    setError
+    setError,
   });
 }
 ```
@@ -465,12 +485,12 @@ try {
 ### Data Transformation
 
 ```tsx
-import { 
-  flattenObjectKeys, 
+import {
+  flattenObjectKeys,
   readValueAsDate,
   propertyExists,
   removeLeadingTrailingSlashes,
-  getTimezone
+  getTimezone,
 } from '@gnwebsoft/ui/utils';
 
 // Flatten nested objects
@@ -496,6 +516,7 @@ const timezone = getTimezone();
 ```
 
 **Available Utilities:**
+
 - `api` / `api2` - HTTP clients with authentication
 - `handleServerErrors` - Form error mapping
 - `flattenObjectKeys` - Nested object flattening
@@ -528,9 +549,7 @@ const theme = createTheme({
 
 function App() {
   return (
-    <ThemeProvider theme={theme}>
-      {/* Your app components */}
-    </ThemeProvider>
+    <ThemeProvider theme={theme}>{/* Your app components */}</ThemeProvider>
   );
 }
 ```
@@ -546,16 +565,16 @@ import { AsyncSelect } from '@gnwebsoft/ui/wrappers';
   control={control}
   name="assignee"
   label="Assign to User"
-  loadOptions={async (searchValue) => {
+  loadOptions={async searchValue => {
     const response = await api.get(`/users/search?q=${searchValue}`);
     return response.data.map(user => ({
       value: user.id,
-      label: `${user.name} (${user.email})`
+      label: `${user.name} (${user.email})`,
     }));
   }}
   placeholder="Search users..."
   noOptionsText="No users found"
-/>
+/>;
 ```
 
 ### Cascade Selects
@@ -573,11 +592,11 @@ import { SelectCascadeElement } from '@gnwebsoft/ui/wrappers';
       label: 'United States',
       children: [
         { value: 'ny', label: 'New York' },
-        { value: 'ca', label: 'California' }
-      ]
-    }
+        { value: 'ca', label: 'California' },
+      ],
+    },
   ]}
-/>
+/>;
 ```
 
 ## Testing
@@ -594,7 +613,7 @@ test('renders button with loading state', () => {
       Submit
     </SimpleButton>
   );
-  
+
   expect(screen.getByText('Loading...')).toBeInTheDocument();
   expect(screen.getByRole('button')).toBeDisabled();
 });
@@ -613,6 +632,7 @@ test('renders button with loading state', () => {
 Comprehensive documentation is available for all components and utilities:
 
 ### 📚 Complete Documentation
+
 - **[Component Documentation](./docs/COMPONENT_DOCUMENTATION.md)** - Detailed guide for all components
 - **[Components](./docs/components/README.md)** - UI Components documentation
 - **[Form Wrappers](./docs/wrappers/README.md)** - Form wrapper components documentation
@@ -621,12 +641,15 @@ Comprehensive documentation is available for all components and utilities:
 - **[Types](./docs/types/README.md)** - TypeScript types documentation
 
 ### 🎯 Quick References
+
 - **[Getting Started Guide](./docs/guides/getting-started.md)** - Setup and basic usage
 - **[Forms Guide](./docs/guides/forms.md)** - Form handling patterns
 - **[API Documentation](./docs/api/README.md)** - Generated API docs
 
 ### 📖 Examples
+
 Each component includes:
+
 - ✅ Basic usage examples
 - ✅ Advanced configuration options
 - ✅ TypeScript integration examples
@@ -657,6 +680,7 @@ pnpm run check-exports
 ```
 
 ### Development Workflow
+
 The package supports instant development with hot module reloading:
 
 ```bash
@@ -685,4 +709,4 @@ See [CHANGELOG.md](./CHANGELOG.md) for release history.
 
 ---
 
-**Made with ❤️ by GNWebsoft Team**
+**Made with ❤️ by GNWebsoft Team**