Nakula Component

A comprehensive React component library with data-driven components including DataGrid, Tabs, DynamicForm, and AutoCompleteSelect. Built with TypeScript, Material-UI, and modern React patterns.

✨ All MUI dependencies auto-install! No need to manually install Material-UI packages.

Features

• 🚀 TypeScript First: Full TypeScript support with comprehensive type definitions
• 🎨 Material-UI Integration: Built on top of MUI components with consistent theming
• 📦 Batteries Included: MUI and all dependencies auto-install
• 📊 Data-Driven: Components designed for dynamic data with SWR integration
• 🔧 Highly Configurable: Extensive customization options for all components
• 📱 Responsive: Mobile-friendly components with responsive design
• ♿ Accessible: WCAG compliant with proper ARIA attributes
• 🧪 Well Tested: Comprehensive test coverage with Vitest and Testing Library

Installation

Single command - everything included!

npm install nakula-component
# or
yarn add nakula-component
# or
bun add nakula-component

What gets installed automatically:

• ✅ @mui/material
• ✅ @mui/x-data-grid
• ✅ @mui/x-date-pickers
• ✅ @emotion/react & @emotion/styled
• ✅ formik & yup
• ✅ swr

Required peer dependencies (must be in your project):

• React 18+ or 19+
• ReactDOM 18+ or 19+

Quick Start

import React from 'react';
import { DataGrid, MinimalTabs, DynamicForm, AutoCompleteSelect } from 'nakula-component';

// Basic DataGrid usage
function MyDataGrid() {
  return (
    <DataGrid
      endpoint="/api/users"
      cacheKey="users"
      columns={(refresh) => [
        { field: 'id', headerName: 'ID', width: 90 },
        { field: 'name', headerName: 'Name', width: 150 },
        { field: 'email', headerName: 'Email', width: 200 },
      ]}
    />
  );
}

// Basic DynamicForm usage
function MyForm() {
  const fields = [
    { name: 'name', label: 'Name', type: 'text', grid: 6 },
    { name: 'email', label: 'Email', type: 'email', grid: 6 },
  ];

  return (
    <DynamicForm
      fields={fields}
      initialValues={{ name: '', email: '' }}
      onSubmit={(values) => console.log(values)}
    />
  );
}

Components

DataGrid

Advanced data grid component with server-side pagination, filtering, sorting, and actions.

Key Features:

• Server-side pagination with SWR caching
• Advanced filtering system with multiple filter types
• Sortable columns with persistent state
• Action buttons with permission handling
• Row selection and bulk operations
• Responsive design with mobile optimization

Basic Usage:

<DataGrid
  endpoint="/api/data"
  cacheKey="my-data"
  columns={(refresh) => [
    { field: 'id', headerName: 'ID' },
    { field: 'name', headerName: 'Name' },
  ]}
  filterOptions={[
    { field: 'name', label: 'Name', type: 'text' },
    { field: 'status', label: 'Status', type: 'select', options: statusOptions },
  ]}
  tableButton={{
    type: 'dialog',
    title: 'Add New',
    component: AddDialog,
  }}
/>

MinimalTabs

Flexible tab component with dynamic configuration and conditional rendering.

Key Features:

• Dynamic tab configuration
• Icon support for each tab
• Conditional tab visibility
• Props passing to tab components
• Read-only mode support
• Responsive scrollable tabs

Basic Usage:

<MinimalTabs
  tabs={[
    {
      value: 'tab1',
      label: 'Tab 1',
      icon: <HomeIcon />,
      component: Tab1Component,
      props: { data: tab1Data },
    },
    {
      value: 'tab2',
      label: 'Tab 2',
      component: Tab2Component,
      hidden: !showTab2,
    },
  ]}
  defaultTab="tab1"
  onTabChange={(tabValue) => console.log('Tab changed:', tabValue)}
/>

DynamicForm

Powerful form builder with multiple field types, validation, and dynamic behavior.

Key Features:

• 10+ field types (text, select, autocomplete, date, boolean, etc.)
• Formik integration for form state management
• Yup validation schema support
• Section dividers for form organization
• Custom component support
• Auto-reset and callback handling
• Conditional field rendering

Basic Usage:

