tp-react-elements 1.0.0

package/README.md

@@ -0,0 +1,335 @@
+# tp-react-elements
+
+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.
+
+```bash
+npm install tp-react-elements
+# 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:
+
+```js
+// Import a specific component (top-level component folders only)
+import { ModalField } from 'tp-react-elements/components/ModalField';
+
+// Import Form module shortcuts
+import { RenderForm } from 'tp-react-elements/form';
+
+// Import utilities
+import * as Utils from 'tp-react-elements/utils';
+```
+
+See our [Subpath Imports Guide](./docs/subpath-imports.md) for detailed instructions on optimizing your imports.
+
+### 📋 Manual Installation
+
+#### Step 1: Install Required Dependencies (Core)
+
+```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 \
+  yup@^1.7.0 \
+  crypto-js@^4.2.0 file-saver@^2.0.5 xlsx-js-style@^1.2.0
+```
+
+#### Step 2: Optional Dependencies
+
+```bash
+# 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
+
+```bash
+npm install tp-react-elements
+```
+
+## 🎯 Quick Start
+
+```tsx
+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";
+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.
+
+  ```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}
+          />
+        )}
+      />
+    );
+  };
+  ```
+
+- **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.
+
+  ```typescript
+  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.
+
+  ```typescript
+  // 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.
+
+  ```typescript
+  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.
+
+  ```typescript
+  // 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.
+
+  ```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
+  }
+  ```
+
+- **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
+
+```bash
+# 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/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

package/dist/_virtual/AMPMMidnightParser.esm.js

@@ -0,0 +1,3 @@
+var AMPMMidnightParser = {};
+
+export { AMPMMidnightParser as __exports };

package/dist/_virtual/AMPMParser.esm.js

@@ -0,0 +1,3 @@
+var AMPMParser = {};
+
+export { AMPMParser as __exports };

package/dist/_virtual/DateParser.esm.js

@@ -0,0 +1,3 @@
+var DateParser = {};
+
+export { DateParser as __exports };

package/dist/_virtual/DayOfYearParser.esm.js

@@ -0,0 +1,3 @@
+var DayOfYearParser = {};
+
+export { DayOfYearParser as __exports };

package/dist/_virtual/DayParser.esm.js

@@ -0,0 +1,3 @@
+var DayParser = {};
+
+export { DayParser as __exports };

package/dist/_virtual/DayPeriodParser.esm.js

@@ -0,0 +1,3 @@
+var DayPeriodParser = {};
+
+export { DayPeriodParser as __exports };

package/dist/_virtual/EraParser.esm.js

@@ -0,0 +1,3 @@
+var EraParser = {};
+
+export { EraParser as __exports };

package/dist/_virtual/ExtendedYearParser.esm.js

@@ -0,0 +1,3 @@
+var ExtendedYearParser = {};
+
+export { ExtendedYearParser as __exports };

package/dist/_virtual/FractionOfSecondParser.esm.js

@@ -0,0 +1,3 @@
+var FractionOfSecondParser = {};
+
+export { FractionOfSecondParser as __exports };

package/dist/_virtual/Hour0To11Parser.esm.js

@@ -0,0 +1,3 @@
+var Hour0To11Parser = {};
+
+export { Hour0To11Parser as __exports };

package/dist/_virtual/Hour0to23Parser.esm.js

@@ -0,0 +1,3 @@
+var Hour0to23Parser = {};
+
+export { Hour0to23Parser as __exports };

package/dist/_virtual/Hour1To24Parser.esm.js

@@ -0,0 +1,3 @@
+var Hour1To24Parser = {};
+
+export { Hour1To24Parser as __exports };

package/dist/_virtual/Hour1to12Parser.esm.js

@@ -0,0 +1,3 @@
+var Hour1to12Parser = {};
+
+export { Hour1to12Parser as __exports };

package/dist/_virtual/ISODayParser.esm.js

@@ -0,0 +1,3 @@
+var ISODayParser = {};
+
+export { ISODayParser as __exports };

package/dist/_virtual/ISOTimezoneParser.esm.js

@@ -0,0 +1,3 @@
+var ISOTimezoneParser = {};
+
+export { ISOTimezoneParser as __exports };

