@ram_28/kf-ai-sdk 1.0.18 → 1.0.20

package/docs/useForm.md

@@ -1,207 +1,48 @@
 # useForm
 
-## Brief Description
+Form state management with automatic schema validation, computed fields, and react-hook-form integration.
 
-- Integrates react-hook-form with backend Business Data Object (BDO) schemas for automatic validation and computed field handling
-- Fetches schema metadata from the API and generates validation rules, default values, and field permissions automatically
-- Supports both create and update operations with automatic draft API calls for server-side computed fields
-- Provides flattened state accessors (`errors`, `isValid`, `isDirty`) alongside react-hook-form's standard methods
-
-## Type Reference
+## Imports
 
 ```typescript
-import { useForm } from "@ram_28/kf-ai-sdk/form";
-import type {
-  // Core types
-  UseFormOptionsType,
-  UseFormReturnType,
-  FormOperationType,
-  FormModeType,
-
-  // Form field configuration
-  FormFieldConfigType,
-  FormSchemaConfigType,
-  FormFieldTypeType,
-  SelectOptionType,
-  FieldPermissionType,
-
-  // Result types
-  FieldValidationResultType,
-  SubmissionResultType,
-
-  // BDO Schema types (advanced)
-  BDOSchemaType,
-  BDOFieldDefinitionType,
-  SchemaValidationRuleType,
-} from "@ram_28/kf-ai-sdk/form/types";
-
-// Error utilities
 import {
+  useForm,
   parseApiError,
   isNetworkError,
   isValidationError,
   clearFormCache,
 } from "@ram_28/kf-ai-sdk/form";
-
-// Re-exported from react-hook-form (available from SDK)
 import type {
-  UseFormRegister,
   FieldErrors,
-  FormState,
-  Path,
-  PathValue,
-} from "@ram_28/kf-ai-sdk/form.types";
-
-// FieldErrors type from react-hook-form
-// Maps field names to their error objects (message, type, etc.)
-// Used in handleSubmit's onError callback for validation errors
-type FieldErrors<T> = {
-  [K in keyof T]?: {
-    type: string;
-    message?: string;
-    ref?: React.RefObject<any>;
-  };
-} & {
-  root?: Record<string, { type: string; message?: string }>; // Cross-field errors
-};
-
-// FormState type from react-hook-form
-// Contains all form state information
-interface FormState<T> {
-  isDirty: boolean; // Form has been modified
-  isValid: boolean; // All validations pass
-  isSubmitting: boolean; // Form is being submitted
-  isSubmitted: boolean; // Form has been submitted at least once
-  isSubmitSuccessful: boolean; // Last submission was successful
-  isLoading: boolean; // Form is loading async default values
-  isValidating: boolean; // Form is validating
-  submitCount: number; // Number of times form was submitted
-  errors: FieldErrors<T>; // Current validation errors
-  touchedFields: Partial<Record<keyof T, boolean>>; // Fields that have been touched
-  dirtyFields: Partial<Record<keyof T, boolean>>; // Fields that have been modified
-}
-
-// Form operation type
-type FormOperationType = "create" | "update";
-
-// Form field input types
-type FormFieldTypeType =
-  | "text"
-  | "number"
-  | "email"
-  | "password"
-  | "date"
-  | "datetime-local"
-  | "checkbox"
-  | "select"
-  | "textarea"
-  | "reference";
-
-// Select option for dropdown fields
-interface SelectOptionType {
-  value: any;
-  label: string;
-}
+  UseFormOptionsType,
+  UseFormReturnType,
+} from "@ram_28/kf-ai-sdk/form/types";
+```
 
-// Field permission for current user
-interface FieldPermissionType {
-  editable: boolean;
-  readable: boolean;
-  hidden: boolean;
-}
+## Product Class Pattern
 
-// Field rule IDs by category
-interface FieldRuleIdsType {
-  validation: string[];
-  computation: string[];
-  businessLogic: string[];
-}
+The recommended pattern uses a role-based BDO wrapper class (like `Product`) instead of hardcoded source strings:
 