<DynamicForm
  fields={[
    { name: 'name', label: 'Full Name', type: 'text', grid: 6 },
    { name: 'email', label: 'Email', type: 'email', grid: 6 },
    { name: 'age', label: 'Age', type: 'number', grid: 4 },
    { name: 'country', label: 'Country', type: 'select', grid: 8, options: countries },
    { name: 'bio', label: 'Biography', type: 'textarea', grid: 12, rows: 4 },
    { name: 'newsletter', label: 'Subscribe to newsletter', type: 'boolean', grid: 12 },
  ]}
  initialValues={{
    name: '',
    email: '',
    age: '',
    country: '',
    bio: '',
    newsletter: false,
  }}
  validationSchema={yup.object({
    name: yup.string().required('Name is required'),
    email: yup.string().email('Invalid email').required('Email is required'),
    age: yup.number().min(18, 'Must be at least 18'),
  })}
  onSubmit={async (values) => {
    await submitForm(values);
  }}
  submitLabel="Create Account"
/>

AutoCompleteSelect

Server-side search autocomplete component with SWR caching and advanced features.

Key Features:

• Server-side search with debouncing
• SWR caching for performance optimization
• Fetch by ID for value prepopulation
• Support for returning objects or IDs
• Loading and error states
• Customizable search behavior

Basic Usage:

<AutoCompleteSelect
  value={selectedUserId}
  setValue={(value) => setSelectedUserId(value)}
  label="Select User"
  placeholder="Search users..."
  useOptions={(search) => useUserSearch(search)}
  useById={(id) => useUserById(id)}
  getOptionLabel={(user) => user.name}
  getOptionValue={(user) => user.id}
  returnObject={false}
  minSearchLength={2}
  debounceMs={300}
/>

Hooks and Utilities

The package also exports useful hooks and utilities:

Filter Hooks

import { 
  useFilterRegistry, 
  useGenericFilterOptions,
  textFilter,
  selectFilter,
  booleanFilter,
  autocompleteFilter 
} from 'nakula-component';

SWR Configuration

import { 
  masterConfig, 
  paginationConfig,
  generatePaginationKey,
  useSearchCache 
} from 'nakula-component';

Utility Functions

import { 
  formatNumber, 
  formatTime, 
  formatDate,
  validateEmail,
  debounce 
} from 'nakula-component';

TypeScript Support

All components come with comprehensive TypeScript definitions. The package exports all necessary types:

import type { 
  DataGridProps,
  MinimalTabsProps,
  DynamicFormProps,
  AutoCompleteSelectProps,
  FieldSchema,
  SelectOption,
  FilterColumnMeta 
} from 'nakula-component';

Theming and Customization

Components inherit from your MUI theme and can be customized using standard MUI theming approaches:

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

const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
    },
  },
  components: {
    // Customize Nakula components through MUI component overrides
    MuiDataGrid: {
      styleOverrides: {
        root: {
          border: 'none',
        },
      },
    },
  },
});

function App() {
  return (
    <ThemeProvider theme={theme}>
      {/* Your components */}
    </ThemeProvider>
  );
}

Migration Guide

From Individual Components

If you're migrating from individual component implementations:

1. Install the package and peer dependencies
2. Update imports from individual files to the package
3. Review prop changes - some props may have been renamed or restructured
4. Update type imports to use the centralized type definitions
5. Test thoroughly - while we maintain backward compatibility, some edge cases may behave differently

Breaking Changes

See CHANGELOG.md for detailed information about breaking changes between versions.

Examples

Check out the examples directory for complete working examples:

• Basic Usage: Simple component implementations
• Advanced Patterns: Complex use cases and customizations
• Integration Examples: How to integrate with different backends
• Theming Examples: Custom theme implementations

API Reference

For detailed API documentation, see:

• DataGrid API
• MinimalTabs API
• DynamicForm API
• AutoCompleteSelect API

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Start Storybook for component development
npm run storybook

# Build Storybook for production
npm run build-storybook

# Type checking
npm run type-check

# Linting
npm run lint

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Package Information

• NPM Package: nakula-component
• Version: 1.0.0
• Bundle Size: ~458 KB (ESM)
• TypeScript: Full support included
• License: MIT

Links

• 📦 NPM Package
• 📖 Documentation
• 🐛 Issue Tracker
• 💬 GitHub Repository

Author

Affan Abdullah

• Email: [email protected]
• GitHub: @AffanAbd97

License

MIT © Affan Abdullah

Made with ❤️ by Affan Abdullah