package/dist/_virtual/ISOTimezoneWithZParser.esm.js

@@ -0,0 +1,3 @@
+var ISOTimezoneWithZParser = {};
+
+export { ISOTimezoneWithZParser as __exports };

package/dist/_virtual/ISOWeekParser.esm.js

@@ -0,0 +1,3 @@
+var ISOWeekParser = {};
+
+export { ISOWeekParser as __exports };

package/dist/_virtual/ISOWeekYearParser.esm.js

@@ -0,0 +1,3 @@
+var ISOWeekYearParser = {};
+
+export { ISOWeekYearParser as __exports };

package/dist/_virtual/LocalDayParser.esm.js

@@ -0,0 +1,3 @@
+var LocalDayParser = {};
+
+export { LocalDayParser as __exports };

package/dist/_virtual/LocalWeekParser.esm.js

@@ -0,0 +1,3 @@
+var LocalWeekParser = {};
+
+export { LocalWeekParser as __exports };

package/dist/_virtual/LocalWeekYearParser.esm.js

@@ -0,0 +1,3 @@
+var LocalWeekYearParser = {};
+
+export { LocalWeekYearParser as __exports };

package/dist/_virtual/MinuteParser.esm.js

@@ -0,0 +1,3 @@
+var MinuteParser = {};
+
+export { MinuteParser as __exports };

package/dist/_virtual/MonthParser.esm.js

@@ -0,0 +1,3 @@
+var MonthParser = {};
+
+export { MonthParser as __exports };

package/dist/_virtual/Parser.esm.js

@@ -0,0 +1,3 @@
+var Parser = {};
+
+export { Parser as __exports };

package/dist/_virtual/QuarterParser.esm.js

@@ -0,0 +1,3 @@
+var QuarterParser = {};
+
+export { QuarterParser as __exports };

package/dist/_virtual/SecondParser.esm.js

@@ -0,0 +1,3 @@
+var SecondParser = {};
+
+export { SecondParser as __exports };

package/dist/_virtual/Setter.esm.js

@@ -0,0 +1,3 @@
+var Setter = {};
+
+export { Setter as __exports };

package/dist/_virtual/StandAloneLocalDayParser.esm.js

@@ -0,0 +1,3 @@
+var StandAloneLocalDayParser = {};
+
+export { StandAloneLocalDayParser as __exports };

package/dist/_virtual/StandAloneMonthParser.esm.js

@@ -0,0 +1,3 @@
+var StandAloneMonthParser = {};
+
+export { StandAloneMonthParser as __exports };

package/dist/_virtual/StandAloneQuarterParser.esm.js

@@ -0,0 +1,3 @@
+var StandAloneQuarterParser = {};
+
+export { StandAloneQuarterParser as __exports };

package/dist/_virtual/TimestampMillisecondsParser.esm.js

@@ -0,0 +1,3 @@
+var TimestampMillisecondsParser = {};
+
+export { TimestampMillisecondsParser as __exports };

package/dist/_virtual/TimestampSecondsParser.esm.js

@@ -0,0 +1,3 @@
+var TimestampSecondsParser = {};
+
+export { TimestampSecondsParser as __exports };

package/dist/_virtual/YearParser.esm.js

@@ -0,0 +1,3 @@
+var YearParser = {};
+
+export { YearParser as __exports };

package/dist/_virtual/_commonjsHelpers.esm.js

@@ -0,0 +1,30 @@
+function getAugmentedNamespace(n) {
+  if (Object.prototype.hasOwnProperty.call(n, '__esModule')) return n;
+  var f = n.default;
+	if (typeof f == "function") {
+		var a = function a () {
+			var isInstance = false;
+      try {
+        isInstance = this instanceof a;
+      } catch {}
+			if (isInstance) {
+        return Reflect.construct(f, arguments, this.constructor);
+			}
+			return f.apply(this, arguments);
+		};
+		a.prototype = f.prototype;
+  } else a = {};
+  Object.defineProperty(a, '__esModule', {value: true});
+	Object.keys(n).forEach(function (k) {
+		var d = Object.getOwnPropertyDescriptor(n, k);
+		Object.defineProperty(a, k, d.get ? d : {
+			enumerable: true,
+			get: function () {
+				return n[k];
+			}
+		});
+	});
+	return a;
+}
+
+export { getAugmentedNamespace };

