crowd-funder-for-time-pwa/GiftedDialog-Logic-Flow.md

GiftedDialog UI Logic Flow

Author: Matthew Raymer
Date: December 2025 Component: src/components/GiftedDialog.vue

Executive Summary

The GiftedDialog component is a critical interface in the Time Safari application that enables users to record gifts and contributions between people and projects. This document provides comprehensive analysis of the component's current implementation and a detailed refactoring plan to modernize its architecture using Pinia store management and enhanced template composition.

Current State

• Complexity: 400+ line monolithic Vue component with mixed UI and business logic
• State Management: Local component state with complex prop-based configuration
• Template: Single large template with repetitive patterns and accessibility gaps
• Integration: Used across 8+ views with varying configuration requirements
• Critical Issues: Navigation flow problems, dual-purpose confusion, parameter redundancy

Proposed Solution

• Pinia Store Integration: Centralized state management with improved type safety
• Template Decomposition: Break into focused, reusable sub-components
• Accessibility Enhancement: Comprehensive ARIA labels, keyboard navigation, screen reader support
• User Experience: Visual progress indicators, better error feedback, streamlined workflows
• Developer Experience: Improved debugging, testing, and maintainability

Business Impact

• User Experience: Eliminates navigation dead-ends and confusion, adds visual progress guidance
• Maintainability: Reduces component complexity from 400+ to ~100 lines, improves testability
• Accessibility: Meets WCAG guidelines for assisted user experience
• Development Velocity: Easier debugging, testing, and feature additions
• Risk Mitigation: Backward compatibility preserved during transition

Implementation Timeline

• Aggressive: 25 days (5 weeks) - High risk, may require scope reduction
• Realistic: 30-33 days (6-7 weeks) - Recommended approach with 70-80% confidence
• Conservative: 35-40 days (7-8 weeks) - High confidence with full complexity buffer
• Approach: Incremental migration with feature flags for rollback safety
• Testing: Comprehensive test coverage including accessibility and performance validation
• Deliverables: Modern, accessible, maintainable component with enhanced user experience

---

Summary

Component Overview

The GiftedDialog component serves as the primary interface for recording gifts and contributions in the Time Safari application. It handles complex multi-step workflows for various gift scenarios:

• Person-to-Person: Direct gifts between individuals
• Person-to-Project: Contributions to community projects
• Project-to-Person: Recognition of benefits received from projects

Key Features

Current Capabilities

• Multi-Step Workflow: Entity selection → Gift details → Submission
• Entity Type Detection: Automatic determination of giver/recipient types based on context
• Conflict Prevention: Prevents selecting same person as both giver and recipient
• Cross-Platform Integration: Used across HomeView, ProjectView, ContactsView, and 5+ other views
• Validation System: Comprehensive input validation with user-friendly error messages
• Advanced Options: Integration with GiftedDetailsView for photos and extended descriptions

Proposed Enhancements

• Visual Progress: Step indicators showing "Step 1 of 2" with progress visualization
• Component Composition: Decomposed into 7 focused sub-components for better maintainability
• Accessibility: Full WCAG compliance with keyboard navigation and screen reader support
• Performance: Optimized bundle size and rendering performance
• Type Safety: Enhanced TypeScript definitions throughout component hierarchy

Technical Architecture

Current Implementation

// Monolithic component with local state
export default class GiftedDialog extends Vue {
  visible = false;
  currentStep = 1;
  stepType = "giver";  // Entity selection mode
  giver?: GiverReceiverInputInfo;
  receiver?: GiverReceiverInputInfo;
  // ... 20+ more state variables
}

Proposed Architecture

// Store-based state management
const giftDialogStore = useGiftDialogStore();

// Component composition
<template>
  <GiftDialogStepIndicator />
  <GiftDialogEntitySelection v-if="step1" />
  <GiftDialogDetailsForm v-if="step2" />
</template>

Integration Points

The component integrates with multiple views across the application:

View	Usage Pattern	Configuration
HomeView	Main entry point	Gift prompts, unnamed giver support
ProjectViewView	Dual dialogs	Bidirectional gift recording
ContactsView	Contact-specific	Direction confirmation flows
ContactGiftingView	Advanced UI	Complex entity type handling
ClaimView	Offer fulfillment	Pre-populated offer context

Critical Issues Addressed

1. Navigation Flow Problems

• Issue: Users getting stuck in ContactGiftingView with no completion path
• Solution: Proper success callbacks and navigation logic

2. Component Dual-Purpose Confusion

• Issue: Users unclear about current step and progress
• Solution: Visual step indicators and clearer labeling

3. Parameter Redundancy

• Issue: Legacy projectId conflicts with context-aware parameters
• Solution: Streamlined parameter handling and cleanup

Refactoring Plan Overview

Phase Structure (30-33 days realistic)

1. Pre-Phase 1 (3 days): Address critical missing fields and dependencies
2. Phase 1 (4-5 days): Store infrastructure + foundation components
3. Phase 2 (5-6 days): Hybrid component + main template components
4. Phase 3 (5-6 days): Incremental view migration
5. Phase 4 (5-6 days): Template enhancement and accessibility
6. Phase 5 (3 days): Store enhancement and advanced features
7. Phase 6 (4 days): Cleanup, testing, and finalization

Complexity Analysis

• Overall Complexity Score: 3.7/5 (High)
• Highest Risk Phase: Phase 2 (5/5) - Backward compatibility challenges
• Key Complexity Factors: 8+ integration points, 400+ line template decomposition, WCAG compliance
• Estimation Model: Base effort × 1.4 complexity multiplier + 25% risk buffer

Risk Mitigation

• Backward Compatibility: Feature flags enable rollback at any phase
• Incremental Migration: Views migrated one at a time with full testing
• Comprehensive Testing: Existing Playwright tests maintained throughout
• Performance Monitoring: Bundle size and runtime performance tracked

Success Metrics

• Technical: All existing tests pass, no performance regression >10%
• User Experience: No change in functionality, improved error rates
• Code Quality: Reduced complexity, improved testability, better separation of concerns
• Accessibility: WCAG compliance, improved screen reader support

Expected Outcomes

For Users

• Clearer Navigation: Visual progress indicators and better step guidance
• Reduced Confusion: Eliminated dual-purpose ambiguity and dead-end flows
• Better Accessibility: Full keyboard navigation and screen reader support
• Improved Reliability: Better error handling and recovery mechanisms

For Developers

• Easier Maintenance: Component complexity reduced from 400+ to ~100 lines
• Better Testing: Isolated components enable focused unit testing
• Improved Debugging: Clear separation of concerns and better error messages
• Enhanced Type Safety: Comprehensive TypeScript definitions throughout

For Business

• Reduced Support: Fewer user confusion and navigation issues
• Faster Development: Easier to add features and fix issues
• Better Accessibility: Compliance with accessibility standards
• Future-Proof Architecture: Modern patterns enable easier future enhancements

This refactoring represents a comprehensive modernization that maintains full backward compatibility while significantly improving user experience, developer productivity, and code maintainability.

---

Overview

The GiftedDialog component is a multi-step modal dialog that facilitates recording gifts/contributions between people and projects in the Time Safari application. It supports various gift scenarios including person-to-person, person-to-project, and project-to-person transactions.

This component serves as the primary interface for users to acknowledge and record contributions they have received or given. When a user wants to document a gift, favor, or contribution, they interact with this dialog which guides them through a structured process to ensure all necessary information is captured accurately. The dialog intelligently adapts its interface based on the context from which it was opened, whether from the home screen, a project page, or another part of the application.

Architecture

Component Structure

• Framework: Vue 3 with TypeScript using vue-facing-decorator
• Dependencies:
  • Database layer (db/index.ts, databaseUtil.ts)
  • Endorser server integration (libs/endorserServer.ts)
  • Platform services (PlatformServiceFactory)
  • Child components: EntityIcon, ProjectIcon

The component is built using Vue 3's Composition API with TypeScript decorators for a class-based approach. This architectural choice provides strong typing and clear separation of concerns. The component heavily relies on the application's database layer for storing and retrieving contact information, while the endorser server integration handles the cryptographic signing and publishing of gift records to the distributed network.

Key Properties

@Prop() fromProjectId: string     // Project ID when project is the giver
@Prop() toProjectId: string       // Project ID when project is the recipient  
@Prop() showProjects: boolean     // Whether to show projects in selection
@Prop() isFromProjectView: boolean // Whether opened from project view

These properties control the dialog's behavior and determine what type of entities (people or projects) should be displayed in the selection interface. The fromProjectId and toProjectId properties are mutually exclusive and indicate whether a specific project is involved in the transaction. When showProjects is true, the dialog prioritizes showing available projects rather than people. The isFromProjectView flag helps the component understand the navigation context and adjust its interface accordingly.

Logic Flow

1. Initialization Phase

Entry Point: open() Method

async open(
  giver?: GiverReceiverInputInfo,
  receiver?: GiverReceiverInputInfo,
  offerId?: string,
  customTitle?: string,
  prompt?: string,
  callbackOnSuccess: (amount: number) => void = () => {}
)

The dialog's lifecycle begins when the open() method is called from a parent component. This method accepts several optional parameters that pre-populate the dialog with context-specific information. If a giver or receiver is already known (such as when recording a gift from a specific project), these can be passed in to skip the selection step. The method also accepts custom prompts and titles to provide contextual guidance to the user.

Initialization Steps:

1. Entity Type Determination (updateEntityTypes())
   • Analyzes props to determine if giver/recipient should be person or project
   • Sets giverEntityType and recipientEntityType accordingly

The first step in initialization involves analyzing the component's properties to determine what types of entities should be involved in this gift transaction. This analysis considers the context from which the dialog was opened and sets internal flags that control the subsequent user interface presentation.

2. Database Setup
   • Retrieves active account settings
   • Loads contacts from database
   • Fetches user's DIDs for identification

Next, the component establishes its data foundation by connecting to the local database and retrieving the user's contacts, account settings, and decentralized identifiers (DIDs). This information is essential for populating the selection interface and ensuring the user can choose from their known contacts and projects.

3. Project Loading (if needed)
   • Calls loadProjects() if either entity type is "project"
   • Fetches available projects from API server

If the dialog needs to display projects (either as potential givers or recipients), it makes an API call to the endorser server to retrieve the current list of available projects. This ensures users see the most up-to-date project information when making their selections.

4. Step Determination
   • If giver is pre-selected: starts at Step 2 (Gift Details)
   • Otherwise: starts at Step 1 (Entity Selection)

Finally, the component determines which step to display first. If enough context was provided during opening (such as a pre-selected giver), the dialog can skip directly to the gift details step. Otherwise, it starts with the entity selection step to gather the necessary information from the user.

2. Entity Type Logic

Entity Type Matrix

Context	Giver Type	Recipient Type	Description
showProjects=true	project	person	HomeView "Project" button
fromProjectId set	project	person	Project giving to person
toProjectId set	person	project	Person giving to project
Default	person	person	Person-to-person gift

The entity type determination follows a clear hierarchy of rules based on the dialog's opening context. When users click the "Project" button from the home view, they're indicating they want to record receiving something from a project, so the dialog configures itself for project-to-person gifts. Conversely, when opened from a project page with a "give to this project" context, it sets up for person-to-project transactions.

Dynamic Entity Resolution

updateEntityTypes() {
  // Reset defaults
  this.giverEntityType = "person";
  this.recipientEntityType = "person";
  
  // Apply context-specific logic
  if (this.showProjects) {
    this.giverEntityType = "project";
  } else if (this.fromProjectId) {
    this.giverEntityType = "project";
  } else if (this.toProjectId) {
    this.recipientEntityType = "project";
  }
}

The updateEntityTypes() method implements this logic by first resetting both entity types to "person" (the most common case), then applying specific rules based on the component's properties. This approach ensures a predictable fallback while allowing for context-specific customization. The method is called whenever relevant properties change, ensuring the interface stays synchronized with the current context.

3. Step 1: Entity Selection

Display Logic

The UI dynamically shows different entity grids based on shouldShowProjects:

get shouldShowProjects() {
  return (this.stepType === "giver" && this.giverEntityType === "project") ||
         (this.stepType === "recipient" && this.recipientEntityType === "project");
}

The first step presents users with a grid of selectable entities, but the content of this grid changes dramatically based on whether projects or people should be displayed. The shouldShowProjects computed property determines this by checking if the current selection step (giver or recipient) corresponds to an entity type of "project". This ensures users only see relevant options for their current selection task.

Project Selection Grid

• Layout: 3-4 columns on mobile/desktop
• Content: First 7 projects with icons, names, and issuer info
• Actions:
  • Click project → selectProject() or selectRecipientProject()
  • "Show All" link → Navigate to discover page

When displaying projects, the interface uses a wider grid layout to accommodate project icons and additional information like the project creator's identity. The grid shows only the first seven projects to avoid overwhelming the user, with a "Show All" option that navigates to the main discovery page for browsing the complete project catalog. Each project is displayed with its custom icon (if available), name, and information about who created or manages the project.

Person Selection Grid

• Layout: 4-6 columns responsive
• Content:
  • "You" option (with conflict detection)
  • "Unnamed" option
  • First 10 contacts with avatars and names
• Conflict Prevention:
  • Grays out options that would create giver=recipient conflicts
  • Uses wouldCreateConflict() method for validation

The person selection grid uses a more compact layout since person entries require less information. It always includes a "You" option (allowing users to select themselves) and an "Unnamed" option for cases where the other party isn't in their contact list. The grid then displays up to 10 of the user's contacts, each with their avatar and name. Importantly, the interface includes conflict prevention logic that visually disables options that would result in the same person being selected as both giver and recipient.

Conflict Detection Algorithm

wouldCreateConflict(contactDid: string) {
  // Only applies to person-to-person gifts
  if (this.giverEntityType !== "person" || this.recipientEntityType !== "person") {
    return false;
  }
  
  if (this.stepType === "giver") {
    return this.receiver?.did === contactDid;
  } else if (this.stepType === "recipient") {
    return this.giver?.did === contactDid;
  }
  
  return false;
}

The conflict detection algorithm prevents users from accidentally selecting the same person for both roles in a gift transaction. It only applies to person-to-person gifts, since project-to-person or person-to-project gifts cannot have this type of conflict. The method checks whether selecting a particular contact would create a duplicate selection by comparing their DID (decentralized identifier) with the already-selected entity for the opposite role.

4. Step 2: Gift Details

Entity Display

• Editable Entities: Show edit button, allow clicking to return to Step 1
• Locked Entities: Show lock icon, prevent editing (e.g., when project is pre-selected)
• Visual Representation: Appropriate icons (EntityIcon for people, ProjectIcon for projects)

The second step displays the selected entities prominently at the top of the form, providing visual confirmation of the user's choices. The interface distinguishes between editable and locked entities - editable entities show a pencil icon and can be clicked to return to the selection step, while locked entities (such as when the dialog was opened with a specific project context) show a lock icon and cannot be changed. This prevents users from accidentally modifying critical context information.

Form Controls

1. Description Input
   • Text field with dynamic placeholder
   • Uses custom prompt if provided

The description field allows users to provide context about what was given or received. The placeholder text adapts based on any custom prompt provided when opening the dialog, helping guide users toward appropriate descriptions for their specific context.

2. Amount Controls
   • Increment/decrement buttons
   • Direct numeric input
   • Unit selector (Hours, USD, BTC, BX, ETH)

The amount section provides multiple ways for users to specify the quantity of their gift. Increment and decrement buttons make it easy to adjust whole number amounts, while the direct input field allows for precise decimal values. The unit selector supports various types of contributions, from time (hours) to different currencies, acknowledging that gifts in the Time Safari ecosystem can take many forms.

3. Advanced Options
   • "Photo & more options" link to GiftedDetailsView
   • Passes comprehensive query parameters for state preservation

For users who want to add additional details like photos or more complex descriptions, a link navigates to an expanded details view. The component carefully preserves all current form state by encoding it in query parameters, ensuring users don't lose their progress when exploring these advanced options.

Validation Logic

async confirm() {
  // Check for active DID
  if (!this.activeDid) {
    this.$notify({ type: "danger", text: "You must select an identifier..." });
    return;
  }
  
  // Validate amount
  if (parseFloat(this.amountInput) < 0) {
    this.$notify({ type: "danger", text: "You may not send a negative number." });
    return;
  }
  
  // Require description or amount
  if (!this.description && !parseFloat(this.amountInput)) {
    this.$notify({ type: "danger", text: "You must enter a description or amount." });
    return;
  }
  
  // Check for person conflict
  if (this.hasPersonConflict) {
    this.$notify({ type: "danger", text: "Cannot select same person as giver and recipient." });
    return;
  }
}

The validation logic implements several business rules before allowing gift submission. Users must have an active decentralized identifier selected, cannot submit negative amounts, and must provide either a description or a numeric amount. The system also prevents the logical error of selecting the same person as both giver and recipient in person-to-person transactions.

Gift Recording Logic

API Parameter Mapping

The component translates UI selections into endorser server API parameters:

// Person-to-Person Gift
{
  fromDid: giver.did,
  toDid: receiver.did,
  description: description,
  amount: parseFloat(amountInput),
  unit: unitCode
}

// Person-to-Project Gift  
{
  fromDid: giver.did,
  fulfillsProjectHandleId: toProjectId,
  description: description,
  amount: parseFloat(amountInput),
  unit: unitCode
}

// Project-to-Person Gift
{
  providerPlanHandleId: fromProjectId,
  toDid: receiver.did,
  description: description,
  amount: parseFloat(amountInput),
  unit: unitCode
}

The final step in the gift recording process involves translating the user's selections into the specific parameter format expected by the endorser server API. This mapping is complex because the API uses different fields depending on whether entities are people or projects. For project-to-person gifts, the project is identified by its handle ID in the providerPlanHandleId field, while the person is identified in the toDid field. Person-to-project gifts reverse this pattern, using fromDid for the person and fulfillsProjectHandleId for the project.

Person-to-person gifts use the simpler fromDid and toDid pattern.

State Management

Core State Variables

// UI State
visible: boolean = false;           // Dialog visibility
currentStep: number = 1;            // Current step (1 or 2)
stepType: string = "giver";         // Current selection type

