Matthew Raymer
3 weeks ago
8 changed files with 288 additions and 106 deletions
@ -0,0 +1,207 @@ |
|||
# GiftedDialog Entity Types Refactoring |
|||
|
|||
## Overview |
|||
|
|||
This refactoring simplifies the `GiftedDialog` component by replacing the complex `updateEntityTypes()` method with explicit props for entity types. This makes the component more declarative, reusable, and easier to understand. |
|||
|
|||
## Problem |
|||
|
|||
The original `updateEntityTypes()` method used multiple props (`showProjects`, `fromProjectId`, `toProjectId`, `recipientEntityTypeOverride`) to determine entity types through complex conditional logic: |
|||
|
|||
```typescript |
|||
updateEntityTypes() { |
|||
// Reset and set entity types based on current context |
|||
this.giverEntityType = "person"; |
|||
this.recipientEntityType = "person"; |
|||
|
|||
// If recipient entity type is explicitly overridden, use that |
|||
if (this.recipientEntityTypeOverride) { |
|||
this.recipientEntityType = this.recipientEntityTypeOverride; |
|||
} |
|||
|
|||
// Determine entity types based on current context |
|||
if (this.showProjects) { |
|||
// HomeView "Project" button or ProjectViewView "Given by This" |
|||
this.giverEntityType = "project"; |
|||
// Only override recipient if not already set by recipientEntityTypeOverride |
|||
if (!this.recipientEntityTypeOverride) { |
|||
this.recipientEntityType = "person"; |
|||
} |
|||
} else if (this.fromProjectId) { |
|||
// ProjectViewView "Given by This" button (project is giver) |
|||
this.giverEntityType = "project"; |
|||
// Only override recipient if not already set by recipientEntityTypeOverride |
|||
if (!this.recipientEntityTypeOverride) { |
|||
this.recipientEntityType = "person"; |
|||
} |
|||
} else if (this.toProjectId) { |
|||
// ProjectViewView "Given to This" button (project is recipient) |
|||
this.giverEntityType = "person"; |
|||
// Only override recipient if not already set by recipientEntityTypeOverride |
|||
if (!this.recipientEntityTypeOverride) { |
|||
this.recipientEntityType = "project"; |
|||
} |
|||
} else { |
|||
// HomeView "Person" button |
|||
this.giverEntityType = "person"; |
|||
// Only override recipient if not already set by recipientEntityTypeOverride |
|||
if (!this.recipientEntityTypeOverride) { |
|||
this.recipientEntityType = "person"; |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Issues with the Original Approach |
|||
|
|||
1. **Complex Logic**: Nested conditionals that were hard to follow |
|||
2. **Tight Coupling**: Views needed to understand internal logic to set the right props |
|||
3. **Inflexible**: Adding new entity type combinations required modifying the method |
|||
4. **Unclear Intent**: The relationship between props and entity types was not obvious |
|||
|
|||
## Solution |
|||
|
|||
### 1. Explicit Props |
|||
|
|||
Replace the complex logic with explicit props: |
|||
|
|||
```typescript |
|||
@Prop({ default: "person" }) giverEntityType = "person" as "person" | "project"; |
|||
@Prop({ default: "person" }) recipientEntityType = "person" as "person" | "project"; |
|||
``` |
|||
|
|||
### 2. Simple Inline Logic |
|||
|
|||
Views now use simple inline logic to determine entity types: |
|||
|
|||
```vue |
|||
<!-- HomeView --> |
|||
<GiftedDialog |
|||
ref="giftedDialog" |
|||
:giver-entity-type="showProjectsDialog ? 'project' : 'person'" |
|||
:recipient-entity-type="'person'" |
|||
/> |
|||
|
|||
<!-- ProjectViewView --> |
|||
<GiftedDialog |
|||
ref="giveDialogToThis" |
|||
:giver-entity-type="'person'" |
|||
:recipient-entity-type="'project'" |
|||
:to-project-id="projectId" |
|||
:is-from-project-view="true" |
|||
/> |
|||
|
|||
<!-- ClaimView --> |
|||
<GiftedDialog |
|||
ref="customGiveDialog" |
|||
:giver-entity-type="'person'" |
|||
:recipient-entity-type="projectInfo ? 'project' : 'person'" |
|||
:to-project-id="..." |
|||
/> |
|||
``` |
|||
|
|||
## Benefits |
|||
|
|||
### 1. **Declarative** |
|||
- Entity types are explicitly declared in the template |
|||
- No hidden logic in watchers or complex methods |
|||
- Clear intent at the call site |
|||
|
|||
### 2. **Reusable** |
|||
- Views can easily specify any combination of entity types |
|||
- No need to understand internal logic |
|||
- Simple inline logic is easy to understand |
|||
|
|||
### 3. **Maintainable** |
|||
- Adding new entity type combinations is straightforward |
|||
- Logic is visible directly in the template |
|||
- No additional files to maintain |
|||
|
|||
### 4. **Testable** |
|||
- Entity type logic is visible and predictable |
|||
- No complex state management to test |
|||
- Template logic can be easily verified |
|||
|
|||
### 5. **Type Safe** |
|||
- TypeScript ensures correct entity type values |
|||
- Compile-time validation of entity type combinations |
|||
|
|||
## Migration Guide |
|||
|
|||
### For Views Using GiftedDialog |
|||
|
|||
Simply update the template to use explicit entity type props: |
|||
|
|||
```vue |
|||
<!-- Before --> |
|||
<GiftedDialog :show-projects="showProjects" /> |
|||
|
|||
<!-- After --> |
|||
<GiftedDialog |
|||
:giver-entity-type="showProjects ? 'project' : 'person'" |
|||
:recipient-entity-type="'person'" |
|||
/> |
|||
``` |
|||
|
|||
### Common Patterns |
|||
|
|||
1. **Person-to-Person**: `giver-entity-type="'person'" recipient-entity-type="'person'"` |
|||
2. **Project-to-Person**: `giver-entity-type="'project'" recipient-entity-type="'person'"` |
|||
3. **Person-to-Project**: `giver-entity-type="'person'" recipient-entity-type="'project'"` |
|||
4. **Conditional Project**: `recipient-entity-type="hasProject ? 'project' : 'person'"` |
|||
|
|||
## Files Changed |
|||
|
|||
### Core Changes |
|||
- `src/components/GiftedDialog.vue` - Removed `updateEntityTypes()` method, added explicit props |
|||
|
|||
### View Updates |
|||
- `src/views/HomeView.vue` - Updated to use inline logic |
|||
- `src/views/ProjectViewView.vue` - Updated to use inline logic |
|||
- `src/views/ClaimView.vue` - Updated to use inline logic |
|||
- `src/views/ContactGiftingView.vue` - Updated to use inline logic |
|||
- `src/views/ContactsView.vue` - Updated to use inline logic |
|||
|
|||
## Backward Compatibility |
|||
|
|||
The refactoring maintains backward compatibility by: |
|||
- Keeping all existing props that are still needed (`fromProjectId`, `toProjectId`, `isFromProjectView`) |
|||
- Preserving the same component API for the `open()` method |
|||
- Maintaining the same template structure |
|||
|
|||
## Future Enhancements |
|||
|
|||
1. **Validation**: Add runtime validation for entity type combinations |
|||
2. **Documentation**: Add JSDoc comments to the component props |
|||
3. **Testing**: Add unit tests for the component with different entity type combinations |
|||
|
|||
## Conclusion |
|||
|
|||
This refactoring transforms `GiftedDialog` from a component with complex internal logic to a declarative, reusable component. The explicit entity type props make the component's behavior clear and predictable, while the simple inline logic keeps the code straightforward and maintainable. |
|||
|
|||
## Bug Fixes |
|||
|
|||
### Issue 1: Entity Type Preservation in Navigation |
|||
|
|||
**Problem**: When navigating from HomeView with `showProjects = true` to ContactGiftingView via "Show All", the entity type information was lost because `showAllQueryParams` returned an empty object for project contexts. |
|||
|
|||
**Solution**: Modified `EntitySelectionStep.vue` to always pass entity type information in the query parameters, even for project contexts. |
|||
|
|||
### Issue 2: Recipient Reset in ContactGiftingView |
|||
|
|||
**Problem**: When selecting a giver in ContactGiftingView, the recipient was always reset to "You" instead of preserving the current recipient. |
|||
|
|||
**Solution**: Updated ContactGiftingView to preserve the existing recipient from the context when selecting a giver, and enhanced the query parameter passing to include both giver and recipient information for better context preservation. |
|||
|
|||
### Issue 3: HomeView Project Button Entity Type Mismatch |
|||
|
|||
**Problem**: When navigating from HomeView Project button → change recipient → Show All → ContactGifting, the giver entity type was incorrectly set to "person" instead of "project". |
|||
|
|||
**Root Cause**: ContactGiftingView was inferring entity types from `fromProjectId` and `toProjectId` instead of using the explicitly passed `giverEntityType` and `recipientEntityType` from the query parameters. |
|||
|
|||
**Solution**: Updated ContactGiftingView to use the explicitly passed entity types from query parameters instead of inferring them from project IDs. |
|||
|
|||
### Files Modified for Bug Fixes |
|||
|
|||
- `src/components/EntitySelectionStep.vue` - Enhanced query parameter passing |
|||
- `src/views/ContactGiftingView.vue` - Improved context preservation logic and entity type handling |
|||
Loading…
Reference in new issue