Add Cards To Your Collection: UI Implementation
Hey guys! Let's dive into the UI implementation for the "Add a Card" feature. This is going to be a game-changer, allowing users to easily add cards to their collection, whether they're already in our database or not. We'll break down the different phases, components, API endpoints, navigation integrations, and more. Buckle up, it's gonna be a fun ride!
Phase 1: Single Card Submission - Adding One Card at a Time
This is where the magic begins! Phase 1 focuses on enabling users to add cards one at a time. It's the cornerstone of our "Add a Card" feature. We're going to build a comprehensive UI to make this process as smooth and efficient as possible.
New Components to Build
Let's get into the nitty-gritty of the components we need to build for this phase.
1. AddCardPage.jsx - Main Page (/add-card)
This is the heart of the operation, the main page where users will enter their card details. Think of it as a full-page form with all the necessary fields to capture card information. Here's a breakdown of what it will include:
- Year Selector (Dropdown, 1900-Current+1): A dropdown menu to select the card's year. We're offering a range from 1900 to the current year plus one, just to be safe, you know?
- Set Autocomplete: As the user types, this autocomplete feature will search for matching sets. It will be filtered by the year selected, making it easier to find the right set. This is all about speed and convenience, right?
- Series Autocomplete: Similar to the set autocomplete, this will help users find the series the card belongs to. It will be filtered based on the selected set. If the set has a "Base" series, that will resolve automatically.
- Card Number Input (Free Text): A simple text input for the card number. This is where users enter the number printed on the card.
- Player Autocomplete: A powerful autocomplete feature to search for players. This will eventually support multiple players for those multi-player cards. It will make finding the right player super easy.
- Team Autocomplete: This field will auto-fill based on the player selection. However, users can still edit it if needed. This saves time and ensures accuracy.
- Checkboxes: Rookie, Autograph, Relic, Short Print: Convenient checkboxes to indicate if the card is a rookie card, autograph, relic, or short print. Quick and easy.
- Optional Fields: Color/Parallel, Print Run, Notes: Fields for more detailed information like color/parallel, the print run (if it's a numbered card), and any additional notes the user wants to add.
Live Resolution Panel
This is the magic! The live resolution panel is the brains of the operation. It will display the real-time status of each field as the user enters information. The panel will show whether the entered data matches existing entities in our database. Here's how it works:
- ✓ Matched Entities (Green): Indicates an exact match, which means the card data matches what we have in the database.
- ⚠ Will Be Created (Yellow): If there's no match, but the system believes a new entity needs to be created, this is flagged. It's a heads up that the card might not be in our system yet.
- ✗ Invalid/Error (Red): Any errors or invalid data will be flagged in red. This helps users quickly identify and correct any mistakes.
2. EntityAutocomplete.jsx - Reusable Autocomplete Component
This is a super important reusable component. Think of it as the engine behind the autocomplete features for sets, series, players, and teams.
Props:
entityType(set, series, player, team): This tells the component what type of entity it's dealing with.filterParams(e.g., year for sets, setId for series): Parameters to filter the search results.onSelectcallback: A function that's called when an item is selected.allowCreateboolean (shows "Not found - will be created" option): Allows the creation of new entries.
Features:
- Debounced search (300ms): Prevents too many API calls while the user is typing.
- Keyboard navigation: Allows users to navigate the results using their keyboard.
- Shows match confidence: Displays how confident the system is in its match.
- Highlights exact vs. fuzzy matches: Differentiates between exact and approximate matches for clarity.
3. ResolutionStatus.jsx - Live Feedback Panel
This component is responsible for providing users with real-time feedback on their entries. It shows the resolution status for all fields. It will look something like this:
✓ Set: 2024 Topps Chrome (exact match)
✓ Series: 2024 Topps Chrome (resolved from "Base")
✓ Player: Mike Trout (95% confidence)
✓ Team: Los Angeles Angels (from player)
⚠ Card #150: Not in database - will be created pending review
This panel will give users a clear picture of what's happening with their input.
4. AddCardSuccess.jsx - Confirmation Component
After a successful submission, this component will take over. It will confirm that the card has been added and provide helpful information. It will include:
- Card added confirmation.
- Resolution summary.
- A link to view the card in the user's collection.
- An "Add Another Card" button for adding more cards.
- If the card needs review, an explanation of the review process will be provided.
API Endpoints Needed
We need to build some API endpoints to make this all work.
New Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/search/sets-autocomplete |
Search sets by name, filtered by year |
| GET | /api/search/series-autocomplete |
Search series within a set |
| GET | /api/search/players-autocomplete |
Search players by name |
| GET | /api/search/teams-autocomplete |
Search teams by name |
| POST | /api/resolve/preview |
Preview resolution without submitting |
Existing Endpoints (already built)
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /api/crowdsource/provisional-card |
Submit the card |
| GET | /api/crowdsource/my-provisional-cards |
User's pending cards |
| GET | /api/crowdsource/my-bundles |
User's submission history |
Navigation Integration
We need to make it super easy for users to find the "Add a Card" feature. Here's how we'll integrate it into the navigation.
Desktop Nav
[Logo] [Browse ▼] [Search] [Add a Card] [Collection] [Profile]
^^^^^^^^^^ NEW - prominent button
We'll add a prominent "Add a Card" button in the main navigation.
Mobile Nav
- Floating Action Button (FAB) with "+" icon.
- Or a prominent button in the hamburger menu.
Collection Dashboard
- Hero section: "Add cards to your collection."
- Large "Add a Card" button/card.
Page Flow
Here's the step-by-step process of adding a card:
/add-card
│
├── User fills form with autocomplete assistance
│
├── Live resolution shows what matches/doesn't
│
├── User clicks "Add to My Collection"
│
├── POST /api/crowdsource/provisional-card
│
└── Success State
├── If fully resolved: "Card added to your collection!"
└── If needs review: "Card added! Pending review for new [entity]."
Wireframe
Here is what the basic UI will look like.
┌──────────────────────────────────────────────────────────────────────────┐
│ ← Back ADD A CARD │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────┐ ┌────────────────────────────────┐ │
│ │ CARD DETAILS │ │ RESOLUTION STATUS │ │
│ ├─────────────────────────────────┤ ├────────────────────────────────┤ │
│ │ │ │ │ │
│ │ Year │ │ Checking... │ │
│ │ ┌─────────────────────────┐ │ │ │ │
│ │ │ 2024 ▼ │ │ │ ✓ Set found │ │
│ │ └─────────────────────────┘ │ │ 2024 Topps Chrome │ │
│ │ │ │ │ │
│ │ Set │ │ ✓ Series found │ │
│ │ ┌─────────────────────────┐ │ │ 2024 Topps Chrome (base) │ │
│ │ │ 2024 Topps Chrome ▼ │ │ │ │ │
│ │ └─────────────────────────┘ │ │ ✓ Player found │ │
│ │ │ │ Mike Trout (95%) │ │
│ │ Series │ │ │ │
│ │ ┌─────────────────────────┐ │ │ ✓ Team found │ │
│ │ │ Base ▼ │ │ │ Los Angeles Angels │ │
│ │ └─────────────────────────┘ │ │ │ │
│ │ │ │ ⚠ Card not in database │ │
│ │ Card Number │ │ Will be created upon review │ │
│ │ ┌─────────────────────────┐ │ │ │ │
│ │ │ 150 │ │ ├────────────────────────────────┤ │
│ │ └─────────────────────────┘ │ │ │ │
│ │ │ │ This card will be added to │ │
│ │ Player │ │ your collection immediately. │ │
│ │ ┌─────────────────────────┐ │ │ │ │
│ │ │ Mike Trout ▼ │ │ │ An admin will review and │ │
│ │ └─────────────────────────┘ │ │ create the new card entry. │ │
│ │ │ │ │ │
│ │ Team │ └────────────────────────────────┘ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ Los Angeles Angels ▼ │ │ │
│ │ └─────────────────────────┘ │ │
│ │ │ │
│ │ ☐ Rookie Card │ │
│ │ ☐ Autograph │ │
│ │ ☐ Relic / Memorabilia │ │
│ │ ☐ Short Print │ │
│ │ │ │
│ │ ─────────── Optional ──────── │ │
│ │ │ │
│ │ Color / Parallel │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ Gold Refractor ▼ │ │ │
│ │ └─────────────────────────┘ │ │
│ │ │ │
│ │ Print Run (if numbered) │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ /50 │ │ │
│ │ └─────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ADD TO MY COLLECTION │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Phase 2: User Submission Management - Tracking Your Submissions
This phase is all about giving users control and visibility over their submissions. We want them to easily track the cards they've added and see the status of each submission.
My Submissions Page (/my-submissions)
This page will act as a dashboard for users to manage their card submissions. It will include:
- List of all user's submission bundles.
- Status filter (Pending / Approved / Rejected).
- Expandable rows showing individual cards.
- Rejection feedback visible.
- Re-submit option for rejected cards.
Collection Integration
To make it even better, we'll integrate the provisional cards into the collection with a special badge. This gives the users clear visual distinction.
- Provisional cards appear in the collection with a badge.
- Clicking shows submission status.
- Visual distinction (dashed border? opacity? badge?)
Phase 3: Admin Review UI - Admin Side
This is the backend part of our crowdsourcing system. We need a way for admins to review and approve the cards submitted by users. This phase is super important to maintain data quality.
Admin Crowdsource Review Page (/admin/crowdsource-review)
This will be the central hub for admins to review the submissions.
- Queue of pending bundles.
- Filters by
requires_new_*flags. - Sort by date, submitter.
- Click into bundle for diff view.
Bundle Diff View
This view will give admins a detailed comparison.
- Side-by-side: User Input vs Resolution.
- Inline entity creation forms.
- Approve / Reject buttons.
- Rejection requires notes.
Implementation Order - Putting it all together.
Here's the order of how we'll implement this feature:
- Autocomplete endpoints - Build search APIs for sets, series, players, teams.
- Resolution preview endpoint - Real-time resolution without submission.
- AddCardPage - Main form with live resolution.
- Navigation integration - Add "Add a Card" to nav.
- Success flow - Confirmation and next steps.
- My Submissions page - User can track their submissions.
- Admin Review UI - Admin can review and approve.
File Structure - Where everything lives.
client/src/
├── pages/
│ ├── AddCard.jsx # Main add card page
│ ├── AddCardScoped.css
│ ├── MySubmissions.jsx # User's submission history
│ └── MySubmissionsScoped.css
│
├── components/
│ ├── addcard/
│ │ ├── EntityAutocomplete.jsx # Reusable autocomplete
│ │ ├── ResolutionStatus.jsx # Live resolution panel
│ │ ├── AddCardForm.jsx # Form container
│ │ └── AddCardSuccess.jsx # Success state
│ │
│ └── collection/
│ └── ProvisionalBadge.jsx # Badge for provisional cards
│
server/routes/
└── v1/
└── search/
└── autocomplete.js # New autocomplete endpoints
That's it, guys! This "Add a Card" feature is going to be amazing, and I hope this overview is helpful.
Let's get adding those cards!