// Entity State  
giver?: GiverReceiverInputInfo;     // Selected giver
receiver?: GiverReceiverInputInfo;  // Selected recipient
giverEntityType: "person" | "project";
recipientEntityType: "person" | "project";

// Form State
description: string = "";           // Gift description
amountInput: string = "0";         // Gift amount
unitCode: string = "HUR";          // Unit of measurement

// Data State
allContacts: Contact[] = [];        // Available contacts
projects: PlanData[] = [];          // Available projects
activeDid: string = "";             // Current user's DID

The component maintains several categories of state to track the user's progress through the gift recording process. UI state controls the dialog's visibility and current step, while entity state tracks the selected giver and recipient along with their types. Form state holds the user's input for the gift details, and data state contains the available options loaded from the database and API. This separation makes the component's behavior predictable and easier to debug.

Navigation State Transitions

graph TD
    A[Dialog Closed] --> B[open() called]
    B --> C{Giver pre-selected?}
    C -->|Yes| D[Step 2: Gift Details]
    C -->|No| E[Step 1: Entity Selection]
    E --> F{Entity selected}
    F --> D
    D --> G{User action}
    G -->|Edit Entity| E
    G -->|Confirm| H[Submit Gift]
    G -->|Cancel| A
    H --> I{Success?}
    I -->|Yes| A
    I -->|No| D

The state transition diagram illustrates the possible paths users can take through the dialog. The flow begins when the dialog is opened and branches based on whether sufficient context was provided to skip entity selection. Users can move back and forth between steps, edit their selections, or cancel at any time. After submitting a gift, the flow either returns to the closed state (on success) or back to the details step (on error) to allow for corrections.

Error Handling

Validation Layers

1. UI Prevention: Disable/gray out invalid options
2. Form Validation: Check required fields and business rules
3. API Validation: Handle server-side errors gracefully
4. User Feedback: Clear error messages with specific guidance

The component implements a multi-layered approach to error prevention and handling. The first layer prevents errors by disabling invalid options in the user interface, such as graying out contacts that would create conflicts. The second layer validates form inputs before submission, checking for required fields and business rule violations. The third layer handles errors returned by the server API, while the fourth layer ensures users receive clear, actionable feedback about any issues that occur.

Common Error Scenarios

• Missing Identifier: User hasn't selected an active DID
• Negative Amount: Prevent negative gift values
• Empty Gift: Require either description or amount
• Person Conflict: Same person selected as giver and recipient
• Network Errors: API server unreachable or returns errors
• Database Errors: Local storage issues

Each error scenario is handled with specific validation logic and user-friendly error messages. The component provides clear guidance on how to resolve issues, such as directing users to select an identifier or adjust their amount input. Network and database errors are caught and presented with appropriate fallback options.

Security Considerations

Data Privacy

• DID Protection: User identifiers only shared with explicit consent
• Local Storage: Sensitive data encrypted in local database
• Network Transport: All API calls use HTTPS encryption

The component maintains strict privacy controls over user data, particularly decentralized identifiers which serve as the core of user identity in the system. DIDs are only transmitted to the server when users explicitly choose to record a gift, and all local storage uses encryption to protect sensitive information.

Input Validation

• SQL Injection Prevention: Parameterized database queries
• XSS Protection: Input sanitization and Vue's built-in escaping
• Amount Validation: Numeric input validation and range checking

All user inputs are validated both on the client side for immediate feedback and on the server side for security. The component uses parameterized queries to prevent SQL injection attacks and relies on Vue's built-in template escaping to prevent cross-site scripting vulnerabilities.

Performance Optimization

Lazy Loading

• Projects: Only loaded when needed for project-related gifts
• Contacts: Cached after initial load to avoid repeated queries
• Database: Optimized queries with proper indexing

The component optimizes performance by loading data only when needed. Projects are fetched from the API only when the dialog needs to display them, reducing unnecessary network requests. Contact information is cached after the initial load to avoid repeated database queries. Database operations are optimized through proper indexing and efficient query patterns.

Reactive Updates

• Watchers: Automatically update entity types when props change
• Computed Properties: Efficient conflict detection and UI state
• Minimal Re-renders: Strategic use of v-show vs v-if

Vue's reactivity system is leveraged to ensure the interface stays synchronized with changing data while minimizing unnecessary re-renders. Watchers automatically update internal state when component properties change, computed properties efficiently calculate derived state like conflict detection, and the template uses v-show instead of v-if where appropriate to avoid expensive DOM manipulations.

GiftedDialog Integration Points

External Dependencies

• Endorser Server: Gift submission and verification
• Database Layer: Contact and settings management
• Platform Services: Cross-platform database access
• Router: Navigation to related views

The component integrates with several external systems to provide its functionality. The endorser server handles the cryptographic signing and publishing of gift records to the distributed network. The database layer manages local storage of contacts and user settings. Platform services provide an abstraction layer for database access across different deployment targets (web, mobile, desktop). The Vue router enables navigation to related views while preserving state.

Child Components

• EntityIcon: Person avatar rendering with fallbacks
• ProjectIcon: Project icon rendering with custom images
• Notification System: User feedback and error reporting

The dialog relies on several child components to provide specialized functionality. EntityIcon handles the complex logic of rendering person avatars with appropriate fallbacks when images aren't available. ProjectIcon performs similar duties for project representations. The notification system provides consistent user feedback across the application for both success and error conditions.

Future Considerations

Extensibility

• New Entity Types: Architecture supports additional entity types
• Custom Units: Easy to add new currency/unit types
• Workflow Steps: Framework supports additional steps if needed

The component's architecture is designed to accommodate future enhancements without major restructuring. The entity type system could be extended to support new types beyond people and projects. The unit selection system can easily accommodate new currencies or measurement types. The step-based workflow could be expanded to include additional steps for more complex gift recording scenarios.

Accessibility

• Keyboard Navigation: All interactive elements accessible
• Screen Readers: Semantic HTML and ARIA labels
• Color Contrast: Visual indicators don't rely solely on color

Accessibility considerations ensure the component is usable by people with disabilities. All interactive elements can be navigated using only the keyboard, semantic HTML and ARIA labels provide context for screen readers, and visual indicators use more than just color to convey information. These features make the gift recording process inclusive for all users.

Testing Strategy

• Unit Tests: Individual method testing
• Integration Tests: Full workflow testing
• E2E Tests: User journey validation
• Error Scenarios: Comprehensive error path testing

A comprehensive testing strategy ensures the component works reliably across different scenarios and platforms. Unit tests validate individual methods and computed properties, integration tests verify the complete workflow from opening to submission, end-to-end tests simulate real user journeys, and error scenario tests ensure graceful handling of failure conditions.

Component Usage and Integration Context

Primary Views and Usage Patterns

The GiftedDialog component is referenced and used throughout the Time Safari application in various contexts, each with specific requirements and configurations. Understanding where and how this component is integrated provides insight into its versatility and the different user workflows it supports.

1. HomeView - Main Entry Point

File: src/views/HomeView.vue
Context: Primary application dashboard and activity feed

The HomeView serves as the main entry point for gift recording, providing users with multiple pathways to create gift records. The dialog is integrated here with a showProjectsDialog property that controls whether project options are displayed in the entity selection interface.

<GiftedDialog ref="customDialog" :show-projects="showProjectsDialog" />

Usage Patterns:

• Gift Prompts Integration: Connected with GiftedPrompts component to provide suggested gift ideas
• "Unnamed" Giver Support: Special handling for recording gifts from unknown or unnamed individuals
• Context-Aware Opening: Different title and prompt text based on whether recording from a person or project

The HomeView implementation includes sophisticated logic for handling "Unnamed" givers, where the dialog is opened with specific pre-selections and immediately advances to Step 2 after calling selectGiver(). This streamlines the user experience when users want to record gifts from people not in their contact list.

2. ProjectViewView - Project-Specific Context

File: src/views/ProjectViewView.vue
Context: Individual project pages with bidirectional gift recording

ProjectViewView contains two separate instances of GiftedDialog to handle different gift directions:

<!-- For gifts TO the project -->
<GiftedDialog
  ref="giveDialogToThis"
  :to-project-id="projectId"
  :is-from-project-view="true"
/>

<!-- For gifts FROM the project -->
<GiftedDialog
  ref="giveDialogFromThis"
  :from-project-id="projectId"
  :is-from-project-view="true"
/>

Specialized Features:

• Bidirectional Gift Recording: Supports both giving to and receiving from projects
• Project Context Locking: The project entity is pre-selected and cannot be changed
• Offer Integration: Can be opened with pre-populated offer information
• Project-Specific Prompts: Custom titles and descriptions based on project context

The ProjectViewView demonstrates the component's flexibility in handling complex scenarios where one entity (the project) is fixed while the other (person) needs to be selected. The isFromProjectView property helps the dialog understand this constrained context.

3. ContactsView - Contact-Specific Gift Recording

File: src/views/ContactsView.vue
Context: Contact management with direct gift recording capabilities

ContactsView integrates the dialog for recording gifts between the current user and specific contacts, with sophisticated confirmation flows to ensure users understand the direction of the gift:

<GiftedDialog ref="customGivenDialog" />

Key Features:

• Bidirectional Confirmation: Users confirm whether they're recording giving or receiving
• Contact Pre-selection: The contact is already known, simplifying entity selection
• Direction Clarity: Clear messaging about gift direction to prevent confusion

The ContactsView implementation includes a two-step confirmation process (confirmShowGiftedDialog and showGiftedDialog) that ensures users clearly understand whether they're recording giving something to a contact or receiving something from them.

4. ContactGiftingView - Specialized Gift Recording Interface

File: src/views/ContactGiftingView.vue
Context: Dedicated interface for complex gift recording scenarios

This view provides a specialized interface for gift recording with advanced entity type handling and step management:

<GiftedDialog
  ref="customDialog"
  :from-project-id="fromProjectId"
  :to-project-id="toProjectId"
  :show-projects="showProjects"
  :is-from-project-view="isFromProjectView"
/>

Advanced Features:

• Dynamic Entity Type Resolution: Supports complex scenarios with projects and people
• Step Type Management: Handles both giver and recipient selection workflows
• Context Preservation: Maintains complex state across navigation

ContactGiftingView demonstrates the most sophisticated usage of GiftedDialog, with comprehensive support for all entity type combinations and step management scenarios.

5. ClaimView - Offer Fulfillment Context

File: src/views/ClaimView.vue
Context: Converting offers into actual gift records

ClaimView uses GiftedDialog to record gifts that fulfill existing offers, creating a connection between the offer system and gift recording:

<GiftedDialog ref="customGiveDialog" />

Offer Integration Features:

• Offer Pre-population: Gift details can be pre-filled from offer information
• Fulfillment Tracking: Links gifts to specific offers for tracking purposes
• Context-Aware Prompts: Custom messaging for offer fulfillment scenarios

6. Supporting Views - Additional Integration Points

RecentOffersToUserView & RecentOffersToUserProjectsView:

• Provide quick access to gift recording from offer listings
• Support both personal and project-related offer contexts

NewActivityView:

• Integrates gift recording into activity creation workflows
• Supports creating gifts as part of broader activity documentation

Integration Patterns and Best Practices

Common Integration Pattern

Most views follow a consistent pattern for integrating GiftedDialog:

1. Template Declaration: Include the component with appropriate props
2. Reference Setup: Use ref attribute for programmatic access
3. Method Integration: Implement openDialog or similar methods
4. Context Configuration: Set appropriate props based on view context
5. State Management: Handle dialog results and state updates

Props Configuration Strategy

The component's props are designed to work together to create specific behaviors:

• Mutual Exclusivity: fromProjectId and toProjectId are mutually exclusive
• Context Indicators: isFromProjectView provides navigation context
• Display Control: showProjects overrides default entity type logic
• Behavioral Modification: Props combination determines available workflows

Error Handling and User Experience

Each integration point implements appropriate error handling and user experience considerations:

• Validation Feedback: Clear error messages for invalid selections
• Context Preservation: State maintained across navigation
• Graceful Degradation: Fallback options when data is unavailable
• Accessibility Support: Keyboard navigation and screen reader compatibility

Development and Maintenance Considerations

Component Coupling

The widespread usage of GiftedDialog creates important coupling considerations:

• Interface Stability: Changes to the component's API affect multiple views
• Testing Requirements: Each integration context requires specific test coverage
• Performance Impact: Component optimization benefits multiple user workflows
• Documentation Needs: Clear usage patterns help maintain consistency

Future Evolution

The component's integration patterns suggest several areas for future development:

• Workflow Standardization: Common patterns could be extracted into mixins
• State Management: Complex state could benefit from centralized management
• Type Safety: Better TypeScript integration for props and methods
• Accessibility Enhancement: Consistent accessibility patterns across integrations

This comprehensive integration context demonstrates how GiftedDialog serves as a central component in the Time Safari application's gift recording ecosystem, supporting diverse user workflows while maintaining consistency and usability across different contexts.

Detailed Implementation Roadmap for Future Enhancements

1. New Entity Types Implementation

The current architecture supports people and projects, but could be extended to support additional entity types such as organizations, events, or resources. Here's precisely what these changes would look like:

Current Entity Type System

// Current implementation in GiftedDialog.vue
giverEntityType: "person" | "project" = "person";
recipientEntityType: "person" | "project" = "person";

updateEntityTypes() {
  this.giverEntityType = "person";
  this.recipientEntityType = "person";
  
  if (this.showProjects) {
    this.giverEntityType = "project";
  } else if (this.fromProjectId) {
    this.giverEntityType = "project";
  } else if (this.toProjectId) {
    this.recipientEntityType = "project";
  }
}

Extended Entity Type System

// Enhanced implementation with new entity types
type EntityType = "person" | "project" | "organization" | "event" | "resource";

// New props to support additional entity types
@Prop() fromOrganizationId = "";
@Prop() toOrganizationId = "";
@Prop() fromEventId = "";
@Prop() toEventId = "";
@Prop() fromResourceId = "";
@Prop() toResourceId = "";
@Prop() showOrganizations = false;
@Prop() showEvents = false;
@Prop() showResources = false;

giverEntityType: EntityType = "person";
recipientEntityType: EntityType = "person";

updateEntityTypes() {
  // Reset to default
  this.giverEntityType = "person";
  this.recipientEntityType = "person";
  
  // Apply context-specific logic with priority order
  if (this.showOrganizations) {
    this.giverEntityType = "organization";
  } else if (this.showEvents) {
    this.giverEntityType = "event";
  } else if (this.showResources) {
    this.giverEntityType = "resource";
  } else if (this.showProjects) {
    this.giverEntityType = "project";
  } else if (this.fromOrganizationId) {
    this.giverEntityType = "organization";
  } else if (this.fromEventId) {
    this.giverEntityType = "event";
  } else if (this.fromResourceId) {
    this.giverEntityType = "resource";
  } else if (this.fromProjectId) {
    this.giverEntityType = "project";
  } else if (this.toOrganizationId) {
    this.recipientEntityType = "organization";
  } else if (this.toEventId) {
    this.recipientEntityType = "event";
  } else if (this.toResourceId) {
    this.recipientEntityType = "resource";
  } else if (this.toProjectId) {
    this.recipientEntityType = "project";
  }
}

New Component Integration Required

<!-- New icon components needed -->
<template>
  <OrganizationIcon
    v-if="giverEntityType === 'organization'"
    :entity-id="giver?.handleId"
    :icon-size="32"
    class="rounded-full bg-white overflow-hidden !size-[2rem] object-cover"
  />
  <EventIcon
    v-else-if="giverEntityType === 'event'"
    :entity-id="giver?.handleId"
    :icon-size="32"
    class="rounded-full bg-white overflow-hidden !size-[2rem] object-cover"
  />
  <ResourceIcon
    v-else-if="giverEntityType === 'resource'"
    :entity-id="giver?.handleId"
    :icon-size="32"
    class="rounded-full bg-white overflow-hidden !size-[2rem] object-cover"
  />
</template>

API Parameter Mapping Extensions

// Extended gift recording logic
async recordGive() {
  let apiParams: any = {
    description: this.description,
    amount: parseFloat(this.amountInput),
    unit: this.unitCode
  };

  // Entity-specific parameter mapping
  switch (`${this.giverEntityType}-${this.recipientEntityType}`) {
    case "person-person":
      apiParams.fromDid = this.giver?.did;
      apiParams.toDid = this.receiver?.did;
      break;
    case "person-project":
      apiParams.fromDid = this.giver?.did;
      apiParams.fulfillsProjectHandleId = this.toProjectId;
      break;
    case "project-person":
      apiParams.providerPlanHandleId = this.fromProjectId;
      apiParams.toDid = this.receiver?.did;
      break;
    case "person-organization":
      apiParams.fromDid = this.giver?.did;
      apiParams.fulfillsOrganizationHandleId = this.toOrganizationId;
      break;
    case "organization-person":
      apiParams.providerOrganizationHandleId = this.fromOrganizationId;
      apiParams.toDid = this.receiver?.did;
      break;
    case "person-event":
      apiParams.fromDid = this.giver?.did;
      apiParams.fulfillsEventHandleId = this.toEventId;
      break;
    case "event-person":
      apiParams.providerEventHandleId = this.fromEventId;
      apiParams.toDid = this.receiver?.did;
      break;
    case "person-resource":
      apiParams.fromDid = this.giver?.did;
      apiParams.fulfillsResourceHandleId = this.toResourceId;
      break;
    case "resource-person":
      apiParams.providerResourceHandleId = this.fromResourceId;
      apiParams.toDid = this.receiver?.did;
      break;
    default:
      throw new Error(`Unsupported entity combination: ${this.giverEntityType}-${this.recipientEntityType}`);
  }

  // Submit to endorser server
  const result = await createAndSubmitGive(apiParams);
}

2. Custom Units Implementation

The current unit system supports Hours, USD, BTC, BX, and ETH. Here's how to add new currency/unit types:

Current Unit System

// Current implementation in GiftedDialog.vue
unitCode = "HUR";

// In template
<select v-model="unitCode" class="flex-1 rounded border border-slate-400 ms-2 px-3 py-2">
  <option value="HUR">Hours</option>
  <option value="USD">US $</option>
  <option value="BTC">BTC</option>
  <option value="BX">BX</option>
  <option value="ETH">ETH</option>
