react-form-manage 1.0.8-beta.9 → 1.0.8

package/src/DEEP_TRIGGER_LOGIC.md

@@ -0,0 +1,573 @@
+# Deep Trigger Set Value - Logic Chi Tiết
+
+## Tổng Quan
+
+`handleDeepTriggerSet` là hàm thực thi việc set value và trigger listener một cách đệ quy, đảm bảo:
+
+1. **Thứ tự trigger đúng**: Field level → Item/Index level → Property level
+2. **Xử lý nested structures**: Plain objects, arrays, class instances
+3. **Phân biệt listener types**: Array listeners (FormList) vs Non-array listeners
+4. **Handle data cleanup**: Khi phần tử bị xóa khỏi array/object
+
+---
+
+## Quy Tắc Core
+
+### Quy tắc 1: Primitive Values
+
+**Áp dụng:** `string`, `number`, `boolean`, `null`, `undefined`
+
+**Hành động:**
+
+- Tìm listener trên chính field đó
+- Nếu có: gọi `listener.onChange(value)`
+- Nếu không: `setData(formName, name, value)`
+- **DỪNG** - không đệ quy
+
+### Quy tắc 2: Plain Objects
+
+**Áp dụng:** `isPlainObject(value) === true`
+
+**Hành động:**
+
+1. Trigger listener trên chính field đó (nếu có)
+2. Lấy tất cả paths (bao gồm container level): `getAllPathsIncludingContainers(value)`
+3. Đệ quy vào từng path: `coreRecursive(name.path, get(value, path))`
+
+### Quy tắc 3: Arrays với Listener (FormList)
+
+**Áp dụng:** `Array.isArray(value) && listener.type === "array"`
+
+**Hành động:**
+
+1. Gọi `listener.onArrayChange(value)` → FormList mount/unmount items
+2. Với từng phần tử:
+   - Trigger listener trên `name.index` (nếu có)
+   - Đệ quy vào nested paths
+3. Xử lý phần tử bị xóa: trigger undefined đệ quy
+
+### Quy tắc 4: Arrays không có Listener
+
+**Áp dụng:** `Array.isArray(value) && !listener`
+
+**Hành động:**
+
+1. **Set mảng về kích thước mới TRƯỚC**: `setData(formName, name, value)`
+2. Với từng phần tử thay đổi:
+   - Trigger listener trên `name.index` (nếu có)
+   - Đệ quy vào nested paths
+3. Xử lý phần tử bị xóa: trigger undefined đệ quy
+
+### Quy tắc 5: Class Instances
+
+**Áp dụng:** `!isPlainObject(value) && typeof value === "object"`
+
+**Hành động:** Xử lý như primitive (không đệ quy)
+
+---
+
+## Case Studies với Examples
+
+### Case 1: Plain Object → Primitive Listeners
+
+#### Setup:
+
+```typescript
+// Listeners đã đăng ký:
+// - "user" (non-array listener)
+// - "user.name" (primitive)
+// - "user.age" (primitive)
+
+setFieldValue("user", { name: "John", age: 30 });
+```
+
+#### Execution Flow:
+
+```
+deepTriggerSetCore("user", {name: "John", age: 30})
+│
+├─ isPlainObject = true
+│
+└─ handlePlainObject("user", {name: "John", age: 30})
+   │
+   ├─ Step 1: Trigger field-level listener
+   │  └─ user.onChange({name: "John", age: 30}) ✅
+   │
+   ├─ Step 2: Get all paths
+   │  └─ getAllPathsIncludingContainers({name: "John", age: 30})
+   │     └─ ["name", "age"]
+   │
+   └─ Step 3: Recursive into each path
+      │
+      ├─ coreRecursive("user.name", "John")
+      │  └─ handlePrimitiveValue("user.name", "John")
+      │     ├─ user.name.onChange("John") ✅
+      │     └─ setData(formName, "user.name", "John")
+      │
+      └─ coreRecursive("user.age", 30)
+         └─ handlePrimitiveValue("user.age", 30)
+            ├─ user.age.onChange(30) ✅
+            └─ setData(formName, "user.age", 30)
+```
+
+#### Result:
+
+- ✅ "user" listener: `{name: "John", age: 30}`
+- ✅ "user.name" listener: `"John"`
+- ✅ "user.age" listener: `30`
+
+---
+
+### Case 2: Plain Object → Array Listener (FormList) → Primitives
+
+#### Setup:
+
+```typescript
+// Listeners:
+// - "user"
+// - "user.name"
+// - "user.orders" (array listener - FormList)
+// - "user.orders[0]", "user.orders[1]"
+// - "user.orders[0].id", "user.orders[0].product"
+// - "user.orders[1].id", "user.orders[1].product"
+
+setFieldValue("user", {
+  name: "John",
+  orders: [
+    { id: 1, product: "A" },
+    { id: 2, product: "B" },
+  ],
+});
+```
+
+#### Execution Flow:
+
+```
+deepTriggerSetCore("user", {name: "John", orders: [...]})
+│
+└─ handlePlainObject("user", {name: "John", orders: [...]})
+   │
+   ├─ Step 1: Trigger field-level
+   │  └─ user.onChange({name: "John", orders: [...]}) ✅
+   │
+   ├─ Step 2: Get paths
+   │  └─ ["name", "orders", "orders[0]", "orders[0].id", "orders[0].product",
+   │      "orders[1]", "orders[1].id", "orders[1].product"]
+   │
+   └─ Step 3: Recursive
+      │
+      ├─ coreRecursive("user.name", "John")
+      │  └─ user.name.onChange("John") ✅
+      │
+      └─ coreRecursive("user.orders", [{id: 1, ...}, {id: 2, ...}])
+         │
+         └─ handleArrayListener("user.orders", [...])
+            │
+            ├─ Step 3.1: onArrayChange
+            │  └─ user.orders.onArrayChange([...]) ✅
+            │     └─ FormList mounts 2 items
+            │
+            └─ Step 3.2: Process each item
+               │
+               ├─ Item 0:
+               │  ├─ user.orders[0].onChange({id: 1, product: "A"}) ✅
+               │  └─ Recursive nested:
+               │     ├─ coreRecursive("user.orders[0].id", 1)
+               │     │  └─ user.orders[0].id.onChange(1) ✅
+               │     └─ coreRecursive("user.orders[0].product", "A")
+               │        └─ user.orders[0].product.onChange("A") ✅
+               │
+               └─ Item 1: (similar)
+```
+
+#### Result:
+
+- ✅ "user" listener: Full object
+- ✅ "user.name" listener: `"John"`
+- ✅ "user.orders" FormList: Array updated, 2 items mounted
+- ✅ All nested primitive listeners triggered
+
+---
+
+### Case 3: Array Non-Listener → Primitives
+
+#### Setup:
+
+```typescript
+// Listeners:
+// - "tags[0]", "tags[1]" (individual FormItems, NO FormList)
+// NO listener on "tags" itself
+
+setFieldValue("tags", ["javascript", "react"]);
+// Previous: ["vue", "angular", "svelte"]
+```
+
+#### Execution Flow:
+
+```
+deepTriggerSetCore("tags", ["javascript", "react"])
+│
+└─ handleNonListenerArray("tags", ["javascript", "react"])
+   │
+   ├─ previousValues = ["vue", "angular", "svelte"]
+   │
+   ├─ Step 1: Set array to new size FIRST
+   │  └─ setData(formName, "tags", ["javascript", "react"]) ✅
+   │     └─ Watchers of "tags" see array cut: 3 → 2
+   │
+   ├─ Step 2: Process changed items
+   │  │
+   │  ├─ Index 0: "javascript" !== "vue"
+   │  │  ├─ tags[0].onChange("javascript") ✅
+   │  │  └─ No nested paths (primitive)
+   │  │
+   │  └─ Index 1: "react" !== "angular"
+   │     ├─ tags[1].onChange("react") ✅
+   │     └─ No nested paths
+   │
+   └─ Step 3: Process removed items
+      └─ for index = 2 to 2:
+         └─ coreRecursive("tags[2]", undefined)
+            └─ handlePrimitiveValue("tags[2]", undefined)
+               └─ if tags[2] listener exists:
+                  └─ tags[2].onChange(undefined) ✅
+               └─ else:
+                  └─ setData(formName, "tags[2]", undefined) ✅
+```
+
+#### Result:
+
+- ✅ Data "tags": `["javascript", "react"]` (array cut)
+- ✅ Watcher sees new array length
+- ✅ "tags[0]" listener: `"javascript"`
+- ✅ "tags[1]" listener: `"react"`
+- ✅ "tags[2]": `undefined` (data cleaned or listener notified)
+
+---
+
+### Case 4: Plain Object with Removed Fields
+
+#### Setup:
+
+```typescript
+// Previous data: {name: "John", age: 30, city: "NY"}
+// Listeners: "user", "user.name", "user.age", "user.city"
+
+setFieldValue("user", { name: "John", age: 31 });
+// "city" field REMOVED
+```
+
+#### Execution Flow:
+
+```
+deepTriggerSetCore("user", {name: "John", age: 31})
+│
+└─ handlePlainObject("user", {name: "John", age: 31})
+   │
+   ├─ Step 1: Trigger field-level
+   │  └─ user.onChange({name: "John", age: 31}) ✅
+   │     └─ Listener receives NEW object (without city)
+   │
+   ├─ Step 2: Get paths from NEW value
+   │  └─ ["name", "age"]
+   │     └─ ⚠️ "city" NOT included
+   │
+   └─ Step 3: Recursive
+      ├─ coreRecursive("user.name", "John")
+      └─ coreRecursive("user.age", 31) ✅
+```
+
+#### Problem:
+
+- ❌ "user.city" listener NOT triggered
+- ❌ Data "user.city" still has old value "NY"
+
+#### Solution Needed:
+
+Compare previousValue with newValue → detect removed fields → trigger undefined
+
+**Current Status:** ⚠️ NOT HANDLED - Needs fix
+
+---
+
+### Case 5: Array Listener (FormList) with Removed Items
+
+#### Setup:
+
+```typescript
+// Previous: [{id: 1}, {id: 2}, {id: 3}]
+// Listeners:
+// - "items" (array listener - FormList)
+// - "items[0].id", "items[1].id", "items[2].id"
+
+setFieldValue("items", [{ id: 1 }]);
+// items[1], items[2] REMOVED
+```
+
+#### Execution Flow:
+
+```
+deepTriggerSetCore("items", [{id: 1}])
+│
+└─ handleArrayListener("items", [{id: 1}])
+   │
+   ├─ currentValue = [{id: 1}, {id: 2}, {id: 3}]
+   │
+   ├─ Step 1: onArrayChange
+   │  └─ items.onArrayChange([{id: 1}]) ✅
+   │     └─ FormList unmounts items[1], items[2]
+   │     └─ Listeners "items[1].id", "items[2].id" REVOKED
+   │
+   ├─ Step 2: Process remaining items
+   │  └─ items[0]:
+   │     ├─ items[0].onChange({id: 1}) ✅
+   │     └─ items[0].id.onChange(1) ✅
+   │
+   └─ Step 3: Process removed items
+      └─ for index = 1 to 2:
+         └─ coreRecursive("items[1]", undefined)
+            └─ handlePrimitiveValue("items[1]", undefined)
+               └─ listener = getListeners("items[1]")
+                  └─ NOT FOUND (already revoked)
+                  └─ setData(formName, "items[1]", undefined) ✅
+```
+
+#### Result:
+
+- ✅ FormList unmounts items[1], items[2]
+- ✅ Listeners revoked
+- ✅ Data cleaned with undefined
+- ✅ External watchers (if any) receive undefined
+
+---
+
+### Case 6: Array Non-Listener → Nested Array Listener Removed
+
+#### Setup:
+
+```typescript
+// Previous: [
+//   {id: 1, tags: ["a", "b"]},  // tags is FormList
+//   {id: 2, tags: ["c", "d"]}   // ← REMOVED
+// ]
+// Listeners:
+// - "data[0].tags", "data[1].tags" (array listeners)
+// - "data[0].tags[0]", "data[0].tags[1]"
+// - "data[1].tags[0]", "data[1].tags[1]"
+
+setFieldValue("data", [{ id: 1, tags: ["a", "b"] }]);
+```
+
+#### Execution Flow:
+
+```
+deepTriggerSetCore("data", [{id: 1, tags: ["a", "b"]}])
+│
+└─ handleNonListenerArray("data", [{id: 1, tags: ["a", "b"]}])
+   │
+   ├─ Step 1: Set array to new size
+   │  └─ setData(formName, "data", [{id: 1, tags: [...]}]) ✅
+   │
+   ├─ Step 2: Process data[0]
+   │  ├─ data[0].onChange({id: 1, tags: [...]}) ✅
+   │  └─ Recursive nested:
+   │     ├─ coreRecursive("data[0].id", 1) ✅
+   │     └─ coreRecursive("data[0].tags", ["a", "b"])
+   │        └─ handleArrayListener("data[0].tags", [...])
+   │           ├─ data[0].tags.onArrayChange([...]) ✅
+   │           └─ Recursive items... ✅
+   │
+   └─ Step 3: Process removed items
+      └─ coreRecursive("data[1]", undefined)
+         └─ handlePrimitiveValue("data[1]", undefined)
+            ├─ data[1].onChange(undefined) ✅ (if exists)
+            └─ setData(formName, "data[1]", undefined) ✅
+```
+
+#### Problem:
+
+- ❌ `data[1].tags` (nested array listener) NOT triggered
+- ❌ `data[1].tags[0]`, `data[1].tags[1]` NOT triggered
+- **Root cause:** `coreRecursive("data[1]", undefined)` only handles primitive
+  - Does NOT recurse into nested paths of OLD value
+
+#### Solution Needed:
+
+When triggering undefined for removed items, must recurse into nested paths of **previousValue**
+
+**Current Status:** ⚠️ NOT HANDLED - Needs fix
+
+---
+
+## Edge Cases Summary
+
+### ✅ Handled Correctly:
+
+1. Plain object → primitives
+2. Plain object → array listener (FormList) → primitives
+3. Array non-listener → primitives
+4. Array listener with removed items (FormList auto-cleanup)
+5. Deep nesting with multiple array listeners
+
+### ⚠️ Needs Fix:
+
+1. **Plain object with removed fields**
+   - Fields removed from object not triggered with undefined
+   - Solution: Compare previousValue, detect removed keys, trigger undefined
+
+2. **Array non-listener with nested array listeners removed**
+   - Nested FormLists in removed items not triggered
+   - Solution: When triggering undefined for removed item, recurse into its nested structure using previousValue
+
+---
+
+## Implementation Notes
+
+### Key Functions:
+
+- `handlePrimitiveValue`: Terminal handler for primitives
+- `handlePlainObject`: Handles plain objects, triggers field-level then recurses
+- `handleArrayListener`: Handles FormList arrays, calls onArrayChange then recurses
+- `handleNonListenerArray`: Handles non-FormList arrays, sets data then recurses
+- `deepTriggerSetCore`: Core router, dispatches to appropriate handler
+
+### Important Utilities:
+
+- `getAllPathsIncludingContainers(value)`: Returns ALL paths including intermediate containers
+  - Example: `{user: {profile: {age: 30}}}` → `["user", "user.profile", "user.profile.age"]`
+- `getAllNoneObjStringPath(value)`: Returns only leaf paths (primitives)
+  - Example: Same object → `["user.profile.age"]`
+
+### Data vs Listener Separation:
+
+- **setData**: Updates store data only
+- **listener.onChange**: Triggers listener callback (may cause re-render)
+- **revokeListener**: Removes listener from store (happens on FormItem unmount)
+- **setFieldValue**: Should update data AND trigger listeners appropriately
+
+---
+
+## TODO: Fixes Required
+
+### Fix 1: Handle Removed Object Fields
+
+```typescript
+// In handlePlainObject, after recursive:
+const previousValue = getFieldValue(name);
+if (isPlainObject(previousValue)) {
+  const previousKeys = Object.keys(previousValue);
+  const newKeys = Object.keys(value);
+  const removedKeys = previousKeys.filter((k) => !newKeys.includes(k));
+
+  removedKeys.forEach((key) => {
+    if (coreRecursive) {
+      coreRecursive(`${name}.${key}`, undefined, options);
+    }
+  });
+}
+```
+
+### Fix 2: Handle Removed Array Items with Nested Structures
+
+```typescript
+// In handleNonListenerArray, when processing removed items:
+// Instead of just: coreRecursive(itemName, undefined)
+// Should get nested paths from previousValue[index] and recurse each
+
+if (previousValues.length > value.length) {
+  for (let index = value.length; index < previousValues.length; index++) {
+    const itemName = `${name}.${index}`;
+    const removedItem = previousValues[index];
+
+    // Get all nested paths from REMOVED item
+    const nestedPaths = getAllPathsIncludingContainers(removedItem);
+
+    // Trigger undefined for each nested path
+    nestedPaths.forEach((p) => {
+      if (coreRecursive) {
+        coreRecursive(`${itemName}.${p}`, undefined, options);
+      }
+    });
+
+    // Also trigger for the item itself
+    coreRecursive(itemName, undefined, options);
+  }
+}
+```
+
+---
+
+## Testing Scenarios
+
+### Scenario 1: Deep Nesting
+
+```typescript
+setFieldValue("company", {
+  name: "Acme",
+  departments: [
+    {
+      name: "Engineering",
+      teams: [
+        { name: "Frontend", members: ["Alice", "Bob"] },
+        { name: "Backend", members: ["Charlie"] },
+      ],
+    },
+  ],
+});
+```
+
+Expected: All listeners at every level triggered in correct order
+
+### Scenario 2: Complex Removal
+
+```typescript
+// From 3 departments to 1
+setFieldValue("company.departments", [
+  {name: "Engineering", teams: [...]}
+]);
+```
+
+Expected:
+
+- departments[1], departments[2] cleaned
+- All nested teams/members listeners notified
+
+### Scenario 3: Mixed Structures
+
+```typescript
+setFieldValue("config", {
+  settings: { key: "value" },
+  items: [{ id: 1 }],
+  flags: ["a", "b"],
+  metadata: new Date(), // class instance
+});
+```
+
+Expected: Each type handled correctly per rules
+
+---
+
+## Performance Considerations
+
+While performance is not the primary concern (setFieldValue is not called continuously), the implementation should still be reasonable:
+
+1. **Listener Lookup**: O(n) where n = number of listeners
+   - Could optimize with Map if needed
+2. **Path Collection**: O(m) where m = object/array depth
+   - Unavoidable for complete traversal
+3. **Recursive Calls**: Depth-first traversal
+   - Stack depth = nesting depth
+   - Should handle typical form structures (< 10 levels)
+
+---
+
+## Conclusion
+
+The deep trigger logic ensures complete and correct propagation of value changes through nested form structures. The key principles are:
+
+1. **Top-down triggering**: Field level first, then nested
+2. **Recursive by design**: Each level handled independently
+3. **Listener-aware**: Different handling for FormList vs regular fields
+4. **Cleanup on removal**: Removed data properly cleaned and notified
+
+The remaining edge cases (removed object fields, nested array listeners in removed items) need to be addressed for complete correctness.

package/src/components/Form/FormCleanUp.tsx

@@ -1,20 +1,16 @@
 import { useEffect } from "react";
 import { useShallow } from "zustand/react/shallow";
-import {
-  useFormCleanUp,
-  useFormListeners,
-  useFormStore,
-} from "../../stores/formStore";
+import { useFormStore } from "../../stores/formStore";
 
 const FormCleanUp = () => {
-  const { cleanUpStack, clearCleanUpStack } = useFormCleanUp(
+  const { cleanUpStack, clearCleanUpStack } = useFormStore(
     useShallow((state) => ({
       cleanUpStack: state.cleanUpStack,
       clearCleanUpStack: state.clearCleanUpStack,
     })),
   );
 
-  const { revokeListener } = useFormListeners(
+  const { revokeListener } = useFormStore(
     useShallow((state) => ({
       revokeListener: state.revokeListener,
     })),
@@ -42,7 +38,7 @@ const FormCleanUp = () => {
           });
         } else {
           if (c.type === "array") {
-            console.log(c);
+            // console.log(c);
             clearArrItem(c.formName, c.name);
           } else {
           }