@gnwebsoft/ui

A comprehensive TypeScript library providing reusable React components and wrappers for MUI v7. Built for modern React applications with full TypeScript support, form integration, and accessibility features.


Features

- 🎨 MUI v7 Integration - Built on top of Material-UI components
- 📝 Form Controls - Comprehensive react-hook-form wrappers
- 🔍 TypeScript First - Full type safety and IntelliSense support
- 🌳 Tree Shakeable - Modular exports for optimal bundle size
- ♿ Accessible - WCAG compliant components
- 🎯 Modern React - Hooks, memo, forwardRef patterns
- 📱 Responsive - Mobile-first design approach

Installation

``bash
npm install @gnwebsoft/ui


or

yarn add @gnwebsoft/ui

or

pnpm add @gnwebsoft/ui
`

$3

This library requires the following peer dependencies:

`bash
npm install react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled react-hook-form @hookform/resolvers zod
`

Complete peer dependency list

`json
{
"@emotion/cache": "^11.14.0",
"@emotion/react": "^11.14.0",
"@emotion/styled": "^11.14.0",
"@hookform/resolvers": "^5.2.1",
"@mui/icons-material": "^7.3.1",
"@mui/lab": "^7.0.0-beta.16",
"@mui/material": "^7.3.1",
"@mui/x-data-grid": "^8.9.2",
"@mui/x-date-pickers": "^8.9.2",
"autosuggest-highlight": "^3.3.4",
"axios": "^1.11.0",
"dayjs": "^1.11.13",
"es-toolkit": "^1.39.8",
"lodash": "^4.17.21",
"react": "^19.1.1",
"react-dom": "^19.1.1",
"react-hook-form": "^7.62.0",
"typescript": "^5.9.2",
"zod": "^4.0.15",
"zustand": "^5.0.2"
}
`

Quick Start

`tsx
import React from 'react';
import { SimpleButton, LabelText } from '@gnwebsoft/ui';
import { ThemeProvider, createTheme } from '@mui/material/styles';

const theme = createTheme();

function App() {
return (



);
}

export default App;
`

Module Imports

For optimal bundle size, import from specific modules:

`tsx
// 🎯 Preferred - Tree-shakeable imports
import { SimpleButton } from '@gnwebsoft/ui/components';
import { TextFieldElement } from '@gnwebsoft/ui/wrappers';
import { useTransform } from '@gnwebsoft/ui/hooks';
import type { ApiResponse } from '@gnwebsoft/ui/types';
import { handleServerErrors } from '@gnwebsoft/ui/utils';

// 📦 Alternative - Root import (larger bundle)
import { SimpleButton, TextFieldElement } from '@gnwebsoft/ui';
`

$3

| 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

$3

#### SimpleButton

Enhanced MUI Button with loading states and conditional rendering.

`tsx
import { SimpleButton } from '@gnwebsoft/ui/components';

loading={isSubmitting}
loadingText="Saving..."
show={hasPermission}
variant="contained"
onClick={handleSubmit}
>
Save Changes
;
`

Features:

- Loading state with spinner
- Conditional rendering
- Automatic disabling during loading
- Custom loading text support
- Full TypeScript support

#### LabelText

Responsive label-value display component with grid layout and hover effects.

`tsx
import { LabelText } from '@gnwebsoft/ui/components';

label="Full Name"
value="John Doe"
gridSize={{
labelSize: { xs: 12, sm: 4, md: 3 },
valueSize: { xs: 12, sm: 8, md: 9 },
}}
/>;
`

Features:

- Responsive grid layout
- Hover effects with background color change
- Text overflow handling with ellipsis
- Tooltip on hover showing full value
- Customizable spacing and styling

#### AuthorizedView

Simple conditional rendering component based on a boolean show prop.

`tsx
import { AuthorizedView } from '@gnwebsoft/ui/components';



;
`

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';

isSubmitting={isLoading}
handleClear={() => reset()}
storeKey="userFormData" // Optional localStorage cleanup
/>

isSubmitting={isLoading}
handleCancel={() => navigate('/dashboard')}
/>

isSubmitting={isFiltering}
show={hasFilters}
title="Apply Filters"
icon={}
/>
`

$3

#### FormWrapper

Card-based container for forms with header, title, and action buttons.

`tsx
import { FormWrapper } from '@gnwebsoft/ui/components';

title="User Profile"
icon={}
actionButton={

Reset

}
>


;
`

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
import { FilterWrapper, ListWrapper, SimpleToolbar } from '@gnwebsoft/ui/components';












Add New
Export

`

Form Wrappers

All form wrappers integrate seamlessly with react-hook-form:

`tsx
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import {
TextFieldElement,
SelectElement,
DatePickerElement,
CheckboxElement,
} from '@gnwebsoft/ui/wrappers';

const schema = z.object({
name: z.string().min(1, 'Name is required'),
email: z.string().email('Invalid email'),
category: z.string(),
birthDate: z.date(),
subscribe: z.boolean(),
});

type FormData = z.infer;

function ContactForm() {
const { control, handleSubmit } = useForm({
resolver: zodResolver(schema),
});

return (


control={control}
name="name"
label="Full Name"
required
/>

control={control}
name="email"
label="Email"
type="email"
required
/>

control={control}
name="category"
label="Category"
options={[
{ value: 'general', label: 'General Inquiry' },
{ value: 'support', label: 'Support' },
]}
/>

control={control}
name="birthDate"
label="Birth Date"
/>

control={control}
name="subscribe"
label="Subscribe to newsletter"
/>

Submit

);
}

`

$3

| 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

$3

Transform values with memoization and change handling for form components.

`tsx
import { useTransform } from '@gnwebsoft/ui/hooks';

