tp-react-elements-dev

A comprehensive React form library built with Material-UI and React Hook Form, designed for enterprise applications.

🚀 Features

• 🔄 Seamless Integration - Built on React Hook Form for performance and flexibility
• 🎨 Material Design - Consistent with Material-UI design system
• ✅ Robust Validation - Integrated with Yup for schema validation
• ♿ Accessibility First - WCAG compliant with proper ARIA attributes
• 📝 TypeScript Ready - Full type safety and IntelliSense support
• 📚 Rich Documentation - Comprehensive docs with Storybook
• 🧪 Well Tested - Extensive test coverage with React Testing Library

📋 Requirements

• Node.js: v18.17+ or v20.11+ (LTS recommended)
• React: v18.x or v19.x
• TypeScript: v5.x (recommended)

🔗 Supported Versions

| Package | Supported Versions | | ----------------- | ------------------ | | React | >=18 <20 | | React DOM | >=18 <20 | | React Hook Form | 7.x | | Material-UI | 7.x | | Material-UI Icons | 7.x | | Emotion React | 11.14.x | | Emotion Styled | 11.14.x |

📦 Installation

This library uses peer dependencies to avoid version conflicts and reduce bundle size. You need to install the required dependencies separately.

🚀 Quick Install (Recommended)

Install the library, then install only the core peer dependencies. Optional features (Rich Text, Session Timeout) can be added separately.

npm install tp-react-elements-dev
# installs only core peers (no rich text, no idle timer)
npx install-tp-form-deps

# if you need Rich Text Editor
npx install-tp-form-deps --with-richtext

# or install optional peers manually
npm install jodit@^4.6.2 jodit-react@^5.2.19

🔍 Optimized Imports

To reduce bundle size, you can import only the components you need using subpath imports:

// Import a specific component (top-level component folders only)
import { ModalField } from 'tp-react-elements-dev/components/ModalField';

// Import Form module shortcuts
import { RenderForm } from 'tp-react-elements-dev/form';

// Import utilities
import * as Utils from 'tp-react-elements-dev/utils';

See our Subpath Imports Guide for detailed instructions on optimizing your imports.

📋 Manual Installation

Step 1: Install Required Dependencies (Core)

npm install react@^19.1.1 react-dom@^19.1.1 \
  react-hook-form@^7.62.0 \
  @mui/material@^7.3.1 @mui/icons-material@^7.3.1 \
  @emotion/react@^11.14.0 @emotion/styled@^11.14.1 \
  @mui/x-date-pickers@^8.10.2 \
  @hookform/error-message@^2.0.1 @hookform/resolvers@^5.2.1 \
  date-fns@^4.1.0 dayjs@^1.11.13 \
  yup@^1.7.0 \
  crypto-js@^4.2.0 file-saver@^2.0.5 xlsx-js-style@^1.2.0

Step 2: Optional Dependencies

# Rich Text Editor (optional)
npm install jodit@^4.6.2 jodit-react@^5.2.19

# Session timeout (optional)
npm install react-idle-timer@^5.7.2

Step 3: Install the Library

npm install tp-react-elements-dev

🎯 Quick Start

import React from "react";
import { useForm } from "react-hook-form";
import { yupResolver } from "@hookform/resolvers/yup";
import * as yup from "yup";
import { Input } from "tp-react-elements-dev";
import { ThemeProvider, createTheme } from "@mui/material/styles";
import CssBaseline from "@mui/material/CssBaseline";

const schema = yup.object({
  email: yup.string().email().required(),
  password: yup.string().min(8).required(),
});

function LoginForm() {
  const { control, handleSubmit } = useForm({
    resolver: yupResolver(schema),
  });

  const onSubmit = (data) => {
    console.log(data);
  };

  return (
    <ThemeProvider theme={createTheme()}>
      <CssBaseline />
      <form onSubmit={handleSubmit(onSubmit)}>
        <Input
          name="email"
          control={control}
          label="Email Address"
          type="email"
          required
          fullWidth
        />
        <Input
          name="password"
          control={control}
          label="Password"
          type="password"
          required
          fullWidth
        />
        <button type="submit">Sign In</button>
      </form>
    </ThemeProvider>
  );
}

📋 Components

The library provides a comprehensive set of form components that integrate seamlessly with React Hook Form and Material-UI:

• Input - Text input fields with various types (text, email, password, etc.)
• Select - Single and multi-select dropdowns with autocomplete
• DatePicker - Calendar-based date selection
• TimePicker - Time selection with various formats
• FileUpload - File upload with preview and validation
• RichTextEditor - WYSIWYG editor for formatted text
• Checkbox - Single and group checkbox components
• RadioGroup - Radio button selection groups
• Switch - Toggle switches for boolean values
• Form - Container component with built-in validation

Refer to our Storybook documentation for detailed API documentation and examples.

🏗️ Best Practices for Code Structure and Organization

Component Organization

• Feature-Based Organization: Group related components together in feature-based directories for better organization.

  src/
    features/
      text-inputs/
      date-pickers/
      selects/
      file-uploads/

• Component Documentation: Add JSDoc comments to all components and functions, describing their purpose, props, and usage examples.

• Component Factories: Implement factory patterns for similar components to reduce code duplication.

  // Example of a component factory
  const createFormField = (FieldComponent) => {
    return ({ name, control, label, ...props }) => (
      <Controller
        name={name}
        control={control}
        render={({ field, fieldState }) => (
          <FieldComponent
            {...field}
            label={label}
            error={!!fieldState.error}
            helperText={fieldState.error?.message}
            {...props}
          />
        )}
      />
    );
  };

• Barrel Exports: Use barrel files (index.ts) to simplify imports for consumers.

• Naming Conventions: Adopt consistent naming conventions across the codebase (PascalCase for components, camelCase for utilities).

⚡ Performance Optimization

• Component Memoization: Use React.memo for complex components to prevent unnecessary re-renders.

  const MemoizedFormField = React.memo(FormField, (prevProps, nextProps) => {
    return prevProps.value === nextProps.value && prevProps.error === nextProps.error;
  });

• Code Splitting: Implement dynamic imports for larger components to reduce initial load time.

  // Use dynamic imports for complex components
  const RichTextEditor = React.lazy(() => import('./RichTextEditor'));

• Tree-Shaking Friendly Exports: Ensure all exports are compatible with tree-shaking.

• Debounced Validation: Implement debounced validation for fields with expensive validation operations.

  const debouncedValidate = useCallback(
    debounce((value) => validateField(value), 300),
    []
  );

• Virtual Rendering: For components that render large lists, implement virtualization to improve performance.

• Context Optimization: Split context providers to minimize re-renders when state changes.

  // Split form context into smaller, focused contexts
  const FormValuesContext = createContext({});
  const FormErrorsContext = createContext({});

📚 Documentation and Usability

• Interactive Examples: Enhance Storybook documentation with interactive examples for common use cases.

• Component Playground: Create an online playground for experimenting with components in real-time.

• Migration Guides: Provide comprehensive migration guides for major version updates.

• Enhanced Type Definitions: Improve TypeScript definitions with descriptive comments and examples.

  /**
   * Props for the Input component
   * @example
   * <Input
   *   name="email"
   *   control={control}
   *   label="Email Address"
   *   required
   * />
   */
  export interface InputProps {
    /** Field name in the form */
    name: string;
    /** Form control from useForm hook */
    control: Control<any>;
    // ... other props
  }

• Theme Customization Guide: Document how to customize the theme to match brand guidelines.

• Accessibility Documentation: Add specific documentation about accessibility features and how to maintain accessibility when customizing components.

• Performance Best Practices: Document performance considerations for using the library in large applications.

🔧 For Library Developers

If you're contributing to this library or setting up for development:

Development Setup

# Clone the repository
git clone https://github.com/your-office/form-elements.git
cd form-elements

# Install all dependencies (including devDependencies)
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build the library
npm run build

Dependency Structure

• peerDependencies: Required by library consumers, must be installed separately
• devDependencies: Required for development, testing, and building the library
• dependencies: Empty (following library best practices)

Why Peer Dependencies?

1. Avoid Version Conflicts: Prevents multiple versions of React, MUI, etc.
2. Smaller Bundle Size: No duplicate packages in consumer projects
3. Version Control: Users control which versions they use
4. Industry Standard: Same pattern used by MUI, React Hook Form, etc.

Reducing “Wide” Peer Dependencies

• Make non-core peers optional: Rich text (jodit, jodit-react) and session timeout (react-idle-timer) are optional and not installed by default via install-tp-form-deps.
• Feature subpackages (advanced): Move heavy features into dedicated entry points (e.g., tp-react-elements-dev/richtext) with their own peer sets.
• Thin wrappers (advanced): Provide adapters that lazy-load optional features so apps that don’t use them never import those packages.
• Clear installer flags: Use --with-richtext and --with-idle (or --all) to explicitly include optional peers only when needed.

📝 License

MIT