</select>

Enhanced Unit System

// New unit configuration system
interface UnitDefinition {
  code: string;
  name: string;
  symbol: string;
  category: "time" | "currency" | "token" | "custom";
  decimals: number;
  conversionRate?: number; // Optional conversion to base unit
}

// Configurable unit registry
const UNIT_REGISTRY: UnitDefinition[] = [
  // Time units
  { code: "HUR", name: "Hours", symbol: "hr", category: "time", decimals: 2 },
  { code: "MIN", name: "Minutes", symbol: "min", category: "time", decimals: 0 },
  { code: "DAY", name: "Days", symbol: "day", category: "time", decimals: 1 },
  
  // Traditional currencies
  { code: "USD", name: "US Dollar", symbol: "$", category: "currency", decimals: 2 },
  { code: "EUR", name: "Euro", symbol: "€", category: "currency", decimals: 2 },
  { code: "GBP", name: "British Pound", symbol: "£", category: "currency", decimals: 2 },
  
  // Cryptocurrencies
  { code: "BTC", name: "Bitcoin", symbol: "₿", category: "token", decimals: 8 },
  { code: "ETH", name: "Ethereum", symbol: "Ξ", category: "token", decimals: 18 },
  { code: "BX", name: "BX Token", symbol: "BX", category: "token", decimals: 4 },
  
  // Custom units
  { code: "KARMA", name: "Karma Points", symbol: "♦", category: "custom", decimals: 0 },
  { code: "SKILL", name: "Skill Points", symbol: "⚡", category: "custom", decimals: 1 },
  { code: "REP", name: "Reputation", symbol: "★", category: "custom", decimals: 0 }
];

// Enhanced component implementation
export default class GiftedDialog extends Vue {
  unitCode = "HUR";
  availableUnits: UnitDefinition[] = [];

  async mounted() {
    // Load available units based on user preferences or context
    this.availableUnits = await this.loadAvailableUnits();
  }

  async loadAvailableUnits(): Promise<UnitDefinition[]> {
    // Load from user settings or default configuration
    const userSettings = await this.getUserSettings();
    if (userSettings.customUnits && userSettings.customUnits.length > 0) {
      return [...UNIT_REGISTRY, ...userSettings.customUnits];
    }
    return UNIT_REGISTRY;
  }

  get unitsByCategory() {
    return this.availableUnits.reduce((acc, unit) => {
      if (!acc[unit.category]) acc[unit.category] = [];
      acc[unit.category].push(unit);
      return acc;
    }, {} as Record<string, UnitDefinition[]>);
  }

  get selectedUnit(): UnitDefinition | undefined {
    return this.availableUnits.find(unit => unit.code === this.unitCode);
  }

  formatAmount(amount: number): string {
    const unit = this.selectedUnit;
    if (!unit) return amount.toString();
    
    const formattedAmount = amount.toFixed(unit.decimals);
    return `${unit.symbol}${formattedAmount}`;
  }
}

Enhanced Template with Categorized Units

<template>
  <!-- Enhanced unit selector with categories -->
  <select
    v-model="unitCode"
    class="flex-1 rounded border border-slate-400 ms-2 px-3 py-2"
  >
    <optgroup
      v-for="(units, category) in unitsByCategory"
      :key="category"
      :label="category.charAt(0).toUpperCase() + category.slice(1)"
    >
      <option
        v-for="unit in units"
        :key="unit.code"
        :value="unit.code"
      >
        {{ unit.symbol }} {{ unit.name }}
      </option>
    </optgroup>
  </select>

  <!-- Display formatted amount -->
  <div class="text-sm text-gray-600 mt-1">
    {{ formatAmount(parseFloat(amountInput) || 0) }}
  </div>
</template>

3. Workflow Steps Enhancement

The current two-step workflow could be expanded to include additional steps for more complex scenarios:

Current Workflow Structure

// Current step management
currentStep = 1; // 1 = Entity Selection, 2 = Gift Details

goToStep2() {
  this.currentStep = 2;
}

goBackToStep1(stepType: string) {
  this.stepType = stepType;
  this.currentStep = 1;
}

Enhanced Multi-Step Workflow

// Enhanced workflow with additional steps
type WorkflowStep = "entity-selection" | "gift-details" | "verification" | "attachment" | "confirmation";

interface WorkflowDefinition {
  steps: WorkflowStep[];
  currentStepIndex: number;
  canSkipStep: (step: WorkflowStep) => boolean;
  isStepRequired: (step: WorkflowStep) => boolean;
}

export default class GiftedDialog extends Vue {
  workflow: WorkflowDefinition = {
    steps: ["entity-selection", "gift-details", "verification", "confirmation"],
    currentStepIndex: 0,
    canSkipStep: (step) => {
      switch (step) {
        case "entity-selection":
          return this.giver && this.receiver; // Skip if entities pre-selected
        case "attachment":
          return true; // Always optional
        case "verification":
          return parseFloat(this.amountInput) === 0; // Skip for zero-amount gifts
        default:
          return false;
      }
    },
    isStepRequired: (step) => {
      switch (step) {
        case "entity-selection":
        case "gift-details":
        case "confirmation":
          return true;
        case "verification":
          return parseFloat(this.amountInput) > 0;
        case "attachment":
          return false;
        default:
          return false;
      }
    }
  };

  get currentStep(): WorkflowStep {
    return this.workflow.steps[this.workflow.currentStepIndex];
  }

  get canGoNext(): boolean {
    return this.workflow.currentStepIndex < this.workflow.steps.length - 1;
  }

  get canGoPrevious(): boolean {
    return this.workflow.currentStepIndex > 0;
  }

  async nextStep() {
    if (!this.canGoNext) return;

    // Validate current step before proceeding
    const isValid = await this.validateCurrentStep();
    if (!isValid) return;

    this.workflow.currentStepIndex++;

    // Skip optional steps if conditions are met
    while (
      this.workflow.currentStepIndex < this.workflow.steps.length &&
      this.workflow.canSkipStep(this.currentStep)
    ) {
      this.workflow.currentStepIndex++;
    }
  }

  previousStep() {
    if (!this.canGoPrevious) return;

    this.workflow.currentStepIndex--;

    // Skip back over optional steps
    while (
      this.workflow.currentStepIndex >= 0 &&
      this.workflow.canSkipStep(this.currentStep)
    ) {
      this.workflow.currentStepIndex--;
    }
  }

  async validateCurrentStep(): Promise<boolean> {
    switch (this.currentStep) {
      case "entity-selection":
        return this.validateEntitySelection();
      case "gift-details":
        return this.validateGiftDetails();
      case "verification":
        return this.validateVerification();
      case "attachment":
        return true; // Always valid since optional
      case "confirmation":
        return this.validateConfirmation();
      default:
        return false;
    }
  }

  private validateEntitySelection(): boolean {
    if (!this.giver || !this.receiver) {
      this.$notify({
        type: "danger",
        text: "Please select both giver and recipient"
      });
      return false;
    }
    return true;
  }

  private validateGiftDetails(): boolean {
    if (!this.description && !parseFloat(this.amountInput)) {
      this.$notify({
        type: "danger",
        text: "Please provide either a description or amount"
      });
      return false;
    }
    return true;
  }

  private validateVerification(): boolean {
    // Implement verification logic (e.g., confirm large amounts)
    const amount = parseFloat(this.amountInput);
    if (amount > 1000) {
      // Could show a confirmation dialog here
      return this.confirmLargeAmount();
    }
    return true;
  }

  private validateConfirmation(): boolean {
    // Final validation before submission
    return this.validateEntitySelection() && this.validateGiftDetails();
  }
}

Enhanced Template with Multi-Step Navigation

<template>
  <div v-if="visible" class="dialog-overlay">
    <div class="dialog">
      <!-- Step indicator -->
      <div class="step-indicator mb-4">
        <div class="flex justify-between">
          <div
            v-for="(step, index) in workflow.steps"
            :key="step"
            :class="[
              'step-item',
              {
                'active': index === workflow.currentStepIndex,
                'completed': index < workflow.currentStepIndex,
                'optional': !workflow.isStepRequired(step)
              }
            ]"
          >
            {{ step.replace('-', ' ').replace(/\b\w/g, l => l.toUpperCase()) }}
          </div>
        </div>
      </div>

      <!-- Entity Selection Step -->
      <div v-show="currentStep === 'entity-selection'" class="step-content">
        <!-- Existing entity selection UI -->
      </div>

      <!-- Gift Details Step -->
      <div v-show="currentStep === 'gift-details'" class="step-content">
        <!-- Existing gift details UI -->
      </div>

      <!-- New Verification Step -->
      <div v-show="currentStep === 'verification'" class="step-content">
        <h3 class="text-lg font-semibold mb-4">Verify Gift Details</h3>
        
        <div class="verification-summary bg-gray-50 p-4 rounded-lg mb-4">
          <div class="grid grid-cols-2 gap-4">
            <div>
              <label class="block text-sm font-medium text-gray-700">From:</label>
              <p class="mt-1">{{ giver?.name || 'Unnamed' }}</p>
            </div>
            <div>
              <label class="block text-sm font-medium text-gray-700">To:</label>
              <p class="mt-1">{{ receiver?.name || 'Unnamed' }}</p>
            </div>
            <div>
              <label class="block text-sm font-medium text-gray-700">Amount:</label>
              <p class="mt-1">{{ formatAmount(parseFloat(amountInput) || 0) }}</p>
            </div>
            <div>
              <label class="block text-sm font-medium text-gray-700">Description:</label>
              <p class="mt-1">{{ description || 'No description' }}</p>
            </div>
          </div>
        </div>

        <!-- Large amount warning -->
        <div
          v-if="parseFloat(amountInput) > 1000"
          class="warning-box bg-yellow-50 border border-yellow-200 p-4 rounded-lg mb-4"
        >
          <div class="flex">
            <font-awesome icon="exclamation-triangle" class="text-yellow-400 mr-2" />
            <div>
              <h4 class="text-sm font-medium text-yellow-800">Large Amount Detected</h4>
              <p class="mt-1 text-sm text-yellow-700">
                Please verify this {{ formatAmount(parseFloat(amountInput)) }} gift is correct.
              </p>
            </div>
          </div>
        </div>
      </div>

      <!-- New Attachment Step -->
      <div v-show="currentStep === 'attachment'" class="step-content">
        <h3 class="text-lg font-semibold mb-4">Add Attachments (Optional)</h3>
        
        <div class="attachment-options">
          <button
            @click="addPhoto"
            class="w-full p-4 border-2 border-dashed border-gray-300 rounded-lg text-center hover:border-gray-400 mb-4"
          >
            <font-awesome icon="camera" class="text-2xl text-gray-400 mb-2" />
            <p class="text-gray-600">Add Photo</p>
          </button>

          <button
            @click="addDocument"
            class="w-full p-4 border-2 border-dashed border-gray-300 rounded-lg text-center hover:border-gray-400"
          >
            <font-awesome icon="file" class="text-2xl text-gray-400 mb-2" />
            <p class="text-gray-600">Add Document</p>
          </button>
        </div>

        <!-- Show attached files -->
        <div v-if="attachments.length > 0" class="mt-4">
          <h4 class="font-medium mb-2">Attached Files:</h4>
          <ul class="space-y-2">
            <li
              v-for="(attachment, index) in attachments"
              :key="index"
              class="flex items-center justify-between bg-gray-50 p-2 rounded"
            >
              <span class="text-sm">{{ attachment.name }}</span>
              <button
                @click="removeAttachment(index)"
                class="text-red-600 hover:text-red-800"
              >
                <font-awesome icon="times" />
              </button>
            </li>
          </ul>
        </div>
      </div>

      <!-- Confirmation Step -->
      <div v-show="currentStep === 'confirmation'" class="step-content">
        <h3 class="text-lg font-semibold mb-4">Confirm Gift</h3>
        
        <div class="final-summary bg-blue-50 p-4 rounded-lg mb-4">
          <!-- Complete gift summary -->
          <div class="text-center">
            <div class="text-2xl mb-2">{{ formatAmount(parseFloat(amountInput) || 0) }}</div>
            <div class="text-lg font-medium">{{ description || 'Gift' }}</div>
            <div class="text-sm text-gray-600 mt-2">
              From {{ giver?.name || 'Unnamed' }} to {{ receiver?.name || 'Unnamed' }}
            </div>
          </div>
        </div>

        <div class="text-sm text-gray-600 mb-4">
          <font-awesome icon="info-circle" class="mr-1" />
          This gift will be recorded on the distributed network and cannot be deleted.
        </div>
      </div>

      <!-- Navigation buttons -->
      <div class="flex gap-2 mt-6">
        <button
          v-if="canGoPrevious"
          @click="previousStep"
          class="flex-1 bg-gray-200 text-gray-800 px-4 py-2 rounded-lg"
        >
          Previous
        </button>
        
        <button
          v-if="canGoNext"
          @click="nextStep"
          class="flex-1 bg-blue-600 text-white px-4 py-2 rounded-lg"
        >
          Next
        </button>
        
        <button
          v-if="currentStep === 'confirmation'"
          @click="confirm"
          class="flex-1 bg-green-600 text-white px-4 py-2 rounded-lg"
        >
          Confirm Gift
        </button>
        
        <button
          @click="cancel"
          class="bg-gray-400 text-white px-4 py-2 rounded-lg"
        >
          Cancel
        </button>
      </div>
    </div>
  </div>
</template>

<style scoped>
.step-indicator .step-item {
  @apply px-3 py-1 text-sm rounded-full border;
}

.step-indicator .step-item.active {
  @apply bg-blue-600 text-white border-blue-600;
}

.step-indicator .step-item.completed {
  @apply bg-green-600 text-white border-green-600;
}

.step-indicator .step-item.optional {
  @apply border-dashed;
}
</style>

4. Workflow Standardization Through Mixins

To address the repetitive integration patterns across views, common functionality could be extracted into mixins:

Current Repetitive Pattern

// Repeated across HomeView, ContactsView, ProjectViewView, etc.
openDialog(giver?: GiverReceiverInputInfo, description?: string) {
  (this.$refs.customDialog as GiftedDialog).open(
    giver,
    { did: this.activeDid, name: "You" },
    undefined,
    "Given by " + (giver?.name || "someone not named"),
    description,
  );
}

Standardized Mixin Implementation

// New file: src/mixins/GiftedDialogMixin.ts
import { Component, Vue } from "vue-facing-decorator";
import GiftedDialog from "@/components/GiftedDialog.vue";
import { GiverReceiverInputInfo } from "@/libs/util";

interface GiftedDialogConfig {
  ref: string;
  defaultGiver?: GiverReceiverInputInfo;
  defaultReceiver?: GiverReceiverInputInfo;
  titleTemplate?: string;
  promptTemplate?: string;
  fromProjectId?: string;
  toProjectId?: string;
  showProjects?: boolean;
  isFromProjectView?: boolean;
}

@Component
export default class GiftedDialogMixin extends Vue {
  protected giftedDialogConfig: GiftedDialogConfig = {
    ref: "customDialog"
  };

  /**
   * Standardized method to open GiftedDialog with consistent parameter handling
   */
  protected openGiftedDialog(options: {
    giver?: GiverReceiverInputInfo | "Unnamed";
    receiver?: GiverReceiverInputInfo;
    offerId?: string;
    customTitle?: string;
    prompt?: string;
    callbackOnSuccess?: (amount: number) => void;
  } = {}) {
    const config = this.giftedDialogConfig;
    const dialog = this.$refs[config.ref] as GiftedDialog;

    if (!dialog) {
      console.error(`GiftedDialog ref '${config.ref}' not found`);
      return;
    }

    // Handle "Unnamed" giver special case
    if (options.giver === "Unnamed") {
      dialog.open(
        undefined,
        options.receiver || config.defaultReceiver || this.getCurrentUser(),
        options.offerId,
        options.customTitle || "Given by Unnamed",
        options.prompt
      );
      dialog.selectGiver(); // Immediately advance to step 2
      return;
    }

    // Standard dialog opening
    const giver = options.giver || config.defaultGiver;
    const receiver = options.receiver || config.defaultReceiver || this.getCurrentUser();
    const title = options.customTitle || this.generateTitle(giver, receiver);
    
    dialog.open(
      giver,
      receiver,
      options.offerId,
      title,
      options.prompt,
      options.callbackOnSuccess
    );
  }

  /**
   * Generate contextual title based on entities
   */
  private generateTitle(
    giver?: GiverReceiverInputInfo,
    receiver?: GiverReceiverInputInfo
  ): string {
    const template = this.giftedDialogConfig.titleTemplate;
    if (template) {
      return template
        .replace("{giver}", giver?.name || "someone")
        .replace("{receiver}", receiver?.name || "someone");
    }

    if (giver) {
      return `Given by ${giver.name || "someone not named"}`;
    }
    return "Record a Gift";
  }

  /**
   * Get current user as GiverReceiverInputInfo
   */
  private getCurrentUser(): GiverReceiverInputInfo {
    return {
      did: this.activeDid || "",
      name: "You"
    };
  }

  /**
   * Handle dialog success callback
   */
  protected onGiftRecorded(amount: number) {
    this.$notify({
      group: "alert",
      type: "success",
      title: "Gift Recorded",
      text: `Successfully recorded gift of ${amount}`
    });
  }

  /**
   * Utility method for project-specific dialog opening
   */
  protected openProjectGiftDialog(
    projectId: string,
    isGiving: boolean,
    customTitle?: string
  ) {
    const projectEntity = this.getProjectEntity(projectId);
    
    if (isGiving) {
      // User is giving to project
      this.openGiftedDialog({
        giver: this.getCurrentUser(),
        receiver: projectEntity,
        customTitle: customTitle || `Gift to ${projectEntity?.name || "Project"}`
      });
    } else {
      // User received from project
      this.openGiftedDialog({
        giver: projectEntity,
        receiver: this.getCurrentUser(),
        customTitle: customTitle || `Gift from ${projectEntity?.name || "Project"}`
      });
    }
  }

  /**
   * Get project entity by ID (to be implemented by consuming component)
   */
  protected getProjectEntity(projectId: string): GiverReceiverInputInfo | undefined {
    // Override in consuming component
    return undefined;
  }

  // Abstract properties that consuming components should provide
  protected abstract activeDid: string;
}

Updated Component Implementation Using Mixin

// Updated HomeView.vue using the mixin
import { Component, Mixins } from "vue-facing-decorator";
import GiftedDialogMixin from "@/mixins/GiftedDialogMixin";

@Component({
  components: {
    GiftedDialog,
    // ... other components
  }
})
export default class HomeView extends Mixins(GiftedDialogMixin) {
  // Configure the mixin
  protected giftedDialogConfig = {
    ref: "customDialog",
    titleTemplate: "Given by {giver}",
    showProjects: this.showProjectsDialog
  };

  // Simplified dialog opening methods
  openDialog(giver?: GiverReceiverInputInfo | "Unnamed", description?: string) {
    this.openGiftedDialog({
      giver,
      prompt: description,
      callbackOnSuccess: this.onGiftRecorded
    });
  }

  openGiftedPrompts() {
    (this.$refs.giftedPrompts as GiftedPrompts).open((giver, description) =>
      this.openDialog(giver as GiverReceiverInputInfo, description)
    );
  }

  // Override abstract method
  protected getProjectEntity(projectId: string): GiverReceiverInputInfo | undefined {
    const project = this.projects.find(p => p.handleId === projectId);
    if (!project) return undefined;

    return {
      did: project.handleId,
      name: project.name,
      handleId: project.handleId,
      image: project.image
    };
  }
}

5. State Management Centralization

Complex state could be moved to a centralized Pinia store:

New Pinia Store Implementation

// New file: src/stores/giftDialog.ts
import { defineStore } from 'pinia';
import { GiverReceiverInputInfo } from '@/libs/util';

interface GiftDialogState {
  isVisible: boolean;
  currentStep: WorkflowStep;
  giverEntityType: EntityType;
  recipientEntityType: EntityType;
  giver?: GiverReceiverInputInfo;
  receiver?: GiverReceiverInputInfo;
  description: string;
  amountInput: string;
  unitCode: string;
  validationErrors: string[];
  isSubmitting: boolean;
}

export const useGiftDialogStore = defineStore('giftDialog', {
  state: (): GiftDialogState => ({
    isVisible: false,
    currentStep: 'entity-selection',
    giverEntityType: 'person',
    recipientEntityType: 'person',
    giver: undefined,
    receiver: undefined,
    description: '',
    amountInput: '0',
    unitCode: 'HUR',
    validationErrors: [],
    isSubmitting: false
  }),

  getters: {
    isValid: (state) => {
      return state.giver && state.receiver && 
             (state.description || parseFloat(state.amountInput) > 0);
    },
    
    hasPersonConflict: (state) => {
      return state.giver?.did === state.receiver?.did && 
             state.giver?.did !== undefined &&
             state.giverEntityType === 'person' &&
             state.recipientEntityType === 'person';
    },
    
    formattedAmount: (state) => {
      const amount = parseFloat(state.amountInput) || 0;
      const unit = UNIT_REGISTRY.find(u => u.code === state.unitCode);
      return unit ? `${unit.symbol}${amount.toFixed(unit.decimals)}` : amount.toString();
    }
  },

  actions: {
    openDialog(config: {
      giver?: GiverReceiverInputInfo;
      receiver?: GiverReceiverInputInfo;
      prompt?: string;
    }) {
      this.isVisible = true;
      this.giver = config.giver;
      this.receiver = config.receiver;
      this.description = config.prompt || '';
      this.currentStep = config.giver ? 'gift-details' : 'entity-selection';
      this.resetValidation();
    },

    closeDialog() {
      this.isVisible = false;
      this.resetForm();
    },

    setGiver(giver: GiverReceiverInputInfo) {
      this.giver = giver;
      this.validateStep();
    },

    setReceiver(receiver: GiverReceiverInputInfo) {
      this.receiver = receiver;
      this.validateStep();
    },

    updateDescription(description: string) {
      this.description = description;
      this.validateStep();
    },

    updateAmount(amount: string) {
      this.amountInput = amount;
      this.validateStep();
    },

    updateUnit(unitCode: string) {
      this.unitCode = unitCode;
    },

    addAttachment(file: File) {
      this.attachments.push(file);
    },

    removeAttachment(index: number) {
      this.attachments.splice(index, 1);
    },

    validateStep(): boolean {
      this.validationErrors = [];

      switch (this.currentStep) {
        case 'entity-selection':
          if (!this.giver) this.validationErrors.push('Please select a giver');
          if (!this.receiver) this.validationErrors.push('Please select a receiver');
          if (this.hasPersonConflict) {
            this.validationErrors.push('Cannot select the same person as both giver and recipient');
          }
          break;

        case 'gift-details':
          if (!this.description && !parseFloat(this.amountInput)) {
            this.validationErrors.push('Please provide description or amount');
          }
          if (parseFloat(this.amountInput) < 0) {
            this.validationErrors.push('Amount cannot be negative');
          }
          break;
      }

      return this.validationErrors.length === 0;
    },

    async submitGift(): Promise<boolean> {
      if (!this.isValid) return false;

      this.isSubmitting = true;
      try {
        // Submit logic here
        const result = await this.createGiftRecord();
        if (result.success) {
          this.closeDialog();
          return true;
        }
        return false;
      } finally {
        this.isSubmitting = false;
      }
    },

    private resetForm() {
      this.giver = undefined;
      this.receiver = undefined;
      this.description = '';
      this.amountInput = '0';
      this.unitCode = 'HUR';
      this.attachments = [];
      this.resetValidation();
    },

    private resetValidation() {
      this.validationErrors = [];
    },

    private async createGiftRecord() {
      // Implementation would go here
      return { success: true };
    }
  }
});

Updated Component Using Store

// Updated GiftedDialog.vue using Pinia store
import { useGiftDialogStore } from '@/stores/giftDialog';

@Component({
  components: { EntityIcon, ProjectIcon }
})
export default class GiftedDialog extends Vue {
  private giftDialogStore = useGiftDialogStore();

  // Computed properties map to store getters
  get visible() { return this.giftDialogStore.isVisible; }
  get currentStep() { return this.giftDialogStore.currentStep; }
  get giver() { return this.giftDialogStore.giver; }
  get receiver() { return this.giftDialogStore.receiver; }
  get description() { return this.giftDialogStore.description; }
  get amountInput() { return this.giftDialogStore.amountInput; }
  get unitCode() { return this.giftDialogStore.unitCode; }
  get validationErrors() { return this.giftDialogStore.validationErrors; }
  get isSubmitting() { return this.giftDialogStore.isSubmitting; }

  // Methods delegate to store actions
  open(giver?: GiverReceiverInputInfo, receiver?: GiverReceiverInputInfo, prompt?: string) {
    this.giftDialogStore.openDialog({ giver, receiver, prompt });
  }

  close() {
    this.giftDialogStore.closeDialog();
  }

  selectGiver(giver: GiverReceiverInputInfo) {
    this.giftDialogStore.setGiver(giver);
  }

  selectReceiver(receiver: GiverReceiverInputInfo) {
    this.giftDialogStore.setReceiver(receiver);
  }

  async confirm() {
    const success = await this.giftDialogStore.submitGift();
    if (success) {
      this.$notify({
        type: "success",
        text: "Gift recorded successfully"
      });
    }
  }
}

These detailed implementations show precisely what the future enhancements would look like, providing clear roadmaps for extending the GiftedDialog component's capabilities while maintaining backward compatibility and improving maintainability.

---

ANNEX: Complete GiftedDialog Component Inventory

Purpose

This inventory serves as a comprehensive checklist to ensure no functionality is lost during the Pinia store refactoring. Each item must be accounted for in the new store-based implementation.

A. Component Props

Prop	Type	Default	Status	Store Field	Notes
fromProjectId	string	""	✅ Covered	N/A (passed as context)	Used to determine giverEntityType
toProjectId	string	""	✅ Covered	N/A (passed as context)	Used to determine recipientEntityType
showProjects	boolean	false	✅ Covered	N/A (passed as context)	Controls entity type display
isFromProjectView	boolean	false	✅ Covered	N/A (passed as context)	Navigation context flag

B. Core State Variables

Variable	Type	Default	Status	Store Field	Critical
visible	boolean	false	✅ Covered	isVisible	Yes
currentStep	number	1	✅ Covered	currentStep	Yes
stepType	string	"giver"	✅ Covered	entitySelectionMode	Yes (renamed)
giverEntityType	EntityType	"person"	✅ Covered	giverEntityType	Yes
recipientEntityType	EntityType	"person"	✅ Covered	recipientEntityType	Yes
giver	GiverReceiverInputInfo?	undefined	✅ Covered	giver	Yes
receiver	GiverReceiverInputInfo?	undefined	✅ Covered	receiver	Yes
description	string	""	✅ Covered	description	Yes
amountInput	string	"0"	✅ Covered	amountInput	Yes
unitCode	string	"HUR"	✅ Covered	unitCode	Yes

C. Context State Variables (CRITICAL - Previously Missing)

Variable	Type	Default	Status	Store Field	Critical
callbackOnSuccess	Function?	() => {}	❌ ADDED	callbackOnSuccess	YES
customTitle	string?	undefined	❌ ADDED	customTitle	YES
offerId	string	""	❌ ADDED	offerId	YES
prompt	string	""	❌ ADDED	prompt	YES

D. API and Account State Variables (CRITICAL - Previously Missing)

Variable	Type	Default	Status	Store Field	Critical
apiServer	string	""	❌ ADDED	apiServer	YES
activeDid	string	""	❌ ADDED	activeDid	YES
allMyDids	string[]	[]	❌ ADDED	allMyDids	YES

E. Data State Variables

Variable	Type	Default	Status	Store Field	Critical
allContacts	Contact[]	[]	✅ Covered	allContacts	Yes
projects	PlanData[]	[]	✅ Covered	projects	Yes

F. Utility References (CRITICAL - Previously Missing)

Variable	Type	Status	Store Implementation	Critical
libsUtil	object	❌ NEEDS IMPORT	Import in store	YES
didInfo	function	❌ NEEDS IMPORT	Import in store	YES

G. Computed Properties

Property	Return Type	Status	Store Getter	Critical
shouldShowProjects	boolean	✅ Covered	shouldShowProjects	Yes
hasPersonConflict	boolean	✅ Covered	hasPersonConflict	Yes
giftedDetailsQuery	object	✅ Covered	giftedDetailsQuery	Yes

H. Watchers

Watched Property	Handler	Status	Store Implementation	Critical
showProjects	onShowProjectsChange()	✅ Covered	Reactive in store	Yes
fromProjectId	onFromProjectIdChange()	✅ Covered	Reactive in store	Yes
toProjectId	onToProjectIdChange()	✅ Covered	Reactive in store	Yes

I. Public Methods (API Contract)

Method	Parameters	Return Type	Status	Store Action	Critical
open()	giver?, receiver?, offerId?, customTitle?, prompt?, callback?	Promise<void>	✅ Covered	openDialog()	YES
close()	none	void	✅ Covered	closeDialog()	Yes
cancel()	none	void	✅ Covered	cancel()	Yes
confirm()	none	Promise<void>	✅ Covered	submitGift()	YES

J. Entity Selection Methods

Method	Parameters	Return Type	Status	Store Action	Critical
selectGiver()	contact?	void	✅ Covered	setGiver()	YES
selectRecipient()	contact?	void	✅ Covered	setReceiver()	YES
selectProject()	project	void	✅ Covered	selectProject()	YES
selectRecipientProject()	project	void	✅ Covered	selectRecipientProject()	YES

K. Navigation Methods

Method	Parameters	Return Type	Status	Store Action	Critical
goBackToStep1()	step	void	✅ Covered	setEntitySelectionMode() + setCurrentStep()	YES

L. Utility Methods

Method	Parameters	Return Type	Status	Store Action	Critical
wouldCreateConflict()	contactDid	boolean	✅ Covered	wouldCreateConflict()	YES
increment()	none	void	✅ Covered	increment()	Yes
decrement()	none	void	✅ Covered	decrement()	Yes
changeUnitCode()	none	void	✅ Covered	changeUnitCode()	Yes
explainData()	none	void	✅ Covered	Component method	No

M. Business Logic Methods

Method	Parameters	Return Type	Status	Store Action	Critical
recordGive()	giverDid, recipientDid, description, amount, unitCode	Promise<void>	✅ Covered	submitGift()	YES
updateEntityTypes()	none	void	✅ Covered	Reactive logic	YES
loadProjects()	none	Promise<void>	✅ Covered	loadProjects()	YES

N. Data Loading Methods (CRITICAL - Previously Missing)

Method	Parameters	Return Type	Status	Store Action	Critical
loadAccountData()	none	Promise<void>	❌ ADDED	loadAccountData()	YES
loadContacts()	none	Promise<void>	❌ ADDED	loadContacts()	YES

O. Helper Methods

Method	Parameters	Return Type	Status	Implementation	Critical
getGiveCreationErrorMessage()	result	string	✅ Covered	Component method	No
eraseValues()	none	void	✅ Covered	resetForm()	Yes

P. Template Dependencies

Template Reference	Type	Status	Store Implementation	Critical
stepType	string	✅ Covered	entitySelectionMode	YES
shouldShowProjects	computed	✅ Covered	shouldShowProjects getter	YES
hasPersonConflict	computed	✅ Covered	hasPersonConflict getter	YES
giftedDetailsQuery	computed	✅ Covered	giftedDetailsQuery getter	YES

Q. External Dependencies (Must be imported in store)

Dependency	Source	Status	Required For	Critical
createAndSubmitGive	libs/endorserServer	❌ NEEDS IMPORT	Gift submission	YES
didInfo	libs/endorserServer	❌ NEEDS IMPORT	Contact display	YES
getHeaders	libs/endorserServer	❌ NEEDS IMPORT	API calls	YES
retrieveSettingsForActiveAccount	db/index	❌ NEEDS IMPORT	Account data	YES
retrieveAccountDids	libs/util	❌ NEEDS IMPORT	DID management	YES
PlatformServiceFactory	services/PlatformServiceFactory	❌ NEEDS IMPORT	Database access	YES
databaseUtil	db/databaseUtil	❌ NEEDS IMPORT	Data mapping	YES
logger	utils/logger	❌ NEEDS IMPORT	Error logging	YES
UNIT_SHORT	libs/util	❌ NEEDS IMPORT	Unit display	YES
PRIVACY_MESSAGE	libs/util	❌ NEEDS IMPORT	Data explanation	No

R. Type Definitions Required

Type	Source	Status	Required For	Critical
GiverReceiverInputInfo	libs/util	✅ Covered	Entity info	YES
Contact	db/tables/contacts	✅ Covered	Contact data	YES
PlanData	interfaces/records	✅ Covered	Project data	YES
NotificationIface	constants/app	✅ Covered	Notifications	Yes

S. Integration Points (Must be preserved)

Integration	Views Using	Status	Refactoring Impact	Critical
HomeView	Main entry	✅ Planned	Phase 3.1	YES
ProjectViewView	Dual dialogs	✅ Planned	Phase 3.3	YES
ContactsView	Contact gifts	✅ Planned	Phase 3.2	YES
ContactGiftingView	Advanced UI	✅ Planned	Phase 3.4	YES
ClaimView	Offer fulfillment	✅ Planned	Phase 3.4	YES
GiftedDetailsView	Advanced options	✅ Covered	Query params	YES

T. Risk Assessment Summary

Category	Items	Covered	Missing	Risk Level	Pre-Phase Status
Props	4	4	0	✅ LOW	✅ Ready
Core State	10	10	0	✅ LOW	✅ Ready
Context State	4	0	4	🚨 HIGH → ⏳ IN PROGRESS	🔄 Pre-Phase 1.1
API/Account State	3	0	3	🚨 HIGH → ⏳ IN PROGRESS	🔄 Pre-Phase 1.1
Data State	2	2	0	✅ LOW	✅ Ready
Methods	20	18	2	⚠️ MEDIUM → ⏳ IN PROGRESS	🔄 Pre-Phase 1.3
External Deps	11	0	11	🚨 HIGH → ⏳ IN PROGRESS	🔄 Pre-Phase 1.2
Integrations	6	6	0	✅ LOW	✅ Ready

U. Action Items for Refactoring Plan

🔄 PRE-PHASE 1 (IN PROGRESS - 3 days)

• Pre-Phase 1.1: Complete store interface with all missing fields
• Pre-Phase 1.2: Validate all external dependency imports
• Pre-Phase 1.3: Implement critical method stubs
• Pre-Phase 1.4: Run integration tests
• Pre-Phase 1.5: Update documentation and verify readiness

⏸️ CRITICAL (Must Complete Before Phase 1)

• ✅ All context state fields added to store interface
• ✅ All API/account state fields added to store interface
• ✅ All external dependencies imported and tested in store
• ✅ Data loading actions implemented and tested in store
• ✅ Utility reference imports validated

⚠️ HIGH PRIORITY (Phase 1 - Enhanced with Template Foundations)

• Implement complete store with all identified fields
• Create comprehensive test coverage for missing functionality
• Validate callback function handling
• Test offer ID integration
• NEW: Create foundation template components (GiftDialogStepIndicator, EntityGridItem, EntitySummaryCard, ValidationErrorList)
• NEW: Establish component design system and accessibility patterns
• NEW: Implement TypeScript interfaces for component props and events

✅ MEDIUM PRIORITY (Phase 2-3 - Enhanced with Template Integration)

• Implement hybrid component with ALL computed properties
• Migrate views with full integration testing
• Validate query parameter generation
• NEW: Create main template components (GiftDialogEntitySelection, GiftDialogDetailsForm)
• NEW: Integrate step indicators and progress visualization
• NEW: Implement accessibility enhancements (ARIA labels, keyboard navigation)
• NEW: Add loading and error state components

🎨 TEMPLATE ENHANCEMENT PRIORITY (Phase 4-5)

• NEW: Complete template decomposition and component integration
• NEW: Implement visual progress indicators and animations
• NEW: Optimize component performance and bundle size
• NEW: Add comprehensive accessibility testing
• NEW: Create component documentation and examples

