From 2e40c0ae4d64b4602c3f1d311dce25da177b34f5 Mon Sep 17 00:00:00 2001 From: trex Date: Sun, 22 Nov 2026 01:18:28 -0600 Subject: [PATCH] feat(mdx): add ImageCarousel component for post galleries Scroll-snap carousel usable directly in .mdx posts: Props: images (required), aspect (default aspect-[16/9]), fit (cover|contain), showArrows, showDots, showCounter. Native swipe and trackpad scroll, arrow-key support when focused, per-slide captions, and arrows/dots/counter auto-hide for a single image. No new dependencies; reuses the existing Image wrapper so s3.jonb.io and /static paths work as-is. --- components/ImageCarousel.tsx | 188 +++++++++++++++++++++++++++++++++++ components/MDXComponents.tsx | 2 + 2 files changed, 190 insertions(+) create mode 100644 components/ImageCarousel.tsx diff --git a/components/ImageCarousel.tsx b/components/ImageCarousel.tsx new file mode 100644 index 0000000..7656db9 --- /dev/null +++ b/components/ImageCarousel.tsx @@ -0,0 +1,188 @@ +'use client' + +import { useCallback, useEffect, useRef, useState } from 'react' +import Image from './Image' + +export type CarouselImage = { + src: string + alt?: string + caption?: string +} + +interface ImageCarouselProps { + images: CarouselImage[] + /** Tailwind aspect class for the slide box. */ + aspect?: string + /** `cover` crops to fill, `contain` letterboxes. */ + fit?: 'cover' | 'contain' + showArrows?: boolean + showDots?: boolean + showCounter?: boolean +} + +const Arrow = ({ dir }: { dir: 'left' | 'right' }) => ( + +) + +export default function ImageCarousel({ + images, + aspect = 'aspect-[16/9]', + fit = 'cover', + showArrows = true, + showDots = true, + showCounter = true, +}: ImageCarouselProps) { + const trackRef = useRef(null) + const [index, setIndex] = useState(0) + + const count = images?.length ?? 0 + const multiple = count > 1 + + const goTo = useCallback( + (i: number) => { + const track = trackRef.current + if (!track) return + const clamped = Math.max(0, Math.min(count - 1, i)) + track.scrollTo({ left: clamped * track.clientWidth, behavior: 'smooth' }) + }, + [count] + ) + + // Keep the dot/counter state in sync with native swipe + trackpad scrolling. + useEffect(() => { + const track = trackRef.current + if (!track) return + let raf = 0 + const onScroll = () => { + cancelAnimationFrame(raf) + raf = requestAnimationFrame(() => { + const width = track.clientWidth || 1 + setIndex(Math.round(track.scrollLeft / width)) + }) + } + track.addEventListener('scroll', onScroll, { passive: true }) + return () => { + track.removeEventListener('scroll', onScroll) + cancelAnimationFrame(raf) + } + }, []) + + if (count === 0) return null + + const onKeyDown = (event: React.KeyboardEvent) => { + if (!multiple) return + if (event.key === 'ArrowLeft') { + event.preventDefault() + goTo(index - 1) + } else if (event.key === 'ArrowRight') { + event.preventDefault() + goTo(index + 1) + } + } + + const activeCaption = images[index]?.caption + + return ( +
+ {/* WAI-ARIA carousel pattern: the region is focusable so arrow keys work. */} + {/* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions */} +
+
+ {images.map((image, i) => ( +
+ {image.alt +
+ ))} +
+ + {multiple && showArrows && ( + <> + + + + )} + + {multiple && showCounter && ( +
+ {index + 1} / {count} +
+ )} +
+ + {multiple && showDots && ( +
+ {images.map((image, i) => ( +
+ )} + + {activeCaption && ( +
+ {activeCaption} +
+ )} +
+ ) +} diff --git a/components/MDXComponents.tsx b/components/MDXComponents.tsx index 4b3e271..0bc0c58 100644 --- a/components/MDXComponents.tsx +++ b/components/MDXComponents.tsx @@ -3,11 +3,13 @@ import Pre from 'pliny/ui/Pre' import BlogNewsletterForm from 'pliny/ui/BlogNewsletterForm' import type { MDXComponents } from 'mdx/types' import Image from './Image' +import ImageCarousel from './ImageCarousel' import CustomLink from './Link' import TableWrapper from './TableWrapper' export const components: MDXComponents = { Image, + ImageCarousel, TOCInline, a: CustomLink, pre: Pre, -- 2.54.1