@nordwerk/scroll-carousel 0.1.0

package/docs/migration.md

@@ -0,0 +1,84 @@
+# Replacing a library carousel
+
+Option and API names on the left are those of Swiper, the most widely used carousel library;
+other libraries name the same things similarly. The main change of mindset: layout moves from
+JavaScript options into CSS, so breakpoints become media or container queries instead of
+options that the script re-applies after load.
+
+## Options
+
+| Library | Here | Notes |
+| --- | --- | --- |
+| `slidesPerView: 3` | `--sc-per-view: 3` | Fractions work the same way |
+| `slidesPerView: 'auto'` | `--sc-slide-size: auto` | Or any length, e.g. `18rem` |
+| `spaceBetween: 16` | `--sc-gap: 16px` | |
+| `slidesOffsetBefore` / `After` | `--sc-offset-before` / `--sc-offset-after` | Snapped slides line up after the offset |
+| `breakpoints: { … }` | `@media` or `@container sc (min-width: …)` | Container queries follow the carousel's own width |
+| `slidesPerGroup: 3` | `--sc-group: 3` | Only group starts are snap points |
+| `slidesPerGroupAuto` | `--sc-group: page` | As many whole slides as fit |
+| `centeredSlides: true` | `--sc-align: center; --sc-centered: 1` | |
+| `centeredSlidesBounds` | `--sc-align: center` without `--sc-centered` | |
+| `centerInsufficientSlides` | class `sc--center-few` | |
+| clamping slides per view to the slide count | `--sc-count: <n>` | |
+| `initialSlide: 4` | `data-sc-initial` on the slide, or `initial: 4` | Plus the inline `PRE_POSITION` snippet for server rendering |
+| `freeMode: true` | `--sc-snap: none` | |
+| `freeMode: { sticky: true }` | `--sc-snap: mandatory` | Native momentum still carries across several slides |
+| `loop: true` | `rewind: true` | Fades back to the start instead of cloning slides |
+| `rewind: true` | `rewind: 'scroll'` | Scrolls back across all slides |
+| `autoplay: { delay }` | `autoplay({ delay })` plugin | Adds a required pause button; focus stops it |
+| `simulateTouch` (mouse drag) | `drag()` plugin | Opt-in |
+| `navigation` | `[data-sc-prev]`, `[data-sc-next]` on any element | Or call `next()` / `prev()` from your own components |
+| `pagination` (bullets) | `[data-sc-dots]` | Or render your own from `state.page` / `state.pageCount` |
+| `watchOverflow` | automatic | `data-sc-overflow` on the root; controls hide without it |
+| `a11y` module | built in | Live region, `aria-disabled`, keyboard |
+| `lazy` | native `loading="lazy"` on images | |
+| `speed` | not configurable | Native smooth scrolling; instant with reduced motion |
+| `allowTouchMove: false` | `overflow-x: hidden` on the track | Arrows and the API still work |
+
+## API
+
+| Library | Here |
+| --- | --- |
+| `new Swiper(el, options)` | `attach(root, options)` |
+| `swiper.slideTo(i)` | `carousel.slideTo(i)` (shows the page that contains slide i) |
+| `swiper.slideToLoop(i)` | `carousel.slideTo(i)` |
+| `swiper.slideNext()` / `slidePrev()` | `carousel.next()` / `prev()` |
+| `swiper.activeIndex`, `realIndex` | `carousel.index` |
+| `swiper.snapIndex` | `carousel.page` |
+| `swiper.isBeginning` / `isEnd` | the same names |
+| `swiper.slides` | `carousel.slides` |
+| `swiper.el`, `wrapperEl` | `carousel.root`, `carousel.track` |
+| `swiper.update()` | `carousel.update()`, rarely needed: it measures on resize and content changes |
+| `swiper.destroy()` | `carousel.destroy()` |
+| `on('slideChange')` | `sc:change` event on the root, or `onChange`, once per settled move |
+| `onSwiper(swiper)` | `carousel` returned by `attach`, or `carouselRef` in React and Preact |
+
+Behaviour that differs:
+
+- No change event on attach. A wrapper that promised one should call its handler once with
+  `carousel.state` after attaching.
+- `index` is the slide at the snap position. At the end of a row it is the first slide of the
+  last full view, not the last slide.
+- Arrows at the ends are disabled only without `rewind`; with `rewind` they stay enabled.
+- There are no duplicate slides, so code that skips `.swiper-slide-duplicate` or reads
+  `data-swiper-slide-index` goes away, as do workarounds that reset a container's scroll
+  position after focus moved into a slide.
+
+## Deliberately not supported
+
+- A true infinite loop (cloned slides and a teleported scroll position). It is fragile on native
+  scrolling and confusing for assistive technology; use `rewind`.
+- Vertical carousels, zoom, a draggable scrollbar, slide effects (fade, cube, flip), virtual
+  slides, parallax, and syncing thumbnails with a second carousel. Thumbnails can call
+  `slideTo()` and listen to `sc:change`.
+- Changing the transition speed or easing of moves.
+
+## Migrating step by step
+
+1. Keep your component's public props and imperative handle; swap its internals.
+2. Move per-device options into CSS: one media or container query per former breakpoint.
+3. Replace loop with rewind; check with product owners where an endless loop was visible.
+4. Keep your own arrows and dots, bound to `next()`, `prev()`, `goToPage()` and `sc:change`.
+5. Remove layout workarounds made for script-computed layout, such as first-image fixes for
+   server rendering.
+6. Behind a flag, migrate one call site at a time and compare with visual tests.

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@nordwerk/scroll-carousel",
+  "version": "0.1.0",
+  "description": "A dependency-free carousel on native scrolling: CSS scroll snap first, arrows, dots, paging and an API as progressive enhancement.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/studio-nordwerk/scroll-carousel.git"
+  },
+  "homepage": "https://studio-nordwerk.github.io/scroll-carousel/",
+  "keywords": [
+    "carousel",
+    "slider",
+    "scroll-snap",
+    "progressive-enhancement",
+    "accessibility",
+    "react",
+    "preact",
+    "astro"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./drag": {
+      "types": "./dist/drag.d.ts",
+      "default": "./dist/drag.js"
+    },
+    "./autoplay": {
+      "types": "./dist/autoplay.d.ts",
+      "default": "./dist/autoplay.js"
+    },
+    "./markup": {
+      "types": "./dist/markup.d.ts",
+      "default": "./dist/markup.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./preact": {
+      "types": "./dist/preact.d.ts",
+      "default": "./dist/preact.js"
+    },
+    "./astro": "./src/astro/Carousel.astro",
+    "./carousel.css": "./dist/carousel.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/astro",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "docs/migration.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test \"test/unit/*.test.ts\"",
+    "size": "node scripts/size.mjs",
+    "site": "node scripts/build.mjs && node site/generate.mjs",
+    "fixtures": "node scripts/fixtures.mjs",
+    "test:e2e": "playwright test",
+    "serve": "node scripts/serve.mjs",
+    "check": "pnpm typecheck && pnpm test && pnpm site && pnpm size && pnpm fixtures && pnpm test:e2e",
+    "prepublishOnly": "node scripts/build.mjs"
+  },
+  "peerDependencies": {
+    "preact": ">=10",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "preact": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "4.13.0",
+    "@playwright/test": "1.61.1",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "astro": "^7.3.3",
+    "esbuild": "0.28.2",
+    "preact": "^10.29.8",
+    "preact-render-to-string": "6.7.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@12.5.1"
+}

