@ram_28/kf-ai-sdk 1.0.0

package/sdk/components/hooks/useForm/useForm.llm.txt

@@ -0,0 +1,340 @@
+# useForm Hook - LLM Documentation
+
+## Overview
+
+The `useForm` hook is a React hook that integrates react-hook-form with backend schemas for building dynamic forms. It provides:
+- Automatic schema fetching from Business Data Objects (BDO)
+- Validation rules from backend schema
+- Computed field support via draft API
+- Cross-field validation
+- Record fetching for update operations
+- Role-based field permissions
+- Type-safe form handling
+
+## Import
+
+```typescript
+import { useForm } from "kf-ai-sdk";
+```
+
+## Basic Usage
+
+```typescript
+const form = useForm<ProductType>({
+  source: "BDO_ProductMaster",
+  operation: "create", // or "update"
+  recordId: selectedProduct?._id, // required for update
+  enabled: showForm,
+  mode: "onBlur",
+  onSuccess: () => {
+    setShowForm(false);
+    table.refetch();
+  },
+  onError: (error) => console.error(error),
+});
+```
+
+## Configuration Options
+
+### UseFormOptions<T>
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `source` | `string` | Yes | - | Data source identifier (BDO name) |
+| `operation` | `"create" \| "update"` | Yes | - | Form operation type |
+| `recordId` | `string` | For update | - | Record ID for update operations |
+| `defaultValues` | `Partial<T>` | No | `{}` | Default form values |
+| `mode` | `FormMode` | No | `"onBlur"` | Validation mode |
+| `enabled` | `boolean` | No | `true` | Enable schema fetching |
+| `userRole` | `string` | No | - | User role for permissions |
+| `onSuccess` | `(data: T) => void` | No | - | Success callback |
+| `onError` | `(error: Error) => void` | No | - | Error callback |
+| `onSchemaError` | `(error: Error) => void` | No | - | Schema load error callback |
+| `onSubmitError` | `(error: Error) => void` | No | - | Submit error callback |
+| `skipSchemaFetch` | `boolean` | No | `false` | Skip schema fetching |
+| `schema` | `BackendSchema \| BDOSchema` | No | - | Manual schema |
+| `draftOnEveryChange` | `boolean` | No | `false` | Trigger draft API on every change |
+
+### Validation Modes
+
+| Mode | Description |
+|------|-------------|
+| `"onSubmit"` | Validate only when form is submitted |
+| `"onBlur"` | Validate when field loses focus (default) |
+| `"onChange"` | Validate on every keystroke/change |
+| `"onTouched"` | Validate on first blur, then on every change |
+| `"all"` | Validate on both blur and change |
+
+**Important:** Computation (draft API calls) ALWAYS fires on blur regardless of mode, but only if the field value is valid.
+
+## Return Value
+
+### UseFormReturn<T>
+
+#### Form Methods
+| Property | Type | Description |
+|----------|------|-------------|
+| `register` | `<K extends Path<T>>(name: K, options?) => ...` | Register field for validation |
+| `handleSubmit` | `() => (e?) => Promise<void>` | Handle form submission |
+| `watch` | `<K extends Path<T>>(name?: K) => ...` | Watch field values |
+| `setValue` | `<K extends Path<T>>(name: K, value, options?) => void` | Set field value programmatically |
+| `reset` | `(values?: T) => void` | Reset form to default values |
+
+#### Flattened Form State
+| Property | Type | Description |
+|----------|------|-------------|
+| `errors` | `FieldErrors<T>` | Form validation errors |
+| `isValid` | `boolean` | Form is valid |
+| `isDirty` | `boolean` | Form has been modified |
+| `isSubmitting` | `boolean` | Form is submitting |
+| `isSubmitSuccessful` | `boolean` | Submission was successful |
+| `formState` | `FormState<T>` | Full form state (backward compatibility) |
+
+#### Loading States
+| Property | Type | Description |
+|----------|------|-------------|
+| `isLoadingInitialData` | `boolean` | Loading schema/data |
+| `isLoadingRecord` | `boolean` | Loading record for update |
+| `isLoading` | `boolean` | Any loading state active |
+
+#### Error Handling
+| Property | Type | Description |
+|----------|------|-------------|
+| `loadError` | `Error \| null` | Schema fetch error |
+| `submitError` | `Error \| null` | Form submission error |
+| `hasError` | `boolean` | Any error active |
+
+#### Schema Information
+| Property | Type | Description |
+|----------|------|-------------|
+| `schema` | `BackendSchema \| null` | Raw backend schema |
+| `processedSchema` | `ProcessedSchema \| null` | Processed schema for rendering |
+| `computedFields` | `Array<keyof T>` | Computed field names |
+| `requiredFields` | `Array<keyof T>` | Required field names |
+
+#### Field Helpers
+| Property | Type | Description |
+|----------|------|-------------|
+| `getField` | `<K extends keyof T>(fieldName: K) => ProcessedField \| null` | Get field metadata |
+| `getFields` | `() => Record<keyof T, ProcessedField>` | Get all fields |
+| `hasField` | `<K extends keyof T>(fieldName: K) => boolean` | Check if field exists |
+| `isFieldRequired` | `<K extends keyof T>(fieldName: K) => boolean` | Check if required |
+| `isFieldComputed` | `<K extends keyof T>(fieldName: K) => boolean` | Check if computed |
+
+#### Operations
+| Property | Type | Description |
+|----------|------|-------------|
+| `submit` | `() => Promise<void>` | Submit form manually |
+| `refreshSchema` | `() => Promise<void>` | Refresh schema |
+| `validateForm` | `() => Promise<boolean>` | Validate form manually |
+| `clearErrors` | `() => void` | Clear all errors |
+
+## E-Commerce App Usage Example
+
+### Seller Products Page (SellerProductsPage.tsx)
+
+```typescript
+const [formMode, setFormMode] = useState<"create" | "update">("create");
+const [selectedProduct, setSelectedProduct] = useState<Product | null>(null);
+const [showForm, setShowForm] = useState(false);
+
+const form = useForm<SellerProduct>({
+  source: "BDO_AmazonProductMaster",
+  operation: formMode,
+  recordId: selectedProduct?._id,
+  enabled: showForm,
+  mode: "onBlur",
+  draftOnEveryChange: false, // Only trigger draft for computed field dependencies
+  onSuccess: () => {
+    setShowForm(false);
+    setSelectedProduct(null);
+    table.refetch();
+  },
+  onError: (error) => setGeneralError(error.message),
+  onSchemaError: (error) => setGeneralError(`Configuration Error: ${error.message}`),
+  onSubmitError: (error) => setGeneralError(`Submission Failed: ${error.message}`),
+});
+
+// Form submission
+const handleSubmit = async (e: React.FormEvent) => {
+  e.preventDefault();
+  await form.handleSubmit()();
+};
+
+// Form fields
+<form onSubmit={handleSubmit}>
+  {/* Text input with register */}
+  <Input
+    {...form.register("Title")}
+    placeholder="Enter product title"
+    defaultValue={selectedProduct?.Title || ""}
+    className={form.formState.errors.Title ? "border-red-500" : ""}
+  />
+  {form.formState.errors.Title && (
+    <p className="text-red-600">{form.formState.errors.Title.message}</p>
+  )}
+
+  {/* Number input */}
+  <Input
+    type="number"
+    {...form.register("Price")}
+    placeholder="0.00"
+    defaultValue={selectedProduct?.Price || ""}
+  />
+
+  {/* Select with setValue */}
+  <Select
+    value={form.watch("Category") || ""}
+    onValueChange={(value) => form.setValue("Category", value)}
+  >
+    <SelectTrigger>
+      <SelectValue placeholder="Select category" />
+    </SelectTrigger>
+    <SelectContent>
+      {categories.map((cat) => (
+        <SelectItem key={cat.Value} value={cat.Value}>
+          {cat.Label}
+        </SelectItem>
+      ))}
+    </SelectContent>
+  </Select>
+
+  {/* Computed field (read-only) */}
+  <Input
+    value={(form.watch("Discount") || 0).toFixed(2)}
+    readOnly
+    disabled
+    className="bg-gray-50"
+  />
+  <p className="text-xs text-gray-500">
+    Auto-calculated from (MRP - Price) / MRP * 100
+  </p>
+
+  {/* Computed boolean indicator */}
+  <span className={form.watch("LowStock") ? "text-red-800" : "text-green-800"}>
+    {form.watch("LowStock") ? "Low Stock" : "Good Stock"}
+  </span>
+
+  {/* Root/Cross-field errors */}
+  {form.formState.errors.root && (
+    <div className="bg-red-50 text-red-700">
+      {Object.values(form.formState.errors.root).map((err, idx) => (
+        <li key={idx}>{err.message}</li>
+      ))}
+    </div>
+  )}
+
+  {/* Submit button */}
+  <Button type="submit" disabled={form.isSubmitting}>
+    {form.isSubmitting ? "Saving..." : "Save"}
+  </Button>
+</form>
+```
+
+## Field Types
+
+The hook maps backend field types to HTML input types:
+
+| Backend Type | HTML Type |
+|--------------|-----------|
+| `String` | `text` |
+| `Number` | `number` |
+| `Boolean` | `checkbox` |
+| `Date` | `date` |
+| `DateTime` | `datetime-local` |
+| `Reference` | `reference` (select) |
+
+## Computed Fields
+
+Computed fields are automatically calculated by the backend. The hook:
+
+1. Detects computed field dependencies from the schema
+2. Watches for changes in dependency fields
+3. Calls draft API on blur (after validation passes)
+4. Updates computed field values from API response
+
+```typescript
+// Example: Discount is computed from MRP and Price
+// When Price or MRP changes and blurs, draft API is called
+// Backend returns new Discount value which is auto-applied
+
+// Computed fields are read-only
+<Input
+  value={form.watch("Discount")}
+  readOnly
+  disabled
+/>
+```
+
+### draftOnEveryChange Option
+
+- `false` (default): Draft API only called when computed field dependencies change
+- `true`: Draft API called for any field change (useful for complex server-side logic)
+
+## Validation
+
+### Client-side Validation
+
+The hook automatically generates validation rules from the schema:
+- Required field validation
+- Type-specific validation (number, date, etc.)
+- Expression-based validation rules
+
+### Cross-field Validation
+
+Cross-field validation rules are executed on form submission:
+
+```typescript
+// Cross-field errors appear in form.formState.errors.root
+{form.formState.errors.root && (
+  <div className="error">
+    {Object.values(form.formState.errors.root).map((err) => (
+      <p>{err.message}</p>
+    ))}
+  </div>
+)}
+```
+
+## Schema Structure
+
+### ProcessedField
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Field name |
+| `type` | `string` | HTML input type |
+| `label` | `string` | Display label |
+| `required` | `boolean` | Is required |
+| `computed` | `boolean` | Is computed |
+| `defaultValue` | `any` | Default value |
+| `options` | `Array<{value, label}>` | Select options |
+| `description` | `string` | Help text |
+| `permission` | `FieldPermission` | User permissions |
+| `rules` | `object` | Validation/computation rules |
+
+### FieldPermission
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `editable` | `boolean` | Can user edit |
+| `readable` | `boolean` | Can user see |
+| `hidden` | `boolean` | Is completely hidden |
+
+## Key Behaviors
+
+1. **Schema caching**: Schemas are cached for 30 minutes
+2. **Record caching**: Records are cached for 5 minutes
+3. **Auto-reset on create**: Form resets after successful create
+4. **Draft API debouncing**: Draft calls are debounced by 300ms
+5. **Computed field exclusion**: Computed fields are excluded from submission
+6. **Type-safe registration**: `register` is fully typed with Path<T>
+7. **Enhanced onBlur**: Custom onBlur triggers validation + computation
+
+## Architecture Notes
+
+- Built on react-hook-form for form state management
+- Uses TanStack Query for schema and record fetching
+- Expression validator for backend rule evaluation
+- Optimized dependency tracking for computed fields
+- Stable callback refs to prevent infinite loops
+- Full TypeScript generics support