@mitchellslager/carousel 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitchell Slager
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# @mitchellslager/carousel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A headless, accessible image carousel for React 19, driven by native CSS scroll snapping.
+
+- Thumbnail navigation, synchronised with the carousel
+- A "3 / 10" counter
+- The WAI-ARIA carousel pattern, with translatable labels
+- Respects `prefers-reduced-motion`
+
+[Demo](https://mitchellslager.github.io/carousel/) · [Design decisions](https://github.com/mitchellslager/carousel/blob/main/DESIGN.md)
+
+## Usage
+
+```bash
+pnpm add @mitchellslager/carousel
+```
+
+```tsx
+import { Carousel } from "@mitchellslager/carousel"
+import "@mitchellslager/carousel/styles.css"
+
+export function ProductGallery({
+  images,
+}: {
+  images: { src: string; alt: string }[]
+}) {
+  return (
+    <Carousel.Root aria-label="Product images">
+      <Carousel.Viewport>
+        {images.map((image) => (
+          <Carousel.Slide key={image.src}>
+            <img src={image.src} alt={image.alt} />
+          </Carousel.Slide>
+        ))}
+      </Carousel.Viewport>
+      <Carousel.Prev>←</Carousel.Prev>
+      <Carousel.Counter />
+      <Carousel.Next>→</Carousel.Next>
+      <Carousel.Thumbnails>
+        {images.map((image, index) => (
+          <Carousel.Thumbnail key={image.src} index={index}>
+            <img src={image.src} alt="" />
+          </Carousel.Thumbnail>
+        ))}
+      </Carousel.Thumbnails>
+    </Carousel.Root>
+  )
+}
+```
+
+Give `Root` an accessible name with `aria-label` or `aria-labelledby`. Every part is optional and can be placed anywhere inside `Root`.
+
+### Parts
+
+| Part           | Renders  | Notes                                                            |
+| -------------- | -------- | ---------------------------------------------------------------- |
+| `Root`         | `div`    | `index` / `defaultIndex` / `onIndexChange`, `labels`, `motion`.  |
+| `Viewport`     | `div`    | The scroll-snap container. Its `Slide` children are the slides.  |
+| `Slide`        | `div`    | `inert` unless active. `data-active` when active.                |
+| `Prev`, `Next` | `button` | `aria-disabled` and `data-disabled` at the edges. `render` prop. |
+| `Counter`      | `span`   | "3 / 10" by default; pass a function child to change it.         |
+| `Thumbnails`   | `div`    | Tab list; `orientation` is `"horizontal"` or `"vertical"`.       |
+| `Thumbnail`    | `button` | Tab for slide `index`. `data-active` when active. `render` prop. |
+
+### State
+
+`onIndexChange` fires once scrolling settles on a new slide. Pass `index` to request a slide from outside: changing it scrolls there, but a swipe always wins and reports itself through `onIndexChange`. To reset the carousel, for example when a product variant changes its images, give `Root` a new `key`.
+
+### Labels
+
+All accessible text is English by default. Translate it with `labels`:
+
+```tsx
+<Carousel.Root
+  aria-label="Productafbeeldingen"
+  labels={{
+    carousel: "carrousel",
+    slideLabel: (index, total) => `${index + 1} van ${total}`,
+    previous: "Vorige afbeelding",
+    next: "Volgende afbeelding",
+    thumbnails: "Afbeeldingen",
+    thumbnailLabel: (index) => `Afbeelding ${index + 1}`,
+    announcement: (index, total) => `Afbeelding ${index + 1} van ${total}`,
+  }}
+>
+```
+
+### Motion
+
+The carousel scrolls smoothly, and jumps instead when the user prefers reduced motion. Pass `motion="reduce"` to always jump.
+
+### Custom elements
+
+`Prev`, `Next` and `Thumbnail` take a `render` prop to render as your own component. Props are merged: class names are joined, and your event handlers run first (call `event.preventDefault()` to skip the carousel's own).
+
+```tsx
+<Carousel.Next render={<Button variant="ghost" />}>Next</Carousel.Next>
+```
+
+## Styling
+
+Import the base styles once:
+
+```ts
+import "@mitchellslager/carousel/styles.css"
+```
+
+They only handle layout, snapping and reduced motion, inside `@layer carousel`. Unlayered CSS of your own always wins. If you use Tailwind or other cascade layers, declare the carousel layer first so your utilities override it:
+
+```css
+@layer carousel;
+@import "tailwindcss";
+```
+
+## Contributing
+
+Development happens in the [GitHub repository](https://github.com/mitchellslager/carousel).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import { ComponentProps, ReactElement, ReactNode } from "react";
+/**
+ * Every text the carousel puts in the accessibility tree. Pass a partial
+ * object to `Carousel.Root`'s `labels` prop to translate or reword them.
+ * Indexes are zero-based.
+ */
+interface CarouselLabels {
+  /** `aria-roledescription` of the root. */
+  carousel: string;
+  /** `aria-roledescription` of each slide. */
+  slide: string;
+  /** `aria-label` of each slide. */
+  slideLabel: (index: number, total: number) => string;
+  /** `aria-label` of `Carousel.Prev`. */
+  previous: string;
+  /** `aria-label` of `Carousel.Next`. */
+  next: string;
+  /** `aria-label` of the thumbnail tab list. */
+  thumbnails: string;
+  /** `aria-label` of each thumbnail tab. */
+  thumbnailLabel: (index: number, total: number) => string;
+  /** Announced by the live region when the carousel settles on a slide. */
+  announcement: (index: number, total: number) => string;
+}
+export declare const defaultLabels: CarouselLabels;
+interface RootProps extends Omit<ComponentProps<"div">, "onChange"> {
+  /**
+   * The requested slide (controlled). Changing it scrolls there, but a swipe
+   * always wins and reports itself through `onIndexChange`.
+   */
+  index?: number;
+  /** The slide to start on (uncontrolled). Defaults to 0. */
+  defaultIndex?: number;
+  /** Called once scrolling settles on a different slide. */
+  onIndexChange?: (index: number) => void;
+  /** Overrides for the accessible texts. */
+  labels?: Partial<CarouselLabels>;
+  /**
+   * `"auto"` follows the user's `prefers-reduced-motion` setting; `"reduce"`
+   * always jumps instead of scrolling smoothly.
+   */
+  motion?: "auto" | "reduce";
+}
+declare function Root({ index, defaultIndex, onIndexChange, labels: labelOverrides, motion, children, ...props }: RootProps): import("react").JSX.Element;
+type Props = Record<string, unknown>;
+/**
+ * Lets a part render as another element, Base UI style:
+ * `<Carousel.Next render={<MyButton />} />`. The element's own props are
+ * merged with the part's props.
+ */
+type RenderProp = ReactElement<Props>;
+type ViewportProps = ComponentProps<"div">;
+/** The scroll-snap container. Its direct `Carousel.Slide` children are the slides. */
+declare function Viewport({ ref, children, ...props }: ViewportProps): import("react").JSX.Element;
+type SlideProps = ComponentProps<"div">;
+/** One slide. Slides that are not active are `inert`. */
+declare function Slide({ ref, ...props }: SlideProps): import("react").JSX.Element;
+interface NavigationProps extends ComponentProps<"button"> {
+  /** Render as another element, for example `render={<MyButton />}`. */
+  render?: RenderProp;
+}
+/** Scrolls to the previous slide. `aria-disabled` on the first slide. */
+declare function Prev({ render, ...props }: NavigationProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Scrolls to the next slide. `aria-disabled` on the last slide. */
+declare function Next({ render, ...props }: NavigationProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+interface CounterState {
+  /** Zero-based index of the active slide. */
+  index: number;
+  total: number;
+}
+interface CounterProps extends Omit<ComponentProps<"span">, "children"> {
+  /** Custom content. Defaults to "3 / 10". */
+  children?: (state: CounterState) => ReactNode;
+}
+/**
+ * Shows the position, such as "3 / 10". Hidden from assistive technology:
+ * slide labels and the live region already convey it. Empty until the slides
+ * are known, so also during server rendering.
+ */
+declare function Counter({ children, ...props }: CounterProps): import("react").JSX.Element;
+interface ThumbnailsProps extends ComponentProps<"div"> {
+  /** Layout direction; decides which arrow keys move between thumbnails. */
+  orientation?: "horizontal" | "vertical";
+}
+/**
+ * A tab list of thumbnails, one per slide. Arrow keys, Home and End move
+ * between thumbnails and select them at once.
+ */
+declare function Thumbnails({ orientation, ...props }: ThumbnailsProps): import("react").JSX.Element;
+interface ThumbnailProps extends ComponentProps<"button"> {
+  /** The zero-based index of the slide this thumbnail selects. */
+  index: number;
+  /** Render as another element, for example `render={<MyButton />}`. */
+  render?: RenderProp;
+}
+/** A tab that selects slide `index`. Keeps itself in view when active. */
+declare function Thumbnail({ index, render, ref, ...props }: ThumbnailProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+declare namespace index_d_exports {
+  export { Counter, CounterProps, CounterState, NavigationProps, Next, Prev, Root, RootProps, Slide, SlideProps, Thumbnail, ThumbnailProps, Thumbnails, ThumbnailsProps, Viewport, ViewportProps };
+}
+export { index_d_exports as Carousel, type CarouselLabels, type RenderProp };

package/dist/index.js

@@ -0,0 +1,558 @@
+"use client";
+import { t as __exportAll } from "./rolldown-runtime-D8jQpDG7.js";
+import { cloneElement, createContext, createElement, isValidElement, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+// src/core/geometry.ts
+/**
+* Scroll geometry helpers. Everything is measured with
+* `getBoundingClientRect` and moved with `scrollBy`, which both use physical
+* coordinates, so the same code works for left-to-right and right-to-left
+* layouts.
+*/
+/** Differences below one pixel are rounding, not a position to move to. */
+const TOLERANCE = 1;
+function horizontalCentre(element) {
+	const rect = element.getBoundingClientRect();
+	return rect.left + rect.width / 2;
+}
+/**
+* Returns the index of the slide whose centre is nearest the viewport's
+* centre, or -1 when there are no slides.
+*/
+function findNearestSlide(viewport, slides) {
+	const centre = horizontalCentre(viewport);
+	let nearest = -1;
+	let nearestDistance = Infinity;
+	slides.forEach((slide, index) => {
+		const distance = Math.abs(horizontalCentre(slide) - centre);
+		if (distance < nearestDistance) {
+			nearest = index;
+			nearestDistance = distance;
+		}
+	});
+	return nearest;
+}
+/** Whether `slide` sits in the centre of `viewport`. */
+function isCentred(viewport, slide) {
+	const delta = horizontalCentre(slide) - horizontalCentre(viewport);
+	return Math.abs(delta) < TOLERANCE;
+}
+/**
+* Scrolls `viewport` horizontally so `slide` sits in its centre. Returns
+* whether it had to scroll.
+*/
+function scrollSlideIntoCentre(viewport, slide, behavior) {
+	const delta = horizontalCentre(slide) - horizontalCentre(viewport);
+	if (Math.abs(delta) < TOLERANCE) return false;
+	viewport.scrollBy({
+		left: delta,
+		behavior
+	});
+	return true;
+}
+function overflow(start, end, min, max) {
+	if (start < min - TOLERANCE) return start - min;
+	if (end > max + TOLERANCE) return end - max;
+	return 0;
+}
+/**
+* Scrolls `container` the least amount needed to show `element` completely,
+* like `scrollIntoView({ block: "nearest", inline: "nearest" })`, but without
+* scrolling any ancestor or the page.
+*/
+function scrollIntoViewWithin(container, element, behavior) {
+	const outer = container.getBoundingClientRect();
+	const inner = element.getBoundingClientRect();
+	const left = overflow(inner.left, inner.right, outer.left, outer.right);
+	const top = overflow(inner.top, inner.bottom, outer.top, outer.bottom);
+	if (left || top) container.scrollBy({
+		left,
+		top,
+		behavior
+	});
+}
+// src/core/scroll-tracker.ts
+/**
+* Tracks which slide of a horizontal scroll-snap viewport is in view.
+*
+* The scroll position is the source of truth: this module only reads it, and
+* moves it through `scrollToIndex`. It reports two indexes:
+*
+* - the **active** index, updated live (once per frame) while scrolling, for
+*   UI that should react at once, such as the counter and thumbnails;
+* - the **settled** index, updated when scrolling ends, for consumers that
+*   should only see final values, such as `onIndexChange`.
+*
+* Positions come from ./geometry, which works for left-to-right and
+* right-to-left layouts alike.
+*/
+const DEFAULT_SETTLE_DELAY = 100;
+function createScrollTracker(viewport, options) {
+	const { getSlides, onActiveChange, onSettle, settle = "auto", settleDelay = DEFAULT_SETTLE_DELAY } = options;
+	const useScrollEnd = settle === "scrollend" || settle === "auto" && "onscrollend" in window;
+	const initialIndex = Math.max(0, findNearestSlide(viewport, getSlides()));
+	let activeIndex = initialIndex;
+	let settledIndex = initialIndex;
+	let frame = 0;
+	let settleTimer;
+	function measure() {
+		frame = 0;
+		const index = findNearestSlide(viewport, getSlides());
+		if (index !== -1 && index !== activeIndex) {
+			activeIndex = index;
+			onActiveChange(index);
+		}
+	}
+	function settleNow() {
+		cancelAnimationFrame(frame);
+		clearTimeout(settleTimer);
+		measure();
+		if (activeIndex !== settledIndex) {
+			settledIndex = activeIndex;
+			onSettle(activeIndex);
+		}
+	}
+	let lastScroll = 0;
+	function settleWhenAligned() {
+		const slides = getSlides();
+		const nearest = slides[findNearestSlide(viewport, slides)];
+		const quiet = performance.now() - lastScroll;
+		if (nearest && !isCentred(viewport, nearest) && quiet < settleDelay * 5) {
+			settleTimer = setTimeout(settleWhenAligned, settleDelay);
+			return;
+		}
+		settleNow();
+	}
+	function handleScroll() {
+		if (!frame) frame = requestAnimationFrame(measure);
+		if (!useScrollEnd) {
+			lastScroll = performance.now();
+			clearTimeout(settleTimer);
+			settleTimer = setTimeout(settleWhenAligned, settleDelay);
+		}
+	}
+	viewport.addEventListener("scroll", handleScroll, { passive: true });
+	if (useScrollEnd) viewport.addEventListener("scrollend", settleNow);
+	return {
+		get activeIndex() {
+			return activeIndex;
+		},
+		get settledIndex() {
+			return settledIndex;
+		},
+		scrollToIndex(index, behavior = "auto") {
+			const slides = getSlides();
+			const target = slides[Math.min(Math.max(index, 0), slides.length - 1)];
+			if (!target) return false;
+			return scrollSlideIntoCentre(viewport, target, behavior);
+		},
+		update: settleNow,
+		destroy() {
+			cancelAnimationFrame(frame);
+			clearTimeout(settleTimer);
+			viewport.removeEventListener("scroll", handleScroll);
+			viewport.removeEventListener("scrollend", settleNow);
+		}
+	};
+}
+// src/components/context.ts
+const CarouselContext = createContext(null);
+function useCarouselContext(part) {
+	const context = useContext(CarouselContext);
+	if (!context) throw new Error(`Carousel.${part} must be rendered inside Carousel.Root.`);
+	return context;
+}
+// src/components/labels.ts
+const defaultLabels = {
+	carousel: "carousel",
+	slide: "slide",
+	slideLabel: (index, total) => `${index + 1} of ${total}`,
+	previous: "Previous slide",
+	next: "Next slide",
+	thumbnails: "Slides",
+	thumbnailLabel: (index) => `Slide ${index + 1}`,
+	announcement: (index, total) => `Slide ${index + 1} of ${total}`
+};
+// src/components/render.ts
+/** Combines refs into one callback ref. */
+function mergeRefs(...refs) {
+	return (value) => {
+		const cleanups = refs.map((ref) => {
+			if (typeof ref === "function") return ref(value);
+			if (ref) ref.current = value;
+		});
+		return () => {
+			refs.forEach((ref, index) => {
+				const cleanup = cleanups[index];
+				if (typeof cleanup === "function") cleanup();
+				else if (typeof ref === "function") ref(null);
+				else if (ref) ref.current = null;
+			});
+		};
+	};
+}
+/**
+* `mergeRefs` with a stable identity, so React does not detach and reattach
+* the ref on every render.
+*/
+function useMergedRefs(a, b) {
+	return useMemo(() => mergeRefs(a, b), [a, b]);
+}
+function isHandler(key, value) {
+	return /^on[A-Z]/.test(key) && typeof value === "function";
+}
+/**
+* Merges `outer` props (from the consumer) over `inner` props (from the
+* part). Class names are joined, styles merged and refs combined. For event
+* handlers, the consumer's runs first; calling `event.preventDefault()` in it
+* skips the part's own handler.
+*/
+function mergeProps(inner, outer) {
+	const merged = { ...inner };
+	for (const [key, value] of Object.entries(outer)) {
+		const base = inner[key];
+		if (value === void 0) continue;
+		if (key === "className" && base) merged[key] = `${String(base)} ${String(value)}`;
+		else if (key === "style" && base) merged[key] = {
+			...base,
+			...value
+		};
+		else if (key === "ref" && base) merged[key] = mergeRefs(base, value);
+		else if (isHandler(key, value) && isHandler(key, base)) merged[key] = (event) => {
+			value(event);
+			if (!event?.defaultPrevented) base(event);
+		};
+		else merged[key] = value;
+	}
+	return merged;
+}
+/**
+* Renders a part: `tag` with the merged props, or the `render` element with
+* the merged props applied to it.
+*/
+function renderPart(tag, props, render) {
+	if (isValidElement(render)) return cloneElement(render, mergeProps(props, render.props));
+	return createElement(tag, props);
+}
+// src/components/use-reduced-motion.ts
+const QUERY = "(prefers-reduced-motion: reduce)";
+function subscribe(onChange) {
+	const media = window.matchMedia(QUERY);
+	media.addEventListener("change", onChange);
+	return () => media.removeEventListener("change", onChange);
+}
+const getSnapshot = () => window.matchMedia(QUERY).matches;
+const getServerSnapshot = () => false;
+/** Whether the user asked the operating system for reduced motion. */
+function usePrefersReducedMotion() {
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+// src/components/root.tsx
+const SLIDE_SELECTOR = ":scope > [data-carousel-slide]";
+const visuallyHidden = {
+	position: "absolute",
+	width: 1,
+	height: 1,
+	margin: -1,
+	padding: 0,
+	overflow: "hidden",
+	clip: "rect(0 0 0 0)",
+	whiteSpace: "nowrap",
+	border: 0
+};
+/** Keeps the latest value in a ref, for use inside long-lived callbacks. */
+function useLatest(value) {
+	const ref = useRef(value);
+	useLayoutEffect(() => {
+		ref.current = value;
+	});
+	return ref;
+}
+function Root({ index, defaultIndex = 0, onIndexChange, labels: labelOverrides, motion = "auto", children, ...props }) {
+	const baseId = useId();
+	const [initialIndex] = useState(() => index ?? defaultIndex);
+	const [viewport, setViewport] = useState(null);
+	const [slides, setSlides] = useState([]);
+	const [activeIndex, setActiveIndex] = useState(initialIndex);
+	const [hasThumbnails, setHasThumbnails] = useState(false);
+	const [announcement, setAnnouncement] = useState("");
+	const trackerRef = useRef(null);
+	const sourceRef = useRef(null);
+	const prefersReducedMotion = usePrefersReducedMotion();
+	const behavior = motion === "reduce" || prefersReducedMotion ? "instant" : "smooth";
+	const labels = useMemo(() => ({
+		...defaultLabels,
+		...labelOverrides
+	}), [labelOverrides]);
+	const labelsRef = useLatest(labels);
+	const onIndexChangeRef = useLatest(onIndexChange);
+	const behaviorRef = useLatest(behavior);
+	useLayoutEffect(() => {
+		if (!viewport) return;
+		const getSlides = () => [...viewport.querySelectorAll(SLIDE_SELECTOR)];
+		const initialSlides = getSlides();
+		const initialSlide = initialSlides[Math.min(initialIndex, initialSlides.length - 1)];
+		if (initialSlide) scrollSlideIntoCentre(viewport, initialSlide, "instant");
+		const tracker = createScrollTracker(viewport, {
+			getSlides,
+			onActiveChange: setActiveIndex,
+			onSettle: (settled) => {
+				if (sourceRef.current !== "tab") {
+					const total = getSlides().length;
+					setAnnouncement(labelsRef.current.announcement(settled, total));
+				}
+				sourceRef.current = null;
+				onIndexChangeRef.current?.(settled);
+			}
+		});
+		trackerRef.current = tracker;
+		setSlides(initialSlides);
+		setActiveIndex(tracker.activeIndex);
+		const observer = new MutationObserver(() => {
+			setSlides(getSlides());
+			tracker.update();
+		});
+		observer.observe(viewport, { childList: true });
+		return () => {
+			observer.disconnect();
+			tracker.destroy();
+			trackerRef.current = null;
+		};
+	}, [
+		viewport,
+		initialIndex,
+		labelsRef,
+		onIndexChangeRef
+	]);
+	useEffect(() => {
+		if (index === void 0) return;
+		if (trackerRef.current?.scrollToIndex(index, behaviorRef.current)) sourceRef.current = "control";
+	}, [index, behaviorRef]);
+	const goTo = useCallback((target, source) => {
+		if (trackerRef.current?.scrollToIndex(target, behavior)) sourceRef.current = source;
+	}, [behavior]);
+	const context = useMemo(() => ({
+		activeIndex,
+		initialIndex,
+		slides,
+		hasThumbnails,
+		setHasThumbnails,
+		setViewport,
+		goTo,
+		behavior,
+		labels,
+		ids: {
+			root: baseId,
+			viewport: `${baseId}-viewport`,
+			slide: (i) => `${baseId}-slide-${i}`,
+			tab: (i) => `${baseId}-tab-${i}`
+		}
+	}), [
+		activeIndex,
+		initialIndex,
+		slides,
+		hasThumbnails,
+		goTo,
+		behavior,
+		labels,
+		baseId
+	]);
+	const rootProps = mergeProps({
+		id: baseId,
+		role: "region",
+		"aria-roledescription": labels.carousel,
+		"data-carousel-root": ""
+	}, props);
+	return /* @__PURE__ */ jsx(CarouselContext, {
+		value: context,
+		children: /* @__PURE__ */ jsxs("div", {
+			...rootProps,
+			children: [children, /* @__PURE__ */ jsx("div", {
+				"aria-live": "polite",
+				"aria-atomic": "true",
+				style: visuallyHidden,
+				children: announcement
+			})]
+		})
+	});
+}
+// src/components/parts.tsx
+/** The scroll-snap container. Its direct `Carousel.Slide` children are the slides. */
+function Viewport({ ref, children, ...props }) {
+	const { ids, initialIndex, setViewport } = useCarouselContext("Viewport");
+	const mergedRef = useMergedRefs(setViewport, ref);
+	const viewportProps = mergeProps({
+		id: ids.viewport,
+		"data-carousel-viewport": ids.root,
+		ref: mergedRef
+	}, props);
+	return /* @__PURE__ */ jsxs("div", {
+		...viewportProps,
+		children: [initialIndex > 0 && /* @__PURE__ */ jsx("style", {
+			href: `carousel-initial-${ids.root}`,
+			precedence: "carousel",
+			children: `[data-carousel-viewport="${ids.root}"]>[data-carousel-slide]:nth-child(${initialIndex + 1} of [data-carousel-slide]){scroll-initial-target:nearest}`
+		}), children]
+	});
+}
+/** One slide. Slides that are not active are `inert`. */
+function Slide({ ref, ...props }) {
+	const { slides, activeIndex, hasThumbnails, labels, ids } = useCarouselContext("Slide");
+	const [element, setElement] = useState(null);
+	const mergedRef = useMergedRefs(setElement, ref);
+	const index = element ? slides.indexOf(element) : -1;
+	const known = index !== -1;
+	const active = known && index === activeIndex;
+	const slideProps = mergeProps({
+		id: known ? ids.slide(index) : void 0,
+		role: hasThumbnails ? "tabpanel" : "group",
+		"aria-roledescription": labels.slide,
+		"aria-label": known ? labels.slideLabel(index, slides.length) : void 0,
+		inert: known && !active,
+		"data-carousel-slide": "",
+		"data-active": active ? "" : void 0,
+		ref: mergedRef
+	}, props);
+	return /* @__PURE__ */ jsx("div", { ...slideProps });
+}
+function useNavigation(direction, part) {
+	const { activeIndex, slides, goTo, labels, ids } = useCarouselContext(part);
+	const target = activeIndex + direction;
+	const disabled = target < 0 || target >= slides.length;
+	return {
+		type: "button",
+		"aria-label": direction === 1 ? labels.next : labels.previous,
+		"aria-controls": ids.viewport,
+		"aria-disabled": disabled || void 0,
+		"data-disabled": disabled ? "" : void 0,
+		onClick: () => {
+			if (!disabled) goTo(target, "control");
+		}
+	};
+}
+/** Scrolls to the previous slide. `aria-disabled` on the first slide. */
+function Prev({ render, ...props }) {
+	return renderPart("button", mergeProps(useNavigation(-1, "Prev"), props), render);
+}
+/** Scrolls to the next slide. `aria-disabled` on the last slide. */
+function Next({ render, ...props }) {
+	return renderPart("button", mergeProps(useNavigation(1, "Next"), props), render);
+}
+const defaultCounter = ({ index, total }) => `${index + 1} / ${total}`;
+/**
+* Shows the position, such as "3 / 10". Hidden from assistive technology:
+* slide labels and the live region already convey it. Empty until the slides
+* are known, so also during server rendering.
+*/
+function Counter({ children = defaultCounter, ...props }) {
+	const { activeIndex, slides } = useCarouselContext("Counter");
+	const total = slides.length;
+	const counterProps = mergeProps({
+		"aria-hidden": true,
+		"data-carousel-counter": ""
+	}, props);
+	return /* @__PURE__ */ jsx("span", {
+		...counterProps,
+		children: total > 0 ? children({
+			index: activeIndex,
+			total
+		}) : null
+	});
+}
+const NEXT_KEYS = {
+	horizontal: {
+		ltr: "ArrowRight",
+		rtl: "ArrowLeft"
+	},
+	vertical: {
+		ltr: "ArrowDown",
+		rtl: "ArrowDown"
+	}
+};
+const PREVIOUS_KEYS = {
+	horizontal: {
+		ltr: "ArrowLeft",
+		rtl: "ArrowRight"
+	},
+	vertical: {
+		ltr: "ArrowUp",
+		rtl: "ArrowUp"
+	}
+};
+/**
+* A tab list of thumbnails, one per slide. Arrow keys, Home and End move
+* between thumbnails and select them at once.
+*/
+function Thumbnails({ orientation = "horizontal", ...props }) {
+	const { labels, setHasThumbnails } = useCarouselContext("Thumbnails");
+	useEffect(() => {
+		setHasThumbnails(true);
+		return () => setHasThumbnails(false);
+	}, [setHasThumbnails]);
+	function handleKeyDown(event) {
+		const list = event.currentTarget;
+		const tabs = [...list.querySelectorAll("[data-carousel-thumbnail]")];
+		const current = tabs.findIndex((tab) => tab.contains(event.target));
+		if (current === -1) return;
+		const direction = getComputedStyle(list).direction === "rtl" ? "rtl" : "ltr";
+		let next;
+		if (event.key === NEXT_KEYS[orientation][direction]) next = (current + 1) % tabs.length;
+		else if (event.key === PREVIOUS_KEYS[orientation][direction]) next = (current - 1 + tabs.length) % tabs.length;
+		else if (event.key === "Home") next = 0;
+		else if (event.key === "End") next = tabs.length - 1;
+		else return;
+		event.preventDefault();
+		const tab = tabs[next];
+		tab?.focus();
+		tab?.click();
+	}
+	const listProps = mergeProps({
+		role: "tablist",
+		"aria-label": labels.thumbnails,
+		"aria-orientation": orientation,
+		"data-carousel-thumbnails": "",
+		"data-orientation": orientation,
+		onKeyDown: handleKeyDown
+	}, props);
+	return /* @__PURE__ */ jsx("div", { ...listProps });
+}
+/** A tab that selects slide `index`. Keeps itself in view when active. */
+function Thumbnail({ index, render, ref, ...props }) {
+	const { activeIndex, slides, goTo, labels, ids, behavior } = useCarouselContext("Thumbnail");
+	const [element, setElement] = useState(null);
+	const mergedRef = useMergedRefs(setElement, ref);
+	const selected = index === activeIndex;
+	useEffect(() => {
+		const list = element?.closest("[data-carousel-thumbnails]");
+		if (selected && element && list) scrollIntoViewWithin(list, element, behavior);
+	}, [
+		selected,
+		element,
+		behavior
+	]);
+	return renderPart("button", mergeProps({
+		type: "button",
+		role: "tab",
+		id: ids.tab(index),
+		"aria-selected": selected,
+		"aria-controls": ids.slide(index),
+		"aria-label": labels.thumbnailLabel(index, slides.length),
+		tabIndex: selected ? 0 : -1,
+		"data-carousel-thumbnail": "",
+		"data-active": selected ? "" : void 0,
+		ref: mergedRef,
+		onClick: () => goTo(index, "tab")
+	}, props), render);
+}
+// src/components/index.ts
+var components_exports = /* @__PURE__ */ __exportAll({
+	Counter: () => Counter,
+	Next: () => Next,
+	Prev: () => Prev,
+	Root: () => Root,
+	Slide: () => Slide,
+	Thumbnail: () => Thumbnail,
+	Thumbnails: () => Thumbnails,
+	Viewport: () => Viewport
+});
+export { components_exports as Carousel, defaultLabels };

package/dist/rolldown-runtime-D8jQpDG7.js

@@ -0,0 +1,12 @@
+// \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+export { __exportAll as t };

package/dist/styles.css

@@ -0,0 +1,54 @@
+/*
+ * Functional base styles for @mitchellslager/carousel. They live in a cascade
+ * layer, so any unlayered style of your own wins without extra specificity.
+ * Visual styling (colours, buttons, thumbnails) is up to you.
+ */
+@layer carousel {
+  [data-carousel-viewport] {
+    display: flex;
+    overflow-x: auto;
+    overscroll-behavior-x: contain;
+    scroll-snap-type: x mandatory;
+    scroll-behavior: smooth;
+    scrollbar-width: none;
+  }
+
+  [data-carousel-viewport]::-webkit-scrollbar {
+    display: none;
+  }
+
+  [data-carousel-slide] {
+    flex: 0 0 100%;
+    min-width: 0;
+    /*
+     * No scroll-snap-stop: always. It would also stop programmatic scrolls at
+     * the next slide, so thumbnails could not jump several slides at once.
+     */
+    scroll-snap-align: center;
+  }
+
+  [data-carousel-thumbnails] {
+    display: flex;
+    overflow: auto;
+    overscroll-behavior: contain;
+    scrollbar-width: none;
+  }
+
+  [data-carousel-thumbnails]::-webkit-scrollbar {
+    display: none;
+  }
+
+  [data-carousel-thumbnails][data-orientation="vertical"] {
+    flex-direction: column;
+  }
+
+  [data-carousel-thumbnail] {
+    flex: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-carousel-viewport] {
+      scroll-behavior: auto;
+    }
+  }
+}

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@mitchellslager/carousel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "A headless, accessible image carousel for React, driven by native CSS scroll snapping.",
+  "license": "MIT",
+  "author": "Mitchell Slager",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mitchellslager/carousel.git",
+    "directory": "packages/carousel"
+  },
+  "keywords": [
+    "react",
+    "carousel",
+    "gallery",
+    "slider",
+    "thumbnails",
+    "scroll-snap",
+    "accessibility",
+    "headless"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "carousel:source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": {
+      "carousel:source": "./src/styles.css",
+      "default": "./dist/styles.css"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "size-limit": [
+    {
+      "name": "JavaScript (minified, brotli, React excluded)",
+      "path": "dist/index.js",
+      "import": "{ Carousel }",
+      "limit": "4 kB"
+    }
+  ],
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@size-limit/preset-small-lib": "^14.3.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitest/browser-playwright": "^5.1.0",
+    "playwright": "^1.64.1",
+    "publint": "^0.3.25",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "size-limit": "^14.3.0",
+    "tsdown": "^0.23.5",
+    "vitest": "^5.1.0",
+    "vitest-browser-react": "^2.3.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc",
+    "check:package": "publint --strict --pack npm && attw --pack . --profile esm-only --exclude-entrypoints styles.css",
+    "size": "size-limit"
+  }
 }