UPDATED: Refactor Gallery: Unified Schema for Multiple Images, Animation, and Optional Links

[Rutjake]

📸 Gallery Backend Refactor: Photo Object V2 Implementation

The gallery backend is being refactored to align with the established patterns of the members and newsApi modules. The core change involves migrating from the legacy relational structure to the new, flat Photo Object V2 collection.

🔍 Reason for Refactor

The current implementation relies on a rigid photo_version collection which introduces unnecessary overhead. By adopting the Photo Object V2 collection:

• Performance is improved: Reduced database joins.
• Maintainability is increased: Data fetching is unified with other core modules.
• Flexibility is enhanced: Native support for multiple images, animations, and external links within a single object.

---

🛑 Developer Instructions

• Create a New Branch: Start your work by creating a new feature branch (e.g., youname/refactor/615-refactor-gallery).
• Ignore Legacy Implementation: Do not attempt to fix or modify the old code directly. Build the new logic alongside it.
• Reference Existing Modules: While you can check the old code for context, the best examples of modern Directus integration are found in the members (Characters) and newsApi (News) modules.

---

🛠️ 1. Directus Schema (Photo Object V2)

We are using the new Photo Object V2 collection, which includes the following fields directly:

• Primary Assets:
  • image (Image/File, Required) – Primary asset.
  • image_2, image_3 (Image/File, Optional)
  • animation (Video/File, Optional) – To be rendered conditionally.
• Content Details:
  • title (String, Optional) – Primary title of the work.
  • author (String, Optional) – Author of the art (if known).
  • description (Textarea, Optional) – Detailed description of the work.
• References & Socials:
  • link, link_2 (URL/String, Optional) – External references, such as social media profiles, portfolio sites, or project-specific links.

---

✅ 2. Technical Implementation Details

API & Data Fetching

• Interface Update: Update the PhotoObject interface to reflect the V2 flat structure. Remove all legacy photo_version types.
• API Service: Refactor galleryApi to fetch data directly from the Photo Object V2 collection. Implement try-catch blocks and FetchBaseQueryError to match the error-handling patterns used in membersApi and newsApi.

Logic & Hook Integration

• Data Mapping: In the useGetDirectusGalleryImages hook, convert asset IDs into full URLs using the ${directusBaseUrl}/assets/${id} pattern.
• Anchor Mapping: Generate a unique anchorId for each item based on the author field (e.g., by sanitizing the name into a URL-safe string).
• Link Handling: Integrate the linkify utility for the link and link_2 fields to ensure external URLs are handled safely and consistently.

UI & Conditional Rendering

• Anchor ID: Assign the generated author-based ID to each gallery item's container in the DOM.
• Auto-Scroll Logic: Implement a useEffect that checks window.location.hash after the Directus data has loaded. If a match is found, the page must automatically scroll to the corresponding author's work using scrollIntoView({ behavior: 'smooth' }).
• Animation Rendering: The animation button or player must use conditional rendering. It should only be rendered if the animation field contains data; otherwise, it must remain hidden.
• Frames Composition: Bundle image, image_2, image_3, and animation into a single frames array for the UI.
• Button Components: "Project" or "More" buttons should only appear if a valid URL exists after being processed by the linkify logic.

---

🏁 Acceptance Criteria

1. Data is successfully fetched from the Photo Object V2 collection.
2. Gallery items have stable id attributes derived from the author field for anchoring.
3. Deep Linking: Arriving at the gallery with an author hash (e.g., /gallery#MattiMeikalainen) triggers an automatic smooth scroll to that item after data load.
4. Animations and additional images render only when data is present (no empty slots or broken buttons).
5. External links are processed via linkify and appear only when valid.
6. The fetching pattern is unified with the members and newsApi modules.
7. Redundant relational fetches for photo_version are removed from the new implementation.

---

📋 Additional Information

If you do not have Directus credentials yet, please ask the team veterans to create an account for you so you can inspect the V2 collection schema.

• 🎨 UI/UX Design: Please check the latest design and layout specifications from Figma before starting the UI implementation.

🔗 Figma

🔗 Directus Documentation

📷 Preview: