check-lib-cape

A comprehensive React library for building dynamic, type-safe forms with Material-UI components. Features advanced field types including autocomplete, date pickers, filter labels, and more.

🚀 Features

• 🎯 Dynamic Form Generation - Create forms from JSON configurations
• 🎨 Material-UI Integration - Built on top of MUI components
• 📝 Advanced Field Types - Autocomplete, date pickers, filter labels, and more
• 🔧 TypeScript Support - Fully typed with comprehensive type definitions
• 🎮 Form Control API - Programmatic reset and form management
• 📱 Responsive Design - Works seamlessly across devices
• 🧩 Extensible - Easy to customize and extend

📦 Installation

npm install check-lib-cape

Peer Dependencies

This library requires the following peer dependencies:

npm install @mui/material @emotion/react @emotion/styled @mui/icons-material @mui/lab @mui/x-date-pickers @date-io/date-fns date-fns react react-dom react-hook-form

Or install everything at once:

npm install check-lib-cape @mui/material @emotion/react @emotion/styled @mui/icons-material @mui/lab @mui/x-date-pickers @date-io/date-fns date-fns react react-dom react-hook-form

🎯 Quick Start

import React from 'react';
import { DynamicFilter } from 'check-lib-cape';

const MyForm = () => {
  const fields = [
    {
      name: 'name',
      type: 'text',
      label: 'Full Name',
      placeholder: 'Enter your name',
      required: true
    },
    {
      name: 'email',
      type: 'text',
      label: 'Email',
      placeholder: 'Enter your email',
      required: true
    },
    {
      name: 'skills',
      type: 'autocomplete',
      label: 'Skills',
      multiple: true,
      options: [
        { value: 'react', label: 'React' },
        { value: 'typescript', label: 'TypeScript' },
        { value: 'nodejs', label: 'Node.js' }
      ]
    }
  ];

  const handleSubmit = (data) => {
    console.log('Form data:', data);
  };

  return (
    <DynamicFilter
      fields={fields}
      onSubmit={handleSubmit}
      showSubmitButton={true}
    />
  );
};

🎨 Field Types

Text Field

{
  name: 'firstName',
  type: 'text',
  label: 'First Name',
  placeholder: 'Enter your first name',
  required: true
}

Number Field

{
  name: 'age',
  type: 'number',
  label: 'Age',
  placeholder: 'Enter your age',
  min: 0,
  max: 120
}

Password Field

{
  name: 'password',
  type: 'password',
  label: 'Password',
  placeholder: 'Enter password',
  required: true
}

Select Field

{
  name: 'country',
  type: 'select',
  label: 'Country',
  options: [
    { value: 'us', label: 'United States' },
    { value: 'ca', label: 'Canada' },
    { value: 'uk', label: 'United Kingdom' }
  ],
  required: true
}

Autocomplete Field

{
  name: 'technologies',
  type: 'autocomplete',
  label: 'Technologies',
  multiple: true,
  freeSolo: true,
  options: [
    { value: 'react', label: 'React' },
    { value: 'vue', label: 'Vue.js' },
    { value: 'angular', label: 'Angular' }
  ],
  filterSelectedOptions: true,
  limitTags: 3
}

Date Picker

{
  name: 'birthDate',
  type: 'date',
  label: 'Birth Date',
  required: true,
  disableFuture: true
}

Radio Field

{
  name: 'gender',
  type: 'radio',
  label: 'Gender',
  options: [
    { value: 'male', label: 'Male' },
    { value: 'female', label: 'Female' },
    { value: 'other', label: 'Other' }
  ],
  required: true
}

Checkbox Field

{
  name: 'terms',
  type: 'checkbox',
  label: 'I agree to the terms and conditions',
  required: true
}

Filter Labels

{
  name: 'categories',
  type: 'filterlabels',
  label: 'Categories',
  options: [
    { value: 'web', label: 'Web Development' },
    { value: 'mobile', label: 'Mobile Development' },
    { value: 'ai', label: 'Artificial Intelligence' }
  ],
  filterLabelsConfig: {
    direction: 'row',
    allowMultiple: true,
    exclusive: false,
    buttonHeight: 36,
    fontSize: 14
  }
}