-// Form field configuration for rendering
-interface FormFieldConfigType {
-  name: string;
-  type: FormFieldTypeType;
-  label: string;
-  required: boolean;
-  computed: boolean;
-  defaultValue?: any;
-  options?: SelectOptionType[];
-  validation: any;
-  description?: string;
-  _bdoField: BDOFieldDefinitionType;
-  permission: FieldPermissionType;
-  rules: FieldRuleIdsType;
-}
+```tsx
+// sources/Product.ts - Role-based BDO wrapper
+import { Role, Roles } from "./roles";
 
-// Form schema configuration after processing
-interface FormSchemaConfigType {
-  fields: Record<string, FormFieldConfigType>;
-  fieldOrder: string[];
-  computedFields: string[];
-  requiredFields: string[];
-  crossFieldValidation: SchemaValidationRuleType[];
-  rules: {
-    validation: Record<string, SchemaValidationRuleType>;
-    computation: Record<string, SchemaValidationRuleType>;
-    businessLogic: Record<string, SchemaValidationRuleType>;
-  };
-  fieldRules: Record<string, FieldRuleIdsType>;
-  rolePermissions?: Record<string, RolePermissionType>;
-}
+export type ProductType<TRole extends Role> = /* role-mapped types */;
 
-// BDO field definition structure
-interface BDOFieldDefinitionType {
-  Id: string;
-  Name: string;
-  Type:
-    | "String"
-    | "Number"
-    | "Boolean"
-    | "Date"
-    | "DateTime"
-    | "Reference"
-    | "Array"
-    | "Object";
-  Required?: boolean;
-  Unique?: boolean;
-  DefaultValue?: DefaultValueExpressionType;
-  Formula?: ComputedFieldFormulaType;
-  Computed?: boolean;
-  Validation?: string[] | SchemaValidationRuleType[];
-  Values?: FieldOptionsConfigType;
-  Description?: string;
+export class Product<TRole extends Role = typeof Roles.Admin> {
+  constructor(_role: TRole) {}
+  get _id(): string { return "BDO_AmazonProductMaster"; }
+  // API methods: list, get, create, update, delete, draft, etc.
 }
+```
 
-// BDO schema structure
-interface BDOSchemaType {
-  Id: string;
-  Name: string;
-  Kind: "BusinessObject";
-  Description: string;
-  Rules: {
-    Computation?: Record<string, SchemaValidationRuleType>;
-    Validation?: Record<string, SchemaValidationRuleType>;
-    BusinessLogic?: Record<string, SchemaValidationRuleType>;
-  };
-  Fields: Record<string, BDOFieldDefinitionType>;
-  RolePermission: Record<string, RolePermissionType>;
-  Roles: Record<string, { Name: string; Description: string }>;
-}
+This pattern provides type-safe role-based field access, consistent with `useTable` and other hooks.
 
-// Field validation result
-interface FieldValidationResultType<T = Record<string, any>> {
-  isValid: boolean;
-  message?: string;
-  fieldName?: keyof T;
-}
+## Type Definitions
 
