tp-react-elements-dev 1.12.23 → 1.12.25

package/README.md

@@ -1,4 +1,4 @@
-# tp-form-elements
+# tp-react-elements-dev
 
 A comprehensive React form library built with Material-UI and React Hook Form, designed for enterprise applications.
 
@@ -14,16 +14,16 @@ A comprehensive React form library built with Material-UI and React Hook Form, d
 
 ## 📋 Requirements
 
-- **Node.js**: v22.12.0 or higher (developed with v22.12.0)
-- **React**: v16.8.0 or higher
-- **TypeScript**: v4.5.0 or higher (optional but recommended)
+- **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             | 16.8.0 - 19.x      |
-| React DOM         | 16.8.0 - 19.x      |
+| React             | >=18 <20           |
+| React DOM         | >=18 <20           |
 | React Hook Form   | 7.x                |
 | Material-UI       | 7.x                |
 | Material-UI Icons | 7.x                |
@@ -36,105 +36,67 @@ This library uses **peer dependencies** to avoid version conflicts and reduce bu
 
 ### 🚀 Quick Install (Recommended)
 
-Install the library and run our helper script to install all peer dependencies:
+Install the library, then install only the core peer dependencies. Optional features (Rich Text, Session Timeout) can be added separately.
 
 ```bash
-npm install tp-form-elements
-npm run install-peers
-```
+npm install tp-react-elements-dev
+# installs only core peers (no rich text, no idle timer)
+npx install-tp-form-deps
 
-**Alternative:** Use our standalone installer:
+# if you need Rich Text Editor
+npx install-tp-form-deps --with-richtext
 
-```bash
-npm install tp-form-elements
-npx install-tp-form-deps
+# or install optional peers manually
+npm install jodit@^4.6.2 jodit-react@^5.2.19
 ```
 
-### 📋 Manual Installation
+## 🔍 Optimized Imports
 
-#### Step 1: Install Required Dependencies
+To reduce bundle size, you can import only the components you need using subpath imports:
 
-All of these are **mandatory** for the library to function:
+```js
+// Import a specific component (top-level component folders only)
+import { ModalField } from 'tp-react-elements-dev/components/ModalField';
 
-```bash
-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 jodit@^4.6.2 jodit-react@^5.2.19 yup@^1.7.0 crypto-js@^4.2.0 file-saver@^2.0.5 xlsx-js-style@^1.2.0
-```
+// Import Form module shortcuts
+import { RenderForm } from 'tp-react-elements-dev/form';
 
-#### Step 2: Install Optional Dependencies
-
-```bash
-# Only install if you need session timeout functionality
-npm install react-idle-timer@^5.7.2
+// Import utilities
+import * as Utils from 'tp-react-elements-dev/utils';
 ```
 
-#### Step 3: Install the Library
+See our [Subpath Imports Guide](./docs/subpath-imports.md) for detailed instructions on optimizing your imports.
 
-```bash
-npm install tp-form-elements
-```
+### 📋 Manual Installation
 
-### 🔄 All-in-One Installation
+#### Step 1: Install Required Dependencies (Core)
 
 ```bash
-npm install tp-form-elements 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 jodit@^4.6.2 jodit-react@^5.2.19 crypto-js@^4.2.0 file-saver@^2.0.5 xlsx-js-style@^1.2.0 yup@^1.7.0 react-idle-timer@^5.7.2
+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
 ```
 
-## 🔧 For Library Developers
-
-If you're contributing to this library or setting up for development:
-
-### Development Setup
+#### Step 2: Optional Dependencies
 
 ```bash
-# Clone the repository
-git clone https://github.com/your-office/form-elements.git
-cd form-elements
-
-# Install all dependencies (including devDependencies)
-npm install
+# Rich Text Editor (optional)
+npm install jodit@^4.6.2 jodit-react@^5.2.19
 
-# Start development server
-npm run dev
-
-# Run tests
-npm test
-
-# Build the library
-npm run build
+# Session timeout (optional)
+npm install react-idle-timer@^5.7.2
 ```
 
-### 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.
-
-### ⚠️ Known Issues & Future Improvements
-
-#### `DateRangePicker` Component Status
-
-- **Current Status**: DateRangePicker component temporarily disabled
-- **Reason**: Removed `mui-daterange-picker@1.0.5` due to React 18 compatibility issues
-- **Impact**: DateRangePicker component will show a placeholder message
-- **TODO**: Migrate to `@mui/x-date-pickers` DateRangePicker component for better React 18 support
-- **Timeline**: Migration planned for next major version
-
-**For Developers**: DateRangePicker will display a placeholder message until the migration is complete.
-
-### 🔄 Updating Dependencies
-
-When updating to a new version of the library:
+#### Step 3: Install the Library
 
 ```bash
