extended-dynamic-forms 0.1.0

package/README.md

@@ -0,0 +1,583 @@
+# Extended Dynamic Forms
+
+A comprehensive extension of React JSON Schema Form (RJSF) v5 with shadcn/ui components, custom widgets, fields, layouts, and a powerful central event orchestration system with webhook capabilities.
+
+## Features
+
+- 🎨 **shadcn/ui Integration**: Built on top of @rjsf/shadcn for beautiful, accessible components
+- ✨ **Custom Widgets**: Color picker, date picker, file upload, range slider, rating stars
+- 🏗️ **Custom Fields**: Address, phone number, currency input with formatting
+- 📐 **Layout Components**: Vertical, horizontal, and grid layouts
+- 🎯 **Central Event Orchestration**: Unified system capturing all form field events (focus, blur, change)
+- 🔗 **Webhook Integration**: Configure multiple webhook endpoints with debouncing and retry logic
+- 🔧 **Enhanced Form Events**: Before/after submit and validation hooks plus field-level events
+- 📦 **TypeScript Support**: Fully typed with comprehensive type definitions
+- ⚡ **Vite Powered**: Fast development and optimized builds
+- 🎯 **Tailwind CSS**: Utility-first styling with full customization
+- 🛡️ **Error Handling**: Robust error recovery and retry mechanisms
+- ⚡ **Performance Optimized**: Debouncing, queuing, and async processing
+
+## Installation
+
+```bash
+npm install extended-dynamic-forms
+# or
+yarn add extended-dynamic-forms
+```
+
+### Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```json
+{
+  "react": "^18.0.0",
+  "react-dom": "^18.0.0",
+  "@rjsf/core": "^5.15.0",
+  "@rjsf/utils": "^5.15.0",
+  "@rjsf/validator-ajv8": "^5.15.0",
+  "@rjsf/shadcn": "^0.1.0"
+}
+```
+
+## Setup
+
+### CSS Requirements
+
+This package uses Tailwind CSS and shadcn/ui components. Make sure to include the required CSS in your application:
+
+```tsx
+// In your main entry file (e.g., App.tsx or index.tsx)
+import 'extended-dynamic-forms/dist/index.css';
+```
+
+If you're using Tailwind CSS in your project, ensure your `tailwind.config.js` includes the package in the content array:
+
+```js
+module.exports = {
+  content: [
+    // ... your other content paths
+    "./node_modules/extended-dynamic-forms/**/*.{js,ts,jsx,tsx}",
+  ],
+  // ... rest of your config
+}
+```
+
+## Quick Start
+
+### Basic Form
+
+```tsx
+import React from 'react';
+import { ExtendedForm } from 'extended-dynamic-forms';
+
+const schema = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', title: 'Name' },
+    email: { type: 'string', format: 'email', title: 'Email' },
+    rating: { type: 'number', title: 'Rating' },
+    favoriteColor: { type: 'string', title: 'Favorite Color' }
+  },
+  required: ['name', 'email']
+};
+
+const uiSchema = {
+  rating: {
+    'ui:widget': 'rating',
+    'ui:options': { max: 5 }
+  },
+  favoriteColor: {
+    'ui:widget': 'color'
+  }
+};
+
+function App() {
+  const handleSubmit = ({ formData }) => {
+    console.log('Form data:', formData);
+  };
+
+  const handleFieldChange = (event) => {
+    console.log(`Field ${event.fieldId} changed to:`, event.fieldValue);
+  };
+
+  return (
+    <ExtendedForm
+      schema={schema}
+      uiSchema={uiSchema}
+      onSubmit={handleSubmit}
+      onFieldChange={handleFieldChange}
+    />
+  );
+}
+```
+
+### With Webhook Integration
+
+```tsx
+import React from 'react';
+import { ExtendedForm, WebhookConfig } from 'extended-dynamic-forms';
+
+const webhooks: WebhookConfig[] = [
+  {
+    url: 'https://your-api.com/webhooks/form-events',
+    events: ['change'],
+    debounceMs: 300,
+    headers: {
+      'Authorization': 'Bearer your-token'
+    }
+  }
+];
+
+function App() {
+  return (
+    <ExtendedForm
+      schema={schema}
+      uiSchema={uiSchema}
+      webhooks={webhooks}
+      onSubmit={({ formData }) => {
+        console.log('Form submitted:', formData);
+      }}
+      onFieldFocus={(event) => {
+        console.log('Field focused:', event.fieldId);
+      }}
+    />
+  );
+}
+```
+
+## Custom Widgets
+
+### Color Widget
+```tsx
+const uiSchema = {
+  favoriteColor: {
+    'ui:widget': 'color'
+  }
+};
+```
+
+### Date Widget
+```tsx
+const uiSchema = {
+  birthDate: {
+    'ui:widget': 'date',
+    'ui:options': {
+      inputType: 'datetime-local', // or 'date', 'time'
+      minDate: '2000-01-01',
+      maxDate: '2025-12-31'
+    }
+  }
+};
+```
+
+### File Widget
+```tsx
+const uiSchema = {
+  documents: {
+    'ui:widget': 'file',
+    'ui:options': {
+      accept: '.pdf,.doc,.docx',
+      multiple: true
+    }
+  }
+};
+```
+
+### Range Widget
+```tsx
+const schema = {
+  volume: {
+    type: 'number',
+    minimum: 0,
+    maximum: 100,
+    multipleOf: 5
+  }
+};
+
+const uiSchema = {
+  volume: {
+    'ui:widget': 'range'
+  }
+};
+```
+
+### Rating Widget
+```tsx
+const uiSchema = {
+  satisfaction: {
+    'ui:widget': 'rating',
+    'ui:options': {
+      max: 10 // default is 5
+    }
+  }
+};
+```
+
+## Custom Fields
+
+### Address Field
+```tsx
+const schema = {
+  homeAddress: {
+    type: 'object',
+    properties: {
+      street: { type: 'string' },
+      city: { type: 'string' },
+      state: { type: 'string' },
+      zip: { type: 'string' },
+      country: { type: 'string' }
+    }
+  }
+};
+
+const uiSchema = {
+  homeAddress: {
+    'ui:field': 'address'
+  }
+};
+```
+
+### Phone Field
+```tsx
+const uiSchema = {
+  phoneNumber: {
+    'ui:field': 'phone'
+  }
+};
+```
+
+### Currency Field
+```tsx
+const uiSchema = {
+  price: {
+    'ui:field': 'currency',
+    'ui:options': {
+      currency: 'EUR',
+      symbol: '€'
+    }
+  }
+};
+```
+
+## Central Event Orchestration System
+
+The library features a comprehensive event orchestration system that captures all form field events and enables webhook integration.
+
+### Field-Level Event Handling
+
+```tsx
+import { ExtendedForm, FormFieldEvent } from 'extended-dynamic-forms';
+
+<ExtendedForm
+  schema={schema}
+  uiSchema={uiSchema}
+  formData={formData}
+  
+  // Field-level event handlers
+  onFieldFocus={(event: FormFieldEvent) => {
+    console.log(`Field ${event.fieldId} focused:`, event.fieldValue);
+    // Track user interactions for analytics
+  }}
+  
+  onFieldChange={(event: FormFieldEvent) => {
+    console.log(`Field ${event.fieldId} changed:`, event.fieldValue);
+    // Real-time validation or processing
+    if (event.fieldId === 'root_email') {
+      validateEmailRealTime(event.fieldValue);
+    }
+  }}
+  
+  onFieldBlur={(event: FormFieldEvent) => {
+    console.log(`Field ${event.fieldId} blurred:`, event.fieldValue);
+    // Format field values or trigger validation
+  }}
+  
+  // Traditional form-level events (still supported)
+  beforeSubmit={async (data) => {
+    return { ...data, timestamp: Date.now() };
+  }}
+  
+  afterSubmit={async (data) => {
+    console.log('Form submitted:', data);
+  }}
+/>
+```
+
+### Webhook Integration
+
+Configure multiple webhook endpoints to receive real-time form events:
+
+```tsx
+import { ExtendedForm, WebhookConfig } from 'extended-dynamic-forms';
+
+const webhookConfigs: WebhookConfig[] = [
+  {
+    url: 'https://api.yourapp.com/form-events',
+    method: 'POST',
+    events: ['change', 'blur'],  // Only trigger on change and blur
+    debounceMs: 500,             // Wait 500ms before sending
+    retries: 3,                  // Retry failed requests
+    timeout: 5000,               // 5 second timeout
+    headers: {
+      'Authorization': 'Bearer your-api-token',
+      'X-Form-ID': 'contact-form',
+      'Content-Type': 'application/json'
+    }
+  },
+  {
+    url: 'https://analytics.yourapp.com/field-interactions',
+    events: ['focus'],           // Track focus events for analytics
+    debounceMs: 0,              // No debouncing for real-time analytics
+    retries: 1,
+    headers: {
+      'X-Analytics-Key': 'your-analytics-key'
+    }
+  }
+];
+
+<ExtendedForm
+  schema={schema}
+  uiSchema={uiSchema}
+  webhooks={webhookConfigs}
+  
+  onFieldChange={(event) => {
+    // Local processing alongside webhooks
+    if (event.fieldId === 'root_email') {
+      setEmailValid(validateEmail(event.fieldValue));
+    }
+  }}
+/>
+```
+
+### Webhook Payload Structure
+
+Your webhook endpoints will receive payloads in this format:
+
+```json
+{
+  "event": {
+    "eventType": "change",
+    "fieldId": "root_email",
+    "fieldValue": "user@example.com",
+    "schema": {
+      "type": "string",
+      "format": "email",
+      "title": "Email Address"
+    },
+    "formData": {
+      "email": "user@example.com",
+      "name": "John Doe"
+    },
+    "timestamp": 1678901234567,
+    "fieldPath": ["email"]
+  },
+  "timestamp": 1678901234567,
+  "source": "extended-dynamic-forms"
+}
+```
+
+### Advanced Features
+
+- **Debouncing**: Prevent webhook spam on rapid input changes
+- **Retry Logic**: Automatic retry with exponential backoff for failed requests
+- **Error Isolation**: Webhook failures don't block form functionality
+- **Event Filtering**: Configure which events trigger each webhook
+- **Queue Management**: Asynchronous processing with proper ordering
+- **Custom Headers**: Add authentication, tracking, or custom metadata
+
+## Layouts
+
+```tsx
+import { VerticalLayout, HorizontalLayout, GridLayout } from 'extended-dynamic-forms';
+
+// Vertical Layout
+<VerticalLayout spacing="medium">
+  <input />
+  <button />
+</VerticalLayout>
+
+// Horizontal Layout
+<HorizontalLayout spacing="large" align="center">
+  <label />
+  <input />
+</HorizontalLayout>
+
+// Grid Layout
+<GridLayout columns={3} gap="medium">
+  <Card />
+  <Card />
+  <Card />
+</GridLayout>
+```
+
+## Use Cases
+
+### Real-time Form Analytics
+```tsx
+const webhooks: WebhookConfig[] = [
+  {
+    url: 'https://analytics.yourapp.com/form-interactions',
+    events: ['focus', 'blur', 'change'],
+    debounceMs: 100,
+    headers: { 'X-Analytics-Token': 'your-token' }
+  }
+];
+
+// Track user behavior, field completion rates, abandonment points
+```
+
+### Auto-save & Recovery
+```tsx
+<ExtendedForm
+  schema={schema}
+  onFieldChange={(event) => {
+    // Auto-save to localStorage or server
+    localStorage.setItem(`form_${event.fieldId}`, event.fieldValue);
+  }}
+  webhooks={[{
+    url: 'https://api.yourapp.com/autosave',
+    events: ['change'],
+    debounceMs: 2000 // Save every 2 seconds
+  }]}
+/>
+```
+
+### Real-time Validation
+```tsx
+<ExtendedForm
+  schema={schema}
+  onFieldBlur={async (event) => {
+    if (event.fieldId === 'root_email') {
+      const isValid = await validateEmailWithAPI(event.fieldValue);
+      setEmailValidation(isValid);
+    }
+  }}
+  webhooks={[{
+    url: 'https://validation.yourapp.com/validate',
+    events: ['blur'],
+    headers: { 'Content-Type': 'application/json' }
+  }]}
+/>
+```
+
+### Progressive Form Enhancement
+```tsx
+<ExtendedForm
+  schema={schema}
+  onFieldChange={(event) => {
+    // Show additional fields based on user input
+    if (event.fieldId === 'root_country' && event.fieldValue === 'US') {
+      setShowStateField(true);
+    }
+  }}
+/>
+```
+
+## API Reference
+
+### ExtendedFormProps
+
+```typescript
+interface ExtendedFormProps extends FormProps {
+  // Standard RJSF props
+  schema: RJSFSchema;
+  uiSchema?: UiSchema;
+  formData?: any;
+  onSubmit?: (data: any, event: any) => void;
+  onChange?: (data: any) => void;
+  
+  // Field-level event handlers
+  onFieldFocus?: (event: FormFieldEvent) => Promise<void> | void;
+  onFieldBlur?: (event: FormFieldEvent) => Promise<void> | void;
+  onFieldChange?: (event: FormFieldEvent) => Promise<void> | void;
+  
+  // Webhook configuration
+  webhooks?: WebhookConfig[];
+  
+  // Form lifecycle events
+  beforeSubmit?: (data: any) => Promise<any> | any;
+  afterSubmit?: (data: any) => Promise<void> | void;
+  beforeValidation?: (data: any) => Promise<any> | any;
+  afterValidation?: (data: any, errors: any) => Promise<void> | void;
+}
+```
+
+### FormFieldEvent
+
+```typescript
+interface FormFieldEvent {
+  eventType: 'focus' | 'blur' | 'change';
+  fieldId: string;
+  fieldValue: any;
+  schema?: any;
+  formData?: any;
+  timestamp: number;
+  fieldPath?: string[];
+}
+```
+
+### WebhookConfig
+
+```typescript
+interface WebhookConfig {
+  url: string;
+  method?: 'POST' | 'PUT' | 'PATCH';
+  headers?: Record<string, string>;
+  events?: ('focus' | 'blur' | 'change')[];
+  debounceMs?: number;
+  retries?: number;
+  timeout?: number;
+}
+```
+
+## Utility Functions
+
+```tsx
+import { formDataUtils, schemaUtils, validationUtils } from 'extended-dynamic-forms';
+
+// Form Data Utils
+const clonedData = formDataUtils.cloneFormData(formData);
+const mergedData = formDataUtils.mergeFormData(current, updates);
+const nestedValue = formDataUtils.getNestedValue(data, 'user.address.city');
+const updatedData = formDataUtils.setNestedValue(data, 'user.name', 'John');
+const cleanData = formDataUtils.removeEmptyValues(data);
+
+// Schema Utils
+const required = schemaUtils.getRequiredFields(schema);
+const isRequired = schemaUtils.isFieldRequired(schema, 'email');
+const fieldSchema = schemaUtils.getFieldSchema(schema, 'user.address');
+const merged = schemaUtils.mergeSchemas(schema1, schema2);
+const paths = schemaUtils.getAllFieldPaths(schema);
+
+// Validation Utils
+const isEmail = validationUtils.isValidEmail('test@example.com');
+const isPhone = validationUtils.isValidPhone('(555) 123-4567');
+const isUrl = validationUtils.isValidUrl('https://example.com');
+const isDate = validationUtils.isValidDate('2024-01-01');
+const inRange = validationUtils.isInRange(5, 1, 10);
+const message = validationUtils.getValidationMessage('required');
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run development server
+npm run dev
+
+# Build library
+npm run build
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+```
+
+## License
+
+MIT

package/dist/ExtendedForm.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { ExtendedFormProps } from './types';
+
+export declare const ExtendedForm: React.FC<ExtendedFormProps>;

package/dist/components/fields/AddressField.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { FieldProps } from '@rjsf/utils';
+
+export declare const AddressField: React.FC<FieldProps>;

package/dist/components/fields/CurrencyField.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { FieldProps } from '@rjsf/utils';
+
+export declare const CurrencyField: React.FC<FieldProps>;

package/dist/components/fields/PhoneField.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { FieldProps } from '@rjsf/utils';
+
+export declare const PhoneField: React.FC<FieldProps>;

package/dist/components/index.d.ts

@@ -0,0 +1,10 @@
+import { AddressField } from './fields/AddressField';
+import { PhoneField } from './fields/PhoneField';
+import { CurrencyField } from './fields/CurrencyField';
+
+export declare const customFields: {
+    address: import('react').FC<import('@rjsf/utils').FieldProps<any, import('@rjsf/utils').RJSFSchema, any>>;
+    phone: import('react').FC<import('@rjsf/utils').FieldProps<any, import('@rjsf/utils').RJSFSchema, any>>;
+    currency: import('react').FC<import('@rjsf/utils').FieldProps<any, import('@rjsf/utils').RJSFSchema, any>>;
+};
+export { AddressField, PhoneField, CurrencyField, };

package/dist/components/ui/badge.d.ts

@@ -0,0 +1,9 @@
+import { VariantProps } from 'class-variance-authority';
+import * as React from "react";
+declare const badgeVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface BadgeProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {
+}
+declare function Badge({ className, variant, ...props }: BadgeProps): import("react/jsx-runtime").JSX.Element;
+export { Badge, badgeVariants };

package/dist/components/ui/button.d.ts

@@ -0,0 +1,11 @@
+import { VariantProps } from 'class-variance-authority';
+import * as React from "react";
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "link" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export { Button, buttonVariants };

package/dist/components/ui/card.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+declare const Card: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardTitle: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLHeadingElement> & React.RefAttributes<HTMLParagraphElement>>;
+declare const CardDescription: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+declare const CardContent: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardFooter: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent };

package/dist/components/ui/input.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+}
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
+export { Input };

package/dist/components/ui/label.d.ts

@@ -0,0 +1,5 @@
+import { VariantProps } from 'class-variance-authority';
+import * as React from "react";
+import * as LabelPrimitive from "@radix-ui/react-label";
+declare const Label: React.ForwardRefExoticComponent<Omit<LabelPrimitive.LabelProps & React.RefAttributes<HTMLLabelElement>, "ref"> & VariantProps<(props?: import('class-variance-authority/types').ClassProp | undefined) => string> & React.RefAttributes<HTMLLabelElement>>;
+export { Label };

package/dist/components/ui/slider.d.ts

@@ -0,0 +1,4 @@
+import * as React from "react";
+import * as SliderPrimitive from "@radix-ui/react-slider";
+declare const Slider: React.ForwardRefExoticComponent<Omit<SliderPrimitive.SliderProps & React.RefAttributes<HTMLSpanElement>, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export { Slider };

package/dist/events/FormEventContext.d.ts

@@ -0,0 +1,20 @@
+import { default as React, ReactNode } from 'react';
+import { FormEventHub } from './FormEventHub';
+
+interface FormEventContextType {
+    eventHub: FormEventHub;
+    formData?: any;
+}
+interface FormEventProviderProps {
+    eventHub: FormEventHub;
+    formData?: any;
+    children: ReactNode;
+}
+export declare const FormEventProvider: React.FC<FormEventProviderProps>;
+export declare const useFormEventHub: () => FormEventContextType;
+export declare const useFieldEventHandlers: (fieldId: string, schema?: any, fieldPath?: string[]) => {
+    onFocus: (value: any) => Promise<void>;
+    onBlur: (value: any) => Promise<void>;
+    onChange: (value: any) => Promise<void>;
+};
+export {};