REFACTORING READINESS: ⏳ PRE-PHASE 1 IN PROGRESS - Critical fields being addressed ESTIMATED COMPLETION: 21 days total (3 days pre-phase + 18 days enhanced plan with template improvements)

---

PRE-PHASE 1: CRITICAL MISSING FIELDS RESOLUTION

Pre-phase Overview

Before beginning the Pinia store refactoring, all critical missing fields must be addressed to prevent breaking changes. This pre-phase ensures 100% functionality preservation.

Pre-Phase 1.1: Store Interface Completion

Duration: 1 day Files to create/modify:

src/types/giftDialog.ts (complete interface)
src/stores/giftDialog.ts (skeleton with imports)

✅ TASK CHECKLIST:

1. Complete Type Definitions

• Add all missing context state types
• Add all missing API/account state types
• Import all required external types
• Define complete callback function signatures

Enhanced Type Definitions:

// src/types/giftDialog.ts
import { Contact } from '@/db/tables/contacts';
import { PlanData } from '@/interfaces/records';
import { GiverReceiverInputInfo } from '@/libs/util';

export type EntitySelectionMode = "giver" | "recipient";
export type EntityType = "person" | "project";
export type WorkflowStep = "entity-selection" | "gift-details" | "verification" | "confirmation";

export const ENTITY_SELECTION_MODE = {
  GIVER: "giver" as const,
  RECIPIENT: "recipient" as const
} as const;

// COMPLETE interface with ALL fields identified in audit
export interface GiftDialogState {
  // UI State
  isVisible: boolean;
  currentStep: WorkflowStep;
  entitySelectionMode: EntitySelectionMode;
  
  // Entity State
  giverEntityType: EntityType;
  recipientEntityType: EntityType;
  giver?: GiverReceiverInputInfo;
  receiver?: GiverReceiverInputInfo;
  
  // Form State
  description: string;
  amountInput: string;
  unitCode: string;
  
  // Context State (CRITICAL ADDITIONS)
  callbackOnSuccess?: (amount: number) => void;
  customTitle?: string;
  offerId: string;
  prompt: string;
  
  // API and Account State (CRITICAL ADDITIONS)
  apiServer: string;
  activeDid: string;
  allMyDids: string[];
  
  // Data State
  allContacts: Contact[];
  projects: PlanData[];
  
  // Validation State
  validationErrors: string[];
  isSubmitting: boolean;
}

// Callback function type for success handling
export type GiftSuccessCallback = (amount: number) => void;

// Configuration interface for opening dialog
export interface GiftDialogOpenConfig {
  giver?: GiverReceiverInputInfo;
  receiver?: GiverReceiverInputInfo;
  offerId?: string;
  customTitle?: string;
  prompt?: string;
  callbackOnSuccess?: GiftSuccessCallback;
}

// Query parameters interface for GiftedDetailsView
export interface GiftedDetailsQuery {
  amountInput: string;
  description: string;
  giverDid?: string;
  giverName?: string;
  offerId: string;
  fulfillsProjectId?: string;
  providerProjectId?: string;
  recipientDid?: string;
  recipientName?: string;
  unitCode: string;
}

2. Import All External Dependencies

• Create import statements for all 11 external dependencies
• Verify import paths are correct
• Test imports compile without errors

Complete Import List:

// src/stores/giftDialog.ts
import { defineStore } from 'pinia';
import { Contact } from '@/db/tables/contacts';
import { PlanData } from '@/interfaces/records';
import { 
  GiverReceiverInputInfo, 
  retrieveAccountDids,
  UNIT_SHORT,
  PRIVACY_MESSAGE 
} from '@/libs/util';
import { 
  createAndSubmitGive,
  didInfo,
  getHeaders,
  serverMessageForUser 
} from '@/libs/endorserServer';
import { 
  db, 
  retrieveSettingsForActiveAccount 
} from '@/db/index';
import * as databaseUtil from '@/db/databaseUtil';
import { PlatformServiceFactory } from '@/services/PlatformServiceFactory';
import { logger } from '@/utils/logger';
import { 
  GiftDialogState, 
  EntitySelectionMode, 
  EntityType,
  WorkflowStep,
  GiftDialogOpenConfig,
  GiftedDetailsQuery,
  ENTITY_SELECTION_MODE 
} from '@/types/giftDialog';

3. Create Store Skeleton

• Define complete state with default values
• Create placeholder actions for all methods
• Add validation for critical missing functionality

Store Skeleton:

export const useGiftDialogStore = defineStore('giftDialog', {
  state: (): GiftDialogState => ({
    // UI State
    isVisible: false,
    currentStep: 'entity-selection',
    entitySelectionMode: ENTITY_SELECTION_MODE.GIVER,
    
    // Entity State
    giverEntityType: 'person',
    recipientEntityType: 'person',
    giver: undefined,
    receiver: undefined,
    
    // Form State
    description: '',
    amountInput: '0',
    unitCode: 'HUR',
    
    // Context State (CRITICAL ADDITIONS)
    callbackOnSuccess: undefined,
    customTitle: undefined,
    offerId: '',
    prompt: '',
    
    // API and Account State (CRITICAL ADDITIONS)
    apiServer: '',
    activeDid: '',
    allMyDids: [],
    
    // Data State
    allContacts: [],
    projects: [],
    
    // Validation State
    validationErrors: [],
    isSubmitting: false
  }),

  getters: {
    // All getters will be implemented in Phase 1.2
  },

  actions: {
    // All actions will be implemented in Phase 1.2
  }
});

Pre-Phase 1.2: Dependency Validation

Duration: 0.5 days Objective: Ensure all external dependencies are available and working

✅ TASK CHECKLIST:

1. Validate Import Paths

• Test each import statement individually
• Verify all functions/classes are exported correctly
• Check for any missing dependencies in package.json

2. Create Import Test File

// test-imports.ts (temporary file for validation)
import { createAndSubmitGive, didInfo, getHeaders } from '@/libs/endorserServer';
import { retrieveSettingsForActiveAccount } from '@/db/index';
import { retrieveAccountDids, UNIT_SHORT } from '@/libs/util';
import { PlatformServiceFactory } from '@/services/PlatformServiceFactory';
import * as databaseUtil from '@/db/databaseUtil';
import { logger } from '@/utils/logger';

// Test that all imports are available
console.log('Testing imports...');
console.log('createAndSubmitGive:', typeof createAndSubmitGive);
console.log('didInfo:', typeof didInfo);
console.log('getHeaders:', typeof getHeaders);
console.log('retrieveSettingsForActiveAccount:', typeof retrieveSettingsForActiveAccount);
console.log('retrieveAccountDids:', typeof retrieveAccountDids);
console.log('UNIT_SHORT:', typeof UNIT_SHORT);
console.log('PlatformServiceFactory:', typeof PlatformServiceFactory);
console.log('databaseUtil:', typeof databaseUtil);
console.log('logger:', typeof logger);
console.log('All imports successful!');

3. Function Signature Validation

• Verify createAndSubmitGive signature matches usage in component
• Check didInfo function parameters
• Validate retrieveAccountDids return type
• Confirm PlatformServiceFactory.getInstance() method exists

Pre-Phase 1.3: Critical Method Stubs

Duration: 0.5 days Objective: Create working stubs for all critical methods

✅ TASK CHECKLIST:

1. Data Loading Method Stubs

// Add to store actions
async loadAccountData(): Promise<void> {
  try {
    const settings = await retrieveSettingsForActiveAccount();
    this.apiServer = settings.apiServer || "";
    this.activeDid = settings.activeDid || "";
    this.allMyDids = await retrieveAccountDids();
    logger.info('Account data loaded successfully');
  } catch (error) {
    logger.error("Error loading account data:", error);
    this.validationErrors.push("Failed to load account data");
    throw error;
  }
},

async loadContacts(): Promise<void> {
  try {
    const platformService = PlatformServiceFactory.getInstance();
    const result = await platformService.dbQuery(`SELECT * FROM contacts`);
    if (result) {
      this.allContacts = databaseUtil.mapQueryResultToValues(result) as Contact[];
    }
    logger.info(`Loaded ${this.allContacts.length} contacts`);
  } catch (error) {
    logger.error("Error loading contacts:", error);
    this.validationErrors.push("Failed to load contacts");
    throw error;
  }
},

async loadProjects(): Promise<void> {
  try {
    if (!this.apiServer || !this.activeDid) {
      throw new Error('API server or active DID not available');
    }
    
    const response = await fetch(this.apiServer + "/api/v2/report/plans", {
      method: "GET",
      headers: await getHeaders(this.activeDid),
    });

    if (response.status !== 200) {
      throw new Error(`Failed to load projects: ${response.status}`);
    }

    const results = await response.json();
    if (results.data) {
      this.projects = results.data;
      logger.info(`Loaded ${this.projects.length} projects`);
    }
  } catch (error) {
    logger.error("Error loading projects:", error);
    this.validationErrors.push("Failed to load projects");
    throw error;
  }
}

2. Context Management Method Stubs

// Add to store actions
setCallbackOnSuccess(callback?: (amount: number) => void): void {
  this.callbackOnSuccess = callback;
  logger.debug('Callback on success set:', !!callback);
},

setCustomTitle(title?: string): void {
  this.customTitle = title;
  logger.debug('Custom title set:', title);
},

setOfferId(offerId: string): void {
  this.offerId = offerId || '';
  logger.debug('Offer ID set:', offerId);
},

setPrompt(prompt: string): void {
  this.prompt = prompt || '';
  logger.debug('Prompt set:', prompt);
}

3. Validation Method Stubs

// Add to store actions
validateCurrentStep(): boolean {
  this.validationErrors = [];
  
  switch (this.currentStep) {
    case 'entity-selection':
      if (!this.giver) this.validationErrors.push('Please select a giver');
      if (!this.receiver) this.validationErrors.push('Please select a receiver');
      if (this.hasPersonConflict) {
        this.validationErrors.push('Cannot select the same person as both giver and recipient');
      }
      break;
      
    case 'gift-details':
      if (!this.description && !parseFloat(this.amountInput)) {
        this.validationErrors.push('Please provide description or amount');
      }
      if (parseFloat(this.amountInput) < 0) {
        this.validationErrors.push('Amount cannot be negative');
      }
      if (!this.activeDid) {
        this.validationErrors.push('Active DID required for gift submission');
      }
      break;
  }
  
  const isValid = this.validationErrors.length === 0;
  logger.debug('Validation result:', { isValid, errors: this.validationErrors });
  return isValid;
}

Pre-Phase 1.4: Integration Testing

Duration: 1 day Objective: Test all critical missing functionality before full implementation

✅ TASK CHECKLIST:

1. Create Test Harness

// test-store-functionality.ts (temporary test file)
import { useGiftDialogStore } from '@/stores/giftDialog';

async function testCriticalFunctionality() {
  const store = useGiftDialogStore();
  
  console.log('Testing store initialization...');
  console.log('Initial state:', store.$state);
  
  console.log('Testing data loading...');
  try {
    await store.loadAccountData();
    console.log('✅ Account data loaded');
    
    await store.loadContacts();
    console.log('✅ Contacts loaded');
    
    if (store.allContacts.length > 0) {
      console.log('✅ Contacts available:', store.allContacts.length);
    }
    
    await store.loadProjects();
    console.log('✅ Projects loaded');
    
  } catch (error) {
    console.error('❌ Data loading failed:', error);
  }
  
  console.log('Testing context management...');
  store.setCustomTitle('Test Title');
  store.setPrompt('Test Prompt');
  store.setOfferId('test-offer-123');
  store.setCallbackOnSuccess((amount) => console.log('Success:', amount));
  
  console.log('✅ Context management working');
  
  console.log('Testing validation...');
  const isValid = store.validateCurrentStep();
  console.log('Validation result:', isValid);
  
  console.log('All critical functionality tests completed!');
}

// Run tests
testCriticalFunctionality().catch(console.error);

2. Manual Integration Tests

• Test store can be imported in Vue component
• Verify all data loading methods work with real data
• Test context management preserves values
• Validate error handling works correctly
• Confirm logging output is helpful for debugging

3. Performance Validation

• Measure store initialization time
• Test data loading performance with large contact lists
• Verify no memory leaks in reactive state
• Check bundle size impact

Pre-Phase 1.5: Documentation and Checklist Updates

Duration: 0.5 days Objective: Update documentation with completed critical fields

✅ TASK CHECKLIST:

1. Update Inventory Status

• Mark all critical fields as "✅ Implemented" in annex
• Update risk assessment to show reduced risk levels
• Verify readiness status can be changed to "READY"

2. Create Implementation Checklist

• Document exact steps taken for each critical field
• Create troubleshooting guide for common issues
• Add performance benchmarks and expectations

3. Phase 1 Readiness Validation

• All external dependencies imported and tested
• All critical state fields implemented
• All critical methods have working stubs
• Store can be instantiated without errors
• Integration tests pass

Updated Timeline and Complexity Analysis

Complexity Measurement Framework

Understanding complexity is crucial for accurate estimation. We measure complexity across multiple dimensions:

1. Technical Complexity Factors

• State Dependencies: Number of interconnected state variables (GiftedDialog has 25+ state fields)
• Integration Points: Number of views using the component (8+ integration points identified)
• Backward Compatibility: Requirement to maintain exact existing behavior during transition
• Cross-Platform Requirements: Web, mobile (Capacitor), and desktop (Electron) support
• Type Safety: Comprehensive TypeScript integration across component hierarchy

2. Complexity Scoring System

interface ComplexityMetrics {
  technical: 1-5;     // Code complexity, architecture changes
  integration: 1-5;   // Number of integration points and dependencies  
  testing: 1-5;       // Test coverage requirements and validation
  accessibility: 1-5; // WCAG compliance and inclusive design
  performance: 1-5;   // Bundle size, rendering optimization
}

// GiftedDialog Refactoring Complexity Score
const complexityScore = {
  technical: 4,      // High - 400+ line component, store migration
  integration: 5,    // Very High - 8+ views, complex prop patterns
  testing: 4,        // High - Playwright tests, accessibility testing
  accessibility: 4,  // High - WCAG compliance, keyboard navigation
  performance: 3     // Medium - Bundle optimization, reactive updates
};
// Overall Complexity: 4.0/5 (High)

3. Complexity Indicators by Phase

• Pre-Phase 1: Low complexity (import validation, interface completion)
• Phase 1: Medium-High (store creation + 4 foundation components)
• Phase 2: High (backward compatibility + template decomposition)
• Phase 3: Medium (incremental migration, known patterns)
• Phase 4: High (accessibility compliance, performance optimization)
• Phase 5: Medium (store enhancements, well-defined scope)
• Phase 6: Medium-High (comprehensive testing, documentation)

4. Risk-Adjusted Estimation Model

interface EstimationFactors {
  baseEffort: number;           // Initial estimate
  complexityMultiplier: number; // 1.0-2.0 based on complexity score
  riskBuffer: number;           // 10-40% contingency
  integrationOverhead: number;  // Additional time for coordination
}

const estimationModel = {
  baseEffort: 20,              // 20 days for core functionality
  complexityMultiplier: 1.4,   // 40% increase for high complexity
  riskBuffer: 0.25,            // 25% contingency buffer
  integrationOverhead: 3       // 3 days for integration complexity
};

// Calculation: (20 × 1.4 + 3) × 1.25 = 35 days realistic estimate

Timeline Comparison and Analysis

Original Estimates vs. Complexity-Adjusted

Phase	Original	Complexity Analysis	Revised	Confidence	Risk Factors
Pre-Phase 1	3 days	Low complexity, well-scoped	3 days	High ✅	Import path changes
Phase 1	3 days	Med-High: Store + 4 components	4-5 days	Medium ⚠️	Component design complexity
Phase 2	4 days	High: Backward compatibility	5-6 days	Medium ⚠️	Integration edge cases
Phase 3	5 days	Medium: Known migration patterns	5-6 days	Medium ✅	View-specific quirks
Phase 4	4 days	High: Accessibility + performance	5-6 days	Medium ⚠️	WCAG compliance depth
Phase 5	3 days	Medium: Well-defined enhancements	3 days	High ✅	Store pattern maturity
Phase 6	3 days	Med-High: Comprehensive testing	4 days	Medium ⚠️	Test coverage breadth

Timeline Options

Option A: Aggressive Timeline (Original)

• Duration: 25 days (5 weeks)
• Risk: High - 15-20% probability of overrun
• Conditions: Dedicated developer, minimal scope creep
• Trade-offs: May require reducing accessibility features or advanced optimizations

Option B: Realistic Timeline (Complexity-Adjusted)

• Duration: 30-33 days (6-7 weeks)
• Risk: Medium - 70-80% probability of completion within timeline
• Buffer: 20-30% contingency for complexity factors
• Recommended: ✅ This is the recommended approach

Option C: Conservative Timeline (High-Confidence)

• Duration: 35-40 days (7-8 weeks)
• Risk: Low - 90%+ probability of completion
• Buffer: 40-60% contingency for unknown complexity
• Use Case: When delivery certainty is critical

Detailed Phase Analysis

Phase	Duration	Status	Dependencies	Focus	Complexity Score
Pre-Phase 1	3 days	⏳ In Progress	None	Critical missing fields	2/5 (Low)
Phase 1	4-5 days	⏸️ Waiting	Pre-Phase 1 complete	Store + Foundation Components	4/5 (High)
Phase 2	5-6 days	⏸️ Waiting	Phase 1 complete	Hybrid Component + Main Templates	5/5 (Very High)
Phase 3	5-6 days	⏸️ Waiting	Phase 2 complete	View Migration	3/5 (Medium)
Phase 4	5-6 days	⏸️ Waiting	Phase 3 complete	Template Enhancement	4/5 (High)
Phase 5	3 days	⏸️ Waiting	Phase 4 complete	Store Enhancement	3/5 (Medium)
Phase 6	4 days	⏸️ Waiting	Phase 5 complete	Cleanup & Testing	4/5 (High)
Realistic Total	30-33 days				3.7/5 (High)
Conservative Total	35-40 days				With full buffer

Complexity Justification by Phase

Phase 2 (Highest Complexity - 5/5):

• Maintaining backward compatibility across 8+ integration points
• Dual-mode implementation (legacy + store) with identical behavior
• Template decomposition of 400+ line component
• Event handling synchronization between parent/child components