-npm update tp-form-elements
-npm run install-peers  # Updates peer dependencies to compatible versions
+npm install tp-react-elements-dev
 ```
 
 ## 🎯 Quick Start
@@ -144,8 +106,8 @@ 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-form-elements";
-import { ThemeProvider } from "@mui/material/styles";
+import { Input } from "tp-react-elements-dev";
+import { ThemeProvider, createTheme } from "@mui/material/styles";
 import CssBaseline from "@mui/material/CssBaseline";
 
 const schema = yup.object({
@@ -163,7 +125,7 @@ function LoginForm() {
   };
 
   return (
-    <ThemeProvider theme={customTheme}>
+    <ThemeProvider theme={createTheme()}>
       <CssBaseline />
       <form onSubmit={handleSubmit(onSubmit)}>
         <Input
@@ -191,116 +153,183 @@ function LoginForm() {
 
 ## 📋 Components
 
-### Input
+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.
+
+  ```typescript
+  // 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}
+          />
+        )}
+      />
+    );
+  };
+  ```
 
-A versatile input component that handles text, email, password, number, and multiline inputs.
+- **Barrel Exports**: Use barrel files (index.ts) to simplify imports for consumers.
 
-```tsx
-<Input
-  name="email"
-  control={control}
-  label="Email Address"
-  type="email"
-  placeholder="your@email.com"
-  helpText="We'll never share your email"
-  required
-  fullWidth
-/>
-```
+- **Naming Conventions**: Adopt consistent naming conventions across the codebase (PascalCase for components, camelCase for utilities).
 
-**Props:**
+## ⚡ Performance Optimization
 
-- `name` - Field name for form registration
-- `control` - React Hook Form control object (optional for uncontrolled)
-- `label` - Input label
-- `type` - Input type (text, email, password, number, etc.)
-- `placeholder` - Placeholder text
-- `helpText` - Helper text shown below input
-- `required` - Whether field is required
-- `disabled` - Whether field is disabled
-- `multiline` - Render as textarea
-- `transform` - Transform function for input value
-- All Material-UI TextField props are supported
+- **Component Memoization**: Use React.memo for complex components to prevent unnecessary re-renders.
 
-## 🎨 Theming
+  ```typescript
+  const MemoizedFormField = React.memo(FormField, (prevProps, nextProps) => {
+    return prevProps.value === nextProps.value && prevProps.error === nextProps.error;
+  });
+  ```
 
-The library uses Material-UI's theming system. You can customize the appearance by providing your own theme:
+- **Code Splitting**: Implement dynamic imports for larger components to reduce initial load time.
 
-```tsx
-import { createTheme, ThemeProvider } from "@mui/material/styles";
-
-const customTheme = createTheme({
-  palette: {
-    primary: {
-      main: "#your-primary-color",
-    },
-  },
-});
+  ```typescript
+  // Use dynamic imports for complex components
+  const RichTextEditor = React.lazy(() => import('./RichTextEditor'));
+  ```
 
-function App() {
-  return (
-    <ThemeProvider theme={customTheme}>
-      {/* Your form components */}
-    </ThemeProvider>
+- **Tree-Shaking Friendly Exports**: Ensure all exports are compatible with tree-shaking.
+
+- **Debounced Validation**: Implement debounced validation for fields with expensive validation operations.
+
+  ```typescript
+  const debouncedValidate = useCallback(
+    debounce((value) => validateField(value), 300),
+    []
   );
-}
-```
+  ```
 
-## 🔨 Building
+- **Virtual Rendering**: For components that render large lists, implement virtualization to improve performance.
 
-The library supports multiple build formats for different environments:
+- **Context Optimization**: Split context providers to minimize re-renders when state changes.
 
-```bash
-# Build complete library (ESM + CJS + TypeScript declarations)
-npm run build:lib
+  ```typescript
+  // Split form context into smaller, focused contexts
+  const FormValuesContext = createContext({});
+  const FormErrorsContext = createContext({});
+  ```
 
-# Build specific formats
-npm run build:lib:esm    # ES Module build with TypeScript declarations
-npm run build:lib:cjs    # CommonJS build only
-npm run build:types      # Generate TypeScript declarations only
+## 📚 Documentation and Usability
 
-# Development builds
-npm run build            # Vite build for playground
-npm run dev              # Start development server
-```
+- **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.
 
-### Build Outputs
+- **Enhanced Type Definitions**: Improve TypeScript definitions with descriptive comments and examples.
 
-- **ESM Build** (`dist/index.esm.js`) - For modern bundlers (Vite, Webpack 5+, Rollup)
-- **CommonJS Build** (`dist/index.js`) - For legacy Node.js environments and older tools
-- **TypeScript Declarations** (`dist/index.d.ts`) - Full type definitions for TypeScript projects
-- **CSS Bundles** (`dist/index.esm.css`, `dist/index.css`) - Extracted styles for each format
+  ```typescript
+  /**
+   * 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
+  }
+  ```
 
-For detailed information about our TypeScript declaration setup, see `docs/typescript-declarations.md`.
+- **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:
 
-## 🧪 Testing
+### Development Setup
 
 ```bash
-npm test                 # Run tests
-npm run test:coverage    # Run with coverage
-npm run test:ui          # Run with UI
+# 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
 ```
 
-## 📖 Documentation
+### Dependency Structure
 
-- **Storybook**: Run `npm run storybook` for interactive component documentation
-- **TypeScript**: Full IntelliSense support in your IDE
-- **Playground**: Run `npm run dev` to explore components in the development environment
+- **`peerDependencies`**: Required by library consumers, must be installed separately
+- **`devDependencies`**: Required for development, testing, and building the library
+- **`dependencies`**: Empty (following library best practices)
 
-## 🤝 Contributing
+### Why Peer Dependencies?
 
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/new-component`
-3. Make your changes and add tests
-4. Run tests: `npm test`
-5. Submit a pull request
+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.
 
-## 📄 License
+### Reducing “Wide” Peer Dependencies
 
-MIT License - see LICENSE file for details.
+- 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.
 
-## 🆘 Support
+## 📝 License
 
-- Check our [Storybook documentation](https://your-storybook-url.com)
-- File issues on [GitHub](https://github.com/your-office/form-elements/issues)
-- Internal Slack: #form-library-support
+MIT