const { value, onChange } = useTransform({
value: formValue,
onChange: field.onChange,
transform: {
input: value => value?.toString() || '',
output: event => parseInt(event.target.value) || null,
},
});
`

Features:

- Memoized transformations for performance
- Input/output transformation support
- Change event handling
- TypeScript type safety
- Integration with form components

Common Use Cases:

- Number input formatting
- Date formatting
- Currency formatting
- Array to string conversion

Types

Comprehensive TypeScript interfaces for API integration and form handling:

`tsx
import type {
ApiResponse,
OperationResponse,
ValidationErrors,
OptionItem,
PostModel,
ListResponse,
} from '@gnwebsoft/ui/types';

// API response structure
const response: ApiResponse = {
status: 200,
data: users,
traceId: 'abc123',
};

// Form options
const options: OptionItem[] = [
{ Label: 'Option 1', Value: '1' },
{ Label: 'Option 2', Value: '2' },
];

// Paginated list response
const listResponse: ListResponse = {
Data: [
/ users /
],
Total: 150,
};

// Filter/search request
const filterRequest: PostModel = {
filterModel: { name: 'John' },
pageOffset: 0,
pageSize: 20,
sortField: 'name',
sortOrder: 'asc',
};
`

Available Types:

- ApiResponse - Standard API response structure
- ValidationErrors - Form validation errors
- OptionItem / OptionItem2 - Select options
- PostModel - Filter/pagination requests
- ListResponse - Paginated responses
- AsyncSelectPayload - Async select data

Utilities

$3

`tsx
import { api, handleServerErrors } from '@gnwebsoft/ui/utils';

// API calls with automatic authentication
const users = await api.get('/users');
const newUser = await api.post('/users', userData);
const filteredUsers = await api.filter(
'/users/search',
filterModel
);

// File upload
const uploadResult = await api.upload('/upload', formData);

// Form error handling
try {
await api.post('/submit', formData);
} catch (error) {
handleServerErrors({
errors: error.response.data.errors,
setError,
});
}
`

$3

`tsx
import {
flattenObjectKeys,
readValueAsDate,
propertyExists,
removeLeadingTrailingSlashes,
getTimezone,
} from '@gnwebsoft/ui/utils';

// Flatten nested objects
const flatData = flattenObjectKeys({ user: { name: 'John', age: 30 } });
// Result: { 'user.name': 'John', 'user.age': 30, 'user': {...} }

// Date conversion
const date = readValueAsDate('2023-12-25');
// Result: Date object or null

// Property checking
if (propertyExists(obj, 'user.address.street')) {
console.log(obj.user.address.street);
}

// URL cleaning
const cleanPath = removeLeadingTrailingSlashes('/api/users/');
// Result: 'api/users'

// Timezone info
const timezone = getTimezone();
// Result: 'America/New_York' or current timezone
`

Available Utilities:

- api / api2 - HTTP clients with authentication
- handleServerErrors - Form error mapping
- flattenObjectKeys - Nested object flattening
- readValueAsDate - Safe date conversion
- propertyExists - Type-safe property checking
- removeLeadingTrailingSlashes - URL path cleaning
- getTimezone - Timezone information
- schemaTools - Zod schema utilities

Styling and Theming

Components inherit MUI theme configuration:

`tsx
import { createTheme, ThemeProvider } from '@mui/material/styles';

const theme = createTheme({
palette: {
primary: {
main: '#1976d2',
},
secondary: {
main: '#dc004e',
},
},
typography: {
fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
},
});

function App() {
return (
{/ Your app components /}
);
}
`

Advanced Usage

$3

`tsx
import { AsyncSelect } from '@gnwebsoft/ui/wrappers';

control={control}
name="assignee"
label="Assign to User"
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}),
}));
}}
placeholder="Search users..."
noOptionsText="No users found"
/>;
`

$3

`tsx
import { SelectCascadeElement } from '@gnwebsoft/ui/wrappers';

control={control}
name="location"
label="Location"
options={[
{
value: 'us',
label: 'United States',
children: [
{ value: 'ny', label: 'New York' },
{ value: 'ca', label: 'California' },
],
},
]}
/>;
`

Testing

Components are built with testing in mind:

`tsx
import { render, screen } from '@testing-library/react';
import { SimpleButton } from '@gnwebsoft/ui/components';

test('renders button with loading state', () => {
render(

Submit

);

expect(screen.getByText('Loading...')).toBeInTheDocument();
expect(screen.getByRole('button')).toBeDisabled();
});
`

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Documentation

Comprehensive documentation is available for all components and utilities:

$3

- Component Documentation - Detailed guide for all components
- Components - UI Components documentation
- Form Wrappers - Form wrapper components documentation
- Hooks - Custom React hooks documentation
- Utilities - Utility functions documentation
- Types - TypeScript types documentation

$3

- Getting Started Guide - Setup and basic usage
- Forms Guide - Form handling patterns
- API Documentation - Generated API docs

$3

Each component includes:

- ✅ Basic usage examples
- ✅ Advanced configuration options
- ✅ TypeScript integration examples
- ✅ Testing patterns
- ✅ Accessibility guidelines
- ✅ Performance considerations

Development

`bash


Install dependencies

pnpm install

Start development mode with hot reload

pnpm dev

Run tests

pnpm test

Build library

pnpm build

Generate TypeScript documentation

pnpm docs:generate

Validate package exports

pnpm run check-exports
`

$3

The package supports instant development with hot module reloading:

`bash


Start both UI package and sample app

pnpm dev

Or start individually

pnpm run dev:ui # UI package in watch mode
pnpm run dev:web # Sample web app
``

Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

License

MIT © GNWebsoft Private Limited

Changelog

See CHANGELOG.md for release history.

---

Made with ❤️ by GNWebsoft Team