sevatech-library 1.0.0

package/README.md

@@ -0,0 +1,655 @@
+# SevagoTech Library
+
+[![npm version](https://badge.fury.io/js/sevagotech-library.svg)](https://badge.fury.io/js/sevagotech-library)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+A comprehensive, production-ready React component library built with TypeScript, Material-UI, and modern development practices. Designed for scalable web applications with a focus on developer experience, accessibility, and performance.
+
+## ✨ Features
+
+- **TypeScript First**: Full TypeScript support with comprehensive type definitions
+- **Material-UI Integration**: Built on Material-UI v5 with enhanced theming capabilities
+- **Accessible**: WCAG 2.1 compliant components with keyboard navigation and screen reader support
+- **Responsive**: Mobile-first design with responsive breakpoints
+- **Customizable**: Extensive theming and styling options via Material-UI's sx prop
+- **Tree-Shakable**: Optimized bundle size with ES modules and Rollup
+- **Well-Documented**: Comprehensive documentation with live examples
+
+## 📦 Installation
+
+```bash
+npm install sevagotech-library
+```
+
+or
+
+```bash
+yarn add sevagotech-library
+```
+
+### Peer Dependencies
+
+Ensure you have the following peer dependencies installed:
+
+```json
+{
+  "react": "^18.0.0",
+  "react-dom": "^18.0.0",
+  "@mui/material": "^5.14.0",
+  "@emotion/react": "^11.11.0",
+  "@emotion/styled": "^11.11.0"
+}
+```
+
+## 🚀 Quick Start
+
+```tsx
+import React, { useState } from 'react';
+import { ButtonComponent, TextFieldComponent, ModalComponent } from 'sevagotech-library';
+
+function App() {
+  const [email, setEmail] = useState('');
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <TextFieldComponent
+        label="Email Address"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="Enter your email"
+        fullWidth
+      />
+
+      <ButtonComponent
+        variant="solid"
+        color="brand"
+        onClick={() => setIsOpen(true)}
+        sx={{ marginTop: 2 }}
+      >
+        Open Modal
+      </ButtonComponent>
+
+      <ModalComponent
+        open={isOpen}
+        onClose={() => setIsOpen(false)}
+        title="Welcome to SevagoTech Library"
+        buttonRight={{
+          children: 'Get Started',
+          onClick: () => setIsOpen(false)
+        }}
+      >
+        <p>Start building amazing user interfaces with our comprehensive component library.</p>
+      </ModalComponent>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## 📚 Components
+
+### Form Components
+
+#### Button Component
+
+A versatile button component supporting multiple variants, colors, sizes, and icon integration.
+
+```tsx
+import { ButtonComponent } from 'sevagotech-library';
+
+// Basic usage
+<ButtonComponent variant="solid" color="brand" onClick={handleClick}>
+  Click Me
+</ButtonComponent>
+
+// With icons
+<ButtonComponent variant="outline" prefixIcon="add" suffixIcon="arrow_forward">
+  Add Item
+</ButtonComponent>
+```
+
+**Props:**
+- `variant`: `'solid' | 'outline' | 'ghost' | 'text'`
+- `color`: `'brand' | 'neutral' | 'success' | 'error' | 'warning' | 'info'`
+- `size`: `'sm' | 'md' | 'lg'`
+- `prefixIcon`: Icon name for left side
+- `suffixIcon`: Icon name for right side
+- `loading`: Boolean for loading state
+- `disabled`: Boolean to disable interaction
+
+#### Text Field Component
+
+Advanced input field with validation states, icons, and accessibility features.
+
+```tsx
+import { TextFieldComponent } from 'sevagotech-library';
+
+const [value, setValue] = useState('');
+
+<TextFieldComponent
+  label="Email Address"
+  placeholder="Enter your email"
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  error={!isValidEmail(value)}
+  errorMessage="Please enter a valid email address"
+  success={isValidEmail(value) && value.length > 0}
+  successMessage="Email address is valid"
+  fullWidth
+/>
+```
+
+**Props:**
+- `label`: Input label text
+- `placeholder`: Placeholder text
+- `value`: Controlled value
+- `onChange`: Change handler
+- `error`: Boolean for error state
+- `errorMessage`: Error message text
+- `success`: Boolean for success state
+- `successMessage`: Success message text
+- `disabled`: Boolean to disable input
+- `fullWidth`: Boolean for full width
+
+#### Text Area Component
+
+Multi-line text input with customizable rows and validation.
+
+```tsx
+import { TextAreaComponent } from 'sevagotech-library';
+
+const [description, setDescription] = useState('');
+
+<TextAreaComponent
+  label="Description"
+  placeholder="Enter detailed description..."
+  value={description}
+  onChange={(e) => setDescription(e.target.value)}
+  rows={4}
+  fullWidth
+/>
+```
+
+#### Checkbox Component
+
+Custom-styled checkbox with label support.
+
+```tsx
+import { CheckboxComponent } from 'sevagotech-library';
+
+const [agreed, setAgreed] = useState(false);
+
+<CheckboxComponent
+  label="I agree to the Terms and Conditions"
+  checked={agreed}
+  onChange={(e) => setAgreed(e.target.checked)}
+/>
+```
+
+#### Switch Component
+
+Toggle switch with smooth animations.
+
+```tsx
+import { SwitchComponent } from 'sevagotech-library';
+
+const [notifications, setNotifications] = useState(true);
+
+<SwitchComponent
+  label="Enable notifications"
+  checked={notifications}
+  onChange={(e) => setNotifications(e.target.checked)}
+/>
+```
+
+#### Dropdown Field Component
+
+Select dropdown with search and multi-select capabilities.
+
+```tsx
+import { DropdownFieldComponent } from 'sevagotech-library';
+
+const options = [
+  { label: 'Option 1', value: '1' },
+  { label: 'Option 2', value: '2' },
+  { label: 'Option 3', value: '3' }
+];
+
+<DropdownFieldComponent
+  label="Select Option"
+  options={options}
+  value={selectedValue}
+  onChange={setSelectedValue}
+  searchable
+/>
+```
+
+#### Search Field Component
+
+Debounced search input with clear functionality.
+
+```tsx
+import { SearchFieldComponent } from 'sevagotech-library';
+
+const [searchTerm, setSearchTerm] = useState('');
+
+<SearchFieldComponent
+  placeholder="Search..."
+  value={searchTerm}
+  onChange={(e) => setSearchTerm(e.target.value)}
+  onSearch={(term) => performSearch(term)}
+  debounceMs={300}
+/>
+```
+
+#### Date Field Component
+
+Date picker with customizable format and locale support.
+
+```tsx
+import { DateFieldComponent } from 'sevagotech-library';
+import dayjs from 'dayjs';
+
+const [selectedDate, setSelectedDate] = useState(dayjs());
+
+<DateFieldComponent
+  label="Select Date"
+  value={selectedDate}
+  onChange={(date) => setSelectedDate(date)}
+  format="DD/MM/YYYY"
+/>
+```
+
+#### Money Field Component
+
+Currency input with automatic formatting.
+
+```tsx
+import { MoneyFieldComponent } from 'sevagotech-library';
+
+const [price, setPrice] = useState('');
+
+<MoneyFieldComponent
+  label="Price"
+  value={price}
+  onChange={setPrice}
+  currency="USD"
+  locale="en-US"
+/>
+```
+
+### Layout Components
+
+#### Modal Component
+
+Flexible modal dialog with customizable actions and content.
+
+```tsx
+import { ModalComponent } from 'sevagotech-library';
+
+<ModalComponent
+  open={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="Confirm Action"
+  buttonLeft={{ children: 'Cancel' }}
+  buttonRight={{
+    children: 'Confirm',
+    color: 'brand',
+    onClick: handleConfirm
+  }}
+>
+  <p>Are you sure you want to proceed with this action?</p>
+</ModalComponent>
+```
+
+#### Tabs Component
+
+Animated tabbed interface with icon support.
+
+```tsx
+import { TabsComponent } from 'sevagotech-library';
+
+const tabs = [
+  { id: 'tab1', name: 'Home', icon: 'home' },
+  { id: 'tab2', name: 'Settings', icon: 'settings' },
+  { id: 'tab3', name: 'Info', icon: 'info' }
+];
+
+<TabsComponent
+  tabs={tabs}
+  idSelect={activeTab}
+  onChange={setActiveTab}
+/>
+```
+
+#### Grid Component
+
+Responsive grid system based on Material-UI's Grid.
+
+```tsx
+import { Grid } from 'sevagotech-library';
+
+<Grid container spacing={2}>
+  <Grid item xs={12} sm={6} md={4}>
+    <div>Column 1</div>
+  </Grid>
+  <Grid item xs={12} sm={6} md={4}>
+    <div>Column 2</div>
+  </Grid>
+  <Grid item xs={12} sm={6} md={4}>
+    <div>Column 3</div>
+  </Grid>
+</Grid>
+```
+
+### Data Display Components
+
+#### Avatar Component
+
+User avatar with image and fallback support.
+
+```tsx
+import { AvatarComponent } from 'sevagotech-library';
+
+<AvatarComponent
+  url="https://example.com/avatar.jpg"
+  size="md"
+  border
+/>
+
+<AvatarComponent
+  name="John Doe"
+  size="lg"
+  color="brand"
+/>
+```
+
+#### Avatar Group Component
+
+Grouped avatars with overflow indicators.
+
+```tsx
+import { AvatarGroupComponent } from 'sevagotech-library';
+
+const avatars = [
+  { id: '1', url: 'avatar1.jpg', name: 'User 1' },
+  { id: '2', url: 'avatar2.jpg', name: 'User 2' },
+  { id: '3', url: 'avatar3.jpg', name: 'User 3' }
+];
+
+<AvatarGroupComponent
+  avatars={avatars}
+  maxDisplay={3}
+/>
+```
+
+#### Chip Component
+
+Compact information display with optional delete action.
+
+```tsx
+import { ChipComponent } from 'sevagotech-library';
+
+<ChipComponent label="New" color="success" />
+<ChipComponent label="Important" color="error" variant="outlined" />
+<ChipComponent
+  label="Removable"
+  onDelete={() => handleDelete()}
+/>
+```
+
+#### Typography Component
+
+Text styling with semantic variants.
+
+```tsx
+import { TypographyComponent } from 'sevagotech-library';
+
+<TypographyComponent variant="h1">Main Heading</TypographyComponent>
+<TypographyComponent variant="body1">
+  Regular body text with <strong>bold</strong> and <em>italic</em> formatting.
+</TypographyComponent>
+<TypographyComponent variant="caption" color="text.secondary">
+  Caption text
+</TypographyComponent>
+```
+
+### Navigation Components
+
+#### BreadCumbs Component
+
+Breadcrumb navigation with customizable separators.
+
+```tsx
+import { BreadCumbsComponent } from 'sevagotech-library';
+
+const breadcrumbs = [
+  { label: 'Home', href: '/' },
+  { label: 'Products', href: '/products' },
+  { label: 'Category', href: '/products/category' }
+];
+
+<BreadCumbsComponent items={breadcrumbs} />
+```
+
+#### Link Element
+
+Styled navigation link with external link support.
+
+```tsx
+import { LinkElement } from 'sevagotech-library';
+
+<LinkElement href="/dashboard">Go to Dashboard</LinkElement>
+<LinkElement href="https://example.com" external>
+  External Link
+</LinkElement>
+```
+
+### Utility Components
+
+#### Icon Element
+
+Material Icons integration with size and color options.
+
+```tsx
+import { IconElement } from 'sevagotech-library';
+
+<IconElement icon="home" />
+<IconElement icon="search" size="large" />
+<IconElement icon="favorite" sx={{ color: 'red' }} />
+```
+
+#### Image Element
+
+Optimized image component with lazy loading and fallbacks.
+
+```tsx
+import { ImageElement } from 'sevagotech-library';
+
+<ImageElement
+  url="https://example.com/image.jpg"
+  alt="Example image"
+  sx={{ borderRadius: 2, width: 200, height: 150 }}
+/>
+```
+
+#### Uploader Component
+
+File upload with drag-and-drop and progress tracking.
+
+```tsx
+import { UploaderComponent } from 'sevagotech-library';
+
+<UploaderComponent
+  onFilesSelected={(files) => {
+    console.log('Selected files:', files);
+  }}
+  accept=".jpg,.png,.pdf"
+  maxSize={5 * 1024 * 1024} // 5MB
+/>
+```
+
+## 🛠️ Development
+
+### Prerequisites
+
+- Node.js 18.0.0 or higher
+- npm 8.0.0 or higher (or yarn 1.22.0+)
+
+### Setup
+
+1. Clone the repository:
+```bash
+git clone https://github.com/your-username/sevagotech-library.git
+cd sevagotech-library
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+### Available Scripts
+
+```bash
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Run tests
+npm run test
+
+# Run linting
+npm run lint
+
+# Generate TypeScript declarations
+npm run types
+```
+
+### Component Development Guidelines
+
+1. **TypeScript**: All components must be written in TypeScript with proper type definitions
+2. **Accessibility**: Follow WCAG 2.1 guidelines and use semantic HTML
+3. **Responsive Design**: Ensure components work across all device sizes
+4. **Material-UI Integration**: Leverage Material-UI's theming and styling system
+5. **Performance**: Optimize for bundle size and runtime performance
+6. **Testing**: Include unit tests for all components
+7. **Documentation**: Maintain up-to-date documentation and examples
+
+## 🎨 Theming
+
+SevagoTech Library uses Material-UI's powerful theming system. Customize the theme to match your brand:
+
+```tsx
+import React from 'react';
+import { ThemeProvider, createTheme } from '@mui/material';
+import { ButtonComponent } from 'sevagotech-library';
+
+const theme = createTheme({
+  palette: {
+    primary: {
+      main: '#1976d2',
+    },
+    secondary: {
+      main: '#dc004e',
+    },
+    brand: {
+      main: '#your-brand-color',
+    },
+  },
+  typography: {
+    fontFamily: '"Inter", "Roboto", "Helvetica", "Arial", sans-serif',
+    h1: {
+      fontSize: '2.5rem',
+      fontWeight: 700,
+    },
+  },
+  shape: {
+    borderRadius: 8,
+  },
+});
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <ButtonComponent variant="solid" color="brand">
+        Themed Button
+      </ButtonComponent>
+    </ThemeProvider>
+  );
+}
+```
+
+### Custom Theme Colors
+
+Extend the palette with custom colors:
+
+```tsx
+const theme = createTheme({
+  palette: {
+    brand: {
+      main: '#your-brand-color',
+      light: '#lighter-shade',
+      dark: '#darker-shade',
+      contrastText: '#ffffff',
+    },
+  },
+});
+```
+
+## 📖 API Reference
+
+### Common Props
+
+All components support these standard props:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `sx` | `SxProps<Theme>` | Material-UI sx prop for custom styling |
+| `className` | `string` | CSS class name |
+| `style` | `React.CSSProperties` | Inline styles object |
+| `disabled` | `boolean` | Disable component interaction |
+| `loading` | `boolean` | Show loading state |
+
+### Component-Specific Props
+
+Refer to individual component documentation above for detailed prop tables.
+
+## 🤝 Contributing
+
+We welcome contributions! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes and add tests
+4. Ensure all tests pass: `npm run test`
+5. Commit your changes: `git commit -m 'Add amazing feature'`
+6. Push to the branch: `git push origin feature/amazing-feature`
+7. Open a Pull Request
+
+### Development Workflow
+
+- Follow the existing code style and conventions
+- Write comprehensive tests for new features
+- Update documentation for any API changes
+- Ensure TypeScript compilation passes
+- Test components across different browsers and devices
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 📞 Support
+
+- 📧 Email: 
+- 🐛 Issues: [GitHub Issues](https://github.com/your-username/sevagotech-library/issues)
+- 📚 Documentation: [Full Documentation](https://github.com/golden-lotus-core-web/sevatech-library)
+
+---
+
+Built with ❤️ by the SevaTech team