# Task for Hidden San Diego: grouped lodging photo gallery

Implement the lodging listing-page gallery using Wikiup's affiliate listing content API. This document is an implementation handoff, not a claim that the Hidden San Diego application has been changed. The group fields must be released to the target API before enabling the feature; tolerate their absence during rollout.

## Source and permissions

Fetch on your server with the existing email-associated **affiliate** API key:

```sh
curl --fail-with-body --silent --show-error \
  "$WIKIUP_API_ORIGIN/api/travel/listings/$ENCODED_LISTING_ID" \
  -H "Authorization: Bearer $WIKIUP_API_KEY" -H 'Accept: application/json'
```

Set `WIKIUP_API_ORIGIN=https://api-preview.wikiup.app` for preview. Set `ENCODED_LISTING_ID` to the exact stable listing ID returned by search, for example `hotel:<property-id>` or `rental:<property-id>:room:<room-id>`. Encode it once as a path segment: `hotel:PROPERTY_ID` becomes `hotel%3APROPERTY_ID`. No `x-property-id` header is needed. Keep the key server-side. Existing affiliate suspension, blacklist, rate limits and direct-lookup permissions remain in force. Do not request owner/admin gallery endpoints from the partner site.

## Additive response contract

`GET /api/travel/listings/{listingId}` still returns `{ listing: ... }`. The ordered `listing.gallery` and `listing.coverImage` retain all existing image fields and now include `group`. Listing content also includes `galleryGroups`.

Each image in `gallery` and the nullable `coverImage` uses these fields:

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | string | Stable photo ID. |
| `url` | string | Public image URL. |
| `alt` | string | Alternative text. |
| `width, height` | integer | Actual image dimensions in pixels. |
| `variants` | array of objects | Available thumbnails; may be empty. |
| `variants[].url` | string | Thumbnail URL. |
| `variants[].width, variants[].height` | integer | Actual thumbnail dimensions in pixels. |
| `variants[].format` | string | One of avif, webp, jpeg, png. |
| `group` | object or null | Optional photo group; null means ungrouped. |
| `group.id` | string | Opaque grouping key, stable while the normalized label is unchanged. |
| `group.title` | string | Title Case display text supplied by Wikiup. |

`galleryGroups` is an ordered array of objects with `id` and `title` as above, plus `imageIds` (an array of photo IDs).

Illustrative grouping fragment (image URL/dimension/variant fields omitted here only for brevity; this is not a complete API response):

```json
{
  "gallery": [
    { "id": "photo-a", "group": { "id": "group:front%20yard", "title": "Front Yard" } },
    { "id": "photo-b", "group": { "id": "group:bedroom%201", "title": "Bedroom 1" } },
    { "id": "photo-c", "group": null },
    { "id": "photo-d", "group": { "id": "group:front%20yard", "title": "Front Yard" } }
  ],
  "galleryGroups": [
    { "id": "group:front%20yard", "title": "Front Yard", "imageIds": ["photo-a", "photo-d"] },
    { "id": "group:bedroom%201", "title": "Bedroom 1", "imageIds": ["photo-b"] }
  ]
}
```

The full machine-readable contract is `/travel-listings.schema.json` (`PublicImage`, `PhotoGroup`, `GalleryGroup`, and `ContentResponse`).

- One optional arbitrary group per photo. Labels are trimmed, repeated whitespace collapsed, and limited to 80 characters. Case differences do not create separate groups. `front yard`, `Front Yard`, and `FRONT YARD` share one group.
- Display `title` as returned. Do not derive headings from the ID or use CSS alone to change case.
- Group IDs are label-derived, not database record IDs. Renaming a label changes its grouping key. Do not parse the ID, put it into asset URLs, or persist it as a permanent category identity.
- Menu order follows the first photo in each group. `imageIds` follows the existing gallery order. Empty groups are omitted.
- Ungrouped photos have `group: null` and remain in `gallery`; no synthetic group is created by the API. Legacy responses can omit these additive fields: use `galleryGroups ?? []` and treat absent `image.group` as null.
- `coverImage` stays the first photo in the existing gallery order. A cover/hero URL duplicated in the gallery appears once and inherits the first explicitly assigned group for that URL.
- Hotels expose their existing public property/hero gallery. Rentals expose their own room or room-type gallery, falling back to property photos when empty. No automatic room-name grouping or collection of every hotel's room gallery is introduced. Private check-in photos are never included.
- Group changes do not regenerate thumbnails or change image URLs, dimensions or bytes. Photo replacement continues to generate new versioned URLs.

