From 68f2c672f61c4e1acc69b2bd91507ac18de0b81a Mon Sep 17 00:00:00 2001
From: root <root@rspade.framework.dev.hanson.xyz>
Date: Sun, 23 Nov 2025 22:55:01 +0000
Subject: [PATCH] Update model_fetch man page with correct augmented array
 pattern
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 app/RSpade/man/model_fetch.txt | 59 ++++++++++++++++++++--------------
 1 file changed, 34 insertions(+), 25 deletions(-)

diff --git a/app/RSpade/man/model_fetch.txt b/app/RSpade/man/model_fetch.txt
index 2eee3ae12..ced2086e6 100755
--- a/app/RSpade/man/model_fetch.txt
+++ b/app/RSpade/man/model_fetch.txt
@@ -64,10 +64,14 @@ IMPLEMENTING FETCHABLE MODELS
         5. Return model object, custom array, or false
 
     Return Value Options:
-        - Model object: Serialized via to_export_array(), includes __MODEL for hydration
-        - Custom array: Full control over data shape, include computed/formatted fields
+        - Model object: Serialized via toArray(), includes __MODEL for hydration
+        - Augmented array: Start with $model->toArray(), add computed fields (recommended)
         - false: Record not found or unauthorized (MUST be false, not null)
 
+        Note: Always use toArray() as the base when returning arrays. This preserves
+        the __MODEL property required for JavaScript hydration. See "Augmented Array
+        Return" section below for the correct pattern.
+
     Basic Implementation:
         use Ajax_Endpoint_Model_Fetch;
 
@@ -136,7 +140,7 @@ IMPLEMENTING FETCHABLE MODELS
             }
         }
 
-    Custom Array Return (recommended for CRUD pages):
+    Augmented Array Return (recommended for CRUD pages):
         class Client_Model extends Rsx_Model
         {
             #[Ajax_Endpoint_Model_Fetch]
@@ -147,31 +151,36 @@ IMPLEMENTING FETCHABLE MODELS
                     return false;
                 }
 
-                // Return formatted array with computed fields
-                return [
-                    'id' => $client->id,
-                    'name' => $client->name,
-                    'status' => $client->status,
-                    // Computed display fields
-                    'status_label' => ucfirst($client->status),
-                    'status_badge' => match($client->status) {
-                        'active' => 'bg-success',
-                        'inactive' => 'bg-secondary',
-                        default => 'bg-warning'
-                    },
-                    // Formatted dates
-                    'created_at_formatted' => $client->created_at->format('M d, Y'),
-                    'created_at_human' => $client->created_at->diffForHumans(),
-                    // Related data
-                    'region_name' => $client->region_name(),
-                    'country_name' => $client->country_name(),
-                ];
+                // Start with model's toArray() to get __MODEL and base data
+                $data = $client->toArray();
+
+                // Augment with computed/formatted fields
+                $data['status_label'] = ucfirst($client->status);
+                $data['status_badge'] = match($client->status) {
+                    'active' => 'bg-success',
+                    'inactive' => 'bg-secondary',
+                    default => 'bg-warning'
+                };
+                $data['created_at_formatted'] = $client->created_at->format('M d, Y');
+                $data['created_at_human'] = $client->created_at->diffForHumans();
+                $data['region_name'] = $client->region_name();
+                $data['country_name'] = $client->country_name();
+
+                return $data;
             }
         }
 
-        Note: When returning an array, the JavaScript side receives the plain
-        object (not a hydrated model instance). This is intentional - it gives
-        full control over the data shape for view/edit pages.
+        IMPORTANT: Always start with $model->toArray() when augmenting data.
+        This preserves the __MODEL property needed for JavaScript hydration.
+        The result is a hydrated model instance with your extra fields added.
+
+        DO NOT manually construct the return array like this (outdated pattern):
+            return [
+                'id' => $client->id,
+                'name' => $client->name,
+                // ... manually listing fields
+            ];
+        This loses __MODEL and returns a plain object instead of a model instance.
 
 JAVASCRIPT USAGE
     Single Record Fetching: