A production-ready, type-safe React component library with reusable templates for List Views and Forms. Built with TypeScript and SCSS, following enterprise architecture patterns.

Perfect for teams, interns, and new developers who need quick, standardized solutions for common UI patterns.

✨ Features

List View Template

📊 Data table with sorting and pagination
🔍 Advanced filtering with multiple filter types
✅ Checkbox selection (single/bulk)
📤 Export to CSV/Excel
📥 Import from file
🎬 Custom action buttons per row
🔧 API parameter mapping for different backends
📱 Fully responsive design

Form Template

📝 Multiple field types (text, email, textarea, select, checkbox, date, file, etc.)
✔️ Built-in validation with custom rules
🔄 API-powered dropdowns
📋 Field grouping into sections
👁️ Conditional field visibility
🔄 Auto-save functionality
🎯 Create/Edit mode detection
🎨 Customizable layouts (single/two/three column)

Architecture

⚙️ Centralized API Service - Single instance for all API calls
🎣 Custom Hooks - useListView, useForm, usePagination, useFilters, useApiCall
📦 Type-Safe - Full TypeScript support with strict types
🎨 SCSS Styling - Variables, mixins, and responsive utilities
🔄 No External UI Library - Pure React with minimal dependencies
👨‍💼 Enterprise-Ready - Battle-tested patterns from production

🚀 Quick Start

1. Installation

npm install

2. Run Development Server

npm run dev

3. Copy an Example

# Copy the customer list example
cp src/examples/CustomerListExample/CustomerList.tsx src/pages/MyList.tsx

# Or copy the product form example
cp src/examples/ProductFormExample/ProductForm.tsx src/pages/MyForm.tsx

4. Adapt to Your API

Update the controller, action, and apiParamMap to match your backend.

5. Test with Your Backend

npm run dev
# Navigate to your component

📖 Documentation

For Getting Started

CLAUDE_GUIDE.md - Context guide for Claude (if continuing in next session)
src/examples/README.md - Overview of all examples
src/examples/CustomerListExample/CustomerList.example.md - List View guide
src/examples/ProductFormExample/ProductForm.example.md - Form guide

For Deep Dives

ARCHITECTURE.md - Complete architecture documentation
src/types/ - TypeScript type definitions (self-documented)
src/services/api.service.ts - API service implementation
src/hooks/ - Custom hooks with JSDoc comments

💡 Usage Examples

List View (30 seconds)

import { ListViewTemplate } from '@/components';

const columns = [
  { key: 'id', label: 'ID', sortable: true },
  { key: 'name', label: 'Name', sortable: true },
  { key: 'email', label: 'Email' },
];

export function CustomersList() {
  return (
    <ListViewTemplate
      columns={columns}
      controller="customers"
      action="list"
      enableSort={true}
      enableFilter={true}
      enableExport={true}
      onEdit={(row) => navigate(`/edit/${row.id}`)}
    />
  );
}

Form (30 seconds)

import { FormTemplate } from '@/components';

const fields = [
  { name: 'name', label: 'Name', type: 'text', required: true },
  { name: 'email', label: 'Email', type: 'email', required: true },
];

const validationSchema = {
  name: (val) => !val ? 'Name required' : null,
  email: (val) => !val.includes('@') ? 'Invalid email' : null,
};

export function CustomerForm({ customerId }: { customerId?: string }) {
  return (
    <FormTemplate
      fields={fields}
      validationSchema={validationSchema}
      controller="customers"
      createAction="create"
      editAction="update"
      entityId={customerId}
      onSuccess={() => navigate('/customers')}
    />
  );
}

🏗️ Project Structure

React UI Template/
├── src/
│   ├── components/
│   │   ├── ListViewTemplate/     # Complete list view component
│   │   │   ├── components/       # Sub-components (DataTable, Toolbar, etc.)
│   │   │   └── ListViewTemplate.tsx
│   │   ├── FormTemplate/         # Complete form component
│   │   └── index.ts
│   ├── services/
│   │   ├── api.service.ts        # Centralized API client
│   │   ├── listView.service.ts   # List view business logic
│   │   ├── form.service.ts       # Form business logic
│   │   └── index.ts
│   ├── hooks/
│   │   ├── useApiCall.ts         # Generic API hook
│   │   ├── usePagination.ts      # Pagination logic
│   │   ├── useFilters.ts         # Filter management
│   │   ├── useForm.ts            # Form state management
│   │   ├── useListView.ts        # Complete list view hook
│   │   └── index.ts
│   ├── types/
│   │   ├── api.types.ts          # API types
│   │   ├── listView.types.ts     # List view types
│   │   ├── form.types.ts         # Form types
│   │   └── index.ts
│   ├── utils/
│   │   ├── validation.ts         # Validation utilities
│   │   ├── formatting.ts         # Format utilities
│   │   ├── fileHandlers.ts       # Import/Export utilities
│   │   └── index.ts
│   ├── styles/
│   │   ├── variables.scss        # SCSS variables
│   │   ├── mixins.scss           # SCSS mixins
│   │   └── index.scss            # Global styles
│   ├── examples/
│   │   ├── CustomerListExample/  # Complete list example
│   │   ├── ProductFormExample/   # Complete form example
│   │   └── README.md             # Examples guide
│   └── index.ts
├── README.md                     # This file
├── ARCHITECTURE.md               # Architecture guide
├── CLAUDE_GUIDE.md               # Claude session guide
├── package.json
├── tsconfig.json
├── vite.config.ts
└── .gitignore

🔄 Data Flow

User Interaction (Click, Type)
         ↓
Component (ListViewTemplate / FormTemplate)
         ↓
Custom Hook (useListView / useForm)
         ↓
Service Layer (listView.service / form.service)
         ↓
API Service (apiService.get/post/patch/delete)
         ↓
Backend API
         ↓
Response returned & Component updates

🛠️ Technology Stack

React 18.2.0 - UI framework
TypeScript 5.0.0 - Type safety
SCSS 1.69.0 - Styling
Vite 4.0.0 - Build tool

Zero dependencies on third-party UI libraries. All components built from scratch with React primitives.

📋 API Integration

Supported HTTP Methods

GET - Fetch data
POST - Create data
PATCH - Update data
DELETE - Delete data

Standard Response Format

{
  success: boolean,
  data?: any,
  error?: string,
  status: number
}

Customize API Parameters

<ListViewTemplate
  controller="myentity"
  action="list"
  apiParamMap={{
    pageParam: 'page',          // Your API's page parameter name
    pageSizeParam: 'limit',     // Your API's page size parameter name
    sortParam: 'sort_by',       // Your API's sort parameter name
    sortOrderParam: 'order',    // Your API's sort order parameter name
  }}
/>

🎨 Customization

Change Colors

Edit src/styles/variables.scss:

$color-primary: #007bff;
$color-success: #28a745;
$color-danger: #dc3545;

Change Spacing

$spacing-sm: 8px;
$spacing-md: 16px;
$spacing-lg: 24px;

Add Custom Styles

Create a .scss file in your component directory and import it.

✅ Best Practices

For List Views

✅ Always define rowKey if your data doesn't use id
✅ Make expensive columns filterable
✅ Set reasonable pageSizeOptions
✅ Provide clear emptyMessage
✅ Handle errors gracefully

For Forms

✅ Always validate required fields
✅ Use descriptive helperText
✅ Group related fields with section
✅ Use condition for conditional fields
✅ Test validation with edge cases

General

✅ Use TypeScript for type safety
✅ Add JSDoc comments to custom code
✅ Keep components focused and reusable
✅ Test with your actual backend API early
✅ Use SCSS variables for consistent styling

🧪 Testing

Coming soon! This template is designed for easy testing:

import { ListViewTemplate } from '@/components';
import { render, screen } from '@testing-library/react';

test('renders list with columns', () => {
  const columns = [{ key: 'id', label: 'ID' }];
  render(<ListViewTemplate columns={columns} controller="test" action="list" />);
  expect(screen.getByText('ID')).toBeInTheDocument();
});

📚 Learning Resources

New to React?

Read the examples first
Study the hooks implementation
Review the component structure

New to TypeScript?

Check the type definitions in src/types/
Use your IDE's intellisense
Refer to JSDoc comments

New to This Project?

Start with src/examples/README.md
Copy an example that matches your use case
Adapt it to your API

🐛 Troubleshooting

Data not loading?

Check controller and action match your API
Verify API response format is correct
Check browser console for errors
Test API manually (curl, Postman, etc.)

Filters not working?

Check filter field names match API parameters
Verify API is handling filter parameters
Test with single filter first

Validation not working?

Check validationSchema function returns error message string
Make sure field name matches schema key
Verify validation function is correct

Styling issues?

Import SCSS correctly
Check CSS specificity conflicts
Use browser DevTools to inspect styles

📝 License

This project is internal to Swaayam Infotech and follows internal guidelines.

👥 Contributing

Contributions welcome! Please:

Follow the established patterns
Add TypeScript types
Document with comments
Update examples if adding features

📞 Support

For questions or issues:

Check the examples first
Review the documentation
Examine the type definitions
Ask your team lead

🎯 Roadmap

Unit tests for all hooks
E2E tests with Cypress
Storybook integration
More examples (advanced patterns)
Animation utilities
Dark mode support
Accessibility (a11y) improvements
Performance optimizations

🚀 Quick Reference

Need	See
List View Example	`src/examples/CustomerListExample/`
Form Example	`src/examples/ProductFormExample/`
API Service	`src/services/api.service.ts`
Hooks	`src/hooks/`
Types	`src/types/`
Styling	`src/styles/`
Architecture	`ARCHITECTURE.md`

Built with ❤️ for interns and team members

Start with the examples. Copy. Adapt. Deploy. 🚀