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>
This commit is contained in:
Scott Idem
2026-03-20 10:09:19 -04:00
parent 942b3ddf5f
commit bf9aa9710c

View File

@@ -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.