Phase 4 (High Complexity - 4/5):

• WCAG accessibility compliance requires extensive testing
• Performance optimization across multiple platforms
• Animation and transition implementation
• Focus management and keyboard navigation

Phase 1 & 6 (High Complexity - 4/5):

• Foundation component design affects entire architecture
• Comprehensive testing and documentation requirements
• TypeScript interface design for extensibility

Risk Mitigation

Pre-Phase 1 Risks:

1. Import Path Issues: Some dependencies might have changed locations

   • Mitigation: Test each import individually, update paths as needed

2. Function Signature Changes: External functions might have different signatures

   • Mitigation: Validate signatures against actual usage in component

3. Database Schema Changes: Contact/project data structures might have evolved

   • Mitigation: Test with real data, validate type compatibility

4. Performance Impact: Adding all fields might impact store performance

   • Mitigation: Benchmark before/after, optimize if necessary

Success Criteria for Pre-Phase 1

Must Complete Before Phase 1:

• ✅ All 11 external dependencies successfully imported
• ✅ All 7 critical missing fields added to store interface
• ✅ All data loading methods working with real data
• ✅ Context management methods preserve values correctly
• ✅ Store can be instantiated and used in Vue component
• ✅ Integration tests pass with 100% success rate
• ✅ Performance benchmarks within acceptable ranges
• ✅ Documentation updated to reflect completed work

Readiness Check:

// readiness-check.ts
import { useGiftDialogStore } from '@/stores/giftDialog';

async function verifyReadiness(): Promise<boolean> {
  try {
    const store = useGiftDialogStore();
    
    // Test critical functionality
    await store.loadAccountData();
    await store.loadContacts();
    
    store.setCustomTitle('Readiness Test');
    store.setPrompt('Testing prompt');
    store.setOfferId('test-123');
    
    const hasAccountData = !!store.activeDid && !!store.apiServer;
    const hasContacts = store.allContacts.length >= 0; // Allow empty but defined
    const hasContextFields = store.customTitle === 'Readiness Test';
    
    console.log('Readiness Check Results:');
    console.log('✅ Account data loaded:', hasAccountData);
    console.log('✅ Contacts loaded:', hasContacts);
    console.log('✅ Context management:', hasContextFields);
    
    return hasAccountData && hasContacts && hasContextFields;
    
  } catch (error) {
    console.error('❌ Readiness check failed:', error);
    return false;
  }
}

// Usage: await verifyReadiness() should return true before Phase 1

PHASE 1 CAN BEGIN WHEN: All success criteria are met and readiness check returns true.

GiftedDialog Pinia Store Refactoring Plan

Refactoring Overview

This plan outlines a systematic approach to refactor the GiftedDialog component to use Pinia store for state management while maintaining backward compatibility and minimizing disruption. This refactoring also includes improvements to variable naming, type safety, and code clarity.

CRITICAL UPDATE: After comprehensive audit of GiftedDialog.vue, additional fields and functionality have been identified that must be included in the refactoring plan to prevent breaking changes.

Phase 1: Foundation Setup (Enhanced with Template Foundations)

1.1 Create Store Infrastructure + Foundation Components

Files to create:

src/stores/giftDialog.ts
src/types/giftDialog.ts (type definitions)
src/components/GiftDialog/GiftDialogStepIndicator.vue
src/components/GiftDialog/EntityGridItem.vue
src/components/GiftDialog/EntitySummaryCard.vue
src/components/GiftDialog/ValidationErrorList.vue
src/components/GiftDialog/index.ts (component exports)

Tasks:

• Define complete GiftDialogState interface with all existing fields
• Create basic Pinia store with initial state
• Add core getters (isValid, hasPersonConflict, formattedAmount, shouldShowProjects)
• Implement basic actions (openDialog, closeDialog, setGiver, setReceiver)
• Add context management actions (setCallbackOnSuccess, setCustomTitle, setOfferId, setPrompt)
• Add API and account management actions
• Add simple validation methods
• NEW: Define improved type definitions for entity selection
• NEW: Create GiftDialogStepIndicator component with progress visualization
• NEW: Create EntityGridItem component for standardized entity display
• NEW: Create EntitySummaryCard component for gift details step
• NEW: Create ValidationErrorList component for error feedback
• NEW: Establish component design system and accessibility patterns
• NEW: Implement TypeScript interfaces for all component props and events

Complete Type Definitions:

// src/types/giftDialog.ts
export type EntitySelectionMode = "giver" | "recipient";
export type EntityType = "person" | "project";
export type WorkflowStep = "entity-selection" | "gift-details" | "verification" | "confirmation";

export const ENTITY_SELECTION_MODE = {
  GIVER: "giver" as const,
  RECIPIENT: "recipient" as const
} as const;

export interface GiftDialogState {
  // UI State
  isVisible: boolean;
  currentStep: WorkflowStep;
  entitySelectionMode: EntitySelectionMode;  // Renamed from stepType
  
  // Entity State
  giverEntityType: EntityType;
  recipientEntityType: EntityType;
  giver?: GiverReceiverInputInfo;
  receiver?: GiverReceiverInputInfo;
  
  // Form State
  description: string;
  amountInput: string;
  unitCode: string;
  
  // Context State (CRITICAL: Missing from original plan)
  callbackOnSuccess?: (amount: number) => void;
  customTitle?: string;
  offerId: string;
  prompt: string;
  
  // API and Account State (CRITICAL: Missing from original plan)
  apiServer: string;
  activeDid: string;
  allMyDids: string[];
  
  // Data State
  allContacts: Contact[];
  projects: PlanData[];
  
  // Validation State
  validationErrors: string[];
  isSubmitting: boolean;
}

Deliverable: Working store that can be imported and tested with improved type safety

1.2 Enhanced Store Implementation

Files to create/modify:

src/stores/giftDialog.ts

Complete Store Actions (CRITICAL ADDITIONS):

export const useGiftDialogStore = defineStore('giftDialog', {
  state: (): GiftDialogState => ({
    // ... state definition with all fields ...
  }),

  getters: {
    isValid: (state) => {
      return state.giver && state.receiver && 
             (state.description || parseFloat(state.amountInput) > 0);
    },
    
    hasPersonConflict: (state) => {
      return state.giver?.did === state.receiver?.did && 
             state.giver?.did !== undefined &&
             state.giverEntityType === 'person' &&
             state.recipientEntityType === 'person';
    },
    
    shouldShowProjects: (state) => {
      return (state.entitySelectionMode === ENTITY_SELECTION_MODE.GIVER && state.giverEntityType === 'project') ||
             (state.entitySelectionMode === ENTITY_SELECTION_MODE.RECIPIENT && state.recipientEntityType === 'project');
    },
    
    formattedAmount: (state) => {
      const amount = parseFloat(state.amountInput) || 0;
      const unit = UNIT_REGISTRY.find(u => u.code === state.unitCode);
      return unit ? `${unit.symbol}${amount.toFixed(unit.decimals)}` : amount.toString();
    },

    giftedDetailsQuery: (state) => {
      return {
        amountInput: state.amountInput,
        description: state.description,
        giverDid: state.giverEntityType === "person" ? state.giver?.did : undefined,
        giverName: state.giver?.name,
        offerId: state.offerId,
        fulfillsProjectId: state.giverEntityType === "person" && state.recipientEntityType === "project"
          ? state.receiver?.handleId : undefined,
        providerProjectId: state.giverEntityType === "project" && state.recipientEntityType === "person"
          ? state.giver?.handleId : undefined,
        recipientDid: state.receiver?.did,
        recipientName: state.receiver?.name,
        unitCode: state.unitCode,
      };
    }
  },

  actions: {
    // Context Management Actions (CRITICAL ADDITIONS)
    setCallbackOnSuccess(callback: (amount: number) => void) {
      this.callbackOnSuccess = callback;
    },
    
    setCustomTitle(title: string) {
      this.customTitle = title;
    },
    
    setOfferId(offerId: string) {
      this.offerId = offerId;
    },
    
    setPrompt(prompt: string) {
      this.prompt = prompt;
    },
    
    // API and Account Actions (CRITICAL ADDITIONS)
    setApiServer(apiServer: string) {
      this.apiServer = apiServer;
    },
    
    setActiveDid(activeDid: string) {
      this.activeDid = activeDid;
    },
    
    setAllMyDids(dids: string[]) {
      this.allMyDids = dids;
    },
    
    setAllContacts(contacts: Contact[]) {
      this.allContacts = contacts;
    },
    
    setProjects(projects: PlanData[]) {
      this.projects = projects;
    },

    // Enhanced Dialog Management
    async openDialog(config: {
      giver?: GiverReceiverInputInfo;
      receiver?: GiverReceiverInputInfo;
      offerId?: string;
      customTitle?: string;
      prompt?: string;
      callbackOnSuccess?: (amount: number) => void;
    }) {
      this.isVisible = true;
      this.giver = config.giver;
      this.receiver = config.receiver;
      this.offerId = config.offerId || '';
      this.customTitle = config.customTitle;
      this.prompt = config.prompt || '';
      this.callbackOnSuccess = config.callbackOnSuccess;
      this.currentStep = config.giver ? 'gift-details' : 'entity-selection';
      this.entitySelectionMode = ENTITY_SELECTION_MODE.GIVER;
      this.resetValidation();
      
      // Load necessary data
      await this.loadAccountData();
      await this.loadContacts();
      if (this.giverEntityType === 'project' || this.recipientEntityType === 'project') {
        await this.loadProjects();
      }
    },

    // Data Loading Actions (CRITICAL ADDITIONS)
    async loadAccountData() {
      try {
        const settings = await retrieveSettingsForActiveAccount();
        this.apiServer = settings.apiServer || "";
        this.activeDid = settings.activeDid || "";
        this.allMyDids = await retrieveAccountDids();
      } catch (error) {
        logger.error("Error loading account data:", error);
        this.validationErrors.push("Failed to load account data");
      }
    },
    
    async loadContacts() {
      try {
        const platformService = PlatformServiceFactory.getInstance();
        const result = await platformService.dbQuery(`SELECT * FROM contacts`);
        if (result) {
          this.allContacts = databaseUtil.mapQueryResultToValues(result) as Contact[];
        }
      } catch (error) {
        logger.error("Error loading contacts:", error);
        this.validationErrors.push("Failed to load contacts");
      }
    },
    
    async loadProjects() {
      try {
        const response = await fetch(this.apiServer + "/api/v2/report/plans", {
          method: "GET",
          headers: await getHeaders(this.activeDid),
        });

        if (response.status !== 200) {
          throw new Error("Failed to load projects");
        }

        const results = await response.json();
        if (results.data) {
          this.projects = results.data;
        }
      } catch (error) {
        logger.error("Error loading projects:", error);
        this.validationErrors.push("Failed to load projects");
      }
    },

    // Utility Actions
    wouldCreateConflict(contactDid: string): boolean {
      if (this.giverEntityType !== "person" || this.recipientEntityType !== "person") {
        return false;
      }
      
      if (this.entitySelectionMode === ENTITY_SELECTION_MODE.GIVER) {
        return this.receiver?.did === contactDid;
      } else if (this.entitySelectionMode === ENTITY_SELECTION_MODE.RECIPIENT) {
        return this.giver?.did === contactDid;
      }
      
      return false;
    },

    increment() {
      this.amountInput = `${(parseFloat(this.amountInput) || 0) + 1}`;
    },

    decrement() {
      this.amountInput = `${Math.max(0, (parseFloat(this.amountInput) || 1) - 1)}`;
    },

    changeUnitCode() {
      const units = Object.keys(UNIT_SHORT);
      const index = units.indexOf(this.unitCode);
      this.unitCode = units[(index + 1) % units.length];
    }
  }
});

1.3 Store Integration Setup

Files to modify:

src/main.common.ts
package.json (if Pinia not already installed)

Tasks:

• Verify Pinia is installed and configured
• Add store to main app setup if needed
• Create simple test to verify store works
• NEW: Set up TypeScript strict mode if not already enabled
• CRITICAL: Import all necessary dependencies in store

Success Criteria: Store can be imported and used in any component with full type safety and all existing functionality

Phase 2: Component Hybrid Implementation (Enhanced with Main Template Components)

2.1 Create Backward-Compatible GiftedDialog + Main Template Components

Files to modify/create:

src/components/GiftedDialog.vue
src/components/GiftDialog/GiftDialogEntitySelection.vue
src/components/GiftDialog/GiftDialogDetailsForm.vue
src/components/GiftDialog/GiftDialogLoadingState.vue
src/components/GiftDialog/GiftDialogErrorState.vue

Strategy: Dual-mode implementation that can work with both old and new patterns while preserving ALL existing functionality, enhanced with component composition

Tasks:

• Add store import and initialization
• Create computed properties that proxy between component state and store state for ALL fields
• Add a useStore prop to enable/disable store mode
• Implement store delegation methods alongside existing methods
• Maintain all existing public methods for backward compatibility
• CRITICAL: Add computed properties for all missing fields identified in audit
• NEW: Rename stepType to entitySelectionMode in legacy mode
• NEW: Improve method naming consistency
• NEW: Add type safety enhancements
• NEW: Create GiftDialogEntitySelection component for entity selection logic
• NEW: Create GiftDialogDetailsForm component for gift details step
• NEW: Create loading and error state components
• NEW: Integrate step indicators and progress visualization
• NEW: Implement accessibility enhancements (ARIA labels, keyboard navigation)

Complete Implementation with ALL Fields:

export default class GiftedDialog extends Vue {
  @Prop({ default: false }) useStore = false;
  
  private giftDialogStore = useGiftDialogStore();
  
  // Legacy state (when useStore = false) - ALL FIELDS
  private _visible = false;
  private _currentStep = 1;
  private _entitySelectionMode: EntitySelectionMode = ENTITY_SELECTION_MODE.GIVER;
  private _giverEntityType: EntityType = "person";
  private _recipientEntityType: EntityType = "person";
  private _giver?: GiverReceiverInputInfo;
  private _receiver?: GiverReceiverInputInfo;
  private _description = "";
  private _amountInput = "0";
  private _unitCode = "HUR";
  
  // CRITICAL: Context state fields
  private _callbackOnSuccess?: (amount: number) => void;
  private _customTitle?: string;
  private _offerId = "";
  private _prompt = "";
  
  // CRITICAL: API and account state fields  
  private _apiServer = "";
  private _activeDid = "";
  private _allMyDids: string[] = [];
  private _allContacts: Contact[] = [];
  private _projects: PlanData[] = [];
  
  // Computed properties that choose source - ALL FIELDS
  get visible() {
    return this.useStore ? this.giftDialogStore.isVisible : this._visible;
  }
  
  get currentStep() {
    return this.useStore ? this.giftDialogStore.currentStep : this._currentStep;
  }
  
  get entitySelectionMode() {
    return this.useStore ? this.giftDialogStore.entitySelectionMode : this._entitySelectionMode;
  }
  
  get giverEntityType() {
    return this.useStore ? this.giftDialogStore.giverEntityType : this._giverEntityType;
  }
  
  get recipientEntityType() {
    return this.useStore ? this.giftDialogStore.recipientEntityType : this._recipientEntityType;
  }
  
  get giver() {
    return this.useStore ? this.giftDialogStore.giver : this._giver;
  }
  
  get receiver() {
    return this.useStore ? this.giftDialogStore.receiver : this._receiver;
  }
  
  get description() {
    return this.useStore ? this.giftDialogStore.description : this._description;
  }
  
  get amountInput() {
    return this.useStore ? this.giftDialogStore.amountInput : this._amountInput;
  }
  
  get unitCode() {
    return this.useStore ? this.giftDialogStore.unitCode : this._unitCode;
  }
  
  // CRITICAL: Context computed properties
  get callbackOnSuccess() {
    return this.useStore ? this.giftDialogStore.callbackOnSuccess : this._callbackOnSuccess;
  }
  
  get customTitle() {
    return this.useStore ? this.giftDialogStore.customTitle : this._customTitle;
  }
  
  get offerId() {
    return this.useStore ? this.giftDialogStore.offerId : this._offerId;
  }
  
  get prompt() {
    return this.useStore ? this.giftDialogStore.prompt : this._prompt;
  }
  
  // CRITICAL: API and account computed properties
  get apiServer() {
    return this.useStore ? this.giftDialogStore.apiServer : this._apiServer;
  }
  
  get activeDid() {
    return this.useStore ? this.giftDialogStore.activeDid : this._activeDid;
  }
  
  get allMyDids() {
    return this.useStore ? this.giftDialogStore.allMyDids : this._allMyDids;
  }
  
  get allContacts() {
    return this.useStore ? this.giftDialogStore.allContacts : this._allContacts;
  }
  
  get projects() {
    return this.useStore ? this.giftDialogStore.projects : this._projects;
  }
  
  // Computed properties for derived state
  get shouldShowProjects() {
    return this.useStore ? this.giftDialogStore.shouldShowProjects : 
      ((this.entitySelectionMode === ENTITY_SELECTION_MODE.GIVER && this.giverEntityType === "project") ||
       (this.entitySelectionMode === ENTITY_SELECTION_MODE.RECIPIENT && this.recipientEntityType === "project"));
  }
  
  get hasPersonConflict() {
    return this.useStore ? this.giftDialogStore.hasPersonConflict :
      (this.giver?.did === this.receiver?.did && 
       this.giver?.did !== undefined &&
       this.giverEntityType === 'person' &&
       this.recipientEntityType === 'person');
  }
  
  get giftedDetailsQuery() {
    return this.useStore ? this.giftDialogStore.giftedDetailsQuery : {
      amountInput: this.amountInput,
      description: this.description,
      giverDid: this.giverEntityType === "person" ? this.giver?.did : undefined,
      giverName: this.giver?.name,
      offerId: this.offerId,
      fulfillsProjectId: this.giverEntityType === "person" && this.recipientEntityType === "project"
        ? this.receiver?.handleId : undefined,
      providerProjectId: this.giverEntityType === "project" && this.recipientEntityType === "person"
        ? this.giver?.handleId : undefined,
      recipientDid: this.receiver?.did,
      recipientName: this.receiver?.name,
      unitCode: this.unitCode,
    };
  }
  
