@mitchellslager/carousel 0.0.0 → 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

@@ -0,0 +1,121 @@
+# @mitchellslager/carousel
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitchellslager/carousel",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "A headless, accessible image carousel for React, driven by native CSS scroll snapping.",
   "license": "MIT",
   "author": "Mitchell Slager",
@@ -42,14 +42,6 @@
     "access": "public",
     "provenance": true
   },
-  "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"
-  },
   "peerDependencies": {
     "react": ">=19",
     "react-dom": ">=19"
@@ -76,5 +68,13 @@
     "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"
   }
-}
+}