@connect-soft/form-generator 1.1.0-alpha6 → 1.1.0-alpha8

package/README.md

@@ -120,8 +120,53 @@ registerFields({
 
 // Register the submit button component
 registerFormComponent('SubmitButton', Button);
+
+// Optional: Register field wrappers for custom styling
+registerFormComponent('FieldWrapper', ({ children, name, type, className }) => (
+  <div className={`field-wrapper field-${type}`} data-field={name}>
+    {children}
+  </div>
+));
+
+registerFormComponent('FieldsWrapper', ({ children }) => (
+  <div className="form-fields">
+    {children}
+  </div>
+));
+```
+
+---
+
+## Field Wrappers
+
+Customize how fields are wrapped without modifying individual field components:
+
+### FieldWrapper
+
+Wraps each individual field. Receives the field's `name`, `type`, and `className`:
+
+```typescript
+registerFormComponent('FieldWrapper', ({ children, name, type, className }) => (
+  <div className={`form-group ${className || ''}`} data-field-type={type}>
+    {children}
+  </div>
+));
+```
+
+### FieldsWrapper
+
+Wraps all fields together (excludes the submit button). Useful for grid layouts:
+
+```typescript
+registerFormComponent('FieldsWrapper', ({ children, className }) => (
+  <div className={`grid grid-cols-2 gap-4 ${className || ''}`}>
+    {children}
+  </div>
+));
 ```
 
+Both default to `React.Fragment`, adding zero DOM overhead when not customized.
+
 ---
 
 ## Field Types
@@ -175,12 +220,13 @@ const fields = [
 ] as const;
 ```
 
-Don't forget to register the component for your custom field:
+Then register the component for your custom field:
 
 ```typescript
 import { registerField } from '@connect-soft/form-generator';
 import { ColorPicker } from './components/ColorPicker';
 
+// Type-safe: 'color-picker' must exist in FieldTypeRegistry
 registerField('color-picker', ({ field, formField }) => (
   <ColorPicker
     value={formField.value}
@@ -189,6 +235,71 @@ registerField('color-picker', ({ field, formField }) => (
     showAlpha={field.showAlpha}
   />
 ));
+
+// ❌ TypeScript error: 'unknown-type' is not in FieldTypeRegistry
+// registerField('unknown-type', MyComponent);
+```
+
+> **Note:** Both `registerField` and `registerFields` enforce that field types must be defined in `FieldTypeRegistry`. This ensures type safety between your type definitions and runtime registrations.
+
+### Field Type Validation Helpers
+
+Use helper functions for strict type checking without `as const`:
+
+```typescript
+import { createField, createArrayField, strictFields } from '@connect-soft/form-generator';
+
+// Create a single field with full type checking
+const emailField = createField({
+  type: 'email',
+  name: 'email',
+  label: 'Email',
+  placeholder: 'Enter your email'  // TypeScript knows this is valid for email
+});
+
+// Create an array field
+const contacts = createArrayField({
+  name: 'contacts',
+  fields: [
+    { type: 'text', name: 'name', label: 'Name' },
+    { type: 'email', name: 'email', label: 'Email' }
+  ],
+  minItems: 1,
+  maxItems: 5
+});
+
+// Create an array of fields with type checking
+const fields = strictFields([
+  { type: 'text', name: 'username', label: 'Username' },
+  { type: 'email', name: 'email', label: 'Email' },
+  // { type: 'unknown', name: 'bad' }  // TypeScript error!
+]);
+```
+
+### Runtime Field Type Validation
+
+Enable runtime validation to catch unregistered field types during development:
+
+```typescript
+// Warn in console for unregistered types (recommended for development)
+<FormGenerator
+  fields={fields}
+  onSubmit={handleSubmit}
+  validateTypes
+/>
+
+// Throw an error for unregistered types
+<FormGenerator
+  fields={fields}
+  onSubmit={handleSubmit}
+  validateTypes={{ throwOnError: true }}
+/>
+
+// Manual validation
+import { validateFieldTypes, getRegisteredFieldTypes } from '@connect-soft/form-generator';
+
+const registeredTypes = getRegisteredFieldTypes();
+validateFieldTypes(fields, registeredTypes, { throwOnError: true });
 ```
 
 ---
@@ -365,6 +476,8 @@ The render function receives:
 | `isValid` | `boolean` | Form validity state |
 | `isDirty` | `boolean` | Form dirty state |
 | `renderField` | `function` | Manual field renderer |
+| `FieldWrapper` | `ComponentType` | Registered FieldWrapper component |
+| `FieldsWrapper` | `ComponentType` | Registered FieldsWrapper component |
 
 ### Fields Object
 
@@ -527,6 +640,63 @@ function MyForm() {
 | `isDirty()` | Check if form has unsaved changes |
 | `form` | Access underlying react-hook-form instance |
 
+### Watching Form Values
+
+Detect when field values change from the parent component:
+
+```typescript
+import { useRef, useEffect } from 'react';
+import { FormGenerator, FormGeneratorRef } from '@connect-soft/form-generator';
+
+function MyForm() {
+  const formRef = useRef<FormGeneratorRef>(null);
+
+  useEffect(() => {
+    // Watch all fields for changes
+    const subscription = formRef.current?.form.watch((values, { name, type }) => {
+      console.log('Changed field:', name);
+      console.log('New values:', values);
+    });
+
+    return () => subscription?.unsubscribe();
+  }, []);
+
+  return (
+    <FormGenerator
+      ref={formRef}
+      fields={fields}
+      onSubmit={handleSubmit}
+    />
+  );
+}
+```
+
+Or use `useWatch` inside a custom layout:
+
+```typescript
+import { FormGenerator, useWatch } from '@connect-soft/form-generator';
+
+function ValueWatcher() {
+  const email = useWatch({ name: 'email' }); // Watch specific field
+
+  useEffect(() => {
+    console.log('Email changed:', email);
+  }, [email]);
+
+  return null;
+}
+
+<FormGenerator fields={fields} onSubmit={handleSubmit}>
+  {({ fields, buttons }) => (
+    <>
+      {fields.all}
+      <ValueWatcher />
+      {buttons.submit}
+    </>
+  )}
+</FormGenerator>
+```
+
 ---
 
 ## API Reference
@@ -548,6 +718,7 @@ function MyForm() {
 | `description` | `string` | - | Form description (available in render props) |
 | `showReset` | `boolean` | `false` | Include reset button in `buttons.reset` |
 | `resetText` | `string` | `'Reset'` | Reset button text |
+| `validateTypes` | `boolean \| ValidateTypesOptions` | `false` | Runtime validation of field types |
 
 ### Field Base Properties
 

package/dist/index.js

@@ -2795,6 +2795,49 @@ function t(r,e){try{var o=r();}catch(r){return e(r)}return o&&o.then?o.then(void
 function isArrayField(field) {
   return field.type === 'array' && 'fields' in field;
 }
+function createField(field) {
+  return field;
+}
+function createArrayField(field) {
+  return {
+    ...field,
+    type: 'array'
+  };
+}
+function strictFields(fields) {
+  return fields;
+}
+function validateFieldType(type, registeredTypes) {
+  if (!registeredTypes.includes(type) && type !== 'array') {
+    throw new Error(`Unregistered field type: "${type}". ` + `Registered types: ${registeredTypes.join(', ')}. ` + `Use registerField("${type}", YourComponent) to register it.`);
+  }
+  return type;
+}
+function validateFieldTypes(fields, registeredTypes, options = {}) {
+  const {
+    throwOnError = false,
+    warn = true
+  } = options;
+  const invalidTypes = [];
+  const checkField = field => {
+    if (field.type === 'array' && 'fields' in field) {
+      field.fields.forEach(checkField);
+    } else if (!registeredTypes.includes(field.type) && field.type !== 'array') {
+      invalidTypes.push(field.type);
+    }
+  };
+  fields.forEach(checkField);
+  if (invalidTypes.length > 0) {
+    const uniqueInvalid = [...new Set(invalidTypes)];
+    const message = `Unregistered field type(s): ${uniqueInvalid.map(t => `"${t}"`).join(', ')}. ` + `Registered types: ${registeredTypes.join(', ')}. ` + 'Register custom types with registerField() or use module augmentation for TypeScript support.';
+    if (throwOnError) {
+      throw new Error(message);
+    } else if (warn && typeof console !== 'undefined') {
+      console.warn(`[FormGenerator] ${message}`);
+    }
+  }
+  return fields;
+}
 
 const fieldRegistry = new Map();
 const componentRegistry = {};
@@ -2808,7 +2851,13 @@ const defaultFormComponents = {
     type: 'submit',
     className: className !== null && className !== void 0 ? className : 'form-submit',
     disabled: disabled || isSubmitting
-  }, isSubmitting ? 'Submitting...' : children)
+  }, isSubmitting ? 'Submitting...' : children),
+  FieldWrapper: ({
+    children
+  }) => /*#__PURE__*/React.createElement(React.Fragment, null, children),
+  FieldsWrapper: ({
+    children
+  }) => /*#__PURE__*/React.createElement(React.Fragment, null, children)
 };
 const htmlInputTypes = {
   text: 'text',
@@ -2951,27 +3000,15 @@ function createDefaultFieldComponent(type) {
   };
   return FallbackComponent;
 }
-function registerField(type, component, options = {}, config = {}) {
-  const {
-    override = true
-  } = config;
-  const exists = fieldRegistry.has(type);
-  if (override === 'only' && !exists) return;
-  if (override === false && exists) return;
+function registerField(type, component, options = {}) {
   fieldRegistry.set(type, {
     component,
     options
   });
 }
-function registerFields(fields, config = {}) {
-  const {
-    override = true
-  } = config;
+function registerFields(fields) {
   Object.entries(fields).forEach(([type, definition]) => {
     var _a;
-    const exists = fieldRegistry.has(type);
-    if (override === 'only' && !exists) return;
-    if (override === false && exists) return;
     if (typeof definition === 'function') {
       fieldRegistry.set(type, {
         component: definition,
@@ -3006,24 +3043,12 @@ function unregisterField(type) {
 function getRegisteredFieldTypes() {
   return Array.from(fieldRegistry.keys());
 }
-function registerFormComponents(components, config = {}) {
-  const {
-    override = true
-  } = config;
+function registerFormComponents(components) {
   Object.keys(components).forEach(key => {
-    const exists = key in componentRegistry;
-    if (override === 'only' && !exists) return;
-    if (override === false && exists) return;
     componentRegistry[key] = components[key];
   });
 }
-function registerFormComponent(name, component, config = {}) {
-  const {
-    override = true
-  } = config;
-  const exists = name in componentRegistry;
-  if (override === 'only' && !exists) return;
-  if (override === false && exists) return;
+function registerFormComponent(name, component) {
   componentRegistry[name] = component;
 }
 function getFormComponent(name) {
@@ -3508,8 +3533,19 @@ function FormGeneratorImpl(props) {
     showReset = false,
     resetText = 'Reset',
     children,
-    ref
+    ref,
+    validateTypes
   } = props;
+  React.useMemo(() => {
+    if (validateTypes) {
+      const registeredTypes = getRegisteredFieldTypes();
+      const options = typeof validateTypes === 'object' ? validateTypes : {
+        throwOnError: false,
+        warn: true
+      };
+      validateFieldTypes(fields, registeredTypes, options);
+    }
+  }, [fields, validateTypes]);
   const userSchema = hasSchema(props) ? props.schema : undefined;
   const onSubmit = props.onSubmit;
   const formRef = React.useRef(null);
@@ -3561,6 +3597,8 @@ function FormGeneratorImpl(props) {
     form: form
   }), [form, handleSubmit, mergedDefaultValues]);
   const SubmitButton = getFormComponent('SubmitButton');
+  const FieldWrapper = getFormComponent('FieldWrapper');
+  const FieldsWrapper = getFormComponent('FieldsWrapper');
   const {
     regularFields,
     arrayFields
@@ -3583,8 +3621,13 @@ function FormGeneratorImpl(props) {
     const entries = new Map();
     regularFields.forEach((field_0, index) => {
       if (!field_0.hidden) {
-        const element = jsxRuntime.jsx(FieldRenderer, {
-          field: field_0
+        const element = jsxRuntime.jsx(FieldWrapper, {
+          name: field_0.name,
+          type: field_0.type,
+          className: field_0.className,
+          children: jsxRuntime.jsx(FieldRenderer, {
+            field: field_0
+          })
         }, field_0.name || `field-${index}`);
         entries.set(field_0.name, {
           field: field_0,
@@ -3594,7 +3637,7 @@ function FormGeneratorImpl(props) {
       }
     });
     return entries;
-  }, [regularFields]);
+  }, [regularFields, FieldWrapper]);
   const templateFields = React.useMemo(() => createTemplateFields(fieldEntries), [fieldEntries]);
   const buttons = React.useMemo(() => {
     const result = {
@@ -3614,10 +3657,10 @@ function FormGeneratorImpl(props) {
     }
     return result;
   }, [SubmitButton, disabled, form.formState.isSubmitting, submitText, showReset, resetText, handleReset]);
-  const renderField = React.useCallback((field_1, options) => {
+  const renderField = React.useCallback((field_1, options_0) => {
     return jsxRuntime.jsx(FieldRenderer, {
       field: field_1,
-      namePrefix: options === null || options === void 0 ? void 0 : options.namePrefix
+      namePrefix: options_0 === null || options_0 === void 0 ? void 0 : options_0.namePrefix
     });
   }, []);
   if (!children) {
@@ -3627,11 +3670,23 @@ function FormGeneratorImpl(props) {
         ref: formRef,
         onSubmit: handleSubmit,
         className: className,
-        children: [regularFields.map((field_2, index_0) => jsxRuntime.jsx(FieldRenderer, {
-          field: field_2
-        }, field_2.name || `field-${index_0}`)), arrayFields.map(arrayField => jsxRuntime.jsx(ArrayFieldRenderer, {
-          field: arrayField
-        }, arrayField.name)), jsxRuntime.jsx(SubmitButton, {
+        children: [jsxRuntime.jsxs(FieldsWrapper, {
+          children: [regularFields.map((field_2, index_0) => jsxRuntime.jsx(FieldWrapper, {
+            name: field_2.name,
+            type: field_2.type,
+            className: field_2.className,
+            children: jsxRuntime.jsx(FieldRenderer, {
+              field: field_2
+            })
+          }, field_2.name || `field-${index_0}`)), arrayFields.map(arrayField => jsxRuntime.jsx(FieldWrapper, {
+            name: arrayField.name,
+            type: "array",
+            className: arrayField.className,
+            children: jsxRuntime.jsx(ArrayFieldRenderer, {
+              field: arrayField
+            })
+          }, arrayField.name))]
+        }), jsxRuntime.jsx(SubmitButton, {
           disabled: disabled || form.formState.isSubmitting,
           isSubmitting: form.formState.isSubmitting,
           children: submitText
@@ -3651,7 +3706,9 @@ function FormGeneratorImpl(props) {
     isSubmitting: form.formState.isSubmitting,
     isValid: form.formState.isValid,
     isDirty: form.formState.isDirty,
-    renderField
+    renderField,
+    FieldWrapper,
+    FieldsWrapper
   };
   const renderFn = children;
   return jsxRuntime.jsx(FormProvider, {
@@ -3680,6 +3737,8 @@ exports.FormProvider = FormProvider;
 exports.clearAllRegistries = clearAllRegistries;
 exports.clearFieldRegistry = clearFieldRegistry;
 exports.clearFormComponentRegistry = clearFormComponentRegistry;
+exports.createArrayField = createArrayField;
+exports.createField = createField;
 exports.getFieldComponent = getFieldComponent;
 exports.getFormComponent = getFormComponent;
 exports.getFormComponents = getFormComponents;
@@ -3692,10 +3751,13 @@ exports.registerFields = registerFields;
 exports.registerFormComponent = registerFormComponent;
 exports.registerFormComponents = registerFormComponents;
 exports.resetFormComponentRegistry = resetFormComponentRegistry;
+exports.strictFields = strictFields;
 exports.unregisterField = unregisterField;
 exports.useArrayField = useArrayField;
 exports.useFieldArray = useFieldArray;
 exports.useForm = useForm;
 exports.useFormContext = useFormContext;
 exports.useWatch = useWatch;
+exports.validateFieldType = validateFieldType;
+exports.validateFieldTypes = validateFieldTypes;
 //# sourceMappingURL=index.js.map