feat: drag-and-drop subscription prioritization

Author: raizo07

backend/scripts/009_add_subscription_priority_order.sql

@@ -0,0 +1,6 @@
+-- Personal subscription priority order (drag-and-drop reordering)
+ALTER TABLE public.user_preferences
+ADD COLUMN IF NOT EXISTS subscription_priority_order uuid[] NOT NULL DEFAULT '{}';
+
+COMMENT ON COLUMN public.user_preferences.subscription_priority_order IS
+  'Ordered subscription IDs reflecting the user''s personal priority ranking';

backend/src/schemas/user-preferences.ts

@@ -37,6 +37,10 @@ export const userPreferencesUpdateSchema = z.object({
     .optional(),
   privacy_mode_enabled: z.boolean().optional(),
   encryption_key: z.string().optional(),
+  subscription_priority_order: z
+    .array(z.string().uuid('Each subscription ID must be a valid UUID'))
+    .max(500, 'Maximum 500 subscriptions in priority order')
+    .optional(),
 });
 
 // ─── Quiet Hours Schema ─────────────────────────────────────────────────────

backend/src/services/user-preference-service.ts

@@ -29,6 +29,7 @@ export class UserPreferenceService {
         calendar_export_reminders: true,
         preferred_gift_card_provider: 'atomic_wallet',
         privacy_mode_enabled: false,
+        subscription_priority_order: [],
     };
 
     /**

backend/src/types/reminder.ts

@@ -134,6 +134,8 @@ export interface UserPreferences {
   preferred_gift_card_provider: string;
   privacy_mode_enabled: boolean;
   encryption_key?: string;
+  /** Subscription IDs in personal priority order (highest first). */
+  subscription_priority_order: string[];
   /** ISO-8601 UTC string. */
   updated_at: string;
 }

client/components/__tests__/subscription-card.test.tsx

@@ -4,6 +4,14 @@ import { describe, test, it, expect, vi, beforeEach } from 'vitest'
 import { SubscriptionCard } from '../pages/subscriptions'
 import { mockSubscription, mockCancellationGuide } from '@/lib/test-utils'
 