package/src/astro/Carousel.astro

@@ -0,0 +1,88 @@
+---
+/*
+ * Astro adapter. Renders the carousel markup around the slides you pass in the default slot
+ * (one element per slide: <li> when as="ul", otherwise any element) and attaches the core in the
+ * browser. Drag and autoplay are loaded only when a carousel on the page asks for them.
+ */
+import '@nordwerk/scroll-carousel/carousel.css';
+import { PRE_POSITION, baseVars, responsiveCss, type LayoutProps } from '@nordwerk/scroll-carousel/markup';
+
+interface Props extends LayoutProps {
+  /** Accessible name of the scrolling list. */
+  label: string;
+  as?: 'ul' | 'div';
+  class?: string;
+  style?: string;
+  centerFew?: boolean;
+  arrows?: boolean;
+  dots?: boolean;
+  initial?: number;
+  rewind?: boolean | 'fade' | 'scroll';
+  drag?: boolean;
+  /** Milliseconds per page; renders the play button. */
+  autoplay?: number;
+  /** Label templates: page 'Slide {n} of {count}', status 'Items {first} to {last} of {count}', prev, next. */
+  labels?: { page?: string; status?: string; prev?: string; next?: string; play?: string; pause?: string };
+}
+
+const props = Astro.props;
+const { as: Track = 'div', label, class: className, style = '', centerFew, arrows = true, dots = true } = props;
+const { initial = 0, rewind, drag, autoplay, labels = {} } = props;
+const id = `sc${Math.random().toString(36).slice(2, 10)}`;
+const css = responsiveCss(id, props);
+const vars = Object.entries(baseVars(props)).map(([name, value]) => `${name}:${value}`).join(';');
+const options = JSON.stringify({ initial, rewind, drag, autoplay, labels, group: typeof props.group == 'object' ? undefined : props.group });
+---
+
+<div class:list={['sc', { 'sc--center-few': centerFew }, className]} data-sc-id={id} data-sc-astro={options} style={[vars, style].filter(Boolean).join(';')}>
+  {css && <style set:html={css} />}
+  <Track class="sc-track" data-sc-track tabindex="0" aria-label={label}><slot /></Track>
+  {arrows && (
+    <>
+      <button type="button" class="sc-nav sc-prev" data-sc-prev aria-label={labels.prev ?? 'Previous'}>
+        <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m15 18-6-6 6-6" /></svg>
+      </button>
+      <button type="button" class="sc-nav sc-next" data-sc-next aria-label={labels.next ?? 'Next'}>
+        <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m9 6 6 6-6 6" /></svg>
+      </button>
+    </>
+  )}
+  {autoplay && (
+    <button type="button" class="sc-play" data-sc-play aria-label={labels.pause ?? 'Stop automatic scrolling'}>
+      <svg class="sc-icon-play" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M8 5v14l11-7z" /></svg>
+      <svg class="sc-icon-pause" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M7 5h3.5v14H7zM13.5 5H17v14h-3.5z" /></svg>
+    </button>
+  )}
+  {dots && <div class="sc-dots" data-sc-dots></div>}
+  <p class="sc-status" data-sc-status aria-live="polite"></p>
+</div>
+{initial > 0 && <script is:inline set:html={PRE_POSITION} />}
+
+<script>
+  import { attach, getCarousel, type Plugin } from '@nordwerk/scroll-carousel';
+  import { templateLabels } from '@nordwerk/scroll-carousel/markup';
+
+  async function attachAll() {
+    for (const root of document.querySelectorAll<HTMLElement>('[data-sc-astro]')) {
+      if (getCarousel(root)) continue;
+      const options = JSON.parse(root.dataset.scAstro || '{}');
+      const plugins: Plugin[] = [];
+      if (options.drag) plugins.push((await import('@nordwerk/scroll-carousel/drag')).drag());
+      if (options.autoplay) {
+        const { autoplay } = await import('@nordwerk/scroll-carousel/autoplay');
+        plugins.push(autoplay({ delay: options.autoplay, labels: options.labels }));
+      }
+      // The page may have changed while the plugins loaded.
+      if (root.isConnected) attach(root, { ...options, labels: templateLabels(options.labels), plugins });
+    }
+  }
+
+  attachAll();
+  document.addEventListener('astro:page-load', attachAll);
+  // With view transitions, carousels that leave the page must let go of their listeners.
+  document.addEventListener('astro:before-swap', () => {
+    for (const root of document.querySelectorAll<HTMLElement>('[data-sc-astro]')) {
+      if (!root.closest('[data-astro-transition-persist]')) getCarousel(root)?.destroy();
+    }
+  });
+</script>