Generic JSON Component Library

A comprehensive React component library that allows you to build forms, modals, tables, and buttons using JSON configuration. Built with TypeScript, Tailwind CSS v4, Formik, and Yup for maximum flexibility and type safety.

Features

• 🎨 JSON-Configurable Components: Build complex UIs using simple JSON objects
• 🏭 Factory Pattern: Dynamic form field rendering based on configuration
• 📱 Responsive Design: Mobile-first approach with Tailwind CSS
• 🔧 TypeScript Support: Full type safety and IntelliSense
• 🎯 Form Validation: Built-in Yup integration for robust validation
• 📊 Data Tables: Advanced sorting, filtering, and pagination
• 🪟 Modal Variants: Standard, fullscreen, confirmation, and drawer modals
• 🎨 Customizable Styling: Override default styles via JSON configuration
• 🚀 Performance Optimized: React.memo and efficient re-rendering

Installation

# Using Bun (recommended)
bun add generic-json

# Using npm
npm install generic-json

# Using yarn
yarn add generic-json

Peer Dependencies

Make sure you have these dependencies installed:

bun add react react-dom formik yup

Quick Start

Basic Usage

import { GenericComponent } from 'generic-json';

const formConfig = {
  type: 'form',
  config: {
    fields: [
      {
        name: 'email',
        type: 'email',
        label: 'Email Address',
        validation: { required: true, email: true }
      },
      {
        name: 'password',
        type: 'password',
        label: 'Password',
        validation: { required: true, minLength: 6 }
      }
    ],
    submitButton: {
      label: 'Sign In',
      variant: 'primary'
    },
    onSubmit: (values) => {
      console.log('Form submitted:', values);
    }
  }
};

function App() {
  return <GenericComponent config={formConfig} />;
}

Individual Components

import { 
  GenericForm, 
  GenericModal, 
  GenericTable, 
  GenericButton 
} from 'generic-json';

// Form
<GenericForm config={formConfig} />

// Modal
<GenericModal config={modalConfig} />

// Table
<GenericTable config={tableConfig} />

// Button
<GenericButton config={buttonConfig} />

Components

Forms

Build dynamic forms with validation using the factory pattern:

const formConfig = {
  fields: [
    {
      name: 'firstName',
      type: 'text',
      label: 'First Name',
      validation: { required: true }
    },
    {
      name: 'email',
      type: 'email',
      label: 'Email',
      validation: { required: true, email: true }
    },
    {
      name: 'country',
      type: 'select',
      label: 'Country',
      options: [
        { value: 'us', label: 'United States' },
        { value: 'ca', label: 'Canada' }
      ]
    },
    {
      name: 'newsletter',
      type: 'checkbox',
      label: 'Subscribe to newsletter'
    }
  ],
  submitButton: {
    label: 'Submit',
    variant: 'primary'
  },
  onSubmit: (values) => {
    console.log(values);
  }
};

Supported Field Types:

• text, email, password, number, tel, url
• textarea, select, checkbox, radio
• date, time, datetime-local, file, hidden
• image, video - File upload with preview and validation

File Upload Features:

• Image Input: Multiple image upload with thumbnails, drag & drop
• Video Input: Video upload with preview player, size validation
• File Input: General file upload with type icons and file info
• Validation: File size limits, type restrictions, max file count
• Preview: Visual previews for images and videos
• Drag & Drop: Intuitive file selection interface

File Upload Examples:

// Image Upload
{
  name: 'images',
  type: 'image',
  label: 'Upload Images',
  multiple: true,
  maxFiles: 5,
  maxFileSize: 5 * 1024 * 1024, // 5MB
  showPreview: true,
  previewSize: 'md'
}

// Video Upload
{
  name: 'videos',
  type: 'video',
  label: 'Upload Videos',
  multiple: true,
  maxFiles: 3,
  maxFileSize: 50 * 1024 * 1024, // 50MB
  showPreview: true,
  previewSize: 'md'
}

// File Upload
{
  name: 'documents',
  type: 'file',
  label: 'Upload Files',
  multiple: true,
  maxFiles: 10,
  maxFileSize: 10 * 1024 * 1024, // 10MB
  accept: '*/*'
}

Responsive Form Configuration:

// Responsive Grid Form
{
  layout: 'grid',
  columns: {
    xs: '1',    // 1 column on mobile
    sm: '2',    // 2 columns on small screens
    md: '3',    // 3 columns on medium screens
    lg: '2',    // 2 columns on large screens
    xl: '3'     // 3 columns on extra large screens
  },
  gap: {
    xs: '2',    // Small gap on mobile
    sm: '3',    // Medium gap on small screens
    md: '4',    // Large gap on medium screens
    lg: '6'     // Extra large gap on large screens
  },
  fieldSize: {
    xs: 'full', // Full width on mobile
    sm: 'full', // Full width on small screens
    md: 'full', // Full width on medium screens
    lg: 'full'  // Full width on large screens
  }
}

// Compact Inline Form
{
  layout: 'inline',
  gap: {
    xs: '2',
    sm: '3',
    md: '4'
  },
  fieldSize: {
    xs: 'auto',
    sm: 'auto',
    md: 'auto'
  }
}

Layout Options:

• vertical: Stack fields vertically (default)
• horizontal: Side-by-side layout
• inline: Compact horizontal layout
• grid: CSS Grid with responsive columns

Responsive Breakpoints:

• xs: Mobile (0px+)
• sm: Small (640px+)
• md: Medium (768px+)
• lg: Large (1024px+)
• xl: Extra Large (1280px+)
• 2xl: 2X Large (1536px+)

Modals

Create different modal variants:

const modalConfig = {
  variant: 'standard', // 'standard' | 'fullscreen' | 'confirmation' | 'drawer'
  isOpen: true,
  onClose: () => setModalOpen(false),
  header: {
    title: 'Modal Title',
    subtitle: 'Modal subtitle'
  },
  content: <div>Modal content</div>,
  footer: {
    primaryButton: {
      label: 'Save',
      onClick: () => console.log('Saved')
    },
    cancelButton: {
      label: 'Cancel',
      onClick: () => setModalOpen(false)
    }
  }
};

Tables

Build data tables with sorting, filtering, and pagination:

const tableConfig = {
  columns: [
    {
      key: 'id',
      title: 'ID',
      sortable: true,
      width: '80px'
    },
    {
      key: 'name',
      title: 'Name',
      sortable: true,
      filterable: true,
      filterType: 'text'
    },
    {
      key: 'status',
      title: 'Status',
      filterable: true,
      filterType: 'select',
      filterOptions: [
        { value: 'Active', label: 'Active' },
        { value: 'Inactive', label: 'Inactive' }
      ],
      render: (value) => (
        <span className={`px-2 py-1 rounded ${
          value === 'Active' ? 'bg-green-100' : 'bg-red-100'
        }`}>
          {value}
        </span>
      )
    }
  ],
  data: tableData,
  dataMode: 'client', // 'client' | 'server'
  pagination: {
    current: 1,
    pageSize: 10,
    showSizeChanger: true,
    showTotal: (total, range) => `Showing ${range[0]}-${range[1]} of ${total} entries`
  }
};

Buttons

Create buttons with various styles and states:

const buttonConfig = {
  label: 'Click Me',
  variant: 'primary', // 'primary' | 'secondary' | 'danger' | 'success' | 'outline' | 'ghost' | 'link'
  size: 'md', // 'xs' | 'sm' | 'md' | 'lg' | 'xl'
  loading: false,
  disabled: false,
  icon: <PlusIcon />,
  iconPosition: 'left', // 'left' | 'right'
  onClick: () => console.log('Clicked')
};

Styling Customization

Override default styles using the styles property in your configuration:

const formConfig = {
  fields: [
    {
      name: 'email',
      type: 'email',
      label: 'Email',
      styles: {
        container: 'mb-6',
        label: 'text-lg font-bold text-blue-600',
        input: 'border-2 border-blue-300 rounded-lg px-4 py-2',
        error: 'text-red-500 font-semibold'
      }
    }
  ],
  styles: {
    container: 'max-w-lg mx-auto p-6 bg-white rounded-xl shadow-lg'
  }
};

TypeScript Support

The library provides full TypeScript support with exported types:

import { 
  FormConfig, 
  ModalConfig, 
  TableConfig, 
  ButtonConfig,
  GenericComponentConfig 
} from 'generic-json';

const config: FormConfig = {
  // Your form configuration
};

Advanced Usage

Server-Side Data Handling

For tables with server-side data:

const tableConfig = {
  dataMode: 'server',
  onSort: (sortConfig) => {
    // Handle server-side sorting
    fetchData({ sort: sortConfig });
  },
  onFilter: (filters) => {
    // Handle server-side filtering
    fetchData({ filters });
  },
  onPaginationChange: (page, pageSize) => {
    // Handle server-side pagination
    fetchData({ page, pageSize });
  }
};

Custom Validation

Add custom validation rules:

const formConfig = {
  fields: [
    {
      name: 'username',
      type: 'text',
      validation: {
        required: true,
        custom: (value) => {
          if (value.length < 3) {
            return 'Username must be at least 3 characters';
          }
          return undefined;
        }
      }
    }
  ]
};

API Reference

GenericComponent

The main component that renders different component types based on configuration.

interface GenericComponentProps {
  config: GenericComponentConfig;
  className?: string;
}

Form Components

• GenericForm: Main form component with Formik integration
• FormFactory: Factory component for rendering different input types
• Individual inputs: TextInput, SelectInput, CheckboxInput, etc.

Modal Components

• GenericModal: Main modal component with portal rendering
• Variants: StandardModal, FullscreenModal, ConfirmationModal, DrawerModal

Table Components

• GenericTable: Main table component
• TableHeader, TableBody, TablePagination: Sub-components
• Hooks: useTableSort, useTableFilter, useTablePagination

Button Components

• GenericButton: Configurable button component with variants and states

Development

Building the Library

# Build the library
bun run build:lib

# Development mode
bun run dev

Project Structure

src/
├── lib/                    # Library source code
│   ├── forms/             # Form components
│   ├── modals/            # Modal components
│   ├── tables/            # Table components
│   ├── buttons/           # Button components
│   └── index.ts           # Main exports
├── types/                  # TypeScript type definitions
└── App.tsx                # Playground/demo application

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For questions, issues, or feature requests, please open an issue on GitHub.