  // Enhanced open method to handle ALL parameters
  async open(
    giver?: libsUtil.GiverReceiverInputInfo,
    receiver?: libsUtil.GiverReceiverInputInfo,
    offerId?: string,
    customTitle?: string,
    prompt?: string,
    callbackOnSuccess: (amount: number) => void = () => {},
  ) {
    if (this.useStore) {
      await this.giftDialogStore.openDialog({
        giver,
        receiver,
        offerId,
        customTitle,
        prompt,
        callbackOnSuccess
      });
    } else {
      // Legacy implementation with ALL fields
      this._customTitle = customTitle;
      this._giver = giver;
      this._prompt = prompt || "";
      this._receiver = receiver;
      this._amountInput = "0";
      this._callbackOnSuccess = callbackOnSuccess;
      this._offerId = offerId || "";
      this._currentStep = giver ? 2 : 1;
      this._entitySelectionMode = ENTITY_SELECTION_MODE.GIVER;
      
      // Load data in legacy mode
      await this.loadLegacyData();
      this._visible = true;
    }
  }
  
  // Legacy data loading method
  private async loadLegacyData() {
    try {
      let settings = await databaseUtil.retrieveSettingsForActiveAccount();
      this._apiServer = settings.apiServer || "";
      this._activeDid = settings.activeDid || "";
      
      const platformService = PlatformServiceFactory.getInstance();
      const result = await platformService.dbQuery(`SELECT * FROM contacts`);
      if (result) {
        this._allContacts = databaseUtil.mapQueryResultToValues(result) as Contact[];
      }
      
      this._allMyDids = await retrieveAccountDids();
      
      if (this.giverEntityType === "project" || this.recipientEntityType === "project") {
        await this.loadLegacyProjects();
      }
    } catch (err: any) {
      logger.error("Error retrieving settings from database:", err);
    }
  }
  
  private async loadLegacyProjects() {
    try {
      const response = await fetch(this.apiServer + "/api/v2/report/plans", {
        method: "GET",
        headers: await getHeaders(this.activeDid),
      });
      
      if (response.status === 200) {
        const results = await response.json();
        if (results.data) {
          this._projects = results.data;
        }
      }
    } catch (error) {
      logger.error("Error loading projects:", error);
    }
  }
  
  // Legacy method support for backward compatibility (KEEP ALL EXISTING METHODS)
  goBackToStep1(step: string) {
    if (this.useStore) {
      this.giftDialogStore.setEntitySelectionMode(step as EntitySelectionMode);
      this.giftDialogStore.setCurrentStep('entity-selection');
    } else {
      this._entitySelectionMode = step as EntitySelectionMode;
      this._currentStep = 1;
    }
  }
  
  selectGiver(contact?: Contact) {
    const giverInfo: GiverReceiverInputInfo = contact ? {
      did: contact.did,
      name: contact.name || contact.did,
    } : {
      did: "",
      name: "Unnamed",
    };
    
    if (this.useStore) {
      this.giftDialogStore.setGiver(giverInfo);
      this.giftDialogStore.setCurrentStep('gift-details');
    } else {
      this._giver = giverInfo;
      this._currentStep = 2;
    }
  }
  
  selectRecipient(contact?: Contact) {
    const recipientInfo: GiverReceiverInputInfo = contact ? {
      did: contact.did,
      name: contact.name || contact.did,
    } : {
      did: "",
      name: "Unnamed",
    };
    
    if (this.useStore) {
      this.giftDialogStore.setReceiver(recipientInfo);
      this.giftDialogStore.setCurrentStep('gift-details');
    } else {
      this._receiver = recipientInfo;
      this._currentStep = 2;
    }
  }
  
  selectProject(project: PlanData) {
    const giverInfo = {
      did: project.handleId,
      name: project.name,
      image: project.image,
      handleId: project.handleId,
    };
    const receiverInfo = {
      did: this.activeDid,
      name: "You",
    };
    
    if (this.useStore) {
      this.giftDialogStore.setGiver(giverInfo);
      this.giftDialogStore.setReceiver(receiverInfo);
      this.giftDialogStore.setCurrentStep('gift-details');
    } else {
      this._giver = giverInfo;
      this._receiver = receiverInfo;
      this._currentStep = 2;
    }
  }
  
  selectRecipientProject(project: PlanData) {
    const recipientInfo = {
      did: project.handleId,
      name: project.name,
      image: project.image,
      handleId: project.handleId,
    };
    
    if (this.useStore) {
      this.giftDialogStore.setReceiver(recipientInfo);
      this.giftDialogStore.setCurrentStep('gift-details');
    } else {
      this._receiver = recipientInfo;
      this._currentStep = 2;
    }
  }
  
  wouldCreateConflict(contactDid: string): boolean {
    if (this.useStore) {
      return this.giftDialogStore.wouldCreateConflict(contactDid);
    } else {
      if (this.giverEntityType !== "person" || this.recipientEntityType !== "person") {
        return false;
      }
      
      if (this.entitySelectionMode === ENTITY_SELECTION_MODE.GIVER) {
        return this.receiver?.did === contactDid;
      } else if (this.entitySelectionMode === ENTITY_SELECTION_MODE.RECIPIENT) {
        return this.giver?.did === contactDid;
      }
      
      return false;
    }
  }
  
  increment() {
    if (this.useStore) {
      this.giftDialogStore.increment();
    } else {
      this._amountInput = `${(parseFloat(this._amountInput) || 0) + 1}`;
    }
  }
  
  decrement() {
    if (this.useStore) {
      this.giftDialogStore.decrement();
    } else {
      this._amountInput = `${Math.max(0, (parseFloat(this._amountInput) || 1) - 1)}`;
    }
  }
  
  changeUnitCode() {
    if (this.useStore) {
      this.giftDialogStore.changeUnitCode();
    } else {
      const units = Object.keys(this.libsUtil.UNIT_SHORT);
      const index = units.indexOf(this._unitCode);
      this._unitCode = units[(index + 1) % units.length];
    }
  }
  
  // ALL OTHER EXISTING METHODS PRESERVED...
}

Success Criteria: Component works exactly the same as before when useStore=false with ALL functionality preserved

2.2 Create Test View for Store Mode

Files to create:

src/views/TestGiftDialogStore.vue (temporary)

Tasks:

• Create simple test view that uses <GiftedDialog :use-store="true" />
• Test all major workflows (open, select entities, submit)
• Verify store state updates correctly
• Test validation and error handling
• NEW: Test improved method names and type safety
• NEW: Verify entity selection mode functionality

Success Criteria: Store mode works for basic gift creation workflow with improved UX

Phase 3: Incremental View Migration

3.1 Migrate HomeView

Files to modify:

src/views/HomeView.vue

Tasks:

• Import gift dialog store
• Update openDialog method to use store
• Change template to use <GiftedDialog :use-store="true" />
• Test all gift creation paths from HomeView
• Verify gift prompts integration still works
• NEW: Update any direct references to old method names
• NEW: Improve error handling with store-based validation

Enhanced Implementation:

// Updated HomeView.vue with improved integration
import { useGiftDialogStore } from '@/stores/giftDialog';
import { ENTITY_SELECTION_MODE } from '@/types/giftDialog';

export default class HomeView extends Vue {
  private giftDialogStore = useGiftDialogStore();

  openDialog(giver?: GiverReceiverInputInfo | "Unnamed", description?: string) {
    if (giver === "Unnamed") {
      this.giftDialogStore.openDialog({
        receiver: { did: this.activeDid, name: "You" },
        prompt: description,
        title: "Given by Unnamed"
      });
      // Immediately select unnamed giver and advance to gift details
      this.giftDialogStore.selectAsGiver({ did: "", name: "Unnamed" });
    } else {
      this.giftDialogStore.openDialog({
        giver,
        receiver: { did: this.activeDid, name: "You" },
        prompt: description,
        title: `Given by ${giver?.name || "someone not named"}`
      });
    }
  }
}

Validation:

• All existing Playwright tests pass
• Manual testing of gift creation flows
• Verify no regressions in user experience
• NEW: Verify improved error messages and validation

3.2 Migrate ContactsView

Files to modify:

src/views/ContactsView.vue

Tasks:

• Update contact-specific gift recording
• Migrate bidirectional confirmation flows
• Test contact pre-selection logic
• Verify direction clarity features work
• NEW: Implement improved entity selection mode handling
• NEW: Update method calls to use new naming convention

3.3 Migrate ProjectViewView

Files to modify:

src/views/ProjectViewView.vue

Tasks:

• Handle dual dialog instances (giveDialogToThis, giveDialogFromThis)
• Migrate project context locking
• Update offer integration
• Test bidirectional gift recording
• NEW: Implement proper entity type management for projects
• NEW: Enhance project-specific validation

3.4 Migrate Remaining Views

Files to modify:

src/views/ContactGiftingView.vue
src/views/ClaimView.vue
src/views/RecentOffersToUserView.vue
src/views/RecentOffersToUserProjectsView.vue
src/views/NewActivityView.vue

Tasks:

• Migrate each view systematically
• Test specialized features in each view
• Verify offer fulfillment workflows
• Ensure activity creation integration works
• NEW: Update all method calls to use improved naming
• NEW: Implement consistent error handling patterns

Phase 4: Template Enhancement and Component Integration

4.1 Complete Template Decomposition

Files to create/modify:

src/components/GiftedDialog.vue (major template refactor)
src/components/GiftDialog/GiftDialogStepIndicator.vue (enhance)
src/components/GiftDialog/EntityGridItem.vue (enhance)
src/components/GiftDialog/GiftDialogEntitySelection.vue (enhance)
src/components/GiftDialog/GiftDialogDetailsForm.vue (enhance)

Tasks:

• NEW: Refactor main GiftedDialog template to use component composition
• NEW: Implement visual progress indicators and step transitions
• NEW: Add comprehensive accessibility features (ARIA labels, keyboard navigation, focus management)
• NEW: Create responsive design patterns for all screen sizes
• NEW: Implement loading states and error feedback throughout
• NEW: Add animations and transitions for better UX
• NEW: Optimize component performance and bundle size

Enhanced Template Structure:

<!-- Enhanced GiftedDialog.vue -->
<template>
  <div v-if="isVisible" class="dialog-overlay" @click.self="closeDialog">
    <div class="dialog" role="dialog" aria-labelledby="dialog-title" aria-modal="true">
      <!-- Step Progress Indicator -->
      <GiftDialogStepIndicator 
        :current-step="currentStep"
        :total-steps="2"
        :step-labels="['Select Entities', 'Gift Details']"
      />

      <!-- Step 1: Entity Selection -->
      <GiftDialogEntitySelection
        v-if="currentStep === 'entity-selection'"
        :entity-selection-mode="entitySelectionMode"
        :giver-entity-type="giverEntityType"
        :recipient-entity-type="recipientEntityType"
        :should-show-projects="shouldShowProjects"
        :all-contacts="allContacts"
        :projects="projects"
        :active-did="activeDid"
        :conflict-checker="wouldCreateConflict"
        @select-entity="handleEntitySelection"
        @cancel="closeDialog"
      />

      <!-- Step 2: Gift Details -->
      <GiftDialogDetailsForm
        v-else-if="currentStep === 'gift-details'"
        :giver="giver"
        :receiver="receiver"
        :giver-entity-type="giverEntityType"
        :recipient-entity-type="recipientEntityType"
        :description="description"
        :amount-input="amountInput"
        :unit-code="unitCode"
        :prompt="prompt"
        :has-person-conflict="hasPersonConflict"
        :validation-errors="validationErrors"
        :is-submitting="isSubmitting"
        :can-edit-giver="canEditGiver"
        :can-edit-recipient="canEditRecipient"
        @update-description="updateDescription"
        @update-amount="updateAmount"
        @update-unit="updateUnit"
        @increment="increment"
        @decrement="decrement"
        @edit-entity="handleEditEntity"
        @submit="submitGift"
        @cancel="closeDialog"
        @open-advanced="openAdvancedDetails"
      />
    </div>
  </div>
</template>

4.2 Accessibility and Performance Optimization

Tasks:

• NEW: Implement comprehensive keyboard navigation
• NEW: Add screen reader support with proper ARIA labels
• NEW: Optimize component bundle size and loading performance
• NEW: Add comprehensive error handling and recovery
• NEW: Implement focus management between steps
• NEW: Add animation and transition effects

Success Criteria: Template is fully decomposed, accessible, and performant with improved user experience

Phase 5: Store Enhancement and Advanced Features

5.1 Advanced Store Features

Files to modify:

src/stores/giftDialog.ts

Tasks:

• Add comprehensive validation system
• Implement error handling and recovery
• Add persistence for draft gifts
• Create computed properties for complex UI states
• Add debugging and logging utilities
• NEW: Implement advanced entity selection logic
• NEW: Add conflict resolution strategies
• NEW: Create validation rules engine

5.2 Performance Optimization

Tasks:

• Optimize reactive updates
• Add selective state subscriptions
• Implement computed property caching
• Profile and optimize heavy operations

Success Criteria: No performance regressions, ideally improvements

Phase 6: Cleanup and Finalization

6.1 Remove Legacy Code

Files to modify:

src/components/GiftedDialog.vue

Tasks:

• Remove useStore prop and dual-mode logic
• Delete legacy state variables and methods
• Simplify component to pure UI logic
• Update component documentation
• NEW: Remove deprecated method warnings
• NEW: Clean up old variable names completely
• NEW: Finalize improved method signatures

6.2 Final Template Polish

Files to modify:

src/components/GiftedDialog.vue (template section)

Tasks:

• Update template to use new method names
• Improve template readability with better variable names
• Add better accessibility attributes
• NEW: Update all template references to use entitySelectionMode

Template Improvements:

<template>
  <!-- Before -->
  <label v-if="stepType === 'recipient'">Choose who received the gift:</label>
  
  <!-- After -->
  <label v-if="entitySelectionMode === ENTITY_SELECTION_MODE.RECIPIENT">
    Choose who received the gift:
  </label>
  
  <!-- Improved button actions -->
  <button @click="goBackToEntitySelection(ENTITY_SELECTION_MODE.GIVER)">
    Change Giver
  </button>
  
  <button @click="goBackToEntitySelection(ENTITY_SELECTION_MODE.RECIPIENT)">
    Change Recipient
  </button>
</template>

6.3 Add Comprehensive Testing

Files to create:

src/stores/__tests__/giftDialog.test.ts
test-playwright/gift-dialog-store.spec.ts
test-playwright/gift-dialog-naming.spec.ts (new)

Tasks:

• Unit tests for all store actions and getters
• Integration tests for complex workflows
• Error scenario testing
• Performance regression tests
• NEW: Test improved naming conventions
• NEW: Test entity selection mode functionality
• NEW: Validate type safety improvements

Enhanced Test Examples:

// Enhanced testing with improved naming
describe('GiftDialogStore Entity Selection', () => {
  it('should handle entity selection mode correctly', () => {
    const store = useGiftDialogStore();
    
    store.setEntitySelectionMode(ENTITY_SELECTION_MODE.GIVER);
    expect(store.entitySelectionMode).toBe(ENTITY_SELECTION_MODE.GIVER);
    expect(store.currentSelectionTarget).toBe('giver');
    
    store.setEntitySelectionMode(ENTITY_SELECTION_MODE.RECIPIENT);
    expect(store.entitySelectionMode).toBe(ENTITY_SELECTION_MODE.RECIPIENT);
    expect(store.currentSelectionTarget).toBe('recipient');
  });
  
  it('should detect person conflicts correctly', () => {
    const store = useGiftDialogStore();
    const person = { did: 'user123', name: 'John' };
    
    store.selectAsGiver(person);
    store.selectAsRecipient(person);
    
    expect(store.hasPersonConflict).toBe(true);
    expect(store.validationErrors).toContain('Cannot select the same person as both giver and recipient');
  });
});

6.4 Documentation Updates

Files to modify:

GiftedDialog-Logic-Flow.md
README.md (if applicable)

Tasks:

• Update architecture documentation
• Document new store-based patterns
• Create migration guide for future similar refactoring
• Update developer guidelines
• NEW: Document improved naming conventions
• NEW: Add entity selection mode documentation
• NEW: Create style guide for consistent naming

Risk Mitigation Strategies

Rollback Plan

1. Feature Flag Approach: Keep useStore prop until migration is complete
2. Incremental Rollback: Can revert individual views if issues arise
3. Branch Strategy: Maintain working branch alongside feature branch
4. NEW: Backward Compatibility: Maintain deprecated method warnings during transition

Testing Strategy

1. Continuous Testing: Run existing Playwright tests after each phase
2. Manual Testing: Test critical user journeys after each view migration
3. Performance Monitoring: Track bundle size and runtime performance
4. User Acceptance: Test with actual users before final deployment
5. NEW: Naming Guide: Share improved naming conventions with team
6. NEW: Code Review: Focus on naming consistency in reviews

Success Metrics

Technical Metrics

• All existing Playwright tests pass
• No increase in bundle size > 5%
• No performance regression > 10%
• Test coverage maintained or improved
• NEW: 100% type safety compliance
• NEW: Zero deprecated method usage in production

User Experience Metrics

• No change in user-facing functionality
• No increase in error rates
• Improved developer experience (easier debugging, better error messages)
• NEW: Improved error message clarity
• NEW: Better accessibility scores

Code Quality Metrics

• Reduced component complexity (fewer lines in GiftedDialog.vue)
• Improved testability (store logic can be tested independently)
• Better separation of concerns (UI vs business logic)
• NEW: Consistent naming conventions across codebase
• NEW: Improved TypeScript strict mode compliance
• NEW: Reduced cognitive complexity through better naming

Dependencies and Prerequisites

Required Before Starting

• Pinia already configured in the application
• All existing tests passing
• No major pending changes to GiftedDialog
• Team alignment on approach
• NEW: Team agreement on naming conventions
• NEW: TypeScript strict mode enabled or plan to enable

Nice to Have

• TypeScript strict mode enabled
• ESLint rules for Pinia best practices
• Vue DevTools with Pinia extension installed
• NEW: ESLint rules for consistent naming patterns
• NEW: Automated code formatting tools configured
• NEW: Documentation generation tools for type definitions

Additional Improvements Summary

The enhanced refactoring plan now includes:

1. Improved Variable Naming: stepType → entitySelectionMode with proper typing
2. Method Name Consistency: selectGiver → selectAsGiver, goBackToStep1 → goBackToEntitySelection
3. Enhanced Type Safety: Comprehensive TypeScript interfaces and constants
4. Better Code Organization: Clear separation of concerns and consistent patterns
5. Improved Developer Experience: Better error messages, warnings, and debugging tools
6. Comprehensive Testing: Additional test coverage for naming and type safety
7. Documentation: Enhanced documentation for new patterns and conventions

This plan provides a systematic, low-risk approach to refactoring while maintaining full backward compatibility and significantly improving code quality and maintainability.

---

PROPOSED QUICK FIXES AND ENHANCEMENTS

Overview

During analysis of the GiftedDialog component, several immediate usability improvements were identified. These are documented here as proposed enhancements that can be implemented either as part of the Pinia store refactoring or as separate improvements.

Critical Usability Issues Identified

1. Component Dual-Purpose Confusion

Issue: GiftedDialog serves both entity selection and gift details, which can confuse users about what step they're on.

Proposed Solution: Add clear step indicators to show progress through the dialog workflow.

2. Broken Navigation Flow in ContactGiftingView

Issue: Contact selection in ContactGiftingView led to dead end - users couldn't complete gift recording and had no clear path back.

Proposed Solution: Implement proper success callbacks and navigation logic to return users to appropriate views after gift completion.

3. Redundant Parameters

Issue: Legacy projectId parameter conflicts with new context-aware parameters, causing confusion.

Proposed Solution: Clean up parameter handling and remove redundant legacy parameters.

Proposed Quick Fixes

1. Navigation Flow Improvements

Files to modify:

• src/views/ContactGiftingView.vue
• src/components/GiftedDialog.vue

Proposed Changes:

// Add helper methods to ContactGiftingView.vue
buildCurrentGiver(): GiverReceiverInputInfo {
  if (this.giverEntityType === "project") {
    return {
      did: this.giverProjectHandleId,
      name: this.giverProjectName,
      handleId: this.giverProjectHandleId,
      image: this.giverProjectImage
    };
  }
  if (this.giverDid) {
    return { 
      did: this.giverDid, 
      name: this.giverProjectName || "Someone" 
    };
  }
  return { did: this.activeDid, name: "You" };
}

buildCurrentReceiver(): GiverReceiverInputInfo {
  if (this.recipientEntityType === "project") {
    return {
      did: this.recipientProjectHandleId,
      name: this.recipientProjectName,
      handleId: this.recipientProjectHandleId,
      image: this.recipientProjectImage
    };
  }
  if (this.recipientDid) {
    return { 
      did: this.recipientDid, 
      name: "Someone" 
    };
  }
  return { did: this.activeDid, name: "You" };
}

buildCustomTitle(contact: Contact | "Unnamed"): string {
  const contactName = contact === "Unnamed" ? "Unnamed" : contact.name || "someone";
  return this.stepType === "giver" 
    ? `Given by ${contactName}`
    : `Given to ${contactName}`;
}

// Improved openDialog method with better navigation flow
openDialogImproved(contact: Contact | "Unnamed") {
  const giver = this.stepType === "giver" 
    ? (contact === "Unnamed" ? { did: "", name: "Unnamed" } : contact)
    : this.buildCurrentGiver();
  
  const receiver = this.stepType === "recipient" 
    ? (contact === "Unnamed" ? { did: "", name: "Unnamed" } : contact)
    : this.buildCurrentReceiver();
  
  // Open dialog with success callback to handle navigation
  (this.$refs.customDialog as GiftedDialog).open(
    giver,
    receiver,
    undefined, // offerId
    this.buildCustomTitle(contact),
    this.prompt,
    (amount: number) => {
      // Success callback - show success message and navigate back
      this.$notify({
        group: "alert",
        type: "success",
        title: "Gift Recorded",
        text: `Successfully recorded gift${amount > 0 ? ` of ${amount}` : ''}`
      });
      
      // Navigate back to the appropriate view
      if (this.isFromProjectView && (this.fromProjectId || this.toProjectId)) {
        const projectId = this.fromProjectId || this.toProjectId;
        this.$router.push({ 
          name: 'project', 
          params: { id: projectId }
        });
      } else {
        this.$router.push({ name: 'home' });
      }
    }
  );
  
  // If contact is "Unnamed", immediately advance to step 2
  if (contact === "Unnamed") {
    if (this.stepType === "giver") {
      (this.$refs.customDialog as GiftedDialog).selectGiver();
    } else {
      (this.$refs.customDialog as GiftedDialog).selectRecipient();
    }
  }
}

2. Parameter Cleanup

Proposed Changes:

• Remove legacy projectId parameter from ContactGiftingView
• Eliminate redundant query parameter handling
• Streamline context-aware parameter usage

// Remove from ContactGiftingView.vue
// projectId = ""; // Remove this legacy parameter

// Update query parameter handling to remove redundancy
mounted() {
  // Remove projectId handling, use only context-specific parameters
  this.recipientProjectName =
    (this.$route.query["recipientProjectName"] as string) || "";
  // ... other parameters without projectId
}

3. User Experience Enhancements

Proposed Template Changes for GiftedDialog.vue:

<template>
  <div v-if="visible" class="dialog-overlay">
    <div class="dialog">
      <!-- Step Indicators -->
      <div class="step-indicator mb-4" v-show="currentStep === 1">
        <div class="text-center text-sm text-slate-600 mb-2">
          Step 1 of 2: Select {{ stepType === 'giver' ? 'Giver' : 'Recipient' }}
        </div>
        <div class="flex justify-center">
          <div class="w-8 h-8 bg-blue-500 text-white rounded-full flex items-center justify-center text-sm font-bold mr-2">1</div>
          <div class="w-8 h-8 bg-slate-300 text-slate-600 rounded-full flex items-center justify-center text-sm">2</div>
        </div>
      </div>

      <div class="step-indicator mb-4" v-show="currentStep === 2">
        <div class="text-center text-sm text-slate-600 mb-2">
          Step 2 of 2: Gift Details
        </div>
        <div class="flex justify-center">
          <div class="w-8 h-8 bg-green-500 text-white rounded-full flex items-center justify-center text-sm">✓</div>
          <div class="w-8 h-8 bg-blue-500 text-white rounded-full flex items-center justify-center text-sm font-bold ml-2">2</div>
        </div>
      </div>

      <!-- Step 1: Entity Selection -->
      <div v-show="currentStep === 1" id="sectionGiftedGiver">
        <!-- Improved labels with clearer context -->
        <label class="block font-bold mb-4">
          <span v-if="stepType === 'recipient'" class="text-blue-600">
            👤 Choose who RECEIVED the gift:
          </span>
          <span v-else-if="showProjects" class="text-green-600">
            🏗️ Choose which PROJECT you benefited from:
          </span>
          <span v-else class="text-purple-600">
            👤 Choose who GAVE you something:
          </span>
        </label>
        <!-- ... rest of template ... -->
      </div>
    </div>
  </div>
</template>

Implementation Priority

High Priority (Immediate User Impact)

1. Navigation Flow Fix: Implement success callbacks and proper navigation
2. Step Indicators: Add visual progress indication
3. Parameter Cleanup: Remove legacy projectId confusion

Medium Priority (User Experience)

1. Enhanced Labels: Add color-coded context and emoji visual cues
2. Error Handling: Improve error messages and validation feedback

Low Priority (Code Quality)

1. Method Naming: Standardize method names for consistency
2. Type Safety: Enhance TypeScript definitions
3. Documentation: Update inline documentation

Integration with Pinia Refactoring

These quick fixes can be implemented in two ways:

1. Standalone Implementation: Apply these fixes to the current component before the Pinia refactoring
2. Integrated Implementation: Include these improvements as part of the Pinia store refactoring plan

Recommendation: Implement the navigation flow fixes immediately as they address critical usability issues, then include the UX enhancements as part of the Pinia refactoring for better consistency.

Testing Requirements

Manual Testing Checklist

• ContactGiftingView navigation flow works correctly
• Users can complete gift recording without getting stuck
• Success callbacks navigate to appropriate views
• Step indicators show correct progress
• Error states are handled gracefully

Automated Testing

• Update Playwright tests to verify navigation flows
• Add tests for success callback functionality
• Verify parameter cleanup doesn't break existing functionality

Risk Assessment

Low Risk Changes

• Adding step indicators (purely visual enhancement)
• Improving label text and adding emoji
• Parameter cleanup (removing unused parameters)

Medium Risk Changes

• Navigation flow changes (affects user journey)
• Success callback implementation (new functionality)

Mitigation Strategies

• Implement changes incrementally
• Test thoroughly in development environment
• Have rollback plan ready
• Monitor user feedback after deployment

Status: These improvements are documented as proposed changes and ready for implementation when development resources are available.

---

TEMPLATE IMPROVEMENTS DURING PINIA REFACTORING

Overview

The Pinia refactoring provides an excellent opportunity to modernize and significantly improve the GiftedDialog template. The current template has grown organically and contains several areas that can benefit from modern Vue 3 patterns, better accessibility, improved component composition, and cleaner state management integration.

Current Template Analysis

Strengths

• ✅ Responsive grid layouts for different screen sizes
• ✅ Clear visual hierarchy with icons and typography
• ✅ Conflict detection and prevention UI
• ✅ Comprehensive entity selection interface

Areas for Improvement

• 🔄 Complex conditional logic in template makes it hard to maintain
• 🔄 Repetitive code for entity display and selection
• 🔄 Accessibility gaps in keyboard navigation and screen readers
• 🔄 Mixed concerns - UI logic mixed with business logic
• 🔄 Inconsistent styling patterns across similar elements
• 🔄 No step indicators for user guidance
• 🔄 Limited error feedback for validation states

Proposed Template Improvements

1. Component Composition and Extraction

Current Issue: The template is monolithic with ~400 lines of mixed logic.

Proposed Solution: Extract reusable sub-components for better maintainability.

New Component Structure:

<!-- Enhanced GiftedDialog.vue -->
<template>
  <div v-if="isVisible" class="dialog-overlay" @click.self="closeDialog">
    <div class="dialog" role="dialog" aria-labelledby="dialog-title" aria-modal="true">
      <!-- Step Progress Indicator -->
      <GiftDialogStepIndicator 
        :current-step="currentStep"
        :total-steps="2"
        :step-labels="['Select Entities', 'Gift Details']"
      />

      <!-- Step 1: Entity Selection -->
      <GiftDialogEntitySelection
        v-if="currentStep === 'entity-selection'"
        :entity-selection-mode="entitySelectionMode"
        :giver-entity-type="giverEntityType"
        :recipient-entity-type="recipientEntityType"
        :should-show-projects="shouldShowProjects"
        :all-contacts="allContacts"
        :projects="projects"
        :active-did="activeDid"
        :conflict-checker="wouldCreateConflict"
        @select-entity="handleEntitySelection"
        @cancel="closeDialog"
      />

      <!-- Step 2: Gift Details -->
      <GiftDialogDetailsForm
        v-else-if="currentStep === 'gift-details'"
        :giver="giver"
        :receiver="receiver"
        :giver-entity-type="giverEntityType"
        :recipient-entity-type="recipientEntityType"
        :description="description"
        :amount-input="amountInput"
        :unit-code="unitCode"
        :prompt="prompt"
        :has-person-conflict="hasPersonConflict"
        :validation-errors="validationErrors"
        :is-submitting="isSubmitting"
        :can-edit-giver="canEditGiver"
        :can-edit-recipient="canEditRecipient"
        @update-description="updateDescription"
        @update-amount="updateAmount"
        @update-unit="updateUnit"
        @increment="increment"
        @decrement="decrement"
        @edit-entity="handleEditEntity"
        @submit="submitGift"
        @cancel="closeDialog"
        @open-advanced="openAdvancedDetails"
      />

      <!-- Loading State -->
      <GiftDialogLoadingState
        v-else-if="currentStep === 'loading'"
        :message="loadingMessage"
      />

      <!-- Error State -->
      <GiftDialogErrorState
        v-else-if="currentStep === 'error'"
        :error-message="errorMessage"
        @retry="retryAction"
        @close="closeDialog"
      />
    </div>
  </div>
</template>

2. Step Progress Indicator Component

New Component: GiftDialogStepIndicator.vue

<template>
  <div class="step-indicator mb-6" role="progressbar" :aria-valuenow="currentStep" :aria-valuemax="totalSteps">
    <!-- Progress Bar -->
    <div class="relative mb-4">
      <div class="overflow-hidden h-2 text-xs flex rounded bg-slate-200">
        <div 
          class="shadow-none flex flex-col text-center whitespace-nowrap text-white justify-center bg-blue-500 transition-all duration-300"
          :style="{ width: \`\${(currentStep / totalSteps) * 100}%\` }"
        ></div>
      </div>
    </div>

    <!-- Step Circles and Labels -->
    <div class="flex justify-between items-center">
      <div 
        v-for="(label, index) in stepLabels" 
        :key="index"
        class="flex flex-col items-center"
        :class="{ 'flex-1': index < stepLabels.length - 1 }"
      >
        <!-- Step Circle -->
        <div 
          class="w-8 h-8 rounded-full flex items-center justify-center text-sm font-bold mb-2 transition-all duration-200"
          :class="getStepCircleClasses(index + 1)"
          :aria-label="\`Step \${index + 1}: \${label}\`"
        >
          <font-awesome 
            v-if="index + 1 < currentStep" 
            icon="check" 
            class="text-white"
          />
          <span v-else>{{ index + 1 }}</span>
        </div>
        
        <!-- Step Label -->
        <span 
          class="text-xs text-center font-medium transition-colors duration-200"
          :class="getStepLabelClasses(index + 1)"
        >
          {{ label }}
        </span>
      </div>
    </div>
  </div>
</template>

3. Enhanced Entity Selection Component

New Component: GiftDialogEntitySelection.vue

• Dedicated component for entity selection logic
• Better accessibility with proper ARIA labels
• Cleaner separation of projects vs contacts logic
• Improved conflict detection UI
• Keyboard navigation support

4. Reusable Entity Grid Item Component

New Component: EntityGridItem.vue

• Standardized entity display across projects and contacts
• Consistent hover and focus states
• Accessibility improvements
• Conflict state visualization
• Responsive design patterns

5. Enhanced Gift Details Form Component

New Component: GiftDialogDetailsForm.vue

• Clean form layout with proper labels
• Improved validation feedback
• Better amount input controls
• Enhanced accessibility
• Loading state management

Benefits of Template Improvements

1. Maintainability

• ✅ Smaller, focused components easier to understand and modify
• ✅ Clear separation of concerns between UI and business logic
• ✅ Reusable components reduce duplication
• ✅ Consistent patterns across similar functionality

2. Accessibility

• ✅ Proper ARIA labels and roles
• ✅ Keyboard navigation support
• ✅ Screen reader compatibility
• ✅ Focus management between steps
• ✅ Clear error messaging

3. User Experience

• ✅ Visual progress indicators
• ✅ Clear step-by-step guidance
• ✅ Consistent styling and interactions
• ✅ Better error feedback
• ✅ Loading and error states

4. Developer Experience

• ✅ TypeScript support throughout
• ✅ Clear component APIs with props and events
• ✅ Easier testing with isolated components
• ✅ Better debugging with focused responsibilities

5. Performance

• ✅ Smaller bundle sizes for individual components
• ✅ Better tree-shaking opportunities
• ✅ Optimized re-rendering with focused state
• ✅ Lazy loading potential for sub-components

Store Integration Patterns

Enhanced Store Integration:

<script lang="ts">
import { Vue, Component } from "vue-facing-decorator";
import { useGiftDialogStore } from "@/stores/giftDialog";
import { storeToRefs } from "pinia";

@Component({
  components: {
    GiftDialogStepIndicator,
    GiftDialogEntitySelection,
    GiftDialogDetailsForm
  }
})
export default class GiftedDialog extends Vue {
  private giftDialogStore = useGiftDialogStore();
  private storeRefs = storeToRefs(this.giftDialogStore);

  // Computed properties directly from store
  get isVisible() { return this.storeRefs.isVisible.value; }
  get currentStep() { return this.storeRefs.currentStep.value; }
  get entitySelectionMode() { return this.storeRefs.entitySelectionMode.value; }

  // Event handlers that delegate to store actions
  handleEntitySelection(selection: any) {
    if (selection.type === 'giver') {
      this.giftDialogStore.setGiver(selection.entity);
    } else {
      this.giftDialogStore.setReceiver(selection.entity);
    }
    this.giftDialogStore.setCurrentStep('gift-details');
  }

  async submitGift() {
    const success = await this.giftDialogStore.submitGift();
    if (success && this.giftDialogStore.callbackOnSuccess) {
      this.giftDialogStore.callbackOnSuccess(parseFloat(this.amountInput) || 0);
    }
  }
}
</script>

Implementation Strategy

Phase 1: Foundation Components (2 days)

1. Create GiftDialogStepIndicator component
2. Create EntityGridItem component
3. Create EntitySummaryCard component
4. Create ValidationErrorList component

Phase 2: Main Components (3 days)

1. Create GiftDialogEntitySelection component
2. Create GiftDialogDetailsForm component
3. Create loading and error state components

Phase 3: Integration (2 days)

1. Update main GiftedDialog.vue to use new components
2. Integrate with Pinia store
3. Update styling and accessibility
4. Add comprehensive testing

Phase 4: Polish (1 day)

1. Add animations and transitions
2. Optimize performance
3. Documentation and examples

Key Improvements Summary

1. Component Decomposition: Break 400+ line template into focused, reusable components
2. Accessibility Enhancement: Add proper ARIA labels, keyboard navigation, and screen reader support
3. Visual Progress: Add step indicators and better state feedback
4. Store Integration: Clean separation between UI components and Pinia store state
5. Type Safety: Full TypeScript support across all new components
6. Testing: Easier unit testing with isolated component responsibilities
7. Performance: Better optimization opportunities with focused components

This template refactoring transforms a monolithic component into a well-organized, maintainable, and accessible system that fully leverages the Pinia store architecture while providing significantly better user and developer experience.