🔧 Advanced Usage

Form Control with Refs

import React, { useRef } from 'react';
import { DynamicFilter, DynamicFilterRef } from 'check-lib-cape';

const AdvancedForm = () => {
  const formRef = useRef<DynamicFilterRef>(null);

  const resetForm = () => {
    formRef.current?.resetForm();
  };

  const loadData = () => {
    formRef.current?.resetForm({
      name: 'John Doe',
      email: '[email protected]',
      skills: ['react', 'typescript']
    });
  };

  return (
    <div>
      <DynamicFilter
        ref={formRef}
        fields={fields}
        onSubmit={handleSubmit}
      />
      <button onClick={resetForm}>Reset</button>
      <button onClick={loadData}>Load Sample Data</button>
    </div>
  );
};

Custom Layout

const fields = [
  {
    name: 'preferences',
    type: 'filterlabels',
    label: 'Preferences',
    options: preferences,
    filterLabelsConfig: {
      direction: 'column',
      gap: 2,
      wrap: false,
      allowMultiple: true,
      exclusive: false,
      buttonHeight: 40,
      fontSize: 14,
      textTransform: 'none',
      selectedOpacity: 1,
      unselectedOpacity: 0.6,
      hoverOpacity: 0.8,
      borderColor: '#1976d2'
    }
  }
];

Initial Data

const initialData = {
  name: 'Jane Smith',
  email: '[email protected]',
  skills: ['react', 'nodejs'],
  birthDate: new Date('1990-01-01')
};

<DynamicFilter
  fields={fields}
  initialData={initialData}
  onSubmit={handleSubmit}
/>

🎮 API Reference

DynamicFilter Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | fields | FieldConfig[] | - | Array of field configurations | | onSubmit | (data: Record<string, any>) => void | - | Form submission handler | | initialData | Record<string, any> | {} | Initial form data | | showSubmitButton | boolean | true | Show submit button | | showResetButton | boolean | false | Show reset button | | submitButtonText | string | "Submit" | Submit button text | | resetButtonText | string | "Reset" | Reset button text | | onReset | () => void | - | Reset handler |

DynamicFilterRef Methods

| Method | Type | Description | |--------|------|-------------| | resetForm | (data?: Record<string, any>) => void | Reset form (optionally with new data) |

Field Configuration

All fields share these common properties:

| Property | Type | Required | Description | |----------|------|----------|-------------| | name | string | ✅ | Field name (form key) | | type | FieldType | ✅ | Field type | | label | string | ✅ | Field label | | placeholder | string | ❌ | Placeholder text | | required | boolean | ❌ | Required field | | disabled | boolean | ❌ | Disabled state |

Field-specific properties vary by type. See individual field documentation above.

🛠️ TypeScript Support

The library is fully typed with TypeScript. Import types as needed:

import {
  DynamicFilterProps,
  DynamicFilterRef,
  FieldConfig,
  AutocompleteFieldConfig,
  FilterLabelsFieldConfig,
  DateFieldConfig
} from 'check-lib-cape';

🎨 Theming

The library uses Material-UI components and respects your MUI theme:

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

const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
    },
  },
});

<ThemeProvider theme={theme}>
  <DynamicFilter fields={fields} onSubmit={handleSubmit} />
</ThemeProvider>

📱 Responsive Design

All components are responsive by default. The FilterLabels component adapts to screen size automatically:

// Will stack vertically on mobile, horizontally on desktop
{
  name: 'filters',
  type: 'filterlabels',
  label: 'Filters',
  options: options,
  filterLabelsConfig: {
    direction: 'row',
    wrap: true  // Enables responsive wrapping
  }
}

🤝 Contributing

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

Development Setup

# Clone the repository
git clone [repository-url]
cd check-lib-cape

# Install dependencies
npm install

# Start development
npm run dev

# Build library
npm run build

# Run Storybook
npm run storybook

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🐛 Bug Reports & Feature Requests

Please use GitHub Issues to report bugs or request features.

📚 Examples

Check out our demo application for comprehensive examples and use cases.

🔄 Changelog

See CHANGELOG.md for a detailed history of changes.

Made with ❤️ by the check-lib-cape team