Cross-Malet Product Comparison & Quick Actions

Two related Buyer-facing features that enhance product discovery across the platform:

1. Compare Deck — Pin up to 4 products from any Malet and evaluate them side-by-side in a unified modal.
2. Card Quick Menu — A universal kebab (⋮) dropdown on every product and service card with contextual actions.

Both features are entirely client-side — no backend changes required.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Root Layout                              │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ ComparisonTray (fixed bottom, persistent across routes)  │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ ComparisonModal (overlay, opens from tray)               │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Every Card Surface:                                            │
│  ├─ ProductCard (catalog)         → CardQuickMenu               │
│  ├─ ServiceCard (catalog)         → CardQuickMenu               │
│  ├─ LobbyTrending (mosaic)        → CardQuickMenu               │
│  ├─ Lobby inline cards            → CardQuickMenu               │
│  ├─ FeaturedProducts (widget)     → CardQuickMenu               │
│  ├─ SearchResultCard              → CardQuickMenu               │
│  └─ Item Detail Page              → CompareButton (expanded)    │
└─────────────────────────────────────────────────────────────────┘
         │
         ▼
┌────────────────────────────────────┐
│ comparisonStore (Svelte 5 Runes)   │
│ ─ items: ComparisonProduct[]       │
│ ─ isOpen: boolean                  │
│ ─ canAdd / canCompare (derived)    │
│ ─ localStorage persistence         │
└────────────────────────────────────┘
         │
         ▼
┌────────────────────────────────────┐
│ comparisonUtils.ts                 │
│ ─ buildComparisonRows()            │
│ ─ formatComparisonValue()          │
│ ─ getComparisonDiffFlag()          │
│ ─ extractComparisonProduct()       │
│ ─ ComparisonProductSchema (Zod)    │
└────────────────────────────────────┘

No backend changes required. The comparison operates entirely on data already loaded by existing GET_ITEM_DETAILS, GET_MALET_PRODUCTS, and GET_PRODUCTS queries.

Card Quick Menu (`CardQuickMenu`)

A universal kebab (⋮) dropdown that appears on hover over any product or service card. Provides contextual quick actions without navigating away from the current page.

Menu Items

Technical Details

• Portal rendering: The dropdown is teleported to document.body via a Svelte use:portal action. This is necessary because product cards use CSS transform on hover (for the lift effect), which creates a new containing block that breaks position: fixed inside overflow: hidden containers.
• Event isolation: All click events within the menu are stopped from propagating to parent <a> tags, preventing accidental navigation.
• Keyboard support: Escape key closes the dropdown.
• Click-outside dismissal: Global click listener with a 10ms delay to prevent the open-click from immediately closing the menu.

Integration Points

The CardQuickMenu is integrated into every card surface across the platform:

Props

Comparison Store API

`comparisonStore` (Singleton)

Persistence: Items are synced to localStorage('ngwenya_compare_items') via a $effect.root() watcher. The $effect.root() wrapper is required because the store is a module-level singleton instantiated outside any component's reactive context.

Visual Components

`ComparisonTray`

Fixed-bottom bar showing current comparison set. Visible when ≥1 product is pinned.

• Mini product thumbnails with Malet handle
• Empty slot placeholders (dashed borders)
• "Clear All" button
• "Compare Now" CTA (disabled with <2 items)
• Auto-hides when comparison set is empty

`ComparisonModal`

Full-screen overlay with side-by-side comparison table.

• Header: Product image, name, price, Malet link per column
• Body: Attribute rows (Price, Compare-At, Status, SKU, Weight, Dimensions, Inventory, Tags, Variants). Rows with differing values are highlighted.
• Footer: "View Details" link per product
• Escape key and backdrop click close the modal

Utility Functions

`buildComparisonRows(products): ComparisonRow[]`

Generates normalized attribute rows from an array of products. Omits rows where all products have null values.

`formatComparisonValue(value, key): string`

Formats raw product data for display: cents → currency, dimensions → L×W×H unit, arrays → comma-separated, booleans → Yes/No, nulls → —.

`getComparisonDiffFlag(row): boolean`

Returns true if any non-null values in the row differ — used to highlight divergent attributes.

`extractComparisonProduct(product, maletHandle, maletName): ComparisonProduct`

Bridge function that extracts a ComparisonProduct from a raw ProductNode (as returned by GraphQL queries) plus Malet context.

`ComparisonProductSchema` (Zod)

Validates data before it enters the comparison store. Required fields: id, name, maletHandle, maletName, basePrice.

File Reference

Design Decisions

1. Client-side only: No new GraphQL queries or mutations. Products loaded by existing queries are reused.
2. Products only: Services excluded from comparison — their attributes (duration, booking, location) don't suit tabular comparison. Services still get the quick menu for future "Add to List".
3. Max 4 items: Standard comparison limit. Beyond 4, the comparison table becomes unwieldy on mobile.
4. localStorage: Simple, session-scoped persistence. No server-side state needed.
5. Diff highlighting: Rows where products differ get a subtle accent background to draw the Buyer's eye to distinguishing attributes.
6. Portal rendering: The dropdown is teleported to document.body because card wrappers use overflow: hidden + transform on hover, which breaks position: fixed positioning.

Related

• Storefront Sections — Layout widgets where product cards with quick menus render
• Tech & Electronics — Vertical-specific SPEC_COMPARISON widget
• Community Features — Future integration point for social lists/wishlists