package/dist/_virtual/add.esm.js

@@ -0,0 +1,3 @@
+var add = {};
+
+export { add as __exports };

package/dist/_virtual/addBusinessDays.esm.js

@@ -0,0 +1,3 @@
+var addBusinessDays = {};
+
+export { addBusinessDays as __exports };

package/dist/_virtual/addDays.esm.js

@@ -0,0 +1,3 @@
+var addDays = {};
+
+export { addDays as __exports };

package/dist/_virtual/addHours.esm.js

@@ -0,0 +1,3 @@
+var addHours = {};
+
+export { addHours as __exports };

package/dist/_virtual/addISOWeekYears.esm.js

@@ -0,0 +1,3 @@
+var addISOWeekYears = {};
+
+export { addISOWeekYears as __exports };

package/dist/_virtual/addLeadingZeros.esm.js

@@ -0,0 +1,3 @@
+var addLeadingZeros = {};
+
+export { addLeadingZeros as __exports };

package/dist/_virtual/addMilliseconds.esm.js

@@ -0,0 +1,3 @@
+var addMilliseconds = {};
+
+export { addMilliseconds as __exports };

package/dist/_virtual/addMinutes.esm.js

@@ -0,0 +1,3 @@
+var addMinutes = {};
+
+export { addMinutes as __exports };

package/dist/_virtual/addMonths.esm.js

@@ -0,0 +1,3 @@
+var addMonths = {};
+
+export { addMonths as __exports };

package/dist/_virtual/addQuarters.esm.js

@@ -0,0 +1,3 @@
+var addQuarters = {};
+
+export { addQuarters as __exports };

package/dist/_virtual/addSeconds.esm.js

@@ -0,0 +1,3 @@
+var addSeconds = {};
+
+export { addSeconds as __exports };

package/dist/_virtual/addWeeks.esm.js

@@ -0,0 +1,3 @@
+var addWeeks = {};
+
+export { addWeeks as __exports };

package/dist/_virtual/addYears.esm.js

@@ -0,0 +1,3 @@
+var addYears = {};
+
+export { addYears as __exports };

package/dist/_virtual/areIntervalsOverlapping.esm.js

@@ -0,0 +1,3 @@
+var areIntervalsOverlapping = {};
+
+export { areIntervalsOverlapping as __exports };

package/dist/_virtual/buildFormatLongFn.esm.js

@@ -0,0 +1,3 @@
+var buildFormatLongFn = {};
+
+export { buildFormatLongFn as __exports };

package/dist/_virtual/buildLocalizeFn.esm.js

@@ -0,0 +1,3 @@
+var buildLocalizeFn = {};
+
+export { buildLocalizeFn as __exports };

package/dist/_virtual/buildMatchFn.esm.js

@@ -0,0 +1,3 @@
+var buildMatchFn = {};
+
+export { buildMatchFn as __exports };

package/dist/_virtual/buildMatchPatternFn.esm.js

@@ -0,0 +1,3 @@
+var buildMatchPatternFn = {};
+
+export { buildMatchPatternFn as __exports };

package/dist/_virtual/clamp.esm.js

@@ -0,0 +1,3 @@
+var clamp = {};
+
+export { clamp as __exports };

package/dist/_virtual/closestIndexTo.esm.js

@@ -0,0 +1,3 @@
+var closestIndexTo = {};
+
+export { closestIndexTo as __exports };

package/dist/_virtual/closestTo.esm.js

@@ -0,0 +1,3 @@
+var closestTo = {};
+
+export { closestTo as __exports };

package/dist/_virtual/compareAsc.esm.js

@@ -0,0 +1,3 @@
+var compareAsc = {};
+
+export { compareAsc as __exports };

package/dist/_virtual/compareDesc.esm.js

@@ -0,0 +1,3 @@
+var compareDesc = {};
+
+export { compareDesc as __exports };

package/dist/_virtual/constants.esm.js

@@ -0,0 +1,3 @@
+var constants = {};
+
+export { constants as __exports };

package/dist/_virtual/constants.esm2.js

@@ -0,0 +1,3 @@
+var constants = {};
+
+export { constants as __exports };