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 | | `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` | Electron/Launcher reference |
| `tests/README.md` | Playwright test guide — shared helpers, hard-won lessons, demo IDs | | `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. URL params consumed by the app. Params are read by layouts and applied on mount.