# Feature: Photo Carousels

> **Terminology note:** This example uses terms from the underlying semantic data model, such as `PublishedWork` and `Carousel`. This model is not included as another example.

## Summary

A carousel is one visitor-facing PublishedWork containing an intentionally ordered sequence of Photos. It lets the photographer publish related images as one coherent work with one public name, one cover, one localized title, and one localized description.

A carousel is not a Series. A carousel is opened and viewed as a single portfolio entry; a Series curates multiple PublishedWorks and may include both carousels and standalone works.

## Goals

- Publish a related sequence without presenting every contained Photo as a separate gallery entry.
- Preserve one shared artistic title and description for the sequence.
- Preserve Photo-specific representations, capture facts, year, and person-visibility classification.
- Make carousel publications recognizable before they are opened.
- Provide distinct, accessible controls for Photo-level and PublishedWork-level navigation.
- Allow a carousel to participate in Series curation, new-publication highlighting, search discovery, and the same public routing as a standalone work.

## Domain Rules

- A carousel is exactly one PublishedWork of type Carousel.
- It contains an ordered list of Photos and normally contains at least two.
- Its cover Photo is one of its contained Photos and is used in gallery and sharing contexts.
- All contained Photos share the carousel's visitor-facing title and description.
- Each contained Photo retains its own preview/detail images, capture details, year, and person-visibility classification.
- A contained Photo is not also published as a standalone PublishedWork.
- A Photo belongs to at most one carousel in the current product.
- Optional Series membership and New status belong to the carousel PublishedWork, not to each contained Photo.

## Gallery Presentation

A carousel appears once in the gallery, using its cover Photo. Its tile:

- shows the localized carousel title;
- is visibly marked as a carousel;
- communicates the number of Photos visually and in its accessible link name; and
- shows New status when the carousel PublishedWork is highlighted.

Selecting the tile opens the carousel detail page at its first Photo. Contained Photos do not receive separate gallery tiles or visitor routes.

## Detail Presentation

The carousel detail page:

- shows one Photo at a time;
- initially selects the first Photo;
- shows the carousel's shared localized title and description;
- adds the visible Photo's capture year to the title when known;
- shows capture details for the visible Photo;
- shows a Person Notice only when the visible Photo requires one;
- shows a localized position such as `2 of 6`; and
- exposes previous/next carousel-Photo controls.

The shared title and description are not repeated as if they were different content for each Photo, and individual hidden Photo titles are not introduced.

## Two Navigation Scopes

Carousel pages expose two deliberately separate control groups.

### PublishedWork Controls

First, previous, next, and last controls move among PublishedWorks in the global portfolio. They never move only one position within the carousel.

### Carousel-Photo Controls

Previous and next Photo controls move only within the current carousel. They disable at the first and last Photo and never cross into another PublishedWork. A visible position indicator communicates progress through the sequence.

The controls have distinct localized accessible names so a visitor can tell whether an action changes the portfolio entry or the Photo inside it.

## Sequential Keyboard and Swipe Behavior

For Left/Right keyboard navigation and horizontal swipe gestures, the carousel behaves as one continuous segment in the portfolio:

- forward movement advances to the next carousel Photo;
- at the last Photo, further forward movement opens the next PublishedWork;
- backward movement advances to the previous carousel Photo; and
- at the first Photo, further backward movement opens the previous PublishedWork.

Escape returns to the gallery. Gesture recognition remains confined to the image stage and favors vertical scrolling unless the movement is clearly horizontal.

This boundary-crossing behavior applies to keyboard and swipe navigation only. Visible carousel controls remain internal, and visible PublishedWork controls remain work-level.

## Loading Behavior

- Every carousel Photo follows the same preview-first, detail-image loading behavior as a standalone Photo.
- Navigating to another Photo resets the loading and error state for that Photo.
- Adjacent carousel Photos are prepared ahead of use.
- At carousel boundaries, the cover Photo of the adjacent PublishedWork may be prepared to keep continuous navigation responsive.

## Series Behavior

- A carousel may belong to one Series.
- It occupies one position and counts as one PublishedWork in that Series, regardless of its Photo count.
- Its Series membership is shown and linked from the detail page.
- In the Series overview it remains identifiable as a multi-photo work.

## Discovery and Sharing

- The carousel has one stable PublishedWork URL in each language.
- The localized carousel title and description describe the page.
- The cover Photo is the primary social-preview image.
- Search metadata may associate all contained Photos with the carousel page, in carousel order, while keeping the cover first.
- Contained Photos do not create separate PublishedWork sitemap locations.

## Publication Behavior

The publisher must be able to determine:

- the ordered Photo membership;
- the cover Photo;
- the stable public name;
- German and English title and description;
- optional Series membership and Series position;
- whether the carousel is temporarily highlighted as new; and
- person visibility for every contained Photo.

The publication workflow may infer a carousel when two or more Photo asset names share a base followed by a numeric index immediately before their representation suffix. Inferred order is ascending numeric order, the first Photo is the default cover, and the shared base is the default public name. Inference supplies candidates only: publication text, privacy classification, and curation still require review.

## Edge Cases

- A carousel with missing Photo references presents the valid referenced Photos in their curated order; if no Photo resolves, the PublishedWork is unavailable.
- A one-Photo carousel may be technically representable for recovery, but normal publication should use a standalone work or add the missing sequence members.
- Work-level controls and keyboard/swipe boundary crossing disable naturally when the carousel is at the beginning or end of the entire portfolio.
- The year and Person Notice may change while the shared title and description remain constant.

## Acceptance Criteria

- A carousel appears once as a recognizable multi-photo gallery entry with a count.
- Opening it starts at the first Photo and shows one Photo at a time.
- The title and description are shared across the sequence.
- Year, capture details, loading state, and Person Notice follow the visible Photo.
- Internal controls move only within the carousel and disable at its boundaries.
- PublishedWork controls always move between portfolio entries.
- Left/Right and swipe traverse Photos first, then adjacent PublishedWorks at sequence boundaries.
- The current position is localized and announced as text.
- A carousel occupies one Series position and one public route.
- Search and sharing use the carousel text and cover while allowing all contained images in page metadata.
- Contained Photos are not also published as standalone works.

## Out of Scope

- Automatic slideshow playback.
- Per-Photo public titles or descriptions inside a carousel.
- Swipe navigation on the gallery overview.
- One Photo appearing in multiple carousels.
- A carousel containing other carousels or Series.