OSIT-AE-App-Svelte/documentation/PROJECT__AE_Object_Field_Editor_V3_upgrade.md

Project Plan: Aether AE Obj Field Editor v3 (Consolidated)

Status: 🟡 Mostly Complete — Phase 3 items + GUIDE update remaining Date: February 13, 2026 (last updated: 2026-03-20) Target Component: src/lib/elements/element_ae_obj_field_editor.svelte Replaces: element_ae_crud.svelte and element_ae_crud_v2.svelte

1. Overview

Consolidate the legacy CRUD components into a single, high-performance "Aether Object Field Editor" (v3). This component will be the standard for single-property editing across the platform, fully aligned with the FastAPI V3 CRUD patterns and Svelte 5 Runes.

2. Strategic Objectives

• Consolidation: Retire v1 and v2 components in favor of a single, unified codebase.
• API Alignment: Native support for PATCH /v3/crud/{obj_type}/{obj_id}.
• Svelte 5 Runes: Pure $props, $state, and $derived implementation. No legacy imports.
• Callback Pattern: Replace createEventDispatcher with callback props (on_patch, on_success, on_error).
• Iconography: Standardize on Lucide-Svelte.
• Mobile-First: Improved "Tap to Edit" targets and mobile-responsive popovers.

3. Implementation Phases

Phase 1: Foundation & Reactivity (COMPLETED)

• Create the new v3 component shell.
• Implement strict TypeScript interface for Props.
• Use $state for local "draft" values to prevent reactivity loops with the global store.
• Implement the handle_patch logic using the central api.patch helper.

Phase 2: UI & UX Refinement (COMPLETED)

• Standardize Tailwind classes (using Tailwind 4 patterns).
• Implement "Edit Mode" awareness (syncing with $ae_loc.edit_mode).
• Add a "Save" loading state with Lucide's LoaderCircle spinner.
• Implement a clear "Cancel" path that restores the original value.

Phase 3: Field Type Parity (IN PROGRESS)

• Support text, textarea, select, tiptap, and checkbox.
• Add datetime support using native browser pickers — date and datetime-local inputs implemented.
• Implement searchable dropdowns for the select type.

Phase 4: Migration & Cleanup

• Create a playground route for V3 verification (/testing/ae_obj_field_editor).
• Deprecate and remove v1 and v2 files — element_ae_crud.svelte and element_ae_crud_v2.svelte removed 2026-03-20.
• Update GUIDE__Development.md with the new usage patterns.

⚠️ Security & Reliability Stabilization (NEW)

• Account Context: Fixed 403 errors by unifying API helpers to the /v3/crud/ standard.
• Race Conditions: Implemented localStorage scavenging for Account IDs to fix Svelte 5 hydration lags.
• Protocol Hygiene: Purged redundant/misplaced headers (x-aether-api-token, Access-Control-Allow-Origin).

4. Maintenance & Standards

• Component must respect $ae_loc.trusted_access for visibility of edit triggers.
• Always use type="button" for internal actions to prevent form collisions.
• Maintain the object_reload pattern for SWR cache invalidation.