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

Project Plan: Aether CRUD v2 Component Refactor (V3 Alignment)

Status: Draft / Initial Planning
Date: February 9, 2026
Target Component: src/lib/elements/element_ae_crud_v2.svelte

1. Overview

The Element_ae_crud_v2 component is the central property editor for the Aether platform. Following major backend (FastAPI V3) and frontend (Svelte 5) upgrades, this component requires a systematic refactor to restore full functionality, improve performance, and enhance the developer experience (DX).

The goal is a near drop-in replacement that maintains the existing API while leveraging modern platform standards.

2. Strategic Objectives

• API Alignment: Fully integrate with the V3 CRUD pattern (PATCH /v3/crud/{obj_type}/{obj_id}).
• Svelte 5 Optimization: Migrate fully to Runes ($state, $derived, $effect, $props) for cleaner reactivity and improved prop-binding.
• Mobile-First UX: Redesign the edit popover/form for better accessibility on smaller screens.
• Robust Error Handling: Standardize error bubbling and validation feedback.
• Type Safety: Ensure all props and internal state are strictly typed.

3. Current Version Audit (v2)

• Strengths: Support for multiple field types (text, textarea, tiptap, select); SWR-ready via object_reload.
• Weaknesses: Fragmented CSS; manual state synchronization logic; inconsistent button styling; limited feedback for patch failures.

4. Implementation Phases

Phase 1: Core Reactivity & API

• Replace let exports with $props() destructuring.
• Implement $state for internal values and patch status.
• Standardize the handle_obj_field_patch function to use the central api.patch helper.
• Verify Triple-ID mapping within the component.

Phase 2: UI/UX & Accessibility

• Standardize Tailwind classes; remove legacy scope-polluting CSS.
• Implement a "Select" mode optimized for mobile (Bottom Sheet style?).
• Improve "Double Click to Edit" discoverability or provide a single-tap alternative for mobile.
• Standardize button types (type="button") and preset styles.

Phase 3: Field Type Expansion

• Enhance select mode with searchable dropdowns.
• Formalize tiptap integration with full configuration support.
• Add datetime and date field types.

Phase 4: Verification & Migration

• Create a testing playground route for CRUD v2.
• Perform a surgical swap across high-traffic modules (Leads, Events, Journals).
• Verify npm run check baseline.

5. Maintenance & Standards

• Maintain the object_reload={true} pattern for automatic cache revalidation.
• Ensure class_li and display_block props remain backward compatible.