@vtex/faststore 0.0.1

package/dist/docs/product-gallery.md

@@ -0,0 +1,409 @@
+# ProductGallery
+
+**Category:** commerce
+**Purpose:** Product image/video gallery for PDPs. Fetches media from the active product and delegates rendering to the Gallery primitives. Supports thumbnails, fullscreen, zoom, and slider navigation.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A ProductGallery block is present when you see:
+
+- A **large main image or video** of the product — the focal visual element.
+- A **thumbnail strip** (small clickable images below or beside the main image) showing alternate views.
+- A **"+N" overflow badge** on the last thumbnail, indicating more images than are visible.
+- **Previous/Next arrows** for navigating media.
+- A **fullscreen trigger** (zoom icon, click-to-expand, or thumbnail overflow badge).
+
+Presence of any of the above signals `ProductGalleryRoot`. The image is the source of truth for which sub-components to include.
+
+---
+
+## When to use
+
+- PDP media block — the canonical use.
+
+## When NOT to use
+
+- Non-PDP contexts without a `productBySlug` query (use `GalleryRoot` directly with a `media` prop).
+- Static image display unrelated to a product — use a plain `<img>` via a layout component.
+- Product shelf / PLP cards — use a shelf-specific image component.
+
+---
+
+## Composition
+
+`ProductGalleryRoot` is the only entry point on PDPs. It wraps `GalleryRoot` internally and injects the product media. All Gallery sub-components must be descendants of it.
+
+Child order reflects visual order — place sub-components in the same sequence they appear in the image.
+
+### Interaction patterns
+
+The gallery supports two distinct interaction modes, set by props on `ProductGalleryRoot`. Pick one up front:
+
+- **Hover-to-preview + click-to-fullscreen** — `selectOnHover` + `thumbnailOpensFullscreen`. Hovering a thumbnail swaps the main media (no click), and clicking a thumbnail opens the fullscreen overlay. Common on marketplaces (e.g. Americanas-style).
+- **Click-to-select (default)** — neither prop set. Clicking a thumbnail selects it in place; fullscreen, if present, is opened by `GalleryOverflowCount` or by `clickOpensFullscreen` on `GalleryMainMedia`.
+
+These are independent toggles; the two named modes are the combinations agents should reach for, but each prop can be set on its own.
+
+### Canonical PDP layout
+
+```
+ProductGalleryRoot
+├── GalleryMainMedia               ← large main image/video
+└── GalleryThumbnails              ← thumbnail strip
+    ├── GalleryThumbnail           ← one per media item
+    └── GalleryOverflowCount       ← "+N" badge on last slot (optional)
+```
+
+### With fullscreen
+
+```
+ProductGalleryRoot
+├── GalleryMainMedia
+├── GalleryThumbnails
+│   ├── GalleryThumbnail
+│   └── GalleryOverflowCount
+└── GalleryFullscreen              ← modal overlay
+    ├── GalleryFullscreenTitle     ← sr-only a11y title (required)
+    ├── GalleryFullscreenClose     ← close button
+    ├── GalleryPrevious            ← previous arrow
+    ├── GalleryMainMedia           ← reused inside fullscreen
+    ├── GalleryNext                ← next arrow
+    └── GalleryThumbnails          ← optional thumbnail strip in fullscreen
+        └── GalleryThumbnail
+```
+
+### With zoom (hover magnification)
+
+Replace `GalleryMainMedia` with `GalleryZoom` wrapping it:
+
+```
+ProductGalleryRoot
+├── GalleryZoom
+│   ├── GalleryMainMedia
+│   └── GalleryZoomLens
+├── GalleryZoomResult              ← place as sibling of GalleryZoom
+└── GalleryThumbnails
+    └── GalleryThumbnail
+```
+
+### With thumbnail slider and width alignment
+
+When the thumbnail strip (with or without navigation arrows) visually spans the same width as the main image, wrap the entire thumbnail row in a `Container`. This keeps the strip and the arrows constrained to the same horizontal bound as `GalleryMainMedia`, regardless of how many thumbnails are visible.
+
+```
+ProductGalleryRoot
+├── GalleryMainMedia
+└── Container                          ← thumbnail row wrapper, same width as main image
+    ├── GalleryThumbnailsPrevious      ← sibling of GalleryThumbnails, not a child
+    ├── GalleryThumbnails (slider=true, maxVisible=N)
+    │   └── GalleryThumbnail
+    └── GalleryThumbnailsNext          ← sibling of GalleryThumbnails, not a child
+```
+
+Without navigation arrows — the `Container` still aligns the strip to the main image width:
+
+```
+ProductGalleryRoot
+├── GalleryMainMedia
+└── Container
+    └── GalleryThumbnails
+        ├── GalleryThumbnail
+        └── GalleryOverflowCount
+```
+
+The visual signal for this pattern: in the image, the left edge of the first thumbnail (or the left arrow) and the right edge of the last thumbnail (or the right arrow) align with the edges of the main image. When you see that alignment, add the `Container` wrapper.
+
+---
+
+## Components
+
+### ProductGalleryRoot
+
+Entry point. Reads product media via GraphQL fragment and passes it to GalleryRoot.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `defaultIndex` | number | `0` | Initially selected media index |
+| `selectOnHover` | boolean | `false` | Hovering a thumbnail selects it without clicking |
+| `thumbnailOpensFullscreen` | boolean | `false` | Clicking any thumbnail opens fullscreen instead of selecting |
+| `selectedVariantId` | string | — | When set, lazy-fetches that variant's images and videos via the storefront API and shows them instead of the product-level media. On fetch failure or null payload, silently falls back to the product-level media. |
+
+**Data:** declares `fragment ProductGalleryData on Query`. Fetches up to 20 product-level media items. When `selectedVariantId` is set, also runs `VariantGalleryQuery` to fetch variant-specific images and videos.
+
+---
+
+### GalleryMainMedia
+
+Renders the currently selected media item — `<img>` for images, `<video>` for videos. Supports swipe gestures (50 px threshold) to navigate.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `objectFit` | `contain\|cover\|fill\|none` | `contain` | CSS object-fit for the media element |
+| `aspectRatio` | string | — | A CSS `aspect-ratio` value — width and height separated by a space-padded slash. Use `'1 / 1'`, `'4 / 3'`, `'16 / 9'`. Write the spaces (`'16 / 9'`, not `'16/9'`). |
+| `videoAutoPlay` | boolean | `false` | |
+| `videoControls` | boolean | `true` | |
+| `clickOpensFullscreen` | boolean | `false` | Click (not swipe) opens the fullscreen overlay |
+
+Must be inside `ProductGalleryRoot` (or `GalleryZoom` which must itself be inside Root).
+
+---
+
+### GalleryThumbnails
+
+Iterates media items and renders its children once per item. Acts as the data provider for `GalleryThumbnail` and `GalleryOverflowCount`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `maxVisible` | number | — | Cap on visible thumbnails; last slot becomes overflow |
+| `slider` | boolean | `false` | Enable windowed slider mode (needs `GalleryThumbnailsPrevious`/`Next`) |
+| `animated` | boolean | `false` | Smooth scroll animation (requires `slider=true`) |
+| `direction` | `horizontal\|vertical` | `horizontal` | Scroll axis — match to flex layout |
+| `hideWhenSingle` | boolean | `true` | Hides the strip when `media.length <= 1`. Set `false` to force render even on single-image or empty galleries. |
+
+Must be inside `ProductGalleryRoot`.
+
+#### Layout combinations
+
+The thumbnail strip is composed from three independent axes — **placement** (below vs. side), **scroll mode** (static vs. carousel), and **overflow** (plain strip vs. `+N` badge). All combinations below are already composable; this table is a discoverability aid, not new behavior.
+
+| Goal | Placement | Scroll mode | Overflow | Props |
+|---|---|---|---|---|
+| Below, full strip | below | static | none | `direction="horizontal"` (default) + flex-col parent |
+| Below, carousel | below | carousel | none | `direction="horizontal"` + `slider` + `animated` + `GalleryThumbnailsPrevious`/`Next` |
+| Below, +N badge | below | static | `+N` | `maxVisible={N}` + `GalleryOverflowCount` |
+| Side, full strip | side | static | none | `direction="vertical"` + flex-row parent |
+| Side, carousel | side | carousel | none | `direction="vertical"` + `slider` + `animated` + `GalleryThumbnailsPrevious`/`Next` |
+
+Notes: `direction` sets the scroll axis — match it to the parent flex direction (horizontal strip ⇒ `flex-row` parent that itself sits in a `flex-col` root; vertical strip ⇒ `flex-col` strip in a `flex-row` root). Carousel mode needs both `slider` and the `GalleryThumbnailsPrevious`/`Next` siblings; `animated` only adds smooth scrolling. Overflow (`+N`) and carousel are alternative ways to handle more items than fit — use one or the other, not both.
+
+---
+
+### GalleryThumbnail
+
+Thumbnail button for a single media item. Reads from item context — must be a child of `GalleryThumbnails`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `objectFit` | `contain\|cover\|fill\|none` | `contain` | |
+| `aspectRatio` | string | — | Same format as `GalleryMainMedia`: a CSS `aspect-ratio` string with a space-padded slash, e.g. `'1 / 1'`, `'4 / 3'`, `'16 / 9'`. |
+
+Adds `data-fs-gallery-thumbnail-selected="true"` when active. For videos, renders the `previewImageUrl` as thumbnail src.
+
+---
+
+### GalleryOverflowCount
+
+"+N" badge shown when there are more items than `maxVisible`. Only renders on the last thumbnail slot when overflow exists. Clicking opens fullscreen.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `template` | string | `"+{count}"` | `{count}` = number of hidden items |
+| `ariaLabel` | string | `"View all {total} images"` | Applied to the rendered `<button>` so screen readers announce the full action. `{total}` is replaced by the total media count. |
+
+Must be a child of `GalleryThumbnails`, alongside `GalleryThumbnail`.
+
+---
+
+### GalleryFullscreen
+
+Fullscreen overlay (Dialog). Opens via `GalleryOverflowCount`, `clickOpensFullscreen=true` on `GalleryMainMedia`, or `thumbnailOpensFullscreen=true` on Root. No props.
+
+Must be inside `ProductGalleryRoot`. If you omit `GalleryFullscreenTitle`, a default sr-only `"Gallery"` title is rendered automatically so the dialog always has an accessible name.
+
+---
+
+### GalleryFullscreenTitle
+
+Sets the accessible name for the fullscreen dialog. Optional — when absent, `GalleryFullscreen` renders a default sr-only `"Gallery"` title. No props — pass text as children. Add `className="sr-only"` to hide it visually.
+
+Must be inside `GalleryFullscreen`.
+
+---
+
+### GalleryFullscreenClose
+
+Button that closes the fullscreen overlay. Accepts any children (icon, text). No props beyond standard button attributes.
+
+Must be inside `GalleryFullscreen`.
+
+---
+
+### GalleryPrevious / GalleryNext
+
+Navigate to the previous/next media item. By default navigation wraps around (first → last, last → first). Accepts any children (icon, text).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `wrap` | boolean | `true` | When `true`, clicking at a boundary wraps to the other end (carousel behavior). Set `false` to stop at the first/last item (linear, bounded list): at the boundary the button is `disabled` and the click is a no-op. Style the disabled state with the Tailwind `disabled:` variant, e.g. `disabled:opacity-30 disabled:cursor-not-allowed`. |
+
+Use inside `GalleryFullscreen` for fullscreen slider navigation, or inline for carousel arrows in the main view. For a bounded (non-wrapping) gallery, set `wrap={false}` on both.
+
+---
+
+### GalleryMediaCount
+
+Displays current position and total count.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `template` | string | `"{current} / {total}"` | placeholders: `{current}`, `{total}` |
+
+Place anywhere inside `ProductGalleryRoot` — typically inside `GalleryFullscreen` or above `GalleryMainMedia`.
+
+#### Template token vocabulary
+
+Both template-bearing components draw from one shared token vocabulary. Each token has exactly one meaning, and `{total}` means the same thing wherever it appears (including `GalleryOverflowCount.ariaLabel`):
+
+| Token | Meaning | Used by |
+|---|---|---|
+| `{total}` | Total number of media items | `GalleryMediaCount.template`, `GalleryOverflowCount.ariaLabel` |
+| `{current}` | Current 1-based position | `GalleryMediaCount.template` |
+| `{count}` | Number of hidden items (overflow) | `GalleryOverflowCount.template` |
+
+A token only interpolates in the components listed above; elsewhere it is rendered literally. Defaults render exactly as shipped — `GalleryOverflowCount` shows `"+N"` and `GalleryMediaCount` shows `"2 / 10"`.
+
+---
+
+### GalleryZoom / GalleryZoomLens / GalleryZoomResult
+
+Hover zoom for images (not videos). Wrap `GalleryMainMedia` inside `GalleryZoom`. Place `GalleryZoomLens` as a sibling of `GalleryMainMedia` inside `GalleryZoom`. Place `GalleryZoomResult` as a sibling of `GalleryZoom` (side-panel) or absolute inside it (on-image overlay).
+
+Visual configuration lives on the parent `GalleryZoom` — `GalleryZoomLens` and `GalleryZoomResult` have no zoom props of their own (only `className`/`style`). Set `magnification` and `lensSize` on `GalleryZoom`; the lens and result read them from it.
+
+| Component | Key Prop | Default |
+|---|---|---|
+| `GalleryZoom` | `magnification` (number) | `2` |
+| `GalleryZoom` | `lensSize` (number, px) | `150` |
+| `GalleryZoomLens` | — (styling only; config from `GalleryZoom`) | — |
+| `GalleryZoomResult` | — (styling only; config from `GalleryZoom`) | — |
+
+---
+
+### GalleryThumbnailsPrevious / GalleryThumbnailsNext
+
+Slider navigation for the thumbnail strip. Only active when `GalleryThumbnails` has `slider=true`. Place as **siblings** of `GalleryThumbnails`, not as children.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `step` | number | `1` | Items to scroll per click; set to `maxVisible` to jump a full window |
+
+---
+
+## Canonical schema example
+
+Standard PDP gallery — main image + thumbnail strip with overflow:
+
+```json
+{
+  "gallery": {
+    "type": "ProductGalleryRoot",
+    "props": { "defaultIndex": 0, "thumbnailOpensFullscreen": true },
+    "children": ["gallery-main", "gallery-thumbnails"]
+  },
+  "gallery-main": {
+    "type": "GalleryMainMedia",
+    "props": { "objectFit": "contain", "aspectRatio": "1 / 1", "clickOpensFullscreen": true }
+  },
+  "gallery-thumbnails": {
+    "type": "GalleryThumbnails",
+    "props": { "maxVisible": 5 },
+    "children": ["gallery-thumbnail", "gallery-overflow"]
+  },
+  "gallery-thumbnail": {
+    "type": "GalleryThumbnail",
+    "props": { "objectFit": "contain", "aspectRatio": "1 / 1" }
+  },
+  "gallery-overflow": {
+    "type": "GalleryOverflowCount",
+    "props": { "template": "+{count}" }
+  }
+}
+```
+
+Minimal variant — main image only, no thumbnails:
+
+```json
+{
+  "gallery": {
+    "type": "ProductGalleryRoot",
+    "children": ["gallery-main"]
+  },
+  "gallery-main": {
+    "type": "GalleryMainMedia",
+    "props": { "objectFit": "contain", "aspectRatio": "1 / 1" }
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Using `ProductImageGallery`.** That component does not exist. The correct name is `ProductGalleryRoot`.
+- **Using `GalleryRoot` on a PDP.** `GalleryRoot` has no GraphQL fragment — it requires a static `media` prop. On PDPs, always use `ProductGalleryRoot`.
+- **Putting `GalleryThumbnail` directly under `ProductGalleryRoot`.** It must be inside `GalleryThumbnails`, which provides the per-item context.
+- **Putting `GalleryThumbnailsPrevious`/`Next` inside `GalleryThumbnails`.** They are siblings of `GalleryThumbnails`, not children.
+- **Omitting the `Container` wrapper when the thumbnail strip aligns with the main image.** Without a wrapper, the strip and arrows will not share the same horizontal bound as `GalleryMainMedia`. If the image shows the thumbnail row edges aligned with the main image edges, always add a `Container` around the thumbnail row.
+- **Omitting `GalleryFullscreenTitle`.** The fullscreen overlay is a Dialog — it requires an accessible title. Add it with `className="sr-only"` to hide it visually if needed.
+- **Including `GalleryOverflowCount` without `maxVisible` on `GalleryThumbnails`.** Without `maxVisible`, no overflow slot is created and `GalleryOverflowCount` never renders.
+- **Including `GalleryFullscreen` when no fullscreen is visible in the image.** Only add it if the image shows a fullscreen button or zoom icon.
+
+---
+
+## Styling
+
+Fill each element's `style` array with Tailwind classes read off the image. Typical patterns:
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `ProductGalleryRoot` | Stacks the main media over the thumbnails | `flex flex-col gap-[12px] w-full` |
+| `GalleryMainMedia` | Square framed media, contained, light border | `block w-full aspect-square bg-white border border-[#E5E5E5] rounded-[4px] object-contain p-[16px]` |
+| `GalleryThumbnails` | Horizontal row of thumbnails | `flex flex-row items-center gap-[8px] w-full mt-[4px]` |
+| `GalleryThumbnail` | Small square button; mark the selected one via its data attribute | `block w-[64px] h-[64px] bg-white border border-[#E5E5E5] rounded-[4px] object-contain p-[4px] cursor-pointer data-[fs-gallery-thumbnail-selected=true]:border-[#C8102E]` |
+| `GalleryOverflowCount` | "+N" badge matching the thumbnail box | `flex items-center justify-center w-[64px] h-[64px] bg-[#F5F5F5] border border-[#E5E5E5] rounded-[4px] text-[13px] font-medium text-[#1A1A1A]` |
+
+Read the border color, radius, and thumbnail size from the image; use arbitrary values (`w-[64px]`, `border-[#E5E5E5]`) to match it. The selected-thumbnail highlight uses the brand color via the `data-[fs-gallery-thumbnail-selected=true]:` variant.
+
+Styled gallery example:
+
+```json
+{
+  "gallery": {
+    "type": "ProductGalleryRoot",
+    "props": { "defaultIndex": 0, "thumbnailOpensFullscreen": true },
+    "children": ["gallery-main", "gallery-thumbnails"],
+    "style": ["flex", "flex-col", "gap-[12px]", "w-full"]
+  },
+  "gallery-main": {
+    "type": "GalleryMainMedia",
+    "props": { "objectFit": "contain", "aspectRatio": "1 / 1", "clickOpensFullscreen": true },
+    "style": ["block", "w-full", "aspect-square", "bg-white", "border", "border-[#E5E5E5]", "rounded-[4px]", "object-contain", "p-[16px]"]
+  },
+  "gallery-thumbnails": {
+    "type": "GalleryThumbnails",
+    "props": { "maxVisible": 5 },
+    "children": ["gallery-thumbnail", "gallery-overflow"],
+    "style": ["flex", "flex-row", "items-center", "gap-[8px]", "w-full", "mt-[4px]"]
+  },
+  "gallery-thumbnail": {
+    "type": "GalleryThumbnail",
+    "props": { "objectFit": "contain", "aspectRatio": "1 / 1" },
+    "style": ["block", "w-[64px]", "h-[64px]", "bg-white", "border", "border-[#E5E5E5]", "rounded-[4px]", "object-contain", "p-[4px]", "cursor-pointer", "data-[fs-gallery-thumbnail-selected=true]:border-[#C8102E]"]
+  },
+  "gallery-overflow": {
+    "type": "GalleryOverflowCount",
+    "props": { "template": "+{count}" },
+    "style": ["flex", "items-center", "justify-center", "w-[64px]", "h-[64px]", "bg-[#F5F5F5]", "border", "border-[#E5E5E5]", "rounded-[4px]", "text-[13px]", "font-medium", "text-[#1A1A1A]"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[pricing]] — price block, typically a sibling on a PDP.
+- [[product-information]] — title and description block, typically a sibling on a PDP.
+- [[gallery]] — generic gallery without product data; use when media comes from a custom source.