From bf9aa9710c064db35f201cea093bbf1ea9a546f2 Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Fri, 20 Mar 2026 10:09:19 -0400
Subject: [PATCH] docs: add V3 field editor usage section to
 GUIDE__Development.md

Fulfills Phase 4 open item from PROJECT__AE_Object_Field_Editor_V3_upgrade.md.
Covers import, basic text usage, all field types, select with nullable FK,
key props table, and behavior notes (optimistic display, edit_mode visibility).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 documentation/GUIDE__Development.md | 74 ++++++++++++++++++++++++++++-
 1 file changed, 73 insertions(+), 1 deletion(-)

diff --git a/documentation/GUIDE__Development.md b/documentation/GUIDE__Development.md
index 78b91dec..88511f0a 100644
--- a/documentation/GUIDE__Development.md
+++ b/documentation/GUIDE__Development.md
@@ -53,7 +53,79 @@ You are not working in a vacuum. Coordinate with the Backend Agent via MCP tools
 | `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` | Electron/Launcher reference |
 | `tests/README.md` | Playwright test guide — shared helpers, hard-won lessons, demo IDs |
 
-## 6. URL Parameters
+## 6. Inline Field Editing — `element_ae_obj_field_editor_v3`
+
+The standard component for single-field inline editing throughout the platform. Wraps a `PATCH /v3/crud/{obj_type}/{obj_id}` call behind a click-to-edit UI that respects `$ae_loc.edit_mode`.
+
+```svelte
+import Element_ae_obj_field_editor_v3 from '$lib/elements/element_ae_obj_field_editor_v3.svelte';
+```
+
+### Basic usage — text field with custom display
+
+Wrap the display content in the default snippet. The component renders it in view mode and swaps in the input on edit.
+
+```svelte
+<Element_ae_obj_field_editor_v3
+    object_type={'event_session'}
+    object_id={session.id}
+    field_name={'name'}
+    field_type={'text'}
+    current_value={session.name}
+    on_success={() => events_func.load_ae_obj_id__event_session({ api_cfg: $ae_api, event_session_id: session.id })}
+>
+    <h1 class="text-2xl font-bold">{session.name}</h1>
+</Element_ae_obj_field_editor_v3>
+```
+
+### Field types
+
+| `field_type` | Input rendered |
+| --- | --- |
+| `text` (default) | `<input type="text">` — Enter key saves |
+| `textarea` | `<textarea>` — use `textarea_rows` prop |
+| `select` | `<select>` — pass `select_options={{ value: 'Label' }}` |
+| `checkbox` | `<input type="checkbox">` — shows Enabled/Disabled |
+| `tiptap` | TipTap rich-text editor |
+| `date` | `<input type="date">` |
+| `datetime` | `<input type="datetime-local">` |
+| `number` | `<input type="number">` — Enter key saves |
+
+### Select with nullable FK
+
+```svelte
+<Element_ae_obj_field_editor_v3
+    object_type={'event_presenter'}
+    object_id={presenter.event_presenter_id}
+    field_name={'person_id'}
+    field_type={'select'}
+    current_value={presenter.person_id}
+    select_options={$slct.person_obj_kv}
+    allow_null={$ae_loc.administrator_access}
+    on_success={() => events_func.load_ae_obj_id__event_presenter({ api_cfg: $ae_api, event_presenter_id: presenter.event_presenter_id })}
+>
+    {presenter.person_id ?? 'Not linked'}
+</Element_ae_obj_field_editor_v3>
+```
+
+### Key props
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `current_value` | — | Required. Bound with `$bindable` — liveQuery updates flow through automatically |
+| `allow_null` | `false` | Shows a "Set Null" button in edit mode |
+| `display_block` | `false` | Makes the wrapper `display: block` instead of `inline-block` |
+| `on_success` | — | Callback after successful PATCH — use to trigger SWR cache refresh |
+| `object_reload` | `true` | Triggers internal SWR reload after patch (in addition to `on_success`) |
+
+### Behavior notes
+- The edit trigger button is `visibility: hidden` (not `display: none`) when `$ae_loc.edit_mode` is off — this preserves layout so the page doesn't shift when edit mode toggles.
+- Optimistic display: draft value is shown immediately after save; cleared once liveQuery confirms the update came back from the DB.
+- `on_success` should always call the relevant `load_ae_obj_id__*` function to keep Dexie in sync.
+
+---
+
+## 7. URL Parameters
 
 URL params consumed by the app. Params are read by layouts and applied on mount.