-// Form submission result
-interface SubmissionResultType {
-  success: boolean;
-  data?: any;
-  error?: Error;
-  recordId?: string;
-}
+```typescript
+// Form operation type
+type FormOperationType = "create" | "update";
 
 // Hook options
 interface UseFormOptionsType<T> {
@@ -212,61 +53,30 @@ interface UseFormOptionsType<T> {
   mode?: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all";
   enabled?: boolean;
   userRole?: string;
-  schema?: BDOSchemaType;
-  onSchemaError?: (error: Error) => void; // Schema loading errors only
+  onSchemaError?: (error: Error) => void;
 }
 
 // Hook return type
 interface UseFormReturnType<T> {
   // React Hook Form methods
   register: UseFormRegister<T>;
-  /**
-   * handleSubmit follows RHF pattern with optional callbacks:
-   * - onSuccess: Called with API response data on successful submission
-   * - onError: Called with FieldErrors (validation) or Error (API failure)
-   *
-   * Usage:
-   *   form.handleSubmit()                    // No callbacks
-   *   form.handleSubmit(onSuccess)           // Success only
-   *   form.handleSubmit(onSuccess, onError)  // Both callbacks
-   *   form.handleSubmit(undefined, onError)  // Error only
-   */
-  handleSubmit: (
-    onSuccess?: (data: T, e?: React.FormEvent) => void | Promise<void>,
-    onError?: (
-      error: FieldErrors<T> | Error,
-      e?: React.FormEvent,
-    ) => void | Promise<void>,
-  ) => (e?: React.FormEvent) => Promise<void>;
-  watch: <K extends Path<T>>(
-    name?: K,
-  ) => K extends Path<T> ? PathValue<T, K> : T;
-  setValue: <K extends Path<T>>(name: K, value: PathValue<T, K>) => void;
-  reset: (values?: T) => void;
-
-  // Flattened state (recommended)
+  handleSubmit: (onSuccess?, onError?) => (e?) => Promise<void>;
+  watch: (name?) => any;
+  setValue: (name, value) => void;
+  reset: (values?) => void;
+
+  // Form state
   errors: FieldErrors<T>;
   isValid: boolean;
   isDirty: boolean;
   isSubmitting: boolean;
   isSubmitSuccessful: boolean;
 
-  // Legacy (backward compatible)
-  formState: FormState<T>;
-
   // Loading states
   isLoadingInitialData: boolean;
   isLoadingRecord: boolean;
   isLoading: boolean;
 
-  // Draft state
-  draftId: string | null;
-  isCreatingDraft: boolean;
-
-  // Error handling
-  loadError: Error | null;
-  hasError: boolean;
-
   // Schema info
   schema: BDOSchemaType | null;
   schemaConfig: FormSchemaConfigType | null;
@@ -274,338 +84,605 @@ interface UseFormReturnType<T> {
   requiredFields: Array<keyof T>;
 
   // Field helpers
-  getField: <K extends keyof T>(fieldName: K) => FormFieldConfigType | null;
+  getField: (fieldName) => FormFieldConfigType | null;
   getFields: () => Record<keyof T, FormFieldConfigType>;
-  hasField: <K extends keyof T>(fieldName: K) => boolean;
-  isFieldRequired: <K extends keyof T>(fieldName: K) => boolean;
-  isFieldComputed: <K extends keyof T>(fieldName: K) => boolean;
-
-  // Operations
-  refreshSchema: () => Promise<void>;
-  validateForm: () => Promise<boolean>;
-  clearErrors: () => void;
+  isFieldRequired: (fieldName) => boolean;
+  isFieldComputed: (fieldName) => boolean;
+}
+
+// Field configuration
+interface FormFieldConfigType {
+  name: string;
+  type:
+    | "text"
+    | "number"
+    | "email"
+    | "date"
+    | "checkbox"
+    | "select"
+    | "textarea";
+  label: string;
+  required: boolean;
+  computed: boolean;
+  defaultValue?: any;
+  options?: { value: any; label: string }[];
+  permission: { editable: boolean; readable: boolean; hidden: boolean };
 }
 ```
 
