(UX) Files/Images field ordering by drag and drop

[n2ojim]

Scope & Context

We need to introduce drag-and-drop ordering for files and images within a "File/Image" field (or within the attachments/files widget of a record). This is highly critical for industries like Real Estate, e-commerce, or portfolio management, where the specific sequence of images matters (e.g., determining which photo appears first in a property slideshow, thumbnail generation, or gallery ordering on an external website).

Current behavior

Currently, when multiple files or images are uploaded to a record, they are displayed in a static list (usually ordered by upload date or name). There is no way for a user to manually reorder these files through the UI. If a real estate agent wants a specific picture of the living room to be the first one displayed, they cannot easily change its position without deleting and re-uploading files. Furthermore, this specific visual order cannot be retrieved via the API.

Expected behavior

1. Drag-and-Drop Ordering: In the record page (whether in a specific "Images" field or the general Files widget), users should be able to click, hold, and drag files/images to reorder them visually. A drag handle icon (⋮⋮) should be visible on hover to indicate this capability.
2. Visual Feedback: When dragging an image, the UI should show a clear drop indicator (e.g., a blue line or ghost element) to show where the image will be placed.
3. API Exposure: The chosen order must be saved in the database and exposed via the API. When querying a record (e.g., a Property), the array of files/images returned should respect this custom order, or expose a position (integer) property so external applications (like a real estate website slideshow) can render them correctly.
4. Primary Image Designation (Bonus UX): As a related UX enhancement, the first image in the ordered list could automatically be highlighted or badged as the "Cover" or "Primary" image.

Technical inputs

• Database Schema: Add a position (integer) column to the entity managing the attachments (e.g., Attachment or the specific file relation table) to store the custom order.
• Frontend DnD: Implement drag-and-drop functionality in the Files widget / File field component using the existing DnD library (e.g., @dnd-kit).
• Optimistic UI: When a user drops a file in a new position, instantly update the local state for a smooth UI experience.
• Backend Mutation: Trigger a bulk update mutation (e.g., updateAttachmentPositions) that accepts an array of file IDs and their new integer positions to persist the changes in the database.
• API Response: Ensure the GraphQL/REST API queries for fetching records with their related files are automatically sorted by this new position field by default (orderBy: [{ position: "AscNullsLast" }]).