# FeaturedCollectionStage

> Editorial multi-product stage with active details, responsive rail navigation, and per-product media galleries.

Canonical URL: https://0.0.0.0:3005/islands/commerce/featured-collection-stage

> Present several products on one shared visual stage. Use this for featured
> collections, best sellers, and new-arrival sections that should feel more
> editorial than a conventional card carousel.

## Preview

**Category**: Commerce

## Variants

| Variant | Best for |
|---|---|
| `fullBleed` | Edge-to-edge editorial collection stages |
| `contained` | Rounded or inset sections with centered navigation |
| `minimal` | Restrained apparel and new-arrival rails |
| `gallery` | Products with multiple images or videos and internal media controls |

Variants provide defaults only. Layout, colors, product sizing, media framing,
details, badges, and navigation remain CSS-customizable.

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `productIds` | string[] | - | Shopify Product GIDs resolved at runtime |
| `products` | array | - | Authored product data using the shared `media` array |
| `heading` | string | - | Section heading |
| `collectionLabel` | string | `"Shop all"` | Collection-link label |
| `collectionUrl` | string | - | Collection-link destination |
| `variant` | `"fullBleed" \| "contained" \| "minimal" \| "gallery"` | `"fullBleed"` | Stage preset |
| `activation` | `"hover" \| "click" \| "centered"` | `"hover"` | Active-product selection model |
| `initialIndex` | number | `0` | Initially selected product |
| `loop` | boolean | `true` | Wraps outer product navigation |
| `autoplay` | boolean | `false` | Advances the active product |
| `interval` | number | `5000` | Autoplay interval |
| `mediaBehavior` | `"first" \| "hoverAdvance" \| "autoplay"` | `"first"` | Product-media behavior |
| `showBadges` | boolean | `true` | Shows product badges |
| `showDetails` | boolean | `true` | Shows active-product details |
| `animate` | boolean | `true` | Enables motion |

Provide either `productIds` or `products`. Authored products can override
Shopify imagery and add custom badges, subtitles, links, or mixed media.

## Multi-Media Products

Every product uses the same array contract as
[MediaCarousel](/islands/content/media-carousel). The `gallery` variant adds
per-product arrows, dots, and touch swipe without changing the outer collection
navigation.

```html
<lx-island name="FeaturedCollectionStage">
  <script type="application/json">
    {
      "variant": "gallery",
      "heading": "Shop every angle",
      "products": [
        {
          "id": "mug-1",
          "handle": "spoon-mug",
          "title": "Spoon Mug",
          "price": "$32.00",
          "badge": "3 views",
          "media": [
            { "type": "image", "src": "https://cdn.example.com/front.jpg" },
            { "type": "image", "src": "https://cdn.example.com/side.jpg" },
            {
              "type": "video",
              "poster": "https://cdn.example.com/poster.jpg",
              "sources": [{ "url": "https://cdn.example.com/demo.m3u8" }]
            }
          ]
        }
      ]
    }
  </script>
</lx-island>
```

Only the active video slide mounts the adaptive player. Inactive video items
remain lightweight posters.

## Responsive Rail

The outer arrows move through all product indices even when the viewport has
only two physical scroll positions. Selecting an edge product keeps it visible
without restricting active details to the center products.

Default responsive behavior:

- Desktop: product count controlled by `--lx-featured-item-basis`
- Laptop: four visible products by default
- Tablet: two to three visible products
- Mobile: one product plus a partial next-item preview

## CSS Customization

Important variables:

| Variable | Purpose |
|---|---|
| `--lx-featured-item-basis` | Desktop product width |
| `--lx-featured-laptop-item-basis` | Laptop product width |
| `--lx-featured-tablet-item-basis` | Tablet product width |
| `--lx-featured-mobile-item-basis` | Mobile product width |
| `--lx-featured-product-height` | Stage height |
| `--lx-featured-gap` | Product spacing |
| `--lx-featured-media-fit` | `cover` or `contain` |
| `--lx-featured-media-position` | Media alignment |
| `--lx-featured-details-width` | Active details panel width |
| `--lx-featured-arrow-size` | Outer navigation size |
| `--lx-featured-media-arrow-size` | Per-product gallery arrow size |
| `--lx-featured-radius` | Contained-stage radius |

Stable parts include `root`, `header`, `heading`, `collection-link`, `viewport`,
`track`, `product`, `badge`, `media`, `details`, `title`, `subtitle`, `price`,
`navigation`, `previous`, and `next`.

## Related Islands

- [ProductCarousel](/islands/commerce/product-carousel) - Conventional product-card carousel
- [ProductGallery](/islands/commerce/product-gallery) - Single-product PDP gallery
- [MediaCarousel](/islands/content/media-carousel) - Shared media primitive contract