-## Usage Example
+## Basic Example
+
+A minimal create form with field registration and submission.
 
 ```tsx
-import { useState } from "react";
-import { useTable } from "@ram_28/kf-ai-sdk/table";
 import { useForm } from "@ram_28/kf-ai-sdk/form";
 import type {
   UseFormOptionsType,
   UseFormReturnType,
-  FormOperationType,
-  FormFieldConfigType,
-  FormSchemaConfigType,
-  BDOFieldDefinitionType,
-  BDOSchemaType,
 } from "@ram_28/kf-ai-sdk/form/types";
-import type {
-  UseTableOptionsType,
-  UseTableReturnType,
-  ColumnDefinitionType,
-} from "@ram_28/kf-ai-sdk/table/types";
-import type { FieldErrors } from "@ram_28/kf-ai-sdk/form.types";
 import { Product, ProductType } from "../sources";
 import { Roles } from "../sources/roles";
 
-// Get the typed product for the Seller role (who can create/update products)
 type SellerProduct = ProductType<typeof Roles.Seller>;
 
-function ProductManagementPage() {
-  // Instantiate the Product source with role
+function CreateProductForm() {
   const product = new Product(Roles.Seller);
 
-  const [showForm, setShowForm] = useState(false);
-  const [selectedProduct, setSelectedProduct] = useState<SellerProduct | null>(
-    null,
-  );
-  const [formMode, setFormMode] = useState<FormOperationType>("create");
-
-  // Table for listing products
-  const table = useTable<SellerProduct>({
-    source: product._id,
-    columns: [
-      { fieldId: "Title", label: "Name" },
-      { fieldId: "Price", label: "Price" },
-      { fieldId: "Discount", label: "Discount %" },
-    ],
-    enablePagination: true,
-  });
-
-  // Form configuration with all options
-  const formOptions: UseFormOptionsType<SellerProduct> = {
+  const options: UseFormOptionsType<SellerProduct> = {
     source: product._id,
-    operation: formMode,
-    recordId: selectedProduct?._id,
-    enabled: showForm,
-    mode: "onBlur",
+    operation: "create",
     defaultValues: {
       Title: "",
-      Description: "",
       Price: 0,
-      MRP: 0,
-      Category: "Electronics",
-      Stock: 0,
+      Category: "",
     },
-    onSchemaError: (error: Error) =>
-      console.error("Schema error:", error.message),
   };
 
-  const form: UseFormReturnType<SellerProduct> =
-    useForm<SellerProduct>(formOptions);
+  const form: UseFormReturnType<SellerProduct> = useForm<SellerProduct>(options);
 
-  // Handle form submission with new RHF-style callbacks
-  const onFormSuccess = (data: SellerProduct) => {
-    console.log("Product saved:", data);
-    setShowForm(false);
-    table.refetch();
+  const onSuccess = (data: SellerProduct) => {
+    console.log("Product created:", data);
   };
 
-  const onFormError = (error: FieldErrors<SellerProduct> | Error) => {
-    if (error instanceof Error) {
-      // API error
-      console.error("Submit error:", error.message);
-    } else {
-      // Validation errors (FieldErrors)
-      console.error("Validation errors:", error);
-    }
+  const onError = (error: Error) => {
+    console.error("Failed to create:", error.message);
   };
 
-  // Access processed schema
-  const displaySchemaInfo = () => {
-    const schema: FormSchemaConfigType | null = form.schemaConfig;
-    if (!schema) return null;
+  if (form.isLoading) return <div>Loading form...</div>;
 
-    return (
-      <div className="schema-info">
-        <p>Required: {schema.requiredFields.join(", ")}</p>
-        <p>Computed: {schema.computedFields.join(", ")}</p>
-        <p>Field Order: {schema.fieldOrder.join(", ")}</p>
+  return (
+    <form onSubmit={form.handleSubmit(onSuccess, onError)}>
+      <div>
+        <label>Title</label>
+        <input {...form.register("Title")} />
+        {form.errors.Title && <span>{form.errors.Title.message}</span>}
       </div>
-    );
-  };
 
-  // Render a field using FormFieldConfigType metadata
-  const renderField = (fieldName: keyof SellerProduct) => {
-    const field: FormFieldConfigType | null = form.getField(fieldName);
-    if (!field || field.permission.hidden) return null;
+      <div>
+        <label>Price</label>
+        <input type="number" {...form.register("Price")} />
+        {form.errors.Price && <span>{form.errors.Price.message}</span>}
+      </div>
 
-    const isDisabled = !field.permission.editable || field.computed;
-    const error = form.errors[fieldName];
+      <div>
+        <label>Category</label>
+        <input {...form.register("Category")} />
+      </div>
 
-    return (
-      <div key={field.name} className="form-field">
-        <label htmlFor={field.name}>
-          {field.label}
-          {field.required && <span className="required">*</span>}
-          {field.computed && <span className="computed">(auto)</span>}
-        </label>
-
-        {field.type === "select" && field.options ? (
-          <select
-            id={field.name}
-            disabled={isDisabled}
-            {...form.register(fieldName as any)}
-          >
-            <option value="">Select {field.label}</option>
-            {field.options.map((opt) => (
-              <option key={opt.value} value={opt.value}>
-                {opt.label}
-              </option>
-            ))}
-          </select>
-        ) : field.computed ? (
+      <button type="submit" disabled={form.isSubmitting}>
+        {form.isSubmitting ? "Creating..." : "Create Product"}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## Create vs Update
+
+### Create Form
+
+Initialize a form for creating new records.
+
+```tsx
+import { Product, ProductType } from "../sources";
+import { Roles } from "../sources/roles";
+
+type SellerProduct = ProductType<typeof Roles.Seller>;
+
+function CreateForm() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "create",
+    defaultValues: {
+      Title: "",
+      Price: 0,
+      Stock: 0,
+    },
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit()}>
+      <input {...form.register("Title")} placeholder="Product title" />
+      <input type="number" {...form.register("Price")} placeholder="Price" />
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+### Edit Form
+
+Load existing record data for editing.
+
+```tsx
+function EditForm({ productId }: { productId: string }) {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "update",
+    recordId: productId,
+  });
+
+  if (form.isLoadingRecord) return <div>Loading product...</div>;
+
+  return (
+    <form onSubmit={form.handleSubmit()}>
+      <input {...form.register("Title")} />
+      <input type="number" {...form.register("Price")} />
+      <button type="submit" disabled={!form.isDirty}>
+        Save Changes
+      </button>
+    </form>
+  );
+}
+```
+
+### Toggle Between Create and Edit
+
+Switch form mode based on selection.
+
+```tsx
+function ProductForm({ existingProduct }: { existingProduct?: SellerProduct }) {
+  const product = new Product(Roles.Seller);
+  const isEditing = !!existingProduct;
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: isEditing ? "update" : "create",
+    recordId: existingProduct?._id,
+    defaultValues: existingProduct ?? { Title: "", Price: 0 },
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit()}>
+      <h2>{isEditing ? "Edit Product" : "New Product"}</h2>
+      <input {...form.register("Title")} />
+      <input type="number" {...form.register("Price")} />
+      <button type="submit">{isEditing ? "Update" : "Create"}</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Field Rendering
+
+### Using getField for Metadata
+
+Access field configuration from the schema.
+
+```tsx
+function DynamicField({
+  form,
+  fieldName,
+}: {
+  form: UseFormReturnType<SellerProduct>;
+  fieldName: keyof SellerProduct;
+}) {
+  const field = form.getField(fieldName);
+
+  if (!field || field.permission.hidden) return null;
+
+  const isDisabled = !field.permission.editable || field.computed;
+
+  return (
+    <div className="field">
+      <label>
+        {field.label}
+        {field.required && <span className="required">*</span>}
+        {field.computed && <span className="computed">(auto)</span>}
+      </label>
+
+      {field.type === "select" && field.options ? (
+        <select {...form.register(fieldName)} disabled={isDisabled}>
+          <option value="">Select {field.label}</option>
+          {field.options.map((opt) => (
+            <option key={opt.value} value={opt.value}>
+              {opt.label}
+            </option>
+          ))}
+        </select>
+      ) : (
+        <input
+          type={field.type === "number" ? "number" : "text"}
+          {...form.register(fieldName)}
+          disabled={isDisabled}
+        />
+      )}
+
+      {form.errors[fieldName] && (
+        <span className="error">{form.errors[fieldName]?.message}</span>
+      )}
+    </div>
+  );
+}
+```
+
+### Handling Computed Fields
+
+Display auto-calculated fields as read-only.
+
+```tsx
+function FormWithComputedFields() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "create",
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit()}>
+      <div>
+        <label>MRP</label>
+        <input type="number" {...form.register("MRP")} />
+      </div>
+
+      <div>
+        <label>Price</label>
+        <input type="number" {...form.register("Price")} />
+      </div>
+
+      {/* Discount is computed from MRP and Price */}
+      {form.isFieldComputed("Discount") && (
+        <div>
+          <label>Discount % (auto-calculated)</label>
           <input
-            id={field.name}
-            type={field.type === "number" ? "number" : "text"}
-            value={form.watch(fieldName as any) ?? field.defaultValue ?? ""}
+            type="number"
+            value={form.watch("Discount") ?? 0}
             readOnly
             disabled
           />
-        ) : (
-          <input
-            id={field.name}
-            type={field.type === "number" ? "number" : "text"}
-            disabled={isDisabled}
-            {...form.register(fieldName as any)}
-          />
+        </div>
+      )}
+
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+### Render All Fields Dynamically
+
+Generate form fields from schema configuration.
+
+```tsx
+function DynamicForm() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "create",
+  });
+
+  if (form.isLoading) return <div>Loading...</div>;
+
+  const fields = form.getFields();
+
+  return (
+    <form onSubmit={form.handleSubmit()}>
+      {Object.entries(fields).map(([fieldName, field]) => {
+        if (field.permission.hidden) return null;
+
+        return (
+          <div key={fieldName}>
+            <label>{field.label}</label>
+            <input
+              {...form.register(fieldName as keyof SellerProduct)}
+              type={field.type === "number" ? "number" : "text"}
+              disabled={!field.permission.editable || field.computed}
+            />
+          </div>
+        );
+      })}
+
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Validation
+
+### Displaying Field Errors
+
+Show validation errors inline with fields.
+
+```tsx
+function FormWithValidation() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "create",
+    mode: "onBlur", // Validate on blur
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit()}>
+      <div className={form.errors.Title ? "field-error" : ""}>
+        <label>Title *</label>
+        <input {...form.register("Title")} />
+        {form.errors.Title && (
+          <span className="error-message">{form.errors.Title.message}</span>
         )}
+      </div>
 
-        {error && <span className="error">{error.message as string}</span>}
+      <div className={form.errors.Price ? "field-error" : ""}>
+        <label>Price *</label>
+        <input type="number" {...form.register("Price")} />
+        {form.errors.Price && (
+          <span className="error-message">{form.errors.Price.message}</span>
+        )}
       </div>
-    );
-  };
 
-  // Access raw BDO schema
-  const displayRawSchema = () => {
-    const schema: BDOSchemaType | null = form.schema;
-    if (!schema) return null;
+      <button type="submit" disabled={!form.isValid}>
+        Submit
+      </button>
+    </form>
+  );
+}
+```
 
-    return (
-      <details>
-        <summary>Raw Schema: {schema.Name}</summary>
-        <ul>
-          {Object.entries(schema.Fields).map(
-            ([fieldName, field]: [string, BDOFieldDefinitionType]) => (
-              <li key={fieldName}>
-                {field.Name || fieldName} ({field.Type})
-                {field.Required && " - Required"}
-                {field.Computed && " - Computed"}
-              </li>
-            ),
-          )}
-        </ul>
-      </details>
-    );
+### Form State Indicators
+
+Show form status to users.
+
+```tsx
+function FormWithStateIndicators() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "update",
+    recordId: "PROD-001",
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit()}>
+      {/* Form fields */}
+      <input {...form.register("Title")} />
+      <input type="number" {...form.register("Price")} />
+
+      {/* Status bar */}
+      <div className="form-status">
+        {form.isDirty && <span className="unsaved">Unsaved changes</span>}
+        {!form.isValid && <span className="invalid">Please fix errors</span>}
+        {form.isSubmitting && <span className="saving">Saving...</span>}
+        {form.isSubmitSuccessful && <span className="success">Saved!</span>}
+      </div>
+
+      <button type="submit" disabled={form.isSubmitting || !form.isDirty}>
+        Save Changes
+      </button>
+
+      <button
+        type="button"
+        onClick={() => form.reset()}
+        disabled={!form.isDirty}
+      >
+        Discard Changes
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## Submission
+
+### Handle Submit with Callbacks
+
+Process successful submissions and errors.
+
+```tsx
+function FormWithCallbacks() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "create",
+  });
+
+  const onSuccess = (data: SellerProduct) => {
+    alert(`Product "${data.Title}" created successfully!`);
+    form.reset();
   };
 
-  // Check field properties using helpers
-  const checkFieldStatus = () => {
-    console.log("Is Title required?", form.isFieldRequired("Title"));
-    console.log("Is Discount computed?", form.isFieldComputed("Discount"));
-    console.log("Has Category field?", form.hasField("Category"));
-    console.log("All computed fields:", form.computedFields);
-    console.log("All required fields:", form.requiredFields);
+  const onError = (error: FieldErrors<SellerProduct> | Error) => {
+    if (error instanceof Error) {
+      // API error
+      alert(`Server error: ${error.message}`);
+    } else {
+      // Validation errors
+      const fieldNames = Object.keys(error).join(", ");
+      alert(`Please fix errors in: ${fieldNames}`);
+    }
   };
 
-  // Handle form submission - use the new RHF-style API
-  // Note: form.handleSubmit returns a function that handles preventDefault internally
+  return (
+    <form onSubmit={form.handleSubmit(onSuccess, onError)}>
+      <input {...form.register("Title")} placeholder="Title" />
+      <input type="number" {...form.register("Price")} placeholder="Price" />
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+### Programmatic Submission
 
-  // Open create form
-  const handleCreate = () => {
-    setFormMode("create");
-    setSelectedProduct(null);
-    setShowForm(true);
-  };
+Submit form without a submit button.
+
+```tsx
+function FormWithProgrammaticSubmit() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "create",
+  });
+
+  const handleSaveAndClose = async () => {
+    const submitHandler = form.handleSubmit(
+      (data) => {
+        console.log("Saved:", data);
+        // Close modal or navigate away
+      },
+      (error) => {
+        console.error("Validation failed:", error);
+      },
+    );
 
-  // Open edit form
-  const handleEdit = (productItem: SellerProduct) => {
-    setFormMode("update");
-    setSelectedProduct(productItem);
-    setShowForm(true);
+    await submitHandler();
   };
 
   return (
-    <div className="product-management">
-      <h1>Products</h1>
-      <button onClick={handleCreate}>Add Product</button>
-
-      {/* Product Table */}
-      <table>
-        <thead>
-          <tr>
-            <th>Title</th>
-            <th>Price</th>
-            <th>Discount</th>
-            <th>Actions</th>
-          </tr>
-        </thead>
-        <tbody>
-          {table.rows.map((row: SellerProduct) => (
-            <tr key={row._id}>
-              <td>{row.Title}</td>
-              <td>${row.Price.toFixed(2)}</td>
-              <td>{row.Discount}%</td>
-              <td>
-                <button onClick={() => handleEdit(row)}>Edit</button>
-              </td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-
-      {/* Form Dialog */}
-      {showForm && (
-        <dialog open>
-          {form.isLoadingInitialData ? (
-            <div>Loading form...</div>
-          ) : form.loadError ? (
-            <div>
-              <p>Error: {form.loadError.message}</p>
-              <button onClick={() => form.refreshSchema()}>Retry</button>
-            </div>
-          ) : (
-            <form onSubmit={form.handleSubmit(onFormSuccess, onFormError)}>
-              <h2>
-                {formMode === "create" ? "Create Product" : "Edit Product"}
-              </h2>
-
-              {/* Schema Info */}
-              {displaySchemaInfo()}
-
-              {/* Form Fields */}
-              {renderField("Title")}
-              {renderField("Description")}
-              {renderField("MRP")}
-              {renderField("Price")}
-              {renderField("Discount")}
-              {renderField("Category")}
-              {renderField("Stock")}
-
-              {/* Form Status */}
-              <div className="form-status">
-                {form.isDirty && <span>Unsaved changes</span>}
-                {!form.isValid && <span>Please fix validation errors</span>}
-              </div>
-
-              {/* Cross-field validation errors */}
-              {form.errors.root && (
-                <div className="cross-field-errors">
-                  {Object.values(form.errors.root).map((err, i) => (
-                    <p key={i} className="error">
-                      {(err as any).message}
-                    </p>
-                  ))}
-                </div>
-              )}
-
-              {/* Note: Submit errors are now handled via onError callback */}
-
-              {/* Raw Schema Debug */}
-              {displayRawSchema()}
-
-              {/* Form Actions */}
-              <div className="form-actions">
-                <button type="button" onClick={() => setShowForm(false)}>
-                  Cancel
-                </button>
-                <button type="button" onClick={() => form.reset()}>
-                  Reset
-                </button>
-                <button type="button" onClick={() => form.validateForm()}>
-                  Validate
-                </button>
-                <button
-                  type="submit"
-                  disabled={form.isSubmitting || form.isLoading}
-                >
-                  {form.isSubmitting
-                    ? "Saving..."
-                    : formMode === "create"
-                      ? "Create"
-                      : "Update"}
-                </button>
-              </div>
-
-              {/* Watch specific fields */}
-              <div className="field-preview">
-                <p>Current Price: ${form.watch("Price")}</p>
-                <p>Current Discount: {form.watch("Discount")}%</p>
-              </div>
-            </form>
-          )}
-        </dialog>
-      )}
+    <div>
+      <input {...form.register("Title")} />
+      <input type="number" {...form.register("Price")} />
+
+      <div className="actions">
+        <button type="button" onClick={() => form.reset()}>
+          Cancel
+        </button>
+        <button type="button" onClick={handleSaveAndClose}>
+          Save & Close
+        </button>
+      </div>
     </div>
   );
 }
 ```
 
+---
+
+## Watch and setValue
+
+### Watch Field Values
+
+React to field value changes in real-time.
+
+```tsx
+function FormWithWatcher() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "create",
+  });
+
+  const mrp = form.watch("MRP");
+  const price = form.watch("Price");
+  const discount = mrp > 0 ? (((mrp - price) / mrp) * 100).toFixed(1) : 0;
+
+  return (
+    <form onSubmit={form.handleSubmit()}>
+      <div>
+        <label>MRP</label>
+        <input type="number" {...form.register("MRP")} />
+      </div>
+
+      <div>
+        <label>Price</label>
+        <input type="number" {...form.register("Price")} />
+      </div>
+
+      <div className="preview">
+        <p>Discount: {discount}%</p>
+        <p>You save: ${(mrp - price).toFixed(2)}</p>
+      </div>
+
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+### Set Field Values Programmatically
+
+Update field values from external actions.
+
+```tsx
+function FormWithSetValue() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "create",
+  });
+
+  const applyTemplate = (template: string) => {
+    switch (template) {
+      case "electronics":
+        form.setValue("Category", "Electronics");
+        form.setValue("Price", 99.99);
+        break;
+      case "books":
+        form.setValue("Category", "Books");
+        form.setValue("Price", 19.99);
+        break;
+    }
+  };
+
+  return (
+    <form onSubmit={form.handleSubmit()}>
+      <div className="templates">
+        <button type="button" onClick={() => applyTemplate("electronics")}>
+          Electronics Template
+        </button>
+        <button type="button" onClick={() => applyTemplate("books")}>
+          Books Template
+        </button>
+      </div>
+
+      <input {...form.register("Title")} placeholder="Title" />
+      <input {...form.register("Category")} placeholder="Category" />
+      <input type="number" {...form.register("Price")} placeholder="Price" />
+
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+---
+
 ## Error Utilities
 
+The SDK provides utilities to help handle and categorize errors from form operations.
+
+### Available Utilities
+
 ```typescript
 import {
   parseApiError,
@@ -613,17 +690,151 @@ import {
   isValidationError,
   clearFormCache,
 } from "@ram_28/kf-ai-sdk/form";
+```
+
+| Utility                    | Description                                                      |
+| -------------------------- | ---------------------------------------------------------------- |
+| `parseApiError(error)`     | Extracts a user-friendly message from any error type             |
+| `isNetworkError(error)`    | Returns `true` if error is network-related (connection, timeout) |
+| `isValidationError(error)` | Returns `true` if error is a validation/schema error             |
+| `clearFormCache()`         | Clears the schema cache (30-minute TTL by default)               |
+
+### Parse and Handle API Errors
+
+Use built-in utilities for comprehensive error handling.
+
+```tsx
+import {
+  parseApiError,
+  isNetworkError,
+  isValidationError,
+  clearFormCache,
+} from "@ram_28/kf-ai-sdk/form";
+
+function FormWithErrorHandling() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "create",
+  });
+
+  const onError = (error: Error) => {
+    const message = parseApiError(error);
 
-// Parse API error to user-friendly message
-const message = parseApiError(error); // "Failed to save: Invalid data"
+    if (isNetworkError(error)) {
+      alert("Network error. Please check your connection.");
+    } else if (isValidationError(error)) {
+      alert("Validation failed. Please check your input.");
+    } else {
+      alert(message);
+    }
+  };
+
+  const handleClearCache = () => {
+    clearFormCache();
+    window.location.reload();
+  };
+
+  return (
+    <form onSubmit={form.handleSubmit(undefined, onError)}>
+      {/* form fields */}
+      <button type="submit">Save</button>
+      <button type="button" onClick={handleClearCache}>
+        Clear Cache & Reload
+      </button>
+    </form>
+  );
+}
+```
+
+### Handling Different Error Types
+
+The `handleSubmit` callback receives different error types depending on the failure stage:
+
+```tsx
+function FormWithDetailedErrorHandling() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "create",
+  });
+
+  const onSubmit = (data: SellerProduct) => {
+    console.log("Success:", data);
+  };
+
+  const onError = (
+    error: FieldErrors<SellerProduct> | Error,
+    event?: React.BaseSyntheticEvent,
+  ) => {
+    // Check if it's a validation error (from react-hook-form)
+    if (!(error instanceof Error)) {
+      // Field validation errors - error is FieldErrors<SellerProduct>
+      const invalidFields = Object.keys(error);
+      console.log("Validation failed for fields:", invalidFields);
+
+      // Access specific field errors
+      if (error.Title) {
+        console.log("Title error:", error.Title.message);
+      }
+      return;
+    }
 
-// Check error type for specific handling
-if (isNetworkError(error)) {
-  showOfflineMessage();
-} else if (isValidationError(error)) {
-  showValidationErrors();
+    // API/Network error - error is Error
+    if (isNetworkError(error)) {
+      // Handle offline, timeout, connection refused
+      console.error("Network issue:", error.message);
+    } else if (isValidationError(error)) {
+      // Server-side validation error
+      console.error("Server validation:", parseApiError(error));
+    } else {
+      // Other server errors (500, etc.)
+      console.error("Server error:", parseApiError(error));
+    }
+  };
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit, onError)}>
+      {/* form fields */}
+    </form>
+  );
 }
+```
+
+### Schema Loading Errors
+
+Handle errors when the form schema fails to load.
+
+```tsx
+function FormWithSchemaErrorHandling() {
+  const product = new Product(Roles.Seller);
+
+  const form = useForm<SellerProduct>({
+    source: product._id,
+    operation: "create",
+    onSchemaError: (error) => {
+      console.error("Failed to load form schema:", error.message);
+      // Optionally clear cache and retry
+      clearFormCache();
+    },
+  });
 
-// Clear form schema cache (useful after schema changes)
-clearFormCache();
+  // Check for load errors
+  if (form.loadError) {
+    return (
+      <div className="error-state">
+        <p>Failed to load form: {form.loadError.message}</p>
+        <button onClick={() => window.location.reload()}>Retry</button>
+      </div>
+    );
+  }
+
+  if (form.isLoading) {
+    return <div>Loading form...</div>;
+  }
+
+  return <form onSubmit={form.handleSubmit()}>{/* form fields */}</form>;
+}
 ```