+vi.mock('@/components/providers/user-settings-provider', () => ({
+  useUserSettings: () => ({
+    settings: { currency: 'USD', timezone: 'UTC', locale: 'en-US', privacyModeEnabled: false },
+    updateSettings: vi.fn(),
+    isLoading: false,
+  }),
+}))
+
 describe('SubscriptionCard', () => {
   const defaultProps = {
     subscription: mockSubscription({

client/components/modals/keyboard-help-modal.tsx

@@ -18,6 +18,14 @@ const SHORTCUT_GROUPS: { heading: string; shortcuts: ShortcutRow[] }[] = [
       { keys: ["?"], description: "Show keyboard shortcuts" },
     ],
   },
+  {
+    heading: "Subscription priority",
+    shortcuts: [
+      { keys: ["Drag"], description: "Reorder cards by personal priority" },
+      { keys: ["Space"], description: "Pick up / drop focused card (keyboard drag)" },
+      { keys: ["↑", "↓"], description: "Move card while dragging with keyboard" },
+    ],
+  },
   {
     heading: "Filters",
     shortcuts: [

client/components/pages/subscriptions.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import { useState, useEffect, useRef } from "react"
-import { Edit2, Trash2, Mail, Clock, Copy, Lock, Users, Calendar, Check, Download, FileText, Upload, PauseCircle, PlayCircle, AlertTriangle, ShieldAlert, AlertCircle } from "lucide-react"
+import { Edit2, Trash2, Mail, Clock, Copy, Lock, LockOpen, Users, Calendar, Check, Download, FileText, Upload, PauseCircle, PlayCircle, ShieldAlert, AlertCircle } from "lucide-react"
 import { exportAllCSV, exportActiveCSV, exportDateRangeCSV } from "@/lib/csv-export"
 import { downloadSubscriptionPDF } from "@/lib/pdf-report"
 import CSVImportModal from "@/components/modals/csv-import-modal"
@@ -19,6 +19,19 @@ import { useUserSettings } from "@/components/providers/user-settings-provider"
 import { formatCurrency } from "@/lib/currency-utils"
 import { formatDate, getDaysDifference } from "@/lib/timezone-utils"
 import { fetchCalendarToken as getCalendarToken, downloadCalendarExport, getCalendarFeedUrl, updateCalendarPreferences } from "@/lib/api/calendar"
+import { SortableSubscriptionList } from "@/components/subscriptions/sortable-subscription-list"
+import {
+  PriorityBadge,
+  SortableDragHandle,
+  SortableItemShell,
+} from "@/components/subscriptions/subscription-priority-ui"
+import { useSubscriptionPriorityOrder } from "@/hooks/use-subscription-priority-order"
+import {
+  getGlobalPriorityRank,
+  sortByPriorityOrder,
+  type PriorityRank,
+} from "@/lib/subscription-priority-order"
+import type { CSSProperties, ReactNode } from "react"
 
 interface SubscriptionsPageProps {
   subscriptions?: any[]
@@ -66,7 +79,7 @@ export default function SubscriptionsPage({
   const [isSearching, setIsSearching] = useState(false)
   const [advancedFilters, setAdvancedFilters] = useState<FilterState>(EMPTY_FILTERS)
   const [filterEmail, setFilterEmail] = useState("all")
-  const [sortBy, setSortBy] = useState("name")
+  const [sortBy, setSortBy] = useState("priority")
   const [showKeyboardHelp, setShowKeyboardHelp] = useState(false)
   const [showDuplicatesOnly, setShowDuplicatesOnly] = useState(false)
   const [showUnusedOnly, setShowUnusedOnly] = useState(false)
@@ -103,7 +116,7 @@ export default function SubscriptionsPage({
     setShowExportMenu(false)
     setExportingPDF(true)
     try {
-      await downloadSubscriptionPDF(filtered)
+      await downloadSubscriptionPDF(displayed)
     } finally {
       setExportingPDF(false)
     }
@@ -173,6 +186,14 @@ export default function SubscriptionsPage({
     setTimeout(() => setCopied(false), 2000)
   }
 
+  const subscriptionIds = (subscriptions || []).map((sub: any) => sub.id)
+  const {
+    priorityOrder,
+    isLoading: priorityOrderLoading,
+    isSaving: priorityOrderSaving,
+    reorder: reorderPriority,
+  } = useSubscriptionPriorityOrder({ subscriptionIds })
+
   const filtered = (subscriptions || []).filter((sub: any) => {
     const matchesSearch = sub.name.toLowerCase().includes(debouncedSearchTerm.toLowerCase())
     const matchesCategory =
@@ -197,20 +218,23 @@ export default function SubscriptionsPage({
     return matchesSearch && matchesCategory && matchesStatus && matchesEmail && matchesPrice
   })
 
-  if (sortBy === "price-high") {
-    filtered.sort((a, b) => b.price - a.price)
+  let displayed = filtered
+  if (sortBy === "priority") {
+    displayed = sortByPriorityOrder(filtered, priorityOrder)
+  } else if (sortBy === "price-high") {
+    displayed = [...filtered].sort((a, b) => b.price - a.price)
   } else if (sortBy === "price-low") {
-    filtered.sort((a, b) => a.price - b.price)
+    displayed = [...filtered].sort((a, b) => a.price - b.price)
   } else if (sortBy === "renewal") {
-    filtered.sort((a, b) => a.renewsIn - b.renewsIn)
+    displayed = [...filtered].sort((a, b) => a.renewsIn - b.renewsIn)
   } else {
-    filtered.sort((a, b) => a.name.localeCompare(b.name))
+    displayed = [...filtered].sort((a, b) => a.name.localeCompare(b.name))
   }
 
-  const totalCost = filtered.reduce((sum: number, sub: any) => sum + sub.price, 0)
+  const totalCost = displayed.reduce((sum: number, sub: any) => sum + sub.price, 0)
 
   const hasNoSubscriptions = !subscriptions || subscriptions.length === 0
-  const hasNoResults = filtered.length === 0 && subscriptions && subscriptions.length > 0
+  const hasNoResults = displayed.length === 0 && subscriptions && subscriptions.length > 0
 
   // Active trials sorted by urgency (soonest expiry first)
   const activeTrials = (subscriptions || [])
@@ -232,7 +256,40 @@ export default function SubscriptionsPage({
     )
   }
 
-  const shouldVirtualize = filtered.length > 100
+  const shouldVirtualize = displayed.length > 100 && sortBy !== "priority"
+  const isPrioritySort = sortBy === "priority"
+  const filteredIds = displayed.map((sub: any) => sub.id)
+
+  const renderSubscriptionCard = (sub: any, options?: { priorityRank?: PriorityRank; dragHandle?: ReactNode; shellStyle?: CSSProperties; shellRef?: (node: HTMLElement | null) => void; isDragging?: boolean }) => (
+    <ErrorBoundary
+      fallback={<BrokenCardPlaceholder name={sub?.name} darkMode={darkMode} />}
+    >
+      <div
+        ref={options?.shellRef}
+        style={options?.shellStyle}
+        className={`transition-shadow duration-200 ${options?.isDragging ? "shadow-xl ring-2 ring-[#FFD166]/40 rounded-xl" : ""}`}
+      >
+        <SubscriptionCard
+          subscription={sub}
+          onDelete={onDelete}
+          onManage={onManage}
+          selectedSubscriptions={selectedSubscriptions}
+          onToggleSelect={onToggleSelect}
+          darkMode={darkMode}
+          isDuplicate={duplicates.some((dup: any) => dup.subscriptions.some((s: any) => s.id === sub.id))}
+          unusedInfo={unusedSubscriptions.find((unused: any) => unused.id === sub.id)}
+          onCancel={(s) => setSelectedSubForCancel(s)}
+          guide={guides.find((g) => g.service_name.toLowerCase() === sub.name.toLowerCase())}
+          onPause={onPause}
+          onResume={onResume}
+          onCancelTrial={onCancelTrial}
+          onConvertTrial={onConvertTrial}
+          priorityRank={options?.priorityRank}
+          dragHandle={options?.dragHandle}
+        />
+      </div>
+    </ErrorBoundary>
+  )
 
   return (
     <div>
@@ -344,7 +401,7 @@ export default function SubscriptionsPage({
                 CSV
               </p>
               <button
-                onClick={() => { exportAllCSV(filtered); setShowExportMenu(false) }}
+                onClick={() => { exportAllCSV(displayed); setShowExportMenu(false) }}
                 className={`w-full flex items-center gap-2 px-3 py-2 text-sm text-left transition-colors ${
                   darkMode ? "text-gray-300 hover:bg-[#374151]" : "text-gray-700 hover:bg-gray-50"
                 }`}
@@ -473,6 +530,7 @@ export default function SubscriptionsPage({
               : "bg-white border-gray-300 text-gray-900 focus:ring-black"
           }`}
         >
+          <option value="priority">Personal Priority</option>
           <option value="name">Sort by Name</option>
           <option value="price-high">Price: High to Low</option>
           <option value="price-low">Price: Low to High</option>
@@ -490,11 +548,20 @@ export default function SubscriptionsPage({
         />
       </div>
 
+      {isPrioritySort && !hasNoResults && (
+        <p className={`mb-3 text-sm ${darkMode ? "text-gray-400" : "text-gray-600"}`}>
+          Drag cards to set your personal priority. Top 3 subscriptions are highlighted.
+          {priorityOrderSaving ? " Saving order…" : null}
+        </p>
+      )}
+
       {/* Live region for search result count */}
       <div role="status" aria-live="polite" aria-atomic="true" className="sr-only">
         {!isSearching && debouncedSearchTerm
-          ? `Showing ${filtered.length} of ${subscriptions.length} subscriptions`
-          : ""}
+          ? `Showing ${displayed.length} of ${subscriptions.length} subscriptions`
+          : isPrioritySort && priorityOrderSaving
+            ? "Saving subscription priority order"
+            : ""}
       </div>
 
       {/* Active Trials Section */}
@@ -555,58 +622,42 @@ export default function SubscriptionsPage({
         <>
           {shouldVirtualize ? (
             <VirtualizedList
-              items={filtered}
+              items={displayed}
               itemHeight={80}
               containerHeight={600}
-              renderItem={(sub: any, index: number) => (
-                <ErrorBoundary 
-                  fallback={<BrokenCardPlaceholder name={sub?.name} darkMode={darkMode} />}
-                >
-                  <SubscriptionCard
-                    key={sub.id}
-                    subscription={sub}
-                    onDelete={onDelete}
-                    onManage={onManage}
-                    selectedSubscriptions={selectedSubscriptions}
-                    onToggleSelect={onToggleSelect}
-                    darkMode={darkMode}
-                    isDuplicate={duplicates.some((dup: any) => dup.subscriptions.some((s: any) => s.id === sub.id))}
-                    unusedInfo={unusedSubscriptions.find((unused: any) => unused.id === sub.id)}
-                    onCancel={(s) => setSelectedSubForCancel(s)}
-                    guide={guides.find((g) => g.service_name.toLowerCase() === sub.name.toLowerCase())}
-                    onPause={onPause}
-                    onResume={onResume}
-                    onCancelTrial={onCancelTrial}
-                    onConvertTrial={onConvertTrial}
-                  />
-                </ErrorBoundary>
+              renderItem={(sub: any) => renderSubscriptionCard(sub)}
+            />
+          ) : isPrioritySort && !priorityOrderLoading ? (
+            <SortableSubscriptionList
+              items={displayed}
+              darkMode={darkMode}
+              onReorder={(fromIndex, toIndex) =>
+                reorderPriority(fromIndex, toIndex, filteredIds)
+              }
+              renderItem={(sub: any) => (
+                <SortableItemShell id={sub.id}>
+                  {({ setNodeRef, style, isDragging, attributes, listeners }) =>
+                    renderSubscriptionCard(sub, {
+                      priorityRank: getGlobalPriorityRank(sub.id, priorityOrder),
+                      dragHandle: (
+                        <SortableDragHandle
+                          attributes={attributes}
+                          listeners={listeners}
+                          darkMode={darkMode}
+                          label={`Drag to reorder ${sub.name}`}
+                        />
+                      ),
+                      shellRef: setNodeRef,
+                      shellStyle: style,
+                      isDragging,
+                    })
+                  }
+                </SortableItemShell>
               )}
             />
           ) : (
             <div className="space-y-3">
-              {filtered.map((sub: any) => (
-                <ErrorBoundary 
-                  key={sub.id}
-                  fallback={<BrokenCardPlaceholder name={sub?.name} darkMode={darkMode} />}
-                >
-                  <SubscriptionCard
-                    subscription={sub}
-                    onDelete={onDelete}
-                    onManage={onManage}
-                    selectedSubscriptions={selectedSubscriptions}
-                    onToggleSelect={onToggleSelect}
-                    darkMode={darkMode}
-                    isDuplicate={duplicates.some((dup: any) => dup.subscriptions.some((s: any) => s.id === sub.id))}
-                    unusedInfo={unusedSubscriptions.find((unused: any) => unused.id === sub.id)}
-                    onCancel={(s) => setSelectedSubForCancel(s)}
-                    guide={guides.find((g) => g.service_name.toLowerCase() === sub.name.toLowerCase())}
-                    onPause={onPause}
-                    onResume={onResume}
-                    onCancelTrial={onCancelTrial}
-                    onConvertTrial={onConvertTrial}
-                  />
-                </ErrorBoundary>
-              ))}
+              {displayed.map((sub: any) => renderSubscriptionCard(sub))}
             </div>
           )}
         </>
@@ -739,6 +790,8 @@ interface SubscriptionCardProps {
   onResume?: (subscription: any) => void
   onCancelTrial?: (id: string) => void
   onConvertTrial?: (id: string) => void
+  priorityRank?: PriorityRank
+  dragHandle?: ReactNode
 }
 
 export function SubscriptionCard({
@@ -756,7 +809,11 @@ export function SubscriptionCard({
   onResume,
   onCancelTrial,
   onConvertTrial,
+  priorityRank,
+  dragHandle,
 }: SubscriptionCardProps) {
+  const { settings } = useUserSettings()
+  const currency = settings.currency
   const isPaused = sub.status === "paused"
 
   const statusLabel =
@@ -789,6 +846,7 @@ export function SubscriptionCard({
       aria-label={`${sub.name}, ${sub.category}, $${sub.price}/month, ${statusLabel}${isDuplicate ? ", duplicate" : ""}${unusedInfo ? ", unused" : ""}`}
     >
       <div className="flex items-center gap-4 flex-1">
+        {dragHandle}
         {selectedSubscriptions && onToggleSelect && (
           <input
             type="checkbox"
@@ -808,6 +866,7 @@ export function SubscriptionCard({
         <div className="flex-1">
           <div className="flex items-center gap-2">
             <h4 className={`font-semibold ${darkMode ? "text-white" : "text-gray-900"}`}>{sub.name}</h4>
+            {priorityRank && <PriorityBadge rank={priorityRank} darkMode={darkMode} />}
             <div
               className="flex items-center gap-1 text-xs text-gray-500"
               title={