@kolkrabbi/kol-component 0.2.0 → 0.4.0

package/src/organisms/FeaturedCarousel.jsx

@@ -0,0 +1,258 @@
+import { isValidElement, useCallback, useEffect, useState } from 'react'
+import useEmblaCarousel from 'embla-carousel-react'
+import Image from '../molecules/Image.jsx'
+import HlsVideo from '../atoms/HlsVideo.jsx'
+import OverlayGlassPanel from '../atoms/OverlayGlassPanel.jsx'
+
+/**
+ * Per-slide media layer: a `{ src, kind }` descriptor becomes a cover-fit
+ * Image / HlsVideo / inert <video> pinned over the frame
+ * (`.kol-featured-carousel-media` — absolute inset-0 object-cover, CSS in
+ * @kol/theme, out-cascades Image's baked `h-auto`). A ready ReactNode renders
+ * as-is and must position itself (give it that same class). `onEnded` /
+ * `onTimeUpdate` attach to video elements only — they drive the active slide's
+ * auto-advance and the progress bar; images ignore them.
+ */
+function SlideMedia({ media, onEnded, onTimeUpdate }) {
+  if (!media) return null
+  if (isValidElement(media)) return media
+
+  const { src, kind = 'image', poster, srcSet, alt = '' } = media
+
+  if (kind === 'video') {
+    // Non-HLS file (mp4/webm): a plain inert video. HLS manifests and the
+    // poster-only case go through HlsVideo, which owns hls.js attachment and
+    // the non-interactive hardening set. `loop` is dropped once `onEnded` is
+    // wired so the active slide plays once, then advances.
+    if (src && !src.endsWith('.m3u8')) {
+      return (
+        <video
+          src={src}
+          poster={poster}
+          className="kol-featured-carousel-media"
+          style={{ pointerEvents: 'none' }}
+          autoPlay
+          loop={!onEnded}
+          muted
+          playsInline
+          controls={false}
+          onEnded={onEnded}
+          onTimeUpdate={onTimeUpdate}
+        />
+      )
+    }
+    return (
+      <HlsVideo
+        src={src}
+        poster={poster}
+        className="kol-featured-carousel-media"
+        onEnded={onEnded}
+        onTimeUpdate={onTimeUpdate}
+      />
+    )
+  }
+
+  return (
+    <Image
+      src={src}
+      srcSet={srcSet}
+      sizes={srcSet ? '100vw' : undefined}
+      alt={alt}
+      loading="eager"
+      className="kol-featured-carousel-media"
+    />
+  )
+}
+
+/**
+ * FeaturedCarousel — a full-width carousel of featured media: each wide slide
+ * is a fixed-height frame with an image or HLS-video background and a centered
+ * OverlayGlassPanel (title / description / CTA), plus prev/next and optional
+ * autoplay with a progress bar.
+ *
+ * Rebuilt on the DS Carousel *core*: it renders the same embla + `kol-embla`
+ * chrome (`.is-slides` wide-slide mode, `kol-embla-controls` prev/next) rather
+ * than the `Carousel` component, because the autoplay ring needs the embla api
+ * that Carousel encapsulates and Carousel.jsx must not be modified. The
+ * autoplay/progress behavior lives here, wrapped around that core — a timer
+ * for image slides, the video's `ended` event for video slides, and a progress
+ * bar fed by the same clock (rAF for images, `timeupdate` for video).
+ *
+ * Presentational — no copy, no CDN paths, no routes. The monorepo source's
+ * foundry coupling (name-based title size ramp, per-typeface `fontFamily`, the
+ * `'Explore Typeface'` default) is dropped: titles default to a plain KOL type
+ * class and are fully overridable via `renderTitle` / `titleClassName`. The
+ * CTA is a plain anchor styled with the DS button classes plus an `onNavigate`
+ * seam (router-agnostic — call `preventDefault` inside it for SPA nav).
+ *
+ * @param {Array}    items            slides: `{ media: { src, kind: 'image'|'video', poster, srcSet, alt }, title, description, href, ctaLabel, titleClassName }`
+ * @param {string}   sectionLabel     header label (default 'Featured')
+ * @param {string}   ctaLabel         default CTA copy; per-item `ctaLabel` overrides (default 'Learn more')
+ * @param {string}   height           slide-frame height class (default 'h-[440px] md:h-[640px]')
+ * @param {Function} renderTitle      custom title renderer `(item) => ReactNode`; wins over the default
+ * @param {string}   titleClassName   default title class; per-item `titleClassName` overrides
+ * @param {boolean}  showHeader       show the label + `n / total` counter bar (default true)
+ * @param {boolean}  autoPlay         auto-advance: timer for image slides, `ended` for video slides (default false)
+ * @param {number}   autoPlayInterval image-slide timer in ms (default 5000)
+ * @param {Function} onNavigate       `(href, event) => void` CTA click seam for SPA routing
+ * @param {Object}   options          embla options passthrough (default `{ align: 'center', loop: true }`)
+ * @param {string}   className        extra classes on the section
+ */
+export default function FeaturedCarousel({
+  items = [],
+  sectionLabel = 'Featured',
+  ctaLabel = 'Learn more',
+  height = 'h-[440px] md:h-[640px]',
+  renderTitle,
+  titleClassName = '',
+  showHeader = true,
+  autoPlay = false,
+  autoPlayInterval = 5000,
+  onNavigate,
+  options = { align: 'center', loop: true },
+  className = '',
+}) {
+  const [emblaRef, emblaApi] = useEmblaCarousel(options)
+  const [selectedIndex, setSelectedIndex] = useState(0)
+  const [canPrev, setCanPrev] = useState(false)
+  const [canNext, setCanNext] = useState(false)
+  const [paused, setPaused] = useState(false)
+  const [progress, setProgress] = useState(0)
+
+  const onSelect = useCallback((api) => {
+    setSelectedIndex(api.selectedScrollSnap())
+    setCanPrev(api.canScrollPrev())
+    setCanNext(api.canScrollNext())
+  }, [])
+
+  useEffect(() => {
+    if (!emblaApi) return
+    onSelect(emblaApi)
+    emblaApi.on('select', onSelect)
+    emblaApi.on('reInit', onSelect)
+  }, [emblaApi, onSelect])
+
+  const advance = useCallback(() => emblaApi?.scrollNext(), [emblaApi])
+
+  const currentHasVideo = items[selectedIndex]?.media?.kind === 'video'
+
+  // Reset the progress bar whenever the active slide changes.
+  useEffect(() => setProgress(0), [selectedIndex])
+
+  // Image slides: one rAF loop is the source of truth for both the progress
+  // bar and the auto-advance (video slides drive their own via 'ended' /
+  // 'timeupdate', so this bails when the active slide is a video or paused).
+  useEffect(() => {
+    if (!autoPlay || items.length <= 1 || currentHasVideo || paused) return
+    let raf
+    const start = performance.now()
+    const tick = (now) => {
+      const p = Math.min((now - start) / autoPlayInterval, 1)
+      setProgress(p)
+      if (p >= 1) return advance()
+      raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(raf)
+  }, [autoPlay, autoPlayInterval, items.length, selectedIndex, currentHasVideo, paused, advance])
+
+  const handleVideoTime = (e) => {
+    const { currentTime, duration } = e.currentTarget
+    if (duration) setProgress(currentTime / duration)
+  }
+
+  const renderTitleNode = (item) => {
+    if (renderTitle) return renderTitle(item)
+    if (!item.title) return null
+    return (
+      <span className={`kol-sans-display-01 text-emphasis block leading-none ${item.titleClassName || titleClassName}`.trim()}>
+        {item.title}
+      </span>
+    )
+  }
+
+  if (items.length === 0) return null
+
+  const showProgress = autoPlay && items.length > 1
+
+  return (
+    <section
+      className={`kol-featured-carousel w-full ${className}`.trim()}
+      onMouseEnter={autoPlay ? () => setPaused(true) : undefined}
+      onMouseLeave={autoPlay ? () => setPaused(false) : undefined}
+    >
+      {showHeader && (
+        <div className="mb-6 flex items-center gap-4">
+          <span className="kol-label-mono-xs text-auto">{sectionLabel}</span>
+          <span className="kol-mono-12 text-fg-64">{selectedIndex + 1} / {items.length}</span>
+        </div>
+      )}
+
+      <div className="kol-embla is-slides">
+        <div className="relative">
+          {showProgress && (
+            <div className="absolute left-0 right-0 top-0 z-20 h-[2px] bg-fg-08">
+              <div
+                className="h-full origin-left bg-fg-64"
+                style={{ transform: `scaleX(${progress})` }}
+              />
+            </div>
+          )}
+
+          <div className="kol-embla-viewport" ref={emblaRef}>
+            <div className="kol-embla-container">
+              {items.map((item, i) => {
+                const active = i === selectedIndex
+                return (
+                  <div key={i} className="kol-embla-slide">
+                    <div className={`relative overflow-hidden rounded border border-fg-08 bg-surface-secondary ${height}`}>
+                      <SlideMedia
+                        media={item.media}
+                        onEnded={autoPlay && items.length > 1 && active ? advance : undefined}
+                        onTimeUpdate={autoPlay && active ? handleVideoTime : undefined}
+                      />
+                      <div className="relative z-10 flex h-full w-full items-center justify-center p-6">
+                        <OverlayGlassPanel maxWidth="max-w-[600px]">
+                          {renderTitleNode(item)}
+                          {item.description && (
+                            <p className="kol-mono-12 text-auto max-w-[600px]">{item.description}</p>
+                          )}
+                          {item.href && (
+                            <a
+                              href={item.href}
+                              onClick={onNavigate ? (e) => onNavigate(item.href, e) : undefined}
+                              className="kol-btn kol-btn-primary kol-btn-sm kol-mono-12"
+                            >
+                              {item.ctaLabel || ctaLabel}
+                            </a>
+                          )}
+                        </OverlayGlassPanel>
+                      </div>
+                    </div>
+                  </div>
+                )
+              })}
+            </div>
+          </div>
+        </div>
+
+        <div className="kol-embla-controls">
+          <button
+            type="button"
+            className="kol-embla-btn border border-fg-16 hover:border-fg-32 text-auto"
+            aria-label="Previous"
+            onClick={() => emblaApi?.scrollPrev()}
+            disabled={!canPrev}
+          >‹</button>
+          <button
+            type="button"
+            className="kol-embla-btn border border-fg-16 hover:border-fg-32 text-auto"
+            aria-label="Next"
+            onClick={() => emblaApi?.scrollNext()}
+            disabled={!canNext}
+          >›</button>
+        </div>
+      </div>
+    </section>
+  )
+}

package/src/organisms/FeaturesCardSection.jsx

@@ -0,0 +1,90 @@
+import CardFeatureItem from '../molecules/CardFeatureItem.jsx'
+
+/**
+ * FeaturesCardSection — the "N-up feature cards" band: an optional two-part
+ * header (heading + mono lede) over a responsive row of CardFeatureItem
+ * cards, capped by an optional centered CTA row. Cards stack column-wise
+ * below `md` and become a fixed-height row at `md`+; swap
+ * `cardsWrapperClassName` for a grid to change the layout.
+ *
+ * Fully prop-driven — no default copy, images, or routes live here; every
+ * block is presence-gated (header on `headerLabel`/`headerDescription`,
+ * cards on `features.length`, CTA row on `ctas`), so omitted slots emit no
+ * empty nodes. `ctas` is conventionally a row of KOL Buttons (composition
+ * dependency — nothing is imported here). Card links are plain anchors;
+ * pass `onNavigate` to intercept same-tab navigations in an SPA.
+ *
+ * Header, lede, and card text render exactly as authored — no casing
+ * transforms; author strings in their final case at the call site.
+ *
+ * @param {{title, icon, visual, description, href, backgroundColor, imageAspectRatio}[]} features
+ *                                          cards rendered as CardFeatureItem molecules
+ * @param {ReactNode} headerLabel           heading (kol-sans-heading-03)
+ * @param {ReactNode} headerDescription     mono lede under the heading
+ * @param {ReactNode} ctas                  centered CTA row (a row of Buttons, authored by the caller)
+ * @param {Function}  onNavigate            (event, feature) => void — same-tab card-link seam (SPA intercept)
+ * @param {string}    sectionClassName      extra classes on the <section>
+ * @param {string}    wrapperClassName      outer column container
+ * @param {string}    cardsWrapperClassName card row (default) or grid container
+ * @param {string}    ctasClassName         CTA row padding
+ * @param {string}    headerClassName       header container
+ * @param {string}    headerTextWidthClass  lede measure
+ */
+export default function FeaturesCardSection({
+  features = [],
+  headerLabel,
+  headerDescription,
+  ctas,
+  onNavigate,
+  sectionClassName = '',
+  wrapperClassName = 'w-full flex flex-col gap-8 md:gap-10 max-w-[1400px] mx-auto',
+  cardsWrapperClassName = 'self-stretch inline-flex flex-col md:flex-row md:h-72 justify-start items-center gap-6',
+  ctasClassName = 'pt-10 pb-24',
+  headerClassName = 'w-full pt-[224px]',
+  headerTextWidthClass = 'w-full md:w-[30%]',
+}) {
+  return (
+    <section className={`w-full ${sectionClassName}`.trim()}>
+      <div className={wrapperClassName}>
+        {(headerLabel || headerDescription) && (
+          <div className={headerClassName}>
+            {headerLabel && (
+              <div className="flex items-center h-8">
+                <p className="kol-sans-heading-03">{headerLabel}</p>
+              </div>
+            )}
+            {headerDescription && (
+              <p className={`kol-mono-14 text-fg-64 mt-3 ${headerTextWidthClass}`.trim()}>
+                {headerDescription}
+              </p>
+            )}
+          </div>
+        )}
+
+        {features.length > 0 && (
+          <div className={cardsWrapperClassName}>
+            {features.map((feature, index) => (
+              <CardFeatureItem
+                key={index}
+                title={feature.title}
+                icon={feature.icon}
+                visual={feature.visual}
+                description={feature.description}
+                href={feature.href}
+                backgroundColor={feature.backgroundColor}
+                imageAspectRatio={feature.imageAspectRatio}
+                onNavigate={onNavigate ? (event) => onNavigate(event, feature) : undefined}
+              />
+            ))}
+          </div>
+        )}
+
+        {ctas && (
+          <div className={`w-full flex flex-wrap items-center justify-center gap-4 ${ctasClassName}`.trim()}>
+            {ctas}
+          </div>
+        )}
+      </div>
+    </section>
+  )
+}

package/src/organisms/FullBleedHero.jsx

@@ -0,0 +1,111 @@
+import { isValidElement } from 'react'
+import HlsVideo from '../atoms/HlsVideo.jsx'
+import Image from '../molecules/Image.jsx'
+
+/** Height presets; anything else is passed through as a class string. */
+const HEIGHTS = {
+  screen: 'h-screen',
+  lg: 'h-[440px] md:h-[640px]',
+  md: 'h-[320px] md:h-[440px]',
+}
+
+/**
+ * Background layer: a media descriptor becomes a cover-fit Image / HlsVideo /
+ * inert <video> (`.kol-full-bleed-hero-media` pins it absolute + object-cover
+ * — CSS in @kol/theme); a ready ReactNode renders as-is and must position
+ * itself (give it that same class).
+ */
+function MediaLayer({ media }) {
+  if (!media) return null
+  if (isValidElement(media) || typeof media !== 'object') return media
+
+  const { src, kind = 'image', poster, srcSet, alt = '' } = media
+
+  if (kind === 'video') {
+    // Non-HLS file (mp4/webm): a plain inert video element. HLS manifests —
+    // and the poster-only case — go through the HlsVideo atom, which owns
+    // hls.js attachment and the full non-interactive hardening set.
+    if (src && !src.endsWith('.m3u8')) {
+      return (
+        <video
+          src={src}
+          poster={poster}
+          className="kol-full-bleed-hero-media"
+          style={{ pointerEvents: 'none' }}
+          autoPlay
+          loop
+          muted
+          playsInline
+          controls={false}
+        />
+      )
+    }
+    return <HlsVideo src={src} poster={poster} className="kol-full-bleed-hero-media" />
+  }
+
+  return (
+    <Image
+      src={src}
+      srcSet={srcSet}
+      sizes={srcSet ? '100vw' : undefined}
+      alt={alt}
+      loading="eager"
+      className="kol-full-bleed-hero-media"
+    />
+  )
+}
+
+/**
+ * FullBleedHero — full-bleed media hero: cover-fit background media (image or
+ * video) filling a fixed-height section, an optional surface scrim, and one
+ * content slot laid over it. The third member of the hero family — BrandHero
+ * and SubPageHero are band heroes; this is the media one. The canonical
+ * recipe drops an OverlayGlassPanel into `panel`; that recipe with
+ * `kind: 'video'` + `height="screen"` IS the monorepo's StudioHero, folded in
+ * here as a capability rather than a separate component.
+ *
+ * Presentational — no copy, no CDN paths, no routes. All text is authored
+ * inside the caller's panel/children. The source's `opacity-${n}` dynamic
+ * Tailwind class (JIT-invisible) is replaced by the scrim's inline style; the
+ * source's image self-dim (`imageOpacity={40}`) is expressed here as
+ * `overlayOpacity={60}` — a surface-primary veil over full-opacity media.
+ *
+ * @param {ReactNode|{src, kind, poster, srcSet, alt}} media  background — descriptor ({ kind: 'image'|'video' }) or a self-positioning node
+ * @param {number}    overlayOpacity 0–100 surface-primary scrim over the media (inline opacity; default 0 = none)
+ * @param {string}    height         'screen' | 'lg' | 'md' preset, or any Tailwind height class string
+ * @param {ReactNode} panel          content slot, usually a caller-authored OverlayGlassPanel; wins over children
+ * @param {ReactNode} children       fallback content slot when `panel` is omitted
+ * @param {string}    align          'center' | 'start' | 'end' — horizontal placement of the content (vertically centered)
+ * @param {string}    className      extra classes on the section
+ */
+export default function FullBleedHero({
+  media,
+  overlayOpacity = 0,
+  height = 'lg',
+  panel,
+  children,
+  align = 'center',
+  className = '',
+}) {
+  const heightCls = HEIGHTS[height] || height
+  const alignCls =
+    align === 'start' ? 'justify-start'
+    : align === 'end' ? 'justify-end'
+    : 'justify-center'
+
+  return (
+    <section className={`kol-full-bleed-hero relative isolate w-full overflow-hidden ${heightCls} ${className}`.trim()}>
+      <MediaLayer media={media} />
+      {overlayOpacity > 0 && (
+        <div
+          aria-hidden="true"
+          className="absolute inset-0"
+          style={{ background: 'var(--kol-surface-primary)', opacity: overlayOpacity / 100 }}
+        />
+      )}
+      <div className={`relative z-10 flex h-full w-full items-center ${alignCls} p-6 md:p-10`}>
+        {panel ?? children}
+      </div>
+    </section>
+  )
+}

package/src/organisms/GalleryCarousel.jsx

@@ -0,0 +1,83 @@
+import { useRef, useState } from 'react'
+import Carousel from './Carousel.jsx'
+import MediaViewer from './MediaViewer.jsx'
+
+/* Drag-vs-click guard: DS Carousel owns Embla's drag physics but does NOT
+ * forward a click-allowed signal, so a free-scroll drag that ends on a tile
+ * would otherwise fire its onClick and open the viewer. This 5px pointer-move
+ * threshold suppresses that click — self-contained, no Embla api needed. */
+const DRAG_THRESHOLD_SQ = 25
+
+/**
+ * GalleryCarousel — the project-detail media gallery: a horizontal, drag-scroll
+ * shelf of image/video tiles where clicking a tile opens THE shared fullscreen
+ * MediaViewer starting at that tile.
+ *
+ * Composed from DS pieces, not forked: the shelf is DS **Carousel** in its
+ * default `dragFree` mode; the fullscreen stage is DS **MediaViewer** (the one
+ * paged viewer every lightbox collapses onto) opened at the clicked index. The
+ * source's bespoke Embla wiring + `WheelGesturesPlugin` + hand-rolled
+ * `internalEngine()` drag guard are dropped; a lightweight pointer-distance
+ * guard keeps a drag from opening the viewer.
+ *
+ * Media is normalized (no Sanity): each item `{ url, kind: 'image'|'video',
+ * aspect?, alt? }`. `kind` replaces the `_type` sniff; `aspect` replaces the
+ * authored aspect-ratio string ladder (fallback `defaultAspect`). Videos
+ * autoplay muted/looped inline in the track.
+ *
+ * @param {Array}  media          [{ url, kind: 'image'|'video', aspect?, alt? }]
+ * @param {string} title          alt-text fallback (`${title} ${i+1}`)
+ * @param {number} defaultAspect  tile aspect when an item omits `aspect` (default 0.8)
+ * @param {string} className      extra classes on the section
+ */
+export default function GalleryCarousel({ media = [], title = '', defaultAspect = 0.8, className = '' }) {
+  const [viewerIndex, setViewerIndex] = useState(null)
+  const pointerStart = useRef({ x: 0, y: 0 })
+  const dragged = useRef(false)
+
+  if (!media.length) return null
+
+  const onPointerDown = (e) => {
+    dragged.current = false
+    pointerStart.current = { x: e.clientX, y: e.clientY }
+  }
+  const onPointerMove = (e) => {
+    if (dragged.current) return
+    const dx = e.clientX - pointerStart.current.x
+    const dy = e.clientY - pointerStart.current.y
+    if (dx * dx + dy * dy > DRAG_THRESHOLD_SQ) dragged.current = true
+  }
+
+  return (
+    <section className={className}>
+      <Carousel>
+        {media.map((item, i) => {
+          const aspect = item.aspect ?? defaultAspect
+          return (
+            <div
+              key={item.url || i}
+              className="w-full overflow-hidden rounded-[2px] cursor-pointer"
+              style={{ aspectRatio: aspect }}
+              onPointerDown={onPointerDown}
+              onPointerMove={onPointerMove}
+              onClick={() => { if (!dragged.current) setViewerIndex(i) }}
+            >
+              {item.kind === 'video' ? (
+                <video src={item.url} autoPlay muted playsInline loop className="w-full h-full object-cover" />
+              ) : (
+                <img src={item.url} alt={item.alt || `${title} ${i + 1}`} className="w-full h-full object-cover" />
+              )}
+            </div>
+          )
+        })}
+      </Carousel>
+
+      <MediaViewer
+        open={viewerIndex !== null}
+        media={media}
+        initialIndex={viewerIndex ?? 0}
+        onClose={() => setViewerIndex(null)}
+      />
+    </section>
+  )
+}

package/src/organisms/LoaderOverlay.jsx

@@ -0,0 +1,30 @@
+import FullscreenOverlay from '../atoms/FullscreenOverlay.jsx'
+import ColorLoader from './ColorLoader.jsx'
+
+/**
+ * LoaderOverlay — mounts a loading curtain over everything, dead center. A thin
+ * composition: it wraps DS FullscreenOverlay for the fixed, top-`z`,
+ * scroll-locking backdrop (replacing the app's hand-rolled `fixed inset-0 …
+ * z-[100]` div and its `CursorProvider`), then renders `children` — or a
+ * default ColorLoader — as the overlay content. Being mounted IS being visible;
+ * the parent removes this element to dismiss.
+ *
+ * The default ColorLoader is a full-viewport `dismissOnClick` curtain whose
+ * completion is wired to `onEnter`. A `fixed inset-0` box escapes
+ * FullscreenOverlay's centered, `--kol-container-max`-width sheet so the loader
+ * fills the screen. Pass `children` to drop that and mount anything else.
+ *
+ * @param {ReactNode}  children  overlay content; defaults to a full-screen ColorLoader
+ * @param {() => void} onEnter   fired when the default ColorLoader completes/dismisses
+ */
+export default function LoaderOverlay({ children, onEnter }) {
+  return (
+    <FullscreenOverlay open>
+      {children || (
+        <div className="fixed inset-0">
+          <ColorLoader onComplete={onEnter} dismissOnClick />
+        </div>
+      )}
+    </FullscreenOverlay>
+  )
+}

package/src/organisms/MediaViewer.jsx

@@ -0,0 +1,95 @@
+import { useEffect, useRef, useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-loader'
+import FullscreenOverlay from '../atoms/FullscreenOverlay.jsx'
+
+/**
+ * MediaViewer — THE fullscreen paged media viewer. One viewer for every
+ * lightbox/gallery opener (the monorepo's ImageLightbox, FullscreenGallery
+ * and WorkDetail's inline gallery all collapse onto this).
+ *
+ * The shell (scrim, scroll-lock, Escape, backdrop-close, close button) is
+ * FullscreenOverlay — not reimplemented. This adds paging: prev/next chips,
+ * arrow keys, touch swipe, wrap-around.
+ *
+ * ponytail: paging is ~20 lines of state + swipe, so it's inline rather than
+ * composing Carousel — embla's drag physics buy nothing for a one-item stage;
+ * revisit if momentum/preview-of-next is ever wanted.
+ *
+ * @param {boolean}  open           viewer visible
+ * @param {Array}    media          [{ url, alt?, kind: 'image' | 'video' }]
+ * @param {number}   initialIndex   item shown on open
+ * @param {Function} onClose        close request
+ * @param {Function} onIndexChange  fires with the new index on page
+ */
+export default function MediaViewer({ open, media = [], initialIndex = 0, onClose, onIndexChange }) {
+  const [index, setIndex] = useState(initialIndex)
+  const touchStart = useRef(null)
+
+  // re-anchor to initialIndex each time the viewer opens
+  useEffect(() => {
+    if (open) setIndex(initialIndex)
+  }, [open, initialIndex])
+
+  const page = (delta) => {
+    if (media.length < 2) return
+    setIndex((i) => {
+      const next = (i + delta + media.length) % media.length
+      onIndexChange?.(next)
+      return next
+    })
+  }
+
+  useEffect(() => {
+    if (!open) return
+    const onKey = (e) => {
+      if (e.key === 'ArrowLeft') page(-1)
+      if (e.key === 'ArrowRight') page(1)
+    }
+    document.addEventListener('keydown', onKey)
+    return () => document.removeEventListener('keydown', onKey)
+  }, [open, media.length]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  const item = media[index]
+  if (!open || !item) return null
+
+  const onTouchStart = (e) => { touchStart.current = e.touches[0].clientX }
+  const onTouchEnd = (e) => {
+    if (touchStart.current == null) return
+    const delta = e.changedTouches[0].clientX - touchStart.current
+    if (delta > 50) page(-1)
+    if (delta < -50) page(1)
+    touchStart.current = null
+  }
+
+  const chip = 'absolute top-1/2 -translate-y-1/2 z-10 hidden md:flex items-center justify-center w-10 h-10 rounded-full bg-fg-04 hover:bg-fg-08 transition-colors cursor-pointer border-0'
+
+  return (
+    <FullscreenOverlay open={open} onClose={onClose}>
+      <div className="relative flex h-full w-full items-center justify-center" onTouchStart={onTouchStart} onTouchEnd={onTouchEnd}>
+        {media.length > 1 && (
+          <button type="button" className={`${chip} left-4`} aria-label="Previous" onClick={() => page(-1)}>
+            <Icon name="chevron-left" size={20} />
+          </button>
+        )}
+        {item.kind === 'video' ? (
+          <video
+            key={item.url}
+            src={item.url}
+            autoPlay
+            muted
+            loop
+            playsInline
+            className="max-h-[85vh] max-w-full object-contain"
+          />
+        ) : (
+          <img src={item.url} alt={item.alt || ''} className="max-h-[85vh] max-w-full object-contain" />
+        )}
+        {media.length > 1 && (
+          <button type="button" className={`${chip} right-4`} aria-label="Next" onClick={() => page(1)}>
+            <Icon name="chevron-right" size={20} />
+          </button>
+        )}
+      </div>
+    </FullscreenOverlay>
+  )
+}