cogsbox-state 0.5.471 → 0.5.472

package/src/CogsState.tsx

@@ -80,7 +80,11 @@ export type FormElementParams<T> = StateObject<T> & {
         HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
       >
     ) => void;
-    onBlur?: () => void;
+    onBlur?: (
+      event: React.FocusEvent<
+        HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
+      >
+    ) => void;
   };
 };
 
@@ -243,8 +247,12 @@ export type InsertTypeObj<T> = (payload: InsertParams<T>) => void;
 
 type EffectFunction<T, R> = (state: T, deps: any[]) => R;
 export type EndType<T, IsArrayElement = false> = {
-  $addZodValidation: (errors: ValidationError[]) => void;
+  $addZodValidation: (
+    errors: ValidationError[],
+    source?: 'client' | 'sync_engine' | 'api'
+  ) => void;
   $clearZodValidation: (paths?: string[]) => void;
+  $applyOperation: (operation: UpdateTypeDetail) => void;
   $applyJsonPatch: (patches: any[]) => void;
   $update: UpdateType<T>;
   $_path: string[];
@@ -345,8 +353,9 @@ export type UpdateTypeDetail = {
   oldValue: any;
   newValue: any;
   userId?: number;
+  itemId?: string; // For insert: the new item's ID
+  insertAfterId?: string; // For insert: ID to insert after (null = beginning)
 };
-
 export type ReactivityUnion = 'none' | 'component' | 'deps' | 'all';
 export type ReactivityType =
   | 'none'
@@ -366,8 +375,9 @@ type ValidationOptionsType = {
   key?: string;
   zodSchemaV3?: z3.ZodType<any, any, any>;
   zodSchemaV4?: z4.ZodType<any, any, any>;
-
-  onBlur?: boolean;
+  onBlur?: 'error' | 'warning';
+  onChange?: 'error' | 'warning';
+  blockSync?: boolean;
 };
 type UseSyncType<T> = (state: T, a: SyncOptionsType<any>) => SyncApi;
 type SyncOptionsType<TApiParams> = {
@@ -542,6 +552,7 @@ function setAndMergeOptions(stateKey: string, newOptions: OptionsType<any>) {
     ...newOptions,
   });
 }
+
 function setOptions<StateKey, Opt>({
   stateKey,
   options,
@@ -554,44 +565,62 @@ function setOptions<StateKey, Opt>({
   const initialOptions = getInitialOptions(stateKey as string) || {};
   const initialOptionsPartState = initialOptionsPart[stateKey as string] || {};
 
-  const mergedOptions = { ...initialOptionsPartState, ...initialOptions };
-
+  // Start with the base options
+  let mergedOptions = { ...initialOptionsPartState, ...initialOptions };
   let needToAdd = false;
+
   if (options) {
-    for (const key in options) {
-      if (!mergedOptions.hasOwnProperty(key)) {
-        needToAdd = true;
-        mergedOptions[key] = options[key as keyof typeof options];
-      } else {
-        if (
-          key == 'localStorage' &&
-          options[key] &&
-          mergedOptions[key].key !== options[key]?.key
-        ) {
-          needToAdd = true;
-          mergedOptions[key] = options[key];
-        }
-        if (
-          key == 'defaultState' &&
-          options[key] &&
-          mergedOptions[key] !== options[key] &&
-          !isDeepEqual(mergedOptions[key], options[key])
-        ) {
-          needToAdd = true;
-          mergedOptions[key] = options[key];
+    // A function to recursively merge properties
+    const deepMerge = (target: any, source: any) => {
+      for (const key in source) {
+        if (source.hasOwnProperty(key)) {
+          // If the property is an object (and not an array), recurse
+          if (
+            source[key] instanceof Object &&
+            !Array.isArray(source[key]) &&
+            target[key] instanceof Object
+          ) {
+            // Check for changes before merging to set `needToAdd`
+            if (!isDeepEqual(target[key], source[key])) {
+              deepMerge(target[key], source[key]);
+              needToAdd = true;
+            }
+          } else {
+            // Overwrite if the value is different
+            if (target[key] !== source[key]) {
+              target[key] = source[key];
+              needToAdd = true;
+            }
+          }
         }
       }
-    }
+      return target;
+    };
+
+    // Perform a deep merge
+    mergedOptions = deepMerge(mergedOptions, options);
   }
 
-  // Always preserve syncOptions if it exists in mergedOptions but not in options
+  // Your existing logic for defaults and preservation can follow
   if (
     mergedOptions.syncOptions &&
     (!options || !options.hasOwnProperty('syncOptions'))
   ) {
     needToAdd = true;
   }
+  if (
+    (mergedOptions.validation && mergedOptions?.validation?.zodSchemaV4) ||
+    mergedOptions?.validation?.zodSchemaV3
+  ) {
+    // Only set default if onBlur wasn't explicitly provided
+    const wasOnBlurProvided =
+      options?.validation?.hasOwnProperty('onBlur') ||
+      initialOptions?.validation?.hasOwnProperty('onBlur');
 
+    if (!wasOnBlurProvided) {
+      mergedOptions.validation.onBlur = 'error'; // Default to error on blur
+    }
+  }
   if (needToAdd) {
     setInitialStateOptions(stateKey as string, mergedOptions);
   }
@@ -781,7 +810,8 @@ export function createCogsStateFromSync<
     schemas: Record<
       string,
       {
-        schemas: { defaultValues: any };
+        schemas: { defaults: any };
+        relations?: any;
         api?: {
           queryData?: any;
         };
@@ -795,7 +825,13 @@ export function createCogsStateFromSync<
   useSync: UseSyncType<any>
 ): CogsApi<
   {
-    [K in keyof TSyncSchema['schemas']]: TSyncSchema['schemas'][K]['schemas']['defaultValues'];
+    [K in keyof TSyncSchema['schemas']]: TSyncSchema['schemas'][K]['relations'] extends object
+      ? TSyncSchema['schemas'][K] extends {
+          schemas: { defaults: infer D };
+        }
+        ? D
+        : TSyncSchema['schemas'][K]['schemas']['defaults']
+      : TSyncSchema['schemas'][K]['schemas']['defaults'];
   },
   {
     [K in keyof TSyncSchema['schemas']]: GetParamType<
@@ -810,7 +846,16 @@ export function createCogsStateFromSync<
   // Extract defaultValues AND apiParams from each entry
   for (const key in schemas) {
     const entry = schemas[key];
-    initialState[key] = entry?.schemas?.defaultValues || {};
+
+    // Check if we have relations and thus view defaults
+    if (entry?.relations && entry?.schemas?.defaults) {
+      // Use the view defaults when relations are present
+      initialState[key] = entry.schemas.defaults;
+    } else {
+      // Fall back to regular defaultValues
+      initialState[key] = entry?.schemas?.defaults || {};
+    }
+    console.log('initialState', initialState);
 
     // Extract apiParams from the api.queryData._paramType
     if (entry?.api?.queryData?._paramType) {
@@ -1069,78 +1114,34 @@ function getComponentNotifications(
 
   const componentsToNotify = new Set<any>();
 
-  // --- PASS 1: Notify specific subscribers based on update type ---
-
-  if (result.type === 'update') {
-    // --- Bubble-up Notification ---
-    // An update to `user.address.street` notifies listeners of `street`, `address`, and `user`.
-    let currentPath = [...path];
-    while (true) {
-      const pathMeta = getShadowMetadata(stateKey, currentPath);
-
-      if (pathMeta?.pathComponents) {
-        pathMeta.pathComponents.forEach((componentId: string) => {
-          const component = rootMeta.components?.get(componentId);
-          // NEW: Add component to the set instead of calling forceUpdate()
-          if (component) {
-            const reactiveTypes = Array.isArray(component.reactiveType)
-              ? component.reactiveType
-              : [component.reactiveType || 'component'];
-            if (!reactiveTypes.includes('none')) {
-              componentsToNotify.add(component);
-            }
-          }
-        });
-      }
+  // For insert operations, use the array path not the item path
+  let notificationPath = path;
+  if (result.type === 'insert' && result.itemId) {
+    // We have the new structure with itemId separate
+    notificationPath = path; // Already the array path
+  }
 
-      if (currentPath.length === 0) break;
-      currentPath.pop(); // Go up one level
-    }
+  // BUBBLE UP: Notify components at this path and all parent paths
+  let currentPath = [...notificationPath];
+  while (true) {
+    const pathMeta = getShadowMetadata(stateKey, currentPath);
 
-    // --- Deep Object Change Notification ---
-    // If the new value is an object, notify components subscribed to sub-paths that changed.
-    if (
-      result.newValue &&
-      typeof result.newValue === 'object' &&
-      !isArray(result.newValue)
-    ) {
-      const changedSubPaths = getDifferences(result.newValue, result.oldValue);
-
-      changedSubPaths.forEach((subPathString: string) => {
-        const subPath = subPathString.split('.');
-        const fullSubPath = [...path, ...subPath];
-        const subPathMeta = getShadowMetadata(stateKey, fullSubPath);
-
-        if (subPathMeta?.pathComponents) {
-          subPathMeta.pathComponents.forEach((componentId: string) => {
-            const component = rootMeta.components?.get(componentId);
-            // NEW: Add component to the set
-            if (component) {
-              const reactiveTypes = Array.isArray(component.reactiveType)
-                ? component.reactiveType
-                : [component.reactiveType || 'component'];
-              if (!reactiveTypes.includes('none')) {
-                componentsToNotify.add(component);
-              }
-            }
-          });
-        }
-      });
-    }
-  } else if (result.type === 'insert' || result.type === 'cut') {
-    // For array structural changes (add/remove), notify components listening to the parent array.
-    const parentArrayPath = result.type === 'insert' ? path : path.slice(0, -1);
-    const parentMeta = getShadowMetadata(stateKey, parentArrayPath);
-
-    if (parentMeta?.pathComponents) {
-      parentMeta.pathComponents.forEach((componentId: string) => {
+    if (pathMeta?.pathComponents) {
+      pathMeta.pathComponents.forEach((componentId: string) => {
         const component = rootMeta.components?.get(componentId);
-        // NEW: Add component to the set
         if (component) {
-          componentsToNotify.add(component);
+          const reactiveTypes = Array.isArray(component.reactiveType)
+            ? component.reactiveType
+            : [component.reactiveType || 'component'];
+          if (!reactiveTypes.includes('none')) {
+            componentsToNotify.add(component);
+          }
         }
       });
     }
+
+    if (currentPath.length === 0) break;
+    currentPath.pop(); // Go up one level
   }
 
   // --- PASS 2: Handle 'all' and 'deps' reactivity types ---
@@ -1177,8 +1178,16 @@ function getComponentNotifications(
 function handleInsert(
   stateKey: string,
   path: string[],
-  payload: any
-): { type: 'insert'; newValue: any; shadowMeta: any } {
+  payload: any,
+  index?: number
+): {
+  type: 'insert';
+  newValue: any;
+  shadowMeta: any;
+  path: string[];
+  itemId: string;
+  insertAfterId?: string;
+} {
   let newValue;
   if (isFunction(payload)) {
     const { value: currentValue } = getScopedData(stateKey, path);
@@ -1187,21 +1196,26 @@ function handleInsert(
     newValue = payload;
   }
 
-  insertShadowArrayElement(stateKey, path, newValue);
+  const itemId = insertShadowArrayElement(stateKey, path, newValue, index);
   markAsDirty(stateKey, path, { bubble: true });
 
   const updatedMeta = getShadowMetadata(stateKey, path);
-  if (updatedMeta?.arrayKeys) {
-    const newItemKey = updatedMeta.arrayKeys[updatedMeta.arrayKeys.length - 1];
-    if (newItemKey) {
-      const newItemPath = newItemKey.split('.').slice(1);
-      markAsDirty(stateKey, newItemPath, { bubble: false });
-    }
+
+  // Find the ID that comes before this insertion point
+  let insertAfterId: string | undefined;
+  if (updatedMeta?.arrayKeys && index !== undefined && index > 0) {
+    insertAfterId = updatedMeta.arrayKeys[index - 1];
   }
 
-  return { type: 'insert', newValue, shadowMeta: updatedMeta };
+  return {
+    type: 'insert',
+    newValue,
+    shadowMeta: updatedMeta,
+    path: path, // Just the array path now
+    itemId: itemId,
+    insertAfterId: insertAfterId,
+  };
 }
-
 function handleCut(
   stateKey: string,
   path: string[]
@@ -1286,12 +1300,15 @@ function createEffectiveSetState<T>(
     switch (options.updateType) {
       case 'update':
         result = handleUpdate(stateKey, path, payload);
+
         break;
       case 'insert':
         result = handleInsert(stateKey, path, payload);
+
         break;
       case 'cut':
         result = handleCut(stateKey, path);
+
         break;
     }
 
@@ -1308,6 +1325,8 @@ function createEffectiveSetState<T>(
       status: 'new',
       oldValue: result.oldValue,
       newValue: result.newValue ?? null,
+      itemId: result.itemId,
+      insertAfterId: result.insertAfterId,
     };
 
     updateBatchQueue.push(newUpdate);
@@ -1438,9 +1457,13 @@ export function useCogsStateFn<TStateObject extends unknown>(
 
   // Effect 1: When this component's serverState prop changes, broadcast it
   useEffect(() => {
-    setServerStateUpdate(thisKey, serverState);
-  }, [serverState, thisKey]);
+    if (!serverState) return;
 
+    // Only broadcast if we have valid server data
+    if (serverState.status === 'success' && serverState.data !== undefined) {
+      setServerStateUpdate(thisKey, serverState);
+    }
+  }, [serverState, thisKey]);
   // Effect 2: Listen for server state updates from ANY component
   useEffect(() => {
     const unsubscribe = getGlobalStore
@@ -1456,13 +1479,14 @@ export function useCogsStateFn<TStateObject extends unknown>(
             return; // Ignore if no valid data
           }
 
+          // Store the server state in options for future reference
           setAndMergeOptions(thisKey, { serverState: serverStateData });
 
           const mergeConfig =
             typeof serverStateData.merge === 'object'
               ? serverStateData.merge
               : serverStateData.merge === true
-                ? { strategy: 'append' }
+                ? { strategy: 'append' as const, key: 'id' }
                 : null;
 
           const currentState = getShadowValue(thisKey, []);
@@ -1471,7 +1495,7 @@ export function useCogsStateFn<TStateObject extends unknown>(
           if (
             mergeConfig &&
             mergeConfig.strategy === 'append' &&
-            'key' in mergeConfig && // Type guard for key
+            'key' in mergeConfig &&
             Array.isArray(currentState) &&
             Array.isArray(incomingData)
           ) {
@@ -1483,49 +1507,57 @@ export function useCogsStateFn<TStateObject extends unknown>(
               return;
             }
 
+            // Get existing IDs to check for duplicates
             const existingIds = new Set(
               currentState.map((item: any) => item[keyField])
             );
 
+            // Filter out duplicates from incoming data
             const newUniqueItems = incomingData.filter(
               (item: any) => !existingIds.has(item[keyField])
             );
 
             if (newUniqueItems.length > 0) {
+              // Insert only the new unique items
               insertManyShadowArrayElements(thisKey, [], newUniqueItems);
             }
 
-            // Mark the entire final state as synced
+            // Mark the entire merged state as synced
             const finalState = getShadowValue(thisKey, []);
             markEntireStateAsServerSynced(
               thisKey,
               [],
               finalState,
-              serverStateData.timestamp
+              serverStateData.timestamp || Date.now()
             );
           } else {
-            // This handles the "replace" strategy (initial load)
+            // Replace strategy (default) - completely replace the state
             initializeShadowState(thisKey, incomingData);
 
+            // Mark as synced from server
             markEntireStateAsServerSynced(
               thisKey,
               [],
               incomingData,
-              serverStateData.timestamp
+              serverStateData.timestamp || Date.now()
             );
           }
+
+          // Notify all components subscribed to this state
+          notifyComponents(thisKey);
         }
       });
 
     return unsubscribe;
-  }, [thisKey, resolveInitialState]);
-
+  }, [thisKey]);
   useEffect(() => {
     const existingMeta = getGlobalStore
       .getState()
       .getShadowMetadata(thisKey, []);
+
+    // Skip if already initialized
     if (existingMeta && existingMeta.stateSource) {
-      return; // Already initialized, bail out.
+      return;
     }
 
     const options = getInitialOptions(thisKey as string);
@@ -1537,34 +1569,35 @@ export function useCogsStateFn<TStateObject extends unknown>(
       ),
       localStorageEnabled: !!options?.localStorage?.key,
     };
+
     setShadowMetadata(thisKey, [], {
       ...existingMeta,
       features,
     });
+
     if (options?.defaultState !== undefined || defaultState !== undefined) {
       const finalDefaultState = options?.defaultState || defaultState;
-
-      // Only set defaultState if it's not already set
       if (!options?.defaultState) {
         setAndMergeOptions(thisKey as string, {
           defaultState: finalDefaultState,
         });
       }
+    }
 
-      const { value: resolvedState, source, timestamp } = resolveInitialState();
-
-      initializeShadowState(thisKey, resolvedState);
-
-      // Set shadow metadata with the correct source info
-      setShadowMetadata(thisKey, [], {
-        stateSource: source,
-        lastServerSync: source === 'server' ? timestamp : undefined,
-        isDirty: false,
-        baseServerState: source === 'server' ? resolvedState : undefined,
-      });
+    const { value: resolvedState, source, timestamp } = resolveInitialState();
+    initializeShadowState(thisKey, resolvedState);
+    setShadowMetadata(thisKey, [], {
+      stateSource: source,
+      lastServerSync: source === 'server' ? timestamp : undefined,
+      isDirty: source === 'server' ? false : undefined,
+      baseServerState: source === 'server' ? resolvedState : undefined,
+    });
 
-      notifyComponents(thisKey);
+    if (source === 'server' && serverState) {
+      setServerStateUpdate(thisKey, serverState);
     }
+
+    notifyComponents(thisKey);
   }, [thisKey, ...(dependencies || [])]);
 
   useLayoutEffect(() => {
@@ -1658,7 +1691,7 @@ export function useCogsStateFn<TStateObject extends unknown>(
 
   const cogsSyncFn = __useSync;
   const syncOpt = latestInitialOptionsRef.current?.syncOptions;
-
+  console.log('syncOpt', syncOpt);
   if (cogsSyncFn) {
     syncApiRef.current = cogsSyncFn(
       updaterFinal as any,
@@ -1919,15 +1952,11 @@ function createProxyHandler<T>(
           const getStatusFunc = () => {
             // ✅ Use the optimized helper to get all data in one efficient call
             const { shadowMeta, value } = getScopedData(stateKey, path, meta);
-
-            // Priority 1: Explicitly dirty items. This is the most important status.
+            console.log('getStatusFunc', path, shadowMeta, value);
             if (shadowMeta?.isDirty === true) {
               return 'dirty';
             }
 
-            // ✅ Priority 2: Synced items. This condition is now cleaner.
-            // An item is considered synced if it came from the server OR was explicitly
-            // marked as not dirty (isDirty: false), covering all sync-related cases.
             if (
               shadowMeta?.stateSource === 'server' ||
               shadowMeta?.isDirty === false
@@ -1935,20 +1964,15 @@ function createProxyHandler<T>(
               return 'synced';
             }
 
-            // Priority 3: Items restored from localStorage.
             if (shadowMeta?.stateSource === 'localStorage') {
               return 'restored';
             }
 
-            // Priority 4: Items from default/initial state.
             if (shadowMeta?.stateSource === 'default') {
               return 'fresh';
             }
 
-            // ✅ REMOVED the redundant "root" check. The item's own `stateSource` is sufficient.
-
-            // Priority 5: A value exists but has no metadata. This is a fallback.
-            if (value !== undefined && !shadowMeta) {
+            if (value !== undefined) {
               return 'fresh';
             }
 
@@ -2425,7 +2449,7 @@ function createProxyHandler<T>(
               path,
               meta
             );
-
+            registerComponentDependency(stateKey, componentId, path);
             if (!arrayKeys || !Array.isArray(shadowValue)) {
               return []; // It's valid to map over an empty array.
             }
@@ -3110,7 +3134,10 @@ function createProxyHandler<T>(
         }
         if (path.length == 0) {
           if (prop === '$addZodValidation') {
-            return (zodErrors: any[]) => {
+            return (
+              zodErrors: any[],
+              source: 'client' | 'sync_engine' | 'api'
+            ) => {
               zodErrors.forEach((error) => {
                 const currentMeta =
                   getGlobalStore
@@ -3125,7 +3152,7 @@ function createProxyHandler<T>(
                       status: 'INVALID',
                       errors: [
                         {
-                          source: 'client',
+                          source: source || 'client',
                           message: error.message,
                           severity: 'error',
                           code: error.code,
@@ -3156,6 +3183,51 @@ function createProxyHandler<T>(
               });
             };
           }
+
+          if (prop === '$applyOperation') {
+            return (operation: UpdateTypeDetail & { validation?: any[] }) => {
+              const validationErrorsFromServer = operation.validation || [];
+
+              if (!operation || !operation.path) {
+                console.error(
+                  'Invalid operation received by $applyOperation:',
+                  operation
+                );
+                return;
+              }
+
+              const updatePath = operation.path;
+
+              const currentMeta =
+                getGlobalStore
+                  .getState()
+                  .getShadowMetadata(stateKey, updatePath) || {};
+
+              const newErrors: ValidationError[] =
+                validationErrorsFromServer.map((err) => ({
+                  source: 'sync_engine',
+                  message: err.message,
+                  severity: 'warning',
+                  code: err.code,
+                }));
+
+              console.log('updatePath', updatePath);
+              getGlobalStore
+                .getState()
+                .setShadowMetadata(stateKey, updatePath, {
+                  ...currentMeta,
+                  validation: {
+                    status: newErrors.length > 0 ? 'INVALID' : 'VALID',
+                    errors: newErrors,
+                    lastValidated: Date.now(),
+                  },
+                });
+              effectiveSetState(operation.newValue, updatePath, {
+                updateType: operation.updateType,
+                sync: false,
+              });
+            };
+          }
           if (prop === '$applyJsonPatch') {
             return (patches: Operation[]) => {
               const store = getGlobalStore.getState();
@@ -3289,7 +3361,6 @@ function createProxyHandler<T>(
                   .getState()
                   .getShadowMetadata(stateKey, path);
 
-                // Update the metadata for this specific path
                 setShadowMetadata(stateKey, path, {
                   ...shadowMeta,
                   isDirty: false,
@@ -3297,7 +3368,6 @@ function createProxyHandler<T>(
                   lastServerSync: Date.now(),
                 });
 
-                // Notify any components that might be subscribed to the sync status
                 const fullPath = [stateKey, ...path].join('.');
                 notifyPathSubscribers(fullPath, {
                   type: 'SYNC_STATUS_CHANGE',
@@ -3371,21 +3441,15 @@ function createProxyHandler<T>(
         .getShadowMetadata(stateKey, []);
       let revertState;
 
-      // Determine the correct state to revert to (same logic as before)
       if (shadowMeta?.stateSource === 'server' && shadowMeta.baseServerState) {
         revertState = shadowMeta.baseServerState;
       } else {
         revertState = getGlobalStore.getState().initialStateGlobal[stateKey];
       }
 
-      // Perform necessary cleanup
       clearSelectedIndexesForState(stateKey);
-
-      // FIX 1: Use the IMMEDIATE, SYNCHRONOUS state reset function.
-      // This is what your tests expect for a clean slate.
       initializeShadowState(stateKey, revertState);
 
-      // Rebuild the proxy's internal shape after the reset
       rebuildStateShape({
         path: [],
         componentId: outerComponentId!,
@@ -3401,8 +3465,6 @@ function createProxyHandler<T>(
         localStorage.removeItem(storageKey);
       }
 
-      // FIX 2: Use the library's BATCHED notification system instead of a manual forceUpdate loop.
-      // This fixes the original infinite loop bug safely.
       notifyComponents(stateKey);
 
       return revertState;
@@ -3488,7 +3550,6 @@ function SignalRenderer({
 
   const value = getShadowValue(proxy._stateKey, proxy._path, viewIds);
 
-  // Setup effect - runs only once
   useEffect(() => {
     const element = elementRef.current;
     if (!element || isSetupRef.current) return;
@@ -3511,7 +3572,6 @@ function SignalRenderer({
 
       instanceIdRef.current = `instance-${crypto.randomUUID()}`;
 
-      // Store signal info in shadow metadata
       const currentMeta =
         getGlobalStore
           .getState()