## Implement the listing-page interaction

1. Fetch listing content from your server with `cache: 'no-store'`. Keep the existing fresh direct-availability request separate. Never cache prices, counts or booking URLs, including the existing 20-second completed availability cache.
2. Start the gallery menu with **All Photos**, followed by `galleryGroups`, using each returned `title`. All Photos shows the full ordered `gallery`, including ungrouped images. Hide the group menu when no groups exist; still show the gallery.
3. On group selection, resolve `imageIds` against `gallery` in their supplied order. Show one large active photo and a thumbnail strip beneath it. Selecting a thumbnail changes the large photo. Start at that group's first photo unless the current photo belongs to the newly selected group.
4. Use returned `variants` for `srcset`/`sizes`; use small existing variants for thumbnails and appropriately sized variants for the main image. Never invent thumbnail paths or advertise missing sizes. The cover/large-photo image must fill its existing frame (`width: 100%; height: 100%; object-fit: cover; object-position: center`), with a definite frame height or aspect ratio and clipped overflow. Crop excess edges without stretching or exposing matte bands. Use `object-fit: contain` only in a separate expanded full-photo viewer. Preserve original image bytes and API dimensions. The other project's image cache remains independently managed.
5. Use accessible buttons/menu controls with visible selected state, descriptive accessible names and keyboard focus. Thumbnail buttons should identify the photo and expose selection (for example `aria-pressed`). Supply `alt` text as returned. Support touch, keyboard, narrow viewports and your existing themes.
6. If content refresh removes the selected group/photo, fall back to All Photos and the first remaining photo. Do not retain a photo from a different listing when navigation changes. Render empty and failed-image states without stock replacement photos. Honor 429 `Retry-After` and provide retry for content failure.
7. Leave booking links untouched. This feature does not change dates, party, attribution, inventory selection or checkout behavior.

## Wikiup console configuration

Owners can edit **Group (optional)** alongside each public photo's description:

- Property → Listing photos for affiliate property photos. Website slideshow/general galleries remain separate.
- Rooms → room gallery, or room-type gallery for pooled listings.

Use the existing Save action. Existing labels appear as input suggestions. Blank clears the assignment. To rename a group, change its label on the affected photos; there is no separate group entity or new grouping-management screen. Existing property/room-management permissions apply. Affiliates cannot change these labels.

Owner API metadata PATCH contracts (existing authenticated routes; `x-property-id` required):

```json
{ "images": [{ "imageId": "<photo-id>", "group": "front yard" }] }
```

Use the ordered GET/PUT `/api/properties/{id}/listing-photos` contract for affiliate property photos (see [listing photos](/property-listing-photos.md)). The following existing metadata routes manage website/room photos separately: `/api/property-gallery` or `/api/property-hero-gallery`; `/api/room-gallery` also requires `roomId` on every item. `/api/room-types/{id}/gallery` accepts the same imageId/group form. `group` is also accepted on photo creation. Omit it to preserve the existing label, or send null/blank to clear. These are metadata updates only; unrelated captions, ordering and URLs stay intact. Invalid labels return 422; unknown/out-of-property images return 404. A missing schema column returns 503 instead of falsely reporting a saved label.

## Acceptance tests for the consumer

- Mix Front Yard, Bedroom 1, Kitchen, Parking and ungrouped photos; verify menu, order, large photo and thumbnail selection.
- Use equivalent labels with different capitalization/spacing; verify one menu entry.
- Check no groups, no photos, one-photo groups, long labels and mobile/keyboard operation.
- Rename/clear a label in Wikiup and reload content; verify old groups disappear and images stay accessible under All Photos.
- Verify image URLs stay the same on group edits, but change on photo replacement.
- Verify hotel/rental and pooled-listing galleries, affiliate blacklist denial, retry/error handling, and unchanged booking attribution.
- Keep the API key out of browser requests and bundles. Confirm availability is fetched fresh after navigating back from a listing.
