Xu_BrowserBookmark/openspec/changes/archive/2026-01-22-add-dnd-sorting/design.md

Design: Persistent ordering + touch-friendly DnD

Database

• Add sort_order integer not null default 0 to bookmarks.
• Add indexes to support ordered listing:
  • (user_id, folder_id, sort_order)

API

• Extend Bookmark DTO/schema with sortOrder.
• Add POST /bookmarks/reorder similar to existing /folders/reorder:
  • Input: { folderId: uuid|null, orderedIds: uuid[] }
  • Validates orderedIds is a permutation of all bookmarks for that user+folder (excluding deleted).
  • Transactionally updates sort_order for each id.

Web UI

• Replace native HTML5 drag/drop with a touch-capable approach.
  • Implementation choice: sortablejs (small, proven, touch-friendly).
  • Bind Sortable to:
    • Folder header list (per parent group) for folder ordering.
    • Each open folder’s bookmark list for bookmark ordering.
• Root group is rendered as a first-class group and can also be reordered.

Compatibility

• If the DB schema lacks ordering columns (fresh/old DB), endpoints should return a clear 409 prompting db:migrate.